@smartmemory/compose 0.2.51 → 0.2.53-beta

package/lib/gate-prompt.js

@@ -107,8 +107,59 @@ function buildRecommendation(gateDispatch, gateExtras) {
   };
 }
 
-function ask(rl, question) {
-  return new Promise(resolve => rl.question(question, resolve));
+// COMP-PLAN-GATE-LOOP (secondary): default deadline for a gate prompt that is
+// reading the real stdin in a non-interactive context. Long enough for a piped
+// producer to answer, short enough that a backgrounded/no-input runner fails
+// fast instead of blocking forever.
+export const GATE_NONINTERACTIVE_TIMEOUT_MS = 120_000;
+
+const GATE_NONINTERACTIVE_HELP =
+  'stdin is not a TTY and the Compose server is unreachable, so the gate cannot ' +
+  'be answered. Start the :4001 server, run the gate interactively, or pass --all ' +
+  'to auto-approve. The flow state is preserved — re-run with --resume.';
+
+export class GateInputUnavailableError extends Error {
+  constructor(reason) {
+    super(`Gate decision required but ${reason}. ${GATE_NONINTERACTIVE_HELP}`);
+    this.name = 'GateInputUnavailableError';
+  }
+}
+
+/**
+ * Read one line from the readline interface.
+ *
+ * When `armGuard` is set (real stdin, no TTY — see promptGate) the read is
+ * bounded: it rejects with GateInputUnavailableError if the input stream ends
+ * (EOF, e.g. stdin is /dev/null) or no line arrives within `deadlineMs`, so a
+ * non-interactive runner fails fast instead of blocking forever. Piped input
+ * still resolves normally; an unguarded read keeps the original behavior.
+ *
+ * @param {import('node:readline').Interface} rl
+ * @param {string} question
+ * @param {{ armGuard?: boolean, deadlineMs?: number }} [opts]
+ * @returns {Promise<string>}
+ */
+export function ask(rl, question, { armGuard = false, deadlineMs = GATE_NONINTERACTIVE_TIMEOUT_MS } = {}) {
+  if (!armGuard) {
+    return new Promise(resolve => rl.question(question, resolve));
+  }
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const onEnd = () => finish(() => reject(new GateInputUnavailableError('stdin was closed before a decision')));
+    const timer = setTimeout(
+      () => finish(() => reject(new GateInputUnavailableError(`no input arrived within ${Math.round(deadlineMs / 1000)}s`))),
+      deadlineMs,
+    );
+    function finish(act) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      rl.input.removeListener('end', onEnd);
+      act();
+    }
+    rl.input.once('end', onEnd);
+    rl.question(question, answer => finish(() => resolve(answer)));
+  });
 }
 
 /**
@@ -179,7 +230,7 @@ function drawGatePanel(out, gateDispatch, { artifact, gateExtras } = {}) {
  * @param {object}   [options.gateExtras]  - { fromPhase, toPhase } for panel display
  * @returns {Promise<{ outcome: string, rationale: string }>}
  */
-export async function promptGate(gateDispatch, { input, output, artifact, askAgent, gateExtras, nonInteractive } = {}) {
+export async function promptGate(gateDispatch, { input, output, artifact, askAgent, gateExtras, nonInteractive, timeoutMs } = {}) {
   if (nonInteractive) {
     return { outcome: 'approve', rationale: 'auto-approved (--all mode)' };
   }
@@ -189,6 +240,15 @@ export async function promptGate(gateDispatch, { input, output, artifact, askAge
     output: output ?? process.stdout,
   });
 
+  // COMP-PLAN-GATE-LOOP (secondary): only bound the read when there is no
+  // interactive terminal AND we're on the real stdin. A real TTY (a human who
+  // may take their time) and an injected `input` (tests, piped/programmatic
+  // callers) keep the original block-until-answered behavior.
+  const askGuard = {
+    armGuard: input === undefined && !process.stdin.isTTY,
+    deadlineMs: timeoutMs ?? GATE_NONINTERACTIVE_TIMEOUT_MS,
+  };
+
   try {
     const { step_id, on_approve, on_revise, on_kill } = gateDispatch;
 
@@ -219,7 +279,7 @@ export async function promptGate(gateDispatch, { input, output, artifact, askAge
     let outcome;
 
     while (!outcome) {
-      const raw = await ask(rl, '\n> ');
+      const raw = await ask(rl, '\n> ', askGuard);
       const trimmed = raw.trim();
 
       // COMP-UX-3b: Enter alone → use recommended default action (only if recommendation was shown)
@@ -266,7 +326,7 @@ export async function promptGate(gateDispatch, { input, output, artifact, askAge
     let rationale;
     if (notes.length > 0) {
       rationale = notes.join('\n');
-      const addMore = await ask(rl, '  Additional rationale (or Enter to use notes): ');
+      const addMore = await ask(rl, '  Additional rationale (or Enter to use notes): ', askGuard);
       if (addMore.trim()) {
         rationale += '\n' + addMore.trim();
       }
@@ -274,7 +334,7 @@ export async function promptGate(gateDispatch, { input, output, artifact, askAge
       rationale = 'approved';
     } else {
       while (!rationale) {
-        const raw = await ask(rl, 'Rationale: ');
+        const raw = await ask(rl, 'Rationale: ', askGuard);
         const trimmed = raw.trim();
         if (trimmed) {
           rationale = trimmed;

package/lib/lifecycle-modes.js

@@ -0,0 +1,213 @@
+// lib/lifecycle-modes.js
+//
+// COMP-ROADMAP-MODES — the mode-keyed lifecycle registry (keystone).
+//
+// Compose's lifecycle data (phase graph, skippable/terminal sets, the
+// completion edge, per-phase artifacts, edge evidence, phase ordering, and the
+// runner's per-mode behavioral switches) was hard-coded to the BUILD graph and
+// scattered across server/lifecycle-guard.js, server/artifact-manager.js, and
+// lib/build.js. This module lifts that data into a single source of truth keyed
+// by lifecycle mode (`build | fix | plan`), so a third lifecycle (`plan`) is a
+// data add, not a code fork, and so integration ports can later be pluggable.
+//
+// INVARIANT: the `build` entry reproduces the legacy hard-coded data VERBATIM —
+// `build` behavior must stay byte-identical. test/lifecycle-modes.test.js pins
+// the build entry against the legacy exports.
+//
+// Pure data + accessors. No imports from server/ (lib is the lower layer; the
+// runner and server consume THIS, never the reverse). Loaders/functions stay in
+// their owning modules, keyed here by a string the consumer interprets.
+//
+// See docs/features/COMP-ROADMAP-MODES/{design,blueprint,plan}.md.
+
+/**
+ * @typedef {Object} ModeRunnerConfig
+ * @property {'features'|'docs/bugs'|'docs/plans'} artifactRoot  token the runner maps to a dir
+ * @property {boolean} runsTriage         whether the runner runs feature triage
+ * @property {boolean} tracksFeatureJson  whether the runner writes feature.json lifecycle status
+ * @property {'feature'|'bug'|'plan'} descriptionLoader  which description loader the runner uses
+ * @property {'feature'|'bug'|'plan'} planInputs          which Stratum plan-input shape to build
+ * @property {string} defaultTemplate     default Stratum template name for the mode
+ */
+
+/** The mode registry. Keys are canonical modes; `build` data is verbatim-legacy. */
+export const LIFECYCLE_MODES = {
+  // -------------------------------------------------------------------------
+  // BUILD — verbatim from server/lifecycle-guard.js (BASE_TRANSITIONS/SKIPPABLE/
+  // TERMINAL) + server/artifact-manager.js (PHASE_ARTIFACTS) + the runner's
+  // current feature behavior. MUST stay byte-identical.
+  // -------------------------------------------------------------------------
+  build: {
+    transitions: {
+      explore_design: ['prd', 'architecture', 'blueprint'],
+      prd: ['architecture', 'blueprint'],
+      architecture: ['blueprint'],
+      blueprint: ['verification'],
+      verification: ['plan', 'blueprint'],
+      plan: ['execute'],
+      execute: ['report', 'docs'],
+      report: ['docs'],
+      docs: ['ship'],
+      ship: [],
+    },
+    skippable: ['prd', 'architecture', 'report'],
+    terminal: ['complete', 'killed'],
+    genesis: 'explore_design',
+    completablePhase: 'ship', // the phase that → complete (was hard-coded by name)
+    phaseArtifacts: ['design.md', 'prd.md', 'architecture.md', 'blueprint.md', 'plan.md', 'report.md'],
+    edgeEvidence: {
+      'explore_design->blueprint': 'design.md',
+      'blueprint->verification': 'blueprint.md',
+      'plan->execute': 'plan.md',
+    },
+    phaseOrder: ['explore_design', 'prd', 'architecture', 'blueprint', 'verification', 'plan', 'execute', 'report', 'docs', 'ship'],
+    runner: {
+      artifactRoot: 'features',
+      runsTriage: true,
+      tracksFeatureJson: true,
+      descriptionLoader: 'feature',
+      planInputs: 'feature',
+      defaultTemplate: 'build',
+    },
+  },
+
+  // -------------------------------------------------------------------------
+  // FIX — describes today's bug-fix lifecycle. Data parity only: the bug flow
+  // registers NO guard today and MODES does not change that, so the graph here
+  // is informational (exercised by registry tests, not wired into a live guard).
+  // The `runner` block IS load-bearing: it reproduces today's bug runner
+  // behavior byte-identically (docs/bugs root, no triage, no feature.json).
+  // phaseArtifacts is [] → assess() falls back to the global default set, which
+  // is exactly how bug items are assessed today (no change).
+  // -------------------------------------------------------------------------
+  fix: {
+    transitions: {
+      reproduce: ['diagnose'],
+      diagnose: ['scope_check', 'fix'],
+      scope_check: ['fix'],
+      fix: ['test'],
+      test: ['verify', 'fix'],
+      verify: ['retro_check', 'ship'],
+      retro_check: ['ship'],
+      ship: [],
+    },
+    skippable: [],
+    terminal: ['complete', 'killed'],
+    genesis: 'reproduce',
+    completablePhase: 'ship',
+    phaseArtifacts: [], // empty → assess uses the global default (preserves today's bug behavior)
+    edgeEvidence: {},
+    phaseOrder: ['reproduce', 'diagnose', 'scope_check', 'fix', 'test', 'verify', 'retro_check', 'ship'],
+    runner: {
+      artifactRoot: 'docs/bugs',
+      runsTriage: false,
+      tracksFeatureJson: false,
+      descriptionLoader: 'bug',
+      planInputs: 'bug',
+      defaultTemplate: 'bug-fix',
+    },
+  },
+
+  // -------------------------------------------------------------------------
+  // PLAN — minimal SEED graph. COMP-ROADMAP-PLAN owns the real plan lifecycle
+  // (framing → research → ideation → convergence → build-handshake) and the
+  // `compose plan` command. MODES ships only the mechanism: a coherent seed so
+  // a third mode is proven to be a data add. Not run by any CLI command yet.
+  // -------------------------------------------------------------------------
+  plan: {
+    transitions: {
+      explore_design: ['plan'],
+      plan: ['ship'],
+      ship: [],
+    },
+    skippable: [],
+    terminal: ['complete', 'killed'],
+    genesis: 'explore_design',
+    completablePhase: 'ship',
+    phaseArtifacts: ['design.md', 'plan.md'],
+    edgeEvidence: { 'explore_design->plan': 'design.md' },
+    phaseOrder: ['explore_design', 'plan', 'ship'],
+    runner: {
+      artifactRoot: 'docs/plans',
+      runsTriage: false,
+      tracksFeatureJson: false,
+      descriptionLoader: 'plan',
+      planInputs: 'plan',
+      defaultTemplate: 'plan',
+    },
+  },
+};
+
+/**
+ * Map any runtime or canonical mode token to a canonical registry key. Any key
+ * present in LIFECYCLE_MODES resolves to itself — so adding a new mode is a
+ * DATA-ONLY change (no edit here). The legacy runtime aliases (feature→build,
+ * bug→fix) are honored for back-compat; everything else falls back to build.
+ */
+export function resolveMode(raw) {
+  if (raw && Object.prototype.hasOwnProperty.call(LIFECYCLE_MODES, raw)) return raw;
+  if (raw === 'bug') return 'fix';
+  if (raw === 'feature') return 'build';
+  return 'build'; // undefined / null / unknown → build (legacy default)
+}
+
+/** Get the mode entry, normalizing the input. Unknown → build. */
+export function getMode(mode) {
+  return LIFECYCLE_MODES[resolveMode(mode)];
+}
+
+export function genesisOf(mode) {
+  return getMode(mode).genesis;
+}
+
+export function completablePhaseOf(mode) {
+  return getMode(mode).completablePhase;
+}
+
+export function transitionsOf(mode) {
+  return getMode(mode).transitions;
+}
+
+export function skippableOf(mode) {
+  return getMode(mode).skippable;
+}
+
+export function terminalOf(mode) {
+  return getMode(mode).terminal;
+}
+
+export function phaseOrderOf(mode) {
+  return getMode(mode).phaseOrder;
+}
+
+/** Per-edge ("from->to" → artifact filename) evidence map for the mode. */
+export function edgeEvidenceOf(mode) {
+  return getMode(mode).edgeEvidence;
+}
+
+/**
+ * The union of every mode's phase vocabulary — each mode's `phaseOrder` plus its
+ * terminal phases. Read-side recognizers (e.g. status-snapshot's KNOWN_PHASES)
+ * derive from this so a non-build-mode phase isn't flagged "unrecognized".
+ * MUST include the terminal phases (complete/killed): the snapshot's
+ * unknown-phase guard runs BEFORE its terminal branches.
+ */
+export function allKnownPhases() {
+  const set = new Set();
+  for (const key of Object.keys(LIFECYCLE_MODES)) {
+    const m = LIFECYCLE_MODES[key];
+    for (const p of m.phaseOrder) set.add(p);
+    for (const t of m.terminal) set.add(t);
+  }
+  return [...set];
+}
+
+/**
+ * The artifact filenames a mode declares. An EMPTY list means "no narrowing" —
+ * the artifact manager falls back to the global ARTIFACT_SCHEMAS key set (which
+ * is exactly today's behavior for build and bug items). A non-empty list scopes
+ * assessment to that subset.
+ */
+export function artifactsOf(mode) {
+  return getMode(mode).phaseArtifacts;
+}

package/lib/new.js

@@ -16,6 +16,7 @@ import { installFactoryShim } from './connector-factory-shim.js';
 import { buildStepPrompt, buildRetryPrompt, buildGateContext } from './step-prompt.js';
 import { promptGate } from './gate-prompt.js';
 import { VisionWriter } from './vision-writer.js';
+import { readFlowRound } from './flow-state.js';
 
 import { validateStep } from './step-validator.js';
 
@@ -197,7 +198,9 @@ export async function runNew(intent, opts = {}) {
           }
         }
 
-        const gateId = await visionWriter.createGate(flowId, stepId, itemId);
+        // COMP-PLAN-GATE-LOOP: round-aware gate id so a revise re-entry mints a
+        // fresh gate instead of reusing the prior resolved one.
+        const gateId = await visionWriter.createGate(flowId, stepId, itemId, { round: readFlowRound(flowId) });
 
         // Resolve artifact path for this gate
         const gateArtifact = priorValConfig?.artifact
@@ -340,7 +343,8 @@ async function executeChildFlow(
 
     } else if (resp.status === 'await_gate') {
       console.log(`  [${childFlowName}] Gate: ${resp.step_id}`);
-      const gateId = await visionWriter.createGate(childFlowId, resp.step_id, itemId);
+      // COMP-PLAN-GATE-LOOP: round-aware gate id (child flow has its own round).
+      const gateId = await visionWriter.createGate(childFlowId, resp.step_id, itemId, { round: readFlowRound(childFlowId) });
       const { outcome, rationale } = await promptGate(resp, gateOpts);
       await visionWriter.resolveGate(gateId, outcome);
       resp = await stratum.gateResolve(childFlowId, resp.step_id, outcome, rationale, 'human');

package/lib/roadmap-graph/index.js

@@ -1,45 +1,47 @@
 /**
- * index.js — public API for the roadmap dependency graph generator
- * (COMP-ROADMAP-GRAPH-1).
+ * index.js — shared render/write/check helpers for the roadmap dependency
+ * graph (COMP-ROADMAP-GRAPH-1 renderer; COMP-ROADMAP-GRAPH-2 made it
+ * source-agnostic). The collection of inputs lives with the caller — today the
+ * sole collector is the vision projection in server/roadmap-graph-vision.js.
  *
- *   generateRoadmapGraph(cwd, opts) — render + atomic-write the HTML
- *   checkRoadmapGraph(cwd, opts)    — render in-memory, diff vs on-disk
+ *   buildArtifactFromInputs(cwd, inputs) — buildGraph + render (no write)
+ *   writeArtifact(cwd, built, opts)      — atomic-write the HTML
+ *   checkArtifact(cwd, built, opts)      — diff vs on-disk
  *
- * Both throw DanglingEdgeError (code DANGLING_EDGE) when an edge points at an
- * unknown feature — the Cytoscape-crash bug class this feature kills.
+ * buildGraph throws DanglingEdgeError (code DANGLING_EDGE) when an edge points
+ * at an unknown feature — the Cytoscape-crash bug class this feature kills.
  */
 import { existsSync, readFileSync, writeFileSync, renameSync, unlinkSync, mkdirSync } from 'node:fs';
 import { join, isAbsolute, dirname } from 'node:path';
-import { resolveFeaturesPath } from '../project-paths.js';
-import { collectGraphInputs } from './collect.js';
 import { buildGraph } from './model.js';
 import { renderGraphHtml } from './render.js';
 import { loadGraphConfig } from './config.js';
 
 /**
- * Build the HTML + graph stats for a project without writing to disk.
+ * Build the HTML + stats from already-collected graph inputs. The inputs may
+ * come from any collector (the static feature.json/deps.yaml path, or the
+ * vision-store canonical projection) — this is the single render seam.
  * @param {string} cwd
- * @returns {{ html: string, nodes: object[], edges: object[], dropped: string[], warnings: string[], config: object }}
+ * @param {{ nodes: object[], rawEdges: object[], knownCodes: Set<string>, warnings?: string[] }} inputs
  */
-export function buildRoadmapGraph(cwd) {
-  const featuresDir = resolveFeaturesPath(cwd);
-  const inputs = collectGraphInputs(cwd, featuresDir);
+export function buildArtifactFromInputs(cwd, inputs) {
   const graph = buildGraph(inputs); // throws DanglingEdgeError
   const config = loadGraphConfig(cwd);
   const html = renderGraphHtml({ nodes: graph.nodes, edges: graph.edges, config });
-  return { html, nodes: graph.nodes, edges: graph.edges, dropped: graph.dropped, warnings: inputs.warnings, config };
+  return { html, nodes: graph.nodes, edges: graph.edges, dropped: graph.dropped, warnings: inputs.warnings || [], config };
+}
+
+function resolveOutPath(cwd, built, opts) {
+  const outRel = opts.out || built.config.out;
+  return isAbsolute(outRel) ? outRel : join(cwd, outRel);
 }
 
 /**
- * Generate and atomically write roadmap-graph.html.
- * @param {string} cwd project root
- * @param {{ out?: string }} [opts] out path (relative to cwd unless absolute); defaults to config.out
+ * Atomically write a built artifact's HTML and return the summary.
  * @returns {{ path: string, nodeCount: number, edgeCount: number, droppedCount: number, warnings: string[] }}
  */
-export function generateRoadmapGraph(cwd, opts = {}) {
-  const built = buildRoadmapGraph(cwd);
-  const outRel = opts.out || built.config.out;
-  const outPath = isAbsolute(outRel) ? outRel : join(cwd, outRel);
+export function writeArtifact(cwd, built, opts = {}) {
+  const outPath = resolveOutPath(cwd, built, opts);
   atomicWrite(outPath, built.html);
   return {
     path: outPath,
@@ -51,15 +53,11 @@ export function generateRoadmapGraph(cwd, opts = {}) {
 }
 
 /**
- * Render in-memory and compare to the on-disk file.
- * @param {string} cwd
- * @param {{ out?: string }} [opts]
+ * Compare a built artifact's HTML to the on-disk file.
  * @returns {{ matches: boolean, path: string, exists: boolean, diffSummary: string, nodeCount: number, edgeCount: number, warnings: string[] }}
  */
-export function checkRoadmapGraph(cwd, opts = {}) {
-  const built = buildRoadmapGraph(cwd);
-  const outRel = opts.out || built.config.out;
-  const outPath = isAbsolute(outRel) ? outRel : join(cwd, outRel);
+export function checkArtifact(cwd, built, opts = {}) {
+  const outPath = resolveOutPath(cwd, built, opts);
   const exists = existsSync(outPath);
   const onDisk = exists ? readFileSync(outPath, 'utf-8') : null;
   const matches = exists && onDisk === built.html;

package/lib/roadmap-graph/vision-adapter.js

@@ -0,0 +1,126 @@
+/**
+ * vision-adapter.js — COMP-ROADMAP-GRAPH-2.
+ *
+ * Converts a VisionStore's items + connections into the
+ * { nodes, rawEdges, knownCodes, warnings } shape that buildGraph() consumes
+ * (the same shape collect.js produces from feature.json/deps.yaml). This is the
+ * single seam that lets the cockpit/vision model drive the one canonical
+ * renderer (buildGraph -> renderGraphHtml).
+ *
+ * The adapter is source-agnostic: it is fed the LIVE in-memory store (cockpit
+ * export routes) or a freshly-seeded throwaway store (canonical headless
+ * generation). Both go through this one function.
+ */
+
+// Vision connection vocab -> graph edge vocab. Mirrors the dependency/parallel
+// split the static path encodes in deps.yaml (depends_on/blocks -> dep,
+// concurrent_with -> concurrent).
+const VISION_EDGE_TYPE_MAP = {
+  blocks: 'dep',
+  informs: 'dep',
+  implements: 'dep',
+  supports: 'concurrent',
+  contradicts: 'concurrent',
+};
+
+// Vision status (lowercase, 9 values) -> buildGraph input status (UPPERCASE).
+// COMPLETE/KILLED/SUPERSEDED are DROP_STATUSES in model.js and get dropped there.
+const VISION_STATUS_MAP = {
+  planned: 'PLANNED',
+  ready: 'PLANNED',
+  in_progress: 'IN_PROGRESS',
+  review: 'IN_PROGRESS',
+  complete: 'COMPLETE',
+  blocked: 'BLOCKED',
+  parked: 'PARKED',
+  killed: 'KILLED',
+  superseded: 'SUPERSEDED',
+};
+
+function toUpperStatus(status) {
+  return VISION_STATUS_MAP[status] || String(status || '').toUpperCase() || 'PLANNED';
+}
+
+/**
+ * Remove `Track:` / `Priority:` annotation lines from a description so the
+ * graph `desc` is clean prose. The static path reads these from structured
+ * metadata; the cockpit historically encoded them inline.
+ */
+function stripTrackPriority(description) {
+  if (!description) return '';
+  return String(description)
+    .split('\n')
+    .filter((line) => !/^\s*(track|priority)\s*:/i.test(line))
+    .join('\n')
+    .trim();
+}
+
+/**
+ * @param {Array} items - vision items (e.g. [...store.items.values()])
+ * @param {Array} connections - vision connections (e.g. [...store.connections.values()])
+ * @param {{externalPrefixes?: string[], includeProseEdges?: boolean}} [opts]
+ *   includeProseEdges (default true): the LIVE projection renders every
+ *   relationship, including prose-derived `informs` edges (shipped cockpit
+ *   behavior). The CANONICAL projection passes false so only structural
+ *   (deps.yaml-derived blocks/supports/...) edges remain, matching the static
+ *   collector which only ever drew deps.yaml edges.
+ * @returns {{nodes: object[], rawEdges: object[], knownCodes: Set<string>, warnings: string[]}}
+ */
+export function visionToGraphInputs(items, connections, { externalPrefixes = [], includeProseEdges = true } = {}) {
+  const isExternal = (code) => externalPrefixes.some((p) => code && code.startsWith(p));
+  const warnings = [];
+  const nodes = [];
+  const knownCodes = new Set();
+  const idToCode = new Map();
+
+  for (const it of items || []) {
+    if (it.type !== 'feature') continue;
+    // The live store carries the canonical code in lifecycle.featureCode
+    // (set via updateLifecycle); the top-level featureCode and title are
+    // fallbacks. Mirror the precedence the export route used historically.
+    const code = it.lifecycle?.featureCode || it.featureCode || it.title;
+    if (!code) continue;
+    idToCode.set(it.id, code);
+    knownCodes.add(code);
+    // External-prefixed codes are known (so edges to them don't dangle) but are
+    // not rendered as nodes — buildGraph silently drops their edges.
+    if (isExternal(code)) continue;
+    nodes.push({
+      id: code,
+      status: toUpperStatus(it.status),
+      name: it.title || code,
+      priority: it.priority || 'medium',
+      track: it.group || 'standalone',
+      desc: stripTrackPriority(it.description),
+    });
+  }
+
+  const rawEdges = [];
+  for (const c of connections || []) {
+    const fromCode = idToCode.get(c.fromId);
+    const toCode = idToCode.get(c.toId);
+    if (!fromCode || !toCode) {
+      const bad = !fromCode ? c.fromId : c.toId;
+      warnings.push(`connection ${c.id}: endpoint ${bad} is not a feature node (unresolved) — dropped`);
+      continue;
+    }
+    // `informs` is the prose-derived relationship type. The canonical
+    // projection excludes it so it matches the deps.yaml-only static collector.
+    if (!includeProseEdges && c.type === 'informs') continue;
+    const type = VISION_EDGE_TYPE_MAP[c.type];
+    if (!type) {
+      warnings.push(`connection ${c.id}: unmapped connection type "${c.type}" — dropped`);
+      continue;
+    }
+    rawEdges.push({ from: fromCode, to: toCode, type });
+  }
+
+  // Deterministic node order (independent of readdirSync / store insertion order)
+  // so the rendered HTML is byte-stable for --check. buildGraph preserves this
+  // order; edges are sorted inside buildGraph.
+  nodes.sort((a, b) => a.id.localeCompare(b.id));
+
+  return { nodes, rawEdges, knownCodes, warnings };
+}
+
+export { VISION_EDGE_TYPE_MAP, VISION_STATUS_MAP };

package/lib/stratum-mcp-client.js

@@ -139,6 +139,15 @@ export class StratumMcpClient {
 
     const transportOpts = { command, args, stderr: 'pipe' };
     if (opts.cwd) transportOpts.cwd = opts.cwd;
+    // Inherit the parent environment. Given no `env`, StdioClientTransport
+    // supplies only the MCP SDK's 6-var default allowlist
+    // (HOME/LOGNAME/PATH/SHELL/TERM/USER), which strips the auth context the
+    // spawned stratum-mcp → claude agent needs. Once claude credentials moved
+    // to the macOS keychain, that stripped env stopped authenticating and every
+    // agent step failed with `403 forbidden / "Request not allowed"`. Pass the
+    // full env through; the stratum connector scrubs SENSITIVE_ENV_VARS
+    // (API keys, CLAUDECODE) before it spawns the agent.
+    transportOpts.env = opts.env ?? { ...process.env };
     this.#transport = new StdioClientTransport(transportOpts);
 
     this.#client = new Client(

package/lib/triage.js

@@ -232,7 +232,9 @@ export async function runTriage(featureCode, opts = {}) {
  *
  * Returns true if:
  *   - feature.json has no triageTimestamp
- *   - any file in the feature folder has an mtime newer than triageTimestamp
+ *   - any file in the feature folder (EXCEPT feature.json itself) has an mtime
+ *     newer than triageTimestamp. feature.json is excluded because the stamp it
+ *     is compared against lives inside it, so its own mtime would self-stale.
  *
  * @param {string} cwd - Project root
  * @param {string} featureCode - Feature code
@@ -263,6 +265,10 @@ export function isTriageStale(cwd, featureCode, featuresDir = resolveFeaturesPat
     const entries = readdirSync(featureDir, { withFileTypes: true });
     for (const entry of entries) {
       if (!entry.isFile()) continue;
+      // feature.json holds the triageTimestamp we compare against — counting its
+      // own mtime is circular: writing the stamp would self-invalidate the cache
+      // (COMP-ROADMAP-PLAN C14). Exclude it from the staleness scan.
+      if (entry.name === 'feature.json') continue;
       const filePath = join(featureDir, entry.name);
       try {
         const stat = statSync(filePath);