@smartmemory/compose 0.2.49-beta → 0.2.50-beta

package/lib/project-paths.js

@@ -1,52 +1,61 @@
 /**
- * project-paths.js — read .compose/compose.json `paths.features` override
- * for lib-side writers.
+ * project-paths.js — read .compose/compose.json and resolve artifact paths
+ * for lib-side code. All path math is delegated to lib/paths-core.js so the
+ * server and lib resolvers can never diverge.
  *
- * Server-side code uses `server/project-root.js`'s cached `loadProjectConfig`,
- * but lib code may run outside the server process (CLI, tests, MCP stdio)
- * and shouldn't share that cache. This is a tiny per-call read; the file is
- * a few hundred bytes.
- *
- * Introduced by COMP-MCP-MIGRATION-2.
+ * Introduced by COMP-MCP-MIGRATION-2; extended to relocatable artifact paths
+ * by COMP-PATHS-EXTERNAL (absolute readers + *FromConfig alternate-root form).
  */
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
+import { DEFAULT_PATHS, resolvePathValue, relForDisplay } from './paths-core.js';
+
+function readConfig(cwd) {
+  const cfgPath = join(cwd, '.compose', 'compose.json');
+  if (!existsSync(cfgPath)) return {};
+  try { return JSON.parse(readFileSync(cfgPath, 'utf-8')); }
+  catch { return {}; }
+}
+
+/** Resolve one artifact key against the config on disk at `cwd`. Absolute. */
+function resolveKey(cwd, key) {
+  return resolvePathValue(cwd, readConfig(cwd)?.paths?.[key], key);
+}
+/** Resolve one artifact key against an already-loaded config + arbitrary root. Absolute. */
+function resolveKeyFromConfig(root, config, key) {
+  return resolvePathValue(root, config?.paths?.[key], key);
+}
 
-const DEFAULT_FEATURES_DIR = 'docs/features';
+export const resolveDocsPath     = (cwd) => resolveKey(cwd, 'docs');
+export const resolveRoadmapPath  = (cwd) => resolveKey(cwd, 'roadmap');
+export const resolveFeaturesPath = (cwd) => resolveKey(cwd, 'features');
+export const resolveJournalPath  = (cwd) => resolveKey(cwd, 'journal');
+export const resolveContextPath  = (cwd) => resolveKey(cwd, 'context');
+export const resolveIdeaboxPath  = (cwd) => resolveKey(cwd, 'ideabox');
+
+export const resolveDocsPathFromConfig     = (root, config) => resolveKeyFromConfig(root, config, 'docs');
+export const resolveRoadmapPathFromConfig  = (root, config) => resolveKeyFromConfig(root, config, 'roadmap');
+export const resolveFeaturesPathFromConfig = (root, config) => resolveKeyFromConfig(root, config, 'features');
+export const resolveJournalPathFromConfig  = (root, config) => resolveKeyFromConfig(root, config, 'journal');
+export const resolveContextPathFromConfig  = (root, config) => resolveKeyFromConfig(root, config, 'context');
+export const resolveIdeaboxPathFromConfig  = (root, config) => resolveKeyFromConfig(root, config, 'ideabox');
+
+export { relForDisplay };
 
 /**
- * Resolve the project's features directory, respecting `.compose/compose.json`'s
- * `paths.features` override. Returns the relative path (joined onto cwd by callers).
- *
- * @param {string} cwd
- * @returns {string} Relative features dir, e.g. 'docs/features' or 'specs/features'.
+ * @deprecated relative form — prefer resolveFeaturesPath (absolute). Kept for
+ * any caller that genuinely needs the configured RELATIVE string. Callers that
+ * pass the result into feature-json.js should migrate to resolveFeaturesPath,
+ * which is absolute-safe (COMP-PATHS-EXTERNAL S2).
  */
 export function loadFeaturesDir(cwd) {
-  const cfgPath = join(cwd, '.compose', 'compose.json');
-  if (!existsSync(cfgPath)) return DEFAULT_FEATURES_DIR;
-  try {
-    const cfg = JSON.parse(readFileSync(cfgPath, 'utf-8'));
-    const rel = cfg?.paths?.features;
-    return (typeof rel === 'string' && rel.length > 0) ? rel : DEFAULT_FEATURES_DIR;
-  } catch {
-    return DEFAULT_FEATURES_DIR;
-  }
+  const rel = readConfig(cwd)?.paths?.features;
+  return (typeof rel === 'string' && rel.length > 0) ? rel : DEFAULT_PATHS.features;
 }
 
-/**
- * Read `externalPrefixes` from .compose/compose.json — code prefixes (e.g.
- * ["STRAT-"]) for features owned by OTHER projects, present in this roadmap
- * only as cross-project references. Returns [] if absent/unreadable.
- * @param {string} cwd
- * @returns {string[]}
- */
 export function loadExternalPrefixes(cwd) {
-  try {
-    const cfgPath = join(cwd, '.compose', 'compose.json');
-    if (!existsSync(cfgPath)) return [];
-    const cfg = JSON.parse(readFileSync(cfgPath, 'utf-8'));
-    return Array.isArray(cfg.externalPrefixes) ? cfg.externalPrefixes : [];
-  } catch { return []; }
+  const arr = readConfig(cwd)?.externalPrefixes;
+  return Array.isArray(arr) ? arr : [];
 }
 
-export const _internals = { DEFAULT_FEATURES_DIR };
+export const _internals = { DEFAULT_FEATURES_DIR: DEFAULT_PATHS.features };

package/lib/roadmap-gen.js

@@ -5,10 +5,9 @@
  */
 
 import { readFileSync, writeFileSync, existsSync } from 'fs';
-import { join } from 'path';
 import { listFeatures, positionSortKey } from './feature-json.js';
 import { parseStatusToken } from './roadmap-parser.js';
-import { loadFeaturesDir } from './project-paths.js';
+import { loadFeaturesDir, resolveRoadmapPath } from './project-paths.js';
 import {
   readPhaseOverrides,
   readAnonymousRows,
@@ -207,7 +206,7 @@ export function generateRoadmapFromBase(baseText, features, opts = {}) {
  * @returns {string} - Generated ROADMAP.md content
  */
 export function generateRoadmap(cwd, opts = {}) {
-  const roadmapPath = join(cwd, 'ROADMAP.md');
+  const roadmapPath = resolveRoadmapPath(cwd);
   const existingText = existsSync(roadmapPath) ? readFileSync(roadmapPath, 'utf-8') : '';
 
   // Narrative-owned workspace: ROADMAP.md is hand-authored. Return it verbatim
@@ -513,7 +512,7 @@ function buildKeyDocs(features, featuresDir) {
  * @param {object} [opts]
  */
 export function writeRoadmap(cwd, opts = {}) {
-  const roadmapPath = join(cwd, 'ROADMAP.md');
+  const roadmapPath = resolveRoadmapPath(cwd);
 
   // Narrative-owned workspace: never overwrite hand-authored ROADMAP.md (#39).
   // No-op + warn; the existing file on disk is the source of truth.

package/lib/roadmap-graph/collect.js

@@ -12,7 +12,7 @@ import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 import { listFeatures } from '../feature-json.js';
-import { loadFeaturesDir, loadExternalPrefixes } from '../project-paths.js';
+import { resolveFeaturesPath, resolveRoadmapPath, loadExternalPrefixes } from '../project-paths.js';
 import { parseRoadmap } from '../roadmap-parser.js';
 import { SchemaValidator } from '../../server/schema-validator.js';
 import { depsToEdges } from './model.js';
@@ -28,7 +28,7 @@ const FM_KEYS = ['name', 'priority', 'track', 'desc'];
  * @param {string} [featuresDir] relative features dir (default from compose.json)
  * @returns {{ nodes: object[], rawEdges: object[], knownCodes: Set<string>, warnings: string[] }}
  */
-export function collectGraphInputs(cwd, featuresDir = loadFeaturesDir(cwd)) {
+export function collectGraphInputs(cwd, featuresDir = resolveFeaturesPath(cwd)) {
   const warnings = [];
   const depsValidator = new SchemaValidator(DEPS_SCHEMA);
   const fmValidator = new SchemaValidator(FRONTMATTER_SCHEMA);
@@ -48,7 +48,7 @@ export function collectGraphInputs(cwd, featuresDir = loadFeaturesDir(cwd)) {
     // An external-prefixed folder is a cross-project reference living here —
     // known (so edges resolve) but never rendered as one of THIS project's nodes.
     if (isExternal(f.code)) { externalCodes.add(f.code); continue; }
-    const folder = join(cwd, featuresDir, f.code);
+    const folder = join(featuresDir, f.code);
     const fm = readDisplayMetadata(folder, f, fmValidator, warnings);
     universe.set(f.code, {
       id: f.code,
@@ -62,7 +62,7 @@ export function collectGraphInputs(cwd, featuresDir = loadFeaturesDir(cwd)) {
   }
 
   // (b) ROADMAP.md rows — fallback for features not registered as folders.
-  const roadmapPath = join(cwd, 'ROADMAP.md');
+  const roadmapPath = resolveRoadmapPath(cwd);
   if (existsSync(roadmapPath)) {
     let entries = [];
     try { entries = parseRoadmap(readFileSync(roadmapPath, 'utf-8')); } catch { /* ignore */ }
@@ -88,7 +88,7 @@ export function collectGraphInputs(cwd, featuresDir = loadFeaturesDir(cwd)) {
   for (const f of features) {
     if (!f || typeof f.code !== 'string') continue;
     if (isExternal(f.code)) continue;
-    const depsPath = join(cwd, featuresDir, f.code, 'deps.yaml');
+    const depsPath = join(featuresDir, f.code, 'deps.yaml');
     if (!existsSync(depsPath)) continue;
     let deps;
     try {

package/lib/roadmap-graph/index.js

@@ -10,7 +10,7 @@
  */
 import { existsSync, readFileSync, writeFileSync, renameSync, unlinkSync, mkdirSync } from 'node:fs';
 import { join, isAbsolute, dirname } from 'node:path';
-import { loadFeaturesDir } from '../project-paths.js';
+import { resolveFeaturesPath } from '../project-paths.js';
 import { collectGraphInputs } from './collect.js';
 import { buildGraph } from './model.js';
 import { renderGraphHtml } from './render.js';
@@ -22,7 +22,7 @@ import { loadGraphConfig } from './config.js';
  * @returns {{ html: string, nodes: object[], edges: object[], dropped: string[], warnings: string[], config: object }}
  */
 export function buildRoadmapGraph(cwd) {
-  const featuresDir = loadFeaturesDir(cwd);
+  const featuresDir = resolveFeaturesPath(cwd);
   const inputs = collectGraphInputs(cwd, featuresDir);
   const graph = buildGraph(inputs); // throws DanglingEdgeError
   const config = loadGraphConfig(cwd);

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';
 
 /**
@@ -283,8 +283,8 @@ export function runStateMigrations(cwd, opts = {}) {
 
   // --- feature.json walk -----------------------------------------------------
   if (featurePending.length > 0) {
-    const featuresDir = loadFeaturesDir(cwd); // honors paths.features override
-    const featuresRoot = join(cwd, featuresDir);
+    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 = [];

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/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.49-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/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;
       }

package/server/file-watcher.js

@@ -10,6 +10,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { getTargetRoot, loadProjectConfig, ensureDataDir } from './project-root.js';
+import { resolveDocsPathFromConfig, resolveFeaturesPathFromConfig } from '../lib/project-paths.js';
 
 const PROJECT_ROOT = getTargetRoot();
 
@@ -69,7 +70,8 @@ export class FileWatcherServer {
     app.get('/api/files', (_req, res) => {
       const config = loadProjectConfig();
       const docsPrefix = config.paths?.docs || 'docs';
-      const docsDir = path.join(PROJECT_ROOT, docsPrefix);
+      // COMP-PATHS-EXTERNAL: list the RESOLVED docs dir (may be relocated).
+      const docsDir = resolveDocsPathFromConfig(PROJECT_ROOT, config);
       try {
         const files = this.listMarkdownFiles(docsDir, docsPrefix);
         res.json({ files });
@@ -164,7 +166,10 @@ export class FileWatcherServer {
           if (!filename || !fileFilter(filename)) return;
 
           const relativePath = path.join(prefix, filename);
-          const fullPath = path.join(PROJECT_ROOT, relativePath);
+          // COMP-PATHS-EXTERNAL: derive the real path from the WATCHED dir, not
+          // by re-rooting under PROJECT_ROOT — the dir may be relocated outside
+          // the workspace. Byte-identical to the old form for an in-root dir.
+          const fullPath = path.join(dir, filename);
 
           // Debounce: ignore events within 100ms of each other for the same file
           const now = Date.now();
@@ -180,10 +185,11 @@ export class FileWatcherServer {
       }
     };
 
-    // Watch docs/ — broadcast fileChanged events
+    // Watch docs/ — broadcast fileChanged events. COMP-PATHS-EXTERNAL: watch
+    // the RESOLVED absolute dir (may be relocated outside PROJECT_ROOT).
     const config = loadProjectConfig();
     const docsPrefix = config.paths?.docs || 'docs';
-    watchDir(path.join(PROJECT_ROOT, docsPrefix), docsPrefix, (relativePath, fullPath) => {
+    watchDir(resolveDocsPathFromConfig(PROJECT_ROOT, config), docsPrefix, (relativePath, fullPath) => {
       try {
         if (!fs.existsSync(fullPath)) return;
         const content = fs.readFileSync(fullPath, 'utf-8');
@@ -195,9 +201,9 @@ export class FileWatcherServer {
 
     // Watch features/ — notify for auto-reseed into vision store
     const featuresPrefix = config.paths?.features || 'docs/features';
-    watchDir(path.join(PROJECT_ROOT, featuresPrefix), featuresPrefix, (relativePath) => {
-      // Also broadcast as fileChanged (features are docs)
-      const fullPath = path.join(PROJECT_ROOT, relativePath);
+    watchDir(resolveFeaturesPathFromConfig(PROJECT_ROOT, config), featuresPrefix, (relativePath, fullPath) => {
+      // Also broadcast as fileChanged (features are docs). fullPath comes from
+      // the watched dir (COMP-PATHS-EXTERNAL) — do not re-root under PROJECT_ROOT.
       try {
         if (fs.existsSync(fullPath)) {
           const content = fs.readFileSync(fullPath, 'utf-8');

package/server/ideabox-routes.js

@@ -25,6 +25,7 @@ import {
 } from '../lib/ideabox.js'
 import { writeFeature } from '../lib/feature-json.js'
 import { IdeaboxCache } from './ideabox-cache.js'
+import { resolveIdeaboxPathFromConfig, resolveFeaturesPathFromConfig, relForDisplay } from '../lib/project-paths.js'
 
 /**
  * @param {object} app              — Express app
@@ -41,8 +42,7 @@ export function attachIdeaboxRoutes(app, { getProjectRoot, getDataDir, broadcast
     const dataDir = getDataDir()
     if (!_cache || _lastProjectRoot !== projectRoot || _lastDataDir !== dataDir) {
       const config = loadConfig(projectRoot)
-      const ideaboxRel = config?.paths?.ideabox || 'docs/product/ideabox.md'
-      const sourceFile = path.join(projectRoot, ideaboxRel)
+      const sourceFile = resolveIdeaboxPathFromConfig(projectRoot, config)
       _cache = new IdeaboxCache(dataDir, sourceFile)
       _lastProjectRoot = projectRoot
       _lastDataDir = dataDir
@@ -172,16 +172,17 @@ export function attachIdeaboxRoutes(app, { getProjectRoot, getDataDir, broadcast
         resolvedCode = `IDEA-${sourceIdea.num}-${slug}`.toUpperCase()
       }
 
-      // Create feature folder + feature.json (same logic as CLI promote)
+      // Create feature folder + feature.json (same logic as CLI promote).
+      // COMP-PATHS-EXTERNAL: resolve the ABSOLUTE features base (may be
+      // relocated outside projectRoot). Re-rooting under projectRoot would make
+      // existsSync check the wrong path and risk overwriting external canon.
       const composeJsonPath = path.join(projectRoot, '.compose', 'compose.json')
-      let featuresRel = 'docs/features'
+      let cfg = {}
       if (fs.existsSync(composeJsonPath)) {
-        try {
-          const cfg = JSON.parse(fs.readFileSync(composeJsonPath, 'utf-8'))
-          featuresRel = cfg?.paths?.features || 'docs/features'
-        } catch {}
+        try { cfg = JSON.parse(fs.readFileSync(composeJsonPath, 'utf-8')) } catch {}
       }
-      const featuresDir = path.join(projectRoot, featuresRel, resolvedCode)
+      const featuresBase = resolveFeaturesPathFromConfig(projectRoot, cfg)  // absolute
+      const featuresDir = path.join(featuresBase, resolvedCode)
       if (!fs.existsSync(featuresDir)) {
         // COMP-MCP-VALIDATE-1: route through the validated writer instead of a
         // raw fs.writeFileSync so the promoted feature.json is schema-guarded.
@@ -191,7 +192,7 @@ export function attachIdeaboxRoutes(app, { getProjectRoot, getDataDir, broadcast
           status: 'PLANNED',
           promotedFrom: sourceIdea.id,
           createdAt: new Date().toISOString(),
-        }, featuresRel)
+        }, featuresBase)
       }
 
       promoteIdea(parsed, id, resolvedCode)
@@ -200,7 +201,7 @@ export function attachIdeaboxRoutes(app, { getProjectRoot, getDataDir, broadcast
       broadcastUpdate()
 
       const updated = parsed.ideas.find(i => i.id.toUpperCase() === upper)
-      res.json({ ...(updated || { id }), featureCode: resolvedCode, featurePath: `${featuresRel}/${resolvedCode}` })
+      res.json({ ...(updated || { id }), featureCode: resolvedCode, featurePath: relForDisplay(projectRoot, featuresDir) })
     } catch (err) {
       const status = err.message.includes('not found') ? 404 : 500
       res.status(status).json({ error: err.message })

package/server/project-root.js

@@ -15,6 +15,7 @@ import path from 'node:path';
 import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { findProjectRoot } from './find-root.js';
+import { DEFAULT_PATHS, resolvePathValue } from '../lib/paths-core.js';
 
 export { findProjectRoot } from './find-root.js';
 
@@ -99,7 +100,7 @@ export function ensureDataDir() {
 const DEFAULT_CONFIG = Object.freeze({
   version: 1,
   capabilities: Object.freeze({ stratum: true, lifecycle: true }),
-  paths: Object.freeze({ docs: 'docs', features: 'docs/features', journal: 'docs/journal' }),
+  paths: DEFAULT_PATHS,                        // single source of truth (COMP-PATHS-EXTERNAL)
 });
 
 function cloneConfig(obj) {
@@ -120,9 +121,11 @@ export function loadProjectConfig() {
 
 export function resolveProjectPath(key) {
   const config = loadProjectConfig();
-  const rel = config.paths?.[key];
-  if (!rel) return path.join(getTargetRoot(), DEFAULT_CONFIG.paths[key] || key);
-  return path.join(getTargetRoot(), rel);
+  // resolvePathValue handles in-root / ../-escaping / absolute overrides.
+  // Preserve the legacy `|| key` fallback for keys absent from DEFAULT_PATHS.
+  // (COMP-PATHS-EXTERNAL)
+  const value = config.paths?.[key] ?? DEFAULT_PATHS[key] ?? key;
+  return resolvePathValue(getTargetRoot(), value, key);
 }
 
 /**

package/server/session-routes.js

@@ -11,7 +11,7 @@
 
 import path from 'node:path';
 import { readSessionsByFeature } from './session-store.js';
-import { getTargetRoot, getDataDir } from './project-root.js';
+import { getTargetRoot, getDataDir, resolveProjectPath } from './project-root.js';
 import { appendPhaseHistory } from './lifecycle-phase-history.js';
 import { reconcile } from '../lib/checkpoint/reconciler.js';
 import { checkpointConfig } from '../lib/checkpoint/checkpoint-writer.js';
@@ -140,7 +140,7 @@ export function attachSessionRoutes(app, { sessionManager, scheduleBroadcast, br
         featureCode,
         item,
         cwd: targetRoot,
-        featureDir: path.join(targetRoot, 'docs', 'features', featureCode),
+        featureDir: path.join(resolveProjectPath('features'), featureCode),
         composeDir: path.join(targetRoot, '.compose'),
         dataDir,
         store: cpStore,