@praxisflux/gates 0.6.2 → 0.6.4

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.2",
+  "version": "0.6.4",
   "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

@@ -33,8 +33,10 @@ const RANK = { "to do": 0, "in progress": 1, done: 2 };
 const DERIVED_RANK = { [STATUS.TODO]: 0, [STATUS.IN_PROGRESS]: 1, [STATUS.DONE_ELIGIBLE]: 2 };
 
 /**
- * Parse one Backlog task file. Returns { id, status, specDir } for a linked task,
- * null for anything else (no marker, unreadable, or not a task file).
+ * Parse one Backlog task file. Returns { id, status, specDir, acs } for a linked task,
+ * null for anything else (no marker, unreadable, or not a task file). `acs` is the task's
+ * acceptance criteria as [{ index, checked, text }] read from the AC:BEGIN/END block —
+ * still read-only; the plan command needs them to compute reconciling edits.
  */
 export function parseLinkedTask(raw) {
   const text = String(raw ?? "");
@@ -46,7 +48,12 @@ export function parseLinkedTask(raw) {
   const id = field("id");
   const status = field("status");
   if (!id) return null;
-  return { id, status, specDir: marker[1] };
+  const acs = [];
+  const block = text.match(/<!-- AC:BEGIN -->([\s\S]*?)<!-- AC:END -->/);
+  if (block)
+    for (const m of block[1].matchAll(/^- \[( |x|X)\] #(\d+)\s+(.*\S)\s*$/gm))
+      acs.push({ index: +m[2], checked: m[1] !== " ", text: m[3] });
+  return { id, status, specDir: marker[1], acs };
 }
 
 /** Scan <root>/backlog/tasks/*.md for linked tasks. Unreadable files are skipped. */
@@ -117,6 +124,90 @@ export function checkBridge(root) {
   return { links, problems, warnings };
 }
 
+/* ── plan: the exact backlog edits that reconcile the board ────────────── */
+
+const PHASE_PREFIX = "Spec phase: ";
+
+/** Single-quote a string for verbatim shell use. */
+const sq = (s) => `'${String(s).replace(/'/g, "'\\''")}'`;
+
+/**
+ * Pure planner for ONE linked task: the ordered `backlog task edit` commands that reconcile
+ * it to its derived state. Command order matters and is: status move → stale phase-AC
+ * removals (highest index first, so earlier indexes stay valid) → phase-AC additions →
+ * check/uncheck at post-edit indexes → one progress note (only when something changed).
+ * ACs that don't start with "Spec phase: " are human-authored and are never touched.
+ */
+export function planLinkedTask(task, derived) {
+  const cmds = [];
+  const edit = (args) => cmds.push(`backlog task edit ${task.id} ${args}`);
+
+  // Status — Done-eligible is the only path to Done and carries the derived final summary.
+  const target = derived.status === STATUS.DONE_ELIGIBLE ? "Done" : derived.status;
+  const statusChanged = String(task.status).toLowerCase() !== target.toLowerCase();
+  if (statusChanged) {
+    if (target === "Done")
+      edit(`-s ${sq("Done")} --final-summary ${sq(`All spec tasks complete (${derived.progressNote}). Derived Done by spec-bridge sync.`)}`);
+    else edit(`-s ${sq(target)}`);
+  }
+
+  // Phase-AC reconciliation. The bridge owns exactly the "Spec phase: " ACs.
+  const phaseByName = new Map((derived.phases || []).map((p) => [p.name, p]));
+  const seen = new Set();
+  const removed = new Set();
+  for (const a of task.acs || []) {
+    if (!a.text.startsWith(PHASE_PREFIX)) continue;
+    const name = a.text.slice(PHASE_PREFIX.length);
+    if (!phaseByName.has(name) || seen.has(name)) removed.add(a.index); // stale or duplicate
+    else seen.add(name);
+  }
+  for (const i of [...removed].sort((a, z) => z - a)) edit(`--remove-ac ${i}`);
+
+  const additions = (derived.phases || []).filter((p) => !seen.has(p.name));
+  for (const p of additions) edit(`--ac ${sq(PHASE_PREFIX + p.name)}`);
+
+  // Post-edit indexes: survivors keep their relative order and renumber from 1; additions
+  // append after them, unchecked. Check/uncheck against what each phase actually proves.
+  const survivors = (task.acs || []).filter((a) => !removed.has(a.index));
+  const finalList = [
+    ...survivors.map((a) => ({ text: a.text, checked: a.checked })),
+    ...additions.map((p) => ({ text: PHASE_PREFIX + p.name, checked: false })),
+  ];
+  finalList.forEach((item, i) => {
+    if (!item.text.startsWith(PHASE_PREFIX)) return; // human-authored: never touched
+    const p = phaseByName.get(item.text.slice(PHASE_PREFIX.length));
+    if (!p) return;
+    const want = p.total > 0 && p.done === p.total;
+    if (want && !item.checked) edit(`--check-ac ${i + 1}`);
+    else if (!want && item.checked) edit(`--uncheck-ac ${i + 1}`);
+  });
+
+  // One note, only when this sync changed something — no churn in the task history.
+  if (cmds.length) {
+    const suffix = statusChanged ? ` — status ${task.status} → ${target}` : "";
+    edit(`--append-notes ${sq(`spec-bridge sync: ${derived.progressNote}${suffix}`)}`);
+  }
+  return cmds;
+}
+
+/**
+ * Plan every linked task under <root>, in queue order. Returns:
+ *   commands — ordered `backlog task edit` lines; empty on a reconciled board (no-op)
+ *   skipped  — [{ id, status }] for verdict-unknown tasks (custom status: don't guess)
+ * Read-only like everything in gates/: plan PRINTS edits, it never executes them.
+ */
+export function planBridge(root) {
+  const commands = [];
+  const skipped = [];
+  const requireAnalysis = loadBridgeConfig(root).strictDone === true;
+  for (const task of findLinkedTasks(root)) {
+    const derived = deriveSpecState(join(root, task.specDir), { requireAnalysis });
+    if (verdict(task.status, derived.status) === "unknown") { skipped.push({ id: task.id, status: task.status }); continue; }
+    commands.push(...planLinkedTask(task, derived));
+  }
+  return { commands, skipped };
+}
+
 /**
  * The Stop-hook gate, in gate-runner shape. Roots are directories holding a backlog/ dir;
  * a root with no linked tasks yields no problems, so the gate is a natural no-op outside

package/spec-bridge/gates/cli.mjs

@@ -4,14 +4,17 @@
 //   node cli.mjs state <specDir>   derived state for one spec dir, as JSON
 //   node cli.mjs links <root>      every linked task under <root> with derived state + verdict, as JSON
 //   node cli.mjs check <root>      human report; exit 1 if any task's status exceeds its artifacts
+//   node cli.mjs plan <root>       the ordered `backlog task edit` commands that reconcile the
+//                                  board to the derived state (stdout; nothing on a reconciled
+//                                  board). Prints, NEVER executes — the sync skill runs them.
 import { resolve } from "node:path";
 import { deriveSpecState } from "../lib/spec-derive.mjs";
 import { findRootUpwards, hasChild } from "../lib/project-root.mjs";
-import { checkBridge, loadBridgeConfig } from "./bridge.mjs";
+import { checkBridge, loadBridgeConfig, planBridge } from "./bridge.mjs";
 
 const [cmd, target] = process.argv.slice(2);
 if (!cmd || !target) {
-  console.error("usage: cli.mjs state <specDir> | links <root> | check <root>");
+  console.error("usage: cli.mjs state <specDir> | links <root> | check <root> | plan <root>");
   process.exit(2);
 }
 
@@ -31,6 +34,11 @@ if (cmd === "state") {
     process.exit(1);
   }
   console.log(`spec-bridge ok: ${links.length} linked task(s), none exceed their artifacts`);
+} else if (cmd === "plan") {
+  const { commands, skipped } = planBridge(target);
+  for (const s of skipped)
+    console.error(`# ${s.id}: status "${s.status}" is outside To Do/In Progress/Done — not planned; resolve by hand`);
+  for (const c of commands) console.log(c);
 } else {
   console.error(`unknown command: ${cmd}`);
   process.exit(2);