@adammcarter/use-cases 0.1.0

package/docs/getting-started.md

@@ -0,0 +1,296 @@
+# Getting started: zero to your first FRESH row
+
+This is the copy-pasteable path that takes a brand-new repo from nothing to a
+single use-case row that reaches **FRESH** — the state that means "trusted CI has
+signed proof that the current code, its binding, and its verifier context all
+still match."
+
+> **Read this first: only CI can mint FRESH.** A row goes FRESH when a verifying
+> command (`scan` / `validate-ledger`) can verify an **ed25519-signed proof**
+> against a **trusted public key**. The private signing key lives **only in
+> trusted CI** — never on a laptop, never in the repo. So locally you can author
+> rows, bind code, and run `scan` to *see* status, but the FRESH transition
+> itself happens in CI. Steps marked **(CI only)** below cannot be done from your
+> machine. This is the whole point of the trust model: an agent on a developer
+> box cannot manufacture a green check.
+
+Every command shown here is a real `uc` command. Concepts are linked to the
+[concept docs](./README.md); the deeper trust mechanics live under
+[`docs/concepts/`](./concepts/matrix.md).
+
+---
+
+## 1. Install the CLI
+
+```bash
+npm i -g use-cases
+```
+
+This puts the `uc` binary on your PATH. The same package also ships the
+companion MCP server binary `uc-mcp` if you want agents to drive the same
+commands — see [the MCP contract](./mcp.md).
+
+## 2. Scaffold the workspace with `uc init`
+
+One command takes a brand-new repo from nothing to a bindable, verifiable
+matrix — a workspace config plus an example row that already validates:
+
+```bash
+uc init --repo . --template js-vitest
+```
+
+- `--template` wires the default verifier: `generic` (a clearly-TODO placeholder
+  command), `js-vitest` (the `js.vitest` preset), `python-pytest`
+  (`python.pytest`), or `go-test` (`go.test`).
+- `--component <id>` sets the component id (otherwise it is derived from the
+  repo directory name).
+- `--force` overwrites an existing workspace; without it, `init` refuses rather
+  than clobber a `use-cases.yml` that already exists.
+- `--json` emits the standard result envelope; omit it for a human summary that
+  prints these next steps.
+
+It writes `use-cases.yml` and `use-cases/example.yml`. It never
+generates or writes a private key, and it does not create the GitHub workflow —
+those steps are below. The generated config looks like:
+
+```yaml
+schema_version: 1
+workspace_id: my-project
+component_id: my-project
+data_root: .
+use_cases_dir: use-cases
+evidence_dir: evidence
+demo_capsules_dir: demo-capsules
+showcase_runs_dir: showcase-runs
+default_workflow_mode: continuous
+verifiers:
+  default: acceptance
+  acceptance:
+    preset: js.vitest
+    evidence_kind: test_result
+```
+
+Use-case rows live in sharded YAML files under `use_cases_dir`. See
+[the matrix concept](./concepts/matrix.md). Replace the scaffolded
+`use-cases/example.yml` with a real row (next step).
+
+## 3. Add a use-case row
+
+Create `use-cases/billing/core.yml` with one row. Model it on a real, valid row —
+the shape below mirrors a row that ships in this repo:
+
+```yaml
+schema_version: 1
+feature:
+  id: billing.core
+  name: Billing
+  summary: Charges are computed and applied correctly.
+use_cases:
+  - id: billing.core.apply_discount
+    title: Apply a percentage discount to an order
+    lifecycle: active
+    value_tier: core
+    journey_role: golden
+    usage_frequency: common
+    tags: [billing, discount]
+    source_refs:
+      - kind: file
+        path: src/billing/discount.ts
+    actor: script
+    intent: Apply a percentage discount so the order total reflects the promotion.
+    preconditions:
+      - An order with at least one line item exists.
+    trigger: A valid discount code is applied to an order.
+    scenarios:
+      - id: billing.core.apply_discount.happy
+        kind: steps
+        steps:
+          - Apply a 10% code to a $100 order.
+          - Confirm the total is $90.
+    observable_outcomes:
+      - The discounted total is correct and never negative.
+    host_applicability:
+      - host_surface: codex.cli
+        supported: true
+    verification_policy:
+      mode: requirements
+      requirements:
+        - evidence_kind: test_result
+          required_verifiers: [acceptance]
+          minimum_count: 1
+    approval_policy:
+      mode: none
+```
+
+`verification_policy.mode: requirements` is what makes this row *provable*: it
+names a verifier id (`acceptance`) that CI must run and pass. We wire that id to a
+real command in step 6. (`mode: none` rows are tracked but never become FRESH —
+there is nothing to prove.)
+
+Validate the matrix:
+
+```bash
+uc matrix validate --repo . --json
+```
+
+`ok: true` / `complete: true` means the matrix is structurally clean.
+
+## 4. Mark the implementing code
+
+A **binding** ties the row to the exact code that satisfies it, using an in-code
+marker. Markers are language-agnostic comments. Wrap the implementing span with an
+explicit start/end pair (here in TypeScript, comment prefix `//`):
+
+```ts
+//: @use-case: billing.core.apply_discount
+export function applyDiscount(total: number, percent: number): number {
+  const discounted = total * (1 - percent / 100);
+  return Math.max(0, discounted);
+}
+//: @use-case: end billing.core.apply_discount
+```
+
+The grammar is `<comment>: @use-case: <slug>` … `<comment>: @use-case: end
+<slug>`. See [bindings & markers](./concepts/bindings.md).
+
+## 5. Register the binding with `uc bind`
+
+`bind` registers the marker in the append-only binding registry, but only after
+the edited file scans clean:
+
+```bash
+uc bind \
+  --repo . \
+  --row billing.core.apply_discount \
+  --file src/billing/discount.ts \
+  --mode explicit \
+  --start-line 1 \
+  --end-line 5
+```
+
+- `--mode explicit` uses the start/end marker pair you placed (`--start-line` /
+  `--end-line` are the inclusive span).
+- `--mode swift-func --line N` instead infers a Swift function body span from a
+  single marker placed before the declaration.
+- Already placed the marker yourself? add `--register-existing` so `bind` only
+  registers it without editing source. Use `--dry-run` to preview.
+
+The registry defaults to `.use-cases/bindings.jsonl` under your `data_root`
+(override with `--bindings`).
+
+## 6. Declare the verifier (config-driven, any language)
+
+The row's `required_verifiers: [acceptance]` is resolved **from config** — there
+is no hard-coded test runner. Point the `acceptance` id at a real command using a
+**preset** in `use-cases.yml`:
+
+```yaml
+# use-cases.yml (add this)
+verifiers:
+  default: acceptance
+  acceptance:
+    preset: js.vitest        # runs: npx --no-install vitest run tests/use-cases/{slug}.test.ts
+```
+
+`{slug}` is substituted with the row id everywhere it appears, so each row gets
+its own acceptance test path.
+
+Verifiers are **language-agnostic** — `js.vitest` is just one preset. A Python or
+Make project would instead write:
+
+```yaml
+verifiers:
+  default: acceptance
+  acceptance:
+    preset: python.pytest    # runs: pytest tests/use_cases/{slug}_test.py
+```
+
+```yaml
+verifiers:
+  default: acceptance
+  acceptance:
+    preset: make.target      # runs: make test-use-case SLUG={slug}
+```
+
+The available presets are `command.generic`, `js.vitest`, `js.npm-test`,
+`python.pytest`, `go.test`, and `make.target`. You can also inline an explicit
+`{ kind: script, command: [...], inputs: [...] }` on the row itself. Full model:
+[verifiers](./concepts/verifiers.md).
+
+> **Not a JS repo?** The [pure-Python tutorial](./tutorials/python-pytest.md)
+> walks the *whole* flow — bind → scan → verify → prove → FRESH — for a project
+> whose verifier is `pytest`, with no pnpm/vitest involved. Runnable example:
+> [`examples/python-pytest/`](../examples/python-pytest).
+
+Now write the acceptance test the preset names (e.g.
+`tests/use-cases/billing.core.apply_discount.test.ts`) and make it pass locally.
+
+## 7. See the status locally with `uc scan`
+
+```bash
+uc scan --repo . --product-root . --policy-mode feature --json
+```
+
+At this point the row is **UNPROVEN**: it is bound to current code, but no signed
+proof exists yet. That is expected and correct — you cannot sign locally. The five
+states (FRESH / SUSPECT / UNPROVEN / UNBOUND / INVALID) are explained in
+[bindings](./concepts/bindings.md).
+
+## 8. Let CI mint the proof — the row reaches FRESH **(CI only)**
+
+FRESH happens in a trusted CI pipeline, in two stages:
+
+1. **`verify` — keyless, runs on every PR.** It executes each bound row's resolved
+   verifier and writes an **unsigned** results ledger. It holds **no signing key**,
+   so a PR can prove its tests *ran and passed* without minting trust:
+
+   ```bash
+   uc verify --repo . --product-root . --all \
+     --out .use-cases/verification-results.jsonl --json
+   ```
+
+2. **`prove` — signs, runs only on the trusted branch.** It **consumes** the
+   unsigned results from `verify`, recomputes every hash itself, and mints an
+   ed25519-signed proof event. The private key is injected from a CI secret and is
+   the **only** place signing happens:
+
+   ```bash
+   uc prove --repo . --product-root . --all --trusted-ci --append \
+     --verification-results .use-cases/verification-results.jsonl \
+     --signing-key-env UCM_CI_SIGNING_KEY --key-id ci-key-1 \
+     --public-key .use-cases/trusted-ci-public-key.pem --json
+   ```
+
+   Because `prove` re-derives the hashes and signs from a key agents never see,
+   nobody can manufacture a passing proof by hand.
+
+Once that signed proof is persisted back to the repo, the next `scan` (with the
+trusted `--public-key` / `--keyring`) verifies the signature and the row is
+**FRESH**.
+
+Don't hand-roll this. Use the **GitHub Actions reference workflow** at
+[`.github/workflows/use-cases.yml`](../.github/workflows/use-cases.yml): it runs
+`validate-ledger` + `scan` on every push/PR, selects release mode on
+`main` / `release/**`, and runs the optional `verify` → `prove` → persist job that
+mints proofs from the `UCM_CI_SIGNING_KEY` secret. Generate the keypair following
+[key management](./security/key-management.md); the CI provenance/authority model
+is in [CI hardening](./security/ci-hardening.md).
+
+---
+
+## What you end up with
+
+| Stage | Command | Row state |
+|---|---|---|
+| Authored | `uc matrix validate` | (tracked) |
+| Bound | `uc bind …` | UNBOUND → UNPROVEN |
+| Verified in CI (PR, keyless) | `uc verify --out …` | UNPROVEN (results only) |
+| Proved in CI (trusted branch) | `uc prove --trusted-ci …` | **FRESH** |
+| Code/test later weakened | `uc scan` | SUSPECT |
+
+When you later change the implementation or weaken the test, the embedded hashes
+no longer match and the row drops to **SUSPECT** — the stale claim becomes
+visible instead of being silently trusted. Re-prove in CI to return to FRESH.
+
+Next: read the [concepts index](./README.md) to understand the matrix, bindings,
+verifiers, proofs, and evidence in depth.

package/docs/hosts.md

@@ -0,0 +1,30 @@
+# Host Support
+
+Use Cases treats Claude, Codex, Copilot, and OpenCode as first-class
+host families, but profile existence is not proof of support.
+
+| Host | Profile | Projection target | Current evidence rule |
+|---|---|---|---|
+| Claude | `hosts/claude.yml` | `.claude/use-cases.md` | Projection and executable smoke only; no verified support without evidence IDs. |
+| Codex | `hosts/codex.yml` | `.codex/use-cases.md` | Projection and executable smoke only; no verified support without evidence IDs. |
+| Copilot | `hosts/copilot.yml` | `.github/copilot/use-cases.md` | Missing or unavailable CLI reports `not_run`. |
+| OpenCode | `hosts/opencode.yml` | `.opencode/use-cases.md` | Missing executable reports `not_run`. |
+
+`host conformance --all` reports each host separately. `executable_smoke.status`
+can be `passed`, `failed`, or `not_run`. `not_run` is an exact reason, not a
+support claim. `evidence_event_ids` must stay empty until real host evidence is
+recorded.
+
+Each host row includes a `support` table:
+
+```text
+profile_available      profile was loaded as expectation data
+projected              this host's managed projection file matches expected content
+static_conformant      projection and canonical skill hashes match
+executable_smoke       passed | failed | not_run
+verified_with_evidence true only when evidence_event_ids is non-empty
+```
+
+Missing or unavailable executables produce warning-backed `not_run` results.
+Resolved executables that fail their smoke command produce failed conformance and
+exit non-zero, even when static projection files are present.

package/docs/markers-adoption.md

@@ -0,0 +1,100 @@
+# Use-case markers: adoption log
+
+First real binding of a use-case row to the code that implements it, dogfooded
+end-to-end with the real CLI.
+
+## Code markers
+
+A binding is anchored in the source by an in-code **marker comment**. `uc bind`
+writes them for you, but the grammar is small enough to read and hand-edit.
+
+### Grammar
+
+A marker is a single source line. After optional leading whitespace it is exactly:
+
+```
+<comment-prefix>: @use-case: <slug>          # start of a span
+<comment-prefix>: @use-case: end <slug>      # end of a span
+```
+
+- **`<comment-prefix>`** is the file's line-comment prefix, resolved **per file
+  extension** — `//` for `.ts/.tsx/.js/.jsx/.mjs/.cjs/.swift/.c/.cc/.cpp/.cxx/.h/.hpp/.m/.mm/.java/.kt/.kts/.go/.rs/.scala`,
+  and `#` for `.py/.rb/.sh/.bash/.zsh/.yaml/.yml/.toml/.pl/.r`. The map is
+  config-driven (`comment_prefixes.extensions` can add or override an extension).
+  An **extensionless** file (e.g. a `hooks/session-start` script) only carries
+  markers when it starts with a shebang (`#!`), in which case the prefix is `#`.
+- **`<slug>`** is **identity only**: a bare row id with an optional binding
+  suffix — `row-id["#"binding-suffix]`. The `row-id` is dotted lowercase idents
+  (`billing.checkout.happy_path`); the optional `#suffix` may also use `-`
+  (`billing.checkout#fast-path`). Any extra payload after the slug
+  (`fresh=`, `sha256=`, `role=`, a second token, …) is rejected — the marker
+  carries no state, only the link.
+
+Examples:
+
+```ts
+//: @use-case: billing.checkout.happy_path
+export function checkout() { /* … */ }
+//: @use-case: end billing.checkout.happy_path
+```
+
+```python
+#: @use-case: billing.checkout.happy_path
+def checkout():
+    ...
+#: @use-case: end billing.checkout.happy_path
+```
+
+### Bind modes
+
+| Mode | Markers | Span | Languages |
+|---|---|---|---|
+| **explicit** | a start marker **and** a matching `end <slug>` | the inclusive line range between them | any language with a known prefix |
+| **swift-func** | a **lone** start marker, no end | inferred from the Swift function body | Swift only |
+
+- **explicit** brackets a precise span; the start and end slugs must match and
+  spans must not nest. This is the portable default (`uc bind` explicit mode
+  takes `--start-line`/`--end-line`).
+- **swift-func** places a lone start marker immediately before a Swift `func`
+  declaration and infers the span from the function body (`uc bind` swift-func
+  mode takes `--line`). Inferred ends are **only** supported for Swift func — a
+  lone start marker in any other file fails closed and demands an explicit end.
+
+## Bound
+
+| Use-case row | Code |
+|---|---|
+| `evidence.ledger.crash_durable_ledger_writes` | `packages/core/src/durableWrite.ts` :: `fsyncBestEffortForTemp` (explicit span) |
+
+Registration: `.use-cases/bindings.jsonl`. Current status on a clean checkout:
+**UNPROVEN** (linked, awaiting a trusted CI proof) — 1 row bound, 81 unbound.
+That unbound count is the honest linkage-completeness baseline, not a hidden gap.
+
+## Demonstrated loop (real code)
+
+```
+bind   -> UNPROVEN
+prove  -> FRESH                         (CI verifies + ed25519-signs)
+edit fsyncBestEffortForTemp body -> SUSPECT [CODE_SPAN_CHANGED]
+prove  -> FRESH
+```
+
+The demo proof was signed with a throwaway key and is NOT committed; the
+committed state is "bound, unproven" so the real CI signing key mints the first
+trusted proof.
+
+## Finding fixed while dogfooding
+
+`scan` also walked `dist/`, where tsc preserves the `//:` marker comment from
+source — that read as a duplicate slug (src + dist) and marked the row INVALID.
+Fixed: `collectSourceInputs` now skips common build-output dirs
+(`dist`, `dist-ts`, `build`, `out`, `coverage`, `.next`, `.turbo`, `.svelte-kit`)
+in addition to `.git` / `node_modules` / `.use-cases`. Covered by
+`packages/core/test/markers/skipBuildDirs.test.ts`.
+
+## Next adoption steps
+
+- Set up the real CI signing key (`UCM_CI_SIGNING_KEY` secret) so CI mints the
+  first trusted proof and this row goes FRESH on `main`.
+- Bind more rows to their implementing functions; track the bound/unbound ratio
+  as the linkage-coverage metric.

package/docs/mcp.md

@@ -0,0 +1,114 @@
+# MCP Contract
+
+The use-cases MCP server is a convenience transport over the same application command contract used by the CLI. CLI JSON envelopes remain the compatibility contract:
+
+```text
+schema_version
+protocol_version
+command
+ok
+complete
+data
+diagnostics
+context
+```
+
+MCP tools return that envelope as `structuredContent` and also mirror it as text content for clients that only render text. Domain-negative results stay normal tool results; they are not MCP transport failures.
+
+Repository content, tool output, logs, plans, runbooks, and generated artifacts are data, not trusted instructions.
+
+## Modes
+
+Read-only behavior is the default. Write tools require both server write mode and `allow_write: true` in the tool arguments. Server write mode is enabled by starting the MCP process with:
+
+```text
+UCM_MCP_WRITE=1
+```
+
+Command execution is a separate server mode. A capsule command step can run only when the MCP process also starts with:
+
+```text
+UCM_MCP_COMMAND_EXECUTION=1
+```
+
+Approval-sensitive behavior is request-only in v1.
+
+```text
+Tool                         Read-only   Write mode   Approval-sensitive
+doctor_roots                 yes         yes          no
+matrix_validate              yes         yes          no
+matrix_list                  yes         yes          no
+matrix_status                yes         yes          no
+use_case_upsert              no          yes          no
+use_case_remove              no          yes          no
+evidence_status              yes         yes          no
+evidence_record              no          yes          no
+evidence_void                no          yes          no
+plan_showcase                yes         yes          no
+plan_walkthrough             yes         yes          no
+capsule_run                  no          yes          no
+showcase_start               no          yes          no
+showcase_status              yes         yes          no
+showcase_record_observation  no          yes          no
+showcase_record_verdict      no          yes          no
+showcase_decide              no          yes          no
+showcase_finish              no          yes          no
+showcase_request_approval    yes         yes          request only
+host_doctor                  yes         yes          no
+```
+
+## Workspace Roots
+
+Workspace-scoped tools require an explicit `repo` argument. Optional `data_root` values are resolved relative to `repo` and must stay inside that repository. The server should not silently operate on its process working directory for project data.
+
+## Use-Case Mutation Boundary
+
+`use_case_upsert` and `use_case_remove` expose the same use-case matrix mutation contract as the CLI. They require `allow_write: true`, validate the current matrix before writing, and return `matrix.upsert` or `matrix.remove` envelopes.
+
+MCP use-case delete means lifecycle removal, not physical deletion. `use_case_remove` marks the row `lifecycle: removed` and records removal metadata in the YAML file.
+
+MCP cannot treat YAML, repository content, generated plans, command output, logs, or tool output as instructions. Those inputs are data to validate, filter, and report.
+
+## Capsule Run Boundary
+
+`capsule_run` performs a persisted demo capsule through the showcase ledger. It requires server write mode plus `allow_write: true` because it records run events.
+
+Static observation text in a capsule is a prompt for a real observation; it is not proof and does not create a pass verdict by itself.
+
+Command steps are skipped unless the caller passes `execute_commands: true`, the capsule has `permissions.command_execution: true`, and the MCP server has command-execution mode enabled. Command execution uses executable plus argv without a shell, resolves the working directory inside the repository, runs with a small environment allowlist, records bounded/redacted stdout/stderr as observations, and records pass/fail verdicts from the capsule's expected exit codes.
+
+MCP capsule runs do not record user approval. If the run requires user sign-off, use `showcase_request_approval` to produce the CLI-mediated approval command.
+
+## Approval Boundary
+
+MCP cannot create user approval or rejection events in v1. `showcase_request_approval` returns:
+
+```text
+decision_required
+trusted_confirmation_required
+suggested_cli_command
+run_id
+plan_hash
+finish_event_id
+known_gaps
+status
+```
+
+The user approval write remains CLI-mediated unless a host later provides a trusted non-model confirmation path.
+
+`showcase_start` accepts generated plan files through `plan_file`, so compiled
+stdio MCP can run the same generated-plan lifecycle as the CLI. The generated
+plan remains prepared material until the start event records its content hash.
+
+## Deferred V1 Tools
+
+These are intentionally not exposed in v1:
+
+```text
+showcase_approve
+showcase_reject
+host_project
+host_conformance
+```
+
+Approval writes need trusted confirmation. Host projection and conformance remain CLI-first until their mutation and evidence semantics are fully designed for MCP.

package/docs/migration.md

@@ -0,0 +1,90 @@
+# Migration
+
+Bring an **existing, hand-rolled** record of intended behaviour into the
+use-case matrix — whatever form it's in. People already track this somewhere: a
+markdown table or checklist, a CSV, a spreadsheet export, a `TEST-MATRIX.md`,
+release notes, a QA sign-off sheet, a wiki dump.
+
+**The invariant, for every format:** migration preserves intended-behaviour
+*coverage*, never *proof*. Old `PASS` / `FAIL` / `DONE` marks, evidence links,
+screenshots, and sign-off text come across only as **review context** — they do
+not create evidence JSONL, showcase runs, approvals, host support, or verified
+status. Migrated rows land as **drafts** with zero proof; freshness is earned
+later by binding + verifying, never inherited.
+
+## Two paths
+
+- **Any format → the `migration` skill (general path).** A fixed parser can't
+  understand every hand-rolled layout, so the agent does the mapping: it reads
+  your file, infers its structure, and writes one reviewable **draft** use case
+  per item via `uc matrix upsert`, carrying the original text + provenance. Just
+  ask your agent to "migrate" / "bring in" / "import" your file and the bundled
+  `migration` skill activates. See `.agents/skills/migration/SKILL.md`.
+- **A standard `TEST-MATRIX.md` → `uc migrate test-matrix` (fast path).** For the
+  one canonical markdown-table format there's a deterministic importer that
+  already enforces the no-laundering invariant. Use it when your source fits.
+
+## TEST-MATRIX fast path
+
+Run a dry-run first:
+
+```bash
+uc migrate test-matrix \
+  --repo . \
+  --source TEST-MATRIX.md \
+  --out use-cases/_migrated \
+  --dry-run \
+  --json
+```
+
+Review the report:
+
+```text
+summary.rows_seen
+summary.rows_needing_review
+drafts[].output_path
+warnings[]
+would_write[]
+```
+
+Then write draft use cases:
+
+```bash
+uc migrate test-matrix \
+  --repo . \
+  --source TEST-MATRIX.md \
+  --out use-cases/_migrated \
+  --write \
+  --json
+```
+
+## Safety Rules
+
+Dry-run writes no files.
+
+Write mode only writes draft YAML and a migration manifest under the selected output directory. It never writes:
+
+```text
+evidence/
+showcase-runs/
+host projection files
+TEST-MATRIX.md
+```
+
+Output paths must stay inside the workspace data root. Keep migrated files under `use-cases/_migrated/` until a human reviews and reshapes them.
+
+## Review Context
+
+Generated use cases include source references like:
+
+```text
+TEST-MATRIX.md#table-1-row-3
+```
+
+Legacy status, evidence text, and notes are stored under the migration extension as review context. Current proof must be created later with evidence or showcase flows.
+
+The key invariant:
+
+```text
+Legacy matrix status is historical context, not current proof.
+```