cohorte 1.3.0 → 1.3.2

package/CHANGELOG.md

@@ -3,6 +3,41 @@
 Entries are shown by `/update-pipeline` ("What's new") after a core refresh. Keep them short,
 user-facing, most recent first. One `## <version> — <YYYY-MM-DD>` section per release.
 
+## 1.3.2 — 2026-07-30
+
+> **Re-run `npx cohorte@latest update --global` (or `update`).** This release repairs the gate
+> hook registration in place — updating is what applies it.
+
+- **1.3.0's preflight phase gate never fired on any install.** `gate.py` gates review/smoke
+  dispatches on `tool_name == "Task"`, but all three installers registered the hook with
+  `matcher: "Bash"` — a Task call never reached it. The `preflight` block in `gate-config.json`
+  and `gate.preflight` in `PIPELINE.md` were both dead config. The matcher is now `Bash|Task`.
+- **Re-installing duplicated the hook, every time.** The "already registered?" test was
+  `command.endswith("gate.py")`, which is false for the Windows form `py "C:\…\gate.py"` because
+  of the trailing quote — so `install.sh` and `bin/cli.js` appended another copy on each run, and
+  `gate.py` ran once per copy on every Bash call (four copies seen in the wild). Registration is
+  now a **reconcile**: it drops every existing `gate.py` entry and writes exactly one. Idempotent,
+  it collapses the duplicates you already have, and it upgrades the stale matcher — an
+  append-if-absent would have found the stale entry and skipped, pinning the bug forever.
+  Unrelated hooks and every other settings key are untouched.
+- **`npx cohorte update` never touched the hook at all**, so neither fix above could have reached
+  you through the command you actually run to get fixes — only a full re-install rewrote it.
+  `install.sh` and `install.ps1` always registered on update; this port had drifted (the same
+  class of drift as 1.2.4 and 1.2.6). It now registers on both paths.
+- CI installs **twice** before asserting the hook, via a new `scripts/assert-gate-hook.mjs`:
+  exactly one registration, matcher covering both Bash and Task. A single install could never
+  surface the duplication — which is precisely why CI stayed green while it shipped.
+
+## 1.3.1 — 2026-07-30
+
+- **`/cycle <feature_id> [max_rounds]`** — a launcher command for the full dev-cycle workflow,
+  so you don't have to phrase the request in prose. It resolves `workflows/cycle.js`
+  (bundled or global), checks the runtime is available (missing ⇒ it hands you the
+  conversational `/build` → `/smoke` → `/review` path instead), sanity-checks the spec is
+  frozen, launches the workflow in the background, then relays the verdict: outcome,
+  contract re-authorings to eyeball, the `questions` array verbatim, and the next step
+  (`/ship` on SHIP-READY, rerun `/cycle` or `/fix` otherwise). Kanban card moves included.
+
 ## 1.3.0 — 2026-07-30
 
 **Token economy — immediate wins, no workflow needed:**

package/README.md

@@ -7,6 +7,9 @@
 [![Publish to npm](https://github.com/TheBidouilleAgency/cohorte/actions/workflows/publish.yml/badge.svg)](https://github.com/TheBidouilleAgency/cohorte/actions/workflows/publish.yml)
 [![node >=18](https://img.shields.io/node/v/cohorte?logo=node.js&logoColor=white)](https://nodejs.org)
 [![license: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue)](LICENSE)
+[![docs](https://img.shields.io/badge/docs-thebidouilleagency.github.io%2Fcohorte-6f42c1)](https://thebidouilleagency.github.io/cohorte/)
+
+**[📖 Full documentation](https://thebidouilleagency.github.io/cohorte/)** — guides (feature cycle, workflows, token economy, parallel features) + complete reference (commands, agents, profile, gate, scripts).
 
 </div>
 
@@ -214,6 +217,7 @@ it in `.claude/pipeline/VERSION` and bundled repos in their committed `pipeline.
 | `/brainstorm`        | Interactive persona panel that pressure-tests a feature idea.                         |
 | `/spec`              | Freeze the feature spec + contract into `specs/<id>.md` (UI features also get a standalone design brief at `specs/design/<id>.md`). Also applies review returns. |
 | `/build <id>`        | Lead authors the contract, then dispatches one implementer per surface in parallel.   |
+| `/cycle <id>`        | Launch the full dev-cycle **workflow** on a frozen spec: build → smoke ∥ review → fix until zero findings; deferred questions in the output. Needs workflows enabled (falls back to the conversational path). |
 | `/smoke <id>`        | Run the feature for real: infra up, contract endpoints, UI flows, design conformance. |
 | `/review <id>`       | Read-only review agents (one per touched surface, parallel) audit the diff vs the spec. |
 | `/fix <id>`          | Apply a review/smoke report: remediation into the spec, re-dispatch only the surfaces with findings. |

package/bin/cli.js

@@ -21,6 +21,13 @@ const VERSION = pkg.version;
 
 const REPO_URL = 'https://github.com/TheBidouilleAgency/cohorte';
 
+// PreToolUse matcher for the gate hook. 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. Keep in lockstep with install.sh and install.ps1.
+const GATE_MATCHER = 'Bash|Task';
+
 function usage(code) {
   console.log(`cohorte v${VERSION}
 
@@ -274,19 +281,24 @@ function registerGlobalHook() {
   } catch { /* absent or invalid → start fresh */ }
   if (!data.hooks || typeof data.hooks !== 'object') data.hooks = {};
   if (!Array.isArray(data.hooks.PreToolUse)) data.hooks.PreToolUse = [];
-  const pre = data.hooks.PreToolUse;
-  const hooks = [
-    { file: path.join(dest, 'hooks', 'gate.py'), matcher: 'Bash' },
-  ];
-  for (const { file, matcher } of hooks) {
-    const base = path.basename(file);
-    const already = pre.some(entry => (entry.hooks || []).some(
-      h => typeof h.command === 'string' && h.command.trim().endsWith(base)));
-    if (!already) {
-      const cmd = process.platform === 'win32' ? `${python} "${file}"` : `${python} ${file}`;
-      pre.push({ matcher, hooks: [{ type: 'command', command: cmd }] });
-    }
-  }
+
+  const file = path.join(dest, 'hooks', 'gate.py');
+  const base = path.basename(file);
+  // Trailing-quote tolerant: the Windows form is `py "C:\...\gate.py"`, and a
+  // bare .endsWith() missed it — which is how repeat `npx cohorte install`
+  // runs accumulated a duplicate registration every time (gate.py then ran
+  // once per copy on every Bash call).
+  const isGate = entry => (entry.hooks || []).some(
+    h => typeof h.command === 'string' && h.command.trim().replace(/"+$/, '').endsWith(base));
+  const cmd = process.platform === 'win32' ? `${python} "${file}"` : `${python} ${file}`;
+
+  // 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.
+  data.hooks.PreToolUse = data.hooks.PreToolUse.filter(e => !isGate(e));
+  data.hooks.PreToolUse.push({ matcher: GATE_MATCHER, hooks: [{ type: 'command', command: cmd }] });
+
   fs.writeFileSync(settingsPath, JSON.stringify(data, null, 2) + '\n');
   return 'ok';
 }
@@ -311,7 +323,13 @@ if (scope === 'global') {
     : `→ updating pipeline core GLOBALLY in ${dest} (keeping global settings.json)`);
   copyFixedAgents();
   copyCore();
-  const hookState = mode === 'install' ? registerGlobalHook() : 'unchanged';
+  // Register on UPDATE too — install.sh and install.ps1 always have, and this
+  // port skipping it is why a duplicated or stale-matcher registration could
+  // never be repaired by `npx cohorte update`: the only route that rewrites it
+  // was a full re-install, which is not what anyone runs to get a fix. Safe to
+  // run every time — registration reconciles only gate.py entries and leaves
+  // every other hook and settings key untouched.
+  const hookState = registerGlobalHook();
   await seedConfig();
   console.log(`
 ✓ pipeline core installed globally into ${dest}  (version ${VERSION})

package/core/commands/cycle.md

@@ -0,0 +1,54 @@
+---
+model: sonnet
+description: Launch the full dev-cycle workflow (contract → build → smoke ∥ review → fix, until zero findings) for a frozen spec; relay its verdict + deferred questions.
+argument-hint: <feature_id> [max_rounds]
+---
+
+You are the **lead**. Launch the full dev-cycle **workflow** for feature **$ARGUMENTS** — the
+deterministic script does the orchestration (SCHEMA.md §Workflows, `cycle.js`); your job is only to
+start it and relay its result. Do NOT run the phases yourself here — that's the conversational path
+(`/build` → `/smoke` → `/review` → `/fix`), which remains the fallback below.
+
+> **Kanban** (SCHEMA.md §Kanban): move card `#<feature_id>` → **Building** at launch. No-op silently
+> if no board.
+
+## 1. Resolve & check (fail fast, before spending anything)
+
+- Parse `$ARGUMENTS`: the first token is `<feature_id>`, an optional second numeric token is
+  `<max_rounds>` (the workflow defaults to 5).
+- Resolve the script: `.claude/workflows/cycle.js` if it exists, else `~/.claude/workflows/cycle.js`
+  (`test -f`). **Missing both** ⇒ the core predates 1.3.0 or is half-copied: tell the human to run
+  `/update-pipeline`, and stop.
+- **Workflow runtime available?** If the `Workflow` tool is not in your toolset (Claude Code
+  < 2.1.154 or workflows disabled), say so and hand over the conversational path instead:
+  `/build <feature_id>` → `/smoke` → `/review` → `/fix` — same phases, interactive. Stop.
+- Quick spec sanity (the workflow re-checks properly — this just saves a doomed launch):
+  `grep '^status:' specs/<feature_id>.md` must say `frozen` or `in-review`; otherwise tell the human
+  to run `/spec` first, and stop.
+
+## 2. Launch
+
+Call the `Workflow` tool: `scriptPath: <resolved cycle.js path>`,
+`args: {"feature": "<feature_id>", "maxRounds": <max_rounds, omit if not given>}`.
+It runs in the background — tell the human it's off and what it will do (build, then smoke ∥ review
+→ fix rounds until zero findings + PASS; no questions mid-run), and that `/workflows` shows live
+progress. Then END YOUR TURN — never poll, never sleep; the completion notification re-wakes you.
+
+## 3. Relay the result (when the task notification arrives)
+
+The workflow returns only a verdict object — the bulk is already on disk
+(`specs/reports/<feature_id>.md`, spec `## Remediation`). Print, without re-reading any of it into
+context:
+
+- `outcome` · rounds used · review verdict · smoke result.
+- `contractChanges` if any — flag them explicitly: the loop re-authored the frozen contract
+  lead-style; the human should eyeball those hunks in the diff.
+- **The `questions` array, verbatim** — this is the human's inbox from the run (empty when the spec
+  pre-answered everything). Each one is a decision to make, usually by sharpening the spec.
+- The `next` line: **SHIP-READY** ⇒ `/ship <feature_id>` (DoD ticked + freshness stamped — ship is a
+  straight shot, its human confirmation stays). **STOPPED** ⇒ answer the questions, then rerun
+  `/cycle <feature_id>` (it picks up from the spec's Remediation) or finish conversationally with
+  `/fix <feature_id>` + `/review <feature_id>`.
+- **Kanban:** outcome SHIP-READY ⇒ move card → **Review** (the cycle's last verdict is a review);
+  otherwise → **Fix**. No-op silently if no board.
+- **Recommend a `/clear`** — everything the next command needs is on disk.

package/core/commands/doctor.md

@@ -37,7 +37,7 @@ fix only with the human's go-ahead (or hand them the command).
    (`review.md`, `release.md`, `smoke.md`, `profile-reader.md` — repo or `~/.claude/agents/`) must
    each carry their `model:` line too (sonnet/haiku/sonnet/haiku). **Command pins:** every mechanical command file
    (`build`, `review`, `fix`, `smoke`, `ship`, `audit`, `refactor`, `doctor`, `align-ds`,
-   `update-pipeline` — in `.claude/commands/` or `~/.claude/commands/`) carries `model: sonnet` in
+   `update-pipeline`, `cycle` — in `.claude/commands/` or `~/.claude/commands/`) carries `model: sonnet` in
    its frontmatter — ⚠️ if missing (the lead's orchestration turn then bills at the session model,
    e.g. Opus/Fable). `brainstorm`, `spec`, and `init-pipeline` are intentionally unpinned
    (interactive — they inherit the session model).

package/install.ps1

@@ -251,23 +251,31 @@ try {
             $data.hooks | Add-Member -NotePropertyName PreToolUse -NotePropertyValue @()
         }
 
-        $already = $false
+        # 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 = @()
         foreach ($entry in @($data.hooks.PreToolUse)) {
+            $isGate = $false
             foreach ($h in @($entry.hooks)) {
                 if ($h -and $h.command -and "$($h.command)".Trim().TrimEnd('"').EndsWith('gate.py')) {
-                    $already = $true
+                    $isGate = $true
                 }
             }
+            if (-not $isGate) { $kept += $entry }
         }
-        if (-not $already) {
-            $data.hooks.PreToolUse = @($data.hooks.PreToolUse) + [pscustomobject]@{
-                matcher = 'Bash'
-                hooks   = @([pscustomobject]@{ type = 'command'; command = $cmd })
-            }
-            Write-JsonFile $settingsPath $data
-            return 'ok'
+        # 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. Keep in lockstep with install.sh
+        # and bin/cli.js.
+        $data.hooks.PreToolUse = @($kept) + [pscustomobject]@{
+            matcher = 'Bash|Task'
+            hooks   = @([pscustomobject]@{ type = 'command'; command = $cmd })
         }
-        return 'present'
+        Write-JsonFile $settingsPath $data
+        return 'ok'
     }
 
     # Bump only the core_version in a repo's committed .claude/pipeline.json (bundled mode).

package/install.sh

@@ -185,8 +185,24 @@ register_global_hook() {
   python3 - "$dest/settings.json" "$dest/hooks/gate.py" <<'PY'
 import json, sys
 settings, gate = sys.argv[1], sys.argv[2]
-# (hook path, PreToolUse matcher)
-hooks = [(gate, "Bash")]
+# 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)
@@ -195,15 +211,14 @@ try:
 except Exception:
     data = {}
 pre = data.setdefault("hooks", {}).setdefault("PreToolUse", [])
-for path, matcher in hooks:
-    base = path.rsplit("/", 1)[-1]
-    already = any(
-        h.get("command", "").strip().endswith(base)
-        for entry in pre for h in entry.get("hooks", [])
-    )
-    if not already:
-        pre.append({"matcher": matcher,
-                    "hooks": [{"type": "command", "command": "python3 " + path}]})
+# 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")

package/package.json

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

package/profile/SCHEMA.md

@@ -318,7 +318,9 @@ Workflow runtime executes instead of the lead reasoning out the fan-out turn by
 `<core>/workflows/review.js`, `audit.js`, `refactor.js` (installed to `.claude/workflows/` bundled or
 `~/.claude/workflows/` global). The conversational commands (`/review`, `/audit`, `/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.
+for it ("run the review workflow", or via the `/cycle <id>` launcher command, which resolves
+`cycle.js` and invokes the runtime for them), and requires Claude Code ≥ **2.1.154** with workflows
+enabled.
 `/doctor` reports which path a session will take. The interactive commands (`/init-pipeline`,
 `/brainstorm`, `/spec`) and the dispatch-only ones (`/build`, `/ship`) have **no** workflow variant on
 purpose: they're interviews or already a single parallel dispatch — a script adds nothing.

package/scripts/assert-gate-hook.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+//
+// assert-gate-hook.mjs — post-install assertion on a settings.json's gate hook.
+//
+//   node scripts/assert-gate-hook.mjs <path-to-settings.json>
+//
+// Two invariants, both regressions that shipped to users:
+//
+//  1. EXACTLY ONE registration. Until 1.3.2 the installers appended
+//     if-absent, and their "already registered?" test was a bare
+//     `.endsWith("gate.py")` — false for the Windows form `py "C:\...\gate.py"`
+//     because of the trailing quote. Every re-install appended another copy
+//     (four seen in the wild), so gate.py ran once per copy on every Bash call.
+//     CI installed only once, so it never noticed. Callers must install TWICE
+//     before running this.
+//
+//  2. THE MATCHER COVERS Task. gate.py's preflight phase gate dispatches on
+//     tool_name === "Task" (the `preflight` block in a repo's
+//     gate-config.json). A Bash-only matcher never delivers a Task call to the
+//     hook, so the gate was dead code from 1.3.0 (which introduced it) to 1.3.1.
+//
+// Exits non-zero with a specific message on failure.
+
+import fs from 'node:fs';
+
+const settingsPath = process.argv[2];
+if (!settingsPath) {
+  console.error('usage: assert-gate-hook.mjs <path-to-settings.json>');
+  process.exit(2);
+}
+
+let data;
+try {
+  data = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+} catch (err) {
+  console.error(`assert-gate-hook: cannot read ${settingsPath}: ${err.message}`);
+  process.exit(1);
+}
+
+const pre = (data.hooks || {}).PreToolUse || [];
+const isGate = (entry) =>
+  (entry.hooks || []).some(
+    (h) => typeof h.command === 'string' && h.command.trim().replace(/"+$/, '').endsWith('gate.py')
+  );
+const gate = pre.filter(isGate);
+
+if (gate.length !== 1) {
+  console.error(
+    `assert-gate-hook: expected exactly 1 gate.py registration, found ${gate.length}.\n` +
+      (gate.length > 1
+        ? '  Registration is not idempotent — a re-install duplicated the hook.'
+        : '  The installer did not register the gate hook.') +
+      `\n  PreToolUse: ${JSON.stringify(pre, null, 2)}`
+  );
+  process.exit(1);
+}
+
+const matcher = gate[0].matcher || '';
+if (!/\bTask\b/.test(matcher)) {
+  console.error(
+    `assert-gate-hook: gate matcher must cover Task, got ${JSON.stringify(matcher)}.\n` +
+      "  gate.py's preflight phase gate keys off tool_name === 'Task'; without it\n" +
+      '  the `preflight` block in gate-config.json is dead code.'
+  );
+  process.exit(1);
+}
+if (!/\bBash\b/.test(matcher)) {
+  console.error(
+    `assert-gate-hook: gate matcher must cover Bash, got ${JSON.stringify(matcher)}.\n` +
+      '  The deny/ask command gating runs on Bash tool calls.'
+  );
+  process.exit(1);
+}
+
+console.log(`gate hook ok — 1 registration, matcher ${JSON.stringify(matcher)}`);

package/scripts/validate-core.mjs

@@ -23,7 +23,7 @@ const frontmatter = (text) => {
 // orchestration turn silently bills at the session model — Opus/Fable).
 // Interactive commands must stay unpinned (they inherit on purpose).
 const PINNED = ["build", "review", "fix", "smoke", "ship", "audit",
-  "refactor", "doctor", "align-ds", "update-pipeline"];
+  "refactor", "doctor", "align-ds", "update-pipeline", "cycle"];
 const UNPINNED = ["brainstorm", "spec", "init-pipeline"];
 
 for (const f of readdirSync(join(root, "core/commands"))) {