@pareto4/pp-core 1.5.0

package/pp-core/bin/lib/roadmap.cjs

@@ -0,0 +1,738 @@
+"use strict";
+/**
+ * Roadmap — Roadmap parsing and update operations
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/roadmap.cjs collapsed
+ * to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
+ * from the prior hand-written .cjs; only strict types are added.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const clock_cjs_1 = require("./clock.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const ioMod = require("./io.cjs");
+const { output, error } = ioMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseIdMod = require("./phase-id.cjs");
+const { escapeRegex, normalizePhaseName, phaseMarkdownRegexSource, phaseMarkdownRegexSourceExact, phaseTokenMatches } = phaseIdMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseLocatorMod = require("./phase-locator.cjs");
+const { findPhaseInternal } = phaseLocatorMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const roadmapParserModule = require("./roadmap-parser.cjs");
+const { stripShippedMilestones, extractCurrentMilestone, replaceInCurrentMilestone } = roadmapParserModule;
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningWorkspace = require("./planning-workspace.cjs");
+const { planningPaths, withPlanningLock, findContextMdIn } = planningWorkspace;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const scanPhasePlans = require("./plan-scan.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const frontmatter = require("./frontmatter.cjs");
+const { extractFrontmatter, parseMustHavesBlock } = frontmatter;
+// ─── coerceTruthToString ──────────────────────────────────────────────────────
+/**
+ * Coerce an arbitrary YAML scalar/object into a string for cross-cutting
+ * truth aggregation. Handles:
+ *   - strings (passthrough)
+ *   - numbers / booleans (String() coercion — issue #2770: bare YAML ints
+ *     like `- 3` must be surfaced, not silently skipped)
+ *   - kv-shaped objects from parseMustHavesBlock continuation kv (issue
+ *     #2757) — extract the first meaningful string field
+ *
+ * Returns the empty string when no usable text can be derived; callers should
+ * skip empty results.
+ */
+function coerceTruthToString(t) {
+    if (t === null || t === undefined)
+        return '';
+    if (typeof t === 'string')
+        return t;
+    if (typeof t === 'number' || typeof t === 'boolean' || typeof t === 'bigint') {
+        return String(t);
+    }
+    if (typeof t === 'object') {
+        // Prefer common title-bearing keys produced by parseMustHavesBlock
+        for (const k of ['title', 'text', 'name', 'rule', 'path', 'provides']) {
+            const v = t[k];
+            if (typeof v === 'string' && v.trim())
+                return v;
+            if (typeof v === 'number' || typeof v === 'boolean')
+                return String(v);
+        }
+    }
+    return '';
+}
+// ─── countPhasePlansAndSummaries ──────────────────────────────────────────────
+function countPhasePlansAndSummaries(phaseDir) {
+    const { planCount, summaryCount } = scanPhasePlans(phaseDir);
+    // hasContext and hasResearch are not plan-scan concerns — read the directory
+    // once and share the listing for all non-plan metadata that cmdRoadmapAnalyze needs.
+    let phaseFiles = [];
+    try {
+        phaseFiles = node_fs_1.default.readdirSync(phaseDir);
+    }
+    catch { /* empty */ }
+    return {
+        planCount,
+        summaryCount,
+        hasContext: findContextMdIn(phaseFiles) !== null,
+        hasResearch: phaseFiles.some(f => f.endsWith('-RESEARCH.md') || f === 'RESEARCH.md'),
+    };
+}
+// `phaseMarkdownRegexSource` lives in phase-id.cjs (#3537) and is imported above.
+// ─── searchPhaseInContent ─────────────────────────────────────────────────────
+/**
+ * Search for a phase header (and its section) within the given content string.
+ * Returns a result object if found (either a full match or a malformed_roadmap
+ * checklist-only match), or null if the phase is not present at all.
+ */
+function searchPhaseInContent(content, escapedPhase, phaseNum) {
+    // Match "## Phase X:", "### Phase X:", or "#### Phase X:" with optional name
+    const phasePattern = new RegExp(`#{2,4}\\s*(?:\\[[^\\]]+\\]\\s*)?Phase\\s+${escapedPhase}:\\s*([^\\n]+)`, 'i');
+    const headerMatch = content.match(phasePattern);
+    if (!headerMatch) {
+        // Fallback: check if phase exists in summary list but missing detail section
+        const checklistPattern = new RegExp(`-\\s*\\[[ x]\\]\\s*\\*\\*Phase\\s+${escapedPhase}:\\s*([^*]+)\\*\\*`, 'i');
+        const checklistMatch = content.match(checklistPattern);
+        if (checklistMatch) {
+            return {
+                found: false,
+                phase_number: phaseNum,
+                phase_name: checklistMatch[1].trim(),
+                error: 'malformed_roadmap',
+                message: `Phase ${phaseNum} exists in summary list but missing "### Phase ${phaseNum}:" detail section. ROADMAP.md needs both formats.`
+            };
+        }
+        return null;
+    }
+    const phaseName = headerMatch[1].trim();
+    const headerIndex = headerMatch.index;
+    // Find the end of this section (next ## or ### phase header, or end of file).
+    // Also matches bracket-prefixed headings like ### [GSD] Phase 2-01:.
+    const restOfContent = content.slice(headerIndex);
+    const nextHeaderMatch = restOfContent.match(/\n#{2,4}\s+(?:\[[^\]]+\]\s*)?Phase\s+[\w][\w.-]*/i);
+    const sectionEnd = nextHeaderMatch
+        ? headerIndex + nextHeaderMatch.index
+        : content.length;
+    const section = content.slice(headerIndex, sectionEnd).trim();
+    // Extract goal if present (supports both **Goal:** and **Goal**: formats)
+    const goalMatch = section.match(/\*\*Goal(?::\*\*|\*\*:)\s*([^\n]+)/i);
+    const goal = goalMatch ? goalMatch[1].trim() : null;
+    // Mode: vertical-MVP slice mode flag. Lowercased + trimmed for canonical
+    // comparison; unrecognized values are preserved verbatim for forward-compat.
+    const modeMatch = section.match(/\*\*Mode(?::\*\*|\*\*:)\s*([^\n]+)/i);
+    const mode = modeMatch ? modeMatch[1].trim().toLowerCase() : null;
+    // Extract success criteria as structured array
+    const criteriaMatch = section.match(/\*\*Success Criteria\*\*[^\n]*:\s*\n((?:\s*\d+\.\s*[^\n]+\n?)+)/i);
+    const success_criteria = criteriaMatch
+        ? criteriaMatch[1].trim().split('\n').map(line => line.replace(/^\s*\d+\.\s*/, '').trim()).filter(Boolean)
+        : [];
+    return {
+        found: true,
+        phase_number: phaseNum,
+        phase_name: phaseName,
+        goal,
+        mode,
+        success_criteria,
+        section,
+    };
+}
+// ─── getRoadmapPhaseWithFallback ──────────────────────────────────────────────
+/**
+ * Two-pass phase lookup that mirrors cmdRoadmapGetPhase's resolution strategy.
+ *
+ * Pass 1: current-milestone slice (extractCurrentMilestone).
+ * Pass 2: full roadmap content (stripShippedMilestones) — covers cross-milestone
+ *         and older frontend phases that are no longer in the current milestone slice.
+ *
+ * Returns the phase section string if found, null if ROADMAP.md is missing,
+ * or throws if ROADMAP.md read fails.
+ *
+ * Used by check-command-router (computeUiPlanGate) so ui-plan-gate uses the SAME
+ * phase resolution as `roadmap.get-phase` — not a milestone-only subset.
+ */
+function getRoadmapPhaseWithFallback(cwd, phaseNum) {
+    const roadmapPath = planningPaths(cwd).roadmap;
+    if (!node_fs_1.default.existsSync(roadmapPath))
+        return null;
+    const rawContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
+    const milestoneContent = extractCurrentMilestone(rawContent, cwd);
+    const fullContent = stripShippedMilestones(rawContent);
+    const exactSource = phaseMarkdownRegexSourceExact(phaseNum);
+    if (exactSource) {
+        const exactMilestone = searchPhaseInContent(milestoneContent, exactSource, phaseNum);
+        if (exactMilestone && !exactMilestone.error)
+            return exactMilestone.section ?? null;
+        const exactFull = searchPhaseInContent(fullContent, exactSource, phaseNum);
+        if (exactFull && !exactFull.error)
+            return exactFull.section ?? null;
+    }
+    const escapedPhase = phaseMarkdownRegexSource(phaseNum);
+    const milestoneResult = searchPhaseInContent(milestoneContent, escapedPhase, phaseNum);
+    const result = (milestoneResult && !milestoneResult.error)
+        ? milestoneResult
+        : searchPhaseInContent(fullContent, escapedPhase, phaseNum) || milestoneResult;
+    if (!result || result.error)
+        return null;
+    return result.section ?? null;
+}
+// ─── cmdRoadmapGetPhase ───────────────────────────────────────────────────────
+function cmdRoadmapGetPhase(cwd, phaseNum, raw) {
+    const roadmapPath = planningPaths(cwd).roadmap;
+    if (!node_fs_1.default.existsSync(roadmapPath)) {
+        output({ found: false, error: 'ROADMAP.md not found' }, raw, '');
+        return;
+    }
+    try {
+        const rawContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
+        const milestoneContent = extractCurrentMilestone(rawContent, cwd);
+        // #3599 two-pass: when the caller passes a project-code-prefixed ID like
+        // `PROJ-42`, try the exact-prefixed heading first (`### Phase PROJ-42:`).
+        // If no match, fall back to the #3537 padding-tolerant numeric form so
+        // a `CK-01` query still resolves to `### Phase 1:`. Doing this at the
+        // call site (instead of inside phaseMarkdownRegexSource) avoids the
+        // alternation-order ambiguity where a bare `### Phase 42:` heading in
+        // the same document would intercept the match for a `PROJ-42` query.
+        const fullContent = stripShippedMilestones(rawContent);
+        const exactSource = phaseMarkdownRegexSourceExact(phaseNum);
+        if (exactSource) {
+            const exactMilestone = searchPhaseInContent(milestoneContent, exactSource, phaseNum);
+            if (exactMilestone && !exactMilestone.error) {
+                output(exactMilestone, raw, exactMilestone.section);
+                return;
+            }
+            const exactFull = searchPhaseInContent(fullContent, exactSource, phaseNum);
+            if (exactFull && !exactFull.error) {
+                output(exactFull, raw, exactFull.section);
+                return;
+            }
+        }
+        // #3537: padding-tolerant fragment so callers passing `02.7` still match
+        // un-padded ROADMAP prose (`### Phase 2.7:`).
+        const escapedPhase = phaseMarkdownRegexSource(phaseNum);
+        // Search the current milestone slice first, then fall back to full roadmap.
+        // A malformed_roadmap result (checklist-only) from the milestone should not
+        // block finding a full header match in the wider roadmap content.
+        const milestoneResult = searchPhaseInContent(milestoneContent, escapedPhase, phaseNum);
+        const result = (milestoneResult && !milestoneResult.error)
+            ? milestoneResult
+            : searchPhaseInContent(fullContent, escapedPhase, phaseNum) || milestoneResult;
+        if (!result) {
+            output({ found: false, phase_number: phaseNum }, raw, '');
+            return;
+        }
+        if (result.error) {
+            output(result, raw, '');
+            return;
+        }
+        output(result, raw, result.section);
+    }
+    catch (e) {
+        error('Failed to read ROADMAP.md: ' + e.message);
+    }
+}
+// ─── cmdRoadmapAnalyze ────────────────────────────────────────────────────────
+function cmdRoadmapAnalyze(cwd, raw) {
+    const roadmapPath = planningPaths(cwd).roadmap;
+    if (!node_fs_1.default.existsSync(roadmapPath)) {
+        output({ error: 'ROADMAP.md not found', milestones: [], phases: [], current_phase: null }, raw, undefined);
+        return;
+    }
+    const rawContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
+    const content = extractCurrentMilestone(rawContent, cwd);
+    const phasesDir = planningPaths(cwd).phases;
+    // Extract all phase headings: ## Phase N: Name or ### Phase N: Name
+    const phasePattern = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+(\d+[A-Z]?(?:[.-]\d+)*)\s*:\s*([^\n]+)/gi;
+    const phases = [];
+    let match;
+    // Build phase directory lookup once (O(1) readdir instead of O(N) per phase)
+    const _phaseDirNames = (() => {
+        try {
+            return node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true })
+                .filter(e => e.isDirectory())
+                .map(e => e.name);
+        }
+        catch {
+            return [];
+        }
+    })();
+    while ((match = phasePattern.exec(content)) !== null) {
+        const phaseNum = match[1];
+        const phaseName = match[2].replace(/\(INSERTED\)/i, '').trim();
+        // Extract goal from the section
+        const sectionStart = match.index;
+        const restOfContent = content.slice(sectionStart);
+        // #3691: `\d` → `\d[\d.]*` so decimal phase headings (e.g. `### Phase 02.3:`) are
+        // recognised as section boundaries.
+        const nextHeader = restOfContent.match(/\n#{2,4}\s+(?:\[[^\]]+\]\s*)?Phase\s+\d[\d.-]*/i);
+        const sectionEnd = nextHeader ? sectionStart + nextHeader.index : content.length;
+        const section = content.slice(sectionStart, sectionEnd);
+        const goalMatch = section.match(/\*\*Goal(?::\*\*|\*\*:)\s*([^\n]+)/i);
+        const goal = goalMatch ? goalMatch[1].trim() : null;
+        const modeMatch = section.match(/\*\*Mode(?::\*\*|\*\*:)\s*([^\n]+)/i);
+        const mode = modeMatch ? modeMatch[1].trim().toLowerCase() : null;
+        const dependsMatch = section.match(/\*\*Depends on(?::\*\*|\*\*:)\s*([^\n]+)/i);
+        const depends_on = dependsMatch ? dependsMatch[1].trim() : null;
+        // Check completion on disk
+        const normalized = normalizePhaseName(phaseNum);
+        let diskStatus = 'no_directory';
+        let planCount = 0;
+        let summaryCount = 0;
+        let hasContext = false;
+        let hasResearch = false;
+        try {
+            const dirMatch = _phaseDirNames.find(d => phaseTokenMatches(d, normalized));
+            if (dirMatch) {
+                const counts = countPhasePlansAndSummaries(node_path_1.default.join(phasesDir, dirMatch));
+                planCount = counts.planCount;
+                summaryCount = counts.summaryCount;
+                hasContext = counts.hasContext;
+                hasResearch = counts.hasResearch;
+                if (summaryCount >= planCount && planCount > 0)
+                    diskStatus = 'complete';
+                else if (summaryCount > 0)
+                    diskStatus = 'partial';
+                else if (planCount > 0)
+                    diskStatus = 'planned';
+                else if (hasResearch)
+                    diskStatus = 'researched';
+                else if (hasContext)
+                    diskStatus = 'discussed';
+                else
+                    diskStatus = 'empty';
+            }
+        }
+        catch { /* intentionally empty */ }
+        // Check ROADMAP checkbox status.
+        // #3537: padding-tolerant fragment — the heading discovered above may use
+        // a different padding than the summary-bullet checkbox below it (mixed
+        // padding inside one ROADMAP is legal and seen in real projects).
+        const checkboxPattern = new RegExp(`-\\s*\\[(x| )\\]\\s*.*Phase\\s+${phaseMarkdownRegexSource(phaseNum)}[:\\s]`, 'i');
+        const checkboxMatch = content.match(checkboxPattern);
+        const roadmapComplete = checkboxMatch ? checkboxMatch[1] === 'x' : false;
+        // If roadmap marks phase complete, trust that over disk file structure.
+        // Phases completed before GSD tracking (or via external tools) may lack
+        // the standard PLAN/SUMMARY pairs but are still done.
+        if (roadmapComplete && diskStatus !== 'complete') {
+            diskStatus = 'complete';
+        }
+        phases.push({
+            number: phaseNum,
+            name: phaseName,
+            goal,
+            mode,
+            depends_on,
+            plan_count: planCount,
+            summary_count: summaryCount,
+            has_context: hasContext,
+            has_research: hasResearch,
+            disk_status: diskStatus,
+            roadmap_complete: roadmapComplete,
+        });
+    }
+    // Extract milestone info
+    const milestones = [];
+    const milestonePattern = /##\s*(.*v(\d+(?:\.\d+)+)[^(\n]*)/gi;
+    let mMatch;
+    while ((mMatch = milestonePattern.exec(content)) !== null) {
+        milestones.push({
+            heading: mMatch[1].trim(),
+            version: 'v' + mMatch[2],
+        });
+    }
+    // Find current and next phase
+    const currentPhase = phases.find(p => p.disk_status === 'planned' || p.disk_status === 'partial') || null;
+    const nextPhase = phases.find(p => p.disk_status === 'empty' || p.disk_status === 'no_directory' || p.disk_status === 'discussed' || p.disk_status === 'researched') || null;
+    // Aggregated stats
+    const totalPlans = phases.reduce((sum, p) => sum + p.plan_count, 0);
+    const totalSummaries = phases.reduce((sum, p) => sum + p.summary_count, 0);
+    const completedPhases = phases.filter(p => p.disk_status === 'complete').length;
+    // Detect phases in summary list without detail sections (malformed ROADMAP)
+    const checklistPattern = /-\s*\[[ x]\]\s*\*\*Phase\s+(\d+[A-Z]?(?:\.\d+)*)/gi;
+    const checklistPhases = new Set();
+    let checklistMatch;
+    while ((checklistMatch = checklistPattern.exec(content)) !== null) {
+        checklistPhases.add(checklistMatch[1]);
+    }
+    const detailPhases = new Set(phases.map(p => p.number));
+    const missingDetails = [...checklistPhases].filter(p => !detailPhases.has(p));
+    const result = {
+        milestones,
+        phases,
+        phase_count: phases.length,
+        completed_phases: completedPhases,
+        total_plans: totalPlans,
+        total_summaries: totalSummaries,
+        progress_percent: totalPlans > 0 ? Math.min(100, Math.round((totalSummaries / totalPlans) * 100)) : 0,
+        current_phase: currentPhase ? currentPhase.number : null,
+        next_phase: nextPhase ? nextPhase.number : null,
+        missing_phase_details: missingDetails.length > 0 ? missingDetails : null,
+    };
+    output(result, raw, undefined);
+}
+// ─── cmdRoadmapUpdatePlanProgress ─────────────────────────────────────────────
+function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
+    if (!phaseNum) {
+        error('phase number required for roadmap update-plan-progress');
+    }
+    const roadmapPath = planningPaths(cwd).roadmap;
+    const phaseInfo = findPhaseInternal(cwd, phaseNum);
+    if (!phaseInfo) {
+        error(`Phase ${phaseNum} not found`);
+    }
+    const planCount = phaseInfo.plans.length;
+    const summaryCount = phaseInfo.summaries.length;
+    if (planCount === 0) {
+        output({ updated: false, reason: 'No plans found', plan_count: 0, summary_count: 0 }, raw, 'no plans');
+        return;
+    }
+    const isComplete = summaryCount >= planCount;
+    const status = isComplete ? 'Complete' : summaryCount > 0 ? 'In Progress' : 'Planned';
+    const today = clock_cjs_1.realClock.today();
+    if (!node_fs_1.default.existsSync(roadmapPath)) {
+        output({ updated: false, reason: 'ROADMAP.md not found', plan_count: planCount, summary_count: summaryCount }, raw, 'no roadmap');
+        return;
+    }
+    // Wrap entire read-modify-write in lock to prevent concurrent corruption
+    withPlanningLock(cwd, () => {
+        let roadmapContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
+        const phasePattern = phaseMarkdownRegexSource(phaseNum);
+        // Progress table row: update Plans/Status/Date columns (handles 4 or 5 column tables)
+        const tableRowPattern = new RegExp(`^(\\|\\s*${phasePattern}\\.?\\s[^|]*(?:\\|[^\\n]*))$`, 'im');
+        roadmapContent = roadmapContent.replace(tableRowPattern, (fullRow) => {
+            const cells = fullRow.split('|').slice(1, -1); // drop leading/trailing empty from split
+            const dateShape = /^\d{4}-\d{2}-\d{2}$/;
+            if (cells.length === 5) {
+                // 5-col: Phase | Milestone | Plans | Status | Completed
+                cells[2] = ` ${summaryCount}/${planCount} `;
+                cells[3] = ` ${status.padEnd(11)}`;
+                // Preserve only a valid ISO date (#1161: idempotent; self-heal garbage)
+                const existingDate5 = cells[4].trim();
+                cells[4] = isComplete
+                    ? (dateShape.test(existingDate5) ? cells[4] : ` ${today} `)
+                    : '  ';
+            }
+            else if (cells.length === 4) {
+                // 4-col: Phase | Plans | Status | Completed
+                cells[1] = ` ${summaryCount}/${planCount} `;
+                cells[2] = ` ${status.padEnd(11)}`;
+                // Preserve only a valid ISO date (#1161: idempotent; self-heal garbage)
+                const existingDate4 = cells[3].trim();
+                cells[3] = isComplete
+                    ? (dateShape.test(existingDate4) ? cells[3] : ` ${today} `)
+                    : '  ';
+            }
+            return '|' + cells.join('|') + '|';
+        });
+        // Update plan count in phase detail section.
+        // Three recognised forms (all tolerated; canonical template uses the first):
+        //   `**Plans**: N plans`  — bold word + outer colon (gsd-core/templates/roadmap.md)
+        //   `**Plans:** N plans`  — bold "Plans:" (colon inside bold)
+        //   `Plans: N plans`      — plain text header
+        const planCountPattern = new RegExp(`(#{2,4}\\s*Phase\\s+${phasePattern}(?=[:\\s])[\\s\\S]*?(?:\\*\\*Plans\\*\\*:|\\*\\*Plans:\\*\\*|(?:^|\\n)Plans:)\\s*)[^\\n]+`, 'i');
+        const planCountText = isComplete
+            ? `${summaryCount}/${planCount} plans complete`
+            : `${summaryCount}/${planCount} plans executed`;
+        roadmapContent = replaceInCurrentMilestone(roadmapContent, planCountPattern, `$1${planCountText}`);
+        // If complete: check checkbox
+        if (isComplete) {
+            const checkboxPattern = new RegExp(`(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${phasePattern}[:\\s][^\\n]*)`, 'i');
+            roadmapContent = replaceInCurrentMilestone(roadmapContent, checkboxPattern, `$1x$2 (completed ${today})`);
+        }
+        // Mark completed plan checkboxes (e.g. "- [ ] 50-01-PLAN.md", "- [ ] 50-01:", or "- [ ] **50-01**")
+        for (const summaryFile of phaseInfo.summaries) {
+            const planId = summaryFile.replace('-SUMMARY.md', '').replace('SUMMARY.md', '');
+            if (!planId)
+                continue;
+            const planEscaped = escapeRegex(planId);
+            const planCheckboxPattern = new RegExp(`(-\\s*\\[) (\\]\\s*(?:\\*\\*)?${planEscaped}(?:\\*\\*)?)`, 'i');
+            roadmapContent = roadmapContent.replace(planCheckboxPattern, '$1x$2');
+        }
+        // Compute the active (post-</details>) region offset ONCE.  Both the
+        // missing-plan DETECTION and the row INSERTION must use the same active
+        // region string so that a plan row that exists only in an archived <details>
+        // block is not counted as "already present" in the active milestone section.
+        // (Finding 1 code-review: detection was previously running against the full
+        //  roadmapContent, causing archived rows to suppress active-section inserts.)
+        const lastDetailsClose = roadmapContent.lastIndexOf('</details>');
+        const activeRegion = lastDetailsClose === -1
+            ? roadmapContent
+            : roadmapContent.slice(lastDetailsClose + '</details>'.length);
+        // Compute which plan files are MISSING a checkbox row in the ACTIVE region.
+        // This handles three cases:
+        //   (a) Fresh template — no rows at all: all plans are missing.
+        //   (b) Partial gap — some rows exist, others don't: only the absent ones.
+        //   (c) All rows present — nothing to insert (idempotent).
+        //
+        // Detection is scoped to the active region so a plan that appears in an
+        // archived <details> block is still correctly detected as missing from the
+        // active milestone section.
+        const missingPlans = phaseInfo.plans.filter((planFile) => {
+            const planEscaped = escapeRegex(planFile);
+            return !new RegExp(`-\\s*\\[[x ]\\]\\s*(?:\\*\\*)?${planEscaped}`, 'i').test(activeRegion);
+        });
+        if (missingPlans.length > 0) {
+            // Insert missing plan checklist rows (#1163).  We prefer to anchor to the
+            // bare `Plans:` checklist header (canonical template form) and fall back to
+            // the bold `**Plans**:`/`**Plans:**` summary line only when no bare header
+            // is present.  Using two separate patterns avoids the lazy-quantifier trap
+            // where a single alternation would stop at the first matching alternative
+            // (the bold summary) before reaching the checklist header.
+            //
+            // Canonical template (gsd-core/templates/roadmap.md) uses BOTH lines:
+            //   **Plans**: N plans   ← summary (colon outside bold)
+            //   Plans:               ← checklist header (PREFERRED insertion anchor)
+            // Rows must land after `Plans:`, not between the summary and the header.
+            //
+            // Pattern A: anchor to bare `Plans:` header (preferred).
+            // Pattern B: fallback to bold summary when no bare header exists.
+            const insertRowsPatternA = new RegExp(`(#{2,4}\\s*Phase\\s+${phasePattern}(?=[:\\s])[\\s\\S]*?(?:^|\\n)(?:Plans:)[^\\n]*)`, 'i');
+            const insertRowsPatternB = new RegExp(`(#{2,4}\\s*Phase\\s+${phasePattern}(?=[:\\s])[\\s\\S]*?(?:\\*\\*Plans\\*\\*:|\\*\\*Plans:\\*\\*)[^\\n]*)`, 'i');
+            const sortedMissing = [...missingPlans].sort();
+            const newRows = sortedMissing.map(p => `- [ ] ${p}`).join('\n');
+            const inserter = (match) => `${match}\n${newRows}`;
+            // Scope insertion to the active (post-</details>) milestone region to
+            // prevent duplicate phase headings in archived sections from receiving rows.
+            // replaceInCurrentMilestone only accepts a string replacement, so we
+            // perform the scoped replace manually here (same strategy as that helper).
+            // Note: lastDetailsClose was computed above (shared with detection).
+            const scopedReplace = (src, pat) => src.replace(pat, inserter);
+            let withRows;
+            if (lastDetailsClose === -1) {
+                // activeRegion === roadmapContent when there are no </details> blocks.
+                const regionA = scopedReplace(activeRegion, insertRowsPatternA);
+                withRows = regionA !== activeRegion ? regionA : scopedReplace(activeRegion, insertRowsPatternB);
+            }
+            else {
+                const beforeDetails = roadmapContent.slice(0, lastDetailsClose + '</details>'.length);
+                const regionA = scopedReplace(activeRegion, insertRowsPatternA);
+                const afterWithRows = regionA !== activeRegion ? regionA : scopedReplace(activeRegion, insertRowsPatternB);
+                withRows = beforeDetails + afterWithRows;
+            }
+            if (withRows !== roadmapContent) {
+                roadmapContent = withRows;
+                // Mark any newly-inserted rows that already have summaries as complete
+                for (const summaryFile of phaseInfo.summaries) {
+                    const planId = summaryFile.replace('-SUMMARY.md', '').replace('SUMMARY.md', '');
+                    if (!planId)
+                        continue;
+                    const planEscaped = escapeRegex(planId);
+                    const planCheckboxPattern = new RegExp(`(-\\s*\\[) (\\]\\s*(?:\\*\\*)?${planEscaped}(?:\\*\\*)?)`, 'i');
+                    roadmapContent = roadmapContent.replace(planCheckboxPattern, '$1x$2');
+                }
+            }
+        }
+        (0, shell_command_projection_cjs_1.platformWriteSync)(roadmapPath, roadmapContent);
+    });
+    output({
+        updated: true,
+        phase: phaseNum,
+        plan_count: planCount,
+        summary_count: summaryCount,
+        status,
+        complete: isComplete,
+    }, raw, `${summaryCount}/${planCount} ${status}`);
+}
+// ─── cmdRoadmapAnnotateDependencies ───────────────────────────────────────────
+/**
+ * Annotate the ROADMAP.md plan list for a phase with wave dependency notes
+ * and a cross-cutting constraints subsection derived from PLAN frontmatter.
+ *
+ * Wave dependency notes: "Wave 2 — blocked on Wave 1 completion" inserted as
+ * bold headers before each wave group in the plan checklist.
+ *
+ * Cross-cutting constraints: must_haves.truths strings that appear in 2+ plans
+ * are surfaced in a "Cross-cutting constraints" subsection below the plan list.
+ *
+ * The operation is idempotent: if wave headers already exist in the section
+ * the function returns without modifying the file.
+ */
+function cmdRoadmapAnnotateDependencies(cwd, phaseNum, raw) {
+    if (!phaseNum) {
+        error('phase number required for roadmap annotate-dependencies');
+    }
+    const roadmapPath = planningPaths(cwd).roadmap;
+    if (!node_fs_1.default.existsSync(roadmapPath)) {
+        output({ updated: false, reason: 'ROADMAP.md not found' }, raw, 'no roadmap');
+        return;
+    }
+    const phaseInfo = findPhaseInternal(cwd, phaseNum);
+    if (!phaseInfo || phaseInfo.plans.length === 0) {
+        output({ updated: false, reason: 'no plans found for phase', phase: phaseNum }, raw, 'no plans');
+        return;
+    }
+    // Read each PLAN.md and extract wave + must_haves.truths
+    const planData = [];
+    for (const planFile of phaseInfo.plans) {
+        const planPath = node_path_1.default.join(node_path_1.default.resolve(cwd, phaseInfo.directory), planFile);
+        try {
+            const content = node_fs_1.default.readFileSync(planPath, 'utf-8');
+            const fm = extractFrontmatter(content);
+            const wave = parseInt(fm.wave, 10) || 1;
+            const planId = planFile.replace(/-PLAN\.md$/i, '').replace(/PLAN\.md$/i, '');
+            const truths = parseMustHavesBlock(content, 'truths') || [];
+            planData.push({ planFile, planId, wave, truths });
+        }
+        catch { /* skip unreadable plans */ }
+    }
+    if (planData.length === 0) {
+        output({ updated: false, reason: 'could not read plan frontmatter' }, raw, 'no frontmatter');
+        return;
+    }
+    // Group plans by wave (sorted)
+    const waveGroups = new Map();
+    for (const p of planData) {
+        if (!waveGroups.has(p.wave))
+            waveGroups.set(p.wave, []);
+        waveGroups.get(p.wave).push(p);
+    }
+    const waves = [...waveGroups.keys()].sort((a, b) => a - b);
+    // Find cross-cutting truths: appear in 2+ plans (de-duplicated, case-insensitive).
+    //
+    // Issue #2770: must **coerce, not skip**. A previous guard
+    // `if (typeof t !== 'string') continue` silently dropped numeric scalars
+    // (YAML ints like `- 3`) and kv-shaped truths (`- title: X`), so the
+    // cross-cutting analysis lost real constraints rather than crashing on
+    // `t.trim()`. We coerce primitives via `String(t)` and extract a sensible
+    // string field from object-shaped items produced by parseMustHavesBlock's
+    // continuation-kv path (issue #2757 produces those shapes for nested keys).
+    const truthCounts = new Map();
+    for (const { truths } of planData) {
+        const seen = new Set();
+        for (const t of truths) {
+            const text = coerceTruthToString(t);
+            if (!text)
+                continue;
+            const trimmed = text.trim();
+            const key = trimmed.toLowerCase();
+            if (!key || seen.has(key))
+                continue;
+            seen.add(key);
+            if (!truthCounts.has(key))
+                truthCounts.set(key, { count: 0, text: trimmed });
+            truthCounts.get(key).count++;
+        }
+    }
+    const crossCuttingTruths = [...truthCounts.values()]
+        .filter(v => v.count >= 2)
+        .map(v => v.text);
+    // Patch ROADMAP.md
+    let updated = false;
+    withPlanningLock(cwd, () => {
+        const content = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
+        // Find the phase section.
+        // #3537: padding-tolerant fragment so the caller's resolved padded id
+        // matches un-padded ROADMAP headings.
+        const phaseEscaped = phaseMarkdownRegexSource(phaseNum);
+        const phaseHeaderPattern = new RegExp(`(#{2,4}\\s*Phase\\s+${phaseEscaped}:[^\\n]*)`, 'i');
+        const phaseMatch = content.match(phaseHeaderPattern);
+        if (!phaseMatch)
+            return;
+        const phaseStart = phaseMatch.index;
+        const restAfterHeader = content.slice(phaseStart);
+        const nextPhaseOffset = restAfterHeader.slice(1).search(/\n#{2,4}\s+Phase\s+\d/i);
+        const phaseEnd = nextPhaseOffset >= 0 ? phaseStart + 1 + nextPhaseOffset : content.length;
+        const phaseSection = content.slice(phaseStart, phaseEnd);
+        // Idempotency: skip if annotation markers already present
+        if (/\*\*Wave\s+\d+/i.test(phaseSection) ||
+            /\*\*Cross-cutting constraints:\*\*/i.test(phaseSection))
+            return;
+        // Find the Plans: section within the phase section.
+        // #3691 Bug 1: `Plans:\s*\n` required no text after the colon, missing variants like
+        // `Plans: 3 plans across 2 waves\n` or `**Plans:** 3 plans\n` (bold-wrapped).
+        // `\*{0,2}Plans\*{0,2}:[^\n]*\n` accepts any text (or none) after the colon
+        // and tolerates optional `**` markdown bold wrappers on either side.
+        // The checklist group uses `+` (not `*`) so that a bold `**Plans:**` description
+        // line with no immediately-following checklist items (e.g. a summary line above a
+        // separate bare `Plans:` block) does not consume the match and prevent the actual
+        // list from being found.
+        // Review fix (F2): `(?:^|\n)` anchors the match to start-of-line so mid-line
+        // occurrences like `***Plans:***` embedded in a sentence or `OpenPlans: foo`
+        // do not trigger a false match. Groups 1 and 2 retain the same semantics.
+        const plansBlockMatch = phaseSection.match(/(?:^|\n)(\*{0,2}Plans\*{0,2}:[^\n]*\n)((?:\s*-\s*\[[ x]\][^\n]*\n?)+)/i);
+        if (!plansBlockMatch)
+            return;
+        const plansHeader = plansBlockMatch[1];
+        const existingList = plansBlockMatch[2];
+        const listLines = existingList.split('\n').filter(l => /^\s*-\s*\[/.test(l));
+        if (listLines.length === 0)
+            return;
+        // #314 perf: build a first-wins Map so per-line lookup is O(1) instead of O(plans).
+        // First-wins mirrors .find() semantics: if the same planId appears more than once
+        // in planData, the earlier entry wins — identical to what .find() returned before.
+        const planById = new Map();
+        for (const p of planData) {
+            if (!planById.has(p.planId))
+                planById.set(p.planId, p);
+        }
+        // Build wave-annotated plan list
+        const linesByWave = new Map();
+        for (const line of listLines) {
+            // Match plan ID from line: "- [ ] 01-01-PLAN.md — ..." or "- [ ] 01-01: ..."
+            // #3691 Bug 3: `[\w-]+?` excluded `.`, so decimal IDs like `02.3-01` were captured
+            // as `02` only and never matched planData entries. `[\w.-]+?` preserves the
+            // terminating alternation (`-PLAN.md|.md|:|\s—`) as the boundary anchor.
+            const idMatch = line.match(/\[\s*[x ]\s*\]\s*([\w.-]+?)(?:-PLAN\.md|\.md|:|\s—)/i);
+            const planId = idMatch ? idMatch[1] : null;
+            // Review fix (F3): reject malformed IDs that start with `.`, contain consecutive
+            // dots, or otherwise violate the `^\w[\w.-]*$` contract. A leading-dot ID
+            // (e.g. `.invalid-PLAN.md`) would silently default to wave 1 — defensively
+            // skip the line instead so corrupted ROADMAP entries don't corrupt wave layout.
+            if (planId && !/^\w[\w.-]*$/.test(planId))
+                continue;
+            const planEntry = planId ? (planById.get(planId) || null) : null;
+            const wave = planEntry ? planEntry.wave : 1;
+            if (!linesByWave.has(wave))
+                linesByWave.set(wave, []);
+            linesByWave.get(wave).push(line);
+        }
+        const annotatedLines = [];
+        const sortedWaves = [...linesByWave.keys()].sort((a, b) => a - b);
+        for (let i = 0; i < sortedWaves.length; i++) {
+            const w = sortedWaves[i];
+            const waveLines = linesByWave.get(w);
+            if (sortedWaves.length > 1) {
+                const dep = i > 0 ? ` *(blocked on Wave ${sortedWaves[i - 1]} completion)*` : '';
+                annotatedLines.push(`**Wave ${w}**${dep}`);
+            }
+            annotatedLines.push(...waveLines);
+            if (i < sortedWaves.length - 1)
+                annotatedLines.push('');
+        }
+        // Append cross-cutting constraints subsection if any found
+        if (crossCuttingTruths.length > 0) {
+            annotatedLines.push('');
+            annotatedLines.push('**Cross-cutting constraints:**');
+            for (const t of crossCuttingTruths) {
+                annotatedLines.push(`- ${t}`);
+            }
+        }
+        const newListBlock = annotatedLines.join('\n') + '\n';
+        // #1103: when `(?:^|\n)` consumed a leading `\n` (mid-string match), re-emit it
+        // so the line preceding the Plans: header is not fused onto it.
+        const leadingNewline = plansBlockMatch[0].startsWith('\n') ? '\n' : '';
+        const newPhaseSection = phaseSection.replace(plansBlockMatch[0], leadingNewline + plansHeader + newListBlock);
+        const nextContent = content.slice(0, phaseStart) + newPhaseSection + content.slice(phaseEnd);
+        if (nextContent === content)
+            return;
+        (0, shell_command_projection_cjs_1.platformWriteSync)(roadmapPath, nextContent);
+        updated = true;
+    });
+    output({
+        updated,
+        phase: phaseNum,
+        waves: waves.length,
+        cross_cutting_constraints: crossCuttingTruths.length,
+    }, raw, updated ? `annotated ${waves.length} wave(s), ${crossCuttingTruths.length} constraint(s)` : 'skipped (already annotated or no plan list)');
+}
+module.exports = {
+    cmdRoadmapGetPhase,
+    getRoadmapPhaseWithFallback,
+    cmdRoadmapAnalyze,
+    cmdRoadmapUpdatePlanProgress,
+    cmdRoadmapAnnotateDependencies,
+};