pincer-workflow 0.5.0 → 0.7.0

package/README.md

@@ -31,15 +31,80 @@ On Codex CLI the commands are skills, invoked by mention rather than slash:
 `$pincer-plan <brief>` → `$pincer-narrow` → `$pincer-code` → `$pincer-evaluate`
 → `$pincer-release`, and `$pincer-status`.
 
+## Your first change, end to end
+
+The five commands above are the shape of the work. This is the whole journey for one
+change on a project that wants strict requirement coverage — the path most of the
+runtime exists to support. Every step is a real command; none of them is optional
+ceremony, and the two read-only reports (`coverage scaffold`, `resume --brief`) write
+nothing.
+
+```bash
+# 1. Install, then plan and break down the work.
+npx pincer-workflow init
+#    /pincer-plan <brief>      → .prd/prd-v1.md with R-NN requirements and S-NN scenarios
+#    /pincer-narrow            → tickets/T-*.md, one per unit of work
+
+# 2. Register the change and select it in this worktree.
+node scripts/pincer-runtime.cjs register --prd .prd/prd-v1.md
+node scripts/pincer-runtime.cjs change select prd-v1
+
+# 3. Choose your coverage. Default is fine: tickets, checks and evidence work without
+#    this step. Strict coverage additionally binds every S-NN to a ticket and a check.
+#    Start the map from the draft — it lists every scenario and ticket for you:
+node scripts/pincer-runtime.cjs coverage scaffold --change prd-v1
+
+# 4. Author .prd/coverage/prd-v1.json yourself from that draft, then review the links.
+#    The draft never invents a link, a check command or a scope disposition, and it is
+#    not a map: `coverage adopt` refuses it. Working through its Unresolved list is the
+#    authoring step.
+
+# 5. Adopt strict coverage explicitly, then record the user's actual approval.
+node scripts/pincer-runtime.cjs coverage adopt --preview --change prd-v1
+node scripts/pincer-runtime.cjs coverage adopt --apply   --change prd-v1
+node scripts/pincer-runtime.cjs change authorize prd-v1 --agreement <digest> \
+  --reference "<where the user said it>" --excerpt "<the user's approval, quoted>"
+node scripts/pincer-runtime.cjs change activate prd-v1
+
+# 6. Implement. One commit per ticket; `done` refuses without a current passing check.
+#    /pincer-code
+
+# 7. Come back tomorrow, or in a fresh session with no memory of any of this:
+node scripts/pincer-runtime.cjs resume --brief
+#    → one screen: the change, the authorization verdict, the coverage label, the
+#      blocker categories with counts, and the exact next command. `resume` (no
+#      --brief) prints every row; the brief names the command that shows them.
+
+# 8. Evaluate and audit.
+#    /pincer-evaluate          → validated evidence under .prd/evidence/
+#    /pincer-release           → read-only pass/fail audit
+```
+
+Adoption grants no approval, and approval is never inferred: `coverage adopt` records
+the agreement, `change authorize` records what the user actually said about it, and a
+generic "continue" authorizes no revised scope. Edit the PRD, the tickets or the map
+afterwards and the agreement changes — the runtime reports `AGREEMENT_CHANGED` and
+waits for a fresh decision rather than carrying the old approval forward.
+
+### Pinning a management kit
+
+The kit under `scripts/` is code that the workflow also runs *on* the project. When you
+are changing that code, manage the work with a pinned released copy from outside the
+tree rather than with the version you are editing — extract the scripts from a release
+tag into a directory outside the repository, record its digest, and run the lifecycle
+commands from there. A project that only uses PINCER never needs this; a project that
+develops it does.
+
 ### Claude Code
 
-Works immediately: the commands, the two subagents, the `.env` deny rules and
+Installs complete: the commands, the two subagents, the `.env` deny rules and
 the destructive-command and ticket-guard hooks install to `.claude/`. Start
-`claude` in the repo and run `/pincer-plan <brief>`.
+`claude` in the repo and run `/pincer-plan <brief>`. See
+[platform support](#platform-support) for what that install has been observed to do.
 
 ### Codex CLI
 
-Works immediately as well: `AGENTS.md` loads natively, and the six commands
+Installs complete as well: `AGENTS.md` loads natively, and the six commands
 install as skills under `.agents/skills/`, which Codex discovers from the repo
 (no copying into your home directory — Codex removed custom prompts and
 `~/.codex/prompts/` in early 2026). Start `codex` in the repo, then type
@@ -61,11 +126,33 @@ Full notes in `.codex/README.md`.
 Enable `"chat.promptFiles": true` in VS Code settings, then run `/pincer-plan`
 in chat. `.github/copilot-instructions.md` is wired to `AGENTS.md`.
 
+## Platform support
+
+Two different claims, kept apart on purpose. **Installation-tested** means the packed
+artifact installs and its files land where they should, proven by the suites in this
+repository on every push. **Live-observed** means a real agent session carried a real
+change through the workflow on that surface and the artifacts were reviewed. An
+installation check is not a platform trial, and packaged parity is not live success.
+
+| Surface | Installation-tested | Live-observed |
+| --- | --- | --- |
+| Claude Code (`npx pincer-workflow init`) | yes — packed install, layout and generated parity | not for this release |
+| Codex CLI (`.agents/skills/`) | yes — packed install and skill layout | not for this release |
+| GitHub Copilot (VS Code prompts) | yes — packed install and prompt layout | no |
+| Claude Code plugin (marketplace) | yes — plugin build parity | no |
+| Windows (native, no POSIX shell) | no | no |
+
+No live platform trial has been observed for the current release. The work that would
+produce one — a full strict journey on Claude Code and on Codex, plus a real cross-agent
+handoff resumed from files — is open, and until it reports, every "live-observed" cell
+above stays as it reads. Earlier releases have their own recorded trials under `docs/`;
+those describe the versions they were run against, not this one.
+
 ## Claude Code plugin (alternative)
 
 Claude users can install PINCER as a plugin instead — commands arrive
 namespaced (`/pincer:plan` … `/pincer:release`) and update automatically
-through the marketplace. The plugin's structured hook parser requires Node.js 18+:
+through the marketplace. The plugin's structured hook parser requires Node.js 22+:
 
 ```
 /plugin marketplace add orchestratedbyalex/pincer-workflow
@@ -80,17 +167,6 @@ and Copilot). Installing both gives you duplicate commands. Plugin users who
 want the repo-side rules too can copy `AGENTS.md` from the
 [template](template/AGENTS.md).
 
-## Update
-
-```bash
-npx pincer-workflow@latest update
-```
-
-Files you never touched are refreshed in place. (Installs older than v0.2.0 gain the ticket state machine, the status report and the ticket-guard hook on update; `.claude/settings.json` conflicts if you edited it — merge the new hook entry from the `.new` file. v0.2.2 replaces the Codex adapter: the commands are now skills in `.agents/skills/` invoked as `$pincer-*`, since Codex no longer loads `~/.codex/prompts/` — you can delete the copies there. v0.2.3 ships the playbooks, rubrics and templates under `.claude/` on every platform, which Codex- and Copilot-only installs were missing. v0.3.0 makes trust revocable: every verification attempt is recorded, `done` re-runs the check, tickets carry `prd:`, the release audit is read-only, and `.pincer.json` moves to schema 2 — an install from 0.2.x is treated as an untrusted baseline, so on the first update every changed file arrives as a `.new` proposal once; hooks now need Node 18+. v0.4.0 carries requirement IDs and `Proves:` checks from the PRD to evaluation, adds `profile: small|standard`, and saves candidate evidence under `.prd/evidence/`; the update is additive, but an existing `NOTES.md` without an `evidence:` manifest reads as stale until `/pincer-evaluate` is re-run. v0.4.1 is playbook wording only: the code playbook gains one recovery exception (a tree back at the evaluated candidate is restored by the user and nothing is committed), evaluate records one check per command, and plan asks only the open part of a partly answered question. v0.5.0 adds the runtime: `scripts/pincer-runtime.cjs` with its modules under `scripts/pincer-runtime/` now implements the ticket lifecycle, status, migration and evidence export, and `pincer-ticket.sh` / `pincer-status.sh` delegate to it, so every command needs Node.js 18+; unmigrated projects keep their receipts and behavior. Run `node scripts/pincer-runtime.cjs migrate --preview --prd .prd/prd-vN.md` to see what migration would change; after `--apply`, `verify` records attempts with captured logs under the ignored `.pincer/runtime/` and writes no receipt into the ticket, `done` consumes the current passing attempt against the current source, and `/pincer-evaluate` exports evidence schema 2 from runtime attempts. `docs/runtime-contracts.md` is the contract; `pincer doctor` tells you when a migration is available and never migrates on its own. Updating the kit inside a migrated project changes tracked runtime files, so every done ticket's attempt reads `SOURCE_CHANGED` until it is verified again; update between changes, not mid-ticket. An update from 0.4.x leaves the retired `scripts/pincer-ticket-lib.sh` on disk; `pincer doctor` names it and it is safe to delete.) Files you edited are left
-alone — the new version lands next to them as `<file>.new` for a manual merge.
-`npx pincer-workflow doctor` checks the health of an install (hook executable,
-`.gitignore` covering `.env*`, no unmerged `*.new` files, version current).
-
 ## What you get
 
 | Piece | Purpose |
@@ -98,18 +174,29 @@ alone — the new version lands next to them as `<file>.new` for a manual merge.
 | `AGENTS.md` | Project rules, single cross-platform source (workflow order, security defaults, secrets, untrusted-content and dependency rules) |
 | `.claude/commands/` | The five playbooks plus `/pincer-status` (canonical — adapters are generated from them; ships on every platform together with `agents/` and `references/`) |
 | `.claude/agents/` | `codebase-explorer` and `code-quality-reviewer` subagents, with inline fallbacks for platforms without subagents |
-| `scripts/pincer-runtime.cjs` + `scripts/pincer-runtime/` | The runtime (Node.js 18+, no dependencies): one implementation of the ticket lifecycle, readiness, status (`--json` too), change registration, source identity, verification attempts with sanitized captured logs, migration with backups, candidate checks and evidence export; `docs/runtime-contracts.md` is its contract. Local attempts live in the ignored `.pincer/runtime/`, change bindings in `.prd/changes/`; both are written only by the runtime |
+| `scripts/pincer-runtime.cjs` + `scripts/pincer-runtime/` | The runtime (Node.js 22+, no dependencies): one implementation of the ticket lifecycle, readiness, status (`--json` too), change records with lifecycle, agreements, authorization and decisions (`change list|show|select|activate|pause|resume|complete|reopen|cancel|supersede|revise|authorize|decide`), the read-only `resume` report, source identity, verification attempts with sanitized captured logs, migration with backups, candidate checks and evidence export; `docs/runtime-contracts.md` is its contract. Local attempts and the worktree's selection live in the ignored `.pincer/runtime/`, change records in `.prd/changes/`, evaluation locators in `.prd/evidence/changes/`; all are written only by the runtime |
 | `scripts/pincer-ticket.sh` | Wrapper for the lifecycle: `start` (enforces dependency order) → `verify` (runs the ticket's check; before migration it stamps a receipt only on green, after migration it records an attempt bound to the current source) → `done` (refuses without a current pass or with unticked criteria; after migration it consumes the attempt without re-running the check) |
 | `scripts/pincer-status.sh` | Wrapper for the read-only state report: current PRD and profile, `Runtime` mode, associated tickets, wall-clock elapsed time while work is active or against an explicit budget, evidence verdict and `Provenance`, warnings with reason codes, and next command |
 | `scripts/pincer-evidence.cjs` | Read-only validator for candidate evidence (schema 1 authored, schema 2 exported from runtime attempts): `/pincer-evaluate` writes `.prd/evidence/prd-vN/<candidate>/manifest.json` plus logs and screenshots; status and release validate schema, references, candidate association, required results, provenance, file containment and SHA-256 digests. Legacy `NOTES.md` without a manifest is readable but never release-ready; an older runtime does not enforce this contract |
-| `docs/runtime-contracts.md` | The runtime contract: modes, commands and exit codes, supported grammar, identities, source manifest, attempts, capture limits, reason codes, evidence schema 2, migration and rollback |
-| `.claude/hooks/` + `settings.json` | Claude guardrails for documented destructive command forms and for writes to ticket state, `.pincer/` and `.prd/changes/`; Node.js 18+ parses hook payloads structurally |
+| `docs/runtime-contracts.md` | The runtime contract: modes (legacy, migrated, changes), commands and exit codes, supported grammar, change records, selection, lifecycle, agreements and authorization, command gates, identities, source manifest, attempts, transactions, capture limits, reason codes, evidence schema 2, the evaluation locator, the resume report, migration and rollback, worktrees |
+| `.claude/hooks/` + `settings.json` | Claude guardrails for documented destructive command forms and for writes to ticket state, `.pincer/`, `.prd/changes/` and `.prd/evidence/changes/`; Node.js 22+ parses hook payloads structurally |
 | `.agents/skills/` · `.codex/` · `.github/` | Generated Codex skills and Copilot prompt files + platform wiring (`.codex/README.md` covers the Codex posture) |
 | `scripts/sync-prompts.sh` | Regenerates the adapters after you edit a playbook |
-| `scripts/build-plugin.sh` | Regenerates the Claude Code plugin (`plugin/`) from the template |
+| `scripts/build-plugin.sh` (maintainers of this repository only — not installed into your project) | Regenerates the Claude Code plugin (`plugin/`) from the template |
 | `docs/release-checklist.md` | General, read-only candidate audit used by `/pincer-release` |
 | `docs/dry-run-checklist.md` | Separate manual platform trial for the Pincer kit |
 
+## Update
+
+```bash
+npx pincer-workflow@latest update
+```
+
+Files you never touched are refreshed in place. (Installs older than v0.2.0 gain the ticket state machine, the status report and the ticket-guard hook on update; `.claude/settings.json` conflicts if you edited it — merge the new hook entry from the `.new` file. v0.2.2 replaces the Codex adapter: the commands are now skills in `.agents/skills/` invoked as `$pincer-*`, since Codex no longer loads `~/.codex/prompts/` — you can delete the copies there. v0.2.3 ships the playbooks, rubrics and templates under `.claude/` on every platform, which Codex- and Copilot-only installs were missing. v0.3.0 makes trust revocable: every verification attempt is recorded, `done` re-runs the check, tickets carry `prd:`, the release audit is read-only, and `.pincer.json` moves to schema 2 — an install from 0.2.x is treated as an untrusted baseline, so on the first update every changed file arrives as a `.new` proposal once; hooks now need Node 18+. v0.4.0 carries requirement IDs and `Proves:` checks from the PRD to evaluation, adds `profile: small|standard`, and saves candidate evidence under `.prd/evidence/`; the update is additive, but an existing `NOTES.md` without an `evidence:` manifest reads as stale until `/pincer-evaluate` is re-run. v0.4.1 is playbook wording only: the code playbook gains one recovery exception (a tree back at the evaluated candidate is restored by the user and nothing is committed), evaluate records one check per command, and plan asks only the open part of a partly answered question. v0.5.0 adds the runtime: `scripts/pincer-runtime.cjs` with its modules under `scripts/pincer-runtime/` now implements the ticket lifecycle, status, migration and evidence export, and `pincer-ticket.sh` / `pincer-status.sh` delegate to it, so every command needs Node.js 18+; unmigrated projects keep their receipts and behavior. Run `node scripts/pincer-runtime.cjs migrate --preview --prd .prd/prd-vN.md` to see what migration would change; after `--apply`, `verify` records attempts with captured logs under the ignored `.pincer/runtime/` and writes no receipt into the ticket, `done` consumes the current passing attempt against the current source, and `/pincer-evaluate` exports evidence schema 2 from runtime attempts. `docs/runtime-contracts.md` is the contract; `pincer doctor` tells you when a migration is available and never migrates on its own. v0.6.0 keeps several changes side by side: `register` writes a change record (schema 2) that retains every earlier change, the worktree selects the change it works on (`change select`), the user's approval is recorded against the reviewed agreement (`change authorize`), the lifecycle is explicit (`change activate|pause|resume|complete|reopen|cancel|supersede`), and `resume` prints where to continue from files alone. A v0.5.0 binding converts with the same `migrate --preview` / `--apply`; the converted change is planned with no authorization, its old attempts and evaluation are history until verified again, and the old free-text authorization never authorizes execution. Selection and local attempts are per worktree; records are tracked and shared through git; completed means ready for evaluation, not released. v0.6.0 also raises the floor to Node.js 22+, because 18 and 20 are past end of life. It separately fixes a defect that was never version-specific: a command whose output exceeded one pipe buffer (65,536 bytes) lost the tail when the process exited and still exited 0, on every version including 22 and 24. Every write is now synchronous, so piped `--json` is complete. Updating the kit inside a migrated project changes tracked runtime files, so every done ticket's attempt reads `SOURCE_CHANGED` until it is verified again; update between changes, not mid-ticket. An update from 0.4.x leaves the retired `scripts/pincer-ticket-lib.sh` on disk; `pincer doctor` names it and it is safe to delete.) Files you edited are left
+alone — the new version lands next to them as `<file>.new` for a manual merge.
+`npx pincer-workflow doctor` checks the health of an install (hook executable,
+`.gitignore` covering `.env*`, no unmerged `*.new` files, version current).
+
 ## Design principles
 
 - **Approval gates scale with decision cost** — a human owns architecture, scope,

package/bin/pincer.js

@@ -273,7 +273,23 @@ function cmdDoctor() {
     ? fs.readdirSync(ticketsDir).filter((n) => /^T-\d+.*\.md$/.test(n)).filter((n) => /^(verified|last_check):/m.test(fs.readFileSync(path.join(ticketsDir, n), 'utf8')))
     : [];
   const bindingsDir = path.join(dir, '.prd', 'changes');
-  const hasBinding = fs.existsSync(bindingsDir) && fs.readdirSync(bindingsDir).some((n) => n.endsWith('.json'));
+  const bindingFiles = fs.existsSync(bindingsDir) ? fs.readdirSync(bindingsDir).filter((n) => n.endsWith('.json')) : [];
+  const hasBinding = bindingFiles.length > 0;
+  // A v0.5.0 binding (schema 1) converts explicitly into a schema 2 change record; doctor only reports it.
+  const oldBindings = bindingFiles.filter((n) => { try { return JSON.parse(fs.readFileSync(path.join(bindingsDir, n), 'utf8')).schema === 1; } catch { return false; } });
+  for (const n of oldBindings) {
+    let prd = '.prd/prd-vN.md';
+    try { prd = JSON.parse(fs.readFileSync(path.join(bindingsDir, n), 'utf8')).prd || prd; } catch { /* reported above by the runtime */ }
+    console.log(`  note  migration to change records available: .prd/changes/${n} is a v0.5.0 binding (schema 1) — preview with: node scripts/pincer-runtime.cjs migrate --preview --prd ${prd}`);
+  }
+  // A schema 2 change record beside an authored coverage map can adopt strict coverage explicitly; doctor only reports it.
+  for (const n of bindingFiles) {
+    let doc = null;
+    try { doc = JSON.parse(fs.readFileSync(path.join(bindingsDir, n), 'utf8')); } catch { doc = null; }
+    if (!doc || doc.schema !== 2) continue;
+    const id = n.replace(/\.json$/, '');
+    if (fs.existsSync(path.join(dir, '.prd', 'coverage', `${id}.json`))) console.log(`  note  strict coverage adoption available: .prd/coverage/${id}.json exists and .prd/changes/${n} is a schema 2 record — preview with: node scripts/pincer-runtime.cjs coverage adopt --preview --change ${id}`);
+  }
   if (legacyReceipts.length && !hasBinding) {
     const prdDir = path.join(dir, '.prd');
     const prds = fs.existsSync(prdDir) ? fs.readdirSync(prdDir).map((n) => n.match(/^prd-v(\d+)\.md$/)).filter(Boolean).map((m) => Number(m[1])) : [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pincer-workflow",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "PINCER — a PRD-driven agentic delivery workflow for Claude Code, Codex CLI, and GitHub Copilot. Plan · Investigate · Narrow · Code · Evaluate · Release.",
   "bin": {
     "pincer": "bin/pincer.js"
@@ -11,10 +11,10 @@
     "template"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "scripts": {
-    "test": "node test/smoke.test.js && node test/installer.test.js && node test/ticket.test.js && node test/validation.test.js && node test/verification.test.js && node test/behavioral-verification.test.js && node test/evidence.test.js && node test/candidate.test.js && node test/recovery.test.js && node test/hooks.test.js && node test/runtime-parse.test.js && node test/runtime-identity.test.js && node test/runtime-state.test.js && node test/runtime-status.test.js && node test/runtime-runner.test.js && node test/runtime-lifecycle.test.js && node test/runtime-migrate.test.js && node test/runtime-evidence.test.js && node test/workflow.test.js && node test/contracts.test.js && node test/distribution.test.js"
+    "test": "node test/smoke.test.js && node test/installer.test.js && node test/strict-onboarding.test.js && node test/ticket.test.js && node test/validation.test.js && node test/verification.test.js && node test/behavioral-verification.test.js && node test/evidence.test.js && node test/candidate.test.js && node test/recovery.test.js && node test/hooks.test.js && node test/runtime-parse.test.js && node test/coverage-inventory.test.js && node test/coverage-map.test.js && node test/coverage-scaffold.test.js && node test/coverage-agreement.test.js && node test/coverage-adoption.test.js && node test/coverage-readiness.test.js && node test/coverage-impact.test.js && node test/coverage-checks.test.js && node test/coverage-evidence.test.js && node test/coverage-reports.test.js && node test/runtime-identity.test.js && node test/change-registry.test.js && node test/change-selection.test.js && node test/change-agreement.test.js && node test/change-authorization.test.js && node test/change-lifecycle.test.js && node test/change-command-gates.test.js && node test/change-evidence-context.test.js && node test/change-evaluations.test.js && node test/change-resume.test.js && node test/resume-brief.test.js && node test/change-trial-record.test.js && node test/change-review-packet.test.js && node test/runtime-state.test.js && node test/change-transactions.test.js && node test/runtime-status.test.js && node test/runtime-output.test.js && node test/runtime-runner.test.js && node test/runtime-lifecycle.test.js && node test/runtime-migrate.test.js && node test/change-migration.test.js && node test/runtime-evidence.test.js && node test/workflow.test.js && node test/improvement-contracts.test.js && node test/contracts.test.js && node test/change-contracts.test.js && node test/coverage-contracts.test.js && node test/distribution.test.js && node test/change-distribution.test.js && node test/coverage-distribution.test.js && node test/effort-records.test.js && node test/execution-freeze.test.js && node test/delivery-benchmark.test.js && node test/delivery-benchmark-v7.test.js && node test/benchmark-orchestrator.test.js && node test/strict-pilot-records.test.js && node test/platform-trial-records.test.js && node test/improvement-trial-records.test.js && node test/coverage-trial-record.test.js && node test/coverage-review-packet.test.js && node test/improvement-review-packet.test.js && node test/readiness-contracts.test.js && node test/benchmark-effective-inputs.test.js && node test/release-preparation.test.js && node test/benchmark-run-claims.test.js && node test/benchmark-environment.test.js && node test/benchmark-browser.test.js && node test/benchmark-restart.test.js && node test/benchmark-usage-completeness.test.js && node test/benchmark-terminal-records.test.js && node test/study-readiness.test.js && node test/benchmark-allocation.test.js && node test/benchmark-prepared-bases.test.js && node test/benchmark-study-launch.test.js"
   },
   "keywords": [
     "claude-code",

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

@@ -21,8 +21,14 @@ receipt that matches the current check, or with unticked acceptance criteria. Ne
 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/` and `.prd/changes/`
-are written only by the runtime; never edit or delete them by hand.
+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
 
@@ -30,15 +36,37 @@ 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. Read the `Runtime` line before the first ticket: a change
-binding present → continue; `legacy` and no ticket of this PRD carries legacy
-receipts → register now (`node scripts/pincer-runtime.cjs register --prd .prd/prd-vN.md --authorization "<the user's approval, quoted>"`,
-commit `.prd/changes/` and `.gitignore` as `Register PRD vN`); `legacy` with legacy receipts → run
-`node scripts/pincer-runtime.cjs migrate --preview --prd .prd/prd-vN.md`, show the plan
-(backups, receipts imported as history, `.gitignore` line) and ask once whether to
-apply. Apply only on a yes, then commit the rewritten tickets, `.gitignore` and the
-binding as `Migrate PRD vN to the runtime`. Never migrate silently, and never apply
-when the preview reports a conflict.
+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. `resume --brief` is the same report projected to counts and one next
+action — the same verdict and the same `Next` line, with every blocker category kept
+and its `Detail` line naming the command that prints the rows it grouped. Prefer it
+when you are orienting, and read the full report when a blocker needs its detail. 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)
 
@@ -138,6 +166,48 @@ above applies only before migration. A session that died mid-`verify` leaves a `
 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
 
 - If the user set `PINCER_BUILD_BUDGET_MIN` or stated another budget, use the elapsed
@@ -149,7 +219,8 @@ attempt: run `node scripts/pincer-runtime.cjs recover`, which finalizes it as
 
 ## 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."
@@ -161,6 +232,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/.agents/skills/pincer-evaluate/SKILL.md

@@ -21,8 +21,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
@@ -30,7 +32,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;
@@ -65,8 +73,20 @@ run the pipeline, then present results.
    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>/`.
-   Migrated project (the `Runtime` status line names a change): run each executable
-   check through the runtime on the clean candidate view —
+   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
@@ -79,8 +99,12 @@ run the pipeline, then present results.
    `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. A
-   tool that cannot run is recorded as an authored command check with
+   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
@@ -122,11 +146,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
@@ -144,6 +170,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/.agents/skills/pincer-narrow/SKILL.md

@@ -34,10 +34,29 @@ 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`). Start from
+     `node scripts/pincer-runtime.cjs coverage scaffold --change <change id>`: it prints
+     a read-only draft listing every live scenario exactly once with its requirement,
+     every ticket with its objective, its own `Implements:` claim and its Verification
+     text, and an `Unresolved` list of what is still unauthored. It writes nothing,
+     adopts nothing and decides nothing — it removes the transcription, not the
+     judgment, so a ticket's claim is material to check rather than a link, and no check
+     command, ticket role or scope disposition is ever invented. The draft is not a map:
+     it carries no `schema` key and `coverage adopt` refuses it. You author the real map
+     yourself, working through the draft's unresolved entries:
+     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
@@ -87,12 +106,31 @@ existing authorization for the same scope and order.
    once it is resolved — only when step 4 surfaced a newly discovered consequential
    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: `node scripts/pincer-runtime.cjs register --prd .prd/prd-vN.md --authorization "<the user's approval, quoted>"`,
-   then stage `.prd/changes/` and `.gitignore` (registration adds `.pincer/` to it) and
-   commit them as `Register PRD vN`. The authorization
-   text records the user's own words; running the command proves nothing by itself. A
-   project whose tickets carry legacy receipts is migrated from `$pincer-code` after a
-   preview, never here. Finish with:
+   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)
@@ -102,6 +140,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/.agents/skills/pincer-plan/SKILL.md

@@ -93,8 +93,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:
@@ -121,6 +126,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.