pincer-workflow 0.2.3 → 0.4.0

package/template/.claude/hooks/ticket-guard.sh

@@ -1,66 +1,9 @@
 #!/bin/bash
-# PreToolUse guard for ticket state. A ticket's state fields — status
-# (in_progress / done), started, verified, finished — are written only by
-# scripts/pincer-ticket.sh, whose `done` needs a passing verification receipt.
-# This hook makes that script the only door on Claude Code: editing tools may
-# not write those fields into tickets/T-*.md, and Bash may not sed/echo them in.
-# Creating a ticket with `status: open` and ticking acceptance boxes stay allowed.
-# Exit 2 blocks the tool call; stderr goes back to the agent.
-#
-# A guard against carelessness, not an adversary: the agent could still route
-# around it, but it can no longer do so by accident or habit.
-
-input=$(cat)
-
-field() { # dotted path into the hook JSON, e.g. tool_input.file_path
-  if command -v jq >/dev/null 2>&1; then
-    printf '%s' "$input" | jq -r ".$1 // empty" 2>/dev/null
-  elif command -v python3 >/dev/null 2>&1; then
-    printf '%s' "$input" | python3 -c '
-import json, sys
-d = json.load(sys.stdin)
-for k in sys.argv[1].split("."):
-    d = d.get(k, "") if isinstance(d, dict) else ""
-print(d if isinstance(d, str) else json.dumps(d))' "$1" 2>/dev/null
-  else # crude fallback: last path segment, first match, no unescaping
-    printf '%s' "$input" | grep -oE "\"${1##*.}\"[[:space:]]*:[[:space:]]*\"([^\"\\\\]|\\\\.)*\"" | head -1 | sed -E 's/^"[^"]*"[[:space:]]*:[[:space:]]*"//; s/"$//'
-  fi
-}
-
-tool=$(field tool_name)
-# `status: open` is fine; these are the fields only the script may write.
-PROTECTED='(^|\\n|[[:space:]])(status:[[:space:]]*(in_progress|done)|started:|verified:|finished:)'
-TICKET='(^|/)tickets/T-[0-9]+[^/]*\.md$'
-
-block() {
-  echo "Blocked by PINCER ticket guard: $1 Use pincer-ticket.sh (path in the /pincer-code playbook): 'verify T-NN' writes the receipt when the check passes, 'done T-NN' flips the status. Ticking acceptance boxes and editing the body are fine." >&2
+# PreToolUse guard for ticket lifecycle fields. The Node helper parses JSON,
+# compares existing and proposed frontmatter for editing tools, and permits only
+# exact pincer-ticket.sh lifecycle calls as shell writers.
+command -v node >/dev/null 2>&1 || {
+  echo 'Blocked by PINCER ticket guard: Node.js is required to parse hook input safely.' >&2
   exit 2
 }
-
-case "$tool" in
-  Edit|Write|MultiEdit)
-    file=$(field tool_input.file_path)
-    printf '%s' "$file" | grep -qE "$TICKET" || exit 0
-    case "$tool" in
-      Edit)  new=$(field tool_input.new_string) ;;
-      Write) new=$(field tool_input.content) ;;
-      *)     new=$(field tool_input.edits) ;;
-    esac
-    [ -n "$new" ] || new=$input
-    if printf '%s' "$new" | grep -qE "$PROTECTED"; then
-      block "ticket state fields (status in_progress/done, started, verified, finished) are never written by hand."
-    fi
-    ;;
-  Bash)
-    cmd=$(field tool_input.command)
-    [ -n "$cmd" ] || cmd=$input
-    printf '%s' "$cmd" | grep -q 'pincer-ticket.sh' && exit 0
-    if printf '%s' "$cmd" | grep -qE 'tickets/|T-[0-9][0-9]' &&
-       printf '%s' "$cmd" | grep -qE 'status:[[:space:]]*(in_progress|done)|started:|verified:|finished:' &&
-       printf '%s' "$cmd" | grep -qE '(sed|perl)[[:space:]]+(-[a-zA-Z]*i|-i)|>|tee[[:space:]]|python|node|ruby'; then
-      block "that command writes ticket state fields from the shell."
-    fi
-    ;;
-esac
-
-exit 0
+exec node "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/hook-policy.cjs" ticket

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

@@ -1,17 +1,33 @@
 # PRD Template
 
-Used by `/pincer-plan` Phase 4. Core sections always included; optional sections only when they
-earn their space in the timebox. Keep the whole PRD under ~2 pages.
+Used by `/pincer-plan` Phase 4. Core sections are always included. Add optional detail
+when uncertainty, product context, or risk warrants it; a small fix may remain compact.
+
+## Profile
+
+The frontmatter field `profile: small | standard` sets the planning weight; a PRD
+without it is `standard`. `small` means bounded scope, low risk, known behavior and
+straightforward verification. Few changed lines alone do not qualify: migrations,
+authorization boundaries, uncertain requirements and broad effects stay `standard`
+even for a tiny patch. The PRD records in one or two sentences why the profile fits.
+
+A small PRD keeps Problem (with the outcome), Scope, Requirements with scenarios,
+Success Criteria (its verification), risks and exclusions, and omits empty sections
+and repetition. Interface examples may clarify a contract; implementation code must
+not substitute for requirements in any profile.
 
 ---
 
 ## Core Sections (always include)
 
 ### 1. Problem
-What problem does this solve? Who has it? (2–4 sentences.)
+What problem does this solve? Who has it? (2–4 sentences.) Preserve or link the
+original brief (quote it in an appendix or name where it lives) so the source of
+every requirement stays reviewable.
 
 ### 2. Solution
-One-paragraph summary of what we're building.
+One-paragraph summary of what we're building: the desired outcome, the assumptions
+it rests on, and what it deliberately excludes.
 
 ### 3. Scope
 
@@ -19,7 +35,22 @@ One-paragraph summary of what we're building.
 | --- | --- |
 | ... | ... |
 
-### 4. Architecture
+### 4. Requirements
+One entry per requirement with a stable ID. IDs are assigned once within this PRD
+and never renumbered: a revision keeps existing IDs and adds new ones. Tickets
+name the IDs they implement and evaluation dispositions every ID.
+
+#### R-01 — short title
+- Scenario: an observable acceptance scenario (given / when / then, or a command
+  and its expected output). Add one line per scenario.
+- Failure path: what invalid input or the relevant failure produces.
+- Preserve: existing behavior this must not change (brownfield).
+
+When the user supplied a PRD, keep its meaning and its existing requirement IDs.
+If its structure needs adapting to this template, add a `Requirement mapping`
+table under this section (`their section or ID → R-NN`) instead of rewriting it.
+
+### 5. Architecture
 
 #### Structure
 ```
@@ -32,13 +63,13 @@ What each component does, owns, and depends on.
 #### Data flow
 Input → processing → output.
 
-### 5. Success Criteria
+### 6. Success Criteria
 
 | Criterion | How to verify |
 | --- | --- |
 | ... | a command to run or a thing to observe |
 
-### 6. Out of Scope
+### 7. Out of Scope
 Explicit list. Anything cut for time during `/pincer-code` gets appended here with a reason.
 
 ---
@@ -56,13 +87,14 @@ and where they live (server-side only, named in `.env.example`), and what the cl
 sees on failure (generic message — details stay in server logs).
 
 ### Dependencies & Risks
-Only if something outside our control could sink the timebox.
+Include when something outside our control or a migration/rollback concern could sink delivery.
 
 ---
 
 ## Formatting Rules
 
-- Save as `.prd/prd-v{N}.md` with YAML frontmatter (`version`, `status`, `date`).
+- Save as `.prd/prd-v{N}.md` with YAML frontmatter (`version`, `status`, `date`,
+  and `profile` when small).
 - Status lifecycle: `draft → ticketed → built`.
 - Diagrams as ASCII or markdown tables only.
 - No implementation code and no exact line numbers — those belong in tickets.

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

@@ -6,7 +6,8 @@ Used by `/pincer-narrow` for every file in `tickets/`. Filename: `T-{NN}-{slug}.
 ---
 ticket: T-{NN}
 status: open        # open | in_progress | done
-size: S             # S (≤15 min) | M (≤30 min)
+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]
 ---
 
@@ -16,6 +17,8 @@ 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" —
@@ -26,6 +29,7 @@ One sentence: what to build and why.
 - [ ] 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.
 ```
@@ -35,15 +39,44 @@ One sentence: what to build and why.
 ```
 
 Rules:
-- `status` and the stamps `started`, `verified`, `finished` are written only by
+- 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.
 - 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.
-- Ticket T-01 is the walking skeleton: scaffold + thin end-to-end slice that runs.
-- If a ticket needs more than ~30 minutes, split it before writing it.
+- 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/.codex/README.md

@@ -28,8 +28,8 @@ commit the result.
 
 ## Recommended posture (`~/.codex/config.toml`)
 
-Codex has no PreToolUse hooks, so PINCER's guardrail posture is expressed
-through the sandbox and approval policy instead:
+This kit does not currently install a Codex hook adapter. Use Codex's sandbox,
+approval policy, and project instructions as the guardrail posture:
 
 ```toml
 approval_policy = "on-request"     # agent asks before escalating
@@ -38,8 +38,8 @@ sandbox_mode   = "workspace-write" # writes confined to the repo; no network by
 
 The ticket scripts are plain bash and work here unchanged:
 `scripts/pincer-ticket.sh start|verify|done T-NN` and `scripts/pincer-status.sh`.
-What Codex lacks is the hook that stops an agent hand-editing ticket state, so the
-rule in `AGENTS.md` carries that weight; `$pincer-status` warns about any ticket
+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.
 
 Never run with approvals disabled. The destructive-command rule in `AGENTS.md`

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

@@ -7,8 +7,9 @@ description: "Implement tickets sequentially with verification and one commit pe
 
 # /pincer-code — Ticket Implementation
 
-You are implementing the tickets in `tickets/` sequentially. Mostly autonomous: after the
-user confirms the starting point, run continuously and report progress between tickets.
+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)}
 
@@ -16,14 +17,15 @@ 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`, `verified`, or `finished` by hand — on Claude Code a hook blocks it.
+`status`, `started`, `last_check`, `verified`, or `finished` by hand — on Claude Code a hook blocks it.
 
 ## 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. Confirm the starting point with the user, then go.
+from wherever the receipt says you are. Do not ask the user to reconfirm unchanged,
+previously authorized work.
 
 ## Loop (per ticket, in dependency order)
 
@@ -39,14 +41,17 @@ from wherever the receipt says you are. Confirm the starting point with the user
    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,
-   not assumptions. Green output is the definition of done, not your confidence.
+   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:
-   - No secret values: run
-     `git diff | grep -iE '(api[_-]?key|secret|token|password)[[:space:]]*[:=]'`
-     and treat any hit that isn't a `process.env` reference or a name in
-     `.env.example` as a blocker.
+   - 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`.
@@ -55,14 +60,41 @@ from wherever the receipt says you are. Confirm the starting point with the user
 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
    criterion that was cut is a scope change to record in the PRD, not a box to skip.
-   Commit code and ticket file together: `git add -A && git commit -m "T-{NN}: {title}"`.
-6. Give a one-line progress update using the elapsed figure from
-   `scripts/pincer-status.sh` ("T-02 done, 3 remaining, 38m elapsed of 75m") and continue.
+   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.
 
-## Timebox rules
+## Recovering a ticket file
 
-- The budget is ~75 minutes of build time, measured by `scripts/pincer-status.sh` from
-  the first ticket's start stamp — never estimated. If the remaining tickets won't fit,
+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. Automated recovery that preserves attempt history is later work (M1).
+
+## 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.
@@ -70,5 +102,18 @@ from wherever the receipt says you are. Confirm the starting point with the user
 
 ## When all tickets are done
 
-Update the PRD to `status: built`, then finish with:
+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. 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-evaluate.prompt.md

@@ -12,23 +12,42 @@ run the pipeline, then present results.
 
 ## Steps
 
-1. Run `scripts/pincer-status.sh`. Every ticket should be `done` with a receipt; if one
+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 session: `git log --oneline` and `git diff <first-commit>..HEAD`.
+   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 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.)
-3. Yourself, in parallel, check spec compliance: does what was built match every ticket's
-   acceptance criteria and the PRD scope? List any gaps.
+   Keep the reviewer's report — or its explicit no-findings statement — for step 9,
+   where it is saved as an artifact; a review that left no record cannot be audited.
+3. Yourself, in parallel, check spec compliance. For every requirement `R-NN` in the
+   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 (cheap, ~2 min — do all of these):
-   - Whole history, not just the tree:
-     `git log -p | grep -iE '(api[_-]?key|secret|token|password)[[:space:]]*[:=]'` —
-     a secret committed then deleted is still leaked.
+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.
@@ -38,15 +57,66 @@ run the pipeline, then present results.
    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 (within the timebox) or noting as known-issue.
-8. Fix what the user approves (or everything clearly broken, if time allows), verify,
-   and commit as `review: fixes`.
-9. Close out: write a brief `NOTES.md` at the repo root — what was built, what was cut
+   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>/`:
+   - `checks/C-NN.log` — the command and a redacted summary or safe log of each
+     executable check. Never secrets, never an environment dump.
+   - `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 and its listed artifacts — and nothing else —
+   as `evaluate: PRD vN candidate <short sha>`. Status accepts this later commit only
+   when its diff from the candidate is limited to `NOTES.md` and the evidence files
+   the manifest lists; changes to source, tests, configuration, tickets, the PRD or
+   other evaluations require reevaluation. Legacy notes without these references
+   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). Commit it. This is the first document a reviewer of this repo
-   should read.
-10. Suggest `/pincer-release` as the final step: "Run `/pincer-release` for a pass/fail audit of 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. 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-narrow.prompt.md

@@ -7,47 +7,92 @@ description: "Turn the approved PRD into local, AI-ready ticket files"
 
 # /pincer-narrow — PRD to Local Tickets
 
-You are decomposing the PRD into small, independently verifiable tickets stored as local
-markdown files (no external tracker needed). Target: 4–7 tickets that fit a ~75-minute
-build window.
+You are decomposing the PRD into coherent, independently verifiable tickets stored as
+local markdown files (no external tracker needed). Ticket count and size follow the
+change's dependencies and risk, plus any budget the user supplied. There is no hard
+one-to-two-ticket cap for small PRDs and no default timebox: cohesion and dependencies
+decide the count. A breakdown that follows the PRD needs no second approval; a newly
+discovered consequential choice is surfaced before implementation.
 
 **Initial request:** ${input:request:Task brief or arguments (optional)}
 
 ## Steps
 
-1. Run `scripts/pincer-status.sh`. If tickets already exist, ask before adding to them —
-   new tickets continue the numbering, existing ones are never renumbered. Then read the
+1. Run `scripts/pincer-status.sh`. If tickets already exist for another PRD, leave them
+   as history. New tickets continue the numbering and existing ones are never renumbered.
+   If tickets already exist for this PRD, extend them only when the current request already
+   authorizes that work; otherwise present the concrete addition before asking. Then read the
    PRD (`${input:request:Task brief or arguments (optional)}` or the latest `.prd/prd-v*.md`). If its status isn't `draft`, ask
    which PRD to use.
 2. Decompose into tickets. Rules:
-   - Each ticket is one coherent unit: sized S or M, never L. Split anything larger.
-   - Ticket 1 is always the walking skeleton: project scaffold + a thin end-to-end slice
-     that runs. Everything after builds on a working base.
+   - Each ticket is one coherent unit. Use S, M, or L as relative scope indicators and
+     split work when that improves dependency order, verification, or ownership.
+   - For greenfield work, use a walking skeleton when it reduces integration risk. For
+     brownfield work, begin with the smallest protected vertical change; add a
+     characterization ticket before changing load-bearing code that lacks coverage.
    - Order by dependency; note blockers explicitly ("depends on T-01").
+   - Build the requirement map: for every `R-NN` in the PRD and each of its
+     scenarios, name the ticket that owns the implementation and the executable
+     check that exercises it, or an explicit review method when no executable check
+     exists. Record the IDs in each ticket's Context as `Implements: R-NN, R-MM`.
+     Enabling work that implements no requirement states its purpose in the ticket
+     Objective. Resolve missing coverage and conflicting criteria with the user
+     before implementation; do not start with an unmapped required scenario.
    - 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").
+   - 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,
+     preservation of existing behavior) and fail when the behavior is wrong, not only
+     when an identifier is renamed. Reuse adequate focused tests. A build, a syntax
+     check, or an identifier grep alone is not proof; static assertions are primary
+     evidence only for static contracts such as generated files, and `Proves:` says so.
+   - Adequacy is a judgment about what the command observes, never a word match: do
+     not call a command sufficient because it contains `grep`, `test`, or a runner
+     name, nor insufficient for lacking them. Manual visual judgment is recorded
+     separately in evaluation; a tool the check needs but cannot run yields an
+     explicit `unverified` result, never fabricated evidence or a silent waiver.
    - If the brief or stack implies automated tests, at least one ticket's verification
      command must be the test runner (e.g. `npm test`) — manual checks alone don't count.
    - Any ticket whose surface accepts external input (HTTP endpoint, form, file,
      LLM output) gets an acceptance criterion for the reject path — what invalid
      input produces (e.g. "empty goal → 400 with a clear message"), not only the
      happy path.
-   - The walking skeleton (T-01) includes `.gitignore` covering `.env*` (except
-     `.env.example`) and an `.env.example` naming any required secrets — before
-     any secret can exist in the repo.
-   - Brownfield: a ticket that modifies load-bearing code with no test coverage
-     is preceded by a characterization ticket — a test that pins the current
-     behavior before any ticket is allowed to change it.
+   - A greenfield setup ticket includes `.gitignore` covering `.env*` (except
+     `.env.example`) and an `.env.example` naming any required secrets before any
+     secret can exist in the repo. In brownfield repositories, preserve and verify
+     the existing ignore and environment conventions.
 3. Write each ticket to `tickets/T-{NN}-{slug}.md` using
-   `.claude/references/ticket-template.md`, with `status: open`. The other state fields
-   (`started`, `verified`, `finished`) are added later by `scripts/pincer-ticket.sh` —
+   `.claude/references/ticket-template.md`, with `status: open` and an explicit
+   `prd: .prd/prd-vN.md` naming the selected PRD. Never infer this association from
+   numbering or old notes. The other state fields
+   (`started`, `last_check`, `verified`, `finished`) are added later by `scripts/pincer-ticket.sh` —
    never write them yourself.
-4. Present the ticket list (number, title, size, dependencies) as a table.
+4. Present the ticket list (number, title, size, dependencies) as a table, followed
+   by the requirement map as a second table (requirement · scenario · ticket · check
+   or review method). Whether the map is complete and each check is adequate is your
+   judgment as the author; say so rather than presenting the table as mechanical proof.
 
-**Gate (medium):** Ask for approval of the breakdown and build order. Adjust if pushed back.
+Present the concrete breakdown and build order as a report, not a question. Reuse
+existing authorization for the same scope and order.
 
-5. After approval, update the PRD frontmatter to `status: ticketed`, commit the tickets
-   (`git add .prd tickets && git commit`), and finish with:
+5. Finalize. A breakdown that follows the PRD is already authorized by the PRD: do not
+   ask whether to proceed. Update the selected PRD frontmatter to `status: ticketed`,
+   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:
    "Tickets ready in `tickets/`. Run `/pincer-code` to start implementing."
+
+## 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.