cohorte 1.5.0 → 2.0.0

package/scripts/loop-detach.sh

@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+#
+# loop-detach.sh — run loop.sh so it outlives the session that launched it.
+#
+#   loop-detach.sh start <feature-id> [loop.sh flags…]
+#   loop-detach.sh wait  <feature-id>
+#
+# WHY THIS EXISTS. `/cohorte-loop` used to run the driver as one foreground Bash
+# call ("let it run to completion"). Two things make that impossible for a real
+# feature:
+#
+#   1. The Bash tool caps a single call at 600 s. A build is 25–40 min, so the
+#      call was killed mid-`/cohorte-build` and the loop reported nothing.
+#   2. A backgrounded Bash call is NOT detached — the child stays in the calling
+#      session's process group, so when Claude Code goes down (a restart, a
+#      crash, a laptop sleep) `loop.sh` and every `claude -p` child die with it.
+#      Diagnosed on a real run: four teardowns in 45 min, each one aborting both
+#      surface implementers mid-write and leaving a half-built tree.
+#
+# `screen -dmS` is the fix: its server double-forks and reparents to init, so the
+# driver is in its own session and survives the launching process entirely. The
+# exit code — which `/cohorte-loop` keys its whole report table on — would be lost
+# that way, so the wrapper appends `__EXIT__ <code>` to the status file.
+#
+# STATUS FILE vs LOG — these are different files and the distinction is the whole
+# token economy of this command. loop.sh writes ONE LINE PER PHASE to stdout; that
+# is what lands in <id>.loop.status and it is safe to read. The full transcript of
+# every child session — the diff, every review report, every handoff — goes to
+# <id>.loop.log, which must never be read into a session. Do not merge them.
+
+set -uo pipefail
+
+usage() {
+  cat >&2 <<'EOF'
+usage: loop-detach.sh start <feature-id> [loop.sh flags…]
+       loop-detach.sh wait  <feature-id>
+
+  start   launch the driver detached; returns immediately
+  wait    block up to ~9 min waiting for it to finish (safely under the Bash
+          tool's 600 s ceiling), then print the small status file. Call again
+          while it prints __RUNNING__.
+EOF
+  exit 64
+}
+
+mode="${1:-}"; id="${2:-}"
+[ -n "$mode" ] && [ -n "$id" ] || usage
+shift 2 2>/dev/null || usage
+case "$mode" in start|wait) ;; *) echo "loop-detach: unknown mode: $mode" >&2; usage ;; esac
+
+root="$(git rev-parse --show-toplevel 2>/dev/null)" || {
+  echo "loop-detach: not inside a git checkout" >&2; exit 64; }
+cd "$root" || exit 64
+
+status="$root/specs/reports/$id.loop.status"
+sess="cohorte-$id"
+
+# ── wait ─────────────────────────────────────────────────────────────────────
+# 36 × 15 s = 540 s, comfortably inside the 600 s tool ceiling. The driver is
+# detached, so this timing out means nothing to the run — call wait again.
+if [ "$mode" = "wait" ]; then
+  [ -f "$status" ] || { echo "loop-detach: no run to wait on ($status absent)" >&2; exit 64; }
+  i=0
+  while [ "$i" -lt 36 ]; do
+    grep -q '__EXIT__' "$status" 2>/dev/null && break
+    sleep 15
+    i=$((i + 1))
+  done
+  cat "$status"
+  grep -q '__EXIT__' "$status" 2>/dev/null || echo "__RUNNING__"
+  exit 0
+fi
+
+# ── start ────────────────────────────────────────────────────────────────────
+# Refuse to double-launch: two drivers on one feature would interleave commits and
+# fight over the same verdict files, and the second would silently win the report.
+# `screen -ls` exits 1 when it DOES find sessions, so under `pipefail` a piped
+# `| grep -q` reports failure on the very case we are testing for — the guard
+# silently never fired. Capture first, match second.
+sessions="$(screen -ls 2>/dev/null || true)"
+if [ -n "$sessions" ] && printf '%s\n' "$sessions" | grep -q "[.]$sess[[:space:]]"; then
+  echo "loop-detach: '$sess' is already running — 'wait $id' to follow it, or"
+  echo "             'screen -S $sess -X quit' to stop it first" >&2
+  exit 64
+fi
+# The screen check above only sees the screen tier. On the setsid/nohup tiers there is
+# no session to list, so match the process itself — otherwise the guard silently covers
+# macOS and misses every platform that lacks screen. `[l]oop.sh` keeps this pgrep from
+# matching itself. Skipped where pgrep is absent (Git Bash): the guard degrades to
+# nothing there rather than blocking a legitimate launch.
+if command -v pgrep >/dev/null 2>&1 && pgrep -f "[l]oop\.sh .*$id" >/dev/null 2>&1; then
+  echo "loop-detach: a driver is already running for '$id' — 'wait $id' to follow it," >&2
+  echo "             or stop that process before launching another" >&2
+  exit 64
+fi
+
+loop=""
+for cand in "$root/.claude/pipeline/scripts/loop.sh" "$HOME/.claude/pipeline/scripts/loop.sh"; do
+  [ -f "$cand" ] && { loop="$cand"; break; }
+done
+[ -n "$loop" ] || { echo "loop-detach: no loop.sh in .claude/ or ~/.claude/ — run /cohorte-doctor" >&2; exit 64; }
+
+mkdir -p "$root/specs/reports"
+: >"$status"
+
+# A self-deleting wrapper, rather than interpolating "$@" into a `sh -c` string:
+# feature ids and flags would otherwise need shell-correct quoting at two nesting
+# levels, and getting that subtly wrong silently drops a flag (`--max=3` becoming
+# `--max`). `printf %q` is a bash builtin — present even in macOS's bash 3.2.
+wrapper="$(mktemp "${TMPDIR:-/tmp}/cohorte-detach-XXXXXX")" || exit 1
+{
+  echo '#!/usr/bin/env bash'
+  printf 'rm -f -- %q\n' "$wrapper"          # self-delete: no litter in TMPDIR
+  printf 'cd %q || exit 1\n' "$root"
+  printf 'bash %q %q' "$loop" "$id"
+  for a in "$@"; do printf ' %q' "$a"; done
+  printf ' >>%q 2>&1\n' "$status"
+  printf 'printf "__EXIT__ %%s\\n" "$?" >>%q\n' "$status"
+} >"$wrapper"
+chmod +x "$wrapper"
+
+# Three tiers, because "detached" means different things per platform and only the
+# first two are actually detached. What matters is escaping the caller's process
+# GROUP — not just ignoring SIGHUP — since that is what a Claude Code teardown kills.
+#
+#   screen  — macOS + Linux (macOS ships it at /usr/bin/screen). Its server
+#             double-forks and reparents to init: fully out of our session.
+#   setsid  — Linux (util-linux, effectively always present; NOT on macOS, and not
+#             in Git Bash). Puts the child in a brand-new session directly.
+#   nohup   — last resort, and NOT equivalent: it survives SIGHUP but stays in this
+#             process group, so a teardown still takes it. This is the Windows/Git
+#             Bash path today.
+if command -v screen >/dev/null 2>&1; then
+  screen -dmS "$sess" "$wrapper"
+  echo "▶ detached as screen session '$sess' — survives this session ending"
+  echo "  follow it live with: screen -r $sess"
+elif command -v setsid >/dev/null 2>&1; then
+  setsid "$wrapper" >/dev/null 2>&1 &
+  echo "▶ detached with setsid (no 'screen' on PATH) — survives this session ending"
+else
+  # Say so plainly. A silent downgrade here reads as "safe to walk away" when it is
+  # not, which is the exact failure that made a half-built tree look like a cohorte
+  # bug for three hours.
+  nohup "$wrapper" >/dev/null 2>&1 &
+  echo "▶ launched with nohup — no 'screen' or 'setsid' on PATH."
+  echo "  WARNING: this does NOT survive the calling session being torn down. It"
+  echo "  ignores SIGHUP but stays in this process group. For a truly unattended"
+  echo "  run, install screen, or start the driver from your own terminal:"
+  echo "    bash <core>/pipeline/scripts/loop.sh $id"
+fi
+
+echo "  status: specs/reports/$id.loop.status   (small — one line per phase)"
+echo "  log:    specs/reports/$id.loop.log      (full transcript — never read this)"

package/scripts/loop.sh

@@ -1,44 +1,102 @@
 #!/usr/bin/env bash
 #
-# loop.sh — autonomous /build → /review → /fix → /review … loop for ONE feature.
+# loop.sh — autonomous /cohorte-build → /cohorte-review → /cohorte-fix → /cohorte-review …
+#           loop for ONE feature.
 #
-#   loop.sh <feature-id> [--max=N] [--no-build] [--rebuild]
+#   loop.sh <feature-id> [--max=N] [--no-build] [--rebuild] [--resume]
 #
 # THE POINT: every phase runs as a SEPARATE `claude -p` child with its own fresh
-# context. The session that typed /loop never sees the diff, the N review reports
+# context. The session that typed /cohorte-loop never sees the diff, the N review reports
 # or the N contracts — it reads only this script's one-line-per-phase stdout and,
 # at the end, the verdict JSON. Running the loop inside the calling session would
 # accumulate all of it in a history that is re-sent at input price on every turn,
 # which is the exact cost the pipeline's /clear discipline exists to avoid.
 #
-# Contract with the pipeline: /review writes specs/reports/<id>.verdict.json on
-# every run. That file — `blocking` and `fingerprint` — is the ONLY channel
-# between cohorte and this driver. No prose is parsed.
+# Contract with the pipeline: /cohorte-review writes specs/reports/<id>.verdict.json on
+# every run, and /cohorte-build writes <id>.readiness.json + <id>.build.json. Those three
+# files — `blocking`, `fingerprint`, `unreviewed`, `verdict`, `dead` — are the ONLY
+# channel between cohorte and this driver. No prose is parsed.
 #
-# Exit codes (three distinct diagnostics, do not collapse them):
+# Two of those fields exist for the same reason: a subagent that DIES returns
+# nothing, and nothing is byte-identical to "clean". A dead implementer means a
+# surface was never built; a dead reviewer means a surface was never audited, and
+# `blocking == 0` would then certify code no one read. Both abort as exit 2.
+#
+# Exit codes (distinct diagnostics, do not collapse them):
 #   0   clean — a review returned blocking == 0
 #   1   ceiling — --max passes used, still blocking (the fix was progressing;
 #       re-run with a higher --max)
-#   2   no usable verdict — /review produced nothing, or aborted on a red
+#   2   no usable verdict — /cohorte-review produced nothing, or aborted on a red
 #       preflight (typecheck/lint/tests broken; the message says which)
 #   3   non-convergent — two consecutive reviews returned the SAME blocking
 #       fingerprint: the fix is treading water, a higher --max will not help
+#   4   not implementable — /cohorte-build's readiness gate returned NOT-READY and spawned
+#       no agent: the frozen spec cannot be built (missing contract shape, unowned
+#       area, absent dependency). Needs /cohorte-spec, not more passes.
 #   64  usage — bad flag, bad id, missing spec, no `claude` on PATH
 #
-# No /fix runs on the last pass: fixing without a review behind it ships
+# No /cohorte-fix runs on the last pass: fixing without a review behind it ships
 # unaudited code. Each fix pass is committed — that commit is the only way back
 # after N autonomous passes.
+#
+# RESUME: the spec's front-matter IS the loop's state (SCHEMA.md §Spec status).
+# Before every phase this script stamps `status: in-progress` + `loop_phase` +
+# `loop_pass` into specs/<id>.md — deterministically, with awk, costing no tokens
+# — and on exit stamps a terminal status (`in-review` clean, `blocked` otherwise).
+# `--resume` reads `loop_pass` back and continues from that pass instead of 1, so
+# a session that died at pass 3 of 5 does not re-pay passes 1 and 2. The build is
+# skipped or redone by the same stamp logic as always (the stamp is only written
+# on a build that finished), so an interrupted build still rebuilds.
 
 set -uo pipefail
 
+# --- hold the machine awake for the whole run --------------------------------
+# System sleep aborts every in-flight `claude -p` request, so a loop that spans
+# hours must own a power assertion for its entire life — a driver killed at hour
+# two has spent hour one for nothing, and the abort is indistinguishable from a
+# clean "agent returned nothing" (which is the `dead` family this script exists
+# to catch). Re-exec ourselves under caffeinate once; the guard keeps it to one
+# level, and `exec` leaves no extra process to reap.
+#
+# macOS `caffeinate -ims`: `-i` idle system sleep · `-m` disk sleep · `-s` system
+# sleep (AC only). NOT `-d`/`-u` — an unattended build has no reason to hold the
+# display on. Linux gets the systemd equivalent. Windows has no scriptable
+# equivalent, and neither does a systemd-less Linux, so both fall through to a
+# no-op rather than pretending: the run still works, it is just as sleep-proof as
+# the machine's own settings make it. A *refused* inhibitor falls through the same
+# way — an unheld power assertion is a degraded run, not a failed one.
+#
+# THIS CANNOT PREVENT LID-CLOSE SLEEP on any platform. No userspace assertion can
+# override it — keep the lid open, or use clamshell mode (AC + external display +
+# external input).
+#
+# PROBE before exec'ing. `exec` replaces this shell, so an inhibitor that *exists* but is
+# refused — `systemd-inhibit` in a container, in CI, or in any session without a logind
+# seat answers `Failed to inhibit: Access denied` and exits 1 — would become the driver's
+# own exit code, and the run would never start at all. "Present" and "usable" are not the
+# same test; only the second one is safe to build an `exec` on. One fast subprocess on a
+# run measured in hours.
+if [ -z "${COHORTE_CAFFEINATED:-}" ]; then
+  if command -v caffeinate > /dev/null 2>&1 && caffeinate -ims true > /dev/null 2>&1; then
+    COHORTE_CAFFEINATED=1 exec caffeinate -ims "$0" "$@"
+  elif command -v systemd-inhibit > /dev/null 2>&1 \
+    && systemd-inhibit --what=sleep:idle --who=cohorte --why="probe" true > /dev/null 2>&1; then
+    COHORTE_CAFFEINATED=1 exec systemd-inhibit \
+      --what=sleep:idle --who=cohorte --why="autonomous $0 run" "$0" "$@"
+  fi
+fi
+
 usage() {
   cat >&2 <<'EOF'
-usage: loop.sh <feature-id> [--max=N] [--no-build] [--rebuild]
+usage: loop.sh <feature-id> [--max=N] [--no-build] [--rebuild] [--resume]
 
-  --max=N      stop after N review passes (default 5)
-  --no-build   never build — re-run the /review ⇄ /fix loop on a feature that
+  --max=N      stop after N review passes (default 5) — a ceiling on the TOTAL
+               pass count, so it still means "5 passes" when resuming at pass 3
+  --no-build   never build — re-run the /cohorte-review ⇄ /cohorte-fix loop on a feature that
                is already built (the common case; the build stamp is ignored)
-  --rebuild    force a /build even if the stamp says it was already built
+  --rebuild    force a /cohorte-build even if the stamp says it was already built
+  --resume     continue from the pass recorded in the spec's front-matter
+               (loop_pass), instead of starting over at pass 1
 
   env CLAUDE_FLAGS   flags for every child session
                      (default: --permission-mode acceptEdits)
@@ -49,6 +107,7 @@ EOF
 id=""
 max=5
 build_mode="auto"          # auto | never | force
+resume=0
 
 for arg in "$@"; do
   case "$arg" in
@@ -61,6 +120,7 @@ for arg in "$@"; do
       ;;
     --no-build) build_mode="never" ;;
     --rebuild)  build_mode="force" ;;
+    --resume)   resume=1 ;;
     -h|--help)  usage ;;
     -*)         echo "loop: unknown flag: $arg" >&2; usage ;;
     *)
@@ -88,14 +148,52 @@ cd "$root" || exit 64
 
 spec="specs/$id.md"
 [ -f "$spec" ] || {
-  echo "loop: no spec at $spec — run /spec $id first" >&2; exit 64; }
+  echo "loop: no spec at $spec — run /cohorte-spec $id first" >&2; exit 64; }
 
 reports="specs/reports"
 mkdir -p "$reports"
 verdict="$reports/$id.verdict.json"
+readiness="$reports/$id.readiness.json"
+buildjson="$reports/$id.build.json"
 stamp="$reports/$id.built"
 log="$reports/$id.loop.log"
 
+# --- the spec front-matter as loop state -------------------------------------
+# Best-effort by design: a spec with no front-matter (or an unwritable one) makes
+# every fm_* call a silent no-op. This is bookkeeping for resume + the dashboard,
+# never a precondition — the loop must not die over a status line.
+fm_get() {                        # fm_get <key>  → value, or empty
+  [ -f "$spec" ] || return 0
+  awk -v k="$1" '
+    NR==1 && $0=="---" { fm=1; next }
+    fm==1 && $0=="---" { exit }
+    fm==1 && $0 ~ "^"k":" {
+      sub("^"k":[[:space:]]*", ""); sub("#.*", "")
+      gsub(/^[[:space:]]+|[[:space:]]+$/, ""); print; exit
+    }
+  ' "$spec"
+}
+
+fm_set() {                        # fm_set <key> <value>  (replace, else append)
+  [ -f "$spec" ] || return 0
+  awk -v k="$1" -v v="$2" '
+    NR==1 && $0!="---" { nofm=1 }
+    nofm { print; next }
+    NR==1 { fm=1; print; next }
+    fm==1 && $0=="---" {
+      if (!done) print k ": " v          # key absent: add it before the closing ---
+      fm=2; print; next
+    }
+    fm==1 && $0 ~ "^"k":" {
+      if (done) next                     # a duplicate key: drop it
+      c=""; i=index($0, "#"); if (i>0) c=" " substr($0, i)   # keep a trailing comment
+      print k ": " v c; done=1; next
+    }
+    { print }
+  ' "$spec" >"$spec.loop.tmp" 2>/dev/null &&
+    mv "$spec.loop.tmp" "$spec" 2>/dev/null || rm -f "$spec.loop.tmp"
+}
+
 : "${CLAUDE_FLAGS:=--permission-mode acceptEdits}"
 
 : >"$log"
@@ -109,8 +207,24 @@ log="$reports/$id.loop.log"
 # parent re-imports the children's transcripts, the whole point is lost.
 # $CLAUDE_FLAGS is intentionally unquoted — it is a flag list, not one word.
 run_phase() {
-  cmd="$1"
-  printf '▶ /%-6s %-24s ' "$cmd" "$id"
+  # $1 is the PHASE name (build|review|fix), which is not the same string as the
+  # command that runs it (`/cohorte-build`). Every command gained a `cohorte-`
+  # prefix in 2.0.0 so Claude Code's built-ins can never shadow them again — but
+  # the phase name is a DATA CONTRACT, written into the spec's `loop_phase`, into
+  # specs/reports/<id>.*.json and into pipeline-metrics.jsonl, and read back by
+  # --resume and the dashboard. Prefixing it too would orphan every historical
+  # metrics line and break resume on specs written by 1.x. So: prefix the command,
+  # never the phase.
+  phase="$1"
+  cmd="cohorte-$phase"
+  # Stamp the state BEFORE the phase runs: if this child dies (or the whole
+  # session does), the spec already says where the loop was — that is what
+  # --resume reads back. Child commands write `status` themselves (/cohorte-fix
+  # sets in-review); re-stamping here each phase keeps `in-progress` true.
+  fm_set status in-progress
+  fm_set loop_pass "$pass"
+  fm_set loop_phase "$phase"
+  printf '▶ /%-14s %-24s ' "$cmd" "$id"
   printf '\n\n===== /%s %s =====\n' "$cmd" "$id" >>"$log"
   # shellcheck disable=SC2086
   if claude -p "/$cmd $id" $CLAUDE_FLAGS >>"$log" 2>&1; then
@@ -127,24 +241,79 @@ run_phase() {
 json_num() { sed -n 's/.*"'"$2"'"[[:space:]]*:[[:space:]]*\([0-9][0-9]*\).*/\1/p' "$1" | head -n1; }
 json_str() { sed -n 's/.*"'"$2"'"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$1" | head -n1; }
 
-finish() { echo "$2"; exit "$1"; }
+# Terminal status goes into the spec, not just into this stdout: a clean run
+# leaves the feature ready to /cohorte-ship, any failure leaves it visibly `blocked` for
+# the human and for the dashboard. Exit 64 never reaches here (usage dies earlier),
+# so every code handled below is a real run outcome.
+finish() {
+  if [ "$1" -eq 0 ]; then
+    fm_set status in-review
+    fm_set loop_pass 0
+    fm_set loop_phase done
+  else
+    fm_set status blocked
+  fi
+  echo "$2"
+  exit "$1"
+}
+
+# One short clause naming the deferred findings, appended to a closing line.
+# They are NOT blocking (they live in the backlog, not in ## Remediation), so
+# they never change an exit code — but a loop that silently drops them is the
+# leak /cohorte-review §3.5 exists to close, so the driver names them.
+def_note() {
+  d="$(json_num "$verdict" deferred 2>/dev/null)"
+  case "$d" in ''|0) return 0 ;; esac
+  printf ' · %s deferred finding(s) parked in specs/refactor-backlog.md' "$d"
+}
 
 # --- build -------------------------------------------------------------------
-# The stamp is the driver's own bookkeeping — /build knows nothing about it.
+# The stamp is the driver's own bookkeeping — /cohorte-build knows nothing about it.
 case "$build_mode" in
   force) do_build=1 ;;
   never) do_build=0 ;;
   auto)  [ -f "$stamp" ] && do_build=0 || do_build=1 ;;
 esac
 
+# --resume: continue from the pass the spec records, not from 1. A missing or
+# junk value falls back to 1 — resuming must never be less safe than starting.
+pass=1
+if [ "$resume" -eq 1 ]; then
+  rp="$(fm_get loop_pass)"
+  case "$rp" in ''|*[!0-9]*|0) rp=1 ;; esac
+  [ "$rp" -le "$max" ] || {
+    echo "loop: --resume says pass $rp but --max=$max — raise --max to continue" >&2; exit 64; }
+  pass="$rp"
+  [ "$pass" -eq 1 ] || printf '↻ resuming at review pass %s (from %s)\n' "$pass" "$spec"
+fi
+
 if [ "$do_build" -eq 1 ]; then
-  run_phase build || finish 2 "✗ /build failed — see $log"
+  # Delete first: a NOT-READY left by a previous build would abort this one on
+  # someone else's verdict (and a stale READY would hide a gate that never ran).
+  rm -f "$readiness" "$buildjson"
+  build_ok=0
+  run_phase build && build_ok=1
+  # The readiness gate is checked BEFORE the child's exit status: /cohorte-build aborting
+  # on NOT-READY is a cleaner diagnosis than "/cohorte-build failed", and it is the one
+  # outcome that more passes cannot fix.
+  if [ -f "$readiness" ] &&
+     grep -q '"verdict"[[:space:]]*:[[:space:]]*"NOT-READY"' "$readiness"; then
+    finish 4 "✗ spec not implementable — /cohorte-build's readiness gate returned NOT-READY and \
+spawned no agent; see $readiness, then /cohorte-spec $id"
+  fi
+  # A dead implementer returns nothing, so /cohorte-build can finish "successfully" having
+  # built one surface of two. Reviewing that would spend N reviewers auditing a
+  # half-built feature and report its gaps as findings to fix — the wrong diagnosis
+  # at the wrong price. `dead` is a non-empty array only when a surface died twice.
+  if [ -f "$buildjson" ] && grep -q '"dead"[[:space:]]*:[[:space:]]*\[[^]]' "$buildjson"; then
+    finish 2 "✗ an implementer died — the surface(s) in \"dead\" were never built; see $buildjson and $log"
+  fi
+  [ "$build_ok" -eq 1 ] || finish 2 "✗ /cohorte-build failed — see $log"
   date -u +%Y-%m-%dT%H:%M:%SZ >"$stamp"
 fi
 
 # --- review ⇄ fix ------------------------------------------------------------
 prev_fp=""
-pass=1
 while [ "$pass" -le "$max" ]; do
   # Delete first: a stale verdict from the previous pass read as this pass's
   # answer would end the loop on someone else's numbers.
@@ -152,10 +321,18 @@ while [ "$pass" -le "$max" ]; do
   run_phase review || true          # exit status of the child is not the verdict
 
   [ -f "$verdict" ] || finish 2 \
-    "✗ /review wrote no verdict (pass $pass) — see $log"
+    "✗ /cohorte-review wrote no verdict (pass $pass) — see $log"
 
   if grep -q '"aborted"' "$verdict"; then
-    finish 2 "✗ /review aborted on a red preflight — typecheck/lint/tests are broken, see $reports/$id.preflight.txt"
+    finish 2 "✗ /cohorte-review aborted on a red preflight — typecheck/lint/tests are broken, \
+see $reports/$id.preflight.txt"
+  fi
+
+  # A reviewer that died twice leaves its surface unaudited, and `blocking` counts only
+  # what the SURVIVING reviewers found — so blocking == 0 here would mean "clean" about
+  # code nobody read. Checked BEFORE blocking, because it invalidates it.
+  if grep -q '"unreviewed"[[:space:]]*:[[:space:]]*\[[^]]' "$verdict"; then
+    finish 2 "✗ a reviewer died — the surface(s) in \"unreviewed\" carry no verdict (pass $pass); see $verdict"
   fi
 
   blocking="$(json_num "$verdict" blocking)"
@@ -163,7 +340,7 @@ while [ "$pass" -le "$max" ]; do
     "✗ verdict has no usable 'blocking' count (pass $pass) — see $verdict"
 
   [ "$blocking" -eq 0 ] && finish 0 \
-    "✓ clean after $pass review pass(es) — no blocking findings"
+    "✓ clean after $pass review pass(es) — no blocking findings$(def_note)"
 
   fp="$(json_str "$verdict" fingerprint)"
   if [ -n "$fp" ] && [ "$fp" = "$prev_fp" ]; then
@@ -171,9 +348,9 @@ while [ "$pass" -le "$max" ]; do
   fi
   prev_fp="$fp"
 
-  # Last pass: report and stop. A /fix here would leave unreviewed code behind.
+  # Last pass: report and stop. A /cohorte-fix here would leave unreviewed code behind.
   [ "$pass" -eq "$max" ] && finish 1 \
-    "✗ ceiling — $blocking blocking finding(s) after $max pass(es); re-run with a higher --max"
+    "✗ ceiling — $blocking blocking finding(s) after $max pass(es); re-run with a higher --max --resume$(def_note)"
 
   run_phase fix || true
 

package/scripts/metrics/collect.mjs

@@ -41,12 +41,12 @@ const IDLE_GAP_S = 120;
 
 // A prompt this short with no command in it ("continue", "go", "ok next") is the human
 // steering a run that is already going, not starting a new one. Without this, a single
-// /review driven by three "continue"s reports as one /review plus three anonymous chat
+// /cohorte-review driven by three "continue"s reports as one /cohorte-review plus three anonymous chat
 // runs, and three quarters of its cost lands under (chat).
 const CONTINUATION_MAX_CHARS = 40;
 
 // Commands are recognised two ways. `<command-name>` is emitted only when the whole prompt
-// IS the slash command; in practice people write "move on branding-ramp and /review", which
+// IS the slash command; in practice people write "move on branding-ramp and /cohorte-review", which
 // the harness records as ordinary prose. So we also look for an inline mention, checked
 // against the real command list rather than any /token — otherwise a file path like
 // /usr/bin or a URL fragment would invent commands that were never run.
@@ -60,20 +60,29 @@ function knownCommands() {
   }
   // Fallback for a collector run outside the package (e.g. copied into a repo on its own).
   if (!names.size) {
-    for (const n of ['brainstorm', 'spec', 'build', 'review', 'fix', 'ship',
-                     'audit', 'refactor', 'align-ds', 'doctor', 'init-pipeline', 'update-pipeline']) names.add(n);
+    for (const n of ['cohorte-brainstorm', 'cohorte-spec', 'cohorte-build', 'cohorte-review',
+                     'cohorte-fix', 'cohorte-ship', 'cohorte-audit', 'cohorte-refactor',
+                     'cohorte-align-ds', 'cohorte-doctor', 'cohorte-loop',
+                     'cohorte-init-pipeline', 'cohorte-update-pipeline']) names.add(n);
   }
   // Retired commands. The list above is read from the shipped core, so a command that is
   // removed stops being recognised — and every run of it already in the transcripts silently
   // reclassifies as (chat), rewriting history and inflating the catch-all bucket. Keep the
   // names here so past runs stay attributed to what actually ran.
-  for (const n of ['cycle', 'smoke']) names.add(n);
+  //
+  // 2.0.0 prefixed every command with `cohorte-`, which retires all 13 bare names at once:
+  // months of transcripts say `/build`, and without these they would all reclassify to (chat)
+  // — the largest instance of exactly the bug this list exists to prevent. `drive`/`loop` are
+  // both here because the driver was `/loop` → `/drive` (1.6.0) → `/cohorte-loop` (2.0.0).
+  for (const n of ['cycle', 'smoke', 'drive', 'loop', 'brainstorm', 'spec', 'build', 'review',
+                   'fix', 'ship', 'audit', 'refactor', 'align-ds', 'doctor',
+                   'init-pipeline', 'update-pipeline']) names.add(n);
   return names;
 }
 const COMMANDS = knownCommands();
 
 // An invocation is a short instruction that is mostly the command ("move on branding-ramp
-// and /review"). A long prompt that happens to name one is someone TALKING ABOUT the
+// and /cohorte-review"). A long prompt that happens to name one is someone TALKING ABOUT the
 // command — a bug report, a design discussion, a pasted transcript. Counting those as runs
 // inflates a command's run count and cost with conversation that never invoked it, which is
 // exactly what happened in cohorte's own repo while this pipeline was being discussed.
@@ -84,7 +93,7 @@ function commandIn(text) {
   const explicit = /<command-name>\s*(\/?[\w:-]+)\s*<\/command-name>/.exec(text);
   if (explicit) return explicit[1].replace(/^\//, '');
   if (text.trim().length > MENTION_MAX_CHARS) return null;
-  // Last mention wins: "finish /build then /review" ends on the one being asked for.
+  // Last mention wins: "finish /cohorte-build then /cohorte-review" ends on the one being asked for.
   let found = null;
   for (const m of text.matchAll(/(?:^|\s)\/([a-z][a-z0-9-]{2,})\b/g)) {
     if (COMMANDS.has(m[1])) found = m[1];
@@ -250,7 +259,7 @@ function parseSession(file) {
       // Not every user-role turn is the human starting something. The harness injects
       // turns mid-run — a local-command echo, and (critically for cohorte) a
       // <task-notification> when a background agent finishes. Those arrive DURING a
-      // a /build; treating them as boundaries chops one command into several
+      // a /cohorte-build; treating them as boundaries chops one command into several
       // cheap-looking fragments and strands the agent spend in the wrong segment.
       if (!cmd && /<(local-command-(stdout|stderr)|task-notification|system-reminder)>/.test(text)) continue;
       // A short steer with no command keeps the current run open rather than opening a new

package/scripts/new-feature.sh.template

@@ -1,9 +1,9 @@
 #!/usr/bin/env bash
 #
 # new-feature.sh — spin up an ISOLATED git worktree for one feature so features
-# can be built fully in parallel. Rendered from a template by /init-pipeline;
+# can be built fully in parallel. Rendered from a template by /cohorte-init-pipeline;
 # the double-underscore tokens below are substituted from PIPELINE.md §isolation.
-# (This comment deliberately avoids spelling the token pattern: /doctor flags any
+# (This comment deliberately avoids spelling the token pattern: /cohorte-doctor flags any
 # leftover double-underscore-caps token in the RENDERED script as unrendered.)
 #
 # Usage:  scripts/new-feature.sh <feature_id>
@@ -85,7 +85,7 @@ Fully isolated — run its dev + migrations alongside other worktrees:
   cd $worktree_dir
   __MIGRATE_CMD__
   cd $worktree_dir && __DEV_CMD__
-  /brainstorm → /spec → (design) → /build $id → test → /review → /ship
+  /cohorte-brainstorm → /cohorte-spec → (design) → /cohorte-build $id → test → /cohorte-review → /cohorte-ship
 
 Tear down when merged:  scripts/remove-feature.sh $id
 EOF

package/scripts/preflight.sh

@@ -1,6 +1,6 @@
 #!/bin/sh
 #
-# preflight.sh — deterministic phase gate for /review.
+# preflight.sh — deterministic phase gate for /cohorte-review.
 #
 # Runs the profile's mechanical checks (typecheck, lint, tests — whatever the caller
 # passes) BEFORE any agent is spawned. A red gate means the caller aborts and relays
@@ -13,9 +13,14 @@
 #   never enters the calling agent's context.
 # - First failure: prints the last 40 lines of the report raw to stderr and exits 1.
 #   The caller must stop there — no agents.
-# - All green: writes `<project>/.claude/preflight.ok` ("<epoch> <HEAD sha>") — the
-#   stamp `hooks/gate.py` checks (gate-config.json `preflight` block) before letting
+# - All green: writes `<project>/.claude/preflight.ok` ("<epoch> <HEAD sha> <tree digest>")
+#   — the stamp `hooks/gate.py` checks (gate-config.json `preflight` block) before letting
 #   review agents dispatch.
+#
+# The stamp is a LOCAL, GITIGNORED artifact. Versioning it breaks the gate outright: the
+# stamp records the pre-commit sha, committing it moves HEAD, so the checked-out stamp can
+# never match its own commit — every dispatch then reports "HEAD moved" on a clean tree.
+# A tracked stamp also rides into every new worktree, handing it a green it never earned.
 
 set -u
 
@@ -46,6 +51,37 @@ done
 # resolves to the MAIN checkout's .git from any worktree.
 proj="${CLAUDE_PROJECT_DIR:-$(dirname "$(git rev-parse --git-common-dir 2>/dev/null || echo ./.git)")}"
 sha=$(git rev-parse HEAD 2>/dev/null || echo none)
+
+# Content digest of the state we actually verified: the git TREE id of the working tree,
+# built in a throwaway index so nothing touches the real one. The sha alone is the wrong
+# key — the reviewed tree is normally DIRTY (uncommitted feature work), so committing it
+# invalidates the stamp without changing a line of code, while an implementer's edit
+# changes every line without moving HEAD. A tree id is content-addressed: it survives a
+# commit of the same content and dies on any real edit (including new untracked files).
+# `.claude` (stamps, metrics) and `specs` (DoD ticks, report buffer) are excluded — the
+# pipeline writes those itself between the preflight and the dispatch it must not invalidate.
+# gate.py recomputes this identically; any change here must land there too.
+digest=none
+tmpidx=$(mktemp 2>/dev/null || echo "")
+if [ -n "$tmpidx" ]; then
+  # Seed from the real index (not `read-tree HEAD`) so its stat cache is preserved and
+  # `add` only re-hashes files that actually changed.
+  idx=$(git rev-parse --git-path index 2>/dev/null || echo "")
+  if [ -n "$idx" ] && [ -f "$idx" ]; then
+    cp "$idx" "$tmpidx" 2>/dev/null || true
+  else
+    rm -f "$tmpidx"                       # a 0-byte index is a corrupt index
+  fi
+  # Drop the excluded paths from the throwaway index entirely: an `add` exclude only stops
+  # them being *updated*, so anything already tracked there (a committed stamp, a spec)
+  # would still land in the tree and shift the digest.
+  GIT_INDEX_FILE="$tmpidx" git rm --cached -r -q --ignore-unmatch -- .claude specs > /dev/null 2>&1 || true
+  if GIT_INDEX_FILE="$tmpidx" git add -A -- . ':(exclude).claude' ':(exclude)specs' > /dev/null 2>&1; then
+    digest=$(GIT_INDEX_FILE="$tmpidx" git write-tree 2>/dev/null || echo none)
+  fi
+  rm -f "$tmpidx" "$tmpidx.lock" 2>/dev/null || true
+fi
+[ -n "$digest" ] || digest=none
 # Stamp BOTH the main checkout and the cwd: gate.py reads CLAUDE_PROJECT_DIR,
 # which is the worktree when the session was opened there and the main checkout
 # when it wasn't — the two disagree, and either layout is supported.
@@ -55,7 +91,7 @@ for d in "$proj" "$(pwd)"; do
   [ "$d" = "$last" ] && continue          # same dir twice in the main checkout
   last="$d"
   mkdir -p "$d/.claude" 2>/dev/null || true
-  printf '%s %s\n' "$now" "$sha" > "$d/.claude/preflight.ok" 2>/dev/null || true
+  printf '%s %s %s\n' "$now" "$sha" "$digest" > "$d/.claude/preflight.ok" 2>/dev/null || true
 done
 
 echo "PREFLIGHT PASS ($n checks green) — full log: $report"