@opengsd/gsd-core 1.19.0 → 1.20.0

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

@@ -13,25 +13,29 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const clock_cjs_1 = require("./clock.cjs");
 const pattern_cjs_1 = require("./pattern.cjs");
+const phase_entry_grammar_cjs_1 = require("./phase-entry-grammar.cjs");
 const text_lines_cjs_1 = require("./text-lines.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
 const { output, error, formatDiagnosticToken, declineNoOp } = ioMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
-const { normalizePhaseName, phaseMarkdownRegexSource, matchPhaseDirs, stripProjectCodePrefix, OPTIONAL_PHASE_TAG_SOURCE, roadmapPhaseLookupSources, phaseHeadingPrefixSrcFor, PHASE_HEADING_BASELINE, isSentinelPhaseId, scopeToPhase, bracketQualifiedKey, foldBracketId } = phaseIdMod;
+const { phaseMarkdownRegexSource, stripProjectCodePrefix, OPTIONAL_PHASE_TAG_SOURCE, roadmapPhaseLookupSources, phaseHeadingPrefixSrcFor, PHASE_HEADING_BASELINE, isSentinelPhaseId, scopeToPhase, bracketQualifiedKey, foldBracketId } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseLocatorMod = require("./phase-locator.cjs");
-const { findPhaseInternal, listMilestonePhaseDirs, listAllPhaseDirs } = phaseLocatorMod;
+const { phaseDirectoryOptions, findPhaseInternal, listMilestonePhaseDirs, listAllPhaseDirs, resolvePhaseDirectoryLookup, matchPhaseDirsForLookup, } = phaseLocatorMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningScopeMod = require("./planning-scope.cjs");
 const { SCOPE } = planningScopeMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapParserModule = require("./roadmap-parser.cjs");
-const { stripShippedMilestones, extractCurrentMilestone, extractCurrentMilestoneScoped, replaceInCurrentMilestone, listMilestoneHeadings, scanMilestonePhaseIds, collectTablePhaseRows, hasPhaseListingTableHeader } = roadmapParserModule;
+const { stripShippedMilestones, extractCurrentMilestone, extractCurrentMilestoneScoped, checklistBulletExtent, phaseChecklistBullet: phaseChecklistBulletFor, withPhaseSection, listMilestoneHeadings, scanMilestonePhaseIds, collectTablePhaseRows, hasPhaseListingTableHeader } = roadmapParserModule;
+/** Every phase-list entry line, any phase: the rows between two of them belong to the first. */
+const ANY_PHASE_ENTRY_LINE = (0, phase_entry_grammar_cjs_1.phaseEntryRegExp)('Phase[ \\t][^\\r\\n]*$', 'gi');
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 const markdown_table_cjs_1 = require("./markdown-table.cjs");
 const phase_lifecycle_cjs_1 = require("./phase-lifecycle.cjs");
+const roadmap_progress_cjs_1 = require("./roadmap-progress.cjs");
 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");
@@ -154,7 +158,7 @@ function searchPhaseInContent(content, escapedPhase, phaseNum, convention) {
         // Fallback: check if phase exists in summary list but missing detail section
         // A BARE `Phase\s+` at base — takes the label-only baseline, so a bracket
         // repo gains the bracket-ID form and nothing else.
-        const checklistPattern = new RegExp(`-\\s*\\[[ x]\\]\\s*\\*\\*${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY, convention)}${escapedPhase}${OPTIONAL_PHASE_TAG_SOURCE}:\\s*([^*]+)\\*\\*`, 'i');
+        const checklistPattern = (0, phase_entry_grammar_cjs_1.phaseEntryRegExp)(`${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY, convention)}${escapedPhase}${OPTIONAL_PHASE_TAG_SOURCE}:\\s*([^*]+?)${phase_entry_grammar_cjs_1.PHASE_ENTRY_BOLD_CLOSE_SRC}`, 'i', { bold: 'required' });
         const checklistMatch = content.match(checklistPattern);
         if (checklistMatch) {
             return {
@@ -354,7 +358,7 @@ const occurrenceKey = (num, bracketId) => {
  * `cmdRoadmapAnalyze`'s former inline loop so the fallback re-runs the EXACT
  * same enrichment, not a second derivation.
  */
-function collectAnalyzePhases(content, phasesDir, phaseDirNames, convention) {
+function collectAnalyzePhases(cwd, content, phasesDir, phaseDirNames, convention, directoryContext) {
     // Extract all phase headings: ## Phase N: Name or ### Phase N: Name
     // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
     // #612: CAPTURING intro under the bracket convention — group 1 is the
@@ -375,7 +379,7 @@ function collectAnalyzePhases(content, phasesDir, phaseDirNames, convention) {
     // (src/markdown-sectionizer.cts:453) so a legitimately-indented heading that
     // matched before this fix still matches after it.
     // phase-id-owner: uses the [.-] (dot-or-dash) separator variant, not the canonical dot-only token; a swap to PHASE_NUMBER_TOKEN_SOURCE would drop hyphenated phase-id matches.
-    const phasePattern = new RegExp(`^ {0,3}#{2,4}\\s*${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.ANY_BRACKET, convention, true)}([A-Za-z]?\\d+[A-Z]?(?:[.-]\\d+)*)(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:\\s*([^\\n]+)`, 'gim');
+    const phasePattern = new RegExp(`^ {0,3}#{2,4}\\s*${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.ANY_BRACKET, convention, true)}(${directoryContext.phaseNaming === 'custom' && convention !== 'bracket' ? phaseIdMod.phaseScanTokenSource(directoryContext) : '[A-Za-z]?\\d+[A-Z]?(?:[.-]\\d+)*'})(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:\\s*([^\\n]+)`, 'gim');
     // The capturing intro inserts the bracket id at group 1 only under the
     // bracket convention; the token and name shift by the same offset.
     const G = convention === 'bracket' ? 1 : 0;
@@ -413,7 +417,7 @@ function collectAnalyzePhases(content, phasesDir, phaseDirNames, convention) {
         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);
+        const lookup = resolvePhaseDirectoryLookup(cwd, phaseNum, undefined, directoryContext);
         let diskStatus = phase_status_cjs_1.DISK_STATUS.NO_DIRECTORY;
         let planCount = 0;
         let summaryCount = 0;
@@ -447,9 +451,9 @@ function collectAnalyzePhases(content, phasesDir, phaseDirNames, convention) {
         // That is verbatim the asymmetry the note above the W026 rule says this PR
         // closed — the directory read widens with the heading read, or every bracket
         // phase resolves to nothing.
-        // Upstream centralized this choice in `matchPhaseDirs`; thread the same
-        // convention into that owner rather than reviving the primitive `.find()`.
-        const dirMatch = matchPhaseDirs(phaseDirNames, normalized, convention).matches[0];
+        // The locator adapter applies the canonical bracket spelling first and the
+        // migration-window legacy spelling only when the canonical pass misses.
+        const dirMatch = matchPhaseDirsForLookup(phaseDirNames, lookup, undefined, directoryContext).matches[0];
         if (dirMatch) {
             const counts = countPhasePlansAndSummaries(node_path_1.default.join(phasesDir, dirMatch), convention);
             planCount = counts.planCount;
@@ -494,9 +498,9 @@ function collectAnalyzePhases(content, phasesDir, phaseDirNames, convention) {
         // checkbox — no passing `*-VERIFICATION.md`, plans outstanding — now
         // reports incomplete; this is the deliberate Tier-2 break (ADR-3180 §7.4
         // Decision 3).
-        const checkboxPattern = new RegExp(`^[ \\t]*-[ \\t]*\\[(x| )\\][ \\t]*(?:\\*\\*)?${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY, convention)}${phaseMarkdownRegexSource(phaseNum)}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s]`, 'im');
+        const checkboxPattern = (0, phase_entry_grammar_cjs_1.phaseEntryRegExp)(`${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY, convention)}${phaseMarkdownRegexSource(phaseNum, directoryContext)}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s]`, 'im', { state: 'captured' });
         const checkboxMatch = content.match(checkboxPattern);
-        const roadmapComplete = checkboxMatch ? checkboxMatch[1] === 'x' : false;
+        const roadmapComplete = checkboxMatch ? (0, phase_entry_grammar_cjs_1.isBoxCharChecked)(checkboxMatch[1]) : false;
         const headingPhase = {
             number: phaseNum,
             name: phaseName,
@@ -528,7 +532,8 @@ function collectAnalyzePhases(content, phasesDir, phaseDirNames, convention) {
         detailKeys.add(occurrenceKey(tr.id));
         if (seen.has(stripPadA(tr.id)))
             continue;
-        const dirMatchA = matchPhaseDirs(phaseDirNames, normalizePhaseName(tr.id), convention).matches[0];
+        const tableLookup = resolvePhaseDirectoryLookup(cwd, tr.id, undefined, directoryContext);
+        const dirMatchA = matchPhaseDirsForLookup(phaseDirNames, tableLookup, undefined, directoryContext).matches[0];
         let tPlanCount = 0;
         let tSummaryCount = 0;
         let tHasContext = false;
@@ -588,6 +593,7 @@ function cmdRoadmapAnalyze(cwd, raw) {
     const phasesDir = planningPaths(cwd).phases;
     // #612: resolve once per command and thread the same reading through both
     // the scoped scan and any fallback scan.
+    const directoryContext = phaseDirectoryOptions(cwd, undefined, rawContent);
     const convention = resolvePhaseIdConvention(cwd);
     const G = convention === 'bracket' ? 1 : 0;
     // Build phase directory lookup once (O(1) readdir instead of O(N) per phase)
@@ -605,7 +611,7 @@ function cmdRoadmapAnalyze(cwd, raw) {
     // Scan the scoped milestone window for phase-detail headings and enrich each
     // with its on-disk status. Extracted into `collectAnalyzePhases` (#3165) so
     // the SAME enrichment re-runs on the fallback below — not a second copy.
-    let collected = collectAnalyzePhases(content, phasesDir, _phaseDirNames, convention);
+    let collected = collectAnalyzePhases(cwd, content, phasesDir, _phaseDirNames, convention, directoryContext);
     let phases = collected.phases;
     let detailKeys = collected.detailKeys;
     // #5118: carried from every phaseStatus read this command makes.
@@ -631,7 +637,7 @@ function cmdRoadmapAnalyze(cwd, raw) {
     // populated, flagged result.
     if (phases.length === 0 && scope !== SCOPE.COMPLETE && _phaseDirNames.length > 0) {
         const fallbackContent = stripShippedMilestones(rawContent);
-        const fallbackCollection = collectAnalyzePhases(fallbackContent, phasesDir, _phaseDirNames, convention);
+        const fallbackCollection = collectAnalyzePhases(cwd, fallbackContent, phasesDir, _phaseDirNames, convention, directoryContext);
         if (fallbackCollection.phases.length > 0) {
             collected = fallbackCollection;
             phases = collected.phases;
@@ -664,7 +670,8 @@ function cmdRoadmapAnalyze(cwd, raw) {
     // phase-id-owner: uses the [.-] (dot-or-dash) separator variant, not the canonical dot-only token; a swap to PHASE_NUMBER_TOKEN_SOURCE would drop hyphenated phase-id matches.
     // #3036: widen to accept non-numeric-leading ids (same widening as the detail-heading pattern above).
     // phase-id-owner: uses the [.-] (dot-or-dash) separator variant, not the canonical dot-only token; a swap to PHASE_NUMBER_TOKEN_SOURCE would drop hyphenated phase-id matches.
-    const checklistPattern = new RegExp(`-\\s*\\[[ x]\\]\\s*\\*\\*${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY, convention, true)}([A-Za-z]?\\d+[A-Z]?(?:[.-]\\d+)*)`, 'gi');
+    const customIds = directoryContext.phaseNaming === 'custom' && convention !== 'bracket';
+    const checklistPattern = new RegExp(checklistEntrySrc(convention, true, customIds), 'gim');
     // #2761 M1: an OCCURRENCE list keyed by `occurrenceKey`, not a token->bracket
     // map. The map was first-wins on the bare token, so of two checklist entries
     // sharing a token across brackets the FIRST one's bracket id classified BOTH:
@@ -687,7 +694,7 @@ function cmdRoadmapAnalyze(cwd, raw) {
         // `checklistPattern` — adding one would shift every downstream `1 + G` /
         // `G` index this loop and `missingDetails` below already depend on.
         // Reading it off the full match text instead is index-safe.
-        checklistOccurrences.push({ token, bracketId, checked: /\[x\]/i.test(checklistMatch[0]) });
+        checklistOccurrences.push({ token, bracketId, checked: (0, phase_entry_grammar_cjs_1.isPhaseEntryChecked)(checklistMatch[0]) });
     }
     // #4899: `collectAnalyzePhases` only recognises `### Phase N:` headings and
     // progress-table rows — the shape `templates/roadmap.md` itself emits
@@ -724,8 +731,8 @@ function cmdRoadmapAnalyze(cwd, raw) {
         for (const occ of checklistOccurrences) {
             if (isSentinelPhase(occ.token, occ.bracketId))
                 continue;
-            const normalized = normalizePhaseName(occ.token);
-            const dirMatch = matchPhaseDirs(_phaseDirNames, normalized, convention).matches[0];
+            const checklistLookup = resolvePhaseDirectoryLookup(cwd, occ.token, undefined, directoryContext);
+            const dirMatch = matchPhaseDirsForLookup(_phaseDirNames, checklistLookup, undefined, directoryContext).matches[0];
             let diskStatus = 'no_directory';
             let planCount = 0;
             let summaryCount = 0;
@@ -829,6 +836,54 @@ function cmdRoadmapAnalyze(cwd, raw) {
         plan_count: p.plan_count,
         summary_count: p.summary_count,
     }));
+    // #5221: ship's completeness gate. Phase number (zero-padding folded per segment, as ship.md's `n`)
+    // -> true only when EVERY record of it reads complete: each checklist entry (any bracket — a shared
+    // token fails closed) and the phase-table Status cell. Absent = no record. The table is read from the
+    // exact slice `update-plan-progress` writes (editProgressTableSlice), so reader and writer agree.
+    const roadmapRecord = {};
+    const fold = (token, done) => {
+        const k = foldPhaseId(token);
+        roadmapRecord[k] = (roadmapRecord[k] ?? true) && done;
+    };
+    for (const o of checklistOccurrences)
+        if (!isSentinelPhase(o.token, o.bracketId))
+            fold(o.token, o.checked);
+    // phase_naming: custom ids (`- [ ] **Phase AUTH: …**`, as phase add writes them) are records too.
+    const isCustomId = (t) => customIds && !/^[A-Za-z]?\d/.test(t);
+    if (customIds) {
+        for (const m of effectiveContent.matchAll(new RegExp(checklistEntrySrc(convention, false, true), 'gim'))) {
+            if (isCustomId(m[1]))
+                fold(m[1], (0, phase_entry_grammar_cjs_1.isPhaseEntryChecked)(m[0]));
+        }
+    }
+    // A phase table that does not parse (e.g. a ragged row) makes the record unknown: null, so ship stops.
+    let tableUnreadable = false;
+    const archivedForRecord = roadmapParserModule.maskArchivedDetails(rawContent, cwd);
+    editProgressTableSlice(archivedForRecord.visible, (scoped) => {
+        // Same table the writer picks (findPhaseTableHeader); a slice without a Plans column keeps the whole-slice Phase + Status scan.
+        const planned = findPhaseTableHeader(scoped);
+        const header = planned !== -1 ? planned : scoped.search(/^[ \t]*(?=.*\|[ \t]*Phase[ \t]*\|)(?=.*\|[ \t]*Status[ \t]*\|)\|.*$/m);
+        if (header === -1)
+            return scoped;
+        const table = (0, markdown_table_cjs_1.parseMarkdownTable)(scoped.slice(header));
+        // A phase table whose Phase/Status headers are not recognised (other case or wording) is unknown: null, so ship stops.
+        if (!table.ok || !table.value.columns.includes('Phase') || !table.value.columns.includes('Status')) {
+            tableUnreadable = true;
+            return scoped;
+        }
+        const wantMilestone = table.value.columns.includes('Milestone')
+            ? (0, roadmap_progress_cjs_1.normalizeMilestoneToken)(roadmapParserModule.getMilestoneInfo(cwd).value?.version)
+            : null;
+        for (const r of table.value.rows) {
+            if (wantMilestone !== null && (wantMilestone === '' || (0, roadmap_progress_cjs_1.normalizeMilestoneToken)(r['Milestone']) !== wantMilestone))
+                continue;
+            const cell = (r['Phase'] ?? '').trim();
+            const token = cell.match(/^[A-Za-z]?\d\S*?(?=\.?(?:\s|$))/)?.[0] ?? cell.match(new RegExp(`^${CUSTOM_PHASE_ID_SRC}?(?=\\.?(?:\\s|$))`))?.[0];
+            if (token && (/^[A-Za-z]?\d/.test(token) ? !isSentinelPhase(token) : isCustomId(token)))
+                fold(token, (0, phase_status_cjs_1.parseRoadmapStatusCell)(r['Status']) === phase_status_cjs_1.WIRE_STATUS.COMPLETE);
+        }
+        return scoped;
+    }, archivedForRecord.activeRange);
     const result = {
         milestones,
         phases,
@@ -859,6 +914,7 @@ function cmdRoadmapAnalyze(cwd, raw) {
         // #4757: phases whose ROADMAP checkbox disagrees with `disk_status`
         // (`roadmap_complete` vs `disk_status === "complete"`); always an array.
         checkbox_conflict: checkboxConflict,
+        roadmap_record: tableUnreadable ? null : roadmapRecord,
         missing_phase_details: missingDetails.length > 0 ? missingDetails : null,
         // #3184/#3165: distinguishes a genuinely empty milestone (`scope:
         // "complete"`, `phase_count: 0`) from a window that could not be fully
@@ -932,14 +988,57 @@ function cmdRoadmapMilestoneScope(cwd, raw) {
     output({ scope, phases, phase_count: phases.length }, raw, undefined);
 }
 // ─── cmdRoadmapUpdatePlanProgress ─────────────────────────────────────────────
+/** #5221: phase-id fold (leading zeros stripped per segment) keying roadmap_record; ship.md's jq `def n` folds identically (pinned by a test). */
+function foldPhaseId(token) {
+    return token.split('.').map((s) => s.replace(/^0+(?=\d)/, '')).join('.');
+}
+/** #5221: whether offset `idx` of `text` sits inside a bare <details> block (an open-attribute wrapper is the active milestone, not shipped) that has not closed. */
+function insideOpenDetails(text, idx) {
+    const prior = text.slice(0, idx).toLowerCase();
+    return prior.lastIndexOf('<details>') > prior.lastIndexOf('</details>');
+}
+/** #5221: a `phase_naming: custom` id (`Phase AUTH:`). */
+const CUSTOM_PHASE_ID_SRC = '[A-Za-z][\\w-]{0,63}';
+/**
+ * #5221: source of a `- [ ] **Phase N:` checklist entry, the one shape `roadmap analyze` reads and
+ * phase add/insert anchor on. Token is the last group; `custom` also admits a custom id before `:`.
+ */
+function checklistEntrySrc(convention, capturing = false, custom = false) {
+    // phase-id-owner: uses [.-] (dot-or-dash) separator variant, not the canonical dot-only token; swapping to PHASE_NUMBER_TOKEN_SOURCE would drop hyphenated phase-id matches.
+    const numeric = '[A-Za-z]?\\d+[A-Z]?(?:[.-]\\d+)*';
+    // numeric must end at a word edge, else `P1-setup` matches as `P1` before the custom alternative is tried.
+    const token = custom ? `(?:${numeric}(?![\\w-])|${CUSTOM_PHASE_ID_SRC}(?=:))` : numeric;
+    return `${(0, phase_entry_grammar_cjs_1.phaseEntryPrefixSrc)({ bold: 'required' })}${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY, convention, capturing)}(${token})`;
+}
+/**
+ * #5221: offset of the phase table's header row — the first table row whose cells
+ * name `Phase` and `Plans Complete` (or `Plans`), compared case-insensitively. The one
+ * predicate `editFromPhaseTable` (writer) and `roadmap analyze`'s `roadmap_record` (reader)
+ * both pick the table by, so they never disagree on which table is the phase table. -1: none.
+ */
+function findPhaseTableHeader(text) {
+    for (const m of text.matchAll(/^[ \t]*\|.*$/gm)) {
+        const cells = m[0].split('|').map((c) => c.trim().toLowerCase());
+        if (cells.includes('phase') && (cells.includes('plans complete') || cells.includes('plans')))
+            return m.index;
+    }
+    return -1;
+}
+function editFromPhaseTable(scoped, edit) {
+    // #5221: Status/Completed bind to the first table carrying that column; start
+    // at the phase table so an earlier versions table is never the target. A Progress
+    // slice with no Plans column at all keeps the whole-slice scan.
+    const at = Math.max(findPhaseTableHeader(scoped), 0);
+    return scoped.slice(0, at) + edit(scoped.slice(at));
+}
 /**
  * Scope a ROADMAP.md content string down to its "Progress table" writable
  * slice, run `edit` against just that slice, then splice the result back into
  * the original content (ADR-2143 §7). Layered scoping:
- *   1. Milestone scope — everything after the LAST `</details>` close tag
- *      (mirrors `replaceInCurrentMilestone`), so a same-numbered phase row in
- *      an archived milestone is never touched.
- *   2. Heading scope — within that milestone slice, the `## Progress` heading
+ *   1. Milestone scope — the caller has already hidden archived `<details>`
+ *      blocks (`maskArchivedDetails`, #5553), so a same-numbered phase row in
+ *      an archived milestone is never seen here.
+ *   2. Heading scope — within the visible text, the `## Progress` heading
  *      section (up to the next `#`/`##` heading) when present, else the whole
  *      milestone slice (mirrors phase-lifecycle.cjs's `deriveProgressFromRoadmap`
  *      read-side scoping, #2012 decoy avoidance — a differently-headed table
@@ -948,29 +1047,19 @@ function cmdRoadmapMilestoneScope(cwd, raw) {
  * found within the scoped slice) simply returns its input unchanged, mirroring
  * the prior regex `.replace()`'s no-match-is-a-no-op semantics.
  */
-function editProgressTableSlice(content, edit) {
-    const lastDetailsClose = content.lastIndexOf('</details>');
-    const milestoneOffset = lastDetailsClose === -1 ? 0 : lastDetailsClose + '</details>'.length;
-    const before = content.slice(0, milestoneOffset);
-    const milestoneSlice = content.slice(milestoneOffset);
-    const progressMatch = milestoneSlice.match(/^##[ \t]+Progress\b/im);
-    if (!progressMatch || progressMatch.index === undefined) {
-        return before + edit(milestoneSlice);
-    }
-    const headingOffset = progressMatch.index;
-    const beforeHeading = milestoneSlice.slice(0, headingOffset);
-    const fromHeading = milestoneSlice.slice(headingOffset);
-    const nextHeading = fromHeading.search(/\n#{1,2}[ \t]/);
-    const scoped = nextHeading >= 0 ? fromHeading.slice(0, nextHeading) : fromHeading;
-    const after = nextHeading >= 0 ? fromHeading.slice(nextHeading) : '';
-    return before + beforeHeading + edit(scoped) + after;
+function editProgressTableSlice(content, edit, active = null) {
+    // #5762: the Progress section is the owner's (`editRoadmapProgress`, the write side of the
+    // rule every reader uses; the first one inside the active milestone's range wins, #5553).
+    // A headingless document is edited whole, from the phase table's header.
+    return (0, roadmap_progress_cjs_1.editRoadmapProgress)(content, (scoped) => editFromPhaseTable(scoped, edit), { active });
 }
 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);
+    const directoryContext = phaseDirectoryOptions(cwd);
+    const phaseInfo = findPhaseInternal(cwd, phaseNum, undefined, directoryContext);
     if (!phaseInfo) {
         error(`Phase ${phaseNum} not found`);
     }
@@ -1075,6 +1164,8 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
     // refusal below declines with the analyzer's own `missing_phase_details`
     // vocabulary and leaves ROADMAP.md byte-identical.
     let missingPhaseDetails = false;
+    let archiveRestoreFailed = false;
+    let archiveAmbiguous = false;
     const warnings = [];
     withPlanningLock(cwd, () => {
         // #3957 (B9.4): captured BEFORE any transform runs, so the write/report
@@ -1082,9 +1173,14 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         // anything — not just that they ran. Every transform below still runs
         // unconditionally exactly as before; only the final write-and-report
         // step becomes conditional on `roadmapContent !== originalContent`.
-        const originalContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
+        const rawContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
+        // #5553: every transform below runs on the text with archived `<details>`
+        // blocks hidden, so none can reach an archive; restored before the write.
+        const archived = roadmapParserModule.maskArchivedDetails(rawContent, cwd);
+        const originalContent = archived.visible;
         let roadmapContent = originalContent;
-        const phasePattern = phaseMarkdownRegexSource(phaseNum);
+        // #5186: a custom ID such as SETUP-2 is literal, not numeric phase 2.
+        const phasePattern = phaseMarkdownRegexSource(phaseNum, directoryContext);
         // #4247: ONE local source for the ATX phase-heading anchor that every
         // section-scoped writer below (`planSectionPattern`,
         // `insertRowsPatternA|B`) starts with — extracted so the target-detection
@@ -1101,16 +1197,12 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         // phase-id-owner: deliberately unmigrated (#4984 revert) — see comment above.
         const phaseHeadingAnchor = `#{2,4}\\s*Phase\\s+${phasePattern}${OPTIONAL_PHASE_TAG_SOURCE}(?=[:\\s])`;
         // #4247: target detection runs against the ORIGINAL content's active
-        // (post-</details>) region — the same milestone scoping every writer
+        // (archive-masked) text — the same milestone scoping every writer
         // below applies — so the gate asks "does the file carry a writable phase
         // representation" rather than "did some regex fire mid-transform".
-        const gateDetailsClose = originalContent.lastIndexOf('</details>');
-        const gateActiveRegion = gateDetailsClose === -1
-            ? originalContent
-            : originalContent.slice(gateDetailsClose + '</details>'.length);
         // Heading target: the exact grammar `planSectionPattern` /
         // `insertRowsPatternA|B` anchor on (an ATX phase heading for this phase).
-        const headingTargetFound = new RegExp(phaseHeadingAnchor, 'i').test(gateActiveRegion);
+        const headingTargetFound = new RegExp(phaseHeadingAnchor, 'i').test(originalContent);
         // #5545: the phase-checklist bullet grammar, defined ONCE for the writer
         // (an unchecked bullet to tick) and the gate probe (`anyState`).
         // Line-anchored, with only an optional `**` before the label and horizontal
@@ -1121,16 +1213,18 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         // same narrowing #4965 made for `roadmap analyze`'s checklist reader.
         // The lookahead only PEEKS (its `\s` may see a newline but consumes none):
         // the label must be followed by `:`, whitespace or the end of the line, so
-        // `Phase 2.1` / `Phase 20` are not `Phase 2`. Capture group 1 is the opening
-        // `- [`, group 2 the rest of the line after the box.
-        const phaseChecklistBullet = (anyState) => new RegExp(`^([ \\t]*-[ \\t]*\\[)${anyState ? '[ x]' : ' '}(\\][ \\t]*(?:\\*\\*)?[ \\t]*Phase[ \\t]+${phasePattern}${OPTIONAL_PHASE_TAG_SOURCE}(?=[:\\s]|$)[^\\n]*)`, 'im');
+        // `Phase 2.1` / `Phase 20` are not `Phase 2`. Capture group 1 is everything through
+        // the opening `[`, group 2 the rest of the line from the closing `]`. The grammar (marker,
+        // box, bold token) is the phase-entry grammar's, shared with every reader
+        // and writer through roadmap-parser's `phaseChecklistBullet` (#5764).
+        const phaseChecklistBullet = (anyState) => phaseChecklistBulletFor(phasePattern, anyState);
         // Checklist target: when the phase is complete, its own checklist bullet
         // (`- [ ] **Phase N: …**`) IS a writable phase row — the completion
         // checkbox stamp below updates it. Same grammar as that writer, widened
         // one notch to `[ x]` so an ALREADY-checked bullet still counts as a
         // found target: an idempotent re-run then takes the honest
         // "no changes were needed" decline instead of this refusal.
-        const checklistTargetFound = isComplete && phaseChecklistBullet(true).test(gateActiveRegion);
+        const checklistTargetFound = isComplete && phaseChecklistBullet(true).test(originalContent);
         // Table-row target: set by the row-scoped cell updates below.
         let tableRowFound = false;
         // Progress table row: update Plans Complete/Status/Completed columns BY
@@ -1203,14 +1297,14 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
                 tableRowFound = true;
             }
             return text;
-        });
+        }, archived.activeRange);
         // #4947: a word-prefixed Phase cell (`Phase 68`) is deliberately not a
         // writable table target (#4247 — the read side ignores it too), but when the
         // phase's heading section is still written the command reports
         // `updated: true` and the unwritten Status cell looked like a silent bug.
         // The row stays byte-identical; the output now says so.
         const wordPrefixedCellRe = new RegExp(`^Phase\\s+${phasePattern}\\.?(?:\\s|$)`, 'i');
-        const progressTable = tableRowFound ? null : (0, markdown_table_cjs_1.findTableWithColumns)(gateActiveRegion, ['Phase', 'Status']);
+        const progressTable = tableRowFound ? null : (0, markdown_table_cjs_1.findTableWithColumns)(originalContent, ['Phase', 'Status']);
         if (progressTable && progressTable.rows.some((row) => wordPrefixedCellRe.test((row['Phase'] ?? '').trim()))) {
             warnings.push(`Progress table row for phase ${formatDiagnosticToken(String(phaseNum))} was not updated: its Phase cell is word-prefixed ("Phase N"), and only a bare phase number (N or N.) is recognized. Edit that row by hand or rewrite the cell as the bare number.`);
         }
@@ -1332,7 +1426,7 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
                 : `; ${stillPending.length} ${m[2]}plan${stillPending.length === 1 ? '' : 's'} pending (${stillPending.join(', ')})`;
             return tail.slice(0, m.index) + replacement + tail.slice(m.index + m[0].length);
         };
-        roadmapContent = replaceInCurrentMilestone(roadmapContent, planSectionPattern, (sectionText) => {
+        roadmapContent = roadmapContent.replace(planSectionPattern, (sectionText) => {
             const parsed = (0, planning_document_cjs_1.parsePlanningDoc)(sectionText, 'ROADMAP.md');
             if (!parsed.ok) {
                 // Unreadable section (e.g. an unterminated frontmatter fence) —
@@ -1412,7 +1506,7 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         });
         // If complete: check checkbox
         if (isComplete) {
-            roadmapContent = replaceInCurrentMilestone(roadmapContent, phaseChecklistBullet(false), `$1x$2 (completed ${today})`);
+            roadmapContent = roadmapContent.replace(phaseChecklistBullet(false), `$1x$2 (completed ${today})`);
         }
         // Mark completed plan checkboxes (e.g. "- [ ] 50-01-PLAN.md", "- [ ] 50-01:", or "- [ ] **50-01**")
         // #4741: tick only plans the phase's own COUNT still counts. `plans` is the
@@ -1429,19 +1523,98 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
             .map((summaryFile) => ({ summaryFile, planId: summaryFile.replace('-SUMMARY.md', '').replace('SUMMARY.md', '') }))
             .filter(({ summaryFile, planId }) => planId !== ''
             && coreUtils.summaryPairsWithAnyPlan(phaseInfo.plans, summaryFile));
-        for (const { planId } of tickableSummaries) {
-            roadmapContent = roadmapContent.replace(coreUtils.planRowPattern(planId), '$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.
+        // #5483: a plan's row is ticked only in THIS phase's own scopes (its detail
+        // section, then the rows under its checklist bullet, as `phase complete` does).
+        // A scope that was located but holds no row ticks nothing, so a sibling phase's
+        // same-named row is never touched; only a phase with neither scope falls back
+        // to the first row outside every phase bullet's rows. Archived blocks are
+        // already hidden by maskArchivedDetails (#5553), which owns which regions are editable.
+        const editPhaseScopes = (text, edit, levelBounded = false) => {
+            let out = withPhaseSection(text, phaseNum, edit, levelBounded);
+            const bullet = phaseChecklistBullet(true).exec(out);
+            if (bullet) {
+                const { start, end } = checklistBulletExtent(out, bullet);
+                out = out.slice(0, start) + edit(out.slice(start, end)) + out.slice(end);
+            }
+            return out;
+        };
+        // Read-only view of the scopes `editPhaseScopes` edits: the non-empty text of each.
+        const readPhaseScopes = (text, levelBounded = false) => {
+            const scopes = [];
+            editPhaseScopes(text, (scope) => { if (scope.trim() !== '')
+                scopes.push(scope); return scope; }, levelBounded);
+            return scopes;
+        };
+        // Decided once on the pre-insertion text: insertion only adds rows under an existing section.
+        const phaseScopes = readPhaseScopes(roadmapContent, true);
+        const located = phaseScopes.length > 0;
+        // Same-length copy of `text` with every phase's detail section and checklist-bullet rows blanked: what is
+        // left is "unowned" text (e.g. rows under a non-phase heading inside the active milestone), which belongs to no sibling phase.
+        const unownedText = (text) => {
+            const spans = [];
+            const heads = (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(text);
+            heads.forEach((h, i) => {
+                if (/^Phase\b/i.test(h.text.replace(/^\[[^\]]*\]\s*/, '')))
+                    spans.push([h.offset, heads[i + 1]?.offset ?? text.length]);
+            });
+            for (const b of text.matchAll(ANY_PHASE_ENTRY_LINE))
+                spans.push([b.index, checklistBulletExtent(text, b).end]);
+            let out = text;
+            for (const [a, z] of spans)
+                out = out.slice(0, a) + out.slice(a, z).replace(/[^\r\n]/g, ' ') + out.slice(z);
+            return out;
+        };
+        const tickUnowned = (text, planId) => {
+            const blank = unownedText(text);
+            const ticked = coreUtils.tickAnchoredPlanRow(blank, planId);
+            if (ticked === blank)
+                return text;
+            let out = '';
+            for (let i = 0; i < text.length; i++)
+                out += ticked[i] !== blank[i] ? ticked[i] : text[i];
+            return out;
+        };
+        const fallbackTicked = new Set();
+        const tickPlanRow = (text, planId) => {
+            // levelBounded: a row under the phase's own `#### Plans` sub-heading ticks too.
+            const out = editPhaseScopes(text, (scope) => coreUtils.tickAnchoredPlanRow(scope, planId), true);
+            if (out !== text)
+                return out;
+            // A located scope without the row: a row no sibling phase owns (under a non-phase heading) is still this phase's.
+            if (located)
+                return tickUnowned(text, planId);
+            if (fallbackTicked.has(planId))
+                return out;
+            // First row outside every phase bullet's rows: one nested under a sibling's bullet is that sibling's.
+            let ticked = text;
+            let from = 0;
+            for (const b of text.matchAll(ANY_PHASE_ENTRY_LINE)) {
+                const { start, end } = checklistBulletExtent(text, b);
+                const seg = text.slice(from, start);
+                const t = coreUtils.tickAnchoredPlanRow(seg, planId);
+                if (t !== seg) {
+                    ticked = text.slice(0, from) + t + text.slice(start);
+                    break;
+                }
+                from = end;
+            }
+            if (ticked === text) {
+                const tail = coreUtils.tickAnchoredPlanRow(text.slice(from), planId);
+                if (tail !== text.slice(from))
+                    ticked = text.slice(0, from) + tail;
+            }
+            if (ticked !== text)
+                fallbackTicked.add(planId);
+            return ticked;
+        };
+        const tickPlanRows = (text) => tickableSummaries.reduce((acc, { planId }) => tickPlanRow(acc, planId), text);
+        roadmapContent = tickPlanRows(roadmapContent);
+        // Detection reads presentRows (the archive-masked text plus rows hidden in
+        // collapsed blocks of the active range); insertion edits the masked text only.
+        // A plan row that exists only in an archived <details> block is therefore
+        // 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.
@@ -1461,12 +1634,20 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         // up to the SAME boundary the tick loop uses (`planRowPattern`, #5542), so
         // `5-011` never satisfies `5-01` and a dotted sub-id (`5-01.5`) is a real
         // distinct plan whose row does not count as 5-01's presence.
+        // Rows inside a collapsed block of the active range are hidden from edits but still present.
+        // #5483: presence is judged in THIS phase's own scopes (plus rows hidden in collapsed active blocks), so a
+        // sibling phase's same-named un-prefixed row never makes a plan look present; a phase with no scope reads the whole text.
+        const presentRows = located
+            ? `${readPhaseScopes(roadmapContent, true).join('\n')}\n${archived.hiddenInActive}`
+            : `${roadmapContent}\n${archived.hiddenInActive}`;
+        const unownedNow = located ? unownedText(roadmapContent) : '';
+        const hasUnownedAny = (planFile, stem) => new RegExp(`-\\s*\\[[x ]\\]\\s*(?:\\*\\*)?${(0, pattern_cjs_1.escapeRegex)(planFile)}`, 'i').test(unownedNow) || coreUtils.planRowPattern(stem, { anyState: true }).test(unownedNow);
         const missingPlans = phaseInfo.plans.filter((planFile) => {
             const planEscaped = (0, pattern_cjs_1.escapeRegex)(planFile);
-            if (new RegExp(`-\\s*\\[[x ]\\]\\s*(?:\\*\\*)?${planEscaped}`, 'i').test(activeRegion))
+            if (new RegExp(`-\\s*\\[[x ]\\]\\s*(?:\\*\\*)?${planEscaped}`, 'i').test(presentRows))
                 return false;
             const stem = planFile.replace(/-PLAN\.md$/i, '');
-            return !coreUtils.planRowPattern(stem, { anyState: true }).test(activeRegion);
+            return !coreUtils.planRowPattern(stem, { anyState: true }).test(presentRows) && !(located && hasUnownedAny(planFile, stem));
         });
         if (missingPlans.length > 0) {
             // Insert missing plan checklist rows (#1163).  We prefer to anchor to the
@@ -1488,32 +1669,16 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
             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;
-            }
+            // Archived `<details>` blocks are already hidden (maskArchivedDetails), so
+            // archived duplicate phase headings cannot receive rows.
+            const regionA = roadmapContent.replace(insertRowsPatternA, inserter);
+            const withRows = regionA !== roadmapContent ? regionA : roadmapContent.replace(insertRowsPatternB, inserter);
             if (withRows !== roadmapContent) {
                 roadmapContent = withRows;
                 // Mark any newly-inserted rows that already have summaries as complete
                 // (#4741: same superseded-filtered tick list as the loop above — a
                 // pre-existing superseded row must stay unchecked on this path too).
-                for (const { planId } of tickableSummaries) {
-                    roadmapContent = roadmapContent.replace(coreUtils.planRowPattern(planId), '$1x$2');
-                }
+                roadmapContent = tickPlanRows(roadmapContent);
             }
         }
         // #3957 (B9.4): write and report an update only when the transforms
@@ -1532,8 +1697,16 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         // left byte-identical, and the caller gets a typed
         // `missing_phase_details` decline instead of a false green.
         const phaseRepresentationFound = tableRowFound || headingTargetFound || checklistTargetFound;
-        if (phaseRepresentationFound && roadmapContent !== originalContent) {
-            (0, shell_command_projection_cjs_1.platformWriteSync)(roadmapPath, roadmapContent);
+        // Unpaired <details> tags make the archive extents a guess: refuse rather than edit inconsistently.
+        const finalContent = archived.ambiguous ? null : archived.restore(roadmapContent);
+        if (archived.ambiguous) {
+            archiveAmbiguous = true;
+        }
+        else if (finalContent === null) {
+            archiveRestoreFailed = true;
+        }
+        else if (phaseRepresentationFound && finalContent !== rawContent) {
+            (0, shell_command_projection_cjs_1.platformWriteSync)(roadmapPath, finalContent);
             updated = true;
         }
         if (!phaseRepresentationFound) {
@@ -1551,6 +1724,14 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
     if (updated) {
         output(warnings.length > 0 ? { updated: true, ...computed, warnings } : { updated: true, ...computed }, raw, `${summaryCount}/${planCount} ${status}`);
     }
+    else if (archiveAmbiguous) {
+        declineNoOp(raw, 'updated', 'archive_structure_ambiguous', 'roadmap update-plan-progress skipped — ROADMAP.md has an unpaired <details> tag that hides where an archived block ends. ROADMAP.md was left unchanged.', computed);
+    }
+    else if (archiveRestoreFailed) {
+        // An edit dropped an archive placeholder (#5553): writing would lose that
+        // archive, so refuse loudly instead of reporting "no changes were needed".
+        declineNoOp(raw, 'updated', 'archive_placeholder_lost', 'roadmap update-plan-progress skipped — an edit would have dropped an archived ROADMAP block. ROADMAP.md was left unchanged.', computed);
+    }
     else if (missingPhaseDetails) {
         // #4247: honest refusal — the reason names the real condition (the
         // analyzer's `missing_phase_details` vocabulary), never "already
@@ -1563,6 +1744,23 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
     }
 }
 // ─── cmdRoadmapAnnotateDependencies ───────────────────────────────────────────
+/** #5321: tags a generated constraints heading so re-runs can tell it from a pre-#5321 one. */
+const GENERATED_MARK = ' <!-- gsd:generated -->';
+const BULLET_RE = /^\s*-\s+/;
+/**
+ * #5321: first checklist-shaped row left after the matched Plans block, scanning the rest of the
+ * Plans region — it ends at a heading or an unindented non-list line, so a later section's
+ * checklist is never mistaken for a stranded plan row. Indented detail lines are skipped, not final.
+ */
+function findStrandedRow(rest) {
+    for (const l of rest) {
+        if (/^[ \t]*[-*+][ \t]+\[[ \t]*[xX ]?[ \t]*\]/.test(l))
+            return l;
+        if (/^#{1,6}\s/.test(l) || /^\S/.test(l) && !/^(?:[-*+]\s|\*\*Wave\s+\d+\*\*)/i.test(l))
+            return undefined;
+    }
+    return undefined;
+}
 /**
  * Annotate the ROADMAP.md plan list for a phase with wave dependency notes
  * and a cross-cutting constraints subsection derived from PLAN frontmatter.
@@ -1573,8 +1771,8 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
  * 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.
+ * Re-running regenerates the annotation from current PLAN frontmatter (replans
+ * update waves/constraints, #5321); idempotent: an unchanged result writes nothing.
  */
 function cmdRoadmapAnnotateDependencies(cwd, phaseNum, raw) {
     if (!phaseNum) {
@@ -1585,7 +1783,8 @@ function cmdRoadmapAnnotateDependencies(cwd, phaseNum, raw) {
         declineNoOp(raw, 'updated', 'ROADMAP.md not found', 'roadmap annotate-dependencies skipped — ROADMAP.md not found.');
         return;
     }
-    const phaseInfo = findPhaseInternal(cwd, phaseNum);
+    const directoryContext = phaseDirectoryOptions(cwd);
+    const phaseInfo = findPhaseInternal(cwd, phaseNum, undefined, directoryContext);
     // #3957 (B9.1): distinguish "phase does not resolve at all" from "phase
     // resolves but has zero plans" — previously both collapsed into the same
     // 'no plans found for phase' reason, which is simply false for the first
@@ -1655,6 +1854,9 @@ function cmdRoadmapAnnotateDependencies(cwd, phaseNum, raw) {
         .map(v => v.text);
     // Patch ROADMAP.md
     let updated = false;
+    let skipped;
+    let staleLegacy = [];
+    let droppedGenerated = [];
     withPlanningLock(cwd, () => {
         const content = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
         // #3413: preserve the file's own EOL style when the checklist block below
@@ -1665,7 +1867,7 @@ function cmdRoadmapAnnotateDependencies(cwd, phaseNum, raw) {
         // 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 phaseEscaped = phaseMarkdownRegexSource(phaseNum, directoryContext);
         // #4906 Phase 5 (#4984): NOT migrated onto the heading-baseline selector —
         // this site was never one of the five ADR-4910 §8 call sites this phase
         // owns (init.cts/milestone.cts's buildPhaseHeadingScanRegex sites); a
@@ -1684,10 +1886,6 @@ function cmdRoadmapAnnotateDependencies(cwd, phaseNum, raw) {
         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).
@@ -1707,15 +1905,32 @@ function cmdRoadmapAnnotateDependencies(cwd, phaseNum, raw) {
         // it accepts the first complete parse and stops, which rules out the #2128-class
         // ambiguous-boundary blowup despite the nested-quantifier shape. Non-global match on
         // already phase-sliced content, not the whole file.
-        // eslint-disable-next-line local/no-unbounded-quantifier -- outer `+` has no trailing constraint to force re-partitioning; measured linear to 10.9MB
-        const plansBlockMatch = phaseSection.match(/(?:^|\r?\n)(\*{0,2}Plans\*{0,2}:[^\r\n]*\r?\n)((?:\s*-\s*\[[ x]\][^\r\n]*\r?\n?)+)/i);
+        // #5321: re-runs rebuild a prior annotation: group 2 swallows generated `**Wave N**` headers
+        // only (user prose kept); group 3 the exact constraints header + bullets, never read as plans.
+        // Block ends in one blank line (group 3 eats it) so later user bullets survive; legacy blocks
+        // (no marker) keep bullets that are not current shared truths; the exact heading is reserved.
+        // Blank lines inside the list are crossed only before a plan-id row, so a hand-written bullet after a blank line stays out.
+        // Outer `+` has no trailing constraint to force re-partitioning; alternatives start with distinct literals; measured linear to 10.9MB.
+        const plansBlockMatch = phaseSection.match(new RegExp(String.raw `(?:^|\r?\n)(\*{0,2}Plans\*{0,2}:[^\r\n]*\r?\n)((?:[ \t]*-\s*\[[ x]\][^\r\n]*\r?\n?|(?:[ \t]*\r?\n)+(?=[ \t]*-\s*\[[ x]\]\s*[\w.-]+?(?:-PLAN\.md|\.md|:|\s—))|\s*\*\*Wave\s+\d+\*\*(?: \*\(blocked on Wave \d+ completion\)\*)?[ \t]*(?:\r?\n|$)(?=\s*-\s*\[[ x]\]))+)(\s*\*\*Cross-cutting constraints:\*\*(${(0, pattern_cjs_1.escapeRegex)(GENERATED_MARK)})?[ \t]*(?:\r?\n|$)(?:[ \t]*-[ \t]+[^\r\n]*\r?\n?)*(?:[ \t]*\r?\n)?)?`, 'i'));
         if (!plansBlockMatch)
             return;
         const plansHeader = plansBlockMatch[1];
         const existingList = plansBlockMatch[2];
-        const listLines = (0, text_lines_cjs_1.splitLines)(existingList).filter(l => /^\s*-\s*\[/.test(l));
+        const listLines = (0, text_lines_cjs_1.splitLines)(existingList).filter(l => /^\s*-\s*\[[ x]\]/i.test(l));
         if (listLines.length === 0)
             return;
+        const oldBlock = plansBlockMatch[3] ? (0, text_lines_cjs_1.splitLines)(plansBlockMatch[3]) : [];
+        // #5321: a checklist row group 2 rejects (`- [  ]`, `* [ ]`), or an empty generated wave
+        // header, splits the list; rewriting only the prefix would orphan the rest — skip loudly.
+        const stranded = plansBlockMatch[3] ? undefined : findStrandedRow((0, text_lines_cjs_1.splitLines)(phaseSection.slice(plansBlockMatch.index + plansBlockMatch[0].length)));
+        const warn = (head, tail) => {
+            process.stderr.write(`[gsd-tools] WARNING: roadmap annotate-dependencies ${head}${formatDiagnosticToken(String(phaseNum))}${tail}`);
+        };
+        if (stranded) {
+            warn(`skipped — unrecognised checklist row ${formatDiagnosticToken(stranded.trim())} splits the Plans list of phase `, '.\n');
+            skipped = 'unrecognised_checklist_row';
+            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.
@@ -1761,11 +1976,38 @@ function cmdRoadmapAnnotateDependencies(cwd, phaseNum, raw) {
         // Append cross-cutting constraints subsection if any found
         if (crossCuttingTruths.length > 0) {
             annotatedLines.push('');
-            annotatedLines.push('**Cross-cutting constraints:**');
+            annotatedLines.push(`**Cross-cutting constraints:**${GENERATED_MARK}`);
             for (const t of crossCuttingTruths) {
                 annotatedLines.push(`- ${t}`);
             }
+            annotatedLines.push(''); // #5321: delimiter so user bullets after the block survive re-runs
+        }
+        // #5321: bullets of the old constraints block that equal ANY current plan truth were generated
+        // from one (rebuilt above, or no longer shared): drop them. Any other bullet is a user bullet or
+        // a reworded/removed constraint; both look alike. Without the generated marker (pre-#5321) keep
+        // and report it; under the marker the block is machine-owned, so drop it but warn.
+        if (plansBlockMatch[3]) {
+            const unknown = oldBlock
+                .filter(l => BULLET_RE.test(l) && !truthCounts.has(l.replace(BULLET_RE, '').trim().toLowerCase()));
+            const texts = unknown.map(l => l.replace(BULLET_RE, '').trim());
+            const names = texts.map(formatDiagnosticToken).join('; ');
+            if (unknown.length > 0 && plansBlockMatch[4]) {
+                droppedGenerated = texts;
+                warn(`dropped ${unknown.length} bullet(s) under the generated `
+                    + `constraints heading that match no current plan truth in phase `, `: ${names} — put your own bullets after a blank line.\n`);
+            }
+            else if (unknown.length > 0) {
+                if (crossCuttingTruths.length === 0)
+                    annotatedLines.push('');
+                annotatedLines.push(...unknown);
+                staleLegacy = texts;
+                warn(`kept ${unknown.length} bullet(s) under a pre-#5321 `
+                    + `constraints block that match no current plan truth in phase `, `: ${names} — delete any that are stale.\n`);
+            }
         }
+        // The old block's trailing blank line separated it from user content below: keep it when the block is dropped.
+        if (oldBlock.length > 2 && !oldBlock[oldBlock.length - 2].trim() && annotatedLines[annotatedLines.length - 1] !== '')
+            annotatedLines.push('');
         const newListBlock = (0, text_lines_cjs_1.joinLines)(annotatedLines, eol) + eol;
         // #1103: when `(?:^|\r?\n)` consumed a leading terminator (mid-string
         // match), re-emit it verbatim so the line preceding the Plans: header is
@@ -1783,7 +2025,8 @@ function cmdRoadmapAnnotateDependencies(cwd, phaseNum, raw) {
         // never pattern-interpreted.
         const newPhaseSection = phaseSection.replace(plansBlockMatch[0], () => leadingNewline + plansHeader + newListBlock);
         const nextContent = content.slice(0, phaseStart) + newPhaseSection + content.slice(phaseEnd);
-        if (nextContent === content)
+        // #5321: compare post-normalize (platformWriteSync collapses blank runs), not raw strings.
+        if (!(0, shell_command_projection_cjs_1.contentChangedAfterNormalize)(roadmapPath, content, nextContent))
             return;
         (0, shell_command_projection_cjs_1.platformWriteSync)(roadmapPath, nextContent);
         updated = true;
@@ -1793,7 +2036,10 @@ function cmdRoadmapAnnotateDependencies(cwd, phaseNum, raw) {
         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)');
+        ...(skipped && { skipped }),
+        ...(staleLegacy.length > 0 && { stale_legacy_constraints: staleLegacy }),
+        ...(droppedGenerated.length > 0 && { dropped_generated_constraints: droppedGenerated }),
+    }, raw, updated ? `annotated ${waves.length} wave(s), ${crossCuttingTruths.length} constraint(s)` : skipped ? `skipped (${skipped})` : 'skipped (already up to date or no plan list)');
 }
 module.exports = {
     cmdRoadmapGetPhase,
@@ -1803,4 +2049,10 @@ module.exports = {
     cmdRoadmapUpdatePlanProgress,
     cmdRoadmapAnnotateDependencies,
     buildPhaseHeadingRegex,
+    editFromPhaseTable,
+    findPhaseTableHeader,
+    editProgressTableSlice,
+    foldPhaseId,
+    insideOpenDetails,
+    checklistEntrySrc,
 };