@praxisflux/gates 0.59.3 → 0.59.6

package/codebase-to-course/lib/project-root.mjs

@@ -14,6 +14,14 @@ export function hasChild(name) {
   return (dir) => existsSync(join(dir, name));
 }
 
+/** Combine markers: true when ANY of `names` exists as a child. One definition composed
+ *  from `hasChild`, so every caller that needs "either sentinel marks a project" (e.g. the
+ *  spec-bridge Stop hook and its CLI, which must never disagree about what a project is)
+ *  shares it instead of duplicating the predicate inline at each call site. */
+export function hasAnyChild(...names) {
+  return (dir) => names.some((n) => hasChild(n)(dir));
+}
+
 /**
  * Walk up from `startDir` until `markerFn(dir)` is truthy. Returns the matching
  * directory (absolute) or null if the filesystem root is reached without a match.

package/grounding-wiki/lib/project-root.mjs

@@ -14,6 +14,14 @@ export function hasChild(name) {
   return (dir) => existsSync(join(dir, name));
 }
 
+/** Combine markers: true when ANY of `names` exists as a child. One definition composed
+ *  from `hasChild`, so every caller that needs "either sentinel marks a project" (e.g. the
+ *  spec-bridge Stop hook and its CLI, which must never disagree about what a project is)
+ *  shares it instead of duplicating the predicate inline at each call site. */
+export function hasAnyChild(...names) {
+  return (dir) => names.some((n) => hasChild(n)(dir));
+}
+
 /**
  * Walk up from `startDir` until `markerFn(dir)` is truthy. Returns the matching
  * directory (absolute) or null if the filesystem root is reached without a match.

package/lib/project-root.mjs

@@ -14,6 +14,14 @@ export function hasChild(name) {
   return (dir) => existsSync(join(dir, name));
 }
 
+/** Combine markers: true when ANY of `names` exists as a child. One definition composed
+ *  from `hasChild`, so every caller that needs "either sentinel marks a project" (e.g. the
+ *  spec-bridge Stop hook and its CLI, which must never disagree about what a project is)
+ *  shares it instead of duplicating the predicate inline at each call site. */
+export function hasAnyChild(...names) {
+  return (dir) => names.some((n) => hasChild(n)(dir));
+}
+
 /**
  * Walk up from `startDir` until `markerFn(dir)` is truthy. Returns the matching
  * directory (absolute) or null if the filesystem root is reached without a match.

package/package.json

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

@@ -22,8 +22,8 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
 import { deriveSpecState, STATUS, STAGE, STAGES } from "../lib/spec-derive.mjs";
-import { hasChild, findRootsDownwards } from "../lib/project-root.mjs";
-import { parseLinkedTask, findLinkedTasks } from "../lib/board-mirror.mjs";
+import { hasAnyChild, findRootsDownwards } from "../lib/project-root.mjs";
+import { parseLinkedTask, findLinkedTasks, readMirror, providers, mirrorStaleness } from "../lib/board-mirror.mjs";
 
 /**
  * Per-project bridge config: `.spec-bridge.json` at the project root (beside backlog/).
@@ -264,6 +264,44 @@ const DERIVED_RANK = { [STATUS.TODO]: 0, [STATUS.IN_PROGRESS]: 1, [STATUS.DONE_E
 // every existing import site still resolves.
 export { parseLinkedTask, findLinkedTasks };
 
+/**
+ * The one seam through which the bridge learns what's on the board (spec 053 R1). Resolution
+ * order, MIRROR FIRST:
+ *   1. `.board/links.json` present → its `links` (readMirror throws fail-closed on a
+ *      malformed/unknown-schema mirror; that throw is left to propagate so gate-runner.mjs
+ *      surfaces it as a blocking problem, never a silently empty board).
+ *   2. No mirror, but backlog/tasks/ present → project it live via `providers.backlog.project`
+ *      — the backward-compatibility path: a host that never adopts the mirror keeps working,
+ *      byte-identically, forever.
+ *   3. Neither → [].
+ * Mirror-first is deliberate, not incidental: a host that HAS adopted the mirror must be
+ * answered from that receipt, not from a live rescan of backlog/tasks/ — otherwise an adopted
+ * mirror is never actually exercised by the bridge, and 052's `--check` drift detection would
+ * be guarding a file nothing reads.
+ */
+export function boardLinks(root) {
+  const mirror = readMirror(root);
+  if (mirror) return mirror.links;
+  if (existsSync(join(root, "backlog", "tasks"))) return providers.backlog.project(root);
+  return [];
+}
+
+/**
+ * `.board.json` (spec 054, not yet merged) declares which provider a host uses. Read
+ * defensively — absent, unreadable, or malformed all collapse to `"backlog"` — so this spec
+ * lands and tests before 054 merges: `"backlog"` is the one provider that has ever worked
+ * without a mirror at all (boardLinks' live-projection fallback), so a host that predates
+ * `.board.json` entirely is judged exactly as it always was.
+ */
+function declaredProvider(root) {
+  try {
+    const raw = JSON.parse(readFileSync(join(root, ".board.json"), "utf8"));
+    return typeof raw?.provider === "string" && raw.provider ? raw.provider : "backlog";
+  } catch {
+    return "backlog";
+  }
+}
+
 /** Compare a task's Backlog status to its derived status: "exceeds" | "lags" | "ok" | "unknown". */
 export function verdict(taskStatus, derivedStatus) {
   const t = RANK[String(taskStatus).toLowerCase()];
@@ -316,6 +354,46 @@ export function checkBridge(root, { runGates = true, run } = {}) {
   const requireAnalysis = config.strictDone === true;
   const profile = vocabularyProfile(config);
   const gatesProfile = projectGatesProfile(config);
+
+  // R3/R4 (spec 053 phase 2): fail-closed board-evidence findings. Computed once per call,
+  // independent of any particular linked task — the finding is about whether evidence EXISTS
+  // at all, not about a task's derived state. `readMirror` throws on a malformed/unknown-schema
+  // mirror; that throw is left to propagate (boardLinks() below re-reads it for the same
+  // reason) so gate-runner.mjs's evaluate() surfaces it as a blocking problem — never a
+  // silently empty board (lib/gate-runner.mjs :52-54).
+  const mirror = readMirror(root);
+  if (mirror) {
+    // R3: for a requiresSync:true provider (e.g. Jira) the mirror IS the evidence, so a stale
+    // one blocks — name the reason AND the remedy so the reader never needs a second lookup.
+    // For requiresSync:false (Backlog) a stale mirror is deliberately NOT blocking: boardLinks()
+    // step 2's live backlog/tasks/ projection is preferred over the stale receipt, so the gate
+    // recomputes instead of complaining. Same staleness fact, opposite consequence — this
+    // asymmetry is R3's point, not an inconsistency to "fix" into symmetry.
+    const providerInfo = providers[mirror.provider];
+    const requiresSync = providerInfo ? providerInfo.requiresSync : true; // unknown name: fail closed
+    if (requiresSync) {
+      const { stale, reason } = mirrorStaleness(root, mirror);
+      if (stale) {
+        problems.push(
+          `[spec-bridge] board mirror is stale (${reason}) — run the board:sync skill to refresh .board/links.json before claiming status.`
+        );
+      }
+    }
+  } else {
+    // R4: no mirror at all. `.board.json` declares which provider the host uses (absence =
+    // "backlog", the only provider that has ever worked mirror-less). A requiresSync provider
+    // with no mirror has NO evidence for this gate to check — that is the fail-closed finding
+    // this whole spec exists to add, never a silently empty board.
+    const provider = declaredProvider(root);
+    const providerInfo = providers[provider];
+    const requiresSync = providerInfo ? providerInfo.requiresSync : true;
+    if (requiresSync) {
+      problems.push(
+        `[spec-bridge] provider "${provider}" is declared but .board/links.json is missing — the gate has no board evidence to check. Run the board:sync skill.`
+      );
+    }
+  }
+
   // Run declared project gates only when they're opted into and the caller asked for it (the Stop
   // hook runs them in `check` but not the duplicate `warn` pass). SPEC_BRIDGE_GATE_ACTIVE, set on
   // every child runGateCommand spawns, is the reentrancy guard: a host gate command that itself
@@ -327,7 +405,7 @@ export function checkBridge(root, { runGates = true, run } = {}) {
   const injected = run !== undefined;
   const execGates = runGates && !!gatesProfile && (injected || process.env.SPEC_BRIDGE_GATE_ACTIVE !== "1");
   const runOne = memoizeRun(run || ((command) => runGateCommand(command, { cwd: root })));
-  for (const task of findLinkedTasks(root)) {
+  for (const task of boardLinks(root)) {
     const derived = deriveSpecState(join(root, task.specDir), { requireAnalysis });
     // Opted-in boards are judged on the stage ladder against their own status names;
     // everyone else gets the 3-status comparison, untouched.
@@ -403,7 +481,7 @@ export function verifyBridge(root, { run } = {}) {
   const requireAnalysis = config.strictDone === true;
   // Share each distinct gate result across every spec this invocation checks (spec 050 defect 2).
   const runOne = memoizeRun(run || ((command) => runGateCommand(command, { cwd: root })));
-  for (const task of findLinkedTasks(root)) {
+  for (const task of boardLinks(root)) {
     const derived = deriveSpecState(join(root, task.specDir), { requireAnalysis });
     const anyTicked = (derived.phaseBoxes || []).some((p) => (p.boxes || []).some((b) => b.checked));
     if (!anyTicked) continue; // nothing claims greenness yet — no tick to outrun a gate
@@ -419,7 +497,7 @@ export function verifyBridge(root, { run } = {}) {
   return problems;
 }
 
-/* ── plan: the exact backlog edits that reconcile the board ────────────── */
+/* ── plan: reconciliation intents, and the Backlog renderer for them ───── */
 
 const PHASE_PREFIX = "Spec phase: ";
 
@@ -427,33 +505,32 @@ const PHASE_PREFIX = "Spec phase: ";
 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.
+ * Pure reconciliation for ONE linked task (spec 053 R5): the board-neutral INTENT that would
+ * bring it in line with its derived state — decided here, rendered nowhere. ALL the ordering
+ * logic lives here, not in a renderer: stale phase-AC removals highest-index-first (so
+ * earlier indexes stay valid while they're being removed), check/uncheck computed at
+ * POST-EDIT indexes (after removals and additions have already renumbered the list). That
+ * ordering is load-bearing and hard-won — it is reconciliation, not rendering, which is
+ * exactly why the split puts it on this side of the line. ACs that don't start with
+ * "Spec phase: " are human-authored and are never touched.
+ *
+ * Shape (spec 053 R5's minimum, so a future provider's renderer has something to render):
+ *   { id, statusFrom, statusTo, finalSummary, acRemove, acAdd, acCheck, acUncheck, note }
+ * `statusTo` / `finalSummary` / `note` are null when nothing moves on that axis.
  *
  * With an opted-in vocabulary profile (third argument), status targets are the profile's
  * stage names instead of the 3-status collapse. Done keeps its meaning: a board that leaves
- * "reviewing" at its default still plans `-s Done` with the derived final summary; a board
- * that names it (say "In Review") is planned to that name, and moving to Done stays a
- * human/consumer act the gate already accepts (Done never exceeds a fully-proven spec).
+ * "reviewing" at its default still resolves `statusTo: "Done"` with the derived final
+ * summary; a board that names it (say "In Review") resolves to that name, and moving to Done
+ * stays a human/consumer act the gate already accepts (Done never exceeds a fully-proven spec).
  */
-export function planLinkedTask(task, derived, profile = null) {
-  const cmds = [];
-  const edit = (args) => cmds.push(`backlog task edit ${task.id} ${args}`);
-
+export function planIntents(task, derived, profile = null) {
   // Status — Done-eligible is the only path to Done and carries the derived final summary.
   const mapped = profile ? profile.names[derived.stage] : null;
   const target = derived.status === STATUS.DONE_ELIGIBLE
     ? (mapped && mapped.toLowerCase() !== "done" ? mapped : "Done")
     : (mapped ?? 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]));
@@ -465,10 +542,10 @@ export function planLinkedTask(task, derived, profile = null) {
     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 acRemove = [...removed].sort((a, z) => z - a); // highest index first, so earlier indexes stay valid
 
   const additions = (derived.phases || []).filter((p) => !seen.has(p.name));
-  for (const p of additions) edit(`--ac ${sq(PHASE_PREFIX + p.name)}`);
+  const acAdd = additions.map((p) => 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.
@@ -477,42 +554,106 @@ export function planLinkedTask(task, derived, profile = null) {
     ...survivors.map((a) => ({ text: a.text, checked: a.checked })),
     ...additions.map((p) => ({ text: PHASE_PREFIX + p.name, checked: false })),
   ];
+  const acCheck = [];
+  const acUncheck = [];
   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}`);
+    if (want && !item.checked) acCheck.push(i + 1);
+    else if (!want && item.checked) acUncheck.push(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}`)}`);
+  // Nothing to note when nothing changed — no churn in the task history.
+  const changed = statusChanged || acRemove.length > 0 || acAdd.length > 0 || acCheck.length > 0 || acUncheck.length > 0;
+  const suffix = statusChanged ? ` — status ${task.status} → ${target}` : "";
+
+  return {
+    id: task.id,
+    statusFrom: task.status,
+    statusTo: statusChanged ? target : null,
+    finalSummary: statusChanged && target === "Done"
+      ? `All spec tasks complete (${derived.progressNote}). Derived Done by spec-bridge sync.`
+      : null,
+    acRemove, acAdd, acCheck, acUncheck,
+    note: changed ? `spec-bridge sync: ${derived.progressNote}${suffix}` : null,
+  };
+}
+
+/**
+ * Render one task's intents as the exact `backlog task edit …` command strings — today's
+ * literal bytes (spec 053 R5). Order: status move → AC removals → AC additions → check →
+ * uncheck → one append-notes. `id` is taken as a parameter rather than read off `intents` so
+ * a renderer never has to trust the blob it's handed.
+ */
+export function renderBacklog(id, intents) {
+  const cmds = [];
+  const edit = (args) => cmds.push(`backlog task edit ${id} ${args}`);
+  if (intents.statusTo) {
+    if (intents.statusTo === "Done") edit(`-s ${sq("Done")} --final-summary ${sq(intents.finalSummary)}`);
+    else edit(`-s ${sq(intents.statusTo)}`);
   }
+  for (const i of intents.acRemove) edit(`--remove-ac ${i}`);
+  for (const text of intents.acAdd) edit(`--ac ${sq(text)}`);
+  for (const i of intents.acCheck) edit(`--check-ac ${i}`);
+  for (const i of intents.acUncheck) edit(`--uncheck-ac ${i}`);
+  if (intents.note) edit(`--append-notes ${sq(intents.note)}`);
   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.
+ * Backward-compatible single-shot planner: `planIntents` then `renderBacklog` in one call.
+ * Every call site inside this module now goes through the two halves directly; this wrapper
+ * exists only because it is still a public, imported symbol (spec 053 AC #9).
+ */
+export function planLinkedTask(task, derived, profile = null) {
+  return renderBacklog(task.id, planIntents(task, derived, profile));
+}
+
+/**
+ * Which provider `planBridge` renders for (spec 053 R5): the mirror's own declared provider
+ * when a mirror is on disk (it's the artifact that exists, so it's the truth), `.board.json`'s
+ * declaration otherwise — the same present-artifact split `checkBridge`'s R3/R4 block uses,
+ * for the same reason: don't let a config file override live mirror evidence when both exist.
+ */
+function resolvedProvider(root) {
+  const mirror = readMirror(root);
+  return mirror ? mirror.provider : declaredProvider(root);
+}
+
+/**
+ * Plan every linked task under <root>, in queue order (spec 053 R5). `skipped` — [{ id,
+ * status }] for verdict-unknown tasks (custom status: don't guess) — is returned either way.
+ * For the `backlog` provider: `{ commands, skipped }`, today's exact `backlog task edit`
+ * strings, byte-identical to before the split (empty `commands` on a reconciled board is
+ * still a no-op). For any other provider: `{ intents, skipped, notice }` — the same
+ * reconciliation as structured intents, plus a notice that command rendering is
+ * provider-specific (spec 055 owns that verb table; guessing it here would mean writing it
+ * twice). Read-only like everything in gates/: plan computes edits, it never executes them.
  */
 export function planBridge(root) {
-  const commands = [];
   const skipped = [];
+  const perTask = [];
   const config = loadBridgeConfig(root);
   const requireAnalysis = config.strictDone === true;
   const profile = vocabularyProfile(config);
-  for (const task of findLinkedTasks(root)) {
+  for (const task of boardLinks(root)) {
     const derived = deriveSpecState(join(root, task.specDir), { requireAnalysis });
     const v = profile ? stageVerdict(task.status, derived.stage, profile) : verdict(task.status, derived.status);
     if (v === "unknown") { skipped.push({ id: task.id, status: task.status }); continue; }
-    commands.push(...planLinkedTask(task, derived, profile));
+    perTask.push(planIntents(task, derived, profile));
   }
-  return { commands, skipped };
+  if (resolvedProvider(root) === "backlog") {
+    return { commands: perTask.flatMap((intents) => renderBacklog(intents.id, intents)), skipped };
+  }
+  return {
+    intents: perTask,
+    skipped,
+    notice:
+      "command rendering is provider-specific — \"backlog\" is the only rendered provider today " +
+      "(spec 055 owns the verb table for the rest); these are structured intents, not commands.",
+  };
 }
 
 /**
@@ -522,7 +663,7 @@ export function planBridge(root) {
  */
 export const bridgeGate = {
   name: "spec-bridge",
-  resolveRoots: (startDir) => findRootsDownwards(startDir, hasChild("backlog")),
+  resolveRoots: (startDir) => findRootsDownwards(startDir, hasAnyChild(".board", "backlog")),
   // The runner calls check() then warn() per root; run the (possibly costly) project-gate
   // commands only in check so a Stop pays for them once, not twice. Warnings never depend on
   // gate execution, so runGates:false loses nothing.

package/spec-bridge/gates/cli.mjs

@@ -13,7 +13,7 @@
 //                                  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 { findRootUpwards, hasAnyChild } from "../lib/project-root.mjs";
 import { checkBridge, loadBridgeConfig, planBridge, verifyBridge, vocabularyProfile } from "./bridge.mjs";
 
 const [cmd, target] = process.argv.slice(2);
@@ -24,7 +24,9 @@ if (!cmd || !target) {
 
 if (cmd === "state") {
   // Honor the project's .spec-bridge.json (strictDone) — same config checkBridge uses.
-  const root = findRootUpwards(resolve(target), hasChild("backlog"));
+  // hasAnyChild(".board", "backlog") in lockstep with bridgeGate.resolveRoots (bridge.mjs) —
+  // the hook and this CLI must never disagree about what a project is (spec 053 R2).
+  const root = findRootUpwards(resolve(target), hasAnyChild(".board", "backlog"));
   const requireAnalysis = root ? loadBridgeConfig(root).strictDone === true : false;
   console.log(JSON.stringify(deriveSpecState(target, { requireAnalysis }), null, 2));
 } else if (cmd === "links") {

package/spec-bridge/lib/project-root.mjs

@@ -14,6 +14,14 @@ export function hasChild(name) {
   return (dir) => existsSync(join(dir, name));
 }
 
+/** Combine markers: true when ANY of `names` exists as a child. One definition composed
+ *  from `hasChild`, so every caller that needs "either sentinel marks a project" (e.g. the
+ *  spec-bridge Stop hook and its CLI, which must never disagree about what a project is)
+ *  shares it instead of duplicating the predicate inline at each call site. */
+export function hasAnyChild(...names) {
+  return (dir) => names.some((n) => hasChild(n)(dir));
+}
+
 /**
  * Walk up from `startDir` until `markerFn(dir)` is truthy. Returns the matching
  * directory (absolute) or null if the filesystem root is reached without a match.