@smartmemory/compose 0.2.40-beta → 0.2.41-beta

package/bin/compose.js

@@ -329,14 +329,16 @@ async function runDoctor(flags = []) {
 // compose init — project-local setup
 // ---------------------------------------------------------------------------
 
-async function runInit(flags) {
+async function runInit(flags, cwdOverride) {
   const noStratum = flags.includes('--no-stratum')
   const noLifecycle = flags.includes('--no-lifecycle')
   // init creates the workspace — never go through resolveCwdWithWorkspace (which
   // requires one to exist). Strip --workspace if present to avoid leaving it in
   // the shared args array for downstream subcommands.
   getWorkspaceFlag(args)
-  const cwd = process.cwd()
+  // cwdOverride lets callers (e.g. runUpdate) target the resolved workspace root
+  // instead of process.cwd(), which differs when run from a subdirectory.
+  const cwd = cwdOverride || process.cwd()
 
   // 1. Create .compose/ directory
   const composeDir = join(cwd, '.compose')
@@ -373,8 +375,10 @@ async function runInit(flags) {
   // 4. Write .compose/compose.json (merge with existing if present)
   const configPath = join(composeDir, 'compose.json')
   let existing = {}
+  let existingConfigCorrupt = false
   if (existsSync(configPath)) {
-    try { existing = JSON.parse(readFileSync(configPath, 'utf-8')) } catch {}
+    try { existing = JSON.parse(readFileSync(configPath, 'utf-8')) }
+    catch { existingConfigCorrupt = true }
   }
 
   const agentsConfig = {}
@@ -388,6 +392,10 @@ async function runInit(flags) {
   }
 
   const config = {
+    // Preserve unknown top-level keys (tracker, roadmap, stateVersion, …) — the
+    // explicit keys below override the merged sub-objects. Without this spread,
+    // init/upgrade silently drops e.g. `roadmap.narrative` and `tracker` config.
+    ...existing,
     version: 2,
     capabilities: {
       ...(existing.capabilities || {}),
@@ -418,6 +426,23 @@ async function runInit(flags) {
   // 5. Create .compose/data/
   mkdirSync(join(composeDir, 'data'), { recursive: true })
 
+  // 5a. Run pending feature.json state migrations (COMP-MIGRATE-ON-UPGRADE).
+  // Uses init's own resolved cwd; never aborts init on a migration fault. Skip
+  // when the prior compose.json was corrupt — init just normalized it to a
+  // default, so its tracker/paths can't be trusted to scope the migration.
+  if (existingConfigCorrupt) {
+    console.warn('state migration skipped: prior compose.json was unreadable (normalized to default; re-run `compose migrate-state` after verifying config)')
+  } else {
+    try {
+      const { runStateMigrations, summarizeMigrationReport } = await import('../lib/state-migrations.js')
+      const rep = runStateMigrations(cwd, {})
+      const line = summarizeMigrationReport(rep)
+      if (line && !rep.noop) console.log(line)
+    } catch (err) {
+      console.warn(`state migration skipped: ${err.message}`)
+    }
+  }
+
   // 5b. Scaffold docs/context/ with ambient context templates
   const contextDir = join(cwd, config.paths.context)
   mkdirSync(contextDir, { recursive: true })
@@ -669,7 +694,11 @@ async function runUpdate(flags) {
   if (existsSync(join(cwd, '.compose', 'compose.json'))) {
     console.log('')
     console.log(`Refreshing project at ${cwd}...`)
-    await runInit([])
+    // Thread the RESOLVED workspace root into runInit (it otherwise uses
+    // process.cwd(), which differs when upgrading from a subdirectory). This
+    // makes all of init's refresh — including its state-migration step — target
+    // the right workspace (COMP-MIGRATE-ON-UPGRADE finding 6).
+    await runInit([], cwd)
   }
 
   console.log('')
@@ -704,6 +733,25 @@ if (cmd === 'update' || cmd === 'upgrade') {
   process.exit(0)
 }
 
+if (cmd === 'migrate-state') {
+  // COMP-MIGRATE-ON-UPGRADE — run pending feature.json state migrations explicitly.
+  // Distinct from `compose roadmap migrate` (ROADMAP→feature.json backfill).
+  const { root: cwd } = resolveCwdWithWorkspace(args)
+  const dryRun = args.includes('--dry-run')
+  const { runStateMigrations, summarizeMigrationReport } = await import('../lib/state-migrations.js')
+  const rep = runStateMigrations(cwd, { dryRun })
+  if (rep.skipped) {
+    console.log(`migrate-state: skipped (${rep.skipped})`)
+    process.exit(0)
+  }
+  console.log(summarizeMigrationReport(rep))
+  for (const m of rep.perMigration) {
+    if (m.touched.length) console.log(`  [${m.id}] v${m.version}: ${m.touched.join(', ')}`)
+  }
+  for (const e of rep.parseErrors) console.error(`  unparseable: ${e.path} — ${e.message}`)
+  process.exit(0)
+}
+
 if (cmd === 'install') {
   // Backwards-compat: run both init + setup
   await runInit(args)

package/lib/get-roadmap.js

@@ -46,13 +46,15 @@ function stripVolatile(text) {
 /**
  * @param {string} root - Project root.
  * @param {object} [opts]
- * @param {string} [opts.status] - Comma-list status filter applied to active/blocked rows.
- * @param {string} [opts.phase] - Exact phaseId filter applied to active/blocked rows.
+ * @param {string} [opts.status] - Comma-list status filter applied to active/blocked + rows.
+ * @param {string} [opts.phase] - Exact phaseId filter applied to active/blocked + rows.
  * @param {'summary'|'markdown'} [opts.format='summary'] - Omit or include raw markdown.
  * @param {boolean} [opts.check_drift=true] - Compare render vs on-disk ROADMAP.md.
+ * @param {number} [opts.limit=50] - Cap on the general `rows` list (emitted only when
+ *   a status/phase filter or an explicit limit is supplied — keeps the default call token-safe).
  */
 export function getRoadmap(root, opts = {}) {
-  const { status, phase, format = 'summary', check_drift = true } = opts ?? {};
+  const { status, phase, format = 'summary', check_drift = true, limit } = opts ?? {};
 
   const roadmapPath = join(root, 'ROADMAP.md');
   const onDisk = existsSync(roadmapPath) ? readFileSync(roadmapPath, 'utf-8') : '';
@@ -103,6 +105,23 @@ export function getRoadmap(root, opts = {}) {
 
   const out = { source, path: roadmapPath, summary, active, blocked };
 
+  // General filtered rows list — emitted only when the caller signals intent via a
+  // status/phase filter or an explicit limit. This is what lets `/roadmap next` read
+  // the PLANNED list structured instead of re-parsing the markdown. The no-arg summary
+  // call stays token-safe (no rows key). Anonymous rows are excluded, same as the lists.
+  const wantsRows = status != null || phase != null || limit != null;
+  if (wantsRows) {
+    // Resolve the row cap with predictable semantics for malformed input: a finite
+    // number is floored and clamped to >= 0 (so limit:-1 → 0 rows, limit:1.5 → 1),
+    // never silently widened. Anything non-finite (no limit, just a status/phase
+    // filter) falls back to the default 50.
+    const cap = Number.isFinite(limit) ? Math.max(0, Math.floor(limit)) : 50;
+    const matched = named.filter(matchFilter).map(pick);
+    out.rowsTotal = matched.length;
+    out.rows = matched.slice(0, cap);
+    out.rowsTruncated = matched.length > cap;
+  }
+
   if (check_drift) {
     if (narrative) {
       out.stale = false; // the content IS the file

package/lib/state-migrations.js

@@ -0,0 +1,217 @@
+/**
+ * COMP-MIGRATE-ON-UPGRADE — versioned, eager feature.json state migration.
+ *
+ * `compose upgrade` refreshes code but historically ran no state migration:
+ * vision-state is migrated lazily on every load, but feature.json cold data
+ * (e.g. legacy `complexity: null` that fails the schema oneOf) is never touched
+ * unless the file happens to be rewritten. This runner walks every feature.json
+ * eagerly, applies an ordered registry of pure transforms, and records progress
+ * in a durable, dedicated state file.
+ *
+ * Design: docs/features/COMP-MIGRATE-ON-UPGRADE/design.md (rev 2).
+ *
+ * Invariants:
+ *   - migrateFeature transforms are PURE and TOTAL: no I/O, never throw on
+ *     valid-JSON input. (A throw means a migration-code bug → fail-fast.)
+ *   - The runner owns all I/O, atomicity (temp+rename), and reporting.
+ *   - The stamp lives in .compose/data/migration-state.json — NOT compose.json
+ *     (runInit rewrites compose.json from a fixed shape and would drop it; and a
+ *     torn write to tracker config would break workspace resolution).
+ *   - Convergent: corrupt/unparseable feature.json is REPORTED, not a permanent
+ *     block — the stamp still advances, so one bad file can't re-run the whole
+ *     stack forever.
+ *   - local-provider only; narrative-safe (never regenerates ROADMAP.md).
+ */
+import {
+  readFileSync, writeFileSync, existsSync, mkdirSync,
+  renameSync, unlinkSync, readdirSync,
+} from 'fs';
+import { join } from 'path';
+import { loadFeaturesDir } from './project-paths.js';
+import { writeFeature } from './feature-json.js';
+
+/**
+ * Ordered, append-only migration registry. Each `migrateFeature` is pure/total.
+ * @type {{version:number, id:string, describe:string,
+ *         migrateFeature:(f:object)=>{changed:boolean, feature:object}}[]}
+ */
+// Legacy free-text complexity → schema enum (S/M/L/XL), preserving ordinal intent.
+const COMPLEXITY_SYNONYMS = {
+  xs: 'S', s: 'S', small: 'S', low: 'S', trivial: 'S',
+  m: 'M', medium: 'M', med: 'M', moderate: 'M',
+  l: 'L', large: 'L', high: 'L',
+  xl: 'XL', 'extra-large': 'XL', 'extra large': 'XL', 'very-high': 'XL', 'very high': 'XL',
+};
+const VALID_COMPLEXITY = new Set(['S', 'M', 'L', 'XL']);
+
+export const MIGRATIONS = [
+  {
+    version: 1,
+    id: 'normalize-complexity',
+    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)
+      // feature.json is malformed data, not a migration target — never throw.
+      if (!f || typeof f !== 'object' || Array.isArray(f)) return { changed: false, feature: f };
+      if (!('complexity' in f)) return { changed: false, feature: f };
+      const c = f.complexity;
+      // Already schema-valid: a number or an enum member — leave untouched.
+      if (typeof c === 'number') return { changed: false, feature: f };
+      if (typeof c === 'string' && VALID_COMPLEXITY.has(c)) return { changed: false, feature: f };
+      // Mappable legacy free-text → enum.
+      if (typeof c === 'string') {
+        const mapped = COMPLEXITY_SYNONYMS[c.trim().toLowerCase()];
+        if (mapped) return { changed: true, feature: { ...f, complexity: mapped } };
+      }
+      // null or unmappable (object/garbage string) → drop the optional key.
+      const { complexity, ...rest } = f;
+      return { changed: true, feature: rest };
+    },
+  },
+];
+
+function stateFilePath(cwd) {
+  return join(cwd, '.compose', 'data', 'migration-state.json');
+}
+
+/** Read the durable stamp. Absent or corrupt ⇒ {stateVersion:0, applied:[]}. */
+export function readMigrationState(cwd) {
+  const p = stateFilePath(cwd);
+  if (!existsSync(p)) return { stateVersion: 0, applied: [] };
+  try {
+    const parsed = JSON.parse(readFileSync(p, 'utf-8'));
+    return {
+      stateVersion: Number.isInteger(parsed?.stateVersion) ? parsed.stateVersion : 0,
+      applied: Array.isArray(parsed?.applied) ? parsed.applied : [],
+    };
+  } catch {
+    // A corrupt state file is treated as version 0; re-running is idempotent.
+    return { stateVersion: 0, applied: [] };
+  }
+}
+
+function writeMigrationStateAtomic(cwd, state) {
+  const dir = join(cwd, '.compose', 'data');
+  mkdirSync(dir, { recursive: true });
+  const p = join(dir, 'migration-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'
+ *   'non-local'  — an explicit non-local provider (e.g. github)
+ *   'unreadable' — config present but not parseable (mirrors factory.js failing
+ *                  fast rather than silently assuming local)
+ */
+function trackerKind(cwd) {
+  let cfg;
+  try {
+    cfg = JSON.parse(readFileSync(join(cwd, '.compose', 'compose.json'), 'utf-8'));
+  } catch {
+    return 'unreadable';
+  }
+  const t = cfg.tracker;
+  if (t === undefined || t === null || !t.provider || t.provider === 'local') return 'local';
+  return 'non-local';
+}
+
+/**
+ * Run pending feature.json state migrations for the workspace at `cwd`.
+ *
+ * @param {string} cwd - workspace root
+ * @param {{dryRun?: boolean}} [opts]
+ * @returns {object} report — one of:
+ *   {skipped:'no-workspace'|'non-local-tracker'}
+ *   {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.
+ */
+export function runStateMigrations(cwd, opts = {}) {
+  const dryRun = !!opts.dryRun;
+
+  // Guard: never write stray state into a non-workspace cwd (e.g. when runUpdate
+  // → runInit lands on a process.cwd() that isn't the resolved workspace root).
+  if (!existsSync(join(cwd, '.compose', 'compose.json'))) {
+    return { skipped: 'no-workspace' };
+  }
+  const kind = trackerKind(cwd);
+  if (kind === 'non-local') return { skipped: 'non-local-tracker' };
+  if (kind === 'unreadable') return { skipped: 'unreadable-config' };
+
+  const { stateVersion: from, applied } = readMigrationState(cwd);
+  const pending = MIGRATIONS
+    .filter((m) => m.version > from)
+    .sort((a, b) => a.version - b.version);
+  if (pending.length === 0) {
+    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 = [];
+
+  // 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
+  }
+
+  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;
+    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);
+      }
+    });
+    if (changedAny && !dryRun) {
+      writeFeature(cwd, feature, featuresDir, { validate: false });
+    }
+  }
+
+  const to = pending[pending.length - 1].version;
+  if (!dryRun) {
+    writeMigrationStateAtomic(cwd, {
+      stateVersion: to,
+      applied: applied.concat(pending.map((m) => ({ version: m.version, id: m.id }))),
+    });
+  }
+  return { from, to, dryRun, perMigration, parseErrors };
+}
+
+/** One-line human summary for the upgrade/init narration. */
+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}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartmemory/compose",
-  "version": "0.2.40-beta",
+  "version": "0.2.41-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.js

@@ -361,14 +361,15 @@ const TOOLS = [
   },
   {
     name: 'get_roadmap',
-    description: 'Read the current roadmap rendered from canon (feature.json) WITHOUT writing. Returns a status summary plus active/blocked rows, and a staleness flag comparing the render against on-disk ROADMAP.md. Narrative-owned workspaces return the hand-authored file verbatim. Read-only — prefer this over reading ROADMAP.md directly.',
+    description: 'Read the current roadmap rendered from canon (feature.json) WITHOUT writing. Returns a status summary, the active/blocked convenience lists, and a staleness flag vs on-disk ROADMAP.md. Pass a status/phase filter or a limit to also get a general `rows` list (e.g. {status:"PLANNED", limit:10} for "what to work on next") — structured rows so callers never re-parse the markdown. Narrative-owned workspaces return the hand-authored file verbatim. Read-only — prefer this over reading ROADMAP.md directly.',
     inputSchema: {
       type: 'object',
       properties: {
-        status: { type: 'string', description: 'Filter active/blocked rows by status (comma-separated): PLANNED, IN_PROGRESS, PARTIAL, BLOCKED, COMPLETE, …' },
-        phase: { type: 'string', description: 'Filter active/blocked rows to a single phase (matched against phaseId)' },
+        status: { type: 'string', description: 'Filter active/blocked + rows by status (comma-separated): PLANNED, IN_PROGRESS, PARTIAL, BLOCKED, COMPLETE, …' },
+        phase: { type: 'string', description: 'Filter active/blocked + rows to a single phase (matched against phaseId)' },
         format: { type: 'string', description: '"summary" (default — counts + lists, token-safe) or "markdown" (full rendered text)' },
         check_drift: { type: 'boolean', description: 'Compare the render against on-disk ROADMAP.md and set stale/drift (default true)' },
+        limit: { type: 'integer', minimum: 0, description: 'Cap on the general `rows` list (default 50). Supplying status/phase/limit emits rows[]/rowsTotal/rowsTruncated; without any of them rows is omitted (token-safe summary). A finite value is floored and clamped to ≥ 0.' },
       },
     },
   },