rcf-lite 0.21.0 → 0.23.0

package/blueprints/application-forms-wizard/probe-packs/application-forms-wizard.pack.mjs

@@ -0,0 +1,233 @@
+// application-forms-wizard probe pack (v1.0.0).
+//
+// Four surface-observable checks, one per core contract, anchored
+// to the blueprint's contributed AC ids:
+//   AC-24101-1 task-list (per-step state from the GOV.UK vocabulary,
+//              ARIA progressbar wrapper)
+//   AC-24103-1 error-summary (top-of-page summary, skip links,
+//              aria-invalid on the field, focus to summary heading)
+//   AC-24104-1 summary-review (summary-list rows, Change links,
+//              answer retention across an edit-and-save round-trip)
+//   AC-24105-1 save-and-return (server-draft POST/GET round-trip on
+//              ?draft-store=server, localStorage write plus sync tick
+//              on ?draft-store=local; the ?draft-store=none branch
+//              proves the missing-transport refusal on the fixture)
+//
+// 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-forms-wizard/
+// Fixture ships four routes (/task-list, /step/<n>, /summary,
+// /in-progress) plus query switches (?draft-store=server|local|none,
+// ?nav=linear|free, ?step=<n>) and break switches
+// (?break=task-list-vocab, ?break=no-summary, ?break=no-retain,
+// ?break=no-draft) so the negative runs can be driven from a
+// single boot.
+
+function withUrl(runtimeUrl, path) {
+  return new URL(path, runtimeUrl).toString();
+}
+
+// GOV.UK task-list vocabulary (closed enum, v1.0.0). A fifth state
+// is a v1.1.0 minor bump.
+const TASK_LIST_STATES = ['Cannot start yet', 'Not started', 'In progress', 'Completed'];
+
+export default {
+  packName: 'application-forms-wizard',
+  version: '1.0.0',
+  blueprintSlug: 'application-forms-wizard',
+  // Applies to any FBS that realises the task-list TAC or whose
+  // navModel routes name an operator-configured wizard 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-2501-application-forms-wizard-task-list')) return true;
+    return routes.some((r) => typeof r?.path === 'string' && /\/(?:task-list|step|summary|in-progress|wizard)(\/|$|\?)/.test(r.path));
+  },
+  boot: { bootCommand: null, waitForUrl: null, waitForSelector: null },
+  checks: [
+    {
+      id: 'AC-24101-1',
+      severity: 'block',
+      description: 'task-list surface renders every step with a data-step-state from the closed GOV.UK vocabulary {Cannot start yet, Not started, In progress, Completed}, wraps them in an ARIA progressbar with aria-valuenow, aria-valuemax and aria-valuetext, and enumerates the step slugs in the manifest order (per WCAG 2.2 SC 2.4.6 Headings and Labels).',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        await browser.goto(withUrl(runtimeUrl, '/task-list'));
+        const dom = await browser.evaluate(() => {
+          const region = document.querySelector('[data-surface="task-list"]');
+          if (!region) return { present: false };
+          const progressbar = region.querySelector('[role="progressbar"]');
+          const rows = Array.from(region.querySelectorAll('[data-step-slug]'));
+          return {
+            present: true,
+            hasProgressbar: !!progressbar,
+            valueNow: progressbar ? progressbar.getAttribute('aria-valuenow') : null,
+            valueMax: progressbar ? progressbar.getAttribute('aria-valuemax') : null,
+            valueText: progressbar ? progressbar.getAttribute('aria-valuetext') : null,
+            rows: rows.map((r) => ({ slug: r.getAttribute('data-step-slug'), state: r.getAttribute('data-step-state') })),
+          };
+        });
+        if (!dom.present) return { verdict: 'fail', detail: 'task-list region [data-surface="task-list"] not found' };
+        if (!dom.hasProgressbar) return { verdict: 'fail', detail: 'task-list region missing [role="progressbar"] wrapper' };
+        if (!dom.valueNow || !dom.valueMax || !dom.valueText) {
+          return { verdict: 'fail', detail: `progressbar missing aria attributes: valuenow=${JSON.stringify(dom.valueNow)} valuemax=${JSON.stringify(dom.valueMax)} valuetext=${JSON.stringify(dom.valueText)}` };
+        }
+        if (dom.rows.length < 2) return { verdict: 'fail', detail: `task-list rows must number at least 2; got ${dom.rows.length}` };
+        const closedStates = ['Cannot start yet', 'Not started', 'In progress', 'Completed'];
+        const badRow = dom.rows.find((r) => !r.slug || !closedStates.includes(r.state));
+        if (badRow) return { verdict: 'fail', detail: `task-list row outside the closed GOV.UK vocabulary: ${JSON.stringify(badRow)}` };
+        return { verdict: 'pass', detail: `rows=${dom.rows.length} progressbar=${JSON.stringify({ now: dom.valueNow, max: dom.valueMax, text: dom.valueText })}` };
+      },
+    },
+    {
+      id: 'AC-24103-1',
+      severity: 'block',
+      description: 'On submit refusal the step renders [data-surface="error-summary"] with a heading, one anchor per failed field whose href points at the field id, every failed field carries aria-invalid="true" and aria-describedby referencing its per-field error message, and focus lands on the summary heading (per WCAG 2.2 SC 3.3.1 Error Identification and SC 3.3.3 Error Suggestion).',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        // The fixture step 2 route pre-renders the error summary shape
+        // on ?refused=1 so the pack can read the DOM without driving
+        // the submit click through the browser transport.
+        await browser.goto(withUrl(runtimeUrl, '/step/2?refused=1'));
+        const dom = await browser.evaluate(() => {
+          const region = document.querySelector('[data-surface="error-summary"]');
+          if (!region) return { present: false };
+          const heading = region.querySelector('h2, [role="heading"]');
+          const anchors = Array.from(region.querySelectorAll('a[href^="#"]'));
+          const anchorHrefs = anchors.map((a) => a.getAttribute('href'));
+          const invalidFields = Array.from(document.querySelectorAll('[aria-invalid="true"]'));
+          const describedFields = invalidFields.map((f) => ({
+            id: f.id,
+            describedBy: f.getAttribute('aria-describedby'),
+            messagePresent: f.getAttribute('aria-describedby')
+              ? !!document.getElementById(f.getAttribute('aria-describedby'))
+              : false,
+          }));
+          const activeSelector = document.activeElement
+            ? [document.activeElement.tagName.toLowerCase(), document.activeElement.getAttribute('data-role') || document.activeElement.id || ''].filter(Boolean).join('#')
+            : null;
+          return {
+            present: true,
+            headingText: heading ? heading.textContent.trim() : null,
+            anchorHrefs,
+            invalidFields: describedFields,
+            activeSelector,
+            activeIsHeading: !!(document.activeElement && heading && document.activeElement === heading),
+          };
+        });
+        if (!dom.present) return { verdict: 'fail', detail: 'error-summary region [data-surface="error-summary"] not found' };
+        if (!dom.headingText) return { verdict: 'fail', detail: 'error-summary region missing heading' };
+        if (dom.anchorHrefs.length < 1) return { verdict: 'fail', detail: 'error-summary region carries no skip links' };
+        if (dom.invalidFields.length < 1) return { verdict: 'fail', detail: 'no fields carry aria-invalid="true" on submit refusal' };
+        const unbound = dom.invalidFields.find((f) => !f.describedBy || !f.messagePresent);
+        if (unbound) return { verdict: 'fail', detail: `field ${JSON.stringify(unbound.id)} missing aria-describedby or its message: ${JSON.stringify(unbound)}` };
+        if (!dom.activeIsHeading) return { verdict: 'fail', detail: `focus did not land on the summary heading; activeSelector=${JSON.stringify(dom.activeSelector)}` };
+        return { verdict: 'pass', detail: `anchors=${dom.anchorHrefs.length} invalidFields=${dom.invalidFields.length} heading=${JSON.stringify(dom.headingText)}` };
+      },
+    },
+    {
+      id: 'AC-24104-1',
+      severity: 'block',
+      description: 'summary-review surface renders one [data-summary-list-section] per step with a <dl> holding [data-summary-row] entries, every row exposes a [data-recovery="change"] link, and after following one Change link and saving a new value the other rows retain their original values verbatim (per WCAG 2.2 SC 3.3.4 Error Prevention).',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        // The fixture seeds three steps of answers on ?seed=complete
+        // so /summary renders fully populated for the pack.
+        await browser.goto(withUrl(runtimeUrl, '/summary?seed=complete'));
+        const before = await browser.evaluate(() => {
+          const region = document.querySelector('[data-surface="summary-review"]');
+          if (!region) return { present: false };
+          const sections = Array.from(region.querySelectorAll('[data-summary-list-section]'));
+          const rows = Array.from(region.querySelectorAll('[data-summary-row]'));
+          const rowSnapshot = rows.map((r) => {
+            const dt = r.querySelector('dt');
+            const dd = r.querySelector('dd');
+            const change = r.querySelector('[data-recovery="change"]');
+            return {
+              label: dt ? dt.textContent.trim() : null,
+              value: dd ? dd.textContent.trim() : null,
+              hasChange: !!change,
+              slug: r.getAttribute('data-field-slug') || null,
+            };
+          });
+          return { present: true, sectionCount: sections.length, rows: rowSnapshot };
+        });
+        if (!before.present) return { verdict: 'fail', detail: 'summary-review region [data-surface="summary-review"] not found' };
+        if (before.sectionCount < 1) return { verdict: 'fail', detail: 'summary-review carries zero [data-summary-list-section] blocks' };
+        if (before.rows.length < 1) return { verdict: 'fail', detail: 'summary-review carries zero [data-summary-row] entries' };
+        const rowMissingChange = before.rows.find((r) => !r.hasChange);
+        if (rowMissingChange) return { verdict: 'fail', detail: `summary-review row missing [data-recovery="change"] link: ${JSON.stringify(rowMissingChange)}` };
+        // Drive the edit-and-save round-trip via the fixture's
+        // synthetic ?edit=<slug>&value=<new> query on /summary so the
+        // browser transport does not require a full form submit path.
+        const editTarget = before.rows[0];
+        if (!editTarget.slug) return { verdict: 'fail', detail: 'first summary row is missing [data-field-slug]; the fixture must expose the slug for the round-trip' };
+        const newValue = `edited-value-${Date.now()}`;
+        await browser.goto(withUrl(runtimeUrl, `/summary?seed=complete&edit=${encodeURIComponent(editTarget.slug)}&value=${encodeURIComponent(newValue)}`));
+        const after = await browser.evaluate(() => {
+          const region = document.querySelector('[data-surface="summary-review"]');
+          const rows = Array.from(region.querySelectorAll('[data-summary-row]'));
+          return rows.map((r) => {
+            const dd = r.querySelector('dd');
+            return {
+              slug: r.getAttribute('data-field-slug') || null,
+              value: dd ? dd.textContent.trim() : null,
+            };
+          });
+        });
+        const editedAfter = after.find((r) => r.slug === editTarget.slug);
+        if (!editedAfter || editedAfter.value !== newValue) {
+          return { verdict: 'fail', detail: `edited row did not update to the new value; expected ${JSON.stringify(newValue)}, got ${JSON.stringify(editedAfter && editedAfter.value)}` };
+        }
+        const drifted = before.rows.filter((r) => r.slug && r.slug !== editTarget.slug).find((r) => {
+          const afterRow = after.find((a) => a.slug === r.slug);
+          return !afterRow || afterRow.value !== r.value;
+        });
+        if (drifted) return { verdict: 'fail', detail: `an unedited row changed value across the edit-and-save round-trip: ${JSON.stringify(drifted)}` };
+        return { verdict: 'pass', detail: `sections=${before.sectionCount} rows=${before.rows.length} editedSlug=${JSON.stringify(editTarget.slug)}` };
+      },
+    },
+    {
+      id: 'AC-24105-1',
+      severity: 'block',
+      description: 'save-and-return contract ships either the server-side draft table (?draft-store=server issues POST /drafts on advance and GET /drafts returns the persisted answer) or the client-side local buffer (?draft-store=local writes to window.localStorage and renders [data-sync-tick] carrying an ISO-8601 timestamp on every write). The ?draft-store=none branch refuses at severity block (per WCAG 2.2 SC 3.3.7 Redundant Entry).',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        // The fixture pre-drives the write on /step/1 boot so the
+        // pack can inspect the persisted state without simulating a
+        // form submit through the browser transport.
+        await browser.goto(withUrl(runtimeUrl, '/step/1?draft-store=server&preseed=1'));
+        const server = await browser.evaluate(async () => {
+          const res = await fetch('/drafts');
+          const body = res.ok ? await res.json() : null;
+          return { status: res.status, body };
+        });
+        if (server.status !== 200 || !server.body || typeof server.body !== 'object') {
+          return { verdict: 'fail', detail: `server-draft GET /drafts did not return a JSON body: status=${server.status} body=${JSON.stringify(server.body)}` };
+        }
+        const persistedFields = server.body.fields;
+        if (!persistedFields || Object.keys(persistedFields).length < 1) {
+          return { verdict: 'fail', detail: `server-draft body carries no persisted fields: ${JSON.stringify(server.body)}` };
+        }
+        await browser.goto(withUrl(runtimeUrl, '/step/1?draft-store=local&preseed=1'));
+        const local = await browser.evaluate(() => {
+          const keys = Object.keys(window.localStorage).filter((k) => k.startsWith('draft:application-forms-wizard:'));
+          const tick = document.querySelector('[data-sync-tick]');
+          return { keys, tickText: tick ? tick.getAttribute('data-sync-tick') || tick.textContent.trim() : null };
+        });
+        if (local.keys.length < 1) {
+          return { verdict: 'fail', detail: `client-local localStorage did not carry a namespaced draft key: keys=${JSON.stringify(local.keys)}` };
+        }
+        if (!local.tickText || !/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/.test(local.tickText)) {
+          return { verdict: 'fail', detail: `client-local [data-sync-tick] missing or not ISO-8601: ${JSON.stringify(local.tickText)}` };
+        }
+        return { verdict: 'pass', detail: `serverPersistedFields=${JSON.stringify(Object.keys(persistedFields))} localKeys=${local.keys.length} tick=${JSON.stringify(local.tickText)}` };
+      },
+    },
+  ],
+};

package/blueprints/application-notifications-in-app/docs/topics.md

@@ -22,6 +22,15 @@ The `application-notifications-` prefix is reserved for the sibling channel blue
 | application-dashboard | 19101-19899 | 20xx | shipped v1.0.0 | none |
 | application-notifications-in-app | 20101-20899 | 21xx | shipped v1.0.0 | none |
 | application-admin-console | 21101-21899 | 22xx | shipped v1.0.0 | none |
+| application-empty-error-states | 22101-22899 | 23xx | shipped v1.0.0 | none |
+| application-file-upload | 23101-23899 | 24xx | shipped v1.0.0 | none |
+| application-forms-wizard | 24101-24899 | 25xx | shipped v1.0.0 | none |
+| application-account-settings | 25101-25899 | 26xx | shipped v1.0.0 | none |
+| application-onboarding-tour | 26101-26899 | 27xx | shipped v1.0.0 | none |
+| persistence-data-postgres | 27101-27899 | 28xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| object-storage-s3 | 28101-28899 | 29xx | shipped v1.0.0 | `objectStorageContract` |
+| messaging-queue-cloudflare | 29101-29899 | 30xx | shipped v1.0.0 | `deliverySemantics` |
+| jobs-background | 30101-30899 | 31xx | shipped v1.0.0 | `backgroundJobModel` |
 | application-notifications-email (reserved) | to be claimed at ship | to be claimed at ship | name-only doc reservation (not shipped) | tba |
 | application-notifications-push (reserved) | to be claimed at ship | to be claimed at ship | name-only doc reservation (not shipped) | tba |
 | application-notifications-webhook (reserved) | to be claimed at ship | to be claimed at ship | name-only doc reservation (not shipped) | tba |

package/blueprints/application-onboarding-tour/CHANGELOG.md

@@ -0,0 +1,12 @@
+# application-onboarding-tour CHANGELOG
+
+## 1.0.0 (visual round T-5, spec 2026-09-06 section 5.5)
+
+- First shipped version. Introduces the tour step runner (ARIA APG dialog-modal per step, focus lifecycle, `role="dialog"`, `aria-labelledby`, `aria-describedby`, keyboard trap inside the tooltip with Escape as the exit, focus-not-obscured at 1440 and 360 breakpoints via `browser.resize`), the checklist slot (dashboard-top open collapse on `application-dashboard` applied; settings-page closed collapse when not; `<details>` browser-native for keyboard-native keyboard behaviour and screen-reader-native semantics), and the completion-state store contract (three backend shapes selected at apply time from the elicited answer or the Q4 fallback `spa-local-storage` when no persistence blueprint is applied).
+- Ships six elicits: `tour-step-manifest`, `anchor-selectors`, `per-step-content-voice` (all project-owned strings the blueprint contributes the WHAT for), `dismissal-policy` (default `dismiss-permanently`), `completion-state-store` (default `spa-local-storage` per Q4), `checklist-anchor` (default derived at apply time from the applied-blueprint set).
+- Ships a Playwright probe pack under `probe-packs/application-onboarding-tour.pack.mjs` with four surface-observable checks anchored to `AC-26101-1` (step-container focus and Escape), `AC-26102-1` (tooltip-as-dialog contract at two breakpoints), `AC-26103-1` (checklist-slot on both dashboard-top and settings-page anchors), and `AC-26104-1` (completion-state persistence and restart-tour re-open).
+- Ships a dependency-free sample-app fixture at `packages/rcf-lite/test/fixtures/probe-pack-application-onboarding-tour/` realising the tour surface honestly across both checklist branches and multiple completion-store shapes, plus four break switches (`?break=no-role`, `?break=focus-escape`, `?break=no-collapse`, `?break=no-persist`) driving the negative runs.
+- Composes on `application-spa` (routing and iconography), `application-dashboard` (dashboard-top anchor slot; settings-page fallback), `application-notifications-in-app` (polite `aria-live` completion announce), `application-account-settings` (restart-tour control home; any settings-shaped surface as fallback), and any `security-auth-*` blueprint (per-principal completion state; per-browser under a bare namespace as fallback).
+- Q4 default: when no persistence blueprint is applied AND the operator does not answer `completion-state-store`, the store defaults to `spa-local-storage`. Rationale in ADR-2702 and the README's Q4 fallback section.
+- Two documented mechanism-reach gaps: `AC-26105-1` first-run detection is fixture-verified via the manual boot line; `AC-26107-1` screen-reader traversal is asserted at the DOM contract level and verified manually via the fixture READMEs VoiceOver smoke. Runner cleanup rides `w-2026-09-04-dave-020`.
+- No new global topics claimed. Extends the section 5 shelf id band registry with `application-onboarding-tour` at 26101 to 26899 (US) and 27xx (ADR/TAC).

package/blueprints/application-onboarding-tour/README.md

@@ -0,0 +1,77 @@
+# Onboarding-tour blueprint (v1.0.0)
+
+Vendor-neutral onboarding-tour surface for an rcf-lite application. Composes on the SPA, dashboard, notifications-in-app, account-settings and any auth blueprint the project has applied, without a hard dependency on any of them: where a compose target is present the tour uses it, where it is not the tour uses the documented fallback per Q4. Ships a tour step runner mounted as an ARIA APG dialog-modal per step, a first-run checklist that renders on the dashboard shell when `application-dashboard` is applied and collapses to the settings page when not, a completion-state store with three backend shapes, and a restart-tour affordance on the settings surface. Ships a Playwright probe pack under `probe-packs/application-onboarding-tour.pack.mjs` whose four checks drive the real browser against a dependency-free sample-app fixture.
+
+## Apply
+
+```
+rcf define blueprint add <path-to>/blueprints/application-onboarding-tour
+```
+
+No `requiresAppliedCapabilities`: T-5 has no hard dependency, and the compose targets (SPA, dashboard, notifications-in-app, account-settings, any auth) are all optional. Prompts the elicitation phase for six parameters: the step manifest (3 to 5 steps with per-step anchor and content), the anchor selectors, the per-step content voice, the dismissal policy (default `dismiss-permanently`), the completion-state store shape (default `spa-local-storage`, the Q4 fallback), and the checklist anchor slot (default derived at apply time from what is applied). Writes a sidecar `rcf/blueprints/application-onboarding-tour.applied.json` capturing the answered elicits and the discovered `appliedBlueprints[]` (dashboard, notifications-in-app, account-settings, spa presence). Consumes the `logging` and `errorHandling` companions when they resolve to an applied provider or a registered library.
+
+## Anatomy
+
+| Piece | Where | What |
+|---|---|---|
+| Metadata | `blueprint.json` | Slug, version 1.0.0, category `application`, no `requiresAppliedCapabilities`, six elicits, `suggestedCompanions: [logging, errorHandling]`, 17 contributions in the 26xxx / 27xx bands |
+| Doc set | `contributions/` | 4 REQs, 7 USs (7 runtime-observable ACs; two documented mechanism-reach gaps on AC-26105-1 and AC-26107-1), 3 TACs, 3 ADRs |
+| Probe pack | `probe-packs/application-onboarding-tour.pack.mjs` | Four surface-observable browser-verify checks anchored to AC-26101-1 step-container focus, AC-26102-1 tooltip-as-dialog, AC-26103-1 checklist-slot, AC-26104-1 completion-state persistence |
+| Guide | `guide/application-onboarding-tour.md` | Operator-facing: when to reach, when not, mechanism-reach gaps, ARIA APG dialog-modal pattern and WCAG SCs the tour honours |
+| Coordination vocabulary | `docs/topics.md` | Shelf id band registry update; no new global topics claimed; cross-references to `application-dashboard`, `application-notifications-in-app`, `application-account-settings`, `application-spa` |
+| Sample-app fixture | `packages/rcf-lite/test/fixtures/probe-pack-application-onboarding-tour/` | Dependency-free Node HTTP server the pack is probed against on the shelf gate |
+
+## Composition: what the tour reaches when
+
+| Applied blueprint | Effect on the tour |
+|---|---|
+| `application-spa` applied | Routing (`/tour`, `/dashboard`, `/settings`), iconography, theming carry through. Absent: the tour still renders but the project supplies the routing shell. |
+| `application-dashboard` applied | Checklist anchor defaults to `dashboard-top` inside a `<details open>` element on the dashboard shell. Absent: checklist anchor defaults to `settings-page` inside a `<details>` (closed) element on the settings surface, per ADR-2703 and AC-26103-1. |
+| `application-notifications-in-app` applied | Tour completion emits a polite `aria-live` announcement through the notifications-in-app live region. Absent: the completion is silent at the announce layer (the step runner still logs one line if a `logging` companion resolves). |
+| `application-account-settings` applied | Restart-tour control lives inside the account settings surface. Absent: the restart-tour control renders on any settings-shaped surface the project supplies (`/settings`, `/account`, `/account/settings`). |
+| Any `security-auth-*` applied | Completion state persists per principal identifier (the sidecar carries the principal namespace at apply). Absent: completion state persists per browser under a bare namespace; the tour behaves as a single-principal experience. |
+
+## Q4 fallback: completion-state store shape
+
+Q4 of the ratified spec (section 10) settles the completion-state fallback. When no persistence blueprint is applied AND the operator does not answer `completion-state-store` explicitly, the store defaults to `spa-local-storage`: a per-browser record so a returning principal on the same browser is not re-onboarded, and a different browser is re-onboarded. Rationale: a per-session tour that re-plays on every new session is worse than a one-time tour that persists across sessions on that browser; per the elicit surface, the operator can override to `spa-session-storage` (per-session refresh) or `server-side-per-principal` (cross-device; requires an applied persistence blueprint).
+
+## Standards trace
+
+- ARIA APG dialog-modal pattern: `role="dialog"`, `aria-labelledby` on the step heading, `aria-describedby` on the step body, focus moves to the tooltip on open, focus returns to the anchor on close. `AC-26102-1`, `AC-26107-1`.
+- WCAG 2.2 AA 2.1.1 Keyboard: every tour control activatable with the keyboard. `AC-26101-1`.
+- WCAG 2.2 AA 2.1.2 No Keyboard Trap: Escape always exits, focus never permanently trapped. `AC-26101-1`.
+- WCAG 2.2 AA 2.4.3 Focus Order: Tab reaches every tour control in DOM order inside the tooltip. `AC-26101-1`.
+- WCAG 2.2 AA 2.4.11 Focus Not Obscured Minimum: tooltip visible at the 1440 wide and 360 narrow breakpoints (probed via `browser.resize`). `AC-26102-1`.
+
+Spec `standardsTrace` empty at the blueprint level; each ADR contribution carries a non-null `standardsTraceClause` per authoring section 8a.4 (the sentinel `generic enterprise practice` used where no SC applies).
+
+## Known mechanism-reach gaps
+
+- `AC-26105-1` (first-run detection): the runner cannot fully prove the first-run vs returning-principal branch in one browser session without a persisted state seed; the pack drives the first-run branch via `?first-run=1` and the returning branch is verified by the fixture READMEs manual boot line (walk `/tour` twice, confirm the tour auto-opens on run 1 and does not on run 2).
+- `AC-26107-1` (screen-reader traversal): the pack asserts the DOM contract (`aria-labelledby`, `aria-describedby`) but does not drive a real screen reader in CI. The fixture README names the manual VoiceOver smoke. Runner cleanup rides `w-2026-09-04-dave-020`.
+- `AC-26106-1` (restart-tour clears state and re-opens): fully exercised inside the AC-26104-1 pack check end-to-end (the check clicks restart, then navigates to `/tour` and asserts the tooltip re-appears).
+
+## Elicited parameters
+
+- `tour-step-manifest` (string; project-owned): the ordered list of 3 to 5 steps with per-step anchor, heading and body slot.
+- `anchor-selectors` (string; project-owned): the CSS selectors the runner resolves at step-open time.
+- `per-step-content-voice` (string; project-owned): the copy for each step.
+- `dismissal-policy` (enum: `dismiss-permanently` | `dismiss-until-next-major` | `dismiss-until-next-minor`; default `dismiss-permanently`).
+- `completion-state-store` (enum: `spa-local-storage` | `spa-session-storage` | `server-side-per-principal`; default `spa-local-storage` per Q4).
+- `checklist-anchor` (enum: `dashboard-top` | `settings-page` | `custom-anchor`; default derived at apply time from what is applied).
+
+## Suggested companions
+
+- `logging`: every step transition and tour completion writes one request-scoped log line with the correlation identifier.
+- `errorHandling`: a completion-state persistence failure constructs an internal error record.
+
+## Probe pack
+
+`probe-packs/application-onboarding-tour.pack.mjs` ships four surface-observable checks anchored to blueprint AC ids:
+
+- `AC-26101-1` step-container focus lifecycle and Escape.
+- `AC-26102-1` tooltip-as-dialog contract at 1440 and 360 breakpoints (via `browser.resize`).
+- `AC-26103-1` checklist slot on both dashboard-top (open) and settings-page (closed) branches.
+- `AC-26104-1` completion-state persistence and restart-tour re-open.
+
+The pack applies to any FBS binding `TAC-2701-application-onboarding-tour-step-runner` or whose `navModel` routes match the operator-configured tour-anchor path glob (`/tour`, `/welcome`, `/getting-started`, `/onboarding`). Every URL string is composed through the `withUrl(runtimeUrl, path)` helper (no bare string concatenation).

package/blueprints/application-onboarding-tour/blueprint.json

@@ -0,0 +1,164 @@
+{
+  "slug": "application-onboarding-tour",
+  "version": "1.0.0",
+  "category": "application",
+  "elicits": [
+    {
+      "id": "tour-step-manifest",
+      "prompt": "Tour step manifest: an ordered list of 3 to 5 steps, each with an anchor selector (CSS) and a content voice slot the project fills. Names each step id, anchor, heading and body.",
+      "kind": "string",
+      "default": ""
+    },
+    {
+      "id": "anchor-selectors",
+      "prompt": "Anchor selectors: CSS selectors the runtime resolves at step-open time to place the tooltip. One per manifest step.",
+      "kind": "string",
+      "default": ""
+    },
+    {
+      "id": "per-step-content-voice",
+      "prompt": "Per-step content voice: the project-owned copy for each step (heading and body). The blueprint contributes the WHAT, not the words.",
+      "kind": "string",
+      "default": ""
+    },
+    {
+      "id": "dismissal-policy",
+      "prompt": "Dismissal policy: dismiss-permanently (the tour never re-opens for a returning principal), dismiss-until-next-major (re-opens on a major version bump of the applied blueprint set), or dismiss-until-next-minor (re-opens on a minor bump). Recommended default: dismiss-permanently.",
+      "kind": "enum",
+      "options": [
+        "dismiss-permanently",
+        "dismiss-until-next-major",
+        "dismiss-until-next-minor"
+      ],
+      "default": "dismiss-permanently"
+    },
+    {
+      "id": "completion-state-store",
+      "prompt": "Completion-state store shape: spa-local-storage (per-browser, the Q4 fallback when no persistence blueprint is applied), spa-session-storage (per-session, re-plays on every new session), or server-side-per-principal (follows the principal across devices; requires an applied persistence blueprint). Recommended default: spa-local-storage.",
+      "kind": "enum",
+      "options": [
+        "spa-local-storage",
+        "spa-session-storage",
+        "server-side-per-principal"
+      ],
+      "default": "spa-local-storage"
+    },
+    {
+      "id": "checklist-anchor",
+      "prompt": "Checklist anchor slot: dashboard-top (renders on the dashboard shell when application-dashboard is applied), settings-page (renders on the settings surface when application-account-settings is applied or on any settings surface as a fallback), or custom-anchor (the project supplies a CSS selector). Default derived at apply time from what is applied.",
+      "kind": "enum",
+      "options": [
+        "dashboard-top",
+        "settings-page",
+        "custom-anchor"
+      ],
+      "default": "dashboard-top"
+    }
+  ],
+  "suggestedCompanions": [
+    {
+      "role": "logging",
+      "reason": "Every step transition and tour completion writes one request-scoped log line with the correlation identifier; a logging companion supplies the factory."
+    },
+    {
+      "role": "errorHandling",
+      "reason": "A completion-state persistence failure constructs an internal error record; an error-handling companion supplies the record factory and the boundary."
+    }
+  ],
+  "contributions": [
+    {
+      "id": "application-onboarding-tour-REQ-001",
+      "kind": "req",
+      "path": "requirements/application-onboarding-tour-req-001.json"
+    },
+    {
+      "id": "application-onboarding-tour-REQ-002",
+      "kind": "req",
+      "path": "requirements/application-onboarding-tour-req-002.json"
+    },
+    {
+      "id": "application-onboarding-tour-REQ-003",
+      "kind": "req",
+      "path": "requirements/application-onboarding-tour-req-003.json"
+    },
+    {
+      "id": "application-onboarding-tour-REQ-004",
+      "kind": "req",
+      "path": "requirements/application-onboarding-tour-req-004.json"
+    },
+    {
+      "id": "application-onboarding-tour-US-26101",
+      "kind": "us",
+      "path": "user-stories/application-onboarding-tour-us-26101.json"
+    },
+    {
+      "id": "application-onboarding-tour-US-26102",
+      "kind": "us",
+      "path": "user-stories/application-onboarding-tour-us-26102.json"
+    },
+    {
+      "id": "application-onboarding-tour-US-26103",
+      "kind": "us",
+      "path": "user-stories/application-onboarding-tour-us-26103.json"
+    },
+    {
+      "id": "application-onboarding-tour-US-26104",
+      "kind": "us",
+      "path": "user-stories/application-onboarding-tour-us-26104.json"
+    },
+    {
+      "id": "application-onboarding-tour-US-26105",
+      "kind": "us",
+      "path": "user-stories/application-onboarding-tour-us-26105.json"
+    },
+    {
+      "id": "application-onboarding-tour-US-26106",
+      "kind": "us",
+      "path": "user-stories/application-onboarding-tour-us-26106.json"
+    },
+    {
+      "id": "application-onboarding-tour-US-26107",
+      "kind": "us",
+      "path": "user-stories/application-onboarding-tour-us-26107.json"
+    },
+    {
+      "id": "TAC-2701-application-onboarding-tour-step-runner",
+      "kind": "tac",
+      "path": "tacs/tac-2701-application-onboarding-tour-step-runner.json"
+    },
+    {
+      "id": "TAC-2702-application-onboarding-tour-checklist-slot",
+      "kind": "tac",
+      "path": "tacs/tac-2702-application-onboarding-tour-checklist-slot.json"
+    },
+    {
+      "id": "TAC-2703-application-onboarding-tour-completion-store",
+      "kind": "tac",
+      "path": "tacs/tac-2703-application-onboarding-tour-completion-store.json"
+    },
+    {
+      "id": "ADR-2701-application-onboarding-tour-dismissal-policy",
+      "kind": "adr",
+      "path": "adrs/adr-2701-application-onboarding-tour-dismissal-policy.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "generic enterprise practice"
+    },
+    {
+      "id": "ADR-2702-application-onboarding-tour-completion-store-shape",
+      "kind": "adr",
+      "path": "adrs/adr-2702-application-onboarding-tour-completion-store-shape.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "generic enterprise practice"
+    },
+    {
+      "id": "ADR-2703-application-onboarding-tour-checklist-anchor",
+      "kind": "adr",
+      "path": "adrs/adr-2703-application-onboarding-tour-checklist-anchor.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "generic enterprise practice"
+    }
+  ]
+}

package/blueprints/application-onboarding-tour/contributions/adrs/adr-2701-application-onboarding-tour-dismissal-policy.json

@@ -0,0 +1,20 @@
+{
+  "adrId": "ADR-2701-application-onboarding-tour-dismissal-policy",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Dismissal policy: dismiss-permanently default, dismiss-until-next-major or dismiss-until-next-minor",
+  "context": "A dismissed tour has three legal re-open behaviours. Dismiss-permanently is the least intrusive: a principal who dismissed the tour once never sees it again unless the restart-tour control fires. Dismiss-until-next-major re-opens the tour when the applied blueprint set makes a major-version bump (a new tour surface a returning principal has not seen). Dismiss-until-next-minor re-opens on a minor bump for the same reason at higher frequency. The spec section 5.5 names all three; the recommended default is dismiss-permanently because a returning principal who dismissed the tour deliberately signalled that they do not want re-onboarding, and the restart-tour control on the settings surface remains available.",
+  "decision": "dismissal-policy is elicited (enum: dismiss-permanently | dismiss-until-next-major | dismiss-until-next-minor). Recommended default: dismiss-permanently. The step runner honours the answer by comparing the CompletionRecord.blueprintSetVersion against the current applied blueprint set version at principal load: dismiss-permanently never re-opens; dismiss-until-next-major re-opens when the major differs; dismiss-until-next-minor re-opens when the major or the minor differs. A blueprintSetVersion mismatch always renders the checklist on the resolved anchor even when the tour does not auto-open.",
+  "consequences": "A returning principal in the dismiss-permanently branch is not re-onboarded on any bump; a project that adds a major surface (a new admin console, a new billing area) can prompt returning principals through a restart-tour affordance on the release note surface rather than an intrusive re-open. A project that opts into dismiss-until-next-major or dismiss-until-next-minor accepts the interruption for the benefit of re-onboarding on shipped changes; the CompletionRecord.stepIds field lets the step runner skip already-seen steps when a re-open fires.",
+  "alternativesConsidered": [
+    {
+      "name": "Alternative approach considered",
+      "summary": "A time-based re-open (re-open after 30 days) was considered but time-based re-opens do not correlate with actual product changes; a returning principal on a stable product would be re-onboarded on nothing. Version-based re-opens correlate with real surface changes and let the operator choose the frequency.",
+      "reasonNotChosen": "See the decision text; the chosen shape composes cleanly with the applied blueprint set the spec section 5.5 names."
+    }
+  ],
+  "createdAt": "2026-09-06T23:15:00Z",
+  "updatedAt": "2026-09-06T23:15:00Z"
+}

package/blueprints/application-onboarding-tour/contributions/adrs/adr-2702-application-onboarding-tour-completion-store-shape.json

@@ -0,0 +1,20 @@
+{
+  "adrId": "ADR-2702-application-onboarding-tour-completion-store-shape",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Completion-state store shape: spa-local-storage default (Q4 fallback), spa-session-storage or server-side-per-principal",
+  "context": "The completion state needs a store. Three shapes are legal. spa-local-storage keeps the completion state per browser and per principal identifier; a returning principal on the same browser is not re-onboarded, and a different browser (or a private window) is re-onboarded. spa-session-storage keeps the completion state per session and re-plays the tour on every new session; useful only for a project that deliberately wants a per-session refresher. server-side-per-principal keeps the completion state on the principals record so it follows the user across devices; requires an applied persistence blueprint and the projects own writer adapter. The spec section 5.5 and section 10 Q4 ratify spa-local-storage as the fallback when no persistence blueprint is applied because a per-session tour that re-plays on every new session is worse than a one-time tour that persists across sessions on that browser.",
+  "decision": "completion-state-store is elicited (enum: spa-local-storage | spa-session-storage | server-side-per-principal). Recommended default: spa-local-storage. At apply time the elicit surface offers all three; a project that answers server-side-per-principal without an applied persistence blueprint hits a documented refusal (the elicit's when predicate refuses per the mechanism minor T-5 does not extend; the refusal is enforced at the surface load by TAC-2703 which refuses to construct a server-side backend without a resolved persistence adapter and falls back to spa-local-storage with a documented note on the sidecar).",
+  "consequences": "A project with no persistence blueprint applied gets the spa-local-storage backend automatically per the Q4 fallback; a project with a persistence blueprint and the server-side-per-principal answer gets a cross-device tour completion; a project answering spa-session-storage accepts a per-session re-onboarding. The dismiss-until-next-major and dismiss-until-next-minor policies (ADR-2701) still work under any of the three shapes because the CompletionRecord.blueprintSetVersion travels with the record.",
+  "alternativesConsidered": [
+    {
+      "name": "Alternative approach considered",
+      "summary": "spa-session-storage as the default was considered but re-onboarding on every new session is intrusive on a stable product; the Q4 ratification names spa-local-storage as the fallback for that reason.",
+      "reasonNotChosen": "See the decision text; the chosen default composes cleanly with the applied blueprint set the spec section 5.5 names."
+    }
+  ],
+  "createdAt": "2026-09-06T23:15:00Z",
+  "updatedAt": "2026-09-06T23:15:00Z"
+}

package/blueprints/application-onboarding-tour/contributions/adrs/adr-2703-application-onboarding-tour-checklist-anchor.json

@@ -0,0 +1,20 @@
+{
+  "adrId": "ADR-2703-application-onboarding-tour-checklist-anchor",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Checklist anchor slot: dashboard-top when application-dashboard is applied, settings-page when not, custom-anchor as escape hatch",
+  "context": "The checklist has three legal homes. dashboard-top when application-dashboard is applied because the dashboard shell is the highest-value surface a returning principal reaches. settings-page when application-dashboard is not applied because the settings surface is the next-highest-value reference surface. custom-anchor when the project prefers a bespoke slot (a marketing surface, a landing shell, a home route). The spec section 5.5 ratifies all three and marks the anchor as elicited with a default derived at apply time from what is applied.",
+  "decision": "checklist-anchor is elicited (enum: dashboard-top | settings-page | custom-anchor). Recommended default: derived at apply time (dashboard-top when application-dashboard is in the applied set; settings-page when it is not; custom-anchor requires the projects own CSS selector). The collapse contract is a <details open> element on dashboard-top and a <details> (closed) element on settings-page; custom-anchor takes the setting-page default (closed) unless the project supplies an override.",
+  "consequences": "A project applying application-dashboard renders the checklist open on the dashboard shell so a new principal sees the outstanding items at a glance; a project not applying application-dashboard renders it closed on the settings surface so it does not intrude; a project with a custom-anchor takes responsibility for the placement. AC-26103-1 probes the collapse contract on the two shipped anchors; custom-anchor is verified by the fixture READMEs manual boot line.",
+  "alternativesConsidered": [
+    {
+      "name": "Alternative approach considered",
+      "summary": "Auto-selecting always to the dashboard-top slot regardless of the applied set was considered but a project without application-dashboard applied has no dashboard shell to mount into; the checklist would be lost. Deriving the default from the applied set at apply time keeps the anchor honest.",
+      "reasonNotChosen": "See the decision text; the chosen shape composes cleanly with the applied blueprint set the spec section 5.5 names."
+    }
+  ],
+  "createdAt": "2026-09-06T23:15:00Z",
+  "updatedAt": "2026-09-06T23:15:00Z"
+}

package/blueprints/application-onboarding-tour/contributions/requirements/application-onboarding-tour-req-001.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-onboarding-tour-REQ-001",
+  "prdId": "PRD-001",
+  "title": "Step-manifest contract: 3 to 5 steps per tour with per-step anchor selector and per-step content voice slot",
+  "description": "The blueprint contributes a step-manifest contract for a 3 to 5 step onboarding tour. Each step declares a step id, an anchor selector (CSS resolved at step-open time to place the tooltip against a live element in the DOM), a heading and a body slot the project fills with its own voice. The step runner walks the manifest in order and refuses to open a step whose anchor does not resolve to a visible element rather than rendering a floating tooltip. The blueprint contributes the WHAT (the manifest shape and the resolver contract), not the words.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Per visual round 4 spec (2026-09-06) section 5.5, REQ 1 of the onboarding-tour blueprint.",
+  "tags": [
+    "blueprint:application-onboarding-tour",
+    "category:01-step-runner"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T23:15:00Z",
+  "updatedAt": "2026-09-06T23:15:00Z"
+}

package/blueprints/application-onboarding-tour/contributions/requirements/application-onboarding-tour-req-002.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-onboarding-tour-REQ-002",
+  "prdId": "PRD-001",
+  "title": "Tooltip-as-dialog contract per the ARIA APG dialog-modal pattern",
+  "description": "Each step's tooltip carries role=\"dialog\", aria-labelledby to the step heading, aria-describedby to the step body. Focus moves to the tooltip on open, focus returns to the anchor on close. The dialog traps focus between the tour controls (previous, next, dismiss) and refuses to let Tab escape to the underlying surface (WCAG 2.1.2 No Keyboard Trap satisfied because Escape always exits). Escape dismisses the tour. Focus is not obscured on any breakpoint (WCAG 2.4.11 Focus Not Obscured Minimum). Follows the ARIA APG dialog-modal pattern for the tooltip surface.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Per visual round 4 spec (2026-09-06) section 5.5, REQ 2 of the onboarding-tour blueprint.",
+  "tags": [
+    "blueprint:application-onboarding-tour",
+    "category:02-dialog-modal"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T23:15:00Z",
+  "updatedAt": "2026-09-06T23:15:00Z"
+}