pincer-workflow 0.2.2 → 0.3.0

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

@@ -1,6 +1,9 @@
 # PINCER Dry-Run Checklist
 
-How to test that the `.claude/` workflow works: run the full chain on a small toy
+This is the manual platform trial for the Pincer kit, not the product release audit.
+For release readiness, use `docs/release-checklist.md`.
+
+To test that the `.claude/` workflow works, run the full chain on a small toy
 feature (e.g. "a CLI todo app in TypeScript — add, list, complete, delete, stored in a
 local JSON file"), then tick every box below. All boxes ticked = the workflow passes.
 A failed box points at the command file to fix.
@@ -9,20 +12,22 @@ Use a throwaway copy of this repo and a cheap model (`claude --model sonnet`).
 
 ## After `/pincer-plan`
 
-- [ ] `.prd/prd-v1.md` exists
+- [ ] The selected `.prd/prd-vN.md` exists
 - [ ] Its frontmatter has `version`, `status: draft`, and `date`
 - [ ] All 6 core sections are present (Problem, Solution, Scope, Architecture,
       Success Criteria, Out of Scope)
 - [ ] The Scope table has both columns filled (in AND out)
 - [ ] No implementation code inside the PRD
 - [ ] Discovery asked ≤4 questions and none were already answered by the brief
-- [ ] `.git/` exists and the first commit contains the PRD
+- [ ] `.git/` exists and the selected PRD is committed without unrelated brownfield work
 
 ## After `/pincer-narrow`
 
-- [ ] 4–7 files exist in `tickets/`, named `T-{NN}-{slug}.md`
-- [ ] Every ticket is sized S or M — none L
-- [ ] T-01 is a walking skeleton (scaffold + thin end-to-end slice that runs)
+- [ ] Ticket files are named `T-{NN}-{slug}.md`; count follows dependencies and risk
+- [ ] Every ticket has a coherent S, M, or L scope; larger work is split when that
+      improves ownership, dependency order, or verification
+- [ ] Greenfield uses a walking skeleton when helpful; brownfield protects the
+      smallest useful vertical change
 - [ ] Every ticket has a runnable, non-interactive command in its fenced
       Verification block (it is what `scripts/pincer-ticket.sh verify` runs)
 - [ ] Dependencies are declared where they exist (`depends_on`)
@@ -30,8 +35,8 @@ Use a throwaway copy of this repo and a cheap model (`claude --model sonnet`).
       verification command is the test runner
 - [ ] Every ticket whose surface accepts external input has a reject-path
       acceptance criterion (what invalid input produces), not only the happy path
-- [ ] T-01 includes `.gitignore` covering `.env*` (except `.env.example`) and an
-      `.env.example` naming required secrets
+- [ ] Greenfield setup covers `.env*` (except `.env.example`) and names required
+      secrets in `.env.example`; brownfield preserves and verifies existing conventions
 - [ ] PRD frontmatter now says `status: ticketed`
 - [ ] Tickets are committed
 
@@ -50,12 +55,12 @@ Use a throwaway copy of this repo and a cheap model (`claude --model sonnet`).
 ## After `/pincer-evaluate`
 
 - [ ] Findings (if any) were presented with `file:line` references
-- [ ] The mechanical security audit ran: history grep for secret-like strings,
+- [ ] The mechanical security audit used redacted, location-only secret findings;
       `git ls-files` shows no `.env` beyond `.env.example`, dependency audit,
       and (if there's an API) one invalid-input request returned a clean 4xx
 - [ ] If the project has a UI, it was actually opened and checked visually, not
       only read as code
-- [ ] Approved fixes were committed as `review: fixes` and re-verified
+- [ ] Evaluation fixes were completed through new tickets and re-verified
 - [ ] `NOTES.md` exists at the repo root and covers: what was built, what was cut
       and why, known issues, next steps
 
@@ -63,8 +68,8 @@ Use a throwaway copy of this repo and a cheap model (`claude --model sonnet`).
 
 - [ ] `git log --oneline` reads as a coherent story: setup → tickets → T-01…T-NN → review
 - [ ] No `.env` file contents ever appeared in the conversation
-- [ ] `git log -p` contains no secret values anywhere in history (a committed-then-
-      deleted key is still leaked)
+- [ ] Relevant history was checked for committed-then-deleted secrets without printing
+      candidate values into the conversation or audit report
 - [ ] Every dependency in the lockfile is named in the PRD's architecture or was
       explicitly approved during build
 - [ ] `NOTES.md` has a Handover section (orientation, dependency justification,
@@ -73,6 +78,5 @@ 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 `.agents/skills/` or `.github/prompts/`
-- [ ] `scripts/pincer-status.sh` says `Next /pincer-release` and its build elapsed
-      figure fit the ~75-minute build budget (note where time went if not)
-- [ ] Total wall-clock time fit the ~2-hour budget
+- [ ] `scripts/pincer-status.sh` says `Next /pincer-release`; if the user supplied a
+      budget, its elapsed figure and any deliberate cuts are reported against that budget

package/template/docs/release-checklist.md

@@ -0,0 +1,34 @@
+# PINCER Release Checklist
+
+Audit the selected PRD and its evaluated candidate. This checklist applies to product
+changes in greenfield and brownfield repositories. It is read-only: failures return work
+to the owning stage or a new ticket.
+
+## Change identity and state
+
+- [ ] `scripts/pincer-status.sh` selects the intended PRD with `status: built` and no warnings
+- [ ] Every ticket associated with that PRD is done with current `last_check` and `verified` evidence
+- [ ] `NOTES.md` names the selected PRD, reviewed base, and candidate; status reports it current
+- [ ] The working tree is clean before and after the audit
+
+## Scope and evidence
+
+- [ ] Every in-scope success criterion has delivered evidence or an explicit non-delivered disposition
+- [ ] Ticket dependencies, acceptance criteria, and verification commands match the implemented change
+- [ ] The repository's candidate-wide release gate passes when run directly, without invoking the ticket state writer
+- [ ] Scope cuts and known limitations are explicit in the PRD or evaluation notes
+
+## Review
+
+- [ ] High-confidence review findings have file and line evidence and a disposition
+- [ ] Fixes made after evaluation use a new ticket, current verification, and a scoped commit
+- [ ] UI changes have visual evidence; non-UI changes mark this item not applicable with a reason
+- [ ] Security review reports locations and remediation without printing candidate secret values
+- [ ] No secret environment file is tracked; dependency and invalid-input checks run when applicable
+
+## Handover and verdict
+
+- [ ] Commit history identifies the plan, ticket work, evaluation, and any review-fix tickets
+- [ ] `NOTES.md` covers what shipped, cuts, limitations, next steps, dependencies, and the riskiest aging assumption
+- [ ] Platform or environment limits are stated without claiming untested support
+- [ ] Every failed or skipped required item is named before the final PASS or FAIL verdict

package/template/scripts/pincer-status.sh

@@ -6,23 +6,15 @@
 #
 # 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).
+# Optional build budget: PINCER_BUILD_BUDGET_MIN.
 set -uo pipefail
 
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/pincer-ticket-lib.sh"
 ROOT=${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}
 cd "$ROOT"
-BUDGET=${PINCER_BUILD_BUDGET_MIN:-75}
+BUDGET=${PINCER_BUILD_BUDGET_MIN:-}
 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
 }
@@ -32,7 +24,11 @@ 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)
+if ! prd=$(latest_prd 2>&1); then
+  printf 'WARN     invalid PRD: %s\n' "$prd"
+  echo 'Next     repair PRD input before continuing'
+  exit 1
+fi
 prd_status=""
 if [ -z "$prd" ]; then
   echo "PRD      none"
@@ -41,17 +37,43 @@ else
   echo "PRD      $prd · status: ${prd_status:-?} · date: $(fm_get "$prd" date)"
 fi
 
+# Reject malformed/ambiguous tickets instead of treating unknown states as open.
+if ! errors=$(validate_ticket_set 2>&1); then
+  printf 'WARN     invalid tickets: %s\n' "$errors"
+  echo "Next     repair ticket input before continuing"
+  exit 1
+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)
+n_open=0; n_prog=0; n_done=0; first_start=""; in_prog=""; next_open=""; warn=""; reverify=""
+files=""; historical=0; unresolved=0
+for f in tickets/T-*.md; do
+  [ -e "$f" ] || continue
+  if ! associated=$(ticket_prd "$f" 2>&1); then
+    printf 'WARN     unresolved ticket PRD: %s\n' "$associated"
+    unresolved=$((unresolved + 1)); continue
+  fi
+  if [ "$associated" = "$prd" ]; then
+    files="$files$f
+"
+  else
+    historical=$((historical + 1))
+  fi
+done
+[ "$historical" -eq 0 ] || echo "History  $historical ticket(s) associated with other PRDs"
 if [ -z "$files" ]; then
   echo "Tickets  none"
 else
   rows=""
-  for f in $files; do
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
     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)
+    attempt=$(fm_get "$f" last_check)
+    if [ -n "$attempt" ] && ! printf '%s' "$attempt" | grep -q ' passed '; then
+      warn="$warn  WARN $id latest verification: $attempt — re-run verify\n"
+    fi
     deps=$(fm_get "$f" depends_on | grep -oE 'T-[0-9]+' | tr '\n' ' ' || true)
     if [ -n "$started" ]; then
       se=$(to_epoch "$started")
@@ -62,7 +84,10 @@ else
         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"
+        if ! readiness=$(ticket_readiness "$f"); then
+          warn="$warn  WARN $id $readiness\n"
+          reverify="$reverify $id"
+        fi
         ;;
       in_progress)
         n_prog=$((n_prog + 1)); in_prog="$in_prog $id"
@@ -74,38 +99,54 @@ else
         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"
+          df=$(ticket_file "$d" 2>/dev/null || true)
+          dep_prd=""
+          [ -z "$df" ] || dep_prd=$(ticket_prd "$df" 2>/dev/null || true)
+          if [ -z "$df" ] || [ "$(fm_get "$df" status)" != done ] ||
+             [ "$dep_prd" != "$prd" ] || ! usable_ticket_prd "$df" >/dev/null 2>&1 ||
+             ! ticket_readiness "$df" >/dev/null; then
+            blocked="$blocked $d"
+          fi
         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
+  done <<< "$files"
   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"
+    build="Build    elapsed $(mins "$first_start" "$NOW") since the first ticket started"
+    [ -z "$BUDGET" ] || build="$build · budget ${BUDGET}m"
+    echo "$build"
   fi
 fi
 
-[ -f NOTES.md ] && notes=yes || notes=no
+notes_valid=no
+if notes=$(notes_current "$prd"); then notes_valid=yes; fi
 echo "Notes    NOTES.md: $notes"
 
 # ── Next action ──
 if [ -z "$prd" ]; then
   next="/pincer-plan <brief> — no PRD yet"
+elif [ "$unresolved" -gt 0 ]; then
+  next="resolve PRD association with pincer-ticket.sh bind T-NN .prd/prd-vN.md before continuing"
+elif [ "$prd_status" = draft ]; then
+  next="/pincer-narrow — current PRD is draft; earlier tickets and notes do not complete it"
 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
+elif [ -n "$reverify" ]; then
+  next="/pincer-code — re-run verify for${reverify}; resolve readiness warnings before evaluation or release"
+elif [ "$notes_valid" = no ] || [ "$prd_status" != built ]; 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"
+  next="/pincer-release — evaluation matches the current PRD and candidate; audit the artifacts"
 fi
 echo "Next     $next"
+[ "$unresolved" -eq 0 ] || exit 1

package/template/scripts/pincer-ticket-lib.sh

@@ -0,0 +1,270 @@
+#!/bin/bash
+# Shared, read-only parsing for the supported Pincer ticket format.
+# Validators return nonzero with a diagnostic; callers decide how to report it.
+
+normalize() { # CLI shorthand -> canonical ID; bound arithmetic before conversion.
+  local n=${1#T-}; n=${n#t-}
+  if ! [[ $n =~ ^[0-9]{1,6}$ ]] || [ "$((10#$n))" -eq 0 ]; then
+    printf 'pincer-ticket: not a ticket id (expected 1..999999): %s\n' "$1" >&2
+    return 1
+  fi
+  printf 'T-%02d' "$((10#$n))"
+}
+
+fm_get() {
+  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"
+}
+
+verification_cmds() {
+  awk '
+    inb { if ($0 ~ /^[ \t]*```[ \t]*$/) exit; print; next }
+    otherfence { if ($0 ~ /^[ \t]*```/) otherfence = 0; next }
+    /^## Verification[ \t]*$/ { inv = 1; next }
+    inv && /^[ \t]*```bash[ \t]*$/ { inb = 1; next }
+    inv && /^## / { exit }
+    /^[ \t]*```/ { otherfence = 1 }
+  ' "$1"
+}
+
+unticked() {
+  awk '
+    otherfence { if ($0 ~ /^[ \t]*```/) otherfence = 0; next }
+    /^[ \t]*```/ { otherfence = 1; next }
+    /^## Acceptance Criteria[ \t]*$/ { ina = 1; next }
+    ina && /^## / { exit }
+    ina && /^[ \t]*([-+*]|[0-9]+[.)])[ \t]+\[ \]/ { print }
+  ' "$1"
+}
+
+validate_ticket() {
+  local file=$1 cmds
+  awk -v file="$file" '
+    function fail(msg) { print "pincer-ticket: " file ": " msg > "/dev/stderr"; bad = 1; exit 1 }
+    function trim(s) { gsub(/^[ \t]+|[ \t]+$/, "", s); return s }
+    function idok(s, n) {
+      if (s !~ /^T-[0-9][0-9]+$/) return 0
+      n = substr(s, 3)
+      return length(n) <= 6 && n + 0 > 0 && sprintf("T-%02d", n + 0) == s
+    }
+    NR == 1 { if ($0 != "---") fail("frontmatter must begin with ---"); next }
+    !closed {
+      if ($0 == "---") { closed = 1; next }
+      if ($0 ~ /^[ \t]*(#.*)?$/) next
+      if ($0 !~ /^[a-z_][a-z0-9_]*:[ \t]*/) fail("frontmatter requires unindented key: value fields")
+      key = $0; sub(/:.*/, "", key)
+      if (seen[key]++) fail("duplicate frontmatter key: " key)
+      value = substr($0, length(key) + 2); sub(/#.*/, "", value); values[key] = trim(value)
+      next
+    }
+    inverify {
+      if ($0 ~ /^[ \t]*```[ \t]*$/) { inverify = 0; next }
+      if ($0 ~ /^[ \t]*```/) fail("Verification requires one closed bash fence")
+      if ($0 !~ /^[ \t]*(#.*)?$/) runnable++
+      next
+    }
+    otherfence {
+      if ($0 ~ /^[ \t]*```/) otherfence = 0
+      next
+    }
+    /^## Acceptance Criteria[ \t]*$/ { if (accept++) fail("duplicate Acceptance Criteria section"); section = "accept"; next }
+    /^## Verification[ \t]*$/ { if (verify++) fail("duplicate Verification section"); section = "verify"; next }
+    /^## / { section = ""; next }
+    section == "accept" {
+      if ($0 ~ /^[ \t]*(```|~~~)/) fail("Acceptance Criteria must contain visible checkboxes, not fences")
+      if ($0 ~ /^[ \t]*([-+*]|[0-9]+[.)])[ \t]+/ || $0 ~ /^[ \t]*([-+*]|[0-9]+[.)])?[ \t]*\[/) {
+        if ($0 !~ /^[ \t]*([-+*]|[0-9]+[.)])[ \t]+\[[ xX]\][ \t]+[^ \t]/)
+          fail("malformed acceptance checkbox; use - [ ] text or - [x] text (indented/list marker variants supported)")
+        boxes++
+      }
+    }
+    /^[ \t]*~~~/ { fail("use backtick fences; tilde fences are unsupported") }
+    /^[ \t]*```/ {
+      if (section == "verify") {
+        if ($0 !~ /^[ \t]*```bash[ \t]*$/ || fences++) fail("Verification requires exactly one bash fence")
+        inverify = 1
+      } else otherfence = 1
+    }
+    END {
+      if (bad) exit 1
+      if (!closed) fail("frontmatter must close with ---")
+      if (!seen["ticket"] || !idok(values["ticket"])) fail("ticket must be a canonical ID between T-01 and T-999999")
+      base = file; sub(/^.*\//, "", base)
+      prefix = values["ticket"] "-"
+      if (index(base, prefix) != 1 || base !~ /.+\.md$/ || length(base) <= length(prefix) + 3) fail("ticket ID must match filename T-NN-slug.md")
+      if (values["status"] !~ /^(open|in_progress|done)$/) fail("status must be open, in_progress, or done")
+      if (values["size"] !~ /^(S|M|L)$/) fail("size must be S, M, or L")
+      timestamp = "^[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]T[0-9][0-9]:[0-9][0-9]:[0-9][0-9]Z$"
+      for (key in seen) {
+        if ((key == "started" || key == "finished") && values[key] !~ timestamp) fail(key " must be an ISO UTC timestamp")
+        if (key == "verified" || key == "last_check") {
+          parts = split(values[key], stamp, /[ \t]+/)
+          expected = key == "verified" ? 2 : 3
+          if (parts != expected || stamp[1] !~ timestamp || length(stamp[parts]) != 12 || stamp[parts] !~ /^[0-9a-f]+$/)
+            fail("malformed " key " timestamp/hash")
+          if (key == "last_check" && stamp[2] !~ /^(running|passed|failed|interrupted)$/) fail("invalid last_check outcome")
+        }
+      }
+      deps = values["depends_on"]
+      if (!seen["depends_on"] || deps !~ /^\[[ \t]*(T-[0-9]+([ \t]*,[ \t]*T-[0-9]+)*)?[ \t]*\]$/) fail("depends_on must be an inline list such as [T-01, T-02]")
+      sub(/^\[[ \t]*/, "", deps); sub(/[ \t]*\]$/, "", deps)
+      count = split(deps, entries, ",")
+      for (i = 1; i <= count; i++) {
+        dep = trim(entries[i]); if (dep == "") continue
+        if (!idok(dep)) fail("depends_on contains noncanonical ticket ID: " dep)
+        if (dep == values["ticket"]) fail("ticket cannot depend on itself")
+        if (depseen[dep]++) fail("duplicate depends_on ID: " dep)
+      }
+      if (!accept || !boxes) fail("Acceptance Criteria requires at least one nonempty checkbox")
+      if (!verify || fences != 1 || inverify || !runnable) fail("Verification requires exactly one closed runnable bash fence")
+    }
+  ' "$file" || return 1
+  cmds=$(verification_cmds "$file") || return 1
+  if ! bash -n -c "$cmds"; then
+    printf 'pincer-ticket: %s: invalid bash syntax in Verification block\n' "$file" >&2
+    return 1
+  fi
+}
+
+validate_ticket_set() {
+  local file id ids=' '
+  for file in tickets/T-*.md; do
+    [ -e "$file" ] || continue
+    id=$(fm_get "$file" ticket)
+    if [ -n "$id" ]; then
+      case "$ids" in *" $id "*) printf 'pincer-ticket: duplicate ticket ID: %s\n' "$id" >&2; return 1 ;; esac
+      ids="$ids$id "
+    fi
+  done
+  for file in tickets/T-*.md; do
+    [ -e "$file" ] || continue
+    validate_ticket "$file" || return 1
+  done
+}
+
+ticket_file() {
+  local id file found=''
+  id=$(normalize "$1") || return 1
+  for file in "tickets/$id"-*.md; do
+    [ -e "$file" ] || continue
+    if [ -n "$found" ]; then printf 'pincer-ticket: several files match tickets/%s-*.md\n' "$id" >&2; return 1; fi
+    found=$file
+  done
+  if [ -z "$found" ]; then printf 'pincer-ticket: no ticket file tickets/%s-*.md\n' "$id" >&2; return 1; fi
+  printf '%s' "$found"
+}
+
+# PRDs and evaluation notes use the same deliberately small metadata format.
+validate_metadata() {
+  awk -v file="$1" '
+    function fail(msg) { print "pincer: " file ": " msg > "/dev/stderr"; bad = 1; exit 1 }
+    NR == 1 { if ($0 != "---") fail("frontmatter must begin with ---"); next }
+    !closed {
+      if ($0 == "---") { closed = 1; next }
+      if ($0 ~ /^[ \t]*(#.*)?$/) next
+      if ($0 !~ /^[a-z_][a-z0-9_]*:[ \t]*/) fail("expected unindented key: value metadata")
+      key = $0; sub(/:.*/, "", key)
+      if (seen[key]++) fail("duplicate metadata key: " key)
+    }
+    END { if (bad) exit 1; if (!closed) fail("frontmatter must close with ---") }
+  ' "$1"
+}
+
+validate_prd() {
+  local ref=$1 version
+  if ! [[ $ref =~ ^\.prd/prd-v([1-9][0-9]{0,8})\.md$ ]]; then
+    printf 'pincer: invalid PRD reference %s; use .prd/prd-vN.md\n' "$ref" >&2; return 1
+  fi
+  version=${BASH_REMATCH[1]}
+  [ -f "$ref" ] || { printf 'pincer: PRD does not exist: %s\n' "$ref" >&2; return 1; }
+  validate_metadata "$ref" || return 1
+  [ "$(fm_get "$ref" version)" = "$version" ] || { printf 'pincer: %s: version must match filename (%s)\n' "$ref" "$version" >&2; return 1; }
+  case "$(fm_get "$ref" status)" in draft|ticketed|built) ;; *) printf 'pincer: %s: PRD status must be draft, ticketed, or built\n' "$ref" >&2; return 1 ;; esac
+}
+
+latest_prd() {
+  local ref latest='' highest=0 n
+  for ref in .prd/prd-v*.md; do
+    [ -e "$ref" ] || continue
+    if ! [[ $ref =~ ^\.prd/prd-v([1-9][0-9]{0,8})\.md$ ]]; then
+      printf 'pincer: invalid PRD filename: %s\n' "$ref" >&2; return 1
+    fi
+    n=${BASH_REMATCH[1]}
+    if [ "$n" -gt "$highest" ]; then highest=$n; latest=$ref; fi
+  done
+  [ -z "$latest" ] || validate_prd "$latest" || return 1
+  printf '%s' "$latest"
+}
+
+ticket_prd() { # resolve without writing; ambiguous legacy tickets require bind.
+  local file=$1 ref candidate count=0
+  ref=$(fm_get "$file" prd)
+  if [ -z "$ref" ]; then
+    for candidate in .prd/prd-v*.md; do
+      [ -e "$candidate" ] || continue
+      ref=$candidate; count=$((count + 1))
+    done
+    if [ "$count" -ne 1 ]; then
+      printf 'pincer: %s: missing or ambiguous PRD association; use pincer-ticket.sh bind %s .prd/prd-vN.md\n' "$file" "$(fm_get "$file" ticket)" >&2
+      return 1
+    fi
+  fi
+  validate_prd "$ref" || return 1
+  printf '%s' "$ref"
+}
+
+usable_ticket_prd() {
+  local ref
+  ref=$(ticket_prd "$1") || return 1
+  case "$(fm_get "$ref" status)" in
+    ticketed|built) printf '%s' "$ref" ;;
+    *) printf 'pincer: %s: PRD is draft; complete the authorized breakdown before starting (expected ticketed or built)\n' "$ref" >&2; return 1 ;;
+  esac
+}
+
+sha256() { if command -v sha256sum >/dev/null; then sha256sum; else shasum -a 256; fi; }
+verify_hash() { verification_cmds "$1" | sha256 | cut -c1-12; }
+
+ticket_readiness() { # explain why a done ticket needs attention, without mutation.
+  local file=$1 receipt attempt hash
+  receipt=$(fm_get "$file" verified); attempt=$(fm_get "$file" last_check)
+  hash=$(verify_hash "$file")
+  if [ -z "$attempt" ]; then
+    printf 'missing latest verification outcome — re-run verify'; return 1
+  fi
+  if ! [[ $attempt =~ ^[0-9T:Z-]+\ passed\ [a-f0-9]{12}$ ]] || [ "${attempt##* }" != "$hash" ]; then
+    printf 'latest verification: %s — re-run verify' "$attempt"; return 1
+  fi
+  if [ -z "$receipt" ]; then printf 'done without a verification receipt — re-run verify'; return 1; fi
+  if ! [[ $receipt =~ ^[0-9T:Z-]+\ [a-f0-9]{12}$ ]] || [ "${receipt##* }" != "$hash" ]; then
+    printf 'stale or malformed verification receipt — re-run verify'; return 1
+  fi
+  if [ -n "$(unticked "$file")" ]; then printf 'unticked acceptance criteria — complete and re-run verify'; return 1; fi
+}
+
+notes_current() {
+  local prd=$1 candidate base changes
+  [ -f NOTES.md ] || { printf 'missing'; return 1; }
+  validate_metadata NOTES.md >/dev/null 2>&1 || { printf 'stale: invalid or missing evaluation metadata'; return 1; }
+  [ "$(fm_get NOTES.md prd)" = "$prd" ] || { printf 'stale: evaluation PRD does not match'; return 1; }
+  candidate=$(fm_get NOTES.md candidate); base=$(fm_get NOTES.md base)
+  if ! [[ $candidate =~ ^([a-f0-9]{40}|[a-f0-9]{64})$ ]] || ! [[ $base =~ ^([a-f0-9]{40}|[a-f0-9]{64})$ ]]; then
+    printf 'stale: candidate and base must be full commit IDs'; return 1
+  fi
+  if ! git rev-parse --verify "$candidate^{commit}" >/dev/null 2>&1 ||
+     ! git rev-parse --verify "$base^{commit}" >/dev/null 2>&1 ||
+     ! git merge-base --is-ancestor "$base" "$candidate" 2>/dev/null ||
+     ! git merge-base --is-ancestor "$candidate" HEAD 2>/dev/null; then
+    printf 'stale: evaluation commits or ancestry unavailable'; return 1
+  fi
+  changes=$(git diff --name-only "$candidate" HEAD -- . ':(exclude)NOTES.md') || return 1
+  if [ -n "$changes" ]; then printf 'stale: candidate changed after evaluation'; return 1; fi
+  changes=$(git status --porcelain --untracked-files=all -- . ':(exclude)NOTES.md') || return 1
+  if [ -n "$changes" ]; then printf 'stale: working tree has changes outside NOTES.md'; return 1; fi
+  printf 'current (%s)' "$candidate"
+}