cohorte 2.7.0 → 2.9.0

package/install.sh

@@ -43,8 +43,9 @@ install.sh — install the cohorte pipeline core.
 
 Honours $CLAUDE_CONFIG_DIR for the global destination and $PIPELINE_REPO for the
 source when piped through curl. The npm CLI (`npm i -g cohorte` then `cohorte install`)
-does the same thing and is the documented route; this script exists for Node-less
-environments.
+does the same thing and is the documented route; this script exists for npm-less
+setups (curl straight from the repo). Node itself is still required — the commands
+are rendered per coding agent at install time and there is no shell renderer.
 USAGE
       exit 0 ;;
     --)       shift; break ;;
@@ -59,7 +60,12 @@ src=""
 self="${0:-}"
 self_dir=""
 case "$self" in
-  */*) self_dir=$(CDPATH= cd -- "$(dirname -- "$self")" && pwd) ;;
+  # `sh install.sh` from inside a checkout hands $0 with no slash — the old */*-only
+  # case missed it and silently CLONED the remote instead of installing the local
+  # tree the human was standing in (dirname of a bare name is `.`, which is exactly
+  # right here; the piped-stdin case stays `sh`, matches neither arm, and clones).
+  */*)          self_dir=$(CDPATH= cd -- "$(dirname -- "$self")" && pwd) ;;
+  *install.sh*) self_dir=$(pwd) ;;
 esac
 if [ -n "$self_dir" ] && [ -d "$self_dir/core" ]; then
   src="$self_dir"
@@ -72,313 +78,37 @@ else
 fi
 [ -d "$src/core" ] || { echo "error: pipeline source not found (no core/ in $src)" >&2; exit 1; }
 
-# --- delegate to the Node CLI ------------------------------------------------
+# --- require Node >= 18, then delegate to the Node CLI -----------------------
 # Since 2.2.0 the commands in core/ are runtime-NEUTRAL sources: they carry capability
 # conditionals (`<!-- cohorte:if subagents -->`) and path tokens (`<core>`, `<state>`) that
 # the adapter resolves per coding agent. Copying them verbatim, as this script used to,
 # would install prompts full of unresolved markers — an install that looks successful and
 # instructs the model with text meant for a different runtime. There is no shell renderer,
-# so hand the whole job to bin/cli.js, which is the documented route anyway.
+# so the whole job goes to bin/cli.js, which is the documented route anyway. (The legacy
+# copy-verbatim shell path was removed in 2.7.0 — it had been unreachable dead code since
+# 2.2.0, and its text was what validate-core's copy checks were vacuously matching.)
 if command -v node >/dev/null 2>&1; then
+  # An old Node fails DEEP into cli.js (fs.cpSync needs >= 16.7) after some files are
+  # already on disk — a half-install that reports as a crash. Refuse up front instead.
+  node_major=$(node -p 'process.versions.node.split(".")[0]' 2>/dev/null || echo 0)
+  case "$node_major" in *[!0-9]*) node_major=0 ;; esac
+  if [ "$node_major" -lt 18 ]; then
+    echo "error: cohorte needs Node >= 18 — found $(node --version 2>/dev/null || echo '?')." >&2
+    echo "  Upgrade Node, then re-run this script (or: npm i -g cohorte && cohorte install$([ "$scope" = global ] && echo ' --global'))." >&2
+    exit 1
+  fi
   set -- install
   [ "$mode" = "update" ] && set -- update
   [ "$scope" = "global" ] && set -- "$@" --global
   [ "$scope" = "project" ] && set -- "$@" "$target"
-  exec node "$src/bin/cli.js" "$@"
+  # Not `exec`: exec replaces this shell, so the curl-path EXIT trap (rm -rf "$tmp")
+  # never fires and every piped install leaks the shallow clone in $TMPDIR.
+  node "$src/bin/cli.js" "$@"
+  exit $?
 fi
-echo "error: cohorte needs Node ≥ 18 to install." >&2
+echo "error: cohorte needs Node >= 18 to install." >&2
 echo "  The pipeline's commands are rendered per coding agent (Claude Code, Codex, Cursor," >&2
 echo "  Gemini CLI, OpenCode) at install time; there is no shell equivalent of that step," >&2
 echo "  and a raw copy would install prompts this runtime cannot follow." >&2
 echo "  Install Node, then:  npm i -g cohorte && cohorte install$([ "$scope" = global ] && echo ' --global')" >&2
 exit 1
-
-# --- resolve the destination .claude dir ------------------------------------
-if [ "$scope" = "global" ]; then
-  dest="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
-else
-  dest="$target/.claude"
-fi
-mkdir -p "$dest"
-
-# version stamp so a per-repo pointer can record which core it expects:
-# the package.json semver, with the git sha for traceability on from-main installs
-semver=$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$src/package.json" 2>/dev/null | head -n 1)
-sha=$(git -C "$src" rev-parse --short HEAD 2>/dev/null || true)
-if [ -n "$semver" ] && [ -n "$sha" ]; then ver="$semver ($sha)"
-elif [ -n "$semver" ]; then ver="$semver"
-else ver="${sha:-unknown}"
-fi
-
-copy_core() {
-  cp -R "$src/core/commands"  "$dest/"
-  cp -R "$src/core/hooks"     "$dest/"
-  cp -R "$src/core/templates" "$dest/"
-  cp -R "$src/core/workflows" "$dest/"
-  # A Python bytecode cache appears in a source checkout the moment anyone compiles
-  # or imports gate.py (CI does) and `cp -R` carries it along — machine- and
-  # interpreter-specific, and copy-over would never delete it later.
-  rm -rf "$dest/hooks/__pycache__"
-  # 0.1.19 renamed questionnaire-domain-brief.md → research-brief.md; drop the stale copy.
-  rm -f "$dest/templates/questionnaire-domain-brief.md"
-  mkdir -p "$dest/pipeline/scripts"
-  cp "$src/profile/PIPELINE.template.md" "$dest/pipeline/"
-  cp "$src/profile/SCHEMA.md"            "$dest/pipeline/"
-  cp "$src/profile/cohorte.config.template.yaml" "$dest/pipeline/"
-  cp "$src"/scripts/*.template           "$dest/pipeline/scripts/"
-  cp "$src/scripts/kanban-move.sh"       "$dest/pipeline/scripts/"
-  cp "$src/scripts/preflight.sh"         "$dest/pipeline/scripts/"
-  chmod +x "$dest/pipeline/scripts/kanban-move.sh" \
-           "$dest/pipeline/scripts/preflight.sh" 2>/dev/null || true
-  # 2.3.0 removed telemetry. Copy-over never deletes, so an existing install would keep an
-  # executable that still POSTs to the collector — scrub the script itself. The dead
-  # `telemetry:` block in the user's config is not this installer's to parse; the interactive
-  # /cohorte-update-pipeline deletes it (SCHEMA.md §Reconcile step 5).
-  rm -f "$dest/pipeline/scripts/telemetry-send.sh"
-  cp "$src/core/agents/implementer.template.md" "$dest/pipeline/"
-  [ -f "$src/CHANGELOG.md" ] && cp "$src/CHANGELOG.md" "$dest/pipeline/"
-  printf '%s\n' "$ver" > "$dest/pipeline/VERSION"
-  chmod +x "$dest/hooks/gate.py" 2>/dev/null || true
-  scrub_tdd_gate
-}
-
-# The TDD gate was removed in 0.1.6. Older installs have hooks/tdd_gate.py on disk and
-# registered in settings.json — copy-over never deletes, and a registered hook whose file
-# is gone errors on every Write/Edit, so scrub both.
-scrub_tdd_gate() {
-  rm -f "$dest/hooks/tdd_gate.py"
-  [ -f "$dest/settings.json" ] || return 0
-  command -v python3 >/dev/null 2>&1 || return 0
-  python3 - "$dest/settings.json" <<'PY'
-import json, sys
-settings = sys.argv[1]
-try:
-    with open(settings) as fh:
-        data = json.load(fh)
-except Exception:
-    sys.exit(0)
-pre = data.get("hooks", {}).get("PreToolUse")
-if not isinstance(pre, list):
-    sys.exit(0)
-kept = [e for e in pre if not any(
-    h.get("command", "").strip().endswith("tdd_gate.py") for h in e.get("hooks", []))]
-if len(kept) != len(pre):
-    data["hooks"]["PreToolUse"] = kept
-    with open(settings, "w") as fh:
-        json.dump(data, fh, indent=2)
-        fh.write("\n")
-    print("  · removed the retired tdd_gate.py hook (file + settings registration)")
-PY
-}
-
-# the fixed (non-rendered) agents: the dev review/release pipeline agents
-copy_fixed_agents() {
-  mkdir -p "$dest/agents"
-  cp "$src/core/agents/review.md" "$src/core/agents/release.md" \
-     "$src/core/agents/profile-reader.md" \
-     "$dest/agents/"
-  # 1.5.0 removed the /smoke phase; copy-over never deletes, so scrub the orphan agent.
-  rm -f "$dest/agents/smoke.md" "$dest/commands/smoke.md"
-  # 1.4.0 removed /cycle and its workflow — and no installer ever scrubbed them, so every
-  # install since has kept offering a command that dispatches a workflow whose phases were
-  # later deleted. A dead command is worse than a missing one: the model can still fire it.
-  rm -f "$dest/commands/cycle.md" "$dest/workflows/cycle.js"
-  # 1.6.0 renamed /loop → /drive: Claude Code's own built-in /loop shadowed ours, so a leftover
-  # commands/loop.md is a command the user can never reach — scrub it rather than leave a decoy.
-  rm -f "$dest/commands/loop.md"
-  # 2.0.0 prefixed every command with `cohorte-`, which ends the shadowing problem for good.
-  # Copy-over never deletes, so all 13 bare names would survive an upgrade as decoys — and a
-  # stale /build is the worst kind: it still dispatches implementers, from a 1.x command file
-  # that knows nothing of this core's contract. /drive goes too (it became /cohorte-loop).
-  for c in align-ds audit brainstorm build doctor drive fix init-pipeline \
-           refactor review ship spec update-pipeline; do
-    rm -f "$dest/commands/$c.md"
-  done
-  # 0.1.19 split the bi-mode questionnaire-researcher into research-agent + questionnaire-architect;
-  # copy-over never deletes, so scrub the retired agent lest a dead subagent_type linger.
-  rm -f "$dest/agents/questionnaire-researcher.md"
-  scrub_research_questionnaire
-}
-
-# The research + questionnaire capability was removed. Older installs have its agents, commands,
-# templates and template-step dirs on disk; copy-over never deletes, so scrub every orphan.
-scrub_research_questionnaire() {
-  rm -f "$dest/agents/research-agent.md" \
-        "$dest/agents/questionnaire-architect.md" \
-        "$dest/agents/questionnaire-writer.md" \
-        "$dest/agents/questionnaire-validator.md" \
-        "$dest/commands/research.md" \
-        "$dest/commands/questionnaire.md" \
-        "$dest/templates/research-brief.md" \
-        "$dest/templates/questionnaire-blueprint.md" \
-        "$dest/templates/questionnaire-declaration.md" \
-        "$dest/templates/questionnaire-verdict.md"
-  rm -rf "$dest/templates/steps/research" "$dest/templates/steps/questionnaire"
-}
-
-# pipeline capability config is USER-level (vault, Notion DB, kanban boards) — it lives in
-# ~/.claude regardless of install scope. Seed it only if neither the consolidated nor the
-# legacy copy exists. This piped installer is non-interactive: it seeds disabled defaults;
-# /cohorte-init-pipeline + /cohorte-update-pipeline wire it (the npm CLI's installer offers a quick interview instead).
-seed_config() {
-  base="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
-  cfg="$base/cohorte.config.yaml"
-  legacy=""
-  for n in thebidouille.config.yaml; do
-    [ -f "$base/$n" ] && { legacy="$base/$n"; break; }
-  done
-  if [ -f "$cfg" ]; then
-    echo "  · kept your existing $cfg"
-  elif [ -n "$legacy" ]; then
-    echo "  · found legacy $legacy — kept as-is (read as a fallback)."
-    echo "    Run /cohorte-update-pipeline to migrate it into cohorte.config.yaml + wire the kanban."
-  else
-    mkdir -p "$base"
-    cp "$src/profile/cohorte.config.template.yaml" "$cfg"
-    echo "  · seeded $cfg (disabled defaults — enable via /cohorte-init-pipeline or /cohorte-update-pipeline)"
-  fi
-}
-
-# Register the profile-driven gate hook in the GLOBAL settings.json. Idempotent: the
-# hook reads each repo's own .claude/gate-config.json (and no-ops where absent),
-# so one registration serves every project.
-register_global_hook() {
-  python3 - "$dest/settings.json" "$dest/hooks/gate.py" <<'PY'
-import json, sys
-settings, gate = sys.argv[1], sys.argv[2]
-# The matcher MUST cover Task as well as Bash: gate.py's preflight phase gate
-# keys off tool_name == "Task" (the `preflight` block in a repo's
-# gate-config.json). A Bash-only matcher never delivers a Task dispatch to the
-# hook, so that gate silently never fires — it was dead code from 1.3.0 to 1.3.1.
-MATCHER = "Bash|Task"
-base = gate.rsplit("/", 1)[-1]
-
-
-def is_gate(entry):
-    # Trailing-quote tolerant: the Windows form is `py "C:\...\gate.py"`, and a
-    # bare .endswith() missed it — which is how repeat installs accumulated a
-    # duplicate registration every time (gate.py then ran once per copy).
-    return any(
-        (h.get("command") or "").strip().rstrip('"').endswith(base)
-        for h in entry.get("hooks", [])
-    )
-
-
-try:
-    with open(settings) as fh:
-        data = json.load(fh)
-    if not isinstance(data, dict):
-        data = {}
-except Exception:
-    data = {}
-pre = data.setdefault("hooks", {}).setdefault("PreToolUse", [])
-# Reconcile rather than append-if-absent: drop every existing gate.py
-# registration, then add exactly one. Idempotent, collapses duplicates older
-# installers left behind, and upgrades a stale "Bash"-only matcher in place —
-# an append-if-absent would find the stale entry and skip, pinning the bug.
-kept = [e for e in pre if not is_gate(e)]
-kept.append({"matcher": MATCHER,
-             "hooks": [{"type": "command", "command": "python3 " + gate}]})
-data["hooks"]["PreToolUse"] = kept
-with open(settings, "w") as fh:
-    json.dump(data, fh, indent=2)
-    fh.write("\n")
-print("ok")
-PY
-}
-
-# Bump only the core_version in a repo's committed .claude/pipeline.json (bundled mode).
-# Leaves every other field intact; no-ops if the pointer is absent or has no core_version.
-bump_pointer_version() {
-  ptr="$1"; newver="$2"
-  [ -f "$ptr" ] || return 0
-  python3 - "$ptr" "$newver" <<'PY'
-import json, sys
-ptr, newver = sys.argv[1], sys.argv[2]
-try:
-    with open(ptr) as fh:
-        data = json.load(fh)
-except Exception:
-    sys.exit(0)
-if isinstance(data, dict) and "core_version" in data:
-    data["core_version"] = newver
-    with open(ptr, "w") as fh:
-        json.dump(data, fh, indent=2, ensure_ascii=False)
-        fh.write("\n")
-PY
-}
-
-if [ "$scope" = "global" ]; then
-  if [ "$mode" = "install" ]; then
-    echo "→ installing pipeline core GLOBALLY into $dest"
-  else
-    echo "→ updating pipeline core GLOBALLY in $dest (keeping global settings.json)"
-  fi
-  copy_fixed_agents
-  copy_core
-  hook_state=$(register_global_hook || echo "skipped")
-  seed_config
-  cat <<EOF
-
-✓ pipeline core installed globally into $dest  (version $ver)
-  gate hook: $hook_state  (reads each repo's .claude/gate-config.json; silent where absent)
-
-The commands (/cohorte-init-pipeline, /cohorte-brainstorm, /cohorte-build …) and the review/release agents are now
-available in EVERY project on this machine — nothing is copied per repo.
-
-Per repo:
-  1. Open the project in Claude Code.
-  2. Run  /cohorte-init-pipeline  — it generates PIPELINE.md, renders the surface agents, writes
-     .claude/gate-config.json, and drops a committed .claude/pipeline.json pointer so
-     teammates know to install the global core ($REPO_URL).
-  3. Commit PIPELINE.md + .claude/, then  /cohorte-brainstorm  to start a feature.
-
-Code retrieval (Serena — the default provider /cohorte-init-pipeline wires per repo):
-  uv tool install -p 3.13 serena-agent   # once per machine
-  Make sure ~/.local/bin is on PATH (uv tool update-shell) — otherwise the
-  registered MCP server silently fails to start.
-
-Global kanban config, user-scoped — optional:
-  · One consolidated file: ~/.claude/cohorte.config.yaml (don't hand-edit it).
-  · /cohorte-init-pipeline (new project) and /cohorte-update-pipeline (existing) wire it for you: creating +
-    syncing an Obsidian kanban board of the pipeline in your shared vault.
-EOF
-  exit 0
-fi
-
-if [ "$mode" = "install" ]; then
-  echo "→ installing pipeline core into $dest"
-  copy_fixed_agents
-  copy_core
-  seed_config
-  mkdir -p "$target/specs"
-  [ -f "$target/specs/_template.md" ] || cp "$src/core/templates/spec.template.md" "$target/specs/_template.md"
-  cat <<EOF
-
-✓ pipeline core installed into $dest  (version $ver)
-
-Next:
-  1. Open the project in Claude Code.
-  2. Run  /cohorte-init-pipeline   — it detects your stack, asks the gaps, and generates
-     PIPELINE.md + renders one implementer agent per surface.
-  3. Commit PIPELINE.md, then  /cohorte-brainstorm  to start a feature.
-
-Code retrieval (Serena — the default provider /cohorte-init-pipeline wires per repo):
-  uv tool install -p 3.13 serena-agent   # once per machine
-  Make sure ~/.local/bin is on PATH (uv tool update-shell) — otherwise the
-  registered MCP server silently fails to start.
-
-Prefer one shared core across all your repos?  Re-run with  --global.
-EOF
-else
-  echo "→ updating pipeline core in $dest (keeping your PIPELINE.md + rendered agents)"
-  copy_core
-  copy_fixed_agents 2>/dev/null || true
-  seed_config
-  bump_pointer_version "$dest/pipeline.json" "$ver"
-  cat <<EOF
-
-✓ core refreshed to $ver. Your PIPELINE.md, rendered surface agents, gate-config.json and
-  settings.json were left as-is. Re-run /cohorte-init-pipeline if your stack changed.
-EOF
-fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cohorte",
-  "version": "2.7.0",
+  "version": "2.9.0",
   "description": "Portable, stack-agnostic multi-agent development pipeline for Claude Code, Codex CLI, Cursor, Gemini CLI and OpenCode — install the core, run /cohorte-init-pipeline, and it adapts to your project's stack.",
   "bin": {
     "cohorte": "bin/cli.js"

package/profile/SCHEMA.md

@@ -185,8 +185,13 @@ proposing a split: split the surface that actually dominates wall-clock, not the
 ## Measuring cost — what's slow vs what's expensive
 
 `pipeline-metrics.jsonl` records **wall-clock seconds** per phase batch (§Specialization) — it tells you
-what's SLOW. It deliberately does NOT record tokens: the lead can't reliably read a subagent's token count
-to log it. For what's EXPENSIVE, use Claude Code's own accounting:
+what's SLOW. Tokens are recorded only where they can be read honestly: the **workflow paths**
+(`loop.js`, `review.js`) stamp an approximate `tokens` field per batch from the runtime's own
+counter (`budget.spent()` deltas), and the loop's return carries a per-round breakdown in its
+`history`. The **conversational** commands still record none — a lead cannot reliably read a
+subagent's token count, and a guessed number is worse than a missing one. The dashboard sums
+whatever is stamped (a token-less line aggregates as 0, rendered as absent, never as "free").
+For exact spend, use Claude Code's own accounting:
 
 - **`/cost`** (built-in, zero setup) — reports per-**subagent** and per-**slash-command** share of your usage
   over the last 24 h / 7 d (e.g. _"Top subagents: frontend 7 %, backend 4 % · Top skills: /cohorte-build 1 %,
@@ -237,11 +242,15 @@ it, the dashboard boards on it, and the kanban backfill maps it to a column. Six
 | `blocked` | a round gave up here (non-convergent, no verdict, not implementable) | an automated driver, if any | yes, with the reason named |
 | `shipped` | the PR is open; the status flip is part of the release commit | `/cohorte-ship` | no |
 
-**`in-progress` and `blocked` are for external drivers.** No shipped command writes them: the
-built-in autonomous driver (`/cohorte-loop`) was retired in 2.2.0, and the human-driven cycle moves
-`frozen` → `in-review` → `shipped`. They stay valid states because specs in existing repos carry
-them, and because anything automating the cycle from outside needs somewhere to record "a round is
-under way" and "a round gave up". Every reader still routes on them; nothing produces them.
+**`in-progress` and `blocked` are driver states.** No conversational command writes them — the
+human-driven cycle moves `frozen` → `in-review` → `shipped`. Their producer is the **loop
+workflow** (`core/workflows/loop.js`, `/cohorte-loop` — the successor of the 2.2.0-retired
+conversational driver): it stamps `in-progress` at each round, `in-review` when a run ends at
+zero blocking findings, and `blocked` when a round gives up (non-convergent, unreviewed
+surfaces, dead implementers, a contract-change finding), with the reason in
+`specs/reports/<id>.loop.json`. External drivers may write them too. Every reader routes on
+them either way, and a stamp on a spec with no front-matter stays a silent no-op — no driver
+dies over a status line.
 
 **`kind` — feature (default) or `patch`.** Orthogonal to `status`, and the only other front-matter
 field commands route on. `/cohorte-patch` freezes `specs/patch-<slug>.md` with `kind: patch` from
@@ -348,11 +357,14 @@ project has *decided*. Without somewhere for those, every `/cohorte-spec` re-dis
 `specs/_decisions.md` (from `core/templates/decisions.template.md`) is that place, deliberately small:
 
 - **Append-only, one line per decision, ≤ ~160 chars:**
-  `- <YYYY-MM-DD> · <area> · <decision> — because <reason> · <feature_id>`. Reversal never edits a line:
+  `- <YYYY-MM-DD> · <area> · <decision> — because <reason> · <origin>`, where `<origin>` is the
+  `feature_id` that decided it — or the originating command (`retro`) when no single feature owns
+  it. Reversal never edits a line:
   append a superseding one (`· supersedes <date> <area>`) and move the old one to `## Superseded`. When
   `## Live` passes ~100 lines, sweep the superseded ones down.
 - **Written by** `/cohorte-spec` at freeze (the decisions that outlive the feature — typically 0–3 lines, and
-  zero is a normal outcome) and `/cohorte-build` §1.5 when it adds or splits a surface.
+  zero is a normal outcome), `/cohorte-build` §1.5 when it adds or splits a surface, and
+  `/cohorte-retro` §4 when the human ratifies a convention rule (one line per adopted rule).
 - **Read by the deciding stages only** — `/cohorte-brainstorm` (so the panel argues about the idea, not about
   settled ground), `/cohorte-spec` (so a new spec does not silently un-decide something), `/cohorte-audit` (standing
   decisions are part of the rulebook it audits against).
@@ -525,16 +537,21 @@ itself changes in ways `/cohorte-build` §1.5 can't auto-grow (e.g. package mana
 
 ## Workflows — deterministic multi-agent runs (opt-in)
 
-Three phases have a **workflow variant** — a deterministic orchestration script the Claude Code
-Workflow runtime executes instead of the lead reasoning out the fan-out turn by turn:
-`<core>/workflows/review.js`, `audit.js`, `refactor.js` (installed to `<core>/workflows/` bundled or
-`<core>/workflows/` global). The conversational commands (`/cohorte-review`, `/cohorte-audit`, `/cohorte-refactor`)
+Four scripts run under the Claude Code Workflow runtime instead of the lead reasoning out the
+fan-out turn by turn: `<core>/workflows/review.js`, `audit.js`, `refactor.js` — each the
+**workflow variant** of its same-named conversational command — plus `loop.js`
+(`/cohorte-loop`), which has **no conversational form at all** (below). For the variant pairs,
+the conversational commands (`/cohorte-review`, `/cohorte-audit`, `/cohorte-refactor`)
 **remain the default path and the fallback** — a workflow runs only when the human explicitly asks
 for it ("run the review workflow"), and requires Claude Code ≥ **2.1.154** with workflows
 enabled.
 `/cohorte-doctor` reports which path a session will take. The interactive commands (`/cohorte-init-pipeline`,
 `/cohorte-brainstorm`, `/cohorte-spec`) and the dispatch-only ones (`/cohorte-build`, `/cohorte-ship`) have **no** workflow variant on
 purpose: they're interviews or already a single parallel dispatch — a script adds nothing.
+`/cohorte-loop` does not change that: it **consumes** `/cohorte-build`'s outputs (the frozen
+spec, `readiness.json`, the lead-authored contract, `build.json`) — it is not a build variant,
+and adding one would put the lead-only steps (§1.5 reconcile, §2 contract authoring) inside a
+script that cannot ask.
 
 Shared design, all four scripts:
 
@@ -564,10 +581,24 @@ Shared design, all four scripts:
 - **`refactor.js`** — big domains only (it skips domains with a handful of open items — the
   conversational `/cohorte-refactor` is cheaper there): `shared` first and alone, then the other domains'
   implementers in parallel, each verified per-domain.
+- **`loop.js`** (`/cohorte-loop`) — build → review → [fix → review]* for ONE feature, unattended and
+  resumable. Preconditions it verifies and refuses to work around: frozen/`in-review` spec, a fresh
+  `readiness.json` at `READY`/`RESERVATIONS`, the contract on disk, every readiness surface owned by
+  the profile. Round exits, in order: child abort relayed → `unreviewed` non-empty → `blocking == 0`
+  ⇒ ship → same blocking-item identity two consecutive rounds ⇒ treading water → `maxRounds`
+  (default 5). A blocking finding on the contract file aborts (`contract-change` — lead-only, per
+  `/cohorte-fix` §1). It calls the review **workflow** per round and reads the same `verdict.json`
+  contract the conversational `/cohorte-review` §3 writes; it stamps `in-progress` while running,
+  `in-review` on ship, `blocked` on a give-up. **Workflow-only, no command file, ever**
+  (`validate-core.mjs` pins it): if the runtime is unavailable it refuses explicitly rather than
+  degrading to a lead re-reasoning the fan-out every round at session-model prices.
 - **No input mid-run.** A workflow runs to completion without questions; anything interactive
   (contract changes, human decisions) belongs to the conversational path. The gate hook still
   fires on workflow subagents (see
-  §Preflight) — in unattended runs its asks become denies.
+  §Preflight) — in unattended runs its asks become denies. Know what that means for edits:
+  workflow subagents run in **`acceptEdits` whatever the session mode**, so for the length of a
+  run — and `loop.js` runs long, unattended stretches — `hooks/gate.py` is the only brake on
+  what agents write. That is stated here rather than discovered.
 - **Permissions:** `/cohorte-init-pipeline` and `/cohorte-update-pipeline` extend the generated `settings.json`
   `allow` list with what workflow agents need (the quiet commands, the shipped
   `pipeline/scripts/*.sh`, read-only git incl. `git rev-parse`, and the retrieval provider's MCP

package/profile/cohorte.config.template.yaml

@@ -1,7 +1,7 @@
 # ~/.claude/cohorte.config.yaml — GLOBAL, user-scoped config for the Cohorte
 # pipeline capabilities. One machine, every project. NOT tied to any project's PIPELINE.md.
 #
-# Seeded once by the installer (npx cohorte install) and never clobbered on update. Wired
+# Seeded once by the installer (cohorte install) and never clobbered on update. Wired
 # interactively by /cohorte-init-pipeline (new project) and /cohorte-update-pipeline (existing project) —
 # you should never need to hand-edit it.
 #

package/scripts/kanban-move.sh

@@ -44,11 +44,17 @@ else
 fi
 pr=""; title=""; project=""; profile="PIPELINE.md"
 while [ $# -gt 0 ]; do
+  # A flag with no value must exit 2 (usage) like every other usage error — a bare
+  # `shift 2` fails under set -e with exit 1, outside the 0/2/3 contract callers branch on.
   case "$1" in
-    --pr)      pr="${2-}";      shift 2 ;;
-    --title)   title="${2-}";   shift 2 ;;
-    --project) project="${2-}"; shift 2 ;;
-    --profile) profile="${2-}"; shift 2 ;;
+    --pr|--title|--project|--profile)
+      [ $# -ge 2 ] || { echo "error: $1 needs a value" >&2; echo "$usage" >&2; exit 2; } ;;
+  esac
+  case "$1" in
+    --pr)      pr="$2";      shift 2 ;;
+    --title)   title="$2";   shift 2 ;;
+    --project) project="$2"; shift 2 ;;
+    --profile) profile="$2"; shift 2 ;;
     *) echo "error: unknown flag $1" >&2; echo "$usage" >&2; exit 2 ;;
   esac
 done
@@ -246,7 +252,11 @@ ID="$id" COL="$col" PR="$pr" TITLE="${title:-$id}" awk '
     pr = ENVIRON["PR"]; title = ENVIRON["TITLE"]
     n = 0; card = ""; found = 0; colseen = 0; sn = 0; lastblank = 0
   }
-  { lines[++n] = $0 }
+  # Strip CR at capture: a CRLF board (Windows-synced vault) otherwise fails the
+  # `h == col` heading compare and exits 3 on a column that exists — while the
+  # config parser in this same script already strips \r. Emitting LF-only is fine
+  # (Obsidian reads both).
+  { sub(/\r$/, ""); lines[++n] = $0 }
   END {
     # pass 1: extract the FIRST card block tagged #id; mark every block for removal
     for (i = 1; i <= n; i++) {

package/scripts/new-feature.sh.template

@@ -53,8 +53,15 @@ web_port=$((__WEB_PORT_BASE__ + slot))
 
 echo "→ feature '$id' → slot $slot   (db $db_name · api :$api_port · web :$web_port)"
 echo "→ creating worktree $worktree_dir on $branch (off __DEFAULT_BRANCH__)"
+# Branch off the REMOTE ref when it exists: `git fetch origin <branch>` updates
+# origin/<branch>, never the local one, so branching off the local ref silently
+# started every feature from wherever the local default branch last sat.
 git -C "$repo_root" fetch --quiet origin __DEFAULT_BRANCH__ || true
-git -C "$repo_root" worktree add -b "$branch" "$worktree_dir" __DEFAULT_BRANCH__
+base=__DEFAULT_BRANCH__
+if git -C "$repo_root" rev-parse --verify -q "origin/__DEFAULT_BRANCH__" >/dev/null 2>&1; then
+  base="origin/__DEFAULT_BRANCH__"
+fi
+git -C "$repo_root" worktree add -b "$branch" "$worktree_dir" "$base"
 
 # Replace (or append) KEY=VALUE in a dotenv file — one definitive line per key.
 set_env() {

package/scripts/preflight.sh

@@ -43,6 +43,9 @@ for cmd in "$@"; do
     exit 1
   fi
 done
+# All-empty arguments verified nothing — stamping green here would gate reviews on a
+# check that never ran. Same failure as zero arguments, and the same exit.
+[ "$n" -gt 0 ] || { echo "preflight: every command argument was empty — nothing was verified" >&2; exit 2; }
 
 # Stamp for the gate.py phase gate: epoch + HEAD sha of the checkout we verified.
 # The stamp MUST land where gate.py reads it: <main checkout>/.claude. CLAUDE_PROJECT_DIR
@@ -75,8 +78,13 @@ if [ -n "$tmpidx" ]; then
     # same window or they compute different trees for the same content. `date -d` is GNU and
     # `date -v` is BSD — try both, and if neither exists just skip the touch (the digest is
     # still correct for anything not edited in the last few seconds).
-    stamp=$(date -u -d '5 seconds ago' +%Y%m%d%H%M.%S 2>/dev/null \
-         || date -u -v-5S +%Y%m%d%H%M.%S 2>/dev/null || echo "")
+    # LOCAL time on purpose: `touch -t` interprets its stamp as local time, so a
+    # UTC-formatted stamp future-dates the index anywhere west of UTC — which makes
+    # git trust the stat cache of files edited THIS second, the exact race the
+    # backdate exists to prevent. (gate.py's side uses os.utime with an epoch, which
+    # has no timezone to get wrong.)
+    stamp=$(date -d '5 seconds ago' +%Y%m%d%H%M.%S 2>/dev/null \
+         || date -v-5S +%Y%m%d%H%M.%S 2>/dev/null || echo "")
     [ -n "$stamp" ] && touch -t "$stamp" "$tmpidx" 2>/dev/null || true
   else
     rm -f "$tmpidx"                       # a 0-byte index is a corrupt index

package/scripts/remove-feature.sh.template

@@ -28,7 +28,9 @@ registry="$repo_root/.worktrees/slots.tsv"
 branch="__BRANCH_PREFIX__${id}"
 
 echo "→ removing worktree $worktree_dir"
-if git -C "$repo_root" worktree list | grep -q "$worktree_dir"; then
+# Porcelain + fixed-string + whole-line: the human-readable list matched any worktree
+# whose path merely CONTAINS this one (auth vs auth-2fa), and dots in the path were regex.
+if git -C "$repo_root" worktree list --porcelain | grep -Fxq "worktree $worktree_dir"; then
   git -C "$repo_root" worktree remove "$worktree_dir" "${@:3}"
 else
   echo "   (no such worktree registered — skipping)"