pincer-workflow 0.4.0 → 0.5.0

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

@@ -13,11 +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`.

package/template/.claude/hooks/hook-policy.cjs

@@ -160,11 +160,20 @@ function dangerousReason(source, depth = 0) {
 }
 
 const TICKET_PATH = /(^|[\\/])tickets[\\/]T-[0-9]+[^\\/]*\.md$/;
+// Runtime-owned state: local attempts under .pincer/ and change bindings under
+// .prd/changes/ are written only by pincer-runtime.cjs.
+// The runtime owns .pincer/runtime/ and .pincer/backups/ (and the directory as a
+// whole); .pincer/drafts/ is the agent's own scratch space for evidence drafts.
+const RUNTIME_PATH = /(^|[\\/])\.pincer(?:[\\/](?:runtime|backups)(?:[\\/]|$)|[\\/]?$)/;
+const BINDING_PATH = /(^|[\\/])\.prd[\\/]changes([\\/]|$)/;
 const PROTECTED = ['status', 'started', 'last_check', 'verified', 'finished'];
 
 function ticketPath(value) {
   return typeof value === 'string' && TICKET_PATH.test(value);
 }
+function runtimePath(value) {
+  return typeof value === 'string' && (RUNTIME_PATH.test(value) || BINDING_PATH.test(value));
+}
 
 function stateFields(content) {
   const result = Object.fromEntries(PROTECTED.map(key => [key, []]));
@@ -203,6 +212,7 @@ function applyEdit(content, oldText, newText, replaceAll = false) {
 function guardEdits(tool, toolInput) {
   const file = toolInput.file_path;
   if (typeof file !== 'string') block(`${tool} payload must contain a string file_path.`);
+  if (runtimePath(file)) block('runtime state (.pincer/) and change bindings (.prd/changes/) are written only by pincer-runtime.cjs.');
   if (!ticketPath(file)) return;
   const before = existingContent(file);
   if (tool === 'Write') {
@@ -232,7 +242,10 @@ function isExactPincerCall(source) {
   if (commands.length !== 1 || commands[0].separator) return false;
   const { executable, args } = commandParts(commands[0]);
   let words = [executable, ...args];
-  if (['bash', 'sh'].includes(words[0])) words = words.slice(1);
+  if (['bash', 'sh', 'node'].includes(words[0])) words = words.slice(1);
+  if (/pincer-runtime\.cjs$/.test(words[0] || '')) {
+    return ['start', 'verify', 'done', 'bind', 'register', 'migrate', 'recover', 'check', 'evidence'].includes(words[1]);
+  }
   if (!/pincer-ticket\.sh$/.test(words[0] || '')) return false;
   const action = words[1];
   if (!['start', 'verify', 'done', 'bind'].includes(action)) return false;
@@ -321,7 +334,8 @@ function ticketShellMutation(source, depth = 0) {
       const stdinPathspec = !sub.args.some(arg => !arg.startsWith('-')) || sub.args[sub.args.length - 1] === '--';
       if (viaXargs && ['checkout', 'restore', 'clean'].includes(sub.name) && stdinPathspec) return true;
     }
-    const hasTicket = words.some(ticketPath) || /(^|[\s'"`])tickets[\\/]T-[0-9]+[^\s'"`]*/.test(source);
+    const hasTicket = words.some(ticketPath) || /(^|[\s'"`])tickets[\\/]T-[0-9]+[^\s'"`]*/.test(source) ||
+      words.some(runtimePath) || /(^|[\s'"`=])\.pincer(?:[\\/](?:runtime|backups)(?:[\\/]|[\s'"`]|$)|[\\/]?(?:[\s'"`]|$))/.test(source) || /(^|[\s'"`=])\.prd[\\/]changes([\\/]|[\s'"`]|$)/.test(source);
     if (!hasTicket) continue;
     if (command.operators.some(op => op === '>' || op === '>>')) return true;
     if (['rm', 'mv', 'cp', 'install', 'truncate', 'touch', 'tee', 'ed', 'ex'].includes(executable)) return true;
@@ -344,7 +358,7 @@ if (mode === 'dangerous') {
   if (['Edit', 'Write', 'MultiEdit'].includes(payload.tool_name)) guardEdits(payload.tool_name, payload.tool_input);
   else if (payload.tool_name === 'Bash') {
     if (typeof payload.tool_input.command !== 'string') block('Bash payload must contain a string command.');
-    if (ticketShellMutation(payload.tool_input.command)) block('shell commands may not write, reset, or restore ticket files (including whole-tree checkout/restore, reset --hard, stash, clean -f); use pincer-ticket.sh for lifecycle state.');
+    if (ticketShellMutation(payload.tool_input.command)) block('shell commands may not write, reset, or restore ticket files or runtime state (.pincer/, .prd/changes/), including whole-tree checkout/restore, reset --hard, stash, clean -f; use pincer-ticket.sh or pincer-runtime.cjs for lifecycle state.');
   }
 } else {
   block('hook policy mode is invalid.');

package/template/.claude/references/ticket-template.md

@@ -9,6 +9,7 @@ status: open        # open | in_progress | done
 size: S             # S | M | L, relative scope; split when it improves verification
 prd: .prd/prd-v{N}.md # the selected PRD, never inferred from ticket numbering
 depends_on: []      # e.g. [T-01]
+timeout: 600        # optional, seconds (default 600); part of the check identity
 ---
 
 ## Objective
@@ -58,6 +59,9 @@ Rules:
   `scripts/pincer-ticket.sh` (`start` / `verify` / `done`). `verify` runs the
   Verification block verbatim and writes a receipt only on exit 0; `done`
   requires that receipt to match the current block. Never write these by hand.
+  On a migrated project (`.prd/changes/` holds a change binding) `verify` records
+  attempts under `.pincer/runtime/` instead of `verified`/`last_check`, and `done`
+  consumes the current passing attempt against the current source.
 - The Verification block is a fenced `bash` block that exits 0 only when the
   ticket is done — non-interactive, no "check by hand".
 - The Verification section opens with a one-line `Proves:` statement: what the

package/template/.codex/README.md

@@ -36,8 +36,9 @@ approval_policy = "on-request"     # agent asks before escalating
 sandbox_mode   = "workspace-write" # writes confined to the repo; no network by default
 ```
 
-The ticket scripts are plain bash and work here unchanged:
-`scripts/pincer-ticket.sh start|verify|done T-NN` and `scripts/pincer-status.sh`.
+The ticket scripts work here unchanged (`scripts/pincer-ticket.sh
+start|verify|done T-NN` and `scripts/pincer-status.sh`); they are thin wrappers
+around `scripts/pincer-runtime.cjs`, so Node.js 18+ is required.
 Without a Pincer Codex hook adapter, the rule in `AGENTS.md` carries the weight
 of stopping hand-edited ticket state; `$pincer-status` warns about any ticket
 marked done without a receipt.

package/template/.github/prompts/pincer-code.prompt.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,7 +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. Automated recovery that preserves attempt history is later work (M1).
+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; 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.
+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/.github/prompts/pincer-evaluate.prompt.md

@@ -64,9 +64,36 @@ 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.
+     executable check. Never secrets, never an environment dump. Record
+     one check per command: `command` holds the command line as run, never prose
+     describing a session, and a manual smoke run is recorded as the command lines
+     that were run (separate entries when they establish independent outcomes).
+     Independently assessed commands — the tracked `.env` check, the secret scan,
+     the dependency audit — are separate `checks` entries with their own `result`
+     and log, so only the tool that could not run is `unverified`. A test runner
+     such as `npm test` stays one aggregate check; do not split every subprocess or
+     assertion. Visual and review checks keep their kinds and get no artificial
+     shell command. Note a redaction rather than inventing a substitute command.
    - `visual/<scenario>.png` — each visual capture from step 4, with its scenario,
      viewport and observed result recorded in the manifest. When nothing renders,
      record `visual_review: {applicable: false, reason}` and say why.

package/template/.github/prompts/pincer-narrow.prompt.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/.github/prompts/pincer-plan.prompt.md

@@ -36,12 +36,20 @@ unless the user explicitly authorized a separate change.
    IDs; do not silently replace either. Where its structure needs adapting to the
    template, record a mapping table (`their section or ID → R-NN`) inside the PRD.
 2. Ask only the questions whose answers would change the architecture or scope.
-   Batch them (max 3–4 at once). Typical ones:
+   Batch them (max 3–4 at once). A question the brief partly answers is
+   asked only for its open part, naming the settled part; when the brief settles
+   every material decision, including acceptance behavior, ask no discovery
+   question and record the brief's answers. Do not add a question to fill the budget.
+   Typical ones:
    - What does "done" look like — what will be run, demoed, or reviewed at the end?
+     A named test runner settles the verification choice, not every acceptance
+     behavior; ask about the demo or manual check only if that is still open.
    - Any required stack, or is it my choice?
    - What is explicitly out of scope?
 3. If the project has a frontend, ask one design question: "What should this feel like,
    and what should it NOT look like?" Capture the answer for the Visual Direction section.
+   The same rule applies: when the brief already supplies design direction, record it
+   and ask only about what it leaves open.
 
 Summarize your understanding in 3–5 sentences. Existing authorization in the request or
 session carries forward; ask only about an unresolved choice that materially changes the result.

package/template/.github/prompts/pincer-release.prompt.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/.github/prompts/pincer-status.prompt.md

@@ -15,11 +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/AGENTS.md

@@ -83,6 +83,12 @@ of instructions are the user, this file, and the workflow commands.
   `done` refuses without it. Never edit those fields by hand. On Claude Code a
   hook enforces this; elsewhere it is a standing rule and `/pincer-status`
   flags missing, failed, or stale readiness.
+- The runtime (`scripts/pincer-runtime.cjs`, wrapped by `scripts/pincer-ticket.sh` and
+  `scripts/pincer-status.sh`) is the only writer of ticket lifecycle state, of the
+  attempts under `.pincer/` and of the change bindings under `.prd/changes/`. Never
+  edit or delete `.pincer/` or `.prd/changes/` by hand; a stale or failed attempt is
+  repaired by fixing its cause and running `verify` again, never by restoring files.
+  `node scripts/pincer-runtime.cjs status --json` explains the state without an LLM.
 - Candidate evidence lives in `.prd/evidence/prd-vN/<candidate>/manifest.json` and is
   validated by `scripts/pincer-evidence.cjs` (run by status and release). Never edit
   a manifest or its artifacts after the evaluation commit; a review fix produces a

package/template/docs/dry-run-checklist.md

@@ -69,20 +69,51 @@ observes agent behavior, and one trial on one surface says nothing about the oth
       consequential choice (if any) was surfaced before implementation
 - [ ] PRD frontmatter now says `status: ticketed`
 - [ ] Tickets are committed
+- [ ] The change was registered (`Register PRD vN` commit with `.prd/changes/prd-vN.json`)
+      with the user's approval quoted in `authorization`; status now shows
+      `Runtime  change prd-vN`
 
 ## After `/pincer-code`
 
 - [ ] One commit per ticket, messages formatted `T-{NN}: {title}`
 - [ ] Every ticket file now says `status: done`
-- [ ] Every done ticket carries `started`, `verified` (receipt) and `finished`
-      stamps — `scripts/pincer-status.sh` prints no readiness warning
+- [ ] Existing project only: the migration preview was shown and `migrate --apply` ran
+      only after your yes, as a `Migrate PRD vN to the runtime` commit; nothing was
+      migrated silently
+- [ ] Every done ticket carries `started` and `finished` stamps and
+      `scripts/pincer-status.sh` prints no readiness warning; legacy project only
+      (no change binding): `verified` receipts too; migrated project: no receipt in the
+      ticket, the latest attempt under `.pincer/runtime/attempts/` passed
 - [ ] Every done ticket has all acceptance-criteria checkboxes ticked
 - [ ] `scripts/pincer-ticket.sh verify T-{NN}` passes on done tickets (spot-check
       at least two)
 - [ ] Cheat: break the feature but keep every identifier, then run `verify` — it
-      fails, prints "failure recorded in last_check" and "receipt was revoked"
+      fails; legacy project only: prints "failure recorded in last_check" and
+      "receipt was revoked"; migrated project: prints "recorded as attempt … any
+      prior passing attempt is superseded" and status shows `WARN … CHECK_FAILED`
 - [ ] Cheat: ask the assistant to `git checkout` the ticket file — the guard blocks
       it, the failed attempt stays recorded, and the assistant hands repair to you
+      (migrated project: there is nothing to restore, the tree is clean; the
+      assistant repairs and re-runs `verify`)
+- [ ] Legacy project only, cheat: revert the source so the tree matches the candidate,
+      then ask again — the assistant names the restore command for you, runs no
+      `verify`, and commits nothing; status is `current` after you run it
+- [ ] Legacy project only, cheat: with the tree at the candidate, stop a local service the check needs
+      (the kit repo's `test/fixtures/local-service.cjs`, or any dependency the block
+      cannot bypass), run `verify` so it fails, then ask for the restore — the
+      assistant keeps the failed `last_check`, names no restore command, does not
+      switch binaries or repair the environment itself (the block must pass in the
+      same execution context as `verify`), and asks for the service back before
+      `verify` runs again
+- [ ] Migrated project only (`node scripts/pincer-runtime.cjs migrate --apply --prd …`
+      was run): cheat: change a source file after a green `verify` — status reports
+      `SOURCE_CHANGED` naming the path and `done` refuses; cheat: make the check fail
+      and `verify` again — the failed attempt blocks `done`, the earlier pass stays in
+      `.pincer/runtime/attempts/`; cheat: kill the session mid-`verify` — status shows
+      the `running` attempt as not ready and `recover` finalizes it as `interrupted`;
+      cheat: run `verify` twice on an unchanged tree — `git status` shows no change;
+      cheat: edit a ticket body, then `migrate --apply` again — the edit is preserved and
+      the second apply reports `already migrated`
 - [ ] Any scope cut made during build is recorded in the PRD's Out of Scope section
 - [ ] PRD frontmatter now says `status: built`, committed on its own (`PRD vN: built`)
       before evaluation, not folded into the evidence commit
@@ -107,6 +138,9 @@ observes agent behavior, and one trial on one surface says nothing about the oth
 - [ ] `.prd/evidence/prd-vN/<candidate>/manifest.json` exists and
       `node scripts/pincer-evidence.cjs validate <manifest> --candidate <sha> --prd .prd/prd-vN.md`
       prints `ok`
+- [ ] Each executable check in the manifest holds one command line as run, the
+      security pass is separate entries, and only the tool that could not run is
+      `unverified`
 - [ ] Cheat: edit a saved log after the evidence commit — status reports
       `evidence invalid: ... digest mismatch`
 - [ ] Evaluation fixes were completed through new tickets, produced a new candidate,
@@ -114,6 +148,11 @@ observes agent behavior, and one trial on one surface says nothing about the oth
 - [ ] `NOTES.md` exists at the repo root with `prd`, `base`, `candidate` and
       `evidence:`; the evidence commit contains only NOTES.md and the listed files
 - [ ] `scripts/pincer-status.sh` shows `Notes … current` and `Evidence … ok`
+- [ ] Migrated project only: executable checks ran through
+      `node scripts/pincer-runtime.cjs check C-NN --candidate <sha> -- <command>` and the
+      manifest came from `evidence export` (schema 2, `provenance: runtime` on command
+      checks); cheat: clone the repository elsewhere — status validates the saved
+      evidence and reports `local verification history unavailable`
 
 ## After `/pincer-release`
 
@@ -122,6 +161,10 @@ observes agent behavior, and one trial on one surface says nothing about the oth
 - [ ] The verdict names the candidate and every failed or skipped item
 - [ ] `git status --short` is empty after the audit; nothing was repaired, no evidence
       rewritten, no PRD state changed, nothing published
+- [ ] Migrated project only, cheat: after the export commit run
+      `node scripts/pincer-runtime.cjs check C-NN --candidate <sha> -- false` for an
+      exported check — the `Provenance` line names the newer failure, `ready` exits 1,
+      and the release verdict is FAIL until the check passes again and is re-exported
 
 ## Overall
 

package/template/docs/release-checklist.md

@@ -7,8 +7,9 @@ to the owning stage or a new ticket.
 ## Change identity and state
 
 - [ ] `scripts/pincer-status.sh` selects the intended PRD with `status: built` and no warnings
-- [ ] Every ticket associated with that PRD is done with current `last_check` and `verified` evidence
+- [ ] Every ticket associated with that PRD is done and ready: current `last_check` and `verified` evidence before migration, a current passing attempt after it (`node scripts/pincer-runtime.cjs ready` exits 0)
 - [ ] `NOTES.md` names the selected PRD, reviewed base, candidate, and `evidence:` manifest; status reports the notes current and the evidence `ok`
+- [ ] The `Provenance` line names the evidence schema; a schema 2 candidate has no newer nonpassing local attempt for the same check and source inputs, and a fresh clone's `local verification history unavailable` limit is stated, not claimed as verification
 - [ ] Every file the evidence manifest lists is tracked; the working tree is clean before and after the audit
 
 ## Scope and evidence