@smartmemory/compose 0.2.50-beta → 0.2.51-beta

package/lib/codex-preflight.js

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

package/lib/completion-writer.js

@@ -209,6 +209,18 @@ function validate(args) {
     throw inputError('completion-writer: set_status must be a boolean');
   }
 
+  // built_via — OPTIONAL marker recording the pipeline template a feature was
+  // built with (e.g. 'build-quick'). Persisted on feature.json so downstream
+  // consumers (e.g. the validator's report-completion check) can tell which
+  // lifecycle produced the feature. Must be a lowercase template slug.
+  if (args.built_via !== undefined && args.built_via !== null) {
+    if (typeof args.built_via !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(args.built_via)) {
+      throw inputError(
+        `completion-writer: built_via must be a lowercase template slug (e.g. "build-quick"), got "${args.built_via}"`
+      );
+    }
+  }
+
   // force — boolean if present
   if (args.force !== undefined && typeof args.force !== 'boolean') {
     throw inputError('completion-writer: force must be a boolean');
@@ -264,6 +276,8 @@ async function safeAppendEvent(cwd, event) {
  * @param {string}   [args.notes]
  * @param {boolean}  [args.set_status]     Default true — flip status to COMPLETE
  * @param {boolean}  [args.force]          Replace existing same-(code,sha) record
+ * @param {string}   [args.built_via]      Optional template slug (e.g. 'build-quick')
+ *                                         stamped onto feature.json (COMP-BUILD-QUICK-1)
  * @param {string}   [args.idempotency_key]
  *
  * @returns {{ feature_code, completion_id, commit_sha, commit_sha_short,
@@ -344,7 +358,13 @@ export async function recordCompletion(cwd, args) {
       // 5h. Persist completion record BEFORE status flip (so flip failure doesn't lose the record)
       // Use persistFeatureRaw (policy-free, no status-delta guard) — completion-writer
       // owns its own ordering/locking and only mutates the completions array, not status.
-      await provider.persistFeatureRaw(feature_code, { ...feature, completions });
+      await provider.persistFeatureRaw(feature_code, {
+        ...feature,
+        completions,
+        // COMP-BUILD-QUICK-1: stamp the build template (e.g. 'build-quick') so the
+        // validator can exempt quick-built features from MISSING_COMPLETION_REPORT.
+        ...(args.built_via ? { built_via: args.built_via } : {}),
+      });
 
       // 5i. Status flip (default on)
       const set_status = args.set_status !== false;

package/lib/feature-validator.js

@@ -573,7 +573,11 @@ function runArtifactLinkChecks(fctx, ctx, findings) {
     // PLANNED / SUPERSEDED / KILLED / PARKED — no finding (expected baseline)
   }
   // MISSING_COMPLETION_REPORT (warning, COMPLETE)
-  if (status === 'COMPLETE' && !folder.files.has('report.md')) {
+  // COMP-BUILD-QUICK-1: the quick lifecycle (compose build --quick) omits the
+  // report phase by design and stamps built_via:'build-quick' on feature.json at
+  // ship. Exempt those features — a missing report.md is expected, not debt.
+  if (status === 'COMPLETE' && !folder.files.has('report.md') &&
+      featureJson?.built_via !== 'build-quick') {
     findings.push(finding('warning', 'MISSING_COMPLETION_REPORT', code,
       `Feature is COMPLETE but report.md is missing (current writers do not enforce this; warning only)`));
   }

package/lib/hooks-status.js

@@ -0,0 +1,135 @@
+/**
+ * hooks-status.js — Shared git-hook status logic.
+ *
+ * Single source of truth for hook drift detection, consumed by:
+ *   - `compose hooks status` (bin/compose.js) — prints lines via formatHookStatusLines
+ *   - `GET /api/environment-health` (server/health-routes.js) — maps raw facts to API states
+ *
+ * Extracted verbatim from the historical inline `statusOne` (bin/compose.js) so
+ * the CLI output stays byte-identical. The ONLY addition is the non-state
+ * `wsVerified` flag: when the expected workspace id is unknown (null), the CLI
+ * stays lenient (reports "current") but the flag lets the API surface
+ * `workspace-unverified` instead of a false "current".
+ *
+ * Pure: no console output, no process exit. Reads only the hook files on disk.
+ *
+ * Roadmap: COMP-PARITY-3.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Marker comment baked into each Compose-installed hook (identifies "ours"). */
+export const HOOK_MARKERS = {
+  'post-commit': '# Compose post-commit hook —',
+  'pre-push': '# Compose pre-push hook —',
+};
+
+/** The hook types Compose manages, in display order. */
+export const HOOK_TYPE_LIST = Object.keys(HOOK_MARKERS);
+
+/** Pull the baked COMPOSE_WORKSPACE_ID="..." value out of hook content, or null. */
+export function extractBakedWorkspaceId(content) {
+  const m = content.match(/^COMPOSE_WORKSPACE_ID="([^"]*)"$/m);
+  return m ? m[1] : null;
+}
+
+/**
+ * Compute the raw status facts for every managed hook type.
+ *
+ * @param {object} opts
+ * @param {string} opts.projectRoot — repo root (hooks live at <root>/.git/hooks)
+ * @param {string|null} [opts.expectedWsId] — workspace id to compare against; null
+ *   means "unknown" (lenient match, wsVerified=false)
+ * @param {string} opts.composeNode — expected COMPOSE_NODE (process.execPath)
+ * @param {string} opts.composeBin — expected COMPOSE_BIN (path to compose.js)
+ * @returns {Record<string, HookStatusRaw>} keyed by hook type
+ */
+export function computeHooksStatus({ projectRoot, expectedWsId = null, composeNode, composeBin }) {
+  const hooksDir = join(projectRoot, '.git', 'hooks');
+  const out = {};
+  for (const type of HOOK_TYPE_LIST) {
+    out[type] = computeOne({ type, hooksDir, expectedWsId, composeNode, composeBin });
+  }
+  return out;
+}
+
+function computeOne({ type, hooksDir, expectedWsId, composeNode, composeBin }) {
+  const marker = HOOK_MARKERS[type];
+  const dest = join(hooksDir, type);
+
+  const empty = {
+    reason: null,
+    bakedWorkspace: null,
+    expectedWorkspace: expectedWsId ?? null,
+    wsVerified: false,
+    nodeMatch: false,
+    binMatch: false,
+  };
+
+  if (!existsSync(dest)) return { state: 'absent', ...empty };
+
+  const content = readFileSync(dest, 'utf-8');
+  if (!content.includes(marker)) return { state: 'foreign', ...empty };
+
+  const nodeMatch = content.includes(`COMPOSE_NODE="${composeNode}"`);
+  const binMatch = content.includes(`COMPOSE_BIN="${composeBin}"`);
+  const hasRawToken = content.includes('__COMPOSE_WORKSPACE_ID__');
+  const bakedWorkspace = extractBakedWorkspaceId(content);
+  // Mirror of statusOne: raw token never matches; a known expected id must match
+  // the baked value; an unknown (null) expected id is treated leniently as a match.
+  const wsMatch = hasRawToken ? false : expectedWsId ? content.includes(`COMPOSE_WORKSPACE_ID="${expectedWsId}"`) : true;
+
+  const base = {
+    bakedWorkspace,
+    expectedWorkspace: expectedWsId ?? null,
+    wsVerified: expectedWsId != null,
+    nodeMatch,
+    binMatch,
+  };
+
+  if (nodeMatch && binMatch && wsMatch && !hasRawToken) {
+    return { state: 'installed-current', reason: null, ...base };
+  }
+  const reason = hasRawToken
+    ? 'MISSING_WORKSPACE_ID'
+    : expectedWsId && !wsMatch
+      ? 'STALE_WORKSPACE_ID'
+      : 'stale paths';
+  return { state: 'installed-stale', reason, ...base };
+}
+
+/**
+ * Reproduce the exact lines `compose hooks status` printed for one hook type.
+ * Returns an array of strings (callers print each with console.log).
+ *
+ * @param {string} type — hook type ('post-commit' | 'pre-push')
+ * @param {HookStatusRaw} s — a single entry from computeHooksStatus
+ * @param {{composeNode: string, composeBin: string}} opts — current env values for the "expected" lines
+ * @returns {string[]}
+ */
+export function formatHookStatusLines(type, s, { composeNode, composeBin }) {
+  if (s.state === 'absent') return [`${type}: absent — no hook installed`];
+  if (s.state === 'foreign') return [`${type}: foreign — hook exists but is not a Compose hook`];
+  if (s.state === 'installed-current') {
+    const lines = [`${type}: installed (current)`];
+    if (s.bakedWorkspace) lines.push(`  workspace: ${s.bakedWorkspace}`);
+    return lines;
+  }
+  // installed-stale
+  const lines = [`${type}: installed (${s.reason} — re-run install)`];
+  if (s.reason === 'STALE_WORKSPACE_ID') lines.push(`  expected COMPOSE_WORKSPACE_ID="${s.expectedWorkspace}"`);
+  if (!s.nodeMatch) lines.push(`  expected COMPOSE_NODE="${composeNode}"`);
+  if (!s.binMatch) lines.push(`  expected COMPOSE_BIN="${composeBin}"`);
+  return lines;
+}
+
+/**
+ * @typedef {object} HookStatusRaw
+ * @property {'absent'|'foreign'|'installed-current'|'installed-stale'} state
+ * @property {null|'MISSING_WORKSPACE_ID'|'STALE_WORKSPACE_ID'|'stale paths'} reason
+ * @property {string|null} bakedWorkspace
+ * @property {string|null} expectedWorkspace
+ * @property {boolean} wsVerified
+ * @property {boolean} nodeMatch
+ * @property {boolean} binMatch
+ */

package/lib/install-agent-defs.js

@@ -0,0 +1,22 @@
+import { existsSync, mkdirSync, readdirSync, copyFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Install Claude Code agent definitions (*.md) from srcDir into destDir.
+ * Idempotent: mkdir -p the dest and overwrite existing files. Returns the list
+ * of installed agent names (filenames sans `.md`). No-op → [] when srcDir is
+ * absent or has no `.md` files. (COMP-AGENT-VENDOR-1 — vendored compose-explorer
+ * / compose-architect were referenced by the skill but never installed.)
+ */
+export function installAgentDefs(srcDir, destDir) {
+  if (!srcDir || !existsSync(srcDir)) return [];
+  const defs = readdirSync(srcDir).filter(f => f.endsWith('.md'));
+  if (defs.length === 0) return [];
+  mkdirSync(destDir, { recursive: true });
+  const installed = [];
+  for (const f of defs) {
+    copyFileSync(join(srcDir, f), join(destDir, f));
+    installed.push(f.replace(/\.md$/, ''));
+  }
+  return installed;
+}

package/lib/migrate-anon.js

@@ -0,0 +1,277 @@
+/**
+ * migrate-anon — COMP-MCP-MIGRATION-2-1-1-1
+ *
+ * `compose migrate-anon`: interactive promotion of historical *anonymous*
+ * ROADMAP rows (the `| — | Item | Status |` form preserved verbatim by
+ * COMP-MCP-MIGRATION-2-1-1) to typed features.
+ *
+ * Load-bearing correctness point: anonymous rows are re-emitted on regen by
+ * `predecessorCode` anchoring, and a row only stops being anonymous when its raw
+ * Feature cell becomes a valid code. So scaffolding a feature.json ALONE leaves
+ * the `—` row passing through verbatim → a DUPLICATE. Promotion therefore strips
+ * the source `rawLine` from ROADMAP.md *before* scaffold+regen.
+ *
+ * `readAnonymousRows` is the canonical classifier for which rows are anonymous +
+ * their order + anchor; this module only adds header-aware cell display and the
+ * strip-then-scaffold primitive on top of it.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+
+import { resolveRoadmapPath, loadFeaturesDir } from './project-paths.js';
+import { readAnonymousRows, PRESERVED_OPEN_RE, PRESERVED_CLOSE_RE } from './roadmap-preservers.js';
+import { splitRoadmapCells, detectColumnLayout } from './roadmap-parser.js';
+import { splitPhaseHeading, PHASE_HEADING_TEXT_RE, parseStatusToken, STATUS_TOKENS } from './roadmap-heading.js';
+import { isFeatureCode } from './feature-code.js';
+import { listFeatures, positionSortKey } from './feature-json.js';
+import { addRoadmapEntry } from './feature-writer.js';
+
+const FENCE_RE = /^```/;
+const TABLE_ROW_RE = /^\|.+\|$/;
+const TABLE_DIVIDER_RE = /^\|[\s|:-]+\|$/;
+
+// Strip markdown bold/code markers so a `**IN_PROGRESS**` or `` `x` `` cell
+// matches the same way the roadmap parser sees it (it bold-strips before parsing).
+// NB: do NOT strip `_` — it's part of the `IN_PROGRESS` status token itself.
+const stripEmphasis = (s) => String(s ?? '').replace(/[*`]/g, '').trim();
+
+/**
+ * Parse anonymous rows for display, header-aware. Classification + raw text +
+ * anchor come from the canonical `readAnonymousRows`; the column layout only
+ * decides which cell is title vs status, and is taken from the **nearest
+ * preceding header** of each row's own table — a phase can hold multiple tables
+ * with different layouts (3-col then 4-col), so a single per-phase header is
+ * wrong. The forward scan mirrors `readAnonymousRows`' table-state reset (a
+ * non-table line or a new heading ends the current table) and matches anon rows
+ * by in-order `rawLine` equality, so classification never drifts and the layout
+ * is display-only (a misread can never affect strip/anchor).
+ *
+ * @param {string} text - ROADMAP.md source
+ * @returns {Array<{phaseId:string, occurrenceIndex:number, num:string, title:string, status:string, rawLine:string, predecessorCode:string|null}>}
+ */
+export function collectAnonRowsFromText(text) {
+  const anonMap = readAnonymousRows(text);
+  const ptr = new Map(); // phaseId → next occurrence index to match
+  const out = [];
+  let inFence = false;
+  let inPreserved = false;
+  let cur = null;
+  let header = null;
+  let inTable = false;
+
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (FENCE_RE.test(trimmed)) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    if (PRESERVED_OPEN_RE.test(trimmed)) { inPreserved = true; inTable = false; header = null; continue; }
+    if (PRESERVED_CLOSE_RE.test(trimmed)) { inPreserved = false; continue; }
+    if (inPreserved) continue;
+
+    const h = line.match(PHASE_HEADING_TEXT_RE);
+    if (h && line.startsWith('## ')) { cur = splitPhaseHeading(h[1]).title; inTable = false; header = null; continue; }
+    if (!cur) continue;
+
+    if (!TABLE_ROW_RE.test(trimmed)) { inTable = false; header = null; continue; }
+    if (!inTable) { header = splitRoadmapCells(line); inTable = true; continue; } // header row
+    if (TABLE_DIVIDER_RE.test(trimmed)) continue;
+
+    // Data row — match against the canonical anon list in document order.
+    const rows = anonMap.get(cur) ?? [];
+    const p = ptr.get(cur) ?? 0;
+    if (p < rows.length && line === rows[p].rawLine) {
+      const layout = detectColumnLayout(header ?? ['#', 'Item', 'Status']);
+      const cells = splitRoadmapCells(line);
+      const num = layout.codeCol >= 0 ? (cells[layout.codeCol] ?? '') : (cells[0] ?? '');
+      const title = stripEmphasis(cells[layout.descCol] ?? '');
+      const status = parseStatusToken(stripEmphasis(cells[layout.statusCol] ?? '')) ?? 'PLANNED';
+      out.push({ phaseId: cur, occurrenceIndex: p, num, title, status, rawLine: line, predecessorCode: rows[p].predecessorCode });
+      ptr.set(cur, p + 1);
+    }
+  }
+  return out;
+}
+
+/**
+ * Locate the physical line index of the `occurrenceIndex`-th anonymous row in a
+ * phase. Forward-scans, consuming `readAnonymousRows`' ordered rawLines so that
+ * identical row text resolves to the correct physical occurrence (no global
+ * string match). Returns -1 if not found.
+ */
+function anonLineIndex(text, phaseId, occurrenceIndex) {
+  const rows = readAnonymousRows(text).get(phaseId) ?? [];
+  if (occurrenceIndex < 0 || occurrenceIndex >= rows.length) return -1;
+  const lines = text.split('\n');
+  let inFence = false;
+  let inPreserved = false;
+  let cur = null;
+  let ptr = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+    if (FENCE_RE.test(trimmed)) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    if (PRESERVED_OPEN_RE.test(trimmed)) { inPreserved = true; continue; }
+    if (PRESERVED_CLOSE_RE.test(trimmed)) { inPreserved = false; continue; }
+    if (inPreserved) continue;
+    const h = line.match(PHASE_HEADING_TEXT_RE);
+    if (h && line.startsWith('## ')) { cur = splitPhaseHeading(h[1]).title; continue; }
+    if (cur === phaseId && ptr < rows.length && line === rows[ptr].rawLine) {
+      if (ptr === occurrenceIndex) return i;
+      ptr++;
+    }
+  }
+  return -1;
+}
+
+/**
+ * Remove the `occurrenceIndex`-th anonymous row of `phaseId` from ROADMAP text.
+ * Phase-scoped and occurrence-specific. Returns the new text (throws if not found).
+ */
+export function stripAnonLine(text, phaseId, occurrenceIndex) {
+  const idx = anonLineIndex(text, phaseId, occurrenceIndex);
+  if (idx === -1) {
+    throw new Error(`migrate-anon: anon row #${occurrenceIndex} not found in phase "${phaseId}"`);
+  }
+  const lines = text.split('\n');
+  lines.splice(idx, 1);
+  return lines.join('\n');
+}
+
+// Best-effort end-of-phase position. Computed with positionSortKey (string-aware),
+// NOT nextPositionInPhase which coerces string/ranged positions to 0.
+async function endOfPhasePosition(cwd, phaseId) {
+  // Config-aware features dir (mirrors addRoadmapEntry) — listFeatures defaults to
+  // docs/features and would otherwise miss relocated feature sets.
+  const peers = (await listFeatures(cwd, loadFeaturesDir(cwd))).filter((f) => f.phase === phaseId);
+  if (peers.length === 0) return 1;
+  const max = peers.reduce((m, f) => Math.max(m, positionSortKey(f.position)), 0);
+  return max + 1;
+}
+
+/**
+ * Promote one anonymous row to a typed feature: strip its rawLine, then scaffold.
+ *
+ * Failure handling keys on the error code, because addRoadmapEntry commits
+ * feature.json BEFORE regenerating ROADMAP.md:
+ *   - pre-commit failures (validation / code-exists / ROUNDTRIP_NOT_FIXED_POINT)
+ *     → restore the stripped snapshot (nothing committed) and rethrow.
+ *   - ROADMAP_PARTIAL_WRITE (feature.json committed, regen failed) → do NOT
+ *     restore (that would re-add the anon row alongside the typed feature = the
+ *     duplicate this flow avoids); rethrow as-is. Re-running reconciles.
+ *
+ * @param {string} cwd
+ * @param {{phaseId:string, occurrenceIndex:number, title:string}} row
+ * @param {{code:string, status?:string, scaffold?:Function}} opts
+ */
+export async function promoteAnonRow(cwd, row, { code, status = 'PLANNED', scaffold = addRoadmapEntry } = {}) {
+  const upper = String(code).toUpperCase();
+  if (!isFeatureCode(upper)) {
+    throw new Error(`migrate-anon: "${code}" is not a valid feature code`);
+  }
+  const roadmapPath = resolveRoadmapPath(cwd);
+  const snapshot = readFileSync(roadmapPath, 'utf-8');
+  const stripped = stripAnonLine(snapshot, row.phaseId, row.occurrenceIndex);
+  writeFileSync(roadmapPath, stripped);
+  try {
+    const position = await endOfPhasePosition(cwd, row.phaseId);
+    return await scaffold(cwd, {
+      code: upper,
+      description: row.title,
+      phase: row.phaseId,
+      status,
+      complexity: 'S',
+      position,
+    });
+  } catch (err) {
+    if (err && err.code === 'ROADMAP_PARTIAL_WRITE') throw err;
+    // Pre-commit failure: nothing was committed — put the anon row back.
+    writeFileSync(roadmapPath, snapshot);
+    throw err;
+  }
+}
+
+/**
+ * Interactive driver. Streams are injectable for testing. Callers (the CLI) own
+ * the non-TTY guard: pass `nonInteractive: true` for piped stdin / --non-interactive
+ * / --dry-run, and this lists the rows without prompting.
+ *
+ * @param {string} cwd
+ * @param {{input?:any, output?:any, nonInteractive?:boolean, dryRun?:boolean, scaffold?:Function}} [opts]
+ * @returns {Promise<{listed:number, promoted:string[], aborted:boolean}>}
+ */
+export async function runMigrateAnon(cwd, opts = {}) {
+  const {
+    input = process.stdin,
+    output = process.stdout,
+    nonInteractive = false,
+    dryRun = false,
+    scaffold = addRoadmapEntry,
+  } = opts;
+  const write = (s) => output.write(s + '\n');
+  const roadmapPath = resolveRoadmapPath(cwd);
+  const rows = collectAnonRowsFromText(readFileSync(roadmapPath, 'utf-8'));
+
+  if (rows.length === 0) {
+    write('migrate-anon: no anonymous rows found.');
+    return { listed: 0, promoted: [], aborted: false };
+  }
+
+  if (nonInteractive || dryRun) {
+    write(`migrate-anon: ${rows.length} anonymous row(s):`);
+    for (const r of rows) write(`  [${r.phaseId}] ${r.title}  (${r.status})`);
+    write('Run interactively in a TTY to promote rows.');
+    return { listed: rows.length, promoted: [], aborted: false };
+  }
+
+  const rl = createInterface({ input, output });
+  const ask = (q) => new Promise((res) => rl.question(q, res));
+  const promoted = [];
+  const promotedByPhase = {};
+  let aborted = false;
+
+  try {
+    for (const row of rows) {
+      write(`\n[${row.phaseId}] ${row.title}`);
+      write(`  inferred status: ${row.status}`);
+
+      // Code prompt (re-prompt on invalid; Enter=skip; q=abort).
+      let code = null;
+      for (;;) {
+        const ans = (await ask('  Code to assign (Enter=skip, q=abort): ')).trim();
+        if (ans === '') break;
+        if (ans.toLowerCase() === 'q') { aborted = true; break; }
+        const c = ans.toUpperCase();
+        if (!isFeatureCode(c)) { write(`  ✗ "${ans}" is not a valid feature code — try again`); continue; }
+        code = c;
+        break;
+      }
+      if (aborted) break;
+      if (!code) continue;
+
+      // Status confirm/override.
+      const sAns = (await ask(`  Status [${row.status}] (Enter=keep, or one of ${STATUS_TOKENS.join('/')}): `)).trim();
+      let status = row.status;
+      if (sAns !== '') {
+        const s = sAns.toUpperCase();
+        if (STATUS_TOKENS.includes(s)) status = s;
+        else write(`  (unrecognized status "${sAns}" — keeping ${row.status})`);
+      }
+
+      const liveIndex = row.occurrenceIndex - (promotedByPhase[row.phaseId] ?? 0);
+      try {
+        await promoteAnonRow(cwd, { ...row, occurrenceIndex: liveIndex }, { code, status, scaffold });
+        promoted.push(code);
+        promotedByPhase[row.phaseId] = (promotedByPhase[row.phaseId] ?? 0) + 1;
+        write(`  ✓ promoted to ${code}`);
+      } catch (err) {
+        write(`  ✗ promotion failed: ${err.message}`);
+        throw err;
+      }
+    }
+  } finally {
+    rl.close();
+  }
+
+  write(`\nmigrate-anon: ${promoted.length} promoted${aborted ? ' (aborted early)' : ''}.`);
+  return { listed: rows.length, promoted, aborted };
+}

package/lib/roadmap-parser.js

@@ -192,7 +192,7 @@ export function parseRoadmap(text) {
  *   3-col: ID | Item | Status            → code=ID, desc=Item
  *   3-col: # | Item | Status             → anonymous (# is a row number, not a code)
  */
-function detectColumnLayout(headerCells) {
+export function detectColumnLayout(headerCells) {
   const lower = headerCells.map(c => c.toLowerCase());
 
   // 4+ columns: look for a Feature column as the code source