@smartmemory/compose 0.1.44-beta → 0.2.0

package/lib/roadmap-gen.js

@@ -6,7 +6,8 @@
 
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { join } from 'path';
-import { listFeatures } from './feature-json.js';
+import { listFeatures, positionSortKey } from './feature-json.js';
+import { parseStatusToken } from './roadmap-parser.js';
 import { loadFeaturesDir } from './project-paths.js';
 import {
   readPhaseOverrides,
@@ -17,22 +18,15 @@ import {
   readPhaseBlocks,
 } from './roadmap-preservers.js';
 import { emitDrift } from './roadmap-drift.js';
+import { isNarrativeOwned, narrativeOwnedMessage } from './roadmap-config.js';
 
-const STATUS_ORDER = ['IN_PROGRESS', 'PARTIAL', 'PLANNED', 'COMPLETE', 'SUPERSEDED', 'PARKED'];
-const STATUS_TOKENS = ['COMPLETE', 'IN_PROGRESS', 'PARTIAL', 'PLANNED', 'SUPERSEDED', 'PARKED', 'BLOCKED', 'KILLED'];
+// Escape literal pipes in free-text table cells so they don't break markdown
+// column splitting. Symmetric with the unescape in roadmap-parser.js /
+// roadmap-preservers.js (split on unescaped `|`, then restore `\|` → `|`).
+// Only applied to description/item cells — #/code/status never contain pipes.
+const escCell = (s) => String(s ?? '').replace(/\|/g, '\\|');
 
-/**
- * Extract the leading status token from override text like
- * `PARTIAL (1a–1d COMPLETE, 2 PLANNED)` → `PARTIAL`.
- * Returns null if no token recognized.
- */
-function parseStatusToken(override) {
-  for (const t of STATUS_TOKENS) {
-    if (override === t) return t;
-    if (override.startsWith(t + ' ') || override.startsWith(t + '(')) return t;
-  }
-  return null;
-}
+const STATUS_ORDER = ['IN_PROGRESS', 'PARTIAL', 'PLANNED', 'COMPLETE', 'SUPERSEDED', 'PARKED'];
 
 /**
  * Compute the aggregate status for a phase based on its features.
@@ -56,6 +50,8 @@ function phaseStatus(features) {
  * @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)
+ * @param {string} [opts.now] - ISO date (YYYY-MM-DD) for the 'Last updated' line; defaults to today. Inject for deterministic output.
+ * @param {boolean} [opts.suppressDrift] - When true, skip emitDrift side effects (used by the pure roundtrip checker).
  * @returns {string} - Merged ROADMAP.md content
  */
 export function generateRoadmapFromBase(baseText, features, opts = {}) {
@@ -115,9 +111,12 @@ export function generateRoadmapFromBase(baseText, features, opts = {}) {
   const orderedPhaseIds = [...new Set(sourcePhaseOrder)];
   const seenInSource = new Set(sourcePhaseOrder);
   const newPhases = [...phases.keys()].filter(p => !seenInSource.has(p));
+  // Range-tolerant numeric key (same as listFeatures' sort) so a new phase whose
+  // features carry ranged-string positions ("92–95") still orders numerically
+  // instead of collapsing to a NaN comparator.
   newPhases.sort((a, b) => {
-    const minA = Math.min(...phases.get(a).map(f => f.position ?? 999));
-    const minB = Math.min(...phases.get(b).map(f => f.position ?? 999));
+    const minA = Math.min(...phases.get(a).map(f => positionSortKey(f.position)));
+    const minB = Math.min(...phases.get(b).map(f => positionSortKey(f.position)));
     return minA - minB;
   });
   orderedPhaseIds.push(...newPhases);
@@ -151,7 +150,7 @@ export function generateRoadmapFromBase(baseText, features, opts = {}) {
     if (override) {
       const overrideToken = parseStatusToken(override);
       if (overrideToken && overrideToken !== rollupStatus) {
-        if (cwd) emitDrift(cwd, { phaseId: phase, override, computed: rollupStatus });
+        if (cwd && !opts.suppressDrift) 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
@@ -207,17 +206,25 @@ export function generateRoadmapFromBase(baseText, features, 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
+ * @param {string} [opts.now] - ISO date (YYYY-MM-DD) for the 'Last updated' line; defaults to today. Inject for deterministic output.
  * @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 });
+  // Narrative-owned workspace: ROADMAP.md is hand-authored. Return it verbatim
+  // rather than regenerating from feature.json (#39).
+  if (isNarrativeOwned(cwd)) {
+    console.warn(narrativeOwnedMessage(cwd));
+    return existingText;
+  }
+
+  const featuresDir = opts.featuresDir ?? loadFeaturesDir(cwd);
+  const features = listFeatures(cwd, featuresDir);
+
+  const now = opts.now ?? new Date().toISOString().slice(0, 10);
+  return generateRoadmapFromBase(existingText, features, { ...opts, cwd, featuresDir, now });
 }
 
 /**
@@ -256,7 +263,7 @@ function readPreamble(cwd, opts, existingText) {
   // Default preamble
   const name = opts.projectName ?? 'Project';
   const desc = opts.projectDescription ?? '';
-  const today = new Date().toISOString().slice(0, 10);
+  const today = opts.now ?? new Date().toISOString().slice(0, 10);
   return `# ${name} Roadmap
 
 ${desc ? desc + '\n\n' : ''}<!-- Generated from feature.json — do not edit manually -->
@@ -370,13 +377,13 @@ function renderTableLines(features, anonRows) {
       if (f.items && f.items.length > 0) {
         for (const item of f.items) {
           const num = item.position ?? '—';
-          const desc = item.description ?? '';
+          const desc = escCell(item.description ?? '');
           const st = item.status ?? f.status;
           lines.push(`| ${num} | ${f.code} | ${desc} | ${st} |`);
         }
       } else {
         const num = f.position ?? '—';
-        lines.push(`| ${num} | ${f.code} | ${f.description} | ${f.status} |`);
+        lines.push(`| ${num} | ${f.code} | ${escCell(f.description)} | ${f.status} |`);
       }
       emitAnonAfter(f.code);
     }
@@ -386,7 +393,7 @@ function renderTableLines(features, anonRows) {
     emitAnonAfter(null);
     for (const f of features) {
       const num = f.position ?? '—';
-      const desc = f.description ?? '';
+      const desc = escCell(f.description ?? '');
       lines.push(`| ${num} | ${f.code} | ${desc} | ${f.status} |`);
       emitAnonAfter(f.code);
     }
@@ -434,13 +441,13 @@ function renderPhase(phaseName, status, features, anonRows = []) {
       if (f.items && f.items.length > 0) {
         for (const item of f.items) {
           const num = item.position ?? '—';
-          const desc = item.description ?? '';
+          const desc = escCell(item.description ?? '');
           const st = item.status ?? f.status;
           lines.push(`| ${num} | ${f.code} | ${desc} | ${st} |`);
         }
       } else {
         const num = f.position ?? '—';
-        lines.push(`| ${num} | ${f.code} | ${f.description} | ${f.status} |`);
+        lines.push(`| ${num} | ${f.code} | ${escCell(f.description)} | ${f.status} |`);
       }
       emitAnonAfter(f.code);
     }
@@ -454,7 +461,7 @@ function renderPhase(phaseName, status, features, anonRows = []) {
     emitAnonAfter(null); // any head-of-table anon rows
     for (const f of features) {
       const num = f.position ?? '—';
-      const desc = f.description ?? '';
+      const desc = escCell(f.description ?? '');
       lines.push(`| ${num} | ${f.code} | ${desc} | ${f.status} |`);
       emitAnonAfter(f.code);
     }
@@ -509,8 +516,16 @@ function buildKeyDocs(features, featuresDir) {
  * @param {object} [opts]
  */
 export function writeRoadmap(cwd, opts = {}) {
-  const content = generateRoadmap(cwd, opts);
   const roadmapPath = join(cwd, 'ROADMAP.md');
+
+  // Narrative-owned workspace: never overwrite hand-authored ROADMAP.md (#39).
+  // No-op + warn; the existing file on disk is the source of truth.
+  if (isNarrativeOwned(cwd)) {
+    console.warn(narrativeOwnedMessage(cwd));
+    return roadmapPath;
+  }
+
+  const content = generateRoadmap(cwd, opts);
   writeFileSync(roadmapPath, content);
   return roadmapPath;
 }

package/lib/roadmap-heading.js

@@ -0,0 +1,85 @@
+/**
+ * roadmap-heading.js — Shared phase-heading parsing for ROADMAP.md.
+ *
+ * A phase heading is `## <title> — <status>`, where <title> may itself contain
+ * em-dashes (e.g. `## Wave 6 — Situational Awareness — COMPLETE`). Splitting on
+ * the FIRST ` — ` truncated such titles to their leading fragment and mis-read
+ * the status — see issue #38. The status is instead the trailing segment that
+ * begins, at an em-dash boundary, with a recognized status token.
+ *
+ * Single source of truth for the parser (roadmap-parser.js) and the typed-writer
+ * preservers (roadmap-preservers.js), so they never disagree on a phaseId.
+ */
+
+// Canonical status enum. None is a prefix of another, so leading-token matching
+// is unambiguous regardless of order.
+export const STATUS_TOKENS = ['COMPLETE', 'IN_PROGRESS', 'PARTIAL', 'PLANNED', 'SUPERSEDED', 'PARKED', 'BLOCKED', 'KILLED'];
+
+/**
+ * Extract the leading status token from cell/override text. The token must be
+ * the whole string OR be followed by whitespace or `(` — the only separators a
+ * real status cell uses before commentary: `PARKED — needs X` → `PARKED`,
+ * `PARTIAL (1a COMPLETE)` → `PARTIAL`, `COMPLETE` → `COMPLETE`. Deliberately
+ * conservative: glued forms like `PLANNED-ish` or `PARKED/blocked` return null
+ * (left for the validator to flag) rather than being coerced to a valid enum.
+ * Case-insensitive; returns the canonical UPPERCASE token, or null if none.
+ *
+ * @param {string} text
+ * @returns {string|null}
+ */
+export function parseStatusToken(text) {
+  const up = String(text ?? '').trim().toUpperCase();
+  for (const t of STATUS_TOKENS) {
+    if (up === t) return t;
+    if (up.startsWith(t) && /[\s(]/.test(up[t.length])) return t;
+  }
+  return null;
+}
+
+// Matches a level-2 heading line and captures its content (everything after
+// `## `). Excludes `###` milestones: the required `\s+` after `##` fails on a
+// third `#`. Requires at least one content char, so a bare `## ` is not a phase.
+export const PHASE_HEADING_TEXT_RE = /^##\s+(.+)$/;
+
+/**
+ * Split phase-heading content into { title, status }.
+ *
+ * The status is the run after the RIGHTMOST ` — ` boundary whose tail begins
+ * with a recognized status token; the title is everything before it. Choosing
+ * the rightmost (not the first) qualifying boundary is what lets a title
+ * fragment that itself starts with a status word stay in the title
+ * (`Phase 9 — BLOCKED API Cleanup — COMPLETE` → title `Phase 9 — BLOCKED API
+ * Cleanup`, status `COMPLETE`) while still keeping status commentary that
+ * contains an em-dash attached to the status (`A — PARKED — needs X` → status
+ * `PARKED — needs X`, since `needs X` is not a status token so the PARKED
+ * boundary stays the rightmost qualifying one). If no segment after a ` — `
+ * begins with a status token, the whole string is the title.
+ *
+ * Limitation (inherent ambiguity): a segment of the form `TOKEN words` is
+ * structurally identical whether it is a title fragment (`BLOCKED API Cleanup`)
+ * or a status with trailing commentary (`SUPERSEDED by STRAT-1`). The rightmost
+ * rule treats the LAST such segment as the status, so the rare heading whose
+ * status commentary itself begins with another bare status token
+ * (`X — PARKED — BLOCKED by upstream`) mis-splits. No real roadmap heading uses
+ * that form (write `PARKED (blocked by upstream)` instead); the rightmost rule
+ * is correct for every heading in the corpus and the common commentary forms.
+ *
+ *   'Wave 6 — Situational Awareness — COMPLETE' → { title: 'Wave 6 — Situational Awareness', status: 'COMPLETE' }
+ *   'Phase 9 — BLOCKED API Cleanup — COMPLETE'  → { title: 'Phase 9 — BLOCKED API Cleanup', status: 'COMPLETE' }
+ *   'A — PARKED — needs X'                       → { title: 'A', status: 'PARKED — needs X' }
+ *   'Phase 0: Bootstrap — COMPLETE'              → { title: 'Phase 0: Bootstrap', status: 'COMPLETE' }
+ *   'Wave 6 — Situational Awareness'             → { title: 'Wave 6 — Situational Awareness', status: '' }
+ *
+ * @param {string} text  heading content (without the leading `## `)
+ * @returns {{ title: string, status: string }}
+ */
+export function splitPhaseHeading(text) {
+  const s = String(text ?? '').trim();
+  let best = null;
+  for (const m of s.matchAll(/\s+—\s+/g)) {
+    const tail = s.slice(m.index + m[0].length);
+    if (parseStatusToken(tail)) best = { index: m.index, tail };
+  }
+  if (best) return { title: s.slice(0, best.index).trim(), status: best.tail.trim() };
+  return { title: s, status: '' };
+}

package/lib/roadmap-parser.js

@@ -5,14 +5,21 @@
  * from the markdown table format used by Compose roadmaps.
  */
 
+import { isFeatureCode } from './feature-code.js';
+import { PRESERVED_OPEN_RE, PRESERVED_CLOSE_RE } from './roadmap-preservers.js';
+import { parseStatusToken, splitPhaseHeading, PHASE_HEADING_TEXT_RE } from './roadmap-heading.js';
+
+// Re-exported for backward compatibility — these now live in roadmap-heading.js,
+// the shared source of truth for heading/status parsing (issue #38).
+export { parseStatusToken, STATUS_TOKENS } from './roadmap-heading.js';
+
 // Statuses that exclude a feature from the buildable list. KILLED is
 // terminal; BLOCKED isn't buildable until unblocked.
 const SKIP_STATUSES = new Set(['COMPLETE', 'SUPERSEDED', 'PARKED', 'KILLED', 'BLOCKED']);
 
-const PHASE_HEADING_RE = /^##\s+(.+?)(?:\s+—\s+(.+))?$/;
 const MILESTONE_HEADING_RE = /^###\s+(.+?)(?:\s*:\s*(.+))?$/;
 const TABLE_ROW_RE = /^\|(.+)\|$/;
-const FEATURE_CODE_RE = /^[A-Z][\w-]*-\d+/;
+const FENCE_RE = /^```/;
 
 /**
  * @typedef {{ code: string, description: string, status: string, phaseId: string, position: number }} FeatureEntry
@@ -30,19 +37,52 @@ export function parseRoadmap(text) {
   const lines = text.split('\n');
   const entries = [];
   let currentPhaseId = '';
+  let currentParentPhaseId = '';
   let currentPhaseStatus = '';
   let position = 0;
   let inTable = false;
+  let inFence = false;
+  let inPreserved = false;
   let columnLayout = null; // { codeCol, descCol, statusCol }
 
   for (const line of lines) {
+    // Fence + preserved-section detection run on the RAW line (never the
+    // trimmed one) so the parser agrees with the preservers — which use raw
+    // lines — on what counts as a marker. Markers/fences are column-0 by
+    // convention; an indented `<!-- preserved-section -->` is NOT a marker.
+    if (FENCE_RE.test(line)) {
+      inFence = !inFence;
+      inTable = false;
+      columnLayout = null;
+      continue;
+    }
+    if (inFence) continue;
+
+    // Content inside a preserved-section is curated narrative emitted verbatim
+    // by the writer (readPreservedSections). It must not be parsed as feature
+    // rows — otherwise migrate mints phantom features from planning tables with
+    // non-standard schemas, and the roundtrip never reaches a fixed point.
+    if (PRESERVED_OPEN_RE.test(line)) {
+      inPreserved = true;
+      inTable = false;
+      columnLayout = null;
+      continue;
+    }
+    if (PRESERVED_CLOSE_RE.test(line)) {
+      inPreserved = false;
+      continue;
+    }
+    if (inPreserved) continue;
+
     const trimmed = line.trim();
 
-    // Phase heading: ## Phase 0: Bootstrap — COMPLETE
-    const phaseMatch = trimmed.match(PHASE_HEADING_RE);
+    // Phase heading: ## Phase 0: Bootstrap — COMPLETE (title may contain em-dashes)
+    const phaseMatch = trimmed.match(PHASE_HEADING_TEXT_RE);
     if (phaseMatch) {
-      currentPhaseId = phaseMatch[1].trim();
-      currentPhaseStatus = phaseMatch[2]?.trim() ?? '';
+      const { title, status } = splitPhaseHeading(phaseMatch[1]);
+      currentPhaseId = title;
+      currentParentPhaseId = title;
+      currentPhaseStatus = status;
       inTable = false;
       columnLayout = null;
       continue;
@@ -51,13 +91,13 @@ export function parseRoadmap(text) {
     // Milestone heading: ### Milestone 1: Stratum Engine Complete
     const milestoneMatch = trimmed.match(MILESTONE_HEADING_RE);
     if (milestoneMatch) {
-      // Nest under parent phase
+      // Nest under the PARENT phase, resetting on each milestone. Without
+      // resetting off the parent, consecutive ### headings would accumulate
+      // ("Phase > M1 > M2") instead of yielding sibling milestones.
       const milestoneLabel = milestoneMatch[1].trim();
-      if (currentPhaseId) {
-        currentPhaseId = `${currentPhaseId} > ${milestoneLabel}`;
-      } else {
-        currentPhaseId = milestoneLabel;
-      }
+      currentPhaseId = currentParentPhaseId
+        ? `${currentParentPhaseId} > ${milestoneLabel}`
+        : milestoneLabel;
       inTable = false;
       columnLayout = null;
       continue;
@@ -72,7 +112,10 @@ export function parseRoadmap(text) {
       continue;
     }
 
-    const cells = trimmed.split('|').slice(1, -1).map(c => c.trim());
+    // Split on UNESCAPED pipes only, then unescape `\|` → `|` in each cell.
+    // Symmetric with escCell() in roadmap-gen.js. For pipe-free rows this is
+    // identical to split('|') (no backslashes, no lookbehind matches).
+    const cells = trimmed.split(/(?<!\\)\|/).slice(1, -1).map(c => c.trim().replace(/\\\|/g, '|'));
 
     // Skip separator rows (|---|---|---|)
     if (cells.every(c => /^[-:]+$/.test(c))) {
@@ -93,15 +136,23 @@ export function parseRoadmap(text) {
     const desc = cells[columnLayout.descCol] ?? '';
     let status = cells[columnLayout.statusCol] ?? '';
 
-    // Clean up status (strip bold markers, etc.)
+    // Clean up status (strip bold markers, etc.) then reduce to a bare enum
+    // token so a cell like "PARKED — needs Claude Code adoption" yields PARKED
+    // (the inline rationale would otherwise produce a schema-invalid status).
+    // Cells with no recognized token are left as-is (the validator flags them).
     status = status.replace(/\*\*/g, '').trim();
-
-    // If the entire phase is COMPLETE, override individual statuses
-    if (SKIP_STATUSES.has(currentPhaseStatus)) {
+    const statusToken = parseStatusToken(status);
+    if (statusToken) status = statusToken;
+
+    // If the entire phase is a SKIP_STATUS, only fill in rows that have NO
+    // explicit status. An explicit per-row status (e.g. a PLANNED item under a
+    // rolled-up COMPLETE phase) must win over the phase-level override.
+    const explicitStatus = status;
+    if (SKIP_STATUSES.has(currentPhaseStatus) && !explicitStatus) {
       status = currentPhaseStatus;
     }
 
-    const isAnonymous = code === '—' || code === '-' || !FEATURE_CODE_RE.test(code);
+    const isAnonymous = code === '—' || code === '-' || !isFeatureCode(code);
 
     entries.push({
       code: isAnonymous ? `_anon_${position}` : code,

package/lib/roadmap-preservers.js

@@ -12,15 +12,18 @@
  *   - non-feature sections wrapped in `<!-- preserved-section: <id> -->`
  */
 
-const PHASE_HEADING_RE = /^##\s+(.+?)\s+—\s+(.+?)\s*$/;
+import { FEATURE_CODE_RE_STRICT } from './feature-code.js';
+import { splitPhaseHeading, PHASE_HEADING_TEXT_RE } from './roadmap-heading.js';
+
 const FENCE_RE = /^```/;
 const TABLE_HEADER_RE = /^\|.*\|$/;
 const TABLE_DIVIDER_RE = /^\|[\s|:-]+\|$/;
 const TABLE_ROW_RE = /^\|.+\|$/;
-const FEATURE_CODE_RE = /^[A-Z][A-Z0-9-]*[A-Z0-9]$/;
 
-const PRESERVED_OPEN_RE = /^<!--\s*preserved-section:\s*([a-z][a-z0-9-]*)\s*-->\s*$/;
-const PRESERVED_CLOSE_RE = /^<!--\s*\/preserved-section\s*-->\s*$/;
+// Exported so roadmap-parser.js can apply the SAME preserved-section skipping
+// (single source of truth — parser and preservers must agree on what's preserved).
+export const PRESERVED_OPEN_RE = /^<!--\s*preserved-section:\s*([a-z][a-z0-9-]*)\s*-->\s*$/;
+export const PRESERVED_CLOSE_RE = /^<!--\s*\/preserved-section\s*-->\s*$/;
 
 /**
  * Scan ROADMAP.md text and return a Map of phaseId → override text.
@@ -35,14 +38,26 @@ const PRESERVED_CLOSE_RE = /^<!--\s*\/preserved-section\s*-->\s*$/;
 export function readPhaseOverrides(text) {
   const out = new Map();
   let inFence = false;
+  let inPreserved = false;
   for (const line of text.split('\n')) {
     if (FENCE_RE.test(line)) {
       inFence = !inFence;
       continue;
     }
     if (inFence) continue;
-    const m = line.match(PHASE_HEADING_RE);
-    if (m) out.set(m[1].trim(), m[2].trim());
+    // Headings inside a preserved-section are part of curated content emitted
+    // verbatim by readPreservedSections — they are not phase overrides.
+    if (PRESERVED_OPEN_RE.test(line)) { inPreserved = true; continue; }
+    if (PRESERVED_CLOSE_RE.test(line)) { inPreserved = false; continue; }
+    if (inPreserved) continue;
+    const m = line.match(PHASE_HEADING_TEXT_RE);
+    if (m) {
+      // Only a recognized trailing status token counts as an override; an
+      // em-dash that is part of the title (no status token after it) yields no
+      // override. See splitPhaseHeading / issue #38.
+      const { title, status } = splitPhaseHeading(m[1]);
+      if (status) out.set(title, status);
+    }
   }
   return out;
 }
@@ -56,7 +71,7 @@ export function readPhaseOverrides(text) {
  *   table, or null if this anon row was at the table head (no typed predecessor).
  *
  * A row is "anonymous" if its Feature column (detected by header) is `—` or
- * doesn't match FEATURE_CODE_RE. The current parser regex (looser, requires
+ * doesn't match FEATURE_CODE_RE_STRICT. The current parser regex (looser, requires
  * trailing -<digits>) is NOT used here; we use the strict regex for accurate
  * classification (anon means truly no feature code, not the parser's regex bug).
  * For the 3-col anonymous form (`# | Item | Status`), all rows are anon.
@@ -67,6 +82,7 @@ export function readPhaseOverrides(text) {
 export function readAnonymousRows(text) {
   const out = new Map();
   let inFence = false;
+  let inPreserved = false;
   let currentPhaseId = null;
   let inTable = false;
   let codeColIdx = -1; // -1 means anonymous-form (3-col) table
@@ -81,10 +97,23 @@ export function readAnonymousRows(text) {
     }
     if (inFence) continue;
 
+    // Rows inside a preserved-section are owned verbatim by
+    // readPreservedSections — never capture them as anon (else generate emits
+    // them twice and the roundtrip accumulates duplicates every pass). Keep
+    // currentPhaseId across the block (the phase is unchanged by it); only the
+    // table state resets, so anon rows AFTER the block still anchor correctly.
+    if (PRESERVED_OPEN_RE.test(line)) {
+      inPreserved = true;
+      inTable = false; codeColIdx = -1; lastTypedCode = null;
+      continue;
+    }
+    if (PRESERVED_CLOSE_RE.test(line)) { inPreserved = false; continue; }
+    if (inPreserved) continue;
+
     // Phase heading resets table state.
-    const phaseMatch = line.match(/^##\s+(.+?)(?:\s+—\s+.+)?\s*$/);
+    const phaseMatch = line.match(PHASE_HEADING_TEXT_RE);
     if (phaseMatch && line.startsWith('## ')) {
-      currentPhaseId = phaseMatch[1].trim();
+      currentPhaseId = splitPhaseHeading(phaseMatch[1]).title;
       inTable = false;
       codeColIdx = -1;
       lastTypedCode = null;
@@ -99,7 +128,11 @@ export function readAnonymousRows(text) {
       continue;
     }
 
-    const cells = line.split('|').slice(1, -1).map(c => c.trim());
+    // Split on UNESCAPED pipes only (lockstep with roadmap-parser.js), then
+    // unescape `\|` → `|`. This affects column detection / code extraction only;
+    // anon rows are stored as `rawLine: line` verbatim below, so the raw source
+    // line round-trips unchanged regardless of escaping.
+    const cells = line.split(/(?<!\\)\|/).slice(1, -1).map(c => c.trim().replace(/\\\|/g, '|'));
 
     // Header row — detect column layout.
     if (!inTable) {
@@ -120,14 +153,22 @@ export function readAnonymousRows(text) {
     // Skip divider rows.
     if (TABLE_DIVIDER_RE.test(line.trim())) continue;
 
-    // Data row.
+    // Data row. A code that matches the strict contract case-INSENSITIVELY is
+    // a typed row (the same feature as feature.json's uppercase code); anchor by
+    // the uppercased canonical form so emitAnonAfter() re-places following anon
+    // rows during regen. Classifying a lowercase code as anon would preserve a
+    // phantom duplicate alongside the regenerated typed row (GENFIX T5).
     let isAnon = false;
+    let typedCode = null;
     if (codeColIdx === -1) {
       isAnon = true;
     } else {
       const codeCell = cells[codeColIdx] ?? '';
-      if (codeCell === '—' || codeCell === '' || !FEATURE_CODE_RE.test(codeCell)) {
+      const upper = codeCell.toUpperCase();
+      if (codeCell === '—' || codeCell === '' || !FEATURE_CODE_RE_STRICT.test(upper)) {
         isAnon = true;
+      } else {
+        typedCode = upper;
       }
     }
 
@@ -136,7 +177,7 @@ export function readAnonymousRows(text) {
       arr.push({ rawLine: line, predecessorCode: lastTypedCode });
       out.set(currentPhaseId, arr);
     } else {
-      lastTypedCode = cells[codeColIdx];
+      lastTypedCode = typedCode;
     }
   }
   return out;
@@ -248,10 +289,10 @@ export function readPhaseBlocks(text) {
     }
     if (inPreserved) continue;
 
-    const phaseMatch = line.match(/^##\s+(.+?)(?:\s+—\s+.+)?\s*$/);
+    const phaseMatch = line.match(PHASE_HEADING_TEXT_RE);
     if (phaseMatch && line.startsWith('## ')) {
       finalize(i);
-      currentPhaseId = phaseMatch[1].trim();
+      currentPhaseId = splitPhaseHeading(phaseMatch[1]).title;
       currentStartLineIdx = i;
     }
   }
@@ -291,9 +332,9 @@ export function readPhaseOrder(text) {
     }
     if (inPreserved) continue;
 
-    const phaseMatch = line.match(/^##\s+(.+?)(?:\s+—\s+.+)?\s*$/);
+    const phaseMatch = line.match(PHASE_HEADING_TEXT_RE);
     if (phaseMatch && line.startsWith('## ')) {
-      out.push(phaseMatch[1].trim());
+      out.push(splitPhaseHeading(phaseMatch[1]).title);
     }
   }
   return out;
@@ -330,9 +371,9 @@ export function readPreservedSectionAnchors(text) {
 
     // Phase headings inside an open preserved-section do NOT advance the anchor.
     if (openId === null) {
-      const phaseMatch = line.match(/^##\s+(.+?)(?:\s+—\s+.+)?\s*$/);
+      const phaseMatch = line.match(PHASE_HEADING_TEXT_RE);
       if (phaseMatch && line.startsWith('## ') && !PRESERVED_OPEN_RE.test(line) && !PRESERVED_CLOSE_RE.test(line)) {
-        currentPhaseId = phaseMatch[1].trim();
+        currentPhaseId = splitPhaseHeading(phaseMatch[1]).title;
         continue;
       }
     }