@smartmemory/compose 0.1.34-beta → 0.1.36-beta

package/lib/changelog-writer.js

@@ -20,14 +20,19 @@
  * CLI, or future REST routes.
  */
 
-import {
-  readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, renameSync,
-} from 'node:fs';
-import { join, dirname } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 
-import { appendEvent, normalizeSince } from './feature-events.js';
+import { normalizeSince } from './feature-events.js';
 import { checkOrInsert } from './idempotency.js';
 
+// providerFor is imported lazily to avoid the load-time cycle:
+// factory.js → local-provider.js → changelog-writer.js
+async function getProvider(cwd) {
+  const { providerFor } = await import('./tracker/factory.js');
+  return providerFor(cwd);
+}
+
 // ---------------------------------------------------------------------------
 // Validation helpers
 // ---------------------------------------------------------------------------
@@ -304,9 +309,13 @@ function readChangelogText(cwd) {
   return readFileSync(p, 'utf-8');
 }
 
-function safeAppendEvent(cwd, event) {
+// Routes through provider.appendEvent so GitHubProvider can post
+// <!--compose-event--> comments. LocalFileProvider delegates to
+// feature-events.js#appendEvent producing byte-identical output.
+async function safeAppendEvent(cwd, event) {
   try {
-    appendEvent(cwd, event);
+    const provider = await getProvider(cwd);
+    await provider.appendEvent(event.code, event);
   } catch (err) {
     // eslint-disable-next-line no-console
     console.warn(`[changelog-writer] audit append failed for ${event.tool} ${event.code ?? ''}: ${err.message}`);
@@ -320,17 +329,86 @@ function maybeIdempotent(args, fn) {
   return Promise.resolve().then(fn);
 }
 
-function atomicWrite(cwd, content) {
-  const p = changelogPath(cwd);
-  const tmp = p + '.tmp';
-  mkdirSync(dirname(p), { recursive: true });
-  try {
-    writeFileSync(tmp, content);
-    renameSync(tmp, p);
-  } catch (err) {
-    try { if (existsSync(tmp)) unlinkSync(tmp); } catch { /* ignore */ }
-    throw err;
+/**
+ * spliceChangelog(currentText, entry) — pure string-in / string-out transform.
+ *
+ * Parses `currentText`, applies the mutation described by `entry` (same shape
+ * as the `args` to addChangelogEntry), and returns the new file content.
+ *
+ * Exported so future providers (e.g. GitHubProvider) can fetch a remote blob,
+ * pass it here, then PUT the result back — without touching the local FS.
+ *
+ * Throws formatError if the file exists but lacks the `# Changelog` header.
+ * Returns { content, insertedAtLine, surface, action } — callers write content.
+ */
+export function spliceChangelog(currentText, entry) {
+  const text = currentText;
+  if (text.length > 0 && !H1_RE.test(text.split('\n')[0] ?? '')) {
+    throw formatError('first line must be "# Changelog" (line 1)');
+  }
+
+  const parsed = parseChangelog(text);
+
+  // Find existing entry across all matching surfaces.
+  const matchingSurfaces = parsed.surfaces.filter(s => s.label === entry.date_or_version);
+  let existingSurface = null;
+  let existingEntry = null;
+  for (const s of matchingSurfaces) {
+    const e = s.entries.find(en => en.code === entry.code);
+    if (e) { existingSurface = s; existingEntry = e; break; }
+  }
+
+  const rendered = renderEntry({
+    code: entry.code,
+    summary: entry.summary,
+    body: entry.body,
+    sections: entry.sections,
+  });
+
+  let action;
+  let chosenSurfaceLabel = entry.date_or_version;
+  let chosenSurfaceStartLine = -1;
+
+  if (existingEntry && !entry.force) {
+    // Storage-level idempotent no-op — caller decides what to do with this.
+    return {
+      content: null,
+      insertedAtLine: existingEntry.startLine,
+      surface: existingSurface.label,
+      idempotent: true,
+    };
   }
+
+  if (existingEntry && entry.force) {
+    action = { kind: 'replace', entry: existingEntry, code: entry.code };
+    chosenSurfaceLabel = existingSurface.label;
+    chosenSurfaceStartLine = existingSurface.startLine;
+  } else if (matchingSurfaces.length > 0) {
+    const surface = matchingSurfaces[0];
+    action = { kind: 'append-to-surface', surface, code: entry.code };
+    chosenSurfaceLabel = surface.label;
+    chosenSurfaceStartLine = surface.startLine;
+  } else if (text.length === 0) {
+    action = { kind: 'new-file', code: entry.code };
+    chosenSurfaceStartLine = 3;
+  } else {
+    action = { kind: 'new-surface', code: entry.code };
+  }
+
+  const { content, insertedAtLine } = buildNextContent(text, parsed, action, rendered, entry.date_or_version);
+
+  // For new-surface, recompute chosenSurfaceStartLine from output.
+  if (action.kind === 'new-surface' || action.kind === 'new-file') {
+    const outLines = content.split('\n');
+    for (let i = 0; i < outLines.length; i++) {
+      if (outLines[i] === `## ${entry.date_or_version}`) {
+        chosenSurfaceStartLine = i + 1;
+        break;
+      }
+    }
+  }
+
+  return { content, insertedAtLine, surface: chosenSurfaceLabel, idempotent: false, action, chosenSurfaceStartLine };
 }
 
 /**
@@ -507,91 +585,41 @@ export async function addChangelogEntry(cwd, args) {
   validateSummary(args.summary);
   validateSections(args.sections);
 
-  return maybeIdempotent({ ...args, cwd }, () => {
-    const text = readChangelogText(cwd);
-    if (text.length > 0 && !H1_RE.test(text.split('\n')[0] ?? '')) {
-      throw formatError('first line must be "# Changelog" (line 1)');
-    }
+  return maybeIdempotent({ ...args, cwd }, async () => {
+    // Route through provider low-level primitives (getChangelog / putChangelog).
+    // Do NOT call provider.appendChangelog — that's LocalFileProvider→addChangelogEntry = recursion.
+    const provider = await getProvider(cwd);
+    const text = await provider.getChangelog();
 
-    const parsed = parseChangelog(text);
-
-    // Find existing entry across all matching surfaces.
-    const matchingSurfaces = parsed.surfaces.filter(s => s.label === args.date_or_version);
-    let existingSurface = null;
-    let existingEntry = null;
-    for (const s of matchingSurfaces) {
-      const e = s.entries.find(en => en.code === args.code);
-      if (e) { existingSurface = s; existingEntry = e; break; }
-    }
+    const spliced = spliceChangelog(text, args);
 
-    const rendered = renderEntry({
-      code: args.code,
-      summary: args.summary,
-      body: args.body,
-      sections: args.sections,
-    });
-
-    let action;
-    let chosenSurfaceLabel = args.date_or_version;
-    let chosenSurfaceStartLine = -1;
-
-    if (existingEntry && !args.force) {
+    if (spliced.idempotent) {
       // Storage-level idempotent no-op: no file write, no audit event
       // (Decision 2 of design). Caller-supplied idempotency_key replays are
       // handled separately by the maybeIdempotent wrapper above.
       return {
-        inserted_at: existingEntry.startLine,
+        inserted_at: spliced.insertedAtLine,
         idempotent: true,
-        surface: existingSurface.label,
+        surface: spliced.surface,
       };
     }
 
-    if (existingEntry && args.force) {
-      action = { kind: 'replace', entry: existingEntry, code: args.code };
-      chosenSurfaceLabel = existingSurface.label;
-      chosenSurfaceStartLine = existingSurface.startLine;
-    } else if (matchingSurfaces.length > 0) {
-      // No existing entry; insert into first (topmost) matching surface.
-      const surface = matchingSurfaces[0];
-      action = { kind: 'append-to-surface', surface, code: args.code };
-      chosenSurfaceLabel = surface.label;
-      chosenSurfaceStartLine = surface.startLine;
-    } else if (text.length === 0) {
-      action = { kind: 'new-file', code: args.code };
-      chosenSurfaceStartLine = 3;  // line of new surface heading after H1 + blank
-    } else {
-      action = { kind: 'new-surface', code: args.code };
-    }
-
-    const { content, insertedAtLine } = buildNextContent(text, parsed, action, rendered, args.date_or_version);
-
-    // For new-surface, recompute chosenSurfaceStartLine from output.
-    if (action.kind === 'new-surface' || action.kind === 'new-file') {
-      const outLines = content.split('\n');
-      for (let i = 0; i < outLines.length; i++) {
-        if (outLines[i] === `## ${args.date_or_version}`) {
-          chosenSurfaceStartLine = i + 1;
-          break;
-        }
-      }
-    }
-
-    atomicWrite(cwd, content);
+    await provider.putChangelog(spliced.content);
 
     const event = {
       tool: 'add_changelog_entry',
       code: args.code,
-      surface_label: chosenSurfaceLabel,
-      surface_start_line: chosenSurfaceStartLine,
+      surface_label: spliced.surface,
+      surface_start_line: spliced.chosenSurfaceStartLine,
     };
     if (args.idempotency_key) event.idempotency_key = args.idempotency_key;
-    if (action.kind === 'replace') event.force = true;
-    safeAppendEvent(cwd, event);
+    if (spliced.action?.kind === 'replace') event.force = true;
+    await safeAppendEvent(cwd, event);
 
     return {
-      inserted_at: insertedAtLine,
+      inserted_at: spliced.insertedAtLine,
       idempotent: false,
-      surface: chosenSurfaceLabel,
+      surface: spliced.surface,
     };
   });
 }

package/lib/completion-writer.js

@@ -24,12 +24,19 @@
 import { mkdirSync, rmSync, statSync } from 'fs';
 import { join, dirname, posix } from 'path';
 
-import { readFeature, updateFeature, listFeatures } from './feature-json.js';
+import { readFeature, listFeatures } from './feature-json.js';
 import { loadFeaturesDir } from './project-paths.js';
-import { appendEvent, normalizeSince } from './feature-events.js';
+import { normalizeSince } from './feature-events.js';
 import { checkOrInsert } from './idempotency.js';
 import { FEATURE_CODE_RE_STRICT as FEATURE_CODE_RE } from './feature-code.js';
 
+// providerFor is imported lazily to avoid the load-time cycle:
+// factory.js → local-provider.js → completion-writer.js
+async function getProvider(cwd) {
+  const { providerFor } = await import('./tracker/factory.js');
+  return providerFor(cwd);
+}
+
 // ---------------------------------------------------------------------------
 // Constants + regexes
 // ---------------------------------------------------------------------------
@@ -206,11 +213,17 @@ function maybeIdempotent(args, fn) {
 // ---------------------------------------------------------------------------
 // safeAppendEvent — best-effort; failed append must NOT roll back a committed
 // mutation (per sibling-writer convention).
+//
+// Routes through provider.appendEvent so GitHubProvider can post
+// <!--compose-event--> comments. LocalFileProvider delegates to
+// feature-events.js#appendEvent producing byte-identical output.
 // ---------------------------------------------------------------------------
 
-function safeAppendEvent(cwd, event) {
+async function safeAppendEvent(cwd, event) {
   try {
-    appendEvent(cwd, event);
+    const { providerFor } = await import('./tracker/factory.js');
+    const provider = await providerFor(cwd);
+    await provider.appendEvent(event.code, event);
   } catch (err) {
     // eslint-disable-next-line no-console
     console.warn(
@@ -252,14 +265,16 @@ export async function recordCompletion(cwd, args) {
   // 3. Compute completion_id
   const completion_id = `${feature_code}:${commit_sha}`;
 
-  const featuresDir = loadFeaturesDir(cwd);
   // 4. Wrap in maybeIdempotent for caller-key path
   return maybeIdempotent({ ...args, cwd }, async () => {
+    // Acquire provider once per operation (resolves factory, no per-call overhead)
+    const provider = await getProvider(cwd);
+
     // 5a. Acquire per-feature advisory lock (Decision 10)
     const release = await acquireFeatureLock(cwd, feature_code);
     try {
-      // 5b. Read feature
-      const feature = readFeature(cwd, feature_code, featuresDir);
+      // 5b. Read feature via provider (low-level primitive — no recursion risk)
+      const feature = await provider.getFeature(feature_code);
       if (!feature) throw notFoundError(feature_code);
 
       // 5c. Snapshot completions array
@@ -303,7 +318,9 @@ export async function recordCompletion(cwd, args) {
       }
 
       // 5h. Persist completion record BEFORE status flip (so flip failure doesn't lose the record)
-      updateFeature(cwd, feature_code, { completions }, featuresDir);
+      // 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 });
 
       // 5i. Status flip (default on)
       const set_status = args.set_status !== false;
@@ -357,7 +374,7 @@ export async function recordCompletion(cwd, args) {
       };
       if (args.force) auditEvent.force = args.force;
       if (args.idempotency_key) auditEvent.idempotency_key = args.idempotency_key;
-      safeAppendEvent(cwd, auditEvent);
+      await safeAppendEvent(cwd, auditEvent);
 
       // 5l. Return
       return {

package/lib/feature-writer.js

@@ -19,13 +19,18 @@
 import { existsSync, realpathSync, statSync } from 'fs';
 import { resolve, normalize, sep, basename, dirname } from 'path';
 
-import { readFeature, writeFeature, listFeatures, updateFeature } from './feature-json.js';
-const _listFeatures = listFeatures;
-import { writeRoadmap } from './roadmap-gen.js';
-import { appendEvent, readEvents } from './feature-events.js';
+import { readEvents } from './feature-events.js';
 import { checkOrInsert } from './idempotency.js';
 import { loadFeaturesDir } from './project-paths.js';
 
+// providerFor is imported lazily (inside each function) to break the
+// module-load-time cycle: factory.js → local-provider.js → feature-writer.js.
+// Dynamic import resolves at call time, after all modules have loaded.
+async function getProvider(cwd) {
+  const { providerFor } = await import('./tracker/factory.js');
+  return providerFor(cwd);
+}
+
 // ---------------------------------------------------------------------------
 // Status / transition policy
 // ---------------------------------------------------------------------------
@@ -99,9 +104,10 @@ export async function addRoadmapEntry(cwd, args) {
     throw new Error(`feature-writer: invalid status "${status}"`);
   }
 
-  const featuresDir = loadFeaturesDir(cwd);
-  return maybeIdempotent({ ...args, cwd }, () => {
-    const existing = readFeature(cwd, args.code, featuresDir);
+  return maybeIdempotent({ ...args, cwd }, async () => {
+    const provider = await getProvider(cwd);
+
+    const existing = await provider.getFeature(args.code);
     if (existing) {
       throw new Error(`feature-writer: feature "${args.code}" already exists`);
     }
@@ -118,14 +124,18 @@ export async function addRoadmapEntry(cwd, args) {
     if (args.complexity) feature.complexity = args.complexity;
     feature.position = args.position !== undefined
       ? args.position
-      : nextPositionInPhase(cwd, args.phase, featuresDir);
+      : await nextPositionInPhase(provider, args.phase);
     if (args.parent) feature.parent = args.parent;
     if (args.tags && args.tags.length) feature.tags = args.tags;
 
-    writeFeature(cwd, feature, featuresDir);
+    // Use createFeature (not putFeature) for the initial write of a brand-new
+    // feature: the not-found check above has already confirmed it doesn't exist,
+    // and createFeature carries the correct semantics for remote providers
+    // (e.g. GitHubProvider creates a new issue rather than patching an existing one).
+    await provider.createFeature(args.code, feature);
     let roadmapPath;
     try {
-      roadmapPath = writeRoadmap(cwd, { featuresDir });
+      roadmapPath = await provider.renderRoadmap();
     } catch (err) {
       throw partialWriteError(
         `add_roadmap_entry: feature.json for "${args.code}" was written but ROADMAP.md regeneration failed. ` +
@@ -134,7 +144,7 @@ export async function addRoadmapEntry(cwd, args) {
       );
     }
 
-    safeAppendEvent(cwd, {
+    await safeAppendEvent(cwd, {
       tool: 'add_roadmap_entry',
       code: args.code,
       to: status,
@@ -153,8 +163,9 @@ export async function addRoadmapEntry(cwd, args) {
 
 // Default position for a new feature: max existing position in the same
 // phase, plus 1. Falls back to 1 when the phase is empty.
-function nextPositionInPhase(cwd, phase, featuresDir) {
-  const peers = _listFeatures(cwd, featuresDir).filter(f => f.phase === phase);
+async function nextPositionInPhase(provider, phase) {
+  const all = await provider.listFeatures();
+  const peers = all.filter(f => f.phase === phase);
   if (peers.length === 0) return 1;
   const maxPos = peers.reduce((m, f) => {
     const p = typeof f.position === 'number' ? f.position : 0;
@@ -178,9 +189,14 @@ function partialWriteError(message, cause) {
 // Audit-log writes are best-effort: a failed append must NOT roll back a
 // committed mutation (per design Decision 2 and docs/mcp.md). Log a warning
 // and continue.
-function safeAppendEvent(cwd, event) {
+//
+// Routes through provider.appendEvent so GitHubProvider can post
+// <!--compose-event--> comments + mirror Projects v2. LocalFileProvider
+// delegates to feature-events.js#appendEvent producing byte-identical output.
+async function safeAppendEvent(cwd, event) {
   try {
-    appendEvent(cwd, event);
+    const provider = await getProvider(cwd);
+    await provider.appendEvent(event.code, event);
   } catch (err) {
     // eslint-disable-next-line no-console
     console.warn(`[feature-writer] audit append failed for ${event.tool} ${event.code ?? ''}: ${err.message}`);
@@ -207,9 +223,10 @@ export async function setFeatureStatus(cwd, args) {
     throw new Error(`feature-writer: invalid status "${args.status}" — must be one of ${[...STATUSES].join(', ')}`);
   }
 
-  const featuresDir = loadFeaturesDir(cwd);
-  return maybeIdempotent({ ...args, cwd }, () => {
-    const feature = readFeature(cwd, args.code, featuresDir);
+  return maybeIdempotent({ ...args, cwd }, async () => {
+    const provider = await getProvider(cwd);
+
+    const feature = await provider.getFeature(args.code);
     if (!feature) {
       throw new Error(`feature-writer: feature "${args.code}" not found`);
     }
@@ -230,11 +247,14 @@ export async function setFeatureStatus(cwd, args) {
       );
     }
 
-    const updates = { status: to };
-    if (args.commit_sha) updates.commit_sha = args.commit_sha;
-    updateFeature(cwd, args.code, updates, featuresDir);
+    // Build the updated feature object. We use persistFeatureRaw (not putFeature)
+    // because putFeature rejects status deltas by contract. Transition policy
+    // enforcement has already happened above — this is the raw persistence step.
+    const updated = { ...feature, status: to };
+    if (args.commit_sha) updated.commit_sha = args.commit_sha;
+    await provider.persistFeatureRaw(args.code, updated);
     try {
-      writeRoadmap(cwd, { featuresDir });
+      await provider.renderRoadmap();
     } catch (err) {
       throw partialWriteError(
         `set_feature_status: feature.json for "${args.code}" was updated (${from} → ${to}) but ROADMAP.md regeneration failed. ` +
@@ -253,7 +273,7 @@ export async function setFeatureStatus(cwd, args) {
     if (args.reason) event.reason = args.reason;
     if (args.commit_sha) event.commit_sha = args.commit_sha;
     if (args.force && !allowed.includes(to)) event.forced = true;
-    safeAppendEvent(cwd, event);
+    await safeAppendEvent(cwd, event);
 
     return { code: args.code, from, to, ts: new Date().toISOString() };
   });
@@ -382,8 +402,10 @@ export async function linkArtifact(cwd, args) {
   const featuresDir = loadFeaturesDir(cwd);
   rejectCanonicalArtifact(featuresDir, args.feature_code, normalizedPath);
 
-  return maybeIdempotent({ ...args, cwd }, () => {
-    const feature = readFeature(cwd, args.feature_code, featuresDir);
+  return maybeIdempotent({ ...args, cwd }, async () => {
+    const provider = await getProvider(cwd);
+
+    const feature = await provider.getFeature(args.feature_code);
     if (!feature) {
       throw new Error(`feature-writer: feature "${args.feature_code}" not found`);
     }
@@ -408,9 +430,9 @@ export async function linkArtifact(cwd, args) {
     if (matchIdx !== -1) artifacts[matchIdx] = entry;
     else artifacts.push(entry);
 
-    updateFeature(cwd, args.feature_code, { artifacts }, featuresDir);
+    await provider.putFeature(args.feature_code, { ...feature, artifacts });
 
-    safeAppendEvent(cwd, {
+    await safeAppendEvent(cwd, {
       tool: 'link_artifact',
       code: args.feature_code,
       artifact_type: args.artifact_type,
@@ -452,9 +474,10 @@ export async function linkFeatures(cwd, args) {
     );
   }
 
-  const featuresDir = loadFeaturesDir(cwd);
-  return maybeIdempotent({ ...args, cwd }, () => {
-    const feature = readFeature(cwd, args.from_code, featuresDir);
+  return maybeIdempotent({ ...args, cwd }, async () => {
+    const provider = await getProvider(cwd);
+
+    const feature = await provider.getFeature(args.from_code);
     if (!feature) {
       throw new Error(`feature-writer: feature "${args.from_code}" not found`);
     }
@@ -474,9 +497,9 @@ export async function linkFeatures(cwd, args) {
     if (matchIdx !== -1) links[matchIdx] = entry;
     else links.push(entry);
 
-    updateFeature(cwd, args.from_code, { links }, featuresDir);
+    await provider.putFeature(args.from_code, { ...feature, links });
 
-    safeAppendEvent(cwd, {
+    await safeAppendEvent(cwd, {
       tool: 'link_features',
       code: args.from_code,
       to_code: args.to_code,
@@ -508,8 +531,8 @@ export async function linkFeatures(cwd, args) {
  */
 export async function getFeatureArtifacts(cwd, args) {
   validateCode(args.feature_code);
-  const featuresDir = loadFeaturesDir(cwd);
-  const feature = readFeature(cwd, args.feature_code, featuresDir);
+  const provider = await getProvider(cwd);
+  const feature = await provider.getFeature(args.feature_code);
   if (!feature) {
     throw new Error(`feature-writer: feature "${args.feature_code}" not found`);
   }
@@ -525,6 +548,7 @@ export async function getFeatureArtifacts(cwd, args) {
   let canonical = null;
   try {
     const { ArtifactManager } = await import('../server/artifact-manager.js');
+    const featuresDir = loadFeaturesDir(cwd);
     const featureRoot = resolve(realCwd, featuresDir);
     if (existsSync(featureRoot)) {
       const manager = new ArtifactManager(featureRoot);
@@ -550,7 +574,7 @@ export async function getFeatureArtifacts(cwd, args) {
  * @param {'outgoing'|'incoming'|'both'} [args.direction='both']
  * @param {string} [args.kind]
  */
-export function getFeatureLinks(cwd, args) {
+export async function getFeatureLinks(cwd, args) {
   validateCode(args.feature_code);
   const direction = args.direction ?? 'both';
   if (!['outgoing', 'incoming', 'both'].includes(direction)) {
@@ -560,11 +584,11 @@ export function getFeatureLinks(cwd, args) {
   }
   const kind = args.kind;
 
-  const featuresDir = loadFeaturesDir(cwd);
+  const provider = await getProvider(cwd);
   const out = { feature_code: args.feature_code };
 
   if (direction === 'outgoing' || direction === 'both') {
-    const feature = readFeature(cwd, args.feature_code, featuresDir);
+    const feature = await provider.getFeature(args.feature_code);
     if (!feature) {
       throw new Error(`feature-writer: feature "${args.feature_code}" not found`);
     }
@@ -574,7 +598,7 @@ export function getFeatureLinks(cwd, args) {
   }
 
   if (direction === 'incoming' || direction === 'both') {
-    const all = _listFeatures(cwd, featuresDir);
+    const all = await provider.listFeatures();
     const incoming = [];
     for (const f of all) {
       if (f.code === args.feature_code) continue;

package/lib/roadmap-gen.js

@@ -46,22 +46,23 @@ function phaseStatus(features) {
 }
 
 /**
- * Generate ROADMAP.md content from feature.json files.
+ * Pure transform: merge a features array into a base ROADMAP.md text string
+ * and return the resulting text. No filesystem access.
  *
- * @param {string} cwd - Project root
+ * @param {string} baseText - The existing ROADMAP.md content (empty string for a fresh file)
+ * @param {Array} features - Feature objects (as returned by listFeatures)
  * @param {object} [opts]
- * @param {string} [opts.featuresDir] - Relative path to features dir
- * @param {string} [opts.projectName] - Project name for header
- * @param {string} [opts.projectDescription] - Project description for header
- * @returns {string} - Generated ROADMAP.md content
+ * @param {string} [opts.projectName] - Project name for default preamble
+ * @param {string} [opts.projectDescription] - Project description for default preamble
+ * @param {string} [opts.cwd] - Used only for drift emission (optional; defaults to '')
+ * @param {string} [opts.featuresDir] - Passed through to buildKeyDocs (optional)
+ * @returns {string} - Merged ROADMAP.md content
  */
-export function generateRoadmap(cwd, opts = {}) {
-  const featuresDir = opts.featuresDir ?? loadFeaturesDir(cwd);
-  const features = listFeatures(cwd, featuresDir);
+export function generateRoadmapFromBase(baseText, features, opts = {}) {
+  const cwd = opts.cwd ?? '';
+  const featuresDir = opts.featuresDir ?? 'docs/features';
 
-  // Read existing ROADMAP.md once: preamble + curated content for splice-back.
-  const roadmapPath = join(cwd, 'ROADMAP.md');
-  const existingText = existsSync(roadmapPath) ? readFileSync(roadmapPath, 'utf-8') : '';
+  const existingText = baseText ?? '';
   const preamble = readPreamble(cwd, opts, existingText);
   const overrides = readPhaseOverrides(existingText);
   const anonRows = readAnonymousRows(existingText);
@@ -141,7 +142,7 @@ export function generateRoadmap(cwd, opts = {}) {
     if (override) {
       const overrideToken = parseStatusToken(override);
       if (overrideToken && overrideToken !== rollupStatus) {
-        emitDrift(cwd, { phaseId: phase, override, computed: rollupStatus });
+        if (cwd) emitDrift(cwd, { phaseId: phase, override, computed: rollupStatus });
       }
       // Override always wins. We can't reliably distinguish curated overrides
       // from previously-auto-generated rollups without explicit marking, so
@@ -189,6 +190,27 @@ export function generateRoadmap(cwd, opts = {}) {
   return sections.join('\n\n---\n\n') + '\n';
 }
 
+/**
+ * Generate ROADMAP.md content from feature.json files.
+ *
+ * @param {string} cwd - Project root
+ * @param {object} [opts]
+ * @param {string} [opts.featuresDir] - Relative path to features dir
+ * @param {string} [opts.projectName] - Project name for header
+ * @param {string} [opts.projectDescription] - Project description for header
+ * @returns {string} - Generated ROADMAP.md content
+ */
+export function generateRoadmap(cwd, opts = {}) {
+  const featuresDir = opts.featuresDir ?? loadFeaturesDir(cwd);
+  const features = listFeatures(cwd, featuresDir);
+
+  // Read existing ROADMAP.md once: preamble + curated content for splice-back.
+  const roadmapPath = join(cwd, 'ROADMAP.md');
+  const existingText = existsSync(roadmapPath) ? readFileSync(roadmapPath, 'utf-8') : '';
+
+  return generateRoadmapFromBase(existingText, features, { ...opts, cwd, featuresDir });
+}
+
 /**
  * Read the preamble (everything before the first ## Phase/Feature section)
  * from an existing ROADMAP.md, or generate a default one.
@@ -206,7 +228,12 @@ function readPreamble(cwd, opts, existingText) {
         if (firstHeadingIdx === -1 || idx < firstHeadingIdx) firstHeadingIdx = idx;
       }
     }
-    if (firstHeadingIdx > 0) {
+    if (firstHeadingIdx === -1) {
+      // No phase headings found — the entire file is a preamble (e.g. remote file
+      // contains only a header/intro with no generated sections yet). Preserve it.
+      const stripped = existingText.trimEnd().replace(/\n---\s*$/, '').trimEnd();
+      if (stripped.length > 0) return stripped;
+    } else if (firstHeadingIdx > 0) {
       // Walk back over a possible `---\n\n` separator immediately before the heading
       // so it doesn't get duplicated against the join("\n\n---\n\n") below.
       let cutIdx = firstHeadingIdx;