@adammcarter/use-cases 0.1.0

package/docs/adr/0004-p3-evidence-ledger-contracts.md

@@ -0,0 +1,85 @@
+# ADR 0004: P3 Evidence Ledger Contracts
+
+## Status
+
+Accepted.
+
+## Context
+
+P3 records observed proof as append-only JSONL and derives current evidence
+state mechanically. Evidence must not become approval, verification-policy
+satisfaction, or final sign-off.
+
+An external reasoning model reviewed P3 before implementation and identified fail-open risks in loose
+replay ordering, damaged-line handling, and idempotency scope.
+
+## Decision
+
+Evidence replay uses aggregate `sequence` as the sole order authority.
+`recorded_at` is audit/display metadata, and `event_id` is identity only. A
+duplicate or missing aggregate sequence invalidates that aggregate.
+
+Replay continues after damaged ledger input to recover inspectable state, but
+damage is not hidden:
+
+```text
+torn final line
+  excluded from replay
+  complete=false
+
+unparseable complete line
+  unknown_scope_damage=true
+  complete=false
+
+invalid aggregate history
+  affected aggregate status=invalid
+  complete=false
+```
+
+Normal append operations use a data-root-wide evidence append lock:
+
+```text
+evidence/.locks/append.lock
+```
+
+That lock covers replay, idempotency lookup, event generation, sequence
+allocation, append, file fsync, and result construction. P3 reports the actual
+durability class it achieved.
+
+Idempotency scope is:
+
+```text
+data_root + operation intent + idempotency_key
+```
+
+The persisted `intent_digest` excludes generated fields such as `event_id`,
+`sequence`, `recorded_at`, aggregate ID, and storage path. A retry with the same
+key and same digest returns the original event and appends nothing. A retry with
+the same key and a different digest fails closed.
+
+Evidence targets stable use-case IDs and captures the P2 semantic hash at the
+time of evidence recording. Matrix linkage is a separate operation from replay:
+
+```text
+replay evidence
+  independent of current YAML/files
+
+link evidence to matrix
+  resolves IDs/scenarios through P2
+  compares semantic hash freshness input
+```
+
+Assurance is represented as deterministic facets and a convenience class. P3
+does not emit approval, user sign-off, verification-satisfied, final-pass, or
+policy-satisfied state.
+
+## Consequences
+
+P4 can wrap evidence append/status as stable CLI JSON without inventing replay
+semantics.
+
+P9 can expose MCP tools safely because evidence recording cannot impersonate
+user approval.
+
+Later showcase and verification layers can combine P2 intended behavior and P3
+evidence history without changing the append-only ledger contract.

package/docs/adr/0005-p4-cli-contract.md

@@ -0,0 +1,70 @@
+# ADR 0005: P4 CLI Contract Semantics
+
+## Status
+
+Accepted.
+
+## Context
+
+P4 makes the CLI the normative public contract that later MCP tools will reuse.
+P2 and P3 already expose schema-backed JSON envelopes, so P4 must refine the
+existing contract without introducing a second envelope shape.
+
+An external reasoning model reviewed P4 before implementation and found that the plan conflated
+command execution success, domain validity, input completeness, and process
+exit status.
+
+## Decision
+
+The v1 JSON envelope remains:
+
+```text
+schema_version
+protocol_version
+command
+ok
+complete
+data
+diagnostics
+context
+```
+
+Meanings are separate:
+
+```text
+ok
+  the requested command contract executed successfully
+
+complete
+  every relevant input was safely considered
+
+data.*
+  command-specific domain result
+
+exit status
+  shell-level classification
+```
+
+For example, `matrix validate` on damaged input exits `1`, keeps `ok:true`,
+sets `complete:false`, and returns `data.valid:false`.
+
+Strict mode is an integrity policy. It does not change parsing, diagnostics, or
+domain state; it only changes whether incomplete state is accepted for the
+requested operation.
+
+Workflow mode is advisory configuration, not evidence history. `workflow
+set-mode` updates the owning workspace config atomically and persists canonical
+P1 enum values. It cannot relax schema validation, path policy, evidence
+integrity, strictness, or approval requirements.
+
+P4 also adds read-only `doctor roots`, composed `matrix status`, and evidence
+voiding. Evidence void appends a terminal event and leaves prior JSONL bytes
+unchanged.
+
+## Consequences
+
+P9 can map MCP calls onto the same CLI/application semantics without treating
+negative domain results as transport failures.
+
+Future presentation and showcase layers can rely on workflow mode as guidance
+only, not as a hidden enforcement switch.

package/docs/adr/0006-trusted-user-approval-path.md

@@ -0,0 +1,125 @@
+# ADR 0006 — Trusted user-approval path (showcase sign-off)
+
+Status: proposed (roadmap row `roadmap.deferred.trusted_host_confirmation_path`).
+
+## Context
+
+A showcase run can require user approval (`approval_policy.mode: predefined`,
+`approver_type: user`). The trust thesis is: an autonomous agent may **perform
+and record** work but must **not be able to mint a human's sign-off**.
+
+Today the negative half holds and the positive half is missing:
+
+- `appendShowcaseApproval` accepts an approval only from a **trusted authority**
+  (`trusted_interactive_cli` with `stdinIsTty && confirmed`, or
+  `trusted_host_token` with `verified`); anything else is `untrusted_automation`
+  and is rejected with `showcase.trusted_user_confirmation_required`.
+- But the **CLI `showcase approve` hard-codes `authority: untrusted_automation`**.
+  There is no code path that ever produces a trusted authority. So a real human
+  cannot grant sign-off either — user-required runs sit at `approval_state:
+  pending` forever.
+
+This ADR records the design for the path that lets a real human approve while an
+agent cannot — without weakening the guarantee.
+
+## Decision
+
+Approval trust comes from a **non-forgeable signed token**, not from "a process
+saw a `y` on a TTY". The boundary is: a trusted issuer **outside the agent's
+controllable I/O** signs an approval statement **bound to the exact run**
+(run id, ledger head, evidence digest, git commit, CI-freshness digest, a
+short-lived single-use nonce). The plugin **verifies** the signature against a
+protected keyring (the same model already used for CI freshness proof).
+
+### Why not TTY confirmation
+
+A modern coding agent already drives interactive terminals — it can allocate a
+pseudo-TTY, read the prompt, and type the answer. A randomized challenge phrase
+only converts *blind* automation into *interactive* automation, which agents
+already are. TTY confirmation is therefore a **speed bump, not a trust root**: it
+defends against pipes / `yes` / CI / blind scripts, never against an agent that
+controls the terminal.
+
+### Invariant (load-bearing)
+
+The verifier **computes** trust; it must **never** accept a caller-supplied
+`verified`/`confirmed` boolean. The current `TrustedApprovalAuthority` type
+(`{ kind: "trusted_host_token"; token; verified: boolean }`) is a footgun — the
+boolean is asserted by the caller. The future implementation MUST replace it with
+a caller input that carries only the token, and a verifier that derives
+`verified` from a signature check. (No code path constructs a trusted token
+today, so this is latent, not yet exploitable — but it must not ship wired.)
+
+### Assurance levels, not a boolean
+
+Replace `trusted iff stdinIsTty && confirmed` with explicit tiers, and let
+`approval_policy` choose the floor:
+
+| Authority input | Assurance | trustedForHumanSignoff |
+|---|---|---|
+| `untrusted_automation` | none | false |
+| `interactive_cli_challenge` (hardened TTY) | `same_channel_operator_confirmation` (agent-spoofable) | **false** |
+| `host_signed_approval_token` (verified) | `trusted_host_user_presence` | true |
+| `webauthn_approval_assertion` (UP/UV) | `hardware_user_presence_or_verification` | true |
+
+`trusted_interactive_cli` is **relabelled** to make its spoofability explicit; it
+is excluded from any policy that requires non-spoofable human sign-off.
+
+### Flow
+
+```
+agent / CLI / MCP may REQUEST approval
+   -> ApprovalRequested { run_id, showcase_id, ledger_head_hash, evidence_digest,
+                          git_commit, ci_freshness_digest, nonce, exp }
+   -> trusted issuer confirms with a real human OUTSIDE agent control
+      (host dialog / OS auth / WebAuthn / out-of-band page)
+   -> issuer signs an approval token bound to that exact request
+   -> plugin verifies signature against the protected keyring + checks
+      audience, run binding, nonce/jti single-use, expiry, policy floor
+   -> append ApprovalGranted
+```
+
+### MCP
+
+MCP **elicitation** is the UX transport, not the proof. A raw `accept` from an
+MCP client is protocol data, not a human signature. Elicitation (form mode, or
+URL mode for out-of-band) requests the approval and shows context; the proof is
+the resulting signed token the plugin verifies.
+
+## Ranked build plan
+
+1. `ApprovalRequested` object (nonce + run/evidence/ledger digest binding) and a
+   **signed approval-token verifier** (reuse the existing keyring/Ed25519 infra).
+2. A **local approval broker / host token issuer** — signing key outside the
+   workspace (OS keychain / hardware-backed), native dialog or browser page,
+   optional WebAuthn.
+3. **MCP elicitation** integration that hands off to the issuer.
+4. **Hardened TTY** (`/dev/tty`, both ends ttys, randomized single-use challenge,
+   nonce-bound) as a clearly-labelled **weak** fallback, excluded from
+   non-spoofable-required policies.
+
+Defer: WebAuthn-only mode, separate-device approval, org key policy + revocation,
+approval transparency log, multi-approver quorum.
+
+## Threat boundary
+
+| Boundary | Agent can spoof? |
+|---|---|
+| CLI flag / stdin / `/dev/tty` prompt / TTY challenge | yes (agent drives the terminal) |
+| MCP raw `accept` | depends on client; not proof alone |
+| Host-signed token (protected key) | no, unless host/key compromised |
+| WebAuthn / OS biometric assertion | much harder |
+| Separate-device approval | hardest locally |
+
+## Product language
+
+> "An agent can REQUEST approval but cannot MINT it. Trusted approvals require a
+> signed confirmation from a configured approval issuer."
+
+Never claim "a terminal prompt proves a human approved."
+
+## Provenance
+
+Design reviewed with an external reasoning model. This ADR is
+the spec for `roadmap.deferred.trusted_host_confirmation_path`; the row stays
+`lifecycle: planned` until the verifier + an issuer ship.

package/docs/cli.md

@@ -0,0 +1,108 @@
+# CLI Reference
+
+All commands use JSON envelopes with `schema_version`, `protocol_version`,
+`command`, `ok`, `complete`, `data`, `diagnostics`, and `context`.
+
+## Onboarding
+
+- `uc init [--repo <dir>] [--template generic|js-vitest|python-pytest|go-test] [--component <id>] [--force] [--json]`:
+  scaffold a minimal working workspace — a `use-cases.yml` (with a
+  `verifiers.default` matching the template) and a `use-cases/example.yml` whose
+  one row already validates. The scaffolded workspace passes `matrix validate`
+  immediately. `init` never generates or writes a private key and never creates
+  the GitHub workflow; it prints the next steps (key setup, CI workflow) instead.
+  It refuses to overwrite an existing `use-cases.yml` unless `--force`
+  is given. Omit `--json` for a human-readable summary.
+
+## Matrix
+
+- `matrix validate --repo <path> --json`: load all sharded YAML use cases and
+  report structural integrity.
+- `matrix list --repo <path> --json`: list addressable use cases. Filters:
+  `--value`, `--journey-role`, `--lifecycle`, `--host`, `--tag`,
+  `--changed-path`.
+- `matrix status --repo <path> --json`: combine matrix integrity and evidence
+  replay status.
+- `matrix upsert --repo <path> --file <path> (--use-case-json <json> | --use-case-file <path>) --json`:
+  add or update one use-case entry in an existing feature file. `--file` is the
+  destination feature YAML; supply the row payload either inline with
+  `--use-case-json '{...}'` or from a JSON file with `--use-case-file <path>`.
+  A row with `lifecycle: active` must include the conditionally-required fields
+  (`actor`, `intent`, `preconditions`, `trigger`, `scenarios`,
+  `observable_outcomes`, `host_applicability`, `verification_policy`,
+  `approval_policy`).
+- `matrix remove --repo <path> --use-case <id> --reason <text> --json`:
+  mark a use case as `removed`. This is a lifecycle change, not physical
+  deletion.
+
+## Evidence
+
+- `evidence record --repo <path> --use-case <id> --kind <kind> --result <result> --json`
+  appends one evidence event.
+- `evidence status --repo <path> --json` replays append-only JSONL history.
+- `evidence void --repo <path> --evidence <id> --expected-head <event-id> --reason <text> --json`
+  records a correction event without deleting history.
+
+## Markers & Trust
+
+The trust flow ties a behaviour row to code and marks it `FRESH` only when trusted
+CI has signed proof that the current code, binding, and verifier still match. The
+signing key must be a PKCS8 ed25519 PEM — see
+[key management](./security/key-management.md) for how to generate one.
+
+- `uc bind --row <id> --file <path> --mode explicit --start-line <n> --end-line <n> [--repo <path>] [--json]`:
+  bind a row to a code span. `--mode explicit` inserts `//: @use-case: <id>` …
+  `//: @use-case: end <id>` markers around the span (the comment prefix is inferred
+  per file type). Use `--register-existing` to register a span whose markers are
+  already present in the file instead of inserting new ones. Note: inserting the
+  opening marker shifts the file's line numbers down by one, so a later `scan`
+  reports the span one line below the `--start-line`/`--end-line` you passed —
+  that is expected, not drift.
+- `uc scan [--repo <path>] [--public-key <pem>] [--keyring <path>] [--json]`:
+  derive each row's freshness — `FRESH` / `SUSPECT` / `UNPROVEN` / `UNBOUND` /
+  `INVALID` — from the current code, the binding registry, and the proof ledger.
+  Without a trusted `--public-key` (or `--keyring`), signed proofs read `UNPROVEN`
+  (the tool never trusts a signature it cannot verify).
+- `uc verify [--row <id> | --all] --out <path> [--repo <path>] [--json]`: run each
+  bound row's verifier command and write an **unsigned** verification-results
+  ledger (one JSONL record per row). This is the step that actually executes tests.
+- `uc prove (--row <id> | --all) --verification-results <path> --trusted-ci --signing-key-env <ENV> [--key-id <id>] [--append] [--repo <path>] [--json]`:
+  mint **signed** ed25519 proof events from the `verify` results. Signing is
+  CI-only: the private key is read from the named environment variable and never
+  written to disk. A present-but-malformed key returns a `signing_key.invalid`
+  diagnostic rather than crashing.
+- `uc validate-ledger [--repo <path>] [--json]`: check the append-only proof/
+  evidence ledger for integrity (hash-chain, ordering, signature shape).
+
+## Planning And Showcases
+
+- `plan showcase --repo <path> --json` selects high-value live-demo items.
+- `plan walkthrough --repo <path> --json` selects broader review coverage.
+- `plan cards --repo <path> --plan-file <path> --json` renders presentation cards
+  from a saved plan file.
+- `capsule validate|list|plan --repo <path> --json` works with persisted demo
+  capsules.
+- `capsule run --repo <path> --capsule <id> --json` performs a persisted demo
+  capsule as a live showcase run. Command steps stay pending unless
+  `--execute-commands` is passed and the capsule permits command execution.
+- `showcase start|record-observation|record-verdict|decide|pause|resume|finish|approve|reject|correct`
+  records a mechanical showcase run ledger.
+
+## Hosts And Doctors
+
+- `host project --host <host> --repo <path> --dry-run|--write|--revert --json`
+  projects or removes thin activation stubs.
+- `host doctor --host <host> --repo <path> --json` checks profile and projection
+  visibility.
+- `host conformance --host <host> --repo <path> --json` checks one profile.
+- `host conformance --all --repo <path> --json` checks Claude, Codex, Copilot,
+  and OpenCode.
+- `doctor roots|skills|package --repo <path> --json` checks workspace roots,
+  canonical skills, and release packaging.
+
+## Migration
+
+- `migrate test-matrix --repo <path> --source TEST-MATRIX.md --dry-run --json`
+  previews draft use cases.
+- `migrate test-matrix --repo <path> --source TEST-MATRIX.md --out use-cases/_migrated --write --json`
+  writes reviewed draft YAML. Old status and evidence stay review context only.

package/docs/data-model.md

@@ -0,0 +1,56 @@
+# Data Model
+
+Project data lives under the configured `data_root`; installed plugin code is
+read-only.
+
+## Directory layout at a glance
+
+Two pairs of similarly-named paths are deliberately distinct — the dot-prefixed
+ones are tool-managed machine state (like `.git`), the others are yours:
+
+| Path | Owner | Holds |
+|---|---|---|
+| `use-cases/` | you (authored) | the sharded use-case matrix YAML |
+| `.use-cases/` | the tool (machine state) | the code-marker **binding registry** + **signed proof** ledger + the trusted public key |
+| `evidence/` | the tool (append-only) | **use-case evidence** events (observations, results) keyed by id |
+| `showcase-runs/` | the tool (append-only) | performed **showcase run** event ledgers |
+
+Don't confuse `evidence/` with the proof ledger: `evidence/` holds **use-case
+evidence** (observations attached to use cases), while `.use-cases/proofs.jsonl`
+is the marker-freshness **proof** ledger (CI-signed). The names now make the
+distinction plain — proofs vs evidence. Both are append-only and content-addressed.
+
+## Use Cases
+
+Use cases are sharded YAML files under `use-cases/`. Each file describes one
+feature and one or more behavior rows. Active rows include actor, intent,
+scenarios, observable outcomes, host applicability, verification policy, and
+approval policy.
+
+Damaged YAML does not bring the matrix down. Valid siblings stay addressable and
+diagnostics explain damaged files, duplicate IDs, broken references, and unsafe
+paths.
+
+## Evidence
+
+Evidence is append-only JSONL under `evidence/`. Corrections, voids,
+invalidations, and supersessions are new events. Normal workflows do not rewrite
+or delete old lines.
+
+## Showcases
+
+Showcase runs are append-only JSONL under `showcase-runs/<run-id>/events.jsonl`.
+Prepared plans are not proof. A run becomes proof only after observations,
+verdicts, finish events, and any required approval are recorded.
+
+## Demo Capsules
+
+Demo capsules are optional persisted scripts under `demo-capsules/`. Most runs
+can stay ad hoc; persisted capsules are best for smoke demos and common golden
+paths.
+
+## Host Profiles
+
+Host profiles under `hosts/` define expectations for Claude, Codex, Copilot,
+and OpenCode. A profile is not support proof. Conformance and evidence state are
+separate.