@praxisflux/gates 0.30.0 → 0.31.0

package/README.md

@@ -73,7 +73,8 @@ codes, same failure lines.
 
 ## The contract
 
-Gate names, inputs, and exit codes (0 all pass · 1 any gate failed · 2 usage error) are
+Gate names, inputs, and exit codes (0 all pass · 1 any gate failed — a gate that crashes
+while running counts as failed · 2 usage error) are
 praxisflux's versioned consumer interface, released and semver-bumped like everything else
 (`docs/releasing.md`); each failure line names its fix. You can also invoke the runner
 directly from any praxisflux checkout:

package/codebase-to-course/lib/gate-runner.mjs

@@ -10,6 +10,8 @@
 // A gate that resolves no roots is a no-op (this isn't its kind of project). `check` problems
 // block the stop (exit 2); optional `warn` notices are surfaced on stderr but never block (exit 0)
 // — for freshness reminders and the like that shouldn't refuse to let the model finish.
+// A gate that CRASHES — in resolveRoots or in check — surfaces as a blocking problem naming
+// the gate: a crash swallowed silently would be permanent non-enforcement wearing a green exit.
 // `ctx` is { sessionId, input }: the invoking session's identity (hook input `session_id`,
 // falling back to $CLAUDE_CODE_SESSION_ID) plus the raw hook input — gates that scope state
 // to its owning session (e.g. reorient run records) key off it; every existing gate ignores it.
@@ -43,7 +45,9 @@ export function evaluate(input, gates, { cwd = process.cwd() } = {}) {
   const warnings = [];
   for (const gate of gates) {
     let roots = [];
-    try { roots = gate.resolveRoots(start, ctx) || []; } catch { roots = []; }
+    try { roots = gate.resolveRoots(start, ctx) || []; } catch (e) {
+      problems.push(`[${gate.name || "gate"}] resolveRoots crashed on ${start}: ${e.message}`);
+    }
     for (const root of roots) {
       try { problems.push(...(gate.check(root, ctx) || [])); } catch (e) {
         problems.push(`[${gate.name || "gate"}] crashed on ${root}: ${e.message}`);

package/grounding-wiki/lib/gate-runner.mjs

@@ -10,6 +10,8 @@
 // A gate that resolves no roots is a no-op (this isn't its kind of project). `check` problems
 // block the stop (exit 2); optional `warn` notices are surfaced on stderr but never block (exit 0)
 // — for freshness reminders and the like that shouldn't refuse to let the model finish.
+// A gate that CRASHES — in resolveRoots or in check — surfaces as a blocking problem naming
+// the gate: a crash swallowed silently would be permanent non-enforcement wearing a green exit.
 // `ctx` is { sessionId, input }: the invoking session's identity (hook input `session_id`,
 // falling back to $CLAUDE_CODE_SESSION_ID) plus the raw hook input — gates that scope state
 // to its owning session (e.g. reorient run records) key off it; every existing gate ignores it.
@@ -43,7 +45,9 @@ export function evaluate(input, gates, { cwd = process.cwd() } = {}) {
   const warnings = [];
   for (const gate of gates) {
     let roots = [];
-    try { roots = gate.resolveRoots(start, ctx) || []; } catch { roots = []; }
+    try { roots = gate.resolveRoots(start, ctx) || []; } catch (e) {
+      problems.push(`[${gate.name || "gate"}] resolveRoots crashed on ${start}: ${e.message}`);
+    }
     for (const root of roots) {
       try { problems.push(...(gate.check(root, ctx) || [])); } catch (e) {
         problems.push(`[${gate.name || "gate"}] crashed on ${root}: ${e.message}`);

package/lib/gate-runner.mjs

@@ -10,6 +10,8 @@
 // A gate that resolves no roots is a no-op (this isn't its kind of project). `check` problems
 // block the stop (exit 2); optional `warn` notices are surfaced on stderr but never block (exit 0)
 // — for freshness reminders and the like that shouldn't refuse to let the model finish.
+// A gate that CRASHES — in resolveRoots or in check — surfaces as a blocking problem naming
+// the gate: a crash swallowed silently would be permanent non-enforcement wearing a green exit.
 // `ctx` is { sessionId, input }: the invoking session's identity (hook input `session_id`,
 // falling back to $CLAUDE_CODE_SESSION_ID) plus the raw hook input — gates that scope state
 // to its owning session (e.g. reorient run records) key off it; every existing gate ignores it.
@@ -43,7 +45,9 @@ export function evaluate(input, gates, { cwd = process.cwd() } = {}) {
   const warnings = [];
   for (const gate of gates) {
     let roots = [];
-    try { roots = gate.resolveRoots(start, ctx) || []; } catch { roots = []; }
+    try { roots = gate.resolveRoots(start, ctx) || []; } catch (e) {
+      problems.push(`[${gate.name || "gate"}] resolveRoots crashed on ${start}: ${e.message}`);
+    }
     for (const root of roots) {
       try { problems.push(...(gate.check(root, ctx) || [])); } catch (e) {
         problems.push(`[${gate.name || "gate"}] crashed on ${root}: ${e.message}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisflux/gates",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "praxisflux gate checks as a zero-dependency CLI (spec-bridge, wiki-freshness, course) — status can't exceed proven artifacts",
   "license": "MIT",
   "repository": {

package/scripts/run-gates.mjs

@@ -7,9 +7,10 @@
 //                              [--wiki-dir docs/wiki] [--course-dir docs/course]
 //
 // Gate names, options, and exit codes are praxisflux's versioned consumer contract
-// (docs/consuming-gates.md): exit 0 when every gate passes, 1 when any gate fails, 2 on a
-// usage error (unknown gate, missing --gates). Each failure line names its fix. This same
-// file ships as the @praxisflux/gates npm bin (scripts/build-npm.mjs carves the package).
+// (docs/consuming-gates.md): exit 0 when every gate passes, 1 when any gate fails — including
+// a gate that crashes while running — and 2 on a usage error (unknown gate, missing --gates).
+// Each failure line names its fix. This same file ships as the @praxisflux/gates npm bin
+// (scripts/build-npm.mjs carves the package).
 import { join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import { runAsCli } from "../lib/cli.mjs";
@@ -46,14 +47,29 @@ export const GATES = {
   },
 };
 
-/** Run the named gates against opts.root. Returns [{gate, problems, warnings, ok}].
- *  Throws on an unknown or empty gate list — a misspelled gate must fail the build loudly,
- *  never skip silently. */
-export function runGates(names, opts) {
+/** Validate a requested gate list. Throws on an unknown or empty list — a misspelled gate
+ *  must fail the build loudly, never skip silently. These throws are the ONLY usage errors
+ *  (exit 2); anything that goes wrong after validation is a gate result, not usage. */
+export function validateGateNames(names) {
   if (!names.length) throw new Error(`no gates requested — pass --gates with any of: ${Object.keys(GATES).join(", ")}`);
   for (const n of names)
     if (!GATES[n]) throw new Error(`unknown gate "${n}" — valid gates: ${Object.keys(GATES).join(", ")}`);
-  return names.map((gate) => ({ gate, ...GATES[gate](opts) }));
+}
+
+/** Run the named gates against opts.root. Returns [{gate, problems, warnings, ok}].
+ *  Throws on an unknown or empty gate list (validateGateNames). An exception thrown WHILE a
+ *  gate runs is a gate failure, never a usage error: it becomes a problem on that gate's
+ *  result naming the gate and the error, so the CLI exits 1 — the exit code CI consumers
+ *  branch on for "a gate did not pass" (docs/consuming-gates.md). */
+export function runGates(names, opts) {
+  validateGateNames(names);
+  return names.map((gate) => {
+    try {
+      return { gate, ...GATES[gate](opts) };
+    } catch (e) {
+      return { gate, problems: [`gate "${gate}" crashed while running: ${e.message}`], warnings: [], ok: "" };
+    }
+  });
 }
 
 if (runAsCli(import.meta.url)) {
@@ -69,13 +85,16 @@ if (runAsCli(import.meta.url)) {
   };
   const names = opt("gates", "").split(",").map((s) => s.trim()).filter(Boolean);
 
-  let results;
+  // Usage validation alone lives inside the exit-2 try/catch; gate execution happens
+  // outside it, so an exception thrown while a gate runs can never masquerade as usage —
+  // runGates converts it into that gate's failure result and the run exits 1.
   try {
-    results = runGates(names, opts);
+    validateGateNames(names);
   } catch (e) {
     console.error(`usage error: ${e.message}`);
     process.exit(2);
   }
+  const results = runGates(names, opts);
   let failed = 0;
   for (const { gate, problems, warnings, ok } of results) {
     for (const w of warnings) console.log(`[${gate}] warn: ${w}`);

package/spec-bridge/lib/gate-runner.mjs

@@ -10,6 +10,8 @@
 // A gate that resolves no roots is a no-op (this isn't its kind of project). `check` problems
 // block the stop (exit 2); optional `warn` notices are surfaced on stderr but never block (exit 0)
 // — for freshness reminders and the like that shouldn't refuse to let the model finish.
+// A gate that CRASHES — in resolveRoots or in check — surfaces as a blocking problem naming
+// the gate: a crash swallowed silently would be permanent non-enforcement wearing a green exit.
 // `ctx` is { sessionId, input }: the invoking session's identity (hook input `session_id`,
 // falling back to $CLAUDE_CODE_SESSION_ID) plus the raw hook input — gates that scope state
 // to its owning session (e.g. reorient run records) key off it; every existing gate ignores it.
@@ -43,7 +45,9 @@ export function evaluate(input, gates, { cwd = process.cwd() } = {}) {
   const warnings = [];
   for (const gate of gates) {
     let roots = [];
-    try { roots = gate.resolveRoots(start, ctx) || []; } catch { roots = []; }
+    try { roots = gate.resolveRoots(start, ctx) || []; } catch (e) {
+      problems.push(`[${gate.name || "gate"}] resolveRoots crashed on ${start}: ${e.message}`);
+    }
     for (const root of roots) {
       try { problems.push(...(gate.check(root, ctx) || [])); } catch (e) {
         problems.push(`[${gate.name || "gate"}] crashed on ${root}: ${e.message}`);