@praxisflux/gates 0.53.0 → 0.55.0

package/codebase-to-course/lib/spec-derive.mjs

@@ -58,7 +58,12 @@ export function coarseStatus(stage) {
 }
 
 const PHASE_HEADING = /^##\s+(.+?)\s*$/;
-const TASK_LINE = /^\s*[-*]\s+\[([ xX])\]\s+\S/;
+// Captures the checkbox char AND the box's trailing descriptive text. The matched-line SET is
+// identical to the old `/^\s*[-*]\s+\[([ xX])\]\s+\S/` (both require a non-space after the box;
+// per-line matching, so `.*?\s*$` always closes over the remainder) — this only adds capture
+// group 2, so parseTasks() output is byte-identical. The text feeds spec 050's blocking message
+// (AC #1: name the phase, the box, and the failing gate).
+const TASK_LINE = /^\s*[-*]\s+\[([ xX])\]\s+(\S.*?)\s*$/;
 
 /** Strip Spec Kit's "Phase 3.1:" style prefix so phase names read as AC labels ("Setup"). */
 function phaseName(heading) {
@@ -66,34 +71,59 @@ function phaseName(heading) {
 }
 
 /**
- * Pure parser: tasks.md markdown -> [{ name, done, total }] in document order.
- * A phase is a `##` heading; a task is any checkbox list line under it. Checkbox lines before
- * the first heading are collected under a synthetic "Tasks" phase. Phases with no checkbox
- * lines (e.g. a "Dependencies" notes section) are dropped.
+ * Rich internal parse: tasks.md markdown -> [{ name, done, total, boxes }] in document order,
+ * where boxes is [{ checked, text }] for every checkbox line under the phase. A phase is a `##`
+ * heading; a task is any checkbox list line under it. Checkbox lines before the first heading
+ * are collected under a synthetic "Tasks" phase. Phases with no checkbox lines (e.g. a
+ * "Dependencies" notes section) are dropped. The two exported views below are pure projections
+ * of this one pass, so they can never disagree.
  */
-export function parseTasks(markdown) {
+function parsePhaseList(markdown) {
   const phases = [];
   let current = null;
   for (const line of String(markdown ?? "").split("\n")) {
     const heading = line.match(PHASE_HEADING);
     if (heading) {
-      current = { name: phaseName(heading[1]), done: 0, total: 0 };
+      current = { name: phaseName(heading[1]), done: 0, total: 0, boxes: [] };
       phases.push(current);
       continue;
     }
     const task = line.match(TASK_LINE);
     if (task) {
       if (!current) {
-        current = { name: "Tasks", done: 0, total: 0 };
+        current = { name: "Tasks", done: 0, total: 0, boxes: [] };
         phases.push(current);
       }
       current.total += 1;
-      if (task[1] !== " ") current.done += 1;
+      const checked = task[1] !== " ";
+      if (checked) current.done += 1;
+      current.boxes.push({ checked, text: task[2] });
     }
   }
   return phases.filter((p) => p.total > 0);
 }
 
+/**
+ * Pure parser: tasks.md markdown -> [{ name, done, total }] in document order. The stable
+ * shape both the gate and the sync planner consume; deliberately carries no box text (see
+ * parseTaskBoxes for that). Byte-identical to its long-standing output.
+ */
+export function parseTasks(markdown) {
+  return parsePhaseList(markdown).map(({ name, done, total }) => ({ name, done, total }));
+}
+
+/**
+ * The additive companion view (spec 050): tasks.md markdown -> [{ name, boxes }] where boxes is
+ * [{ checked, text }] per checkbox line, in document order. Kept SEPARATE from parseTasks rather
+ * than widening its objects, because existing tests pin parseTasks/deriveSpecState().phases to
+ * the exact { name, done, total } shape — a `boxes` key on those objects would break them. The
+ * spec-bridge project-gate check reads this (via deriveSpecState().phaseBoxes) to name the
+ * ticked box a red gate stands over.
+ */
+export function parseTaskBoxes(markdown) {
+  return parsePhaseList(markdown).map(({ name, boxes }) => ({ name, boxes }));
+}
+
 /** "Setup: 2/2 · Core: 4/7" — one segment per phase, empty string when there are no tasks. */
 export function progressNote(phases) {
   return phases.map((p) => `${p.name}: ${p.done}/${p.total}`).join(" · ");
@@ -121,7 +151,9 @@ export function deriveSpecState(specDir, { requireAnalysis = false } = {}) {
     try { return has(name) ? readFileSync(join(specDir, name), "utf8") : ""; } catch { return ""; }
   };
 
-  const phases = parseTasks(read("tasks.md"));
+  const tasksMd = read("tasks.md");
+  const phases = parseTasks(tasksMd);
+  const phaseBoxes = parseTaskBoxes(tasksMd); // additive: per-box { checked, text }, same pass
   const tasksTotal = phases.reduce((n, p) => n + p.total, 0);
   const tasksDone = phases.reduce((n, p) => n + p.done, 0);
 
@@ -149,6 +181,9 @@ export function deriveSpecState(specDir, { requireAnalysis = false } = {}) {
 
   return {
     status: coarseStatus(stage), stage, phases, tasksDone, tasksTotal,
+    // phaseBoxes is strictly additive — .phases keeps its { name, done, total } shape (pinned by
+    // existing tests); phaseBoxes carries the box text spec 050's message needs, nothing more.
+    phaseBoxes,
     progressNote: progressNote(phases),
     analysis: { required: requireAnalysis, present: analysisPresent, criticals },
   };

package/grounding-wiki/lib/spec-derive.mjs

@@ -58,7 +58,12 @@ export function coarseStatus(stage) {
 }
 
 const PHASE_HEADING = /^##\s+(.+?)\s*$/;
-const TASK_LINE = /^\s*[-*]\s+\[([ xX])\]\s+\S/;
+// Captures the checkbox char AND the box's trailing descriptive text. The matched-line SET is
+// identical to the old `/^\s*[-*]\s+\[([ xX])\]\s+\S/` (both require a non-space after the box;
+// per-line matching, so `.*?\s*$` always closes over the remainder) — this only adds capture
+// group 2, so parseTasks() output is byte-identical. The text feeds spec 050's blocking message
+// (AC #1: name the phase, the box, and the failing gate).
+const TASK_LINE = /^\s*[-*]\s+\[([ xX])\]\s+(\S.*?)\s*$/;
 
 /** Strip Spec Kit's "Phase 3.1:" style prefix so phase names read as AC labels ("Setup"). */
 function phaseName(heading) {
@@ -66,34 +71,59 @@ function phaseName(heading) {
 }
 
 /**
- * Pure parser: tasks.md markdown -> [{ name, done, total }] in document order.
- * A phase is a `##` heading; a task is any checkbox list line under it. Checkbox lines before
- * the first heading are collected under a synthetic "Tasks" phase. Phases with no checkbox
- * lines (e.g. a "Dependencies" notes section) are dropped.
+ * Rich internal parse: tasks.md markdown -> [{ name, done, total, boxes }] in document order,
+ * where boxes is [{ checked, text }] for every checkbox line under the phase. A phase is a `##`
+ * heading; a task is any checkbox list line under it. Checkbox lines before the first heading
+ * are collected under a synthetic "Tasks" phase. Phases with no checkbox lines (e.g. a
+ * "Dependencies" notes section) are dropped. The two exported views below are pure projections
+ * of this one pass, so they can never disagree.
  */
-export function parseTasks(markdown) {
+function parsePhaseList(markdown) {
   const phases = [];
   let current = null;
   for (const line of String(markdown ?? "").split("\n")) {
     const heading = line.match(PHASE_HEADING);
     if (heading) {
-      current = { name: phaseName(heading[1]), done: 0, total: 0 };
+      current = { name: phaseName(heading[1]), done: 0, total: 0, boxes: [] };
       phases.push(current);
       continue;
     }
     const task = line.match(TASK_LINE);
     if (task) {
       if (!current) {
-        current = { name: "Tasks", done: 0, total: 0 };
+        current = { name: "Tasks", done: 0, total: 0, boxes: [] };
         phases.push(current);
       }
       current.total += 1;
-      if (task[1] !== " ") current.done += 1;
+      const checked = task[1] !== " ";
+      if (checked) current.done += 1;
+      current.boxes.push({ checked, text: task[2] });
     }
   }
   return phases.filter((p) => p.total > 0);
 }
 
+/**
+ * Pure parser: tasks.md markdown -> [{ name, done, total }] in document order. The stable
+ * shape both the gate and the sync planner consume; deliberately carries no box text (see
+ * parseTaskBoxes for that). Byte-identical to its long-standing output.
+ */
+export function parseTasks(markdown) {
+  return parsePhaseList(markdown).map(({ name, done, total }) => ({ name, done, total }));
+}
+
+/**
+ * The additive companion view (spec 050): tasks.md markdown -> [{ name, boxes }] where boxes is
+ * [{ checked, text }] per checkbox line, in document order. Kept SEPARATE from parseTasks rather
+ * than widening its objects, because existing tests pin parseTasks/deriveSpecState().phases to
+ * the exact { name, done, total } shape — a `boxes` key on those objects would break them. The
+ * spec-bridge project-gate check reads this (via deriveSpecState().phaseBoxes) to name the
+ * ticked box a red gate stands over.
+ */
+export function parseTaskBoxes(markdown) {
+  return parsePhaseList(markdown).map(({ name, boxes }) => ({ name, boxes }));
+}
+
 /** "Setup: 2/2 · Core: 4/7" — one segment per phase, empty string when there are no tasks. */
 export function progressNote(phases) {
   return phases.map((p) => `${p.name}: ${p.done}/${p.total}`).join(" · ");
@@ -121,7 +151,9 @@ export function deriveSpecState(specDir, { requireAnalysis = false } = {}) {
     try { return has(name) ? readFileSync(join(specDir, name), "utf8") : ""; } catch { return ""; }
   };
 
-  const phases = parseTasks(read("tasks.md"));
+  const tasksMd = read("tasks.md");
+  const phases = parseTasks(tasksMd);
+  const phaseBoxes = parseTaskBoxes(tasksMd); // additive: per-box { checked, text }, same pass
   const tasksTotal = phases.reduce((n, p) => n + p.total, 0);
   const tasksDone = phases.reduce((n, p) => n + p.done, 0);
 
@@ -149,6 +181,9 @@ export function deriveSpecState(specDir, { requireAnalysis = false } = {}) {
 
   return {
     status: coarseStatus(stage), stage, phases, tasksDone, tasksTotal,
+    // phaseBoxes is strictly additive — .phases keeps its { name, done, total } shape (pinned by
+    // existing tests); phaseBoxes carries the box text spec 050's message needs, nothing more.
+    phaseBoxes,
     progressNote: progressNote(phases),
     analysis: { required: requireAnalysis, present: analysisPresent, criticals },
   };

package/lib/spec-derive.mjs

@@ -58,7 +58,12 @@ export function coarseStatus(stage) {
 }
 
 const PHASE_HEADING = /^##\s+(.+?)\s*$/;
-const TASK_LINE = /^\s*[-*]\s+\[([ xX])\]\s+\S/;
+// Captures the checkbox char AND the box's trailing descriptive text. The matched-line SET is
+// identical to the old `/^\s*[-*]\s+\[([ xX])\]\s+\S/` (both require a non-space after the box;
+// per-line matching, so `.*?\s*$` always closes over the remainder) — this only adds capture
+// group 2, so parseTasks() output is byte-identical. The text feeds spec 050's blocking message
+// (AC #1: name the phase, the box, and the failing gate).
+const TASK_LINE = /^\s*[-*]\s+\[([ xX])\]\s+(\S.*?)\s*$/;
 
 /** Strip Spec Kit's "Phase 3.1:" style prefix so phase names read as AC labels ("Setup"). */
 function phaseName(heading) {
@@ -66,34 +71,59 @@ function phaseName(heading) {
 }
 
 /**
- * Pure parser: tasks.md markdown -> [{ name, done, total }] in document order.
- * A phase is a `##` heading; a task is any checkbox list line under it. Checkbox lines before
- * the first heading are collected under a synthetic "Tasks" phase. Phases with no checkbox
- * lines (e.g. a "Dependencies" notes section) are dropped.
+ * Rich internal parse: tasks.md markdown -> [{ name, done, total, boxes }] in document order,
+ * where boxes is [{ checked, text }] for every checkbox line under the phase. A phase is a `##`
+ * heading; a task is any checkbox list line under it. Checkbox lines before the first heading
+ * are collected under a synthetic "Tasks" phase. Phases with no checkbox lines (e.g. a
+ * "Dependencies" notes section) are dropped. The two exported views below are pure projections
+ * of this one pass, so they can never disagree.
  */
-export function parseTasks(markdown) {
+function parsePhaseList(markdown) {
   const phases = [];
   let current = null;
   for (const line of String(markdown ?? "").split("\n")) {
     const heading = line.match(PHASE_HEADING);
     if (heading) {
-      current = { name: phaseName(heading[1]), done: 0, total: 0 };
+      current = { name: phaseName(heading[1]), done: 0, total: 0, boxes: [] };
       phases.push(current);
       continue;
     }
     const task = line.match(TASK_LINE);
     if (task) {
       if (!current) {
-        current = { name: "Tasks", done: 0, total: 0 };
+        current = { name: "Tasks", done: 0, total: 0, boxes: [] };
         phases.push(current);
       }
       current.total += 1;
-      if (task[1] !== " ") current.done += 1;
+      const checked = task[1] !== " ";
+      if (checked) current.done += 1;
+      current.boxes.push({ checked, text: task[2] });
     }
   }
   return phases.filter((p) => p.total > 0);
 }
 
+/**
+ * Pure parser: tasks.md markdown -> [{ name, done, total }] in document order. The stable
+ * shape both the gate and the sync planner consume; deliberately carries no box text (see
+ * parseTaskBoxes for that). Byte-identical to its long-standing output.
+ */
+export function parseTasks(markdown) {
+  return parsePhaseList(markdown).map(({ name, done, total }) => ({ name, done, total }));
+}
+
+/**
+ * The additive companion view (spec 050): tasks.md markdown -> [{ name, boxes }] where boxes is
+ * [{ checked, text }] per checkbox line, in document order. Kept SEPARATE from parseTasks rather
+ * than widening its objects, because existing tests pin parseTasks/deriveSpecState().phases to
+ * the exact { name, done, total } shape — a `boxes` key on those objects would break them. The
+ * spec-bridge project-gate check reads this (via deriveSpecState().phaseBoxes) to name the
+ * ticked box a red gate stands over.
+ */
+export function parseTaskBoxes(markdown) {
+  return parsePhaseList(markdown).map(({ name, boxes }) => ({ name, boxes }));
+}
+
 /** "Setup: 2/2 · Core: 4/7" — one segment per phase, empty string when there are no tasks. */
 export function progressNote(phases) {
   return phases.map((p) => `${p.name}: ${p.done}/${p.total}`).join(" · ");
@@ -121,7 +151,9 @@ export function deriveSpecState(specDir, { requireAnalysis = false } = {}) {
     try { return has(name) ? readFileSync(join(specDir, name), "utf8") : ""; } catch { return ""; }
   };
 
-  const phases = parseTasks(read("tasks.md"));
+  const tasksMd = read("tasks.md");
+  const phases = parseTasks(tasksMd);
+  const phaseBoxes = parseTaskBoxes(tasksMd); // additive: per-box { checked, text }, same pass
   const tasksTotal = phases.reduce((n, p) => n + p.total, 0);
   const tasksDone = phases.reduce((n, p) => n + p.done, 0);
 
@@ -149,6 +181,9 @@ export function deriveSpecState(specDir, { requireAnalysis = false } = {}) {
 
   return {
     status: coarseStatus(stage), stage, phases, tasksDone, tasksTotal,
+    // phaseBoxes is strictly additive — .phases keeps its { name, done, total } shape (pinned by
+    // existing tests); phaseBoxes carries the box text spec 050's message needs, nothing more.
+    phaseBoxes,
     progressNote: progressNote(phases),
     analysis: { required: requireAnalysis, present: analysisPresent, criticals },
   };

package/package.json

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

@@ -20,6 +20,7 @@
 
 import { existsSync, readdirSync, 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";
 
@@ -83,6 +84,177 @@ export function vocabularyProfile(config) {
   return { names, cover };
 }
 
+/**
+ * The opt-in project-gate declaration, normalized. `.spec-bridge.json` may carry
+ *   { "projectGates": {
+ *       "required":          [ { "name": "tests",     "command": ["node", "--test"] } ],
+ *       "redByConstruction": [ { "name": "freshness", "command": ["node", "grounding-wiki/gates/cli.mjs", "freshness", ".", "docs/wiki"] } ]
+ *   } }
+ * declaring which host gates must be green before a linked spec may be Done-eligible
+ * (`required`) and which a mid-PR phase MAY leave red — the freshness gate between a
+ * source edit and its re-pin commit (`redByConstruction`). "Red until the re-pin commit"
+ * is not a property this checker can see, so the host STATES it; it is data the check
+ * reads, never prose (spec 050 R1).
+ *
+ * This mirrors vocabularyProfile exactly: returns null — behavior bit-for-bit unchanged,
+ * every existing message and plan byte-identical — unless at least one validly-shaped gate
+ * entry exists. A valid entry is `{ name: <non-empty string>, command: <non-empty array of
+ * non-empty strings> }`; malformed entries are dropped silently (unknown keys / bad values
+ * ignored, never guessed), and if nothing valid survives in either bucket the whole opt-in
+ * is null. `command` is an argv array by design (never a shell string): declared commands
+ * run via spawnSync with shell:false, so there is no interpolation and no injection surface
+ * (spec 050 R4; the exec itself lands in phase 2). The field case this guards: 2026-08-01,
+ * spec 048 phases 1-2, "254 pass, 0 fail" reported and a tasks.md box ticked while four wiki
+ * notes were staled and the freshness gate was red.
+ *
+ * Returns { required, redByConstruction } — each an array of { name, command } with command
+ * a string[] argv; an absent-but-other-present bucket is []. Null iff no valid entry at all.
+ */
+export function projectGatesProfile(config) {
+  const raw = config?.projectGates;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const parseBucket = (value) => {
+    if (!Array.isArray(value)) return [];
+    const out = [];
+    for (const entry of value) {
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+      const name = typeof entry.name === "string" ? entry.name.trim() : "";
+      // A validly-shaped entry needs a name AND an argv that is a non-empty array of
+      // non-empty strings. A string `command` is NOT accepted — no safe split exists, and
+      // the whole point is to never touch a shell. A malformed element (empty/non-string)
+      // fails the whole entry rather than being silently repaired; drop it, never guess.
+      const cmd = entry.command;
+      const argvOk = Array.isArray(cmd) && cmd.length > 0 && cmd.every((a) => typeof a === "string" && a.trim());
+      if (!name || !argvOk) continue;
+      out.push({ name, command: cmd });
+    }
+    return out;
+  };
+  const required = parseBucket(raw.required);
+  const redByConstruction = parseBucket(raw.redByConstruction);
+  if (required.length === 0 && redByConstruction.length === 0) return null;
+  return { required, redByConstruction };
+}
+
+/* ── project gates: running the declared commands and turning red into findings ────────────
+ *
+ * spec 050. The field case this exists to stop: 2026-08-01, spec 048 phases 1-2, a dispatched
+ * implementer reported "node --test — 254 pass, 0 fail" and ticked its tasks.md box while four
+ * wiki notes were staled and the freshness gate was red; the next phase re-ran the suite and
+ * found 258/259. A ticked tasks.md checkbox IS status, and a status can never exceed the
+ * artifacts that prove it — so a ticked box standing over a red project gate blocks.
+ *
+ * One pure evaluator (evaluateProjectGates), two entry points that differ only in WHEN and
+ * WHICH buckets they run: the Stop hook (checkBridge) fires only at Done-eligible; the CLI
+ * `verify` verb (verifyBridge) covers the mid-PR case. Command execution is injected so tests
+ * drive every branch — green, red, spawn-failure, timeout — without a subprocess. */
+
+/** Per-command wall-clock ceiling. `node --test` here is ~5.7s (spec 050 R4, measured); 2 min is
+ *  ample headroom while still boxing a hung gate so it cannot wedge every Stop (fail-closed). */
+export const GATE_TIMEOUT_MS = 120000;
+
+/**
+ * Run ONE declared gate command as a subprocess and classify the outcome. argv only, shell:false
+ * (no interpolation, no injection surface — spec 050 R4); cwd is the project root. Returns
+ *   { ok: true }                          — exit 0, green
+ *   { ok: false, kind: "red", reason }    — nonzero exit / killed by signal
+ *   { ok: false, kind: "error", reason }  — could not execute at all (ENOENT, spawn error)
+ *   { ok: false, kind: "timeout", timeoutMs } — exceeded the time box
+ * "error" and "timeout" are the fail-closed cases: a command that cannot run is NEVER green (it
+ * is the gate-runner contract applied one level down — a crash is a blocking problem, not a
+ * silent pass). Sets SPEC_BRIDGE_GATE_ACTIVE on the child env so a declared command that itself
+ * invokes the bridge short-circuits instead of recursing (see checkBridge/verifyBridge).
+ */
+export function runGateCommand(command, { cwd, timeoutMs = GATE_TIMEOUT_MS, spawn = spawnSync } = {}) {
+  let res;
+  try {
+    res = spawn(command[0], command.slice(1), {
+      cwd, timeout: timeoutMs, shell: false, encoding: "utf8",
+      env: { ...process.env, SPEC_BRIDGE_GATE_ACTIVE: "1" },
+    });
+  } catch (e) {
+    return { ok: false, kind: "error", reason: e.code || e.message };
+  }
+  if (res.error) {
+    if (res.error.code === "ETIMEDOUT") return { ok: false, kind: "timeout", timeoutMs };
+    return { ok: false, kind: "error", reason: res.error.code || res.error.message };
+  }
+  if (res.status === 0) return { ok: true };
+  if (res.status == null) return { ok: false, kind: "red", reason: res.signal ? `killed by ${res.signal}` : "no exit status" };
+  return { ok: false, kind: "red", reason: `exited ${res.status}` };
+}
+
+/** The last ticked box in document order — the tick that (in sequence) claimed the most, and so
+ *  the box a red gate most directly stands over. Null when nothing is ticked. */
+function lastTickedBox(phaseBoxes) {
+  let witness = null;
+  for (const p of phaseBoxes || [])
+    for (const b of p.boxes || [])
+      if (b.checked) witness = { phase: p.name, box: b.text };
+  return witness;
+}
+
+/** Flatten a profile into the ordered { name, command, bucket } gates for the named buckets. */
+function gatesFor(profile, buckets) {
+  const out = [];
+  for (const bucket of buckets)
+    for (const g of profile[bucket] || []) out.push({ ...g, bucket });
+  return out;
+}
+
+/**
+ * Memoize a gate runner by its argv so each DISTINCT declared command runs at most once per
+ * bridge invocation. Declared gates are project-wide, not per-spec — the same `node --test` is
+ * the `tests` gate for every linked spec — so its RESULT is computed once and shared across all
+ * of them (spec 050 defect 2, Phase 5). Findings are still built per spec (each names its own
+ * phase/box/gate); only the gate result is shared, never the finding. Before this, checkBridge
+ * ran the full gate set once per Done-eligible spec — 49× on this repo's own board, ~358s — which
+ * defeated R4's cost argument the moment more than one spec was Done-eligible.
+ */
+function memoizeRun(rawRun) {
+  const cache = new Map();
+  return (command) => {
+    const key = command.join("");
+    if (!cache.has(key)) cache.set(key, rawRun(command));
+    return cache.get(key);
+  };
+}
+
+/** The human clause for why a gate isn't green — honest about red vs. couldn't-run vs. timed-out. */
+function gateReason(result) {
+  if (result.kind === "timeout") return `timed out after ${result.timeoutMs}ms and is treated as failed, never green`;
+  if (result.kind === "error") return `could not be executed (${result.reason}) and is treated as failed, never green`;
+  return `is red (${result.reason})`;
+}
+
+/** The blocking finding: names the phase, the box, and the failing gate (spec 050 AC #1). */
+function projectGateProblem({ id, specDir, witness, gate, result }) {
+  const where = witness
+    ? `phase "${witness.phase}", box "${witness.box}" is ticked, but `
+    : "a ticked box stands over a gate that ";
+  const label = gate.bucket === "redByConstruction" ? "red-by-construction gate" : "required gate";
+  return `[spec-bridge] ${id} · ${specDir}: ${where}the ${label} "${gate.name}" ${gateReason(result)}. ` +
+    `A ticked tasks.md checkbox cannot outrun a red project gate — make the gate pass or set the box back.`;
+}
+
+/**
+ * Pure evaluator (spec 050): run the given gates for ONE linked spec, return one blocking finding
+ * per gate that is not green. `link` is { id, specDir, phaseBoxes }; `gates` the ordered flattened
+ * gate list (the caller picks the buckets — the two entry points differ there); `run` executes one
+ * command and returns runGateCommand's shape (injected so tests need no subprocess). The witness box
+ * is computed once from phaseBoxes so every finding names it.
+ */
+export function evaluateProjectGates({ id, specDir, phaseBoxes }, gates, run) {
+  const witness = lastTickedBox(phaseBoxes);
+  const problems = [];
+  for (const gate of gates) {
+    const result = run(gate.command);
+    if (result.ok) continue;
+    problems.push(projectGateProblem({ id, specDir, witness, gate, result }));
+  }
+  return problems;
+}
+
 const MARKER = /^Spec:\s*(\S+?)\/?\s*$/m;
 const RANK = { "to do": 0, "in progress": 1, done: 2 };
 const DERIVED_RANK = { [STATUS.TODO]: 0, [STATUS.IN_PROGRESS]: 1, [STATUS.DONE_ELIGIBLE]: 2 };
@@ -170,13 +342,25 @@ function shortfall(root, specDir, derived) {
  *   problems — blocking messages, one per "exceeds"
  *   warnings — non-blocking messages, one per "lags"
  */
-export function checkBridge(root) {
+export function checkBridge(root, { runGates = true, run } = {}) {
   const links = [];
   const problems = [];
   const warnings = [];
   const config = loadBridgeConfig(root);
   const requireAnalysis = config.strictDone === true;
   const profile = vocabularyProfile(config);
+  const gatesProfile = projectGatesProfile(config);
+  // 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
+  // re-invokes the bridge short-circuits instead of forking forever (spec 050 R4). But that guard
+  // exists to stop the DEFAULT runner from spawning real subprocesses — an injected `run` is a
+  // test double that spawns nothing, so it MUST bypass the guard (spec 050 defect 1, Phase 5).
+  // Without this bypass the bridge's own dogfood reddens its `tests` gate: `node --test` runs the
+  // Phase-3 suite with the flag set, and every injected-run test there fail-closes to [].
+  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)) {
     const derived = deriveSpecState(join(root, task.specDir), { requireAnalysis });
     // Opted-in boards are judged on the stage ladder against their own status names;
@@ -213,10 +397,62 @@ export function checkBridge(root) {
           : `unresolved CRITICAL finding(s) in analysis.md: ${a.criticals.join(" | ")}`)
       );
     }
+
+    // Project-gate check (spec 050 R4): execute declared gates ONLY when the spec is
+    // Done-eligible — the one bounded moment a red gate under a ticked box changes an outcome,
+    // so ordinary turns pay zero subprocess cost. At Done-eligible the mid-PR window has closed
+    // (every box, including the re-pin box, is ticked), so BOTH buckets must be green: required,
+    // AND redByConstruction — its "allowed red mid-PR" license has expired now that its re-pin
+    // was claimed done. Any red / unrunnable / timed-out gate is a blocking finding.
+    if (execGates && derived.status === STATUS.DONE_ELIGIBLE) {
+      const gates = gatesFor(gatesProfile, ["required", "redByConstruction"]);
+      problems.push(
+        ...evaluateProjectGates(
+          { id: task.id, specDir: task.specDir, phaseBoxes: derived.phaseBoxes }, gates, runOne)
+      );
+    }
   }
   return { links, problems, warnings };
 }
 
+/**
+ * The `verify` entry point (spec 050 R4): the mid-PR counterpart to the Stop hook. For every
+ * linked spec that has at least one ticked box — a box claiming greenness — run the declared
+ * gates and return the blocking findings. A Done-eligible spec is held to BOTH buckets (as the
+ * Stop hook does); a mid-PR spec to `required` only, because redByConstruction gates are
+ * legitimately red between a source edit and its re-pin commit. Shares evaluateProjectGates, so
+ * it and the Stop hook agree by construction. Read-only like the rest of gates/: it runs the
+ * host's declared subprocesses but writes nothing itself. Injectable `run` for tests.
+ */
+export function verifyBridge(root, { run } = {}) {
+  const problems = [];
+  const config = loadBridgeConfig(root);
+  const gatesProfile = projectGatesProfile(config);
+  if (!gatesProfile) return problems; // no opt-in → nothing to do
+  // Reentrancy guard (spec 050 defect 1, Phase 5): a spawned gate command that re-invokes the
+  // bridge with the DEFAULT runner short-circuits so it can't fork forever; an injected `run` is
+  // a test double that spawns nothing, so it bypasses the guard.
+  const injected = run !== undefined;
+  if (!injected && process.env.SPEC_BRIDGE_GATE_ACTIVE === "1") return problems;
+  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)) {
+    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
+    const buckets = derived.status === STATUS.DONE_ELIGIBLE
+      ? ["required", "redByConstruction"]
+      : ["required"];
+    const gates = gatesFor(gatesProfile, buckets);
+    problems.push(
+      ...evaluateProjectGates(
+        { id: task.id, specDir: task.specDir, phaseBoxes: derived.phaseBoxes }, gates, runOne)
+    );
+  }
+  return problems;
+}
+
 /* ── plan: the exact backlog edits that reconcile the board ────────────── */
 
 const PHASE_PREFIX = "Spec phase: ";
@@ -321,6 +557,9 @@ export function planBridge(root) {
 export const bridgeGate = {
   name: "spec-bridge",
   resolveRoots: (startDir) => findRootsDownwards(startDir, hasChild("backlog")),
-  check: (root) => checkBridge(root).problems,
-  warn: (root) => checkBridge(root).warnings,
+  // 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.
+  check: (root) => checkBridge(root, { runGates: true }).problems,
+  warn: (root) => checkBridge(root, { runGates: false }).warnings,
 };

package/spec-bridge/gates/cli.mjs

@@ -4,17 +4,21 @@
 //   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 verify <root>     run declared project gates against ticked boxes (spec 050);
+//                                  exit 1 if any ticked box stands over a red/unrunnable gate.
+//                                  The mid-PR counterpart to the Done-eligible Stop-hook check —
+//                                  the sweep's per-phase loop and CI call it.
 //   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, planBridge, vocabularyProfile } from "./bridge.mjs";
+import { checkBridge, loadBridgeConfig, planBridge, verifyBridge, vocabularyProfile } from "./bridge.mjs";
 
 const [cmd, target] = process.argv.slice(2);
 if (!cmd || !target) {
-  console.error("usage: cli.mjs state <specDir> | links <root> | check <root> | plan <root>");
+  console.error("usage: cli.mjs state <specDir> | links <root> | check <root> | verify <root> | plan <root>");
   process.exit(2);
 }
 
@@ -34,6 +38,14 @@ if (cmd === "state") {
     process.exit(1);
   }
   console.log(`spec-bridge ok: ${links.length} linked task(s), none exceed their artifacts`);
+} else if (cmd === "verify") {
+  const problems = verifyBridge(target);
+  if (problems.length) {
+    console.log(`\nGATE FAILED (${problems.length} issue(s)):`);
+    for (const p of problems) console.log(`  - ${p}`);
+    process.exit(1);
+  }
+  console.log("spec-bridge verify ok: every ticked box's declared project gates are green");
 } else if (cmd === "plan") {
   const { commands, skipped } = planBridge(target);
   // Name the vocabulary the board actually speaks: the opted-in phase-level names when

package/spec-bridge/lib/spec-derive.mjs

@@ -58,7 +58,12 @@ export function coarseStatus(stage) {
 }
 
 const PHASE_HEADING = /^##\s+(.+?)\s*$/;
-const TASK_LINE = /^\s*[-*]\s+\[([ xX])\]\s+\S/;
+// Captures the checkbox char AND the box's trailing descriptive text. The matched-line SET is
+// identical to the old `/^\s*[-*]\s+\[([ xX])\]\s+\S/` (both require a non-space after the box;
+// per-line matching, so `.*?\s*$` always closes over the remainder) — this only adds capture
+// group 2, so parseTasks() output is byte-identical. The text feeds spec 050's blocking message
+// (AC #1: name the phase, the box, and the failing gate).
+const TASK_LINE = /^\s*[-*]\s+\[([ xX])\]\s+(\S.*?)\s*$/;
 
 /** Strip Spec Kit's "Phase 3.1:" style prefix so phase names read as AC labels ("Setup"). */
 function phaseName(heading) {
@@ -66,34 +71,59 @@ function phaseName(heading) {
 }
 
 /**
- * Pure parser: tasks.md markdown -> [{ name, done, total }] in document order.
- * A phase is a `##` heading; a task is any checkbox list line under it. Checkbox lines before
- * the first heading are collected under a synthetic "Tasks" phase. Phases with no checkbox
- * lines (e.g. a "Dependencies" notes section) are dropped.
+ * Rich internal parse: tasks.md markdown -> [{ name, done, total, boxes }] in document order,
+ * where boxes is [{ checked, text }] for every checkbox line under the phase. A phase is a `##`
+ * heading; a task is any checkbox list line under it. Checkbox lines before the first heading
+ * are collected under a synthetic "Tasks" phase. Phases with no checkbox lines (e.g. a
+ * "Dependencies" notes section) are dropped. The two exported views below are pure projections
+ * of this one pass, so they can never disagree.
  */
-export function parseTasks(markdown) {
+function parsePhaseList(markdown) {
   const phases = [];
   let current = null;
   for (const line of String(markdown ?? "").split("\n")) {
     const heading = line.match(PHASE_HEADING);
     if (heading) {
-      current = { name: phaseName(heading[1]), done: 0, total: 0 };
+      current = { name: phaseName(heading[1]), done: 0, total: 0, boxes: [] };
       phases.push(current);
       continue;
     }
     const task = line.match(TASK_LINE);
     if (task) {
       if (!current) {
-        current = { name: "Tasks", done: 0, total: 0 };
+        current = { name: "Tasks", done: 0, total: 0, boxes: [] };
         phases.push(current);
       }
       current.total += 1;
-      if (task[1] !== " ") current.done += 1;
+      const checked = task[1] !== " ";
+      if (checked) current.done += 1;
+      current.boxes.push({ checked, text: task[2] });
     }
   }
   return phases.filter((p) => p.total > 0);
 }
 
+/**
+ * Pure parser: tasks.md markdown -> [{ name, done, total }] in document order. The stable
+ * shape both the gate and the sync planner consume; deliberately carries no box text (see
+ * parseTaskBoxes for that). Byte-identical to its long-standing output.
+ */
+export function parseTasks(markdown) {
+  return parsePhaseList(markdown).map(({ name, done, total }) => ({ name, done, total }));
+}
+
+/**
+ * The additive companion view (spec 050): tasks.md markdown -> [{ name, boxes }] where boxes is
+ * [{ checked, text }] per checkbox line, in document order. Kept SEPARATE from parseTasks rather
+ * than widening its objects, because existing tests pin parseTasks/deriveSpecState().phases to
+ * the exact { name, done, total } shape — a `boxes` key on those objects would break them. The
+ * spec-bridge project-gate check reads this (via deriveSpecState().phaseBoxes) to name the
+ * ticked box a red gate stands over.
+ */
+export function parseTaskBoxes(markdown) {
+  return parsePhaseList(markdown).map(({ name, boxes }) => ({ name, boxes }));
+}
+
 /** "Setup: 2/2 · Core: 4/7" — one segment per phase, empty string when there are no tasks. */
 export function progressNote(phases) {
   return phases.map((p) => `${p.name}: ${p.done}/${p.total}`).join(" · ");
@@ -121,7 +151,9 @@ export function deriveSpecState(specDir, { requireAnalysis = false } = {}) {
     try { return has(name) ? readFileSync(join(specDir, name), "utf8") : ""; } catch { return ""; }
   };
 
-  const phases = parseTasks(read("tasks.md"));
+  const tasksMd = read("tasks.md");
+  const phases = parseTasks(tasksMd);
+  const phaseBoxes = parseTaskBoxes(tasksMd); // additive: per-box { checked, text }, same pass
   const tasksTotal = phases.reduce((n, p) => n + p.total, 0);
   const tasksDone = phases.reduce((n, p) => n + p.done, 0);
 
@@ -149,6 +181,9 @@ export function deriveSpecState(specDir, { requireAnalysis = false } = {}) {
 
   return {
     status: coarseStatus(stage), stage, phases, tasksDone, tasksTotal,
+    // phaseBoxes is strictly additive — .phases keeps its { name, done, total } shape (pinned by
+    // existing tests); phaseBoxes carries the box text spec 050's message needs, nothing more.
+    phaseBoxes,
     progressNote: progressNote(phases),
     analysis: { required: requireAnalysis, present: analysisPresent, criticals },
   };