@smartmemory/compose 0.2.49-beta → 0.2.51-beta

package/lib/checkpoint/checkpoint-writer.js

@@ -16,6 +16,7 @@ import { captureFingerprint } from './fingerprint.js';
 import { captureAnchor } from './anchor.js';
 import { scribePrompt } from './prompts.js';
 import { createCheckpointStore } from './store/index.js';
+import { resolveFeaturesPath } from '../project-paths.js';
 
 /**
  * Resolve the checkpoint config block from .compose/compose.json with defaults
@@ -75,7 +76,7 @@ export function writeCheckpoint(targetRoot, {
   const cfg = checkpointConfig(targetRoot);
   const dataDir = path.join(targetRoot, '.compose', 'data');
   const composeDir = path.join(targetRoot, '.compose');
-  const featureDir = path.join(targetRoot, 'docs', 'features', featureCode);
+  const featureDir = path.join(resolveFeaturesPath(targetRoot), featureCode);
 
   const store = createCheckpointStore(cfg.backend, { dataDir });
   // The prior checkpoint (read before writing) seeds the scribe prompt's context.
@@ -121,7 +122,7 @@ export function anchorBoundary(targetRoot, { item, trigger, flowId = null } = {}
     if (!featureCode) return null;
     const dataDir = path.join(targetRoot, '.compose', 'data');
     const composeDir = path.join(targetRoot, '.compose');
-    const featureDir = path.join(targetRoot, 'docs', 'features', featureCode);
+    const featureDir = path.join(resolveFeaturesPath(targetRoot), featureCode);
     const store = createCheckpointStore(cfg.backend, { dataDir });
     return captureAnchor({ item, trigger, cwd: targetRoot, featureDir, composeDir, dataDir, store, flowId });
   } catch (err) {

package/lib/codex-preflight.js

@@ -0,0 +1,151 @@
+/**
+ * COMP-CODEX-IMPL — preflight probe for the Codex-as-implementer path.
+ *
+ * Codex self-applies a Seatbelt sandbox ([[project_codex_seatbelt_nonnesting]]).
+ * Compose's `execute` step runs each task agent inside a *detached git worktree*
+ * (`git worktree add --detach`), whose `.git` is a file pointer, not a directory.
+ * Whether Codex's Seatbelt tolerates writing inside such a worktree is UNVERIFIED —
+ * no Codex+worktree path exists in the repo today (Codex only ever ran read-only
+ * reviews with cwd at the repo root). If it cannot, a `--codex` build would
+ * hard-fail at `execute`. A runtime warning would only explain that after the fact.
+ *
+ * So before any real `--codex` work, we probe the exact primitive: create a throwaway
+ * detached worktree, have Codex write a sentinel file in it, and verify the write
+ * landed. On failure the build aborts fast with an actionable message rather than
+ * failing mid-execute. The result is cached per-repo (the primitive doesn't change
+ * between builds) and can be skipped via COMPOSE_SKIP_CODEX_PROBE for CI/tests.
+ *
+ * The proper fix for a probe-fails environment (a Codex `isolation: none` execution
+ * path) is deferred to COMP-CODEX-IMPL-SPIKE.
+ */
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+export const PROBE_SENTINEL = 'COMPOSE_CODEX_PROBE_OK';
+const WORKTREE_BASE = join(homedir(), '.stratum', 'worktrees');
+const PROBE_CACHE = 'codex-worktree-probe.json';
+// Bound the probe's agent run so a wedged Codex CLI can't hang the whole build
+// before the flow even starts. On timeout we reject → the finally cleanup runs.
+const PROBE_AGENT_TIMEOUT_MS = 180_000;
+
+function cachePath(dataDir) {
+  return join(dataDir, PROBE_CACHE);
+}
+
+export function readProbeCache(dataDir) {
+  try {
+    return JSON.parse(readFileSync(cachePath(dataDir), 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+export function writeProbeCache(dataDir, result) {
+  try {
+    mkdirSync(dataDir, { recursive: true });
+    writeFileSync(cachePath(dataDir), JSON.stringify(result, null, 2));
+  } catch { /* best-effort cache; a miss just re-probes */ }
+}
+
+function isGitRepo(cwd) {
+  try {
+    execSync('git rev-parse --is-inside-work-tree', { cwd, encoding: 'utf-8', timeout: 5000, stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Verify Codex can write inside a detached git worktree under its sandbox.
+ *
+ * @param {object} args
+ * @param {string} args.cwd       repo working directory
+ * @param {object} args.stratum   stratum client (uses runAgentText('codex', ...))
+ * @param {string} args.dataDir   .compose/data dir for the per-repo cache
+ * @param {string} args.ts        caller-supplied timestamp string (unique worktree name)
+ * @param {boolean} [args.force]  ignore the cache and re-probe
+ * @returns {Promise<{ok: boolean, reason: string, cached?: boolean, skipped?: boolean}>}
+ */
+export async function preflightCodexWorktreeProbe({ cwd, stratum, dataDir, ts, force = false }) {
+  if (process.env.COMPOSE_SKIP_CODEX_PROBE) {
+    return { ok: true, skipped: true, reason: 'COMPOSE_SKIP_CODEX_PROBE set — probe skipped' };
+  }
+  if (!force) {
+    const cached = readProbeCache(dataDir);
+    if (cached && cached.ok === true) return { ...cached, cached: true };
+  }
+  // Not a git repo → the execute step won't create worktrees (useWorktrees gates on
+  // isGitRepo), so there is no worktree primitive to probe. Treat as a pass.
+  if (!isGitRepo(cwd)) {
+    return { ok: true, reason: 'not a git repo — worktree isolation is not used, nothing to probe' };
+  }
+
+  try { mkdirSync(WORKTREE_BASE, { recursive: true }); } catch { /* best-effort */ }
+  const wtPath = join(WORKTREE_BASE, `codex-probe-${ts}`);
+
+  // Create the detached worktree (the exact primitive the execute step uses).
+  try {
+    execSync(`git worktree add "${wtPath}" --detach HEAD`, {
+      cwd, encoding: 'utf-8', timeout: 30_000, stdio: 'pipe',
+    });
+  } catch (err) {
+    try { execSync(`rm -rf "${wtPath}"`, { encoding: 'utf-8', timeout: 10_000 }); } catch { /* best-effort */ }
+    const result = { ok: false, reason: `could not create a probe worktree: ${err?.message ?? err}` };
+    writeProbeCache(dataDir, result);
+    return result;
+  }
+
+  // Unique per-run filename so a file committed in the repo (carried into the
+  // detached worktree from HEAD) can never make the probe false-pass.
+  const probeName = `codex-probe-${ts}.txt`;
+  try {
+    const prompt =
+      `Write a file named ${probeName} in the current working directory whose exact ` +
+      `contents are the single line: ${PROBE_SENTINEL}\n` +
+      `Do nothing else. This is an environment write-probe.`;
+    try {
+      // Bound the agent run — a hang here would otherwise stall the build and skip
+      // the finally cleanup. On timeout the race rejects and we fall to the catch.
+      await Promise.race([
+        stratum.runAgentText('codex', prompt, { cwd: wtPath }),
+        new Promise((_, reject) =>
+          setTimeout(() => reject(new Error(`probe timed out after ${PROBE_AGENT_TIMEOUT_MS}ms`)), PROBE_AGENT_TIMEOUT_MS).unref?.()
+        ),
+      ]);
+    } catch (err) {
+      const result = { ok: false, reason: `Codex agent run failed/timed out inside the worktree: ${err?.message ?? err}` };
+      writeProbeCache(dataDir, result);
+      return result;
+    }
+    const probeFile = join(wtPath, probeName);
+    let landed = false;
+    try {
+      landed = existsSync(probeFile) && readFileSync(probeFile, 'utf-8').includes(PROBE_SENTINEL);
+    } catch { landed = false; }
+    const result = landed
+      ? { ok: true, reason: 'Codex wrote the sentinel inside a detached worktree' }
+      : { ok: false, reason: 'Codex did not write the sentinel file inside the detached worktree (likely a Seatbelt/worktree write restriction)' };
+    writeProbeCache(dataDir, result);
+    return result;
+  } finally {
+    try {
+      execSync(`git worktree remove "${wtPath}" --force`, { cwd, encoding: 'utf-8', timeout: 30_000, stdio: 'pipe' });
+    } catch {
+      try { execSync(`rm -rf "${wtPath}"`, { encoding: 'utf-8', timeout: 10_000 }); } catch { /* give up */ }
+    }
+  }
+}
+
+/** The actionable abort message when the probe fails. */
+export function codexProbeAbortMessage(reason) {
+  return (
+    `--codex aborted: Codex cannot write inside a detached git worktree in this environment.\n` +
+    `  Reason: ${reason}\n` +
+    `  This is the known COMP-CODEX-IMPL-SPIKE limitation (Codex Seatbelt vs worktree isolation).\n` +
+    `  Re-run without --codex (Claude implements), or set COMPOSE_SKIP_CODEX_PROBE=1 to bypass the\n` +
+    `  probe at your own risk. A Codex isolation:none execution path is tracked as the follow-up.`
+  );
+}

package/lib/completion-writer.js

@@ -42,6 +42,13 @@ async function getProvider(cwd) {
 // ---------------------------------------------------------------------------
 const SHA_RE          = /^[0-9a-f]{40}$/i;   // FULL SHA only (Decision 9). Case-insensitive input; normalize to lowercase.
 const SHORT_LEN       = 8;                    // Display only — never the dedup key.
+// git's null-SHA. Stamped for a commit-less completion (non-git workspace —
+// COMP-PATHS-EXTERNAL Decision 6b). Schema-valid (matches SHA_RE) and a
+// well-known "no commit" marker, so no schema or downstream change is needed.
+const NULL_SHA        = '0'.repeat(40);
+// Monotonic per-process counter so distinct commit-less completions get
+// distinct completion_ids even within the same millisecond.
+let _nocommitSeq      = 0;
 const DEFAULT_LIMIT   = 50;
 const MAX_LIMIT       = 500;
 
@@ -124,6 +131,10 @@ function validateRepoRelativePath(p) {
   if (p.includes('\0')) {
     throw inputError(`files_changed: entry contains NUL byte: "${p}"`);
   }
+  // files_changed stays repo-relative on purpose — absolute paths are a
+  // path-safety hazard (e.g. "/etc/passwd") and no caller needs them: the
+  // commit-less (external) ship path passes []. (COMP-PATHS-EXTERNAL: kept the
+  // guard rather than widen it for an unused capability.)
   if (p.startsWith('/')) {
     throw inputError(`files_changed: absolute paths not allowed: "${p}"`);
   }
@@ -151,16 +162,21 @@ function validate(args) {
     );
   }
 
-  // commit_sha — full 40-char hex required (Decision 9)
-  if (typeof args.commit_sha !== 'string' || args.commit_sha.trim().length === 0) {
-    throw inputError('completion-writer: commit_sha is required (non-empty string)');
-  }
-  const trimmedSha = args.commit_sha.trim();
-  if (!SHA_RE.test(trimmedSha)) {
-    throw inputError(
-      `completion-writer: commit_sha must be a full 40-char hex SHA (Decision 9). ` +
-      `Got "${trimmedSha}" (length ${trimmedSha.length}). Short prefixes are rejected on write.`
-    );
+  // commit_sha — OPTIONAL (COMP-PATHS-EXTERNAL Decision 6b): omitted/null means
+  // a commit-less completion (non-git workspace) and is stamped with NULL_SHA.
+  // When PRESENT it must still be a full 40-char hex SHA (Decision 9) — a
+  // malformed value (short, non-hex, empty string, non-string) is rejected.
+  if (args.commit_sha !== undefined && args.commit_sha !== null) {
+    if (typeof args.commit_sha !== 'string' || args.commit_sha.trim().length === 0) {
+      throw inputError('completion-writer: commit_sha must be a non-empty 40-char hex SHA when provided');
+    }
+    const trimmedSha = args.commit_sha.trim();
+    if (!SHA_RE.test(trimmedSha)) {
+      throw inputError(
+        `completion-writer: commit_sha must be a full 40-char hex SHA (Decision 9). ` +
+        `Got "${trimmedSha}" (length ${trimmedSha.length}). Short prefixes are rejected on write.`
+      );
+    }
   }
 
   // tests_pass — strict boolean
@@ -193,6 +209,18 @@ function validate(args) {
     throw inputError('completion-writer: set_status must be a boolean');
   }
 
+  // built_via — OPTIONAL marker recording the pipeline template a feature was
+  // built with (e.g. 'build-quick'). Persisted on feature.json so downstream
+  // consumers (e.g. the validator's report-completion check) can tell which
+  // lifecycle produced the feature. Must be a lowercase template slug.
+  if (args.built_via !== undefined && args.built_via !== null) {
+    if (typeof args.built_via !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(args.built_via)) {
+      throw inputError(
+        `completion-writer: built_via must be a lowercase template slug (e.g. "build-quick"), got "${args.built_via}"`
+      );
+    }
+  }
+
   // force — boolean if present
   if (args.force !== undefined && typeof args.force !== 'boolean') {
     throw inputError('completion-writer: force must be a boolean');
@@ -248,6 +276,8 @@ async function safeAppendEvent(cwd, event) {
  * @param {string}   [args.notes]
  * @param {boolean}  [args.set_status]     Default true — flip status to COMPLETE
  * @param {boolean}  [args.force]          Replace existing same-(code,sha) record
+ * @param {string}   [args.built_via]      Optional template slug (e.g. 'build-quick')
+ *                                         stamped onto feature.json (COMP-BUILD-QUICK-1)
  * @param {string}   [args.idempotency_key]
  *
  * @returns {{ feature_code, completion_id, commit_sha, commit_sha_short,
@@ -257,13 +287,21 @@ export async function recordCompletion(cwd, args) {
   // 1. Validate
   validate(args);
 
-  // 2. Normalize SHA
-  const commit_sha       = args.commit_sha.trim().toLowerCase();
+  // 2. Normalize SHA (omitted/null ⇒ NULL_SHA sentinel — commit-less completion)
+  const commit_sha       = (args.commit_sha === undefined || args.commit_sha === null)
+    ? NULL_SHA
+    : args.commit_sha.trim().toLowerCase();
   const commit_sha_short = commit_sha.slice(0, SHORT_LEN);
   const feature_code     = args.feature_code;
 
-  // 3. Compute completion_id
-  const completion_id = `${feature_code}:${commit_sha}`;
+  // 3. Compute completion_id. For a real commit the SHA makes it stable and
+  //    dedup-able. For a commit-less completion (NULL_SHA) the SHA is constant,
+  //    so id off the sha would alias every no-commit completion of a feature
+  //    onto one record (a re-completion would idempotent-no-op). Derive a
+  //    distinct id from a timestamp instead. (COMP-PATHS-EXTERNAL D6b)
+  const completion_id = (commit_sha === NULL_SHA)
+    ? `${feature_code}:nocommit:${Date.now().toString(36)}-${(_nocommitSeq++).toString(36)}`
+    : `${feature_code}:${commit_sha}`;
 
   // 4. Wrap in maybeIdempotent for caller-key path
   return maybeIdempotent({ ...args, cwd }, async () => {
@@ -320,7 +358,13 @@ export async function recordCompletion(cwd, args) {
       // 5h. Persist completion record BEFORE status flip (so flip failure doesn't lose the record)
       // Use persistFeatureRaw (policy-free, no status-delta guard) — completion-writer
       // owns its own ordering/locking and only mutates the completions array, not status.
-      await provider.persistFeatureRaw(feature_code, { ...feature, completions });
+      await provider.persistFeatureRaw(feature_code, {
+        ...feature,
+        completions,
+        // COMP-BUILD-QUICK-1: stamp the build template (e.g. 'build-quick') so the
+        // validator can exempt quick-built features from MISSING_COMPLETION_REPORT.
+        ...(args.built_via ? { built_via: args.built_via } : {}),
+      });
 
       // 5i. Status flip (default on)
       const set_status = args.set_status !== false;

package/lib/feature-json.js

@@ -10,6 +10,17 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync, unlinkS
 import { join, basename } from 'path';
 import { readdirSync } from 'fs';
 import { assertValidLinkShape, assertLinkTargetsExist } from './feature-write-guard.js';
+import { resolvePathValue } from './paths-core.js';
+
+/**
+ * Resolve the features-dir base. `featuresDir` may be relative-to-cwd (legacy,
+ * incl. the default), ../-escaping, or absolute (COMP-PATHS-EXTERNAL D7).
+ * Identical to join(cwd, featuresDir) for plain relative dirs.
+ * @returns {string} absolute features dir
+ */
+function featuresBase(cwd, featuresDir) {
+  return resolvePathValue(cwd, featuresDir, 'features');
+}
 
 /**
  * @typedef {object} FeatureJson
@@ -34,7 +45,7 @@ import { assertValidLinkShape, assertLinkTargetsExist } from './feature-write-gu
  * @returns {FeatureJson|null}
  */
 export function readFeature(cwd, code, featuresDir = 'docs/features') {
-  const path = join(cwd, featuresDir, code, 'feature.json');
+  const path = join(featuresBase(cwd, featuresDir), code, 'feature.json');
   if (!existsSync(path)) return null;
   try {
     return JSON.parse(readFileSync(path, 'utf-8'));
@@ -66,7 +77,7 @@ export function writeFeature(cwd, feature, featuresDir = 'docs/features', opts =
     const priorLinks = hasTargets ? (readFeature(cwd, feature.code, featuresDir)?.links) : undefined;
     assertLinkTargetsExist(cwd, feature, { allowForwardRefs: opts.allowForwardRefs, priorLinks });
   }
-  const dir = join(cwd, featuresDir, feature.code);
+  const dir = join(featuresBase(cwd, featuresDir), feature.code);
   mkdirSync(dir, { recursive: true });
   const path = join(dir, 'feature.json');
   feature.updated = new Date().toISOString().slice(0, 10);
@@ -115,7 +126,7 @@ export function positionSortKey(position) {
  * @returns {FeatureJson[]}
  */
 export function listFeatures(cwd, featuresDir = 'docs/features') {
-  const dir = join(cwd, featuresDir);
+  const dir = featuresBase(cwd, featuresDir);
   if (!existsSync(dir)) return [];
 
   const features = [];

package/lib/feature-validator.js

@@ -43,6 +43,9 @@ import { featureStatusToVisionStatus } from './status-projection.js';
 import { GitHubApi } from './tracker/github-api.js';
 import { ArtifactManager } from '../server/artifact-manager.js';
 import { SchemaValidator } from '../server/schema-validator.js';
+import {
+  resolveRoadmapPathFromConfig, resolveFeaturesPathFromConfig, resolveJournalPathFromConfig,
+} from './project-paths.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -51,7 +54,6 @@ const FEATURE_JSON_SCHEMA   = path.resolve(__dirname, '../contracts/feature-json
 const VISION_STATE_SCHEMA   = path.resolve(__dirname, '../contracts/vision-state.schema.json');
 const ROADMAP_ROW_SCHEMA    = path.resolve(__dirname, '../contracts/roadmap-row.schema.json');
 
-const DEFAULT_PATHS = { docs: 'docs', features: 'docs/features', journal: 'docs/journal' };
 
 const TERMINAL_STATUSES = new Set(['KILLED', 'SUPERSEDED']);
 const VALID_STATUSES = new Set(['PLANNED', 'IN_PROGRESS', 'PARTIAL', 'COMPLETE', 'SUPERSEDED', 'PARKED', 'BLOCKED', 'KILLED']);
@@ -109,13 +111,14 @@ function readProjectConfig(cwd) {
 }
 
 function resolveProjectPaths(cwd) {
-  const cfg = readProjectConfig(cwd);
-  const paths = (cfg && cfg.paths) || DEFAULT_PATHS;
+  const cfg = readProjectConfig(cwd) || {};
+  // Artifact paths may be relocated outside cwd (COMP-PATHS-EXTERNAL); resolve
+  // through the shared resolver. vision-state + changelog stay at the root.
   return {
-    roadmap: path.join(cwd, 'ROADMAP.md'),
+    roadmap: resolveRoadmapPathFromConfig(cwd, cfg),
     visionState: path.join(cwd, '.compose', 'data', 'vision-state.json'),
-    features: path.join(cwd, paths.features || DEFAULT_PATHS.features),
-    journal: path.join(cwd, paths.journal || DEFAULT_PATHS.journal),
+    features: resolveFeaturesPathFromConfig(cwd, cfg),
+    journal: resolveJournalPathFromConfig(cwd, cfg),
     changelog: path.join(cwd, 'CHANGELOG.md'),
   };
 }
@@ -570,7 +573,11 @@ function runArtifactLinkChecks(fctx, ctx, findings) {
     // PLANNED / SUPERSEDED / KILLED / PARKED — no finding (expected baseline)
   }
   // MISSING_COMPLETION_REPORT (warning, COMPLETE)
-  if (status === 'COMPLETE' && !folder.files.has('report.md')) {
+  // COMP-BUILD-QUICK-1: the quick lifecycle (compose build --quick) omits the
+  // report phase by design and stamps built_via:'build-quick' on feature.json at
+  // ship. Exempt those features — a missing report.md is expected, not debt.
+  if (status === 'COMPLETE' && !folder.files.has('report.md') &&
+      featureJson?.built_via !== 'build-quick') {
     findings.push(finding('warning', 'MISSING_COMPLETION_REPORT', code,
       `Feature is COMPLETE but report.md is missing (current writers do not enforce this; warning only)`));
   }
@@ -1125,6 +1132,18 @@ export async function validateProject(cwd, options = {}) {
   const ctx = loadValidationContext(cwd, options);
   const findings = [];
 
+  // COMP-PATHS-EXTERNAL: a relocated artifact path may resolve into a parent
+  // that does not exist (e.g. the external docs repo isn't checked out). A
+  // not-yet-created leaf dir is fine — writers mkdir it — but an unreachable
+  // PARENT is a configuration error worth surfacing with the resolved path.
+  for (const [key, p] of [['features', ctx.paths.features], ['roadmap', ctx.paths.roadmap]]) {
+    const isExternal = path.relative(cwd, p).startsWith('..');
+    if (isExternal && !fs.existsSync(path.dirname(p))) {
+      findings.push(finding('error', 'CONFIGURED_PATH_UNREACHABLE', null,
+        `configured ${key} path parent does not exist: ${path.dirname(p)} (resolved ${key} = ${p})`));
+    }
+  }
+
   const allCodes = new Set([
     ...ctx.roadmapByCode.keys(),
     ...ctx.visionByCode.keys(),
@@ -1146,9 +1165,7 @@ export async function validateProject(cwd, options = {}) {
 
   // --- COMP-ROADMAP-RT: roundtrip + hierarchy ---
   if (ctx.featureJsonMode) {
-    const cfg = readProjectConfig(cwd);
-    const featuresDir = (cfg && cfg.paths && cfg.paths.features) || DEFAULT_PATHS.features;
-    const features = listFeatures(cwd, featuresDir);
+    const features = listFeatures(cwd, ctx.paths.features);
     const roadmapText = fs.existsSync(ctx.paths.roadmap)
       ? fs.readFileSync(ctx.paths.roadmap, 'utf8')
       : '';

package/lib/feature-write-guard.js

@@ -20,6 +20,7 @@ import { fileURLToPath } from 'url';
 import { SchemaValidator } from '../server/schema-validator.js';
 import { FEATURE_CODE_RE_STRICT } from './feature-code.js';
 import { splitRoadmapCells } from './roadmap-parser.js';
+import { resolveFeaturesPath, resolveRoadmapPath } from './project-paths.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const SCHEMA_PATH = resolve(__dirname, '../contracts/feature-json.schema.json');
@@ -77,14 +78,11 @@ export function assertValidLinkShape(feature) {
 }
 
 function resolvePaths(cwd) {
-  let featuresRel = 'docs/features';
-  try {
-    const cfg = JSON.parse(readFileSync(join(cwd, '.compose', 'compose.json'), 'utf-8'));
-    if (cfg?.paths?.features) featuresRel = cfg.paths.features;
-  } catch { /* no config — use defaults (mirrors resolveProjectPaths) */ }
+  // Artifact paths may be relocated outside cwd (COMP-PATHS-EXTERNAL); resolve
+  // through the shared resolver. vision-state stays at the root (D4).
   return {
-    features: join(cwd, featuresRel),
-    roadmap: join(cwd, 'ROADMAP.md'),
+    features: resolveFeaturesPath(cwd),
+    roadmap: resolveRoadmapPath(cwd),
     visionState: join(cwd, '.compose', 'data', 'vision-state.json'),
   };
 }

package/lib/feature-writer.js

@@ -21,7 +21,7 @@ import { resolve, normalize, sep, basename, dirname, join } from 'path';
 
 import { readEvents } from './feature-events.js';
 import { checkOrInsert } from './idempotency.js';
-import { loadFeaturesDir } from './project-paths.js';
+import { loadFeaturesDir, resolveRoadmapPath } from './project-paths.js';
 import { checkRoundtrip } from './roadmap-roundtrip.js';
 import { isNarrativeOwned, narrativeOwnedMessage } from './roadmap-config.js';
 import { knownFeatureCodes, FeatureWriteValidationError } from './feature-write-guard.js';
@@ -238,7 +238,7 @@ function readRoadmapBase(roadmapPath) {
 async function roundtripGuard(cwd, provider, mutate, { force, label }) {
   const current = await provider.listFeatures();
   const projected = mutate(current.map(f => ({ ...f })));
-  const roadmapPath = join(cwd, 'ROADMAP.md');
+  const roadmapPath = resolveRoadmapPath(cwd);
   // Read the existing ROADMAP as the regen base, but only when it's a readable
   // regular file. If the path is missing, a directory, or otherwise unreadable,
   // treat the base as empty: the guard must never mask the downstream
@@ -728,7 +728,7 @@ export async function setRoadmapRowStatus(cwd, args) {
     throw new Error(`feature-writer: invalid status "${args.status}"`);
   }
   return maybeIdempotent({ ...args, cwd }, async () => {
-    const roadmapPath = join(cwd, 'ROADMAP.md');
+    const roadmapPath = resolveRoadmapPath(cwd);
     let text;
     try { text = readFileSync(roadmapPath, 'utf-8'); }
     catch { return { code: args.code, changed: false }; }

package/lib/followup-writer.js

@@ -28,7 +28,7 @@ import { writeRoadmap } from './roadmap-gen.js';
 import { appendEvent } from './feature-events.js';
 import { checkOrInsert } from './idempotency.js';
 import { FEATURE_CODE_RE_STRICT } from './feature-code.js';
-import { loadFeaturesDir } from './project-paths.js';
+import { loadFeaturesDir, resolveRoadmapPath } from './project-paths.js';
 
 const TERMINAL_STATUSES = new Set(['KILLED', 'SUPERSEDED']);
 const VALID_STATUSES = new Set([
@@ -509,7 +509,7 @@ async function orchestrate({ cwd, parent_code, parent, args, phase, status, requ
       parent_code,
       phase: created?.phase ?? phase,
       position: created?.position,
-      roadmap_path: resolve(cwd, 'ROADMAP.md'),
+      roadmap_path: resolveRoadmapPath(cwd),
       scaffolded: scaffolded ?? { created: [], skipped: ['design.md'] },
       link: { kind: 'surfaced_by', from_code: allocated_code, to_code: parent_code },
     };

package/lib/get-roadmap.js

@@ -12,11 +12,11 @@
  *   - Row parsing reuses parseRoadmap — no second hand-rolled regex.
  */
 import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
 
 import { generateRoadmap } from './roadmap-gen.js';
 import { isNarrativeOwned } from './roadmap-config.js';
 import { parseRoadmap, parseStatusToken } from './roadmap-parser.js';
+import { resolveRoadmapPath } from './project-paths.js';
 
 // Whole `**Last updated:** <date>` line — date-only and per-day, so it is
 // stripped (not literal-matched) before drift comparison.
@@ -56,7 +56,7 @@ function stripVolatile(text) {
 export function getRoadmap(root, opts = {}) {
   const { status, phase, format = 'summary', check_drift = true, limit } = opts ?? {};
 
-  const roadmapPath = join(root, 'ROADMAP.md');
+  const roadmapPath = resolveRoadmapPath(root);
   const onDisk = existsSync(roadmapPath) ? readFileSync(roadmapPath, 'utf-8') : '';
 
   // Branch on narrative ownership ourselves: read the file directly for narrative

package/lib/gsd.js

@@ -33,6 +33,7 @@ import { writeGsdState, readGsdState, gsdStatePath, pidAlive, clearGsdHaltArtifa
 import { generateGsdMilestoneReport } from './gsd-milestone-report.js';
 import { readHeadlessConfig } from './gsd-headless-config.js';
 import { appendGsdEvent, clearGsdEvents } from './gsd-events.js';
+import { resolveFeaturesPath } from './project-paths.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = resolve(__dirname, '..');
@@ -62,7 +63,7 @@ export async function runGsd(featureCode, opts = {}) {
   }
 
   // 1. Validate preconditions: blueprint exists + Boundary Map ok
-  const blueprintPath = join(cwd, 'docs', 'features', featureCode, 'blueprint.md');
+  const blueprintPath = join(resolveFeaturesPath(cwd), featureCode, 'blueprint.md');
   if (!existsSync(blueprintPath)) {
     throw new Error(
       `runGsd: blueprint missing at ${blueprintPath}. ` +