rcf-lite 0.12.0 → 0.13.0

package/blueprints/application-spa/contributions/user-stories/application-spa-us-1131.json

@@ -0,0 +1,72 @@
+{
+  "usId": "application-spa-US-1131",
+  "prdId": "PRD-001",
+  "reqId": "application-spa-REQ-018",
+  "version": "1.0.1",
+  "status": "approved",
+  "title": "Styled-under-shipped-CSP adherence probe refuses ship on inline styles or unstyled runtime",
+  "asA": "operator relying on the security baseline the application-spa blueprint declares",
+  "iWant": "a runtime check that fails the build when the application ships with inline style blocks, a CSP relaxed to unsafe-inline, or a runtime surface that renders unstyled under the shipped headers",
+  "soThat": "the application-spa-REQ-018 security floor is enforced at the ship gate and every UI surface reaches production styled without the CSP being weakened",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-1131-1",
+      "description": "The CSP served on every HTML document declares style-src that resolves to 'self' (or a nonce / hash allowlist), and NEVER contains the 'unsafe-inline' or 'unsafe-eval' relaxations. A wildcard style-src is refused; declaring 'unsafe-inline' as a fallback is refused. The CSP style-src is the sole styling-authority signal the runtime respects; a stylesheet the CSP would refuse is a defect, not a warning.",
+      "given": "the deployed application document response",
+      "when": "the Content-Security-Policy header is inspected",
+      "then": "style-src is present, resolves to 'self' or a nonce / hash allowlist, and contains neither 'unsafe-inline' nor 'unsafe-eval' nor a wildcard source",
+      "testable": true,
+      "scope": "deployed"
+    },
+    {
+      "id": "AC-1131-2",
+      "description": "No HTML surface shipped by the application carries an inline <style> block. Stylesheets are served from same-origin routes referenced via <link rel=\"stylesheet\">; every occurrence of <style> in a rendered response body is a defect, including <style> injected via templating helpers or partials.",
+      "given": "any rendered HTML response from the application surface",
+      "when": "the response body is scanned for the substring '<style'",
+      "then": "zero occurrences are present; a positive match is a hard refusal",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-1131-3",
+      "description": "Every UI-bearing route renders styled UNDER the shipped strict CSP, AND the probe proves it exercised the requested surface (not a page a redirect would land on). A browser-driven check drives the same server instance that stamps the production security headers, navigates each enumerated UI route, and asserts (a) the browser's final URL path equals the requested route path; a silent redirect (for example an authenticated route 302'ing to /login when the harness session is broken) is a hard refusal because a headless browser follows redirects by default and would otherwise validate the redirect target's styled state seven times over, and (b) the computed body background is NOT the browser default (rgba(0,0,0,0) / transparent) and the computed body font-family resolves to a non-empty value. Verification runs through the production header path; a harness that strips the security headers, injects nonces the CSP does not declare, or invokes the app via app.inject() rather than a real browser fetch does NOT satisfy the AC. Cures the class of harness where a broken session lane silently causes every route assertion to run against /login (styled) and pass (watchpost run4 partial-acceptance gap, w-2026-08-24-003 / AC-1601-14).",
+      "given": "a server booted through the project's production entry point with every UI-bearing route registered",
+      "when": "a real browser navigates each enumerated route, its final URL is read, and getComputedStyle(document.body) is read",
+      "then": "the final URL path equals the requested route (no silent redirect chain to another surface) AND the computed background is not the browser default AND the computed font-family resolves; on any route the check fails, the run refuses ship with a per-route diagnostic naming the requested and landed paths",
+      "testable": true,
+      "scope": "deployed"
+    },
+    {
+      "id": "AC-1131-4",
+      "description": "The stylesheet-serving route is registered by the same server construction that stamps the production security headers. A separate server instance, a static-file-only mount, or a build harness that skips the shipped header stack does NOT satisfy the AC. The intent is that a same-origin GET for the linked stylesheet URL returns 200 with content-type text/css under the same headers a browser sees for the HTML documents.",
+      "given": "the application boot topology at ship",
+      "when": "the boot topology is inspected AND a same-origin GET is issued for the URL every rendered HTML links via <link rel=\"stylesheet\">",
+      "then": "the stylesheet is served by the same server instance that stamps the production headers AND the response is 200 with content-type text/css",
+      "testable": true,
+      "scope": "deployed"
+    },
+    {
+      "id": "AC-1131-5",
+      "description": "The styled-under-shipped-CSP adherence probe (TAC-209) writes a JSON report at a stable relative path (`reports/csp-styled-adherence.json` under the configured report directory) naming every route probed, the CSP header captured for that route, whether an inline <style> was detected, the computed body background and font-family, the landed URL path (the browser's final URL after any redirect chain resolved) so a pathMismatch refusal names both the requested and landed paths, and an ok / fail verdict.",
+      "given": "a completed probe run (pass or fail)",
+      "when": "the report file is inspected on disk",
+      "then": "the JSON at `reports/csp-styled-adherence.json` matches the shape declared by TAC-209 and its verdict field agrees with the process exit code",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-1131-6",
+      "description": "When the styled-under-shipped-CSP adherence probe is wired as a gate in the ci-pipeline runner (TAC-701), a non-zero probe exit propagates through the per-gate report (TAC-702) and the aggregate report (TAC-703), and the ci-pipeline runner refuses ship with a non-zero exit.",
+      "given": "the ci-pipeline runner configured with the styled-under-CSP adherence probe as a required gate",
+      "when": "the probe reports `fail` on any run",
+      "then": "the aggregate report records the gate as failed and the runner exits non-zero",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-209-application-spa-csp-styled-adherence-probe"
+  ],
+  "createdAt": "2026-08-24T10:30:00Z",
+  "updatedAt": "2026-08-31T11:15:00Z"
+}

package/blueprints/application-spa/contributions/user-stories/application-spa-us-1132.json

@@ -0,0 +1,72 @@
+{
+  "usId": "application-spa-US-1132",
+  "prdId": "PRD-001",
+  "reqId": "application-spa-REQ-018",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "External-service-dependency provisioning adherence probe refuses ship on placeholder credentials or unratified deferrals",
+  "asA": "operator responsible for the deployed application's dependence on external services",
+  "iWant": "a runtime check that fails the build when the application ships with a declared external-service dependency whose credentials are placeholder-shaped, or whose provisioning has been silently deferred without an operator-ratified deferral record",
+  "soThat": "an app is never signed off as deployed while an external service the runtime depends on is inert on a placeholder key or has been quietly parked as a documented quirk",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-1132-1",
+      "description": "Every external-service dependency the application declares (email transports, payment providers, third-party API adapters, transactional-mail senders, SMS gateways, storage providers, and any other network dependency the runtime reaches for at request-time) is enumerated in a stable, discoverable manifest at ship-time. The manifest names, per dependency, the dependency id, the purpose, the credential field name, the intended provider, and a status of either 'verified' or 'deferred'. A dependency the app calls at runtime but does NOT declare in the manifest is a hard refusal.",
+      "given": "the application boot topology at ship",
+      "when": "the external-service-dependency manifest is inspected",
+      "then": "the manifest exists at the stable path the probe reads, enumerates every runtime-reached external service, and names a status per dependency; any runtime-reached external service missing from the manifest refuses ship",
+      "testable": true,
+      "scope": "deployed"
+    },
+    {
+      "id": "AC-1132-2",
+      "description": "Placeholder-shaped credential values are detected at gate time and refused. The placeholder-shape detector rejects: the empty string, the single characters '-' and '_', values matching /^(changeme|placeholder|example|test|dummy|fake|todo|tbd|xxx+|your[_-].+[_-]here)$/i, values matching /YOUR_.+_HERE/i, values equal to the literal strings 'null' or 'undefined' or 'None', and values that repeat a single character across their full length (e.g. 'xxxxxxxx'). A positive match against any credential field named on the manifest is a hard refusal, regardless of the declared status.",
+      "given": "the resolved value of every credential field named on the external-service-dependency manifest at ship",
+      "when": "the placeholder-shape detector is applied to each value",
+      "then": "no manifest-named credential field carries a placeholder-shape value; a positive match refuses ship",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-1132-3",
+      "description": "A dependency at status 'verified' requires captured evidence of a real live handshake with the external service, gathered from the SHIPPED runtime (the same server construction the production entry point boots). Evidence is a provider-side acknowledgement of a probe request: a provider message id, a 2xx from the provider's own status endpoint, or an equivalent provider-attested receipt. A unit-test pass, a mocked adapter response, a synthetic 'ok', or an in-process stub does NOT satisfy the evidence requirement.",
+      "given": "a dependency declared with status 'verified' on the external-service-dependency manifest",
+      "when": "the probe replays the manifest-declared handshake against the shipped runtime",
+      "then": "the provider returns a live acknowledgement whose id or timestamp is captured on the probe report; the run refuses ship on any absent or synthesised evidence",
+      "testable": true,
+      "scope": "deployed"
+    },
+    {
+      "id": "AC-1132-4",
+      "description": "A dependency at status 'deferred' requires an operator-ratified deferral record persisted at a stable project-owned path. The record names the dependency id, the reason for deferral, the acknowledging operator identifier, the ISO-8601 acknowledgement timestamp, and the intended resolution route. A README note, a status.md 'quirk' or 'known-issue' line, a code comment, a commit message, or a work-item link on its own does NOT satisfy the deferral requirement. Absence of a ratified record for a 'deferred' dependency refuses ship.",
+      "given": "a dependency declared with status 'deferred' on the external-service-dependency manifest",
+      "when": "the probe checks for the deferral record at the manifest-named path",
+      "then": "the record exists at the stable path, carries the required fields, and is not stale beyond the ratified window; the run refuses ship on any missing, malformed, or expired record",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-1132-5",
+      "description": "The external-service-dependency provisioning probe (TAC-210) writes a JSON report at a stable relative path ('reports/external-dependency-provisioning.json' under the configured report directory) naming every dependency declared, the credential-field placeholder-detector verdict per dependency, the captured handshake evidence per 'verified' dependency, the ratified deferral record reference per 'deferred' dependency, per-dependency verdict, and an aggregate verdict of 'ok' | 'deployed-with-defects'. The 'ok' verdict is reserved for runs in which every declared dependency resolves to 'verified' with live evidence OR 'deferred' with a valid ratified record; any placeholder-shape match, any missing handshake evidence for a 'verified' entry, or any missing ratified record for a 'deferred' entry lands the aggregate at 'deployed-with-defects'.",
+      "given": "a completed probe run (pass or fail)",
+      "when": "the report file is inspected on disk",
+      "then": "the JSON at 'reports/external-dependency-provisioning.json' matches the shape declared by TAC-210 and its aggregate 'verdict' field agrees with the process exit code (0 for 'ok', non-zero for 'deployed-with-defects')",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-1132-6",
+      "description": "When the external-service-dependency provisioning probe is wired as a gate in the ci-pipeline runner (TAC-701), a non-zero probe exit propagates through the per-gate report (TAC-702) and the aggregate report (TAC-703), and the ci-pipeline runner refuses ship with a non-zero exit. The 'deployed-with-defects' probe verdict maps deterministically to a 'failed' entry in the TAC-703 aggregate; a run cannot land the pipeline aggregate at 'passed' while any external-service dependency carries placeholder credentials or an unratified deferral.",
+      "given": "the ci-pipeline runner configured with the external-service-dependency provisioning probe as a required gate",
+      "when": "the probe reports 'deployed-with-defects' on any run",
+      "then": "the aggregate report records the gate as failed and the runner exits non-zero",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-210-application-spa-external-dependency-provisioning-probe"
+  ],
+  "createdAt": "2026-08-24T13:00:00Z",
+  "updatedAt": "2026-08-24T13:00:00Z"
+}

package/blueprints/application-spa/contributions/user-stories/application-spa-us-1133.json

@@ -0,0 +1,72 @@
+{
+  "usId": "application-spa-US-1133",
+  "prdId": "PRD-001",
+  "reqId": "application-spa-REQ-008",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Core-flow end-to-end adherence probe refuses ship without captured evidence every core flow completes against the shipped runtime",
+  "asA": "operator relying on the journey-completeness discipline the application-spa blueprint declares",
+  "iWant": "a runtime check that fails the build unless every core user flow the application enumerates completes end-to-end against the shipped runtime with real providers and captured evidence, with authentication always included when the application has any authentication surface",
+  "soThat": "an app is never signed off as done while its core flows (authentication first) are unproven end-to-end in the production runtime, and 'a workaround exists' explicitly does not convert a broken flow into a passing check",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-1133-1",
+      "description": "The application enumerates its core user flows in a stable, discoverable manifest at ship-time. Each enumerated flow names a flow id, an entry-point route, an ordered sequence of user-driven steps that reach a terminal success state, and a terminal success assertion (a DOM signal, a URL, or an authenticated-session signal). When the application declares any authentication surface (application-spa-REQ-009), authentication is ALWAYS enumerated as a core flow; the probe refuses ship when the manifest omits an authentication flow while application-spa-REQ-009 surfaces are present.",
+      "given": "the application boot topology at ship",
+      "when": "the core-flow manifest is inspected",
+      "then": "the manifest exists at the stable path the probe reads, enumerates every declared core flow with the required fields, and includes an authentication flow whenever the application has a application-spa-REQ-009 authentication surface",
+      "testable": true,
+      "scope": "deployed"
+    },
+    {
+      "id": "AC-1133-2",
+      "description": "Every enumerated core flow executes end-to-end against the SHIPPED runtime: the same server construction the production entry point boots (same route registration, same production security-header stack, same middleware, same static-asset serving), driven by a real headless browser against real external-service providers (not stubbed adapters, not app.inject, not a bespoke test harness). The probe refuses ship when any flow ran through an in-process fetch, a mocked provider, a header-stripping harness, or a server instance the production entry point does not construct.",
+      "given": "the server the probe drives",
+      "when": "every enumerated core flow is executed by a real browser against the shipped construction",
+      "then": "every flow runs through the production entry-point path with real providers; any flow executed against a mocked provider or a bypassed header path refuses ship",
+      "testable": true,
+      "scope": "deployed"
+    },
+    {
+      "id": "AC-1133-3",
+      "description": "For every enumerated core flow the probe captures evidence sufficient to reconstruct the run: the ordered navigation trace (routes visited with response status codes), the terminal DOM assertion result, the wall-clock timing per step, and any provider-side ids the flow generated (e.g. an emailed magic-link id, a payment-provider intent id). A skipped, timed-out, or absent evidence entry for any enumerated core flow is a HARD REFUSAL; 'a documented workaround exists', a status.md quirk line, an operator note, or a mint-your-own-token bypass explicitly does NOT convert a broken or skipped flow into a passing verdict.",
+      "given": "an enumerated core flow whose captured evidence is absent, marked 'skipped', or ends in a non-success terminal state",
+      "when": "the probe assembles its report",
+      "then": "the flow is recorded as 'fail' (or 'skip') and the probe refuses ship; no workaround note, README caveat, or documented quirk overrides the refusal",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-1133-4",
+      "description": "For every core flow that fails or is skipped, the probe writes a machine-readable refusal on the report naming the flow id, the entry-point route, the step at which the flow diverged from expectation, the assertion that did not hold, and the captured evidence up to the divergence. The refusal renders in the probe's stdout with the flow id and the report path, so a ci-pipeline operator reading the runner output sees which flow refused and where to look. Silent-log refusals are not permitted; every refusal exits the probe non-zero.",
+      "given": "any core flow the probe records as 'fail' or 'skip'",
+      "when": "the probe run terminates",
+      "then": "the probe report carries a structured refusal entry naming the flow, the divergence step, and the failing assertion; stdout names the flow id and the report path; the process exit is non-zero",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-1133-5",
+      "description": "The core-flow end-to-end probe (TAC-211) writes a JSON report at a stable relative path ('reports/core-flow-e2e-adherence.json' under the configured report directory) naming every core flow enumerated, its captured evidence entry, its per-flow verdict ('ok' | 'fail' | 'skip'), and an aggregate 'verdict' field of 'ok' | 'deployed-with-defects'. The 'ok' aggregate is reserved for runs in which every enumerated core flow lands 'ok'; any 'fail' or 'skip' entry lands the aggregate at 'deployed-with-defects'.",
+      "given": "a completed probe run (pass or fail)",
+      "when": "the report file is inspected on disk",
+      "then": "the JSON at 'reports/core-flow-e2e-adherence.json' matches the shape declared by TAC-211 and its aggregate 'verdict' agrees with the process exit code (0 for 'ok', non-zero for 'deployed-with-defects')",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-1133-6",
+      "description": "When the core-flow end-to-end probe is wired as a gate in the ci-pipeline runner (TAC-701), a non-zero probe exit propagates through the per-gate report (TAC-702) and the aggregate report (TAC-703), and the ci-pipeline runner refuses ship with a non-zero exit. The 'deployed-with-defects' probe verdict maps deterministically to a 'failed' entry in the TAC-703 aggregate; a run cannot land the pipeline aggregate at 'passed' while any enumerated core flow ran as 'fail' or 'skip'.",
+      "given": "the ci-pipeline runner configured with the core-flow end-to-end probe as a required gate",
+      "when": "the probe reports 'deployed-with-defects' on any run",
+      "then": "the aggregate report records the gate as failed and the runner exits non-zero",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-211-application-spa-core-flow-e2e-probe"
+  ],
+  "createdAt": "2026-08-24T13:00:00Z",
+  "updatedAt": "2026-08-24T13:00:00Z"
+}

package/blueprints/application-spa/docs/topics.md

@@ -0,0 +1,57 @@
+# application-spa blueprint coordination vocabulary
+
+This file is the cross-blueprint contract. The Phase 1 conflict detector matches scope:global ADR topics by EXACT string equality, and AC ids are unnamespaced by the 0.4.4 grammar. Any blueprint intended to compose with this one must reuse these exact strings and respect these bands.
+
+## Global ADR topics (exact strings)
+
+| Topic string | application-spa contribution | Meaning | Composition note |
+|---|---|---|---|
+| `clientRouting` | ADR-201-application-spa-routing | How URLs map to client surfaces | Owned by the client tier; a second client-tier blueprint on one project conflicts here by design |
+| `theming` | ADR-202-application-spa-theming | The one theming mechanism for the project | Any blueprint contributing themable UI must join or supersede this decision. v1.1 strengthens the ADR in place with a runtime-observable probe (TAC-207); topic ownership is unchanged. |
+| `clientState` | ADR-203-application-spa-client-state | Client cache and state regime | Client-tier owned |
+| `errorEnvelope` | ADR-204-application-spa-error-envelope | The wire error shape | The application-api-rest blueprint contributes its own scope:global ADR on this exact topic; `rcf define blueprint add application-api-rest` after application-spa (or vice versa) surfaces a DELIBERATE conflict for operator resolution. Expected resolution: one project-level ADR adopting RFC 7807 end to end, superseding both |
+| `authModel` | ADR-205-application-spa-auth-model | The project authentication model | Same deliberate pairing with the application-api-rest blueprint's auth-classes decision; security-auth-magic-link blueprint adds a third contributor. Resolve with one project-level ADR and `--resolve authModel=project:<id>` on subsequent adds |
+
+Rules for new topics: lower camel case, one concept per topic, no version suffixes. A topic names the decision area, not the chosen answer.
+
+v1.1 mints ZERO new global topics. The mechanism-reach cure lives entirely in additive non-global contributions (TAC-207, TAC-208, application-spa-US-1129, application-spa-US-1130) plus in-place amendments to ADR-206 and ADR-202 that strengthen the consequences narrative without moving the decision. `iconography` is NOT a global topic and remains non-global in v1.1.
+
+## Id number bands
+
+AC ids (and therefore US numeric ids, which anchor them) are NOT namespaced by the 0.4.4 schema grammar; only the band allocation prevents cross-blueprint AC collisions. The band IS the AC-collision enforcement mechanism: composing blueprints take a fresh band rather than proposing namespaced AC ids.
+
+## Full-ecosystem registry table (post-v1.1.0 SPA bump)
+
+This table is maintained shelf-wide across every blueprint's `docs/topics.md`. Rows are recorded at ship, never predicted.
+
+| Blueprint | US band | ADR/TAC suffix block | Status | Global topics |
+|---|---|---|---|---|
+| application-spa | 1101-1899 | 2xx | shipped v1.3.0 | `clientRouting`, `theming`, `clientState`, `errorEnvelope`, `authModel` |
+| application-api-rest | 2101-2899 | 3xx | shipped v1.0.0 | `errorEnvelope`, `authModel`, `apiVersioning`, `logging` |
+| security-auth-magic-link | 3101-3899 | 5xx | shipped v1.0.0 | `authModel` |
+| email-smtp-resend | 4101-4899 | 4xx | shipped v1.0.0 | none |
+| hello-panel (walkthrough exemplar) | 4101-4899 | 4xx | doc-reserved; teaching exemplar in `packages/rcf-lite/docs/blueprint-authoring-walkthrough.md`, not shipped as a blueprint directory | `operatorPanel` |
+| persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| ci-pipeline | 6101-6899 | 7xx | shipped v1.0.0 | `ciGates`, `strictCoverageGate` |
+| observability-essentials | 7101-7899 | 8xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics`, `statusPageContract` |
+| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.0 | `secretsSource` |
+| security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
+| security-auth-oauth2 | 10101-10899 | 11xx | shipped v1.0.0 | `authModel` |
+| security-auth-keycloak | 11101-11899 | 12xx | shipped v1.0.0 | `authModel` |
+| deploy-cloudflare-workers | 12101-12899 | 13xx | shipped v1.0.0 | `deploymentTarget` |
+| persistence-data-d1 | 13101-13899 | 14xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| observability-probe-endpoints | 14101-14899 | 15xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics` |
+
+SPA v1.1.0 stays on the LOW end of its band: v1.0.0 occupied US-1101 through US-1128; v1.1.0 adds US-1129 and US-1130, leaving headroom above 1130 for future minor bumps and for project-side stories that mechanically derive to the 11xx numeric range.
+
+Suffix-family ids (ADR, TAC) are string-distinct once slug-suffixed. SPA numbers its ADRs and TACs in the 2xx block for legibility: v1.0.0 ADR-201 through ADR-209 and TAC-201 through TAC-206; v1.1.0 adds TAC-207-application-spa-token-adherence-probe and TAC-208-application-spa-icon-adherence-probe.
+
+## Shared expectations for composing blueprints
+
+- Reuse `errorEnvelope`, `authModel`, and `theming` exactly as spelled above; do not mint `errorShape`, `auth`, or theme variants. New blueprints authoring in the `theming` space either supersede ADR-202 with a project-level ruling or supersede-and-adopt.
+- The SPA data layer consumes RFC 7807 problem details (ADR-204) and cookie-based sessions (ADR-205); a client-tier blueprint's decisions should state their client-facing halves in terms compatible with these or expect the operator to supersede both.
+- The v1.1 token-adherence probe and icon-adherence probe are BLUEPRINT ACs bound to BLUEPRINT TACs. A composing project realises the TACs against its own build layout; the ACs are runtime-observable and TC-bindable in the project's build cycle.
+
+## v1.0.0 US-1101 collision note (preserved)
+
+In run4 of the watchpost case study, a project-side `US-1101` derived mechanically from `REQ-011` (leading `11` + sequence `01`) collided with the application-spa blueprint's `application-spa-us-1101` at the AC-id-scoping bucket. The seat allocated the project story as `US-1181` and moved on. Lesson: keep contributions on the LOW end of the band and leave headroom at the HIGH end for project-side stories that mechanically derive to your numbers. v1.1 preserves this lesson: US-1129 and US-1130 remain at the low end.

package/blueprints/application-spa/guide/application-spa.md

@@ -0,0 +1,40 @@
+# The application-spa blueprint: an operator's guide
+
+This guide is for the human running the project, not the coding agent. It explains what applying this blueprint buys you, when it is the wrong tool, and what still needs your judgement afterwards.
+
+## What this blueprint is
+
+A specification package for single-page applications with public and authenticated surfaces, session-based auth, one deployable, dark and light by default, fully responsive by default. Applying it (`rcf define blueprint add <path>`) merges 64 namespaced documents into your RCF tree: 21 requirements, 28 user stories carrying 167 acceptance criteria, 6 architectural components, and 9 decision records. It also ships a design system: contrast-validated design tokens for both themes, a realising stylesheet, wireframes for the nine canonical surfaces, per-component behaviour contracts, a viewport table, and sample data.
+
+The point, in one sentence: the visual and UX floor of your build becomes part of the specification, so the same build cycle that verifies your features also verifies that the product looks and behaves like someone cared.
+
+## What it deliberately is not
+
+- It is not code. No components, no framework choice, no test files. Your working agent implements tests from the ACs the same way it does for your own stories, and writes the application in whatever stack the project chose. (Blueprints shipping tests was considered and ratified out: adherence is expressed as ACs, decision 5 of the design brief.)
+- It is not your product spec. It says every route must handle empty, loading, error, and success; it cannot know what your routes are. Elicitation still happens; this package is the floor under it.
+- It does not ship FBS work items. FBSs are the work of the implementing agent, not the blueprint: build tasks have to be derived in the host project at creation time, where the project's own constraints, sequencing, and existing work apply. The blueprint contributes the WHAT (REQ/US/AC/TAC/ADR); your project derives the HOW.
+
+## When to reach for it
+
+Any project whose primary surface is a browser SPA: dashboards, admin panels, SaaS products, internal tools that deserve to feel like products. Compose it freely with an API blueprint; that composition is the intended shape.
+
+## When it does not fit
+
+- Server-rendered or content-first sites (marketing, docs): the routing and state decisions here assume a client-side application; a future static-site blueprint is the right home.
+- Native or hybrid mobile shells: the breakpoints and target-size floors overlap, but the navigation and auth decisions do not transfer.
+- Projects with a mandated design system: apply the blueprint for its behavioural ACs, then supersede the theming ADR and swap the token values; the parity and contrast ACs still hold and will validate your mandated palette.
+
+## What a good outcome looks like
+
+Walk any journey in the finished product and try to catch it looking abandoned: force an error, empty a list, expire the session mid-form, switch to dark, drop the network, tab through without a mouse, load it on a phone. A build that honours this doc set has a designed answer everywhere you poke. That is the measure: what the user sees out of the box, against how much was left for them to discover broken.
+
+## Your decisions that remain open
+
+1. Copy. Every empty state, error, and onboarding surface carries product-specific copy; the ACs require the template text be replaced (AC-1124-5).
+2. The five global decisions. Routing, theming, client state, error envelope, auth model ship as accepted defaults. Disagree by superseding with a project-level ADR, not by editing the blueprint's files.
+3. Composition conflicts. Adding a REST-style blueprint will surface deliberate conflicts on `errorEnvelope` and `authModel`. That is the mechanism working: resolve each with one project-level decision.
+4. Key routes and journeys. The performance and journey ACs bind to inventories your project declares during elicitation. Declare them honestly; an empty journey inventory makes those ACs vacuously green and that defeats the point.
+
+## Cost honesty
+
+This doc set makes builds slower to declare done, on purpose: 167 criteria is the price of "no route ships half-dressed". If the project is a one-day throwaway, that price is wrong for you; skip the blueprint rather than opting out of half of it. If the project has users, the price is the product.

package/blueprints/ci-pipeline/README.md

@@ -0,0 +1,49 @@
+# Ci-pipeline blueprint (v1.0.0)
+
+The fifth content blueprint on the rcf-build-lite blueprint mechanism (design brief v2, ratified). Scope: a CI-provider-neutral gate suite that runs `rcf define validate` and `rcf audit coverage --strict` as required gates on every push to the default branch and every pull request into it, writes machine-readable JSON reports at stable paths, and refuses to declare a pipeline pass on any missing or failed required gate. The suite is a single Node entry-point script the CI job invokes with one line; one illustrative GitHub Actions workflow ships as a starting point and alternate providers wire the same script.
+
+## Apply
+
+```
+rcf define blueprint add <path-to>/blueprints/ci-pipeline
+```
+
+Phase 1 resolves local path sources only; registry and git-ref resolution is a mechanism follow-up. Apply is idempotent; `rcf define blueprint list` shows the applied entry; `rcf define blueprint remove ci-pipeline` cleanly removes an unreferenced application.
+
+## Anatomy
+
+| Piece | Where | What |
+|---|---|---|
+| Metadata | `blueprint.json` | Slug, version, and the 27 contributions with scope/topic on the two global ADRs |
+| Doc set | `contributions/` | 10 REQs, 10 USs (20 ACs), 3 TACs, 4 ADRs, all schema-valid against rcf-schemas 0.4.5 and namespaced (`ci-pipeline-REQ-001` prefix family; `ADR-701-ci-pipeline-ci-gates` suffix family) |
+| GitHub Actions example | `assets/ci-provider-examples/github-actions.yml` | One illustrative workflow: push and pull_request triggers on the default branch, Node and pnpm setup, single-line entry-point invocation, artefact upload of the report directory |
+| Alternate-provider notes | `assets/ci-provider-examples/notes.md` | The four-point mapping (job trigger event, Node setup, single-line entry-point invocation, artefact upload) for GitLab CI, CircleCI, Buildkite, and Jenkins |
+| Report-shape samples | `assets/report-samples/per-gate.json`, `assets/report-samples/pipeline.json` | Worked examples of a per-gate report and an aggregate report at the ratified schemas |
+| Guide | `guide/ci-pipeline.md` | Operator-facing: when to use it, when not, what stays your call, and how to extend the required gate set |
+| Coordination vocabulary | `docs/topics.md` | The two global-topic strings this blueprint contributes, the shared id band registry (application-spa, application-api-rest, security-auth-magic-link, hello-panel, persistence-data-sqlite, ci-pipeline, observability-essentials) |
+
+The doc set is contributions (copied into the project tree by `rcf define blueprint add`); the guide, assets, and docs are package-resident references. Guide rendering into `rcf/knowledge/docs/blueprint-guides/` and asset ingestion are mechanism follow-ups; until they land, the working agent reads them from the applied blueprint's source path recorded in `manifest.blueprints[].source`.
+
+## What it contributes, and what it deliberately does not
+
+Contributed kinds: REQ, US (with inline ACs), TAC, ADR. Adherence is expressed as ACs; the blueprint ships no test files (ratified decision 5) and no code.
+
+No FBS contributions, as a matter of principle (ratified policy 2026-08-19): FBSs are the work of the implementing agent, not the blueprint. The blueprint contributes the WHAT (the gate-runner contract, the per-gate report writer contract, the aggregate report writer contract, the fixed-gate-set discipline); the implementing agent derives the HOW-tasks in the host project, where the ACs contributed here get picked up by the project's own build sequencing.
+
+Deliberately not contributed: a matrix of provider-specific configuration files (only one illustrative GitHub Actions workflow ships; alternate providers wire the same Node entry point per the guide's four-point mapping); provider-specific pipeline plugins or actions (each provider's action or plugin catalogue is a per-provider decision the project owns); a Node entry-point source file or scaffolding code (adherence is expressed as ACs, not code; the project realises the entry point in its own build cycle against the TAC contracts); a linter, formatter, or unit-test gate (out of scope at v1.0.0; a project that wants those adds them via a project-level ADR superseding ADR-701 and lists the extended gate set); a merge-queue integration (a project that wants one wires the aggregate report into the merge-queue tool the project picked); a coverage-trend dashboard (a project that wants one reads the aggregate reports over time and layers the dashboard on top).
+
+## The two global decisions
+
+ADR-701-ci-pipeline-ci-gates ships `scope: global` on topic `ciGates`. This is the project's required-gate set: two gates in fixed order at v1.0.0 (`validate` then `coverage-strict`). A composing blueprint that ships its own required-gate opinion (adherence packs, browser-verify smokes, observability probes) conflicts here by design and expects a project-level ADR that names the extended set.
+
+ADR-702-ci-pipeline-strict-coverage-gate ships `scope: global` on topic `strictCoverageGate`. This is the project's coverage-mode posture: per-AC strict, not shallow-any. A composing blueprint that holds a different coverage posture (a shallow-any-for-early-projects blueprint, a coverage-with-grace-window blueprint) conflicts here by design.
+
+See `docs/topics.md` for the exact strings, the expected resolutions, the delineation from the application-api-rest blueprint's `logging` topic (wire-log shape, not build-time report shape), and the AC id band allocation (ci-pipeline owns 6101-6899).
+
+## Quality bar
+
+Every push to the default branch and every pull request into it runs the RCF gate suite as a required check; `rcf define validate` runs first and its non-zero exit terminates the aggregate as failed; `rcf audit coverage --strict` runs second and its non-zero exit terminates the aggregate as failed; per-gate JSON reports at stable paths carry a fixed key set (gate, command, toolVersion, startedAt, endedAt, durationMs, exitCode, outcome, stdout, stderr); an aggregate report at `<reportDir>/pipeline.json` carries verdict, trigger, timing, runner metadata, and the ordered gates array; a missing required gate report is recorded as `outcome: missing` with a reason and flips the aggregate to `failed`; the suite continues past a failing gate to record every failure on one run; operator-visible failure summaries name the gate and the report path in the runner-log tail; the Node entry point invocation is identical locally and in CI; no CI-provider environment variable gates the entry point's control flow; the applied blueprint's source path carries one illustrative GitHub Actions workflow and a notes file mapping four points to alternate providers. Every bar is carried by ACs in the doc set, not by this README.
+
+## Known mechanism-reach gaps
+
+None at v1.0.0. Every AC on every story is bound to at least one TAC that the host project must realise, and every AC's `then` clause is runtime-observable in the deployed pipeline surface (per-gate JSON report inspection, aggregate JSON report inspection, source-tree grep for CI-provider environment reads, workflow-file inspection under the applied blueprint's source path). The mechanism-reach principle from the authoring standard section 7 is satisfied at ship: a project that applies this blueprint and does not realise a TAC leaves an unresolved `tacIds` reference on the story that `rcf define validate` and `rcf audit coverage` refuse. The one operational responsibility a project must own is the branch-protection or equivalent merge-policy configuration on the default branch that binds the pipeline job's aggregate exit to the merge criterion (AC-6101-2); that responsibility is stated as an AC observable on the platform's own configuration surface, not a smuggled runtime probe.

package/blueprints/ci-pipeline/assets/ci-provider-examples/github-actions.yml

@@ -0,0 +1,61 @@
+# Illustrative GitHub Actions workflow for the ci-pipeline blueprint.
+# Copy this file into the host project as `.github/workflows/rcf-ci.yml`
+# and adjust the `node-version`, package-manager setup, and entry-point
+# path to match the project's realised gate runner (TAC-701).
+#
+# The workflow runs one CI-provider-neutral Node entry point that
+# invokes `rcf define validate` and `rcf audit coverage --strict`,
+# writes per-gate and aggregate JSON reports under `.rcf/reports/ci/`,
+# and uploads the report directory as a workflow artefact for
+# downstream readers.
+#
+# See `guide/ci-pipeline.md` (four-point mapping) for translating
+# this workflow to GitLab CI, CircleCI, Buildkite, or Jenkins.
+
+name: rcf-ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  rcf-gates:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+
+      - name: setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # Single-line invocation of the project's realised gate runner.
+      # The runner spawns `rcf define validate` then `rcf audit coverage --strict`,
+      # writes `.rcf/reports/ci/<gate>.json` per gate, and writes
+      # `.rcf/reports/ci/pipeline.json` as the aggregate. Its exit code
+      # is the pipeline's aggregate exit code.
+      - name: run rcf ci gates
+        run: node scripts/rcf-ci.js
+
+      - name: upload rcf ci reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: rcf-ci-reports
+          path: .rcf/reports/ci/
+          if-no-files-found: warn
+          retention-days: 30

package/blueprints/ci-pipeline/assets/ci-provider-examples/notes.md

@@ -0,0 +1,50 @@
+# Wiring the gate runner on alternate CI providers
+
+The blueprint ships one illustrative provider example (GitHub Actions, `github-actions.yml`). Every mainstream provider hosts the same pipeline by translating four points and keeping the Node entry-point invocation unchanged. These notes are read alongside `guide/ci-pipeline.md`, not instead of it.
+
+## The four mapping points
+
+1. Job trigger. Fire the job on a push to the default branch AND on every pull request opened, synchronised, or reopened against the default branch.
+2. Node setup. Install Node 24 or later on the runner.
+3. Package-manager setup and install. Install the project's dependencies with the frozen-lockfile discipline of whichever manager the project uses.
+4. Node entry-point invocation and artefact upload. Run `node <path>` (or a package-manager script that resolves to the same); upload the configured report directory as a run artefact for downstream readers.
+
+The blueprint does not ship provider-specific configuration files for the providers below at v1.0.0. A project hand-authors the first three points in the provider's own runner language and keeps the fourth unchanged.
+
+## GitLab CI (`.gitlab-ci.yml`)
+
+- Trigger: `rules:` with `if: $CI_COMMIT_BRANCH == "main"` for the push half, `if: $CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "main"` for the merge-request half.
+- Node setup: use a `node:24` image or install through the runner's setup hook.
+- Install: `pnpm install --frozen-lockfile` (or equivalent).
+- Invoke: `node scripts/rcf-ci.js`.
+- Artefact upload: `artifacts: { when: always, paths: [.rcf/reports/ci/] }`.
+
+## CircleCI (`.circleci/config.yml`)
+
+- Trigger: `workflows:` with `filters: { branches: { only: [main] } }` for the push half; pull-request contexts are handled through CircleCI's GitHub integration or via the `pull_request_number` pipeline parameter.
+- Node setup: `cimg/node:24.19` or the `node/install` orb command.
+- Install: `pnpm install --frozen-lockfile`.
+- Invoke: `node scripts/rcf-ci.js`.
+- Artefact upload: `store_artifacts: { path: .rcf/reports/ci }`.
+
+## Buildkite (`.buildkite/pipeline.yml`)
+
+- Trigger: pipeline-level branch conditions or per-step `branches: main` with additional pull-request-only steps triggered through Buildkite's GitHub integration.
+- Node setup: install Node 24 in the queue's setup hook or use a Docker plugin (`docker#v5.0.0`).
+- Install: `pnpm install --frozen-lockfile`.
+- Invoke: `node scripts/rcf-ci.js`.
+- Artefact upload: `artifact_paths: [".rcf/reports/ci/**"]`.
+
+## Jenkins (declarative pipeline)
+
+- Trigger: `triggers { githubPush() }` plus a multibranch pipeline configured to build pull requests against the default branch.
+- Node setup: install Node 24 via `tools { nodejs '24' }` or provision the agent with Node preinstalled.
+- Install: `sh 'pnpm install --frozen-lockfile'`.
+- Invoke: `sh 'node scripts/rcf-ci.js'`.
+- Artefact upload: `archiveArtifacts artifacts: '.rcf/reports/ci/**', allowEmptyArchive: true`.
+
+## Cross-provider notes
+
+- The Node entry-point path is the same on every provider. A project that changes providers rewrites its trigger, setup, install, and artefact-upload steps; the entry-point step is unchanged.
+- The report directory (default `.rcf/reports/ci/`) is the same on every provider. Downstream readers do not need per-provider knowledge to pick up the aggregate report.
+- The tool-version pin (which `rcf` version to run) is the project's decision. The runner records the installed version on every per-gate report's `toolVersion` field; a mismatch across two runs is visible in the reports without re-running the gate.

package/blueprints/ci-pipeline/assets/report-samples/per-gate.json

@@ -0,0 +1,12 @@
+{
+  "gate": "validate",
+  "command": ["rcf", "validate"],
+  "toolVersion": "0.7.4",
+  "startedAt": "2026-08-24T10:15:03.221Z",
+  "endedAt": "2026-08-24T10:15:04.891Z",
+  "durationMs": 1670,
+  "exitCode": 0,
+  "outcome": "passed",
+  "stdout": "[rcf] validate: 0 issue(s) across 47 document(s)\n",
+  "stderr": ""
+}

package/blueprints/ci-pipeline/assets/report-samples/pipeline.json

@@ -0,0 +1,28 @@
+{
+  "verdict": "failed",
+  "trigger": "pull_request",
+  "startedAt": "2026-08-24T10:15:03.100Z",
+  "endedAt": "2026-08-24T10:15:12.045Z",
+  "durationMs": 8945,
+  "runner": {
+    "entryPoint": "scripts/rcf-ci.js",
+    "environment": {
+      "provider": "github-actions",
+      "runId": "8214332015"
+    }
+  },
+  "gates": [
+    {
+      "gate": "validate",
+      "outcome": "passed",
+      "durationMs": 1670,
+      "reportPath": "validate.json"
+    },
+    {
+      "gate": "coverage-strict",
+      "outcome": "failed",
+      "durationMs": 7220,
+      "reportPath": "coverage-strict.json"
+    }
+  ]
+}

package/blueprints/ci-pipeline/blueprint.json

@@ -0,0 +1,46 @@
+{
+  "slug": "ci-pipeline",
+  "version": "1.0.0",
+  "category": "delivery",
+  "contributions": [
+    { "id": "ci-pipeline-REQ-001", "kind": "req", "path": "requirements/ci-pipeline-req-001.json" },
+    { "id": "ci-pipeline-REQ-002", "kind": "req", "path": "requirements/ci-pipeline-req-002.json" },
+    { "id": "ci-pipeline-REQ-003", "kind": "req", "path": "requirements/ci-pipeline-req-003.json" },
+    { "id": "ci-pipeline-REQ-004", "kind": "req", "path": "requirements/ci-pipeline-req-004.json" },
+    { "id": "ci-pipeline-REQ-005", "kind": "req", "path": "requirements/ci-pipeline-req-005.json" },
+    { "id": "ci-pipeline-REQ-006", "kind": "req", "path": "requirements/ci-pipeline-req-006.json" },
+    { "id": "ci-pipeline-REQ-007", "kind": "req", "path": "requirements/ci-pipeline-req-007.json" },
+    { "id": "ci-pipeline-REQ-008", "kind": "req", "path": "requirements/ci-pipeline-req-008.json" },
+    { "id": "ci-pipeline-REQ-009", "kind": "req", "path": "requirements/ci-pipeline-req-009.json" },
+    { "id": "ci-pipeline-REQ-010", "kind": "req", "path": "requirements/ci-pipeline-req-010.json" },
+    { "id": "ci-pipeline-US-6101", "kind": "us", "path": "user-stories/ci-pipeline-us-6101.json" },
+    { "id": "ci-pipeline-US-6102", "kind": "us", "path": "user-stories/ci-pipeline-us-6102.json" },
+    { "id": "ci-pipeline-US-6103", "kind": "us", "path": "user-stories/ci-pipeline-us-6103.json" },
+    { "id": "ci-pipeline-US-6104", "kind": "us", "path": "user-stories/ci-pipeline-us-6104.json" },
+    { "id": "ci-pipeline-US-6105", "kind": "us", "path": "user-stories/ci-pipeline-us-6105.json" },
+    { "id": "ci-pipeline-US-6106", "kind": "us", "path": "user-stories/ci-pipeline-us-6106.json" },
+    { "id": "ci-pipeline-US-6107", "kind": "us", "path": "user-stories/ci-pipeline-us-6107.json" },
+    { "id": "ci-pipeline-US-6108", "kind": "us", "path": "user-stories/ci-pipeline-us-6108.json" },
+    { "id": "ci-pipeline-US-6109", "kind": "us", "path": "user-stories/ci-pipeline-us-6109.json" },
+    { "id": "ci-pipeline-US-6110", "kind": "us", "path": "user-stories/ci-pipeline-us-6110.json" },
+    { "id": "TAC-701-ci-pipeline-gate-runner", "kind": "tac", "path": "tacs/tac-701-ci-pipeline-gate-runner.json" },
+    { "id": "TAC-702-ci-pipeline-gate-report", "kind": "tac", "path": "tacs/tac-702-ci-pipeline-gate-report.json" },
+    { "id": "TAC-703-ci-pipeline-aggregate-report", "kind": "tac", "path": "tacs/tac-703-ci-pipeline-aggregate-report.json" },
+    {
+      "id": "ADR-701-ci-pipeline-ci-gates",
+      "kind": "adr",
+      "path": "adrs/adr-701-ci-pipeline-ci-gates.json",
+      "scope": "global",
+      "topic": "ciGates"
+    },
+    {
+      "id": "ADR-702-ci-pipeline-strict-coverage-gate",
+      "kind": "adr",
+      "path": "adrs/adr-702-ci-pipeline-strict-coverage-gate.json",
+      "scope": "global",
+      "topic": "strictCoverageGate"
+    },
+    { "id": "ADR-703-ci-pipeline-node-only-runner", "kind": "adr", "path": "adrs/adr-703-ci-pipeline-node-only-runner.json" },
+    { "id": "ADR-704-ci-pipeline-report-shape", "kind": "adr", "path": "adrs/adr-704-ci-pipeline-report-shape.json" }
+  ]
+}