pincer-workflow 0.4.0 → 0.5.0

package/template/scripts/pincer-ticket.sh

@@ -1,145 +1,25 @@
 #!/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.
+# PINCER ticket state machine — the ONLY writer of a ticket's lifecycle fields.
+# Compatibility wrapper: every call is executed by scripts/pincer-runtime.cjs
+# (docs/runtime-contracts.md). 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
+#   scripts/pincer-ticket.sh start  T-03   open -> in_progress; refuses while a depends_on ticket isn't ready
+#   scripts/pincer-ticket.sh verify T-03   runs the ticket's Verification block and records the outcome
+#   scripts/pincer-ticket.sh done   T-03   closes the ticket on a current passing check with all criteria ticked
+#   scripts/pincer-ticket.sh bind   T-03 .prd/prd-vN.md   associates a legacy ticket with its PRD
 #
-# 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.
-# Every attempt revokes its predecessor; done runs a fresh final check.
-set -euo 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"
-
-die() { printf 'pincer-ticket: %b\n' "$*" >&2; exit 1; }
-now() { date -u +%Y-%m-%dT%H:%M:%SZ; }
-
-
-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"
+# Unmigrated (legacy) projects keep the v0.4.1 receipts: `verify` writes
+# `last_check` and `verified` into the ticket and `done` re-runs the check.
+# Migrated projects record attempts under .pincer/runtime/ and `done` consumes
+# the current passing attempt. Exit codes follow docs/runtime-contracts.md.
+command -v node >/dev/null 2>&1 || {
+  echo 'pincer-ticket: Node.js 18+ is required — the runtime is scripts/pincer-runtime.cjs' >&2
+  exit 4
 }
-
-fm_unset() {
-  local tmp; tmp=$(mktemp)
-  awk -v k="$2" 'NR > 1 && $0 == "---" { closed = 1 }
-    !closed && index($0, k ":") == 1 { next } { print }' "$1" > "$tmp" && mv "$tmp" "$1"
-}
-
-cmd_bind() {
-  local f ref existing
-  f=$(ticket_file "$1"); ref=$2
-  validate_prd "$ref" || exit 1
-  existing=$(fm_get "$f" prd)
-  [ -z "$existing" ] || [ "$existing" = "$ref" ] || die "$1 already references $existing; refusing to rebind it to $ref"
-  [ "$existing" = "$ref" ] || fm_set "$f" prd "$ref"
-  echo "$1 bound to PRD $ref"
-}
-
-cmd_start() {
-  local f id st dep df ref dep_ref readiness
-  f=$(ticket_file "$1"); id=$(normalize "$1"); st=$(fm_get "$f" status)
-  ref=$(usable_ticket_prd "$f") || exit 1
-  case "$st" in
-    in_progress)
-      [ -n "$(fm_get "$f" prd)" ] || fm_set "$f" prd "$ref"
-      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)"
-    dep_ref=$(usable_ticket_prd "$df") || exit 1
-    [ "$dep_ref" = "$ref" ] || die "$id references $ref but dependency $dep references $dep_ref"
-    if ! readiness=$(ticket_readiness "$df"); then die "$id depends on $dep: $readiness"; fi
-  done
-  [ -n "$(fm_get "$f" prd)" ] || fm_set "$f" prd "$ref"
-  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 hash child
-  f=$(ticket_file "$1"); id=$(normalize "$1"); st=$(fm_get "$f" status)
-  usable_ticket_prd "$f" >/dev/null || exit 1
-  case "$st" in
-    open) cmd_start "$id" ;;
-    done) echo "$id is done — re-running its check and updating the latest outcome" ;;
-  esac
-  cmds=$(verification_cmds "$f")
-  fm_unset "$f" verified
-  hash=$(verify_hash "$f")
-  fm_set "$f" last_check "$(now) running $hash"
-  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/^/  $ /'
-  bash -eo pipefail -c "$cmds" & child=$!
-  trap 'kill "$child" 2>/dev/null || true; fm_set "$f" last_check "$(now) interrupted $hash"; exit 130' INT TERM
-  set +e; wait "$child"; rc=$?; set -e
-  trap - INT TERM
-  if [ "$rc" -ne 0 ]; then
-    fm_set "$f" last_check "$(now) failed $hash"
-    echo "✗ $id verification FAILED (exit $rc) — failure recorded in last_check of $f; any prior successful receipt was revoked. Fix, then re-run verify." >&2
-    exit "$rc"
-  fi
-  if [ "$hash" != "$(verify_hash "$f")" ]; then
-    fm_set "$f" last_check "$(now) failed $hash"
-    die "Verification block changed during execution — re-run verify"
-  fi
-  if ! validate_ticket "$f" || ! usable_ticket_prd "$f" >/dev/null; then
-    fm_set "$f" last_check "$(now) failed $hash"
-    die "ticket became invalid during verification — fix it and re-run verify"
-  fi
-  fm_set "$f" last_check "$(now) passed $hash"
-  fm_set "$f" verified "$(now) $hash"
-  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)
-  usable_ticket_prd "$f" >/dev/null || exit 1
-  [ "$st" = in_progress ] || [ "$st" = done ] || 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."
-  cmd_verify "$id"
-  u=$(unticked "$f")
-  [ -z "$u" ] || die "unticked acceptance criteria on $id after verification:\n$u"
-  [ "$st" = done ] && { echo "$id already done — current check passed"; return 0; }
-  fm_set "$f" status done
-  fm_set "$f" finished "$(now)"
-  slug=$(basename "$f" .md); slug=${slug#T-[0-9][0-9]-}
-  echo "✓ $id done. Inspect staged work, stage only this ticket's paths, review git diff --cached, then commit: $id: ${slug//-/ }"
-}
-
-case "${1:-}" in
-  start|verify|done|bind) validate_ticket_set || exit 1 ;;
-esac
-
 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" ;;
-  bind)   [ $# -eq 3 ] || die "usage: $0 bind T-NN .prd/prd-vN.md"; cmd_bind "$2" "$3" ;;
-  *) sed -n '2,13p' "$0" | sed 's/^# \{0,1\}//'; exit 1 ;;
+  start|verify|done|bind) ;;
+  *) sed -n '8,11p' "$0" | sed 's/^# \{0,1\}//'; exit 2 ;;
 esac
+exec node "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/pincer-runtime.cjs" "$@"

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

@@ -1,321 +0,0 @@
-#!/bin/bash
-# Shared, read-only parsing for the supported Pincer ticket format.
-# Validators return nonzero with a diagnostic; callers decide how to report it.
-
-PINCER_LIB_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
-PINCER_EVIDENCE="$PINCER_LIB_DIR/pincer-evidence.cjs"
-
-# Run the shared evidence validator; prints its combined output, returns its status.
-# Usage: evidence_validate <manifest> <candidate> <base> <prd> [--files]
-# Absent or malformed candidate/base/prd values are simply not checked, so a bad
-# NOTES.md field is reported by notes_current, never as a manifest verdict.
-evidence_validate() {
-  local manifest=$1 candidate=$2 base=$3 prd=$4; shift 4
-  command -v node >/dev/null 2>&1 || { printf 'evidence: %s: Node.js 18+ is required to validate evidence\n' "$manifest"; return 1; }
-  local -a args=(validate "$manifest")
-  if [[ $candidate =~ ^[a-f0-9]{40}$ ]]; then args+=(--candidate "$candidate"); fi
-  if [[ $base =~ ^[a-f0-9]{40}$ ]]; then args+=(--base "$base"); fi
-  if [[ $prd =~ ^\.prd/prd-v[1-9][0-9]{0,8}\.md$ ]]; then args+=(--prd "$prd"); fi
-  node "$PINCER_EVIDENCE" "${args[@]}" "$@" 2>&1
-}
-evidence_reason() { # first diagnostic line without the manifest prefix; usage errors are labelled
-  printf '%s\n' "$1" | head -1 | sed -e 's/^evidence: [^:]*: //' -e 's/^pincer-evidence: /validator usage: /'
-}
-
-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
-  case "$(fm_get "$ref" profile)" in ''|small|standard) ;; *) printf 'pincer: %s: profile must be small or standard (omit for standard)\n' "$ref" >&2; return 1 ;; esac
-}
-
-prd_profile() { # effective planning profile; older PRDs without the field are standard
-  local profile; profile=$(fm_get "$1" profile)
-  printf '%s' "${profile:-standard}"
-}
-
-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
-}
-
-# An evaluation is current when NOTES.md names this PRD, a reviewed base and
-# candidate that are ancestors of HEAD, and an evidence manifest that validates
-# for that candidate; after the candidate, only NOTES.md and the files the
-# manifest lists may have changed, all of them tracked, and the working tree is
-# clean apart from NOTES.md. Legacy notes without a manifest never grant readiness.
-notes_current() {
-  local prd=$1 candidate base changes manifest output listed file stored canonical offending
-  [ -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}$ ]] || ! [[ $base =~ ^[a-f0-9]{40}$ ]]; then
-    printf 'stale: candidate and base must be full 40-hex 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
-  manifest=$(fm_get NOTES.md evidence)
-  if [ -z "$manifest" ]; then
-    printf 'stale: legacy evaluation without evidence manifest — re-run /pincer-evaluate for evidence schema 1'; return 1
-  fi
-  if ! output=$(evidence_validate "$manifest" "$candidate" "$base" "$prd" --files); then
-    printf 'stale: evidence invalid: %s' "$(evidence_reason "$output")"; return 1
-  fi
-  listed=$(printf '%s\n' "$output" | tail -n +2)
-  # Every listed file must be tracked; keep git's own spelling of each path
-  # (unquoted, relative to this directory, NFC where git normalises) so the set
-  # compares byte-for-byte with the diff below.
-  canonical=""
-  while IFS= read -r file; do
-    [ -n "$file" ] || continue
-    stored=$(git -c core.quotePath=false ls-files --error-unmatch -- "$file" 2>/dev/null) || { printf 'stale: evidence not tracked: %s' "$file"; return 1; }
-    canonical="$canonical$stored
-"
-  done <<< "$listed"
-  # Paths relative to the project root (which may be below the git toplevel).
-  changes=$(git -c core.quotePath=false diff --name-only --relative "$candidate" HEAD -- . ':(exclude)NOTES.md') || return 1
-  offending=$(printf '%s\n' "$changes" | grep -vxF -f <(printf '%s' "$canonical") | grep -v '^$' | head -1)
-  if [ -n "$offending" ]; then printf 'stale: candidate changed after evaluation: %s' "$offending"; 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"
-}