@smartmemory/compose 0.2.52-beta → 0.2.54-beta

package/server/roadmap-graph-vision.js

@@ -0,0 +1,138 @@
+/**
+ * roadmap-graph-vision.js — COMP-ROADMAP-GRAPH-2 S4.
+ *
+ * The CANONICAL projection of the one graph model: build the roadmap graph from
+ * a freshly, deterministically seeded vision store (committed source only — no
+ * persisted cockpit state), through the same adapter + renderer the live
+ * cockpit export uses. This is what the headless CLI / MCP / CI call.
+ *
+ * Lives in server/ (not lib/) because it depends on the vision store + seed,
+ * which are server-side; it reuses the pure render/write/check helpers from
+ * lib/roadmap-graph/index.js. This is the seam that lets us retire collect.js.
+ */
+import { mkdtempSync, existsSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { VisionStore } from './vision-store.js';
+import { scanFeatures, seedFeatures } from './feature-scan.js';
+import { resolveFeaturesPath, resolveRoadmapPath, loadExternalPrefixes } from '../lib/project-paths.js';
+import { parseRoadmap } from '../lib/roadmap-parser.js';
+import { visionToGraphInputs } from '../lib/roadmap-graph/vision-adapter.js';
+import { depsToEdges, DanglingEdgeError } from '../lib/roadmap-graph/model.js';
+import { buildArtifactFromInputs, writeArtifact, checkArtifact } from '../lib/roadmap-graph/index.js';
+
+// ROADMAP/feature UPPERCASE status -> vision status. The vision vocab has no
+// `partial`; PARTIAL collapses to in_progress (documented delta — the adapter
+// maps it back to IN_PROGRESS, so a PARTIAL feature renders as in_progress in
+// the canonical graph rather than the static path's `partial` border).
+const ROADMAP_TO_VISION_STATUS = {
+  PLANNED: 'planned',
+  IN_PROGRESS: 'in_progress',
+  PARTIAL: 'in_progress',
+  COMPLETE: 'complete',
+  BLOCKED: 'blocked',
+  PARKED: 'parked',
+  KILLED: 'killed',
+  SUPERSEDED: 'superseded',
+};
+
+function toVisionStatus(status) {
+  return ROADMAP_TO_VISION_STATUS[String(status || 'PLANNED').toUpperCase()] || 'planned';
+}
+
+/**
+ * Seed ROADMAP.md rows that lack a feature folder as fallback feature items,
+ * mirroring collect.js section (b) so the node universe matches.
+ */
+function seedRoadmapFallback(store, cwd, externalPrefixes) {
+  const roadmapPath = resolveRoadmapPath(cwd);
+  if (!existsSync(roadmapPath)) return;
+  const isExternal = (code) => externalPrefixes.some((p) => code.startsWith(p));
+  const have = new Set(
+    [...store.items.values()]
+      .filter((i) => i.type === 'feature')
+      .map((i) => i.lifecycle?.featureCode || i.title),
+  );
+  let entries = [];
+  try { entries = parseRoadmap(readFileSync(roadmapPath, 'utf-8')); } catch { return; }
+  for (const e of entries) {
+    if (!e.code || e.code.startsWith('_anon_')) continue;
+    if (have.has(e.code) || isExternal(e.code)) continue;
+    const item = store.createItem({
+      type: 'feature',
+      title: e.code,
+      description: e.description || '',
+      status: toVisionStatus(e.status),
+      phase: 'planning',
+      confidence: 0,
+      group: 'standalone',
+    });
+    try { store.updateLifecycle(item.id, { featureCode: e.code, currentPhase: 'explore_design' }); } catch { /* optional */ }
+    have.add(e.code);
+  }
+}
+
+/**
+ * Build the canonical graph inputs from committed source via a throwaway store.
+ * @param {string} cwd
+ * @returns {{ nodes, rawEdges, knownCodes, warnings }}
+ */
+export function collectVisionInputs(cwd) {
+  const dataDir = mkdtempSync(join(tmpdir(), 'rg2-canonical-'));
+  try {
+    const store = new VisionStore(dataDir);
+    const featuresDir = resolveFeaturesPath(cwd);
+    const externalPrefixes = loadExternalPrefixes(cwd);
+    // Canon: only feature.json-backed folders are managed features (mirrors
+    // collect.js's listFeatures universe — doc-only folders are not nodes).
+    const features = scanFeatures(featuresDir).filter((f) => f.hasFeatureJson);
+    seedFeatures(features, store);
+    seedRoadmapFallback(store, cwd, externalPrefixes);
+
+    // Preserve the dangling-edge refusal (the anti-typo lint kept from the
+    // static path). A deps.yaml edge to a code that resolves to no managed
+    // feature and isn't an external reference can't become a connection, so it
+    // would silently vanish; detect + refuse instead, mirroring collect.js.
+    const isExternal = (code) => externalPrefixes.some((p) => code.startsWith(p));
+    const known = new Set(
+      [...store.items.values()]
+        .filter((i) => i.type === 'feature')
+        .map((i) => i.lifecycle?.featureCode || i.title),
+    );
+    const dangling = [];
+    for (const f of features) {
+      if (!f.deps) continue;
+      for (const e of depsToEdges(f.name, f.deps)) {
+        const missing = [e.from, e.to].filter((c) => !known.has(c) && !isExternal(c));
+        if (missing.length) dangling.push({ from: e.from, to: e.to, kind: e.type, missing });
+      }
+    }
+    if (dangling.length) throw new DanglingEdgeError(dangling);
+
+    return visionToGraphInputs(
+      [...store.items.values()],
+      [...store.connections.values()],
+      { externalPrefixes, includeProseEdges: false },
+    );
+  } finally {
+    try { rmSync(dataDir, { recursive: true, force: true }); } catch { /* best-effort */ }
+  }
+}
+
+/** Build HTML + stats from the canonical vision projection (no disk write). */
+export function buildRoadmapGraph(cwd) {
+  return buildArtifactFromInputs(cwd, collectVisionInputs(cwd));
+}
+
+/** Generate + atomically write roadmap-graph.html from the canonical projection. */
+export function generateRoadmapGraph(cwd, opts = {}) {
+  return writeArtifact(cwd, buildRoadmapGraph(cwd), opts);
+}
+
+/** Render in-memory and diff vs on-disk, from the canonical projection. */
+export function checkRoadmapGraph(cwd, opts = {}) {
+  return checkArtifact(cwd, buildRoadmapGraph(cwd), opts);
+}
+
+export { DanglingEdgeError };

package/server/smartmemory-routes.js

@@ -0,0 +1,113 @@
+/**
+ * smartmemory-routes.js — COMP-SMARTMEMORY-RECALL S01.
+ *
+ * Route:
+ *   GET /api/smartmemory/recall?featureCode=<CODE> — ranked prior-context
+ *     lookup for the cockpit's Recall tab, backed by INGEST's SmartMemory
+ *     client + config (lib/smartmemory-client.js, lib/smartmemory-config.js).
+ *
+ * Degrade-never-fail (the qa-scope-routes.js model): every branch returns a
+ * shaped 200, never a throw. Flag OFF (or no workspace root) answers from
+ * config alone — zero client construction, zero SmartMemory-bound traffic.
+ *
+ * Not on the auth allowlist (server/index.js) — auth-gated in remote mode
+ * like the vision routes, since results can carry local project context.
+ */
+import { getSmartmemoryConfig, resolveProjectTag as defaultResolveProjectTag } from '../lib/smartmemory-config.js';
+import { createSmartmemoryClient } from '../lib/smartmemory-client.js';
+import { readFeature as defaultReadFeature } from '../lib/feature-json.js';
+import { resolveFeaturesPath as defaultResolveFeaturesPath } from '../lib/project-paths.js';
+
+function defaultCreateClient(cfg) {
+  return createSmartmemoryClient(cfg);
+}
+
+function shortReason(e) {
+  return e?.message?.slice(0, 200) || 'unreachable';
+}
+
+function safeProjectTag(resolveProjectTag, root) {
+  try {
+    return resolveProjectTag(root);
+  } catch {
+    return null;
+  }
+}
+
+/** Defensive adapter over the SmartMemory hit shape (multiple field-name fallbacks). */
+function mapHit(hit) {
+  const content = hit?.content ?? hit?.text ?? '';
+  return {
+    id: hit?.id ?? hit?.item_id ?? null,
+    snippet: content.length > 280 ? content.slice(0, 280) + '…' : content,
+    score: hit?.score ?? null,
+    memoryType: hit?.memory_type ?? hit?.memoryType ?? null,
+    ts: hit?.context?.event?.ts ?? hit?.context?.ts ?? hit?.ts ?? null,
+    project: hit?.context?.project ?? null,
+  };
+}
+
+/**
+ * @param {import('express').Express} app
+ * @param {object} [deps]
+ * @param {Function} [deps.getConfig]           — (cwd) => {} | {enabled,baseUrl,apiKeyEnv,timeoutMs}
+ * @param {Function} [deps.createClient]         — (cfg) => { search(query, opts) }
+ * @param {Function} [deps.readFeature]          — (cwd, code, featuresDir) => FeatureJson|null
+ * @param {Function} [deps.resolveFeaturesPath]  — (cwd) => absolute features dir
+ * @param {Function} [deps.resolveProjectTag]    — (cwd) => canonical project tag
+ */
+export function attachSmartmemoryRoutes(app, {
+  getConfig = getSmartmemoryConfig,
+  createClient = defaultCreateClient,
+  readFeature = defaultReadFeature,
+  resolveFeaturesPath = defaultResolveFeaturesPath,
+  resolveProjectTag = defaultResolveProjectTag,
+} = {}) {
+  app.get('/api/smartmemory/recall', async (req, res) => {
+    const root = req.workspace?.root;
+    if (!root) {
+      return res.json({ enabled: false });
+    }
+
+    let cfg;
+    try {
+      cfg = getConfig(root);
+    } catch {
+      cfg = {};
+    }
+    if (cfg?.enabled !== true) {
+      return res.json({ enabled: false });
+    }
+
+    const featureCode = (req.query.featureCode || '').toString().trim();
+    if (!featureCode) {
+      return res.json({ enabled: true, available: true, results: [], invalidFeatureCode: true });
+    }
+
+    let feature;
+    try {
+      feature = readFeature(root, featureCode, resolveFeaturesPath(root));
+    } catch {
+      feature = null;
+    }
+    const desc = feature?.description || '';
+    const query = desc ? `${featureCode} ${desc}` : featureCode;
+
+    let hits;
+    try {
+      const client = createClient(cfg);
+      hits = await client.search(query, { top_k: 10 });
+    } catch (e) {
+      return res.json({ enabled: true, available: false, error: shortReason(e) });
+    }
+
+    const results = (Array.isArray(hits) ? hits : (hits?.results ?? [])).map(mapHit);
+    return res.json({
+      enabled: true,
+      available: true,
+      featureCode,
+      project: safeProjectTag(resolveProjectTag, root),
+      results,
+    });
+  });
+}

package/server/status-snapshot.js

@@ -21,13 +21,14 @@
 
 import { readGateLog } from './gate-log-store.js';
 import { isStaleLoop } from './open-loops-store.js';
-
-// Known lifecycle phases — must match LIFECYCLE_PHASE_LABELS in constants.js
-const KNOWN_PHASES = new Set([
-  'explore_design', 'prd', 'architecture', 'blueprint',
-  'verification', 'plan', 'execute', 'report', 'docs', 'ship',
-  'complete', 'killed',
-]);
+import { allKnownPhases } from '../lib/lifecycle-modes.js';
+
+// Known lifecycle phases — DERIVED from the mode registry (the union of every
+// mode's phaseOrder ∪ terminal). This is a superset of the legacy build-only
+// list, so non-build-mode phases (e.g. a fix lifecycle's `diagnose`) are no
+// longer flagged "unrecognized". It still includes the terminal phases, which
+// is required because the unknown-phase guard runs BEFORE the terminal branches.
+const KNOWN_PHASES = new Set(allKnownPhases());
 
 const TERMINAL_PHASES = new Set(['complete', 'killed']);
 const MAX_SENTENCE = 280;

package/server/vision-routes.js

@@ -50,10 +50,13 @@ import { anchorBoundary } from '../lib/checkpoint/checkpoint-writer.js';
 import { appendGateLogEntry, readGateLog, mapResolveOutcomeToSchema } from './gate-log-store.js';
 import { addOpenLoop, resolveOpenLoop, listOpenLoops } from './open-loops-store.js';
 import {
-  BASE_TRANSITIONS, SKIPPABLE, TERMINAL,
+  TERMINAL,
   guardedTransition, ensureGuard, projectFeatureStatus,
   verifyCompletionEvidence, guardTestCommand,
 } from './lifecycle-guard.js';
+import {
+  transitionsOf, skippableOf, completablePhaseOf, getMode, resolveMode,
+} from '../lib/lifecycle-modes.js';
 import { requireSensitiveOrPaired as requireSensitiveToken } from './security.js';
 
 const PROJECT_ROOT = getTargetRoot();
@@ -214,9 +217,13 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
     ? resolveFeaturesPathFromConfig(projectRoot, loadComposeConfig(projectRoot))
     : resolveProjectPath('features');
 
-  // Phase graph + SKIPPABLE + TERMINAL are owned by lifecycle-guard.js (single
-  // source of truth shared with the STRAT-GUARD graph) — see COMP-MCP-ENFORCE.
-  const TRANSITIONS = BASE_TRANSITIONS;
+  // Phase graph + skippable + terminal are owned by the mode registry (single
+  // source of truth shared with the STRAT-GUARD graph) — see COMP-MCP-ENFORCE /
+  // COMP-ROADMAP-MODES. Legality is resolved PER-ITEM from its lifecycle mode
+  // (build|fix|plan); legacy items with no mode default to build, so build
+  // transitions are byte-identical. typeToMode stamps the mode at creation.
+  const modeOf = (item) => item?.lifecycle?.mode ?? 'build';
+  const typeToMode = (type) => (type === 'bug' ? 'fix' : 'build');
   const ITERATION_TYPES = new Set(['review', 'coverage']);
 
   app.get('/api/vision/items/:id/lifecycle', (req, res) => {
@@ -251,9 +258,18 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       if (!item) return res.status(404).json({ error: `Item not found: ${req.params.id}` });
       if (item.lifecycle) return res.status(400).json({ error: `Item ${req.params.id} already has a lifecycle` });
 
+      // COMP-ROADMAP-MODES / COMP-ROADMAP-PLAN: stamp the lifecycle mode. Prefer
+      // an explicit mode on the start payload (the CLI/VisionWriter forwards
+      // `mode` so a plan session is stamped mode='plan'), normalized through
+      // resolveMode (feature→build, bug→fix). Fall back to typeToMode(item.type)
+      // when the caller does not specify one — byte-identical to pre-PLAN for
+      // build AND bug. The genesis phase stays 'explore_design'.
+      const mode = req.body.mode != null ? resolveMode(req.body.mode) : typeToMode(item.type);
+      const genesis = 'explore_design';
       const now = new Date().toISOString();
       const lifecycle = {
-        currentPhase: 'explore_design',
+        currentPhase: genesis,
+        mode,
         featureCode,
         startedAt: now,
         completedAt: null,
@@ -261,22 +277,26 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
         killReason: null,
       };
       // COMP-OBS-TIMELINE: populate phaseHistory before storing
-      appendPhaseHistory({ lifecycle }, { from: null, to: 'explore_design', outcome: null, timestamp: now });
+      appendPhaseHistory({ lifecycle }, { from: null, to: genesis, outcome: null, timestamp: now });
       store.updateLifecycle(req.params.id, lifecycle);
       // COMP-MCP-ENFORCE: eager guard registration seeded at the genesis phase
       // (the clean bootstrap path; backfill for pre-rollout items happens lazily
       // on first transition). Best-effort — a registration hiccup must not block
       // starting a lifecycle; the next guarded transition re-attempts ensureGuard.
       if (guardEnabled) {
-        try { await ensureGuard(featureCode, 'explore_design', projectRoot); }
+        try { await ensureGuard(featureCode, genesis, projectRoot, mode); }
         catch (e) { console.warn(`[lifecycle/start] guard register for ${featureCode} failed: ${e.message}`); }
-        // Slice 2: starting a lifecycle projects explore_design → IN_PROGRESS so
+        // Slice 2: starting a lifecycle projects the genesis phase → IN_PROGRESS so
         // the first active phase is not left stuck at PLANNED in feature.json.
-        await projectFeatureStatus({ featureCode, phase: 'explore_design', cwd: projectRoot });
+        // COMP-ROADMAP-PLAN: skipped for tracksFeatureJson:false modes (e.g. a
+        // plan session has no feature.json to project onto).
+        if (getMode(mode).runner.tracksFeatureJson) {
+          await projectFeatureStatus({ featureCode, phase: genesis, cwd: projectRoot });
+        }
       }
       scheduleBroadcast();
-      broadcastMessage({ type: 'lifecycleStarted', itemId: req.params.id, phase: 'explore_design', featureCode, timestamp: now });
-      emitDecisionEvent(broadcastMessage, buildPhaseTransitionEvent({ featureCode, from: null, to: 'explore_design', outcome: null, timestamp: now }));
+      broadcastMessage({ type: 'lifecycleStarted', itemId: req.params.id, phase: genesis, featureCode, timestamp: now });
+      emitDecisionEvent(broadcastMessage, buildPhaseTransitionEvent({ featureCode, from: null, to: genesis, outcome: null, timestamp: now }));
       // COMP-OBS-DRIFT: emit drift axes before status so STATUS reads fresh drift_axes
       const startedItem = store.items.get(req.params.id);
       if (startedItem) emitDriftAxes(broadcastMessage, store, startedItem, projectRoot, now);
@@ -328,12 +348,12 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       if (!item?.lifecycle) return res.status(404).json({ error: 'No lifecycle on this item' });
       const from = item.lifecycle.currentPhase;
       if (TERMINAL.has(from)) return res.status(400).json({ error: `Cannot advance from terminal state: ${from}` });
-      const valid = TRANSITIONS[from];
+      const valid = transitionsOf(modeOf(item))[from];
       if (!valid?.includes(targetPhase)) return res.status(400).json({ error: `Invalid transition: ${from} → ${targetPhase}` });
 
       // COMP-MCP-ENFORCE: verdict-gate the transition (fail-closed) before mutating.
       if (guardEnabled) {
-        const g = await guardedTransition({ featureCode: item.lifecycle.featureCode, from, to: targetPhase, workspaceRoot: projectRoot, resolvedBy: 'agent' });
+        const g = await guardedTransition({ featureCode: item.lifecycle.featureCode, from, to: targetPhase, workspaceRoot: projectRoot, resolvedBy: 'agent', mode: modeOf(item) });
         if (!g.applied) return res.status(422).json({ error: 'transition refused by guard', from, to: targetPhase, verdict: g.verdict, guardError: g.error });
       }
 
@@ -344,7 +364,8 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       store.updateLifecycle(req.params.id, item.lifecycle);
       // COMP-MCP-ENFORCE Slice 2 (lifecycle-as-truth): project the new phase onto
       // feature.json STATUS (best-effort; idempotent — only writes on a real change).
-      if (guardEnabled) await projectFeatureStatus({ featureCode: item.lifecycle.featureCode, phase: targetPhase, cwd: projectRoot });
+      // COMP-ROADMAP-PLAN: skipped for tracksFeatureJson:false modes (no feature.json).
+      if (guardEnabled && getMode(modeOf(item)).runner.tracksFeatureJson) await projectFeatureStatus({ featureCode: item.lifecycle.featureCode, phase: targetPhase, cwd: projectRoot });
       scheduleBroadcast();
       broadcastMessage({ type: 'lifecycleTransition', itemId: req.params.id, from, to: targetPhase, outcome, timestamp: now });
       emitDecisionEvent(broadcastMessage, buildPhaseTransitionEvent({ featureCode: item.lifecycle.featureCode, from, to: targetPhase, outcome, timestamp: now }));
@@ -368,13 +389,13 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       if (!item?.lifecycle) return res.status(404).json({ error: 'No lifecycle on this item' });
       const from = item.lifecycle.currentPhase;
       if (TERMINAL.has(from)) return res.status(400).json({ error: `Cannot skip from terminal state: ${from}` });
-      if (!SKIPPABLE.has(from)) return res.status(400).json({ error: `Phase ${from} is not skippable` });
-      const valid = TRANSITIONS[from];
+      if (!skippableOf(modeOf(item)).includes(from)) return res.status(400).json({ error: `Phase ${from} is not skippable` });
+      const valid = transitionsOf(modeOf(item))[from];
       if (!valid?.includes(targetPhase)) return res.status(400).json({ error: `Invalid transition: ${from} → ${targetPhase}` });
 
       // COMP-MCP-ENFORCE: verdict-gate the skip (fail-closed) before mutating.
       if (guardEnabled) {
-        const g = await guardedTransition({ featureCode: item.lifecycle.featureCode, from, to: targetPhase, workspaceRoot: projectRoot, resolvedBy: 'agent' });
+        const g = await guardedTransition({ featureCode: item.lifecycle.featureCode, from, to: targetPhase, workspaceRoot: projectRoot, resolvedBy: 'agent', mode: modeOf(item) });
         if (!g.applied) return res.status(422).json({ error: 'transition refused by guard', from, to: targetPhase, verdict: g.verdict, guardError: g.error });
       }
 
@@ -384,7 +405,8 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       appendPhaseHistory(item, { from, to: targetPhase, outcome: 'skipped', timestamp: now });
       store.updateLifecycle(req.params.id, item.lifecycle);
       // COMP-MCP-ENFORCE Slice 2 (lifecycle-as-truth): project phase → STATUS.
-      if (guardEnabled) await projectFeatureStatus({ featureCode: item.lifecycle.featureCode, phase: targetPhase, cwd: projectRoot });
+      // COMP-ROADMAP-PLAN: skipped for tracksFeatureJson:false modes (no feature.json).
+      if (guardEnabled && getMode(modeOf(item)).runner.tracksFeatureJson) await projectFeatureStatus({ featureCode: item.lifecycle.featureCode, phase: targetPhase, cwd: projectRoot });
       scheduleBroadcast();
       broadcastMessage({ type: 'lifecycleTransition', itemId: req.params.id, from, to: targetPhase, outcome: 'skipped', timestamp: now });
       emitDecisionEvent(broadcastMessage, buildPhaseTransitionEvent({ featureCode: item.lifecycle.featureCode, from, to: targetPhase, outcome: 'skipped', timestamp: now }));
@@ -414,7 +436,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       // is unreachable — consistent with advance/skip/complete. Authorized
       // bypass remains stratum_guard_override (Slice 3).
       if (guardEnabled) {
-        const g = await guardedTransition({ featureCode: item.lifecycle.featureCode, from, to: 'killed', workspaceRoot: projectRoot, resolvedBy: 'agent' });
+        const g = await guardedTransition({ featureCode: item.lifecycle.featureCode, from, to: 'killed', workspaceRoot: projectRoot, resolvedBy: 'agent', mode: modeOf(item) });
         if (!g.applied) return res.status(422).json({ error: 'kill refused by guard', from, to: 'killed', verdict: g.verdict, guardError: g.error });
       }
 
@@ -428,7 +450,8 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       store.updateItem(req.params.id, { status: 'killed' });
       // COMP-MCP-ENFORCE Slice 2: project kill → KILLED onto feature.json
       // (closes the COMP-PARITY-7 gap — kill previously wrote vision-state only).
-      if (guardEnabled) await projectFeatureStatus({ featureCode: item.lifecycle.featureCode, phase: 'killed', cwd: projectRoot });
+      // COMP-ROADMAP-PLAN: skipped for tracksFeatureJson:false modes (no feature.json).
+      if (guardEnabled && getMode(modeOf(item)).runner.tracksFeatureJson) await projectFeatureStatus({ featureCode: item.lifecycle.featureCode, phase: 'killed', cwd: projectRoot });
       scheduleBroadcast();
       broadcastMessage({ type: 'lifecycleTransition', itemId: req.params.id, from, to: 'killed', outcome: 'killed', timestamp: now });
       emitDecisionEvent(broadcastMessage, buildPhaseTransitionEvent({ featureCode: item.lifecycle.featureCode, from, to: 'killed', outcome: 'killed', timestamp: now }));
@@ -449,8 +472,11 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
     try {
       const item = store.items.get(req.params.id);
       if (!item?.lifecycle) return res.status(404).json({ error: 'No lifecycle on this item' });
-      if (item.lifecycle.currentPhase !== 'ship') {
-        return res.status(400).json({ error: `Can only complete from ship phase, currently in: ${item.lifecycle.currentPhase}` });
+      // COMP-ROADMAP-MODES: the phase that completes is the mode's completable
+      // phase (build → 'ship', byte-identical), not a hard-coded literal.
+      const completable = completablePhaseOf(modeOf(item));
+      if (item.lifecycle.currentPhase !== completable) {
+        return res.status(400).json({ error: `Can only complete from ${completable} phase, currently in: ${item.lifecycle.currentPhase}` });
       }
 
       // COMP-MCP-ENFORCE Slice 3: evidence-bound completion. Under the guard,
@@ -471,15 +497,15 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
         }
         verifiedTestsPass = ev.testsAttested ? true : (req.body?.tests_pass === true);
 
-        const g = await guardedTransition({ featureCode: item.lifecycle.featureCode, from: 'ship', to: 'complete', workspaceRoot: projectRoot, commitSha: req.body?.commit_sha, resolvedBy: 'agent' });
-        if (!g.applied) return res.status(422).json({ error: 'completion refused by guard', from: 'ship', to: 'complete', verdict: g.verdict, guardError: g.error });
+        const g = await guardedTransition({ featureCode: item.lifecycle.featureCode, from: completable, to: 'complete', workspaceRoot: projectRoot, commitSha: req.body?.commit_sha, resolvedBy: 'agent', mode: modeOf(item) });
+        if (!g.applied) return res.status(422).json({ error: 'completion refused by guard', from: completable, to: 'complete', verdict: g.verdict, guardError: g.error });
       }
 
       const now = new Date().toISOString();
       item.lifecycle.currentPhase = 'complete';
       item.lifecycle.completedAt = now;
       // COMP-OBS-TIMELINE: populate phaseHistory + emit phase_transition DecisionEvent
-      appendPhaseHistory(item, { from: 'ship', to: 'complete', outcome: 'approved', timestamp: now });
+      appendPhaseHistory(item, { from: completable, to: 'complete', outcome: 'approved', timestamp: now });
       store.updateLifecycle(req.params.id, item.lifecycle);
       store.updateItem(req.params.id, { status: 'complete' });
       // COMP-MCP-ENFORCE Slice 2: status projection for the no-commit path is
@@ -487,8 +513,8 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       // recordCompletion bridge, which is the authority + partial-write reporter
       // on the commit_sha path.
       scheduleBroadcast();
-      broadcastMessage({ type: 'lifecycleTransition', itemId: req.params.id, from: 'ship', to: 'complete', outcome: 'approved', timestamp: now });
-      emitDecisionEvent(broadcastMessage, buildPhaseTransitionEvent({ featureCode: item.lifecycle.featureCode, from: 'ship', to: 'complete', outcome: 'approved', timestamp: now }));
+      broadcastMessage({ type: 'lifecycleTransition', itemId: req.params.id, from: completable, to: 'complete', outcome: 'approved', timestamp: now });
+      emitDecisionEvent(broadcastMessage, buildPhaseTransitionEvent({ featureCode: item.lifecycle.featureCode, from: completable, to: 'complete', outcome: 'approved', timestamp: now }));
       // COMP-OBS-DRIFT: emit drift axes before status so STATUS reads fresh drift_axes
       emitDriftAxes(broadcastMessage, store, item, projectRoot, now);
       // COMP-OBS-STATUS: emit status snapshot after lifecycle transition (complete)
@@ -545,7 +571,8 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
           } catch { /* decision event emit best-effort */ }
           // No recordCompletion bridge ran — project complete → COMPLETE so
           // lifecycle-as-truth still reaches feature.json (best-effort).
-          if (guardEnabled) await projectFeatureStatus({ featureCode, phase: 'complete', cwd: projectRoot });
+          // COMP-ROADMAP-PLAN: skipped for tracksFeatureJson:false modes (no feature.json).
+          if (guardEnabled && getMode(modeOf(item)).runner.tracksFeatureJson) await projectFeatureStatus({ featureCode, phase: 'complete', cwd: projectRoot });
         }
       }
 
@@ -756,7 +783,9 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
   });
 
   // ── Artifact endpoints ───────────────────────────────────────────────
-  const artifactManager = new ArtifactManager(featuresPath);
+  // ArtifactManager is constructed per-request from the item's lifecycle mode —
+  // the artifact metadata it assesses/scaffolds is mode-scoped (the root stays
+  // features-rooted; mode-owned root resolution is a deferred follow-up).
 
   app.get('/api/vision/items/:id/artifacts', (req, res) => {
     try {
@@ -765,7 +794,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       if (!item.lifecycle?.featureCode) {
         return res.status(400).json({ error: 'Item has no lifecycle featureCode' });
       }
-      const assessment = artifactManager.assess(item.lifecycle.featureCode);
+      const assessment = new ArtifactManager(featuresPath, item.lifecycle?.mode).assess(item.lifecycle.featureCode);
       res.json(assessment);
     } catch (err) {
       res.status(500).json({ error: err.message });
@@ -779,7 +808,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       if (!item.lifecycle?.featureCode) {
         return res.status(400).json({ error: 'Item has no lifecycle featureCode' });
       }
-      const result = artifactManager.scaffold(item.lifecycle.featureCode, req.body);
+      const result = new ArtifactManager(featuresPath, item.lifecycle?.mode).scaffold(item.lifecycle.featureCode, req.body);
       res.json(result);
     } catch (err) {
       res.status(400).json({ error: err.message });
@@ -828,9 +857,11 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       if (existing) {
         return res.status(200).json(existing); // idempotent
       }
-      // Dedup: if a pending gate already exists for the same item+step, reuse it
+      // Dedup: if a pending gate already exists for the same item+step in THIS
+      // flow, reuse it. Scoped to flowId so a fresh run never inherits a stale
+      // pending gate from a prior crashed/aborted run for the same feature.
       if (itemId) {
-        const dupGate = store.findPendingGate(itemId, stepId);
+        const dupGate = store.findPendingGate(itemId, stepId, flowId);
         if (dupGate) {
           return res.status(200).json(dupGate);
         }

package/server/vision-server.js

@@ -30,6 +30,7 @@ import { attachSettingsRoutes } from './settings-routes.js';
 import { attachHealthRoutes } from './health-routes.js';
 import { attachValidateRoutes } from './validate-routes.js';
 import { attachQaScopeRoutes } from './qa-scope-routes.js';
+import { attachSmartmemoryRoutes } from './smartmemory-routes.js';
 import { attachDesignRoutes } from './design-routes.js';
 import { DesignSessionManager } from './design-session.js';
 import { attachPipelineRoutes } from './pipeline-routes.js';
@@ -102,6 +103,11 @@ export class VisionServer {
     // Read-only GET /api/qa-scope?featureCode=…; reads off req.workspace.
     attachQaScopeRoutes(app);
 
+    // ── SmartMemory recall (COMP-SMARTMEMORY-RECALL, opt-in) ───────────────
+    // Read-only GET /api/smartmemory/recall?featureCode=…; degrade-never-fail,
+    // answers {enabled:false} from config alone when the flag is OFF.
+    attachSmartmemoryRoutes(app);
+
     // ── Vision CRUD + lifecycle routes ─────────────────────────────────────
     attachVisionRoutes(app, {
       store: this.store,

package/server/vision-store.js

@@ -200,7 +200,7 @@ export class VisionStore {
       throw new Error(`Invalid phase: ${updates.phase}`);
     }
 
-    const allowed = ['type', 'title', 'description', 'confidence', 'status', 'phase', 'position', 'parentId', 'summary', 'files', 'featureCode', 'stratumFlowId', 'evidence', 'group'];
+    const allowed = ['type', 'title', 'description', 'confidence', 'status', 'phase', 'position', 'parentId', 'summary', 'files', 'featureCode', 'stratumFlowId', 'evidence', 'group', 'priority'];
     for (const key of allowed) {
       if (updates[key] !== undefined) {
         item[key] = updates[key];
@@ -349,10 +349,19 @@ export class VisionStore {
     return this.gates.get(gateId) || null;
   }
 
-  /** Find an existing pending gate for the same item+step */
-  findPendingGate(itemId, stepId) {
+  /**
+   * Find an existing pending gate for the same item+step within the same flow.
+   *
+   * The flowId guard prevents a fresh run (new flowId) from reusing a stale
+   * pending gate left by a prior crashed/aborted run for the same feature — that
+   * gate is never resolved, so reusing it would poll until the server TTL
+   * expires it and then error. A null flowId falls back to the legacy
+   * item+step match (callers that don't track a flow).
+   */
+  findPendingGate(itemId, stepId, flowId = null) {
     for (const gate of this.gates.values()) {
-      if (gate.status === 'pending' && gate.itemId === itemId && gate.stepId === stepId) {
+      if (gate.status === 'pending' && gate.itemId === itemId && gate.stepId === stepId
+          && (flowId == null || gate.flowId === flowId)) {
         return gate;
       }
     }