cohorte 1.4.0 → 1.6.0

package/scripts/loop.sh

@@ -0,0 +1,318 @@
+#!/usr/bin/env bash
+#
+# loop.sh — autonomous /build → /review → /fix → /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 /drive 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, and /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 — /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 — /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 /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
+# 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
+
+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 /review ⇄ /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
+  --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)
+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 /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"
+{
+  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() {
+  cmd="$1"
+  # 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 (/fix sets
+  # in-review); re-stamping here each phase is what keeps `in-progress` true.
+  fm_set status in-progress
+  fm_set loop_pass "$pass"
+  fm_set loop_phase "$cmd"
+  printf '▶ /%-6s %-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 /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 /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.
+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: /build aborting
+  # on NOT-READY is a cleaner diagnosis than "/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 — /build's readiness gate returned NOT-READY and spawned no agent; see $readiness, then /spec $id"
+  fi
+  # A dead implementer returns nothing, so /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 "✗ /build failed — 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 \
+    "✗ /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"
+  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 /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"

package/scripts/metrics/collect.mjs

@@ -60,21 +60,30 @@ 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', 'smoke', 'review', 'fix', 'ship',
+    for (const n of ['brainstorm', 'spec', 'build', 'review', 'fix', 'ship',
                      'audit', 'refactor', 'align-ds', 'doctor', 'init-pipeline', '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']) names.add(n);
+  for (const n of ['cycle', 'smoke']) 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
+// 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.
+// Only inline mentions are length-gated; an explicit <command-name> is always an invocation.
+const MENTION_MAX_CHARS = 120;
+
 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.
   let found = null;
   for (const m of text.matchAll(/(?:^|\s)\/([a-z][a-z0-9-]{2,})\b/g)) {

package/scripts/preflight.sh

@@ -1,6 +1,6 @@
 #!/bin/sh
 #
-# preflight.sh — deterministic phase gate for /review and /smoke.
+# preflight.sh — deterministic phase gate for /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
@@ -15,7 +15,7 @@
 #   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
-#   review/smoke agents dispatch.
+#   review agents dispatch.
 
 set -u
 

package/scripts/telemetry-send.sh

@@ -2,7 +2,7 @@
 # telemetry-send.sh — fire-and-forget anonymous usage ping (SCHEMA.md §Telemetry).
 #
 #   telemetry-send.sh <phase> <feature_id> <seconds> [results]
-#     phase    brainstorm|spec|build|smoke|review|fix|ship — the feature funnel, and only it.
+#     phase    brainstorm|spec|build|review|fix|ship — the feature funnel, and only it.
 #              Setup/maintenance commands never ping (SCHEMA.md §Telemetry).
 #     feature  the feature id — NEVER sent raw; SHA-256-hashed to 12 hex chars
 #     seconds  batch wall-clock
@@ -39,7 +39,10 @@ phase="${1:-}"; feature="${2:-}"; seconds="${3:-0}"; results="${4:-}"
 # Allowlist the phase here — the collector accepts any string, so a typo in a command
 # file would silently pollute the dataset with a phantom phase nobody notices.
 case "$phase" in
-  brainstorm|spec|build|smoke|review|fix|ship) ;;
+  brainstorm|spec|build|review|fix|ship) ;;
+  # `smoke` is a RETIRED phase (removed in 1.5.0) — still accepted so a stale install
+  # pinging it lands in its own bucket instead of being silently dropped.
+  smoke) ;;
   *) exit 0 ;;
 esac
 

package/scripts/test-dashboard.mjs

@@ -20,6 +20,7 @@ const require = createRequire(import.meta.url);
 const root = fileURLToPath(new URL("..", import.meta.url));
 const { parse, parseProfileBlock } = require(join(root, "dashboard/server/yaml.js"));
 const { metrics } = require(join(root, "dashboard/server/metrics.js"));
+const { usage } = require(join(root, "dashboard/server/usage.js"));
 const { state, scanSpecs } = require(join(root, "dashboard/server/doctor.js"));
 const { kanban } = require(join(root, "dashboard/server/kanban.js"));
 const fleet = require(join(root, "dashboard/server/fleet.js"));
@@ -106,6 +107,25 @@ console.log("metrics.js — the funnel aggregate");
   check("no metrics file ⇒ present:false", metrics({ projectRoot: scratch() }).present === false);
 }
 
+// ── usage.js ─────────────────────────────────────────────────────────────────
+// Wraps the ESM metrics collector for the CJS server. The failure that matters is
+// not a crash: a project with no transcripts must say so, because rendering zeros
+// reads as "this pipeline costs nothing" rather than "nothing was measured".
+console.log("usage.js — the collector bridge");
+{
+  const empty = usage({ projectRoot: scratch() });
+  check("a project with no transcripts reports present:false", empty.present === false);
+  check("…and says why rather than returning silent zeros",
+    typeof empty.error === "string" && empty.error.length > 0, JSON.stringify(empty));
+
+  // Same project twice: the second call must come from cache, or the panel's polling
+  // would re-parse tens of MB of transcripts on every refresh.
+  const d = scratch();
+  const t0 = Date.now(); usage({ projectRoot: d });
+  const t1 = Date.now(); usage({ projectRoot: d }); const cached = Date.now() - t1;
+  check("a repeated read is served from cache", cached <= Math.max(50, (t1 - t0)), `${cached}ms`);
+}
+
 // ── doctor.js ────────────────────────────────────────────────────────────────
 console.log("doctor.js — the /doctor port");
 {
@@ -135,7 +155,7 @@ console.log("doctor.js — the /doctor port");
   const d = scratch();
   const gate = {
     deny: ["x"], ask: ["y"], ask_on_default_branch: ["git push"], default_branch: "main",
-    preflight: { enabled: true, agents: ["review", "smoke"], max_age_minutes: 30 },
+    preflight: { enabled: true, agents: ["review"], max_age_minutes: 30 },
   };
   writeFileSync(join(d, "PIPELINE.md"), [
     "```yaml pipeline-profile",
@@ -153,7 +173,7 @@ console.log("doctor.js — the /doctor port");
     '  ask_on_default_branch: ["git push"]',
     "  preflight:",
     "    enabled: true",
-    "    agents: [review, smoke]",
+    "    agents: [review]",
     "    max_age_minutes: 30",
     "```",
   ].join("\n"));

package/scripts/test-gate.mjs

@@ -181,7 +181,7 @@ console.log("gate.py — config robustness");
 // ── the preflight phase gate (Task dispatches) ───────────────────────────────
 console.log("gate.py — preflight phase gate");
 {
-  const pf = { enabled: true, agents: ["review", "smoke"], max_age_minutes: 30 };
+  const pf = { enabled: true, agents: ["review"], max_age_minutes: 30 };
   const d = scratch(); writeConfig(d, { ...GATE_CFG, preflight: pf });
   const head = gitRepo(d, "main");
   const stamp = (epoch, sha) =>
@@ -195,7 +195,6 @@ console.log("gate.py — preflight phase gate");
 
   stamp(now(), head);
   check("fresh stamp at the current HEAD ⇒ passes", run(task("review"), at).decision === null);
-  check("smoke is gated too", run(task("smoke"), at).decision === null);
 
   stamp(now() - 60 * 60, head);
   check("stamp older than max_age_minutes ⇒ ask", run(task("review"), at).decision === "ask");