pincer-workflow 0.7.0 → 1.0.0

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

@@ -1,86 +0,0 @@
-# Ticket Template
-
-Used by `/pincer-narrow` for every file in `tickets/`. Filename: `T-{NN}-{slug}.md`.
-
-```markdown
----
-ticket: T-{NN}
-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
-One sentence: what to build and why.
-
-## Context
-- Relevant files: `src/path/to/file.ts` (what's there / what to follow)
-- PRD section: which part of the PRD this implements
-- Implements: R-01, R-03 (requirement IDs from the PRD; enabling work that
-  implements no requirement states its purpose in the Objective instead)
-
-## Requirements
-- Concrete, checkable requirements. No vague "handle errors properly" —
-  say which errors and what the user sees.
-
-## Acceptance Criteria
-- [ ] Observable behavior 1
-- [ ] Observable behavior 2
-
-## Verification
-Proves: one line — what this check establishes and which regression it detects.
-```bash
-# command(s) the builder runs to prove the criteria — tests, build, curl, etc.
-```
-
-## Constraints
-- What NOT to do (out-of-scope temptations adjacent to this ticket).
-```
-
-Rules:
-- New tickets always name their PRD with `prd: .prd/prd-vN.md`. The file must
-  have matching version metadata and status `ticketed` or `built` before work
-  starts. This status is a workflow precondition, not proof of user approval.
-  Legacy tickets with one PRD are associated on start; with multiple PRDs, use
-  `scripts/pincer-ticket.sh bind T-NN .prd/prd-vN.md` to resolve explicitly.
-- Supported syntax is deliberately limited: closed `---` frontmatter with unique,
-  unindented `key: value` fields; required `ticket`, `status`, `size`, and
-  `depends_on`. IDs use `T-01` through `T-999999` and match the filename; dependencies
-  use an inline list such as `[T-01, T-02]`, without duplicates or self references.
-- Use exactly one `## Acceptance Criteria` section with nonempty checkboxes.
-  Indentation and `-`, `+`, `*`, or numbered list markers are supported, with
-  `[ ]`, `[x]`, or `[X]`. Every unchecked criterion blocks completion.
-- Use exactly one `## Verification` section containing one closed fenced `bash`
-  block with runnable commands. Missing sections, malformed metadata, duplicate
-  ticket IDs, unsupported checkbox syntax, and invalid Bash fail before a transition.
-- `status` and the attempt/stamp fields `started`, `last_check`, `verified`, `finished` are written only by
-  `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
-  check establishes and which regression it detects. Executable changes need
-  checks that exercise observable behavior — including relevant rejection paths
-  and, in brownfield work, preservation of existing behavior. Reuse adequate
-  focused tests rather than inventing ad-hoc commands. A build, a syntax check, or
-  an identifier grep alone does not prove a feature works: the check must fail
-  when the behavior is wrong, not only when a name is renamed. Static assertions
-  may be primary evidence for static contracts (generated files, adapter wording)
-  when `Proves:` explains that fit.
-- Manual visual judgment is recorded separately during evaluation, never as the
-  Verification command. When a tool the check needs is unavailable, the result is
-  an explicit `unverified`, never fabricated output or a silent waiver.
-- Every ticket must be verifiable without human judgment where possible.
-- If the ticket's surface accepts external input (HTTP, form, file, LLM output),
-  Requirements must state the validation and the rejection behavior, and
-  Acceptance Criteria must include the reject path as an observable behavior.
-- Use a walking skeleton for greenfield work when it reduces integration risk. In
-  brownfield work, protect the smallest useful vertical change and characterize
-  uncovered load-bearing behavior before modifying it.
-- Split a ticket when it contains separate dependencies, owners, or verification paths.

package/template/.github/prompts/pincer-code.prompt.md

@@ -1,240 +0,0 @@
----
-mode: agent
-description: "Implement tickets sequentially with verification and one commit per ticket"
----
-<!-- Generated from .claude/commands/pincer-code.md by scripts/sync-prompts.sh — edit the source, not this file -->
-
-
-# /pincer-code — Ticket Implementation
-
-You are implementing the tickets in `tickets/` sequentially. The approved PRD, ticket
-breakdown, and existing session authorization define the work; run continuously and report
-progress between tickets unless a material scope or design decision appears.
-
-**Initial request:** ${input:request:Task brief or arguments (optional)}
-
-Ticket state lives in the ticket file's frontmatter and is written **only** by
-`scripts/pincer-ticket.sh` (`start` → `verify` → `done`). `verify` runs the ticket's
-Verification block and stamps a receipt only on a green exit; `done` refuses without a
-receipt that matches the current check, or with unticked acceptance criteria. Never edit
-`status`, `started`, `last_check`, `verified`, or `finished` by hand — on Claude Code a hook blocks it.
-On a migrated project (a change binding under `.prd/changes/`; the `Runtime` line of
-`scripts/pincer-status.sh` names it) `verify` records an attempt under `.pincer/runtime/`
-and writes no receipt into the ticket, and `done` consumes the current passing attempt
-against the current source without re-running the check. `.pincer/`, `.prd/changes/` and `.prd/evidence/changes/`
-are written only by the runtime; never edit or delete them by hand. On a project with
-change records (`Runtime  changes …`) every `start`, `verify` and `done` first passes
-the change gate: the ticket's change must be selected in this worktree, `active`
-(`verify` also runs on a `completed` change), on a compatible branch, and authorized
-for the current agreement — otherwise the command refuses with `SELECTION_REQUIRED`,
-`WRONG_CHANGE`, `LIFECYCLE_BLOCKED`, `BASE_MISMATCH`, `DECISION_REQUIRED`,
-`AUTHORIZATION_REQUIRED` or `AGREEMENT_CHANGED` before anything runs or is written.
-
-## Before the loop
-
-Run `scripts/pincer-status.sh`. It lists every ticket's state, what is blocked, elapsed
-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. `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)
-
-1. **Start:** `scripts/pincer-ticket.sh start T-{NN}` — refuses while a `depends_on` ticket
-   isn't done, and stamps the start time. Read the ticket and the files it references.
-   Announce: "Starting T-{NN}: {title}."
-2. **Implement.** Follow the conventions in `AGENTS.md` and the PRD's architecture and
-   visual direction. Installing a dependency not named in the PRD's architecture is a
-   stop-and-ask: verify it's the real package on the registry (linked repo, downloads —
-   hallucinated names get typosquatted), say why it earns its place, and wait for a yes.
-   For an S ticket, implement directly. For an M ticket touching isolated files, you may
-   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 (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
-   the check needs but cannot run yields an explicit `unverified` result, never
-   fabricated output.
-4. **Self-review the diff** before committing: silent failures (empty catches,
-   un-awaited promises), leftover debug code, drift from the ticket's acceptance criteria.
-   Then a security sweep of the same diff:
-   - Check for secret-like assignments without printing values. If a scanner reports a
-     possible secret, report only its file and line until the value is safely redacted;
-     environment references and names in `.env.example` are allowed.
-   - External input touched by this diff is validated server-side, and untrusted
-     content (user input, LLM output) is escaped where rendered — per the
-     Security defaults in `AGENTS.md`.
-   - 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}`. 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`
-   before committing as `T-{NN}: {title}`.
-6. Give a one-line progress update ("T-02 done, 3 remaining") and continue. Quote the
-   wall-clock elapsed figure from `scripts/pincer-status.sh` when it shows one — it
-   appears while a ticket is in progress or a budget is set, and it is not a measure
-   of active execution time.
-
-## Recovering a ticket file
-
-Ticket lifecycle fields are written only by `scripts/pincer-ticket.sh`, and the guard
-also blocks shell restores that would touch ticket files from the assistant's shell:
-`git checkout`/`git restore`/`git switch` naming a ticket path or a normalized
-pathspec that cannot be shown to stay outside `tickets/` (the whole tree, `.`, `:/`,
-`:(top)`, globs, absolute or unexpanded paths, `tickets/…` in any spelling, a
-`-C tickets` prefix), force flags (`-f`, `--force`, `--discard-changes`,
-`--pathspec-from-file`), `git reset --hard|--merge|--keep`, `git stash` (except
-`list`, `show`, `create`, `store`), `git clean -f` without a narrow pathspec,
-`git checkout-index -a` and `git read-tree -u|--reset`, including when wrapped in
-`bash -c`, `eval`, `nice`, `time`, `nohup`, `timeout` or `xargs`. Restoring HEAD
-would erase a newer failed attempt and revive an old passing receipt. Branch
-switches and file-specific restores outside `tickets/` stay allowed. The guard is a
-pattern-based safety net for documented mistake forms, not a complete shell
-boundary; the receipt and status checks remain the source of trust. When a ticket file is malformed or its state was hand
-edited, preserve the malformed contents as they are, report the validation error that
-the script or `scripts/pincer-status.sh` printed, and hand the repair to the user, who
-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;
-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.
-
-## 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
-  figure from `scripts/pincer-status.sh` rather than estimating. If the remaining tickets won't fit,
-  stop and propose a scope cut: which remaining tickets to drop or shrink. Cutting scope
-  deliberately beats an unfinished mess — record the cut in the PRD's Out of Scope.
-- If a ticket reveals the plan was wrong, stop and say so rather than silently diverging.
-  Update the ticket/PRD, then continue.
-
-## When all tickets are done
-
-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."
-
-## Authorization rule (shared by plan, narrow, code and evaluate)
-
-Reuse explicit authorization for the same scope and decisions; ask only about a
-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, 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 — read the `resume` report; an authorization
-it reports as `current` needs no repeat approval, and any other verdict is asked.

package/template/.github/prompts/pincer-evaluate.prompt.md

@@ -1,178 +0,0 @@
----
-mode: agent
-description: "Final quality pass over everything built — high-confidence findings only"
----
-<!-- Generated from .claude/commands/pincer-evaluate.md by scripts/sync-prompts.sh — edit the source, not this file -->
-
-
-# /pincer-evaluate — Final Quality Pass
-
-You are reviewing all work built this session against the PRD and tickets. Autonomous —
-run the pipeline, then present results.
-
-## Steps
-
-1. Run `scripts/pincer-status.sh`. Review only tickets associated with the selected
-   PRD. Every such ticket should be `done` with a current receipt; if one
-   is still open or in progress, stop and ask whether it was cut (then it goes in the
-   PRD's Out of Scope) or should be finished first via `/pincer-code`. Then get the full
-   diff of the change: identify the actual base commit before this change from
-   its ticket commits and recorded context. If it cannot be established, resolve
-   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, 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
-   dispatch two in parallel. (No subagents on this platform? Review the diff yourself
-   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. 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;
-   record the scope decision in the PRD's Out of Scope and evaluate the revised
-   candidate). Compare what was built against every ticket's acceptance criteria and
-   the PRD scope, and list any gaps. Whether the requirement map is complete and each
-   check is semantically adequate is your judgment as reviewer — record that judgment
-   in the evaluation; the kit is not a mechanical traceability engine and does not
-   validate requirement-revision impact.
-4. If the project has a UI, look at it — don't only read the code. Start it, open it in
-   the browser (screenshot via Chrome DevTools MCP if available), and check it against
-   the PRD's Visual Direction and Success Criteria. Note anything visibly broken or off.
-5. Run a mechanical security audit:
-   - Inspect the relevant history with a secret scanner that redacts values, when one is
-     available. Otherwise review likely locations without copying candidate values into
-     output. Report file, line, and remediation only; a secret committed then deleted is
-     still leaked.
-   - `.gitignore` covers `.env*` (except `.env.example`), and `git ls-files | grep -i env`
-     shows only `.env.example`.
-   - `npm audit --omit=dev` (or the ecosystem's equivalent) — report high/critical only.
-   - If there's an HTTP API: hit one endpoint with invalid input (empty, oversized)
-     and confirm a clean 4xx with a generic message, no stack trace.
-6. Filter the agent's findings: report only issues you'd flag in a real PR review —
-   concrete bugs, silent failures, misleading code. Drop nitpicks and style opinions.
-7. Present findings as a short list with `file:line` references, ordered by severity.
-   Security findings always rank above style-adjacent ones. For each, say whether you
-   recommend fixing now through a ticket or recording it as a known issue.
-8. Fix findings clearly within the authorized PRD through a new ticket associated with
-   that PRD. Use `pincer-ticket.sh` to start, verify, and close it, then make a scoped
-   `T-{NN}: {title}` commit. Ask only when a fix changes scope, architecture, or another
-   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>/`.
-   Strict coverage: run every declared command check as
-   `node scripts/pincer-runtime.cjs check C-NN --candidate <sha>` (no command, no
-   timeout: the map's declaration is the only source, and a supplied command is
-   `CHECK_UNDECLARED`); record each declared review or visual obligation in the
-   draft with its `result` and an artifact saved under the candidate's evidence
-   directory (a required one that is not passed with an artifact is
-   `REVIEW_MISSING`); write `adequacy: { verdict: "adequate" | "inadequate", note }`;
-   list every declared check once and no `requirements` (they are derived). The
-   export writes the inventory and map snapshots under `coverage/`, derives the
-   scenario and requirement rows and `delivery` (original versus agreed scope) and
-   validates them against the committed candidate; an `inadequate` judgment or a
-   failed required check is recorded honestly and blocks readiness. Migrated
-   project without strict coverage (the `Runtime` status line names a change): run
-   each executable check through the runtime on the clean candidate view —
-   `node scripts/pincer-runtime.cjs check C-NN --candidate <sha> -- <command>` (one
-   command per check, the command line as run; `npm test` stays one aggregate check) —
-   then write the authored fields to a draft outside the evidence directory, for
-   example `.pincer/drafts/<sha>.json`: `environment.tools` and `environment.limitations`,
-   `coverage_review`, `requirements`, review and visual checks with their saved
-   artifacts, `visual_review`, and a stub `{"id": "C-NN", "kind": "command",
-   "required": true|false}` for each executable check. Then run
-   `node scripts/pincer-runtime.cjs evidence export --candidate <sha> --base <base> --prd .prd/prd-vN.md --draft <file>`.
-   The export writes `checks/C-NN.log` from the captured logs, fills `command`,
-   `result`, `provenance: runtime` and `attempt` from the attempts, labels review and
-   visual checks `provenance: authored`, computes the digests and writes an evidence
-   schema 2 manifest; it refuses a dirty tree, a HEAD that is not the candidate, a stub
-   without an attempt, and a `passed` or `failed` command result written by hand. On a
-   project with change records the export also appends the evaluation to the change's
-   locator `.prd/evidence/changes/<id>.json` (the identity of this change's
-   evaluation; root `NOTES.md` stays the human summary and may be overwritten by a
-   later change's evaluation without losing this one) — commit the locator with the
-   evidence. A tool that cannot run is recorded as an authored command check with
-   `result: unverified` and a note, as before. Legacy project (no change binding):
-   author the schema 1 manifest as follows.
-   - `checks/C-NN.log` — the command and a redacted summary or safe log of each
-     executable check. Never secrets, never an environment dump. Record
-     one check per command: `command` holds the command line as run, never prose
-     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.
-   - `review/code-quality.md` — the reviewer's findings from step 2 with their
-     dispositions, or its explicit no-findings statement, recorded as a check of
-     kind `review` and referenced by the requirements it covers.
-   - `manifest.json` — evidence schema 1 (field list in the header of
-     `scripts/pincer-evidence.cjs`): selected PRD, full `base` and `candidate` IDs,
-     `created`, `environment` with tool limitations, `coverage_review` (your judgment
-     from step 3), one `requirements` entry per `R-NN` with its disposition, tickets
-     and check IDs, one `checks` entry per check with `kind`, `required`, `result`,
-     `command`, timestamp and artifact paths, and `artifacts` with digests from
-     `node scripts/pincer-evidence.cjs digest <file>...`.
-   A tool you cannot run yields a check with `result: unverified` and a note — never a
-   fabricated artifact. A deferred requirement carries `authorized_by` naming the
-   user's explicit authorization. Then run
-   `node scripts/pincer-evidence.cjs validate .prd/evidence/prd-vN/<candidate>/manifest.json --candidate <candidate> --prd .prd/prd-vN.md`
-   and correct the manifest until it prints `ok`; the same validator runs in status
-   and release. It checks the record's consistency, not that the commands ran.
-10. Close out: write a brief `NOTES.md` at the repo root with frontmatter:
-   ```yaml
-   ---
-   prd: .prd/prd-vN.md
-   base: <full reviewed base commit ID>
-   candidate: <full reviewed candidate commit ID>
-   evidence: .prd/evidence/prd-vN/<candidate>/manifest.json
-   ---
-   ```
-   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`, 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
-   oriented (which file to read first), what each dependency is for and why it earned
-   its place, and what breaks first as the code ages (the riskiest assumption, the
-   least-tested path). This is the first document a reviewer of this repo should read;
-   summarize the requirement dispositions from the manifest in it.
-11. Suggest `/pincer-release` as the final step: "Run `/pincer-release` for a pass/fail audit of the
-   whole workflow's artifacts."
-
-## Authorization rule (shared by plan, narrow, code and evaluate)
-
-Reuse explicit authorization for the same scope and decisions; ask only about a
-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, 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 — read the `resume` report; an authorization
-it reports as `current` needs no repeat approval, and any other verdict is asked.