@opengsd/gsd-core 1.14.0 → 1.15.0

package/gsd-core/bin/lib/project-root.cjs

@@ -17,12 +17,28 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.setExplicitProjectRoot = setExplicitProjectRoot;
+exports.resolveProjectRoot = resolveProjectRoot;
 exports.findProjectRoot = findProjectRoot;
 exports.consentProjectRoot = consentProjectRoot;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
 const FIND_PROJECT_ROOT_MAX_DEPTH = 10;
+// #4894: an operator-supplied `--project-dir` IS the project root — the
+// dispatcher validates it and skips the ancestor walk-up for `cwd`, but code
+// that derives a root from a PHASE DIRECTORY (verification) never sees `cwd`.
+// The dispatcher records the validated root here, once per process, and those
+// callers resolve through `resolveProjectRoot`. `null` (the default, and what
+// the dispatcher sets when the flag is absent) leaves `findProjectRoot`'s
+// walk-up as the only source of truth, so no-flag behavior is unchanged.
+let explicitProjectRoot = null;
+function setExplicitProjectRoot(root) {
+    explicitProjectRoot = root;
+}
+function resolveProjectRoot(startDir) {
+    return explicitProjectRoot ?? findProjectRoot(startDir);
+}
 function findProjectRoot(startDir) {
     let resolvedStart;
     try {
@@ -43,12 +59,35 @@ function findProjectRoot(startDir) {
     catch {
         // fall through
     }
+    // A `.planning` that is itself a symlink is a deliberate hop into a separate
+    // tree (the documented "keep planning content out of the tracked repo"
+    // convention: `.planning -> ~/.gsd-external-planning/<project>/`, its own git
+    // repo). `fs.existsSync(d + '/.git')` DEREFERENCES `d`, so at `d ===
+    // <the .planning symlink path>` it finds the EXTERNAL store's `.git`, and
+    // both isInsideGitRepo/nearestGitRoot misread it as a crossed nested-child-
+    // repo boundary (#2843's guard). `fs.lstatSync` does not dereference its
+    // final path component, so it answers "is `d` ITSELF a symlink" (#4815).
+    //
+    // Deliberately scoped to a symlink named `.planning`, NOT any symlinked
+    // directory: a nested child repo reached through some other symlinked
+    // ancestor is still a real repo boundary, and skipping it would reopen
+    // #2843 through a different trigger.
+    function isSymlinkedPlanningDir(d) {
+        if (node_path_1.default.basename(d) !== '.planning')
+            return false;
+        try {
+            return node_fs_1.default.lstatSync(d).isSymbolicLink();
+        }
+        catch {
+            return false;
+        }
+    }
     // Walk upward, mirroring isInsideGitRepo from the CJS reference.
     function isInsideGitRepo(candidateParent) {
         let d = resolvedStart;
         while (d !== fsRoot) {
             try {
-                if (node_fs_1.default.existsSync(d + node_path_1.default.sep + '.git'))
+                if (!isSymlinkedPlanningDir(d) && node_fs_1.default.existsSync(d + node_path_1.default.sep + '.git'))
                     return true;
             }
             catch {
@@ -77,7 +116,7 @@ function findProjectRoot(startDir) {
             if (d === upTo)
                 break;
             try {
-                if (node_fs_1.default.existsSync(d + node_path_1.default.sep + '.git'))
+                if (!isSymlinkedPlanningDir(d) && node_fs_1.default.existsSync(d + node_path_1.default.sep + '.git'))
                     return d;
             }
             catch {

package/gsd-core/bin/lib/review-lane-descriptor.cjs

@@ -64,7 +64,7 @@ exports.checkReviewerDocsParity = checkReviewerDocsParity;
  * `args` is an argv TEMPLATE, not a prefix. The injected pieces — model, effort, output file,
  * argv-borne prompt — do not all go in the same place, and no positional rule expresses that:
  * `codex` injects the model in the MIDDLE (after the `exec --ephemeral` subcommand) and the output
- * file later still, while `gemini` injects the model first and five lanes end with a bare `-` that
+ * file later still, while `kimi-code` injects the model first and five lanes end with a bare `-` that
  * must stay last. Splicing by position silently produced
  * `codex --model M -o F exec --ephemeral …`, which is not a valid codex invocation.
  *
@@ -94,36 +94,16 @@ const SPAWN_STDIN_STDOUT = {
     outputChannel: 'stdout',
 };
 /**
- * The twelve declared lanes, in `write_reviews` order.
+ * The eleven declared lanes, in `write_reviews` order.
+ *
+ * The `gemini` lane was retired by #4709: Google sunset Gemini CLI on 2026-06-18 (the same
+ * sunset that removed the gemini RUNTIME in #1928/1.8.0), so the lane spawned a binary that no
+ * longer serves the free/Pro/Ultra tiers that are GSD's audience.
  *
  * `kimi-code` joined in Phase 5b (#2799, closes #2718) — ADR-2782's phase table lands it here
  * rather than in 5a precisely so it arrives together with the iteration that can invoke it.
  */
 exports.REVIEWER_LANES = Object.freeze([
-    {
-        slug: 'gemini',
-        flags: ['--gemini'],
-        transport: 'spawn',
-        probe: { kind: 'command-exists', binary: 'gemini' },
-        invoke: {
-            binary: 'gemini',
-            args: ['{{model}}', '-p', '-'],
-            ...SPAWN_STDIN_STDOUT,
-            modelArg: '-m',
-            effortChannel: 'none',
-        },
-        timeoutFloorMs: 900_000,
-        timeoutConfigKey: 'review.timeouts.gemini',
-        emptyOutput: 'stub-with-stderr',
-        reviewsSection: 'Gemini',
-        evidenceClass: 'source-grounded',
-        requiresBinaries: [],
-        promptBudgetKey: 'review.max_prompt_tokens_per_reviewer.gemini',
-        modelConfigKey: 'review.models.gemini',
-        effortConfigKey: null,
-        defaultEffort: null,
-        handler: null,
-    },
     {
         // 1_200_000 rather than the 900_000 floor: headless Claude measured ~525 s
         // on a large plan set (review.md:304).
@@ -139,8 +119,8 @@ exports.REVIEWER_LANES = Object.freeze([
             effortChannel: 'argv',
             // #2483: without these the claude leg is the only reviewer that additionally inherits the
             // invoking user's global CLAUDE.md, the project CLAUDE.md, and Claude Code auto-memory —
-            // a context asymmetry against the independent-review premise (gemini sees only the
-            // assembled prompt; codex runs --ephemeral). Both flags, not just the first: CLAUDE.md
+            // a context asymmetry against the independent-review premise (codex sees only the
+            // assembled prompt and runs --ephemeral). Both flags, not just the first: CLAUDE.md
             // loading and auto-memory are independently-toggled mechanisms, and an environment
             // exporting CLAUDE_CODE_DISABLE_AUTO_MEMORY=0 forces auto-memory back ON — the explicit
             // pair is robust against that. Applies when /gsd:review runs from a non-Claude-Code host;
@@ -796,7 +776,7 @@ const NON_LANE_SIGNATURE_FLAGS = new Set(['--all']);
 /**
  * Is `flag` documented in `text` under one of the two structural shapes docs actually use?
  *
- * Backticked is the `COMMANDS.md` table-cell shape; bracketed (`[--gemini]`) is the
+ * Backticked is the `COMMANDS.md` table-cell shape; bracketed (`[--codex]`) is the
  * `FEATURES.md` signature shape. Requiring one of those two delimiters — rather than a bare
  * substring — is what keeps prose and fenced examples from satisfying the gate, and it bounds the
  * token for free: a backticked `--claude` demands its closing backtick, so a backticked
@@ -889,7 +869,7 @@ const BRACKETED_FLAG_RE = /\[(--[a-z0-9][a-z0-9-]*)\]/g;
  * cell 3. A file-scoped check is therefore satisfied by the forwarding row alone, so deleting a
  * lane's actual table row — the exact #2781 regression — passes. Keying on cell 1 separates the
  * two: `| `--agy` / `--antigravity` | … |` is one lane row declaring two flags, while
- * `| Reviewer flags | No | … `--gemini`, `--claude` … |` is not a lane row at all.
+ * `| Reviewer flags | No | … `--codex`, `--claude` … |` is not a lane row at all.
  */
 function flagsInFirstTableCell(lines, declared) {
     const found = new Set();

package/gsd-core/bin/lib/review-reviewer-selection.cjs

@@ -20,7 +20,7 @@
  * `reviewer` bodies in the capability registry, not a hand-maintained tail.
  * A capability of EITHER `role: "runtime"` (the six dual-purpose hosts —
  * antigravity/claude/codex/cursor/opencode/qwen) or the lane-only
- * `role: "reviewer"` (gemini/coderabbit/ollama/lm_studio/llama_cpp) may carry
+ * `role: "reviewer"` (coderabbit/ollama/lm_studio/llama_cpp) may carry
  * a `reviewer` body, and it is the body's `reviewer.slug` — NOT the capability
  * id — that becomes the roster entry: the two differ for `lm-studio` (id) /
  * `lm_studio` (slug) and `llama-cpp` (id) / `llama_cpp` (slug), ADR-2782's
@@ -229,7 +229,7 @@ function resolveReviewerSelection(input) {
         // ADR-2782 D4: absent-safe governs DISCOVERY, never explicit selection.
         // Not finding a lane nobody asked for is normal; failing to run a lane
         // somebody asked for is an error. Every miss used to be an `info`, so a
-        // PARTIAL miss (`--gemini --qwen` with qwen absent) ran the review with a
+        // PARTIAL miss (`--codex --qwen` with qwen absent) ran the review with a
         // thinner reviewer set while present_results reported success — "a cross-AI
         // review that silently drops a lane is blind in one eye" (review.md).
         // A total miss already errored, but only as a side effect of the selected

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

@@ -19,6 +19,9 @@ const { routeCjsCommandFamily } = cjsCommandRouterAdapter;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapUpgrade = require("./roadmap-upgrade.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseIdCardMod = require("./phase-id-card.cjs");
+const { phaseIdCard } = phaseIdCardMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
 const { planningDir } = planningWorkspace;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -234,7 +237,7 @@ function routeRoadmapCommand({ roadmap, args, cwd, raw, error }) {
             'upgrade': () => {
                 const dryRun = !args.includes('--apply');
                 // Parse `--convention <value>` and `--convention=<value>`. When the flag is
-                // absent entirely, default to the only supported convention; when present
+                // absent entirely, default to the legacy supported convention; when present
                 // with a missing/unsupported value, fall through to the rejection below
                 // (fail-closed — never silently run a migration the user did not request).
                 let convention = 'milestone-prefixed';
@@ -245,13 +248,18 @@ function routeRoadmapCommand({ roadmap, args, cwd, raw, error }) {
                         ? token.slice(token.indexOf('=') + 1)
                         : (args[conventionFlagIdx + 1] ?? '');
                 }
-                if (convention !== 'milestone-prefixed') {
+                if (convention !== 'milestone-prefixed' && convention !== 'bracket') {
                     // No-throw hub contract (ADR-0012): a hub-dispatched handler must not call
                     // process.exit. Throw instead — the hub converts this to HandlerFailure and
                     // the adapter routes it through the injected error() boundary.
-                    throw new Error('Only --convention milestone-prefixed is supported');
+                    throw new Error('Only --convention milestone-prefixed or bracket is supported');
+                }
+                if (convention === 'bracket') {
+                    // Keep stdout machine-readable for the dry-run JSON plan. The card is
+                    // human guidance emitted at command start for both dry-run and apply.
+                    process.stderr.write(`${phaseIdCard({ title: 'Bracket phase-ID convention' })}\n`);
                 }
-                const plan = roadmapUpgrade.computeMigrationPlan(cwd);
+                const plan = roadmapUpgrade.computeMigrationPlan(cwd, { convention });
                 roadmapUpgrade.applyMigration(cwd, plan, { dryRun });
             },
         },

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

@@ -571,6 +571,55 @@ function sliceMilestoneWindow(content, version) {
         return null;
     return content.slice(selected.index, computeMilestoneSectionEnd(content, selected[0], selected.index));
 }
+/**
+ * Enumerate the milestone section ranges recognized by the ROADMAP readers.
+ * Markdown boundaries reuse the reader's heading tokenizer, milestone-signal
+ * vocabulary, name/version extractor, and section-end owner. Collapsed
+ * archives reuse the same `<details><summary>` shape handled by
+ * `extractCurrentMilestoneScoped`.
+ */
+function milestoneSections(content) {
+    const sections = [];
+    const headings = (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(content);
+    for (const heading of headings) {
+        if (heading.level < 1 || heading.level > 3)
+            continue;
+        if (/^Phase\s+\S/i.test(heading.text))
+            continue;
+        if (!MILESTONE_HEADING_SIGNAL_PATTERN.test(heading.text))
+            continue;
+        const extracted = extractMilestoneHeadingName(heading.text);
+        const version = extracted?.version ?? null;
+        const versionMajor = version?.match(/^v(\d+)/i);
+        const milestoneInt = versionMajor ? parseInt(versionMajor[1], 10) : null;
+        const lineEnd = content.indexOf('\n', heading.offset);
+        const fullLine = content.slice(heading.offset, lineEnd === -1 ? content.length : lineEnd);
+        sections.push({
+            start: heading.offset,
+            end: computeMilestoneSectionEnd(content, fullLine, heading.offset, undefined, headings),
+            version,
+            milestoneInt: milestoneInt !== null && Number.isSafeInteger(milestoneInt) ? milestoneInt : null,
+        });
+    }
+    const detailsPattern = /<details\b[^>]*>[\s\S]*?<\/details>/gi;
+    let detailsMatch;
+    while ((detailsMatch = detailsPattern.exec(content)) !== null) {
+        const summary = detailsMatch[0].match(/<summary[^>]*>([^<]*)<\/summary>/i)?.[1]?.trim() ?? '';
+        if (!MILESTONE_HEADING_SIGNAL_PATTERN.test(summary))
+            continue;
+        const extracted = extractMilestoneHeadingName(summary);
+        const version = extracted?.version ?? null;
+        const versionMajor = version?.match(/^v(\d+)/i);
+        const milestoneInt = versionMajor ? parseInt(versionMajor[1], 10) : null;
+        sections.push({
+            start: detailsMatch.index,
+            end: detailsMatch.index + detailsMatch[0].length,
+            version,
+            milestoneInt: milestoneInt !== null && Number.isSafeInteger(milestoneInt) ? milestoneInt : null,
+        });
+    }
+    return sections.sort((a, b) => a.start - b.start || a.end - b.end);
+}
 /**
  * #3184: counts RAW phase references — a `#{2,4} Phase <id>:` heading
  * (fence-aware via `tokenizeHeadings`) or a `#2199` bullet entry — BEFORE any
@@ -600,17 +649,37 @@ function sliceMilestoneWindow(content, version) {
 // decoy `### [GSD.04] Notes:` outside the window manufactured a false V005
 // while suppressing the correct V004. The digit anchor forecloses both.
 const BRACKET_PHASE_ENTRY_HEADING_RE = new RegExp(`^${PHASE_HEADING_PREFIX_SRC}${PHASE_NUMBER_TOKEN_SOURCE}${OPTIONAL_PHASE_TAG_SOURCE}\\s*:`, 'i');
+// #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal
+// mirror of OPTIONAL_PHASE_TAG_SOURCE). Hoisted out of hasPhaseEntries (#4144
+// round 5 Blocker 1) so a consumer OUTSIDE this file's own phase-entry count —
+// the bracket roadmap migrator's "phase-like but unparsed" refusal
+// (src/roadmap-upgrade.cts) — can ask "is this heading text a phase heading
+// by the readers' own rules" without re-deriving the pattern. A heading with
+// no phase-number token and no trailing colon (`## Phase Details`, `##
+// Phase Lifecycle`, `### Phase Notes`) is NOT a phase heading by this
+// grammar — it is an ordinary section heading that happens to start with the
+// word "Phase".
+const PHASE_HEADING_TEXT_RE = /^(?:\[[^\]]{1,200}\]\s*)?Phase\s+([\w][\w.-]*)(?:\s*\([^)\n]{0,200}\))?\s*:/i;
+/**
+ * #4144 round 5 Blocker 1: whether `headingText` — a heading's text with its
+ * 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.
+ */
+function isPhaseHeadingText(headingText) {
+    return PHASE_HEADING_TEXT_RE.test(headingText);
+}
 function hasPhaseEntries(markdown, phaseIdConvention) {
-    // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
     // #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 phaseHeadingPattern = /^(?:\[[^\]]{1,200}\]\s*)?Phase\s+([\w][\w.-]*)(?:\s*\([^)\n]{0,200}\))?\s*:/i;
     const bracketMode = phaseIdConvention === 'bracket';
     for (const h of (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(markdown)) {
         if (h.level < 2 || h.level > 4)
             continue;
-        if (phaseHeadingPattern.test(h.text))
+        if (isPhaseHeadingText(h.text))
             return true;
         if (bracketMode && BRACKET_PHASE_ENTRY_HEADING_RE.test(h.text))
             return true;
@@ -671,6 +740,23 @@ function collectTablePhaseRows(window) {
     }
     return rows;
 }
+/**
+ * True when `content` contains a GFM table whose header row is phase-listing
+ * SHAPED (`| Phase | ... |`), regardless of whether it also declares a `Name`
+ * column. `collectTablePhaseRows` correctly refuses to mint a phase from a
+ * `| Phase | Status |`-shaped table (no name column, so no declaration) —
+ * but that table's mere presence still signals this roadmap has moved to
+ * table-based tracking, not checklist-based tracking. Callers that decide
+ * whether to treat bare checklist entries as phase declarations (#4899's
+ * roadmap.cts synthesis fallback) must see this signal even when
+ * `collectTablePhaseRows` itself returns nothing for the same content —
+ * otherwise a thin, name-less Progress table cannot suppress a checklist
+ * synthesis it was never meant to coexist with.
+ */
+function hasPhaseListingTableHeader(content) {
+    const unfenced = (0, markdown_sectionizer_cjs_1.stripFencedCode)(content).text;
+    return unfenced.split(/\r?\n/).some((line) => PHASE_LISTING_HEADER_RE.test(line));
+}
 /**
  * #3262: the sole owner of "which phase ids does THIS milestone window
  * declare". Extracted verbatim from `getMilestonePhaseFilter`'s former inline
@@ -965,6 +1051,7 @@ function extractCurrentMilestoneScoped(content, cwd, ws, phaseIdConvention) {
                 const preambleCutoff = firstMilestoneMatch ? firstMilestoneMatch.index : detailsOpenIdx;
                 const preamble = (0, markdown_sectionizer_cjs_1.stripTaggedBlocks)(content.slice(0, preambleCutoff), 'details')
                     // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+                    // phase-id-owner: pre-existing hand-rolled Phase-heading pattern — grandfathered pending Phase 6 migration (ADR-4910 §8, epic #4906)
                     .replace(/^#{2,4}\s*Phase\s+[\w][\w.-]*(?:\s*\([^)\n]{0,200}\))?\s*:[^\n]*(?:\n(?!#{1,6}\s)[^\n]*)*\n?/gim, '')
                     .replace(/^#{1,4}\s*Phase Details\b[^\n]*\n?/gim, '');
                 const value = preamble + content.slice(detailsOpenIdx, detailsEnd);
@@ -1200,6 +1287,7 @@ function extractCurrentMilestoneScoped(content, cwd, ws, phaseIdConvention) {
     // every phase (phase_count: 0, exit 0). Only strip preamble phase details when
     // the selected milestone section actually contains its own — otherwise the
     // preamble phases ARE this milestone's phases and must be preserved.
+    // phase-id-owner: pre-existing hand-rolled Phase-heading pattern — grandfathered pending Phase 6 migration (ADR-4910 §8, epic #4906)
     const currentSectionHasPhaseDetails = /^#{2,4}\s*Phase\s+\S/im.test(currentSection);
     const preambleBase = (0, markdown_sectionizer_cjs_1.stripTaggedBlocks)(beforeMilestones, 'details');
     // #3235: the conditional wraps the REPLACE, not the pattern. This used to select between the
@@ -1208,6 +1296,7 @@ function extractCurrentMilestoneScoped(content, cwd, ws, phaseIdConvention) {
     // replacement argument, so changing `''` would silently give the no-op branch a real effect.
     // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
     const preambleWithoutPhaseDetails = currentSectionHasPhaseDetails
+        // phase-id-owner: pre-existing hand-rolled Phase-heading pattern — grandfathered pending Phase 6 migration (ADR-4910 §8, epic #4906)
         ? preambleBase.replace(/^#{2,4}\s*Phase\s+[\w][\w.-]*(?:\s*\([^)\n]{0,200}\))?\s*:[^\n]*(?:\n(?!#{1,6}\s)[^\n]*)*\n?/gim, '')
         : preambleBase;
     // Unconditional in BOTH branches -- the #730 `Phase Details` heading strip is independent of
@@ -2056,6 +2145,69 @@ function currentMilestoneRawRanges(content, cwd) {
     }
     return { primary: { start: sectionStart, end: sectionEnd }, details };
 }
+/**
+ * #4731 — extract a bold-labeled phase field (Goal, Requirements, ...) reading
+ * past hard-wrapped continuation lines. The roadmapper soft-wraps long fields
+ * at ~85 chars, so a single-line capture silently truncated every wrapped
+ * Goal/Requirements. Stops at: another `**Field**` label line, a blank line,
+ * or any heading. Wrapped lines are trimmed and joined with single spaces; a
+ * single-line field is returned unchanged (trimmed). Returns null when the
+ * label is absent.
+ */
+function extractPhaseFieldMultiline(section, label) {
+    // #2769 label shapes: `**X:**`, `**X**:`, and the spaced `**X** :`.
+    // #4837: anchored to line start (`^[ \t]*`, `m` flag) so an inline
+    // `**Label**` mention embedded in an EARLIER field's own body text cannot
+    // shadow the real field's own declaration line. `[ \t]*` (not `\s*`) keeps
+    // the anchor scoped to same-line leading whitespace under the `m` flag.
+    const labelRe = new RegExp('^[ \\t]*\\*\\*' + label + '(?::\\*\\*|\\*\\*\\s*:?)\\s*([^\\n]+)', 'im');
+    const match = section.match(labelRe);
+    if (!match)
+        return null;
+    const startIdx = match.index ?? 0;
+    const after = section.slice(startIdx + match[0].length);
+    const firstLine = match[1].trim();
+    // #4837 (isolated-review finding): the continuation loop's fence-stop check
+    // only ever sees lines AFTER the label's own line — a fence opener on the
+    // SAME line as the label (`**Requirements:** ```js`) was invisible to it,
+    // leaking one line of fence content before the closing fence line
+    // coincidentally matched the same stop check. Checked here too, so a fence
+    // opening on the label's own line is caught just as conservatively.
+    if (/^(?:`{3,}|~{3,})/.test(firstLine))
+        return null;
+    const contLines = [];
+    const lines = after.split('\n');
+    for (let li = 0; li < lines.length; li++) {
+        const raw = lines[li];
+        // The split's first element is the remainder of the captured first line's
+        // own newline — an empty leading element is the line break, not a blank
+        // continuation line.
+        if (li === 0 && !raw.trim())
+            continue;
+        if (!raw.trim())
+            break;
+        // #4837: a list item is a structural boundary — the real corruption
+        // vector (a `- Deferred to Phase N: OTHER-ID` bullet folding a foreign
+        // REQ-ID into this field's citation-scan input).
+        if (/^\s*[-*+]\s/.test(raw))
+            break;
+        // #4837: case-insensitive label-start character class — a
+        // lowercase-first-letter label (`**requirements:**`) is as much a field
+        // boundary as a capitalized one.
+        if (/^\s*\*\*[A-Za-z][A-Za-z ]*:?(\*\*)?:?\s/.test(raw))
+            break;
+        if (/^\s*#{1,4}\s/.test(raw))
+            break;
+        if (/^\s*\|/.test(raw))
+            break;
+        // #4837: a fenced code block opener stops the scan — folding fence
+        // content is never safe, and stopping early is conservative.
+        if (/^\s*(?:`{3,}|~{3,})/.test(raw))
+            break;
+        contLines.push(raw.trim());
+    }
+    return [firstLine, ...contLines].join(' ').trim() || null;
+}
 module.exports = {
     stripShippedMilestones,
     extractCurrentMilestone,
@@ -2077,6 +2229,7 @@ module.exports = {
     // own doc comment. milestone.cts's destructive-consumer guard consumes
     // this instead of composing locate+select+section-end itself.
     sliceMilestoneWindow,
+    milestoneSections,
     hasVersionedMilestones,
     hasMilestoneSectioning,
     // #3642: the >=1 sibling buildStateFrontmatter's unbounded branch consumes.
@@ -2090,9 +2243,16 @@ module.exports = {
     // guards and the edit-phase workflow's pre/post capture are built on.
     scanMilestonePhaseIds,
     collectTablePhaseRows,
+    hasPhaseListingTableHeader,
     findMilestoneScopeHeadingLines,
     // #3641: the scope axis's phase-ENTRY predicate, exported so roadmap
     // validate's V004 document-level check routes through the same single
     // owner (and its convention gate) instead of a private inline copy.
+    extractPhaseFieldMultiline,
     hasPhaseEntries,
+    // #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
+    // "starts with the word Phase" regex.
+    isPhaseHeadingText,
 };