cohorte 2.1.0 → 2.3.0

package/core/commands/cohorte-loop.md

@@ -1,110 +0,0 @@
----
-model: sonnet
-description: Autonomous /cohorte-build → /cohorte-review → /cohorte-fix → /cohorte-review loop for one feature, until no blocking finding remains.
-argument-hint: <feature_id> [--max=N] [--no-build] [--rebuild] [--resume]
-allowed-tools: Bash(bash ~/.claude/pipeline/scripts/loop-detach.sh:*), Bash(bash .claude/pipeline/scripts/loop-detach.sh:*), Bash(test:*), Read(specs/reports/**)
-disable-model-invocation: true
----
-
-You are the **launcher**, not the loop. Run the driver for **$ARGUMENTS** and relay three lines.
-
-> **The driver's name has moved twice.** It was `/loop`, which Claude Code's own built-in `/loop`
-> (run a prompt on a recurring interval) silently **shadowed** — typing `/loop <id>` started the
-> interval runner with the feature id as its prompt, so the driver never ran and the session
-> reported a loop that did not exist. 1.6.0 renamed it `/drive` to escape that. 2.0.0 prefixed
-> every command with `cohorte-`, which makes shadowing impossible by construction, so the accurate
-> name is back: **`/cohorte-loop`**. The shipped script keeps its `loop.sh` name throughout.
->
-> This command exists because a slash command cannot `/clear` itself. Every phase of the loop runs
-> as a **separate `claude -p` child session** with its own fresh context, driven by a bash script —
-> so the diff, the N review reports and the N contracts never accumulate in YOUR history, which is
-> re-sent at input price on every turn. Running the loop conversationally here would cost more than
-> the loop saves.
-
-## 1. Launch — detached, then poll
-
-The driver runs for **hours**, which rules out running it as one foreground Bash call: a single
-call is capped at 600 s, and a backgrounded one is not detached — the child stays in this session's
-process group, so a Claude Code restart, crash or laptop sleep kills `loop.sh` and every `claude -p`
-child with it, mid-write. `loop-detach.sh` puts the driver in its own `screen` session so it
-survives all of that, and `loop.sh` re-execs itself under `caffeinate` so idle sleep cannot abort
-its in-flight requests either.
-
-Launch — returns immediately:
-
-```
-test -f .claude/pipeline/scripts/loop-detach.sh \
-  && bash .claude/pipeline/scripts/loop-detach.sh start $ARGUMENTS \
-  || bash ~/.claude/pipeline/scripts/loop-detach.sh start $ARGUMENTS
-```
-
-Then poll. Each call blocks up to ~9 min (inside the tool ceiling) and prints the **status file** —
-one line per phase, plus `__EXIT__ <code>` when the run is over:
-
-```
-bash ~/.claude/pipeline/scripts/loop-detach.sh wait <feature_id>
-```
-
-**Repeat `wait` until you see `__EXIT__ <code>`.** A `__RUNNING__` line means the driver is still
-working and nothing is wrong — call `wait` again. Never conclude anything from a `__RUNNING__`;
-the run has not finished and you have no verdict to report. If the human says to stop waiting,
-tell them the run continues detached and how to follow it (`screen -r cohorte-<id>`) — do not
-kill it unless they ask.
-
-Pass `$ARGUMENTS` through untouched — `loop.sh` owns its own flag parsing (`--max=N`,
-`--no-build`, `--rebuild`, `--resume`) and exits 64 on anything it doesn't know. Don't validate flags
-yourself, don't rewrite them, don't add any.
-
-**One lid-close caveat to pass on** if the human is walking away from a laptop: `caffeinate` holds
-off *idle* sleep, but no userspace assertion can prevent lid-close sleep. Lid open, or clamshell
-mode (AC + external display + external input).
-
-**Resume is the human's call, not yours.** The loop records its position in the spec's front-matter
-(`status: in-progress` · `loop_pass` · `loop_phase` — SCHEMA.md §Spec status), so a run killed by a
-dead session, a ceiling or a `blocked` exit can continue with `--resume` instead of re-paying the
-passes it already made. If the human types `/cohorte-loop <id>` on a spec whose front-matter says
-`status: in-progress` or `blocked` with `loop_pass` > 1, say so in one line and ask whether to resume
-or restart — never silently add the flag, and never silently restart from pass 1.
-
-**Never read `specs/reports/<id>.loop.log`.** It holds the full transcript of every child session —
-the entire diff, every review report, every fix handoff. Pulling it into this session re-imports
-exactly the context the loop was built to keep out, and it is the one mistake that turns this
-command into the most expensive one in the pipeline. Point the human at the path instead; they can
-open it in an editor for free. The same goes for the per-surface `.diff` and `.preflight.txt` files.
-
-`<id>.loop.status` is the **other** file and is safe: it is the driver's stdout, one line per phase.
-`wait` already prints it, so you never need to Read it yourself. Two files, one letter apart —
-`.log` is the expensive one.
-
-## 2. Report — three lines, from the exit code
-
-`wait` prints one line per phase, one closing line, and `__EXIT__ <code>`; that is your raw
-material, and that code is the exit code the table below is keyed on. For exit
-**1** or **3** only, also Read `specs/reports/<id>.verdict.json` (small, structured, safe) to name
-the remaining findings — never the markdown report, which is the findings body in full. For exit
-**4**, Read `specs/reports/<id>.readiness.json` instead (also small) and relay its `gaps`. On any
-other exit the closing line already carries the deferred count, so read nothing.
-
-| exit | meaning | what to say |
-| ---- | ------- | ----------- |
-| `0` | clean | no blocking findings left; the human can `/cohorte-ship <id>` |
-| `1` | ceiling hit | the fix was progressing but ran out of passes ⇒ re-run with a higher `--max` |
-| `2` | no usable verdict | `/cohorte-review` produced nothing, or aborted on a red preflight — the closing line says which; point at `specs/reports/<id>.preflight.txt` |
-| `3` | non-convergent | the same blocking findings survived a fix pass; a higher `--max` will NOT help — the human needs to look at them (list them from the verdict) |
-| `4` | not implementable | `/cohorte-build`'s readiness gate returned `NOT-READY` — the frozen spec cannot be built and **no agent ran**; Read `specs/reports/<id>.readiness.json` (small, structured) and relay its `gaps`, then point at `/cohorte-spec <id>`. More passes cannot fix this |
-| `64` | usage | relay the script's own message verbatim |
-
-Then print exactly three lines and nothing else — plus a fourth **only when the verdict carries
-`deferred` > 0** (findings that were real but out of this feature's scope, parked in the backlog by
-`/cohorte-review` §3.5; they are not blocking and never cost a pass, but they are not nothing either):
-
-```
-outcome:    <one clause — clean / ceiling / no verdict / non-convergent / not implementable / usage>
-iterations: <n> review pass(es)<, m fix pass(es) committed>
-remaining:  <blocking count + one short phrase per blocking item, or "none">
-deferred:   <n> parked in specs/refactor-backlog.md — /cohorte-refactor <domain> when you want them
-```
-
-Add at most one follow-up sentence: the next command to run. Never restate a finding's fix, never
-summarize the log, never open the diff. Each fix pass is already committed
-(`loop(<id>): fix pass <i>`) — say so on a non-zero exit, since those commits are the way back.

package/scripts/loop-detach.sh

@@ -1,153 +0,0 @@
-#!/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,399 +0,0 @@
-#!/usr/bin/env bash
-#
-# loop.sh — autonomous /cohorte-build → /cohorte-review → /cohorte-fix → /cohorte-review …
-#           loop for ONE feature.
-#
-#   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 /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: /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.
-#
-# 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 — /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 /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] [--resume]
-
-  --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 /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 bypassPermissions)
-EOF
-  exit 64
-}
-
-id=""
-max=5
-build_mode="auto"          # auto | never | force
-resume=0
-
-for arg in "$@"; do
-  case "$arg" in
-    --max=*)
-      max="${arg#--max=}"
-      case "$max" in
-        ''|*[!0-9]*) echo "loop: --max must be a positive integer (got '${arg#--max=}')" >&2; exit 64 ;;
-      esac
-      [ "$max" -ge 1 ] || { echo "loop: --max must be >= 1" >&2; exit 64; }
-      ;;
-    --no-build) build_mode="never" ;;
-    --rebuild)  build_mode="force" ;;
-    --resume)   resume=1 ;;
-    -h|--help)  usage ;;
-    -*)         echo "loop: unknown flag: $arg" >&2; usage ;;
-    *)
-      [ -z "$id" ] || { echo "loop: unexpected argument: $arg" >&2; usage; }
-      id="$arg"
-      ;;
-  esac
-done
-
-[ -n "$id" ] || usage
-# --no-build --rebuild together is a contradiction, not a precedence puzzle.
-case " $* " in
-  *" --no-build "*) case " $* " in *" --rebuild "*)
-    echo "loop: --no-build and --rebuild are mutually exclusive" >&2; exit 64 ;; esac ;;
-esac
-
-command -v claude >/dev/null 2>&1 || {
-  echo "loop: no 'claude' on PATH — the loop drives child claude -p sessions" >&2
-  exit 64
-}
-
-root="$(git rev-parse --show-toplevel 2>/dev/null)" || {
-  echo "loop: not inside a git checkout" >&2; exit 64; }
-cd "$root" || exit 64
-
-spec="specs/$id.md"
-[ -f "$spec" ] || {
-  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"
-}
-
-# --- child session flags -----------------------------------------------------
-# bypassPermissions, NOT acceptEdits. acceptEdits auto-approves Write/Edit and
-# NOTHING else, so every Bash call in a child falls back to the settings.json
-# rules — and the first one no `allow` prefix covers raises a permission prompt.
-# In `claude -p` there is nobody to answer it: the child stalls, eventually
-# prints prose asking the human to approve, and EXITS 0. The driver then reads
-# that as a clean phase. Observed on a real run: the review child hung on its own
-# preflight.sh call ("could you approve the pending tool-call prompt") and the
-# loop scored the phase `ok`.
-#
-# This is also what the gate hook is built for: hooks/gate.py escalates every
-# `ask` match to a hard DENY under bypassPermissions, precisely because an
-# unattended run has nobody to confirm. The dangerous commands stay blocked — by
-# the gate, deterministically, from PIPELINE.md `gate` — while the mechanical
-# ones (typecheck, lint, tests, git diff) stop needing a human. Driving the loop
-# in acceptEdits gets this backwards: nothing is auto-denied and everything is
-# auto-hung. Override with CLAUDE_FLAGS to run in a stricter mode interactively.
-: "${CLAUDE_FLAGS:=--permission-mode bypassPermissions}"
-
-# A `/cohorte-build` implementer batch runs 25–40 min as background tasks. In print
-# mode the harness waits a bounded time for background work and then TERMINATES it
-# ("Background tasks still running after 600s; terminating"), which cuts implementers
-# off mid-write and still exits the child 0. 0 = wait indefinitely; the caffeinate
-# assertion above and the phase's own completion are what bound a phase, not a
-# stopwatch that fires in the middle of the longest one.
-export CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0
-
-: >"$log"
-{
-  printf '# loop %s — max=%s build=%s\n' "$id" "$max" "$build_mode"
-  printf '# flags: %s\n' "$CLAUDE_FLAGS"
-} >>"$log"
-
-# --- one phase = one throwaway child session ---------------------------------
-# ALL child output is redirected into $log and never surfaces here: if the
-# 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() {
-  # $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
-    echo "ok"
-    return 0
-  fi
-  echo "fail"
-  return 1
-}
-
-# Scalar reads on a flat JSON object — no jq dependency (the pipeline ships no
-# runtime deps). Only `blocking` and `fingerprint` are ever read; both are
-# top-level scalars by construction of the verdict contract.
-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; }
-
-# 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 — /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
-  # 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"
-  # An ABSENT build.json is the same class of lie as a dead implementer, and the `dead`
-  # check above cannot see it: a phase cut short (harness background-task ceiling, a
-  # Claude Code teardown, a crash) never reaches §3's report, so there is no file to
-  # grep and no surface to name — while the child still exits 0. Treating "no report"
-  # as "nothing to report" is what let a build of 3 surfaces stamp itself green with 2
-  # of them never written, and sent reviewers at the result.
-  [ -f "$buildjson" ] || finish 2 "✗ /cohorte-build wrote no $buildjson — the phase was cut short \
-(background-task ceiling, teardown or crash) and the surfaces it never reported are unbuilt; see $log"
-  date -u +%Y-%m-%dT%H:%M:%SZ >"$stamp"
-fi
-
-# --- review ⇄ fix ------------------------------------------------------------
-prev_fp=""
-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.
-  rm -f "$verdict"
-  run_phase review || true          # exit status of the child is not the verdict
-
-  [ -f "$verdict" ] || finish 2 \
-    "✗ /cohorte-review wrote no verdict (pass $pass) — see $log"
-
-  if grep -q '"aborted"' "$verdict"; then
-    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)"
-  [ -n "$blocking" ] || finish 2 \
-    "✗ verdict has no usable 'blocking' count (pass $pass) — see $verdict"
-
-  [ "$blocking" -eq 0 ] && finish 0 \
-    "✓ clean after $pass review pass(es) — no blocking findings$(def_note)"
-
-  fp="$(json_str "$verdict" fingerprint)"
-  if [ -n "$fp" ] && [ "$fp" = "$prev_fp" ]; then
-    finish 3 "✗ non-convergent — the same $blocking blocking finding(s) survived a fix pass; see $verdict"
-  fi
-  prev_fp="$fp"
-
-  # 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 --resume$(def_note)"
-
-  run_phase fix || true
-
-  # Non-fatal by design: nothing to commit is a legitimate outcome (an agent
-  # that decided a finding needed no code change). The commit itself is the
-  # rollback point for the pass that just ran.
-  git add -A >>"$log" 2>&1
-  git commit -m "loop($id): fix pass $pass" >>"$log" 2>&1 || true
-
-  pass=$((pass + 1))
-done
-
-finish 1 "✗ ceiling — $max pass(es) exhausted"