@smartmemory/compose 0.2.49-beta → 0.2.51-beta

package/lib/hooks-status.js

@@ -0,0 +1,135 @@
+/**
+ * hooks-status.js — Shared git-hook status logic.
+ *
+ * Single source of truth for hook drift detection, consumed by:
+ *   - `compose hooks status` (bin/compose.js) — prints lines via formatHookStatusLines
+ *   - `GET /api/environment-health` (server/health-routes.js) — maps raw facts to API states
+ *
+ * Extracted verbatim from the historical inline `statusOne` (bin/compose.js) so
+ * the CLI output stays byte-identical. The ONLY addition is the non-state
+ * `wsVerified` flag: when the expected workspace id is unknown (null), the CLI
+ * stays lenient (reports "current") but the flag lets the API surface
+ * `workspace-unverified` instead of a false "current".
+ *
+ * Pure: no console output, no process exit. Reads only the hook files on disk.
+ *
+ * Roadmap: COMP-PARITY-3.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Marker comment baked into each Compose-installed hook (identifies "ours"). */
+export const HOOK_MARKERS = {
+  'post-commit': '# Compose post-commit hook —',
+  'pre-push': '# Compose pre-push hook —',
+};
+
+/** The hook types Compose manages, in display order. */
+export const HOOK_TYPE_LIST = Object.keys(HOOK_MARKERS);
+
+/** Pull the baked COMPOSE_WORKSPACE_ID="..." value out of hook content, or null. */
+export function extractBakedWorkspaceId(content) {
+  const m = content.match(/^COMPOSE_WORKSPACE_ID="([^"]*)"$/m);
+  return m ? m[1] : null;
+}
+
+/**
+ * Compute the raw status facts for every managed hook type.
+ *
+ * @param {object} opts
+ * @param {string} opts.projectRoot — repo root (hooks live at <root>/.git/hooks)
+ * @param {string|null} [opts.expectedWsId] — workspace id to compare against; null
+ *   means "unknown" (lenient match, wsVerified=false)
+ * @param {string} opts.composeNode — expected COMPOSE_NODE (process.execPath)
+ * @param {string} opts.composeBin — expected COMPOSE_BIN (path to compose.js)
+ * @returns {Record<string, HookStatusRaw>} keyed by hook type
+ */
+export function computeHooksStatus({ projectRoot, expectedWsId = null, composeNode, composeBin }) {
+  const hooksDir = join(projectRoot, '.git', 'hooks');
+  const out = {};
+  for (const type of HOOK_TYPE_LIST) {
+    out[type] = computeOne({ type, hooksDir, expectedWsId, composeNode, composeBin });
+  }
+  return out;
+}
+
+function computeOne({ type, hooksDir, expectedWsId, composeNode, composeBin }) {
+  const marker = HOOK_MARKERS[type];
+  const dest = join(hooksDir, type);
+
+  const empty = {
+    reason: null,
+    bakedWorkspace: null,
+    expectedWorkspace: expectedWsId ?? null,
+    wsVerified: false,
+    nodeMatch: false,
+    binMatch: false,
+  };
+
+  if (!existsSync(dest)) return { state: 'absent', ...empty };
+
+  const content = readFileSync(dest, 'utf-8');
+  if (!content.includes(marker)) return { state: 'foreign', ...empty };
+
+  const nodeMatch = content.includes(`COMPOSE_NODE="${composeNode}"`);
+  const binMatch = content.includes(`COMPOSE_BIN="${composeBin}"`);
+  const hasRawToken = content.includes('__COMPOSE_WORKSPACE_ID__');
+  const bakedWorkspace = extractBakedWorkspaceId(content);
+  // Mirror of statusOne: raw token never matches; a known expected id must match
+  // the baked value; an unknown (null) expected id is treated leniently as a match.
+  const wsMatch = hasRawToken ? false : expectedWsId ? content.includes(`COMPOSE_WORKSPACE_ID="${expectedWsId}"`) : true;
+
+  const base = {
+    bakedWorkspace,
+    expectedWorkspace: expectedWsId ?? null,
+    wsVerified: expectedWsId != null,
+    nodeMatch,
+    binMatch,
+  };
+
+  if (nodeMatch && binMatch && wsMatch && !hasRawToken) {
+    return { state: 'installed-current', reason: null, ...base };
+  }
+  const reason = hasRawToken
+    ? 'MISSING_WORKSPACE_ID'
+    : expectedWsId && !wsMatch
+      ? 'STALE_WORKSPACE_ID'
+      : 'stale paths';
+  return { state: 'installed-stale', reason, ...base };
+}
+
+/**
+ * Reproduce the exact lines `compose hooks status` printed for one hook type.
+ * Returns an array of strings (callers print each with console.log).
+ *
+ * @param {string} type — hook type ('post-commit' | 'pre-push')
+ * @param {HookStatusRaw} s — a single entry from computeHooksStatus
+ * @param {{composeNode: string, composeBin: string}} opts — current env values for the "expected" lines
+ * @returns {string[]}
+ */
+export function formatHookStatusLines(type, s, { composeNode, composeBin }) {
+  if (s.state === 'absent') return [`${type}: absent — no hook installed`];
+  if (s.state === 'foreign') return [`${type}: foreign — hook exists but is not a Compose hook`];
+  if (s.state === 'installed-current') {
+    const lines = [`${type}: installed (current)`];
+    if (s.bakedWorkspace) lines.push(`  workspace: ${s.bakedWorkspace}`);
+    return lines;
+  }
+  // installed-stale
+  const lines = [`${type}: installed (${s.reason} — re-run install)`];
+  if (s.reason === 'STALE_WORKSPACE_ID') lines.push(`  expected COMPOSE_WORKSPACE_ID="${s.expectedWorkspace}"`);
+  if (!s.nodeMatch) lines.push(`  expected COMPOSE_NODE="${composeNode}"`);
+  if (!s.binMatch) lines.push(`  expected COMPOSE_BIN="${composeBin}"`);
+  return lines;
+}
+
+/**
+ * @typedef {object} HookStatusRaw
+ * @property {'absent'|'foreign'|'installed-current'|'installed-stale'} state
+ * @property {null|'MISSING_WORKSPACE_ID'|'STALE_WORKSPACE_ID'|'stale paths'} reason
+ * @property {string|null} bakedWorkspace
+ * @property {string|null} expectedWorkspace
+ * @property {boolean} wsVerified
+ * @property {boolean} nodeMatch
+ * @property {boolean} binMatch
+ */

package/lib/ideabox.js

@@ -16,6 +16,7 @@
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs'
 import { join, dirname } from 'node:path'
+import { resolvePathValue } from './paths-core.js'
 
 // ---------------------------------------------------------------------------
 // Default template
@@ -540,7 +541,7 @@ export function loadLens(cwd, lensName) {
  * Read and parse the ideabox file from the project.
  */
 export function readIdeabox(cwd, ideaboxPath) {
-  const fullPath = join(cwd, ideaboxPath)
+  const fullPath = resolvePathValue(cwd, ideaboxPath, 'ideabox')
   if (!existsSync(fullPath)) {
     // Return empty state
     return { ideas: [], killed: [], nextId: 1 }
@@ -553,7 +554,7 @@ export function readIdeabox(cwd, ideaboxPath) {
  * Write serialized ideabox back to disk.
  */
 export function writeIdeabox(cwd, ideaboxPath, parsedData) {
-  const fullPath = join(cwd, ideaboxPath)
+  const fullPath = resolvePathValue(cwd, ideaboxPath, 'ideabox')
   mkdirSync(dirname(fullPath), { recursive: true })
   writeFileSync(fullPath, serializeIdeabox(parsedData))
 }

package/lib/install-agent-defs.js

@@ -0,0 +1,22 @@
+import { existsSync, mkdirSync, readdirSync, copyFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Install Claude Code agent definitions (*.md) from srcDir into destDir.
+ * Idempotent: mkdir -p the dest and overwrite existing files. Returns the list
+ * of installed agent names (filenames sans `.md`). No-op → [] when srcDir is
+ * absent or has no `.md` files. (COMP-AGENT-VENDOR-1 — vendored compose-explorer
+ * / compose-architect were referenced by the skill but never installed.)
+ */
+export function installAgentDefs(srcDir, destDir) {
+  if (!srcDir || !existsSync(srcDir)) return [];
+  const defs = readdirSync(srcDir).filter(f => f.endsWith('.md'));
+  if (defs.length === 0) return [];
+  mkdirSync(destDir, { recursive: true });
+  const installed = [];
+  for (const f of defs) {
+    copyFileSync(join(srcDir, f), join(destDir, f));
+    installed.push(f.replace(/\.md$/, ''));
+  }
+  return installed;
+}

package/lib/journal-writer.js

@@ -29,12 +29,12 @@ import { join, dirname } from 'node:path';
 
 import { appendEvent, normalizeSince } from './feature-events.js';
 import { checkOrInsert } from './idempotency.js';
+import { resolveJournalPath } from './project-paths.js';
 
 // ---------------------------------------------------------------------------
 // Constants & regexes
 // ---------------------------------------------------------------------------
 
-const JOURNAL_DIR     = 'docs/journal';
 const INDEX_FILE      = 'README.md';
 const ENTRIES_HEADING = '## Entries';
 
@@ -649,7 +649,7 @@ export async function writeJournalEntry(cwd, args) {
   validateArgs(args);
 
   return maybeIdempotent({ ...args, cwd }, async () => {
-    const journalDir = join(cwd, JOURNAL_DIR);
+    const journalDir = resolveJournalPath(cwd);
     const indexPath  = join(journalDir, INDEX_FILE);
 
     // Pre-flight: read + parse index before any disk mutation.
@@ -857,7 +857,7 @@ export async function writeJournalEntry(cwd, args) {
  * @returns {{ entries: Array, count: number }}
  */
 export function getJournalEntries(cwd, opts = {}) {
-  const journalDir = join(cwd, JOURNAL_DIR);
+  const journalDir = resolveJournalPath(cwd);
   if (!existsSync(journalDir)) return { entries: [], count: 0 };
 
   const sinceMs = opts.since !== undefined ? normalizeSince(opts.since) : null;

package/lib/migrate-anon.js

@@ -0,0 +1,277 @@
+/**
+ * migrate-anon — COMP-MCP-MIGRATION-2-1-1-1
+ *
+ * `compose migrate-anon`: interactive promotion of historical *anonymous*
+ * ROADMAP rows (the `| — | Item | Status |` form preserved verbatim by
+ * COMP-MCP-MIGRATION-2-1-1) to typed features.
+ *
+ * Load-bearing correctness point: anonymous rows are re-emitted on regen by
+ * `predecessorCode` anchoring, and a row only stops being anonymous when its raw
+ * Feature cell becomes a valid code. So scaffolding a feature.json ALONE leaves
+ * the `—` row passing through verbatim → a DUPLICATE. Promotion therefore strips
+ * the source `rawLine` from ROADMAP.md *before* scaffold+regen.
+ *
+ * `readAnonymousRows` is the canonical classifier for which rows are anonymous +
+ * their order + anchor; this module only adds header-aware cell display and the
+ * strip-then-scaffold primitive on top of it.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+
+import { resolveRoadmapPath, loadFeaturesDir } from './project-paths.js';
+import { readAnonymousRows, PRESERVED_OPEN_RE, PRESERVED_CLOSE_RE } from './roadmap-preservers.js';
+import { splitRoadmapCells, detectColumnLayout } from './roadmap-parser.js';
+import { splitPhaseHeading, PHASE_HEADING_TEXT_RE, parseStatusToken, STATUS_TOKENS } from './roadmap-heading.js';
+import { isFeatureCode } from './feature-code.js';
+import { listFeatures, positionSortKey } from './feature-json.js';
+import { addRoadmapEntry } from './feature-writer.js';
+
+const FENCE_RE = /^```/;
+const TABLE_ROW_RE = /^\|.+\|$/;
+const TABLE_DIVIDER_RE = /^\|[\s|:-]+\|$/;
+
+// Strip markdown bold/code markers so a `**IN_PROGRESS**` or `` `x` `` cell
+// matches the same way the roadmap parser sees it (it bold-strips before parsing).
+// NB: do NOT strip `_` — it's part of the `IN_PROGRESS` status token itself.
+const stripEmphasis = (s) => String(s ?? '').replace(/[*`]/g, '').trim();
+
+/**
+ * Parse anonymous rows for display, header-aware. Classification + raw text +
+ * anchor come from the canonical `readAnonymousRows`; the column layout only
+ * decides which cell is title vs status, and is taken from the **nearest
+ * preceding header** of each row's own table — a phase can hold multiple tables
+ * with different layouts (3-col then 4-col), so a single per-phase header is
+ * wrong. The forward scan mirrors `readAnonymousRows`' table-state reset (a
+ * non-table line or a new heading ends the current table) and matches anon rows
+ * by in-order `rawLine` equality, so classification never drifts and the layout
+ * is display-only (a misread can never affect strip/anchor).
+ *
+ * @param {string} text - ROADMAP.md source
+ * @returns {Array<{phaseId:string, occurrenceIndex:number, num:string, title:string, status:string, rawLine:string, predecessorCode:string|null}>}
+ */
+export function collectAnonRowsFromText(text) {
+  const anonMap = readAnonymousRows(text);
+  const ptr = new Map(); // phaseId → next occurrence index to match
+  const out = [];
+  let inFence = false;
+  let inPreserved = false;
+  let cur = null;
+  let header = null;
+  let inTable = false;
+
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (FENCE_RE.test(trimmed)) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    if (PRESERVED_OPEN_RE.test(trimmed)) { inPreserved = true; inTable = false; header = null; continue; }
+    if (PRESERVED_CLOSE_RE.test(trimmed)) { inPreserved = false; continue; }
+    if (inPreserved) continue;
+
+    const h = line.match(PHASE_HEADING_TEXT_RE);
+    if (h && line.startsWith('## ')) { cur = splitPhaseHeading(h[1]).title; inTable = false; header = null; continue; }
+    if (!cur) continue;
+
+    if (!TABLE_ROW_RE.test(trimmed)) { inTable = false; header = null; continue; }
+    if (!inTable) { header = splitRoadmapCells(line); inTable = true; continue; } // header row
+    if (TABLE_DIVIDER_RE.test(trimmed)) continue;
+
+    // Data row — match against the canonical anon list in document order.
+    const rows = anonMap.get(cur) ?? [];
+    const p = ptr.get(cur) ?? 0;
+    if (p < rows.length && line === rows[p].rawLine) {
+      const layout = detectColumnLayout(header ?? ['#', 'Item', 'Status']);
+      const cells = splitRoadmapCells(line);
+      const num = layout.codeCol >= 0 ? (cells[layout.codeCol] ?? '') : (cells[0] ?? '');
+      const title = stripEmphasis(cells[layout.descCol] ?? '');
+      const status = parseStatusToken(stripEmphasis(cells[layout.statusCol] ?? '')) ?? 'PLANNED';
+      out.push({ phaseId: cur, occurrenceIndex: p, num, title, status, rawLine: line, predecessorCode: rows[p].predecessorCode });
+      ptr.set(cur, p + 1);
+    }
+  }
+  return out;
+}
+
+/**
+ * Locate the physical line index of the `occurrenceIndex`-th anonymous row in a
+ * phase. Forward-scans, consuming `readAnonymousRows`' ordered rawLines so that
+ * identical row text resolves to the correct physical occurrence (no global
+ * string match). Returns -1 if not found.
+ */
+function anonLineIndex(text, phaseId, occurrenceIndex) {
+  const rows = readAnonymousRows(text).get(phaseId) ?? [];
+  if (occurrenceIndex < 0 || occurrenceIndex >= rows.length) return -1;
+  const lines = text.split('\n');
+  let inFence = false;
+  let inPreserved = false;
+  let cur = null;
+  let ptr = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+    if (FENCE_RE.test(trimmed)) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    if (PRESERVED_OPEN_RE.test(trimmed)) { inPreserved = true; continue; }
+    if (PRESERVED_CLOSE_RE.test(trimmed)) { inPreserved = false; continue; }
+    if (inPreserved) continue;
+    const h = line.match(PHASE_HEADING_TEXT_RE);
+    if (h && line.startsWith('## ')) { cur = splitPhaseHeading(h[1]).title; continue; }
+    if (cur === phaseId && ptr < rows.length && line === rows[ptr].rawLine) {
+      if (ptr === occurrenceIndex) return i;
+      ptr++;
+    }
+  }
+  return -1;
+}
+
+/**
+ * Remove the `occurrenceIndex`-th anonymous row of `phaseId` from ROADMAP text.
+ * Phase-scoped and occurrence-specific. Returns the new text (throws if not found).
+ */
+export function stripAnonLine(text, phaseId, occurrenceIndex) {
+  const idx = anonLineIndex(text, phaseId, occurrenceIndex);
+  if (idx === -1) {
+    throw new Error(`migrate-anon: anon row #${occurrenceIndex} not found in phase "${phaseId}"`);
+  }
+  const lines = text.split('\n');
+  lines.splice(idx, 1);
+  return lines.join('\n');
+}
+
+// Best-effort end-of-phase position. Computed with positionSortKey (string-aware),
+// NOT nextPositionInPhase which coerces string/ranged positions to 0.
+async function endOfPhasePosition(cwd, phaseId) {
+  // Config-aware features dir (mirrors addRoadmapEntry) — listFeatures defaults to
+  // docs/features and would otherwise miss relocated feature sets.
+  const peers = (await listFeatures(cwd, loadFeaturesDir(cwd))).filter((f) => f.phase === phaseId);
+  if (peers.length === 0) return 1;
+  const max = peers.reduce((m, f) => Math.max(m, positionSortKey(f.position)), 0);
+  return max + 1;
+}
+
+/**
+ * Promote one anonymous row to a typed feature: strip its rawLine, then scaffold.
+ *
+ * Failure handling keys on the error code, because addRoadmapEntry commits
+ * feature.json BEFORE regenerating ROADMAP.md:
+ *   - pre-commit failures (validation / code-exists / ROUNDTRIP_NOT_FIXED_POINT)
+ *     → restore the stripped snapshot (nothing committed) and rethrow.
+ *   - ROADMAP_PARTIAL_WRITE (feature.json committed, regen failed) → do NOT
+ *     restore (that would re-add the anon row alongside the typed feature = the
+ *     duplicate this flow avoids); rethrow as-is. Re-running reconciles.
+ *
+ * @param {string} cwd
+ * @param {{phaseId:string, occurrenceIndex:number, title:string}} row
+ * @param {{code:string, status?:string, scaffold?:Function}} opts
+ */
+export async function promoteAnonRow(cwd, row, { code, status = 'PLANNED', scaffold = addRoadmapEntry } = {}) {
+  const upper = String(code).toUpperCase();
+  if (!isFeatureCode(upper)) {
+    throw new Error(`migrate-anon: "${code}" is not a valid feature code`);
+  }
+  const roadmapPath = resolveRoadmapPath(cwd);
+  const snapshot = readFileSync(roadmapPath, 'utf-8');
+  const stripped = stripAnonLine(snapshot, row.phaseId, row.occurrenceIndex);
+  writeFileSync(roadmapPath, stripped);
+  try {
+    const position = await endOfPhasePosition(cwd, row.phaseId);
+    return await scaffold(cwd, {
+      code: upper,
+      description: row.title,
+      phase: row.phaseId,
+      status,
+      complexity: 'S',
+      position,
+    });
+  } catch (err) {
+    if (err && err.code === 'ROADMAP_PARTIAL_WRITE') throw err;
+    // Pre-commit failure: nothing was committed — put the anon row back.
+    writeFileSync(roadmapPath, snapshot);
+    throw err;
+  }
+}
+
+/**
+ * Interactive driver. Streams are injectable for testing. Callers (the CLI) own
+ * the non-TTY guard: pass `nonInteractive: true` for piped stdin / --non-interactive
+ * / --dry-run, and this lists the rows without prompting.
+ *
+ * @param {string} cwd
+ * @param {{input?:any, output?:any, nonInteractive?:boolean, dryRun?:boolean, scaffold?:Function}} [opts]
+ * @returns {Promise<{listed:number, promoted:string[], aborted:boolean}>}
+ */
+export async function runMigrateAnon(cwd, opts = {}) {
+  const {
+    input = process.stdin,
+    output = process.stdout,
+    nonInteractive = false,
+    dryRun = false,
+    scaffold = addRoadmapEntry,
+  } = opts;
+  const write = (s) => output.write(s + '\n');
+  const roadmapPath = resolveRoadmapPath(cwd);
+  const rows = collectAnonRowsFromText(readFileSync(roadmapPath, 'utf-8'));
+
+  if (rows.length === 0) {
+    write('migrate-anon: no anonymous rows found.');
+    return { listed: 0, promoted: [], aborted: false };
+  }
+
+  if (nonInteractive || dryRun) {
+    write(`migrate-anon: ${rows.length} anonymous row(s):`);
+    for (const r of rows) write(`  [${r.phaseId}] ${r.title}  (${r.status})`);
+    write('Run interactively in a TTY to promote rows.');
+    return { listed: rows.length, promoted: [], aborted: false };
+  }
+
+  const rl = createInterface({ input, output });
+  const ask = (q) => new Promise((res) => rl.question(q, res));
+  const promoted = [];
+  const promotedByPhase = {};
+  let aborted = false;
+
+  try {
+    for (const row of rows) {
+      write(`\n[${row.phaseId}] ${row.title}`);
+      write(`  inferred status: ${row.status}`);
+
+      // Code prompt (re-prompt on invalid; Enter=skip; q=abort).
+      let code = null;
+      for (;;) {
+        const ans = (await ask('  Code to assign (Enter=skip, q=abort): ')).trim();
+        if (ans === '') break;
+        if (ans.toLowerCase() === 'q') { aborted = true; break; }
+        const c = ans.toUpperCase();
+        if (!isFeatureCode(c)) { write(`  ✗ "${ans}" is not a valid feature code — try again`); continue; }
+        code = c;
+        break;
+      }
+      if (aborted) break;
+      if (!code) continue;
+
+      // Status confirm/override.
+      const sAns = (await ask(`  Status [${row.status}] (Enter=keep, or one of ${STATUS_TOKENS.join('/')}): `)).trim();
+      let status = row.status;
+      if (sAns !== '') {
+        const s = sAns.toUpperCase();
+        if (STATUS_TOKENS.includes(s)) status = s;
+        else write(`  (unrecognized status "${sAns}" — keeping ${row.status})`);
+      }
+
+      const liveIndex = row.occurrenceIndex - (promotedByPhase[row.phaseId] ?? 0);
+      try {
+        await promoteAnonRow(cwd, { ...row, occurrenceIndex: liveIndex }, { code, status, scaffold });
+        promoted.push(code);
+        promotedByPhase[row.phaseId] = (promotedByPhase[row.phaseId] ?? 0) + 1;
+        write(`  ✓ promoted to ${code}`);
+      } catch (err) {
+        write(`  ✗ promotion failed: ${err.message}`);
+        throw err;
+      }
+    }
+  } finally {
+    rl.close();
+  }
+
+  write(`\nmigrate-anon: ${promoted.length} promoted${aborted ? ' (aborted early)' : ''}.`);
+  return { listed: rows.length, promoted, aborted };
+}

package/lib/migrate-roadmap.js

@@ -6,10 +6,9 @@
  */
 
 import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
 import { parseRoadmap } from './roadmap-parser.js';
 import { readFeature, writeFeature } from './feature-json.js';
-import { loadFeaturesDir } from './project-paths.js';
+import { loadFeaturesDir, resolveRoadmapPath } from './project-paths.js';
 
 /**
  * Migrate ROADMAP.md entries to feature.json files.
@@ -31,7 +30,7 @@ export function migrateRoadmap(cwd, opts = {}) {
   const featuresDir = opts.featuresDir ?? loadFeaturesDir(cwd);
   const externalPrefixes = opts.externalPrefixes ?? [];
   const isExternal = (code) => externalPrefixes.some((p) => code.startsWith(p));
-  const roadmapPath = join(cwd, 'ROADMAP.md');
+  const roadmapPath = resolveRoadmapPath(cwd);
 
   if (!existsSync(roadmapPath)) {
     throw new Error(`No ROADMAP.md found at ${roadmapPath}`);

package/lib/paths-core.js

@@ -0,0 +1,47 @@
+/**
+ * paths-core.js — PURE artifact-path resolution. No fs, no config reading.
+ * Single source of truth for default artifact locations (COMP-PATHS-EXTERNAL).
+ *
+ * `resolvePathValue` uses path.resolve (NOT path.join) so an absolute or
+ * ../-escaping `paths.*` override resolves correctly instead of being
+ * silently re-rooted under cwd.
+ */
+import path from 'node:path';
+
+export const DEFAULT_PATHS = Object.freeze({
+  docs: 'docs',
+  roadmap: 'ROADMAP.md',
+  features: 'docs/features',
+  journal: 'docs/journal',
+  context: 'docs/context',
+  ideabox: 'docs/product/ideabox.md',
+});
+
+/**
+ * Resolve a configured `paths[key]` value to an absolute, normalized path.
+ *
+ * @param {string} root  Absolute workspace root.
+ * @param {*} value      The configured paths[key] value (any type).
+ * @param {string} key   Fallback key into DEFAULT_PATHS when value is unusable.
+ * @returns {string}     Absolute, normalized path.
+ */
+export function resolvePathValue(root, value, key) {
+  const v = (typeof value === 'string' && value.trim().length > 0)
+    ? value
+    : DEFAULT_PATHS[key];
+  return path.isAbsolute(v) ? path.normalize(v) : path.resolve(root, v);
+}
+
+/**
+ * Display-safe relativization: a clean root-relative string when `abs` is
+ * inside `root`, else the absolute path (never a `../`-prefixed string).
+ *
+ * @param {string} root  Absolute workspace root.
+ * @param {string} abs   Absolute path to relativize for display.
+ * @returns {string}
+ */
+export function relForDisplay(root, abs) {
+  const rel = path.relative(root, abs);
+  if (rel === '') return '.';
+  return rel.startsWith('..') || path.isAbsolute(rel) ? abs : rel;
+}

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 };