@smartmemory/compose 0.1.44-beta → 0.2.0

package/lib/feature-validator.js

@@ -34,6 +34,10 @@ import { fileURLToPath } from 'node:url';
 import { FEATURE_CODE_RE_STRICT, validateCode } from './feature-code.js';
 import { parseRoadmap } from './roadmap-parser.js';
 import { listFeatures, readFeature } from './feature-json.js';
+import { loadExternalPrefixes } from './project-paths.js';
+import { checkRoundtrip, LOSSY_LABELS } from './roadmap-roundtrip.js';
+import { isNarrativeOwned } from './roadmap-config.js';
+import { readPhaseOrder, readPhaseBlocks, readPreservedSectionAnchors, readPhaseOverrides } from './roadmap-preservers.js';
 import { parseCitations } from './xref-citation.js';
 import { GitHubApi } from './tracker/github-api.js';
 import { ArtifactManager } from '../server/artifact-manager.js';
@@ -51,6 +55,45 @@ const DEFAULT_PATHS = { docs: 'docs', features: 'docs/features', journal: 'docs/
 const TERMINAL_STATUSES = new Set(['KILLED', 'SUPERSEDED']);
 const VALID_STATUSES = new Set(['PLANNED', 'IN_PROGRESS', 'PARTIAL', 'COMPLETE', 'SUPERSEDED', 'PARKED', 'BLOCKED', 'KILLED']);
 
+// Finding kinds that treat ROADMAP.md as a canonical, machine-comparable source
+// — roundtrip/structure derived from feature.json, folder↔row linkage, and any
+// drift check that compares a parsed ROADMAP row against feature.json OR
+// vision-state. All are false positives in a narrative-owned workspace (#39),
+// where ROADMAP.md is hand-authored prose, not a data source. Findings that do
+// NOT involve the roadmap (e.g. STATUS_MISMATCH_FEATUREJSON_VS_VISION_STATE,
+// CONTRADICTORY_PHASE_CLAIM) are real drift and intentionally NOT listed here.
+const NARRATIVE_SUPPRESSED_KINDS = new Set([
+  'ROUNDTRIP_NOT_FIXED_POINT', 'ROADMAP_LOSSY', 'HIERARCHY_DEPTH_INVALID', 'ORPHAN_PHASE',
+  'ROADMAP_ROW_WITHOUT_FOLDER', 'FOLDER_WITHOUT_ROADMAP_ROW', 'ORPHAN_FOLDER',
+  'STATUS_MISMATCH_ROADMAP_VS_FEATUREJSON', 'STATUS_MISMATCH_ROADMAP_VS_VISION_STATE',
+  'COMPLEXITY_OR_DESCRIPTION_DRIFT',
+  // Hand-authored rows are not typed rows — don't validate them against the
+  // ROADMAP row schema in a narrative-owned workspace (#39).
+  'ROADMAP_ROW_SCHEMA_VIOLATION',
+]);
+
+// Drop roadmap-derived findings on a narrative-owned workspace and record the
+// skip as a single info finding (#39). Applied at every public entry point
+// (validateProject and direct validateFeature) so the CLI/MCP feature scope is
+// as clean as the project scope. No-op unless narrative-owned; returns the
+// findings unchanged when nothing was suppressed so a clean feature stays quiet.
+function applyNarrativeSuppression(findings, ctx) {
+  // Deliberately gated on featureJsonMode: "narrative-owned" means feature.json
+  // is canonical and ROADMAP.md is a hand-authored sidecar. In legacy
+  // roadmap-as-source mode (featureJsonMode=false) feature.json isn't even
+  // loaded and the project roundtrip checks don't run, so the roadmap IS a
+  // primary source — its row-schema/drift findings are real signal there and
+  // must NOT be suppressed. narrative-owned + featureJsonMode=false is a
+  // contradictory config; we honor featureJsonMode.
+  if (!(ctx.featureJsonMode && ctx.narrativeOwned)) return findings;
+  const dropped = findings.filter((f) => NARRATIVE_SUPPRESSED_KINDS.has(f.kind)).length;
+  if (dropped === 0) return findings;
+  const kept = findings.filter((f) => !NARRATIVE_SUPPRESSED_KINDS.has(f.kind));
+  kept.push(finding('info', 'ROADMAP_NARRATIVE_OWNED', undefined,
+    `roadmap.narrative=true — ROADMAP.md is hand-authored; ${dropped} roadmap↔feature.json correspondence finding(s) suppressed`));
+  return kept;
+}
+
 const _validatorCache = {};
 function getValidator(schemaPath) {
   if (!_validatorCache[schemaPath]) _validatorCache[schemaPath] = new SchemaValidator(schemaPath);
@@ -208,9 +251,21 @@ function loadValidationContext(cwd, options = {}) {
     citationRows,
     externalPrefixes: options.externalPrefixes || [],
     featureJsonMode: options.featureJsonMode !== false,
+    // Narrative-owned (#39): ROADMAP.md is hand-authored, so a parsed roadmap row
+    // is NOT a canonical data source. Computed once here and consulted by checks
+    // that would otherwise treat a row as authoritative.
+    narrativeOwned: isNarrativeOwned(cwd),
   };
 }
 
+// Effective status for per-feature checks. feature.json is canonical; the parsed
+// ROADMAP row is only a fallback — and NOT even that on a narrative-owned
+// workspace, where the row is hand-authored prose (#39).
+function effectiveStatus(fctx, ctx) {
+  return normalizeStatus(fctx.featureJson?.status)
+    || (ctx?.narrativeOwned ? null : normalizeStatus(fctx.roadmap?.status));
+}
+
 function loadFeatureContext(cwd, code, ctx) {
   const folder = ctx.foldersByCode.get(code);
   let featureJson = null;
@@ -244,17 +299,20 @@ function finding(severity, kind, code, detail, source) {
 // Per-feature checks
 // ---------------------------------------------------------------------------
 
-function runKilledModeChecks(fctx, findings) {
+function runKilledModeChecks(fctx, findings, narrativeOwned = false) {
   const { code, folder, roadmap, vision, featureJson } = fctx;
   // KILLED_STATUS_NOT_TERMINAL
   const statuses = [];
-  if (roadmap?.status) statuses.push({ src: 'roadmap', val: String(roadmap.status).toUpperCase() });
+  // On a narrative-owned workspace the ROADMAP row is hand-authored, not a
+  // canonical data source, so a non-terminal roadmap status is not real drift
+  // (#39). feature.json / vision-state are still checked.
+  if (!narrativeOwned && roadmap?.status) statuses.push({ src: 'roadmap', val: String(roadmap.status).toUpperCase() });
   if (featureJson?.status) statuses.push({ src: 'feature.json', val: String(featureJson.status).toUpperCase() });
   if (vision?.status) statuses.push({ src: 'vision-state', val: String(vision.status).toUpperCase() });
   for (const s of statuses) {
     if (!TERMINAL_STATUSES.has(s.val)) {
       findings.push(finding('error', 'KILLED_STATUS_NOT_TERMINAL', code,
-        `${s.src} status is ${s.val} but killed.md is present; expected KILLED or SUPERSEDED`));
+        `${s.src} status is ${s.val} but killed.md is present; expected KILLED or SUPERSEDED`, s.src));
     }
   }
   // KILLED_SUCCESSOR_NOT_LINKED
@@ -422,7 +480,7 @@ function runArtifactLinkChecks(fctx, ctx, findings) {
   try { assessment = am.assess(code); } catch { /* fall through */ }
 
   // MISSING_DESIGN_ARTIFACT — error for active work, warning for COMPLETE (legacy may not have design.md).
-  const status = normalizeStatus(featureJson?.status) || normalizeStatus(fctx.roadmap?.status);
+  const status = effectiveStatus(fctx, ctx);
   const ACTIVE_STATUSES = new Set(['IN_PROGRESS', 'PARTIAL', 'BLOCKED']);
   if (status && !folder.files.has('design.md')) {
     if (ACTIVE_STATUSES.has(status)) {
@@ -491,7 +549,7 @@ function runCrossFeatureRefChecks(fctx, ctx, findings) {
   }
   // SUPERSEDED_WITHOUT_LINK — non-killed feature in SUPERSEDED status without a
   // typed `supersedes` link to the successor.
-  const status = normalizeStatus(featureJson?.status) || normalizeStatus(fctx.roadmap?.status);
+  const status = effectiveStatus(fctx, ctx);
   if (status === 'SUPERSEDED' && !fctx.killed) {
     const links = featureJson?.links || [];
     const hasSupersedes = links.some((l) => l.kind === 'supersedes' && l.to_code);
@@ -505,7 +563,7 @@ function runCrossFeatureRefChecks(fctx, ctx, findings) {
 function runCoherenceChecks(fctx, ctx, findings) {
   const { code, featureJson } = fctx;
   // COMPLETION_WITHOUT_CHANGELOG — check at project level, but per-feature too
-  const status = normalizeStatus(featureJson?.status) || normalizeStatus(fctx.roadmap?.status);
+  const status = effectiveStatus(fctx, ctx);
   if (status === 'COMPLETE' || status === 'PARTIAL') {
     let changelog = '';
     try { changelog = fs.readFileSync(ctx.paths.changelog, 'utf8'); } catch {}
@@ -620,8 +678,9 @@ export async function validateFeature(cwd, code, options = {}) {
   const fctx = loadFeatureContext(cwd, code, ctx);
 
   if (fctx.killed) {
-    runKilledModeChecks(fctx, findings);
-    return { scope: 'feature', feature_code: code, validated_at: nowIso(), findings };
+    runKilledModeChecks(fctx, findings, ctx.narrativeOwned);
+    const kf = options._deferNarrative ? findings : applyNarrativeSuppression(findings, ctx);
+    return { scope: 'feature', feature_code: code, validated_at: nowIso(), findings: kf };
   }
 
   runSchemaChecks(fctx, ctx, findings);
@@ -631,7 +690,11 @@ export async function validateFeature(cwd, code, options = {}) {
   runCrossFeatureRefChecks(fctx, ctx, findings);
   runCoherenceChecks(fctx, ctx, findings);
 
-  return { scope: 'feature', feature_code: code, validated_at: nowIso(), findings };
+  // Direct feature-scope calls suppress roadmap-derived findings here; when
+  // invoked by validateProject (_deferNarrative) the project does it once over
+  // the aggregate so the info finding isn't multiplied per feature (#39).
+  const kept = options._deferNarrative ? findings : applyNarrativeSuppression(findings, ctx);
+  return { scope: 'feature', feature_code: code, validated_at: nowIso(), findings: kept };
 }
 
 // ---------------------------------------------------------------------------
@@ -975,13 +1038,69 @@ export async function validateProject(cwd, options = {}) {
 
   for (const code of allCodes) {
     if (!FEATURE_CODE_RE_STRICT.test(code)) continue;
-    const result = await validateFeature(cwd, code, options);
+    // Defer narrative suppression to the single project-level pass below, so the
+    // ROADMAP_NARRATIVE_OWNED info finding isn't emitted once per feature (#39).
+    const result = await validateFeature(cwd, code, { ...options, _deferNarrative: true });
     findings.push(...result.findings);
   }
 
   runOrphanFolderCheck(ctx, findings);
   runChangelogReferenceCheck(ctx, findings);
   runJournalIndexDriftCheck(ctx, findings);
+
+  // --- 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 roadmapText = fs.existsSync(ctx.paths.roadmap)
+      ? fs.readFileSync(ctx.paths.roadmap, 'utf8')
+      : '';
+
+    for (const f of features) {
+      if (!f.phase) {
+        findings.push(finding('warning', 'HIERARCHY_DEPTH_INVALID', f.code,
+          'feature has no phase — renders ungrouped (depth < 2)'));
+      }
+    }
+
+    const externalPrefixes = (ctx.externalPrefixes && ctx.externalPrefixes.length)
+      ? ctx.externalPrefixes
+      : loadExternalPrefixes(cwd);
+    const rt = checkRoundtrip(roadmapText, features, { now: '0000-00-00', externalPrefixes });
+    if (!rt.fixedPoint) {
+      const d = rt.diffs.find((x) => x.kind === 'FIXED_POINT_DIVERGENCE');
+      findings.push(finding('error', 'ROUNDTRIP_NOT_FIXED_POINT', undefined,
+        `ROADMAP.md is not a generation fixed point: ${d?.detail ?? 'diverges on regen'}`));
+    }
+    for (const d of rt.diffs.filter((x) => x.kind.startsWith('LOSSLESS_'))) {
+      const label = LOSSY_LABELS[d.kind] ?? d.kind;
+      findings.push(finding('warning', 'ROADMAP_LOSSY', d.code ?? undefined,
+        `${label}${d.detail ? ': ' + d.detail : ''}`));
+    }
+
+    const phasesWithFeatures = new Set(features.map((f) => f.phase).filter(Boolean));
+    const phaseBlocks = readPhaseBlocks(roadmapText);
+    const phaseOverrides = readPhaseOverrides(roadmapText);
+    const anchoredPhases = new Set(
+      [...readPreservedSectionAnchors(roadmapText).values()].filter(Boolean));
+    for (const phaseId of readPhaseOrder(roadmapText)) {
+      if (phasesWithFeatures.has(phaseId)) continue;
+      const block = phaseBlocks.get(phaseId);
+      const hasBody = block && block.split('\n').slice(1).some((l) => l.trim().length > 0);
+      if (!hasBody && !anchoredPhases.has(phaseId)) {
+        // A dead heading (no rows, no body) is a warning — but if the heading
+        // itself carries an active status, it is holding live work in a
+        // place that renders nothing: escalate to error.
+        const ov = (phaseOverrides.get(phaseId) ?? '').toUpperCase();
+        const active = ov.startsWith('IN_PROGRESS') || ov.startsWith('PARTIAL');
+        findings.push(finding(active ? 'error' : 'warning', 'ORPHAN_PHASE', undefined,
+          `phase "${phaseId}" has no feature.json features and no preserved content`
+          + (active ? ' (active status — dead heading holds live work)' : '')));
+      }
+    }
+  }
+
   try {
     await runExternalRefChecks(ctx, findings, options);
   } catch (e) {
@@ -995,5 +1114,10 @@ export async function validateProject(cwd, options = {}) {
     ));
   }
 
-  return { scope: 'project', validated_at: nowIso(), findings };
+  // Narrative-owned workspaces (#39): ROADMAP.md is hand-authored, not driven by
+  // feature.json, so every finding that treats a roadmap row as canonical is a
+  // false positive. Strip them in one place (robust against new such checks) and
+  // record the skip as a single info finding. feature.json↔vision drift is left
+  // intact — it doesn't involve the roadmap.
+  return { scope: 'project', validated_at: nowIso(), findings: applyNarrativeSuppression(findings, ctx) };
 }

package/lib/feature-writer.js

@@ -16,12 +16,14 @@
  * be called from MCP tools, the CLI, or future REST routes.
  */
 
-import { existsSync, realpathSync, statSync } from 'fs';
-import { resolve, normalize, sep, basename, dirname } from 'path';
+import { existsSync, realpathSync, statSync, readFileSync } from 'fs';
+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 { checkRoundtrip } from './roadmap-roundtrip.js';
+import { isNarrativeOwned, narrativeOwnedMessage } from './roadmap-config.js';
 
 // providerFor is imported lazily (inside each function) to break the
 // module-load-time cycle: factory.js → local-provider.js → feature-writer.js.
@@ -90,9 +92,15 @@ function maybeIdempotent(args, fn) {
  * @param {number} [args.position]
  * @param {string} [args.parent]
  * @param {string[]} [args.tags]
+ * @param {boolean} [args.force]
  * @param {string} [args.idempotency_key]
  */
 export async function addRoadmapEntry(cwd, args) {
+  // Narrative-owned workspaces have a hand-authored ROADMAP.md and no typed
+  // tracker provider — refuse before writing any feature.json (#39).
+  if (isNarrativeOwned(cwd)) {
+    throw new Error(narrativeOwnedMessage(cwd));
+  }
   validateCode(args.code);
   if (!args.description) throw new Error('feature-writer: description is required');
   if (!args.phase) throw new Error('feature-writer: phase is required');
@@ -128,6 +136,13 @@ export async function addRoadmapEntry(cwd, args) {
     if (args.parent) feature.parent = args.parent;
     if (args.tags && args.tags.length) feature.tags = args.tags;
 
+    let roundtrip = null;
+    if (isLocalProvider(provider)) {
+      roundtrip = await roundtripGuard(cwd, provider,
+        (feats) => [...feats, feature],
+        { force: args.force, label: 'add_roadmap_entry' });
+    }
+
     // 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
@@ -157,6 +172,7 @@ export async function addRoadmapEntry(cwd, args) {
       phase: args.phase,
       position: feature.position,
       roadmap_path: roadmapPath,
+      roundtrip,
     };
   });
 }
@@ -186,6 +202,62 @@ function partialWriteError(message, cause) {
   return err;
 }
 
+// Local-provider discriminator. LocalFileProvider.name() returns 'local';
+// GitHubProvider.name() returns 'github' (see lib/tracker/*-provider.js). The
+// factory returns the bare local instance for the local case and a Proxy
+// wrapping GitHubProvider otherwise — name() resolves correctly through both.
+// Test mock providers that don't model the local file tracker won't report
+// 'local', so the guard is correctly skipped for them.
+function isLocalProvider(provider) {
+  return typeof provider?.name === 'function' && provider.name() === 'local';
+}
+
+// Read ROADMAP.md as a regen base only if it's a readable regular file.
+// Anything else (absent, directory, unreadable) yields '' so the guard stays a
+// pure pre-check and leaves any real write-path I/O fault to renderRoadmap.
+function readRoadmapBase(roadmapPath) {
+  try {
+    if (!existsSync(roadmapPath) || !statSync(roadmapPath).isFile()) return '';
+    return readFileSync(roadmapPath, 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+// Pre-commit roundtrip guard (LOCAL providers only — remote providers render
+// server-side and are out of scope for COMP-ROADMAP-RT). Runs checkRoundtrip on
+// the prospective feature set BEFORE persistence; throws (unless force) when the
+// render won't stabilize, so canonical feature.json is never written ahead of a
+// broken view. Returns the RoundtripResult on success.
+//
+// Blocks only on fixed-point divergence (a visibly churning rendered view);
+// losslessness is surfaced by the validator (Task 6 / validate_project), not
+// blocked here. The full RoundtripResult — including lossless + diffs — is still
+// returned for callers to inspect.
+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');
+  // 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
+  // renderRoadmap partial-write error (which surfaces that I/O fault with the
+  // correct ROADMAP_PARTIAL_WRITE envelope after feature.json is committed).
+  const baseText = readRoadmapBase(roadmapPath);
+  const rt = checkRoundtrip(baseText, projected, { now: '0000-00-00' });
+  if (!rt.fixedPoint && !force) {
+    const d = rt.diffs.find(x => x.kind === 'FIXED_POINT_DIVERGENCE');
+    const err = new Error(
+      `${label}: aborted — ROADMAP.md would not be a generation fixed point ` +
+      `(${d?.detail ?? 'diverges on regen'}). No changes were written. ` +
+      `Pass force: true to commit anyway.`
+    );
+    err.code = 'ROUNDTRIP_NOT_FIXED_POINT';
+    throw err;
+  }
+  return rt;
+}
+
 // 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.
@@ -252,6 +324,14 @@ export async function setFeatureStatus(cwd, args) {
     // 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;
+
+    let roundtrip = null;
+    if (isLocalProvider(provider)) {
+      roundtrip = await roundtripGuard(cwd, provider,
+        (feats) => feats.map(f => f.code === args.code ? updated : f),
+        { force: args.force, label: 'set_feature_status' });
+    }
+
     await provider.persistFeatureRaw(args.code, updated);
     try {
       await provider.renderRoadmap();
@@ -275,7 +355,7 @@ export async function setFeatureStatus(cwd, args) {
     if (args.force && !allowed.includes(to)) event.forced = true;
     await safeAppendEvent(cwd, event);
 
-    return { code: args.code, from, to, ts: new Date().toISOString() };
+    return { code: args.code, from, to, ts: new Date().toISOString(), roundtrip };
   });
 }
 

package/lib/migrate-roadmap.js

@@ -19,12 +19,18 @@ import { loadFeaturesDir } from './project-paths.js';
  * @param {string} [opts.featuresDir] - Relative features path
  * @param {boolean} [opts.dryRun] - Print what would be created without writing
  * @param {boolean} [opts.overwrite] - Overwrite existing feature.json files
- * @returns {{ created: string[], skipped: string[], updated: string[] }}
+ * @param {string[]} [opts.externalPrefixes] - Code prefixes for features owned by
+ *   OTHER projects (cross-project references). Entries whose code matches any
+ *   prefix are skipped entirely — no feature.json is created — and recorded in
+ *   the returned `skippedExternal` array.
+ * @returns {{ created: string[], skipped: string[], updated: string[], skippedExternal: string[] }}
  */
 export function migrateRoadmap(cwd, opts = {}) {
   // COMP-MCP-MIGRATION-2-1: honor `paths.features` override so backfill
   // writes under the configured root rather than the hardcoded default.
   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');
 
   if (!existsSync(roadmapPath)) {
@@ -37,11 +43,19 @@ export function migrateRoadmap(cwd, opts = {}) {
   const created = [];
   const skipped = [];
   const updated = [];
+  const skippedExternal = [];
 
   for (const entry of entries) {
     // Skip anonymous entries
     if (entry.code.startsWith('_anon_')) continue;
 
+    // Skip cross-project references — owned by another project, present here
+    // only as a roadmap reference. Never create a feature.json for these.
+    if (isExternal(entry.code)) {
+      skippedExternal.push(entry.code);
+      continue;
+    }
+
     const existing = readFeature(cwd, entry.code, featuresDir);
 
     if (existing && !opts.overwrite) {
@@ -81,7 +95,7 @@ export function migrateRoadmap(cwd, opts = {}) {
     }
   }
 
-  return { created, skipped, updated };
+  return { created, skipped, updated, skippedExternal };
 }
 
 /**

package/lib/project-paths.js

@@ -33,4 +33,20 @@ export function loadFeaturesDir(cwd) {
   }
 }
 
+/**
+ * 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 []; }
+}
+
 export const _internals = { DEFAULT_FEATURES_DIR };

package/lib/roadmap-config.js

@@ -0,0 +1,50 @@
+/**
+ * roadmap-config.js — Workspace-level roadmap policy (issue #39).
+ *
+ * A workspace is "narrative-owned" when its ROADMAP.md is hand-authored and
+ * must NOT be machine-regenerated from feature.json. It is signalled by
+ * `roadmap.narrative: true` in `.compose/compose.json`. The typed writer
+ * (generateRoadmap / writeRoadmap / add_roadmap_entry) refuses to engage such a
+ * workspace — otherwise regen flattens curated reconciliation prose into
+ * rendered tables (the forge-top "Wave 6" duplication, root cause of #39).
+ *
+ * feature.json files may still exist in a narrative-owned workspace — they are
+ * structured link carriers (xref-sync) and cross-references; they simply do not
+ * DRIVE ROADMAP.md. The guard stops the writer, it does not delete data.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * @param {string} cwd - Workspace root
+ * @returns {boolean} true if `.compose/compose.json` declares roadmap.narrative
+ */
+export function isNarrativeOwned(cwd) {
+  const p = join(cwd, '.compose/compose.json');
+  if (!existsSync(p)) return false;
+  try {
+    const parsed = JSON.parse(readFileSync(p, 'utf8'));
+    return parsed?.roadmap?.narrative === true;
+  } catch {
+    // Malformed config: don't claim narrative-owned. The tracker factory
+    // (loadTrackerConfig) is the loud validator for malformed compose.json;
+    // this gate stays quiet so a parse error there doesn't double-report here.
+    return false;
+  }
+}
+
+/**
+ * Actionable message explaining why a typed-writer operation was refused.
+ * @param {string} cwd
+ * @returns {string}
+ */
+export function narrativeOwnedMessage(cwd) {
+  return (
+    `compose: ${cwd} is narrative-owned (roadmap.narrative=true in ` +
+    `.compose/compose.json) — its ROADMAP.md is hand-authored and is not ` +
+    `regenerated from feature.json. Edit ROADMAP.md directly. To re-enable ` +
+    `typed-roadmap generation, remove "roadmap": { "narrative": true } from ` +
+    `.compose/compose.json.`
+  );
+}