rcf-lite 0.12.0 → 0.13.0

package/blueprints/security-secrets-management/contributions/tacs/tac-905-security-secrets-management-agent-cli.json

@@ -0,0 +1,59 @@
+{
+  "tacId": "TAC-905-security-secrets-management-agent-cli",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Secrets CLI (agent-safe surface)",
+  "purpose": "The command-line surface every agent, operator, and CI job uses when working with secrets. Keeps secret material off argv, off logs, off structured output, and off terminal echoes captured by an agent transcript. Its structured output surface is also the field contract the optional admin-UI Secrets page renders against.",
+  "responsibilities": [
+    "Expose `list`, `read <name>`, `put <name>`, `reflect`, `rotate <name>`, `verify` verbs; each verb enforces the value-off-argv and value-off-log rules regardless of how it is invoked (AC-8105-1, AC-8105-2).",
+    "Refuse to print a secret value to a TTY without an explicit `--show` flag; the flag is honoured only when stdout is a TTY, deliberately excluding scripted transcript capture (AC-8105-1).",
+    "Refuse a value passed as a positional argument or as an option value with `SECRETS_VALUE_ON_ARGV_REFUSED`; require `put` to read the value from stdin (AC-8105-2).",
+    "Emit a structured `--json` and `--report` output surface whose entries carry `name`, `environment`, `owner`, `rotationDays`, `lastRotatedAt`, and `required`; never a `value` or a hash of it (AC-8105-3, AC-8110-2).",
+    "Wrap the CLI's own logger in a redactor that replaces any bytes matching a resolved secret value with a fixed-length placeholder before writing to any log sink (AC-8105-4).",
+    "Serve as the field contract for the optional admin-UI Secrets page: the page renders the same field set the `--json` surface carries and adds no value-carrying cell (AC-8110-2)."
+  ],
+  "internalStructure": "One CLI module with per-verb handlers. Composes TAC-901 (client), TAC-902 (manifest), TAC-903 (reflector), TAC-904 (rotation gate). A shared redactor middleware wraps every log-emit point; a shared TTY/argv guard middleware runs before every verb's handler.",
+  "interfaces": [
+    {
+      "name": "process",
+      "kind": "read-api",
+      "description": "The host process's argv, stdin, stdout, stderr, and env; the CLI reads argv and stdin, writes to stdout and stderr, and reads a small allow-listed env slice (audit principal id, active environment)."
+    },
+    {
+      "name": "logSink",
+      "kind": "callback",
+      "description": "The CLI's own log destination (stderr by default; a file when `--log-file` is set); every write passes through the redactor."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Secrets Manager client",
+      "kind": "tac",
+      "tacId": "TAC-901-security-secrets-management-manager-client",
+      "description": "Underlying reader for `read`, `list`, `verify`."
+    },
+    {
+      "name": "Secrets Manifest",
+      "kind": "tac",
+      "tacId": "TAC-902-security-secrets-management-manifest",
+      "description": "Source of the metadata `list --json` emits."
+    },
+    {
+      "name": "Env reflector",
+      "kind": "tac",
+      "tacId": "TAC-903-security-secrets-management-env-reflector",
+      "description": "Backing implementation for the `reflect` verb."
+    },
+    {
+      "name": "Rotation gate",
+      "kind": "tac",
+      "tacId": "TAC-904-security-secrets-management-rotation-gate",
+      "description": "Backing implementation for the `verify` verb when scoped to rotation checks."
+    }
+  ],
+  "tradeoffs": "The `--show` flag gated on a TTY closes the common agent-transcript leak but does not stop a human copying a value from their own terminal into a screenshot; nothing at the CLI layer can. Projects that need a harder gate override with a project-level ADR requiring an out-of-band value delivery (a browser paste-buffer with clipboard auto-clear, a hardware-token flow), and this CLI becomes read-only-metadata plus the piped-stdin `put`.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,46 @@
+{
+  "usId": "security-secrets-management-US-8101",
+  "prdId": "PRD-001",
+  "reqId": "security-secrets-management-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The repo-root manifest is the sole declaration of every secret the project needs",
+  "asA": "operator reading a fresh repo",
+  "iWant": "one file at the repo root that lists every secret the project depends on",
+  "soThat": "I can see the dependency graph without grepping every deployable",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-8101-1",
+      "description": "A file `secrets.yaml` exists at the repo root and parses as YAML into an object with a `secrets` array; each entry carries a logical name, a per-environment path map, an owner, a rotationDays integer, and a required boolean.",
+      "given": "a fresh clone of the repo",
+      "when": "a manifest loader runs against `secrets.yaml`",
+      "then": "the loader returns a manifest object whose `secrets` array is non-empty and every entry has the fields `name`, `paths`, `owner`, `rotationDays`, `required`; no entry carries a `value` field",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-8101-2",
+      "description": "The Secrets Manager client refuses to serve a name that is not declared in the manifest.",
+      "given": "a running process whose declared slice does not include the logical name `unknown-key`",
+      "when": "the process calls `secretsClient.get('unknown-key')`",
+      "then": "the call throws a stable-coded `SECRETS_UNDECLARED_NAME` error naming `unknown-key` and no vendor call is made",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-8101-3",
+      "description": "A CI gate scans the source tree for code that reads a secret shape (an env-var name that appears in the manifest, or a call to a vendor SDK directly) and fails when a used name is not declared in the manifest or when a vendor SDK is imported outside the Secrets Manager module.",
+      "given": "a change adds `process.env.THIRD_PARTY_TOKEN` to a source file and does not add `THIRD_PARTY_TOKEN` to the manifest",
+      "when": "the CI gate runs on the change",
+      "then": "the run fails with a stable-coded `SECRETS_MANIFEST_MISS` error naming the offending source path and the missing manifest name",
+      "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-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`), ci-pipeline (`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, ci-pipeline, 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` |
+| 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` |
+
+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.