@praxisflux/gates 0.17.0 → 0.18.0

package/README.md

@@ -43,6 +43,9 @@ Dependabot's `github-actions` ecosystem automates that.
 
 - **`spec-bridge`** — every Backlog task linked to a Spec Kit spec dir carries a status its
   spec artifacts prove (needs a `backlog/` dir; passes trivially with zero linked tasks).
+  The gate honors the checked repo's own `.spec-bridge.json`: `strictDone` (analyze-gated
+  Done) and `statusVocabulary` (opt-in phase-level status names, enforced at that finer
+  granularity). The contract for both lives in `spec-bridge/README.md`.
 - **`wiki-freshness`** — every `docs/wiki` note is fresh against its `verified_against` pin
   (needs full git history: `fetch-depth: 0`; a shallow clone fails with exactly that fix).
 - **`course`** — a built codebase-to-course course passes its output gate (self-contained,

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

@@ -13,6 +13,11 @@
 // "Done-eligible" deliberately isn't "Done": the sync skill may move the Backlog task to Done,
 // and the bridge gate treats a Done status without this derivation as a blocking problem.
 //
+// Every derivation also names a finer STAGE (specifying → planning → implementing →
+// validating → reviewing); the status above is a fixed collapse of it (coarseStatus). The
+// stage feeds the opt-in phase-level board vocabulary in gates/bridge.mjs and is purely
+// additive — nothing here behaves differently because of it.
+//
 // Strict mode ({ requireAnalysis: true }): checked boxes are necessary but weak proof, so
 // Done-eligible additionally requires an analysis report saved as analysis.md in the spec dir
 // (the durable artifact of /speckit.analyze — chat output doesn't count) with no unresolved
@@ -28,6 +33,30 @@ export const STATUS = {
   DONE_ELIGIBLE: "Done-eligible",
 };
 
+// The finer-grained lifecycle ladder underneath the 3-status vocabulary. Every derivation
+// also names the stage it is in; the 3 statuses are a fixed collapse of the 5 stages
+// (specifying → To Do; planning/implementing/validating → In Progress; reviewing →
+// Done-eligible), so the stage is strictly additive information — consumers that never look
+// at it see exactly the behavior above.
+export const STAGE = {
+  SPECIFYING: "specifying",     // no spec.md yet
+  PLANNING: "planning",         // spec.md present, no plan.md
+  IMPLEMENTING: "implementing", // plan.md present, work remaining outside the final phase
+  VALIDATING: "validating",     // only the final tasks.md phase still has unchecked work,
+                                //   or all boxes checked but strict-mode analysis pending
+  REVIEWING: "reviewing",       // everything proven — same state as Done-eligible
+};
+
+/** The stages in lifecycle order — the ranking the bridge gate compares against. */
+export const STAGES = [STAGE.SPECIFYING, STAGE.PLANNING, STAGE.IMPLEMENTING, STAGE.VALIDATING, STAGE.REVIEWING];
+
+/** The fixed collapse: stage → 3-status. */
+export function coarseStatus(stage) {
+  if (stage === STAGE.SPECIFYING) return STATUS.TODO;
+  if (stage === STAGE.REVIEWING) return STATUS.DONE_ELIGIBLE;
+  return STATUS.IN_PROGRESS;
+}
+
 const PHASE_HEADING = /^##\s+(.+?)\s*$/;
 const TASK_LINE = /^\s*[-*]\s+\[([ xX])\]\s+\S/;
 
@@ -100,15 +129,27 @@ export function deriveSpecState(specDir, { requireAnalysis = false } = {}) {
   const criticals = requireAnalysis && analysisPresent ? findCriticalFindings(read("analysis.md")) : [];
   const analysisOk = !requireAnalysis || (analysisPresent && criticals.length === 0);
 
-  let status = STATUS.TODO;
+  // Stage first, status as its fixed collapse — one ladder, two vocabularies. The stage
+  // rules refine "In Progress" without moving any 3-status boundary: Done-eligible is still
+  // exactly all-boxes-checked (+ clean analysis in strict mode), To Do is still no spec.md.
+  const allChecked = tasksTotal > 0 && tasksDone === tasksTotal;
+  let stage = STAGE.SPECIFYING;
   if (has("spec.md")) {
-    status = has("plan.md") && tasksTotal > 0 && tasksDone === tasksTotal && analysisOk
-      ? STATUS.DONE_ELIGIBLE
-      : STATUS.IN_PROGRESS;
+    if (!has("plan.md")) stage = STAGE.PLANNING;
+    else if (allChecked && analysisOk) stage = STAGE.REVIEWING;
+    else {
+      // Validating: the only unchecked work left sits in tasks.md's final phase (needs ≥2
+      // phases to mean anything), or every box is checked and only the strict-mode analysis
+      // artifact is outstanding. Anything earlier is implementing.
+      const earlierPhasesDone =
+        phases.length >= 2 && phases.slice(0, -1).every((p) => p.done === p.total);
+      stage = allChecked || earlierPhasesDone ? STAGE.VALIDATING : STAGE.IMPLEMENTING;
+    }
   }
 
   return {
-    status, phases, tasksDone, tasksTotal, progressNote: progressNote(phases),
+    status: coarseStatus(stage), stage, phases, tasksDone, tasksTotal,
+    progressNote: progressNote(phases),
     analysis: { required: requireAnalysis, present: analysisPresent, criticals },
   };
 }

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

@@ -13,6 +13,11 @@
 // "Done-eligible" deliberately isn't "Done": the sync skill may move the Backlog task to Done,
 // and the bridge gate treats a Done status without this derivation as a blocking problem.
 //
+// Every derivation also names a finer STAGE (specifying → planning → implementing →
+// validating → reviewing); the status above is a fixed collapse of it (coarseStatus). The
+// stage feeds the opt-in phase-level board vocabulary in gates/bridge.mjs and is purely
+// additive — nothing here behaves differently because of it.
+//
 // Strict mode ({ requireAnalysis: true }): checked boxes are necessary but weak proof, so
 // Done-eligible additionally requires an analysis report saved as analysis.md in the spec dir
 // (the durable artifact of /speckit.analyze — chat output doesn't count) with no unresolved
@@ -28,6 +33,30 @@ export const STATUS = {
   DONE_ELIGIBLE: "Done-eligible",
 };
 
+// The finer-grained lifecycle ladder underneath the 3-status vocabulary. Every derivation
+// also names the stage it is in; the 3 statuses are a fixed collapse of the 5 stages
+// (specifying → To Do; planning/implementing/validating → In Progress; reviewing →
+// Done-eligible), so the stage is strictly additive information — consumers that never look
+// at it see exactly the behavior above.
+export const STAGE = {
+  SPECIFYING: "specifying",     // no spec.md yet
+  PLANNING: "planning",         // spec.md present, no plan.md
+  IMPLEMENTING: "implementing", // plan.md present, work remaining outside the final phase
+  VALIDATING: "validating",     // only the final tasks.md phase still has unchecked work,
+                                //   or all boxes checked but strict-mode analysis pending
+  REVIEWING: "reviewing",       // everything proven — same state as Done-eligible
+};
+
+/** The stages in lifecycle order — the ranking the bridge gate compares against. */
+export const STAGES = [STAGE.SPECIFYING, STAGE.PLANNING, STAGE.IMPLEMENTING, STAGE.VALIDATING, STAGE.REVIEWING];
+
+/** The fixed collapse: stage → 3-status. */
+export function coarseStatus(stage) {
+  if (stage === STAGE.SPECIFYING) return STATUS.TODO;
+  if (stage === STAGE.REVIEWING) return STATUS.DONE_ELIGIBLE;
+  return STATUS.IN_PROGRESS;
+}
+
 const PHASE_HEADING = /^##\s+(.+?)\s*$/;
 const TASK_LINE = /^\s*[-*]\s+\[([ xX])\]\s+\S/;
 
@@ -100,15 +129,27 @@ export function deriveSpecState(specDir, { requireAnalysis = false } = {}) {
   const criticals = requireAnalysis && analysisPresent ? findCriticalFindings(read("analysis.md")) : [];
   const analysisOk = !requireAnalysis || (analysisPresent && criticals.length === 0);
 
-  let status = STATUS.TODO;
+  // Stage first, status as its fixed collapse — one ladder, two vocabularies. The stage
+  // rules refine "In Progress" without moving any 3-status boundary: Done-eligible is still
+  // exactly all-boxes-checked (+ clean analysis in strict mode), To Do is still no spec.md.
+  const allChecked = tasksTotal > 0 && tasksDone === tasksTotal;
+  let stage = STAGE.SPECIFYING;
   if (has("spec.md")) {
-    status = has("plan.md") && tasksTotal > 0 && tasksDone === tasksTotal && analysisOk
-      ? STATUS.DONE_ELIGIBLE
-      : STATUS.IN_PROGRESS;
+    if (!has("plan.md")) stage = STAGE.PLANNING;
+    else if (allChecked && analysisOk) stage = STAGE.REVIEWING;
+    else {
+      // Validating: the only unchecked work left sits in tasks.md's final phase (needs ≥2
+      // phases to mean anything), or every box is checked and only the strict-mode analysis
+      // artifact is outstanding. Anything earlier is implementing.
+      const earlierPhasesDone =
+        phases.length >= 2 && phases.slice(0, -1).every((p) => p.done === p.total);
+      stage = allChecked || earlierPhasesDone ? STAGE.VALIDATING : STAGE.IMPLEMENTING;
+    }
   }
 
   return {
-    status, phases, tasksDone, tasksTotal, progressNote: progressNote(phases),
+    status: coarseStatus(stage), stage, phases, tasksDone, tasksTotal,
+    progressNote: progressNote(phases),
     analysis: { required: requireAnalysis, present: analysisPresent, criticals },
   };
 }

package/lib/spec-derive.mjs

@@ -13,6 +13,11 @@
 // "Done-eligible" deliberately isn't "Done": the sync skill may move the Backlog task to Done,
 // and the bridge gate treats a Done status without this derivation as a blocking problem.
 //
+// Every derivation also names a finer STAGE (specifying → planning → implementing →
+// validating → reviewing); the status above is a fixed collapse of it (coarseStatus). The
+// stage feeds the opt-in phase-level board vocabulary in gates/bridge.mjs and is purely
+// additive — nothing here behaves differently because of it.
+//
 // Strict mode ({ requireAnalysis: true }): checked boxes are necessary but weak proof, so
 // Done-eligible additionally requires an analysis report saved as analysis.md in the spec dir
 // (the durable artifact of /speckit.analyze — chat output doesn't count) with no unresolved
@@ -28,6 +33,30 @@ export const STATUS = {
   DONE_ELIGIBLE: "Done-eligible",
 };
 
+// The finer-grained lifecycle ladder underneath the 3-status vocabulary. Every derivation
+// also names the stage it is in; the 3 statuses are a fixed collapse of the 5 stages
+// (specifying → To Do; planning/implementing/validating → In Progress; reviewing →
+// Done-eligible), so the stage is strictly additive information — consumers that never look
+// at it see exactly the behavior above.
+export const STAGE = {
+  SPECIFYING: "specifying",     // no spec.md yet
+  PLANNING: "planning",         // spec.md present, no plan.md
+  IMPLEMENTING: "implementing", // plan.md present, work remaining outside the final phase
+  VALIDATING: "validating",     // only the final tasks.md phase still has unchecked work,
+                                //   or all boxes checked but strict-mode analysis pending
+  REVIEWING: "reviewing",       // everything proven — same state as Done-eligible
+};
+
+/** The stages in lifecycle order — the ranking the bridge gate compares against. */
+export const STAGES = [STAGE.SPECIFYING, STAGE.PLANNING, STAGE.IMPLEMENTING, STAGE.VALIDATING, STAGE.REVIEWING];
+
+/** The fixed collapse: stage → 3-status. */
+export function coarseStatus(stage) {
+  if (stage === STAGE.SPECIFYING) return STATUS.TODO;
+  if (stage === STAGE.REVIEWING) return STATUS.DONE_ELIGIBLE;
+  return STATUS.IN_PROGRESS;
+}
+
 const PHASE_HEADING = /^##\s+(.+?)\s*$/;
 const TASK_LINE = /^\s*[-*]\s+\[([ xX])\]\s+\S/;
 
@@ -100,15 +129,27 @@ export function deriveSpecState(specDir, { requireAnalysis = false } = {}) {
   const criticals = requireAnalysis && analysisPresent ? findCriticalFindings(read("analysis.md")) : [];
   const analysisOk = !requireAnalysis || (analysisPresent && criticals.length === 0);
 
-  let status = STATUS.TODO;
+  // Stage first, status as its fixed collapse — one ladder, two vocabularies. The stage
+  // rules refine "In Progress" without moving any 3-status boundary: Done-eligible is still
+  // exactly all-boxes-checked (+ clean analysis in strict mode), To Do is still no spec.md.
+  const allChecked = tasksTotal > 0 && tasksDone === tasksTotal;
+  let stage = STAGE.SPECIFYING;
   if (has("spec.md")) {
-    status = has("plan.md") && tasksTotal > 0 && tasksDone === tasksTotal && analysisOk
-      ? STATUS.DONE_ELIGIBLE
-      : STATUS.IN_PROGRESS;
+    if (!has("plan.md")) stage = STAGE.PLANNING;
+    else if (allChecked && analysisOk) stage = STAGE.REVIEWING;
+    else {
+      // Validating: the only unchecked work left sits in tasks.md's final phase (needs ≥2
+      // phases to mean anything), or every box is checked and only the strict-mode analysis
+      // artifact is outstanding. Anything earlier is implementing.
+      const earlierPhasesDone =
+        phases.length >= 2 && phases.slice(0, -1).every((p) => p.done === p.total);
+      stage = allChecked || earlierPhasesDone ? STAGE.VALIDATING : STAGE.IMPLEMENTING;
+    }
   }
 
   return {
-    status, phases, tasksDone, tasksTotal, progressNote: progressNote(phases),
+    status: coarseStatus(stage), stage, phases, tasksDone, tasksTotal,
+    progressNote: progressNote(phases),
     analysis: { required: requireAnalysis, present: analysisPresent, criticals },
   };
 }

package/package.json

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

@@ -12,22 +12,77 @@
 //   ok      — they agree.
 //   unknown — the task uses a status outside To Do / In Progress / Done (custom workflow);
 //             the bridge doesn't guess, so it neither blocks nor warns.
+//
+// A project MAY opt into a finer, phase-level status vocabulary via `statusVocabulary` in
+// `.spec-bridge.json` (see vocabularyProfile): the same four verdicts, ranked on the
+// derivation-stage ladder against the board's own status names. Absent that config, every
+// path below behaves exactly as described above.
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { deriveSpecState, STATUS } from "../lib/spec-derive.mjs";
+import { deriveSpecState, STATUS, STAGE, STAGES } from "../lib/spec-derive.mjs";
 import { hasChild, findRootsDownwards } from "../lib/project-root.mjs";
 
 /**
  * Per-project bridge config: `.spec-bridge.json` at the project root (beside backlog/).
- * `{ "strictDone": true }` turns on analyze-gated Done (see lib/spec-derive.mjs). Missing or
- * malformed config means checkbox-only mode — strictness is opt-in.
+ * `{ "strictDone": true }` turns on analyze-gated Done (see lib/spec-derive.mjs);
+ * `"statusVocabulary"` opts the board into phase-level status names (see
+ * vocabularyProfile below). Missing or malformed config means checkbox-only mode with the
+ * 3-status vocabulary — everything finer is opt-in.
  */
 export function loadBridgeConfig(root) {
   try { return JSON.parse(readFileSync(join(root, ".spec-bridge.json"), "utf8")) ?? {}; }
   catch { return {}; }
 }
 
+/**
+ * What each derivation stage is called on a board that has NOT renamed it. This is exactly
+ * the 3-status collapse ("reviewing" is named Done because the sync skill's only move from
+ * there is `-s Done`), which is why a statusVocabulary that renames nothing behaves
+ * bit-for-bit like no statusVocabulary at all.
+ */
+export const DEFAULT_STAGE_NAMES = {
+  [STAGE.SPECIFYING]: "To Do",
+  [STAGE.PLANNING]: "In Progress",
+  [STAGE.IMPLEMENTING]: "In Progress",
+  [STAGE.VALIDATING]: "In Progress",
+  [STAGE.REVIEWING]: "Done",
+};
+
+/**
+ * The opt-in phase-level vocabulary, normalized. `.spec-bridge.json` may carry
+ *   { "statusVocabulary": { "<stage>": "<board status name>", ... } }
+ * mapping any of the derivation stages (specifying / planning / implementing / validating /
+ * reviewing) to the consumer board's own status names; unmapped stages keep their
+ * DEFAULT_STAGE_NAMES. Returns null — 3-status behavior, unchanged — unless at least one
+ * stage is validly renamed (string values only; unknown keys ignored).
+ *
+ * The profile carries:
+ *   names — stage → board status name (defaults overlaid with the config)
+ *   cover — lowercase board status name → { min, max } span of stage ranks it stands for
+ *           (a name used for several stages honestly covers all of them; "Done" always
+ *           covers at least the top stage, so Done-eligibility is unchanged by opting in)
+ */
+export function vocabularyProfile(config) {
+  const raw = config?.statusVocabulary;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const names = { ...DEFAULT_STAGE_NAMES };
+  let renamed = false;
+  for (const key of STAGES) {
+    if (typeof raw[key] === "string" && raw[key].trim()) { names[key] = raw[key].trim(); renamed = true; }
+  }
+  if (!renamed) return null;
+  const top = STAGES.length - 1;
+  const cover = new Map([["done", { min: top, max: top }]]);
+  STAGES.forEach((stageKey, rank) => {
+    const name = names[stageKey].toLowerCase();
+    const c = cover.get(name);
+    if (!c) cover.set(name, { min: rank, max: rank });
+    else { c.min = Math.min(c.min, rank); c.max = Math.max(c.max, rank); }
+  });
+  return { names, cover };
+}
+
 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 };
@@ -79,6 +134,20 @@ export function verdict(taskStatus, derivedStatus) {
   return t > d ? "exceeds" : t < d ? "lags" : "ok";
 }
 
+/**
+ * The same comparison at phase grain, against an opted-in vocabulary profile: a board status
+ * exceeds when even the EARLIEST stage it stands for is later than the derived stage, lags
+ * when even the LATEST is earlier, is ok anywhere inside its span, and is unknown when the
+ * status isn't in the vocabulary (custom workflow: don't guess) — verdict()'s semantics,
+ * finer ruler.
+ */
+export function stageVerdict(taskStatus, derivedStage, profile) {
+  const c = profile.cover.get(String(taskStatus).toLowerCase());
+  const d = STAGES.indexOf(derivedStage);
+  if (!c || d < 0) return "unknown";
+  return c.min > d ? "exceeds" : c.max < d ? "lags" : "ok";
+}
+
 /** One human sentence on why a spec dir doesn't prove more than its derived status. */
 function shortfall(root, specDir, derived) {
   const missing = ["spec.md", "plan.md"].filter((f) => !existsSync(join(root, specDir, f)));
@@ -105,19 +174,24 @@ export function checkBridge(root) {
   const links = [];
   const problems = [];
   const warnings = [];
-  const requireAnalysis = loadBridgeConfig(root).strictDone === true;
+  const config = loadBridgeConfig(root);
+  const requireAnalysis = config.strictDone === true;
+  const profile = vocabularyProfile(config);
   for (const task of findLinkedTasks(root)) {
     const derived = deriveSpecState(join(root, task.specDir), { requireAnalysis });
-    const v = verdict(task.status, derived.status);
+    // Opted-in boards are judged on the stage ladder against their own status names;
+    // everyone else gets the 3-status comparison, untouched.
+    const v = profile ? stageVerdict(task.status, derived.stage, profile) : verdict(task.status, derived.status);
+    const proven = profile ? profile.names[derived.stage] : derived.status;
     links.push({ ...task, derived, verdict: v });
     if (v === "exceeds") {
       problems.push(
-        `[spec-bridge] ${task.id} is "${task.status}" but ${task.specDir} only proves "${derived.status}": ` +
+        `[spec-bridge] ${task.id} is "${task.status}" but ${task.specDir} only proves "${proven}": ` +
         `${shortfall(root, task.specDir, derived)}. Finish the spec work or set the task back (backlog task edit ${task.id} -s "...").`
       );
     } else if (v === "lags") {
       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.`
+        `[spec-bridge] ${task.id} is "${task.status}" but ${task.specDir} already derives "${proven}" — 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
@@ -156,13 +230,22 @@ const sq = (s) => `'${String(s).replace(/'/g, "'\\''")}'`;
  * 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.
+ *
+ * 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).
  */
-export function planLinkedTask(task, derived) {
+export function planLinkedTask(task, derived, profile = null) {
   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 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")
@@ -218,11 +301,14 @@ export function planLinkedTask(task, derived) {
 export function planBridge(root) {
   const commands = [];
   const skipped = [];
-  const requireAnalysis = loadBridgeConfig(root).strictDone === true;
+  const config = loadBridgeConfig(root);
+  const requireAnalysis = config.strictDone === true;
+  const profile = vocabularyProfile(config);
   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));
+    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));
   }
   return { commands, skipped };
 }

package/spec-bridge/gates/cli.mjs

@@ -10,7 +10,7 @@
 import { resolve } from "node:path";
 import { deriveSpecState } from "../lib/spec-derive.mjs";
 import { findRootUpwards, hasChild } from "../lib/project-root.mjs";
-import { checkBridge, loadBridgeConfig, planBridge } from "./bridge.mjs";
+import { checkBridge, loadBridgeConfig, planBridge, vocabularyProfile } from "./bridge.mjs";
 
 const [cmd, target] = process.argv.slice(2);
 if (!cmd || !target) {
@@ -36,8 +36,14 @@ if (cmd === "state") {
   console.log(`spec-bridge ok: ${links.length} linked task(s), none exceed their artifacts`);
 } else if (cmd === "plan") {
   const { commands, skipped } = planBridge(target);
+  // Name the vocabulary the board actually speaks: the opted-in phase-level names when
+  // .spec-bridge.json carries a statusVocabulary, the 3-status default otherwise.
+  const profile = vocabularyProfile(loadBridgeConfig(target));
+  const vocab = profile
+    ? [...new Set([...Object.values(profile.names), "Done"])].join("/")
+    : "To Do/In Progress/Done";
   for (const s of skipped)
-    console.error(`# ${s.id}: status "${s.status}" is outside To Do/In Progress/Done — not planned; resolve by hand`);
+    console.error(`# ${s.id}: status "${s.status}" is outside ${vocab} — not planned; resolve by hand`);
   for (const c of commands) console.log(c);
 } else {
   console.error(`unknown command: ${cmd}`);

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

@@ -13,6 +13,11 @@
 // "Done-eligible" deliberately isn't "Done": the sync skill may move the Backlog task to Done,
 // and the bridge gate treats a Done status without this derivation as a blocking problem.
 //
+// Every derivation also names a finer STAGE (specifying → planning → implementing →
+// validating → reviewing); the status above is a fixed collapse of it (coarseStatus). The
+// stage feeds the opt-in phase-level board vocabulary in gates/bridge.mjs and is purely
+// additive — nothing here behaves differently because of it.
+//
 // Strict mode ({ requireAnalysis: true }): checked boxes are necessary but weak proof, so
 // Done-eligible additionally requires an analysis report saved as analysis.md in the spec dir
 // (the durable artifact of /speckit.analyze — chat output doesn't count) with no unresolved
@@ -28,6 +33,30 @@ export const STATUS = {
   DONE_ELIGIBLE: "Done-eligible",
 };
 
+// The finer-grained lifecycle ladder underneath the 3-status vocabulary. Every derivation
+// also names the stage it is in; the 3 statuses are a fixed collapse of the 5 stages
+// (specifying → To Do; planning/implementing/validating → In Progress; reviewing →
+// Done-eligible), so the stage is strictly additive information — consumers that never look
+// at it see exactly the behavior above.
+export const STAGE = {
+  SPECIFYING: "specifying",     // no spec.md yet
+  PLANNING: "planning",         // spec.md present, no plan.md
+  IMPLEMENTING: "implementing", // plan.md present, work remaining outside the final phase
+  VALIDATING: "validating",     // only the final tasks.md phase still has unchecked work,
+                                //   or all boxes checked but strict-mode analysis pending
+  REVIEWING: "reviewing",       // everything proven — same state as Done-eligible
+};
+
+/** The stages in lifecycle order — the ranking the bridge gate compares against. */
+export const STAGES = [STAGE.SPECIFYING, STAGE.PLANNING, STAGE.IMPLEMENTING, STAGE.VALIDATING, STAGE.REVIEWING];
+
+/** The fixed collapse: stage → 3-status. */
+export function coarseStatus(stage) {
+  if (stage === STAGE.SPECIFYING) return STATUS.TODO;
+  if (stage === STAGE.REVIEWING) return STATUS.DONE_ELIGIBLE;
+  return STATUS.IN_PROGRESS;
+}
+
 const PHASE_HEADING = /^##\s+(.+?)\s*$/;
 const TASK_LINE = /^\s*[-*]\s+\[([ xX])\]\s+\S/;
 
@@ -100,15 +129,27 @@ export function deriveSpecState(specDir, { requireAnalysis = false } = {}) {
   const criticals = requireAnalysis && analysisPresent ? findCriticalFindings(read("analysis.md")) : [];
   const analysisOk = !requireAnalysis || (analysisPresent && criticals.length === 0);
 
-  let status = STATUS.TODO;
+  // Stage first, status as its fixed collapse — one ladder, two vocabularies. The stage
+  // rules refine "In Progress" without moving any 3-status boundary: Done-eligible is still
+  // exactly all-boxes-checked (+ clean analysis in strict mode), To Do is still no spec.md.
+  const allChecked = tasksTotal > 0 && tasksDone === tasksTotal;
+  let stage = STAGE.SPECIFYING;
   if (has("spec.md")) {
-    status = has("plan.md") && tasksTotal > 0 && tasksDone === tasksTotal && analysisOk
-      ? STATUS.DONE_ELIGIBLE
-      : STATUS.IN_PROGRESS;
+    if (!has("plan.md")) stage = STAGE.PLANNING;
+    else if (allChecked && analysisOk) stage = STAGE.REVIEWING;
+    else {
+      // Validating: the only unchecked work left sits in tasks.md's final phase (needs ≥2
+      // phases to mean anything), or every box is checked and only the strict-mode analysis
+      // artifact is outstanding. Anything earlier is implementing.
+      const earlierPhasesDone =
+        phases.length >= 2 && phases.slice(0, -1).every((p) => p.done === p.total);
+      stage = allChecked || earlierPhasesDone ? STAGE.VALIDATING : STAGE.IMPLEMENTING;
+    }
   }
 
   return {
-    status, phases, tasksDone, tasksTotal, progressNote: progressNote(phases),
+    status: coarseStatus(stage), stage, phases, tasksDone, tasksTotal,
+    progressNote: progressNote(phases),
     analysis: { required: requireAnalysis, present: analysisPresent, criticals },
   };
 }