@opengsd/gsd-core 1.14.0 → 1.16.0

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

@@ -22,6 +22,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_child_process_1 = require("node:child_process");
+const frontmatter_fence_cjs_1 = require("./frontmatter-fence.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- io.cjs is an export= CommonJS module
 const ioMod = require("./io.cjs");
 const { output, error, ERROR_REASON, formatDiagnosticToken } = ioMod;
@@ -38,11 +39,13 @@ const coreUtilsMod = require("./core-utils.cjs");
 // generative-fix divergence CLAUDE.md warns about. Collapsed onto core-utils'
 // copy, which was already the leaf owner, so there is no second surface left to
 // drift and no parity test needed to police one.
-const { toPosixPath, generateSlugInternal, readSubdirectories, extractCanonicalPlanId, findUnsummarizedPlans, normalizeLineEndings, } = coreUtilsMod;
+const { toPosixPath, generateSlugInternal, readSubdirectories, extractCanonicalPlanId, findUnsummarizedPlans, } = coreUtilsMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-id.cjs is an export= CommonJS module
 const phaseIdMod = require("./phase-id.cjs");
-const { normalizePhaseName, phaseMarkdownRegexSource, comparePhaseNum, matchPhaseDirs, isSentinelPhaseId, scopeToPhase, OPTIONAL_PROJECT_CODE_PREFIX_SOURCE, OPTIONAL_PHASE_TAG_SOURCE, PHASE_NUMBER_TOKEN_SOURCE, } = phaseIdMod;
+const { normalizePhaseName, phaseMarkdownRegexSource, comparePhaseNum, matchPhaseDirs, isSentinelPhaseId, scopeToPhase, OPTIONAL_PROJECT_CODE_PREFIX_SOURCE, OPTIONAL_PHASE_TAG_SOURCE, PHASE_NUMBER_TOKEN_SOURCE, phaseHeadingPrefixSrcFor, PHASE_HEADING_BASELINE, buildPhaseHeadingScanRegex, } = phaseIdMod;
 const pattern_cjs_1 = require("./pattern.cjs");
+const gate_exit_cjs_1 = require("./gate-exit.cjs");
+const gate_verdict_cjs_1 = require("./gate-verdict.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-locator.cjs is an export= CommonJS module
 const phaseLocatorMod = require("./phase-locator.cjs");
 const { findPhaseInternal, getArchivedPhaseDirs, listMilestonePhaseDirs, listAllPhaseDirs } = phaseLocatorMod;
@@ -65,11 +68,17 @@ const frontmatterMod = require("./frontmatter.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- state.cjs is an export= CommonJS module
 const stateMod = require("./state.cjs");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const planning_document_cjs_1 = require("./planning-document.cjs");
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 const clock_cjs_1 = require("./clock.cjs");
 const state_transition_cjs_1 = require("./state-transition.cjs");
 const markdown_table_cjs_1 = require("./markdown-table.cjs");
+// #5060: the Phase Status Module owns the ROADMAP Status-cell token vocabulary.
+const phase_status_cjs_1 = require("./phase-status.cjs");
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- roadmap.cjs is an export= CommonJS module
+const roadmapMod = require("./roadmap.cjs");
+const { buildPhaseHeadingRegex } = roadmapMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- uat-predicate.cjs is an export= CommonJS module
 const uatPredicate = require("./uat-predicate.cjs");
 const { evaluateUatPassed } = uatPredicate;
@@ -80,20 +89,19 @@ const verificationMod = require("./verification.cjs");
 // cycle (the reverse edge, `state.cts → verify.cjs`, would).
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- verify.cjs is an export= CommonJS module
 const verifyMod = require("./verify.cjs");
-const { readVerificationStatus } = verificationMod;
+const { readVerificationStatus, VERIFICATION_STATUS, findVerificationStatusError } = verificationMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- plan-dependency-graph.cjs is an export= CommonJS module
 const planDependencyGraphMod = require("./plan-dependency-graph.cjs");
 const { computeHaltPropagation, buildSummaryFileIndex, isSummaryFileHalted, isSummaryFileBlocked } = planDependencyGraphMod;
 // #612: `resolvePhaseIdConvention` selects the write-time milestone-scope
 // guard's terminator vocabulary (see assertDescriptionPreservesMilestoneScope).
-const { planningDir, withPlanningLock, listAvailableWorkstreams, peekActiveWorkstream, diagnoseUnresolvedActiveWorkstream, describeUnresolvedWorkstreamReason, resolvePhaseIdConvention, } = planningWorkspace;
+const { planningDir, withPlanningLock, listAvailableWorkstreams, peekActiveWorkstream, diagnoseUnresolvedActiveWorkstream, describeUnresolvedWorkstreamReason, resolveEnvWorkstream, resolvePhaseIdConvention, } = planningWorkspace;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- milestone-lock.cjs is an export= CommonJS module
 const milestoneLockMod = require("./milestone-lock.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planDocumentMod = require("./plan-document.cjs");
 const { parsePlanDocument, planIdFromFile } = planDocumentMod;
-const { extractFrontmatter } = frontmatterMod;
-const { readModifyWriteStateMd, stateExtractField, stateReplaceField, syncAndPreserveStateMd, withStateLock, updatePerformanceMetricsSection, } = stateMod;
+const { readModifyWriteStateMd, stateExtractField, stateReplaceField, syncAndPreserveStateMd, assertVerificationReportsReadable, withStateLock, updatePerformanceMetricsSection, } = stateMod;
 // Any .md file with PLAN anywhere in the basename — diagnostic net
 const PLAN_OUTLINE_RE = /-PLAN-OUTLINE\.md$/i;
 const PLAN_PRE_BOUNCE_RE = /-PLAN.*\.pre-bounce\.md$/i;
@@ -348,16 +356,25 @@ function getRoadmapModeForPhase(cwd, phaseNum) {
     const milestoneContent = extractCurrentMilestone(rawContent, cwd);
     const fullContent = stripShippedMilestones(rawContent);
     const escapedPhase = phaseMarkdownRegexSource(phaseNum);
-    const phaseHeader = new RegExp(`#{2,4}\\s*Phase\\s+${escapedPhase}${OPTIONAL_PHASE_TAG_SOURCE}\\s*:`, 'i');
+    // #5007 (Phase 6 / ADR-4910 §8): buildPhaseHeadingRegex (src/roadmap.cts) is
+    // anchored `^...$` with no 'm' flag — it is designed to test ONE
+    // already-tokenized heading LINE (mirroring searchPhaseInContent's own
+    // usage), not to `.match()` against multi-line content directly. Routing
+    // through tokenizeHeadings first is therefore required here, not a pure
+    // regex-literal swap (the design doc's "direct swap" plan does not hold
+    // once the anchor is accounted for).
+    const phaseHeader = buildPhaseHeadingRegex(escapedPhase);
     for (const content of [milestoneContent, fullContent]) {
-        const headerMatch = content.match(phaseHeader);
-        if (!headerMatch || headerMatch.index === undefined)
+        const heading = (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(content).find((h) => phaseHeader.test(h.text));
+        if (!heading)
             continue;
-        const sectionStart = headerMatch.index;
+        const headingLineEnd = content.indexOf('\n', heading.offset);
+        const headerMatchLength = (headingLineEnd === -1 ? content.length : headingLineEnd) - heading.offset;
+        const sectionStart = heading.offset;
         const rest = content.slice(sectionStart);
-        const nextHeader = rest.slice(headerMatch[0].length).match(/\n#{2,4}\s+Phase\s+\S/i);
+        const nextHeader = rest.slice(headerMatchLength).match(/\n#{2,4}\s+Phase\s+\S/i);
         const sectionEnd = nextHeader
-            ? sectionStart + headerMatch[0].length + nextHeader.index
+            ? sectionStart + headerMatchLength + nextHeader.index
             : content.length;
         const section = content.slice(sectionStart, sectionEnd);
         const modeMatch = section.match(/\*\*Mode(?::\*\*|\*\*:)\s*([^\n]+)/i);
@@ -592,8 +609,16 @@ function cmdFindPhase(cwd, phase, raw) {
  * none left in this file) degrades to the pre-#3897 two-tier behavior rather
  * than throwing on a missing argument.
  */
+/**
+ * The dependency resolver's one comparison normalization. Callers that must
+ * predict whether a token names a plan reuse this seam instead of copying its
+ * case-folding rule.
+ */
+function normalizeDependencyToken(token) {
+    return String(token).toLowerCase();
+}
 function resolveDependencyId(dep, planMap, canonicalToId, shortFormToId) {
-    const lower = dep.toLowerCase();
+    const lower = normalizeDependencyToken(dep);
     if (planMap.has(lower))
         return planMap.get(lower).id;
     if (canonicalToId.has(lower))
@@ -634,7 +659,7 @@ function buildShortFormToId(rawPlans) {
         const canonical = extractCanonicalPlanId(p.id);
         const lastDash = canonical.lastIndexOf('-');
         if (lastDash > 0 && lastDash < canonical.length - 1) {
-            const shortForm = canonical.slice(lastDash + 1).toLowerCase();
+            const shortForm = normalizeDependencyToken(canonical.slice(lastDash + 1));
             if (/^\d+$/.test(shortForm) && !shortFormToId.has(shortForm)) {
                 shortFormToId.set(shortForm, p.id);
             }
@@ -744,12 +769,12 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
             phase: normalized,
             error: `Phase ${normalized} is ambiguous: ${ambiguousMatches.length} directories match (${ambiguousMatches.map((m) => `"${m}"`).join(', ')}).`,
             ambiguous_matches: ambiguousMatches,
-            plans: [], waves: {}, incomplete: [], has_checkpoints: false,
+            plans: [], waves: {}, incomplete: [], runnable: [], ready_plans: [], has_checkpoints: false,
         }, raw);
         return;
     }
     if (!phaseDir) {
-        output({ phase: normalized, error: 'Phase not found', plans: [], waves: {}, incomplete: [], runnable: [], has_checkpoints: false }, raw);
+        output({ phase: normalized, error: 'Phase not found', plans: [], waves: {}, incomplete: [], runnable: [], ready_plans: [], has_checkpoints: false }, raw);
         return;
     }
     void phaseDirName; // used only to set phaseDir above
@@ -836,6 +861,7 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
             filesModified: planDoc.filesModified,
             filesDeleted: planDoc.filesDeleted,
             agentHint: planDoc.agentHint,
+            gapClosure: planDoc.gapClosure,
             taskCount: planDoc.taskCount,
             hasSummary,
             halted,
@@ -844,7 +870,7 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
     // ── Pass 2: topological level assignment via depends_on DAG ──────────────
     const seenLower = new Map();
     for (const p of rawPlans) {
-        const lower = p.id.toLowerCase();
+        const lower = normalizeDependencyToken(p.id);
         const existing = seenLower.get(lower);
         if (existing !== undefined) {
             error(`depends_on index collision in phase ${normalized}: plan IDs '${existing}' and '${p.id}' are identical when case-folded. Rename one file to avoid ambiguous dependency resolution.`);
@@ -852,8 +878,8 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
         }
         seenLower.set(lower, p.id);
     }
-    const planMap = new Map(rawPlans.map((p) => [p.id.toLowerCase(), p]));
-    const canonicalToId = new Map(rawPlans.map((p) => [extractCanonicalPlanId(p.id).toLowerCase(), p.id]));
+    const planMap = new Map(rawPlans.map((p) => [normalizeDependencyToken(p.id), p]));
+    const canonicalToId = new Map(rawPlans.map((p) => [normalizeDependencyToken(extractCanonicalPlanId(p.id)), p.id]));
     // #3897 rung 4 (ADR-3473 §8.9) — the third depends_on resolution tier.
     // Resolves a bare in-phase plan-number short form (e.g. "01") to its owning
     // plan id. In-phase only by construction (T49): the map is built from THIS
@@ -888,6 +914,10 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
     const waves = {};
     const incomplete = [];
     const runnable = [];
+    // #4628: DAG-ready view — see the per-plan emission below. Keyed by id so
+    // the per-plan pass can resolve each plan's dependency edges.
+    const resolvedDepsByPlan = new Map(haltNodes.map((n) => [n.id, n.resolvedDependsOn]));
+    const readyPlans = [];
     let hasCheckpoints = false;
     const warnings = [];
     // #3427 / ADR-3473 §8.5: name every dropped depends_on edge (plan AND
@@ -897,8 +927,12 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
     // plan with no dropped edges and a genuinely wrong `wave:` still warns
     // (N3, D6, T25).
     const plansWithUnresolvedTokens = new Set();
+    const unresolvedTokensByPlan = new Map();
     for (const { plan, token } of unresolved) {
         plansWithUnresolvedTokens.add(plan);
+        const tokens = unresolvedTokensByPlan.get(plan) ?? [];
+        tokens.push(formatDiagnosticToken(token));
+        unresolvedTokensByPlan.set(plan, tokens);
         warnings.push(`Plan ${plan}: depends_on token ${formatDiagnosticToken(token)} does not resolve to any plan in this phase — edge dropped, wave placement for this plan may be unreliable`);
     }
     for (const rawPlan of rawPlans) {
@@ -906,14 +940,34 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
             hasCheckpoints = true;
         }
         const blockedByIds = blockedBy.get(rawPlan.id) ?? [];
+        // #4628: readiness fails closed — every resolved dependency must have
+        // completion evidence (has_summary), and a depends_on edge that never
+        // resolved (#3427 — a dropped edge) carries no evidence to check. A
+        // single evaluation feeds both the ready_plans list and the per-plan
+        // `ready` / `unresolved_dependencies` fields below.
+        // Case-fold the dep before the planMap lookup: planMap is lowercase-keyed
+        // (#2237) while resolveDependencyId returns the raw id — a mixed-case id
+        // must not read as 'no evidence' (over-blocking a ready plan).
+        const missingEvidence = (resolvedDepsByPlan.get(rawPlan.id) ?? [])
+            .filter((dep) => planMap.get(dep.toLowerCase())?.hasSummary !== true);
+        if (plansWithUnresolvedTokens.has(rawPlan.id)) {
+            missingEvidence.push(...(unresolvedTokensByPlan.get(rawPlan.id) ?? []));
+        }
+        const isReady = blockedByIds.length === 0 && missingEvidence.length === 0;
         if (!rawPlan.hasSummary) {
             incomplete.push(rawPlan.id);
             // #2830: the runnable-only view — incomplete AND not transitively
             // blocked by a halted upstream plan. Additive alongside `incomplete`,
             // which keeps its existing "no SUMMARY yet" meaning unchanged.
+            // #4628: runnable says NOTHING about completion evidence — a runnable
+            // plan whose dependencies lack a SUMMARY is not DAG-ready. Consumers
+            // dispatch from `ready_plans`.
             if (blockedByIds.length === 0) {
                 runnable.push(rawPlan.id);
             }
+            if (isReady) {
+                readyPlans.push(rawPlan.id);
+            }
         }
         const computedWave = (level.get(rawPlan.id) ?? 0) + levelOffset;
         const effectiveWave = computedWave;
@@ -943,6 +997,10 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
                 return planMap.has(lower) ? planMap.get(lower).id : dep;
             }),
             autonomous: rawPlan.autonomous,
+            // #4924: execute-phase's `--gaps-only` filter reads this field off the
+            // index. Before it was emitted, every plan read as non-gap-closure and the
+            // filter selected nothing — a silent, successful-looking empty run.
+            gap_closure: rawPlan.gapClosure,
             objective: rawPlan.objective,
             files_modified: rawPlan.filesModified,
             files_deleted: rawPlan.filesDeleted,
@@ -955,6 +1013,15 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
             halted: rawPlan.halted,
             blocked_by: blockedByIds,
         };
+        if (!rawPlan.hasSummary) {
+            // #4628: readiness is a property of INCOMPLETE plans (a summarized plan
+            // is filtered by has_summary before readiness is ever consulted). The
+            // unresolved_dependencies list names exactly which predecessors lack
+            // completion evidence, for the named-skip report.
+            plan['ready'] = isReady;
+            if (missingEvidence.length > 0)
+                plan['unresolved_dependencies'] = missingEvidence;
+        }
         plans.push(plan);
         const waveKey = String(effectiveWave);
         if (!waves[waveKey]) {
@@ -968,6 +1035,7 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
         waves,
         incomplete,
         runnable,
+        ready_plans: readyPlans,
         has_checkpoints: hasCheckpoints,
     };
     if (planNamingWarning)
@@ -1115,7 +1183,14 @@ function collectSiblingWorktreePhaseNums(cwd, used) {
     const siblingPlanningDir = (wt) => planningDir(wt, ws);
     const dirNumPattern = /^(?:[A-Z][A-Z0-9]*-)?(\d+)-/;
     // Same header shape the allocators scan locally (#1729 tag tolerance).
-    const headerPattern = /#{2,4}\s*Phase\s+(\d+)[A-Z]?(?:\.\d+)*(?:\s*\([^)\n]{0,200}\))?:/gi;
+    // #5007 (Phase 6 / ADR-4910 §8): migrated onto buildPhaseHeadingScanRegex
+    // (src/phase-id.cjs), the shared "which phases exist in this content" scan
+    // owner. LABEL_ONLY baseline with no convention argument reproduces the
+    // prior literal `Phase\s+` (no bracket tolerance) byte-for-byte — this is a
+    // counter, matching the LABEL_ONLY docstring guidance exactly, so it is
+    // deliberately NOT widened onto the bracket grammar the way the real-heading
+    // readers (getRoadmapModeForPhase, phaseDisplayNameFromRoadmap) are.
+    const { regex: headerPattern, phaseNumGroup } = buildPhaseHeadingScanRegex(PHASE_HEADING_BASELINE.LABEL_ONLY);
     for (const line of porcelain.split('\n')) {
         if (!line.startsWith('worktree '))
             continue;
@@ -1140,7 +1215,7 @@ function collectSiblingWorktreePhaseNums(cwd, used) {
             let m;
             headerPattern.lastIndex = 0;
             while ((m = headerPattern.exec(content)) !== null) {
-                const num = parseInt(m[1], 10);
+                const num = parseInt(m[phaseNumGroup], 10);
                 if (!isSentinelPhaseId(num))
                     used.add(num);
             }
@@ -1180,7 +1255,13 @@ function cmdPhaseAdd(cwd, description, raw, customId) {
             // (section header, roadmap bullet, or on-disk directory) is counted:
             // 1) Section headers: ### Phase N: / ## Phase N: / #### Phase N:
             // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
-            const headerPattern = /#{2,4}\s*Phase\s+(\d+)[A-Z]?(?:\.\d+)*(?:\s*\([^)\n]{0,200}\))?:/gi;
+            // #5007 (Phase 6 / ADR-4910 §8): migrated onto buildPhaseHeadingScanRegex
+            // (src/phase-id.cjs) with the LABEL_ONLY baseline and no convention
+            // argument — a counter site, matching phase-id.cts's own LABEL_ONLY
+            // docstring guidance, reproducing the prior `Phase\s+` literal (no
+            // bracket tolerance) byte-for-byte. See collectSiblingWorktreePhaseNums
+            // (above) for the identical migration on the same regex shape.
+            const { regex: headerPattern, phaseNumGroup } = buildPhaseHeadingScanRegex(PHASE_HEADING_BASELINE.LABEL_ONLY);
             // 2) Roadmap bullet entries: - [ ] **Phase N: ...** (all checkbox variants)
             // The lookahead accepts colon, decimal-dot, whitespace, bold-close asterisk,
             // or end-of-line so titleless forms ("- [ ] **Phase 11**", "- [ ] Phase 11")
@@ -1189,7 +1270,7 @@ function cmdPhaseAdd(cwd, description, raw, customId) {
             const usedPhaseNums = new Set();
             let m;
             while ((m = headerPattern.exec(content)) !== null) {
-                const num = parseInt(m[1], 10);
+                const num = parseInt(m[phaseNumGroup], 10);
                 // #3185: canonical sentinel predicate (SENTINEL_RANGES [0,999]) — this was a local 999-only literal that admitted Phase 0.
                 if (!isSentinelPhaseId(num))
                     usedPhaseNums.add(num);
@@ -1289,11 +1370,15 @@ function cmdPhaseAddBatch(cwd, descriptions, raw) {
             // bullets, on-disk dirs. The bullet scan was missing here — a bullet-only
             // `Phase N` row was invisible to batch allocation (#3849 secondary).
             // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
-            const phasePattern = /#{2,4}\s*Phase\s+(\d+)[A-Z]?(?:\.\d+)*(?:\s*\([^)\n]{0,200}\))?:/gi;
+            // #5007 (Phase 6 / ADR-4910 §8): migrated onto buildPhaseHeadingScanRegex
+            // (src/phase-id.cjs) with the LABEL_ONLY baseline and no convention
+            // argument — same counter-site migration as cmdPhaseAdd's identical
+            // regex above.
+            const { regex: phasePattern, phaseNumGroup } = buildPhaseHeadingScanRegex(PHASE_HEADING_BASELINE.LABEL_ONLY);
             const bulletPattern = /^[ \t]*-[ \t]*\[[^\]]{0,200}\][ \t]*\*{0,2}Phase[ \t]+(\d+)(?=[:.\s*]|$)/gim;
             let m;
             while ((m = phasePattern.exec(content)) !== null) {
-                const num = parseInt(m[1], 10);
+                const num = parseInt(m[phaseNumGroup], 10);
                 // #3185: canonical sentinel predicate (SENTINEL_RANGES [0,999]) — this was a local 999-only literal that admitted Phase 0.
                 if (isSentinelPhaseId(num))
                     continue;
@@ -1416,7 +1501,19 @@ function scanExistingDecimalPhaseNumbers(phasesDir, rawContent, base) {
                 decimalSet.add(parseInt(dm[1], 10));
         }
     }
-    const rmPhasePattern = new RegExp(`#{2,4}\\s*Phase\\s+${phaseMarkdownRegexSource(base)}\\.(\\d+)${OPTIONAL_PHASE_TAG_SOURCE}\\s*:`, 'gi');
+    // #5007 (Phase 6 / ADR-4910 §8): composes phaseHeadingPrefixSrcFor directly
+    // rather than routing through buildPhaseHeadingScanRegex — the owner has no
+    // decimal-subphase capture group. The design doc's suggested composition
+    // passed `capturing=true` to phaseHeadingPrefixSrcFor, but this site has no
+    // use for the bracket-id capture it would add, and doing so would silently
+    // shift `rmMatch[1]` (the decimal digits) to group 2 — a real correctness
+    // hazard. `capturing` is left at its default (false), and the `#{2,4}\s*`
+    // heading marker (also omitted from the design's snippet) is kept explicit,
+    // since phaseHeadingPrefixSrcFor never includes it — callers always add it
+    // themselves (see buildPhaseHeadingScanRegex's own usage). No convention
+    // argument: LABEL_ONLY with convention=undefined reproduces the prior
+    // `Phase\s+` literal byte-for-byte.
+    const rmPhasePattern = new RegExp(`#{2,4}\\s*${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY)}${phaseMarkdownRegexSource(base)}\\.(\\d+)${OPTIONAL_PHASE_TAG_SOURCE}\\s*:`, 'gi');
     let rmMatch;
     while ((rmMatch = rmPhasePattern.exec(rawContent)) !== null) {
         decimalSet.add(parseInt(rmMatch[1], 10));
@@ -1443,10 +1540,27 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw, allocation = 'nested'
         const content = extractCurrentMilestone(rawContent, cwd);
         const normalizedAfter = normalizePhaseName(afterPhase);
         const afterPhaseEscaped = phaseMarkdownRegexSource(normalizedAfter);
-        const targetPattern = new RegExp(`#{2,4}\\s*Phase\\s+${afterPhaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}:`, 'i');
-        const headingMatch = targetPattern.test(content);
+        const insertConvention = resolvePhaseIdConvention(cwd);
+        // #5007 (Phase 6 / ADR-4910 §8): buildPhaseHeadingRegex (src/roadmap.cts)
+        // is anchored `^...$` with no 'm' flag — designed to test ONE
+        // already-tokenized heading LINE, not to `.test()` against multi-line
+        // `content` directly (the design doc's "no anchoring change needed"
+        // claim for this site does not hold once the anchor is accounted for —
+        // same discrepancy as getRoadmapModeForPhase and phaseDisplayNameFromRoadmap
+        // above/below). Routed through tokenizeHeadings, mirroring
+        // searchPhaseInContent's own usage.
+        const targetPattern = buildPhaseHeadingRegex(afterPhaseEscaped, insertConvention);
+        const headingMatch = (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(content).some((h) => targetPattern.test(h.text));
         const bulletPattern = new RegExp(`-\\s*\\[[ x]\\]\\s*(?:\\*\\*)?Phase\\s+${afterPhaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s]`, 'i');
-        const anyHeadingPattern = /#{2,4}\s*Phase\s+\d/i;
+        // #5007 (Phase 6 / ADR-4910 §8): a pure "does ANY phase heading exist"
+        // boolean — neither shared owner exposes this shape (buildPhaseHeadingRegex
+        // is phase-N-specific; buildPhaseHeadingScanRegex always captures a phase
+        // number). Composed directly from phaseHeadingPrefixSrcFor with the
+        // `#{2,4}\s*` marker kept explicit (phaseHeadingPrefixSrcFor never
+        // includes it). Unanchored `.test()` on multi-line content, same as the
+        // pre-migration literal — no tokenize-first refactor needed here since
+        // there is no anchor in this source.
+        const anyHeadingPattern = new RegExp(`#{2,4}\\s*${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY, insertConvention)}\\d`, 'i');
         const roadmapHasHeadingPhases = anyHeadingPattern.test(content);
         const isBulletStyle = !headingMatch && bulletPattern.test(content) && !roadmapHasHeadingPhases;
         if (!headingMatch && !isBulletStyle) {
@@ -1522,14 +1636,42 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw, allocation = 'nested'
         }
         else {
             const phaseEntry = `\n### Phase ${_decimalPhase}: ${description} (INSERTED)\n\n**Goal:** [Urgent work - to be planned]\n**Requirements**: TBD\n**Depends on:** Phase ${afterPhase}\n**Plans:** 0 plans\n\nPlans:\n- [ ] TBD (run ${(0, runtime_slash_cjs_1.formatGsdSlash)('plan-phase', (0, runtime_slash_cjs_1.resolveRuntime)(cwd))} ${_decimalPhase} to break down)\n`;
-            const headerPattern = new RegExp(`(#{2,4}\\s*Phase\\s+${afterPhaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}:[^\\n]*\\n)`, 'i');
+            // #5007 (Phase 6 / ADR-4910 §8): this site needs the WHOLE matched
+            // heading line plus its trailing newline (for splicing the new entry
+            // in immediately after it) — neither shared owner returns that shape
+            // (buildPhaseHeadingRegex captures only the title). Composed directly
+            // from phaseHeadingPrefixSrcFor, keeping this site's own full-line
+            // capture; audited together with the targetPattern/anyHeadingPattern
+            // migration above (same describe block, same afterPhaseEscaped/
+            // insertConvention inputs).
+            const headerPattern = new RegExp(`(#{2,4}\\s*${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY, insertConvention)}${afterPhaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}:[^\\n]*\\n)`, 'i');
             const headerMatch = rawContent.match(headerPattern);
             if (!headerMatch) {
                 error(`Could not find Phase ${afterPhase} header`);
             }
             const headerIdx = rawContent.indexOf(headerMatch[0]);
             const afterHeader = rawContent.slice(headerIdx + headerMatch[0].length);
-            const nextPhaseMatch = afterHeader.match(/\r?\n#{2,4}\s+Phase\s+\d[\d.]*/i);
+            // #5007 (Phase 6 / ADR-4910 §8): this next-phase-boundary lookup was NOT
+            // one of the 15 originally-marked grandfathered sites, but it hand-rolls
+            // the identical `#{2,4}...Phase\s+` heading-marker shape and sits right
+            // next to headerPattern above, which this same commit series just
+            // widened (via insertConvention) to recognize a bracket-tagged target
+            // heading. Left bracket-blind, this regex would silently defeat that
+            // widening: under the bracket convention a freshly-recognized
+            // bracket-tagged target could still fail to find the NEXT heading as a
+            // boundary (`[CODE.MM] Phase N+1:` never matches a bare `Phase\s+`
+            // literal), so the newly inserted entry falls through to the
+            // rawContent.length branch and lands appended at end-of-file instead of
+            // directly after the target section. Found while migrating the
+            // neighboring sites, not deferred: this is the same defect class the
+            // whole Phase 6 effort exists to drain, just an unmarked instance of it.
+            // Composed with the SAME baseline/convention as headerPattern above so
+            // target-discovery and next-boundary-discovery agree. The base
+            // `#{2,4}\s+` (mandatory whitespace after the hashes, not `\s*`) is
+            // preserved exactly as the prior literal had it — a pre-existing,
+            // deliberately-unchanged asymmetry with the other sites in this file.
+            const nextPhaseHeadingPrefix = `#{2,4}\\s+${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY, insertConvention)}`;
+            const nextPhaseMatch = afterHeader.match(new RegExp(`\\r?\\n${nextPhaseHeadingPrefix}\\d[\\d.]*`, 'i'));
             let insertIdx;
             if (nextPhaseMatch) {
                 insertIdx = headerIdx + headerMatch[0].length + nextPhaseMatch.index;
@@ -1844,7 +1986,30 @@ function updateRoadmapAfterPhaseRemoval(roadmapPath, targetPhase, isDecimal, rem
         if (!isDecimal) {
             // #1729: fold an optional pre-colon ( ) tag into the suffix capture so it
             // is re-emitted verbatim — a tagged later phase still gets renumbered.
-            content = content.replace(/(#{2,4}\s*Phase\s+)(\d+(?:\.\d+)?)((?:\s*\([^)\r\n]{0,200}\))?\s*:)/gi, (_match, prefix, num, suffix) => `${prefix}${decrementRoadmapPhaseToken(num, removedInt)}${suffix}`);
+            // #5007 (Phase 6 / ADR-4910 §8): composes phaseHeadingPrefixSrcFor
+            // directly (needs prefix/number/suffix as three separate capture groups
+            // for a verbatim in-place rewrite — neither shared owner returns that
+            // shape). Two deliberate departures from the design doc's suggested
+            // composition, both kept for zero behavior change on this
+            // highest-blast-radius site (feeds phase remove's renumber path):
+            //   1. The `#{2,4}\s*` heading marker is kept explicit and folded INTO
+            //      the prefix capture group — the design's snippet omitted it
+            //      entirely (phaseHeadingPrefixSrcFor never includes it; every
+            //      caller adds it, e.g. buildPhaseHeadingScanRegex), and the
+            //      original group 1 here captured the marker too.
+            //   2. No convention argument is threaded (LABEL_ONLY with
+            //      convention=undefined), even though phaseHeadingPrefixSrcFor
+            //      COULD accept one — this keeps the composed source byte-identical
+            //      to the prior `Phase\s+` literal, a deliberate non-widening for
+            //      this specific site (unlike cmdPhaseInsert's targetPattern).
+            // The number group widens from `\d+(?:\.\d+)?` to the full
+            // PHASE_NUMBER_TOKEN_SOURCE (letter suffix + multi-segment decimals) —
+            // this is SAFE, not a behavior change: decrementRoadmapPhaseToken's own
+            // regex (`^(\d+)(\.\d+)?$`) rejects anything wider and returns the
+            // token unchanged, so a heading this widening newly matches (e.g.
+            // "Phase 12A:") is written back byte-for-byte unchanged, identical to
+            // the pre-migration outcome of the whole regex simply not matching it.
+            content = content.replace(new RegExp(`(#{2,4}\\s*${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY)})(${PHASE_NUMBER_TOKEN_SOURCE})(${OPTIONAL_PHASE_TAG_SOURCE}\\s*:)`, 'gi'), (_match, prefix, num, suffix) => `${prefix}${decrementRoadmapPhaseToken(num, removedInt)}${suffix}`);
             content = content.replace(/(-\s*\[[ x]\]\s*.*?Phase\s+)(\d+)(\s*:|\s+)/gi, (_match, prefix, num, suffix) => `${prefix}${decrementRoadmapPhaseNumber(num, removedInt)}${suffix}`);
             // ORDINAL-RENUMBER — CELL EDIT (not row-deletion) — migrated onto
             // updateTableCell (ADR-2143 §7, sibling of the deleteTableRow scoping
@@ -1933,8 +2098,52 @@ function updateRoadmapAfterPhaseRemoval(roadmapPath, targetPhase, isDecimal, rem
                 content = ordinalBefore + ordinalSection + ordinalRest;
             }
             content = content.replace(/(?<![0-9-])(\d{2})-(\d{2})(?=(?:(?:-[A-Za-z][A-Za-z0-9-]*)?-(?:PLAN|SUMMARY)\.md)|(?![0-9-]))/g, (_match, phaseNum, planNum) => `${decrementRoadmapPaddedPhaseNumber(phaseNum, removedInt)}-${planNum}`);
-            content = content.replace(/(\*\*Depends on\*\*\s*:\s*Phase\s+)(\d+(?:\.\d+)?)\b/gi, (_match, prefix, num) => `${prefix}${decrementRoadmapPhaseToken(num, removedInt)}`);
-            content = content.replace(/(Depends on:\*\*\s*Phase\s+)(\d+(?:\.\d+)?)\b/gi, (_match, prefix, num) => `${prefix}${decrementRoadmapPhaseToken(num, removedInt)}`);
+            // #5007 (Phase 6 / ADR-4910): migrated the "Depends on" bold-field
+            // decrement off two hand-rolled regexes — one per bold-placement
+            // variant, `**Depends on**: Phase N` and `**Depends on:** Phase N` —
+            // onto the PlanningDoc `boldField` read/write seam (`writePlansField`
+            // above is the established precedent for this migration shape).
+            // `BOLD_FIELD_RE` (planning-document.cts) recognizes BOTH placements
+            // as the SAME field label ("Depends on") — `parseBoldFieldLine` strips
+            // the token down to its inner text regardless of which side of `**`
+            // the colon lands on — so this single loop naturally replaces both
+            // regexes with one call site; no variant-specific branching remains.
+            // Unlike `writePlansField`'s single `findField` lookup (scoped to one
+            // already-isolated phase section), a whole ROADMAP.md can carry a
+            // "Depends on" field in EVERY phase's detail section, so this walks
+            // every `boldField` node in the whole parsed document whose label is
+            // "Depends on" and rewrites each one independently — a
+            // representability refusal or absent match on one field leaves that
+            // field untouched and never blocks any other field, mirroring the
+            // prior regexes' per-occurrence independence. A parse failure or an
+            // unreadable-nodes refusal on `serialize` leaves `content` byte-for-
+            // byte untouched, the same silent no-op the prior regexes had for any
+            // input they didn't match (neither ever threw or warned).
+            const dependsOnParsed = (0, planning_document_cjs_1.parsePlanningDoc)(content, 'ROADMAP.md');
+            if (dependsOnParsed.ok) {
+                let dependsOnDoc = dependsOnParsed.value;
+                const dependsOnFieldIds = dependsOnDoc.nodes
+                    .filter((n) => n.kind === 'boldField' && n.label === 'Depends on')
+                    .map((n) => n.id);
+                for (const fieldId of dependsOnFieldIds) {
+                    const currentRead = (0, planning_document_cjs_1.readNode)(dependsOnDoc, fieldId);
+                    if (!currentRead.ok)
+                        continue;
+                    const depMatch = /^(Phase\s+)(\d+(?:\.\d+)?)\b/i.exec(currentRead.value);
+                    if (!depMatch)
+                        continue;
+                    const [wholeMatch, prefix, num] = depMatch;
+                    const newValue = `${prefix}${decrementRoadmapPhaseToken(num, removedInt)}` + currentRead.value.slice(wholeMatch.length);
+                    if (newValue === currentRead.value)
+                        continue;
+                    const staged = (0, planning_document_cjs_1.setFieldValue)(dependsOnDoc, fieldId, newValue);
+                    if (staged.ok)
+                        dependsOnDoc = staged.value;
+                }
+                const dependsOnOut = (0, planning_document_cjs_1.serialize)(dependsOnDoc);
+                if (dependsOnOut.ok)
+                    content = dependsOnOut.value;
+            }
         }
         (0, shell_command_projection_cjs_1.platformWriteSync)(roadmapPath, content);
         // #3685 / #3691: compare NORMALIZED bytes (what platformWriteSync actually
@@ -1958,21 +2167,22 @@ function updateRoadmapAfterPhaseRemoval(roadmapPath, targetPhase, isDecimal, rem
  * phase, a stray 'Total Phases: 0' between fences). A file with no leading
  * frontmatter is all body: the field goes to content start, preserving the
  * former behavior for that shape.
+ *
+ * The block is the one `locateFrontmatterFence` finds (the one fence owner), so this writer
+ * and every STATE.md reader agree on where the body starts. The blank line and the field go
+ * right after the closing fence line, ended by that line's own line ending — so a CRLF file
+ * gains CRLF lines only (#3572 review: a blanket re-join on '\r\n' doubled every carriage
+ * return; joining the new lines on a bare '\n' mixed line endings).
  */
 function insertStateBodyFieldAtTop(content, fieldLine) {
-    // Split AND join on bare '\n' so CRLF line endings stay attached to their
-    // own lines — each '\r' remains the tail of the line it terminated, where
-    // the trimmed fence compare still matches it. (#3572 review: splitting on
-    // '\n' but re-joining on a detected '\r\n' doubled every carriage return.)
-    const lines = content.split('\n');
-    if ((lines[0] ?? '').trim() === '---') {
-        const closeIdx = lines.findIndex((l, i) => i > 0 && l.trim() === '---');
-        if (closeIdx !== -1) {
-            lines.splice(closeIdx + 1, 0, '', fieldLine);
-            return lines.join('\n');
-        }
-    }
-    return fieldLine + '\n' + content;
+    const fence = (0, frontmatter_fence_cjs_1.locateFrontmatterFence)(content);
+    if (fence?.closed) {
+        const nl = content[fence.closingFenceEnd] === '\r' ? '\r\n' : '\n';
+        return `${content.slice(0, fence.closingFenceEnd)}${nl}${nl}${fieldLine}${content.slice(fence.closingFenceEnd)}`;
+    }
+    // All body: the field is the new first line, ended like the document's first line.
+    const firstNewline = content.indexOf('\n');
+    return fieldLine + (firstNewline > 0 && content[firstNewline - 1] === '\r' ? '\r\n' : '\n') + content;
 }
 function cmdPhaseRemove(cwd, targetPhase, options, raw) {
     if (!targetPhase)
@@ -2017,6 +2227,21 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
             error(`Phase ${targetPhase} has ${summaryCount} executed plan(s). Use --force to remove anyway.`);
         }
     }
+    // #5118 (no write before the error): the STATE.md rewrite below rebuilds the
+    // frontmatter from EVERY surviving phase's report (buildStateFrontmatter →
+    // isPhaseComplete), and it runs AFTER the directory removal, the sibling
+    // renames and the ROADMAP rewrite. Validate every surviving phase's report
+    // here, BEFORE the first write, so a report whose `status` is outside the
+    // closed set fails this command having written nothing (the removed phase's
+    // own report is not read afterwards — it is excluded). The set is the one the
+    // rebuild scans (`statePhaseDirsToScan`: milestone-scoped, deduped), so a
+    // survivor OUTSIDE that set — another milestone's phase directory — does not
+    // block the remove.
+    if (node_fs_1.default.existsSync(node_path_1.default.join(planningDir(cwd), 'STATE.md'))) {
+        const survivorStatusError = findVerificationStatusError(stateMod.statePhaseDirsToScan(cwd).filter((d) => d !== targetDir).map((d) => node_path_1.default.join(phasesDir, d)), { convention: resolvePhaseIdConvention(cwd) });
+        if (survivorStatusError)
+            throw survivorStatusError;
+    }
     if (targetDir)
         node_fs_1.default.rmSync(node_path_1.default.join(phasesDir, targetDir), { recursive: true, force: true });
     let renamedDirs = [];
@@ -2177,7 +2402,20 @@ function phaseDisplayNameFromRoadmap(roadmapContent, phaseNum) {
     if (!roadmapContent || !phaseNum)
         return null;
     const phaseEscaped = phaseMarkdownRegexSource(phaseNum);
-    const heading = roadmapContent.match(new RegExp(`^#{2,4}\\s*Phase\\s+${phaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}\\s*:\\s*([^\\n]+)`, 'im'));
+    // #5007 (Phase 6 / ADR-4910 §8): buildPhaseHeadingRegex (src/roadmap.cts) is
+    // anchored `^...$` with no 'm' flag by design — it expects one
+    // already-tokenized heading LINE, not a `^`/`m` scan against multi-line
+    // content directly. Routed through tokenizeHeadings first (the same real
+    // refactor searchPhaseInContent's own usage already requires), not a pure
+    // regex-literal swap. Adopts buildPhaseHeadingRegex's ANY_BRACKET baseline —
+    // a deliberate widening, matching getRoadmapModeForPhase's identical choice
+    // above: this is a real-heading reader, so it inherits the same bracket-tag
+    // tolerance searchPhaseInContent already applies everywhere else.
+    const headingPattern = buildPhaseHeadingRegex(phaseEscaped);
+    const matchedHeading = (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(roadmapContent).find((h) => headingPattern.test(h.text));
+    if (!matchedHeading)
+        return null;
+    const heading = matchedHeading.text.match(headingPattern);
     if (!heading)
         return null;
     const name = heading[1].replace(/\(INSERTED\)/i, '').trim();
@@ -2838,7 +3076,7 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
     // non-mutating peek so an unresolvable pointer isn't self-healed (cleared)
     // here and then found "absent" by diagnoseUnresolvedActiveWorkstream below,
     // which would misreport a present-but-bad marker as no marker at all.
-    const resolvedWorkstream = process.env['GSD_WORKSTREAM'] || peekActiveWorkstream(cwd);
+    const resolvedWorkstream = resolveEnvWorkstream() ?? peekActiveWorkstream(cwd);
     if (availableWorkstreams.length > 0 && !resolvedWorkstream) {
         // #3579: getActiveWorkstream now inherits a pointer-less session's read
         // from the shared .planning/active-workstream marker, so reaching this
@@ -2985,27 +3223,12 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
             if (/status: diagnosed/.test(content))
                 warnings.push(`${file}: has diagnosed gaps`);
         }
-        for (const file of scopeToPhase(phaseFiles.filter((f) => f.includes('-VERIFICATION') && f.endsWith('.md')), phaseFullDirBaseName)) {
-            const verificationFilePath = node_path_1.default.join(phaseFullDir, file);
-            // #3707-CR follow-up MINOR: normalize line endings at this read boundary
-            // (same fix as src/verification.cts's readVerificationStatus) so a
-            // lone-CR VERIFICATION.md's `---\r...\r---` frontmatter fence still
-            // matches extractFrontmatter's byte-0 check instead of silently
-            // dropping the human_needed/gaps_found advisory warning below.
-            const content = normalizeLineEndings(node_fs_1.default.readFileSync(verificationFilePath, 'utf-8'));
-            // #1159 (Defect A): read ONLY the frontmatter `status` key to avoid false positives
-            // from historical metadata in the file body (e.g. `previous_status: gaps_found`).
-            // A full-text regex like /status: gaps_found/ matches the substring inside
-            // `previous_status: gaps_found`, producing spurious warnings even when the
-            // current frontmatter status is `passed`.
-            const verFm = extractFrontmatter(content, verificationFilePath);
-            // Normalise to lower-case so `status: Passed` (title-case) is not missed.
-            const verStatus = typeof verFm['status'] === 'string' ? verFm['status'].trim().toLowerCase() : '';
-            if (verStatus === 'human_needed')
-                warnings.push(`${file}: needs human verification`);
-            if (verStatus === 'gaps_found')
-                warnings.push(`${file}: has unresolved gaps`);
-        }
+        // #5118 (ADR-5057 Phase 4): the VERIFICATION report's `status` is no
+        // longer read here. This pre-scan used to read each report's frontmatter
+        // itself (case-folded, bypassing the owner) to warn on human_needed /
+        // gaps_found — but the completion GATE below (readVerificationStatus)
+        // already refuses those statuses and names the route, so the advisory
+        // could only ever duplicate the gate's own answer. One reader: the gate.
     }
     catch {
         /* best-effort (#2245 audit): this is an ADVISORY pre-scan of UAT/
@@ -3084,6 +3307,9 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
         // #2617: pass the project's runtime so the blocked-completion error below
         // suggests the command surface this runtime actually installs
         // ($gsd-… on Codex) rather than a hard-coded Claude-style string.
+        // #5118: an out-of-set report status THROWS VerificationStatusError out
+        // of here; withPlanningLock releases the lock on the way out and the CLI
+        // seam reports `verification_status_invalid`.
         const verificationStatus = readVerificationStatus(phaseFullDir, {
             runtime: (0, runtime_slash_cjs_1.resolveRuntime)(cwd),
             convention: resolvePhaseIdConvention(cwd),
@@ -3101,9 +3327,22 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
             staleCheckIndeterminate = true;
             warnings.push(`verification staleness check could not complete for phase ${phaseNum} — routed as not-stale, but this was not actually verified (#3057)`);
         }
-        if (verificationStatus.status !== 'passed') {
+        if (verificationStatus.status !== VERIFICATION_STATUS.PASSED) {
             return verificationStatus;
         }
+        // #5118 (no write before the error): the transaction below writes ROADMAP,
+        // REQUIREMENTS and STATE, and the STATE frontmatter rebuild reads EVERY
+        // phase's report (buildStateFrontmatter → isPhaseComplete). Validate it
+        // here, BEFORE the first write, over EXACTLY the set that rebuild scans
+        // (the milestone-scoped, deduped phase set — the owner runs
+        // buildStateFrontmatter itself, so `state sync` and this command refuse
+        // for the same phases), so a report whose `status` is outside the closed
+        // set fails this command having written nothing (withPlanningLock
+        // releases the lock).
+        const preflightStatePath = node_path_1.default.join(planningDir(cwd), 'STATE.md');
+        if (node_fs_1.default.existsSync(preflightStatePath)) {
+            assertVerificationReportsReadable(node_fs_1.default.readFileSync(preflightStatePath, 'utf-8'), cwd);
+        }
         const runPhaseCompleteTransaction = () => {
             const writes = [];
             let roadmapContent = null;
@@ -3130,7 +3369,7 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                 // whole-slice `.replace()` onto the seam. Applied per single physical
                 // line by updateBullet, so the pattern no longer needs the `m` flag
                 // (it never sees more than one line at a time); see
-                // planCountBodyPattern below for the sites that were migrated onto
+                // writePlansField below for the sites that were migrated onto
                 // withPhaseSection instead.
                 //
                 // #2245 review Fix 6: this is behaviour-preserving for GSD-GENERATED
@@ -3183,12 +3422,105 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                 };
                 // ADR-2143 §4: the plan-count write is now routed through
                 // withPhaseSection (see mutateMilestonePhase below), which hands this
-                // pattern ONLY phase N's own detail-section body — so the pattern no
-                // longer needs its own `#{2,4}\s*Phase\s+N` anchor + skip-ahead-past-
-                // interior-headings lookahead; the section boundary itself confines
-                // the match (the #2067/#2200 boundary-crossing class is now
-                // structurally impossible for this site rather than regex-enforced).
-                const planCountBodyPattern = /(\*\*Plans:\*\*\s*)[^\n]+/i;
+                // seam call ONLY phase N's own detail-section body — the section
+                // boundary itself confines the write (the #2067/#2200 boundary-
+                // crossing class is structurally impossible for this site).
+                //
+                // #4906 Phase 2 (#4917/ADR-4910): migrated off the one-capture-group
+                // regex that replaced to end of line, dropping any hand-written
+                // trailing prose after the count (#4852) — onto the PlanningDoc
+                // `boldField` write seam, whose `valueSpan`/`trailingSpan` split
+                // never touches the trailing annotation.
+                const writePlansField = (body) => {
+                    const parsed = (0, planning_document_cjs_1.parsePlanningDoc)(body, 'ROADMAP.md');
+                    if (!parsed.ok) {
+                        preservationWarnings.push({ field: 'Plans', reason: parsed.reason });
+                        return body;
+                    }
+                    const fieldId = (0, planning_document_cjs_1.findField)(parsed.value, 'Plans');
+                    if (!fieldId) {
+                        // #4906 regression (#1163 parity, caught by gsd-test against
+                        // roadmap.cts's sibling site): a hand-edited or pre-template
+                        // ROADMAP.md may carry a PLAIN (non-bold) `Plans:` line rather
+                        // than the canonical `**Plans**:`/`**Plans:**` bold field.
+                        // BOLD_FIELD_RE stays bold-only (widening it would register
+                        // ordinary prose as a spurious field seam-wide) — this fallback
+                        // mirrors roadmap.cts's identical one, kept in parity per
+                        // Decision 2 rather than letting the two sites diverge on which
+                        // legacy shapes they tolerate.
+                        const plainMatch = body.match(/^([ \t]*)Plans:([ \t]*)([^\r\n]*)$/m);
+                        if (!plainMatch) {
+                            // No `**Plans:**`/`**Plans**:`/plain `Plans:` line in this
+                            // phase's section — nothing to write; not a failure (mirrors
+                            // the old regex's silent no-match no-op).
+                            return body;
+                        }
+                        const [whole, indent, spacing, plainValue] = plainMatch;
+                        const plainCountPrefixMatch = plainValue.match(/^(?:\d+\s*\/\s*\d+\s+plans(?:\s+(?:complete|executed))?|\d+\s+plans?)/i);
+                        const plainIsTemplatePlaceholder = /^\[\s*Number of plans\b[\s\S]*\]$/i.test(plainValue.trim());
+                        if (!plainCountPrefixMatch && !plainIsTemplatePlaceholder) {
+                            // Arm 3: freeform prose, TBD, a bracketed human annotation, or
+                            // an empty value — leave the field exactly as it was.
+                            return body;
+                        }
+                        const plainNewCountText = `${summaryCount}/${planCount} plans complete`;
+                        const plainSuffix = plainCountPrefixMatch ? plainValue.slice(plainCountPrefixMatch[0].length) : '';
+                        const newPlainLine = `${indent}Plans:${spacing}${plainNewCountText}${plainSuffix}`;
+                        const start = plainMatch.index ?? body.indexOf(whole);
+                        return body.slice(0, start) + newPlainLine + body.slice(start + whole.length);
+                    }
+                    // #4906 regression fix: PREFIX-match the existing value's count
+                    // token and re-glue whatever follows it VERBATIM — a glued-on
+                    // annotation with no ` — ` separator (e.g. a parenthetical like
+                    // `0/1 plans executed (11-16 are gap closure from VERIFICATION)`)
+                    // lives entirely inside `value` (`TRAILING_SEPARATOR_RE` in
+                    // planning-document.cts only splits on ` — `, unchanged/correct),
+                    // so overwriting `value` outright previously destroyed it.
+                    //
+                    // #4906 review finding (isolated adversarial pass): the prior
+                    // version of this migration preserved this site's OLD
+                    // unconditional-overwrite behavior for the no-count-prefix case,
+                    // which clobbers arm 3 (freeform prose / TBD / a bracketed human
+                    // annotation like `[Deferred pending re-scope]`) — a real
+                    // regression against the design doc's own Behavior table row 4,
+                    // not an accepted trade-off. Fixed here by adopting the SAME
+                    // template-placeholder / arm-3-untouched classification
+                    // roadmap.cts's sibling site already uses (isTemplatePlaceholder +
+                    // "no count prefix and not a placeholder => leave untouched"),
+                    // rather than letting the two migrated sites diverge on this.
+                    const newCountText = `${summaryCount}/${planCount} plans complete`;
+                    const current = (0, planning_document_cjs_1.readNode)(parsed.value, fieldId);
+                    if (!current.ok) {
+                        return body;
+                    }
+                    const currentValue = current.value;
+                    const countPrefixMatch = currentValue.match(/^(?:\d+\s*\/\s*\d+\s+plans(?:\s+(?:complete|executed))?|\d+\s+plans?)/i);
+                    const isTemplatePlaceholder = /^\[\s*Number of plans\b[\s\S]*\]$/i.test(currentValue.trim());
+                    if (!countPrefixMatch && !isTemplatePlaceholder) {
+                        // Arm 3: freeform prose, TBD, a bracketed human annotation, or an
+                        // empty value — leave the field exactly as it was.
+                        return body;
+                    }
+                    const newValueToWrite = countPrefixMatch
+                        ? newCountText + currentValue.slice(countPrefixMatch[0].length)
+                        : newCountText;
+                    const staged = (0, planning_document_cjs_1.setFieldValue)(parsed.value, fieldId, newValueToWrite);
+                    if (!staged.ok) {
+                        preservationWarnings.push({ field: 'Plans', reason: staged.reason });
+                        return body;
+                    }
+                    const out = (0, planning_document_cjs_1.serialize)(staged.value);
+                    if (!out.ok) {
+                        // `hasUnreadableNodes` refusal (ADR-4910 amendment) — a ragged
+                        // SIBLING node elsewhere in this same section refuses the whole
+                        // splice. Never throw / crash the phase-complete transaction over
+                        // a node unrelated to this write; surface it and leave `body`
+                        // unchanged, same as any other preservation warning.
+                        preservationWarnings.push({ field: 'Plans', reason: out.reason });
+                        return body;
+                    }
+                    return out.value;
+                };
                 const phaseInfoSummaries = phaseInfo['summaries'];
                 // #2200: apply the phase-checkbox flip, the plan-count write, and the
                 // per-plan checkbox flips ONLY within the current milestone's region(s)
@@ -3204,7 +3536,7 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                         const plansResult = (0, markdown_table_cjs_1.updateTableCell)(text, rowMatch, 'Plans Complete', ` ${summaryCount}/${planCount} `);
                         if (plansResult.ok)
                             text = plansResult.value;
-                        const statusResult = (0, markdown_table_cjs_1.updateTableCell)(text, rowMatch, 'Status', ' Complete    ');
+                        const statusResult = (0, markdown_table_cjs_1.updateTableCell)(text, rowMatch, 'Status', ` ${(0, phase_status_cjs_1.toRoadmapStatusCell)(phase_status_cjs_1.PHASE_STATUS.COMPLETE).padEnd(11)} `);
                         if (statusResult.ok)
                             text = statusResult.value;
                         // Preserve only a valid ISO date (#1161: idempotent; self-heal
@@ -3225,14 +3557,18 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                     // section's body, so neither regex can escape into a sibling
                     // phase's section, a shipped milestone, or a Backlog entry.
                     s = withPhaseSection(s, phaseNum, (body) => {
-                        let b = body.replace(planCountBodyPattern, `$1${summaryCount}/${planCount} plans complete`);
+                        let b = writePlansField(body);
                         for (const summaryFile of phaseInfoSummaries) {
                             const planId = summaryFile.replace('-SUMMARY.md', '').replace('SUMMARY.md', '');
                             if (!planId)
                                 continue;
                             const planEscaped = (0, pattern_cjs_1.escapeRegex)(planId);
-                            const planCheckboxPattern = new RegExp(`(-\\s*\\[) (\\]\\s*(?:\\*\\*)?${planEscaped}(?:\\*\\*)?)`, 'i');
-                            b = b.replace(planCheckboxPattern, '$1x$2');
+                            // ADR-5057 §6 (Phase 13, #5217): the per-plan flip is a bullet
+                            // mutation, so it goes through `updateBullet` like the phase
+                            // checkbox flip above — first matching bullet only, never a
+                            // fenced line, never a mid-line occurrence.
+                            const planCheckboxPattern = new RegExp(`^(\\s*-\\s*\\[) (\\]\\s*(?:\\*\\*)?${planEscaped}(?:\\*\\*)?)`, 'i');
+                            b = (0, markdown_sectionizer_cjs_1.updateBullet)(b, (_bulletText, rawLine) => planCheckboxPattern.test(rawLine), (rawLine) => rawLine.replace(planCheckboxPattern, '$1x$2'));
                         }
                         return b;
                     });
@@ -3270,14 +3606,38 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                 if (node_fs_1.default.existsSync(reqPath)) {
                     const phaseEsc = phaseMarkdownRegexSource(phaseNum);
                     const currentMilestoneRoadmap = extractCurrentMilestone(roadmapContent, cwd);
-                    const phaseSectionMatch = currentMilestoneRoadmap.match(new RegExp(`(#{2,4}\\s*Phase\\s+${phaseEsc}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s][\\s\\S]*?)(?=#{2,4}\\s*Phase\\s+|$)`, 'i'));
+                    // #5007 (Phase 6 / ADR-4910 §8): this site captures the entire
+                    // section BODY through to the next heading (via its own
+                    // `[\s\S]*?` lookahead-to-next-heading structure) — neither shared
+                    // owner returns that shape, so phaseHeadingPrefixSrcFor is composed
+                    // directly, keeping this site's own lookahead. The prior hand-rolled
+                    // heading-marker-plus-label literal appeared TWICE in this source
+                    // (the main capture prefix AND the lookahead) — both occurrences
+                    // were the literal-drift detector's target
+                    // (findPhaseHeadingScanLiteralDrift is a pure literal-text match,
+                    // blind to what surrounds it), so both are replaced with the same
+                    // composed prefix, built once via phaseHeadingPrefixSrcFor and
+                    // reused, so the two halves cannot drift from each other. No
+                    // convention argument: LABEL_ONLY with convention=undefined
+                    // reproduces the prior `Phase\s+` literal byte-for-byte — this
+                    // feeds cmdPhaseComplete, so no widening was introduced.
+                    const phaseSectionHeadingPrefix = `#{2,4}\\s*${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY)}`;
+                    const phaseSectionMatch = currentMilestoneRoadmap.match(new RegExp(`(${phaseSectionHeadingPrefix}${phaseEsc}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s][\\s\\S]*?)(?=${phaseSectionHeadingPrefix}|$)`, 'i'));
                     const sectionText = phaseSectionMatch ? phaseSectionMatch[1] : '';
-                    const reqMatch = sectionText.match(/\*\*Requirements:?\*\*[^\S\n]*:?[^\S\n]*([^\n]+)/i);
+                    // #4731: multiline-aware — hard-wrapped Requirements read past the
+                    // line break before the ID scan. The shared extractor also stops at
+                    // headings and table rows, so a Requirements field followed by the
+                    // Traceability table cannot bleed other phases' REQ-IDs into the
+                    // citation scan (isolated-review MEDIUM on the inline lookahead,
+                    // whose lazy capture swallowed everything to section end).
+                    const reqLine = sectionText
+                        ? roadmapParserMod.extractPhaseFieldMultiline(sectionText, 'Requirements')
+                        : null;
                     const originalReqContent = node_fs_1.default.readFileSync(reqPath, 'utf-8');
                     let reqContent = originalReqContent;
                     // #2316: `citedReqIds` — the REQ-IDs ROADMAP's own **Requirements:**
                     // line for this phase actually cites — is hoisted out of the
-                    // `if (reqMatch)` block (previously scoped only inside it) so the
+                    // `if (reqLine)` block (previously scoped only inside it) so the
                     // ghost-ID cross-check below (~#2316-1) can consult it. `TBD` is the
                     // literal placeholder `phase.add`/`-batch`/`-insert` seed
                     // (`**Requirements**: TBD`, src/phase.cts:833,920,1078) — never a
@@ -3289,16 +3649,16 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                     // otherwise) — the `if (reqUpdate.ok)` below previously had no
                     // `else`, discarding this fact silently instead of surfacing it.
                     const traceabilityWriteMisses = [];
-                    if (reqMatch) {
+                    if (reqLine) {
                         // #2334 HIGH 3 + #3697: selection and under-selection detection both
                         // live in `analyzeRequirementsLine` (module scope, above), extracted in
                         // round 3 so the parser is directly testable — a closure in here is
                         // reachable only by spawning the CLI, which no fast-check property test
                         // can do. `citedReqIds` is byte-identical to the expression that stood
                         // here; nothing about what phase-complete MARKS has changed.
-                        const reqLineAnalysis = analyzeRequirementsLine(reqMatch[1]);
+                        const reqLineAnalysis = analyzeRequirementsLine(reqLine);
                         citedReqIds = reqLineAnalysis.citedReqIds;
-                        const reqLineWarning = formatRequirementsLineWarning(phaseNum, reqMatch[1], reqLineAnalysis);
+                        const reqLineWarning = formatRequirementsLineWarning(phaseNum, reqLine, reqLineAnalysis);
                         if (reqLineWarning) {
                             warnings.push(reqLineWarning.message);
                             // Carried out to the JSON result as its own field — see
@@ -3584,6 +3944,34 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
             let diskNextName = null;
             let roadmapNextNum = null;
             let roadmapNextName = null;
+            // #4699: a phase whose roadmap checkbox is `[x]` is already complete and
+            // must never be selected as next_phase — out-of-order completion (a
+            // reopened phase finished after later phases shipped) otherwise persists
+            // the already-done phase as STATE.md current_phase. Collected from the
+            // same milestone-scoped text the roadmap scan walks; membership is
+            // comparePhaseNum-based so `02` and `2` dedupe. With no ROADMAP.md (or no
+            // parseable rows) the set is empty and the scans behave exactly as
+            // before.
+            const roadmapCompleteNums = [];
+            if (roadmapContent !== null) {
+                try {
+                    const milestoneForComplete = extractCurrentMilestone(roadmapContent, cwd);
+                    const completePattern = new RegExp(`-\\s*\\[[xX]\\]\\s*(?:\\*\\*|__)?\\s*Phase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})`, 'gi');
+                    let cm;
+                    while ((cm = completePattern.exec(milestoneForComplete)) !== null) {
+                        if (isSentinelPhaseId(cm[1]))
+                            continue;
+                        if (!roadmapCompleteNums.some((n) => comparePhaseNum(cm[1], n) === 0)) {
+                            roadmapCompleteNums.push(cm[1]);
+                        }
+                    }
+                }
+                catch {
+                    /* best-effort: an unreadable milestone section leaves the complete
+                     * set empty — the scans then behave exactly as they did pre-#4699. */
+                }
+            }
+            const isCompletePhaseNum = (num) => roadmapCompleteNums.some((n) => comparePhaseNum(num, n) === 0);
             try {
                 // #3185 (ADR-3180 Decision 1): "which phase directories belong to
                 // the CURRENT milestone" — routed through the canonical owner
@@ -3599,6 +3987,10 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                         // #3185: canonical sentinel predicate (SENTINEL_RANGES [0,999]) — this was a local 999-only literal that admitted Phase 0.
                         if (isSentinelPhaseId(dm[1]))
                             continue;
+                        // #4699: an already-complete phase (roadmap checkbox [x]) is never
+                        // a next_phase candidate — out-of-order completion must skip it.
+                        if (roadmapContent !== null && isCompletePhaseNum(dm[1]))
+                            continue;
                         // Numeric MINIMUM above N, not "first encountered". `listMilestonePhaseDirs`
                         // does sort by `comparePhaseNum`, so a `break` on the first hit happens to be
                         // correct today — but that makes this scan's correctness depend on an
@@ -3666,6 +4058,11 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                         // stage 2's heading scan must not advance into backlog headings either.
                         if (isSentinelPhaseId(pmNum))
                             continue;
+                        // #4699: skip complete phases — a `[x]` checkbox row and the
+                        // `## Phase Details` heading of an already-done phase both name a
+                        // phase that must never be next_phase.
+                        if (roadmapContent !== null && isCompletePhaseNum(pmNum))
+                            continue;
                         // #3701 review: the numeric MINIMUM above N, not the first row above N in
                         // DOCUMENT order. This scan walks raw roadmap text, and one global regex
                         // sweeps both the `## Phases` checklist and the `## Phase Details`
@@ -4009,6 +4406,9 @@ function cmdPhaseUatPassed(cwd, phaseNum, raw, opts = {}) {
     const phaseFullDir = node_path_1.default.join(cwd, phaseInfo['directory']);
     const report = evaluateUatPassed(phaseFullDir, { policy: opts.policy });
     output({ phase: phaseNum, ...report }, raw);
+    // #5170: the exit status follows the verdict (status mode: a failing verdict is exit 1). Declared
+    // AFTER output(), which rewrites the pending-outcome cell. The JSON above is unchanged.
+    (0, gate_exit_cjs_1.declareGateExit)((0, gate_verdict_cjs_1.gateVerdict)(report.passed ? 'pass' : 'block', !report.passed, { phase: phaseNum, ...report }), 'status');
 }
 // #1437 — phase.list-plans: list plan files for a given phase number.
 // Returns the full scan result from scanPhasePlans so callers can read plan
@@ -4057,4 +4457,5 @@ module.exports = {
     cmdPhaseListPlans,
     computeDependencyLevels,
     buildShortFormToId,
+    normalizeDependencyToken,
 };