@smartmemory/compose 0.2.48-beta → 0.2.50-beta

package/lib/state-migrations.js

@@ -27,7 +27,7 @@ import {
   renameSync, unlinkSync, readdirSync,
 } from 'fs';
 import { join } from 'path';
-import { loadFeaturesDir } from './project-paths.js';
+import { resolveFeaturesPath } from './project-paths.js';
 import { writeFeature } from './feature-json.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 = resolveFeaturesPath(cwd); // absolute; honors paths.features override
+    const featuresRoot = 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/tracker/local-provider.js

@@ -2,7 +2,7 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, renameS
 import { join, dirname } from 'path';
 
 import { readFeature, listFeatures as listFeaturesRaw, writeFeature } from '../feature-json.js';
-import { loadFeaturesDir } from '../project-paths.js';
+import { resolveFeaturesPath } from '../project-paths.js';
 import { TrackerProvider, CAP } from './provider.js';
 
 import { setFeatureStatus, addRoadmapEntry as addRoadmapEntryRaw } from '../feature-writer.js';
@@ -38,7 +38,7 @@ export class LocalFileProvider extends TrackerProvider {
 
   async init(cwd) {
     this.cwd = cwd;
-    this.featuresDir = loadFeaturesDir(cwd);
+    this.featuresDir = resolveFeaturesPath(cwd);
     return this;
   }
 

package/lib/triage.js

@@ -11,6 +11,8 @@
 
 import { readFileSync, existsSync, statSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
+import { resolveFeaturesPath } from './project-paths.js';
+import { resolvePathValue } from './paths-core.js';
 
 // ---------------------------------------------------------------------------
 // Tier definitions
@@ -185,8 +187,8 @@ function deriveProfile(signals) {
  */
 export async function runTriage(featureCode, opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
-  const featuresDir = opts.featuresDir ?? 'docs/features';
-  const featureDir = join(cwd, featuresDir, featureCode);
+  const featuresDir = opts.featuresDir ?? resolveFeaturesPath(cwd);
+  const featureDir = join(resolvePathValue(cwd, featuresDir, 'features'), featureCode);
 
   // Collect content from key files
   const candidateFiles = ['plan.md', 'blueprint.md', 'design.md', 'prd.md', 'architecture.md'];
@@ -234,11 +236,11 @@ export async function runTriage(featureCode, opts = {}) {
  *
  * @param {string} cwd - Project root
  * @param {string} featureCode - Feature code
- * @param {string} [featuresDir] - Relative path to features dir (default: docs/features)
+ * @param {string} [featuresDir] - Path to features dir (absolute or relative; default: resolved features path)
  * @returns {boolean}
  */
-export function isTriageStale(cwd, featureCode, featuresDir = 'docs/features') {
-  const featureDir = join(cwd, featuresDir, featureCode);
+export function isTriageStale(cwd, featureCode, featuresDir = resolveFeaturesPath(cwd)) {
+  const featureDir = join(resolvePathValue(cwd, featuresDir, 'features'), featureCode);
   const featureJsonPath = join(featureDir, 'feature.json');
 
   if (!existsSync(featureJsonPath)) return true;

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/lib/xref-push.js

@@ -17,7 +17,7 @@
 
 import { readdirSync, existsSync, readFileSync } from 'fs';
 import { join } from 'path';
-import { loadFeaturesDir } from './project-paths.js';
+import { resolveFeaturesPath } from './project-paths.js';
 import { resolveSiblingRoot } from './xref-local.js';
 
 const GITHUB_STATES = new Set(['open', 'closed']);
@@ -145,7 +145,7 @@ function localResolve(link, cwd) {
   const sib = resolveSiblingRoot(cwd, link.repo);
   if (sib.skipped) return sib;
   try {
-    const fjPath = join(sib.root, loadFeaturesDir(sib.root), link.to_code, 'feature.json');
+    const fjPath = join(resolveFeaturesPath(sib.root), link.to_code, 'feature.json');
     if (!existsSync(fjPath)) return { skipped: true, reason: `local target ${link.repo}/${link.to_code} not found` };
     return { state: JSON.parse(readFileSync(fjPath, 'utf8')).status || null, root: sib.root };
   } catch (e) { return { skipped: true, reason: `unreadable local target: ${e.message}` }; }
@@ -171,13 +171,13 @@ function localResolve(link, cwd) {
  * @returns {Promise<{pushed: Array, skipped: Array, unchanged: number, scanned: number}>}
  */
 export async function pushExternalRefs(cwd, opts = {}) {
-  const featuresDir = opts.featuresDir ?? loadFeaturesDir(cwd);
+  const featuresDir = opts.featuresDir ?? resolveFeaturesPath(cwd);
   const clientOpts = { transport: opts.githubTransport ?? null, auth: opts.githubAuth };
   const ghResolve = opts.resolve ?? ((link) => defaultResolve(link, clientOpts));
   const ghWrite = opts.write ?? ((link, patch) => defaultWrite(link, patch, clientOpts));
   const setStatus = opts.setStatus ?? defaultSetStatus;
   const apply = opts.apply === true;
-  const dir = join(cwd, featuresDir);
+  const dir = featuresDir;
 
   const pushed = [];
   const skipped = [];

package/lib/xref-sync.js

@@ -16,7 +16,7 @@
 import { readdirSync, existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { writeFeature } from './feature-json.js';
-import { loadFeaturesDir } from './project-paths.js';
+import { resolveFeaturesPath } from './project-paths.js';
 import { resolveSiblingRoot } from './xref-local.js';
 
 const RESOLVABLE = new Set(['github', 'local']);
@@ -80,7 +80,7 @@ async function defaultResolve(link, cwd, featuresDir) {
     const citedRoot = sib.root;
     // Resolve the SIBLING's own features dir (it may have its own paths.features).
     try {
-      const fjPath = join(citedRoot, loadFeaturesDir(citedRoot), link.to_code, 'feature.json');
+      const fjPath = join(resolveFeaturesPath(citedRoot), link.to_code, 'feature.json');
       if (!existsSync(fjPath)) return { skipped: true, reason: `local target ${link.repo}/${link.to_code} not found` };
       return { state: JSON.parse(readFileSync(fjPath, 'utf8')).status || null };
     } catch (e) { return { skipped: true, reason: `unreadable local target: ${e.message}` }; }
@@ -100,9 +100,9 @@ async function defaultResolve(link, cwd, featuresDir) {
  * @returns {Promise<{synced: Array, skipped: Array, unchanged: number, scanned: number}>}
  */
 export async function syncExternalRefs(cwd, opts = {}) {
-  const featuresDir = opts.featuresDir ?? loadFeaturesDir(cwd);
+  const featuresDir = opts.featuresDir ?? resolveFeaturesPath(cwd);
   const resolve = opts.resolve ?? defaultResolve;
-  const dir = join(cwd, featuresDir);
+  const dir = featuresDir;
 
   const synced = [];
   const skipped = [];

package/package.json

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

@@ -16,6 +16,8 @@ import { randomUUID } from 'node:crypto';
 import { parseDecisionBlocks } from '../src/components/vision/designSessionState.js';
 import { StratumMcpClient } from '../lib/stratum-mcp-client.js';
 import { KNOWN_VERSIONS } from '../lib/build-stream-schema.js';
+import { getTargetRoot, resolveProjectPath } from './project-root.js';
+import { relForDisplay } from '../lib/project-paths.js';
 
 // Lazy singleton — design conversations share one stratum-mcp connection
 // across the server process lifetime. Concurrent runs are correlation-id scoped.
@@ -444,16 +446,19 @@ Output ONLY the Markdown content, no code fences.`;
         return;
       }
 
-      // Determine the output path
-      let designDocPath;
+      // Determine the output path. Resolve the absolute write target first
+      // (features may be relocated outside the root — COMP-PATHS-EXTERNAL),
+      // then derive the display-relative string from it.
+      let absPath, designDocPath;
       if (scope === 'feature' && featureCode) {
-        designDocPath = path.join('docs', 'features', featureCode, 'design.md');
+        absPath = path.join(resolveProjectPath('features'), featureCode, 'design.md');
+        designDocPath = relForDisplay(getTargetRoot(), absPath);
       } else {
         designDocPath = path.join('docs', 'design.md');
+        absPath = path.join(projectRoot, designDocPath);
       }
 
       // Guard: never overwrite an existing doc with empty content
-      const absPath = path.join(projectRoot, designDocPath);
       if (!docContent.trim()) {
         console.error('[design] Generated doc is empty — refusing to overwrite');
         res.status(500).json({ error: 'Doc generation produced empty content' });

package/server/drift-axes.js

@@ -19,6 +19,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { execSync } from 'node:child_process';
 import { diffContracts } from './contract-diff.js';
+import { resolveFeaturesPath } from '../lib/project-paths.js';
 
 // ── Threshold constants (Decision 2) ─────────────────────────────────────────
 
@@ -353,9 +354,10 @@ export function computeDriftAxes(item, projectRoot, now) {
 
   const ts = now || new Date().toISOString();
 
-  // Resolve the docs/features/<FC> directory
-  // projectRoot/docs/features/<FC>
-  const featurePath = path.join(projectRoot, 'docs', 'features', featureCode);
+  // Resolve the features/<FC> directory against projectRoot's own config
+  // (relocatable artifact paths, COMP-PATHS-EXTERNAL). Byte-identical to
+  // projectRoot/docs/features/<FC> for the in-root default.
+  const featurePath = path.join(resolveFeaturesPath(projectRoot), featureCode);
 
   const pathAxis = computePathDrift(item, projectRoot, featurePath, ts);
   const contractAxis = computeContractDrift(item, projectRoot, featurePath, ts);

package/server/feature-scan.js

@@ -16,6 +16,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 import { getTargetRoot, resolveProjectPath } from './project-root.js';
+import { relForDisplay } from '../lib/project-paths.js';
 import { assertValidLinkShape } from '../lib/feature-write-guard.js';
 
 // ---------------------------------------------------------------------------
@@ -608,6 +609,11 @@ export function seedFromRoadmapGraph(store) {
 export function seedFeatures(features, store) {
   const seeded = { features: 0, updated: 0, connections: 0 };
   const featureItemMap = new Map(); // featureCode → itemId
+  const root = getTargetRoot();
+  const featuresBase = resolveProjectPath('features');
+  // Root-relative for the in-root default (relForDisplay guarantees byte-identity
+  // there); absolute when the features dir is relocated outside the workspace root.
+  const artifactPath = (feature, a) => relForDisplay(root, path.join(featuresBase, feature.name, a));
 
   // First pass: create/update items
   for (const feature of features) {
@@ -623,7 +629,7 @@ export function seedFeatures(features, store) {
         status: feature.status || 'planned',
         phase: feature.phase || 'planning',
         confidence: feature.confidence,
-        files: feature.artifacts.map(a => `docs/features/${feature.name}/${a}`),
+        files: feature.artifacts.map(a => artifactPath(feature, a)),
         ...(feature.group ? { group: feature.group } : {}),
       });
       try {
@@ -643,7 +649,7 @@ export function seedFeatures(features, store) {
       if (feature.confidence > (featureItem.confidence || 0)) {
         updates.confidence = feature.confidence;
       }
-      const newFiles = feature.artifacts.map(a => `docs/features/${feature.name}/${a}`);
+      const newFiles = feature.artifacts.map(a => artifactPath(feature, a));
       if (JSON.stringify(newFiles) !== JSON.stringify(featureItem.files || [])) {
         updates.files = newFiles;
       }