rcf-lite 0.12.0 → 0.14.0

package/blueprints/security-secrets-management/contributions/user-stories/security-secrets-management-us-8102.json

@@ -0,0 +1,45 @@
+{
+  "usId": "security-secrets-management-US-8102",
+  "prdId": "PRD-001",
+  "reqId": "security-secrets-management-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "One vendor-agnostic client is the sole reader of secret material",
+  "asA": "engineer reading the project",
+  "iWant": "a single named module every call site imports to read secrets",
+  "soThat": "changing vendors is a one-module change and duplicate read paths cannot drift",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-8102-1",
+      "description": "The project exposes one Secrets Manager module whose public surface is `get(name)`, `getRequired(name)`, `list()`, and `refresh()`; the module is the only importer of the vendor binding on the boundary.",
+      "given": "a project that has applied the blueprint and realised TAC-901",
+      "when": "the source tree is scanned for imports of the vendor SDK identifier or of any additional secrets-reader module",
+      "then": "the only source file that imports the vendor SDK is the Secrets Manager module and no other module names an alternative secrets-reader import",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-8102-2",
+      "description": "`getRequired(name)` on an absent required secret throws a stable-coded error naming the logical name and the active environment.",
+      "given": "a manifest entry `X` marked `required: true` with no resolvable per-environment path in the active environment",
+      "when": "a caller invokes `secretsClient.getRequired('X')`",
+      "then": "the call throws a `SECRETS_REQUIRED_ABSENT` error whose message names `X` and the active environment string, and no secret value is served",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-8102-3",
+      "description": "`refresh()` re-reads exactly the declared slice from the vendor and updates the in-memory cache atomically; a caller invoking `get` mid-refresh sees either the previous full slice or the new full slice, never a mix.",
+      "given": "a running process holding a cached slice",
+      "when": "a `refresh()` call runs while a concurrent `get(name)` call is in flight",
+      "then": "the concurrent `get(name)` returns either the pre-refresh value or the post-refresh value; it never returns null when both refresh states have a value, and it never returns a mixed-slice combination across two names",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-901-security-secrets-management-manager-client"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-secrets-management/contributions/user-stories/security-secrets-management-us-8103.json

@@ -0,0 +1,37 @@
+{
+  "usId": "security-secrets-management-US-8103",
+  "prdId": "PRD-001",
+  "reqId": "security-secrets-management-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Each deployable can only read the secrets its slice declares",
+  "asA": "security-aware operator",
+  "iWant": "each process to be able to read only the secrets its manifest slice names",
+  "soThat": "the blast radius of a compromise is bounded by that slice, not by the whole project",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-8103-1",
+      "description": "A process whose declared slice is `['A', 'B']` serves values for `A` and `B` and refuses `C` even when `C` is a legal manifest entry for a different deployable.",
+      "given": "a running process with declared slice `['A', 'B']` and a manifest that also declares `C` for a different deployable",
+      "when": "the process calls `secretsClient.get('A')`, `secretsClient.get('B')`, then `secretsClient.get('C')`",
+      "then": "the `A` and `B` calls return their values, and the `C` call throws `SECRETS_OUT_OF_SLICE` naming `C` and the current deployable id, with no vendor call made for `C`",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-8103-2",
+      "description": "The vendor credentials the process uses at boot are scoped to its slice; a direct vendor-side probe with those credentials for an out-of-slice path returns the vendor's deny response.",
+      "given": "a process's vendor credentials materialised at boot and a manifest entry `C` for a path that is not in the process's slice",
+      "when": "a probe using those credentials reads directly against the vendor for path `C`",
+      "then": "the vendor responds with its permission-denied outcome for those credentials on that path",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-901-security-secrets-management-manager-client",
+    "TAC-902-security-secrets-management-manifest"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-secrets-management/contributions/user-stories/security-secrets-management-us-8104.json

@@ -0,0 +1,45 @@
+{
+  "usId": "security-secrets-management-US-8104",
+  "prdId": "PRD-001",
+  "reqId": "security-secrets-management-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Every secret access lands on an audit sink with metadata and never a value",
+  "asA": "operator investigating an incident",
+  "iWant": "a durable per-access audit trail that never carries the secret bytes",
+  "soThat": "I can answer who read what and when without the log store becoming a secrets store",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-8104-1",
+      "description": "A successful `get(name)` emits exactly one audit event carrying `name`, `path`, `environment`, `principal`, `outcome: 'served'`, and `at`; no field on the event contains the secret value or any substring of it.",
+      "given": "a running process that has authorised the audit sink and holds the value V for logical name `N`",
+      "when": "the process calls `secretsClient.get('N')` and reads the audit sink for events matching that call",
+      "then": "exactly one event is emitted, its keys are the enumerated set above, and byte-equality checks against V return no match on any field value",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-8104-2",
+      "description": "A refused access emits one audit event with the correct refusal outcome and no value bytes.",
+      "given": "a running process whose declared slice does not include `C`",
+      "when": "the process calls `secretsClient.get('C')` and the sink is read",
+      "then": "one event is emitted with `outcome: 'refusedOutOfSlice'`, name `C`, and no field contains vendor path metadata beyond what the manifest already declares",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-8104-3",
+      "description": "The audit sink is pluggable through a project-supplied adapter; the blueprint's client uses a stub in-memory sink in tests and a project-supplied sink in production.",
+      "given": "a process wired against an in-memory audit adapter for tests",
+      "when": "the process runs its test suite covering successful and refused fetches",
+      "then": "the in-memory adapter accumulates exactly one event per fetch attempt and no vendor SDK is invoked for the audit path",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-901-security-secrets-management-manager-client"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-secrets-management/contributions/user-stories/security-secrets-management-us-8105.json

@@ -0,0 +1,55 @@
+{
+  "usId": "security-secrets-management-US-8105",
+  "prdId": "PRD-001",
+  "reqId": "security-secrets-management-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Agents work with secrets through a piped-stdin CLI, never through transcript-visible values",
+  "asA": "operator running a coding agent",
+  "iWant": "the CLI to keep secret values off the surfaces an agent workflow creates",
+  "soThat": "agent transcripts, tool logs, and workspace backups are safe to keep and share",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-8105-1",
+      "description": "A verb that produces a secret value writes it only to stdout as raw bytes intended for a piped consumer; running it with stdout on a terminal without `--show` refuses and prints an explanatory message that does not contain the value.",
+      "given": "a shell invocation `secrets read N` where stdout is a TTY and no `--show` flag is passed",
+      "when": "the command runs",
+      "then": "the exit code is non-zero, stderr names `SECRETS_TTY_WITHOUT_SHOW`, and stdout contains no bytes of the secret value for `N`",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-8105-2",
+      "description": "A verb that accepts a secret value reads it from stdin only; passing it as a command-line argument is refused with a stable code.",
+      "given": "a shell invocation `secrets put N V` where `V` is a positional argument",
+      "when": "the command runs",
+      "then": "the exit code is non-zero, stderr names `SECRETS_VALUE_ON_ARGV_REFUSED`, and no vendor write is issued",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-8105-3",
+      "description": "The CLI's structured output surface (`--json`, `--report`) never carries secret values; only names and metadata are emitted.",
+      "given": "an operator running `secrets list --json` in an environment where every declared secret resolves",
+      "when": "the JSON payload is inspected",
+      "then": "every top-level entry carries `name`, `environment`, `owner`, `rotationDays`, `lastRotatedAt`, and `required`; no entry contains a field whose value equals or byte-includes any resolved secret value",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-8105-4",
+      "description": "The CLI's own log stream (verbose, debug) refuses to emit a secret value even when a bug elsewhere hands it one; a value passed to the logger is redacted to a fixed-length placeholder before any bytes leave the process.",
+      "given": "a test that instruments the CLI logger with a captured value V that would have been mistakenly logged",
+      "when": "the CLI runs and the log capture is read back",
+      "then": "no captured log line contains V or any substring of length greater than the placeholder length, and every line in place carries the fixed placeholder token",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-905-security-secrets-management-agent-cli",
+    "TAC-901-security-secrets-management-manager-client"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-secrets-management/contributions/user-stories/security-secrets-management-us-8106.json

@@ -0,0 +1,46 @@
+{
+  "usId": "security-secrets-management-US-8106",
+  "prdId": "PRD-001",
+  "reqId": "security-secrets-management-REQ-006",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "`.env` is regenerated from the manifest on demand; the file is never authoritative",
+  "asA": "developer with local tooling that expects a `.env`",
+  "iWant": "a reflector command that fills `.env` from the manifest",
+  "soThat": "my local flow keeps working without the `.env` becoming the source of truth",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-8106-1",
+      "description": "Running the reflector writes a `.env` file at the repo root whose keys equal the manifest slice for the target process and whose values equal the current vendor-resolved values for the active environment; a subsequent invocation overwrites the file atomically.",
+      "given": "an operator who has authenticated to the vendor and passed a deployable id and active environment",
+      "when": "the operator runs `secrets reflect --deployable <id> --env <env>` and reads the resulting `.env`",
+      "then": "the file's parsed key set equals the declared slice for `<id>` and every value equals the vendor-resolved value for the active environment; a repeat run atomically replaces the file and no intermediate partial-write state is observable",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-8106-2",
+      "description": "The project's `.gitignore` at the repo root excludes `.env` (and any `.env.*` reflection variants declared for other environments) from version control.",
+      "given": "the repo's tracked files",
+      "when": "`git check-ignore .env` runs at the repo root",
+      "then": "the command reports `.env` as ignored and exits 0",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-8106-3",
+      "description": "The CI source-tree scan fails a change that reads `.env` directly at boot instead of going through the Secrets Manager client.",
+      "given": "a change that adds a call parsing `.env` (a `dotenv.config()`-shaped call outside the Secrets Manager module)",
+      "when": "the CI gate runs on the change",
+      "then": "the run fails with a stable-coded `SECRETS_DOTENV_DIRECT_READ` error naming the offending source path and directing the author to the Secrets Manager client",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-903-security-secrets-management-env-reflector",
+    "TAC-901-security-secrets-management-manager-client"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-secrets-management/contributions/user-stories/security-secrets-management-us-8107.json

@@ -0,0 +1,46 @@
+{
+  "usId": "security-secrets-management-US-8107",
+  "prdId": "PRD-001",
+  "reqId": "security-secrets-management-REQ-007",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The manifest declares the project's environment set once and enforces it thereafter",
+  "asA": "operator setting up the project",
+  "iWant": "the working agent to elicit our environment names once and record them in the manifest",
+  "soThat": "the environment shape is legible on-disk and boot resolution is unambiguous",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-8107-1",
+      "description": "The manifest carries a top-level `environments` array whose values are the operator-elicited environment names; every entry's `paths` object has exactly the same key set as `environments`.",
+      "given": "a manifest with `environments: ['dev', 'ci', 'live']` and an entry whose `paths` omits `ci`",
+      "when": "the manifest loader validates the file",
+      "then": "the loader rejects the manifest with a stable-coded `SECRETS_ENV_PATH_MISSING` error naming the entry and the missing environment string",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-8107-2",
+      "description": "The Secrets Manager client selects exactly one environment at boot from an unambiguous input; two ambiguous inputs (a set variable and a flag both provided with conflicting values) fails boot.",
+      "given": "a boot with the environment variable resolving to `dev` and a `--env live` flag also provided",
+      "when": "the client initialises",
+      "then": "boot fails with a stable-coded `SECRETS_ENV_AMBIGUOUS` error naming both inputs, and no vendor call is made",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-8107-3",
+      "description": "A required secret whose per-environment path is set to null or an empty string for the active environment fails boot.",
+      "given": "a manifest entry `X` with `required: true` and `paths.live` set to null, resolving in the `live` environment",
+      "when": "the process boots in `live`",
+      "then": "boot fails with `SECRETS_REQUIRED_ABSENT` naming `X` and `live`, and no listener binds to any port",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-902-security-secrets-management-manifest",
+    "TAC-901-security-secrets-management-manager-client"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-secrets-management/contributions/user-stories/security-secrets-management-us-8108.json

@@ -0,0 +1,45 @@
+{
+  "usId": "security-secrets-management-US-8108",
+  "prdId": "PRD-001",
+  "reqId": "security-secrets-management-REQ-008",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "A missing required secret fails boot loudly; a missing optional secret returns null",
+  "asA": "operator investigating a failed deploy",
+  "iWant": "the process to name the missing secret and stop, not stagger on",
+  "soThat": "diagnosis is one step and there is no half-alive state serving traffic",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-8108-1",
+      "description": "A boot with a required manifest entry unresolvable in the active environment aborts with a stable-coded error and does not open any listening port.",
+      "given": "a manifest entry `R` with `required: true` where the vendor returns not-found for the active environment path",
+      "when": "the process boots",
+      "then": "the process exits with a stable-coded `SECRETS_REQUIRED_ABSENT` error naming `R` and the active environment, and a subsequent port scan on the process's declared listen ports returns closed on every port",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-8108-2",
+      "description": "A boot with only optional manifest entries unresolvable proceeds and serves those names as null.",
+      "given": "a manifest entry `O` with `required: false` where the vendor returns not-found for the active environment",
+      "when": "the process boots and a caller invokes `secretsClient.get('O')`",
+      "then": "the process comes up normally, the call returns null, and no `SECRETS_REQUIRED_ABSENT` error is emitted",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-8108-3",
+      "description": "The client does not retry-on-loop for a required-absent secret at boot; the failure is single-shot.",
+      "given": "a required manifest entry that will never resolve",
+      "when": "boot runs against instrumented vendor code that counts read attempts for that entry",
+      "then": "the read is attempted once (plus any vendor-level automatic retry the SDK does internally within a single call), the process exits, and the read counter is one",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-901-security-secrets-management-manager-client"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-secrets-management/contributions/user-stories/security-secrets-management-us-8109.json

@@ -0,0 +1,46 @@
+{
+  "usId": "security-secrets-management-US-8109",
+  "prdId": "PRD-001",
+  "reqId": "security-secrets-management-REQ-009",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "CI refuses a merge when a secret is past its rotation budget",
+  "asA": "operator who set a rotation policy expecting it to hold",
+  "iWant": "CI to fail a change when a secret has aged past its rotation-days budget",
+  "soThat": "rotation cannot silently slip",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-8109-1",
+      "description": "The rotation gate compares each manifest entry's `rotationDays` against the vendor-reported `lastRotatedAt`; an entry with elapsed days greater than `rotationDays` fails the run with a stable-coded error naming the entry, environment, `lastRotatedAt`, and elapsed days.",
+      "given": "a manifest entry `S` with `rotationDays: 90` and a vendor-reported `lastRotatedAt` 120 days before the CI-run wall clock",
+      "when": "the rotation gate runs in CI",
+      "then": "CI fails with `SECRETS_ROTATION_EXPIRED` naming `S`, the environment, the `lastRotatedAt` value, and the number `120`",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-8109-2",
+      "description": "A required entry with no vendor-reported `lastRotatedAt` fails the gate; an optional entry with no `lastRotatedAt` fails the gate.",
+      "given": "a manifest entry `S` where the vendor returns no `lastRotatedAt` field for the active environment path",
+      "when": "the rotation gate runs",
+      "then": "CI fails with `SECRETS_ROTATION_UNKNOWN` naming `S` and the environment, whether `required` is true or false",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-8109-3",
+      "description": "An operator-authored override file with an expiry timestamp is honoured for a named entry until the expiry passes; the gate audits the override every time it applies.",
+      "given": "an override file naming entry `S` with an expiry six hours in the future",
+      "when": "the rotation gate runs against `S` past its rotation budget",
+      "then": "the run does not fail on `S`, and a `SECRETS_ROTATION_OVERRIDE_APPLIED` audit event is emitted naming `S`, the override author, the override expiry, and the wall-clock at gate time",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-904-security-secrets-management-rotation-gate",
+    "TAC-902-security-secrets-management-manifest"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-secrets-management/contributions/user-stories/security-secrets-management-us-8110.json

@@ -0,0 +1,45 @@
+{
+  "usId": "security-secrets-management-US-8110",
+  "prdId": "PRD-001",
+  "reqId": "security-secrets-management-REQ-010",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The operator picks one of three UI outcomes and the manifest records the choice",
+  "asA": "operator applying the blueprint",
+  "iWant": "an explicit choice about whether we get an operator-facing Secrets page and where it lives",
+  "soThat": "the project ends up with the UI it needs and nothing it does not",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-8110-1",
+      "description": "At apply the working agent records the operator's UI choice as one of `integrate`, `admin-spa`, or `none` on the manifest header field `uiIntegration.mode`.",
+      "given": "a fresh apply of the blueprint against a project with no `secrets.yaml`",
+      "when": "the working agent elicits the choice and writes the manifest",
+      "then": "the manifest's `uiIntegration.mode` string equals one of `integrate`, `admin-spa`, or `none` and no other value passes manifest validation",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-8110-2",
+      "description": "When mode is `integrate`, the deployed admin UI exposes a Secrets page whose surface matches TAC-905: a list keyed by name showing environment, owner, `lastRotatedAt`, and `rotationDays`; no cell on the page renders a secret value.",
+      "given": "a project with `uiIntegration.mode: 'integrate'` that has realised TAC-905",
+      "when": "the operator fetches the deployed Secrets page and inspects its rendered content",
+      "then": "every row carries the fields above and byte-equality checks against the vendor-resolved secret values return no match anywhere on the rendered page",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-8110-3",
+      "description": "When mode is `none`, no Secrets page is exposed anywhere in the deployed application; the CLI plus audit sink are the only operator surfaces the blueprint contributes.",
+      "given": "a project with `uiIntegration.mode: 'none'`",
+      "when": "the deployed application is scanned for a Secrets page under any admin path",
+      "then": "no path returns a page whose contents identify as the Secrets Management surface (no page metadata declaring it, no HTML fragment matching the TAC-905 shape)",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-905-security-secrets-management-agent-cli"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-secrets-management/docs/topics.md

@@ -0,0 +1,46 @@
+# security-secrets-management blueprint coordination vocabulary
+
+This file is the security-secrets-management half of 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 this blueprint contributes (exact strings)
+
+| Topic string | security-secrets-management contribution | Origin | Composition note |
+|---|---|---|---|
+| `secretsSource` | ADR-901-security-secrets-management-secrets-source | Minted here; pre-cleared as unclaimed against application-spa (`clientRouting`, `theming`, `clientState`, `errorEnvelope`, `authModel`), application-api-rest (`errorEnvelope`, `authModel`, `apiVersioning`, `logging`), security-auth-magic-link (`authModel`), persistence-data-sqlite (`persistenceStore`, `migrationDiscipline`), delivery-ci-workflows (`ciGates`, `strictCoverageGate`), observability-essentials (`healthProbes`, `readinessSemantics`, `statusPageContract`), and the hello-panel walkthrough exemplar (`operatorPanel`) | The one project-wide source of truth for secret material: a repo-root `secrets.yaml` manifest plus a vendor-agnostic Secrets Manager client. A composing blueprint that holds a different opinion on the secrets source (a vendor-committed opinionated blueprint, a config-server pattern, a plaintext-committed pattern for a public reference project) contributes its own scope:global ADR on this exact string and lets composition surface the pairing. Expected resolution: one project-level ADR that fixes the source shape and the vendor selection |
+
+The security-secrets-management blueprint claims one global topic. Every other contribution is scope-local (ADR-902 through ADR-905 name the default vendor, the agent access discipline, the `.env` reflection posture, and the rotation-and-audit posture without contributing global topics; a composing blueprint that holds a different opinion on any of them authors its own project-level ADR if it wants to override).
+
+Rules for new topics (inherited from the application-spa, application-api-rest, security-auth-magic-link, persistence-data-sqlite, delivery-ci-workflows, and observability vocabularies, restated as law): lower camel case, one concept per topic, no version suffixes. A topic names the decision area, not the chosen answer. Do not mint variants of existing strings (`secrets`, `secretsStore`, `vault`, `secretsVendor`, `credentialsSource` are all wrong when `secretsSource` already exists).
+
+## Id number bands (registry bootstrap)
+
+AC ids (and therefore US numeric ids, which anchor them) are NOT namespaced by the 0.4.4 schema grammar; the band allocation IS the AC-collision enforcement mechanism. Composing blueprints take a fresh band rather than proposing namespaced AC ids. Band allocation is ratified policy (2026-08-19); this table is the shared registry-bootstrap replicated across every shipped and forthcoming blueprint's `docs/topics.md` until a mechanism-side central registry lands (v1.1 candidate).
+
+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` |
+| delivery-ci-workflows | 6101-6899 | 7xx | shipped v2.0.0 (renamed from ci-pipeline) | `ciGates`, `strictCoverageGate`, `releaseArtefacts` |
+| 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` |
+
+US 8101-8110 sit at the LOW end of the 8101-8899 band on purpose. A project-side story that mechanically derives from a security-secrets-management REQ id into the number `8110` would collide against security-secrets-management-US-8110 in this package; the band leaves headroom at the HIGH end (US 8181-8899) so a project's own stories anchored to security-secrets-management REQs can allocate without conflict. The watchpost run4 lesson applies here too.
+
+## Shared expectations for future composing blueprints
+
+- Reuse `secretsSource` exactly as spelled here when your blueprint holds an opinion on the project's secrets source-of-truth model; contribute your own scope:global ADR on that string and let composition surface the pairing. A vendor-committed opinionated blueprint (a Vault-specific blueprint, an AWS Secrets Manager blueprint, a Doppler blueprint) will conflict here by design and expect a project-level ADR resolution.
+- Vendor choice sits at ADR-902 (scope-local) by design: the contract is at ADR-901, the default is at ADR-902. A composing blueprint that wants a different DEFAULT vendor without changing the contract does not conflict on `secretsSource`; the operator supersedes ADR-902 with a project-level ADR and swaps the vendor adapter.
+- Agent access discipline (ADR-903), `.env` reflection posture (ADR-904), and rotation-and-audit posture (ADR-905) are scope-local. A composing blueprint that holds an opinion on any of them authors its own project-level ADR; none of them are minted as globals because the space of legitimate variations is smaller than the space of legitimate `secretsSource` variations.
+- Global topics that plausibly belong to a future blueprint and are NOT claimed by any shipped blueprint: `messageSerialisation` and `deliverySemantics` (a message-consumer blueprint's natural globals), `caching` (unclaimed by every shipped blueprint), `metricsExport` and `tracingProtocol` (natural globals for a metrics or tracing blueprint). Define any of these in your own package's topics doc, in this file's format, and consider whether the band-registry table above needs your slug added.

package/blueprints/security-secrets-management/guide/security-secrets-management.md

@@ -0,0 +1,68 @@
+# Security secrets management blueprint guide
+
+## What it is
+
+A default secrets-management floor for small greenfield rcf-lite projects. The blueprint contributes the WHAT of a secrets pattern: how the project declares what secrets exist, how one client is the sole reader of every value, how each deployable is restricted to its own slice, how every access is audited, how coding agents work with values without leaking them into transcripts and logs, how `.env` sits at the surface as an ephemeral projection rather than the source of truth, how environment shape is elicited from the operator, how rotation is gated at CI, and how an operator-facing Secrets page is offered as a three-way elicited choice.
+
+Concretely, the blueprint ships ten requirements, ten user stories (thirty acceptance criteria), five architecture components, and five architecture decision records. One ADR is `scope: global` on the `secretsSource` topic; the other four are scope-local operational ADRs (default vendor, agent access discipline, `.env` reflection posture, rotation-and-audit posture) that a composing blueprint does not conflict with by default.
+
+## What it is not
+
+Not a vendor SDK. The default vendor named in ADR-902 is SOPS with age keys, chosen for the zero-infrastructure floor the rcf-lite tier expects. Larger deployments supersede ADR-902 with a project-level ADR and swap the vendor adapter for Vault, a cloud secrets manager, or a hosted third-party service; the ADR-901 contract stays intact.
+
+Not an authorisation model. The blueprint governs READ of secret material and the audit trail of that read; who is allowed to trigger a rotation, who sees the admin-UI Secrets page, and who owns which secret at the operational level are project-side authorisation concerns that layer above the audit sink.
+
+Not a rotation orchestrator. The blueprint gates on rotation age at CI, it does not itself run the rotation. Running a rotation is a project-authored procedure the vendor's own tooling supports (SOPS re-encrypt, Vault's rotate endpoint, a cloud provider's rotation trigger); the blueprint's rotation gate then registers the fresh `lastRotatedAt` next time it runs.
+
+Not a UI framework. When `uiIntegration.mode` is `integrate`, the field contract for the Secrets page is fixed (TAC-905's structured output surface) but the page implementation lives in the host project's admin UI. A future admin-spa blueprint (unshipped at v1.0.0, promotion signal: the third project asks for a self-contained admin surface that hosts this page alongside others) will cover the standalone case.
+
+Not a config manager. Non-secret configuration (feature flags, tunable thresholds, endpoint URLs that are not sensitive) sits outside this blueprint; the manifest is for secret material only. A project that wants a unified config surface authors that on top; it does not belong here.
+
+## When to reach for it
+
+Reach for the security-secrets-management blueprint when:
+
+- The project depends on secret material of any kind (third-party API keys, database credentials, signing keys, session salts, TLS keys) and there is no single source of truth for what secrets exist.
+- Multiple deployables share a secret pool and least-privilege slicing is the intended posture rather than a wishful comment in a README.
+- Coding agents (Claude, Cursor, Copilot workflows, in-house LLM-driven scripts) are part of the operator's day and secret material must not land in the surfaces those workflows create.
+- Rotation is a real policy rather than a document nobody reads; CI is the intended enforcement layer.
+- The project is a small greenfield rcf-lite deployment (single deployable or a small deployable fleet, one small team or one solo operator, no ops team standing by) where a zero-infrastructure secrets story is a feature.
+
+## When it does not fit
+
+Do not reach for the security-secrets-management blueprint when:
+
+- The project's secret pool is genuinely trivial (one API key, one deployable, one operator) and running a manifest plus a CI gate is more machinery than the actual risk warrants. A lightweight `.env` and a rotation reminder on a calendar is honestly the right shape at that scale; this blueprint's audit-and-slice discipline is overkill.
+- The project has a hard corporate mandate for a specific hosted secrets vendor and there is no useful default for day one because everything already lives in that vendor. Apply the blueprint anyway if you want the ADR-901 contract, but expect to supersede ADR-902 with a project-level ADR at apply time.
+- Compliance requires an audit stream shape different from the one ADR-905 fixes (a specific SIEM schema, a regulator-mandated field set). The blueprint fixes the SHAPE of the audit events; a project with a stricter schema supersedes ADR-905 with a project-level ADR that names the target schema and the mapping.
+- The deploy target has no persistent filesystem for the SOPS-with-age default to live on and no working alternative vendor. The default vendor assumes a stable path the encrypted files survive at; a project without that assumption picks a different vendor (a hosted service is the natural fit) and supersedes ADR-902 accordingly.
+
+An earlier design pass scoped a Vault-first blueprint (candidate name `secrets-vault`). The blueprint at v1.0.0 does not lead with Vault because the container-plus-server cost is disproportionate for the rcf-lite tier this blueprint targets. Vault remains the reference open-source promotion path for projects with dedicated ops capacity, and the blueprint's contract composes cleanly with a Vault vendor adapter; the promotion is a project-level ADR supersede on ADR-902 and an adapter swap.
+
+## What a good outcome looks like
+
+A project applies the blueprint on a fresh tree, elicits its environment set (say `dev`, `ci`, `live`), declares its deployables and their per-deployable secret slices in `secrets.yaml`, chooses one of the three UI outcomes (`integrate`, `admin-spa`, `none`), realises the five TACs in project-authored FBSes with the default SOPS-with-age vendor adapter, and lands on a deployed application where:
+
+- Every runtime path that reads a secret imports the Secrets Manager client; nothing else touches the vendor SDK. A source-tree scan confirms the boundary.
+- The `secrets.yaml` at the repo root is the file the operator reads to see what secrets the project depends on; adding a new secret is a two-step change (add the manifest entry, then commit an encrypted value file or configure the vendor path).
+- A required secret missing in `live` fails boot with a stable-coded error naming the logical name and the environment; the operator diagnoses in one step.
+- A coding agent that needs to wire a secret into a starting process runs `secrets read N | consumer-tool` and the value never lands in the agent's transcript, its tool log, or a scratch file on the working tree.
+- A developer laptop `.env` exists because the developer ran `secrets reflect --deployable local-api --env dev`; deleting the file and re-running the reflector produces an identical file; the file is gitignored and its stale-and-regenerable status is visible in the workflow.
+- The rotation gate runs on every CI change; a secret past its `rotationDays` budget fails the run with a naming error the author can act on immediately; a legitimate mid-rotation override is authored with an expiry timestamp and every application of it is audited.
+- The audit stream contains every fetch attempt with `name`, `path`, `environment`, `principal`, `outcome`, and `at`; a byte-equality scan against every resolved secret value finds no match anywhere on the stream.
+- When the operator picked `integrate`, the admin UI's Secrets page renders name, environment, owner, `lastRotatedAt`, and `rotationDays` per row; no cell renders a secret value. When the operator picked `none`, no Secrets page exists anywhere on the deployed application; the CLI plus the audit stream are the whole story.
+
+## Operator decisions that remain open after apply
+
+- Vendor choice (SOPS+age default, or a superseding project-level ADR selecting Vault, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, Doppler, Infisical, or a project-authored adapter). Blueprint owns the contract on both sides of the boundary; project owns the vendor.
+- Environment set (`dev`/`ci`/`live` common default; project-specific names supported). Blueprint owns the enforcement that the manifest and the boot input agree; project owns the names.
+- Deployable-to-slice map (which deployable reads which secrets). Blueprint owns the least-privilege enforcement; project owns the split.
+- UI integration outcome (`integrate`, `admin-spa`, `none`). Blueprint owns the field contract for the `integrate` outcome; project owns the page implementation and the admin UI it lives in.
+- Rotation-days budgets per entry (a small budget for high-turnover keys, a larger budget for session salts). Blueprint owns the CI gate that enforces the budget; project owns the numbers.
+- Rotation override policy (who is allowed to author an override, how long an override may last, what the audit review cadence is). Blueprint owns that overrides carry an `expiresAt` and are audited every time; project owns the human process around them.
+- Audit sink implementation (where the audit events land: a local file, a SIEM, a data warehouse, a project's own event bus). Blueprint owns the event shape; project owns the shipper.
+- Secret owners (who is on the hook when an entry expires or an incident touches its blast radius). Blueprint owns that the manifest carries an `owner` field per entry; project owns the roster.
+
+## Cost-honesty paragraph
+
+Shipping this doc set costs the project the following. Every new secret is now a manifest change and a vendor-side configuration change instead of a stray environment variable; the discipline is intentional and adds a small friction to prototype-shaped work. The default SOPS-with-age vendor requires every developer laptop and every CI runner and every deploy host to hold an age key; losing every copy is a recover-by-rewrite problem for a pre-launch project and a recover-by-re-issue problem thereafter. The rotation gate fails CI on real drift; a project that wants faster merges buys them by rotating on cadence or by keeping the override discipline honest, neither is free. The audit sink is a stream the project now maintains; wiring it to a real sink (a SIEM, a data warehouse) is a project cost the blueprint does not carry. The three-way UI choice keeps a project without a UI honest, but a project that later wants one is a real build task rather than a config flip. The blueprint says nothing about authorisation, about the vendor's own rotation orchestration, about SIEM schemas, or about compliance reporting; a project that needs any of those spends its own build cycles on them and this blueprint does not save it any work there.