@praxisflux/gates 0.31.0 → 0.32.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisflux/gates",
-  "version": "0.31.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": {