pincer-workflow 0.4.1 → 0.5.0

package/README.md

@@ -86,7 +86,7 @@ want the repo-side rules too can copy `AGENTS.md` from the
 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.) Files you edited are left
+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).
@@ -98,10 +98,12 @@ 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-ticket.sh` | The ticket state machine: `start` (enforces dependency order) → `verify` (runs the ticket's check, stamps a receipt only on green) → `done` (refuses without a matching receipt or with unticked criteria) |
-| `scripts/pincer-status.sh` | Read-only state report: current PRD and profile, associated tickets, wall-clock elapsed time while work is active or against an explicit budget, evidence verdict, warnings, and next command |
-| `scripts/pincer-evidence.cjs` | Read-only validator for candidate evidence (schema 1): `/pincer-evaluate` writes `.prd/evidence/prd-vN/<candidate>/manifest.json` plus logs and screenshots; status and release validate schema, references, candidate association, required results, 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 |
-| `.claude/hooks/` + `settings.json` | Claude guardrails for documented destructive command forms and ticket state writes; Node.js 18+ parses hook payloads structurally |
+| `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-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 |
 | `.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 |

package/bin/pincer.js

@@ -26,13 +26,15 @@ const MANIFEST_SCHEMA = 2;
 // and Copilot prompts point at them), so they ship everywhere; only Claude
 // Code's own wiring (CLAUDE.md, settings.json, hooks) is platform-specific.
 const PLATFORM_ROOTS = {
-  common: ['AGENTS.md', 'docs/release-checklist.md', 'docs/dry-run-checklist.md', 'scripts/sync-prompts.sh', 'scripts/pincer-ticket.sh', 'scripts/pincer-ticket-lib.sh', 'scripts/pincer-status.sh', 'scripts/pincer-evidence.cjs', '.claude/commands', '.claude/agents', '.claude/references'],
+  common: ['AGENTS.md', 'docs/release-checklist.md', 'docs/dry-run-checklist.md', 'docs/runtime-contracts.md', 'scripts/sync-prompts.sh', 'scripts/pincer-ticket.sh', 'scripts/pincer-status.sh', 'scripts/pincer-evidence.cjs', 'scripts/pincer-runtime.cjs', 'scripts/pincer-runtime', '.claude/commands', '.claude/agents', '.claude/references'],
   claude: ['CLAUDE.md', '.claude/settings.json', '.claude/hooks'],
   codex: ['.codex', '.agents'],
   copilot: ['.github'],
 };
 const EXECUTABLES = ['scripts/sync-prompts.sh', 'scripts/pincer-ticket.sh', 'scripts/pincer-status.sh', '.claude/hooks/block-dangerous.sh', '.claude/hooks/ticket-guard.sh'];
 const GITIGNORE_LINES = ['.env', '.env.*', '!.env.example'];
+// The runtime's local state (attempts, locks, backups) is never tracked.
+const RUNTIME_IGNORE = '.pincer/';
 
 const sha = (buf) => crypto.createHash('sha256').update(buf).digest('hex');
 
@@ -134,12 +136,18 @@ function install(dir, platforms, baseline) {
 
 function ensureGitignore(dir) {
   const p = path.join(dir, '.gitignore');
-  const existing = fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : '';
+  let existing = fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : '';
   const have = new Set(existing.split('\n').map((l) => l.trim()));
   const missing = GITIGNORE_LINES.filter((l) => !have.has(l));
-  if (missing.length === 0) return;
-  const lead = existing && !existing.endsWith('\n') ? '\n' : '';
-  fs.appendFileSync(p, `${lead}${existing ? '\n' : ''}# secrets (added by pincer init)\n${missing.join('\n')}\n`);
+  if (missing.length) {
+    const lead = existing && !existing.endsWith('\n') ? '\n' : '';
+    fs.appendFileSync(p, `${lead}${existing ? '\n' : ''}# secrets (added by pincer init)\n${missing.join('\n')}\n`);
+    existing = fs.readFileSync(p, 'utf8');
+  }
+  if (![RUNTIME_IGNORE, '/.pincer/', '.pincer'].some((l) => have.has(l))) {
+    const lead = existing && !existing.endsWith('\n') ? '\n' : '';
+    fs.appendFileSync(p, `${lead}${existing ? '\n' : ''}# pincer runtime state (added by pincer init)\n${RUNTIME_IGNORE}\n`);
+  }
 }
 
 function report({ written, skipped, conflicted }) {
@@ -240,10 +248,39 @@ function cmdDoctor() {
   const gi = fs.existsSync(path.join(dir, '.gitignore')) ? fs.readFileSync(path.join(dir, '.gitignore'), 'utf8') : '';
   check(GITIGNORE_LINES.every((l) => gi.split('\n').map((s) => s.trim()).includes(l)),
     '.gitignore covers .env files', 'add: .env / .env.* / !.env.example');
+  if (![RUNTIME_IGNORE, '/.pincer/', '.pincer'].some((l) => gi.split('\n').map((s) => s.trim()).includes(l))) {
+    console.log(`  note  .gitignore does not list ${RUNTIME_IGNORE} (runtime state); \`pincer update\`, \`register\` or \`migrate --apply\` adds it`);
+  }
 
   const stale = fs.existsSync(TEMPLATE) && manifest.version !== VERSION;
   check(!stale, `install is current (v${manifest.version})`, 'run: pincer update');
 
+  // The runtime ships with every layout; a project with legacy receipts and no
+  // change binding can migrate explicitly (never silently here).
+  const runtimeFiles = Object.keys(manifest.files).filter((rel) => rel === 'scripts/pincer-runtime.cjs' || rel.startsWith('scripts/pincer-runtime/'));
+  if (runtimeFiles.length) {
+    const missingRuntime = runtimeFiles.filter((rel) => !fs.existsSync(path.join(dir, rel)));
+    check(missingRuntime.length === 0, 'runtime files present', `missing: ${missingRuntime.join(', ')} — run: pincer update`);
+  }
+  // Files an earlier kit installed that this version no longer ships stay on disk
+  // (the installer never deletes); name them so they can be removed by hand.
+  const OBSOLETE = ['scripts/pincer-ticket-lib.sh'];
+  const obsolete = OBSOLETE.filter((rel) => fs.existsSync(path.join(dir, rel)) && !(rel in manifest.files));
+  if (obsolete.length) console.log(`  note  obsolete kit file(s) from an earlier version, safe to delete: ${obsolete.join(', ')}`);
+
+  const ticketsDir = path.join(dir, 'tickets');
+  const legacyReceipts = fs.existsSync(ticketsDir)
+    ? 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'));
+  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])) : [];
+    const latest = prds.length ? `.prd/prd-v${Math.max(...prds)}.md` : '.prd/prd-vN.md';
+    console.log(`  note  migration available: ${legacyReceipts.length} ticket(s) carry legacy receipts and no change binding exists — preview with: node scripts/pincer-runtime.cjs migrate --preview --prd ${latest}`);
+  }
+
   const edited = Object.entries(manifest.files)
     .filter(([rel, h]) => fs.existsSync(path.join(dir, rel)) && sha(fs.readFileSync(path.join(dir, rel))) !== h)
     .map(([rel]) => rel);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pincer-workflow",
-  "version": "0.4.1",
+  "version": "0.5.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"
@@ -14,7 +14,7 @@
     "node": ">=18"
   },
   "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/workflow.test.js && node test/distribution.test.js"
+    "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"
   },
   "keywords": [
     "claude-code",

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

@@ -18,6 +18,11 @@ 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/` and `.prd/changes/`
+are written only by the runtime; never edit or delete them by hand.
 
 ## Before the loop
 
@@ -25,7 +30,15 @@ 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: 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.
 
 ## Loop (per ticket, in dependency order)
 
@@ -40,7 +53,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
@@ -58,7 +73,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`
@@ -89,20 +107,36 @@ 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.
 
 ## Budget rules
 

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

@@ -64,7 +64,25 @@ 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>/`.
+   Migrated project (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. 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

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

@@ -41,7 +41,9 @@ discovered consequential choice is surfaced before implementation.
    - 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,
@@ -83,7 +85,14 @@ 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: `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:
    "Tickets ready in `tickets/`. Run `$pincer-code` to start implementing."
 
 ## Authorization rule (shared by plan, narrow, code and evaluate)

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,13 @@ 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.
    - 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,26 @@ 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.
 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`).
 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,11 @@ 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/` and `.prd/changes/`
+are written only by the runtime; never edit or delete them by hand.
 
 ## Before the loop
 
@@ -23,7 +28,15 @@ 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: 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.
 
 ## Loop (per ticket, in dependency order)
 
@@ -38,7 +51,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 +71,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 +105,36 @@ 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.
 
 ## Budget rules
 

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

@@ -62,7 +62,25 @@ 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>/`.
+   Migrated project (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. 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

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

@@ -39,7 +39,9 @@ discovered consequential choice is surfaced before implementation.
    - 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 +83,14 @@ 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: `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:
    "Tickets ready in `tickets/`. Run `/pincer-code` to start implementing."
 
 ## Authorization rule (shared by plan, narrow, code and evaluate)

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,13 @@ 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.
    - 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,26 @@ 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.
 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`).
 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`.