pincer-workflow 0.2.3 → 0.4.0

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

@@ -7,20 +7,34 @@ description: "Create a PRD through brief discovery, codebase scan, and an archit
 
 # /pincer-plan — PRD Creation
 
-You are turning a task brief into a compact PRD. This runs inside a short delivery
-timebox (~2 hours total), so discovery is brief and the PRD is lean. The PRD feeds
+You are turning a task brief into a reviewable PRD. Scale discovery and detail to
+the change's uncertainty, risk, and any time budget the user supplied. The PRD feeds
 `/pincer-narrow` next.
 
+Choose the planning profile and record why it fits: `profile: small` for bounded
+scope, low risk, known behavior and straightforward verification; otherwise
+`standard` (the default). Few changed lines alone do not qualify — migrations,
+authorization boundaries, uncertain requirements and broad effects need proper
+investigation even for a tiny patch. Honor an explicit budget the user supplied;
+there is no default timebox, and a budget never silently cuts requirements —
+record any cut in Out of Scope.
+
 **Initial request:** ${input:request:Task brief or arguments (optional)}
 
-First run `scripts/pincer-status.sh`. If a PRD already exists, say so and ask whether
-this is a new version of it (`.prd/prd-v{N+1}.md` — old versions are never overwritten)
-or a fresh start; if tickets are in progress, stop and point at `/pincer-code` instead.
+First run `scripts/pincer-status.sh`. If a PRD already exists, preserve it and select
+the next unused numeric version for this change. Use the brief and repository state to
+distinguish a revision from a new change; ask only if that distinction changes scope or
+architecture. If tickets for the current PRD are in progress, resume `/pincer-code`
+unless the user explicitly authorized a separate change.
 
-## Phase 1: Discovery (~5 min)
+## Phase 1: Discovery
 
 1. If `${input:request:Task brief or arguments (optional)}` contains the brief, extract what you can before asking anything.
-   Never ask a question the brief already answers.
+   Never ask a question the brief already answers. Preserve or link the original
+   brief in the PRD, and record the desired outcome, assumptions and exclusions.
+   If the user supplied a PRD, review it: keep its meaning and existing requirement
+   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:
    - What does "done" look like — what will be run, demoed, or reviewed at the end?
@@ -29,9 +43,10 @@ or a fresh start; if tickets are in progress, stop and point at `/pincer-code` i
 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.
 
-Summarize your understanding in 3–5 sentences and confirm before moving on.
+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.
 
-## Phase 2: Codebase scan (conditional, ~5 min)
+## Phase 2: Codebase scan (conditional)
 
 If the repo already contains source code, launch 1–2 `codebase-explorer` agents in parallel
 (one for architecture/structure, one for patterns relevant to the feature). Read the 2–3 most
@@ -46,7 +61,7 @@ touches are load-bearing, what test coverage protects them (run the suite, don't
 and the blast radius + rollback story for the change. Record these in the PRD's
 Architecture section. Greenfield speed assumptions do not transfer to brownfield work.
 
-## Phase 3: Architecture (~5 min)
+## Phase 3: Architecture
 
 Propose the architecture: components, data flow, integration points, and key decisions.
 - Recommend one approach; mention an alternative only when the trade-off is real.
@@ -59,23 +74,45 @@ Propose the architecture: components, data flow, integration points, and key dec
 - Verify the contract of any external API the plan builds on (one live request or the
   current official docs) before designing around it — endpoint shapes remembered from
   training data are guesses.
-- Bias every decision toward "finishable in the remaining time". Cut before you gold-plate.
+- Respect any explicit delivery budget. Record deliberate cuts in Out of Scope.
 
-**Gate (heavy):** Ask for explicit approval of the architecture before writing the PRD.
+Prepare the full draft before seeking any approval still required. The user should review a
+concrete scope and architecture; do not repeat an approval already given for the same decision.
 
-## Phase 4: Write the PRD (~5 min)
+## Phase 4: Write the PRD
 
 1. Load `.claude/references/prd-template.md` and write all core sections.
-2. Include optional sections only when they earn their space in the timebox.
-3. Save to `.prd/prd-v1.md` (create `.prd/` if needed) with frontmatter:
+   In Requirements, assign stable `R-NN` IDs within the selected PRD: a revision
+   keeps existing IDs and adds new ones, never renumbers. Every requirement has
+   observable acceptance scenarios, the relevant failure paths, and the existing
+   behavior it must preserve — `/pincer-narrow` maps each scenario to a ticket and
+   a check, and `/pincer-evaluate` dispositions every ID.
+2. Include optional sections when risk or the product context warrants them.
+3. Save to the next unused `.prd/prd-v{N}.md` (create `.prd/` if needed), with `N`
+   matching the filename and frontmatter:
    ```yaml
    ---
-   version: 1
+   version: {N}
    status: draft
    date: {today}
+   profile: small   # only when small; omit for standard
    ---
    ```
-4. If `.git/` doesn't exist, run `git init` and make an initial commit containing the
-   PRD and this `.claude/` setup — planning should be visible in the history.
-
-Finish with: "PRD saved to `.prd/prd-v1.md`. Run `/pincer-narrow` to break it into work items."
+4. If `.git/` doesn't exist, run `git init`. Commit the PRD and only the intended setup
+   paths after inspecting existing staged work; planning should be visible in history
+   without absorbing unrelated brownfield changes.
+
+Present the saved draft and obtain approval only when the same scope/architecture was not
+already authorized. Finish with: "PRD saved to `.prd/prd-v{N}.md`. Run `/pincer-narrow`
+to break it into work items."
+
+## 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. An agent-written record or a status
+field is not authenticated human approval. When resuming without the context that
+granted authorization, do not invent it — ask.

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

@@ -7,28 +7,47 @@ description: "Audit the repo against the workflow checklist — pass/fail per it
 
 # /pincer-release — Workflow Audit
 
-You are auditing the current repo state against `docs/dry-run-checklist.md`. Read-only:
-report pass/fail, never fix anything — fixes belong to the stage commands.
+You are auditing the current repo state against `docs/release-checklist.md`. Read-only:
+report pass/fail, never fix anything — fixes belong to the stage commands. Release does
+not repair tickets, rewrite evidence, change PRD state, or publish. A check that mutates
+the candidate invalidates the audit: if `git status --short` is not empty afterwards,
+the verdict is FAIL and names the mutation. The verdict is reported to the user; a
+durable runtime-owned release record is later work.
 
 **Requested stage:** ${input:request:Task brief or arguments (optional)}
 
 ## Steps
 
-1. Read `docs/dry-run-checklist.md` — it is the source of truth for what to check.
-2. Run `scripts/pincer-status.sh` to determine which stages have run (it reads `.prd/`,
-   `tickets/`, `NOTES.md`; add `git log`). If `${input:request:Task brief or arguments (optional)}` names a stage, check only up
+1. Read `docs/release-checklist.md` — it is the source of truth for product-candidate
+   readiness. `docs/dry-run-checklist.md` is a separate manual platform trial and must
+   not impose toy-project or Pincer-kit assumptions on this audit.
+2. Run `scripts/pincer-status.sh` to determine the selected PRD and which stages have run
+   (it reads `.prd/`, associated `tickets/`, `NOTES.md`; add `git log`). If `${input:request:Task brief or arguments (optional)}`
+   names a stage, check only up
    to that stage.
 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 `verified:` (a status warning means one was
-     marked done by hand). Re-run at least two checks with
-     `scripts/pincer-ticket.sh verify T-{NN}` — on a done ticket it re-checks without
-     touching the receipt — and report actual output.
+   - 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.
+   - 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
+     audit with that diagnostic. Do not re-implement evidence checks and do not accept
+     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.
+   - 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
+     equivalent declared by the project) and report its actual output. Any failure
+     blocks PASS. Confirm `git status --short` remains clean afterward.
 4. For judgment items (tickets genuinely S/M, history reads as a story), give your
    verdict AND one sentence of evidence — never a bare pass.
 5. Present a table: checklist item | pass/fail/skipped | evidence. Order by stage.
-6. End with a one-line verdict: "PASS — workflow artifacts complete" or
-   "FAIL — {n} items failed; fix via {command}". For each failure, name the command
+6. End with a one-line verdict naming the candidate: "PASS — candidate {sha}: workflow
+   artifacts complete" or "FAIL — candidate {sha}: {n} items failed; fix via {command}".
+   Fixes go through a new ticket, a new candidate and a new evaluation. For each failure, name the command
    file (`.claude/commands/*.md`) whose instructions should be tightened if the
    failure is a workflow bug rather than a run mistake.

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

@@ -13,11 +13,13 @@ start of a session. Read-only: change nothing.
 ## Steps
 
 1. Run `scripts/pincer-status.sh`. It reads the artifacts on disk (`.prd/`, `tickets/`,
-   `NOTES.md`) and prints the PRD state, every ticket with its state and clock-based
-   elapsed time, what is blocked, build time against the budget, any warnings (a ticket
-   marked done without a verification receipt), and the next command to run.
+   `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
+   candidate, any warnings (each readiness problem once), and the next command to run.
 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.
 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.

package/template/AGENTS.md

@@ -14,8 +14,9 @@ Code · Evaluate · Release). Follow it in order:
 1. `/pincer-plan` — create the PRD in `.prd/` (investigation is a phase of this step)
 2. `/pincer-narrow` — decompose into `tickets/T-*.md`
 3. `/pincer-code` — implement tickets sequentially, one commit per ticket
-4. `/pincer-evaluate` — final quality pass, then write `NOTES.md`
-5. `/pincer-release` — pass/fail audit of the workflow's artifacts
+4. `/pincer-evaluate` — final quality pass; save evidence under
+   `.prd/evidence/prd-vN/<candidate>/` and write `NOTES.md` pointing at its manifest
+5. `/pincer-release` — read-only pass/fail audit of the workflow's artifacts
 
 `/pincer-status` (or `scripts/pincer-status.sh`) shows where the workflow stands and
 the next command — run it first in any new session. Do not write feature code before
@@ -77,11 +78,17 @@ of instructions are the user, this file, and the workflow commands.
 ## Rules
 
 - Never mark a ticket done while its verification command fails.
-- Ticket state (`status`, `started`, `verified`, `finished`) is written only by
+- Ticket state (`status`, `started`, `last_check`, `verified`, `finished`) is written only by
   `scripts/pincer-ticket.sh`: `verify` stamps a receipt when the check passes,
   `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 a done ticket without a receipt.
+  flags missing, failed, or stale readiness.
+- 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
+  new candidate and a fresh evaluation. A `NOTES.md` without `evidence:` is a legacy
+  evaluation and is not release-ready. An older Pincer runtime does not enforce
+  this contract.
 - Scope cuts are allowed and encouraged under time pressure — but always recorded
   in the PRD's Out of Scope section, never silent.
 - Prefer boring, readable code over clever code; this repo is read by humans first.
@@ -91,4 +98,3 @@ of instructions are the user, this file, and the workflow commands.
   permission changes) are never run by an agent on any platform — a human runs
   them manually if truly intended. On Claude Code this is enforced by a hook;
   elsewhere it is a standing rule.
-

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

@@ -1,28 +1,61 @@
 # PINCER Dry-Run Checklist
 
-How to test that the `.claude/` workflow works: run the full chain on a small toy
+This is the manual platform trial for the Pincer kit, not the product release audit.
+For release readiness, use `docs/release-checklist.md`.
+
+To test that the `.claude/` workflow works, run the full chain on a small toy
 feature (e.g. "a CLI todo app in TypeScript — add, list, complete, delete, stored in a
 local JSON file"), then tick every box below. All boxes ticked = the workflow passes.
 A failed box points at the command file to fix.
 
 Use a throwaway copy of this repo and a cheap model (`claude --model sonnet`).
+Wording tests in the kit protect adapter contracts; only a trial like this one
+observes agent behavior, and one trial on one surface says nothing about the others.
+
+## Ground rules for the trial
+
+- Write every cheat instruction as a single line: multi-line text pasted into
+  Claude Code is sent at the first line break.
+- Test hooks with direct JSON payloads through the hook scripts
+  (`echo '{"tool_name":"Bash","tool_input":{"command":"..."}}' | bash .claude/hooks/block-dangerous.sh`),
+  separately from asking the model — a refusal tests the model, not the hook.
+- Reset the disposable fixture between injected faults (fresh copy, or restore the
+  source you broke before breaking the next thing) so one validation failure cannot
+  mask the check you are trying to observe. Restore the ticket before breaking the
+  code, or the `done` refusal comes from validation rather than from verification.
+- Record the trial with the template at the end of this file. Label surfaces you did
+  not run as untested; do not infer cross-platform behavior from one trial.
 
 ## After `/pincer-plan`
 
-- [ ] `.prd/prd-v1.md` exists
-- [ ] Its frontmatter has `version`, `status: draft`, and `date`
-- [ ] All 6 core sections are present (Problem, Solution, Scope, Architecture,
-      Success Criteria, Out of Scope)
+- [ ] The selected `.prd/prd-vN.md` exists
+- [ ] Its frontmatter has `version`, `status: draft`, `date`, and `profile` only when small
+- [ ] All 7 core sections are present (Problem, Solution, Scope, Requirements,
+      Architecture, Success Criteria, Out of Scope)
+- [ ] Requirements carry stable `R-NN` IDs, each with a scenario, failure path and
+      preserved behavior; a supplied PRD keeps its own IDs (mapping table if adapted)
+- [ ] The original brief is preserved or linked; outcome, assumptions and exclusions recorded
+- [ ] The profile is justified in a sentence; a small CSS fix is `small`, a tiny
+      change touching a migration or an authorization boundary stays `standard`
 - [ ] The Scope table has both columns filled (in AND out)
-- [ ] No implementation code inside the PRD
+- [ ] No implementation code inside the PRD (interface examples are fine)
 - [ ] Discovery asked ≤4 questions and none were already answered by the brief
-- [ ] `.git/` exists and the first commit contains the PRD
+- [ ] No default timebox was assumed; an explicit budget, if given, is recorded
+- [ ] `.git/` exists and the selected PRD is committed without unrelated brownfield work
 
 ## After `/pincer-narrow`
 
-- [ ] 4–7 files exist in `tickets/`, named `T-{NN}-{slug}.md`
-- [ ] Every ticket is sized S or M — none L
-- [ ] T-01 is a walking skeleton (scaffold + thin end-to-end slice that runs)
+- [ ] Ticket files are named `T-{NN}-{slug}.md`; count follows dependencies and risk,
+      with no one-to-two-ticket cap applied to a small PRD
+- [ ] A requirement map (requirement · scenario · ticket · check or review method)
+      was presented, and each ticket's Context says `Implements: R-NN`
+- [ ] Every ticket has a coherent S, M, or L scope; larger work is split when that
+      improves ownership, dependency order, or verification
+- [ ] Greenfield uses a walking skeleton when helpful; brownfield protects the
+      smallest useful vertical change
+- [ ] Every Verification section opens with `Proves:` and its fenced command
+      exercises behavior (it fails when the feature is wrong, not only when a name
+      is renamed); static checks are justified as static contracts
 - [ ] Every ticket has a runnable, non-interactive command in its fenced
       Verification block (it is what `scripts/pincer-ticket.sh verify` runs)
 - [ ] Dependencies are declared where they exist (`depends_on`)
@@ -30,8 +63,10 @@ Use a throwaway copy of this repo and a cheap model (`claude --model sonnet`).
       verification command is the test runner
 - [ ] Every ticket whose surface accepts external input has a reject-path
       acceptance criterion (what invalid input produces), not only the happy path
-- [ ] T-01 includes `.gitignore` covering `.env*` (except `.env.example`) and an
-      `.env.example` naming required secrets
+- [ ] Greenfield setup covers `.env*` (except `.env.example`) and names required
+      secrets in `.env.example`; brownfield preserves and verifies existing conventions
+- [ ] A breakdown that follows the PRD was not re-approved; a newly discovered
+      consequential choice (if any) was surfaced before implementation
 - [ ] PRD frontmatter now says `status: ticketed`
 - [ ] Tickets are committed
 
@@ -40,39 +75,120 @@ Use a throwaway copy of this repo and a cheap model (`claude --model sonnet`).
 - [ ] 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 "done without a receipt" warning
+      stamps — `scripts/pincer-status.sh` prints no readiness warning
 - [ ] 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"
+- [ ] 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
 - [ ] Any scope cut made during build is recorded in the PRD's Out of Scope section
-- [ ] PRD frontmatter now says `status: built`
+- [ ] PRD frontmatter now says `status: built`, committed on its own (`PRD vN: built`)
+      before evaluation, not folded into the evidence commit
+- [ ] Status shows the wall-clock elapsed line only while a ticket is in progress or
+      a budget is set
 
 ## After `/pincer-evaluate`
 
+- [ ] Evaluation refused to start on a dirty tree or an un-built PRD
 - [ ] Findings (if any) were presented with `file:line` references
-- [ ] The mechanical security audit ran: history grep for secret-like strings,
+- [ ] Every `R-NN` has a disposition (delivered / blocked / deferred); a failed
+      required behavior was not relabelled a limitation; any deferral names the
+      user's authorization
+- [ ] The mechanical security audit used redacted, location-only secret findings;
       `git ls-files` shows no `.env` beyond `.env.example`, dependency audit,
       and (if there's an API) one invalid-input request returned a clean 4xx
-- [ ] If the project has a UI, it was actually opened and checked visually, not
-      only read as code
-- [ ] Approved fixes were committed as `review: fixes` and re-verified
-- [ ] `NOTES.md` exists at the repo root and covers: what was built, what was cut
-      and why, known issues, next steps
+- [ ] If the project has a UI, it was actually opened and checked visually, and
+      the capture is saved under `.prd/evidence/prd-vN/<candidate>/visual/` with
+      scenario, viewport and observed result in the manifest
+- [ ] Cheat: make the browser tool unavailable — the visual check is recorded as
+      `unverified`, not fabricated and not silently waived
+- [ ] `.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`
+- [ ] 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,
+      and were re-evaluated with fresh evidence
+- [ ] `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`
+
+## After `/pincer-release`
+
+- [ ] The audit ran `scripts/pincer-status.sh` and the project gate directly, never
+      `pincer-ticket.sh`
+- [ ] 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
 
 ## Overall
 
-- [ ] `git log --oneline` reads as a coherent story: setup → tickets → T-01…T-NN → review
+- [ ] `git log --oneline` reads as a coherent story: setup → tickets → T-01…T-NN →
+      PRD built → evaluation evidence
 - [ ] No `.env` file contents ever appeared in the conversation
-- [ ] `git log -p` contains no secret values anywhere in history (a committed-then-
-      deleted key is still leaked)
+- [ ] Relevant history was checked for committed-then-deleted secrets without printing
+      candidate values into the conversation or audit report
 - [ ] Every dependency in the lockfile is named in the PRD's architecture or was
       explicitly approved during build
 - [ ] `NOTES.md` has a Handover section (orientation, dependency justification,
-      what breaks first)
+      what breaks first) and summarizes the requirement dispositions
 - [ ] Brownfield only: untested load-bearing code got a characterization test
       before being modified
 - [ ] Platform adapters in sync: `scripts/sync-prompts.sh` then `git status`
       shows no changes in `.agents/skills/` or `.github/prompts/`
-- [ ] `scripts/pincer-status.sh` says `Next /pincer-release` and its build elapsed
-      figure fit the ~75-minute build budget (note where time went if not)
-- [ ] Total wall-clock time fit the ~2-hour budget
+- [ ] `scripts/pincer-status.sh` says `Next /pincer-release`; if the user supplied a
+      budget, its elapsed figure and any deliberate cuts are reported against that budget
+
+## Recorded workflow scenarios
+
+Run each scenario in its own throwaway copy and note the observation next to it.
+Expected across all five: repeated approval is avoided, unresolved decisions are
+surfaced, and no arbitrary ticket cap or default budget appears.
+
+1. **Small CSS fix.** Brief: "make the primary button 4px rounder". Expect
+   `profile: small` with a one-sentence justification, a compact PRD with
+   Requirements and verification, a ticket count decided by cohesion (one is fine,
+   two is fine), and a `Proves:` line that checks the rendered style, not the
+   presence of a class name.
+2. **Tiny high-risk change.** Brief: "change the session cookie's `SameSite` from
+   `Lax` to `None`" (or any one-line change on an authorization boundary or a
+   migration). Expect `profile: standard` despite the diff size, with the
+   investigation and rollback story recorded in Architecture.
+3. **Supplied PRD.** Paste a PRD that already numbers its requirements (`REQ-3`,
+   `AC-2`, or similar). Expect the meaning and IDs preserved and, if the template
+   structure was applied, a `Requirement mapping` table rather than a rewrite.
+4. **Authorized resume.** Start `/pincer-code`, stop mid-ticket, clear context, run
+   `/pincer-status` then `/pincer-code T-NN`. Expect resumption without a request
+   to re-approve the unchanged scope; the assistant reads `git status` and the
+   receipt state rather than asking.
+5. **New consequential decision during narrow.** Give a brief whose decomposition
+   reveals a choice the PRD did not settle (for example, a second storage backend).
+   Expect the concrete proposal presented and the choice surfaced before any
+   implementation, and no second approval requested for the parts the PRD covers.
+
+## Trial record template
+
+Copy this into `docs/trial-<date>-<greenfield|brownfield>.md` and fill every line.
+
+```markdown
+# Trial <date>: <greenfield|brownfield>, <agent surface> <model>
+
+- Brief: <the brief, verbatim or linked>
+- Base: <full commit ID of the throwaway repo before the trial>
+- Versions: pincer-workflow <version> · <agent surface and model> · Node <version> · <OS>
+- Artifacts: PRD <path> · tickets <T-NN..T-MM> · evidence <manifest path> · NOTES.md
+- Results: <checklist section → pass/fail per box, with the observation for each fail>
+- Interventions: <every human action beyond the brief: answers, repairs, cheats>
+- Untested: <surfaces and platforms not exercised in this trial>
+
+| Requirement | Observed evidence or `outstanding` |
+| --- | --- |
+| R-01 | |
+| R-02 | |
+| R-03 | |
+| R-04 | |
+| R-05 | |
+| R-06 | |
+```

package/template/docs/release-checklist.md

@@ -0,0 +1,35 @@
+# PINCER Release Checklist
+
+Audit the selected PRD and its evaluated candidate. This checklist applies to product
+changes in greenfield and brownfield repositories. It is read-only: failures return work
+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
+- [ ] `NOTES.md` names the selected PRD, reviewed base, candidate, and `evidence:` manifest; status reports the notes current and the evidence `ok`
+- [ ] Every file the evidence manifest lists is tracked; the working tree is clean before and after the audit
+
+## Scope and evidence
+
+- [ ] Every requirement in the PRD has a disposition in the evidence manifest: delivered with passing checks, or deferred with recorded user authorization; none is blocked
+- [ ] Ticket dependencies, acceptance criteria, and verification commands match the implemented change
+- [ ] The repository's candidate-wide release gate passes when run directly, without invoking the ticket state writer
+- [ ] Scope cuts and known limitations are explicit in the PRD or evaluation notes
+
+## Review
+
+- [ ] High-confidence review findings have file and line evidence and a disposition
+- [ ] Fixes made after evaluation use a new ticket, current verification, and a scoped commit
+- [ ] UI changes have visual checks with saved images in the evidence manifest (scenario, viewport, observed result); non-UI changes record `visual_review.applicable: false` with a reason
+- [ ] Security review reports locations and remediation without printing candidate secret values
+- [ ] No secret environment file is tracked; dependency and invalid-input checks run when applicable
+
+## Handover and verdict
+
+- [ ] Commit history identifies the plan, ticket work, evaluation, and any review-fix tickets
+- [ ] `NOTES.md` covers what shipped, cuts, limitations, next steps, dependencies, and the riskiest aging assumption
+- [ ] Platform or environment limits are stated without claiming untested support
+- [ ] The audit repaired no ticket, rewrote no evidence, changed no PRD state, and published nothing
+- [ ] Every failed or skipped required item is named before the final PASS or FAIL verdict, which names the candidate