rcf-lite 0.21.0 → 0.22.0

package/blueprints/application-file-upload/probe-packs/application-file-upload.pack.mjs

@@ -0,0 +1,238 @@
+// application-file-upload probe pack (v1.0.0).
+//
+// Four surface-observable checks, one per contract, anchored to the
+// blueprint's contributed AC ids:
+//   AC-23101-1 input surface       (file input, drop-zone, keyboard-opener)
+//   AC-23102-1 progress announcer  (polite tick format + monotonic advance)
+//   AC-23103-1 refusal contract    (aria-describedby, no bytes for refused)
+//   AC-23104-1 chunked transport   (multipart chunks OR tus Upload-Offset)
+//
+// Every check drives the real Playwright browser the T-0 runner
+// injects. URLs are composed by the withUrl(runtimeUrl, path) helper
+// per the round 3 T-3 fix train; no bare string concatenation.
+//
+// Sample-app fixture:
+// packages/rcf-lite/test/fixtures/probe-pack-application-file-upload/
+// Fixture ships /upload with a ?transport=multipart default and a
+// ?transport=tus alternative plus break switches (?break=no-input,
+// ?break=no-live-region, ?break=send-refused, ?break=no-chunks) so
+// the negative runs can be driven from a single boot.
+
+function withUrl(runtimeUrl, path) {
+  return new URL(path, runtimeUrl).toString();
+}
+
+// Progress tick format the announcer TAC pins per ADR-2402:
+//   "<uploaded> of <total> files, <PP> percent"
+const POLITE_FORMAT = /^\d+ of \d+ files, \d{1,3} percent$/;
+
+export default {
+  packName: 'application-file-upload',
+  version: '1.0.0',
+  blueprintSlug: 'application-file-upload',
+  // Applies to any FBS that binds the input TAC or whose navModel
+  // routes name the operator-configured upload path. References BOTH
+  // `tacIds` AND `route` per the loader source-scan rule (T-0
+  // AC-1701-3, cross-check with authoring standard 8c).
+  appliesTo: ({ fbs }) => {
+    const routes = fbs?.designStage?.navModel?.routes ?? [];
+    const tacIds = fbs?.contextRequirements?.tacIds ?? [];
+    if (tacIds.includes('TAC-2401-application-file-upload-input')) return true;
+    return routes.some((r) => typeof r?.path === 'string' && /\/upload(\/|$|\?)/.test(r.path));
+  },
+  boot: { bootCommand: null, waitForUrl: null, waitForSelector: null },
+  checks: [
+    {
+      id: 'AC-23101-1',
+      severity: 'block',
+      description: 'input surface renders a labelled file input, a drop-zone region and a keyboard-focusable opener that opens the picker on Enter (WCAG 2.5.7)',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        await browser.goto(withUrl(runtimeUrl, '/upload'));
+        const dom = await browser.evaluate(() => {
+          const region = document.querySelector('[data-surface="file-upload"]');
+          if (!region) return { present: false };
+          const fileInput = region.querySelector('input[type="file"]');
+          const dropZone = region.querySelector('[data-drop-zone]');
+          const opener = region.querySelector('[data-open-picker]');
+          const inputId = fileInput ? fileInput.id : null;
+          const label = inputId ? document.querySelector(`label[for="${inputId}"]`) : null;
+          const ariaLabel = fileInput ? fileInput.getAttribute('aria-label') : null;
+          const openerFocusable = opener ? opener.tabIndex >= 0 || opener.tagName === 'BUTTON' : false;
+          return {
+            present: true,
+            hasFileInput: !!fileInput,
+            hasDropZone: !!dropZone,
+            hasOpener: !!opener,
+            openerFocusable,
+            hasLabel: !!label,
+            hasAriaLabel: !!ariaLabel,
+          };
+        });
+        if (!dom.present) return { verdict: 'fail', detail: 'upload region [data-surface="file-upload"] not found' };
+        if (!dom.hasFileInput) return { verdict: 'fail', detail: 'upload region missing input[type="file"]' };
+        if (!dom.hasDropZone) return { verdict: 'fail', detail: 'upload region missing [data-drop-zone]' };
+        if (!dom.hasOpener) return { verdict: 'fail', detail: 'upload region missing keyboard [data-open-picker] control (WCAG 2.5.7: drop-zone must not be the only path)' };
+        if (!dom.openerFocusable) return { verdict: 'fail', detail: '[data-open-picker] control not keyboard-focusable' };
+        if (!dom.hasLabel && !dom.hasAriaLabel) return { verdict: 'fail', detail: 'file input carries neither an associated <label> nor aria-label' };
+        return { verdict: 'pass', detail: 'file input, drop-zone and keyboard opener present; accessible name bound' };
+      },
+    },
+    {
+      id: 'AC-23102-1',
+      severity: 'block',
+      description: 'progress announcer emits a polite tick in the closed format and the aggregate percent advances monotonically during an upload',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        await browser.goto(withUrl(runtimeUrl, '/upload?transport=multipart&autostart=1&seed=demo'));
+        // Read the polite wrapper twice with the fixture's polling
+        // interval between so we can prove monotonic advance.
+        const firstRead = await browser.evaluate(() => {
+          const live = document.querySelector('[data-live-region="polite"]');
+          const row = document.querySelector('[data-file-row] [data-file-progress]');
+          return {
+            text: live ? live.textContent.trim() : null,
+            ariaLive: live ? live.getAttribute('aria-live') : null,
+            rowPercent: row ? Number(row.getAttribute('aria-valuenow') ?? row.textContent.trim()) : null,
+          };
+        });
+        // Fixture ticks every ~150ms; poll for advance.
+        const secondRead = await browser.evaluate(async () => {
+          await new Promise((r) => setTimeout(r, 400));
+          const live = document.querySelector('[data-live-region="polite"]');
+          const row = document.querySelector('[data-file-row] [data-file-progress]');
+          return {
+            text: live ? live.textContent.trim() : null,
+            rowPercent: row ? Number(row.getAttribute('aria-valuenow') ?? row.textContent.trim()) : null,
+          };
+        });
+        if (!firstRead.text) return { verdict: 'fail', detail: '[data-live-region="polite"] wrapper missing' };
+        if (firstRead.ariaLive !== 'polite') return { verdict: 'fail', detail: `[data-live-region="polite"] wrapper aria-live expected "polite", got ${JSON.stringify(firstRead.ariaLive)}` };
+        if (!POLITE_FORMAT.test(firstRead.text)) {
+          return { verdict: 'fail', detail: `polite tick text did not match /^\\d+ of \\d+ files, \\d{1,3} percent$/: ${JSON.stringify(firstRead.text)}` };
+        }
+        if (firstRead.rowPercent == null || Number.isNaN(firstRead.rowPercent)) {
+          return { verdict: 'fail', detail: 'per-file [data-file-progress] not present or not numeric' };
+        }
+        if (secondRead.rowPercent == null || secondRead.rowPercent < firstRead.rowPercent) {
+          return { verdict: 'fail', detail: `aggregate progress did not advance monotonically: first=${firstRead.rowPercent}, second=${secondRead.rowPercent}` };
+        }
+        return { verdict: 'pass', detail: `firstTick=${JSON.stringify(firstRead.text)} firstRow=${firstRead.rowPercent} secondRow=${secondRead.rowPercent}` };
+      },
+    },
+    {
+      id: 'AC-23103-1',
+      severity: 'block',
+      description: 'a refused file renders an aria-describedby-bound error, moves focus to the retry control, and is never sent to the server',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        await browser.goto(withUrl(runtimeUrl, '/upload?transport=multipart&seed=refused'));
+        const dom = await browser.evaluate(async () => {
+          // Wait for the upload loop to run to completion (or for
+          // the deadline). We can't read the request log honestly
+          // before the loop has had a chance to run: on the
+          // ?break=send-refused negative branch the refused row's
+          // bytes only land after the loop reaches that row. The
+          // fixture completes a two-file demo set in roughly
+          // 2 * 3 * 120ms + jitter = ~800ms.
+          const deadline = Date.now() + 3000;
+          while (Date.now() < deadline) {
+            const slot = document.querySelector('[data-assertive-slot]');
+            if (slot && slot.textContent && slot.textContent.trim().length > 0) break;
+            await new Promise((r) => setTimeout(r, 100));
+          }
+          const region = document.querySelector('[data-surface="file-upload"]');
+          if (!region) return { present: false };
+          const row = region.querySelector('[data-file-row][data-refused="true"]');
+          if (!row) return { present: true, hasRefusedRow: false };
+          const describedBy = row.getAttribute('aria-describedby');
+          const errId = describedBy ? describedBy.split(/\s+/)[0] : null;
+          const err = errId ? row.querySelector(`#${CSS.escape(errId)}`) || document.getElementById(errId) : null;
+          const reason = row.getAttribute('data-refusal-reason');
+          const retry = row.querySelector('[data-recovery="retry"]');
+          const network = Array.isArray(window.__uploadRequestLog) ? window.__uploadRequestLog : [];
+          const refusedFilename = row.getAttribute('data-refused-filename') || null;
+          const sentRefused = refusedFilename
+            ? network.some((r) => r && typeof r.body === 'string' && r.body.includes(refusedFilename))
+            : false;
+          return {
+            present: true,
+            hasRefusedRow: true,
+            hasErr: !!err,
+            errText: err ? err.textContent.trim() : null,
+            reason,
+            hasRetry: !!retry,
+            refusedFilename,
+            sentRefused,
+            network,
+          };
+        });
+        if (!dom.present) return { verdict: 'fail', detail: 'upload region not found' };
+        if (!dom.hasRefusedRow) return { verdict: 'fail', detail: 'no [data-file-row][data-refused="true"] on the refused seed' };
+        if (!dom.hasErr) return { verdict: 'fail', detail: 'refused row aria-describedby does not resolve to a [data-error-message] element' };
+        const allowedReasons = ['mime-refused', 'size-refused', 'virus-refused'];
+        if (!allowedReasons.includes(dom.reason)) {
+          return { verdict: 'fail', detail: `refused row [data-refusal-reason] expected one of ${JSON.stringify(allowedReasons)}, got ${JSON.stringify(dom.reason)}` };
+        }
+        if (!dom.hasRetry) return { verdict: 'fail', detail: 'refused row missing [data-recovery="retry"] control' };
+        if (dom.sentRefused) {
+          return { verdict: 'fail', detail: `refused filename ${JSON.stringify(dom.refusedFilename)} appears in the upload request log` };
+        }
+        return { verdict: 'pass', detail: `reason=${JSON.stringify(dom.reason)} err=${JSON.stringify(dom.errText)} no refused bytes on the wire (${dom.network.length} recorded upload requests)` };
+      },
+    },
+    {
+      id: 'AC-23104-1',
+      severity: 'block',
+      description: 'the transport uploads in chunks; on the tus branch each PATCH request carries Upload-Offset, on the multipart branch [data-chunks-uploaded] on the DOM exceeds one',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        // Read the transport preference off the base runtimeUrl's own
+        // query string (the withUrl helper resolves a fresh path
+        // against the base, which drops the query). The pack anchors
+        // on the base URL's ?transport= so a caller running the tus
+        // branch passes --url http://.../upload?transport=tus and the
+        // pack observes it here.
+        let configuredTransport = null;
+        try { configuredTransport = new URL(runtimeUrl).searchParams.get('transport'); } catch { /* runtimeUrl may be a bare path in tests */ }
+        const transport = configuredTransport === 'tus' ? 'tus' : 'multipart';
+        await browser.goto(withUrl(runtimeUrl, `/upload?transport=${transport}&seed=large&autostart=1`));
+        const dom = await browser.evaluate(async () => {
+          // Wait for the upload to complete (or for the deadline).
+          // The pack needs to observe the final chunk count, not the
+          // first: an early break at chunks > 0 would read 1 and
+          // spuriously fail the chunked-upload assertion on a fast
+          // fixture. The fixture completes a 5-chunk upload in
+          // roughly 5 * 120ms = 600ms.
+          const deadline = Date.now() + 3000;
+          while (Date.now() < deadline) {
+            const row = document.querySelector('[data-file-row]');
+            const state = row ? row.getAttribute('data-file-state') : null;
+            if (state === 'complete') break;
+            await new Promise((r) => setTimeout(r, 100));
+          }
+          const row = document.querySelector('[data-file-row]');
+          const region = document.querySelector('[data-surface="file-upload"]');
+          const transportAttr = region ? region.getAttribute('data-transport') : null;
+          const chunksUploaded = row ? Number(row.getAttribute('data-chunks-uploaded') ?? '0') : 0;
+          const patchOffsets = Array.isArray(window.__tusPatchOffsets) ? window.__tusPatchOffsets : [];
+          return { transportAttr, chunksUploaded, patchOffsets };
+        });
+        if (dom.transportAttr !== transport) {
+          return { verdict: 'fail', detail: `upload region [data-transport] expected ${JSON.stringify(transport)}, got ${JSON.stringify(dom.transportAttr)}` };
+        }
+        if (dom.chunksUploaded < 2) {
+          return { verdict: 'fail', detail: `[data-chunks-uploaded] expected > 1 (chunked upload), got ${dom.chunksUploaded}` };
+        }
+        if (transport === 'tus') {
+          const numeric = dom.patchOffsets.filter((v) => typeof v === 'number' && Number.isFinite(v));
+          if (numeric.length === 0) {
+            return { verdict: 'fail', detail: `no PATCH request recorded with a numeric Upload-Offset header (window.__tusPatchOffsets=${JSON.stringify(dom.patchOffsets)})` };
+          }
+          return { verdict: 'pass', detail: `tus branch: chunks=${dom.chunksUploaded}, Upload-Offset headers=${JSON.stringify(numeric)}` };
+        }
+        return { verdict: 'pass', detail: `multipart branch: chunks=${dom.chunksUploaded}` };
+      },
+    },
+  ],
+};

package/blueprints/application-forms-wizard/CHANGELOG.md

@@ -0,0 +1,9 @@
+# application-forms-wizard CHANGELOG
+
+## 1.0.0 (visual round T-3, spec 2026-09-06)
+
+- First ratified version of the shelf's forms-wizard blueprint. Five REQs (task-list contract with the closed GOV.UK vocabulary Cannot start yet, Not started, In progress, Completed and an ARIA progressbar wrapper; per-step validation timing with on-blur before first submit then on-change after first failure and a full pass on submit reusing SPA forms-engine TAC-205; error-summary contract with a top-of-page summary, skip links, aria-invalid on the field, aria-describedby to the field-level message and focus moved to the summary heading; summary-review contract with a summary-list per step, Change links per row and answer retention on save; save-and-return contract with a server-side draft table or a client-side local buffer with a sync tick, refuses to ship if neither is wired), eight USs 24101 to 24108 binding one runtime-observable AC per contract plus three cross-cutting cases (linear-vs-free navigation, in-progress list, no-in-progress empty state delegated to application-empty-error-states), three TACs 2501 to 2503 (task-list shell, error-summary contract, draft store), three ADRs 2501 to 2503 (navigation posture linear default with elicited free branch, save-and-return transport with no recommendedDefault so the abandoned-draft loss class does not ship silently, step-indicator shape with task-list default and elicited ARIA progressbar-only or breadcrumb). No new global topics.
+- Ships `probe-packs/application-forms-wizard.pack.mjs`: four surface-observable browser-verify checks anchored one per core contract (`AC-24101-1` task-list, `AC-24103-1` error-summary, `AC-24104-1` summary-review, `AC-24105-1` save-and-return). Every URL is composed by the `withUrl(runtimeUrl, path)` helper per the round 3 T-3 fix train; no bare string concatenation. The pack-level `appliesTo` predicate references BOTH `tacIds` (TAC-2501) AND `route` (the operator-configured wizard-route glob).
+- Ships a dependency-free sample-app fixture at `packages/rcf-lite/test/fixtures/probe-pack-application-forms-wizard/` with a Node HTTP server realising the four wizard surfaces honestly (`/task-list`, `/step/<n>`, `/summary`, `/in-progress`), both save-and-return transports on their query branches (`?draft-store=server` default posting to `/drafts`, `?draft-store=local` writing to `localStorage` with a sync tick), and four break switches (`?break=task-list-vocab`, `?break=no-summary`, `?break=no-retain`, `?break=no-draft`) driving the negative runs from a single boot. The fixture ships its own README naming PORT, every `?step=`, `?draft-store=`, `?nav=`, `?seed=`, `?refused=`, `?preseed=`, `?edit=`, every `?break=`, the manual boot line and the two-line gate-reviewer boot.
+- Declares `suggestedCompanions` `logging` (every step transition, validation failure and save-and-return event writes one request-scoped log line with the correlation identifier and the step slug) and `errorHandling` (the error-summary contract constructs an internal error record per failed field through the applied error-handling factory). Does NOT declare `providesRoles` (leaf blueprint per spec). Does NOT declare `capabilities` and does NOT declare `requiresAppliedCapabilities` (no auth required).
+- Consumes `application-empty-error-states` for the no-in-progress empty state on the /in-progress list surface; the wizard's TAC-2503 delegates the zero-drafts case to the sibling's empty-list state and reads `[data-surface="empty-list"]` with a `[data-recovery="create"]` control from the sibling. T-4 `application-account-settings` will consume this blueprint for its multi-part account setup flow and the summary-review confirm-before-save gate.

package/blueprints/application-forms-wizard/README.md

@@ -0,0 +1,102 @@
+# Forms wizard blueprint (v1.0.0)
+
+Vendor-neutral multi-step forms wizard contract for an rcf-lite application. Ships the GOV.UK Design System task-list pattern with a per-step completion state from the closed vocabulary (Cannot start yet, Not started, In progress, Completed), an ARIA progressbar wrapper on the task-list surface, the per-step validation timing rule (on-blur before first submit, on-change after first failure, full pass on submit), the top-of-page error-summary contract with skip links plus aria-invalid plus focus-to-heading on submit failure, the summary-review pattern with change-per-row and answer retention across an edit-and-save round-trip, and the save-and-return contract with a server-side draft table or a client-side local buffer with a sync tick. Ships a Playwright probe pack under `probe-packs/application-forms-wizard.pack.mjs` whose four checks each anchor one core contract, refuse on the corresponding break switch, and fire against the sample-app fixture on the shelf gate.
+
+## Apply
+
+```
+rcf define blueprint add <path-to>/blueprints/application-forms-wizard
+```
+
+Applies 19 contributions (5 REQs, 8 USs, 3 TACs, 3 ADRs) cleanly on any fresh init project. No `requiresAppliedCapabilities`, no auth prerequisite. The three elicits (ADR-2501 navigation posture with recommendedDefault linear, ADR-2502 save-and-return transport with no recommendedDefault, ADR-2503 step-indicator shape with recommendedDefault task-list) either ship recommended defaults so the apply proceeds silently, or (ADR-2502 alone) require a project answer at apply time because the abandoned-draft loss class is genuinely per-project.
+
+## Anatomy
+
+| Piece | Where | What |
+|---|---|---|
+| Metadata | `blueprint.json` | Slug, version 1.0.0, category `application`, `suggestedCompanions: [logging, errorHandling]`, 19 contributions in the 24xxx / 25xx band |
+| Doc set | `contributions/` | 5 REQs, 8 USs (each carrying one runtime-observable AC), 3 TACs, 3 ADRs |
+| Probe pack | `probe-packs/application-forms-wizard.pack.mjs` | Four surface-observable browser-verify checks, one per core contract |
+| Guide | `guide/application-forms-wizard.md` | Operator-facing: when to reach, when not, mechanism-reach gaps |
+| Coordination vocabulary | `docs/topics.md` | Shelf id band registry update; no new global topics claimed; cross-reference to `application-empty-error-states` for the no-in-progress empty case |
+| Sample-app fixture | `packages/rcf-lite/test/fixtures/probe-pack-application-forms-wizard/` | Dependency-free Node HTTP server the pack is probed against on the shelf gate |
+
+## The task-list vocabulary
+
+The four state strings are a closed enum at v1.0.0. Every task-list row exposes one. A fifth state (Skipped, Locked, or another word) is a v1.1.0 minor bump. Every README, guide, pack `checks[]` and `docs/topics.md` row names the same four strings.
+
+| State | Meaning |
+|---|---|
+| `Cannot start yet` | A prerequisite step is unfinished. On linear navigation the row renders as a non-anchor span. |
+| `Not started` | The step is reachable and has no answers. |
+| `In progress` | The step has partial answers. |
+| `Completed` | The step is fully valid. |
+
+## The validation timing rule
+
+REQ-002 commits to the three-mode timing rule from the GOV.UK Design System error-message pattern. The rule delegates every validation to the SPA blueprint's forms-engine TAC-205 so a project applying `application-spa` does not compose two overlapping engines; a project without `application-spa` supplies an engine of its own choice against TAC-2502's interfaces.
+
+- On blur before the first submit on a step, each field validates on leaving focus.
+- After the first submit failure on a field, subsequent input events on that field update the message on every change (so the operator sees the message clear as they correct it).
+- On the next submit the engine rebuilds the error set from scratch.
+
+## The error-summary contract
+
+On submit refusal the step renders `[data-surface="error-summary"]` at the top of the page with a heading and one skip link per failed field; the skip link's `href` targets the field id. Every failed field carries `aria-invalid="true"` and `aria-describedby` pointing at its per-field error message. On failure focus moves to the summary heading. Per WCAG 2.2 SC 3.3.1 Error Identification and SC 3.3.3 Error Suggestion.
+
+## The summary-review pattern
+
+After every step is Completed the wizard renders `[data-surface="summary-review"]` with one `[data-summary-list-section]` per step. Each section carries a `<dl>` summary list; each row is a `[data-summary-row]` with a `<dt>` label, a `<dd>` value and a `[data-recovery="change"]` link back to the step. Editing on the target step and saving returns to the summary review with every other answer preserved verbatim. Per GOV.UK Design System summary-list pattern; per WCAG 2.2 SC 3.3.4 Error Prevention.
+
+## The save-and-return contract
+
+ADR-2502 commits to two transports without recommendedDefault. The server-side draft table (`POST /drafts` on advance, `GET /drafts` on entry) keys drafts by operator identifier; the client-side local buffer writes into `window.localStorage` under `draft:<wizard-slug>:<step-slug>` and renders `[data-sync-tick]` carrying an ISO-8601 timestamp on every write. A wizard applied without either transport is refused at build gate; ADR-2502 is a required elicit. Per WCAG 2.2 SC 3.3.7 Redundant Entry.
+
+## The no-in-progress empty case
+
+The in-progress-list surface delegates the zero-drafts case to the `application-empty-error-states` empty-list state (`[data-surface="empty-list"]` with a `[data-recovery="create"]` control). The wizard blueprint does not ship its own empty component; a project applying both blueprints reads the same surface from either lane.
+
+## Elicited parameters
+
+- **Step manifest.** The ordered list of steps, one entry per step with a slug, a title and a prerequisites array. Required at apply time; the shipped example manifest is three steps.
+- **Save-and-return transport.** Default: none; ADR-2502 elicits `server-draft-table` or `client-local-buffer`. Required at apply time.
+- **Which steps are optional.** A per-step flag defaulting to `required: true`. Optional steps do not gate the summary review.
+- **Linear or free step navigation.** Default: linear. ADR-2501 elicits `free`.
+- **Step indicator shape.** Default: task-list. ADR-2503 elicits `aria-progressbar-only` or `breadcrumb`.
+
+## The one runtime gate
+
+`probe-packs/application-forms-wizard.pack.mjs` ships four checks the `rcf verify browser` runner invokes on any FBS whose surface binds `TAC-2501-application-forms-wizard-task-list` or whose nav model routes name an operator-configured wizard path. Each check drives the real Playwright browser the runner provisions, reads the DOM and the accessibility tree, and returns a verdict. URLs are composed by the `withUrl(runtimeUrl, path)` helper per the round 3 T-3 fix train; no bare string concatenation.
+
+## Quality bar
+
+WCAG 2.2 AA across every surface: 2.4.6 Headings and Labels (task-list state per row, summary heading on submit failure), 3.3.1 Error Identification (error-summary names every failed field), 3.3.3 Error Suggestion (per-field message names the correction, not just the fault), 3.3.4 Error Prevention (summary-review is reversible before submit), 3.3.7 Redundant Entry (drafts persist across sessions). GOV.UK Design System task-list pattern, summary-list pattern, complete-multiple-tasks pattern. `standardsTrace` on the blueprint is empty (this is a general-enterprise-practice blueprint); each ADR contribution carries `standardsTraceClause` naming the pattern or SC identifier it implements.
+
+## Known mechanism-reach gaps
+
+Runtime-observable ACs the pack does NOT bind directly (checklist section 6.g), listed individually per AC id:
+
+- **AC-24102-1 validation timing.** The pack asserts the field-level message element and the aria-describedby binding via the fixture's refused branch; it does NOT additionally drive a real focus-and-blur sequence through the browser transport nor probe the transition from on-blur-only to on-change-after-failure. A v1.1.0 minor bump can drive keyboard events and diff the message text across events.
+- **AC-24101-1 focus-move-to-task-list.** The pack asserts the task-list rows and the progressbar values; it does NOT additionally probe that focus lands on the task-list on route entry. A v1.1.0 minor bump can drive the accessibility tree and diff.
+- **AC-24103-1 tab-order sweep.** The pack asserts focus lands on the summary heading; it does NOT additionally probe the full tab order across the failed fields. A v1.1.0 minor bump can walk the tab order.
+- **AC-24106-1 linear-vs-free anchor rendering.** The pack does not have a dedicated check; the fixture's `?nav=free` and `?nav=linear` branches render honestly and consumers can probe the shape by inspection. A v1.1.0 minor bump can add a fifth check anchoring AC-24106-1 directly.
+- **AC-24107-1 in-progress list enumeration.** The pack does not have a dedicated check; the `/in-progress` surface is inspected by the anatomy tests. A v1.1.0 minor bump can add a fifth check anchoring AC-24107-1 directly.
+- **AC-24108-1 empty-state delegation.** The pack does not re-probe the empty-list wrapper here; the sibling `application-empty-error-states` pack already asserts it. Consumers apply both blueprints and the empty case is covered by the sibling pack. A v1.1.0 minor bump can add a cross-check that reads the empty wrapper on the `/in-progress` route.
+- **AC-24105-1 cross-tab hydration.** The pack asserts the localStorage write and the sync tick on the local branch; it does NOT additionally probe cross-tab hydration or server-side dedupe on the server branch. Both are v1.1.0 minor-bump candidates.
+- **AC-24104-1 keyboard-focus-on-change-link.** The pack asserts the change link and the answer retention; it does NOT additionally probe that following the change link places keyboard focus on the target field. A v1.1.0 minor bump can drive the click and read the active element on the target step.
+
+## Companions
+
+`suggestedCompanions` declares `logging` (every step transition, validation failure and save-and-return event writes one request-scoped log line with the correlation identifier and the step slug through the applied logger factory) and `errorHandling` (the error-summary contract constructs an internal error record per failed field through the applied error-handling factory). Neither is required to apply the blueprint; a project without a logging companion still renders every state, it just does not emit a per-step log line.
+
+## Consumers
+
+- `application-account-settings` (T-4 of this round) consumes the wizard task-list pattern for its multi-part account setup flow and the summary-review pattern for its confirm-before-save gate.
+
+## Composition with application-spa
+
+`application-spa` REQ-006 ships the forms-engine (TAC-205) that this blueprint's TAC-2502 delegates validation to. This blueprint composes with SPA; the topic-ownership boundary lives in `docs/topics.md`. SPA holds the forms-engine and the field-component library; this sibling holds the wizard shell, the task-list, the error-summary contract, the summary review and the save-and-return draft store.
+
+## Composition with application-empty-error-states
+
+The in-progress list's zero-drafts case delegates to the sibling's empty-list surface. This blueprint's TAC-2503 does not ship an empty component; the consumer applies both blueprints and the empty case reads consistently across the application. The topic-ownership boundary line lives in `docs/topics.md`, cross-referenced from the sibling's `docs/topics.md`.

package/blueprints/application-forms-wizard/blueprint.json

@@ -0,0 +1,120 @@
+{
+  "slug": "application-forms-wizard",
+  "version": "1.0.0",
+  "category": "application",
+  "suggestedCompanions": [
+    {
+      "role": "logging",
+      "reason": "Every step transition, validation failure and save-and-return event writes one request-scoped log line with the correlation identifier and the step slug through the applied logger factory."
+    },
+    {
+      "role": "errorHandling",
+      "reason": "The error-summary contract constructs an internal error record per failed field through the applied error-handling factory so the aria-describedby binding renders a consistent message shape across steps."
+    }
+  ],
+  "contributions": [
+    {
+      "id": "application-forms-wizard-REQ-001",
+      "kind": "req",
+      "path": "requirements/application-forms-wizard-req-001.json"
+    },
+    {
+      "id": "application-forms-wizard-REQ-002",
+      "kind": "req",
+      "path": "requirements/application-forms-wizard-req-002.json"
+    },
+    {
+      "id": "application-forms-wizard-REQ-003",
+      "kind": "req",
+      "path": "requirements/application-forms-wizard-req-003.json"
+    },
+    {
+      "id": "application-forms-wizard-REQ-004",
+      "kind": "req",
+      "path": "requirements/application-forms-wizard-req-004.json"
+    },
+    {
+      "id": "application-forms-wizard-REQ-005",
+      "kind": "req",
+      "path": "requirements/application-forms-wizard-req-005.json"
+    },
+    {
+      "id": "application-forms-wizard-US-24101",
+      "kind": "us",
+      "path": "user-stories/application-forms-wizard-us-24101.json"
+    },
+    {
+      "id": "application-forms-wizard-US-24102",
+      "kind": "us",
+      "path": "user-stories/application-forms-wizard-us-24102.json"
+    },
+    {
+      "id": "application-forms-wizard-US-24103",
+      "kind": "us",
+      "path": "user-stories/application-forms-wizard-us-24103.json"
+    },
+    {
+      "id": "application-forms-wizard-US-24104",
+      "kind": "us",
+      "path": "user-stories/application-forms-wizard-us-24104.json"
+    },
+    {
+      "id": "application-forms-wizard-US-24105",
+      "kind": "us",
+      "path": "user-stories/application-forms-wizard-us-24105.json"
+    },
+    {
+      "id": "application-forms-wizard-US-24106",
+      "kind": "us",
+      "path": "user-stories/application-forms-wizard-us-24106.json"
+    },
+    {
+      "id": "application-forms-wizard-US-24107",
+      "kind": "us",
+      "path": "user-stories/application-forms-wizard-us-24107.json"
+    },
+    {
+      "id": "application-forms-wizard-US-24108",
+      "kind": "us",
+      "path": "user-stories/application-forms-wizard-us-24108.json"
+    },
+    {
+      "id": "TAC-2501-application-forms-wizard-task-list",
+      "kind": "tac",
+      "path": "tacs/tac-2501-application-forms-wizard-task-list.json"
+    },
+    {
+      "id": "TAC-2502-application-forms-wizard-error-summary",
+      "kind": "tac",
+      "path": "tacs/tac-2502-application-forms-wizard-error-summary.json"
+    },
+    {
+      "id": "TAC-2503-application-forms-wizard-draft-store",
+      "kind": "tac",
+      "path": "tacs/tac-2503-application-forms-wizard-draft-store.json"
+    },
+    {
+      "id": "ADR-2501-application-forms-wizard-navigation",
+      "kind": "adr",
+      "path": "adrs/adr-2501-application-forms-wizard-navigation.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "GOV.UK Design System step-by-step navigation pattern"
+    },
+    {
+      "id": "ADR-2502-application-forms-wizard-save-and-return",
+      "kind": "adr",
+      "path": "adrs/adr-2502-application-forms-wizard-save-and-return.json",
+      "elicited": true,
+      "standardsTraceClause": "GOV.UK Design System save and return pattern; generic enterprise practice"
+    },
+    {
+      "id": "ADR-2503-application-forms-wizard-step-indicator",
+      "kind": "adr",
+      "path": "adrs/adr-2503-application-forms-wizard-step-indicator.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "GOV.UK Design System task list pattern; WCAG 2.2 SC 2.4.6 Headings and Labels"
+    }
+  ]
+}

package/blueprints/application-forms-wizard/contributions/adrs/adr-2501-application-forms-wizard-navigation.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-2501-application-forms-wizard-navigation",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Step navigation posture is linear by default with free-step as the elicited alternative",
+  "context": "Wizards divide on how much freedom the operator has to jump between steps. A linear posture forbids advancing until the current step is Completed and disables backward jumps to steps whose prerequisites the domain says must be Completed first (an application with a payment step gated on shipping details, say). A free posture lets the operator pick any step at any time and computes the completion states independently. Neither is wrong; the choice is a per-project posture driven by the domain the wizard serves. GOV.UK Design System publishes the step-by-step navigation pattern as the widely-adopted linear model.",
+  "decision": "Adopt linear as the recommended default. The shipped task-list disables rows whose [data-step-state] is Cannot start yet by rendering them as spans without an href. Projects that want free navigation elicit ADR-2501 to the free branch and every row renders as an anchor. recommendedDefault is true because linear is the safer starting posture for a domain the shelf blueprint does not know; elicited is true because the switch is a real per-project answer.",
+  "consequences": "Projects on the default get a linear wizard out of the box with no configuration; the task-list refuses out-of-order entry and the operator walks the manifest in order. Projects electing free get an unconstrained task-list at the price of surfacing every prerequisite the domain implies through the manifest and the copy. All three step-indicator shapes (ADR-2503) render on both branches; the difference is only the click-through on rows whose prerequisites are unfinished.",
+  "alternativesConsidered": [
+    {
+      "name": "Free-step as the shipped default",
+      "summary": "Ship free navigation everywhere and rely on per-step validation to catch out-of-order entries.",
+      "reasonNotChosen": "Loses the affordance the domain often needs (a payment step should not be reachable before shipping details); reads as more forgiving but pushes the domain rule into copy rather than into the surface."
+    },
+    {
+      "name": "Two-step wizard with no task-list",
+      "summary": "Ship no task-list at all and rely on Back and Next.",
+      "reasonNotChosen": "Loses the completion overview and the ARIA progressbar; a wizard with three or more steps benefits materially from the task-list surface."
+    }
+  ],
+  "createdAt": "2026-09-06T18:00:00Z",
+  "updatedAt": "2026-09-06T18:00:00Z"
+}

package/blueprints/application-forms-wizard/contributions/adrs/adr-2502-application-forms-wizard-save-and-return.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-2502-application-forms-wizard-save-and-return",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Save-and-return transport ships as server-side draft table or client-side local buffer with no recommendedDefault",
+  "context": "The abandoned-draft loss class is genuinely per-project. An application whose operators sign in on shared kiosks with rotating identities cannot rely on a local buffer keyed to the browser; the draft must live on a server-side draft table keyed to the operator identifier so the operator can walk to a different device and continue. An application whose operators run on a single personal device with intermittent connectivity is better served by a local buffer that survives a network drop and syncs on the next flush. A shipped default in either direction quietly ships the wrong loss class for at least one common posture, so this blueprint declines to pick one.",
+  "decision": "Ship two transports: server-draft-table (POST /drafts and GET /drafts against operator-configured endpoints) and client-local-buffer (localStorage keyed by wizard slug and step slug with a per-write ISO-8601 sync tick). ADR-2502 records the elicit as required, elicited is true, and no recommendedDefault is committed: a project applying application-forms-wizard MUST answer the elicit and the build gate refuses when neither transport is wired. The GOV.UK Design System save and return pattern informs the server branch; the local branch is generic enterprise practice.",
+  "consequences": "Projects with a server-side draft table get audit-trail-clean per-operator persistence at the price of a server endpoint and a persistence adapter. Projects with a client-side local buffer get zero-server-work persistence at the price of losing drafts when the operator switches device. A project that has not decided cannot silently ship on the shelf default because there is none; the elicit is a real gate. The pack drives both transports on the sample fixture and refuses on the ?draft-store=none branch to prove the missing-transport case fails at severity block.",
+  "alternativesConsidered": [
+    {
+      "name": "Server-only as the shipped default",
+      "summary": "Ship server-draft-table as the sole transport and refuse projects without a server endpoint.",
+      "reasonNotChosen": "Refuses to apply on a hobby SPA with no server; the shelf blueprint has to be reachable by every applied posture."
+    },
+    {
+      "name": "Local-only as the shipped default",
+      "summary": "Ship client-local-buffer as the sole transport and refuse projects with cross-device operators.",
+      "reasonNotChosen": "Ships the wrong loss class for kiosk-shape and multi-device operators; audit-trail-first projects cannot use it."
+    }
+  ],
+  "createdAt": "2026-09-06T18:00:00Z",
+  "updatedAt": "2026-09-06T18:00:00Z"
+}

package/blueprints/application-forms-wizard/contributions/adrs/adr-2503-application-forms-wizard-step-indicator.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-2503-application-forms-wizard-step-indicator",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Step indicator shape defaults to task-list, with ARIA progressbar and breadcrumb as elicited alternatives",
+  "context": "Wizards indicate the operator's position through one of three widely-adopted shapes. A task-list (the GOV.UK Design System task list pattern) surfaces every step as a row with a completion state; the operator sees the whole shape at a glance and can jump to a specific step. An ARIA progressbar surfaces a single wrapper carrying aria-valuenow and aria-valuemax; the operator gets a compact completion count without a per-step enumeration. A breadcrumb surfaces the linear path with the current step highlighted; the operator sees the trail and can walk back but does not see the future steps' state. All three satisfy WCAG 2.2 SC 2.4.6 Headings and Labels; the choice is a per-project posture driven by the wizard's shape and the design system.",
+  "decision": "Adopt task-list as the recommended default; the shipped surface renders it with the ARIA progressbar wrapper on top per REQ-001 so every project gets the completion count for free. Projects that prefer a compact indicator elicit the aria-progressbar-only branch and the task-list rows collapse into the progressbar's aria-valuetext. Projects that prefer a trail elicit the breadcrumb branch and the task-list rows render as breadcrumb entries. recommendedDefault is true on task-list; elicited is true because the alternative is a real per-project answer.",
+  "consequences": "Projects on the default get the task-list plus the progressbar with no configuration; the pack anchors on the task-list surface and the progressbar wrapper. Projects electing aria-progressbar-only lose the per-step enumeration and the row jump; the pack skips AC-24106-1 (linear-vs-free row rendering has no rows). Projects electing breadcrumb keep the trail affordance and lose the future-state enumeration; the pack asserts the breadcrumb entries in place of the task-list rows.",
+  "alternativesConsidered": [
+    {
+      "name": "ARIA progressbar as the shipped default",
+      "summary": "Ship the compact progressbar and no task-list.",
+      "reasonNotChosen": "Loses the completion overview and the row-jump affordance; a wizard with three or more steps benefits materially from the task-list."
+    },
+    {
+      "name": "Breadcrumb as the shipped default",
+      "summary": "Ship the trail and no task-list.",
+      "reasonNotChosen": "Loses the future-step state enumeration; the operator cannot see at a glance what remains."
+    }
+  ],
+  "createdAt": "2026-09-06T18:00:00Z",
+  "updatedAt": "2026-09-06T18:00:00Z"
+}

package/blueprints/application-forms-wizard/contributions/requirements/application-forms-wizard-req-001.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-forms-wizard-REQ-001",
+  "prdId": "PRD-001",
+  "title": "Task-list contract: per-step completion state announced through the GOV.UK vocabulary Cannot start yet, Not started, In progress, Completed",
+  "description": "The wizard renders a task-list surface listing every step in a stable order. Each step exposes one of four completion states from the closed GOV.UK vocabulary: Cannot start yet (a prerequisite step is unfinished), Not started (the step is reachable but has no answers), In progress (the step has partial answers), Completed (the step is fully valid). The task-list carries an ARIA progressbar shape naming the total step count and the number completed. The four state strings are a closed enum at v1.0.0; a fifth state is a v1.1.0 minor bump. The surface anchors on TAC-2501 (task-list shell) and is vendor-neutral: the blueprint contributes WHAT strings under WHAT condition, not the visual token set.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Per visual round 4 spec section 5.3, REQ 1.",
+  "tags": [
+    "blueprint:application-forms-wizard",
+    "category:01-task-list-contract"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T18:00:00Z",
+  "updatedAt": "2026-09-06T18:00:00Z"
+}

package/blueprints/application-forms-wizard/contributions/requirements/application-forms-wizard-req-002.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-forms-wizard-REQ-002",
+  "prdId": "PRD-001",
+  "title": "Per-step validation timing: on-blur before first submit, then on-change after the first failure, and a full pass on submit reusing the SPA forms-engine",
+  "description": "Every step validates its own answers before advancing. Validation timing is on-blur before the first submit attempt on a step (a field validates when the operator leaves it), then on-change after the first submit failure on that field (so the operator sees the message clear as they correct it), and a full pass on submit that rebuilds the error set from scratch. Validation delegates to the SPA blueprint's forms-engine TAC-205 so a project already applying application-spa does not compose two overlapping engines. On refusal the engine surfaces the failed fields to the error-summary contract (REQ-003). The timing rule is a closed set at v1.0.0; different projects can elicit stricter (validate on every change from the start) via a project-level ADR but the shipped default is the three-mode rule above.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Per visual round 4 spec section 5.3, REQ 2.",
+  "tags": [
+    "blueprint:application-forms-wizard",
+    "category:02-validation-timing"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T18:00:00Z",
+  "updatedAt": "2026-09-06T18:00:00Z"
+}

package/blueprints/application-forms-wizard/contributions/requirements/application-forms-wizard-req-003.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-forms-wizard-REQ-003",
+  "prdId": "PRD-001",
+  "title": "Error-summary contract: top-of-page summary with skip links per failed field, aria-invalid on the field, and focus moved to the summary heading on submit failure",
+  "description": "On submit refusal the step renders a top-of-page error summary region carrying a heading and one skip link per failed field. Each skip link's target is a focusable field element; the field carries aria-invalid=\"true\" while unresolved and aria-describedby pointing at the field-level error message. On submit failure the client moves focus to the summary heading so a screen-reader user hears the error class and can walk the skip links; visual users see the heading anchor scroll into view. The summary and per-field bindings anchor on TAC-2502 (error-summary contract). Per WCAG 2.2 SC 3.3.1 Error Identification and SC 3.3.3 Error Suggestion.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Per visual round 4 spec section 5.3, REQ 3.",
+  "tags": [
+    "blueprint:application-forms-wizard",
+    "category:03-error-summary"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T18:00:00Z",
+  "updatedAt": "2026-09-06T18:00:00Z"
+}