@praxisflux/gates 0.14.0 → 0.16.0

package/grounding-wiki/gates/capsules.mjs

@@ -0,0 +1,152 @@
+// capsules.mjs — the capsule tier of a code-grounded corpus (docs/corpus-spec.md v2,
+// "The capsule tier and CAPSULES.md" + "Note size budget and summary-style splits").
+//
+// Read-only (gates/ contract): renderCapsules computes what CAPSULES.md must contain,
+// checkCapsuleTier enforces the v2 budgets. The one writer is scripts/capsules.mjs, which
+// 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 { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+import { parseFrontmatter, extractWikilinks } from "../lib/markdown.mjs";
+
+/** v2 budgets — producers' write-time caps, enforced once a corpus adopts the capsule tier. */
+export const CAPSULE_BUDGET = 500; // chars, a note's description:
+export const NOTE_BODY_BUDGET = 8000; // chars, everything below the frontmatter
+
+function git(repoRoot, args) {
+  return execFileSync("git", args, { cwd: repoRoot, encoding: "utf8" }).trim();
+}
+
+function corpusPath(repoRoot, corpusDir) {
+  return isAbsolute(corpusDir) ? corpusDir : join(repoRoot, corpusDir);
+}
+
+/** Every note file in the corpus dir — INDEX.md and the generated CAPSULES.md are not notes. */
+export function noteFiles(dir) {
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".md") && f !== "INDEX.md" && f !== "CAPSULES.md")
+    .sort();
+}
+
+/** The note body: everything below the frontmatter block (the text v2's 8,000-char cap measures). */
+export function noteBody(text) {
+  const t = (text || "").replace(/^/, "").replace(/^\s+/, "");
+  const m = /^---\s*\n[\s\S]*?\n---[^\S\n]*\n?/.exec(t);
+  return m ? t.slice(m[0].length) : t;
+}
+
+/** The first sibling-note reference on an INDEX.md list line: a [[wikilink]] target or a
+ *  markdown link to <name>.md. Null for prose/heading lines. */
+export function indexLineTarget(line) {
+  if (!/^\s*[-*]\s/.test(line)) return null;
+  const wiki = extractWikilinks(line);
+  if (wiki.length) return wiki[0];
+  const md = /\[[^\]]*\]\(([^)#\s]+)\.md\)/.exec(line);
+  return md ? basename(md[1]) : null;
+}
+
+/**
+ * Render the CAPSULES.md content for a corpus: a header naming the generator and the corpus
+ * commit it was generated at, then — in INDEX.md order — each note's INDEX line followed by
+ * its capsule (its `description:`). Notes on disk but missing from INDEX.md follow, sorted by
+ * name, so the rollup always covers the whole corpus. Deterministic and idempotent: same
+ * corpus state (and commit) → byte-identical output. Read-only — scripts/capsules.mjs writes.
+ */
+export function renderCapsules(repoRoot, corpusDir = "docs/wiki", { commit } = {}) {
+  const dir = corpusPath(repoRoot, corpusDir);
+  const indexPath = join(dir, "INDEX.md");
+  if (!existsSync(indexPath)) throw new Error(`not a corpus: ${indexPath} missing`);
+  const at = commit || git(repoRoot, ["rev-parse", "HEAD"]);
+
+  const capsules = new Map(); // note name -> description (its capsule)
+  for (const file of noteFiles(dir)) {
+    const fm = parseFrontmatter(readFileSync(join(dir, file), "utf8"));
+    if (fm) capsules.set(basename(file, ".md"), String(fm.description ?? ""));
+  }
+
+  const entries = [];
+  const seen = new Set();
+  for (const line of readFileSync(indexPath, "utf8").split("\n")) {
+    const name = indexLineTarget(line);
+    if (!name || !capsules.has(name) || seen.has(name)) continue; // reserved names stay INDEX-only
+    seen.add(name);
+    entries.push(`${line.trimEnd()}\n  ${capsules.get(name)}`);
+  }
+  for (const name of [...capsules.keys()].sort()) {
+    if (!seen.has(name)) entries.push(`- [[${name}]] (not in INDEX.md)\n  ${capsules.get(name)}`);
+  }
+
+  const header = [
+    "# Capsules — the corpus rollup",
+    "",
+    `Generated by grounding-wiki \`scripts/capsules.mjs\` at corpus commit ${at}.`,
+    'Derived state (docs/corpus-spec.md, "The capsule tier and CAPSULES.md") — do not edit by',
+    "hand; regenerate whenever any note's `description:` changes:",
+    "",
+    // eslint-disable-next-line no-template-curly-in-string
+    "    node ${CLAUDE_PLUGIN_ROOT}/scripts/capsules.mjs <repo-root> " + corpusDir,
+  ].join("\n");
+  return `${header}\n\n${entries.join("\n\n")}\n`;
+}
+
+/**
+ * Enforce the v2 token-economy budgets over a corpus. Adoption is signalled by CAPSULES.md
+ * existing (the artifact v2 defines — no new contract surface):
+ *
+ * - Adopted: description over 500 chars → FAIL; body over 8,000 chars → FAIL pointing at the
+ *   summary-style split rule, downgraded to WARN when the note's frontmatter carries
+ *   `size_budget_exempt: <reason>`; CAPSULES.md stale or hand-edited (regenerate-and-compare
+ *   against this module's render, at the commit the header names) → FAIL naming the
+ *   regeneration command.
+ * - Unadopted (no CAPSULES.md): the same budget checks surface as WARN-only notices —
+ *   visibility during adoption, nothing blocks.
+ *
+ * Returns { adopted, fails, warns }. Notes without frontmatter are skipped here —
+ * validateFreshness already fails them as not-a-corpus-note.
+ */
+export function checkCapsuleTier(repoRoot, corpusDir = "docs/wiki") {
+  const dir = corpusPath(repoRoot, corpusDir);
+  if (!existsSync(join(dir, "INDEX.md"))) return { adopted: false, fails: [], warns: [] };
+  const adopted = existsSync(join(dir, "CAPSULES.md"));
+  const fails = [];
+  const warns = [];
+  const over = (msg, { downgrade = false } = {}) => {
+    if (adopted && !downgrade) fails.push(msg);
+    else if (adopted) warns.push(msg);
+    else warns.push(`v2 budget (warn-only until this corpus adopts CAPSULES.md): ${msg}`);
+  };
+
+  for (const file of noteFiles(dir)) {
+    const rel = `${corpusDir}/${file}`;
+    const text = readFileSync(join(dir, file), "utf8");
+    const fm = parseFrontmatter(text);
+    if (!fm) continue;
+
+    const desc = String(fm.description ?? "");
+    if (desc.length > CAPSULE_BUDGET)
+      over(`${rel}: description capsule is ${desc.length} chars — ${desc.length - CAPSULE_BUDGET} over the ${CAPSULE_BUDGET}-char capsule budget; rewrite it for routing (docs/corpus-spec.md, "The capsule tier and CAPSULES.md")`);
+
+    const body = noteBody(text);
+    if (body.length > NOTE_BODY_BUDGET) {
+      if (fm.size_budget_exempt)
+        over(`${rel}: body is ${body.length} chars, over the ${NOTE_BODY_BUDGET}-char note budget — size_budget_exempt: ${fm.size_budget_exempt}`, { downgrade: true });
+      else
+        over(`${rel}: body is ${body.length} chars — ${body.length - NOTE_BODY_BUDGET} over the ${NOTE_BODY_BUDGET}-char note budget; split summary-style, or add size_budget_exempt: <reason> if nothing is splittable (docs/corpus-spec.md, "Note size budget and summary-style splits")`);
+    }
+  }
+
+  if (adopted) {
+    const capsulesScript = join(dirname(fileURLToPath(import.meta.url)), "..", "scripts", "capsules.mjs");
+    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)
+      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}`);
+  }
+
+  return { adopted, fails, warns };
+}

package/grounding-wiki/gates/freshness.mjs

@@ -2,11 +2,14 @@
 //
 // A note is STALE when any path in its `sources:` frontmatter changed after its
 // `verified_against:` pin. Verified with git plumbing against the repo the corpus lives in.
+// Also enforces the v2 token-economy budgets (capsule tier + note size) via
+// ./capsules.mjs — hard once the corpus adopts CAPSULES.md, warn-only before.
 // Never writes to disk (gates/ contract).
-import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { readFileSync, existsSync } from "node:fs";
 import { join, isAbsolute, basename } from "node:path";
 import { execFileSync } from "node:child_process";
 import { parseFrontmatter, stripCode, extractWikilinks } from "../lib/markdown.mjs";
+import { checkCapsuleTier, noteFiles } from "./capsules.mjs";
 
 function git(repoRoot, args) {
   return execFileSync("git", args, { cwd: repoRoot, encoding: "utf8" }).trim();
@@ -45,7 +48,7 @@ export function validateFreshness(repoRoot, corpusDir = "docs/wiki") {
     return { fails: [`not a corpus: ${join(dir, "INDEX.md")} missing`], warns, checked: 0 };
   }
 
-  const files = readdirSync(dir).filter((f) => f.endsWith(".md") && f !== "INDEX.md").sort();
+  const files = noteFiles(dir); // INDEX.md and the generated CAPSULES.md are not notes
   const names = new Set(files.map((f) => basename(f, ".md")));
   let checked = 0;
 
@@ -88,6 +91,12 @@ export function validateFreshness(repoRoot, corpusDir = "docs/wiki") {
     }
   }
 
+  // v2 token-economy budgets (capsule ≤500 chars, body ≤8,000 chars, CAPSULES.md currency):
+  // FAILs once the corpus has adopted CAPSULES.md, WARN-only notices before.
+  const tier = checkCapsuleTier(repoRoot, corpusDir);
+  fails.push(...tier.fails);
+  warns.push(...tier.warns);
+
   return { fails, warns, checked };
 }
 
@@ -131,7 +140,7 @@ export function planFreshness(repoRoot, corpusDir = "docs/wiki") {
   if (!existsSync(join(dir, "INDEX.md"))) return { head: "", entries, problems: [`not a corpus: ${join(dir, "INDEX.md")} missing`] };
   const head = git(repoRoot, ["rev-parse", "HEAD"]);
 
-  for (const file of readdirSync(dir).filter((f) => f.endsWith(".md") && f !== "INDEX.md").sort()) {
+  for (const file of noteFiles(dir)) {
     const rel = `${corpusDir}/${file}`;
     const text = readFileSync(join(dir, file), "utf8");
     const pin = parseFrontmatter(text)?.verified_against;

package/package.json

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