@smartmemory/compose 0.2.48-beta → 0.2.49-beta

package/lib/state-migrations.js

@@ -48,6 +48,7 @@ export const MIGRATIONS = [
   {
     version: 1,
     id: 'normalize-complexity',
+    target: 'feature',
     describe: 'Normalize legacy free-text complexity to the S/M/L/XL enum; drop null/unmappable (fails the string|number oneOf)',
     migrateFeature(f) {
       // Total on any parseable JSON value: a non-object (scalar/array/null)
@@ -68,8 +69,100 @@ export const MIGRATIONS = [
       return { changed: true, feature: rest };
     },
   },
+  {
+    version: 2,
+    id: 'normalize-vision-legacy',
+    target: 'vision',
+    describe: 'Vision-state: legacy `featureCode: "feature:X"` → `lifecycle.featureCode` + normalize legacy gate outcomes to the imperative enum',
+    migrateState(state) { return migrateVisionState(state); },
+  },
 ];
 
+// ---------------------------------------------------------------------------
+// COMP-MIGRATE-UNIFY-VISION — shared vision-state transforms.
+//
+// These two transforms were historically inlined AND duplicated in
+// server/vision-store.js and lib/vision-writer.js, run lazily on every
+// vision-state load. They are folded here as the single implementation, reused
+// by both:
+//   - the load-time paths (vision-store._load / vision-writer._load), and
+//   - the eager runner below — so cold vision-state the server never loads
+//     (e.g. a frozen forge-top store) is migrated by `compose migrate-state`.
+//
+// Scope is EXACTLY these two transforms. Each file's other load-time work —
+// gate/pending dedup, slug/files/group derivation — is deliberately NOT folded
+// here (it differs per call site and is out of this consolidation's scope).
+//
+// They MUTATE their argument in place (and report `changed`) by design: the
+// on-disk byte image must stay identical to the previous inline behavior, which
+// mutated in place, so key-insertion order is preserved exactly. They are
+// otherwise pure (no I/O) and idempotent.
+// ---------------------------------------------------------------------------
+
+const GATE_OUTCOME_MAP = { approved: 'approve', killed: 'kill', revised: 'revise' };
+
+/** Normalize a legacy past-tense gate outcome to the imperative enum. Pure/total/idempotent. */
+export function normalizeGateOutcome(outcome) {
+  return GATE_OUTCOME_MAP[outcome] || outcome;
+}
+
+/**
+ * Migrate one vision item's legacy `featureCode: "feature:X"` to
+ * `lifecycle.featureCode: "X"`. Mutates `item` in place (for byte-identity with
+ * the prior inline code) and reports whether anything changed. No-op when the
+ * binding is already in lifecycle form or the field is absent.
+ *
+ * PURE + TOTAL (the registry invariant): never throws on parseable JSON. The
+ * `typeof === 'string'` guard is deliberate — the prior inline loaders called
+ * `.startsWith` unguarded and would THROW on a malformed truthy non-string
+ * `featureCode` (a load-path crash → fresh-state fallback). On real corpora every
+ * `featureCode` is a string-or-absent, so the on-disk output is byte-identical;
+ * the only divergence is that pathological non-string values now no-op instead of
+ * crashing, which is required so the eager runner (no per-item try/catch) stays
+ * total. Out of scope to "fix" such malformed data here — this only consolidates.
+ * @param {object} item
+ * @returns {{changed: boolean}}
+ */
+export function migrateVisionItemFeatureCode(item) {
+  if (!item || typeof item !== 'object') return { changed: false };
+  if (item.featureCode && typeof item.featureCode === 'string'
+      && item.featureCode.startsWith('feature:') && !item.lifecycle?.featureCode) {
+    const bare = item.featureCode.replace(/^feature:/, '');
+    item.lifecycle = item.lifecycle || {};
+    item.lifecycle.featureCode = bare;
+    delete item.featureCode;
+    return { changed: true };
+  }
+  return { changed: false };
+}
+
+/**
+ * Apply the legacy vision-state transforms across a whole parsed vision-state
+ * object: `featureCode→lifecycle.featureCode` over `items[]` and gate-outcome
+ * normalization over `gates[]`. Mutates in place and also returns the object so
+ * either the return value or the original reference may be used. Total on any
+ * parseable shape (missing/non-array items/gates are skipped).
+ * @param {object} state
+ * @returns {{changed: boolean, state: object}}
+ */
+export function migrateVisionState(state) {
+  let changed = false;
+  if (state && Array.isArray(state.items)) {
+    for (const item of state.items) {
+      if (migrateVisionItemFeatureCode(item).changed) changed = true;
+    }
+  }
+  if (state && Array.isArray(state.gates)) {
+    for (const gate of state.gates) {
+      if (gate && gate.outcome) {
+        const normalized = normalizeGateOutcome(gate.outcome);
+        if (normalized !== gate.outcome) { gate.outcome = normalized; changed = true; }
+      }
+    }
+  }
+  return { changed, state };
+}
+
 function stateFilePath(cwd) {
   return join(cwd, '.compose', 'data', 'migration-state.json');
 }
@@ -104,6 +197,24 @@ function writeMigrationStateAtomic(cwd, state) {
   }
 }
 
+/**
+ * Atomically rewrite `.compose/data/vision-state.json`, byte-for-byte matching
+ * VisionWriter._atomicWrite (2-space JSON + trailing newline, temp + rename).
+ */
+function writeVisionStateAtomic(cwd, state) {
+  const dir = join(cwd, '.compose', 'data');
+  mkdirSync(dir, { recursive: true });
+  const p = join(dir, 'vision-state.json');
+  const tmp = `${p}.tmp.${process.pid}`;
+  try {
+    writeFileSync(tmp, JSON.stringify(state, null, 2) + '\n');
+    renameSync(tmp, p);
+  } catch (err) {
+    try { unlinkSync(tmp); } catch { /* tmp may not exist */ }
+    throw err;
+  }
+}
+
 /**
  * Tracker classification from `.compose/compose.json`:
  *   'local'      — tracker absent/null or provider==='local'
@@ -124,16 +235,20 @@ function trackerKind(cwd) {
 }
 
 /**
- * Run pending feature.json state migrations for the workspace at `cwd`.
+ * Run pending state migrations for the workspace at `cwd`. Feature-target
+ * migrations walk every feature.json; vision-target migrations walk the single
+ * `.compose/data/vision-state.json` (COMP-MIGRATE-UNIFY-VISION) using the same
+ * pure transforms the server's load-time path uses. One shared `stateVersion`
+ * stamp covers both.
  *
  * @param {string} cwd - workspace root
  * @param {{dryRun?: boolean}} [opts]
  * @returns {object} report — one of:
- *   {skipped:'no-workspace'|'non-local-tracker'}
+ *   {skipped:'no-workspace'|'non-local-tracker'|'unreadable-config'}
  *   {from, to, dryRun, noop:true, perMigration:[], parseErrors:[]}
- *   {from, to, dryRun, perMigration:[{id,version,touched:[]}], parseErrors:[{path,message}]}
- * @throws if a migrateFeature transform throws (migration-code bug) — aborts
- *         WITHOUT advancing the stamp.
+ *   {from, to, dryRun, perMigration:[{id,version,target,touched:[]}], parseErrors:[{path,message}]}
+ * @throws if a migrate transform throws (migration-code bug) — aborts WITHOUT
+ *         advancing the stamp.
  */
 export function runStateMigrations(cwd, opts = {}) {
   const dryRun = !!opts.dryRun;
@@ -155,43 +270,82 @@ export function runStateMigrations(cwd, opts = {}) {
     return { from, to: from, dryRun, noop: true, perMigration: [], parseErrors: [] };
   }
 
-  const featuresDir = loadFeaturesDir(cwd); // honors paths.features override
-  const featuresRoot = join(cwd, featuresDir);
-  const perMigration = pending.map((m) => ({ id: m.id, version: m.version, touched: [] }));
-  const parseErrors = [];
+  // Migrations dispatch by `target` (default 'feature'): feature-target ones
+  // walk every feature.json; vision-target ones walk the single vision-state.json.
+  const featurePending = pending.filter((m) => (m.target || 'feature') === 'feature');
+  const visionPending = pending.filter((m) => m.target === 'vision');
 
-  // Own directory walk — do NOT use listFeatures(): it silently skips unreadable
-  // files, which would hide exactly the cold-data corruption we must surface.
-  let dirs = [];
-  try {
-    dirs = readdirSync(featuresRoot, { withFileTypes: true })
-      .filter((e) => e.isDirectory())
-      .map((e) => e.name);
-  } catch {
-    dirs = []; // features dir may not exist yet
-  }
+  const perMigration = pending.map((m) => ({
+    id: m.id, version: m.version, target: m.target || 'feature', touched: [],
+  }));
+  const perMigrationByVersion = new Map(perMigration.map((p) => [p.version, p]));
+  const parseErrors = [];
 
-  for (const code of dirs) {
-    const fpath = join(featuresRoot, code, 'feature.json');
-    if (!existsSync(fpath)) continue;
-    let feature;
+  // --- feature.json walk -----------------------------------------------------
+  if (featurePending.length > 0) {
+    const featuresDir = loadFeaturesDir(cwd); // honors paths.features override
+    const featuresRoot = join(cwd, featuresDir);
+    // Own directory walk — do NOT use listFeatures(): it silently skips unreadable
+    // files, which would hide exactly the cold-data corruption we must surface.
+    let dirs = [];
     try {
-      feature = JSON.parse(readFileSync(fpath, 'utf-8'));
-    } catch (err) {
-      parseErrors.push({ path: fpath, message: err.message });
-      continue;
+      dirs = readdirSync(featuresRoot, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name);
+    } catch {
+      dirs = []; // features dir may not exist yet
     }
-    let changedAny = false;
-    pending.forEach((m, i) => {
-      const res = m.migrateFeature(feature); // pure/total; a throw = migration-code bug → fail-fast
-      if (res.changed) {
-        feature = res.feature;
-        changedAny = true;
-        perMigration[i].touched.push(feature.code || code);
+
+    for (const code of dirs) {
+      const fpath = join(featuresRoot, code, 'feature.json');
+      if (!existsSync(fpath)) continue;
+      let feature;
+      try {
+        feature = JSON.parse(readFileSync(fpath, 'utf-8'));
+      } catch (err) {
+        parseErrors.push({ path: fpath, message: err.message });
+        continue;
+      }
+      let changedAny = false;
+      for (const m of featurePending) {
+        const res = m.migrateFeature(feature); // pure/total; a throw = migration-code bug → fail-fast
+        if (res.changed) {
+          feature = res.feature;
+          changedAny = true;
+          perMigrationByVersion.get(m.version).touched.push(feature.code || code);
+        }
+      }
+      if (changedAny && !dryRun) {
+        writeFeature(cwd, feature, featuresDir, { validate: false });
+      }
+    }
+  }
+
+  // --- vision-state.json walk (COMP-MIGRATE-UNIFY-VISION) ---------------------
+  // Eagerly migrate cold vision-state the running server never loaded. Same pure
+  // transforms the load-time paths use, so the result is byte-identical.
+  if (visionPending.length > 0) {
+    const vpath = join(cwd, '.compose', 'data', 'vision-state.json');
+    if (existsSync(vpath)) {
+      let state = null;
+      try {
+        state = JSON.parse(readFileSync(vpath, 'utf-8'));
+      } catch (err) {
+        parseErrors.push({ path: vpath, message: err.message }); // reported, never blocks the stamp
+      }
+      if (state) {
+        let changedAny = false;
+        for (const m of visionPending) {
+          const res = m.migrateState(state); // mutates in place; throw = migration-code bug → fail-fast
+          if (res.changed) {
+            changedAny = true;
+            perMigrationByVersion.get(m.version).touched.push('vision-state.json');
+          }
+        }
+        if (changedAny && !dryRun) {
+          writeVisionStateAtomic(cwd, state);
+        }
       }
-    });
-    if (changedAny && !dryRun) {
-      writeFeature(cwd, feature, featuresDir, { validate: false });
     }
   }
 
@@ -209,9 +363,24 @@ export function runStateMigrations(cwd, opts = {}) {
 export function summarizeMigrationReport(report) {
   if (!report || report.skipped) return null;
   if (report.noop) return `state up to date (v${report.to})`;
-  const touched = report.perMigration.reduce((n, m) => n + m.touched.length, 0);
-  const errs = report.parseErrors.length;
   const dry = report.dryRun ? ' (dry-run)' : '';
-  return `migrated ${touched} feature.json across ${report.perMigration.length} migration(s) `
-    + `→ stateVersion ${report.to}${errs ? `, ${errs} unparseable (reported)` : ''}${dry}`;
+  const errs = report.parseErrors.length;
+  const errClause = errs ? `, ${errs} unparseable (reported)` : '';
+
+  // Feature migrations report touched feature.json files; vision migrations
+  // touch the single vision-state.json. Absent `target` ⇒ 'feature' (back-compat
+  // with the COMP-MIGRATE-ON-UPGRADE report shape).
+  const feature = report.perMigration.filter((m) => (m.target || 'feature') === 'feature');
+  const vision = report.perMigration.filter((m) => m.target === 'vision');
+  const parts = [];
+  if (feature.length) {
+    const touched = feature.reduce((n, m) => n + m.touched.length, 0);
+    parts.push(`migrated ${touched} feature.json across ${feature.length} migration(s)`);
+  }
+  if (vision.length) {
+    const touched = vision.reduce((n, m) => n + m.touched.length, 0);
+    parts.push(`vision-state ${touched ? 'migrated' : 'up to date'} across ${vision.length} migration(s)`);
+  }
+  if (parts.length === 0) parts.push('no migrations applied');
+  return `${parts.join('; ')} → stateVersion ${report.to}${errClause}${dry}`;
 }

package/lib/vision-writer.js

@@ -13,6 +13,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { resolvePort } from './resolve-port.js';
 import { probeServer } from './server-probe.js';
+import { migrateVisionItemFeatureCode, normalizeGateOutcome } from './state-migrations.js';
 
 const EMPTY_STATE = () => ({ items: [], connections: [], gates: [] });
 
@@ -34,11 +35,9 @@ function matchFeatureItem(items, featureCode) {
     || null;
 }
 
-/** Canonical outcome normalization — maps legacy past-tense to imperative */
-function normalizeOutcome(outcome) {
-  const map = { approved: 'approve', killed: 'kill', revised: 'revise' };
-  return map[outcome] || outcome;
-}
+/** Canonical outcome normalization — maps legacy past-tense to imperative.
+ *  Shared single implementation lives in state-migrations.js (COMP-MIGRATE-UNIFY-VISION). */
+const normalizeOutcome = normalizeGateOutcome;
 
 export class ServerUnreachableError extends Error {
   constructor(message = 'Server is unreachable') {
@@ -77,16 +76,10 @@ export class VisionWriter {
       parsed.connections = parsed.connections || [];
       parsed.gates = parsed.gates || [];
 
-      // Migration: legacy featureCode → lifecycle.featureCode
+      // Migration: legacy featureCode → lifecycle.featureCode (shared impl)
       let migrated = false;
       for (const item of parsed.items) {
-        if (item.featureCode && item.featureCode.startsWith('feature:') && !item.lifecycle?.featureCode) {
-          const bare = item.featureCode.replace(/^feature:/, '');
-          item.lifecycle = item.lifecycle || {};
-          item.lifecycle.featureCode = bare;
-          delete item.featureCode;
-          migrated = true;
-        }
+        if (migrateVisionItemFeatureCode(item).changed) migrated = true;
       }
 
       // Dedup gates by ID (keep latest)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartmemory/compose",
-  "version": "0.2.48-beta",
+  "version": "0.2.49-beta",
   "description": "Structured AI dev pipeline — goal-to-product orchestration with gates, iteration loops, and feature lifecycle management.",
   "author": "SmartMemory",
   "license": "MIT",

package/server/compose-mcp-tools.js

@@ -9,7 +9,7 @@ import fs from 'node:fs';
 import http from 'node:http';
 import path from 'node:path';
 import { ArtifactManager, ARTIFACT_SCHEMAS } from './artifact-manager.js';
-import { getTargetRoot, getDataDir, resolveProjectPath, switchProject, setCurrentWorkspaceId, loadProjectConfig } from './project-root.js';
+import { getTargetRoot, getDataDir, resolveProjectPath, switchProject, setCurrentWorkspaceId, loadProjectConfig, isLifecycleEnabled } from './project-root.js';
 import { resolveProfile, isToolAllowed } from './mcp-tool-policy.js';
 import { getRoadmap } from '../lib/get-roadmap.js';
 
@@ -125,6 +125,14 @@ export function getSessionsFile() { return path.join(getDataDir(), 'sessions.jso
 // ---------------------------------------------------------------------------
 
 export function loadVisionState() {
+  // FORGE-ROADMAP-RETIRE-STORE: when the bound workspace disables the lifecycle
+  // capability (capabilities.lifecycle:false — e.g. a narrative-owned forge-top),
+  // the vision store is RETIRED. Every MCP vision read funnels through here, so
+  // returning the empty shape guarantees get_vision_items (and every dependent:
+  // phase summary, item detail, pending gates, lifecycle status) can't surface a
+  // second, drift-prone answer beside the prose ROADMAP. Reads stay inert even if
+  // a stray write later recreates the file. get_roadmap (narrative) is unaffected.
+  if (!isLifecycleEnabled()) return { items: [], connections: [], gates: [] };
   try {
     const raw = fs.readFileSync(getVisionFile(), 'utf-8');
     const state = JSON.parse(raw);

package/server/project-root.js

@@ -124,3 +124,17 @@ export function resolveProjectPath(key) {
   if (!rel) return path.join(getTargetRoot(), DEFAULT_CONFIG.paths[key] || key);
   return path.join(getTargetRoot(), rel);
 }
+
+/**
+ * Whether the bound workspace runs the lifecycle/vision store.
+ *
+ * FORGE-ROADMAP-RETIRE-STORE: a workspace sets `capabilities.lifecycle: false`
+ * to RETIRE its vision store — used by narrative-owned workspaces (e.g. forge-top)
+ * where the prose ROADMAP is the single source of truth and a second, frozen
+ * `vision-state.json` would only be a drift-prone parallel answer. Default true
+ * (absent ⇒ enabled); only an explicit `false` disables it.
+ * @returns {boolean}
+ */
+export function isLifecycleEnabled() {
+  return loadProjectConfig().capabilities?.lifecycle !== false;
+}

package/server/vision-store.js

@@ -13,6 +13,7 @@ export const VALID_CONNECTION_TYPES = ['informs', 'blocks', 'supports', 'contrad
 export const VALID_PHASES = ['vision', 'specification', 'planning', 'implementation', 'verification', 'release'];
 
 import { getDataDir as getDefaultDataDir } from './project-root.js';
+import { migrateVisionItemFeatureCode, normalizeGateOutcome } from '../lib/state-migrations.js';
 
 const DATA_FILE = path.join(getDefaultDataDir(), 'vision-state.json');
 
@@ -67,14 +68,8 @@ export class VisionStore {
       let migrated = false;
       if (Array.isArray(data.items)) {
         for (const item of data.items) {
-          // Migration: legacy featureCode → lifecycle.featureCode
-          if (item.featureCode && item.featureCode.startsWith('feature:') && !item.lifecycle?.featureCode) {
-            const bare = item.featureCode.replace(/^feature:/, '');
-            item.lifecycle = item.lifecycle || {};
-            item.lifecycle.featureCode = bare;
-            delete item.featureCode;
-            migrated = true;
-          }
+          // Migration: legacy featureCode → lifecycle.featureCode (shared impl)
+          if (migrateVisionItemFeatureCode(item).changed) migrated = true;
           if (!item.slug && item.title) item.slug = slugify(item.title);
           if (!item.files) item.files = [];
           // Group precedence (most-authoritative first):
@@ -110,10 +105,10 @@ export class VisionStore {
             if (seenPendingKeys.has(key)) { migrated = true; continue; }
             seenPendingKeys.add(key);
           }
-          // Migration: normalize legacy gate outcomes
+          // Migration: normalize legacy gate outcomes (shared impl)
           if (gate.outcome) {
-            const map = { approved: 'approve', killed: 'kill', revised: 'revise' };
-            if (map[gate.outcome]) { gate.outcome = map[gate.outcome]; migrated = true; }
+            const normalized = normalizeGateOutcome(gate.outcome);
+            if (normalized !== gate.outcome) { gate.outcome = normalized; migrated = true; }
           }
           this.gates.set(gate.id, gate);
         }

package/dist/assets/channel-Dh96pu1k.js

@@ -1 +0,0 @@
-import{ai as o,aj as n}from"./App-D7E7S49Q.js";const t=(a,r)=>o.lang.round(n.parse(a)[r]);export{t as c};

package/dist/assets/classDiagram-4FO5ZUOK-BCqpDcaS.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-727SXJPM-zvXhT6iZ.js";import{_ as i}from"./App-D7E7S49Q.js";import"./chunk-FMBD7UC4-DlhrqkBp.js";import"./chunk-ND2GUHAM-lo_8kNzw.js";import"./chunk-55IACEB6-uUk1WzZ1.js";import"./chunk-2J33WTMH-b8Rdk4S-.js";import"./mobile-DwmxS_O4.js";import"./index-DNuHtZwR.js";import"./graph-BBXaecIU.js";var b={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{b as diagram};

package/dist/assets/classDiagram-v2-Q7XG4LA2-BCqpDcaS.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-727SXJPM-zvXhT6iZ.js";import{_ as i}from"./App-D7E7S49Q.js";import"./chunk-FMBD7UC4-DlhrqkBp.js";import"./chunk-ND2GUHAM-lo_8kNzw.js";import"./chunk-55IACEB6-uUk1WzZ1.js";import"./chunk-2J33WTMH-b8Rdk4S-.js";import"./mobile-DwmxS_O4.js";import"./index-DNuHtZwR.js";import"./graph-BBXaecIU.js";var b={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{b as diagram};

package/dist/assets/stateDiagram-v2-BHNVJYJU-BM1Uf6a_.js

@@ -1 +0,0 @@
-import{s as r,b as e,a,S as s}from"./chunk-AQP2D5EJ-B6GCyrIp.js";import{_ as i}from"./App-D7E7S49Q.js";import"./chunk-55IACEB6-uUk1WzZ1.js";import"./chunk-2J33WTMH-b8Rdk4S-.js";import"./mobile-DwmxS_O4.js";import"./index-DNuHtZwR.js";import"./graph-BBXaecIU.js";var n={parser:a,get db(){return new s(2)},renderer:e,styles:r,init:i(t=>{t.state||(t.state={}),t.state.arrowMarkerAbsolute=t.arrowMarkerAbsolute},"init")};export{n as diagram};