@adammcarter/use-cases 0.1.0

package/docs/reference/error-codes.md

@@ -0,0 +1,123 @@
+<!-- GENERATED FILE — do not edit by hand.
+     Regenerate with `node packages/core/scripts/generate-error-codes.mjs`
+     (source of truth: packages/core/src/errors/registry.ts). -->
+
+# Error Codes
+
+Stable `UCM_*` error codes are part of the [public API](./stability.md). Each
+code below is a versioned contract: a code is only removed or repurposed in a
+**major** release; new codes ship additively in a **minor**. Diagnostics carry
+the code in their `code` field.
+
+There are **66** codes across **9** surfaces.
+
+## Marker grammar
+
+| Code | Severity | Message |
+|---|---|---|
+| `UCM_MARKER_DUPLICATE_BINDING_SLUG` | error | Duplicate binding slug within the same source. |
+| `UCM_MARKER_END_MALFORMED` | error | Marker end line is malformed. |
+| `UCM_MARKER_END_MISMATCHED` | error | Marker end line does not match its open marker. |
+| `UCM_MARKER_END_WITHOUT_START` | error | Marker end line has no matching start. |
+| `UCM_MARKER_FORBIDDEN_PAYLOAD` | error | Marker line carries a forbidden payload. |
+| `UCM_MARKER_MALFORMED` | error | Marker line is malformed. |
+| `UCM_MARKER_NESTED_SPAN` | error | Marker spans may not be nested. |
+| `UCM_MARKER_UNSUPPORTED_INFERENCE` | error | Marker span uses an unsupported inference. |
+
+## Binding registry
+
+| Code | Severity | Message |
+|---|---|---|
+| `UCM_REGISTRY_DUPLICATE_REGISTRATION` | error | Duplicate registration in the binding registry. |
+| `UCM_REGISTRY_JSON_PARSE` | error | Binding registry is not valid JSON. |
+| `UCM_REGISTRY_ROW_MISSING` | error | Referenced registry row is missing. |
+| `UCM_REGISTRY_SCHEMA_INVALID` | error | Binding registry does not match its schema. |
+| `UCM_REGISTRY_SLUG_PREFIX_MISMATCH` | error | Binding slug prefix does not match the registry. |
+| `UCM_REGISTRY_SLUG_ROW_CONFLICT` | error | Binding slug conflicts with an existing registry row. |
+
+## Evidence ledger
+
+| Code | Severity | Message |
+|---|---|---|
+| `UCM_EVIDENCE_APPEND_ONLY_VIOLATION` | error | Evidence ledger is append-only; rewrite rejected. |
+| `UCM_EVIDENCE_BINDING_SET_HASH_MISMATCH` | error | Evidence binding-set hash does not match. |
+| `UCM_EVIDENCE_EXPECTED_HEAD_MISMATCH` | error | Expected head event does not match current head. |
+| `UCM_EVIDENCE_IDEMPOTENCY_CONFLICT` | error | Idempotency key was reused with different intent. |
+| `UCM_EVIDENCE_INVALID_TRANSITION` | error | Evidence aggregate is not in a state that allows this transition. |
+| `UCM_EVIDENCE_JSON_PARSE` | error | Evidence ledger line is not valid JSON. |
+| `UCM_EVIDENCE_LEDGER_DAMAGED` | error | Refusing to append to damaged evidence history. |
+| `UCM_EVIDENCE_LOCK_TIMEOUT` | error | Timed out acquiring evidence append lock. |
+| `UCM_EVIDENCE_PRODUCER_NOT_TRUSTED` | error | Evidence producer is not trusted. |
+| `UCM_EVIDENCE_ROW_MISSING` | error | Referenced evidence row is missing. |
+| `UCM_EVIDENCE_SCHEMA_INVALID` | error | Evidence event does not match its schema. |
+| `UCM_EVIDENCE_VERIFICATION_NOT_PASS` | error | Evidence verification did not pass. |
+| `UCM_LEDGER_CHAIN_BROKEN` | error | Evidence ledger hash chain is broken: an entry's previous_entry_hash does not match the preceding entry. |
+| `UCM_LEDGER_DUPLICATE_INDEX` | error | Evidence ledger contains a duplicate entry_index. |
+| `UCM_LEDGER_INDEX_GAP` | error | Evidence ledger entry_index does not match its actual position (gap, reorder, or truncation). |
+
+## Signature / proof verification
+
+| Code | Severity | Message |
+|---|---|---|
+| `UCM_SIGNATURE_ALG_UNSUPPORTED` | error | Proof signature algorithm is unsupported. |
+| `UCM_SIGNATURE_BAD` | error | Proof signature is invalid. |
+| `UCM_SIGNATURE_MISSING` | error | Proof event is missing a signature. |
+| `UCM_SIGNATURE_UNKNOWN_KEY_ID` | error | Proof signature references an unknown key id. |
+
+## Swift function recognizer
+
+| Code | Severity | Message |
+|---|---|---|
+| `UCM_SWIFT_CONDITIONAL_COMPILATION` | error | Conditional compilation directive inside a marked span. |
+| `UCM_SWIFT_FUNC_NO_BODY` | error | Marked function has no body. |
+| `UCM_SWIFT_FUNC_NO_CLOSING_BRACE` | error | Marked function body has no closing brace. |
+| `UCM_SWIFT_MARKER_INSIDE_ATTACHED` | error | Marker is inside an attached declaration. |
+| `UCM_SWIFT_MARKER_INSIDE_SPAN` | error | Another marker appears inside a marked span. |
+| `UCM_SWIFT_MARKER_NOT_ADJACENT` | error | Marker is not adjacent to a declaration. |
+| `UCM_SWIFT_MULTIPLE_CANDIDATES` | error | Multiple candidate declarations for the marker. |
+| `UCM_SWIFT_NESTED_FUNC_UNSUPPORTED` | error | Nested functions are unsupported in a marked span. |
+| `UCM_SWIFT_NEXT_NODE_NOT_FUNC` | error | The node following the marker is not a function. |
+| `UCM_SWIFT_NO_PARSER` | error | No Swift parser is available. |
+| `UCM_SWIFT_PARSE_ERROR` | error | Swift parse error within the marker region. |
+
+## Workspace config
+
+| Code | Severity | Message |
+|---|---|---|
+| `UCM_WORKSPACE_COMPONENT_UNKNOWN` | error | Unknown component '...'; does not match the declared component. |
+| `UCM_WORKSPACE_CONFIG_INVALID` | error | Invalid use-cases.yml. |
+| `UCM_WORKSPACE_CONFIG_PARSE` | error | Unable to parse use-cases.yml. |
+
+## Migration
+
+| Code | Severity | Message |
+|---|---|---|
+| `UCM_MIGRATION_UNSAFE_OUTPUT_PATH` | error | Migration output path must stay inside the data root. |
+| `UCM_MIGRATION_UNSAFE_SOURCE_PATH` | error | Migration source path must stay inside the repository. |
+
+## Showcase lifecycle
+
+| Code | Severity | Message |
+|---|---|---|
+| `UCM_SHOWCASE_FAILURE_DECISION_REQUIRED` | error | Cannot finish until each failed or blocked verdict has a failure decision. |
+| `UCM_SHOWCASE_FINISH_REQUIRED` | error | User approval/rejection requires a finished showcase run. |
+| `UCM_SHOWCASE_IDEMPOTENCY_CONFLICT` | error | Idempotency key was reused with different intent. |
+| `UCM_SHOWCASE_INVALID_CORRECTION_TARGET` | error | Correction target must be a verdict event. |
+| `UCM_SHOWCASE_INVALID_FAILURE_DECISION_TARGET` | error | Failure decision target must be a failed or blocked verdict event. |
+| `UCM_SHOWCASE_KNOWN_GAP_ACK_REQUIRED` | error | Partial plan requires known-gap acknowledgement. |
+| `UCM_SHOWCASE_LEDGER_DAMAGED` | error | Refusing to append to damaged showcase history. |
+| `UCM_SHOWCASE_PLAN_HASH_MISMATCH` | error | Plan content hash does not match plan body. |
+| `UCM_SHOWCASE_PLAN_INVALID` | error | Presentation plan file is not a v1 plan. |
+| `UCM_SHOWCASE_PLAN_PLACEHOLDER_HASH` | error | Plan content hash must not be a placeholder. |
+| `UCM_SHOWCASE_PLAN_UNREADABLE` | error | Presentation plan file could not be read. |
+| `UCM_SHOWCASE_RUN_ID_CONFLICT` | error | Showcase run id already exists. |
+| `UCM_SHOWCASE_TRUSTED_CONFIRMATION_REQUIRED` | error | User approval requires a trusted interactive user confirmation path. |
+| `UCM_SHOWCASE_USER_APPROVAL_REQUIRED` | error | Agent cannot record user-required approval. |
+| `UCM_SHOWCASE_VERDICT_REQUIRES_OBSERVATION` | error | Verdict requires a prior observation. |
+
+## Path safety
+
+| Code | Severity | Message |
+|---|---|---|
+| `UCM_INVALID_ID` | error | Identifier is not a canonical id; refusing to use it as a path segment. |
+| `UCM_PATH_ESCAPE` | error | Unsafe relative path escapes its root boundary. |

package/docs/reference/stability.md

@@ -0,0 +1,123 @@
+# Stability & Versioning Policy
+
+use-cases follows [Semantic Versioning](https://semver.org). At
+`1.0.0` the surfaces listed under **Public API** below are a contract: they only
+change in breaking ways across a **major** version bump. This page is the
+authoritative declaration of what is stable, what is experimental, and how
+versions move.
+
+> **Pre-1.0 (beta).** The current release line is `0.0.x` — beta software. The
+> contracts below describe the *intended* shape that becomes binding **at
+> `1.0.0`**; until then they may still change between `0.0.x` releases. Adopt
+> with that in mind.
+
+> Ships as a single package, `use-cases` (binaries `uc` and `uc-mcp`);
+> the `core` / `cli` / `mcp` workspaces are bundled inside it, not published
+> separately. See the [publishing runbook](../release/publishing.md) for how a
+> release is cut (npm Trusted Publishing + provenance) and the owner one-time npm
+> setup.
+
+## SemVer policy
+
+| Bump | What may change |
+|---|---|
+| **patch** (`1.0.x`) | Bug fixes. No schema, CLI, MCP, or output-shape changes. Human-readable text may change. |
+| **minor** (`1.x.0`) | Additive only: new commands, new MCP tools/resources/prompts, new **optional** schema fields, new error codes, new exit-code *meanings* for previously-unused codes. Existing contracts keep working. |
+| **major** (`x.0.0`) | Anything removed, renamed, or changed in meaning: a command/flag/tool/field/error-code removed or repurposed, an output shape changed, a schema field made required, exit-code semantics changed. |
+
+A change is "breaking" if a correct integration written against `1.0.0` could
+observe different behaviour. When in doubt, treat it as major.
+
+## Public API (stable at 1.0.0)
+
+These are versioned contracts:
+
+- **CLI command + subcommand names and their flags** — e.g. `uc matrix validate`, `uc verify`, `uc prove`, `uc bind`, `uc scan`. Renames/removals are breaking.
+- **CLI `--json` output** — the envelope and every command's `data` shape (see below). Human/text output is **not** part of the contract.
+- **CLI exit codes** and their meanings (see below).
+- **The result envelope** shared by CLI `--json` and MCP structured results.
+- **MCP tool names** and their input/output schemas, plus the MCP **safety policy** defaults (mutations gated, no signing/`prove`, no generic shell, workspace-root locking).
+- **Persisted file formats**, each carrying `schema_version`: the matrix / use-case files, the binding registry (`bindings.jsonl`), the proof/evidence ledger (`proofs.jsonl`), evidence events, showcase specs/runs, capsules, plans, host profiles, and workspace config.
+- **JSON Schemas** published under the `https://use-cases.dev/schemas/v1/...` `$id` namespace (resolved locally; not fetched).
+- **The use-case marker grammar** (`//: @use-case: <slug>` … `//: @use-case: end <slug>`) and slug rules.
+- **The proof/trust model**: ed25519 signed proof events, the hashed inputs (row, binding-set, span, verification-context), and the freshness states (`FRESH`, `SUSPECT`, `UNPROVEN`, `UNBOUND`, `INVALID`). Signing-key management — the single `--public-key` path, the opt-in `--keyring` registry, and key rotation/revocation — is documented in [key management](../security/key-management.md).
+- **Error codes** declared in the [error-code registry](./error-codes.md) (`UCM_*`).
+
+### Result envelope
+
+Every CLI `--json` response and MCP structured result uses this envelope:
+
+```json
+{
+  "schema_version": 1,
+  "protocol_version": 1,
+  "command": "matrix.validate",
+  "ok": true,
+  "complete": true,
+  "data": { },
+  "diagnostics": [],
+  "context": { }
+}
+```
+
+- `schema_version` / `protocol_version` — bumped only on breaking envelope changes.
+- `command` — stable dotted command id.
+- `ok` — success boolean. `complete` — whether the operation ran to completion.
+- `data` — the command-specific payload (validated against that command's schema).
+- `diagnostics` — array of structured items, each with a stable `code` (see [error codes](./error-codes.md)).
+- `context` — workspace/component metadata.
+
+### Exit codes
+
+| Code | Meaning |
+|---:|---|
+| `0` | Success. |
+| `1` | Command failed / validation issues / required rows not FRESH. |
+| `2` | Unknown command or invalid arguments. |
+| `3` | Integrity blocked (matrix/evidence/ledger integrity failure). |
+| `4` | Unsafe path escape (data-root / repo boundary violation). |
+
+Additional trust-engine exit codes used by `prove` (e.g. untrusted append,
+signing-key missing) are documented in the CLI reference and are stable.
+
+## Experimental / not yet covered by the v1 contract
+
+These ship and work, but their **shape** may change in a minor release until
+promoted. They are called out here so adopters can depend on them with eyes open:
+
+- MCP **resources** (`uc://…`) and **prompts** are exposed and read-only, but
+  the exact URI/prompt set may grow in minor releases; treat the MCP *tool*
+  surface as the most stable MCP contract.
+- MCP output **rate-limiting** and **size caps**.
+- **Host profiles are a fixed built-in set for v1** (`claude`, `codex`,
+  `copilot`, `opencode`). The host-applicability/projection engine is generic,
+  but registering *custom* host profiles is a post-v1 extension; the trust core
+  (bind/verify/prove/freshness) is host-independent and unaffected.
+- The **trust-engine commands** (`bind`, `scan`, `verify`, `prove`,
+  `validate-ledger`) always emit JSON — they are machine/CI-oriented and have no
+  separate human-formatted mode (other commands gate JSON behind `--json`).
+- Non-GitHub-Actions CI authority adapters (the proof model is CI-neutral; only
+  the GitHub Actions reference workflow is a supported path at 1.0.0). The
+  CI-neutral authority contract, per-provider authority population, and the
+  opt-in release-gate authority requirement are documented in
+  [CI hardening](../security/ci-hardening.md).
+- Any other CLI command's **human-readable** (non-`--json`) formatting.
+- The `core` / `cli` / `mcp` workspaces are an internal implementation detail: they are bundled into the `use-cases` package, **not** a published programmatic import surface. The stable contract is the CLI, the MCP tools, the JSON envelope, the schemas, and the persisted file formats — not TypeScript imports.
+
+## Supported environments
+
+- **Node**: active LTS lines.
+- **CI**: GitHub Actions is the reference, first-class path. The verify/prove
+  contract is CI-neutral and documented for other providers (best-effort) in
+  [CI hardening](../security/ci-hardening.md), which also covers the opt-in
+  release-gate authority requirement (`release_gate.required_authority` /
+  `require_protected_ref`).
+- **Verifiers**: command verifiers for any language/toolchain. `pnpm`/`vitest`
+  is one preset, not an assumption.
+- **MCP transport**: local stdio. Remote/HTTP transport is **not** a v1 contract.
+
+## Changing a contract
+
+A breaking change to anything above requires: a major version bump, a CHANGELOG
+entry, and a migration note under `docs/migration/`. Additive changes ship in a
+minor with a CHANGELOG entry.

package/docs/release.md

@@ -0,0 +1,26 @@
+# Release Checklist
+
+Run the production release gate from the repository root:
+
+```bash
+node scripts/release-gate.mjs
+```
+
+The gate is intentionally sequential. Do not run `build` concurrently with
+`test`; tests import built workspace package outputs.
+
+Before release, inspect:
+
+- CI runs `node scripts/release-gate.mjs` on Node 22.
+- `doctor package` is complete and has no diagnostics. By default it builds and
+  inspects the real root package tarball, not just the checkout.
+- For external artifacts, use `doctor package --tarball <path> --json`.
+- For installed artifacts, use `doctor package --installed-root <path> --json`;
+  this also runs installed CLI and MCP smoke checks.
+- Root package contents include `.agents/skills`, `.codex-plugin/plugin.json`,
+  `.mcp.json`, built CLI/MCP/Core `dist`, schemas, docs, examples, and use cases.
+- Root package contents omit tests, TypeScript source, local session state,
+  build locks, `node_modules`, and coverage output.
+- Host docs do not claim verified support unless evidence IDs exist.
+- A real showcase run on this plugin is recorded if the release changes user
+  workflow.

package/docs/security/ci-hardening.md

@@ -0,0 +1,144 @@
+# CI hardening: the CI-neutral authority contract & release-gate requirement
+
+Use Cases proofs record **where and how they were produced** in a
+provider-agnostic `authority` block, and a repo can **require a minimum
+authority** before a `required_for_release` row is allowed to ship. This page
+covers the CI-neutral authority contract, the GitHub Actions reference path, how
+other CI providers populate authority, and the release-gate authority
+requirement.
+
+> Authority is about **provenance**, not freshness. A row is `FRESH` when scan
+> can verify a signed proof matching the current row / binding-set / verification
+> context (see [key management](./key-management.md)). The `authority` block is
+> **additive** and never changes that: legacy proofs minted before authority
+> existed still validate and stay `FRESH`. Authority only matters when a repo
+> **opts into** the release-gate requirement below.
+
+## The CI-neutral authority contract
+
+The trust model is **CI-neutral**: GitHub Actions is only the *reference*
+provider. Every proof event may carry an OPTIONAL `authority` block
+([`schemas/v1/authority.schema.json`](../../schemas/v1/authority.schema.json),
+`$id: …/schemas/v1/authority.schema.json`) describing who/where minted it:
+
+| Field | Meaning |
+|---|---|
+| `type` | `"ci"` when produced inside a recognised CI provider; `"local"` otherwise. |
+| `provider` | `github-actions` \| `gitlab-ci` \| `circleci` \| `generic`. `generic` is the local / unrecognised fallback. |
+| `repository` | Provider-shaped repo identifier (e.g. `owner/repo`). Best-effort. |
+| `ref` | The git ref / branch the run executed against. Best-effort. |
+| `commit` | The commit SHA the run executed against. Best-effort. |
+| `run_id` | The provider's run / pipeline / build id. Best-effort. |
+| `actor` | The login that triggered the run, when exposed. Best-effort. |
+| `event` | The triggering event name (`push`, `pull_request`, `merge_request`, …). |
+| `protected_ref` | **Tri-state**: `true`/`false` when the provider attests the protected-branch state, `null` when **unknown**. |
+
+The block is built **into the event before signing**, so the signature covers it
+— authority cannot be forged or altered after minting without breaking the
+proof's signature. The existing GitHub-shaped `producer` block is unchanged;
+`authority` is the CI-neutral trust record beside it.
+
+> **Honest about `protected_ref`.** It is **provider-attested where available and
+> otherwise unknown** (`null`). GitHub Actions does not expose a branch-protection
+> signal in the runner environment, so the reference path reports `null` unless
+> you supply the value out of band (see overrides below). GitLab CI exposes
+> `CI_COMMIT_REF_PROTECTED` and is read directly. A `null` (unknown) value never
+> satisfies a `require_protected_ref` gate — the gate fails closed.
+
+## How authority is populated
+
+`prove` fills the `authority` block automatically by auto-detecting the CI
+environment (pure `detectCiAuthority(env)` in `markers/ciAuthority.ts`), or you
+can supply it explicitly.
+
+### GitHub Actions (the reference path)
+
+Detected via `GITHUB_ACTIONS`. Fields are read from the standard runner env:
+
+| Authority field | Env var |
+|---|---|
+| `repository` | `GITHUB_REPOSITORY` |
+| `ref` | `GITHUB_REF` |
+| `commit` | `GITHUB_SHA` |
+| `run_id` | `GITHUB_RUN_ID` |
+| `actor` | `GITHUB_ACTOR` |
+| `event` | `GITHUB_EVENT_NAME` |
+| `protected_ref` | unknowable from the runner env → `null` (override to set) |
+
+No configuration is needed: running `uc prove …` inside a GitHub Actions job
+yields `type: "ci"`, `provider: "github-actions"`.
+
+### Other CI providers (auto-detected)
+
+The same auto-detection recognises:
+
+- **GitLab CI** (`GITLAB_CI`): `CI_PROJECT_PATH`, `CI_COMMIT_REF_NAME`,
+  `CI_COMMIT_SHA`, `CI_PIPELINE_ID`, `GITLAB_USER_LOGIN`, `CI_PIPELINE_SOURCE`,
+  and the explicit `CI_COMMIT_REF_PROTECTED` → `protected_ref`.
+- **CircleCI** (`CIRCLECI`): `CIRCLE_PROJECT_USERNAME`/`CIRCLE_PROJECT_REPONAME`
+  → `owner/repo`, `CIRCLE_BRANCH`, `CIRCLE_SHA1`, `CIRCLE_BUILD_NUM`,
+  `CIRCLE_USERNAME`. No protected-branch signal → `protected_ref: null`.
+- **Anything else** → `{ type: "local", provider: "generic" }`.
+
+### Unknown providers & overrides: `--authority-file`
+
+For a CI provider that is not auto-detected, or to attest a value the runner
+cannot expose (e.g. `protected_ref` on GitHub), pass a JSON authority record:
+
+```sh
+uc prove --all --trusted-ci \
+  --verification-results "$UCM_VERIFICATION_RESULTS" \
+  --signing-key-env UCM_CI_SIGNING_KEY --key-id ci-key-1 \
+  --authority-file authority.json
+```
+
+`--verification-results` is required — it is the unsigned results ledger written
+earlier by `uc verify --out "$UCM_VERIFICATION_RESULTS"`.
+
+```json
+{
+  "type": "ci",
+  "provider": "generic",
+  "repository": "owner/repo",
+  "ref": "refs/heads/main",
+  "commit": "0123…",
+  "run_id": "4242",
+  "protected_ref": true
+}
+```
+
+The file is validated against `authority.schema.json`, embedded, and signed.
+
+## The release-gate authority requirement
+
+By default the release gate does **not** look at authority — a `FRESH` required
+row passes regardless of how it was proved. A repo can **opt in** to a minimum
+authority via the OPTIONAL `release_gate` section of `use-cases.yml`:
+
+```yaml
+# use-cases.yml
+release_gate:
+  required_authority: ci        # matching proof must have authority.type === "ci"
+  require_protected_ref: true   # ...and authority.protected_ref === true
+```
+
+Semantics, in **release mode only**:
+
+- A `required_for_release` row whose only `FRESH` proof was minted with
+  **insufficient authority** — `type: "local"` when `required_authority: ci`, or
+  `protected_ref` not exactly `true` when `require_protected_ref: true`, or **no
+  authority block at all** — is **POLICY-BLOCKED**. It is surfaced in the
+  freshness / gate output with an `AUTHORITY_INSUFFICIENT` reason and counted in
+  `summary.policy_blocked`.
+- A required row that is already not `FRESH` is blocked exactly as before; the
+  authority gate is **purely additive** — it can only ever block an
+  *otherwise-`FRESH`* required row, never relax existing blocking.
+- **Feature mode is never affected**, and non-`required_for_release` rows are
+  never authority-blocked.
+- **Off by default.** Omit `release_gate`, or leave its fields unset, and gating
+  is exactly as it was — nothing changes for repos that do not configure it.
+
+This is the hardening lever: require that everything you ship was proved by **CI
+on a protected branch**, not on someone's laptop, while keeping the whole trust
+model CI-neutral (any provider that produces a `type: "ci"` /
+provider-attested-`protected_ref` proof satisfies the gate).

package/docs/security/key-management.md

@@ -0,0 +1,158 @@
+# Key management: signing keys, the keyring, rotation & revocation
+
+Use Cases proofs are **ed25519-signed** trusted-CI events. A row is only
+`FRESH` when scan/validate-ledger can verify the signature on a matching proof
+against a **trusted public key**. This page covers how those keys are managed:
+generating a keypair, the keyring file, rotating keys, revoking them, and the
+fail-closed guarantee that ties it all together.
+
+There are two ways to tell the tool which public key(s) to trust:
+
+| Flag | Trust model | Use when |
+|---|---|---|
+| `--public-key <file.pem>` | A **single** key, trusted unconditionally — only as safe as the file the verifier is pointed at, so commit it where the agent cannot swap it (see [threat model](../security.md#threat-model--what-holds-on-its-own-and-what-needs-setup)). | One signer, no rotation. The original, simplest path. |
+| `--keyring <file.json>` | A **registry** of keys, each with a status and validity window. | You need rotation and/or revocation. **Opt-in**, additive. |
+
+Both flags are accepted by `scan`, `verify`, `prove`, and `validate-ledger`.
+`--keyring` is strictly additive: if you never pass it, nothing changes. When
+both are present, the keyring wins.
+
+> The private signing key lives **only in trusted CI** (passed to `prove` via
+> `--signing-key-env <ENV>`, never written to the repo). The repo/config holds
+> only **public** keys.
+
+## Generating an ed25519 keypair
+
+The signing key is a **PKCS8 ed25519 PEM**; the public key is an **SPKI ed25519
+PEM**. Generate the pair with Node — this works everywhere the CLI runs and needs
+no external tools (macOS's bundled LibreSSL cannot `genpkey -algorithm ed25519`):
+
+```sh
+node -e 'const c=require("crypto"),f=require("fs");const{publicKey,privateKey}=c.generateKeyPairSync("ed25519");f.writeFileSync("ci-signing-key.pem",privateKey.export({type:"pkcs8",format:"pem"}));f.writeFileSync("ci-signing-key.pub.pem",publicKey.export({type:"spki",format:"pem"}));'
+```
+
+This writes `ci-signing-key.pem` (the **private** key — keep in CI secrets only,
+never commit) and `ci-signing-key.pub.pem` (the **public** key, for `--public-key`
+or the keyring). If you have OpenSSL ≥ 3 (not macOS LibreSSL) you can instead run:
+
+```sh
+openssl genpkey -algorithm ed25519 -out ci-signing-key.pem
+openssl pkey -in ci-signing-key.pem -pubout -out ci-signing-key.pub.pem
+```
+
+In CI, load the **private** PEM into an environment variable and point `prove`
+at it; tag the proof with the matching key id:
+
+```sh
+export UCM_CI_SIGNING_KEY="$(cat ci-signing-key.pem)"
+uc prove --all --trusted-ci \
+  --signing-key-env UCM_CI_SIGNING_KEY \
+  --key-id ci-key-1
+```
+
+The `--key-id` you sign with must match a `key_id` in the keyring (or be
+irrelevant under the single `--public-key` path, which ignores it).
+
+## The keyring file
+
+A keyring is a JSON file conforming to
+[`schemas/v1/keyring.schema.json`](../../schemas/v1/keyring.schema.json)
+(`$id: https://use-cases.dev/schemas/v1/keyring.schema.json`). It is a
+list of keys; each carries a stable id, the PEM public key, a validity window,
+and a status:
+
+```json
+{
+  "keyring_schema_id": "ucase-public-key-registry-v1",
+  "keys": [
+    {
+      "key_id": "ci-key-1",
+      "algorithm": "ed25519",
+      "public_key": "-----BEGIN PUBLIC KEY-----\n…\n-----END PUBLIC KEY-----\n",
+      "valid_from": "2026-01-01T00:00:00Z",
+      "valid_until": null,
+      "status": "active"
+    }
+  ]
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `key_id` | Stable id referenced by a proof signature's `key_id`. |
+| `algorithm` | Always `ed25519`. |
+| `public_key` | PEM-encoded ed25519 public key. |
+| `valid_from` | Start of the validity window (inclusive). |
+| `valid_until` | End of the window (inclusive), or `null` for open-ended. |
+| `status` | `active` (may verify proofs) or `revoked` (must not). |
+
+A `key_id` resolves to its public key **only when** the key exists, its status
+is `active`, and the **proof's `created_at`** falls inside
+`[valid_from, valid_until]`. The validity window is checked against the moment
+the proof was signed, not "now" — so a proof minted while a key was valid keeps
+verifying after the window closes only if you keep the key active; once the
+window closes or the key is revoked, the proof no longer verifies.
+
+Pass it to any verifying command:
+
+```sh
+uc scan --keyring keyring.json
+uc validate-ledger --keyring keyring.json
+```
+
+## Rotation
+
+Rotation introduces a new signing key without invalidating proofs already in the
+ledger. The order matters — **add then re-prove, revoke last**:
+
+1. **Generate** a new keypair (`ci-key-2`).
+2. **Add** `ci-key-2` to the keyring as `active`, and **keep `ci-key-1` active**.
+   At this point both keys verify, so every existing `ci-key-1` proof stays
+   `FRESH`.
+3. **Re-prove** the rows under `ci-key-2` (`prove … --key-id ci-key-2`). Because
+   the ledger is append-only, this appends fresh proofs signed by the new key;
+   the old proofs remain.
+4. **Revoke** `ci-key-1` (flip its `status` to `revoked`) only after every row
+   you care about has a current-key proof.
+
+A proof minted under an old key that is **still active** stays `FRESH`. The
+moment you revoke that old key, any row whose only proof was signed by it drops
+out of `FRESH` — which is exactly why you re-prove (step 3) before revoking
+(step 4).
+
+> Because the evidence ledger is append-only and **fail-closed**, revoking a key
+> that signed earlier, still-present ledger entries makes those specific entries
+> fail verification (a ledger-integrity error). Re-prove the affected rows under
+> a current key so each row again has a verifiable proof.
+
+## Revocation
+
+To stop trusting a key immediately (e.g. it leaked), set its `status` to
+`revoked` in the keyring. From that point:
+
+- Any proof signed by the revoked key no longer verifies.
+- A row whose only proof was that key falls to `UNPROVEN`/`SUSPECT` — **never
+  `FRESH`**.
+- Re-prove the row under a current, `active` key to restore `FRESH`.
+
+You do not delete the revoked entry: keeping it (as `revoked`) documents that
+the key was once known and is now untrusted.
+
+## The fail-closed guarantee
+
+Verification is **fail-closed**. A proof is `FRESH` only when the keyring
+positively vouches for its signing key at signing time. Every other case yields
+**not `FRESH`**:
+
+| Situation | Result |
+|---|---|
+| `key_id` not in the keyring | not FRESH (`UNKNOWN_KEY_ID`) |
+| key present but `status: revoked` | not FRESH |
+| proof `created_at` before `valid_from` | not FRESH |
+| proof `created_at` after `valid_until` | not FRESH |
+| signature does not verify | not FRESH (`BAD_SIGNATURE`) |
+| **active key, in window, valid signature** | **FRESH** |
+
+There is no "unknown key, allow anyway" path: an unrecognised, revoked, or
+out-of-window key resolves to nothing, so the proof cannot verify and the row
+cannot be `FRESH`.

package/docs/security.md

@@ -0,0 +1,66 @@
+# Security And Trust
+
+Generated plans, migration output, capsules, and host projections are prepared
+material only. They are not proof.
+
+## Threat model — what holds on its own, and what needs setup
+
+The freshness guarantee is cryptographic, but it is only ever as strong as the
+trust anchor you give it. This tool's whole point is to keep claims honest, so it
+is precise about what it enforces *by itself* versus what depends on how you
+deploy it. The adversary worth naming is an **autonomous agent with full shell
+access to the workspace** — the same actor the tool exists to keep honest.
+
+| Property | Enforced by the tool alone | Also requires |
+|---|---|---|
+| A `FRESH` row carries a valid signature over the current row / binding-set / verifier hashes — any drift flips it to `SUSPECT` | ✅ `scan` fails closed on drift, bad/unknown/revoked/out-of-window signatures | — |
+| That signature came from **trusted CI**, not a local actor | ❌ not on its own | The verifier must check against a **public key (or keyring) committed to the repo that the agent cannot swap**, *and* the private signing key must live **only** in a CI secret. Given a key it supplies or can generate, an actor with shell access can `prove` its own proof and `scan` it `FRESH`. |
+| The proof ledger has not been rewritten | ❌ not on its own — a local rewrite re-chains the hashes consistently | `validate-ledger --base-ref <ref>` against a **protected** branch the agent cannot force-push (branch protection on that ref). |
+| A required row was proven **on a protected branch** | ❌ | The release-gate authority requirement + the `protected_ref` attestation — see [CI hardening](./security/ci-hardening.md). |
+| "Approved by a human" on a showcase run | ❌ in v1 | The showcase approval ledger is **unsigned**; sign-off is **operationally** enforced (process / review), not cryptographically. See *Trusted user approval* below. |
+
+In short: **the cryptography proves "this proof was signed by the key you chose to
+trust."** Making that key mean *trusted CI rather than the local agent* is your
+deployment's job — commit the public key, keep the private key CI-only, protect
+the branch, and verify with `--base-ref` / a keyring. With that setup in place a
+local actor cannot manufacture `FRESH`. Without it the proofs are still useful
+integrity signals, but they are not a defence against an actor who controls the
+shell. See [key management](./security/key-management.md) for the keyring, the
+fail-closed table, and rotation/revocation.
+
+## Trusted user approval
+
+An agent can **request** approval but must not be able to **mint** it. In v1 only
+the negative half of that is real: `showcase approve` records an
+`untrusted_automation` authority, and the showcase run ledger is **not signed** —
+so a user-required run stays `pending` until approved out of band, and approval is
+enforced **operationally** (your review process), not cryptographically. There is
+no v1 code path that produces a cryptographically trusted user sign-off, and
+interactive-CLI confirmation is **not** one (an agent that drives the terminal can
+satisfy it). The signed-token approval path that closes this gap is specified in
+[ADR 0006](./adr/0006-trusted-user-approval-path.md); it is planned, not shipped.
+MCP tools can request approval but cannot fabricate it.
+
+Approval proof, once it exists, is bound to the generated plan hash and the finish
+event for the run. Generated plans, capsules, and runbooks are prepared material
+until a run records events against them.
+
+## Ledgers and history
+
+Append-only ledgers preserve accidental or disputed history through correction
+events. Normal commands do not physically delete evidence or showcase history.
+Physical purge for secrets or legal requirements needs a separate destructive
+workflow with explicit audit output. The append-only and hash-chain properties
+are **verifiable**, not self-enforcing: validate them against a trusted prior
+state (`validate-ledger --base-ref`) so a wholesale local rewrite is caught.
+
+## Hosts and packages
+
+Host profiles are expectation data. A host executable smoke result or projection
+manifest can help diagnose setup, but verified host support requires recorded
+evidence IDs.
+
+Package checks inspect real tarballs or installed package roots. They reject
+local/session state such as local agent cache and receipt directories, build
+locks, packaged `node_modules/`, coverage output, local absolute paths, and
+secret-looking values.