Publish: build specification

Glossary (one meaning each)

Scope and reading paths

Backend: Glossary → Data model → States, gates, events → API → Credits & ledger → Audit → Scenarios → Fixture; AI spec §Pipeline, §Cost, §Audit. Frontend: Glossary → States (gates, feed) → each screen's control table with its rows in the per-control accessibility table → Copy rules → the UI strings quoted in those tables. QA: Fixture → per-screen Acceptance → Scenarios → Cross-cutting → Ledger walk → Audit names. Design: Scope → screens → Copy rules → Accessibility → Open questions (three dialogs are specified in text only: Rename, "Which standard should go back?", Delete with a run in flight).

Reference set (read in this order)

1. This page: the build specification. handoff.html
2. Prototype canvas (interactive, 20 screens + sizes): ../index.html
3. Publish flows (every path, screen by screen): flows.html
4. AI call spec v5 (prompts, schemas, validators, charging, safety, gates; clean specification, no history): ai-spec.html
5. How AI readiness works (user-facing dossier; the in-product help panel is board 2g and the text ships as the help article): dossier.html
6. Polish plan (V10 originals beside the proposal, decisions and why): https://claude.ai/artifact/AyWWZFU7S5QCz3ADYdeM6W
7. PRD R10, R14, R15, R24–R30: https://claude.ai/artifact/TZEpQk1SHaK6j5TkxqZZj5 and recovery/ux-review/PRD-accreditation-spec.md
8. Sources: recovery/artifacts/publish-workflow-canvas/ (screens, build scripts, renders).

Data model (new or changed)

Five decisions the model rests on: (1) a Snapshot stores references to immutable repository versions plus derived passage text and hashes, never full copies; only publishing stores a rendered asset. (2) draft_number is assigned when a version is created, final_number when a final is published; numbers are never reused, a withdrawn final keeps its number. (3) Step 4 edits are version-local overrides in the snapshot; the repository is written only when "Also update the response in All Accreditation" is ticked, through the standards service as a new narrative version. (4) Exclusions are derived from open SendBacks per publication, never a flag on the version. (5) One rev per version (the ETag) covers the row, selection, cover and confirmations; section views, runs and finding decisions do not bump it; every write of the version row requires If-Match.

Hashes

• content_hash = hash over included items' (passage hashes, judgement, chain_state, attachment versions, open comment ids) + selection + settings + response type + format_ops. Auto-format changes format_ops, so it is covered.
• item.input_hash = hash(standard text, guidance, rubric, cleaned passages, evidence index with extracts, judgement, human comments), computed before pseudonymisation.
• a1_key = hash(input_hash, pipeline_versions, model, rubric_version, accreditor); a2_key = hash(sorted a1_keys, A2 versions).

States, gates and events

Version lifecycle

in_progress ──(Publish draft)──▶ published(draft)       immutable: every write returns 409 "published"
in_progress ──(Publish final)──▶ published(final)       only when final_ready = true
published(final) ──(Withdraw, coordinator)──▶ withdrawn  file stays downloadable, marked Withdrawn; Final numbering continues (Final 2)
in_progress ──(Delete, confirm)──▶ deleted               published versions never delete
any published ──(Start Draft n+1 / Duplicate)──▶ new in_progress version, created on demand only (never automatically)
published(draft) ──▶ cannot be withdrawn or deleted (it is an internal record; Start Draft n+1 instead)
in_progress with a run in flight ──(Delete)──▶ the run is cancelled first (AI: in-flight standards settled, the rest refunded; Auto-format: refunded), then deleted

Duplicate takes the current template revision and copies the source version's selection, settings, cover and output; it is offered on any published or withdrawn version, never on a live draft (that would fork it). Exclusions are carried by reference: the open SendBack rows belong to the publication, so Draft n+1 reads the same rows and sees them lift when the item returns.

Orthogonal state each version carries: stale, the three confirmations, and in_flight (none | ai | autoformat | publish; a preview build is not in flight, it only locks confirmations through confirmations_unlocked). "Clear confirmations" always means null all three and write version.unconfirmed{cause}.

What Draft n+1 inherits: selection, content settings, response type, cover and output settings. Not inherited: confirmations, viewed sections, readiness and Auto-format runs. AI finding decisions carry over when the finding's (input hash, kind, anchor) still matches; "Will fix after this draft" reopens. Send-back exclusions carry until the standard returns.

AiRun status adds approval_expired (7 days without a decision; reservation released; card returns to the quote with "Approval expired · Ask again"). awaiting_approval is not in flight: it blocks nothing and the draft can be published meanwhile; the run, when approved, uses the snapshot it was quoted on, and if that snapshot is no longer current the quote is void (409 "The draft changed since the quote · Quote again").

AiFinding status is derived: open (no decision, or reopened) · sent_back (accept decision with an open SendBack) · closed (ignore, or clear for injection) · superseded (the result key that produced it is no longer in the latest run, because the input changed and the finding did not recur; shown greyed under "Resolved by the latest run", no buttons). When a new run reproduces the same finding_key, the previous decision carries, whatever draft it was made in. Accept and Ignore are refused on an injection finding (only Mark cleared applies), and an injection finding keeps blocking a final even when outdated until it is cleared or superseded. A send-back prefill lists the standard's open findings with each one ticked; unticking one leaves it open.

A standard returning from send back: when the chain reports it resubmitted or approved, SPOL sets SendBack.returned_at, lifts the exclusion, marks readiness stale, clears the confirmations (cause recorded) and shows "{code} came back from {name} · included again · run checks again". Its AI findings stay sent_back until the next AI run. The banner reads "included again" only when the send back had excluded it; otherwise "{code} came back from {name} · run checks again". A chain approval that arrives without a send back only recomputes final_ready (no banner, no clearing). An exclusion is lifted only by the item returning; there is no manual lift, and a standard that is sent back outside Publish cannot be excluded from this version (the coordinator unselects it in Step 1 instead).

Gates (computed, shown as text wherever they block)

Definitions. excluded = selected items with an open SendBack where exclude is on. in_flight = an Auto-format, AI readiness (status running only; awaiting_approval does not block) or publish job is running for this version; a rules run never blocks. stale = no completed rules run, or the run's snapshot content_hash ≠ the current snapshot's. Every gate below is evaluated server-side on every POST as well as in the client; a POST that fails a gate returns 409 {code: "gate", blockers[]} and records nothing.

What clears the confirmations

• Any saved edit in Step 4 Edit mode (a discard clears nothing).
• Auto-format applied, and Auto-format undone (the document changed either way).
• A change to the selection in Step 1, the content settings, or the response type; a standard removed from the cycle.
• A send back that excludes a standard, and a standard returning from send back.
• A readiness run or an AI run whose finding set differs from the previous one clears only "Findings and comments" (its summary changed); the cause is recorded.
• Not cleared: a narrative, evidence or comment change arriving from the feed. The draft goes stale and Step 4 shows the banner, but confirmations stand: a draft tolerates text that moved under it (it is internal); a final does not, because final_ready requires ¬stale, and a re-run that changes the finding set clears "Findings and comments".
• A confirmation can be unticked by any coordinator or editor, not only the person who ticked it; the audit entry records both.

Roles and impersonation

• Writers may open a version and read every step; Start, Delete, Withdraw, Send back, Unlock, Auto-format, confirmations and Publish are aria-disabled for them: "Only coordinators and editors can do this". Accept, Ignore and Reopen on AI findings are coordinator or editor only.
• While impersonating, Start, Publish, Send back, Unlock, Auto-format, Delete and confirmations are aria-disabled: "Not available while impersonating". Section views are not recorded either (POST …/views → 403), so an impersonator can never unlock confirmations for the person they impersonate.
• Any 403 on a write: "You no longer have access to this publication. Back to Publish."
• A published version opened from the landing shows Published; steps 1–3 are read-only with controls aria-disabled: "Published versions can't be changed".

Defaults the screens assume

• Quote expires_at = 15 minutes after the quote; planned_finish_at = start + 20 s per standard ÷ 4 parallel calls + 60 s for A2, minimum 2 minutes.
• Search debounce 300 ms; autosave debounce 1 s. Sizes print as "2.3 MB" (one decimal, binary MB). "Last edited" is an absolute date "{d Mon yyyy}".
• step_reached advances when Next succeeds and never falls; reload opens the step in the URL, capped at step_reached.
• Section views persist while the section id persists across snapshots; a document section new to the current snapshot counts as unviewed.
• Writes during a running AI run are allowed (a new snapshot marks the run's result stale on completion, "Out of date · Run again"); only publishing waits.
• The preview build starts on entry to Step 4 and after every new snapshot; its limit is 2 minutes, publishing's is 5 minutes, after which "Publishing is taking longer than usual · we'll keep going; you can leave this page" (the job continues; the landing row shows "Publishing…").
• Rename publication: inline dialog, 1–120 characters, trimmed, unique within the cycle ("A publication with this name already exists").
• File name: prefilled "{Institution}_{Source}_{Title}_{Label}_{yyyy-mm-dd}" without spaces; spaces typed are kept; \ / : * ? " < > | removed; over 120 characters truncated with the note "Shortened to 120 characters".
• Impersonation: every write returns 403, including autosave PATCH (controls are read-only, "Not available while impersonating").
• Second approval: any other coordinator of the institution; when none exists, the dialog reads "A second coordinator must approve · none is set up · Ask your administrator" and the run cannot start.
• "Reviewer view: {n} likely follow-ups" = number of high AI findings across checked standards.
• Confirmation titles and summaries: "Sections and standards · {n} standards in {m} sections · Not approved: {codes}", "Formatting and branding · Logo {file} · {cover letter or No cover letter} · Fonts embedded, page numbers continuous", "Findings and comments · {n} open findings carried from Readiness · {m} open comments".

Navigation and saving

• Each step is a URL /publish/versions/{id}/step/{n}; reload opens that step, never beyond step_reached; browser Back moves one step.
• Autosave on every change, debounced 1 s: "Saving…" → "Saved"; on failure "Couldn't save · Retry". A 412 reverts the control to the server value, refetches, and announces "Someone else saved this draft. Reload." No merge.
• A draft deleted elsewhere returns 410 on the next request: "This draft was deleted by {name}. Back to Publish."
• Published elsewhere while open (change feed): "Draft 4 was published by {name} at {time} and can't be edited. Start Draft 5 · View published". Unsaved edits are lost and the notice says so.

Landing (Publish tab)

Controls

Acceptance

• Tabs. Given the fixture. Then "In progress 3" is selected with Draft 4, Online MBA Draft 2 and Draft 2; "Published 3" shows Draft 3, Final 1 and Draft 1 with Format, Pages, Published by, Published on; the search box filters the active tab only; the empty cycle shows "No drafts in progress" / "Nothing published yet" per tab.
• Row menu. Given Draft 2 in progress. When ⋯. Then a menu with Open, Rename publication, Duplicate as new draft, Delete draft; Esc closes it and focus returns to ⋯. Given Final 1 published. When ⋯. Then Open, Download PDF, Copy link, Withdraw final. Given Draft 3 published. Then the menu has no Delete and no Withdraw and reads "Published versions can't be deleted".
• Required markers. Then Source, Cycle and Report template labels carry the required marker and the legend "* Required" is shown once; the selects are aria-required.
• AI panel hide. Given Step 2 with the AI panel locked. When ×. Then the strip "AI readiness · Locked · hidden from view · unlock any time for 29 credits · Show" replaces the panel and the rules dashboard spans the row; Show restores it. Given the panel unlocked with 2 open findings. When ×. Then the strip reads "AI readiness 58 · 2 open findings · 1 contradiction · hidden from view, nothing lost · Show"; the findings are unchanged when shown again.
• Start gated. Given Source "SACSCOC-2018", Cycle "2024–2025 (Current)", Template "Select a template…". When the tester tabs through the header. Then Start has aria-disabled="true", aria-describedby points to a role=status element reading "Choose a report template to start", and clicking it sends no request.
• First draft. Given template "QEP Impact Report" has no publication. When Start. Then the URL is /publish/versions/{id}/step/1, the chip reads "Draft 1", audit publication.created and version.created.
• Draft already open. Given Publication A with Draft 4 in progress. When Start for its template. Then the notice "Draft 4 is in progress · Open Draft 4 · Start Draft 5 anyway"; "Start Draft 5 anyway" sends force=true, which duplicates the latest published version of the publication (Draft 3), never the live Draft 4; chip "Draft 5", confirmations null. "Start Draft n+1" on the Published screen calls POST …/duplicate on that published version; both are allowed to coordinators and editors.
• Delete. Given Draft 2 in progress at Step 1. When ⋯ › Delete draft. Then the dialog "Delete Draft 2? This can't be undone. The deletion is recorded."; Cancel changes nothing; Delete → 204, the row is gone, audit version.deleted{draft_number: 2}; a later Start creates "Draft 5", never "Draft 2".
• Published row. Given Draft 3 published(draft). Then ⋯ shows neither Delete nor Withdraw; DELETE /versions/{Draft 3} → 409 published.
• Withdraw. Given Publication B Final 1 published(final), coordinator. When Withdraw final → dialog "Withdraw Final 1? The file stays downloadable and is marked Withdrawn. This is recorded." → Confirm with a reason. Then status "Withdrawn", Download still works, the next final is "Final 2", audit version.withdrawn{reason}. An editor gets 403.
• Empty state. Given cycle 2025–2026 has no versions. Then "No publications for this cycle yet" and no table; the selectors and Start still work.

Step 1 · Standards & content

Controls

Acceptance

• Section tri-state. Given Section 6 with 6.1, 6.2, 6.3 all unselected and heading "Standards · 9 of 12 selected". When the section checkbox is ticked. Then 6.1, 6.2, 6.3 are checked, the row reads "6 Resources · 3 of 3 selected", the heading "12 of 12 selected". When 6.3 is unticked. Then the section checkbox is aria-checked="mixed" and the row reads "2 of 3 selected".
• Part alone. When 4.2.b is unticked. Then 4.2 stays selected. When 4.2.b is ticked while 4.2 is unselected. Then 4.2 selects too.
• Review an approved standard with inline comments. Given 3.1 Governing Board approved. When Review, then a sentence in paragraph 1 is selected and "Add as comment A" is used with text. Then the passage is highlighted blue with mark A, "Your review of 3.1 · 1 comment in the text" lists it with the quote and paragraph, the draft is saved (PUT review-comments), and the footer reads "Send back with 1 comment" / "Post 1 comment · stays Approved". When an Overall comment is written: footer counts 2. When Post: 201 for each on the comments service, the thread shows both with "from Publish" (the inline one anchored), chain state stays Approved, audit review_comment.posted and comment.created{origin: publish}. When instead Send back with 2 comments: the dialog for 3.1 shows one compiled comment (overall, then A with quote and paragraph, then the readiness findings), "Leave 3.1 out" unticked, Writer preselected; Send back → 201, review drafts marked sent, audit review_comment.sent and send_back.created{review_comment_ids}. Esc closes the panel and focus returns to Review. Given the writer later changes the anchored sentence: the draft shows "The text changed · re-pin or remove".
• Finding details. Given the Readiness page. When the 3.1 row's summary is activated. Then the row expands to two lines: "High · Table wider than the page · Table 3.1 · Board composition, page 15 — 7 columns…" and "Medium · Open comment · paragraph 2 — "Clarify the recusal rule." · Priya Natarajan, 15 Oct 2026", plus the Open-in-All-Accreditation link; activating again collapses it; Send back inside the row opens the dialog without toggling. 3.3 expands to the "No response has been written yet" line.
• Not approved filter. Given the 12-standard selection. When "Not approved 3" (or the heading link "3 not approved") is clicked. Then exactly 3.3 (Not started), 4.2 (In review) and 6.2 (In review) show, and the note reads "3 selected standards are not approved yet (3.3, 4.2, 6.2). You can still publish an internal draft; a final needs every selected standard approved."
• Zero selection. When Clear all. Then Next is aria-disabled with "Select at least one standard"; Step 2 would read "Internal draft: not ready".
• Change clears. Given Draft 4 with a completed rules run (62) and 3 of 3 confirmed. When Documents changes from "Linked in narrative" to "Don't publish". Then Step 2 shows "Out of date · Run again", Step 4 "0 of 3 confirmed" and "Confirm 3 more to publish · 16 of 16 sections viewed" (16-of-16 variant), audit version.settings_changed, readiness.stale{cause: settings}, version.unconfirmed{cause: settings}. Same for unticking 8.1 and for response type → Institutional.
• Standard removed from the cycle. Given 5.2 removed from the cycle. When Draft 4 loads. Then the banner "5.2 was removed from this cycle and is no longer selected", audit version.selection_changed{cause: standard_removed}, stale, confirmations null.
• Template revised. Given revision r2 drops 6.3. Then Draft 4 shows "This template changed on {date}. Draft 4 keeps revision r1; Draft 5 will use the new one." and its selection is unchanged; Start Draft 5 → 6.3 absent with the banner "6.3 is no longer in this template".
• Keyboard. Given Expand all. Then Tab reaches every checkbox in reading order, Space toggles, Left/Right collapse and expand a section row, and the tree exposes role=tree / treeitem with aria-checked.

Step 2 · Readiness check

Controls

Acceptance

• Score. Given fixture run R1. Then the ring reads "62", the formula line "100 − 18 − 10 − 10 = 62", "Internal draft: ready", "Final: not yet". not_approved rows carry no scored severity (they count only in the −6 term).
• Stale after a writer's change. Given R1 and 3 of 3 confirmed. When a writer fixes a spelling finding on 1.1. Then "Out of date · Run again", confirmations kept. When Run checks again. Then the finding set differs → only "Findings and comments" is cleared ("2 of 3"); an identical set clears nothing.
• Unlock refused. Given balance 20 and the card "Uses 29 credits for 12 standards · 20 left this year". When Unlock. Then 402, the card stays locked, Unlock is aria-disabled with "Not enough credits · 29 needed, 20 left this year · Ask your administrator", no ledger entry, no audit ai_readiness.run.
• Quote reuse. Given AI run AR2 cancelled at 4 of 12. When Unlock. Then the quote reads "21 credits for 8 standards · 4 already checked" and quote.cached[] has 4 keys.
• Second approval. Given a cycle with 28 standards selected (61 credits). When Unlock. Then the dialog "This run needs 61 credits. A second coordinator must approve."; choosing yourself → 403 "Someone else must approve"; after sending, the card reads "Waiting for approval from {C2} · Cancel".
• Ignore. Given AI finding F-2.1-evidence_mismatch open. When Ignore. Then the reason select offers the four values (not_issue, covered, later, accepted_risk) and Mark closed is aria-disabled; a forced POST without reason → 422; after "Already covered elsewhere in the report" and Mark closed: chip "Closed · ignored" (no strikethrough), Reopen present, audit ai_finding.decision{kind: ignore, reason: covered}.
• Accept and send back. Given F-4.1-unsupported_claim and 4.1 Approved (written by Tracy Hall). When Accept and send back. Then the dialog "Send 4.1 Institutional Planning back", Writer preselected, the comment prefilled with the finding's why and fix, "Leave 4.1 out of this draft until it comes back" ticked. When Send back. Then 201, chip "Sent back", the Findings-by-standard row "Sent back to Tracy Hall · {date}", SendBack.exclude = true, audit send_back.created{ai_finding_keys: […]} and ai_finding.decision{kind: accept}, confirmations cleared.
• Contradiction. Given the "6.1 vs 5.1" finding. When Accept and send back. Then the dialog first asks "Which standard should go back?" with 6.1 and 5.1 listed with their values; the rest follows the previous item for the chosen one.
• Outdated. Given F-3.1-clarity anchored to passage P-3.1-2. When the tester edits P-3.1-2 in Step 4 and saves. Then the row chip "Outdated" with Accept and send back and Ignore still enabled. For F-2.1-injection the same edit shows "Outdated" and Final still blocks with "Text that tries to steer the review was found in 2.1 · clear it in Readiness"; Accept and Ignore are absent, Mark cleared (coordinator) present.
• Send back twice. Given 6.1 already sent back by Alex Carter. When Send back again. Then the dialog stays open with role=alert "Already sent back by Alex Carter" and no row is written.
• Everything excluded. Given 12 send backs with exclude on. Then "Internal draft: not ready · no standards left in this draft" and Step 4 Publish "Nothing to publish".
• Remind. Given 3.3 Not started (Writer Tracy Hall). When Remind. Then the button reads "Reminded" and audit send_back.reminded; a second click within 24 h → 429 "Reminded today".

Step 3 · Cover & signers

Controls

Acceptance

• Submit date. When submit_by is set to today (17 Oct 2026). Then inline "Submit date must be after 17 Oct 2026." and Next aria-disabled with that reason. Given a saved date that has since passed. Then the warning "Submit date has passed", Next enabled, Step 4 Publish blocked with "Submit date must be after today".
• Vacant role. Given no one holds Liaison. Then "No one holds this role · Assign in Admin" under the Liaison select; the item is listed under "Before you publish"; Final (not draft) is blocked with "Add the three signers in Cover".
• Uploads. A 3 MB PNG → "File is larger than 2 MB"; a GIF → "Use SVG, PNG or JPG"; the previous logo stays in both cases. A 12 MB cover-letter PDF → "File is larger than 10 MB".
• Profile read-only. Institution name and address render from the profile; there is no input; the link "Edit in Admin" opens the profile in a new tab.
• Preview updates. When the CEO changes to Dr. James Okonkwo. Then the cover preview shows the name within one second and autosave reads "Saved"; audit version.cover_changed{diff}.

Step 4 · Preview & publish

Controls

Acceptance

• Viewed tracking. Given 0 viewed. When the first page of 4.2 is at least 60% in view for 2 s (or its thumbnail is clicked). Then "1 of 16 sections viewed" (role=status) and audit version.section_viewed{item: 4.2}; under 2 s nothing is counted.
• Lock. Given 9 of 16 viewed. Then the three checkboxes are aria-disabled with "View all 16 sections to confirm (9 viewed)"; a forced POST confirmations → 409.
• Preview building. Then "Preparing the preview · 40 of 184 pages" with confirmations locked; after 2 min a role=alert "Couldn't build the preview · Retry".
• Edit held in review. Given 4.2 In review. Then "Also update the response in All Accreditation" is aria-disabled with "Not available while 4.2 is in review"; a forced POST with it ticked → 409 and audit version.edit_rejected{held_in_review}.
• Edit clears. Given 3 of 3 confirmed. When a passage is edited and saved. Then confirmations null, audit version.edited and version.unconfirmed{cause: edited}, stale banner, Undo (if any) hidden, footer "Confirm 3 more to publish". Discard changes nothing.
• Auto-format before and after. Given the run completed with 23 changes. When "See before and after" (or a change-list row). Then the view opens on the first change (Table 3.1, p. 15) with Before showing the table cut at the page edge and After showing it fitted; the list has one entry per kind; choosing "Results" under 4.2 shows H4 → H3 with the AI decision line; Undo this change → chip Undone, count "22 of 23 changes kept · 1 undone", audit autoformat.undo{operation_id}; Apply again restores it; Undo all 23 → confirm, every change reverted, no refund.
• Auto-format progress. When Auto-format document. Then the progress modal shows pages laid out and per-kind counts; Cancel before completion → nothing applied, no ledger entry, "Auto-format cancelled · nothing changed".
• Auto-format. When Auto-format document. Then "Formatting {n} of 184 pages", then the banner, "23 changes" (2 tables, 3 images, 1 heading level, 14 paragraph spacing, 3 citations; contents and bookmarks rebuilt, not counted), ledger settle −4, confirmations null, stale. Undo all → no refund, audit autoformat.undo. Failure → "Auto-format couldn't finish · no changes applied · nothing charged · Try again" (settle 0). Nothing to format → "Nothing to format · no credits used", no ledger entry.
• File name. Given input "Report:final?.pdf". Then the saved name is "Reportfinal.pdf"; names over 120 characters are truncated with a note; empty → "File name can't be empty" and Publish aria-disabled.
• Publish draft. Given draft_publishable. When Publish draft. Then the confirm "Publish Draft 4 as PDF? Still open: 17 findings, 3 comments. This is recorded." (zero case: "Nothing open.") → modal "Publishing · {n} of 184 pages" → the Published banner "Draft 4 published · PDF · 184 pages · {size} · 17 Oct 2026, 4:31 PM · Recorded in the audit trail." A retry with the same Idempotency-Key returns the same job; a PATCH afterwards → 409 published.
• Gate order. Given file name empty and 4.2 unapproved. Then the Final radio reason is "File name can't be empty" (draft_publishable reasons precede final reasons).
• Reading mode. When Reading mode. Then the rail, header, thumbnails and side column hide, focus moves to Exit, Esc exits and focus returns to the Reading mode button, sections viewed in reading mode count outside it. When Next › is used. Then the select shows "3.2 Board Oversight · 6 of 16", the document scrolls to its first page, "10 of 16 sections viewed", and the comments panel heading reads "0 comments on 3.2 Board Oversight · 3 open in the report". When → is pressed with focus in the document. Then the same. When Comments (3) is toggled off. Then the panel closes and the page re-centres.
• Review in reading mode. Given reading mode on 3.1 with the comments panel open. When a sentence in paragraph 1 is selected and "Add as comment A" is used with text. Then the sentence carries a blue A mark, "Your review of 3.1 · 1 comment in the text" lists it, the buttons read "Send back with 1 comment" / "Post 1 comment · stays Approved", and the same draft appears in the Readiness review panel for 3.1 (PUT review-comments). When Send back with 1 comment. Then the Send back dialog for 3.1 opens with the compiled comment.
• Section navigator in Preview. Given Step 4 at 3.1. When "5.2 Faculty Evaluation · comments" is chosen in the select. Then the document scrolls to 5.2, its thumbnail is current, the section counts as viewed, and the comments list highlights the 5.2 comment.

Published

• Summary rail: "Readiness · {n} findings open at publish · {m} open comments", "Confirmed · 3 of 3 by {name}", "Format · PDF, bookmarked"; What's next: "Keep working · Start Draft 5", "Final for submission · Blocked · Not yet: {codes} not approved or excluded by send back", Done.
• Banner "Draft 4 published · {format} · {pages} pages · {size} · {date time} · Recorded in the audit trail." Dates print as "17 Oct 2026, 4:31 PM" (the PRD date form).
• File card: title, file name, kind; Download (primary), Copy link (private link, institution users only; failure "Couldn't copy · select the link"), Share with reviewers (opens the existing share dialog). A missing asset shows "File unavailable · Regenerate" (coordinator).
• What's next: Keep working (Start Draft 5 → new version from this one's settings), Final for submission (link or Blocked with reason), Back to Publish.
• Summary rail: standards, readiness, cover, confirmed, output.
• Footer: Done (to landing).

Acceptance

• Download → signed URL and audit version.downloaded. Copy link → audit version.link_copied; on clipboard failure "Couldn't copy · select the link" with the link selected.
• Given the asset missing from storage. Then "File unavailable · Regenerate" (coordinator only); Regenerate renders from published_snapshot_id; 404 when a pinned file version is gone → "A document in this report was deleted and the file can't be regenerated".
• Given 3.3, 4.2, 6.2 unapproved. Then "Final · Blocked · Not yet: 3.3, 4.2, 6.2 not approved or excluded by send back" ; the Final row reads "Blocked" and Start Draft 5 is the Keep working action.
• Given the asset exists. Then the file card shows title, file name and "Internal draft, watermarked" with Download {format}, Copy link and Share with reviewers (existing share dialog); pinned file versions (PRD R25) are recorded, not shown.

API (service contracts)

Every write to the version row carries If-Match: "{rev}" (428 when absent, 412 when stale). Every request that creates or charges something carries an Idempotency-Key. Status codes: 403 is always role or impersonation; 409 is state (published, in flight, open send back); 410 deleted; 412 stale rev; 422 invalid input. Error bodies are {code, message, …detail} with the message strings from the screen tables.

Permissions

• Reader and writer: read everything; every write 403 except views and resolving their own comments.
• Editor: every write except withdraw, regenerate and clear (coordinator).
• Impersonating admin: reads only; 403 on publish, send back, AI readiness, Auto-format, delete, confirmations and views.

Server feed per open version (events the client reacts to)

Credits, ledger and what the coordinator sees

• AI readiness: 2 credits per standard whose result is not already stored + 5 for the consistency pass. The quote is the charge; it is what the card shows ("29 credits for 12 standards"; when some are stored: "21 credits for 8 standards · 4 already checked"). "{n} left this year" always shows available = balance − open reserves, never the raw balance.
• Hold = charge. The reservation holds exactly the charge in credits. The 1.5× figure is the run's USD spend budget inside SPOL, not a credit hold: the institution never pays more than the charge, and a standard whose retries exceed the budget is "not checked: retry budget" and refunded. 402 when available < charge: "Not enough credits · 29 needed, 20 left this year · Ask your administrator".
• Refunds: 2 credits per standard not checked after the charge (ungrounded, retry budget, provider unavailable, refusal, cancelled, timed out); standards excluded at quote time (too long, personal data) are never charged and are listed in the quote. The 5 consistency credits are refunded whenever A2 does not run (any A1 not checked, cancel, timeout).
• Approval: above 50 credits a second coordinator approves (never the requester). The reservation is taken at the request and released on decline or after 7 days (approval_expired / approval_declined). The approver sees "{name} asks you to approve AI readiness on {label} · {charge} credits · Approve · Decline"; the requester's card then reads "Approved by {name} · Reading…" or "Approval declined by {name} · Ask again".
• Auto-format: the deterministic candidate scan runs first. No candidates → "Nothing to format · no credits used", no ledger entry, audit autoformat.run{status: nothing_to_format}. Otherwise reserve 4 → settle −4 on done; on failure settle 0 and "Auto-format couldn't finish · no changes applied · nothing charged · Try again". Undo never refunds; the dialog says so ("Undo doesn't return the credits").
• Delete releases any open reservation on the version, including one awaiting approval (settle 0, audit ai_readiness.run{status: cancelled, cause: deleted}).
• Everything else in Publish is free and never labelled AI: the rules readiness, Send back, Remind, publishing in any format. Writers never see balances or cost lines.
• Provider down before any call: release, no charge, "AI readiness isn't available right now · nothing was charged · Try again".

Ledger rules (invariants the tests assert)

• balance = Σ(settle, refund, purchase, allowance). A reserve entry never changes balance_after; it opens a reservation. available = balance − Σ(open reserves).
• A reservation is open until exactly one settle entry carries its reservation_id (UNIQUE). A release is a settle of 0. A refund is a positive entry with the same reservation_id written in the same transaction as the settle. Every settle is ≤ its reserve in magnitude, so balance can never go negative.
• The reserve check and insert are one serialised write per institution; two coordinators on a shared balance that covers one run get one reserve and one 402.
• Cancel, the reaper and a retried POST …/cancel call one close routine that no-ops when a settle exists. Results arriving after close are stored (free next time) but never charged. Standards in flight at cancel finish, count in "{n} of {N} checked" and in the next quote.
• Amounts are signed integers. Both ai_readiness.run and autoformat.run audit entries carry reservation_id and the ledger entry ids so the audit reconciles to the ledger.

Ledger walk (12 standards, charge 29, balance B)

Audit entries

Accessibility requirements (WCAG 2.2 AA)

• One h1 per page (Accreditation), the page title is h2, sections h3. Skip link to main.
• Every disabled control uses aria-disabled (stays in the tab order; Enter/Space do nothing) with aria-describedby to its reason text; never a tooltip-only reason and never the disabled attribute.
• Every control that performs an action is a <button>; only navigation is a link. (The prototype uses links between artboards; do not copy that.)
• Dialogs: role=dialog, aria-modal, labelled; focus moves in (initial focus named per dialog below), background inert, Esc and Cancel return focus to the opener. When the opener is removed by the action (Send back, Accept), focus moves to the row's new chip (tabindex=-1).
• Status never by colour alone: dot + word; score rings role=img with the score and verdicts in the label; bars aria-hidden with their value in text beside them.
• Contrast: text 4.5:1, control borders and icons 3:1. Input and segmented borders are #8a95a1 (3.1:1); the AI button gradient ends at #7c3aed (white text 5.1:1); hairline separators (#e6e9ee) are decorative only. No strikethrough on closed findings; the chip carries the state.
• Targets ≥ 24 × 24 px on desktop (inline text actions get padding to reach it), ≥ 44 px on phone; focus visible on navy and white.
• Live regions: counts, "Saved", progress and completion use role=status; errors use role=alert and receive focus.
• Reading mode and the viewer are keyboard-operable: Page Down/Up, Home/End, Find (Enter next, Shift+Enter previous, "{i} of {n} matches" role=status), Esc exits.
• Native semantics first: tabs are role=tablist/tab/tabpanel with arrow-key movement; row ⋯ menus are role=menu opened by a button with aria-haspopup and aria-expanded, Esc closes and returns focus; every radio group is native <input type=radio> inside a label (Content settings, Response type, Send to, Version), the custom dot is decorative; expandable standard rows are <details>/<summary> so the chevron needs no script; each selectable sentence in the review panel, Preview and reading mode is an inline <span role=button tabindex=0> with aria-pressed and Enter/Space handling (a native button cannot flow inline through a paragraph: browsers render it as an inline-block, which breaks the line and centres the text).
• Bulk actions are explicit: Send all back lists every standard it will touch with who receives it and what the comment contains, defaults to all ticked, and names the count on the primary button; nothing is sent for a standard the person cannot see in the list.
• Placeholders are not labels: every field has a visible label and a hint with an id; placeholder text is #5f6b7a (4.6:1). "Select a template…" is a placeholder option, never a submitted value.
• Reflow: at ≤ 1100 px the Preview grid drops the thumbnail rail and the Confirm column stacks under the document; at ≤ 900 px the reading-mode Comments panel becomes a bottom sheet (max 60 vh) and the Readiness, Review and Before/after grids go single-column; at 390 px nothing scrolls horizontally and every action stays reachable (WCAG 1.4.10).
• Reflow: at 320 px / 400% zoom nothing scrolls horizontally except the document viewer and data tables inside their own box.
• Native date inputs show a locale placeholder that looks like a value; keep the "Leave the dates blank…" hint linked by aria-describedby and never prefill a signed date.

Per-control names, roles and announcements

UI copy rules (one form everywhere)

• Language checks are checks, not AI. Spelling, grammar, punctuation and style findings say "Spelling", "Grammar", "Punctuation", "Style" with the suggestion; the word "AI" and any credit line never appear on them. The dashboard says "language checks by WProofreader" once, in the last-run line.
• Help text: one lead sentence under each page title; one hint per control, placed directly under it; no floating notes elsewhere on a page. Removed in the prototype: "Descriptions to confirm with the SPOL team", "Updates as you type", "(prototype only: skip ahead)", the landing footnote (its content now lives in the ⋯ menu and the delete dialog).
• finding for every check result ("7 findings · Auto-format", "Links · no findings"); never "issue" or "item". "items" only for the three confirmations.
• Rules: "Run checks again"; AI: "Run again" (then the quote). Help link: "How AI readiness works".
• "Submit date" is the field label; "Submit by {d Mon yyyy}" is what prints.
• Dates: "{d Mon yyyy}" always with the year, "+ , h:mm AM/PM" when time matters ("16 Oct 2026, 4:12 PM", "due 20 Oct 2026"); inputs follow locale; file names use ISO dates.
• Holder: "{Status} · {Role} {Name}" with the role capitalised ("Not started · Writer Tracy Hall", "In review · Reader Dr. Maria Santos"); "Approved · written by {Name}".
• Credits before: "Uses {n} credits for {scope} · {available} left this year"; after: "{n} credits used · {available} left this year · recorded in the audit trail". The same balance must carry through a flow (fixture: 1,866 → 29 used → 1,837 left → Auto-format 4 → 1,833 left).
• Auto-format: button "Auto-format with AI", dialog primary "Auto-format document", chip "Auto-formatted".
• Footer: "Confirm {3−c} more to publish · {v} of {S} sections viewed".
• "Send back" / "Sent back" in sentence case in the source; uppercase chips by CSS only.
• The approval blocker always reads "Not yet: {codes} not approved or excluded by send back" (Step 2 verdict "Final: not yet · {codes} not approved", Step 4 radio, Published line); other blockers are plain sentences in the gate-table order.

Cross-cutting acceptance and seed fixture

Cross-cutting

• Autosave conflict. Given two tabs on Draft 4. When tab A changes the file name and tab B changes it afterwards with the old rev. Then B gets 412, the control reverts to A's value and "Someone else saved this draft. Reload." is announced.
• Deleted elsewhere. Given Draft 2 open in a tab and deleted in another. When the first tab saves. Then 410 and "This draft was deleted by {name}. Back to Publish."
• Published elsewhere. Given Draft 4 open at Step 1 and published in another tab. Then the feed notice "Draft 4 was published by {name} at {time} and can't be edited. Start Draft 5 · View published"; the step's controls become aria-disabled.
• Impersonation. Given an admin impersonating Coordinator C. Then every write listed in §Roles returns 403 and POST …/views is refused; nothing is recorded for C.
• Writer view. Given Writer W opens Draft 4. Then every step is readable, the AI card shows no cost line and Unlock reads "Ask a coordinator or editor to unlock AI readiness".
• Audit names. When every action in §Audit is performed once. Then every row's action matches ^[a-z_]+\.[a-z_]+$ and the set of names equals the §Audit table.
• Ledger invariant. After every scenario in §Credits: sum of entries = balance; no reservation without a settle or refund; a retried settle with the same reservation_id writes nothing.
• Layouts. Every screen at 1390, 1024 (tablet), 390 (phone) and 2560 matches the canvas boards; at 320 px / 400% zoom no horizontal scroll except inside the document viewer and tables.
• AA. axe reports no violations on the 24 screens; every control in §Accessibility has its name, role and reason text.

Seed fixture (prototype state, as of 17 Oct 2026)

• Users: Alex Carter (Coordinator C, owner, tester) · Coordinator C2 (approver) · Priya Natarajan (editor; holds the editor role in the approval chain) · Dr. James Okonkwo (CEO) · Dr. Maria Santos (Accreditation Liaison; also the reader holding 4.2) · Tracy Hall (writer) · Admin (impersonates C). All emails on example.edu.
• Institution: profile address filled; credit balance 1,866, no open holds (29 used → 1,837 → Auto-format 4 → 1,833). Variant: balance 20 (402 test).
• Template "SACSCOC-2018 · Compliance Certification", revision r1; revision r2 drops 6.3.
• Publication A (that template, cycle 2024–2025): Draft 1 published(draft) 17 Sep 2026 · Draft 2 in_progress, step_reached 1 (delete target) · Draft 3 published(draft) 10 Oct 2026 · Draft 4 in_progress, step_reached 4, rev 17, revision r1, preview complete (184 pages; 16 sections = cover, contents, 12 standards, documents, links), confirmations null, C has viewed 9 of 16 (prototype state; variant: 16 of 16), Priya 9 of 16; cover: preparer C, CEO Okonkwo, liaison L, submit_by 15 Dec 2026, logo set, no cover letter; output PDF, file name prefilled.
• Selection (12 of 12): 1.1, 2.1, 3.1, 3.2, 3.3, 4.1, 4.2 (+4.2.a, 4.2.b), 5.1, 5.2, 6.1, 6.2, 6.3. Variant "9 of 12": 6.1–6.3 unselected.
• Chain states (as in the prototype): 3.3 Not started (Writer Tracy Hall) · 4.2 In review (Reader Dr. Maria Santos) · 6.2 In review (Editor Priya Natarajan) · the other 9 Approved ("Approved · written by Tracy Hall"). The template has 12 standards in 6 sections (1 Integrity, 2 Mission, 3 Governance and Administration ×3, 4 Institutional Effectiveness ×2 with 4.2.a/4.2.b, 5 Faculty ×2, 6 Resources ×3).
• Rules run R1 done on the current snapshot, score 62 = 100 − 18 (3 unapproved) − 10 (5 High) − 10 (10 Medium). Findings (17 open, as in the prototype table): 1.1 — Medium open_comment, Medium spelling · 2.1 — Medium spelling ×2, Low style (first person), Low link_changed · 3.1 — High table_width, Medium open_comment · 4.2 — High missing_attachment ×2, Medium image_size, Medium heading_level · 5.2 — Medium open_comment · 6.1 — High table_width, Medium image_size · 6.2 — High missing_attachment (expected count not set), Medium (0 documents) · 3.3 — none (not started). Report-wide (shown only as the Formatting bar and in Preview): Formatting 7 findings (2 wide tables, 3 oversized images, 2 spacing; 4 High, 3 Medium) counted once, not scored. Parts: 4.2.a In review, 4.2.b Approved. not_approved rows carry no scored severity.
• Open comments (3): one each on 1.1, 3.1, 5.2 (the open_comment findings).
• AI: locked; quote "Uses 29 credits for 12 standards · 1,866 left this year". Variant AR1 done (29 charged, 12 of 12 checked, score 58; A2 ran): findings F-4.1-unsupported_claim (High), contradiction "6.1 vs 5.1" (High, faculty count 312 vs 298), F-3.1-clarity (Medium, passage P-3.1-2), F-2.1-evidence_mismatch (Medium); variant AR1i adds F-2.1-injection (passage std:2.1|p:3). Variant AR2 cancelled at 4 of 12 (4 stored results; settle 8, refund 21). Variant AR3: 28 standards selected → 61 credits, awaiting approval from C2.
• Auto-format variant AF1 done: 23 operations (2 tables, 3 images, 1 heading level, 14 paragraph spacing, 3 citations; contents and bookmarks rebuilt, not counted), 4 credits. Undo per change sits in the page margin; the rail has Undo all.
• Publication B "Fifth-Year Interim Report": Final 1 published(final) (withdraw target). Template "QEP Impact Report": no publication (Draft 1 test). Cycle 2025–2026: no versions (empty state).

Worked scenarios (state checks the tests must cover)

1. Edit after confirming. Given 3 of 3 confirmed. When the publisher edits a passage and saves: confirmations null, audit unconfirmed{edited}, stale, Undo hidden, footer "Confirm 3 more to publish". Discard changes nothing.
2. Undo after Auto-format. Given Auto-format applied. When Undo all: audit autoformat.undo, no refund, confirmations cleared, stale. When the publisher then edits and saves: Undo reads "Can't undo after editing".
3. Send back and return. Given 4.2 sent back with exclude on (confirmations null, its AI findings sent_back). When the feed reports it resubmitted: exclusion lifted, stale, confirmations null, findings still sent_back, banner. After Run again, view all, confirm 3, Publish draft → published(draft); Final still says "Not yet: 3.3, 4.2, 6.2 not approved or excluded by send back" until the chain approves them.
4. Cancel an AI run. Given 12 standards, 4 done. When Cancel with none in flight: settle 8, refund 21 (including the 5 for consistency), "Cancelled · 4 of 12 checked". When Unlock again: "21 credits for 8 standards · 4 already checked".
5. Impersonation. Given an admin impersonating X, who has viewed all and confirmed 2 of 3. When the admin opens Step 4: checkboxes aria-disabled, POST → 403, no views recorded for X, X's confirmations untouched.
6. Two confirmers. Given A viewed all and confirmed Sections. When B (9 of 16 viewed) opens Step 4: "1 of 3 confirmed", lock "(9 viewed)". When B views all and confirms the other two: draft_ready, each entry keeps its own by/at.
7. Auto-format by someone else. Given 3 of 3 confirmed, another user starts Auto-format: footer "Wait for Auto-format to finish" via the feed. When it finishes first: confirmations cleared, rev bumped, this user's Publish → 412 "This draft changed since you confirmed it. Reload."
8. Final blocked by one standard. Given the variant where 3.3 and 6.2 are approved and 4.2 is excluded: Final radio reason "Not yet: 4.2 not approved or excluded by send back"; a forced POST returns 409 {code: gate, blockers}. When 4.2 returns approved, Run again, reconfirm → final_ready.
9. Template revised. Given Draft 4 on revision r1; r2 drops 6.3: notice only, Draft 4 unchanged. When Start Draft 5: r2, selection minus 6.3 with the banner, confirmations null, exclusions carried.
10. Writer fixes a finding. Given 3 of 3 confirmed. When a writer fixes a spelling finding: stale, confirmations kept. When Run checks again: finding set differs → only "Findings and comments" cleared, "2 of 3"; identical set → nothing cleared.
11. Approval expires. Given a 61-credit run (28 standards) awaiting approval for 7 days: status approval_expired, reservation released, card "Approval expired · Ask again"; nothing was blocked meanwhile.
12. Delete with a run in flight. Given an AI run with 6 of 12 done. When the owner deletes the draft (confirm dialog adds "An AI readiness run is in progress and will be cancelled"): run cancelled and settled, version deleted, both audited.

Open questions for the SPOL team

1. What do the three response types pull from? The descriptions in Step 1 are placeholders.
2. When a standard is sent back from Publish, does review restart at the Reader when resubmitted, or resume at the level that sent it back?
3. Is "Confirm & Attest" the right term when the CEO and liaison sign the cover separately?
4. Does a Step 4 edit that ticks "Also update All Accreditation" need the standard's approval again?
5. Is 4 credits for Auto-format and 2 per standard for AI readiness the pricing the team wants to launch with?
6. Deferred from the audit. Row menus need roving focus (Up/Down, Home/End) in the build; the prototype only opens and closes them. Content settings should be a real table (th per row and column) if the build keeps the grid. Loading, empty-after-error and offline states are specified in §States but have no boards. The AI score is seeded, not computed from the five bars; the build computes it. After a send back from reading mode, Exit returns to Preview; confirm whether it should land on Step 2 instead.
7. WProofreader contract. Cloud or self-hosted? Cloud sends narrative text to the vendor's AWS US servers with no published retention period; self-hosted keeps it inside SPOL. The dossier and the order form name WProofreader as a sub-processor if the contract is cloud. Also: does the team want the AI writing assistant at all? If yes it sits behind the institution's AI switches, inside the Assist menu, on SPOL's own Bedrock account, never as the vendor's badge.
8. Decision needed (specified in text, beyond the 14 screens): the second-coordinator approval surface ("{name} asks you to approve…"); template-revision banners; Withdraw with reason, Duplicate, Rename and Regenerate (they edge toward a versions overview, which the scope lists as out); large-report grouping above 24 standards; the cross-standard "Which standard should go back?" picker; Remind with its 24-hour limit. Each is kept here so the behaviour is defined if built; none is required for the first release.
9. Still to align after the screen walk (iteration 9, not yet applied): landing seed rows (Draft 1/2/3/4 of Compliance Certification and Fifth-Year Final 1, "6 in this cycle", empty state under 2025–2026); S2c "11 of 12 checked" needs a not-checked row and a 27-credit tally or 12 of 12; "2 contradictions" vs one listed; S2e should read "Out of date · Run again" after the excluding send back; S2d detail panel lacks kind and reviewer question; S3 "Upload file" → "Upload cover letter"; S2 verdict form "Final: not yet · 3.3, 4.2, 6.2 not approved" and the computed formula line; S4b summary-rail copy and L0/S3 subtitles to be quoted in the control tables.
10. Dr. James Okonkwo is the CEO; the approval-chain editor and the substantive-change owner are now Priya Natarajan in the prototype. Confirm the real role holders for the demo data.

Iteration log

Ten review-and-fix passes over the whole set (screens, prompts, spec, this page). Each pass had a different lens.

1. Baseline written.
2. Cross-document consistency. 37 mismatches resolved: credits (29 for 12 standards, 4 for Auto-format) and balances aligned across prototype, plan, flows and AI spec; the rules score reseeded to the formula (62) and what counts stated; "acknowledged items" and "15 items" replaced by 16 open findings; Final for submission made aria-disabled with its reason; the Step 4 edit checkbox and Comments list restored; dates unified to 17 Oct 2026; audit names in one dotted form; decision kinds and ignore-reason values unified; injection message unified; severity added to AI rows; AI bars defined as shares of standards; PRD unlock bullets set to four; superseded round-1 lines marked in the AI spec; formatting counted once report-wide; "23 changes" reseeded; the Auto-format checkbox dropped; share scope corrected; 14 screens; flat landing list; one person per role (Priya Natarajan as editor); cover prints the title as entered; Find and shared zoom in reading mode; Auto-format banner mentions readiness; copy fixes (section labels, confidence colour, "written by", prototype-only links).
3. States, edge cases and error paths. Added: loading and error states per screen; 409 "Start Draft 5 anyway"; 410 deleted-elsewhere; roles and impersonation rules; published-is-immutable (409 on every write); URL per step and reload rules; autosave and 412 behaviour; zero-standard gate; standard removed from the cycle; template revisions; first-run, cancelled and timed-out readiness; writer view of the AI card; second-coordinator approval above 50 credits; AI cancel, timeout, resume and "not checked" rows; injection "Mark cleared"; send-back failures and the all-excluded case; vacant roles and missing address; upload errors; preview build progress and failure; missing evidence files; per-user viewed sections; unsaved-edit prompts; Auto-format failure and undo limits; file-name rules; blocker order for Final; publish in flight, failure, idempotency and 412; published-elsewhere notice; Withdraw and Duplicate; what Draft n+1 inherits; the return from send back; eight new audit entries; four new endpoints.
4. Data model and API. Split draft/final numbering with never-reused counters; rev as the ETag with If-Match on every version write; Snapshot entity defined (when taken, what it holds, content_hash); exclusions derived from open SendBacks per publication; AiResult shared by key with AiFindingDecision carrying across drafts; contradiction findings with two item ids; VersionSectionView so views never 412 other users; PublishJob (async publish); missing endpoints added: rename, cancel readiness, report download, quote token, decline, remind, views, comments, preview, edits, download, link, regenerate; permission matrix and server feed written; cover_valid gate; audit entries for remind, regenerate, quote and rejected edits.
5. State machine. Every gate given a formal definition and a fixed blocker order; final_ready now builds on draft_publishable (closing the 0-standards, in-flight and empty-file-name holes); in_flight defined (awaiting_approval and rules runs do not block); Undo and exclusion added to the stale causes and Undo to what clears confirmations; feed content changes explicitly do not clear confirmations (with the reason); impersonation blocks Start and section views; approval_expired and superseded states added; injection findings refuse Accept/Ignore; published drafts can be neither withdrawn nor deleted; delete cancels runs first; Duplicate semantics fixed; twelve worked scenarios added for the test matrix.
6. Accessibility and copy per control. Every control on the 14 screens given its name, role, keyboard behaviour, focus return and announcement; ten copy rules fixed (finding, Run checks again / Run again, Submit date, dates with year, holder form, credit lines that carry through a flow, Auto-format verbs, footer, chips, "Not yet:"); prototype fixed: Auto-format dialog overlay (was rendering unstyled at the page top), input border and AI button contrast, no strikethrough on closed findings, duplicate hint id on the submit date, aria-pressed removed from radios, Reading mode label, holder capitalisation, "due 20 Oct 2026", balances 1,837 → 1,833.
7. Credits, ledger and audit. The hold is the charge (the 1.5× is SPOL's USD budget, not a credit hold); "left this year" is available, not balance; refunds enumerated incl. the 5 consistency credits whenever A2 does not run; approval request/decline/expire with the approver's screen text; Auto-format scans before charging and fails without charging; delete releases holds; five ledger invariants and a ledger walk; one audit form ai_readiness.run{status} + approval + quoted; not_checked reasons gain cancelled and timed_out; 402 and provider-down texts written.
8. Screen walk against the renders (partial; see Open questions for the rest). Fixture date, balance chain (1,866 → 1,837 → 1,833), viewed count, strikethrough, Formatting severities, Auto-format change counts, Published card and Blocked row aligned to the prototype; prototype: "due 20 Oct 2026", "spacing findings", Final radio reason in the gate-table form, "formatting not yet run" dropped after Auto-format.
9. Report-wide block removed from Step 2 (user review). Formatting, cover letter and links are handled in Preview, Cover and the document; Step 2 keeps the Formatting bar as the link to Auto-format. Handoff row and fixture updated.
10. Auto-format shown end to end (user review). New boards 4b (progress modal with per-kind counts, cancel without charge) and 4d (before-and-after view: representative change per kind, side-by-side fragments with the page edge marked, who decided and the alternative, undo / apply again per change, running count, Undo all). Change-list rows and a "See before and after" button open it. 20 screens.
11. Section content in Preview and reading mode (user review). The document is now rendered per section from a 16-section content set (cover, contents, 12 standards, documents, links) so the navigator, ← →, thumbnails and the comments jump buttons change the page: heading, judgment chip, paragraphs, the 3.1 table, evidence list and page numbers. Inline review comments are stored per section; "Your review" shows the current section's and counts the rest.
12. Review in reading mode (user review). Reading mode now carries the full inline review: click a sentence to comment, letter marks, Your review list with overall comment, Send back / Post, sharing drafts with the Readiness review panel.
13. Demo feedback, six items. Landing: working ⋯ menus per row (drafts and published), required markers and legend on Source / Cycle / Template, Start bottom-aligned with the selects and its reason moved to the legend line, In progress / Published tabs with their own columns and empty states (new board 0b). Help text consolidated to one lead per page and one hint per control. Step 2: the AI panel can be hidden to a one-line strip and shown again. Step 4: a section navigator (‹ select ›, ← →) in the Preview toolbar and in reading mode; reading mode gains a comments side panel with jump-to-section, Resolve / Reopen and a reply box. 18 screens.
14. AI readiness dossier. A user-facing dossier "How AI readiness works" written for coordinators (promises, inputs and exclusions, checks, grounding, score, decisions, privacy, manipulation, cost, quality and fairness, limits, record, FAQ) and added as the in-product help panel (board 2g, linked from both "How AI readiness works" links on Step 2); the AI call spec rewritten as a clean v5 with no review history. 17 screens.
15. Interactive review panel (user review). Board 2e is now live, not a static picture: the comment box appears only when a passage is selected (prototype: click a sentence, click another to extend), the typed comment is added with a letter mark and listed under "Your review", Remove works, the overall comment counts, and the footer labels update ("Send back with n comments" / "Post n comments"). Static copies of the earlier state removed.
16. Inline review comments (user review). Selecting text in the review panel pins a comment to that passage (blue letter marks, distinct from the amber finding marks); an Overall comment covers the standard; drafts are listed in "Your review of {code}" and travel together, either posted to the thread (stays Approved) or compiled into one send-back comment with the findings (new board 2f); ReviewComment entity, draft/post endpoints, send-back payload, audit, a11y and acceptance updated; the readiness findings are unchanged. 16 screens.
17. Review any standard (user review). All 12 selected standards are listed, approved ones too, each with Review and Send back; a Review panel (new board S2f) shows the response with finding and comment marks, the findings, the evidence, the comment thread and an Add-a-comment box that posts to the standard's thread without touching the chain; control table, API (review data, post comment), audit, a11y and an acceptance item added. 15 screens.
18. Per-standard finding details (user review). Readiness rows now expand to list each rule finding with severity, kind, location and detail (comments quoted with author and date), plus the All Accreditation link; first row open by default; control table, a11y row and an acceptance item added.
19. Deliverable read (four roles). 23 contradictions resolved (Auto-format failure copy, finding_key base, kind and status enums, impossible AR1 fixture, standard 7.1, 6.2's state, signers split into cover_valid and signers_complete, in_flight, force-start duplicating the last published version, dialog primary, blocker prefix, "items", Reading mode, one submit-date error, Withdraw and Delete dialog text, hidden text in every rules run, injection excluded from prefill, comment origin, clear note, quote field name, fixture balance); glossary added; reading paths per role; feed events as a table; defaults written out; scenarios moved beside the tests; six text-only behaviours marked "decision needed".
20. Acceptance tests. Every acceptance item rewritten as Given/When/Then with fixture values; Step 3, Step 4 and Published given acceptance lists (they had none); 25 untested behaviours given tests; the summary matrix replaced by cross-cutting tests and a named seed fixture aligned to the prototype (12 of 12 standards, 3.3/4.2/6.2 unapproved, 16 findings → 62); contradictions fixed: score 64→62, Start creates Draft 1, approval_expired as a status, 8 checks vs hidden_text, 60→61 credits, not_approved rows carry no scored severity.
21. Accessibility and enterprise-UX audit (user review). Three passes over the 21 screens: WCAG 2.2 AA (56 items), enterprise SaaS conventions (59) and a bug sweep (50). Fixed in the prototype: native radios everywhere (custom dots decorative), tabs and menus with full roles, <details> rows on Step 2, sentence buttons with aria-pressed, dialogs placed before main with inert background and focus on Cancel, placeholder and border contrast, Select all / Clear all, required markers, one hint per control, lock reasons as text, the Publish-draft gate as aria-disabled with its reason, zoom and status live regions, chips in sentence case, a single Undo all, page numbers and balances reseeded (1,866 → 1,862), reflow at 1100 / 900 / 390 px (reading-mode bottom sheet, single-column grids), the "Published" landing state after a publish (board 0c). Deferred and listed under Open questions: roving focus inside menus, true table semantics for Content settings, loading and error boards, the AI score arithmetic, the Reading-mode exit target after a send back.
22. Demo feedback, round two. Send all back: one dialog sends every standard with findings to the person who holds it, each with its own compiled comment (rule findings and, when AI readiness is unlocked, the open AI recommendations with their suggested fixes), an optional line added to every comment, unapproved ones left out of the draft; the single Send back dialog carries the same AI recommendations checklist; both set the AI findings to Sent back. "What it checks and how" links to the AI readiness dossier from the unlocked panel and both strips. Auto-format dialog relaid out: per-kind checklist with counts, pages and how AI decides, what never changes, what you get afterwards, cost with model and data terms. Order sections dialog in Preview and reading mode (fixed first and last sections, move up/down, moved chips, reset, apply rebuilds contents and clears confirmations). Output options under Publish (contents, page numbers, page breaks, running headers, documents list, cover letter, watermark). New boards 2h, 2i, 4a2; 24 screens. Bug fixed from the demo: since the audit pass the dossier panel (2g), the send-back-with-comments dialog (2f) and the Auto-format progress modal (4b) were missing from their boards because their injection point no longer matched, so "How AI readiness works" appeared to do nothing; all three render again and the dossier panel's "Open the full dossier" opens the published dossier.
23. Free checks aligned with WProofreader (user decision). Spelling, grammar, punctuation and style now run on WProofreader's server API under SPOL's licence, as you type in the editor and in batch at readiness, with SPOL's accreditation dictionary and the institution's dictionary; four rule checks added (Alt text, Placeholder text, Required cover fields, Style) for twelve in all; RuleFinding kinds extended; copy rule that language checks are never labelled AI; the AI writing assistant left disabled; the contract question (cloud vs self-hosted) added to Open questions. Prototype: 2.1 gains a Low style finding (17 open), "12 of 12 checks", "language checks by WProofreader" in the last-run line.