pincer-workflow 0.1.0 → 0.2.1

package/template/.codex/prompts/pincer-evaluate.md

@@ -8,7 +8,10 @@ run the pipeline, then present results.
 
 ## Steps
 
-1. Get the full diff of the session: `git log --oneline` and `git diff <first-commit>..HEAD`.
+1. Run `scripts/pincer-status.sh`. Every ticket should be `done` with a 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`.
 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

package/template/.codex/prompts/pincer-narrow.md

@@ -11,14 +11,19 @@ build window.
 
 ## Steps
 
-1. Read the PRD (`$ARGUMENTS` or the latest `.prd/prd-v*.md`). If its status isn't
-   `draft`, ask which PRD to use.
+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
+   PRD (`$ARGUMENTS` 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.
    - Order by dependency; note blockers explicitly ("depends on T-01").
-   - Every ticket gets a verification command or check the builder can actually run.
+   - 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").
    - 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,
@@ -32,7 +37,9 @@ build window.
      is preceded by a characterization ticket — a test that pins the current
      behavior before any ticket is allowed to change it.
 3. Write each ticket to `tickets/T-{NN}-{slug}.md` using
-   `.claude/references/ticket-template.md`.
+   `.claude/references/ticket-template.md`, with `status: open`. The other state fields
+   (`started`, `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.

package/template/.codex/prompts/pincer-plan.md

@@ -9,6 +9,10 @@ timebox (~2 hours total), so discovery is brief and the PRD is lean. The PRD fee
 
 **Initial request:** $ARGUMENTS
 
+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.
+
 ## Phase 1: Discovery (~5 min)
 
 1. If `$ARGUMENTS` contains the brief, extract what you can before asking anything.

package/template/.codex/prompts/pincer-release.md

@@ -11,12 +11,16 @@ report pass/fail, never fix anything — fixes belong to the stage commands.
 ## Steps
 
 1. Read `docs/dry-run-checklist.md` — it is the source of truth for what to check.
-2. Determine which stages have run, from the artifacts present (`.prd/`, `tickets/`,
-   git log, `NOTES.md`). If `$ARGUMENTS` names a stage, check only up to that stage.
+2. Run `scripts/pincer-status.sh` to determine which stages have run (it reads `.prd/`,
+   `tickets/`, `NOTES.md`; add `git log`). If `$ARGUMENTS` 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`.
-   - Ticket verification commands: run at least two, report actual output.
+   - 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.
 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/.codex/prompts/pincer-status.md

@@ -0,0 +1,19 @@
+<!-- Generated from .claude/commands/pincer-status.md by scripts/sync-prompts.sh — edit the source, not this file -->
+
+
+# /pincer-status — Where are we?
+
+You are orienting in a repo that uses PINCER, typically after a context reset or at the
+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.
+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}`.

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

@@ -12,40 +12,59 @@ user confirms the starting point, run continuously and report progress between t
 
 **Initial request:** ${input:request:Task brief or arguments (optional)}
 
+Ticket state lives in the ticket file's frontmatter and is written **only** by
+`scripts/pincer-ticket.sh` (`start` → `verify` → `done`). `verify` runs the ticket's
+Verification block and stamps a receipt only on a green exit; `done` refuses without a
+receipt that matches the current check, or with unticked acceptance criteria. Never edit
+`status`, `started`, `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.
+
 ## Loop (per ticket, in dependency order)
 
-1. **Read the ticket** and the files it references. Announce: "Starting T-{NN}: {title}."
+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
    visual direction. Installing a dependency not named in the PRD's architecture is a
    stop-and-ask: verify it's the real package on the registry (linked repo, downloads —
-   hallucinated names get typosquatted), say why it earns its place, and wait for a yes. For an S ticket, implement directly. For an M ticket touching
-   isolated files, you may dispatch a subagent with a clean prompt: paste the full ticket
-   body, the relevant conventions, and nothing else.
-3. **Verify.** Run the ticket's verification command(s). If they fail, fix before moving
-   on — never mark a ticket done on a red check. Report actual output, not assumptions.
+   hallucinated names get typosquatted), say why it earns its place, and wait for a yes.
+   For an S ticket, implement directly. For an M ticket touching isolated files, you may
+   dispatch a subagent with a clean prompt: paste the full ticket body, the relevant
+   conventions, and nothing else.
+3. **Verify:** `scripts/pincer-ticket.sh verify T-{NN}` — runs the Verification block and
+   writes the receipt only if it exits 0. Red → fix and re-run; report the actual output,
+   not assumptions. Green output is the definition of done, not your confidence.
 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 --cached | grep -iE '(api[_-]?key|secret|token|password)[[:space:]]*[:=]'`
+     `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.
    - 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`.
    - No error path leaks internals (stack traces, key names with values) to the client.
-5. **Commit** with message `T-{NN}: {title}` and mark the ticket done: set
-   `status: done` in its frontmatter and tick every verified acceptance-criteria
-   checkbox (`- [ ]` → `- [x]`) in the same edit. A ticket is never `done` with
-   unticked criteria — if a criterion was cut, that's a scope change to record,
-   not a box to skip.
-6. Give a one-line progress update ("T-02 done, 3 remaining, ~40 min elapsed") and continue.
+   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}"`.
+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.
 
 ## Timebox rules
 
-- Track elapsed time against the ~75-minute build budget. If you're at risk of running
-  out, 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.
+- 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,
+  stop and propose a scope cut: which remaining tickets to drop or shrink. Cutting scope
+  deliberately beats an unfinished mess — record the cut in the PRD's Out of Scope.
 - If a ticket reveals the plan was wrong, stop and say so rather than silently diverging.
   Update the ticket/PRD, then continue.
 

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

@@ -12,7 +12,10 @@ run the pipeline, then present results.
 
 ## Steps
 
-1. Get the full diff of the session: `git log --oneline` and `git diff <first-commit>..HEAD`.
+1. Run `scripts/pincer-status.sh`. Every ticket should be `done` with a 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`.
 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

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

@@ -15,14 +15,19 @@ build window.
 
 ## Steps
 
-1. 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.
+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
+   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.
    - Order by dependency; note blockers explicitly ("depends on T-01").
-   - Every ticket gets a verification command or check the builder can actually run.
+   - 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").
    - 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,
@@ -36,7 +41,9 @@ build window.
      is preceded by a characterization ticket — a test that pins the current
      behavior before any ticket is allowed to change it.
 3. Write each ticket to `tickets/T-{NN}-{slug}.md` using
-   `.claude/references/ticket-template.md`.
+   `.claude/references/ticket-template.md`, with `status: open`. The other state fields
+   (`started`, `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.

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

@@ -13,6 +13,10 @@ timebox (~2 hours total), so discovery is brief and the PRD is lean. The PRD fee
 
 **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.
+
 ## Phase 1: Discovery (~5 min)
 
 1. If `${input:request:Task brief or arguments (optional)}` contains the brief, extract what you can before asking anything.

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

@@ -15,12 +15,16 @@ report pass/fail, never fix anything — fixes belong to the stage commands.
 ## Steps
 
 1. Read `docs/dry-run-checklist.md` — it is the source of truth for what to check.
-2. Determine which stages have run, from the artifacts present (`.prd/`, `tickets/`,
-   git log, `NOTES.md`). If `${input:request:Task brief or arguments (optional)}` names a stage, check only up to that stage.
+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
+   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`.
-   - Ticket verification commands: run at least two, report actual output.
+   - 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.
 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

@@ -0,0 +1,23 @@
+---
+mode: agent
+description: "Where the workflow stands — PRD, tickets, receipts, elapsed time, next action"
+---
+<!-- Generated from .claude/commands/pincer-status.md by scripts/sync-prompts.sh — edit the source, not this file -->
+
+
+# /pincer-status — Where are we?
+
+You are orienting in a repo that uses PINCER, typically after a context reset or at the
+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.
+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}`.

package/template/AGENTS.md

@@ -17,7 +17,9 @@ Code · Evaluate · Release). Follow it in order:
 4. `/pincer-evaluate` — final quality pass, then write `NOTES.md`
 5. `/pincer-release` — pass/fail audit of the workflow's artifacts
 
-Do not write feature code before a PRD exists and tickets are approved.
+`/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
+a PRD exists and tickets are approved.
 
 The commands live as playbooks in `.claude/commands/` (canonical), with
 generated adapters in `.codex/prompts/` and `.github/prompts/`. If your
@@ -75,6 +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
+  `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.
 - 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.

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

@@ -23,7 +23,8 @@ Use a throwaway copy of this repo and a cheap model (`claude --model sonnet`).
 - [ ] 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)
-- [ ] Every ticket has a runnable command in its Verification block
+- [ ] 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`)
 - [ ] If the brief or stack implies automated tests, at least one ticket's
       verification command is the test runner
@@ -38,8 +39,11 @@ 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
 - [ ] Every done ticket has all acceptance-criteria checkboxes ticked
-- [ ] Running each ticket's verification command passes (spot-check at least two)
+- [ ] `scripts/pincer-ticket.sh verify T-{NN}` passes on done tickets (spot-check
+      at least two)
 - [ ] Any scope cut made during build is recorded in the PRD's Out of Scope section
 - [ ] PRD frontmatter now says `status: built`
 
@@ -69,4 +73,6 @@ Use a throwaway copy of this repo and a cheap model (`claude --model sonnet`).
       before being modified
 - [ ] Platform adapters in sync: `scripts/sync-prompts.sh` then `git status`
       shows no changes in `.codex/prompts/` or `.github/prompts/`
-- [ ] Total wall-clock time fit the ~2-hour budget (note where time went if not)
+- [ ] `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

package/template/scripts/pincer-status.sh

@@ -0,0 +1,111 @@
+#!/bin/bash
+# PINCER status — where the workflow stands, read from the artifacts on disk.
+# Read-only. Every playbook runs this first; /pincer-status wraps it.
+#
+#   scripts/pincer-status.sh
+#
+# Elapsed times come from the `started` / `finished` stamps that
+# scripts/pincer-ticket.sh writes, i.e. from the clock — never estimated.
+# Build budget: PINCER_BUILD_BUDGET_MIN (default 75).
+set -uo pipefail
+
+ROOT=${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}
+cd "$ROOT"
+BUDGET=${PINCER_BUILD_BUDGET_MIN:-75}
+NOW=$(date -u +%s)
+
+fm_get() { # file key -> value with any inline comment stripped; empty if absent
+  awk -v k="$2" '
+    NR == 1 && $0 != "---" { exit }
+    NR > 1 && $0 == "---" { exit }
+    NR > 1 && index($0, k ":") == 1 {
+      v = substr($0, length(k) + 2); sub(/#.*/, "", v)
+      gsub(/^[ \t]+|[ \t]+$/, "", v); print v; exit
+    }' "$1"
+}
+to_epoch() { # ISO-8601 UTC -> seconds (GNU date, then BSD date)
+  date -u -d "$1" +%s 2>/dev/null || date -u -j -f '%Y-%m-%dT%H:%M:%SZ' "$1" +%s 2>/dev/null || echo 0
+}
+mins() { echo "$(( ($2 - $1) / 60 ))m"; }
+hhmm() { [ -n "$1" ] && printf '%s' "$1" | cut -c12-16 || printf '—'; }
+
+echo "PINCER status · $(date -u +%Y-%m-%dT%H:%MZ) · $ROOT"
+
+# ── PRD ──
+prd=$(ls .prd/prd-v*.md 2>/dev/null | sort -V | tail -1 || true)
+prd_status=""
+if [ -z "$prd" ]; then
+  echo "PRD      none"
+else
+  prd_status=$(fm_get "$prd" status)
+  echo "PRD      $prd · status: ${prd_status:-?} · date: $(fm_get "$prd" date)"
+fi
+
+# ── Tickets ──
+n_open=0; n_prog=0; n_done=0; first_start=""; in_prog=""; next_open=""; warn=""
+files=$(ls tickets/T-[0-9]*.md 2>/dev/null | sort || true)
+if [ -z "$files" ]; then
+  echo "Tickets  none"
+else
+  rows=""
+  for f in $files; do
+    id=$(fm_get "$f" ticket); [ -n "$id" ] || id=$(basename "$f" | cut -c1-4)
+    st=$(fm_get "$f" status); size=$(fm_get "$f" size)
+    started=$(fm_get "$f" started); verified=$(fm_get "$f" verified); finished=$(fm_get "$f" finished)
+    deps=$(fm_get "$f" depends_on | grep -oE 'T-[0-9]+' | tr '\n' ' ' || true)
+    if [ -n "$started" ]; then
+      se=$(to_epoch "$started")
+      [ -z "$first_start" ] || [ "$se" -lt "$first_start" ] && first_start=$se
+    fi
+    case "$st" in
+      done)
+        n_done=$((n_done + 1))
+        detail="started $(hhmm "$started") · finished $(hhmm "$finished")"
+        [ -n "$started" ] && [ -n "$finished" ] && detail="$detail ($(mins "$(to_epoch "$started")" "$(to_epoch "$finished")"))"
+        [ -n "$verified" ] || warn="$warn  WARN $id is done without a verification receipt — was it marked done by hand?\n"
+        ;;
+      in_progress)
+        n_prog=$((n_prog + 1)); in_prog="$in_prog $id"
+        detail="started $(hhmm "$started")"
+        [ -n "$started" ] && detail="$detail · elapsed $(mins "$(to_epoch "$started")" "$NOW")"
+        if [ -n "$verified" ]; then detail="$detail · receipt ✓"; else detail="$detail · no receipt yet"; fi
+        ;;
+      *)
+        n_open=$((n_open + 1)); st=${st:-open}
+        blocked=""
+        for d in $deps; do
+          df=$(ls "tickets/$d"-*.md 2>/dev/null | head -1 || true)
+          [ -n "$df" ] && [ "$(fm_get "$df" status)" = done ] || blocked="$blocked $d"
+        done
+        if [ -n "$blocked" ]; then detail="blocked by${blocked}"; else detail="ready"; [ -n "$next_open" ] || next_open=$id; fi
+        ;;
+    esac
+    rows="$rows$(printf '  %-5s %-12s %-2s %s' "$id" "$st" "${size:-?}" "$detail")\n"
+  done
+  echo "Tickets  $((n_open + n_prog + n_done)) total · $n_done done · $n_prog in progress · $n_open open"
+  printf '%b' "$rows"
+  printf '%b' "$warn"
+  if [ -n "$first_start" ]; then
+    echo "Build    elapsed $(mins "$first_start" "$NOW") since the first ticket started · budget ${BUDGET}m"
+  fi
+fi
+
+[ -f NOTES.md ] && notes=yes || notes=no
+echo "Notes    NOTES.md: $notes"
+
+# ── Next action ──
+if [ -z "$prd" ]; then
+  next="/pincer-plan <brief> — no PRD yet"
+elif [ -z "$files" ]; then
+  next="/pincer-narrow — PRD exists, no tickets yet"
+elif [ -n "$in_prog" ]; then
+  next="resume${in_prog}: /pincer-code${in_prog} (check git status for uncommitted work; then verify → done)"
+elif [ "$n_open" -gt 0 ]; then
+  next="/pincer-code — next ready ticket: ${next_open:-none (all remaining are blocked — check depends_on)}"
+elif [ "$notes" = no ]; then
+  next="/pincer-evaluate — all tickets done"
+  [ "$prd_status" = built ] || next="$next (PRD status is '${prd_status:-?}', expected 'built')"
+else
+  next="/pincer-release — evaluate has run (NOTES.md exists); audit the artifacts"
+fi
+echo "Next     $next"

package/template/scripts/pincer-ticket.sh

@@ -0,0 +1,134 @@
+#!/bin/bash
+# PINCER ticket state machine — the ONLY writer of a ticket's state fields
+# (status / started / verified / finished). Works on every platform; on Claude
+# Code a PreToolUse hook (.claude/hooks/ticket-guard.sh) blocks hand edits of
+# those fields so "done" can only be reached through a passing check.
+#
+#   scripts/pincer-ticket.sh start  T-03   open -> in_progress; refuses while a depends_on ticket isn't done
+#   scripts/pincer-ticket.sh verify T-03   runs the ticket's Verification block; exit 0 stamps a receipt
+#   scripts/pincer-ticket.sh done   T-03   needs a receipt matching the current Verification block
+#                                          and no unticked acceptance criteria; in_progress -> done
+#
+# The receipt is `verified: <UTC time> <12-hex hash of the Verification block>`.
+# Change the check after it passed and `done` refuses until it passes again.
+set -euo pipefail
+
+ROOT=${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}
+cd "$ROOT"
+
+die() { printf 'pincer-ticket: %b\n' "$*" >&2; exit 1; }
+now() { date -u +%Y-%m-%dT%H:%M:%SZ; }
+sha256() { if command -v sha256sum >/dev/null; then sha256sum; else shasum -a 256; fi; }
+
+normalize() { # T-3 / t-03 / 3 -> T-03
+  local n=${1#T-}; n=${n#t-}
+  [[ $n =~ ^[0-9]+$ ]] || die "not a ticket id: $1"
+  printf 'T-%02d' "$((10#$n))"
+}
+
+ticket_file() { # id -> tickets/T-NN-*.md (exactly one)
+  local id; id=$(normalize "$1")
+  local matches; matches=$(ls "tickets/$id"-*.md 2>/dev/null || true)
+  [ -n "$matches" ] || die "no ticket file tickets/$id-*.md"
+  [ "$(printf '%s\n' "$matches" | wc -l)" -eq 1 ] || die "several files match tickets/$id-*.md"
+  printf '%s' "$matches"
+}
+
+fm_get() { # file key -> value with any inline comment stripped; empty if absent
+  awk -v k="$2" '
+    NR == 1 && $0 != "---" { exit }
+    NR > 1 && $0 == "---" { exit }
+    NR > 1 && index($0, k ":") == 1 {
+      v = substr($0, length(k) + 2); sub(/#.*/, "", v)
+      gsub(/^[ \t]+|[ \t]+$/, "", v); print v; exit
+    }' "$1"
+}
+
+fm_set() { # file key value — replace inside the frontmatter (keeping an inline comment) or add before the closing ---
+  local tmp; tmp=$(mktemp)
+  awk -v k="$2" -v v="$3" '
+    NR == 1 { print; next }
+    !closed && !done && index($0, k ":") == 1 {
+      c = $0; if (sub(/^[^#]*#/, "#", c)) print k ": " v "   " c; else print k ": " v
+      done = 1; next
+    }
+    !closed && $0 == "---" { if (!done) print k ": " v; closed = 1 }
+    { print }' "$1" > "$tmp" && mv "$tmp" "$1"
+}
+
+verification_cmds() { # the fenced block under "## Verification"
+  awk '
+    /^## Verification/ { inv = 1; next }
+    inv && /^## /      { exit }
+    inv && /^```/      { if (inb) exit; inb = 1; next }
+    inb                { print }' "$1"
+}
+
+verify_hash() { verification_cmds "$1" | sha256 | cut -c1-12; }
+
+unticked() { # unticked boxes inside "## Acceptance Criteria"
+  awk '
+    /^## Acceptance Criteria/ { ina = 1; next }
+    ina && /^## /             { exit }
+    ina && /^- \[ \]/         { print }' "$1"
+}
+
+cmd_start() {
+  local f id st dep df
+  f=$(ticket_file "$1"); id=$(normalize "$1"); st=$(fm_get "$f" status)
+  case "$st" in
+    in_progress) echo "$id already in progress (started $(fm_get "$f" started))"; return 0 ;;
+    done) die "$id is already done" ;;
+  esac
+  for dep in $(fm_get "$f" depends_on | grep -oE 'T-[0-9]+' || true); do
+    df=$(ticket_file "$dep")
+    [ "$(fm_get "$df" status)" = done ] || die "$id depends on $dep, which is '$(fm_get "$df" status)' — finish $dep first (or fix depends_on in $f)"
+  done
+  fm_set "$f" status in_progress
+  [ -n "$(fm_get "$f" started)" ] || fm_set "$f" started "$(now)"
+  echo "▶ $id started $(fm_get "$f" started) — $f"
+}
+
+cmd_verify() {
+  local f id st cmds rc
+  f=$(ticket_file "$1"); id=$(normalize "$1"); st=$(fm_get "$f" status)
+  case "$st" in
+    open) cmd_start "$id" ;;
+    done) echo "$id is done — re-running its check (receipt left unchanged)" ;;
+  esac
+  cmds=$(verification_cmds "$f")
+  printf '%s\n' "$cmds" | grep -vE '^[[:space:]]*(#|$)' >/dev/null || die "no runnable command in the Verification block of $f"
+  echo "── $id verification ──"
+  printf '%s\n' "$cmds" | sed 's/^/  $ /'
+  set +e; bash -eo pipefail -c "$cmds"; rc=$?; set -e
+  if [ "$rc" -ne 0 ]; then
+    echo "✗ $id verification FAILED (exit $rc) — no receipt written. Fix, then re-run." >&2
+    exit "$rc"
+  fi
+  [ "$st" = done ] || fm_set "$f" verified "$(now) $(verify_hash "$f")"
+  echo "✓ $id verified — receipt: $(fm_get "$f" verified)"
+}
+
+cmd_done() {
+  local f id st rec cur u slug
+  f=$(ticket_file "$1"); id=$(normalize "$1"); st=$(fm_get "$f" status)
+  [ "$st" = done ] && { echo "$id already done"; return 0; }
+  [ "$st" = in_progress ] || die "$id is '$st' — run '$0 verify $id' first"
+  rec=$(fm_get "$f" verified)
+  [ -n "$rec" ] || die "no verification receipt on $id — run '$0 verify $id' and get a green check first"
+  cur=$(verify_hash "$f")
+  [ "${rec##* }" = "$cur" ] || die "receipt hash ${rec##* } does not match the current Verification block ($cur): the check changed after it passed — run '$0 verify $id' again"
+  u=$(unticked "$f")
+  [ -z "$u" ] || die "unticked acceptance criteria on $id:\n$u\nTick each verified criterion; a criterion that was cut is a scope change to record in the PRD, not a box to skip."
+  fm_set "$f" status done
+  fm_set "$f" finished "$(now)"
+  slug=$(basename "$f" .md); slug=${slug#T-[0-9][0-9]-}
+  echo "✓ $id done. Commit it with the code: git add -A && git commit -m \"$id: ${slug//-/ }\""
+}
+
+case "${1:-}" in
+  start)  [ $# -eq 2 ] || die "usage: $0 start T-NN";  cmd_start "$2" ;;
+  verify) [ $# -eq 2 ] || die "usage: $0 verify T-NN"; cmd_verify "$2" ;;
+  done)   [ $# -eq 2 ] || die "usage: $0 done T-NN";   cmd_done "$2" ;;
+  *) sed -n '2,13p' "$0" | sed 's/^# \{0,1\}//'; exit 1 ;;
+esac

package/template/scripts/sync-prompts.sh

@@ -4,7 +4,8 @@
 # of truth: edit them, re-run this script, commit the result.
 #
 #   .codex/prompts/pincer-*.md          — Codex CLI custom prompts
-#                                         (install: cp .codex/prompts/*.md ~/.codex/prompts/)
+#                                         (install: mkdir -p ~/.codex/prompts && cp .codex/prompts/*.md ~/.codex/prompts/;
+#                                          invoked as /prompts:pincer-*)
 #   .github/prompts/pincer-*.prompt.md  — VS Code Copilot prompt files
 #                                         (enable: "chat.promptFiles": true)
 set -euo pipefail