@praxisflux/gates 0.30.0 → 0.32.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/gates/capsules.mjs

@@ -6,7 +6,7 @@
 // renders through this module — so the gate's regenerate-and-compare check and the
 // regeneration command can never drift apart.
 import { readdirSync, readFileSync, existsSync } from "node:fs";
-import { join, isAbsolute, basename, dirname } from "node:path";
+import { join, isAbsolute, basename, dirname, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { execFileSync } from "node:child_process";
 import { parseFrontmatter, extractWikilinks } from "../lib/markdown.mjs";
@@ -23,6 +23,17 @@ function corpusPath(repoRoot, corpusDir) {
   return isAbsolute(corpusDir) ? corpusDir : join(repoRoot, corpusDir);
 }
 
+/**
+ * The one canonical spelling of a corpus dir: repo-relative, forward slashes, no trailing
+ * slash — whatever spelling the caller used (absolute path, trailing slash, `./` prefix).
+ * CAPSULES.md embeds corpusDir in its header, and the freshness gate re-renders and
+ * byte-compares; both sides normalizing here makes regenerate-and-compare invariant to how
+ * the generator happened to be invoked.
+ */
+export function normalizeCorpusDir(repoRoot, corpusDir = "docs/wiki") {
+  return relative(repoRoot, corpusPath(repoRoot, corpusDir)).split(sep).join("/");
+}
+
 /** Every note file in the corpus dir — INDEX.md and the generated CAPSULES.md are not notes. */
 export function noteFiles(dir) {
   return readdirSync(dir)
@@ -55,6 +66,7 @@ export function indexLineTarget(line) {
  * corpus state (and commit) → byte-identical output. Read-only — scripts/capsules.mjs writes.
  */
 export function renderCapsules(repoRoot, corpusDir = "docs/wiki", { commit } = {}) {
+  corpusDir = normalizeCorpusDir(repoRoot, corpusDir); // header embeds it — one spelling only
   const dir = corpusPath(repoRoot, corpusDir);
   const indexPath = join(dir, "INDEX.md");
   if (!existsSync(indexPath)) throw new Error(`not a corpus: ${indexPath} missing`);
@@ -107,6 +119,7 @@ export function renderCapsules(repoRoot, corpusDir = "docs/wiki", { commit } = {
  * validateFreshness already fails them as not-a-corpus-note.
  */
 export function checkCapsuleTier(repoRoot, corpusDir = "docs/wiki") {
+  corpusDir = normalizeCorpusDir(repoRoot, corpusDir); // match renderCapsules' spelling
   const dir = corpusPath(repoRoot, corpusDir);
   if (!existsSync(join(dir, "INDEX.md"))) return { adopted: false, fails: [], warns: [] };
   const adopted = existsSync(join(dir, "CAPSULES.md"));
@@ -142,10 +155,25 @@ export function checkCapsuleTier(repoRoot, corpusDir = "docs/wiki") {
     const regen = `node ${capsulesScript} ${repoRoot} ${corpusDir}`;
     const existing = readFileSync(join(dir, "CAPSULES.md"), "utf8");
     const m = /corpus commit ([0-9a-f]{40})/.exec(existing);
-    if (!m)
+    if (!m) {
       fails.push(`${corpusDir}/CAPSULES.md: header names no corpus commit — hand-edited or foreign; regenerate: ${regen}`);
-    else if (renderCapsules(repoRoot, corpusDir, { commit: m[1] }) !== existing)
-      fails.push(`${corpusDir}/CAPSULES.md: stale — regenerate-and-compare mismatch (a description or INDEX.md changed after generation, or the file was hand-edited); regenerate: ${regen}`);
+    } else {
+      const rendered = renderCapsules(repoRoot, corpusDir, { commit: m[1] });
+      // Pre-normalization headers embed corpusDir as the generator was invoked (absolute
+      // path, trailing slash). If the ONLY difference is that spelling, the content is
+      // current — that deserves regeneration guidance, not a hand-edit accusation.
+      const cmd = /^(    node \$\{CLAUDE_PLUGIN_ROOT\}\/scripts\/capsules\.mjs <repo-root> )(.*)$/m.exec(existing);
+      const respelled = cmd && cmd[2] !== corpusDir
+        ? existing.replace(cmd[0], () => cmd[1] + corpusDir)
+        : existing;
+      if (rendered === existing) {
+        // current, canonical header — nothing to say
+      } else if (rendered === respelled) {
+        warns.push(`${corpusDir}/CAPSULES.md: header embeds a pre-normalization corpusDir spelling (${cmd[2]}); content is current — regenerate to refresh the header: ${regen}`);
+      } else {
+        fails.push(`${corpusDir}/CAPSULES.md: stale — regenerate-and-compare mismatch (a description or INDEX.md changed after generation, or the file was hand-edited); regenerate: ${regen}`);
+      }
+    }
   }
 
   return { adopted, fails, warns };

package/grounding-wiki/gates/freshness.mjs

@@ -34,6 +34,17 @@ export function parseSourcesBlock(text) {
   return out;
 }
 
+/**
+ * A note's `sources:` paths — both sanctioned spellings, one truth: inline `sources: [a, b]`
+ * arrays come from lib/markdown.mjs `parseFrontmatter` (already parsed on `fm`), YAML block
+ * lists from parseSourcesBlock above. Aligning on parseFrontmatter for the inline form keeps
+ * this from growing a second frontmatter dialect.
+ */
+export function noteSources(text, fm = parseFrontmatter(text)) {
+  if (Array.isArray(fm?.sources)) return fm.sources;
+  return parseSourcesBlock(text);
+}
+
 /**
  * Check every note in a corpus for staleness against the repo's git history.
  * corpusDir is relative to repoRoot unless absolute. Returns { fails, warns, checked };
@@ -69,10 +80,14 @@ export function validateFreshness(repoRoot, corpusDir = "docs/wiki") {
       continue;
     }
 
-    const sources = parseSourcesBlock(text);
+    const sources = noteSources(text, fm);
     if (sources.length === 0) {
       warns.push(`${rel}: no sources listed — staleness is unverifiable`);
     } else {
+      // A source path absent from the working tree is vanished proof, not freshness: git log
+      // over a nonexistent pathspec is silently empty, which would report FRESH forever.
+      for (const s of sources.filter((s) => !existsSync(join(repoRoot, s))))
+        fails.push(`${rel}: source missing from the working tree: ${s} — renamed, deleted, or a typo; fix the note's sources`);
       let changed = "";
       try {
         changed = git(repoRoot, ["log", "--oneline", `${pin}..HEAD`, "--", ...sources]);
@@ -143,12 +158,19 @@ export function planFreshness(repoRoot, corpusDir = "docs/wiki") {
   for (const file of noteFiles(dir)) {
     const rel = `${corpusDir}/${file}`;
     const text = readFileSync(join(dir, file), "utf8");
-    const pin = parseFrontmatter(text)?.verified_against;
+    const fm = parseFrontmatter(text);
+    const pin = fm?.verified_against;
     if (!pin) { problems.push(`${rel}: no verified_against pin`); continue; }
     try { git(repoRoot, ["cat-file", "-e", `${pin}^{commit}`]); }
     catch { problems.push(`${rel}: pin ${pin} is not a known commit`); continue; }
-    const sources = parseSourcesBlock(text);
+    const sources = noteSources(text, fm);
     if (!sources.length) continue; // unverifiable — the freshness gate already warns
+    const missing = sources.filter((s) => !existsSync(join(repoRoot, s)));
+    if (missing.length) {
+      // The freshness gate blocks on these; plan doesn't paper over them with a re-pin.
+      problems.push(`${rel}: source missing from the working tree: ${missing.join(", ")} — fix the note's sources first`);
+      continue;
+    }
 
     const log = git(repoRoot, ["log", "--oneline", `${pin}..HEAD`, "--", ...sources]);
     if (!log) continue; // fresh

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.32.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}`);