@opengsd/gsd-core 1.18.0 → 1.20.0

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

@@ -21,9 +21,11 @@
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
+const node_crypto_1 = require("node:crypto");
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const pattern_cjs_1 = require("./pattern.cjs");
+const phase_entry_grammar_cjs_1 = require("./phase-entry-grammar.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdModule = require("./phase-id.cjs");
 const { phaseMarkdownRegexSource, stripProjectCodePrefix, OPTIONAL_PHASE_TAG_SOURCE, 
@@ -53,10 +55,14 @@ const planningWorkspace = require("./planning-workspace.cjs");
 const { planningDir, resolvePhaseIdConvention } = planningWorkspace;
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+const frontmatterMod = require("./frontmatter.cjs");
+const { rawFrontmatterMapping } = frontmatterMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 const unusableInputMod = require("./unusable-input.cjs");
 const { UNUSABLE_REASON, warnUnusableInput } = unusableInputMod;
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 const markdown_table_cjs_1 = require("./markdown-table.cjs");
+const roadmap_progress_cjs_1 = require("./roadmap-progress.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningScopeMod = require("./planning-scope.cjs");
 const { SCOPE } = planningScopeMod;
@@ -72,12 +78,94 @@ const MILESTONE_ACTIVE_MARKER_PATTERN = /\b(?:STARTED|ACTIVE|WIP)\b|in\s+progres
 function isClosedMilestoneHeading(headingText) {
     return MILESTONE_CLOSED_MARKER_PATTERN.test(headingText) && !MILESTONE_ACTIVE_MARKER_PATTERN.test(headingText);
 }
+/**
+ * Is this `<details>` block a CLOSED milestone? One test for the read-side strip
+ * and the write-side mask. The `<summary>` is read with inline tags removed
+ * (`<b>v1.0</b> ✅`); a milestone-shaped summary (version token or "milestone")
+ * that says "Complete(d)" counts too. No `<summary>` means not closed.
+ */
+function isClosedMilestoneBlock(block) {
+    const summary = block.match(/<summary[^>]*>([\s\S]{0,1000}?)<\/summary>/i);
+    if (!summary)
+        return false;
+    const text = summary[1].replace(/<[^>]{0,200}>/g, '');
+    return isClosedMilestoneHeading(text)
+        || (/\bcomplete(?:d)?\b/i.test(text) && /\bv\d+(?:\.\d+)*\b|\bmilestone\b/i.test(text)
+            && !MILESTONE_ACTIVE_MARKER_PATTERN.test(text));
+}
 /**
  * Strip shipped milestone content wrapped in <details> blocks.
  */
 function stripShippedMilestones(content) {
     return (0, markdown_sectionizer_cjs_1.stripTaggedBlocks)(content, 'details');
 }
+/**
+ * #5543: hide every CLOSED-milestone `<details>` block (`<details>` opener, a
+ * `<summary>` that `isClosedMilestoneHeading` reads as shipped/archived, the
+ * #3982 test) behind a placeholder comment; `restore` puts them back
+ * byte-for-byte, or returns null when `edited` lost or duplicated a placeholder.
+ * For writers whose first `### Phase N:` in document order must never sit in a
+ * shipped block. Other `<details>` (notes, a phase wrapper, an active
+ * milestone's collapsed block) stay visible, so a roadmap with no archived
+ * milestone is edited as before. Blocks are matched by depth, so a notes
+ * `<details>` nested inside a shipped one stays inside it (the flat
+ * `taggedBlockPattern` closes at the inner `</details>`). An unmatched
+ * opener (prose, a fence) wraps nothing, so a later shipped block is still
+ * masked. Fences are not parsed, as in every ROADMAP `<details>` reader here.
+ */
+function maskShippedBlocks(content) {
+    const blocks = [];
+    let nonce = 0;
+    while (content.includes(`<!-- gsd-masked-shipped-${nonce}-`))
+        nonce += 1;
+    const placeholder = (i) => `<!-- gsd-masked-shipped-${nonce}-${i} -->`;
+    const tags = /<details(?:\s[^>]{0,1000})?>|<\/details>/gi;
+    // Matched pairs by stack; an unmatched opener (prose, a fence) never closes, so it
+    // wraps nothing and a later block is still found. `outer` keeps only the pairs not
+    // nested in another matched pair.
+    const open = [];
+    const outer = [];
+    for (let m = tags.exec(content); m !== null; m = tags.exec(content)) {
+        if (m[0][1] !== '/')
+            open.push(m.index);
+        else if (open.length > 0) {
+            const start = open.pop();
+            while (outer.length > 0 && outer[outer.length - 1][0] >= start)
+                outer.pop();
+            outer.push([start, m.index + m[0].length]);
+        }
+    }
+    let masked = '';
+    let copied = 0;
+    for (const [start, end] of outer) {
+        const block = content.slice(start, end);
+        if (block.startsWith('<details>') && isClosedMilestoneBlock(block)) {
+            masked += content.slice(copied, start) + placeholder(blocks.length);
+            blocks.push(block);
+            copied = end;
+        }
+    }
+    masked += content.slice(copied);
+    return {
+        masked,
+        restore(edited) {
+            let restored = edited;
+            for (let i = 0; i < blocks.length; i++) {
+                const marker = placeholder(i);
+                const at = restored.indexOf(marker);
+                if (at === -1 || restored.indexOf(marker, at + marker.length) !== -1)
+                    return null;
+                restored = restored.slice(0, at) + blocks[i] + restored.slice(at + marker.length);
+            }
+            return restored;
+        },
+    };
+}
+function editOutsideShippedBlocks(content, edit) {
+    const { masked, restore } = maskShippedBlocks(content);
+    const edited = edit(masked);
+    return (typeof edited === 'string' ? restore(edited) : null) ?? content;
+}
 /**
  * #3982: strip only <details> blocks whose <summary> marks a CLOSED milestone
  * (ARCHIVED/SHIPPED/✅/… without an active marker) — the narrow form of
@@ -86,12 +174,15 @@ function stripShippedMilestones(content) {
  * reproduce the phase_count: 0 class of #557/#2947.
  */
 function stripClosedMilestoneDetails(content) {
-    return content.replace(/<details\b[^>]*>[\s\S]*?<\/details>/gi, (block) => {
-        const summaryMatch = block.match(/<summary[^>]*>([^<]*)<\/summary>/i);
-        if (!summaryMatch)
-            return block;
-        return isClosedMilestoneHeading(summaryMatch[1]) ? '' : block;
-    });
+    return content.replace(/<details\b[^>]*>[\s\S]*?<\/details>/gi, (block) => (isClosedMilestoneBlock(block) ? '' : block));
+}
+/**
+ * Classify a complete `<details>` block through isClosedMilestoneBlock, the one rule shared with
+ * stripClosedMilestoneDetails and the write-side shipped-block mask. Destructive consumers share this predicate so
+ * an active collapsed phase list is never reclassified as shipped history.
+ */
+function isClosedMilestoneDetails(block) {
+    return isClosedMilestoneBlock(block);
 }
 /**
  * #2562: is the milestone `version` marked SHIPPED by the ROADMAP itself?
@@ -347,6 +438,25 @@ function listMilestoneHeadings(content) {
 // rather than typing `^#{1,3}\s+(?!Phase\s+\S)` a second time — the exact
 // duplication class ADR-3180 §7.2's widened guard exists to catch.
 const MILESTONE_HEADING_LINE_SOURCE = '^#{1,3}\\s+(?!Phase\\s+\\S)[^\\n]*';
+/**
+ * #4304: classify one level-1..3 heading through the same milestone grammar
+ * the window locator owns. Phase headings are excluded first through the
+ * reader's own legacy/bracket discriminators, regardless of words or markers
+ * in their titles; `Failed Payment Recovery` and `Done ✅` remain phase
+ * titles, never milestone section boundaries. Version-bearing headings route
+ * through `listMilestoneHeadings`; version-less bracket headings route through
+ * `isBracketMilestoneBoundary`, the discriminator also used by the bracket
+ * fallback locator.
+ */
+function isRecognizedMilestoneHeading(headingText, level) {
+    if (level < 1 || level > 3)
+        return false;
+    if (/^Phase\s+\S/i.test(headingText) || BRACKET_PHASE_TAIL_RE.test(headingText))
+        return false;
+    const line = `${'#'.repeat(level)} ${headingText}`;
+    return listMilestoneHeadings(line).length > 0
+        || isBracketMilestoneBoundary(headingText, level, null);
+}
 /**
  * #3184: the sole milestone-heading locator. Boundary-matched on the version
  * token with `\b`, NOT the stricter `(?![\w.-])`: this function keeps `\b`
@@ -665,23 +775,32 @@ const PHASE_HEADING_TEXT_RE = /^(?:\[[^\]]{1,200}\]\s*)?Phase\s+([\w][\w.-]*)(?:
  * leading `#{1,6}` markers and surrounding whitespace already stripped
  * (`tokenizeHeadings`'s own `h.text`, or the equivalent for a line a caller
  * already knows is a `#{2,4}` heading) — is a phase heading by the readers'
- * own grammar. The single owner of this test; `hasPhaseEntries` below is
- * itself just the first caller.
+ * own grammar. The single owner of this test: `hasPhaseEntries` reaches it
+ * through `isPhaseEntryHeading` below, and the bracket roadmap migrator
+ * calls it directly.
  */
 function isPhaseHeadingText(headingText) {
     return PHASE_HEADING_TEXT_RE.test(headingText);
 }
+/**
+ * Does one fence-excluded heading token use the reader's phase-entry grammar?
+ * Kept separate from heading depth so destructive consumers can apply the
+ * same bracket-plus-legacy recognition to tokens from `tokenizeHeadings`.
+ * The legacy arm is `isPhaseHeadingText`, that grammar's single owner.
+ */
+function isPhaseEntryHeading(headingText, phaseIdConvention) {
+    if (isPhaseHeadingText(headingText))
+        return true;
+    return phaseIdConvention === 'bracket' && BRACKET_PHASE_ENTRY_HEADING_RE.test(headingText);
+}
 function hasPhaseEntries(markdown, phaseIdConvention) {
     // #3641: the widened grammar engages ONLY when the resolved convention is
     // 'bracket' — a project that has not opted in runs the legacy pattern
     // alone, byte-identically.
-    const bracketMode = phaseIdConvention === 'bracket';
     for (const h of (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(markdown)) {
         if (h.level < 2 || h.level > 4)
             continue;
-        if (isPhaseHeadingText(h.text))
-            return true;
-        if (bracketMode && BRACKET_PHASE_ENTRY_HEADING_RE.test(h.text))
+        if (isPhaseEntryHeading(h.text, phaseIdConvention))
             return true;
     }
     // #3184 review finding: the bullet fallback must be fence-aware too, or a
@@ -775,7 +894,7 @@ function hasPhaseListingTableHeader(content) {
  * narrower question — "which phase ids does this window declare" — where only
  * the 999 icebox range is excluded.
  */
-function scanMilestonePhaseIdSets(window, convention) {
+function scanMilestonePhaseIdSets(window, convention, context) {
     const ids = new Set();
     const qualifiedIds = new Set();
     // Use tokenizeHeadings (fence-aware) instead of stripFencedLines + regex.
@@ -786,7 +905,7 @@ function scanMilestonePhaseIdSets(window, convention) {
     // belonging to different milestones.
     const capturing = convention === 'bracket';
     const bracketGroups = capturing ? 1 : 0;
-    const phaseHeadingPattern = new RegExp(`^${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.ANY_BRACKET, convention, capturing)}([\\w][\\w.-]*)(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:`, 'i');
+    const phaseHeadingPattern = new RegExp(`^${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.ANY_BRACKET, convention, capturing)}(${context?.phaseNaming === 'custom' && convention !== 'bracket' ? phaseIdModule.phaseScanTokenSource(context) : '[\\w][\\w.-]*'})(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:`, 'i');
     for (const h of (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(window)) {
         if (h.level < 2 || h.level > 4)
             continue;
@@ -944,6 +1063,87 @@ function classifyMilestoneWindow(input) {
 const PHASE_HEADING_BLOCK_STRIP_RE = new RegExp(
 // #1729: `(?:\s*\([^)\n]{0,200}\))?` (OPTIONAL_PHASE_TAG_SOURCE) tolerates a pre-colon ( ) tag.
 `^#{2,4}\\s*${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY)}${PHASE_NUMBER_TOKEN_SOURCE}${OPTIONAL_PHASE_TAG_SOURCE}\\s*:[^\\n]*(?:\\n(?!#{1,6}\\s)[^\\n]*)*\\n?`, 'gim');
+/**
+ * #612/#4304: the bracket-fallback candidate search for a milestone heading
+ * carrying no vX.Y version token at all — the ADR-612 canonical shape
+ * (`## [GSD.09] Hidden`). Tried by a caller only when the legacy
+ * version-string search (`locateMilestoneHeadings`) finds nothing and the
+ * project is on the bracket convention. Extracted (#4304 PR-4) from
+ * `extractCurrentMilestoneScoped`'s own inline block so it and
+ * `currentMilestoneRawRanges` share one heading grammar instead of each
+ * re-deriving the bracket intro pattern independently, the Generative Fix
+ * Divergence class #2761 documents. Byte-identical logic to the block it replaces; moving it
+ * changes no behavior.
+ */
+function bracketFallbackHeadingMatches(content, version, bracketScopeConvention) {
+    if (bracketScopeConvention !== 'bracket')
+        return [];
+    const vMatch = version.match(/^v(\d+)/i);
+    const milestoneInt = vMatch ? parseInt(vMatch[1], 10) : NaN;
+    if (!Number.isSafeInteger(milestoneInt))
+        return [];
+    // #2761 M3: the phase-id owner supplies both the bracket intro grammar
+    // and canonical pad2 spelling; `[CODE.2]` therefore cannot bound a
+    // section whose phase headings the bracket grammar rejects.
+    // #612: HeadingToken.offset is the line start, so require the
+    // `#` there to preserve the old line-start anchor's indentation parity.
+    // For every survivor, rebuilding [fullLine, fullLine] plus `.index`
+    // retains the match shape and first-match order expected downstream.
+    const bracketMilestoneHeadingRe = new RegExp(`^${bracketMilestoneIntroSrcFor(milestoneInt)}`, 'i');
+    return (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(content)
+        .filter((h) => h.level <= 3 && content[h.offset] === '#' && bracketMilestoneHeadingRe.test(h.text))
+        .map((h) => {
+        const lineEnd = content.indexOf('\n', h.offset);
+        const fullLine = content.slice(h.offset, lineEnd === -1 ? content.length : lineEnd);
+        return Object.assign([fullLine, fullLine], { index: h.offset });
+    });
+}
+/**
+ * #612/#4304: the milestone-heading SELECTION fallback chain — prefers the
+ * canonical legacy selector (`selectMilestoneHeading`), then falls back to
+ * the gated bracket candidates (`headingMatches`, already populated by
+ * `bracketFallbackHeadingMatches` when the legacy selector's own internal
+ * `locateMilestoneHeadings` call finds nothing) when a name-only bracket
+ * milestone carries no version token for that selector to find. Shared
+ * (#4304 PR-4) by `extractCurrentMilestoneScoped` and
+ * `currentMilestoneRawRanges` so both agree on which heading is "the active
+ * one" for a version-less bracket milestone. `headingMatches` must be
+ * non-empty (every caller checks this first).
+ */
+function selectActiveMilestoneHeading(content, version, headingMatches) {
+    return selectMilestoneHeading(content, version)
+        ?? headingMatches.find((m) => !isClosedMilestoneHeading(m[1]))
+        ?? headingMatches[0];
+}
+/**
+ * #612/#4304: resolves the bracket-aware milestone SECTION END, the
+ * SELECTED heading's own bracket id, and the `bracketBoundary` predicate
+ * itself — the caller reuses all three afterward (`extractCurrentMilestoneScoped`'s
+ * own "earliest milestone heading" preamble scan reuses `selectedBracketId`;
+ * its "(Phase Details)" section-end lookup reuses `bracketBoundary`).
+ * `bracketBoundaryActive` and `currentMilestoneHeadings` are supplied by the
+ * caller (not recomputed here) because both callers need them again
+ * afterward for their own, divergent purposes. Shared (#4304 PR-4) by
+ * `extractCurrentMilestoneScoped` and `currentMilestoneRawRanges` so a
+ * version-less bracket milestone heading (`## [GSD.09] Hidden`) bounds its
+ * section identically for both, instead of one of them silently running the
+ * LEGACY-only (vX.Y/emoji-only) boundary rule. Byte-identical logic to the
+ * block it replaces; moving it changes no behavior.
+ */
+function bracketAwareMilestoneSection(content, selected, sectionStart, bracketBoundaryActive, currentMilestoneHeadings) {
+    // #2761 B1: a bracket heading bearing the selected milestone's own id is
+    // a continuation, not a boundary. Derive the selected id once and compose
+    // the shared discriminator with upstream's centralized section-end walk.
+    const selectedBracketMatch = bracketBoundaryActive
+        ? selected[0].match(new RegExp(`^#{1,3}\\s+\\[(${BRACKET_ID_SRC})\\]`, 'i'))
+        : null;
+    const selectedBracketId = selectedBracketMatch ? foldBracketId(selectedBracketMatch[1]) : null;
+    const bracketBoundary = bracketBoundaryActive
+        ? (heading) => isBracketMilestoneBoundary(heading.text, heading.level, selectedBracketId)
+        : undefined;
+    const sectionEnd = computeMilestoneSectionEnd(content, selected[0], sectionStart, bracketBoundary, currentMilestoneHeadings);
+    return { sectionEnd, selectedBracketId, bracketBoundary };
+}
 /**
  * #5038: single owner for classifying a `milestone:` scalar as STATE.md spells
  * it. The frontmatter parser (FAILSAFE_SCHEMA) and the raw-regex readers both
@@ -964,6 +1164,28 @@ function classifyMilestoneScalar(raw) {
         return { explicitNull: true, version: null };
     return { explicitNull: false, version: trimmed };
 }
+/**
+ * #4998: STATE.md's `milestone:` scalar as the frontmatter parser DECODES it.
+ * The raw `^milestone:` line read captured the on-disk YAML text — quotes and
+ * escapes included — and that text was re-serialized as the value, adding one
+ * escape layer per `state.*` write. Falls back to the legacy line read only
+ * when there is no parseable frontmatter, or its `milestone` is not text. One
+ * that parses without a `milestone` key names none: a `milestone:` line further
+ * down (a fenced example) is not one (#4998 review, Minor 5).
+ */
+function readStateMilestoneScalar(stateRaw) {
+    const fm = rawFrontmatterMapping(stateRaw);
+    if (fm) {
+        if (!Object.prototype.hasOwnProperty.call(fm, 'milestone'))
+            return null;
+        if (typeof fm['milestone'] === 'string')
+            return fm['milestone'];
+        // A non-string value keeps the pre-#4998 line read, which finds this
+        // frontmatter line first.
+    }
+    const m = stateRaw.match(/^milestone:\s*(.+)/m);
+    return m ? m[1] : null;
+}
 /**
  * Extract the current milestone section from ROADMAP.md by positive lookup,
  * carrying a `scope` discriminator (ADR-3180 Decision 2) alongside the value.
@@ -1003,9 +1225,9 @@ function extractCurrentMilestoneScoped(content, cwd, ws, phaseIdConvention) {
         const statePath = node_path_1.default.join(planningDir(cwd, ws), 'STATE.md');
         const stateRaw = (0, shell_command_projection_cjs_1.platformReadSync)(statePath);
         if (stateRaw !== null) {
-            const milestoneMatch = stateRaw.match(/^milestone:\s*(.+)/m);
-            if (milestoneMatch) {
-                const classified = classifyMilestoneScalar(milestoneMatch[1]);
+            const milestoneScalar = readStateMilestoneScalar(stateRaw);
+            if (milestoneScalar !== null) {
+                const classified = classifyMilestoneScalar(milestoneScalar);
                 version = classified.version;
                 stateAssertsNoMilestone = classified.explicitNull;
             }
@@ -1056,26 +1278,8 @@ function extractCurrentMilestoneScoped(content, cwd, ws, phaseIdConvention) {
         }
         catch { /* unresolvable convention → preserve the legacy fallback */ }
     }
-    if (headingMatches.length === 0 && bracketScopeConvention === 'bracket') {
-        const vMatch = version.match(/^v(\d+)/i);
-        const milestoneInt = vMatch ? parseInt(vMatch[1], 10) : NaN;
-        if (Number.isSafeInteger(milestoneInt)) {
-            // #2761 M3: the phase-id owner supplies both the bracket intro grammar
-            // and canonical pad2 spelling; `[CODE.2]` therefore cannot bound a
-            // section whose phase headings the bracket grammar rejects.
-            // #612 round-5: HeadingToken.offset is the line start, so require the
-            // `#` there to preserve the old line-start anchor's indentation parity.
-            // For every survivor, rebuilding [fullLine, fullLine] plus `.index`
-            // retains the match shape and first-match order expected downstream.
-            const bracketMilestoneHeadingRe = new RegExp(`^${bracketMilestoneIntroSrcFor(milestoneInt)}`, 'i');
-            headingMatches = (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(content)
-                .filter((h) => h.level <= 3 && content[h.offset] === '#' && bracketMilestoneHeadingRe.test(h.text))
-                .map((h) => {
-                const lineEnd = content.indexOf('\n', h.offset);
-                const fullLine = content.slice(h.offset, lineEnd === -1 ? content.length : lineEnd);
-                return Object.assign([fullLine, fullLine], { index: h.offset });
-            });
-        }
+    if (headingMatches.length === 0) {
+        headingMatches = bracketFallbackHeadingMatches(content, version, bracketScopeConvention);
     }
     if (headingMatches.length === 0) {
         const summaryMatch = content.match(summaryPattern);
@@ -1130,29 +1334,14 @@ function extractCurrentMilestoneScoped(content, cwd, ws, phaseIdConvention) {
     // #3184: selection collapses to the sole owner; `allMatches` is still needed
     // below (offsets, detailsMatch search), so only the selection itself routes
     // through `selectMilestoneHeading` rather than the whole block.
-    // Preserve the canonical legacy selector, then fall back to the gated
-    // bracket candidates above when a name-only bracket milestone carries no
-    // version token for that selector to find.
-    const selected = selectMilestoneHeading(content, version)
-        ?? allMatches.find((m) => !isClosed(m[1]))
-        ?? firstMatch;
+    const selected = selectActiveMilestoneHeading(content, version, allMatches);
     const sectionStart = selected.index;
-    // #2761 B1: a bracket heading bearing the selected milestone's own id is
-    // a continuation, not a boundary. Derive the selected id once and compose
-    // the shared discriminator with upstream's centralized section-end walk.
     const bracketBoundaryActive = bracketScopeConvention === 'bracket';
-    const selectedBracketMatch = bracketBoundaryActive
-        ? selected[0].match(new RegExp(`^#{1,3}\\s+\\[(${BRACKET_ID_SRC})\\]`, 'i'))
-        : null;
-    const selectedBracketId = selectedBracketMatch ? foldBracketId(selectedBracketMatch[1]) : null;
     // #2761 B3: tokenize once for both the centralized section-end owner and
     // the bracket preamble scan below. This keeps both boundary decisions
     // fence-aware without restoring the local section walker retired by #3184.
     const currentMilestoneHeadings = (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(content);
-    const bracketBoundary = bracketBoundaryActive
-        ? (heading) => isBracketMilestoneBoundary(heading.text, heading.level, selectedBracketId)
-        : undefined;
-    const sectionEnd = computeMilestoneSectionEnd(content, selected[0], sectionStart, bracketBoundary, currentMilestoneHeadings);
+    const { sectionEnd, selectedBracketId, bracketBoundary } = bracketAwareMilestoneSection(content, selected, sectionStart, bracketBoundaryActive, currentMilestoneHeadings);
     const anyMilestonePattern = /^#{1,3}\s+(?!Phase\s+\S)(?:.*v\d+\.\d+|✅|📋|🚧)/im;
     let earliestMilestoneIndex;
     if (!bracketBoundaryActive) {
@@ -1375,18 +1564,261 @@ function extractCurrentMilestoneScoped(content, cwd, ws, phaseIdConvention) {
 function extractCurrentMilestone(content, cwd, ws) {
     return extractCurrentMilestoneScoped(content, cwd, ws).value;
 }
-function replaceInCurrentMilestone(content, pattern, replacement) {
-    const apply = (src) => typeof replacement === 'function'
-        ? src.replace(pattern, replacement)
-        : src.replace(pattern, replacement);
-    const lastDetailsClose = content.lastIndexOf('</details>');
-    if (lastDetailsClose === -1) {
-        return apply(content);
+/**
+ * Same-length copy of `s` with HTML comments blanked. An unterminated `<!--`, or
+ * one whose `-->` lies beyond the next heading, is bounded at the end of its own
+ * line so a prose mention never hides later archives. Linear: `-->` and heading
+ * lookups are cached while they stay ahead of the cursor.
+ */
+function blankComments(s) {
+    const heading = /\n#{1,6} /g;
+    let out = '';
+    let i = 0;
+    let close = 0;
+    let head = -2; // -2: heading not looked up yet (-1 means none ahead); offset 0 must still trigger the first lookup
+    for (let o = s.indexOf('<!--'); o !== -1; o = s.indexOf('<!--', i)) {
+        if (close !== -1 && close < o + 4)
+            close = s.indexOf('-->', o + 4);
+        if (head !== -1 && head < o) {
+            heading.lastIndex = o;
+            const m = heading.exec(s);
+            head = m ? m.index : -1;
+        }
+        let end;
+        if (close !== -1 && (head === -1 || close < head))
+            end = close + 3;
+        else {
+            end = s.indexOf('\n', o);
+            if (end === -1)
+                end = s.length;
+        }
+        out += s.slice(i, o) + s.slice(o, end).replace(/[^\r\n]/g, ' ');
+        i = end;
+    }
+    return out + s.slice(i);
+}
+const VERSION_TOKEN = /v\d+(?:\.\d+)+(?:[-.][A-Za-z0-9]+)*/i;
+/** Same-length copy of `content` with fenced blocks, inline code spans and HTML comments blanked. */
+function blankCodeAndComments(content) {
+    // Same-length copy with fenced blocks, inline code spans and HTML comments
+    // blanked (code first: a backticked `<!--` must not open a comment), so a `<details>` mentioned in prose or an example never opens or
+    // closes a block.
+    const lines = content.split('\n');
+    const blank = (t) => t.replace(/[^\r\n]/g, ' ');
+    for (const f of (0, markdown_sectionizer_cjs_1.scanFencedBlocks)(lines)) {
+        // An unclosed fence is bounded at the next heading, not EOF, so later archives stay visible.
+        let last = f.closeLineIdx;
+        if (last === -1) {
+            last = lines.length - 1;
+            for (let i = f.openLineIdx + 1; i < lines.length; i++)
+                if (/^#{1,6} /.test(lines[i])) {
+                    last = i - 1;
+                    break;
+                }
+        }
+        for (let i = f.openLineIdx; i <= last; i++)
+            lines[i] = blank(lines[i]);
+    }
+    const joined = lines.join('\n');
+    let codeBlanked = '';
+    let at = 0;
+    for (const sp of (0, markdown_sectionizer_cjs_1.scanInlineCodeSpans)(joined)) {
+        codeBlanked += joined.slice(at, sp.start) + blank(joined.slice(sp.start, sp.end));
+        at = sp.end;
     }
-    const offset = lastDetailsClose + '</details>'.length;
-    const before = content.slice(0, offset);
-    const after = content.slice(offset);
-    return before + apply(after);
+    return blankComments(codeBlanked + joined.slice(at));
+}
+/**
+ * A closed milestone written as a plain heading section (no `<details>`) is archive too; the
+ * active milestone's own `## v2.0 Part 2 ✅` sections are not.
+ */
+function plainClosedSections(content, overlapsActive, activeVersion) {
+    // A closed milestone written as a plain heading section (no `<details>`) is
+    // archive too. It ends at the next heading of the same or shallower level, so
+    // a following `## Progress` table stays visible.
+    const headingTokens = (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(content);
+    const spans = [];
+    for (let i = 0; i < headingTokens.length; i++) {
+        const h = headingTokens[i];
+        if (/^Phase\s+\S/i.test(h.text))
+            continue;
+        if (!isClosedMilestoneHeading(h.text) || extractMilestoneHeadingName(h.text) === null)
+            continue;
+        let next;
+        for (let j = i + 1; j < headingTokens.length && !next; j++) {
+            const t = headingTokens[j];
+            if (t.level <= h.level && !/^Phase\s+\S/i.test(t.text))
+                next = t;
+        }
+        // End before the newline that precedes `next`, so that heading stays at line start.
+        const end = next ? next.offset - (content[next.offset - 2] === '\r' ? 2 : 1) : content.length;
+        if (!overlapsActive(h.offset, end) && !(activeVersion && h.text.match(VERSION_TOKEN)?.[0].toLowerCase() === activeVersion))
+            spans.push({ start: h.offset, end });
+    }
+    return spans;
+}
+/**
+ * #5553: locate every archive span in `content` (`<details>` blocks and plain closed-milestone
+ * sections) that does not wrap the active milestone; `inActive` is the subset overlapping it.
+ */
+function scanArchiveSpans(content, active) {
+    const activeVersion = active.length > 0 ? content.slice(active[0].start, active[0].start + 300).split('\n', 1)[0].match(VERSION_TOKEN)?.[0].toLowerCase() : undefined;
+    // A block whose own <summary> marks a closed milestone is an archive wherever it sits.
+    const closedSummary = (at) => {
+        const m = /^<details\b[^>]{0,200}>[\s>]*<summary[^>]{0,200}>([^<]{0,300})<\/summary>/i.exec(content.slice(at, at + 800));
+        return m !== null && isClosedMilestoneHeading(m[1]);
+    };
+    const scan = blankCodeAndComments(content);
+    // Depth-aware: an outer block closes at its own `</details>`, so a nested
+    // collapsed section inside an archive is masked with it.
+    const spans = [];
+    const inActive = [];
+    const overlapsActive = (start, end) => active.some((r) => start < r.end && end > r.start);
+    // Block-level tags only: a tag at line start (<=3 spaces, optionally inside a
+    // blockquote `>` prefix) starts the scan of its line, and further tags on that
+    // same line (a one-line `<details>...</details>`) count with it. Inline or
+    // indented mentions elsewhere never count, and the bounded attribute run keeps
+    // a hostile run of `<details ` linear.
+    const lineStart = /^[ \t]{0,3}(?:>[ \t]{0,3})*(?=<\/?details\b)/gim;
+    const anyTag = /<details\b[^>]{0,200}>|<\/details[ \t]*>/gi;
+    const tags = [];
+    for (let l = lineStart.exec(scan); l; l = lineStart.exec(scan)) {
+        const from = l.index + l[0].length;
+        const nl = scan.indexOf('\n', from);
+        const lineEnd = nl === -1 ? scan.length : nl;
+        anyTag.lastIndex = from;
+        for (let t = anyTag.exec(scan); t && t.index < lineEnd; t = anyTag.exec(scan)) {
+            tags.push({ at: t.index, len: t[0].length, closer: t[0][1] === '/' });
+        }
+        lineStart.lastIndex = Math.max(lineStart.lastIndex, lineEnd);
+    }
+    // Stack pairing: every closer matches its nearest opener, so each closed pair is
+    // evaluated on its own (a nested archive inside an active wrapper is masked) and
+    // an unmatched opener or closer is ignored instead of disabling later masking.
+    const openers = [];
+    const kept = [];
+    let paired = false;
+    let strayCloser = false;
+    for (const tag of tags) {
+        if (!tag.closer) {
+            openers.push(tag.at);
+            continue;
+        }
+        const start = openers.pop();
+        if (start === undefined) {
+            // A closer with nothing to pair after an earlier pair closed: that pair may have swallowed this block's own opener.
+            if (paired)
+                strayCloser = true;
+            continue;
+        }
+        paired = true;
+        const end = tag.at + tag.len;
+        // Only a block wrapping an active heading stays editable; any other block is archive, with or without a closed <summary>.
+        if (active.some((r) => start <= r.start && r.start < end))
+            continue;
+        const inRange = overlapsActive(start, end) && !closedSummary(start);
+        // A collapsed block of the active range that holds the Progress table stays editable, so the row moves with the plan ticks.
+        // A level-1 `# Progress` has always counted here (#5692: no behavior change), hence `levels`.
+        if (inRange && (0, roadmap_progress_cjs_1.findProgressSection)(scan.slice(start, end), { levels: [1, 2] }) !== null) {
+            kept.push({ start, end });
+            continue;
+        }
+        spans.push({ start, end });
+        if (inRange)
+            inActive.push({ start, end });
+    }
+    // An opener left unpaired makes the structure ambiguous when it either opens a
+    // closed-summary archive that does not close on its own line (its extent is unknown) or precedes a masked
+    // block in the active range (it may be that block's real wrapper, with the
+    // stray tag inside). A harmless stray opener is ignored.
+    const eol = (o) => { const e = content.indexOf('\n', o); return e === -1 ? content.length : e; };
+    const ambiguous = strayCloser || openers.some((o) => closedSummary(o) && !/<\/details/i.test(content.slice(o, eol(o)))) || (openers.length > 0 && [...inActive, ...kept].some((r) => r.start > openers[0]));
+    spans.push(...plainClosedSections(content, overlapsActive, activeVersion));
+    return { spans, inActive, ambiguous };
+}
+/**
+ * #5553: hide every archived `<details>` block, and every closed milestone
+ * written as a plain heading section, behind a placeholder; `restore` puts them
+ * back unchanged. Tag case, attributes and archive position
+ * (before OR after the active milestone) do not matter, unlike a "region after
+ * the last `</details>`" cut. A block stays visible only when it wraps the
+ * start of a resolved active milestone range (`<details open>` around the
+ * active milestone); every other block is hidden, whatever its `<summary>`
+ * (none, non-closed, closed), including a collapsed block inside the active
+ * range. That is deliberate for THIS write path only; the read-side
+ * `stripClosedMilestoneDetails` window (#3982/#1341) is unchanged. With no
+ * resolvable active milestone every block is hidden, as the old
+ * last-`</details>` cut did. `ambiguous` flags unpaired tags that hide where an
+ * archive ends (the caller declines); `activeRange` is the active milestone's
+ * range in `visible` coordinates.
+ */
+function maskArchivedDetails(content, cwd) {
+    if (!/<details\b/i.test(content) && !MILESTONE_CLOSED_MARKER_PATTERN.test(content)) {
+        return { visible: content, restore: (edited) => edited, hiddenInActive: '', ambiguous: false, activeRange: null };
+    }
+    const resolved = currentMilestoneRawRanges(content, cwd);
+    // A stale STATE can name a milestone whose own heading is closed (all headings closed): nothing is active, so everything shipped stays masked.
+    const ranges = resolved && !isClosedMilestoneHeading(content.slice(resolved.primary.start).split('\n', 1)[0]) ? resolved : null;
+    const active = ranges ? [ranges.primary, ...(ranges.details ? [ranges.details] : [])] : [];
+    const { spans, inActive, ambiguous } = scanArchiveSpans(content, active);
+    const blocks = [];
+    // Unguessable per call: a plan filename or any other edited-in text cannot forge a marker.
+    const nonce = (0, node_crypto_1.randomBytes)(8).toString('hex');
+    const marker = (i) => `<!-- gsd-archived-details-${nonce}-${i} -->`;
+    spans.sort((x, y) => x.start - y.start || y.end - x.end);
+    let visible = '';
+    let last = 0;
+    const hidden = [];
+    for (const span of spans) {
+        if (span.start < last) {
+            // Nested in an already-masked span: only a partial overlap extends it.
+            if (span.end <= last)
+                continue;
+            span.start = last;
+        }
+        blocks.push(content.slice(span.start, span.end));
+        visible += content.slice(last, span.start);
+        const m = marker(blocks.length - 1);
+        hidden.push({ start: span.start, end: span.end, vis: visible.length, len: m.length });
+        visible += m;
+        last = span.end;
+    }
+    visible += content.slice(last);
+    // One pass, so a hostile ROADMAP with thousands of blocks stays linear.
+    const markerRe = new RegExp(`<!-- gsd-archived-details-${nonce}-(\\d+) -->`, 'g');
+    const restore = (edited) => {
+        const seen = new Array(blocks.length).fill(0);
+        let bad = false;
+        const restored = edited.replace(markerRe, (m, i) => {
+            const n = Number(i);
+            if (n >= blocks.length || seen[n]++ > 0) {
+                bad = true;
+                return m;
+            }
+            return blocks[n];
+        });
+        // edit dropped or duplicated a placeholder: caller must refuse rather than lose or misplace an archive
+        return bad || seen.includes(0) ? null : restored;
+    };
+    // Blocks hidden inside the active range stay unticked, but their rows still count as present.
+    const hiddenInActive = inActive.map((r) => content.slice(r.start, r.end)).join('\n');
+    // Original offset -> offset in `visible`.
+    const toVisible = (p) => {
+        let h;
+        for (const x of hidden) {
+            if (x.start < p)
+                h = x;
+            else
+                break;
+        }
+        if (!h)
+            return p;
+        return p >= h.end ? h.vis + h.len + (p - h.end) : h.vis;
+    };
+    const activeRange = active.length > 0
+        ? { start: toVisible(Math.min(...active.map((r) => r.start))), end: toVisible(Math.max(...active.map((r) => r.end))) }
+        : null;
+    return { visible, restore, hiddenInActive, ambiguous, activeRange };
 }
 /**
  * Resolve a single phase's detail-section heading (`### Phase N: …`, any level
@@ -1420,11 +1852,21 @@ function replaceInCurrentMilestone(content, pattern, replacement) {
  * phase-heading level, so a level-bounded stop could fold a deeper sibling
  * heading (e.g. a `####` phase following a `###` phase) into this phase's
  * body and let `edit` reach into it.
+ *
+ * `levelBounded: true` instead keeps the phase's own non-phase `####` sub-sections
+ * (a plan list under a sub-heading) in the body, still ending at the next heading
+ * that opens another phase, of any level. Serves the presence check and the
+ * plan-row tick writer.
  */
-function withPhaseSection(content, phaseId, edit) {
+function withPhaseSection(content, phaseId, edit, levelBounded = false) {
     const src = phaseMarkdownRegexSource(phaseId);
     const headingRe = new RegExp(`^\\s*(?:\\[[^\\]]{1,200}\\]\\s*)?Phase\\s+${src}(?=[\\s:(]|$)`, 'i');
-    return (0, markdown_sectionizer_cjs_1.withSection)(content, (h) => headingRe.test(h.text), edit, { levelBounded: false });
+    // levelBounded runs to the next same-or-higher heading, so cut at a deeper phase heading too.
+    const ownBody = !levelBounded ? edit : (body) => {
+        const cut = body.search(/^#{1,6}[ \t]+(?:\[[^\]\n]{1,200}\][ \t]*)?Phase\s+\S/m);
+        return cut === -1 ? edit(body) : edit(body.slice(0, cut)) + body.slice(cut);
+    };
+    return (0, markdown_sectionizer_cjs_1.withSection)(content, (h) => headingRe.test(h.text), ownBody, { levelBounded });
 }
 // ─── Roadmap phase lookup ─────────────────────────────────────────────────────
 // #2199: a bullet/checkbox phase entry, e.g. `- [ ] **Phase 36 — Authentication**`
@@ -1432,11 +1874,11 @@ function withPhaseSection(content, phaseId, edit) {
 // is captured in group 1, the name in group 2; the separator may be an em-dash,
 // en-dash, hyphen, or colon. Used as a fallback when no ATX heading matches, and
 // to count phases in a milestone that uses the bullet form.
-const BULLET_PHASE_LINE_PATTERN = /^\s*[-*]\s+(?:\[[ xX]\]\s+)?\*\*Phase\s+([\w][\w.-]*)(?:\s*\([^)\n]{0,200}\))?\s*[—–:\-]\s*(.+?)\*\*/im;
+const BULLET_PHASE_LINE_PATTERN = (0, phase_entry_grammar_cjs_1.phaseEntryRegExp)(`Phase\\s+([\\w][\\w.-]*)(?:\\s*\\([^)\\n]{0,200}\\))?\\s*[—–:\\-]\\s*(.+?)${phase_entry_grammar_cjs_1.PHASE_ENTRY_BOLD_CLOSE_SRC}`, 'im', { box: 'optional', bold: 'required' });
 /** Build a bullet-phase-line regex pinned to a specific phase number (#2199). */
 function bulletPhaseLineFor(phaseNum, phaseSource) {
     const num = phaseSource ?? phaseMarkdownRegexSource(phaseNum);
-    return new RegExp(`^\\s*[-*]\\s+(?:\\[[ xX]\\]\\s+)?\\*\\*Phase\\s+(${num})${OPTIONAL_PHASE_TAG_SOURCE}\\s*[—–:\\-]\\s*(.+?)\\*\\*`, 'im');
+    return (0, phase_entry_grammar_cjs_1.phaseEntryRegExp)(`Phase\\s+(${num})${OPTIONAL_PHASE_TAG_SOURCE}\\s*[—–:\\-]\\s*(.+?)${phase_entry_grammar_cjs_1.PHASE_ENTRY_BOLD_CLOSE_SRC}`, 'im', { box: 'optional', bold: 'required' });
 }
 function findRoadmapPhaseInContent(content, phaseNum, phaseSource) {
     // #1729: OPTIONAL_PHASE_TAG_SOURCE after the number tolerates a pre-colon ( ) tag.
@@ -1577,39 +2019,6 @@ function reportUnreadableRoadmap(err, roadmapPath) {
         return;
     warnUnusableInput({ reason: UNUSABLE_REASON.ROADMAP_UNREADABLE, source: roadmapPath });
 }
-// ─── Roadmap progress table (#1956/#2012 decoy avoidance) ─────────────────────
-/**
- * Locate ROADMAP.md's "Progress" table — the sole owner of the #2012
- * decoy-avoidance scope for the `drift-guard phase-status` CLI seam (#1956).
- *
- * Scopes to the `## Progress` heading first (level-2, exact case-insensitive
- * text `'progress'`, `{ levelBounded: true }`) via `collectSection` — the
- * same CRLF-safe seam `stateCurrentPositionSlice` (state-document.cts) uses
- * to scope STATE.md's `## Current Position` — so a differently-headed table
- * that happens to share the same column names (e.g. an "Archive Notes"
- * table) is never picked up instead of the real one (#2012). Falls back to
- * scanning the WHOLE document when no `## Progress` heading exists, so a
- * headingless milestone slice (#1445) still resolves rather than going
- * uncheckable — the same fallback `deriveProgressFromRoadmap`
- * (phase-lifecycle.cts) deliberately preserves.
- *
- * `deriveProgressFromRoadmap` independently expresses this same "scope to
- * `## Progress`, else whole document" rule via its own regex-based scope
- * (kept there deliberately rather than refactored onto this function — its
- * blast radius is large). The two locators are therefore separate
- * implementations of the same scoping rule and must agree about WHICH table
- * is the Progress table; a parity test in
- * tests/adr-22-plan-drift-guard.test.cjs asserts they do, per the repo's
- * generative-fix-divergence guard.
- *
- * Returns the same shape `findTableWithColumns` returns (or `null`).
- */
-function findRoadmapProgressTable(roadmapContent) {
-    const isProgressHeading = (h) => h.level === 2 && h.text.trim().toLowerCase() === 'progress';
-    const section = (0, markdown_sectionizer_cjs_1.collectSection)(roadmapContent, isProgressHeading, { levelBounded: true });
-    const scoped = section ? section.body : roadmapContent;
-    return (0, markdown_table_cjs_1.findTableWithColumns)(scoped, ['Phase', 'Plans Complete', 'Status', 'Completed']);
-}
 /**
  * Strip a leading delimiter run (whitespace, em/en-dash, colon, hyphen) from a
  * milestone-name capture. Markdown headings commonly take the shape
@@ -1766,9 +2175,9 @@ function getMilestoneInfo(cwd) {
                 const statePath = node_path_1.default.join(planningDir(cwd), 'STATE.md');
                 const stateRaw = (0, shell_command_projection_cjs_1.platformReadSync)(statePath);
                 if (stateRaw !== null) {
-                    const m = stateRaw.match(/^milestone:\s*(.+)/m);
-                    if (m) {
-                        const classified = classifyMilestoneScalar(m[1]);
+                    const milestoneScalar = readStateMilestoneScalar(stateRaw);
+                    if (milestoneScalar !== null) {
+                        const classified = classifyMilestoneScalar(milestoneScalar);
                         explicitlyNoMilestone = classified.explicitNull;
                         stateVersion = classified.version;
                     }
@@ -1902,7 +2311,7 @@ function getMilestoneInfo(cwd) {
  *   resolution exactly, including its `GSD_WORKSTREAM` env fallback — every
  *   pre-#2562 call site is unaffected.
  */
-function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention, ws) {
+function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention, ws, context) {
     const milestonePhaseNums = new Set();
     // #612: the milestone-QUALIFIED form (`{CODE}.{MM}-{PP}`) of each in-scope
     // bracket heading, kept in its OWN set — deliberately not in
@@ -1999,7 +2408,7 @@ function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention, ws) {
         // #3262 remains the single owner of the phase-set scan. #612 extends its
         // return with qualified bracket ids rather than restoring the superseded
         // inline duplicate this commit was originally written against.
-        const scanned = scanMilestonePhaseIdSets(roadmap, headingConvention);
+        const scanned = scanMilestonePhaseIdSets(roadmap, headingConvention, context);
         for (const id of scanned.ids)
             milestonePhaseNums.add(id);
         for (const qualified of scanned.qualifiedIds)
@@ -2053,7 +2462,11 @@ function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention, ws) {
         ? new RegExp(`^0*(\\d+[A-Za-z]?(?:-${phaseIdModule.PHASE_CONTINUATION_SEGMENT_SOURCE}[A-Z]?)*(?:\\.\\d+)*)(?=-|$)`)
         // phase-id-owner: the [A-Za-z] letter class does real case handling here — this regex carries NO /i flag; kept literal, not source-byte-equal to the canonical PHASE_NUMBER_TOKEN_SOURCE.
         : /^0*(\d+[A-Za-z]?(?:\.\d+)*)/;
+    const customKeys = context?.phaseNaming === 'custom' && headingConvention !== 'bracket'
+        ? new Set([...milestonePhaseNums].map(id => phaseIdModule.phaseKeyFromToken(id, context))) : null;
     function isDirInMilestone(dirName) {
+        if (customKeys)
+            return customKeys.has(phaseIdModule.phaseKeyFromDir(dirName, headingConvention, context));
         // #612: the DIR side of this filter, selected by the same convention the
         // heading side selected. Without it the heading scan's new bracket reach was
         // half a fix: `milestonePhaseNums` became non-empty, so the pass-all degrade
@@ -2142,27 +2555,31 @@ function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention, ws) {
  * Details section) — both consume the same `locateMilestoneHeadings` /
  * `computeMilestoneSectionEnd` owner (#3184), so there is no separate copy to
  * keep in sync. Returns null when there is no versioned active milestone;
- * callers then fall back to whole-content mutation (the prior behaviour).
+ * callers then fall back to the shipped-block-masked whole content
+ * (`editOutsideShippedBlocks`) via `editCurrentMilestone`, or to unscoped
+ * whole-content handling where they call this directly (`phase.cts`
+ * `phaseEntryInsertOffset`).
  *
- * #2761 (round-2 review, Minor 3 — latent, currently harmless): this function
- * consumes #3184's shared owners, but it does not pass the bracket-specific
- * B1/B2 boundary predicate and still has no bracket-fallback SELECTION branch:
- * it returns null when the version-string owner finds nothing, unlike
- * `extractCurrentMilestoneScoped`. The read owner can therefore scope a
- * bracket ROADMAP this write-range consumer still calls unscoped. Probed and
- * confirmed harmless TODAY: this
- * function's single consumer (`mutateMilestonePhase`, src/phase.cts) falls
- * back to whole-content mutation when it returns null, and every mutation
- * inside that caller is still `Phase`-labelled-only (not bracket-widened) per
- * the changeset's own "READ-path opt-in until the migrator and write path
- * land" — so a bracket ROADMAP's checkbox/heading patterns never match inside
- * that fallback and nothing is mutated cross-milestone. The moment the write
- * path is widened (PR-3+), this divergence becomes live: the whole-content
- * fallback would become a cross-milestone writer, which is exactly what this
- * note exists to prevent. Bracket-widen this function in lockstep with the
- * write path landing, not before.
+ * #2761 / #4304: bracket-widened
+ * in lockstep with the write path landing, per this doc's own prior note.
+ * `phaseIdConvention` is the same additive, optional trailing parameter
+ * `extractCurrentMilestoneScoped` accepts — omitted (every pre-#4304 2-arg
+ * call site), it compiles byte-identically to before: `bracketFallbackHeadingMatches`
+ * and `bracketAwareMilestoneSection`'s bracket branch are both no-ops unless
+ * explicitly told `'bracket'`, so a version-string match still short-circuits
+ * both, and a non-bracket/unresolved convention still returns null exactly as
+ * it always has. Now shares its heading-selection and section-end grammar
+ * with `extractCurrentMilestoneScoped` (`bracketFallbackHeadingMatches`,
+ * `selectActiveMilestoneHeading`, `bracketAwareMilestoneSection`) instead of
+ * carrying its own unwidened copy, so a version-less bracket milestone
+ * heading (`## [GSD.09] Hidden`) bounds a section for this function's callers
+ * too, not only for the read path.
+ * Consumers: `editCurrentMilestone` (`phase complete`'s `mutateMilestonePhase`,
+ * `roadmap update-plan-progress`) and `phase.cts` `phaseEntryInsertOffset`. On the null
+ * path `editCurrentMilestone` edits the ROADMAP with closed-milestone `<details>`
+ * blocks masked, so no writer reaches into a shipped block.
  */
-function currentMilestoneRawRanges(content, cwd) {
+function currentMilestoneRawRanges(content, cwd, phaseIdConvention) {
     if (!cwd)
         return null;
     let version = null;
@@ -2171,9 +2588,9 @@ function currentMilestoneRawRanges(content, cwd) {
         const statePath = node_path_1.default.join(planningDir(cwd), 'STATE.md');
         const stateRaw = (0, shell_command_projection_cjs_1.platformReadSync)(statePath);
         if (stateRaw !== null) {
-            const milestoneMatch = stateRaw.match(/^milestone:\s*(.+)/m);
-            if (milestoneMatch) {
-                const classified = classifyMilestoneScalar(milestoneMatch[1]);
+            const milestoneScalar = readStateMilestoneScalar(stateRaw);
+            if (milestoneScalar !== null) {
+                const classified = classifyMilestoneScalar(milestoneScalar);
                 version = classified.version;
                 stateAssertsNoMilestone = classified.explicitNull;
             }
@@ -2187,15 +2604,21 @@ function currentMilestoneRawRanges(content, cwd) {
     }
     if (!version)
         return null;
-    const headingMatches = locateMilestoneHeadings(content, version);
+    const bracketScopeConvention = phaseIdConvention ?? null;
+    let headingMatches = locateMilestoneHeadings(content, version);
+    if (headingMatches.length === 0) {
+        headingMatches = bracketFallbackHeadingMatches(content, version, bracketScopeConvention);
+    }
     if (headingMatches.length === 0)
         return null;
     const isClosed = isClosedMilestoneHeading;
     // #3184: selection collapses to the sole owner; `headingMatches` is still
     // needed below for the detailsMatch search over all headings.
-    const selected = selectMilestoneHeading(content, version);
+    const selected = selectActiveMilestoneHeading(content, version, headingMatches);
     const sectionStart = selected.index ?? 0;
-    const sectionEnd = computeMilestoneSectionEnd(content, selected[0], sectionStart);
+    const bracketBoundaryActive = bracketScopeConvention === 'bracket';
+    const currentMilestoneHeadings = (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(content);
+    const { sectionEnd, bracketBoundary } = bracketAwareMilestoneSection(content, selected, sectionStart, bracketBoundaryActive, currentMilestoneHeadings);
     const selectedVersionToken = selected[1].match(/v\d+(?:\.\d+)+(?:[-.][A-Za-z0-9]+)*/i)?.[0];
     const detailsVersionBoundary = selectedVersionToken
         ? new RegExp(`${(0, pattern_cjs_1.escapeRegex)(selectedVersionToken)}(?![\\w.-])`, 'i')
@@ -2207,10 +2630,160 @@ function currentMilestoneRawRanges(content, cwd) {
     let details = null;
     if (detailsMatch) {
         const detailsStart = detailsMatch.index ?? 0;
-        details = { start: detailsStart, end: computeMilestoneSectionEnd(content, detailsMatch[0], detailsStart) };
+        // #4304: pass the SAME bracketBoundary (and heading tokens)
+        // bracketAwareMilestoneSection already derived for the primary range —
+        // extractCurrentMilestoneScoped's own details lookup (line ~1312) has
+        // always done this; this copy omitted both trailing arguments, so a
+        // version-less bracket milestone heading (no v\d+.\d+/emoji marker) never
+        // stopped this details window at the NEXT milestone's own "(Phase
+        // Details)" section, and the two copies silently disagreed on the active
+        // details window.
+        details = {
+            start: detailsStart,
+            end: computeMilestoneSectionEnd(content, detailsMatch[0], detailsStart, bracketBoundary, currentMilestoneHeadings),
+        };
     }
     return { primary: { start: sectionStart, end: sectionEnd }, details };
 }
+/** `<details>` / `</details>` tags of `content` in document order (bare opener only: `<details open>` wraps the active milestone, it is not an archive). */
+function bareDetailsTags(content) {
+    return [...content.matchAll(/<(\/?)details>/gi)].map((m) => ({ at: m.index, close: m[1] === '/' }));
+}
+/** Whether offset `idx` sits inside a bare `<details>` block that has not closed yet (`tags` from `bareDetailsTags`). */
+function insideBareDetails(tags, idx) {
+    let lo = 0;
+    let hi = tags.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (tags[mid].at < idx)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo > 0 && !tags[lo - 1].close;
+}
+/** A phase heading or a bold phase-list entry: what makes a block a shipped/backlog milestone. */
+const ACTIVE_SCOPE_PHASE_ENTRY_SRC = `(?:^#{2,4}[ \\t]+Phase\\b|${(0, phase_entry_grammar_cjs_1.phaseEntryPrefixSrc)({ bold: 'required' })}Phase\\b)`;
+/**
+ * The active milestone's writable scope as offsets into `content`.
+ *
+ * `start` is just past the last `</details>` that closes BEFORE the selected
+ * milestone heading, so a backlog `</details>` AFTER it no longer hides it
+ * (#5221) while phase/Progress content above the heading (#2947 preamble layout)
+ * stays in scope. No resolved heading, or one that is itself closed (stale
+ * STATE), uses the last `</details>` before the first phase entry outside any
+ * open <details>, so a backlog `</details>` below the active phases does not
+ * hide them.
+ *
+ * `end` is the first line-leading bare `<details>` AFTER that heading (or first
+ * phase entry): a shipped block placed below the active milestone is never
+ * writable, so a second run cannot tick the archived phase once the active one
+ * is done. Writers that must reach a bottom `## Progress` past a backlog block
+ * (`editProgressTableSlice`) use `start` alone. Tags match case-insensitively.
+ * An archive whose `</details>` is missing cannot be told from a wrapper, so
+ * `start` stays 0 for it (documented fail-open).
+ */
+function activeScope(content, cwd) {
+    const tags = bareDetailsTags(content);
+    const headingAt = currentMilestoneRawRanges(content, cwd)?.primary.start;
+    const open = headingAt !== undefined && !isClosedMilestoneHeading(content.slice(headingAt).split('\n', 1)[0]);
+    let anchor;
+    if (open) {
+        anchor = headingAt;
+    }
+    else {
+        const firstActive = [...content.matchAll(new RegExp(ACTIVE_SCOPE_PHASE_ENTRY_SRC, 'gim'))]
+            .find((m) => !insideBareDetails(tags, m.index));
+        anchor = firstActive?.index ?? content.length;
+    }
+    let start = 0;
+    for (const t of tags) {
+        if (t.at >= anchor)
+            break;
+        if (t.close)
+            start = t.at + '</details>'.length;
+    }
+    // Only a block that carries phase entries is a shipped/backlog milestone; a collapsible note inside the active milestone stays writable.
+    const phaseEntry = new RegExp(ACTIVE_SCOPE_PHASE_ENTRY_SRC, 'im');
+    const below = tags.find((t, i) => {
+        if (t.close || t.at <= anchor || !/^[ \t]*$/.test(content.slice(content.lastIndexOf('\n', t.at - 1) + 1, t.at)))
+            return false;
+        const close = tags.slice(i + 1).find((c) => c.close);
+        return phaseEntry.test(content.slice(t.at, close ? close.at : content.length));
+    });
+    return { start, end: below ? below.at : content.length };
+}
+function activeScopeStart(content, cwd) {
+    return activeScope(content, cwd).start;
+}
+/** [start,end) windows of the current milestone, document order; the whole ROADMAP when none resolves. */
+function currentMilestoneWindows(content, cwd) {
+    const ranges = currentMilestoneRawRanges(content, cwd);
+    if (!ranges)
+        return [{ start: 0, end: content.length }];
+    // `details` always starts at or after `primary.end` (see `currentMilestoneRawRanges`),
+    // so this is document order: a "first window wins" caller means the primary one.
+    return [ranges.primary, ranges.details].filter((w) => w !== null);
+}
+/**
+ * Read-only counterpart of `editCurrentMilestone`: the text of each window,
+ * with closed-milestone `<details>` blocks hidden exactly as the writers see it.
+ */
+function readCurrentMilestone(content, cwd) {
+    return currentMilestoneWindows(content, cwd).map((w) => maskShippedBlocks(content.slice(w.start, w.end)).masked);
+}
+/**
+ * Run `edit` over the current milestone's raw window(s) from
+ * `currentMilestoneRawRanges`, or, when no milestone resolves, over the whole
+ * ROADMAP, each with closed-milestone `<details>` blocks hidden (#5543;
+ * `editOutsideShippedBlocks`: a notes or phase-wrapper block stays editable).
+ * `edit` is called once per window, in document order. The one milestone
+ * scoping for per-phase writers (`phase complete`, `roadmap
+ * update-plan-progress` #5483), so neither cuts at the last `</details>`.
+ */
+function editCurrentMilestone(content, cwd, edit) {
+    const windows = currentMilestoneWindows(content, cwd);
+    const edited = windows.map((w) => editOutsideShippedBlocks(content.slice(w.start, w.end), edit));
+    // Splice last-first so an earlier window's offsets are not shifted by a
+    // length-changing mutation in a later window.
+    return windows.reduceRight((acc, w, i) => acc.slice(0, w.start) + edited[i] + acc.slice(w.end), content);
+}
+/**
+ * The checklist bullet of the phase whose number matches `phasePattern`
+ * (`- [ ] **Phase N: …**`), as the one grammar shared by the Plans-count /
+ * completion stamp and the plan-row ticks. `anyState` also matches a checked box.
+ * Group 1 is everything through the opening `[` (indent and marker included),
+ * group 2 the rest of the line from the closing `]`. The prefix (marker, box, bold token) is the phase-entry grammar's (#5764); the
+ * tail stops before `\r` so a stamp appended to group 2 lands on the entry's
+ * line, before its CRLF.
+ */
+function phaseChecklistBullet(phasePattern, anyState) {
+    return (0, phase_entry_grammar_cjs_1.phaseEntrySplitRegExp)(`Phase[ \\t]+${phasePattern}${OPTIONAL_PHASE_TAG_SOURCE}(?=[:\\s]|$)[^\\r\\n]*`, 'i', { state: anyState ? 'any' : 'unchecked' });
+}
+/** A checklist bullet of ANY phase: ends the rows nested under the previous one. */
+const ANY_PHASE_BULLET = (0, phase_entry_grammar_cjs_1.phaseEntryRegExp)('Phase[ \\t]', 'i');
+/**
+ * [start,end) of the rows nested under a phase's checklist bullet: from the
+ * line after `bullet` (a match of `phaseChecklistBullet` in `text`) up to a
+ * blank line, a shallower line, or the next phase's bullet. Empty when the
+ * bullet is the last line with no trailing newline.
+ */
+function checklistBulletExtent(text, bullet) {
+    // The bullet's own indent, read from its line: a caller's capture group 1 may
+    // be the indent alone (which has no non-space and used to give -1, so a
+    // shallower line never ended the extent) or everything through the `[`.
+    const depth = text.slice(bullet.index).search(/\S/);
+    const start = text.indexOf('\n', bullet.index) + 1;
+    let end = start;
+    while (start > 0 && end < text.length) {
+        const next = text.indexOf('\n', end);
+        const line = text.slice(end, next === -1 ? text.length : next);
+        if (line.trim() === '' || line.search(/\S/) < depth || ANY_PHASE_BULLET.test(line))
+            break;
+        end = next === -1 ? text.length : next + 1;
+    }
+    return { start, end };
+}
 /**
  * #4731 — extract a bold-labeled phase field (Goal, Requirements, ...) reading
  * past hard-wrapped continuation lines. The roadmapper soft-wraps long fields
@@ -2275,21 +2848,32 @@ function extractPhaseFieldMultiline(section, label) {
     return [firstLine, ...contLines].join(' ').trim() || null;
 }
 module.exports = {
+    activeScope,
+    activeScopeStart,
     stripShippedMilestones,
     extractCurrentMilestone,
     extractCurrentMilestoneScoped,
     isMilestoneShippedInRoadmap,
     isMilestoneBoundedInRoadmap,
-    replaceInCurrentMilestone,
+    maskArchivedDetails,
     getRoadmapPhaseInternal,
     getMilestoneInfo,
     classifyMilestoneScalar,
+    readStateMilestoneScalar,
     getMilestonePhaseFilter,
     currentMilestoneRawRanges,
     withPhaseSection,
+    editOutsideShippedBlocks,
+    editCurrentMilestone,
+    readCurrentMilestone,
+    phaseChecklistBullet,
+    checklistBulletExtent,
     computeMilestoneSectionEnd,
     locateMilestoneHeadings,
     listMilestoneHeadings,
+    // #4304: historical mutation guards consume the window locator's
+    // milestone-vs-phase decision before applying CLOSED markers.
+    isRecognizedMilestoneHeading,
     selectMilestoneHeading,
     classifyMilestoneWindow,
     // #3184: the sole "give me this version's window" composition — see its
@@ -2301,9 +2885,6 @@ module.exports = {
     hasMilestoneSectioning,
     // #3642: the >=1 sibling buildStateFrontmatter's unbounded branch consumes.
     hasAnyMilestoneSection,
-    // #1956: sole owner of the #2012 decoy-avoidance scope for the
-    // `drift-guard phase-status` CLI seam.
-    findRoadmapProgressTable,
     // #3262 (write-time milestone-scope guard): the window phase-id scan owner
     // (consumed by getMilestonePhaseFilter above and the roadmap milestone-scope
     // CLI probe) and the free-text predicate the phase add/add-batch/insert
@@ -2317,6 +2898,23 @@ module.exports = {
     // owner (and its convention gate) instead of a private inline copy.
     extractPhaseFieldMultiline,
     hasPhaseEntries,
+    isPhaseEntryHeading,
+    // #4304: exported so `phase.cts`'s milestone-marker
+    // enumeration (bracketRecognizedMilestoneMarkers) can recognize a
+    // version-less bracket milestone heading through the SAME grammar the
+    // window locator (bracketAwareMilestoneSection) already uses to decide
+    // section boundaries, instead of a narrower, independently-typed copy.
+    isBracketMilestoneBoundary,
+    bracketFallbackHeadingMatches,
+    // #4304: exported so `phase.cts`'s pre-mutation window guard
+    // (bracketOwnedLineOutsideActiveWindow) can recognize a CLOSED/shipped
+    // milestone heading through the SAME predicate `currentMilestoneRawRanges`
+    // itself already uses to skip a closed heading when selecting the active
+    // one, instead of a re-typed copy of MILESTONE_CLOSED_MARKER_PATTERN.
+    isClosedMilestoneHeading,
+    // #4304: destructive ROADMAP writers classify details blocks through
+    // the same closed-summary rule as stripClosedMilestoneDetails.
+    isClosedMilestoneDetails,
     // #4144 round 5 Blocker 1: the readers' own phase-heading grammar, so the
     // bracket roadmap migrator's "phase-like but unparsed" refusal
     // (src/roadmap-upgrade.cts) can gate on it instead of a private, looser