pincer-workflow 0.2.2 → 0.3.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,7 +1,7 @@
 # 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.
 
 ---
 
@@ -56,7 +56,7 @@ 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.
 
 ---
 

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]
 ---
 
@@ -35,7 +36,22 @@ 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.
@@ -45,5 +61,7 @@ Rules:
 - 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

@@ -15,6 +15,10 @@ $pincer-narrow   →   $pincer-code   →   $pincer-evaluate   →   $pincer-rel
 $pincer-status
 ```
 
+The skills point at the canonical playbooks, the two subagent rubrics and the
+PRD/ticket templates under `.claude/` — those ship on every platform, so the
+directory is expected here even without Claude Code.
+
 `/skills` lists what Codex has loaded — the six `pincer-*` entries should be
 there whenever you start `codex` inside this repo. The skills are generated
 from `.claude/commands/` by `scripts/sync-prompts.sh` (cross-references are
@@ -24,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
@@ -34,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,21 +17,22 @@ 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)
 
 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 `CLAUDE.md` and the PRD's architecture and
+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.
@@ -43,26 +45,27 @@ from wherever the receipt says you are. Confirm the starting point with the user
 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 `CLAUDE.md`.
+     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}`. 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}"`.
+   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 using the elapsed figure from
-   `scripts/pincer-status.sh` ("T-02 done, 3 remaining, 38m elapsed of 75m") and continue.
+   `scripts/pincer-status.sh` ("T-02 done, 3 remaining, 38m elapsed") and continue.
 
-## Timebox rules
+## Budget rules
 
-- 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,
+- 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.

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

@@ -12,10 +12,15 @@ 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>`.
+   Require a clean candidate before review, excluding only the notes being written.
 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
@@ -25,10 +30,11 @@ run the pipeline, then present results.
 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.
@@ -39,9 +45,22 @@ run the pipeline, then present results.
 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
+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.
+9. 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>
+   ---
+   ```
+   Record the candidate before the separate NOTES commit. Status accepts a later
+   commit only when its diff from the candidate changes solely `NOTES.md`; changes
+   to source, tickets, or PRD 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

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

@@ -7,22 +7,26 @@ 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.
 
 **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").
    - 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`
@@ -34,20 +38,22 @@ build window.
      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.
 
-**Gate (medium):** Ask for approval of the breakdown and build order. Adjust if pushed back.
+Present the concrete breakdown and build order. Reuse existing authorization for the same
+scope and order; ask only when the breakdown introduces a material decision or scope change.
 
-5. After approval, update the PRD frontmatter to `status: ticketed`, commit the tickets
-   (`git add .prd tickets && git commit`), and finish with:
+5. Once authorized, 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. Finish with:
    "Tickets ready in `tickets/`. Run `/pincer-code` to start implementing."

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

@@ -7,17 +7,19 @@ 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.
 
 **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.
@@ -29,9 +31,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 +49,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 +62,28 @@ 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:
+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}
    ---
    ```
-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.
+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.
 
-Finish with: "PRD saved to `.prd/prd-v1.md`. Run `/pincer-narrow` to break it into work items."
+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."

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

@@ -7,24 +7,29 @@ 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:
+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.
 
 **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.
+   - 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.

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

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

package/template/AGENTS.md

@@ -77,11 +77,11 @@ 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.
 - 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 +91,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.
-