pincer-workflow 0.4.1 → 0.6.0

package/template/.agents/skills/pincer-release/SKILL.md

@@ -28,9 +28,13 @@ durable runtime-owned release record is later work.
 3. Check every applicable item mechanically where possible:
    - File existence and frontmatter: read the files.
    - Commit format and story: `git log --oneline`.
-   - Receipts: every done ticket carries current `last_check` and `verified` evidence;
-     any status warning fails the audit. Do not call `pincer-ticket.sh` from Release:
-     it writes receipts and would invalidate the evaluated candidate.
+   - Receipts: every done ticket is ready — on a legacy project current `last_check`
+     and `verified` receipts, on a migrated project a current passing attempt
+     (`node scripts/pincer-runtime.cjs ready` exits 0); any status warning fails the
+     audit. Do not call `pincer-ticket.sh` from Release:
+     it writes receipts and would invalidate the evaluated candidate. Release never
+     runs `verify`, `check` or `done`; `status`, `ready` and the project gate are its
+     only commands.
    - Evidence: `scripts/pincer-status.sh` runs the shared validator
      (`scripts/pincer-evidence.cjs`) against the manifest `NOTES.md` names. The `Notes`
      line must read `current` and the `Evidence` line `ok`; any other text fails the
@@ -38,6 +42,31 @@ durable runtime-owned release record is later work.
      screenshots described in chat: read the manifest's `checks`, requirement
      dispositions and `visual_review`. Validation establishes that the record is
      consistent, not that the commands ran — say so if asked.
+   - Provenance: status prints a `Provenance` line for the evaluated candidate:
+     `runtime (schema 2)` with local attempts consistent, or `legacy (schema 1, authored
+     command results)`. A newer local attempt that failed, timed out, was interrupted or
+     is still running for the same check and source inputs fails the audit (`ready`
+     exits 1 and names the check). A fresh clone reports `local verification history
+     unavailable; saved candidate evidence validated only`: state that limit in the
+     verdict rather than claiming local verification.
+   - Change records (the `Runtime` line reads `changes`): the selected change is
+     `completed`, its authorization is `current` for the current agreement, and its
+     evaluation locator `.prd/evidence/changes/<id>.json` names the evaluated
+     candidate; `node scripts/pincer-runtime.cjs ready` reports `SELECTION_REQUIRED`,
+     `LIFECYCLE_BLOCKED`, `DECISION_REQUIRED`, `AUTHORIZATION_REQUIRED` or
+     `AGREEMENT_CHANGED` as failures. Release selects, activates and completes nothing;
+     historical evidence of a cancelled or superseded change is inspectable but never
+     release-ready.
+   - Strict coverage (the status line reads `Coverage strict …`): read
+     `node scripts/pincer-runtime.cjs coverage` — structure complete, every in-scope
+     scenario `delivered` on the evaluated candidate, deferrals and removals backed by
+     their decision and user authorization, `delivery` reported as original versus
+     agreed scope (never conflate them), adequacy `adequate`; the manifest is schema 3
+     and the `Provenance` line reads `runtime (schema 3)`. `ready` names
+     `COVERAGE_INCOMPLETE`, `SCOPE_UNAUTHORIZED`, `OBLIGATION_MISSING`,
+     `REVIEW_MISSING` and `ADEQUACY_REQUIRED` as failures. A change labeled
+     `Coverage unverified` did not adopt strict coverage: audit it under the rules
+     above and say so; never imply strict coverage was established.
    - Every file the manifest lists is tracked, and `git status --short` is empty before
      and after the audit.
    - Run the repository's candidate-wide release gate directly (`npm test`, or the

package/template/.agents/skills/pincer-status/SKILL.md

@@ -15,13 +15,36 @@ start of a session. Read-only: change nothing.
 1. Run `scripts/pincer-status.sh`. It reads the artifacts on disk (`.prd/`, `tickets/`,
    `NOTES.md`) and prints the PRD state and profile, every ticket with its state and
    clock-based elapsed time, what is blocked, wall-clock build time while a ticket is in
-   progress or against an explicit user budget, the evidence verdict for the evaluated
+   progress or against an explicit user budget, the `Runtime` line (legacy receipts or
+   the registered change), the evidence verdict and `Provenance` line for the evaluated
    candidate, any warnings (each readiness problem once), and the next command to run.
+   `scripts/pincer-status.sh --json` prints one status object with reason codes and the
+   next action for tooling; `node scripts/pincer-runtime.cjs ready [T-NN]` is the
+   read-only gate. On a project with change records (`Runtime  changes …`) run
+   `node scripts/pincer-runtime.cjs resume` as well: it reports the selected change, its
+   lifecycle, agreement and authorization, decisions, references, tickets, attempts,
+   candidate, the authored handoff note and the next command, and never writes;
+   `change list` shows every retained change, `status --change <id>` and
+   `resume --change <id>` inspect another one without selecting it. `resume` is the
+   report; `change resume <id>` is the lifecycle operation. The `Coverage` line says
+   `strict` or `unverified`; on a strict change `node scripts/pincer-runtime.cjs coverage`
+   (and `impact` after an edit) name the exact scenario, ticket, check or decision
+   that is next — quote them rather than inferring coverage from the ticket list.
 2. Report in three lines: where the workflow is, what is in progress or blocked, and the
-   next command. Quote the `Next` line as-is.
+   next command. Quote the `Next` line as-is. When the `Runtime` line says `legacy`,
+   add the register or migrate command it names as the step that precedes the next
+   ticket (fresh project → `register`, legacy receipts → `migrate --preview`, a v0.5.0
+   binding → `migrate --preview`, no selection → `change select <id>`).
 3. If a ticket is `in_progress`, read it and `git status`, then offer to resume it with
    `$pincer-code T-{NN}`. If the script printed a warning, surface it — a done ticket
    without a receipt was marked by hand and needs `scripts/pincer-ticket.sh verify T-{NN}`.
    Never restore a ticket file from git to clear a warning; a failed attempt is a record.
    The one exception is the tree-back-at-candidate case in the recovery section of
    `$pincer-code`: the user restores the ticket file, and nothing is verified or committed.
+   It applies only when the recorded failure is explained by a since-reverted source
+   change and the block passes in the same execution context as `verify`; an
+   unexplained failure (a service down, a missing dependency) stays a failure until the
+   environment is repaired and `verify` passes again. After migration never restore a
+   ticket file or delete `.pincer/runtime` to clear a warning: repair the cause and run
+   `verify` again; a dead session's `running` attempt is finalized by
+   `node scripts/pincer-runtime.cjs recover`.

package/template/.claude/commands/pincer-code.md

@@ -16,6 +16,17 @@ Ticket state lives in the ticket file's frontmatter and is written **only** by
 Verification block and stamps a receipt only on a green exit; `done` refuses without a
 receipt that matches the current check, or with unticked acceptance criteria. Never edit
 `status`, `started`, `last_check`, `verified`, or `finished` by hand — on Claude Code a hook blocks it.
+On a migrated project (a change binding under `.prd/changes/`; the `Runtime` line of
+`scripts/pincer-status.sh` names it) `verify` records an attempt under `.pincer/runtime/`
+and writes no receipt into the ticket, and `done` consumes the current passing attempt
+against the current source without re-running the check. `.pincer/`, `.prd/changes/` and `.prd/evidence/changes/`
+are written only by the runtime; never edit or delete them by hand. On a project with
+change records (`Runtime  changes …`) every `start`, `verify` and `done` first passes
+the change gate: the ticket's change must be selected in this worktree, `active`
+(`verify` also runs on a `completed` change), on a compatible branch, and authorized
+for the current agreement — otherwise the command refuses with `SELECTION_REQUIRED`,
+`WRONG_CHANGE`, `LIFECYCLE_BLOCKED`, `BASE_MISMATCH`, `DECISION_REQUIRED`,
+`AUTHORIZATION_REQUIRED` or `AGREEMENT_CHANGED` before anything runs or is written.
 
 ## Before the loop
 
@@ -23,7 +34,34 @@ Run `scripts/pincer-status.sh`. It lists every ticket's state, what is blocked,
 build time from the clock, and the next action. If a ticket is `in_progress`, you are
 resuming: read it, check `git status` / `git diff` for uncommitted work, and continue
 from wherever the receipt says you are. Do not ask the user to reconfirm unchanged,
-previously authorized work.
+previously authorized work. Read the `Runtime` line before the first ticket. `changes` (change records under
+`.prd/changes/`) → run `node scripts/pincer-runtime.cjs resume` and follow its `Next`
+line: it names the selected change, its lifecycle state, the agreement and the
+authorization verdict, the blockers in order and the exact next command, all from the
+files on disk. Select the change to work on (`node scripts/pincer-runtime.cjs change
+select <id>`; selection is local metadata and touches no source), activate it
+(`change activate <id>`; refused until the user's authorization is recorded with
+`change authorize` and no consequential decision is open) and resume a paused change
+with `change resume <id>`. On a change with strict coverage (`Coverage strict …` in status) also read
+`node scripts/pincer-runtime.cjs coverage` — it names the scenario, ticket, check or
+decision that is next and every structural gap (`COVERAGE_INCOMPLETE`,
+`SCOPE_UNAUTHORIZED`, `OBLIGATION_MISSING`) — and, after any PRD, ticket or map edit,
+`node scripts/pincer-runtime.cjs impact` (`--from G-NN` for another baseline): it
+lists the affected scenarios, tickets and checks with reasons and the dependency
+dependents separately, and reports an unscoped PRD change or unavailable history
+rather than "no impact". `legacy` and no ticket of this PRD carries legacy
+receipts → register now (`node scripts/pincer-runtime.cjs register --prd .prd/prd-vN.md`,
+commit `.prd/changes/` and `.gitignore` as `Register PRD vN`), then record the user's
+approval (`change authorize …`, as `/pincer-narrow` describes), select and activate.
+`legacy` with legacy receipts, or a v0.5.0 binding (`Runtime  change <id> · revision …`)
+→ run `node scripts/pincer-runtime.cjs migrate --preview --prd .prd/prd-vN.md`, show
+the plan (backups, receipts imported as history, the converted binding, the
+`.gitignore` line, the local selection) and ask once whether to apply. Apply only on
+a yes, then commit the rewritten tickets, `.gitignore` and the record as `Migrate PRD
+vN to the runtime`. The migrated change is planned with no authorization: record the
+user's actual earlier instruction with `change authorize` (the v0.5.0 free text is
+history only) and activate it. Never migrate silently, and never apply when the
+preview reports a conflict.
 
 ## Loop (per ticket, in dependency order)
 
@@ -38,7 +76,9 @@ previously authorized work.
    dispatch a subagent with a clean prompt: paste the full ticket body, the relevant
    conventions, and nothing else.
 3. **Verify:** `scripts/pincer-ticket.sh verify T-{NN}` — runs the Verification block and
-   writes the receipt only if it exits 0. Red → fix and re-run; report the actual output,
+   writes the receipt only if it exits 0 (after migration it records an attempt with the
+   captured log under `.pincer/runtime/` and writes no receipt into the ticket; readiness
+   derives from the latest attempt and the current source). Red → fix and re-run; report the actual output,
    not assumptions. Green output is the definition of done, not your confidence. If the
    check only validated syntax or a build, say so — that is not behavioral proof. A
    visual judgment is recorded separately in evaluation, not as the receipt, and a tool
@@ -56,7 +96,10 @@ previously authorized work.
    - No error path leaks internals (stack traces, key names with values) to the client.
    If the review changed code, run `verify` again — the receipt must match the code you commit.
 5. **Close the ticket:** tick every verified acceptance-criteria checkbox (`- [ ]` → `- [x]`;
-   editing the checkboxes is allowed), then `scripts/pincer-ticket.sh done T-{NN}`. A
+   editing the checkboxes is allowed), then `scripts/pincer-ticket.sh done T-{NN}`. After
+   migration `done` consumes the current passing attempt and does not re-run the check; it
+   refuses with a reason code (`SOURCE_CHANGED`, `CHECK_CHANGED`, `CHECK_FAILED`,
+   `CRITERIA_UNTICKED`, …) and the next step when the latest attempt is not current. A
    criterion that was cut is a scope change to record in the PRD, not a box to skip.
    Inspect `git status --short`, preserve pre-existing staged work, and stage only the
    explicit paths changed for this ticket plus its ticket file. Review `git diff --cached`
@@ -87,20 +130,78 @@ the script or `scripts/pincer-status.sh` printed, and hand the repair to the use
 performs it in their own terminal. Then return through the lifecycle — `start`,
 `verify`, `done` — so the ticket carries fresh verification; a restored receipt is
 never evidence. Do not recommend restoring source files or unrelated edits as routine
-ticket repair. One exception: when the PRD is built with valid candidate evidence,
+ticket repair. One exception: when the PRD is built with valid candidate evidence;
 tracked files other than the ticket file being restored match the evaluated candidate
-(or the candidate plus its evidence-only commit) with nothing untracked, and the
-ticket's Verification block passes when run
-directly rather than through `verify` (which would write a receipt), then
+(or the candidate plus its evidence-only commit) with nothing untracked; the recorded
+failure is explained by a working-tree change that has since been reverted (the failed
+`last_check` was stamped while source differed from the candidate, and that difference
+is gone); and the ticket's Verification block passes when run
+directly rather than through `verify` (which would write a receipt), in the
+same execution context as `verify` — the same shell, working directory, `PATH`
+and environment, with no substituted binary and no repair made first — then
 the committed evaluation still describes the tree. Say so, name the exact command
 for the user to restore the ticket file in their own terminal, and
 do not run `verify`, refresh the receipt or commit anything — the restored file is
 what is already committed, not new evidence. If the block fails on that clean tree,
 the failure is real: keep the failed `last_check` and repair through the lifecycle.
+A changed executable, runner, working directory or environment repair requires a
+new recorded verification through `verify`; the exception does not apply to it.
+An unexplained failure cannot be cleared by restoring a receipt: when no
+since-reverted source change explains it (a service down, a missing dependency, a
+check that reads external data), keep the failure, name the cause you observed, and
+ask for the environment to be repaired before `verify` runs again.
 If source still differs from the candidate, name the differing paths and let the
 user decide rather than asking which way to fix them; permission to restore a ticket
-does not authorize discarding source changes. Automated recovery that preserves
-attempt history is later work (M1).
+does not authorize discarding source changes.
+After migration (a change binding exists) recovery is the lifecycle itself: retain the
+failure, repair the cause, run `verify` again; readiness derives from the latest attempt,
+both attempts stay in `.pincer/runtime/` and no tracked file changes. Never restore a
+ticket file or delete `.pincer/runtime` to obtain a green status; the legacy exception
+above applies only before migration. A session that died mid-`verify` leaves a `running`
+attempt: run `node scripts/pincer-runtime.cjs recover`, which finalizes it as
+`interrupted` once the owner process is gone, then `verify` again.
+
+## Changes: pausing, decisions and completion
+
+- Stopping before the change is complete (end of session, switching to another
+  change): `node scripts/pincer-runtime.cjs change pause <id> --reason "<why>" --note "<handoff for the next session>"`
+  and commit the record. Pausing keeps every ticket state, attempt and authorization;
+  it refuses while a check is running (`recover` first if its owner died). A fresh
+  session runs `resume`, then `change resume <id>` under the existing authorization —
+  do not ask the user to re-approve unchanged scope. Another change's work in the
+  meantime makes this change's passing attempts `SOURCE_CHANGED`; verify again, do
+  not ask for approval again.
+- A newly discovered consequential choice: `node scripts/pincer-runtime.cjs change decide <id> --summary "<the question>"`
+  blocks execution (`DECISION_REQUIRED`) until the user answers; record the answer with
+  `change decide <id> --resolve D-NN --reference "<where>" --excerpt "<the user's words>"`,
+  then `change authorize <id> --agreement <digest> --reference … --excerpt … --decision D-NN`.
+  A revision within the user's delegation (for example an added regression check for
+  approved behavior) records `change authorize <id> --agreement <digest> --delegated --basis A-NN --explanation "<why it stays within the delegation>"`
+  without asking again, and the changed check still needs fresh verification.
+- Editing the PRD under its filename, or a ticket's acceptance text, dependencies,
+  size, timeout, association or check — and, with strict coverage, a scenario's text,
+  a map link, a declared command or timeout, or a scope entry — changes the agreement:
+  execution refuses with `AGREEMENT_CHANGED` (status shows the structural difference;
+  `impact` explains it) until its disposition is recorded as above. Ticking criteria, starting or closing tickets and recording
+  attempts never change it. An `AGREEMENT_CHANGED` caused by an edit this session
+  did not make — a revised PRD, an added or changed ticket found on resume — is a
+  consequential decision: raise it with `change decide <id> --summary "<what changed>"`,
+  report the structural difference (and the `impact` report) and stop. A general instruction to continue,
+  resume or not re-ask never authorizes new scope; record a `user` authorization for
+  the revised agreement only for an instruction that names the revised content. With strict coverage a scenario that will not be delivered is
+  never dropped from the map or the PRD: it is deferred or removed through a decision
+  the user resolves naming it, a `scope` entry (a removal keeps a tombstone naming the
+  prior agreement) and an authorization naming that decision; `coverage` reports
+  `OBLIGATION_MISSING` or `SCOPE_UNAUTHORIZED` until then, and `change complete`
+  refuses. A revised check declaration (a stricter command, an added check) within the
+  user's delegation is a `--delegated` authorization and needs fresh verification.
+- When every ticket is done and ready: `node scripts/pincer-runtime.cjs change complete <id>`
+  (it refuses unfinished tickets, unticked criteria, stale or failed verification and
+  open decisions; with strict coverage also an incomplete map, an unauthorized
+  disposition or a missing obligation, before the ticket gate) and commit the record
+  as `Complete PRD vN`. Completion never asks for candidate evidence. Completed means ready
+  for evaluation, not evaluated or released; a later finding is `change reopen <id> --reason …`
+  plus a fix ticket.
 
 ## Budget rules
 
@@ -113,7 +214,8 @@ attempt history is later work (M1).
 
 ## When all tickets are done
 
-Update the PRD to `status: built` and commit that change on its own (`PRD vN: built`).
+On a project with change records, complete the change first (`change complete <id>`,
+committed as `Complete PRD vN`). Then update the PRD to `status: built` and commit that change on its own (`PRD vN: built`).
 The built transition is part of the candidate that `/pincer-evaluate` reviews; it is
 never moved into a later evidence-only commit. Then finish with:
 "All tickets built. Run `/pincer-evaluate` for a final quality pass."
@@ -125,6 +227,9 @@ material choice not already authorized, and prepare the concrete proposal before
 asking. A decision the user delegated (for example "pick the architecture") does not
 need another approval when you exercise it, but a newly discovered consequential
 choice is surfaced before implementation. Record the authorization basis and the
-scope it covers in the PRD or the handover. An agent-written record or a status
+scope it covers in the PRD or the handover, and on a project with change records as
+a `change authorize` record (the user's words as the excerpt, or a `--delegated`
+disposition with its basis). An agent-written record or a status
 field is not authenticated human approval. When resuming without the context that
-granted authorization, do not invent it — ask.
+granted authorization, do not invent it — read the `resume` report; an authorization
+it reports as `current` needs no repeat approval, and any other verdict is asked.

package/template/.claude/commands/pincer-evaluate.md

@@ -19,8 +19,10 @@ run the pipeline, then present results.
    that uncertainty before claiming a complete review. Record full commit IDs for
    `base` and `candidate` (`git rev-parse HEAD`), then review `git diff <base>..<candidate>`.
    The candidate is the clean, committed tree that already includes the implementation,
-   the ticket closures and the PRD `status: built` commit: `git status --short` must be
-   empty before review. If anything is uncommitted or the PRD is not yet built, return
+   the ticket closures, on a project with change records the `change complete` commit
+   (the `Runtime` line reads `… · completed ·`; `check` and `evidence export` refuse an
+   active, paused or unauthorized change), and the PRD `status: built` commit:
+   `git status --short` must be empty before review. If anything is uncommitted or the PRD is not yet built, return
    to `/pincer-code`; do not review a dirty tree.
 2. Dispatch a `code-quality-reviewer` agent with: the diff, the PRD's Success Criteria and
    Scope sections, and the list of tickets. If the diff is large, split by area and
@@ -28,7 +30,13 @@ run the pipeline, then present results.
    in a separate pass, applying `.claude/agents/code-quality-reviewer.md` as the rubric.)
    Keep the reviewer's report — or its explicit no-findings statement — for step 9,
    where it is saved as an artifact; a review that left no record cannot be audited.
-3. Yourself, in parallel, check spec compliance. For every requirement `R-NN` in the
+3. Yourself, in parallel, check spec compliance. On a change with strict coverage
+   (`Coverage strict …` in status) start from `node scripts/pincer-runtime.cjs coverage`:
+   its structure must be complete, and its scenario rows are the obligations — the
+   export derives every disposition from the map and the outcomes, so you do not
+   author `requirements`; your judgment is recorded as `adequacy` (whether the
+   declared checks and reviews really establish their scenarios) and in
+   `coverage_review`. Otherwise, for every requirement `R-NN` in the
    PRD record one disposition: `delivered` (evidence on this candidate), `blocked`
    (required behavior failed or was left unverified — this blocks PASS; do not relabel
    it a known limitation to pass), or `deferred` (only with explicit user authorization;
@@ -62,7 +70,41 @@ run the pipeline, then present results.
    material decision; never make an ad-hoc `review: fixes` commit. Every fix commit
    produces a new candidate: re-record `candidate`, re-run the checks against it, and
    write fresh evidence in step 9 — never reuse a manifest from a previous candidate.
-9. Persist evidence for the candidate under `.prd/evidence/prd-vN/<candidate>/`:
+9. Persist evidence for the candidate under `.prd/evidence/prd-vN/<candidate>/`.
+   Strict coverage: run every declared command check as
+   `node scripts/pincer-runtime.cjs check C-NN --candidate <sha>` (no command, no
+   timeout: the map's declaration is the only source, and a supplied command is
+   `CHECK_UNDECLARED`); record each declared review or visual obligation in the
+   draft with its `result` and an artifact saved under the candidate's evidence
+   directory (a required one that is not passed with an artifact is
+   `REVIEW_MISSING`); write `adequacy: { verdict: "adequate" | "inadequate", note }`;
+   list every declared check once and no `requirements` (they are derived). The
+   export writes the inventory and map snapshots under `coverage/`, derives the
+   scenario and requirement rows and `delivery` (original versus agreed scope) and
+   validates them against the committed candidate; an `inadequate` judgment or a
+   failed required check is recorded honestly and blocks readiness. Migrated
+   project without strict coverage (the `Runtime` status line names a change): run
+   each executable check through the runtime on the clean candidate view —
+   `node scripts/pincer-runtime.cjs check C-NN --candidate <sha> -- <command>` (one
+   command per check, the command line as run; `npm test` stays one aggregate check) —
+   then write the authored fields to a draft outside the evidence directory, for
+   example `.pincer/drafts/<sha>.json`: `environment.tools` and `environment.limitations`,
+   `coverage_review`, `requirements`, review and visual checks with their saved
+   artifacts, `visual_review`, and a stub `{"id": "C-NN", "kind": "command",
+   "required": true|false}` for each executable check. Then run
+   `node scripts/pincer-runtime.cjs evidence export --candidate <sha> --base <base> --prd .prd/prd-vN.md --draft <file>`.
+   The export writes `checks/C-NN.log` from the captured logs, fills `command`,
+   `result`, `provenance: runtime` and `attempt` from the attempts, labels review and
+   visual checks `provenance: authored`, computes the digests and writes an evidence
+   schema 2 manifest; it refuses a dirty tree, a HEAD that is not the candidate, a stub
+   without an attempt, and a `passed` or `failed` command result written by hand. On a
+   project with change records the export also appends the evaluation to the change's
+   locator `.prd/evidence/changes/<id>.json` (the identity of this change's
+   evaluation; root `NOTES.md` stays the human summary and may be overwritten by a
+   later change's evaluation without losing this one) — commit the locator with the
+   evidence. A tool that cannot run is recorded as an authored command check with
+   `result: unverified` and a note, as before. Legacy project (no change binding):
+   author the schema 1 manifest as follows.
    - `checks/C-NN.log` — the command and a redacted summary or safe log of each
      executable check. Never secrets, never an environment dump. Record
      one check per command: `command` holds the command line as run, never prose
@@ -102,11 +144,13 @@ run the pipeline, then present results.
    evidence: .prd/evidence/prd-vN/<candidate>/manifest.json
    ---
    ```
-   Then commit NOTES.md, the manifest and its listed artifacts — and nothing else —
+   Then commit NOTES.md, the manifest, its listed artifacts and (change records) the
+   evaluation locator — and nothing else —
    as `evaluate: PRD vN candidate <short sha>`. Status accepts this later commit only
-   when its diff from the candidate is limited to `NOTES.md` and the evidence files
-   the manifest lists; changes to source, tests, configuration, tickets, the PRD or
-   other evaluations require reevaluation. Legacy notes without these references
+   when its diff from the candidate is limited to `NOTES.md`, the candidate's evidence
+   directories and evaluation locators; changes to source, tests, configuration,
+   tickets, the PRD or the change record (a lifecycle transition after the
+   candidate) require reevaluation. Legacy notes without these references
    do not establish readiness. Then describe what was built, what was cut
    and why, known issues, and what you'd do next with more time. Then a **Handover**
    section, written for the stranger who inherits this repo in six months: how to get
@@ -124,6 +168,9 @@ material choice not already authorized, and prepare the concrete proposal before
 asking. A decision the user delegated (for example "pick the architecture") does not
 need another approval when you exercise it, but a newly discovered consequential
 choice is surfaced before implementation. Record the authorization basis and the
-scope it covers in the PRD or the handover. An agent-written record or a status
+scope it covers in the PRD or the handover, and on a project with change records as
+a `change authorize` record (the user's words as the excerpt, or a `--delegated`
+disposition with its basis). An agent-written record or a status
 field is not authenticated human approval. When resuming without the context that
-granted authorization, do not invent it — ask.
+granted authorization, do not invent it — read the `resume` report; an authorization
+it reports as `current` needs no repeat approval, and any other verdict is asked.

package/template/.claude/commands/pincer-narrow.md

@@ -32,14 +32,25 @@ discovered consequential choice is surfaced before implementation.
    - Build the requirement map: for every `R-NN` in the PRD and each of its
      scenarios, name the ticket that owns the implementation and the executable
      check that exercises it, or an explicit review method when no executable check
-     exists. Record the IDs in each ticket's Context as `Implements: R-NN, R-MM`.
-     Enabling work that implements no requirement states its purpose in the ticket
-     Objective. Resolve missing coverage and conflicting criteria with the user
-     before implementation; do not start with an unmapped required scenario.
+     exists. Record the IDs in each ticket's Context as `Implements: R-NN, R-MM`
+     (a navigation aid). Enabling work that implements no requirement states its purpose
+     in the ticket Objective. Resolve missing coverage and conflicting criteria with
+     the user before implementation; do not start with an unmapped required scenario. On a change with change records, author the map once as
+     `.prd/coverage/<change id>.json` (coverage map schema 1, "Coverage map" in
+     `docs/runtime-contracts.md`): one `scenarios` row per `S-NN` naming its
+     implementing tickets and declared checks, every ticket of the change in
+     `tickets` as `implements` or `enables` (with a rationale), each check declared
+     once in `checks` with its kind, `required` flag and, for a command, the exact
+     command line and timeout, and a `scope` entry (`deferred` or `removed`) for a
+     scenario this change will not deliver, naming the decision that records the
+     user's choice. The map is authored work you edit by hand; the runtime never
+     rewrites it, and it validates it against the PRD's definitions.
    - Every ticket gets a runnable command in its Verification block — a fenced `bash`
      block that exits 0 only when the ticket is done. `scripts/pincer-ticket.sh verify`
      runs it verbatim and stamps the receipt that `done` requires, so it must be
-     non-interactive and self-contained (no "check by hand").
+     non-interactive and self-contained (no "check by hand"). An optional
+     `timeout: <seconds>` frontmatter field (default 600) bounds the run; it is part of
+     the check identity, so changing it invalidates earlier passes.
    - Each Verification section opens with `Proves:` — what the check establishes and
      which regression it detects. A check for an executable change must exercise
      observable behavior (including relevant rejection paths and, in brownfield work,
@@ -81,7 +92,33 @@ existing authorization for the same scope and order.
    inspect existing staged changes, stage that PRD and the explicit new ticket paths,
    review `git diff --cached`, and commit only those paths. Ask first — and finalize
    once it is resolved — only when step 4 surfaced a newly discovered consequential
-   choice or a scope change the PRD does not cover. Finish with:
+   choice or a scope change the PRD does not cover. Then register the change when the
+   `Runtime` status line says `legacy` and no ticket of this PRD carries legacy
+   receipts, or `changes` (the project already keeps change records):
+   `node scripts/pincer-runtime.cjs register --prd .prd/prd-vN.md` writes the change
+   record `.prd/changes/prd-vN.json` (retaining every earlier change); stage
+   `.prd/changes/` and `.gitignore` (registration adds `.pincer/` to it) and commit them
+   as `Register PRD vN`. Then record the user's actual approval against the agreement
+   the record binds — `node scripts/pincer-runtime.cjs change show prd-vN --json`
+   prints the agreement digest — with
+   `node scripts/pincer-runtime.cjs change authorize prd-vN --agreement <digest> --reference "<where the user said it>" --excerpt "<the user's approval, quoted>"`,
+   select it for this worktree (`node scripts/pincer-runtime.cjs change select prd-vN`)
+   and commit `.prd/changes/` as `Authorize PRD vN`. When the map was authored, adopt
+   strict coverage explicitly: `node scripts/pincer-runtime.cjs coverage adopt --preview --change prd-vN`
+   shows the inventory, the map digest and the agreement it records (it refuses an
+   incomplete map, naming the scenario or ticket); `--apply` writes the schema 3
+   record with a backup and grants nothing — record the user's approval of that
+   agreement with `change authorize` (the same instruction, if it named this
+   breakdown; a delegated disposition needs its basis) and commit `.prd/coverage/`
+   and `.prd/changes/` as `Adopt strict coverage for PRD vN`. A scenario the user
+   deferred or removed is a decision: `change decide --summary "<the choice>"`,
+   `--resolve D-NN` with the user's words naming the scenario, the `scope` entry in
+   the map, then `change authorize … --decision D-NN`. Never record a disposition
+   the user did not state; `coverage` reports `SCOPE_UNAUTHORIZED` until it is. The excerpt records the user's own
+   words; running the command proves nothing by itself, and a registration, a PRD
+   status or a passing check never becomes an authorization. A project whose tickets
+   carry legacy receipts, or that still holds a v0.5.0 binding (`Runtime  change <id> ·
+   revision …`), is migrated from `/pincer-code` after a preview, never here. Finish with:
    "Tickets ready in `tickets/`. Run `/pincer-code` to start implementing."
 
 ## Authorization rule (shared by plan, narrow, code and evaluate)
@@ -91,6 +128,9 @@ material choice not already authorized, and prepare the concrete proposal before
 asking. A decision the user delegated (for example "pick the architecture") does not
 need another approval when you exercise it, but a newly discovered consequential
 choice is surfaced before implementation. Record the authorization basis and the
-scope it covers in the PRD or the handover. An agent-written record or a status
+scope it covers in the PRD or the handover, and on a project with change records as
+a `change authorize` record (the user's words as the excerpt, or a `--delegated`
+disposition with its basis). An agent-written record or a status
 field is not authenticated human approval. When resuming without the context that
-granted authorization, do not invent it — ask.
+granted authorization, do not invent it — read the `resume` report; an authorization
+it reports as `current` needs no repeat approval, and any other verdict is asked.

package/template/.claude/commands/pincer-plan.md

@@ -91,8 +91,13 @@ concrete scope and architecture; do not repeat an approval already given for the
    In Requirements, assign stable `R-NN` IDs within the selected PRD: a revision
    keeps existing IDs and adds new ones, never renumbers. Every requirement has
    observable acceptance scenarios, the relevant failure paths, and the existing
-   behavior it must preserve — `/pincer-narrow` maps each scenario to a ticket and
-   a check, and `/pincer-evaluate` dispositions every ID.
+   behavior it must preserve, each written as a bold `- **S-NN:** …` item under its
+   requirement heading (the template's grammar; the runtime parses exactly these
+   definitions into the inventory that strict coverage tracks, and a requirement
+   without a scenario is invalid there) — `/pincer-narrow` maps each scenario to a
+   ticket and a check in the coverage map, and `/pincer-evaluate` dispositions every
+   ID. A supplied PRD keeps its own uppercase IDs (`REQ-1`, `AC-3`); only its
+   definition syntax is adapted, and the mapping table records what changed.
 2. Include optional sections when risk or the product context warrants them.
 3. Save to the next unused `.prd/prd-v{N}.md` (create `.prd/` if needed), with `N`
    matching the filename and frontmatter:
@@ -119,6 +124,9 @@ material choice not already authorized, and prepare the concrete proposal before
 asking. A decision the user delegated (for example "pick the architecture") does not
 need another approval when you exercise it, but a newly discovered consequential
 choice is surfaced before implementation. Record the authorization basis and the
-scope it covers in the PRD or the handover. An agent-written record or a status
+scope it covers in the PRD or the handover, and on a project with change records as
+a `change authorize` record (the user's words as the excerpt, or a `--delegated`
+disposition with its basis). An agent-written record or a status
 field is not authenticated human approval. When resuming without the context that
-granted authorization, do not invent it — ask.
+granted authorization, do not invent it — read the `resume` report; an authorization
+it reports as `current` needs no repeat approval, and any other verdict is asked.

package/template/.claude/commands/pincer-release.md

@@ -26,9 +26,13 @@ durable runtime-owned release record is later work.
 3. Check every applicable item mechanically where possible:
    - File existence and frontmatter: read the files.
    - Commit format and story: `git log --oneline`.
-   - Receipts: every done ticket carries current `last_check` and `verified` evidence;
-     any status warning fails the audit. Do not call `pincer-ticket.sh` from Release:
-     it writes receipts and would invalidate the evaluated candidate.
+   - Receipts: every done ticket is ready — on a legacy project current `last_check`
+     and `verified` receipts, on a migrated project a current passing attempt
+     (`node scripts/pincer-runtime.cjs ready` exits 0); any status warning fails the
+     audit. Do not call `pincer-ticket.sh` from Release:
+     it writes receipts and would invalidate the evaluated candidate. Release never
+     runs `verify`, `check` or `done`; `status`, `ready` and the project gate are its
+     only commands.
    - Evidence: `scripts/pincer-status.sh` runs the shared validator
      (`scripts/pincer-evidence.cjs`) against the manifest `NOTES.md` names. The `Notes`
      line must read `current` and the `Evidence` line `ok`; any other text fails the
@@ -36,6 +40,31 @@ durable runtime-owned release record is later work.
      screenshots described in chat: read the manifest's `checks`, requirement
      dispositions and `visual_review`. Validation establishes that the record is
      consistent, not that the commands ran — say so if asked.
+   - Provenance: status prints a `Provenance` line for the evaluated candidate:
+     `runtime (schema 2)` with local attempts consistent, or `legacy (schema 1, authored
+     command results)`. A newer local attempt that failed, timed out, was interrupted or
+     is still running for the same check and source inputs fails the audit (`ready`
+     exits 1 and names the check). A fresh clone reports `local verification history
+     unavailable; saved candidate evidence validated only`: state that limit in the
+     verdict rather than claiming local verification.
+   - Change records (the `Runtime` line reads `changes`): the selected change is
+     `completed`, its authorization is `current` for the current agreement, and its
+     evaluation locator `.prd/evidence/changes/<id>.json` names the evaluated
+     candidate; `node scripts/pincer-runtime.cjs ready` reports `SELECTION_REQUIRED`,
+     `LIFECYCLE_BLOCKED`, `DECISION_REQUIRED`, `AUTHORIZATION_REQUIRED` or
+     `AGREEMENT_CHANGED` as failures. Release selects, activates and completes nothing;
+     historical evidence of a cancelled or superseded change is inspectable but never
+     release-ready.
+   - Strict coverage (the status line reads `Coverage strict …`): read
+     `node scripts/pincer-runtime.cjs coverage` — structure complete, every in-scope
+     scenario `delivered` on the evaluated candidate, deferrals and removals backed by
+     their decision and user authorization, `delivery` reported as original versus
+     agreed scope (never conflate them), adequacy `adequate`; the manifest is schema 3
+     and the `Provenance` line reads `runtime (schema 3)`. `ready` names
+     `COVERAGE_INCOMPLETE`, `SCOPE_UNAUTHORIZED`, `OBLIGATION_MISSING`,
+     `REVIEW_MISSING` and `ADEQUACY_REQUIRED` as failures. A change labeled
+     `Coverage unverified` did not adopt strict coverage: audit it under the rules
+     above and say so; never imply strict coverage was established.
    - Every file the manifest lists is tracked, and `git status --short` is empty before
      and after the audit.
    - Run the repository's candidate-wide release gate directly (`npm test`, or the

package/template/.claude/commands/pincer-status.md

@@ -13,13 +13,36 @@ start of a session. Read-only: change nothing.
 1. Run `scripts/pincer-status.sh`. It reads the artifacts on disk (`.prd/`, `tickets/`,
    `NOTES.md`) and prints the PRD state and profile, every ticket with its state and
    clock-based elapsed time, what is blocked, wall-clock build time while a ticket is in
-   progress or against an explicit user budget, the evidence verdict for the evaluated
+   progress or against an explicit user budget, the `Runtime` line (legacy receipts or
+   the registered change), the evidence verdict and `Provenance` line for the evaluated
    candidate, any warnings (each readiness problem once), and the next command to run.
+   `scripts/pincer-status.sh --json` prints one status object with reason codes and the
+   next action for tooling; `node scripts/pincer-runtime.cjs ready [T-NN]` is the
+   read-only gate. On a project with change records (`Runtime  changes …`) run
+   `node scripts/pincer-runtime.cjs resume` as well: it reports the selected change, its
+   lifecycle, agreement and authorization, decisions, references, tickets, attempts,
+   candidate, the authored handoff note and the next command, and never writes;
+   `change list` shows every retained change, `status --change <id>` and
+   `resume --change <id>` inspect another one without selecting it. `resume` is the
+   report; `change resume <id>` is the lifecycle operation. The `Coverage` line says
+   `strict` or `unverified`; on a strict change `node scripts/pincer-runtime.cjs coverage`
+   (and `impact` after an edit) name the exact scenario, ticket, check or decision
+   that is next — quote them rather than inferring coverage from the ticket list.
 2. Report in three lines: where the workflow is, what is in progress or blocked, and the
-   next command. Quote the `Next` line as-is.
+   next command. Quote the `Next` line as-is. When the `Runtime` line says `legacy`,
+   add the register or migrate command it names as the step that precedes the next
+   ticket (fresh project → `register`, legacy receipts → `migrate --preview`, a v0.5.0
+   binding → `migrate --preview`, no selection → `change select <id>`).
 3. If a ticket is `in_progress`, read it and `git status`, then offer to resume it with
    `/pincer-code T-{NN}`. If the script printed a warning, surface it — a done ticket
    without a receipt was marked by hand and needs `scripts/pincer-ticket.sh verify T-{NN}`.
    Never restore a ticket file from git to clear a warning; a failed attempt is a record.
    The one exception is the tree-back-at-candidate case in the recovery section of
    `/pincer-code`: the user restores the ticket file, and nothing is verified or committed.
+   It applies only when the recorded failure is explained by a since-reverted source
+   change and the block passes in the same execution context as `verify`; an
+   unexplained failure (a service down, a missing dependency) stays a failure until the
+   environment is repaired and `verify` passes again. After migration never restore a
+   ticket file or delete `.pincer/runtime` to clear a warning: repair the cause and run
+   `verify` again; a dead session's `running` attempt is finalized by
+   `node scripts/pincer-runtime.cjs recover`.