@praxisflux/gates 0.6.3 → 0.6.5

package/grounding-wiki/gates/cli.mjs

@@ -1,7 +1,16 @@
 #!/usr/bin/env node
 // cli.mjs — command-line entry to the grounding-wiki gates.
 //   node cli.mjs freshness <repo-root> [corpus-dir]     (corpus-dir defaults to docs/wiki)
-import { validateFreshness } from "./freshness.mjs";
+//   node cli.mjs plan <repo-root> [corpus-dir]          computed reconciliation for stale
+//                                                       notes: RE-PIN-ONLY entries print
+//                                                       runnable repin.mjs commands, NEEDS-
+//                                                       REVIEW entries print a work order.
+//                                                       Fresh corpus prints nothing.
+//                                                       Read-only — plan prints, the
+//                                                       wiki-update skill executes.
+import { fileURLToPath } from "node:url";
+import { join, dirname } from "node:path";
+import { validateFreshness, planFreshness } from "./freshness.mjs";
 
 function report({ fails = [], warns = [], checked = 0 }, okMsg) {
   for (const w of warns) console.log(`warn: ${w}`);
@@ -20,7 +29,25 @@ if (cmd === "freshness") {
   if (!root) { console.error("usage: cli.mjs freshness <repo-root> [corpus-dir]"); process.exit(2); }
   const r = validateFreshness(root, corpusDir || "docs/wiki");
   report(r, "OK: %n note(s) fresh against their pinned sources.");
+} else if (cmd === "plan") {
+  const [root, corpusDir] = rest;
+  if (!root) { console.error("usage: cli.mjs plan <repo-root> [corpus-dir]"); process.exit(2); }
+  const { head, entries, problems } = planFreshness(root, corpusDir || "docs/wiki");
+  if (problems.length) {
+    for (const p of problems) console.error(`# problem: ${p} — fix before planning`);
+    process.exit(1);
+  }
+  const repinScript = join(dirname(fileURLToPath(import.meta.url)), "..", "scripts", "repin.mjs");
+  const summary = (e) => e.files.map((f) => `${f.path} (+${f.plus}/-${f.minus})`).join(", ");
+  for (const e of entries) {
+    if (e.cls === "REPIN") {
+      console.log(`# RE-PIN-ONLY ${e.note} — ${e.reason} (${e.commits} commit(s): ${summary(e)})`);
+      console.log(`node ${repinScript} ${e.absPath} ${head}`);
+    } else {
+      console.log(`# NEEDS-REVIEW ${e.note} — pin ${e.pin.slice(0, 12)}, ${e.commits} commit(s); ${e.reason}; changed: ${summary(e)}`);
+    }
+  }
 } else {
-  console.error("usage: cli.mjs freshness <repo-root> [corpus-dir]");
+  console.error("usage: cli.mjs freshness <repo-root> [corpus-dir] | plan <repo-root> [corpus-dir]");
   process.exit(2);
 }

package/grounding-wiki/gates/freshness.mjs

@@ -90,3 +90,69 @@ export function validateFreshness(repoRoot, corpusDir = "docs/wiki") {
 
   return { fails, warns, checked };
 }
+
+/* ── plan: classify stale notes into computed re-pins vs review work ───── */
+
+// The ONE provably-safe diff class. A changed line is a lockstep version stamp when it is a
+// version key ("version": "1.2.3" / version: 1.2.3) or an npm-style pin (@scope/name@1.2.3).
+const STAMP_LINE = /(["']?version["']?\s*[:=]\s*["']?\d+\.\d+\.\d+)|(@[\w.-]+\/[\w.-]+@\d+\.\d+\.\d+)/;
+const SEMVER = /\d+\.\d+\.\d+/;
+
+/**
+ * Pure classifier. `changedLines` are the +/- content lines of the diff over a note's
+ * sources since its pin; `noteBody` is the note's full text. RE-PIN-ONLY iff every changed
+ * line is a version stamp AND the note quotes no semver literal anywhere (a note that names
+ * versions may claim the very number that just changed). Anything else — including an empty
+ * diff we couldn't read — defaults to NEEDS-REVIEW: a pin is a verification claim, and the
+ * planner must never make one it can't prove.
+ */
+export function classifyNote(changedLines, noteBody) {
+  if (!changedLines.length) return { cls: "REVIEW", reason: "diff could not be read — verify by hand" };
+  if (!changedLines.every((l) => STAMP_LINE.test(l)))
+    return { cls: "REVIEW", reason: "sources changed beyond version stamps — re-verify the prose against the diff" };
+  // Raw body, deliberately: notes quote versions in backticks (`0.6.3`), which stripCode
+  // would hide — and hiding them would flip the classification in the UNSAFE direction.
+  if (SEMVER.test(String(noteBody ?? "")))
+    return { cls: "REVIEW", reason: "stamp-only diff, but the note quotes version literals — update them, then re-pin" };
+  return { cls: "REPIN", reason: "version stamps only, and the note quotes no versions" };
+}
+
+/**
+ * Plan the reconciliation of a stale corpus: for each stale note, the diff summary since its
+ * pin and a classification. Read-only (gates/ contract) — the CLI prints, the wiki-update
+ * skill executes. Returns { head, entries, problems }; a fresh corpus yields entries: [].
+ * Notes that fail structurally (no pin, unknown pin) land in `problems` — plan doesn't
+ * paper over what the freshness gate would reject.
+ */
+export function planFreshness(repoRoot, corpusDir = "docs/wiki") {
+  const entries = [];
+  const problems = [];
+  const dir = isAbsolute(corpusDir) ? corpusDir : join(repoRoot, corpusDir);
+  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()) {
+    const rel = `${corpusDir}/${file}`;
+    const text = readFileSync(join(dir, file), "utf8");
+    const pin = parseFrontmatter(text)?.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);
+    if (!sources.length) continue; // unverifiable — the freshness gate already warns
+
+    const log = git(repoRoot, ["log", "--oneline", `${pin}..HEAD`, "--", ...sources]);
+    if (!log) continue; // fresh
+    const commits = log.split("\n").length;
+    const files = git(repoRoot, ["diff", "--numstat", `${pin}..HEAD`, "--", ...sources])
+      .split("\n").filter(Boolean)
+      .map((l) => { const [plus, minus, path] = l.split("\t"); return { path, plus: +plus || 0, minus: +minus || 0 }; });
+    const changedLines = git(repoRoot, ["diff", "-U0", `${pin}..HEAD`, "--", ...sources])
+      .split("\n")
+      .filter((l) => (/^[+-]/.test(l) && !/^(\+\+\+|---)/.test(l)))
+      .map((l) => l.slice(1))
+      .filter((l) => l.trim() !== "");
+    entries.push({ note: rel, absPath: join(dir, file), pin, head, commits, files, ...classifyNote(changedLines, text) });
+  }
+  return { head, entries, problems };
+}

package/package.json

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

package/spec-bridge/gates/bridge.mjs

@@ -119,6 +119,25 @@ export function checkBridge(root) {
       warnings.push(
         `[spec-bridge] ${task.id} is "${task.status}" but ${task.specDir} already derives "${derived.status}" — run the spec-bridge sync skill to catch the board up.`
       );
+    } else if (
+      // Strict-mode near-miss: the status is honest ("ok"), every checkbox is checked, and
+      // the ONLY thing between this task and Done-eligible is the analysis requirement.
+      // Without this notice the state is silent — Done is out of reach and nothing says so
+      // until someone thinks to run `state`. Warn (the warn channel), never block.
+      v === "ok" &&
+      derived.analysis?.required &&
+      derived.status !== STATUS.DONE_ELIGIBLE &&
+      derived.tasksTotal > 0 &&
+      derived.tasksDone === derived.tasksTotal &&
+      existsSync(join(root, task.specDir, "plan.md"))
+    ) {
+      const a = derived.analysis;
+      warnings.push(
+        `[spec-bridge] ${task.id}: all ${derived.tasksTotal} spec tasks checked; Done blocked by strict mode: ` +
+        (!a.present
+          ? "analysis.md missing — run /speckit.analyze and save its report as " + `${task.specDir}/analysis.md`
+          : `unresolved CRITICAL finding(s) in analysis.md: ${a.criticals.join(" | ")}`)
+      );
     }
   }
   return { links, problems, warnings };