@smartmemory/compose 0.2.49-beta → 0.2.50-beta

package/lib/build.js

@@ -9,7 +9,7 @@
  */
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, renameSync, mkdtempSync, rmSync, symlinkSync } from 'node:fs';
-import { join, resolve, dirname } from 'node:path';
+import { join, resolve, dirname, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir, tmpdir } from 'node:os';
 import { execSync, execFileSync } from 'node:child_process';
@@ -35,7 +35,7 @@ import { rtkPrefix } from './rtk.js';
 
 import YAML from 'yaml';
 // feature-json direct imports removed — mutations now go through TrackerProvider (T9)
-import { loadFeaturesDir } from './project-paths.js';
+import { loadFeaturesDir, resolveContextPath, resolveRoadmapPath, resolveFeaturesPath } from './project-paths.js';
 
 // Lazy provider accessor — avoids circular import risk (factory → local-provider
 // does NOT import build.js, so a static import is safe, but lazy is used for
@@ -605,10 +605,19 @@ export async function runBuild(featureCode, opts = {}) {
   // `docs/features/<featureCode>/`. Callers must use this (not inline
   // string concatenation) so the bug-mode path stays in sync.
   // COMP-MCP-MIGRATION-2: feature-mode honors paths.features override.
+  // COMP-PATHS-EXTERNAL D7: two representations on purpose.
+  //  - `featuresDir` stays RELATIVE (loadFeaturesDir): it flows into
+  //    context.featuresDir → the MCP-enforcement guard, which matches against
+  //    repo-relative `git status` output. External artifacts live in another
+  //    repo and are out of that guard's scope by construction; making this
+  //    absolute would break the relative match. triage consumers are
+  //    absolute-safe (resolvePathValue) so the relative value is fine there too.
+  //  - `resolveItemDir` resolves the actual FILESYSTEM dir via
+  //    resolveFeaturesPath (absolute — handles absolute/../-escaping config).
   const featuresDir = loadFeaturesDir(cwd);
   const resolveItemDir = (code) => isBugMode
     ? join(cwd, 'docs', 'bugs', code)
-    : join(cwd, featuresDir, code);
+    : join(resolveFeaturesPath(cwd), code);
 
   // COMP-MCP-MIGRATION-1: per-build correlation ID stamped onto every audit
   // row written during this run, so `executeShipStep`'s pre-stage scan can
@@ -663,7 +672,7 @@ export async function runBuild(featureCode, opts = {}) {
   }
   let composeConfig = {};
   try { composeConfig = JSON.parse(readFileSync(configPath, 'utf-8')); } catch { /* use defaults */ }
-  const contextDirPath = join(cwd, composeConfig.paths?.context ?? 'docs/context');
+  const contextDirPath = resolveContextPath(cwd);
 
   // COMP-PAR-MERGE-QUEUE-CONSUMER-RETRY (D5): per-task pre-merge gate is opt-in.
   // Resolve ONCE and thread into startFresh's planInputs only when the capability
@@ -2219,6 +2228,43 @@ export function maybeEmitSectionsAfterPlanGate(stepId, featureDir, opts = {}) {
 // Ship step — runs git commit in-process (not via agent)
 // ---------------------------------------------------------------------------
 
+/**
+ * The git repository toplevel that contains `dir`, or null if `dir` is not
+ * inside any git work tree. Used so ship decides commit ownership per-file by
+ * containing repo, not by assuming the workspace root == the repo
+ * (COMP-PATHS-EXTERNAL D6a).
+ */
+function gitToplevel(dir) {
+  try {
+    return execSync('git rev-parse --show-toplevel', {
+      cwd: dir, encoding: 'utf-8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim() || null;
+  } catch { return null; }
+}
+
+/**
+ * For each owned artifact (ROADMAP, the feature folder) that resolves into a
+ * git repo OTHER than the build's repo, log a one-line "commit it there"
+ * notice. v1 does not auto-commit other repos (that is COMP-PATHS-EXTERNAL-1).
+ * Artifacts in the build's own repo, or in no repo at all, produce no notice.
+ */
+function noticeExternalArtifacts(cwd, featureCode, buildToplevel) {
+  try {
+    const candidates = [
+      ['ROADMAP.md', resolveRoadmapPath(cwd)],
+      ['feature folder', join(resolveFeaturesPath(cwd), featureCode)],
+    ];
+    for (const [label, abs] of candidates) {
+      if (!existsSync(abs)) continue;
+      const top = gitToplevel(dirname(abs));
+      if (top && top !== buildToplevel) {
+        // eslint-disable-next-line no-console
+        console.warn(`[build/ship] 📝 wrote ${label} in ${top} — commit it there (Compose does not auto-commit other repos in v1)`);
+      }
+    }
+  } catch { /* notice is best-effort */ }
+}
+
 /**
  * Execute the ship step: run tests, stage feature files, commit.
  * Returns a PhaseResult-shaped object.
@@ -2240,11 +2286,34 @@ export async function executeShipStep(featureCode, agentCwd, cwd, context, descr
     } catch { /* not a git repo */ }
 
     if (!isGitRepo) {
+      // COMP-PATHS-EXTERNAL D6b: there is no repo to commit into (e.g. a
+      // forge-top-shaped workspace), but the lifecycle must still advance —
+      // record a commit-less completion (null-SHA) so status flips to COMPLETE.
+      // Best-effort: a completion failure must not fail ship.
+      let completionWarning = null;
+      if (featureCode) {
+        try {
+          const { recordCompletion } = await import('./completion-writer.js');
+          await recordCompletion(cwd, {
+            feature_code: featureCode,
+            // commit_sha omitted — non-git workspace, stamped with the null-SHA
+            tests_pass: true,
+            files_changed: [],
+            notes: description.split('\n')[0].slice(0, 72),
+          });
+        } catch (err) {
+          completionWarning = `completion record failed (${err.code || 'UNKNOWN'}): ${err.message}`;
+          // eslint-disable-next-line no-console
+          console.warn(`[build/ship] ${featureCode}: ${completionWarning}`);
+        }
+      }
       return {
         phase: 'ship',
         artifact: 'no-git',
         outcome: 'complete',
-        summary: 'No git repository — commit skipped (non-fatal)',
+        summary: 'No git repository — wrote artifacts, recorded completion (commit skipped)',
+        commit: null,
+        ...(completionWarning ? { completionWarning } : {}),
       };
     }
 
@@ -2316,6 +2385,18 @@ export async function executeShipStep(featureCode, agentCwd, cwd, context, descr
         const dataDir = join(cwd, '.compose', 'data');
         const mode = readEnforcementMode(dataDir);
         if (mode !== 'off') {
+          // COMP-PATHS-EXTERNAL: the pre-stage guard matches repo-relative
+          // `git status`, so relocated canon (an external paths.roadmap /
+          // paths.features) is OUT of its scope — unauthorized edits there are
+          // NOT enforced. Surface that visibly instead of failing silently.
+          // Full external-canon enforcement needs cross-repo dirty detection
+          // (tracked with COMP-PATHS-EXTERNAL-1).
+          for (const [label, abs] of [['paths.roadmap', resolveRoadmapPath(cwd)], ['paths.features', resolveFeaturesPath(cwd)]]) {
+            if (relative(cwd, abs).startsWith('..')) {
+              // eslint-disable-next-line no-console
+              console.warn(`[ship] MCP enforcement (${mode}) does NOT cover external ${label} (${abs}) — edits there are unguarded in v1.`);
+            }
+          }
           const events = readEvents(cwd, { since: context.buildStartedAt });
           const { violations } = scanGuarded({
             dirtyFiles: featureFiles,
@@ -2441,6 +2522,11 @@ export async function executeShipStep(featureCode, agentCwd, cwd, context, descr
       }
     }
 
+    // COMP-PATHS-EXTERNAL D6a: if ROADMAP / the feature folder resolved into a
+    // DIFFERENT git repo, they were written but not committed here — tell the
+    // user to commit them there (v1 does not auto-commit other repos).
+    noticeExternalArtifacts(cwd, featureCode, gitToplevel(agentCwd));
+
     return {
       phase: 'ship',
       artifact: sha ?? '',

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/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
@@ -257,13 +273,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 () => {

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'),
   };
 }
@@ -1125,6 +1128,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 +1161,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}. ` +

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