cohorte 1.3.1 → 1.3.3

package/CHANGELOG.md

@@ -3,6 +3,60 @@
 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.3 — 2026-07-30
+
+> **Re-run `npx cohorte@latest update --global` (or `update`)** — the gate fixes only apply once
+> the installed `hooks/gate.py` is refreshed.
+
+- **The cycle workflow could exit SHIP-READY with open findings.** A round with only HIGH/MEDIUM
+  findings scored `SHIP`, broke the loop, ticked the DoD and stamped the freshness gate — making
+  `/ship` a straight shot over unfixed findings, against the workflow's own "zero open findings"
+  contract. The exit condition is now literally zero open findings + a smoke PASS.
+- **Dead implementers went undetected in the cycle workflow.** `agent()` returns `null` when a
+  subagent dies, but the build fan-out wrapped every result in a truthy object before the check —
+  so the "implementer(s) died" question never fired and build telemetry always said `ok`.
+- **`gate.py` gated worktree commands as if they ran on the default branch.** Branch and HEAD were
+  resolved in `CLAUDE_PROJECT_DIR` (the main checkout, usually on `main`) instead of where the
+  command actually runs — so in a feature worktree, every `ask_on_default_branch` pattern
+  prompted, and the preflight HEAD-moved check compared against the wrong checkout. Git state now
+  resolves at the hook payload's `cwd`.
+- **The preflight phase gate hung headless runs.** The bypassPermissions "nobody can answer an
+  ask ⇒ deny" escalation only covered Bash patterns; a review/smoke Task dispatch with a stale
+  stamp still emitted an unanswerable `ask`. The phase gate now escalates the same way.
+- **`/init-pipeline` bundled installs registered the gate with the dead `Bash`-only matcher** —
+  the exact bug 1.3.2 fixed in the installers lived on in the template — and never dropped an
+  existing registration, so a bundled repo later switched to global ran the gate twice per
+  command. The template now mandates `Bash|Task` and a reconcile.
+- Smaller cycle-workflow fixes: smoke telemetry reports the real failure count (was always 0 —
+  it filtered on a `kind` value that doesn't exist); a run whose last round ends on a red
+  preflight now flags that the reported findings are from the previous round; a malformed
+  preflight stamp says "unreadable" instead of "not found".
+
+## 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,

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>
 

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/hooks/gate.py

@@ -48,9 +48,12 @@ SPLIT = re.compile(r"&&|\|\||[;|\n]")
 WS = re.compile(r"\s+")
 
 
+def project_root() -> str:
+    return os.environ.get("CLAUDE_PROJECT_DIR", ".")
+
+
 def load_config() -> dict:
-    root = os.environ.get("CLAUDE_PROJECT_DIR", ".")
-    path = os.path.join(root, ".claude", "gate-config.json")
+    path = os.path.join(project_root(), ".claude", "gate-config.json")
     empty = {"deny": [], "ask": [], "ask_on_default_branch": [], "default_branch": "main",
              "preflight": {}}
     try:
@@ -76,13 +79,19 @@ def norm(s: str) -> str:
     return WS.sub(" ", s.strip())
 
 
-def current_branch():
-    """The checked-out branch of CLAUDE_PROJECT_DIR, or None (not a repo / detached / git absent)."""
-    root = os.environ.get("CLAUDE_PROJECT_DIR", ".")
+def session_cwd(payload: dict) -> str:
+    """Where the gated command actually runs. A feature worktree is its own
+    checkout — resolving git state in CLAUDE_PROJECT_DIR (the main checkout)
+    would gate every worktree command as if it ran on the default branch."""
+    return payload.get("cwd") or project_root()
+
+
+def current_branch(cwd: str):
+    """The checked-out branch at `cwd`, or None (not a repo / detached / git absent)."""
     try:
         out = subprocess.run(
             ["git", "rev-parse", "--abbrev-ref", "HEAD"],
-            cwd=root, capture_output=True, text=True, timeout=3,
+            cwd=cwd, capture_output=True, text=True, timeout=3,
         )
         if out.returncode == 0:
             return out.stdout.strip() or None
@@ -91,13 +100,12 @@ def current_branch():
     return None
 
 
-def current_head():
-    """HEAD sha of CLAUDE_PROJECT_DIR, or None."""
-    root = os.environ.get("CLAUDE_PROJECT_DIR", ".")
+def current_head(cwd: str):
+    """HEAD sha at `cwd`, or None."""
     try:
         out = subprocess.run(
             ["git", "rev-parse", "HEAD"],
-            cwd=root, capture_output=True, text=True, timeout=3,
+            cwd=cwd, capture_output=True, text=True, timeout=3,
         )
         if out.returncode == 0:
             return out.stdout.strip() or None
@@ -116,29 +124,37 @@ def check_preflight(payload: dict, cfg: dict) -> int:
     if subagent not in agents:
         return 0
 
-    root = os.environ.get("CLAUDE_PROJECT_DIR", ".")
-    stamp = os.path.join(root, ".claude", "preflight.ok")
+    stamp = os.path.join(project_root(), ".claude", "preflight.ok")
     why = None
     try:
         with open(stamp, "r", encoding="utf-8") as fh:
-            epoch_s, _, sha = fh.read().strip().partition(" ")
-        age_min = (time.time() - float(epoch_s)) / 60
-        max_age = float(pf.get("max_age_minutes", 30) or 30)
-        if age_min > max_age:
-            why = f"the preflight stamp is {age_min:.0f} min old (max {max_age:.0f})"
-        else:
-            head = current_head()
-            if head and sha not in ("", "none") and head != sha:
-                why = "HEAD moved since the preflight ran"
+            raw = fh.read().strip()
     except Exception:
+        raw = None
         why = "no preflight stamp found"
+    if raw is not None:
+        try:
+            epoch_s, _, sha = raw.partition(" ")
+            age_min = (time.time() - float(epoch_s)) / 60
+            max_age = float(pf.get("max_age_minutes", 30) or 30)
+            if age_min > max_age:
+                why = f"the preflight stamp is {age_min:.0f} min old (max {max_age:.0f})"
+            else:
+                head = current_head(session_cwd(payload))
+                if head and sha not in ("", "none") and head != sha:
+                    why = "HEAD moved since the preflight ran"
+        except Exception:
+            why = "the preflight stamp is unreadable (expected `<epoch> <sha>`)"
     if why is None:
         return 0
+    # Same rule as the Bash gate: unattended runs have nobody to answer an "ask".
+    unattended = payload.get("permission_mode") == "bypassPermissions"
     return decide(
-        "ask",
+        "deny" if unattended else "ask",
         f"Phase gate: dispatching `{subagent}` but {why}. Run the deterministic pre-flight first "
         f"(pipeline/scripts/preflight.sh — typecheck + lint + tests) so agents never review red code; "
-        f"or confirm to dispatch anyway (PIPELINE.md gate.preflight).",
+        f"or confirm to dispatch anyway (PIPELINE.md gate.preflight)."
+        + (" (denied outright: unattended run, nobody to confirm)" if unattended else ""),
     )
 
 
@@ -173,7 +189,7 @@ def main() -> int:
     # be conservative and gate. Resolve the branch once, lazily.
     on_default = False
     if branch_gated:
-        branch = current_branch()
+        branch = current_branch(session_cwd(payload))
         on_default = branch is None or branch == default
 
     for raw in SPLIT.split(command):

package/core/templates/steps/init-pipeline/04-write-render.md

@@ -30,8 +30,12 @@
    retrieval provider's MCP tools when wired (e.g. `mcp__serena`). Never allowlist anything matching
    a `gate.ask`/`gate.deny` pattern. Mention the human can widen it later with
    `/fewer-permission-prompts`) + the hooks, **conditioned on the install mode:**
-   - **bundled:** register the PreToolUse `Bash` hook `.claude/hooks/gate.py` and the PostToolUse
-     formatter (detected formatter).
+   - **bundled:** register the PreToolUse hook `.claude/hooks/gate.py` with matcher `Bash|Task`
+     (Task is required — the preflight phase gate keys off Task dispatches; a `Bash`-only matcher
+     leaves it dead) and the PostToolUse formatter (detected formatter). Before adding, drop any
+     existing PreToolUse entry whose command ends in `gate.py` (here AND in `~/.claude/settings.json`
+     if one points at this repo's copy) — exactly one registration must survive, or every gated
+     command prompts twice.
    - **global:** the PreToolUse gate hook is
      already in `~/.claude/settings.json` and reads this repo's `gate-config.json` — do **not** re-register
      it here (double-registration double-prompts). It no-ops where its config is absent, so one

package/core/workflows/cycle.js

@@ -184,7 +184,9 @@ const buildPrompt = s =>
   'your surface): none'
 const handoffs = await parallel(surfaces.map(s => () =>
   agent(buildPrompt(s), { agentType: s.agent, label: `build:${s.key}`, phase: 'Build' })
-    .then(h => ({ key: s.key, handoff: h }))))
+    // agent() resolves to null (never throws) when a subagent dies — wrapping
+    // unconditionally would hide every death from the `dead` check below.
+    .then(h => (h == null ? null : { key: s.key, handoff: h }))))
 const built = handoffs.filter(Boolean)
 const dead = surfaces.filter(s => !built.some(b => b.key === s.key)).map(s => s.key)
 if (dead.length) questions.push(`implementer(s) died during build: ${dead.join(', ')} — inspect and re-run /build if their surface matters`)
@@ -207,8 +209,10 @@ const runPreflight = () => agent(
 
 let verdict = null
 let smokePass = false
+let smokeFails = []      // last round's smoke failures — Close reports the real count
 let open = []            // findings still open, each {severity,file,line,kind,problem,fix,src}
 let rounds = 0
+let preflightRed = false // did the LAST round end on a red preflight (open/verdict then stale)?
 
 // ── Phases 4/5 — bounded verify → fix rounds ────────────────────────────────
 while (rounds < MAX_ROUNDS && (!budget.total || budget.remaining() > 30000)) {
@@ -218,7 +222,8 @@ while (rounds < MAX_ROUNDS && (!budget.total || budget.remaining() > 30000)) {
 
   // 4a. preflight — mechanical red short-circuits straight to a fix round
   const pre = await runPreflight()
-  if (!pre || !pre.pass) {
+  preflightRed = !pre || !pre.pass
+  if (preflightRed) {
     const tail = (pre && pre.tail) || ''
     const hit = new Set(surfaces.filter(s => tail.includes(String(s.path))).map(s => s.key))
     const targets = hit.size ? [...hit] : built.map(b => b.key)
@@ -281,13 +286,15 @@ while (rounds < MAX_ROUNDS && (!budget.total || budget.remaining() > 30000)) {
   ])
 
   smokePass = !!(smoke && smoke.pass)
-  const smokeFails = (smoke && smoke.failures) || []
+  smokeFails = (smoke && smoke.failures) || []
   open = (reviewed || []).filter(Boolean).flatMap(r => r.kept.map(f => ({ ...f, src: r.key })))
   verdict = open.some(f => f.kind === 'security') ? 'BLOCK'
-    : open.some(f => f.severity === 'CRITICAL') ? 'REVISE' : 'SHIP'
+    : open.length ? 'REVISE' : 'SHIP'
   log(`Round ${rounds}: review ${verdict} (${open.length} finding(s)) · smoke ${smokePass ? 'PASS' : `FAIL:${smokeFails.length}`}`)
 
-  if (verdict === 'SHIP' && smokePass) break
+  // The loop's contract is ZERO open findings + PASS — a SHIP verdict alone
+  // (which older revisions granted despite HIGH/MEDIUM leftovers) is not enough.
+  if (!open.length && smokePass) break
   if (rounds >= MAX_ROUNDS) break
 
   // 5. fix round. Contract-impacting findings stay INSIDE the loop: a
@@ -343,6 +350,9 @@ while (rounds < MAX_ROUNDS && (!budget.total || budget.remaining() > 30000)) {
     { agentType: byKey[k].agent, label: `fix:${k}`, phase: 'Fix' })))
 }
 
+if (preflightRed) {
+  questions.push('the last round ended on a RED preflight — the reported verdict/findings are from the previous round and may already be fixed; rerun /review after the mechanical fixes land')
+}
 if (rounds >= MAX_ROUNDS && !(verdict === 'SHIP' && smokePass)) {
   questions.push(`round cap (${MAX_ROUNDS}) reached with ${open.length} finding(s) open — rerun the cycle (maxRounds higher) or continue with /fix ${feature} + /review`)
 }
@@ -376,7 +386,7 @@ await agent(
   `{"ts":"<ISO now>","feature":"${feature}","phase":"cycle","seconds":0,"surfaces":{"rounds":"${rounds}","verdict":"${verdict || 'none'}:${open.length}","smoke":"${smokePass ? 'PASS' : 'FAIL'}"}}\n` +
   '5. Chain the opt-in usage pings (all funnel phases this run executed, 0 seconds each): ' +
   `<core>/pipeline/scripts/telemetry-send.sh build "${feature}" 0 "${built.map(() => 'ok').join(',') || 'error'}" || true; ` +
-  `<core>/pipeline/scripts/telemetry-send.sh smoke "${feature}" 0 "${smokePass ? 'PASS' : 'FAIL:' + open.filter(f => f.kind === 'runtime').length}" || true; ` +
+  `<core>/pipeline/scripts/telemetry-send.sh smoke "${feature}" 0 "${smokePass ? 'PASS' : 'FAIL:' + smokeFails.length}" || true; ` +
   `<core>/pipeline/scripts/telemetry-send.sh review "${feature}" 0 "${verdict || 'none'}:${open.length}" || true\n` +
   'Return the single word: done.',
   { model: 'haiku', label: 'close', effort: 'low' },

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.1",
+  "version": "1.3.3",
   "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/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)}`);