rcf-lite 0.12.0 → 0.13.0

package/blueprints/security-secrets-management/contributions/adrs/adr-901-security-secrets-management-secrets-source.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-901-security-secrets-management-secrets-source",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "A vendor-agnostic Secrets Manager, driven by a repo-root manifest, is the project's single source of truth for secret material",
+  "context": "Every non-trivial project depends on secret material: API keys for third-party vendors, database passwords, signing keys, session salts. The failure modes accumulate quietly: dependency shape lives in whichever file happened to read it, rotation policies are unenforced, laptop-local `.env` files diverge from the deployed environment, agent workflows echo values into transcripts that persist forever. A single source-of-truth model addresses the root cause: one manifest, one client, one audit stream, one boundary the vendor lives behind. This topic is scoped as a project-level global because a composing blueprint that holds a different opinion about the secrets source (a vendor-specific opinionated blueprint, a config-server pattern, a plaintext-committed pattern for a public reference project) needs to conflict here and be resolved by the operator.",
+  "decision": "The project's secrets source is a Secrets Manager client (TAC-901) reading a repo-root manifest (`secrets.yaml`, TAC-902) that declares every secret by name, per-environment path, owner, rotation-days budget, and required-or-optional. Values live only in the vendor the client resolves against; the manifest carries names and metadata only. Every runtime path that reads a secret value imports the Secrets Manager module and no other; every CI path that gates on secret age or shape reads the manifest and no other. The vendor is pluggable; the interface is not. The default vendor is named in ADR-902; alternatives supersede this ADR at the project level.",
+  "consequences": "One place to change vendors, one place to audit, one place to enforce least-privilege. The manifest becomes a piece of documentation the project maintains as part of its normal change flow, which is the intended cost. Rotation and access-audit surfaces exist because the client is the sole entry point. Composition with a blueprint that would import a vendor SDK directly conflicts here by design; the operator supersedes with a project-level ADR that either accepts the composed blueprint's shape or restates this one's.",
+  "alternativesConsidered": [
+    {
+      "name": "Environment-variable-first with no manifest",
+      "summary": "Every module reads `process.env.X` (or the language equivalent); the shape of the dependency graph is whatever the code paths do.",
+      "reasonNotChosen": "This is the default state most projects drift into and the state this blueprint exists to end. Rotation is unenforced, dependency-shape drift goes unnoticed until a deploy breaks, and there is no audit surface for who read what."
+    },
+    {
+      "name": "Per-deployable manifest instead of a single repo-root manifest",
+      "summary": "Each deployable owns its own secrets file; there is no project-wide view.",
+      "reasonNotChosen": "The estate-wide view is the point. Rotation policies and least-privilege audits need one file to look at; per-deployable files split the truth and re-open the drift class."
+    },
+    {
+      "name": "Vendor-committed opinionated blueprint (HashiCorp Vault only, or AWS Secrets Manager only)",
+      "summary": "Ship the blueprint tied to one specific vendor SDK; the manifest is that vendor's native shape.",
+      "reasonNotChosen": "Locks the project to a vendor at the blueprint layer, which the doctrine of round-2 refuses (vendor default belongs at ADR-902, contract belongs here). A composing blueprint or a project that wants a different vendor can only escape by removing this blueprint. Splitting the contract from the default keeps both moves available."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-secrets-management/contributions/adrs/adr-902-security-secrets-management-default-vendor.json

@@ -0,0 +1,35 @@
+{
+  "adrId": "ADR-902-security-secrets-management-default-vendor",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "The default secrets vendor is SOPS with age keys; committed encrypted files plus a project-held age key",
+  "context": "ADR-901 fixes the contract; a project applying this blueprint still needs a working default vendor at day one. The rcf-lite tier this blueprint targets is small greenfield projects: a single deployable, one small team or one solo operator, no ops team standing by. A default vendor for that tier should ship with zero infrastructure to run, a small dependency footprint, an on-disk shape a human can read without a service running, and an integration surface a coding agent can use through a piped-stdin CLI without extra machinery. Larger deployments will supersede this decision; the point of a default is that day one works.",
+  "decision": "The default vendor is Mozilla SOPS with age keys. Encrypted value files live under a project-authored path (typically `secrets/<environment>/<name>.enc`) committed to the repo; the age private key that decrypts them is a per-machine key held out of the repo (developer laptop keyring, CI runner secret, deployment host key material). The vendor adapter shape is: `readMany` shells to `sops --decrypt` on the resolved path per entry; `lastRotatedAt` is read from a `sops-metadata:` block the encrypt operation stamps; `materialiseCredentials` is a no-op because the SOPS invocation itself relies on the caller's age key. The default is chosen because it makes the zero-infrastructure floor real: no server to run, no account to hold, no per-project vault to provision. Projects that outgrow the default supersede this ADR with a project-level ADR selecting a hosted or self-hosted alternative (see alternatives).",
+  "consequences": "The project ships with a working secrets flow on day one and does not force an ops decision before the first commit. The age key is now a first-class piece of operator state a project must manage (a key on every developer laptop, a key on every CI runner, a key on every host running the app); losing every copy of the key loses access to every committed encrypted file, which is a recoverable-by-rewrite problem for a project pre-launch and a recoverable-by-re-issue problem thereafter. The rotation-days gate reads a metadata block SOPS itself writes; a project that hand-edits the encrypted files bypasses the metadata and loses the gate's truth source. Composition with a vendor-specific superseding blueprint (Vault, AWS Secrets Manager, GCP Secret Manager, Doppler, Infisical) is a project-level ADR change and a vendor-adapter swap; the ADR-901 contract stays intact.",
+  "alternativesConsidered": [
+    {
+      "name": "HashiCorp Vault",
+      "summary": "Run a Vault server (self-hosted or Vault Cloud); the vendor adapter reads through the Vault HTTP API using an app-scoped token or an auth method.",
+      "reasonNotChosen": "Reserved as the primary promotion path for projects that outgrow the SOPS default. Vault is the reference open-source posture for organisations with dedicated ops capacity: dynamic secrets, richer audit, policy engine, mature rotation orchestration. The trade against SOPS is running the server (or paying for the hosted plan) and the operator learning curve; small greenfield rcf-lite projects rarely need that day one."
+    },
+    {
+      "name": "AWS Secrets Manager / GCP Secret Manager / Azure Key Vault",
+      "summary": "Hosted per-cloud secrets managers; the vendor adapter reads through the cloud SDK using workload-identity credentials.",
+      "reasonNotChosen": "Ties the project to one cloud at the secrets layer; the doctrine of ADR-901 keeps the contract vendor-agnostic on purpose. Excellent choice for a project already committed to one cloud and using workload-identity; a project-level ADR supersede is the intended path there."
+    },
+    {
+      "name": "Doppler / Infisical / other hosted third-party secrets services",
+      "summary": "Hosted vendor with a project workspace and per-environment scoping; the vendor adapter reads through the vendor's HTTP API using a service token.",
+      "reasonNotChosen": "Same trade as the cloud-native option: a fine promotion path for a project that wants a managed service without cloud lock-in, but not the zero-infrastructure day-one default. A project-level ADR supersedes this ADR when the operator adopts one."
+    },
+    {
+      "name": "Plaintext values in the repo",
+      "summary": "Commit secrets as plain files; ignore the encryption layer entirely.",
+      "reasonNotChosen": "Fails every requirement in this blueprint that touches secret secrecy. Named only to explain why 'just put the secret in a file' is not the same shape as SOPS+age."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-secrets-management/contributions/adrs/adr-903-security-secrets-management-agent-access-discipline.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-903-security-secrets-management-agent-access-discipline",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Coding agents access secrets through the CLI with piped stdin only; secret bytes never appear in a chat transcript, log line, or committed file",
+  "context": "A coding agent that runs verbs, reads files, and captures its own tool output creates a large surface for secret material to land somewhere durable it should not be. Chat transcripts persist to model provider logs, session artefacts, and shared screenshots. Verbose tool logs land in the operator's terminal scrollback and in workspace backups. A `.env` file the agent generates in a scratch step ends up in git if a stray `git add` follows. The blueprint has to give agents an access path that is both usable (agents can wire the secret into the process that needs it) and safe (the bytes never traverse a surface the agent workflow persists).",
+  "decision": "Agents work with secrets through the Secrets CLI (TAC-905) using piped-stdin flow-through, never argv, never terminal-echoed output. `secrets read N` is called with stdout piped to the downstream consumer (a process being started, a temp file being materialised into a container secret volume, a Kubernetes secret being created); the value crosses one pipe and no more. `secrets put N` is called with stdin piped from the source of the new value (a clipboard reader, another `secrets read` in a rotation flow, a hardware token flow). The CLI refuses to echo a value to a TTY without an explicit `--show` flag, and the flag is honoured only when stdout is actually a TTY (not a captured stream). The CLI's own log stream runs through a redactor that replaces any bytes matching a resolved secret value with a fixed placeholder before emitting. Agent-authored code and configuration never store a secret value as a literal, an inlined constant, or a comment; every reference is by logical name through the client.",
+  "consequences": "Agent workflows compose secrets into running processes without the bytes crossing an observability surface the agent creates. The stdin-piped flow is unfamiliar to some tooling; projects wrap the pattern with small helper scripts (Node.js entry points that spawn a child process with the piped secret material as an environment variable set at spawn time and never printed) to keep the surface friendly. Human operators still have a debug path via `--show` on a real terminal, which is the one legitimate reason to look at a value with their own eyes. Nothing at this layer stops a human copying a value out of their own terminal; that class of leak requires an out-of-band delivery mode (see TAC-905 tradeoffs).",
+  "alternativesConsidered": [
+    {
+      "name": "Let the agent generate a `.env` file and reference it from process startup",
+      "summary": "The agent runs a reflector-like command that writes `.env` and the process reads from there.",
+      "reasonNotChosen": "The `.env` file is now on disk with secret bytes for the lifetime of the working tree, and the agent's transcript of the reflector command already contains everything an attacker needs to reproduce it. A piped-stdin invocation crosses fewer boundaries and leaves nothing on disk unless the operator's own tooling asks for it (that path is the env reflector, deliberately per-invocation-per-operator, not per-agent-step)."
+    },
+    {
+      "name": "Provide agents a mock-value adapter that returns placeholders for every secret",
+      "summary": "The agent works against a stub vendor that always returns strings like `<REDACTED>` and the real values are injected later by a human.",
+      "reasonNotChosen": "The stub adapter is a fine test-harness posture and does not need an ADR to authorise. It is not an access pattern for legitimate production wiring; the CLI's piped-stdin path is."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-secrets-management/contributions/adrs/adr-904-security-secrets-management-dotenv-reflection.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-904-security-secrets-management-dotenv-reflection",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "`.env` is an ephemeral regenerable reflection of the manifest, never the source of truth",
+  "context": "`.env` files have quietly become the de facto secrets store on many projects. Developers edit them by hand, tools like docker-compose and Node's dotenv library expect them at fixed paths, CI runners copy them around, and the file gets committed by accident on a regular schedule. Removing the `.env` entirely breaks a large amount of tooling that assumes its presence; keeping it as the source of truth reintroduces every failure mode this blueprint exists to end. The middle path is to keep the `.env` shape at the surface where tooling expects it and change its role from authoritative to reflective.",
+  "decision": "The `.env` file, when present at the repo root, is generated on demand from the Secrets Manager by the env reflector (TAC-903). Every run of `secrets reflect --deployable <id> --env <env>` overwrites the file atomically with the current vendor-resolved values for the target slice; nothing outside the reflector may write the file, and no runtime code reads the file to bypass the Secrets Manager client. The `.env` path is gitignored at project root by requirement (AC-8106-2) and the reflector refuses to run when it is not (defence against a mis-configured `.gitignore`). Per-environment reflection variants (`.env.dev`, `.env.ci`, `.env.live`) are selected by the `--env` flag; each variant is written and overwritten independently.",
+  "consequences": "Local tooling that expects `.env` keeps working; the developer runs the reflector and the file appears with values that match the current vendor state. The reflection is discardable at any moment (delete the file, rerun the reflector, get an identical result), which makes the file's ephemerality visible in the workflow. A stale `.env` from a week ago is a shape drift no one has to argue about; the reflector regenerates it. A CI job that needs a `.env` runs the reflector as a preamble; the file exists for the job's runtime and disappears with the runner. A process that reads `.env` directly at boot instead of the client is caught by the source-tree scan (AC-8106-3).",
+  "alternativesConsidered": [
+    {
+      "name": "No `.env` at all; every consumer reads the client directly",
+      "summary": "Refuse to write a reflection; every tool that needs a value invokes the CLI or imports the client.",
+      "reasonNotChosen": "Purer but breaks a lot of tooling with hard-coded `.env` expectations (docker-compose, some Node frameworks' hot-reload modes, some IDE integrations). The reflector adds surface but keeps the ecosystem workable."
+    },
+    {
+      "name": "Commit an encrypted `.env` and decrypt in place",
+      "summary": "Ship the reflection encrypted at rest in the repo and decrypt to a plaintext `.env` at boot.",
+      "reasonNotChosen": "Overlaps the default vendor's own encrypt-and-commit posture (ADR-902's SOPS files) without adding anything; the plaintext `.env` still exists on disk during runtime and is now redundant with the encrypted store."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-secrets-management/contributions/adrs/adr-905-security-secrets-management-rotation-and-audit.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-905-security-secrets-management-rotation-and-audit",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Rotation-days budget enforced at CI; every secret access is audited; audit events carry metadata only",
+  "context": "Rotation policies that are not enforced quietly slip; audit trails that carry secret bytes turn every log store into a secrets store. Both problems have a fix at the boundary the Secrets Manager client already owns: the client is the sole reader of secret values, so it is the only place that can emit audit events truthfully, and the manifest is the sole declaration of rotation budgets, so CI has one file to enforce against.",
+  "decision": "Every fetch attempt on the Secrets Manager client emits exactly one structured audit event carrying `{ name, path, environment, principal, outcome, at }`; no field carries the secret value or a substring of it. The audit sink is pluggable behind the same discipline as the wire log; the blueprint fixes the SHAPE of the events, not the storage engine. CI runs the rotation gate (TAC-904) on every change; an entry whose `lastRotatedAt` is more than `rotationDays` in the past fails the run with `SECRETS_ROTATION_EXPIRED`; an entry with no vendor-reported `lastRotatedAt` fails with `SECRETS_ROTATION_UNKNOWN`. An operator-authored override file with an `expiresAt` timestamp is honoured for the named entry until the expiry passes; the override is itself audited every time it applies.",
+  "consequences": "Rotation cannot silently slip; a CI run is the place the project already gates every change through. Investigating an incident starts with the audit stream and stays there; the log store is safe to ship to a third party because it holds no credential material. The vendor becomes the truth source for rotation age; a vendor without native rotation metadata forces the project into a parallel side-file (an acknowledged trade in TAC-904). The override with an expiry keeps a legitimate mid-rotation change unblocked without opening a permanent bypass; the audited-every-time property makes an over-used override visible.",
+  "alternativesConsidered": [
+    {
+      "name": "Hash the secret value into audit events for correlation",
+      "summary": "Emit a stable hash of the value so incident investigators can correlate 'this key was read here and here' without exposing the plaintext.",
+      "reasonNotChosen": "A hashed value still lets an attacker with log access confirm 'this hash is the hash for this secret', which is enough for correlation attacks on high-value keys. The event's `name` and `principal` already provide correlation; a hash adds risk without adding capability."
+    },
+    {
+      "name": "Rely on rotation announcements from the vendor rather than a CI gate",
+      "summary": "Subscribe to the vendor's rotation notification stream and act on drift asynchronously.",
+      "reasonNotChosen": "Async enforcement is a hope; a synchronous CI gate on every change is the place the project already fails on other drift classes (a lint error, a test failure, a schema mismatch). Enforcing at the same layer keeps the operator experience uniform."
+    },
+    {
+      "name": "Rotate on every deploy",
+      "summary": "Every merge triggers a full rotation of every secret.",
+      "reasonNotChosen": "Amplifies blast radius on every deploy failure and makes the vendor's rotation quotas the pacing item. A rotation budget with a bounded override is the honest posture: rotate on the cadence the value's threat model actually needs."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-secrets-management/contributions/requirements/security-secrets-management-req-001.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-secrets-management-REQ-001",
+  "prdId": "PRD-001",
+  "title": "The repo-root secrets manifest is the single source of truth for what secrets exist",
+  "description": "A file named `secrets.yaml` at the repo root enumerates every secret the project depends on. Each entry declares a stable logical name, the path or reference the vendor uses to fetch the value, the owner, the rotation-days budget, the environment scope (declared as an environment-aware structure whose exact shape is elicited from the operator; the common default is `dev`, `ci`, `live`), and whether the secret is required or optional. Nothing outside the manifest may declare a secret dependency; a required secret referenced from code but absent from the manifest is a build refusal. Secret VALUES never appear in the manifest; only names, paths, and metadata.",
+  "category": "functional",
+  "domain": "security",
+  "priority": "must",
+  "rationale": "A scattered secret dependency graph is the failure mode this blueprint exists to end. If every code path names its own environment variable, no one knows what the project actually needs, rotation is guesswork, and a missing secret surfaces as a runtime null. A single manifest at a known path makes the dependency set legible to humans, to CI gates, to onboarding runs, and to the vendor-side least-privilege policy that grants access to exactly the declared set.",
+  "tags": [
+    "blueprint:security-secrets-management",
+    "category:01-manifest"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-secrets-management/contributions/requirements/security-secrets-management-req-002.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-secrets-management-REQ-002",
+  "prdId": "PRD-001",
+  "title": "Secrets are read through one vendor-agnostic manager client interface",
+  "description": "The project imports a single Secrets Manager client that exposes the named verbs `get(name)`, `getRequired(name)`, `list()`, and `refresh()`. `get` returns the current value or null; `getRequired` throws a stable-coded error on absence; `list` returns the manifest-declared name set for this process; `refresh` re-reads every secret this process is authorised for. The client is the sole importer of the vendor binding on the boundary; no other module reaches for the vendor SDK, an environment variable, or a config file directly. The default vendor is named in ADR-902; the interface itself does not depend on which vendor is behind it.",
+  "category": "functional",
+  "domain": "security",
+  "priority": "must",
+  "rationale": "A vendor-agnostic port keeps the project free to change vendors under a passing test suite. It also removes the class of bugs where two modules read the same secret through two different code paths and disagree about whether it is set. One client, one boundary, one behaviour.",
+  "tags": [
+    "blueprint:security-secrets-management",
+    "category:02-client-contract"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-secrets-management/contributions/requirements/security-secrets-management-req-003.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-secrets-management-REQ-003",
+  "prdId": "PRD-001",
+  "title": "Each process reads only the secrets its manifest slice declares (least-privilege)",
+  "description": "Each deployable in the project declares an explicit slice of the manifest it needs (by logical name). At boot the Secrets Manager client materialises credentials for exactly that slice and refuses to serve any other name for the lifetime of the process. A `get('X')` call for a name outside the declared slice throws a stable-coded refusal, even when `X` is a legal manifest entry for a different deployable. Vendor-side access policies are configured to grant this process's credentials read on exactly the declared slice and no other paths; the code-side refusal and the vendor-side deny are both required and both belong to the least-privilege posture.",
+  "category": "nonFunctional",
+  "domain": "security",
+  "priority": "must",
+  "rationale": "A single credential that can read every secret in the project is one bug away from an all-secrets exposure. Slicing the read surface per process makes the blast radius of a code path that gets abused the size of that process's slice, not the size of the whole project.",
+  "tags": [
+    "blueprint:security-secrets-management",
+    "category:03-least-privilege"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-secrets-management/contributions/requirements/security-secrets-management-req-004.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-secrets-management-REQ-004",
+  "prdId": "PRD-001",
+  "title": "Every access to secret material produces a durable audit event",
+  "description": "The Secrets Manager client emits a structured audit event on every fetch of a secret value: the logical name, the manifest path, the environment scope, the requesting principal (deployable name plus operator or agent id where applicable), the outcome (`served`, `refusedOutOfSlice`, `refusedAbsent`, `refusedRotationExpired`), and the wall-clock timestamp. The event never contains the secret value or any prefix or suffix of it. The audit sink is pluggable behind the same discipline as the wire log; the blueprint fixes the SHAPE of the events and the fields that must appear, not the storage engine.",
+  "category": "nonFunctional",
+  "domain": "security",
+  "priority": "must",
+  "rationale": "Rotation, incident response, and least-privilege verification all depend on being able to answer 'who read what, when'. A missing audit trail is the difference between 'we know the blast radius' and 'we hope the blast radius is small'. Keeping the value out of the event is the discipline that makes shipping the audit stream to a third-party log store safe.",
+  "tags": [
+    "blueprint:security-secrets-management",
+    "category:04-audit"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-secrets-management/contributions/requirements/security-secrets-management-req-005.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-secrets-management-REQ-005",
+  "prdId": "PRD-001",
+  "title": "Coding agents work with secrets through a piped-stdin CLI; secret material never appears in a chat transcript, log line, or source-tree file",
+  "description": "A secrets CLI ships alongside the client. Every verb that would surface a secret VALUE accepts and produces that value only on stdin or stdout piped to a downstream consumer; the value never appears in a command argument, an environment variable printed at startup, a prompt echo, a chat transcript captured by any agent harness, or a log line the CLI itself writes. Agent-authored code and agent-authored configuration reference secrets by their logical name only. The CLI's structured output surface (`--json`, `--report`) enumerates names and metadata, never values. A verb that prints a value to a terminal is refused unless the process has an interactive TTY on stdout AND the operator has passed an explicit `--show` flag; the flag is deliberately not scriptable through an agent transcript.",
+  "category": "functional",
+  "domain": "security",
+  "priority": "must",
+  "rationale": "A secret that lands in an agent's transcript is a secret in every downstream copy of that transcript (session artefacts, workspace backups, model provider logs, human-shared screenshots). The stdin-piped posture is the only reliable way to keep secret bytes off the surfaces an agent-driven workflow creates. The `--show` interactive gate keeps the human debugging path open without becoming an agent scripting path.",
+  "tags": [
+    "blueprint:security-secrets-management",
+    "category:05-agent-access"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-secrets-management/contributions/requirements/security-secrets-management-req-006.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-secrets-management-REQ-006",
+  "prdId": "PRD-001",
+  "title": "`.env` files are ephemeral regenerable reflections of the manifest, never the source of truth",
+  "description": "A `.env` file, when it exists on a developer laptop or a CI runner, is a per-machine reflection generated on demand from the Secrets Manager by an env reflector command (`secrets reflect`). The reflector reads the current manifest slice for the target process, fetches the values, and writes them to the `.env` path atomically; a subsequent `secrets reflect` overwrites the file. The `.env` path is gitignored at project root; the manifest is committed. A process that reads `.env` directly at boot instead of going through the Secrets Manager client is a v1 policy violation caught by the source-tree scan the CI gate runs. The `.env` reflection is a convenience for local tooling that expects one; it is never the authoritative store, it is never rotated in-place, and it is discardable at any moment.",
+  "category": "functional",
+  "domain": "security",
+  "priority": "must",
+  "rationale": "`.env` files were invented as a laptop-local shim and have quietly become primary state on many projects, which is where rotation drift, uncommitted-secret-shape drift, and shared-laptop leaks begin. Recentring the manifest as the source of truth and demoting `.env` to a projection removes both classes of drift without breaking the local-dev flow developers already have muscle memory for.",
+  "tags": [
+    "blueprint:security-secrets-management",
+    "category:06-dotenv-reflection"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-secrets-management/contributions/requirements/security-secrets-management-req-007.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-secrets-management-REQ-007",
+  "prdId": "PRD-001",
+  "title": "The manifest is environment-aware; the exact environment shape is elicited from the operator, not assumed",
+  "description": "Each manifest entry carries per-environment metadata: at minimum a path or reference the vendor resolves per environment, and optionally per-environment rotation and required-or-optional overrides. The set of environment names (for example `dev`, `ci`, `live`; or `dev`, `staging`, `prod`; or a project-specific list) is elicited from the operator at first apply, recorded in the manifest header, and enforced from then on. The Secrets Manager client resolves against exactly one environment per process, selected by an unambiguous boot input (a process-scoped variable or a boot flag), and a missing per-environment resolution for the active environment fails boot for a required secret and is served as null for an optional one.",
+  "category": "functional",
+  "domain": "security",
+  "priority": "must",
+  "rationale": "Every project has a slightly different environment shape and forcing one on them is how the manifest becomes the thing developers work around instead of with. Eliciting the shape at apply time (and freezing it in the manifest header) keeps the manifest legible to a first-time reader and keeps the boot-time selection unambiguous.",
+  "tags": [
+    "blueprint:security-secrets-management",
+    "category:07-environment-aware"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-secrets-management/contributions/requirements/security-secrets-management-req-008.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-secrets-management-REQ-008",
+  "prdId": "PRD-001",
+  "title": "The process fails to boot when a required secret is absent; degrades on an optional absent secret",
+  "description": "At boot the Secrets Manager client attempts to materialise every name in the declared slice. A `required: true` entry that cannot be resolved for the active environment aborts boot with a stable-coded error naming the logical name and the environment, and no partial start-up state is exposed on any port. A `required: false` entry that cannot be resolved is served as null; consumers that call `get` on an optional name handle the null branch. The failure mode is loud, early, and irreversible in-boot; there is no wait-and-retry loop that would leave the process half-alive with silently missing secrets.",
+  "category": "functional",
+  "domain": "security",
+  "priority": "must",
+  "rationale": "A process that starts with a required secret missing serves broken traffic while the operator hunts a null-pointer stack trace ten layers down. Failing at boot names the problem exactly once at exactly the right layer, and the operator moves straight to the manifest.",
+  "tags": [
+    "blueprint:security-secrets-management",
+    "category:08-fail-safe"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-secrets-management/contributions/requirements/security-secrets-management-req-009.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-secrets-management-REQ-009",
+  "prdId": "PRD-001",
+  "title": "CI fails a change when a secret has aged past its rotation-days budget",
+  "description": "A rotation gate runs in CI on every change. For each manifest entry with a `rotationDays` value, the gate compares the vendor-reported last-rotated timestamp against the current CI-run wall clock; a gap greater than `rotationDays` fails the run with a stable-coded error naming the logical name, the environment, the last-rotated timestamp, and the elapsed days. The gate has a documented override for a scheduled rotation window (an operator-authored justification file the gate reads with an expiry timestamp), and the override is itself audited. The gate runs on the manifest as-committed against the vendor as-configured; a required secret with no vendor-reported last-rotated timestamp fails the gate.",
+  "category": "nonFunctional",
+  "domain": "security",
+  "priority": "must",
+  "rationale": "Rotation policies that are not enforced are policies that quietly slip. CI is the gate every change already passes through, and failing on staleness turns 'we should rotate this' into 'this change cannot merge until we do'. The override with an expiry keeps a legitimate mid-rotation change unblocked without opening a permanent bypass.",
+  "tags": [
+    "blueprint:security-secrets-management",
+    "category:09-rotation-gate"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-secrets-management/contributions/requirements/security-secrets-management-req-010.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "security-secrets-management-REQ-010",
+  "prdId": "PRD-001",
+  "title": "The operator picks one of three UI outcomes for the Secrets Management surface: integrate a Secrets page into an existing admin UI, adopt an admin-SPA blueprint, or decline a UI",
+  "description": "At apply the working agent elicits a three-way choice about the operator-facing Secrets Management surface: (a) integrate a Secrets Management page into an existing project admin UI, wired to the CLI's structured surface (names and metadata only; the page never renders a secret value); (b) adopt a separate admin-SPA blueprint (a future companion blueprint) that hosts the Secrets page as one of its screens; (c) decline a UI entirely and rely on the CLI plus the audit stream. The choice is recorded in the manifest header. When (a) is chosen the page's contract is fixed by TAC-905 (list, filter by environment, show last-rotated, request-rotation button that hands off to the operator's rotation procedure); the page implementation lives in the host project. When (b) is chosen the project applies the admin-SPA blueprint on top of this one and inherits the page from there. When (c) is chosen this blueprint contributes nothing to the operator UI surface and the CLI plus audit sink remain the whole story.",
+  "category": "functional",
+  "domain": "security",
+  "priority": "should",
+  "rationale": "A UI over secret metadata (names, environments, ages, owners) is useful; a UI over secret values reintroduces the leakage class this blueprint spent nine requirements eliminating. Forcing every project onto a UI would add surface most rcf-lite projects do not need; forbidding one would push operators back to spreadsheets. Eliciting the choice at apply time keeps the blueprint honest across small and larger projects.",
+  "tags": [
+    "blueprint:security-secrets-management",
+    "category:10-ui-integration"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-secrets-management/contributions/tacs/tac-901-security-secrets-management-manager-client.json

@@ -0,0 +1,52 @@
+{
+  "tacId": "TAC-901-security-secrets-management-manager-client",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Secrets Manager client",
+  "purpose": "The one place in the project that reads secret material. Loads the manifest slice for the current deployable at boot, materialises credentials for exactly that slice through a vendor adapter, exposes a fixed named-verb surface to callers, and emits an audit event on every fetch attempt. Every other module in the project reads secrets through this client; nothing else imports the vendor SDK.",
+  "responsibilities": [
+    "Load the manifest for the repo root and pick out the slice for the boot-input deployable id (AC-8101-1, AC-8103-1).",
+    "Refuse `get`/`getRequired` for a name outside the declared slice with a stable-coded `SECRETS_OUT_OF_SLICE` error and no vendor call (AC-8101-2, AC-8103-1).",
+    "Materialise vendor credentials once at boot for exactly the declared slice; refuse boot on a required-absent secret with `SECRETS_REQUIRED_ABSENT` naming the logical name and active environment (AC-8102-2, AC-8108-1, AC-8107-3).",
+    "Serve `get(name)` from an in-memory cache; support `refresh()` as an atomic swap so a concurrent `get` never sees a mixed slice (AC-8102-3).",
+    "Emit exactly one structured audit event per fetch attempt, with fields `name`, `path`, `environment`, `principal`, `outcome`, `at`; no field may carry the secret value or a substring of it (AC-8104-1, AC-8104-2, AC-8104-3).",
+    "Select the active environment from an unambiguous boot input; refuse boot on ambiguous inputs with `SECRETS_ENV_AMBIGUOUS` (AC-8107-2).",
+    "Retry-once semantics at boot: a required-absent read is attempted once, not looped (AC-8108-3)."
+  ],
+  "internalStructure": "One stateless class per process with an injected vendor adapter and an injected audit sink. The cache is a Map keyed by logical name and populated at boot; a refresh swaps a new Map in atomically. The vendor adapter is a project-authored module implementing the port defined in the interfaces block; the reference default vendor is named in ADR-902 and lives under the same package as this client.",
+  "interfaces": [
+    {
+      "name": "vendorAdapter",
+      "kind": "read-write-api",
+      "description": "Project-supplied vendor binding implementing `readMany({ paths, credentials, environment })` returning `{ [name]: { value, lastRotatedAt } }` or an entry-level not-found marker, and `materialiseCredentials({ slicePaths, environment })` returning per-slice credentials the vendor deny-by-default enforces."
+    },
+    {
+      "name": "manifest",
+      "kind": "read-api",
+      "description": "The manifest loader (TAC-902) resolving the current deployable's slice, per-environment paths, and `required` flags."
+    },
+    {
+      "name": "auditSink",
+      "kind": "callback",
+      "description": "Structured-event sink invoked with `{ name, path, environment, principal, outcome, at }` on every fetch attempt; never invoked with the secret value."
+    },
+    {
+      "name": "envSelector",
+      "kind": "read-api",
+      "description": "The boot-input resolver for the active environment: a process variable, a boot flag, or a project-authored selector. Returns exactly one environment string or refuses ambiguity."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Secrets Manifest",
+      "kind": "tac",
+      "tacId": "TAC-902-security-secrets-management-manifest",
+      "description": "Upstream source of the declared slice and per-environment path map the client resolves at boot."
+    }
+  ],
+  "tradeoffs": "The client holds every declared value in memory for the lifetime of the process; a heap dump of a compromised process exposes the slice's cleartext. That trade means every read is a memory access rather than a vendor round trip, which is what makes the hot path affordable and what makes `refresh` cheap. Projects that want per-fetch vendor reads (short-lived credential floors, HSM-mediated flows) supply a vendor adapter whose `readMany` proxies to the vendor on every call and rely on the cache being a thin write-through layer.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-secrets-management/contributions/tacs/tac-902-security-secrets-management-manifest.json

@@ -0,0 +1,34 @@
+{
+  "tacId": "TAC-902-security-secrets-management-manifest",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Secrets manifest loader and validator",
+  "purpose": "Loads `secrets.yaml` at the repo root, validates its shape against the manifest schema, exposes the declared environment set, the declared deployable-to-slice map, and the per-entry per-environment path resolution. Every other component reads the manifest through this loader.",
+  "responsibilities": [
+    "Read `secrets.yaml` from the repo root; refuse a missing file with a stable-coded `SECRETS_MANIFEST_MISSING` error naming the expected path.",
+    "Parse the YAML and validate against the schema: `environments` is a non-empty array of lower-kebab strings; each `secrets[]` entry has `name`, `paths`, `owner`, `rotationDays`, `required` (AC-8101-1).",
+    "Enforce that every entry's `paths` object key set equals `environments` exactly; refuse a partial entry with `SECRETS_ENV_PATH_MISSING` (AC-8107-1).",
+    "Refuse a `value` field on any entry (secret values never live in the manifest) with `SECRETS_MANIFEST_VALUE_FIELD`.",
+    "Resolve a deployable's slice: return the ordered array of manifest entries whose `deployables` list includes the queried deployable id (AC-8103-1).",
+    "Expose a lookup for a single entry by name so downstream tools (rotation gate, env reflector, CLI list surface) share one resolution path."
+  ],
+  "internalStructure": "One pure module: a `loadManifest(rootPath)` function returning a frozen manifest object plus a set of typed accessors (`slicesFor(deployableId)`, `entryByName(name)`, `environments()`, `uiIntegrationMode()`). No I/O beyond the initial file read; no cache invalidation because the manifest is treated as a boot-time constant.",
+  "interfaces": [
+    {
+      "name": "fileSystem",
+      "kind": "read-api",
+      "description": "Project-supplied file reader accepting a repo-root-relative path and returning UTF-8 bytes; injected for test surface."
+    },
+    {
+      "name": "yamlParser",
+      "kind": "read-api",
+      "description": "YAML parser accepting bytes and returning a plain object; injected so the project supplies its own dependency."
+    }
+  ],
+  "dependencies": [],
+  "tradeoffs": "The manifest is treated as boot-time immutable; a change to `secrets.yaml` requires a process restart to take effect. That trade removes a class of cache-invalidation bugs and keeps the audit-event trail truthful about which manifest version was in force. Projects that need hot-reload wire a file watcher that triggers a graceful restart, not an in-place manifest swap.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-secrets-management/contributions/tacs/tac-903-security-secrets-management-env-reflector.json

@@ -0,0 +1,46 @@
+{
+  "tacId": "TAC-903-security-secrets-management-env-reflector",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Env reflector",
+  "purpose": "Regenerates a `.env` file at the repo root from the current manifest slice and the vendor-resolved values, for the local developer tools that expect one. Runs on demand; overwrites atomically; never treats the resulting `.env` as authoritative.",
+  "responsibilities": [
+    "Accept `--deployable <id>` and `--env <env>`; resolve the slice through TAC-902 and the values through TAC-901 (AC-8106-1).",
+    "Write the `.env` atomically: write to a temp file in the same directory and rename over the target so a partial write is never observable to a concurrent reader (AC-8106-1).",
+    "Refuse to run when the target `.env` path is not gitignored at the repo root; emit `SECRETS_DOTENV_NOT_IGNORED` naming the path (defence against a project that mis-configures `.gitignore`).",
+    "Never emit secret values to any surface other than the resulting file bytes; the command's own stdout, stderr, and audit event carry names and counts only.",
+    "Support per-environment reflection variants (`.env.dev`, `.env.ci`, `.env.live`) selected by the `--env` flag; when the same command is re-run with a different `--env` the previously-written variant is left untouched."
+  ],
+  "internalStructure": "One stateless command handler. Composes the manifest loader (TAC-902), the Secrets Manager client (TAC-901), and a small `writeAtomic` utility. The output shape is a POSIX-style `KEY=value` file with values escaped for values containing whitespace, quotes, or newlines.",
+  "interfaces": [
+    {
+      "name": "fileSystem",
+      "kind": "read-write-api",
+      "description": "Project-supplied file reader-writer supporting temp-file creation and atomic rename."
+    },
+    {
+      "name": "gitignoreCheck",
+      "kind": "read-api",
+      "description": "Project-supplied predicate answering whether a given path is gitignored (usually a shell-out to `git check-ignore`)."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Secrets Manager client",
+      "kind": "tac",
+      "tacId": "TAC-901-security-secrets-management-manager-client",
+      "description": "Source of the resolved values for the target slice."
+    },
+    {
+      "name": "Secrets Manifest",
+      "kind": "tac",
+      "tacId": "TAC-902-security-secrets-management-manifest",
+      "description": "Source of the deployable-to-slice map."
+    }
+  ],
+  "tradeoffs": "The reflector puts secret material on disk in a file most tooling has read access to. That trade is the cost of interoperability with the tools that expect a `.env`; the atomic-write plus gitignore-required-check plus explicit re-run posture keeps the reflection legible as ephemeral rather than authoritative. Projects that prefer never to touch disk (in-memory-only container starts) skip the reflector and let their tooling read from the client directly.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/security-secrets-management/contributions/tacs/tac-904-security-secrets-management-rotation-gate.json

@@ -0,0 +1,57 @@
+{
+  "tacId": "TAC-904-security-secrets-management-rotation-gate",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Rotation gate",
+  "purpose": "CI-time enforcer of the rotation-days budget declared on each manifest entry. Reads the manifest, queries the vendor for the current per-entry `lastRotatedAt`, fails the CI run on any expired or unknown-age entry, honours a bounded override, and audits the outcome.",
+  "responsibilities": [
+    "Read the manifest through TAC-902 and iterate every entry with a `rotationDays` value (AC-8109-1).",
+    "For each entry and each configured target environment, query the vendor adapter for the current `lastRotatedAt`; compare the elapsed days against `rotationDays`; fail with `SECRETS_ROTATION_EXPIRED` when elapsed > budget (AC-8109-1).",
+    "Fail with `SECRETS_ROTATION_UNKNOWN` when the vendor returns no `lastRotatedAt` for an entry, regardless of `required` (AC-8109-2).",
+    "Load the operator-authored override file when present; for a named entry with an unexpired override, skip the fail and emit a `SECRETS_ROTATION_OVERRIDE_APPLIED` audit event carrying the override author, expiry, and the wall-clock at gate time (AC-8109-3).",
+    "Refuse to accept an override without an `expiresAt` timestamp; the override is bounded by design.",
+    "Emit a `--report` structured summary listing every entry's environment, `lastRotatedAt`, elapsed days, budget, and outcome; the report never contains a secret value."
+  ],
+  "internalStructure": "One stateless command handler runnable from any CI runner. Composes TAC-902 (manifest), the vendor adapter from TAC-901, and a small override reader. Wall-clock injected for test surface.",
+  "interfaces": [
+    {
+      "name": "vendorAdapter",
+      "kind": "read-api",
+      "description": "The same vendor binding the Secrets Manager client uses (TAC-901), scoped to a rotation-metadata read (no value fetch is required for the gate's own operation)."
+    },
+    {
+      "name": "overrideStore",
+      "kind": "read-api",
+      "description": "Reads the operator-authored override file (project-authored path; a JSON or YAML file listing per-name `{ author, expiresAt, reason }` entries)."
+    },
+    {
+      "name": "clock",
+      "kind": "clock",
+      "description": "Injectable millisecond wall clock for the elapsed-days arithmetic."
+    },
+    {
+      "name": "auditSink",
+      "kind": "callback",
+      "description": "The same sink shape TAC-901 uses; the gate emits override-applied and rotation-expired events through it."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Secrets Manifest",
+      "kind": "tac",
+      "tacId": "TAC-902-security-secrets-management-manifest",
+      "description": "Source of the entries the gate iterates over."
+    },
+    {
+      "name": "Secrets Manager client",
+      "kind": "tac",
+      "tacId": "TAC-901-security-secrets-management-manager-client",
+      "description": "Provider of the vendor adapter shape the gate re-uses for the rotation-metadata query."
+    }
+  ],
+  "tradeoffs": "The gate treats the vendor as the truth source for rotation age; a vendor with an unreliable `lastRotatedAt` field turns the gate into false positives. Projects on a vendor without native rotation metadata track rotation timestamps in a parallel side-file at the cost of an extra source of truth (accept the trade or supersede ADR-905 with a project-level ADR selecting a stricter posture).",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}