rcf-lite 0.21.0 → 0.23.0

package/CHANGELOG.md

@@ -6,6 +6,42 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.23.0] - 2026-09-07
+
+rcf-lite 0.23.0 adds the infrastructure spine four blueprints wide: a Postgres store with a facade contract and forward-only migrations, an S3-shape object store with a Cloudflare R2 first adapter, a Cloudflare Queues producer and consumer with dead-letter semantics, and a background-jobs discipline that refuses to apply until a queue is applied. Each blueprint verifies against the real engine with node-only probes, and the four surfaces compose through the capability mechanism the round-3 admin console shipped.
+
+### Added
+
+- **Round 5 T-1: `persistence-data-postgres` v1.0.0 on the shelf (PR #155).** Postgres facade as the sole reader of the `pg` client, numbered forward-only migrations with per-file transactions, prepared-statement discipline enforced by a source-tree AST scan, a transactional-atomicity helper, scheduled `pg_dump` recovery plus vendor point-in-time recovery, and a connection-pool posture per deploy target. Declares `capabilities: ["relationalStore"]`. Conflicts by design with `persistence-data-sqlite` and `persistence-data-d1` on `persistenceStore` and `migrationDiscipline`. Reserves the round-6 Hyperdrive adapter slot at the driver ADR boundary. Six probes drive `postgres:17-alpine` in the shared `packages/rcf-lite/test/fixtures/infra-postgres/` fixture; probe reports land under `.rcf/reports/blueprints/persistence-data-postgres/` and set the round-5 ship-time evidence precedent.
+- **Round 5 T-2: `object-storage-s3` v1.0.0 on the shelf, with `security-secrets-management` 1.0.1 folded into the same PR (PR #157).** S3-API facade, Cloudflare R2 as the first adapter, MinIO as the local dev target, put, get, delete, list, a presigned-URL contract with a bounded TTL, multipart upload above an elicited threshold, and metadata-only lifecycle events. Refuses composition without `security-secrets-management` applied; the override `--allow-no-secrets-yet` records a note on `source.notes`. In the same PR, `security-secrets-management` bumps to 1.0.1 declaring `capabilities: ["secretsProvider"]` so the bare-project refusal fires end to end. Declares `capabilities: ["objectStorage"]`. Mints the new global topic `objectStorageContract`. Five probes run against MinIO plus one accountBound-skipped R2 smoke.
+- **Round 5 T-3: `messaging-queue-cloudflare` v1.0.0 on the shelf (PR #159).** Producer facade, consumer registration on the Worker's `queue` handler, publish, consume, ack, retry with the attempt counter, dead-letter contract per Cloudflare Queues docs (default retries 3, DLQ 4-day retention), batch consume, and metadata-only lifecycle events. One blueprint, contract plus first adapter. Declares `capabilities: ["queue"]`. Mints the new global topic `deliverySemantics`. Reserved slug `messaging-queue-postgres` sibling documented, deferred pending demand. Five probes drive `wrangler dev` locally plus one accountBound-skipped concurrency smoke that runs against a real account when `CI_HAS_CLOUDFLARE_ACCOUNT` is set.
+- **Round 5 T-4: `jobs-background` v1.0.0 on the shelf (PR #163).** Job-definition contract (name, handler, input schema, retry policy, timeout), scheduler contract (cron and one-shot delayed), retry contract on top of the applied queue, and a metadata-only job-run event log. Refuses to apply on a bare project with exit 3 and the stable message id `jobs-background-no-queue`; the `--allow-no-queue-yet` override records a note on `source.notes`. Declares `capabilities: ["backgroundJobs"]`. Mints the new global topic `backgroundJobModel`. Reserves the round-6 Workflows scheduler-mode slot at the ADR boundary. Five probes: apply-time refusal, apply-time override, fake-clock cron, retry-and-fail, event-secrecy.
+- **Authoring standard capability table extended.** `packages/rcf-lite/docs/blueprint-authoring.md` section 6a gains four new rows: `relationalStore`, `objectStorage`, `queue`, `backgroundJobs`. Chunk-zero-style append, loader unchanged.
+
+#### Also in this release
+
+- **Round 6 T-0: `deploy-cloudflare-workers` v1.1.0 to v1.2.0 (PR #164).** Additive minor bump that blesses the Workers-with-static-assets shape as the SPA-on-Workers deploy shape. Adds two new elicits (`assets-directory`, `run-worker-first`), ADR-1306 carrying the verbatim Cloudflare Pages landing-page recommendation, the `cf-platform` shared sample-app fixture under `packages/rcf-lite/test/fixtures/cf-platform/`, and the `assets-manifest-scan` probe that parses the applied fixture wrangler.toml and asserts the `[assets]` block presence, `run_worker_first` presence and absence of the Pages-only `pages_build_output_dir` field. No capability minted, no new global topic, no runtime dependency added; the shipped v1.1.0 contribution set carries through unchanged.
+
+### Fixed
+
+- **CLI stdout truncation on large outputs (PR #159).** `bin/rcf.js` now flushes stdout before `process.exit` at both exit sites. Previously, stdout was truncated at the 65536-byte pipe buffer on outputs past that size; first hit by `rcf audit coverage --format mermaid` on the umbrella tree.
+
+## [0.22.0] - 2026-09-07
+
+rcf-lite 0.22.0 fills the visual shelf with five application blueprints (empty and error states, file upload with a WCAG keyboard gate, a multi-step forms wizard, a self-service account settings area, and a first-run onboarding tour). Account settings reuses the admin-console capability-gating mechanism, so the five settings surfaces only render when the applied auth blueprint declares the capability. The four shipped auth blueprints and the logging blueprint pick up additive capability declarations in the same release.
+
+Also present on the shelf at this version, ahead of their own 0.23.0 release notes: `persistence-data-postgres` 1.0.0, `object-storage-s3` 1.0.0, and the `security-secrets-management` 1.0.1 minor.
+
+### Added
+
+- **Visual round 4 T-1: `application-empty-error-states` v1.0.0 on the shelf (PR #154).** Ships the eight-state contract (not-found, forbidden, server-error, offline, permission-denied, empty-list, no-search-results, error-boundary), one Playwright probe pack with eight surface-observable checks, three TACs, three ADRs, an RFC 9110 status contract, WCAG 2.2 AA compliance, and the offline write-buffer contract for reconnection.
+- **Visual round 4 T-2: `application-file-upload` v1.0.0 on the shelf (PR #156).** Ships the WCAG 2.5.7 keyboard-alternative gate, a chunked and resumable transport contract, MIME-type, size and virus-scan refusal, tus.io as the elicited alternative transport, four pack checks, and four break switches. Informational: shortened ADR id suffixes on file-upload; elicits declared via ADR entry flags on non-capability blueprints; tus fail-message ordering.
+- **Visual round 4 T-3: `application-forms-wizard` v1.0.0 on the shelf (PR #158).** Ships the GOV.UK task-list and summary-list patterns, per-step validation timing, an error-summary with skip-links, and a save-and-return contract that refuses to ship a default because the draft-store transport is elicited.
+- **Visual round 4 T-4: `application-account-settings` v1.0.0 on the shelf (PR #160).** Ships the five conditional surfaces (profile, security, sessions, notification preferences, theme), reusing the admin-console capability-gating mechanism, a bare-SPA refusal with the `--allow-no-auth-yet` override, a hosted-UI bridge, and five pack checks. Informational: the theme check reads the attribute only.
+- **Visual round 4 T-4 auth minors, in the same PR (PR #160).** `security-auth-clerk` 1.3.0, `security-auth-keycloak` 1.2.0, `security-auth-oauth2` 1.2.0, `security-auth-magic-link` 1.2.0 and `observability-logging` 1.2.0. Additive `capabilities[]` declarations for `credentialSelfService`, `sessionInventory` and `hostedIdentityUi` per vendor and provider; the settings blueprint discovers the applied capability set at apply time and only offers the surfaces the applied auth supports.
+- **Visual round 4 T-5: `application-onboarding-tour` v1.0.0 on the shelf (PR #161).** Ships an ARIA APG dialog-modal tooltip-as-dialog, keyboard-only Escape and focus-return contract, a checklist-on-dashboard collapse-to-settings fallback, completion-state persistence with per-principal or local-storage layers, and four pack checks.
+
+
 ## [0.21.0] - 2026-09-05
 
 rcf-lite 0.21.0 adds five visual-feature blueprints to the shelf (data table, charts, dashboard with packaged design guidance, in-app notifications, admin console) and the mechanism that proves them: a blueprint can now ship a Playwright probe pack that rcf verify runs against your running app in a real browser, and the ship gate refuses while a surface check fails. The admin console only offers the surfaces your applied auth blueprint can support. Blueprints can now ask you questions at apply time. The schema floor moves to rcf-schemas 0.6.1.

package/bin/rcf.js

@@ -267,9 +267,20 @@ export function isSameEntryPoint(metaUrl, argvPath) {
 const isMain = process.argv[1] && isSameEntryPoint(import.meta.url, process.argv[1]);
 if (isMain) {
   main(process.argv.slice(2))
-    .then((code) => process.exit(code))
+    .then((code) => {
+      // Await stdout drain before exit so large payloads (mermaid or
+      // JSON output above ~64KiB) are not truncated when a parent
+      // captures stdout via child_process execFile / spawn. process.exit
+      // otherwise races the OS pipe flush and drops the tail; the
+      // golden fixture tests hit this once the dogfood tree crosses
+      // the pipe buffer size. write('', cb) fires the callback once
+      // pending buffer flushes, then process.exit(code) tears down
+      // immediately - keeping the long-running mcp stdio subcommand
+      // path unchanged (mcp resolves once its own done promise fires).
+      process.stdout.write('', () => process.exit(code));
+    })
     .catch((err) => {
       process.stderr.write(`[rcf] unexpected failure: ${err.message}\n${err.stack}\n`);
-      process.exit(1);
+      process.stdout.write('', () => process.exit(1));
     });
 }

package/blueprints/application-account-settings/CHANGELOG.md

@@ -0,0 +1,12 @@
+# application-account-settings CHANGELOG
+
+## 1.0.0 (visual round T-4, spec 2026-09-06 section 5.4)
+
+- First shipped version. Introduces the account-settings shell (ARIA APG tabs, WCAG 2.4.6 landmark), the profile surface (WCAG 1.3.5 autocomplete tokens, aria-live save-status), the security surface (self-service branch and hosted-UI branch through ADR-2602's elicited security-surface-shape), the sessions surface (ARIA APG dialog-modal terminate flow, aria-live session-terminated announcement, current-session cannot terminate itself), the notification-preferences surface (per-category silence, per-channel opt-in) and the theme surface (light/dark/system radiogroup persisted per ADR-2603's elicited theme-persistence).
+- Declares `requiresAppliedCapabilities: [principalDirectory]` with `refusalMessageId: application-account-settings-bare-spa` and `allowSkipFlag: allow-no-auth-yet`. The refusal template ships in this PR's mechanism minor at `packages/rcf-lite/src/blueprint/capabilities.js` (`buildRefusalMessage`). The Q3 gate (a project declaring neither `credentialSelfService` nor `hostedIdentityUi`) is enforced through the shell's tab-suppression rule (AC-25101-1 probed by the pack), the mechanism's silent gating of the `security-surface-shape` elicit (its `when` predicate refuses), and the surface-side hosted-UI bridge TAC-2603 refusal (documented mechanism-reach gap under AC-25110-1).
+- Ships four capability-gated custom-auth elicits (`custom-auth-provides-principal-directory`, `custom-auth-provides-credential-self-service`, `custom-auth-provides-session-inventory`, `custom-auth-provides-hosted-identity-ui`) that let a project ship its own auth surface without a shelf `security-auth-*` blueprint.
+- Ships four regular elicits (`security-surface-shape`, `hosted-identity-url`, `theme-persistence`, `reauth-window`) whose `when` predicates gate on the applied capability set.
+- Ships a Playwright probe pack under `probe-packs/application-account-settings.pack.mjs` with five checks anchored to `AC-25101-1` (shell tabs mirror caps), `AC-25102-1` (profile autocomplete tokens), `AC-25105-1` (security branch matches applied + elicit), `AC-25106-1` (sessions rows and dialog-modal) and `AC-25108-1` (theme radiogroup and persistence). Every check gates via `readAppliedCapabilities(projectRoot)`; an absent capability records `verdict: skipped` per spec section 3.3.
+- Ships a dependency-free sample-app fixture at `packages/rcf-lite/test/fixtures/probe-pack-application-account-settings/` realising the five conditional surfaces honestly plus four break switches (`?break=leak-tab`, `?break=no-autocomplete`, `?break=no-dialog`, `?break=no-persist`) driving the negative runs.
+- Composes on `application-empty-error-states` (T-1) for the forbidden and empty-history states; no bespoke access-denied UI is invented here.
+- Rides with the auth blueprints minor bumps (`security-auth-clerk` 1.3.0, `security-auth-keycloak` 1.2.0, `security-auth-oauth2` 1.2.0, `security-auth-magic-link` 1.2.0 doc-only) and the `observability-logging` 1.2.0 minor bump (declares `sessionInventory` as the logging-projection provider), extending the section 6a capability table with `credentialSelfService`, `sessionInventory` and `hostedIdentityUi`.

package/blueprints/application-account-settings/README.md

@@ -0,0 +1,114 @@
+# Account settings blueprint (v1.0.0)
+
+Vendor-neutral account-settings surface for an rcf-lite application. Surfaces are CONDITIONAL on what the applied identity blueprints and companion blueprints declare via `capabilities[]`. Ships the settings shell with an ARIA APG tabs region (no dead links to unapplied capabilities), a WCAG 1.3.5 profile surface (always active), a security surface with a self-service branch (password change, MFA) and a hosted-UI branch (link-out or embed), a sessions surface with an ARIA APG dialog-modal terminate flow, a notification preferences surface and a theme surface with light/dark/system. Reuses the visual round T-5 capability grammar and the apply-time discovery, refusal and custom-auth elicitation the spec section 5.4 ratifies. Ships a Playwright probe pack under `probe-packs/application-account-settings.pack.mjs` whose five checks are capability-gated: an absent capability records `verdict: skipped` and the aggregate verdict treats it as neither pass nor fail (spec section 3.3).
+
+## Apply
+
+```
+rcf define blueprint add <path-to>/blueprints/application-account-settings
+```
+
+Refuses with exit 3 and the spec 5.4.1 verbatim message on a project with no applied blueprint declaring `principalDirectory` unless `--allow-no-auth-yet` is passed for a scaffolding pass. Prompts the elicitation phase for parameters whose `when` predicate resolves true against the discovered applied-capability set. Writes a sidecar `rcf/blueprints/application-account-settings.applied.json` capturing the discovered `appliedCapabilities`, the elicit answers, and (when overridden) the scaffolding note. Consumes the `logging` and `errorHandling` companions when they resolve to an applied provider or a registered library; falls back to the shelf providers otherwise.
+
+## Anatomy
+
+| Piece | Where | What |
+|---|---|---|
+| Metadata | `blueprint.json` | Slug, version 1.0.0, category `application`, `requiresAppliedCapabilities: [principalDirectory]`, `elicits[]` (four custom-auth capability provides plus security-surface-shape, hosted-identity-url, theme-persistence, reauth-window), `suggestedCompanions: [logging, errorHandling]`, 24 contributions in the 25xxx / 26xx bands |
+| Doc set | `contributions/` | 6 REQs, 10 USs (13 runtime-observable ACs), 4 TACs, 4 ADRs |
+| Probe pack | `probe-packs/application-account-settings.pack.mjs` | Five capability-gated browser-verify checks anchored to AC-25101-1, AC-25102-1, AC-25105-1, AC-25106-1, AC-25108-1 |
+| Guide | `guide/application-account-settings.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-references application-empty-error-states (T-1) and application-admin-console (T-5) |
+| Sample-app fixture | `packages/rcf-lite/test/fixtures/probe-pack-application-account-settings/` | Dependency-free Node HTTP server the pack is probed against on the shelf gate |
+
+## Conditionality: what surfaces render when
+
+| Applied capability | Surface | Rendered by |
+|---|---|---|
+| `principalDirectory` | Profile (`/account/profile`) always available | Any applied auth blueprint (magic-link, clerk, oauth2, keycloak). |
+| `credentialSelfService` OR `hostedIdentityUi` | Security (`/account/security`) | credentialSelfService: Keycloak from 1.2.0, OAuth2 from 1.2.0 (provider-conditional). hostedIdentityUi: Clerk from 1.3.0, OAuth2 from 1.2.0 (provider-conditional). Neither present: security tab suppressed AND the Q3 refusal fires at apply if the operator answers `--answer security-surface-shape=...`. |
+| `sessionInventory` | Sessions (`/account/sessions`) | Clerk from 1.3.0, Keycloak from 1.2.0, OAuth2 from 1.2.0, or observability-logging from 1.2.0 (as the logging-projection provider). Magic-link does NOT declare it. |
+| `application-notifications-in-app` applied | Notification preferences (`/account/notifications`) | Suppressed when the notifications-in-app blueprint is not applied. |
+| `application-spa` applied | Theme (`/account/theme`) | Suppressed when the SPA blueprint is not applied. |
+| (none) | Unauthenticated principal | Composes on `application-empty-error-states` (T-1) forbidden state; no bespoke access-denied UI. |
+
+## Bare-SPA refusal
+
+On a project with only `application-spa` applied (no auth), the apply exits 3 with:
+
+```
+application-account-settings requires at least one applied security-auth-* blueprint,
+or an operator override with --allow-no-auth-yet.
+
+Applied blueprints on this project:
+  application-spa v1.5.0
+
+Suggested next steps:
+  1. Apply an auth blueprint first:
+       rcf define blueprint add security-auth-magic-link
+     (or security-auth-clerk, security-auth-oauth2, security-auth-keycloak)
+  2. Override for a scaffolding pass (surfaces will refuse at apply until an
+     auth blueprint is applied):
+       rcf define blueprint add application-account-settings --allow-no-auth-yet
+```
+
+The override records a note on the sidecar's `notes` field so `rcf define validate` reads back and flags surfaces that never activated.
+
+## Q3 gate: security surface has no home
+
+A project that declares `principalDirectory` (so apply is not refused at the bare-SPA gate) but NEITHER `credentialSelfService` NOR `hostedIdentityUi`:
+
+1. Silently drops any `--answer security-surface-shape=<any>` at apply (the general elicits mechanism gates the answer via the `when` predicate; the sidecar records no `security-surface-shape` entry).
+2. Renders the shell WITHOUT a security tab (AC-25101-1, probed by the pack).
+3. Refuses the security surface at load time through TAC-2603 hosted-ui-bridge if a project-side FBS renders `/account/security` regardless (project-side enforcement per AC-25110-1 known mechanism-reach gap, spec section 5.4.1).
+
+No `auth managed elsewhere` placeholder ships from the shipped shell surface. Per Baz decision Q3 in the ratified spec, the shell never lies about a surface that has no home.
+
+## Custom-auth projects (auth outside the shelf)
+
+A project that ships its own auth surface (no shelf `security-auth-*` blueprint applied) supplies capability answers via the elicitation phase:
+
+```
+rcf define blueprint add ./blueprints/application-account-settings \
+  --answer custom-auth-provides-principal-directory=true \
+  --answer custom-auth-provides-credential-self-service=true \
+  --answer security-surface-shape=self-service
+```
+
+Answers land on `rcf/blueprints/application-account-settings.applied.json`'s `appliedElicitations{}` map. The `when` predicate on each elicit gates whether the prompt fires: `security-surface-shape` only fires when `credentialSelfService` OR `hostedIdentityUi` is applied (through the shelf or through the custom-auth elicits); `hosted-identity-url` only fires when `hostedIdentityUi` is applied; `theme-persistence` is unconditional (a project that does not apply the SPA blueprint records the answer and the shell simply suppresses the theme tab).
+
+## The one runtime gate
+
+`probe-packs/application-account-settings.pack.mjs` ships five checks the `rcf verify browser` runner invokes on any FBS whose surface matches the pack's `appliesTo` predicate (an FBS that binds `TAC-2601-application-account-settings-shell` or whose nav model routes name an `/account`, `/settings` or `/profile` path). Each check ALSO carries its own `appliesTo` predicate that reads the applied capability sidecar and returns false when the required capability is absent; the check records `verdict: skipped` and the aggregate verdict treats it as neither pass nor fail (spec section 3.3, T-5 residual cure).
+
+Each check drives the real Playwright browser the runner provisions (through the pinned Playwright MCP or the consuming project's own `playwright` installation), reads the accessibility tree and the DOM, and returns a verdict.
+
+## Quality bar
+
+ARIA APG tabs pattern on the shell (TAC-2601); role="tablist" on the nav landmark with `aria-label="Account settings"`, role="tab" on each entry with `aria-selected="true"` on the active tab (WCAG 2.4.6). ARIA APG dialog-modal on the sessions terminate flow (TAC-2604, AC-25105-2); role="dialog" with aria-modal="true" and aria-labelledby to the heading, focus-trap, focus-return on close, polite live-region announcement on the confirm. WCAG 1.3.5 autocomplete tokens on every editable identifier on the profile surface (AC-25102-1). WCAG 3.3.8 Accessible Authentication Minimum on the security surface (ADR-2602). WCAG 3.3.4 Error Prevention on high-value changes gated by the reauth-window elicit (ADR-2604). The security-surface-shape default is elicited (ADR-2602 records no default: the shape leaks the vendor's identity architecture and no default is honest across all four combinations).
+
+## Known mechanism-reach gaps
+
+Runtime-observable ACs the pack does NOT bind directly (checklist section 6.g), listed individually:
+
+- **AC-25101-2 (single primary nav landmark accessible name shape).** The pack's AC-25101-1 asserts the landmark's `aria-label` is present; a future v1.1.0 minor bump can add a heading-order assertion (h1 page, h2 active tab).
+- **AC-25103-1 (self-service branch details beyond password + MFA regions).** The pack's AC-25105-1 confirms the two roles render; a future v1.1.0 minor bump can extend AC-25105-1 with a keyboard-flow assertion.
+- **AC-25104-1 (hosted-embed sandbox token beyond allow-scripts).** The pack's AC-25105-1 confirms `allow-scripts` in the sandbox; the wider token set is documented on ADR-2602 but not additionally asserted.
+- **AC-25105-2 (session-terminate focus-trap behaviour).** The pack's AC-25106-1 asserts the dialog is present and correctly wired; the focus-trap and focus-return behaviour is asserted at fixture-read time and by the project-side smoke tests, not by the pack's browser evaluate at v1.
+- **AC-25107-1 (notification-preferences surface capability discovery).** The pack does NOT probe the notifications surface at v1.0.0; the shell tabs check (AC-25101-1) confirms the tab renders only when `application-notifications-in-app` is applied via the fixture's `?apps=` switch. A future v1.1.0 minor bump can add a dedicated notifications surface check.
+- **AC-25109-1 and AC-25109-2 (apply-time refusal and override).** Probed by the mechanism unit tests, not by the browser pack. The gate reviewer runs the CLI directly.
+- **AC-25110-1 (Q3 apply-time refusal for a missing security capability).** Probed by the mechanism unit tests via the extended `runElicitationPhase` refusal path (added in this PR), not by the browser pack.
+
+## Known schema follow-ups
+
+The applied-blueprint sidecar at `rcf/blueprints/application-account-settings.applied.json` uses the schema shape T-5 admin-console established (no `verdict: skipped` field on the applied-record; the pack runtime records `verdict: skipped` per-check per spec section 3.3, and rcf-schemas 0.6.1 has no `applicable: false` field for the record). A future rcf-schemas minor may adopt the `appliedCapabilities[]` field on the applied-blueprint record directly; the sidecar path stays supported for backward compatibility.
+
+## Companions
+
+`suggestedCompanions` declares `logging` (every rendered account surface writes one request-scoped log line with the correlation identifier; the sessions surface reads a session inventory from `observability-logging` 1.2.0+ when configured) and `errorHandling` (profile-save, security-flow and session-terminate failures construct internal error records). Neither is required to apply the blueprint; the audit-history surface is deferred to v1.1.0.
+
+## Consumers
+
+The forbidden and empty-history states MAP to `application-empty-error-states` (T-1)'s `forbidden` and `empty-list` states. Every project applying `application-account-settings` MUST also apply `application-empty-error-states` if they want the shipped access-denied state; the shell composes on the empty-error-states components rather than inventing bespoke UI.
+
+The sessions and notification-preferences surfaces reuse the `application-datatable` (round-3 T-1) table shell contract when the project renders them through the datatable factory.

package/blueprints/application-account-settings/blueprint.json

@@ -0,0 +1,234 @@
+{
+  "slug": "application-account-settings",
+  "version": "1.0.0",
+  "category": "application",
+  "requiresAppliedCapabilities": {
+    "capabilities": [
+      "principalDirectory"
+    ],
+    "allowSkipFlag": "allow-no-auth-yet",
+    "refusalMessageId": "application-account-settings-bare-spa"
+  },
+  "elicits": [
+    {
+      "id": "custom-auth-provides-principal-directory",
+      "prompt": "Custom auth: does your projects own auth identify principals a users surface (and the account-settings profile surface) can read?",
+      "kind": "boolean",
+      "default": false,
+      "providesCapability": "principalDirectory"
+    },
+    {
+      "id": "custom-auth-provides-credential-self-service",
+      "prompt": "Custom auth: does your projects own auth expose a credential self-service surface (password change, MFA management, email change) the security tab can render in-place?",
+      "kind": "boolean",
+      "default": false,
+      "providesCapability": "credentialSelfService"
+    },
+    {
+      "id": "custom-auth-provides-session-inventory",
+      "prompt": "Custom auth: does your projects own auth (or logging companion) expose an inventory of active sessions with device labels and a terminate action?",
+      "kind": "boolean",
+      "default": false,
+      "providesCapability": "sessionInventory"
+    },
+    {
+      "id": "custom-auth-provides-hosted-identity-ui",
+      "prompt": "Custom auth: does your project point at a hosted identity portal (sign-in, sign-up, account, security) the security tab can link out to or embed?",
+      "kind": "boolean",
+      "default": false,
+      "providesCapability": "hostedIdentityUi"
+    },
+    {
+      "id": "security-surface-shape",
+      "prompt": "Security surface shape: self-service (renders the in-place password change and MFA surface), hosted-link-out (renders a link to your hosted portal) or hosted-embed (renders your hosted portal in an iframe).",
+      "kind": "enum",
+      "options": [
+        "self-service",
+        "hosted-link-out",
+        "hosted-embed"
+      ],
+      "when": {
+        "requiresCapability": [
+          "credentialSelfService",
+          "hostedIdentityUi"
+        ]
+      }
+    },
+    {
+      "id": "hosted-identity-url",
+      "prompt": "Hosted identity URL: the destination the security surface links out to or embeds when security-surface-shape is hosted-*. Ignored on self-service.",
+      "kind": "string",
+      "default": "",
+      "when": {
+        "requiresCapability": [
+          "hostedIdentityUi"
+        ]
+      }
+    },
+    {
+      "id": "theme-persistence",
+      "prompt": "Theme persistence: spa-local-storage (per-browser default), server-scoped (per-principal), or none (defers to prefers-color-scheme).",
+      "kind": "enum",
+      "options": [
+        "spa-local-storage",
+        "server-scoped",
+        "none"
+      ],
+      "default": "spa-local-storage"
+    },
+    {
+      "id": "reauth-window",
+      "prompt": "Re-authenticate window in minutes for high-value changes (password change, MFA change, session terminate, account delete). Enter never, 5, 15 or 60.",
+      "kind": "enum",
+      "options": [
+        "never",
+        "5",
+        "15",
+        "60"
+      ],
+      "default": "15"
+    }
+  ],
+  "suggestedCompanions": [
+    {
+      "role": "logging",
+      "reason": "Every rendered account surface writes one request-scoped log line with the correlation identifier; a logging companion supplies the factory the pipeline calls. When the logging companion also declares sessionInventory (observability-logging 1.2.0+), the sessions surface reads the inventory from the log projection."
+    },
+    {
+      "role": "errorHandling",
+      "reason": "Profile-save failures, security-flow failures and session-terminate failures construct internal error records; an error-handling companion supplies the record factory and the boundary the empty-error-states blueprint renders."
+    }
+  ],
+  "contributions": [
+    {
+      "id": "application-account-settings-REQ-001",
+      "kind": "req",
+      "path": "requirements/application-account-settings-req-001.json"
+    },
+    {
+      "id": "application-account-settings-REQ-002",
+      "kind": "req",
+      "path": "requirements/application-account-settings-req-002.json"
+    },
+    {
+      "id": "application-account-settings-REQ-003",
+      "kind": "req",
+      "path": "requirements/application-account-settings-req-003.json"
+    },
+    {
+      "id": "application-account-settings-REQ-004",
+      "kind": "req",
+      "path": "requirements/application-account-settings-req-004.json"
+    },
+    {
+      "id": "application-account-settings-REQ-005",
+      "kind": "req",
+      "path": "requirements/application-account-settings-req-005.json"
+    },
+    {
+      "id": "application-account-settings-REQ-006",
+      "kind": "req",
+      "path": "requirements/application-account-settings-req-006.json"
+    },
+    {
+      "id": "application-account-settings-US-25101",
+      "kind": "us",
+      "path": "user-stories/application-account-settings-us-25101.json"
+    },
+    {
+      "id": "application-account-settings-US-25102",
+      "kind": "us",
+      "path": "user-stories/application-account-settings-us-25102.json"
+    },
+    {
+      "id": "application-account-settings-US-25103",
+      "kind": "us",
+      "path": "user-stories/application-account-settings-us-25103.json"
+    },
+    {
+      "id": "application-account-settings-US-25104",
+      "kind": "us",
+      "path": "user-stories/application-account-settings-us-25104.json"
+    },
+    {
+      "id": "application-account-settings-US-25105",
+      "kind": "us",
+      "path": "user-stories/application-account-settings-us-25105.json"
+    },
+    {
+      "id": "application-account-settings-US-25106",
+      "kind": "us",
+      "path": "user-stories/application-account-settings-us-25106.json"
+    },
+    {
+      "id": "application-account-settings-US-25107",
+      "kind": "us",
+      "path": "user-stories/application-account-settings-us-25107.json"
+    },
+    {
+      "id": "application-account-settings-US-25108",
+      "kind": "us",
+      "path": "user-stories/application-account-settings-us-25108.json"
+    },
+    {
+      "id": "application-account-settings-US-25109",
+      "kind": "us",
+      "path": "user-stories/application-account-settings-us-25109.json"
+    },
+    {
+      "id": "application-account-settings-US-25110",
+      "kind": "us",
+      "path": "user-stories/application-account-settings-us-25110.json"
+    },
+    {
+      "id": "TAC-2601-application-account-settings-shell",
+      "kind": "tac",
+      "path": "tacs/tac-2601-application-account-settings-shell.json"
+    },
+    {
+      "id": "TAC-2602-application-account-settings-capability-discovery",
+      "kind": "tac",
+      "path": "tacs/tac-2602-application-account-settings-capability-discovery.json"
+    },
+    {
+      "id": "TAC-2603-application-account-settings-hosted-ui-bridge",
+      "kind": "tac",
+      "path": "tacs/tac-2603-application-account-settings-hosted-ui-bridge.json"
+    },
+    {
+      "id": "TAC-2604-application-account-settings-session-store",
+      "kind": "tac",
+      "path": "tacs/tac-2604-application-account-settings-session-store.json"
+    },
+    {
+      "id": "ADR-2601-application-account-settings-capability-vocabulary",
+      "kind": "adr",
+      "path": "adrs/adr-2601-application-account-settings-capability-vocabulary.json",
+      "standardsTraceClause": "generic enterprise practice"
+    },
+    {
+      "id": "ADR-2602-application-account-settings-security-surface-shape",
+      "kind": "adr",
+      "path": "adrs/adr-2602-application-account-settings-security-surface-shape.json",
+      "recommendedDefault": false,
+      "elicited": true,
+      "standardsTraceClause": "WCAG 3.3.8 Accessible Authentication (Minimum)"
+    },
+    {
+      "id": "ADR-2603-application-account-settings-theme-persistence",
+      "kind": "adr",
+      "path": "adrs/adr-2603-application-account-settings-theme-persistence.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "generic enterprise practice"
+    },
+    {
+      "id": "ADR-2604-application-account-settings-reauth-window",
+      "kind": "adr",
+      "path": "adrs/adr-2604-application-account-settings-reauth-window.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "WCAG 3.3.4 Error Prevention (Legal, Financial, Data)"
+    }
+  ]
+}

package/blueprints/application-account-settings/contributions/adrs/adr-2601-application-account-settings-capability-vocabulary.json

@@ -0,0 +1,20 @@
+{
+  "adrId": "ADR-2601-application-account-settings-capability-vocabulary",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Capability vocabulary: credentialSelfService, sessionInventory, hostedIdentityUi additions plus auditLog reuse",
+  "context": "The account-settings blueprint composes on the section 6a capability grammar visual round T-5 ratified. The T-4 spec (section 5.4.2) adds three capability strings the auth vendors need to declare in order for the security and sessions surfaces to render, and reuses auditLog where a project wants a self-view audit history rendered on the account surface (deferred: not a v1 surface but named in the vocabulary so a future minor bump can wire it without a chunk-zero edit).",
+  "decision": "v1.0.0 ratifies three additions to the section 6a capability table: credentialSelfService (in-place password change, MFA management, email change surface), sessionInventory (active-session listing with device labels and a terminate write), and hostedIdentityUi (link-out or embed to a hosted account portal). The auditLog capability continues to route via observability-logging. The three new strings follow the same shape rule (lower camelCase, ^[a-z][a-zA-Z0-9]*$) validated on the loader; the vocabulary lives in the section 6a table extended in the same PR.",
+  "consequences": "A bare-magic-link project gets a profile surface only; a Keycloak project gets profile plus security (self-service) plus sessions; a Clerk project gets profile plus security (hosted-link-out or embed) plus sessions; an OAuth2 project gets what the vendor declares. A future account-audit-history surface lands as a v1.1.0 minor bump reusing auditLog with no new vocabulary.",
+  "alternativesConsidered": [
+    {
+      "name": "Alternative approach considered",
+      "summary": "A single accountSelfService capability covering the security AND sessions AND theme surfaces was considered but conflates surfaces that vendors ship on different roadmaps: Keycloak has credentialSelfService without hostedIdentityUi, Clerk has hostedIdentityUi without a self-service equivalent. Separating them lets each vendor declare what it actually ships and lets the blueprint compose honestly.",
+      "reasonNotChosen": "See the decision text; the chosen shape composes cleanly with the applied blueprint set the spec section 5.4 names."
+    }
+  ],
+  "createdAt": "2026-09-06T20:55:46Z",
+  "updatedAt": "2026-09-06T20:55:46Z"
+}

package/blueprints/application-account-settings/contributions/adrs/adr-2602-application-account-settings-security-surface-shape.json

@@ -0,0 +1,20 @@
+{
+  "adrId": "ADR-2602-application-account-settings-security-surface-shape",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Security surface shape: password vs passkey vs hosted-UI vs link-out per applied auth",
+  "context": "The security surface has four legal shapes depending on the applied auth: self-service password (Keycloak, OAuth2 with a self-service endpoint), self-service passkey (WebAuthn where the auth blueprint declares credentialSelfService and the operator has stood up a passkey flow), hosted link-out to a portal (Clerk, Auth0), or hosted embed of the same portal in an iframe. The spec section 5.4 marks security-surface-shape as elicited with no recommended default because the security surface leaks the vendors identity architecture and no default is honest across all four applied-auth combinations.",
+  "decision": "security-surface-shape is elicited (enum: self-service | hosted-link-out | hosted-embed). No recommended default. Recording no default is the point: the operator picks the shape that matches the applied auth vendors surface. When the elicit is answered but no applied blueprint declares credentialSelfService (for self-service) or hostedIdentityUi (for the two hosted branches), apply refuses (AC-25110-1). The hosted-embed sandbox default is allow-scripts allow-forms allow-same-origin; a project that needs a different token set writes a project-scoped ADR overriding the sandbox.",
+  "consequences": "The operator makes an explicit choice at apply that reads on the sidecar; downstream review has a stable record of which security-surface-shape was elicited. A project that mis-answers (elicits hosted-link-out on a Keycloak project) hits the AC-25110-1 refusal at apply, not at runtime.",
+  "alternativesConsidered": [
+    {
+      "name": "Alternative approach considered",
+      "summary": "Auto-selecting the shape from the applied capability set was considered (self-service when credentialSelfService applied, else hosted-link-out when hostedIdentityUi applied) but the choice is a UX decision the operator owns, not a mechanism inference. Encoding it in the elicit keeps the choice legible.",
+      "reasonNotChosen": "See the decision text; the chosen shape composes cleanly with the applied blueprint set the spec section 5.4 names."
+    }
+  ],
+  "createdAt": "2026-09-06T20:55:46Z",
+  "updatedAt": "2026-09-06T20:55:46Z"
+}

package/blueprints/application-account-settings/contributions/adrs/adr-2603-application-account-settings-theme-persistence.json

@@ -0,0 +1,20 @@
+{
+  "adrId": "ADR-2603-application-account-settings-theme-persistence",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Theme persistence: spa-local-storage default, server-scoped or none",
+  "context": "The theme surface persists the light/dark/system choice. The applied SPA blueprint owns per-tab hydration; the account-settings blueprint owns the operator surface for choosing the theme and the persistence hand-off. The spec section 5.4 marks theme-persistence as elicited with recommendedDefault true on spa-local-storage because per-browser persistence is the least-surprising default and it does not require a server round-trip.",
+  "decision": "theme-persistence is elicited (enum: spa-local-storage | server-scoped | none). Recommended default: spa-local-storage. The applied SPA blueprint reads the persisted choice at hydrate time and applies data-theme on the html element before first paint (no flash of unstyled content). A server-scoped persistence writes the choice on the principals record so it follows the user across devices; the account-settings blueprint records the choice through its themeAdapter interface. A \"none\" choice reflects the projects prefers-color-scheme by default and never persists.",
+  "consequences": "A spa-local-storage project honours the users choice per browser tab family, which is the vernacular expectation. A server-scoped project pays the cost of a per-preference write. A none project honours the OS.",
+  "alternativesConsidered": [
+    {
+      "name": "Alternative approach considered",
+      "summary": "Auto-detecting from the applied blueprint set was considered but the choice is a UX decision.",
+      "reasonNotChosen": "See the decision text; the chosen shape composes cleanly with the applied blueprint set the spec section 5.4 names."
+    }
+  ],
+  "createdAt": "2026-09-06T20:55:46Z",
+  "updatedAt": "2026-09-06T20:55:46Z"
+}

package/blueprints/application-account-settings/contributions/adrs/adr-2604-application-account-settings-reauth-window.json

@@ -0,0 +1,20 @@
+{
+  "adrId": "ADR-2604-application-account-settings-reauth-window",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Re-authenticate before high-value changes (default: enabled)",
+  "context": "A high-value change (password change, MFA change, session terminate, account delete) that runs on the same session that opened the surface is a phishing risk when the session is stale. WCAG 3.3.4 (Error Prevention on legal, financial and data-changing actions) applies. The spec section 5.4 marks reauth-window as elicited with recommendedDefault true, meaning re-authenticate is enabled by default.",
+  "decision": "reauth-window is elicited (enum: never | 5m | 15m | 60m). Recommended default: 15m. A high-value change fires the re-authenticate flow when the session was last authenticated more than reauth-window minutes ago. A project that ships a short-lived session token (reauth-window irrelevant because the session itself expires within minutes) may set never; ADR records the choice and the risk. The re-authenticate flow itself is owned by the applied auth blueprint; this ADR names the trigger, not the implementation.",
+  "consequences": "A stolen laptop with an unlocked session cannot terminate every other session without re-authenticating within 15 minutes. The re-authenticate cost is a modal prompt on the operators sessions view, not a full sign-out flow.",
+  "alternativesConsidered": [
+    {
+      "name": "Alternative approach considered",
+      "summary": "Always require re-authenticate was considered but every operators surface would trigger it; a windowed policy balances safety and workflow.",
+      "reasonNotChosen": "See the decision text; the chosen shape composes cleanly with the applied blueprint set the spec section 5.4 names."
+    }
+  ],
+  "createdAt": "2026-09-06T20:55:46Z",
+  "updatedAt": "2026-09-06T20:55:46Z"
+}

package/blueprints/application-account-settings/contributions/requirements/application-account-settings-req-001.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-account-settings-REQ-001",
+  "prdId": "PRD-001",
+  "title": "Settings shell with no dead links to unapplied capabilities and ARIA APG tabs",
+  "description": "The settings shell renders a single primary tabs region (ARIA APG tabs pattern) whose entries mirror the union of applied capabilities discovered via readAppliedCapabilities. A tab whose capability is not applied does NOT render (no dead link, no disabled shell). A principal without an authenticated session reaching /account routes to the access-denied state through application-empty-error-states (T-1) with a sign-in link; no bespoke access-denied UI is invented here. Landmark, headings, focus order per WCAG 2.4.6.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Per visual round 4 spec (2026-09-06) section 5.4, REQ 1 of the account-settings blueprint.",
+  "tags": [
+    "blueprint:application-account-settings",
+    "category:01-shell"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T20:55:46Z",
+  "updatedAt": "2026-09-06T20:55:46Z"
+}

package/blueprints/application-account-settings/contributions/requirements/application-account-settings-req-002.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-account-settings-REQ-002",
+  "prdId": "PRD-001",
+  "title": "Profile surface always available with autocomplete tokens per WCAG 1.3.5",
+  "description": "The profile surface (/account/profile) is unconditional (any authenticated principal reaches it) and renders a form with WCAG 1.3.5 autocomplete tokens on every editable identifier (name, email, bday, country). Save success announces via aria-live polite (\"Profile saved\"). Save failure per field renders aria-invalid true with aria-describedby to the per-field error message and focus moves to the first invalid field (WCAG 3.3.1 Error Identification).",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Per visual round 4 spec (2026-09-06) section 5.4, REQ 2 of the account-settings blueprint.",
+  "tags": [
+    "blueprint:application-account-settings",
+    "category:02-profile"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T20:55:46Z",
+  "updatedAt": "2026-09-06T20:55:46Z"
+}

package/blueprints/application-account-settings/contributions/requirements/application-account-settings-req-003.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-account-settings-REQ-003",
+  "prdId": "PRD-001",
+  "title": "Security surface conditional on credentialSelfService OR hostedIdentityUi",
+  "description": "The security surface (/account/security) renders when the applied capability set contains credentialSelfService (self-service branch: password change, MFA setup, session-based sign-out) or hostedIdentityUi (link-out or embed branch: rendering an operator-elicited href or handle). When NEITHER capability is applied, the security tab does not render and the surface refuses at apply with the two-remedy message (declare a capability, or drop the security tab from scope) per spec Q3.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Per visual round 4 spec (2026-09-06) section 5.4, REQ 3 of the account-settings blueprint.",
+  "tags": [
+    "blueprint:application-account-settings",
+    "category:03-security"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T20:55:46Z",
+  "updatedAt": "2026-09-06T20:55:46Z"
+}

package/blueprints/application-account-settings/contributions/requirements/application-account-settings-req-004.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-account-settings-REQ-004",
+  "prdId": "PRD-001",
+  "title": "Sessions surface conditional on sessionInventory",
+  "description": "The sessions surface (/account/sessions) renders when sessionInventory is applied. Lists active sessions in a table enumerated by data-session-id with device label, last-active timestamp and terminate control. Terminate opens an ARIA APG dialog-modal (role=dialog, aria-modal=true, aria-labelledby to the heading, focus trap, focus returns to the row on close) confirming the action; on submit the row disappears from the table and a polite \"Session ended\" announcement fires (WCAG 4.1.3 Status Messages).",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Per visual round 4 spec (2026-09-06) section 5.4, REQ 4 of the account-settings blueprint.",
+  "tags": [
+    "blueprint:application-account-settings",
+    "category:04-sessions"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T20:55:46Z",
+  "updatedAt": "2026-09-06T20:55:46Z"
+}