@smartmemory/compose 0.2.7-beta → 0.2.8-beta

package/bin/compose.js

@@ -1969,14 +1969,22 @@ if (cmd === 'build') {
   // pipeline (pipelines/gsd.stratum.yaml). Hard-requires existing
   // docs/features/<code>/blueprint.md with a parseable Boundary Map.
   const gsdCode = args.find(a => !a.startsWith('-'))
+  const gsdResume = args.includes('--resume')
+  const gsdResetBudget = args.includes('--reset-budget')
   if (!gsdCode) {
-    console.error('Usage: compose gsd <feature-code>')
+    console.error('Usage: compose gsd <feature-code> [--resume] [--reset-budget]')
     console.error('')
     console.error('Runs the per-task fresh-context dispatch pipeline (COMP-GSD-2).')
     console.error('Hard-requires docs/features/<code>/blueprint.md with a valid Boundary Map.')
+    console.error('Detects stuck tasks (COMP-GSD-5) and halts with a structured diagnostic.')
+    console.error('Enforces budget ceilings (COMP-GSD-4) from .compose/compose.json gsd.budget.*')
     console.error('')
     console.error('Options:')
-    console.error('  --cwd <path>   Working directory (defaults to current)')
+    console.error('  --resume        Resume a halted run: re-dispatch the unfinished tasks')
+    console.error('                  from .compose/gsd/<code>/pause.json (skips completed tasks).')
+    console.error('  --reset-budget  Clear the feature\'s cumulative budget ledger before running')
+    console.error('                  (use after raising or removing a spent gsd.budget.cumulative cap).')
+    console.error('  --cwd <path>    Working directory (defaults to current)')
     process.exit(1)
   }
   const { root: gsdCwd } = resolveCwdWithWorkspace(args)
@@ -1984,7 +1992,34 @@ if (cmd === 'build') {
   const gsdAgentCwd = cwdIdx !== -1 ? resolve(args[cwdIdx + 1]) : gsdCwd
   const { runGsd } = await import('../lib/gsd.js')
   try {
-    const result = await runGsd(gsdCode, { cwd: gsdAgentCwd })
+    if (gsdResetBudget) {
+      // COMP-GSD-4: clear the cumulative ledger so a spent ceiling no longer
+      // refuses the run. Runs before dispatch; per-run windows reset anyway.
+      const { resetGsdUsage } = await import('../lib/budget-ledger.js')
+      resetGsdUsage(resolve(gsdAgentCwd, '.compose'), gsdCode)
+      console.log(`gsd: cleared cumulative budget ledger for ${gsdCode}.`)
+    }
+    const result = await runGsd(gsdCode, { cwd: gsdAgentCwd, resume: gsdResume })
+    if (result.status === 'stuck') {
+      // COMP-GSD-5: a stuck halt is a clean, recoverable stop — not a crash.
+      console.error(`gsd stuck: task ${result.stuckTaskId} tripped the ${result.signal} detector.`)
+      console.error(`Diagnostic: .compose/gsd/${gsdCode}/stuck.md`)
+      console.error(`Resume with: compose gsd ${gsdCode} --resume`)
+      process.exit(2)
+    }
+    if (result.status === 'budget') {
+      // COMP-GSD-4: a budget halt is a clean, recoverable stop — not a crash.
+      if (result.axis === 'cumulative') {
+        console.error(`gsd budget: cumulative ceiling for ${gsdCode} is already spent.`)
+        console.error(`Diagnostic: .compose/gsd/${gsdCode}/budget.md`)
+        console.error(`Raise gsd.budget.cumulative.* or clear it: compose gsd ${gsdCode} --reset-budget`)
+      } else {
+        console.error(`gsd budget: the ${result.axis} ceiling tripped mid-run.`)
+        console.error(`Diagnostic: .compose/gsd/${gsdCode}/budget.md`)
+        console.error(`Raise gsd.budget.* and resume: compose gsd ${gsdCode} --resume`)
+      }
+      process.exit(2)
+    }
     console.log(`gsd complete: ${result.blackboardEntries} task results captured.`)
   } catch (err) {
     console.error(`gsd failed: ${err.message}`)

package/contracts/gsd-stuck.json

@@ -0,0 +1,141 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gsd-stuck.json",
+  "_source": "COMP-GSD-5",
+  "_also": "COMP-GSD-4",
+  "_roadmap": "COMP-GSD-5",
+  "title": "GsdStuckContracts",
+  "description": "Artifacts written when a `compose gsd` run halts. A STUCK halt (COMP-GSD-5) writes stuck.json/stuck.md; a BUDGET halt (COMP-GSD-4) writes budget.json/budget.md. Both persist `pause.json` (machine-readable resume state); `compose gsd <feature> --resume` reads it, validates ownership/mode, and re-dispatches decomposedTasks minus completedTaskIds (completed results already live in the blackboard). The pause `kind` field (optional; absent ⇒ 'stuck' for back-compat) discriminates: a 'stuck' pause carries the stuck-specific fields, a 'budget' pause carries the `budget` block. GSD-6 reuses the `pause` shape for automatic crash-recovery.",
+  "definitions": {
+    "stuck": {
+      "type": "object",
+      "title": "GsdStuckDiagnostic",
+      "description": "Structured diagnostic emitted on the first stuck verdict for a task.",
+      "required": ["feature", "taskId", "signal", "detail", "attemptCounts", "ts"],
+      "additionalProperties": false,
+      "properties": {
+        "feature": {
+          "type": "string",
+          "description": "Feature code the gsd run is building (e.g. COMP-GSD-5)."
+        },
+        "taskId": {
+          "type": "string",
+          "description": "The decomposed task id that tripped the detector."
+        },
+        "signal": {
+          "type": "string",
+          "enum": ["same_file", "error_recurrence", "no_progress", "wall_clock"],
+          "description": "Which stuck pattern fired. same_file: one file edited >= sameFileEdits times. error_recurrence: a normalized error hash recurred >= errorRepeats. no_progress: >= noProgressCalls consecutive non-file-changing tool calls. wall_clock: task ran >= wallClockMs without finishing."
+        },
+        "detail": {
+          "type": "string",
+          "description": "Human-readable explanation of the offending file / error / stall."
+        },
+        "attemptCounts": {
+          "type": "object",
+          "description": "Snapshot of the per-task counters at the moment of the verdict.",
+          "properties": {
+            "sameFileEdits": { "type": "integer", "minimum": 0, "description": "Max edit count across files for this task." },
+            "errorRepeats": { "type": "integer", "minimum": 0, "description": "Max repeat count across normalized error hashes." },
+            "noProgressCalls": { "type": "integer", "minimum": 0, "description": "Current consecutive non-file-changing tool-call count." }
+          },
+          "additionalProperties": true
+        },
+        "partialDiff": {
+          "type": "string",
+          "description": "Optional unified diff of the stuck task's worktree at halt time, for triage."
+        },
+        "ts": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO-8601 timestamp of the verdict."
+        }
+      }
+    },
+    "pause": {
+      "type": "object",
+      "title": "GsdPauseState",
+      "description": "Resume state persisted on a stuck OR budget halt. Drives blackboard-driven re-dispatch on --resume — NOT mid-task re-entry. Base required fields are kind-agnostic; the `kind` field (optional; absent ⇒ stuck) selects which extra fields are required via the if/then/else at the end.",
+      "required": ["flowId", "stepId", "decomposedTasks", "completedTaskIds", "pid", "mode", "ts"],
+      "additionalProperties": false,
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": ["stuck", "budget"],
+          "description": "Halt kind. Optional for back-compat: an absent kind is interpreted as 'stuck'. Determines which extra fields are required (see if/then/else)."
+        },
+        "budget": {
+          "type": "object",
+          "description": "Present on a budget halt (kind='budget'). The enforced axis that tripped + the stratum budget_state snapshot.",
+          "required": ["axis", "caps", "consumed"],
+          "additionalProperties": true,
+          "properties": {
+            "axis": {
+              "type": ["string", "null"],
+              "enum": ["ms", "max_agent_dispatches", "max_tokens", "usd", null],
+              "description": "Which enforced stratum axis reached its cap (null if indeterminate)."
+            },
+            "caps": { "type": "object", "description": "The flow budget caps {ms?,max_agent_dispatches?,max_tokens?,usd?}." },
+            "consumed": { "type": "object", "description": "Consumed totals {tokens,dispatches,wall_s,dollars}." }
+          }
+        },
+        "flowId": {
+          "type": "string",
+          "description": "Stratum flow id of the halted run (informational; resume opens a fresh flow)."
+        },
+        "stepId": {
+          "type": "string",
+          "description": "The parallel_dispatch step id that was cancelled (e.g. execute)."
+        },
+        "stuckTaskId": {
+          "type": "string",
+          "description": "The task id that tripped the detector."
+        },
+        "signal": {
+          "type": "string",
+          "enum": ["same_file", "error_recurrence", "no_progress", "wall_clock"],
+          "description": "Which stuck pattern fired (mirrors stuck.signal)."
+        },
+        "detail": {
+          "type": "string",
+          "description": "Human-readable explanation (mirrors stuck.detail)."
+        },
+        "decomposedTasks": {
+          "type": "array",
+          "minItems": 1,
+          "description": "The full decomposed task list, persisted so --resume does NOT re-decompose (stable task ids).",
+          "items": { "type": "object" }
+        },
+        "completedTaskIds": {
+          "type": "array",
+          "description": "Task ids whose VALIDATED result is already in the blackboard. --resume skips these.",
+          "items": { "type": "string" }
+        },
+        "pid": {
+          "type": "integer",
+          "description": "OS pid of the process that wrote the pause file. --resume refuses if this pid is still alive (another owner)."
+        },
+        "mode": {
+          "type": "string",
+          "const": "gsd",
+          "description": "Run mode. --resume refuses if this is not 'gsd' (mirrors `compose fix --resume` mode guard)."
+        },
+        "ts": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO-8601 timestamp the pause file was written."
+        }
+      },
+      "if": {
+        "properties": { "kind": { "const": "budget" } },
+        "required": ["kind"]
+      },
+      "then": {
+        "required": ["budget"]
+      },
+      "else": {
+        "required": ["stuckTaskId", "signal", "detail"]
+      }
+    }
+  }
+}

package/lib/budget-ledger.js

@@ -85,6 +85,90 @@ export function checkCumulativeBudget(composeDir, featureCode, limits = {}) {
   return { exceeded: false, reason: null, usage };
 }
 
+// ===========================================================================
+// COMP-GSD-4: cumulative gsd-run usage (tokens + cost). Shares the per-feature
+// ledger entry with COMP-BUDGET's iteration tracking, adding two
+// back-compatible fields (totalTokens/totalCostUsd; absent on legacy entries
+// reads as 0). Wall-clock/dispatch are per-RUN windows enforced by the stratum
+// flow budget — NOT cumulative-checked here (design Decision 3).
+// ===========================================================================
+
+/**
+ * Record a gsd run's token/cost (and informational dispatch/time) usage,
+ * sourced from the stratum terminal envelope's budget_state.consumed.
+ *
+ * @param {string} composeDir — path to .compose directory
+ * @param {string} featureCode
+ * @param {{ tokens?: number, costUsd?: number, dispatches?: number, timeMs?: number }} usage
+ */
+export function recordGsdUsage(composeDir, featureCode, { tokens = 0, costUsd = 0, dispatches = 0, timeMs = 0 } = {}) {
+  const filePath = ledgerPath(composeDir);
+  const ledger = readLedger(composeDir);
+
+  if (!ledger.features[featureCode]) {
+    ledger.features[featureCode] = { totalIterations: 0, totalActions: 0, totalTimeMs: 0, sessions: [] };
+  }
+  const feat = ledger.features[featureCode];
+  feat.totalTokens = (feat.totalTokens ?? 0) + tokens;
+  feat.totalCostUsd = (feat.totalCostUsd ?? 0) + costUsd;
+  feat.totalTimeMs = (feat.totalTimeMs ?? 0) + timeMs;
+  feat.sessions.push({ recordedAt: new Date().toISOString(), kind: 'gsd', tokens, costUsd, dispatches, timeMs });
+
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(ledger, null, 2), 'utf-8');
+  return feat;
+}
+
+/**
+ * Check whether a feature has exceeded its cumulative gsd token/cost ceiling.
+ * Cumulative tokens/cost persist across sessions (a hard ceiling that blocks
+ * resume); per-run wall-clock/dispatch reset each run, so they are not checked.
+ *
+ * @param {string} composeDir
+ * @param {string} featureCode
+ * @param {{ maxTotalTokens?: number, maxTotalCostUsd?: number }} limits
+ * @returns {{ exceeded: boolean, reason: string|null, usage: object }}
+ */
+export function checkGsdCumulativeBudget(composeDir, featureCode, limits = {}) {
+  const ledger = readLedger(composeDir);
+  const feat = ledger.features[featureCode] ?? {};
+  const usage = {
+    totalTokens: feat.totalTokens ?? 0,
+    totalCostUsd: feat.totalCostUsd ?? 0,
+  };
+
+  if (limits.maxTotalTokens != null && usage.totalTokens >= limits.maxTotalTokens) {
+    return { exceeded: true, reason: `Cumulative token ceiling reached (${usage.totalTokens}/${limits.maxTotalTokens})`, usage };
+  }
+  if (limits.maxTotalCostUsd != null && usage.totalCostUsd >= limits.maxTotalCostUsd) {
+    return { exceeded: true, reason: `Cumulative cost ceiling reached ($${usage.totalCostUsd.toFixed(4)}/$${Number(limits.maxTotalCostUsd).toFixed(4)})`, usage };
+  }
+
+  return { exceeded: false, reason: null, usage };
+}
+
+/**
+ * Clear the cumulative gsd usage for a feature (the `--reset-budget` path).
+ * Preserves COMP-BUDGET iteration fields; zeroes only the gsd token/cost
+ * counters and drops gsd sessions. No-op when the feature has no ledger entry.
+ *
+ * @param {string} composeDir
+ * @param {string} featureCode
+ */
+export function resetGsdUsage(composeDir, featureCode) {
+  const filePath = ledgerPath(composeDir);
+  const ledger = readLedger(composeDir);
+  const feat = ledger.features[featureCode];
+  if (!feat) return;
+  feat.totalTokens = 0;
+  feat.totalCostUsd = 0;
+  if (Array.isArray(feat.sessions)) {
+    feat.sessions = feat.sessions.filter((s) => s.kind !== 'gsd');
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(ledger, null, 2), 'utf-8');
+}
+
 /**
  * Read a snapshot budget response for a feature without throwing on quota.
  * Used by GET /api/lifecycle/budget.

package/lib/build-stream-schema.js

@@ -7,15 +7,17 @@
  * Design decisions:
  * - Uses AJV (already in compose deps) compiled once at module load.
  * - On validation failure the caller should warn+drop — never throw.
- * - KNOWN_VERSIONS: set of accepted schema_version strings. v0.2.5 accepted for
- *   one-cycle backward compatibility; v0.2.6 is current.
+ * - KNOWN_VERSIONS: set of accepted schema_version strings. v0.2.5/v0.2.6 accepted
+ *   for backward compatibility; v0.2.7 is current (STRAT-PAR-STREAM-TOOLDETAIL:
+ *   enriched tool_use_summary.input + tool_use_id, new tool_result kind — both
+ *   ride the open catch-all, so no closed metadata schema is added here).
  * - reply_required (Option A, STRAT-PAR-STREAM-CONSUMER-VALIDATE design):
  *   optional boolean reserved for future gate/permission/question kinds.
  */
 
 import Ajv2020 from 'ajv/dist/2020.js';
 
-export const KNOWN_VERSIONS = new Set(['0.2.5', '0.2.6']);
+export const KNOWN_VERSIONS = new Set(['0.2.5', '0.2.6', '0.2.7']);
 
 // ---------------------------------------------------------------------------
 // Envelope schema (top-level fields only; metadata shape is kind-specific)

package/lib/build.js

@@ -2947,12 +2947,19 @@ export async function executeParallelDispatchServer(
   progress,
   streamWriter,
   baseCwd,
+  opts = {},
 ) {
   const { flow_id: flowId, step_id: stepId,
           step_number: stepNum, total_steps: totalSteps,
           tasks } = dispatchResponse;
   const emittedStates = new Map();
 
+  // COMP-GSD-5: optional stuck detector. ONLY the gsd path passes one; build
+  // mode invokes this fn with 6 args (opts={}) so every detector branch below
+  // is skipped and build behavior stays byte-identical.
+  const stuckDetector = opts.stuckDetector ?? null;
+  const startedTasks = new Set();
+
   if (streamWriter) {
     streamWriter.write({
       type: 'build_step_start', stepId,
@@ -2982,11 +2989,18 @@ export async function executeParallelDispatchServer(
   // state-machine driver. Forward valid events through streamWriter so the
   // bridge rebroadcasts them via SSE under the buildStreamEvent wrapper.
   let unsubscribePush = null;
-  if (typeof stratum.onEvent === 'function' && streamWriter) {
+  if (typeof stratum.onEvent === 'function' && (streamWriter || stuckDetector)) {
     unsubscribePush = stratum.onEvent(flowId, stepId, (event) => {
       // Accept all KNOWN_VERSIONS (producer emits 0.2.6); pinning '0.2.5' dropped
       // every push event from the current producer. Client already validated.
       if (!event || !KNOWN_VERSIONS.has(event.schema_version)) return;
+      // COMP-GSD-5: feed the per-task stuck detector (no-op in build mode —
+      // stuckDetector is null there). record() ignores all but
+      // tool_use_summary/tool_result and keys by event.task_id.
+      if (stuckDetector && (event.kind === 'tool_use_summary' || event.kind === 'tool_result')) {
+        try { stuckDetector.record(event); } catch (err) { console.error('[build] stuck detector record failed:', err); }
+      }
+      if (!streamWriter) return;
       try {
         streamWriter.write({ type: 'build_stream_event', event });
       } catch (err) {
@@ -2998,6 +3012,7 @@ export async function executeParallelDispatchServer(
   try {
     // Poll until outcome is present (NOT can_advance — see design §3)
     let pollResult;
+    let stuckVerdict = null;
     const intervalMs = SERVER_DISPATCH_POLL_MS();
     while (true) {
       pollResult = await stratum.parallelPoll(flowId, stepId);
@@ -3007,10 +3022,81 @@ export async function executeParallelDispatchServer(
         );
       }
       emitPerTaskProgress(streamWriter, pollResult, emittedStates);
+
+      // COMP-GSD-5: real-time stuck detection (gsd path only — null in build).
+      // For each running task: establish a wall-clock baseline on first sight,
+      // then ask the detector for a verdict. On the first stuck task, cancel the
+      // step via the terminal cascade primitive (parallelAdvance 'conflict' —
+      // the same path T2-F5 uses) and break with a stuck outcome.
+      if (stuckDetector) {
+        const now = Date.now();
+        for (const [taskId, ts] of Object.entries(pollResult.tasks ?? {})) {
+          if (ts.state === 'running') stuckDetector.startTask(taskId, now);
+          if (ts.state !== 'running') continue;
+          const v = stuckDetector.check(taskId, now);
+          if (v?.stuck) {
+            stuckVerdict = {
+              ...v,
+              taskId,
+              attemptCounts: stuckDetector.attemptCounts(taskId),
+            };
+            if (streamWriter) {
+              streamWriter.write({
+                type: 'system', subtype: 'gsd_stuck',
+                stepId, taskId, signal: v.signal, detail: v.detail, parallel: true,
+              });
+            }
+            const cancel = await stratum.parallelAdvance(flowId, stepId, 'conflict');
+            if (cancel?.error) {
+              throw new Error(
+                `stratum_parallel_advance (stuck cancel) failed: ${cancel.error}: ${cancel.message || ''}`,
+              );
+            }
+            pollResult = { ...pollResult, outcome: cancel };
+            break;
+          }
+        }
+      }
+      if (stuckVerdict) break;
+
       if (pollResult.outcome != null) break;
       await new Promise((resolve) => setTimeout(resolve, intervalMs));
     }
 
+    // COMP-GSD-5: short-circuit return on a stuck verdict. The cancel outcome is
+    // returned verbatim with the verdict attached; the gsd run loop branches on
+    // `.stuck`. This bypasses the merge/advance bookkeeping below — there is
+    // nothing to merge for a cancelled task.
+    if (stuckVerdict) {
+      if (streamWriter) {
+        streamWriter.write({
+          type: 'build_step_done', stepId, parallel: true,
+          summary: { ...(pollResult.summary ?? {}), stuck: stuckVerdict.signal }, flowId,
+        });
+      }
+      // unsubscribePush is invoked by the enclosing finally.
+      return { ...(pollResult.outcome ?? {}), stuck: stuckVerdict };
+    }
+
+    // COMP-GSD-4: budget_exhausted is a stratum terminal status. When the run
+    // budget trips mid-dispatch, the flow has already cascade-cancelled the
+    // in-flight siblings (server-side) and the poll returns the terminal
+    // envelope (carrying budget_state). There is nothing to merge — short-circuit
+    // like stuck and hand the envelope back so the gsd run loop halts. No-op for
+    // build mode: build flows declare no `budget:` block, so the status never
+    // appears and this branch is never taken (byte-identical). The
+    // advance-carried case (a parallelAdvance that returns budget_exhausted)
+    // falls through to the final `return pollResult.outcome` below.
+    if (pollResult.outcome?.status === 'budget_exhausted') {
+      if (streamWriter) {
+        streamWriter.write({
+          type: 'build_step_done', stepId, parallel: true,
+          summary: { ...(pollResult.summary ?? {}), budget_exhausted: true }, flowId,
+        });
+      }
+      return pollResult.outcome;
+    }
+
     if (pollResult.outcome.status === 'already_advanced') {
       throw new Error(
         `stratum_parallel_poll returned already_advanced for step ${stepId} — ` +

package/lib/feature-validator.js

@@ -385,6 +385,17 @@ function normalizeStatus(s) {
   return String(s).toUpperCase();
 }
 
+// vision-state's status vocabulary (contracts/vision-state.schema.json) is the
+// tracker's set MINUS `PARTIAL` — it cannot represent "partially shipped". A
+// tracker status of PARTIAL is the same lifecycle reality as vision's
+// IN_PROGRESS (partially shipped = still in progress), so project the tracker
+// side onto the vision vocabulary before any *_VS_VISION_STATE comparison.
+// Tracker↔tracker comparisons (ROADMAP_VS_FEATUREJSON) keep the full
+// vocabulary — PARTIAL vs IN_PROGRESS there is a real distinction.
+function projectToVisionStatus(s) {
+  return s === 'PARTIAL' ? 'IN_PROGRESS' : s;
+}
+
 function runStateMismatchChecks(fctx, findings) {
   const { code, roadmap, vision, featureJson } = fctx;
   const rStatus = normalizeStatus(roadmap?.status);
@@ -401,22 +412,43 @@ function runStateMismatchChecks(fctx, findings) {
       'STATUS_MISMATCH_ROADMAP_VS_FEATUREJSON', code,
       `ROADMAP says ${rStatus}, feature.json says ${fStatus}`));
   }
-  if (rStatus && vStatus && rStatus !== vStatus) {
-    findings.push(finding(statusSeverity(rStatus, vStatus),
+  // Project BOTH sides to the vision vocabulary (PARTIAL→IN_PROGRESS) before
+  // comparing. Projecting the tracker side stops a legitimately-PARTIAL feature
+  // false-firing against a vision item that can only say in_progress; projecting
+  // the vision side keeps it symmetric so a malformed/legacy vision status of
+  // "partial" (schema-invalid — reported as VISION_STATE_SCHEMA_VIOLATION) still
+  // aligns with tracker PARTIAL instead of double-reporting. Real drift (PARTIAL
+  // vs complete/planned) still differs and fires.
+  const rVis = projectToVisionStatus(rStatus);
+  const fVis = projectToVisionStatus(fStatus);
+  const vVis = projectToVisionStatus(vStatus);
+  if (rStatus && vStatus && rVis !== vVis) {
+    findings.push(finding(statusSeverity(rVis, vVis),
       'STATUS_MISMATCH_ROADMAP_VS_VISION_STATE', code,
       `ROADMAP says ${rStatus}, vision-state says ${vStatus}`));
   }
-  if (fStatus && vStatus && fStatus !== vStatus) {
-    findings.push(finding(statusSeverity(fStatus, vStatus),
+  if (fStatus && vStatus && fVis !== vVis) {
+    findings.push(finding(statusSeverity(fVis, vVis),
       'STATUS_MISMATCH_FEATUREJSON_VS_VISION_STATE', code,
       `feature.json says ${fStatus}, vision-state says ${vStatus}`));
   }
-  // CONTRADICTORY_PHASE_CLAIM
-  const fPhase = featureJson?.phase || featureJson?.lifecycle?.currentPhase;
-  const vPhase = vision?.phase || vision?.lifecycle?.currentPhase;
+  // CONTRADICTORY_PHASE_CLAIM — compare LIFECYCLE phase to LIFECYCLE phase.
+  // feature.json's top-level `phase` holds the ROADMAP heading (e.g. "Phase 7:
+  // MCP Writers"), NOT a lifecycle stage; comparing it to vision-state's
+  // lifecycle phase ("vision"/"explore_design"/…) is a category mismatch that
+  // false-fired on ~every feature with a vision item. Use only the lifecycle
+  // sources on both sides — which is what the "does not involve the roadmap"
+  // comment above always intended. (feature.json doesn't currently carry a
+  // lifecycle phase, so this correctly yields no finding until it does.)
+  const fPhase = featureJson?.lifecycle?.currentPhase;
+  // Lifecycle phase ONLY on both sides. Do NOT fall back to vision.phase — that
+  // is the legacy board-column taxonomy (planning|implementation|…), a different
+  // vocabulary from lifecycle.currentPhase (explore_design|blueprint|…), and
+  // mixing them reintroduces the category mismatch this fix removes (Codex).
+  const vPhase = vision?.lifecycle?.currentPhase;
   if (fPhase && vPhase && fPhase !== vPhase) {
     findings.push(finding('error', 'CONTRADICTORY_PHASE_CLAIM', code,
-      `feature.json phase '${fPhase}' vs vision-state phase '${vPhase}'`));
+      `feature.json lifecycle phase '${fPhase}' vs vision-state phase '${vPhase}'`));
   }
   // COMPLEXITY_OR_DESCRIPTION_DRIFT
   if (roadmap && featureJson) {