@opengsd/gsd-core 1.13.0 → 1.15.0

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

@@ -45,10 +45,19 @@ const { normalizePhaseName, phaseMarkdownRegexSource, comparePhaseNum, matchPhas
 const pattern_cjs_1 = require("./pattern.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 } = phaseLocatorMod;
+const { findPhaseInternal, getArchivedPhaseDirs, listMilestonePhaseDirs, listAllPhaseDirs } = phaseLocatorMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-scope.cjs is an export= CommonJS module
+const planningScopeMod = require("./planning-scope.cjs");
+const { SCOPE } = planningScopeMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- roadmap-parser.cjs is an export= CommonJS module
 const roadmapParserMod = require("./roadmap-parser.cjs");
 const { stripShippedMilestones, extractCurrentMilestone, currentMilestoneRawRanges, withPhaseSection, findMilestoneScopeHeadingLines } = roadmapParserMod;
+// #4129: the single owner of "count the ROADMAP's milestone Complete rows"
+// (pure computation, no I/O — no cycle on this path) for the intent-first
+// progress counters the phase-complete transaction passes downstream.
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-lifecycle.cjs is an export= CommonJS module
+const phaseLifecycleMod = require("./phase-lifecycle.cjs");
+const { deriveProgressFromRoadmap: deriveProgressFromRoadmapForIntent, clampPercent: clampPercentForIntent } = phaseLifecycleMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-workspace.cjs is an export= CommonJS module
 const planningWorkspace = require("./planning-workspace.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- frontmatter.cjs is an export= CommonJS module
@@ -56,6 +65,7 @@ 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");
@@ -77,7 +87,7 @@ 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
@@ -287,25 +297,26 @@ function cmdPhaseNextDecimal(cwd, basePhase, raw) {
             const entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
             const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
             baseExists = matchPhaseDirs(dirs, normalized).matches.length > 0;
-            const dirPattern = new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}${(0, pattern_cjs_1.escapeRegex)(normalized)}\\.(\\d+)`);
-            for (const dir of dirs) {
-                const match = dir.match(dirPattern);
-                if (match)
-                    decimalSet.add(parseInt(match[1], 10));
-            }
         }
         const roadmapPath = node_path_1.default.join(planningDir(cwd), 'ROADMAP.md');
         if (node_fs_1.default.existsSync(roadmapPath)) {
             try {
                 const roadmapContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
-                const phasePattern = new RegExp(`#{2,4}\\s*Phase\\s+${phaseMarkdownRegexSource(normalized)}\\.(\\d+)${OPTIONAL_PHASE_TAG_SOURCE}\\s*:`, 'gi');
-                let pm;
-                while ((pm = phasePattern.exec(roadmapContent)) !== null) {
-                    decimalSet.add(parseInt(pm[1], 10));
+                for (const n of scanExistingDecimalPhaseNumbers(phasesDir, roadmapContent, normalized)) {
+                    decimalSet.add(n);
                 }
             }
             catch {
-                /* ROADMAP.md read failure is non-fatal */
+                // ROADMAP.md read failure is non-fatal — fall back to the directory-only
+                // scan (empty rawContent) so on-disk decimal directories are still counted.
+                for (const n of scanExistingDecimalPhaseNumbers(phasesDir, '', normalized)) {
+                    decimalSet.add(n);
+                }
+            }
+        }
+        else {
+            for (const n of scanExistingDecimalPhaseNumbers(phasesDir, '', normalized)) {
+                decimalSet.add(n);
             }
         }
         const existingDecimals = Array.from(decimalSet)
@@ -338,6 +349,7 @@ function getRoadmapModeForPhase(cwd, phaseNum) {
     const milestoneContent = extractCurrentMilestone(rawContent, cwd);
     const fullContent = stripShippedMilestones(rawContent);
     const escapedPhase = phaseMarkdownRegexSource(phaseNum);
+    // phase-id-owner: pre-existing hand-rolled Phase-heading pattern — grandfathered pending Phase 6 migration (ADR-4910 §8, epic #4906)
     const phaseHeader = new RegExp(`#{2,4}\\s*Phase\\s+${escapedPhase}${OPTIONAL_PHASE_TAG_SOURCE}\\s*:`, 'i');
     for (const content of [milestoneContent, fullContent]) {
         const headerMatch = content.match(phaseHeader);
@@ -582,8 +594,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))
@@ -624,7 +644,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);
             }
@@ -734,12 +754,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
@@ -834,7 +854,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.`);
@@ -842,8 +862,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
@@ -878,6 +898,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
@@ -887,8 +911,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) {
@@ -896,14 +924,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;
@@ -945,6 +993,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]) {
@@ -958,6 +1015,7 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
         waves,
         incomplete,
         runnable,
+        ready_plans: readyPlans,
         has_checkpoints: hasCheckpoints,
     };
     if (planNamingWarning)
@@ -1061,12 +1119,24 @@ function assertDescriptionPreservesMilestoneScope(cwd, description, command) {
  * before any directory does; milestone-scoping is wrong here because a number
  * used under any milestone on another branch is still taken).
  *
+ * #4225 — the horizon must track the ALLOCATION scope. When the allocation is
+ * workstream-scoped (`--ws`/`GSD_WORKSTREAM`, resolved into the env before
+ * dispatch), the sibling's copy of the SAME workstream is what carries that
+ * scope's independent numbering; the sibling's ROOT roadmap and phases/
+ * belong to a different numbering universe (docs/FEATURES.md §51 REQ-WS-01 —
+ * workstream state is isolated in `.planning/workstreams/{name}/`) and must
+ * not contribute. `planningDir(wt, ws)` reuses the canonical resolver, so the
+ * sibling scope matches the local scope's own resolution (env workstream plus
+ * env project segment) by construction; `ws === null` (no workstream active)
+ * keeps the #3849 root-scope horizon byte-for-byte.
+ *
  * Widen, never refuse: a missing `.planning/`, an unreadable sibling, a
  * non-git cwd, or an unavailable git binary each leave `used` untouched —
  * allocation then behaves exactly as it did before this horizon existed.
- * Sentinels reuse the canonical `isSentinelPhaseId`; the dir pattern is the
- * same one the on-disk scan uses, so decimal sub-phases (`411.1-foo`) are
- * correctly not integers.
+ * A sibling that simply lacks the active workstream's directory is the same
+ * fail-open case: it contributes nothing. Sentinels reuse the canonical
+ * `isSentinelPhaseId`; the dir pattern is the same one the on-disk scan uses,
+ * so decimal sub-phases (`411.1-foo`) are correctly not integers.
  */
 function collectSiblingWorktreePhaseNums(cwd, used) {
     let porcelain;
@@ -1084,8 +1154,16 @@ function collectSiblingWorktreePhaseNums(cwd, used) {
     catch {
         return; // not a git repo / git unavailable — unchanged behavior
     }
+    // #4225: the env workstream, read once with planningDir's own discriminator
+    // (`?? null` = deliberately no workstream — never re-derived per sibling).
+    // A poisoned value would already have thrown at the local `planningDir(cwd)`
+    // call every allocator makes before reaching this horizon; the per-sibling
+    // try/catch below still keeps any resolution failure fail-open.
+    const ws = process.env['GSD_WORKSTREAM'] ?? null;
+    const siblingPlanningDir = (wt) => planningDir(wt, ws);
     const dirNumPattern = /^(?:[A-Z][A-Z0-9]*-)?(\d+)-/;
     // Same header shape the allocators scan locally (#1729 tag tolerance).
+    // phase-id-owner: pre-existing hand-rolled Phase-heading pattern — grandfathered pending Phase 6 migration (ADR-4910 §8, epic #4906)
     const headerPattern = /#{2,4}\s*Phase\s+(\d+)[A-Z]?(?:\.\d+)*(?:\s*\([^)\n]{0,200}\))?:/gi;
     for (const line of porcelain.split('\n')) {
         if (!line.startsWith('worktree '))
@@ -1094,7 +1172,7 @@ function collectSiblingWorktreePhaseNums(cwd, used) {
         if (!wt || node_path_1.default.resolve(wt) === node_path_1.default.resolve(cwd))
             continue;
         try {
-            for (const entry of node_fs_1.default.readdirSync(node_path_1.default.join(wt, '.planning', 'phases'))) {
+            for (const entry of node_fs_1.default.readdirSync(node_path_1.default.join(siblingPlanningDir(wt), 'phases'))) {
                 const match = entry.match(dirNumPattern);
                 if (!match)
                     continue;
@@ -1104,10 +1182,10 @@ function collectSiblingWorktreePhaseNums(cwd, used) {
             }
         }
         catch {
-            /* worktree has no .planning — normal, contributes nothing */
+            /* worktree has no .planning (or no copy of this scope) — normal, contributes nothing */
         }
         try {
-            const content = node_fs_1.default.readFileSync(node_path_1.default.join(wt, '.planning', 'ROADMAP.md'), 'utf-8');
+            const content = node_fs_1.default.readFileSync(node_path_1.default.join(siblingPlanningDir(wt), 'ROADMAP.md'), 'utf-8');
             let m;
             headerPattern.lastIndex = 0;
             while ((m = headerPattern.exec(content)) !== null) {
@@ -1117,7 +1195,7 @@ function collectSiblingWorktreePhaseNums(cwd, used) {
             }
         }
         catch {
-            /* no roadmap in that worktree — normal, contributes nothing */
+            /* no roadmap in that worktree (or scope) — normal, contributes nothing */
         }
     }
 }
@@ -1151,6 +1229,7 @@ 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).
+            // phase-id-owner: pre-existing hand-rolled Phase-heading pattern — grandfathered pending Phase 6 migration (ADR-4910 §8, epic #4906)
             const headerPattern = /#{2,4}\s*Phase\s+(\d+)[A-Z]?(?:\.\d+)*(?:\s*\([^)\n]{0,200}\))?:/gi;
             // 2) Roadmap bullet entries: - [ ] **Phase N: ...** (all checkbox variants)
             // The lookahead accepts colon, decimal-dot, whitespace, bold-close asterisk,
@@ -1260,6 +1339,7 @@ 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).
+            // phase-id-owner: pre-existing hand-rolled Phase-heading pattern — grandfathered pending Phase 6 migration (ADR-4910 §8, epic #4906)
             const phasePattern = /#{2,4}\s*Phase\s+(\d+)[A-Z]?(?:\.\d+)*(?:\s*\([^)\n]{0,200}\))?:/gi;
             const bulletPattern = /^[ \t]*-[ \t]*\[[^\]]{0,200}\][ \t]*\*{0,2}Phase[ \t]+(\d+)(?=[:.\s*]|$)/gim;
             let m;
@@ -1343,7 +1423,65 @@ function cmdPhaseAddBatch(cwd, descriptions, raw) {
     // found')` above, which terminates the process and never reaches here.
     publishStateContract(cwd);
 }
-function cmdPhaseInsert(cwd, afterPhase, description, raw) {
+// #4569: scans all three representations of an existing decimal sub-phase
+// under `base` — on-disk `phases/` directories, `### Phase BASE.N:` headings,
+// and `- [ ] Phase BASE.N:` roadmap SUMMARY CHECKLIST bullets. A bullet-only
+// roadmap with no heading yet and no on-disk directory yet must still be
+// seen, or an allocator can silently reallocate an already-used decimal
+// number. Shared by `cmdPhaseInsert`'s normalized-base scan and its
+// sibling-allocation parent-base scan so the two never drift apart.
+function scanExistingDecimalPhaseNumbers(phasesDir, rawContent, base) {
+    const decimalSet = new Set();
+    // #2245 audit: existsSync-guarded, mirroring cmdPhaseNextDecimal's identical
+    // scan above — a missing phasesDir (no decimal sub-phases yet) is the
+    // expected, silent case (empty decimalSet). A readdirSync failure once the
+    // dir is confirmed to EXIST is a genuine anomaly; swallowing it used to let
+    // `phase insert` proceed with an incomplete decimalSet and risk writing a
+    // decimal phase number that collides with an existing on-disk directory
+    // the scan simply never saw — surfaced loud instead, like the sibling.
+    //
+    // #4634 (lint-phase-enumeration-drift): routed through the canonical
+    // PHYSICAL-set owner (`listAllPhaseDirs`, phase-locator.cts) instead of a
+    // hand-rolled `readdirSync`. This scan — like its sibling `cmdPhaseNextDecimal`
+    // and its caller `cmdPhaseInsert` (both exempted in the drift guard for the
+    // same reason) — must see EVERY on-disk decimal sub-phase directory
+    // regardless of the current milestone window, so `listMilestonePhaseDirs`
+    // (windowed) is the wrong owner here; `includeSentinels: true` preserves this
+    // function's pre-existing behavior of never sentinel-filtering (the decimal
+    // regex below only ever matches `base.N`-shaped names, so sentinel inclusion
+    // is a no-op either way).
+    if (node_fs_1.default.existsSync(phasesDir)) {
+        const { value: dirs, scope } = listAllPhaseDirs(phasesDir, { includeSentinels: true });
+        if (scope === SCOPE.UNREADABLE) {
+            // The dir EXISTS but could not be read (EACCES/EIO) — a genuine anomaly,
+            // not the expected empty-decimalSet case above. Surfaced loud, matching
+            // this function's pre-migration `readdirSync` catch: swallowing it would
+            // let `phase insert` proceed with an incomplete decimalSet and collide
+            // with an existing on-disk decimal directory the scan never saw.
+            error(`Failed to scan phase directories for existing decimal phases: unable to read ${phasesDir}`);
+        }
+        const decimalPattern = new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}${(0, pattern_cjs_1.escapeRegex)(base)}\\.(\\d+)`);
+        for (const dir of dirs) {
+            const dm = dir.match(decimalPattern);
+            if (dm)
+                decimalSet.add(parseInt(dm[1], 10));
+        }
+    }
+    const rmPhasePattern = new RegExp(
+    // phase-id-owner: pre-existing hand-rolled Phase-heading pattern — grandfathered pending Phase 6 migration (ADR-4910 §8, epic #4906)
+    `#{2,4}\\s*Phase\\s+${phaseMarkdownRegexSource(base)}\\.(\\d+)${OPTIONAL_PHASE_TAG_SOURCE}\\s*:`, 'gi');
+    let rmMatch;
+    while ((rmMatch = rmPhasePattern.exec(rawContent)) !== null) {
+        decimalSet.add(parseInt(rmMatch[1], 10));
+    }
+    const checklistDecimalPattern = new RegExp(`-\\s*\\[[ x]\\]\\s*(?:\\*\\*)?Phase\\s+${phaseMarkdownRegexSource(base)}\\.(\\d+)${OPTIONAL_PHASE_TAG_SOURCE}[:\\s]`, 'gi');
+    let clMatch;
+    while ((clMatch = checklistDecimalPattern.exec(rawContent)) !== null) {
+        decimalSet.add(parseInt(clMatch[1], 10));
+    }
+    return decimalSet;
+}
+function cmdPhaseInsert(cwd, afterPhase, description, raw, allocation = 'nested') {
     if (!afterPhase || !description) {
         error('after-phase and description required for phase insert');
     }
@@ -1358,9 +1496,11 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
         const content = extractCurrentMilestone(rawContent, cwd);
         const normalizedAfter = normalizePhaseName(afterPhase);
         const afterPhaseEscaped = phaseMarkdownRegexSource(normalizedAfter);
+        // phase-id-owner: pre-existing hand-rolled Phase-heading pattern — grandfathered pending Phase 6 migration (ADR-4910 §8, epic #4906)
         const targetPattern = new RegExp(`#{2,4}\\s*Phase\\s+${afterPhaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}:`, 'i');
         const headingMatch = targetPattern.test(content);
         const bulletPattern = new RegExp(`-\\s*\\[[ x]\\]\\s*(?:\\*\\*)?Phase\\s+${afterPhaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s]`, 'i');
+        // phase-id-owner: pre-existing hand-rolled Phase-heading pattern — grandfathered pending Phase 6 migration (ADR-4910 §8, epic #4906)
         const anyHeadingPattern = /#{2,4}\s*Phase\s+\d/i;
         const roadmapHasHeadingPhases = anyHeadingPattern.test(content);
         const isBulletStyle = !headingMatch && bulletPattern.test(content) && !roadmapHasHeadingPhases;
@@ -1373,43 +1513,20 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
         }
         const phasesDir = node_path_1.default.join(planningDir(cwd), 'phases');
         const normalizedBase = normalizePhaseName(afterPhase);
-        const decimalSet = new Set();
-        // #2245 audit: existsSync-guarded, mirroring cmdPhaseNextDecimal's identical
-        // scan above — a missing phasesDir (no decimal sub-phases yet) is the
-        // expected, silent case (empty decimalSet). A readdirSync failure once the
-        // dir is confirmed to EXIST is a genuine anomaly; swallowing it used to let
-        // `phase insert` proceed with an incomplete decimalSet and risk writing a
-        // decimal phase number that collides with an existing on-disk directory
-        // the scan simply never saw — surfaced loud instead, like the sibling.
-        if (node_fs_1.default.existsSync(phasesDir)) {
-            // Initialized (not just declared) so TS's definite-assignment check is
-            // satisfied without relying on control-flow narrowing through error()'s
-            // `never` return, which TS does not propagate through a destructured
-            // module-property function reference — error() still halts the process
-            // before `dirs` below is ever computed from this placeholder value.
-            let entries = [];
-            try {
-                entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
-            }
-            catch (e) {
-                const msg = e instanceof Error ? e.message : String(e);
-                error(`Failed to scan phase directories for existing decimal phases: ${msg}`);
-            }
-            const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
-            const decimalPattern = new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}${(0, pattern_cjs_1.escapeRegex)(normalizedBase)}\\.(\\d+)`);
-            for (const dir of dirs) {
-                const dm = dir.match(decimalPattern);
-                if (dm)
-                    decimalSet.add(parseInt(dm[1], 10));
-            }
-        }
-        const rmPhasePattern = new RegExp(`#{2,4}\\s*Phase\\s+${phaseMarkdownRegexSource(normalizedBase)}\\.(\\d+)${OPTIONAL_PHASE_TAG_SOURCE}\\s*:`, 'gi');
-        let rmMatch;
-        while ((rmMatch = rmPhasePattern.exec(rawContent)) !== null) {
-            decimalSet.add(parseInt(rmMatch[1], 10));
-        }
+        const decimalSet = scanExistingDecimalPhaseNumbers(phasesDir, rawContent, normalizedBase);
         const nextDecimal = decimalSet.size === 0 ? 1 : Math.max(...decimalSet) + 1;
-        const _decimalPhase = `${normalizedBase}.${nextDecimal}`;
+        let _decimalPhase = `${normalizedBase}.${nextDecimal}`;
+        // #4569: sibling allocation joins afterPhase's PARENT level instead of nesting
+        // one level deeper under afterPhase itself. A top-level phase (no existing
+        // decimal segment) has no sibling level to join; nested is the only sensible
+        // allocation, so we silently fall back for that case.
+        const lastDotIndex = normalizedBase.lastIndexOf('.');
+        if (allocation === 'sibling' && lastDotIndex !== -1) {
+            const parentBase = normalizedBase.slice(0, lastDotIndex);
+            const siblingDecimalSet = scanExistingDecimalPhaseNumbers(phasesDir, rawContent, parentBase);
+            const siblingNextDecimal = siblingDecimalSet.size === 0 ? 1 : Math.max(...siblingDecimalSet) + 1;
+            _decimalPhase = `${parentBase}.${siblingNextDecimal}`;
+        }
         const insertConfig = loadConfig(cwd);
         const projectCode = insertConfig.project_code || '';
         const pfx = projectCode ? `${projectCode}-` : '';
@@ -1460,7 +1577,9 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
         }
         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');
+            const headerPattern = new RegExp(
+            // phase-id-owner: pre-existing hand-rolled Phase-heading pattern — grandfathered pending Phase 6 migration (ADR-4910 §8, epic #4906)
+            `(#{2,4}\\s*Phase\\s+${afterPhaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}:[^\\n]*\\n)`, 'i');
             const headerMatch = rawContent.match(headerPattern);
             if (!headerMatch) {
                 error(`Could not find Phase ${afterPhase} header`);
@@ -1782,7 +1901,9 @@ 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}`);
+            content = content.replace(
+            // phase-id-owner: pre-existing hand-rolled Phase-heading pattern — grandfathered pending Phase 6 migration (ADR-4910 §8, epic #4906)
+            /(#{2,4}\s*Phase\s+)(\d+(?:\.\d+)?)((?:\s*\([^)\r\n]{0,200}\))?\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
@@ -2115,6 +2236,7 @@ function phaseDisplayNameFromRoadmap(roadmapContent, phaseNum) {
     if (!roadmapContent || !phaseNum)
         return null;
     const phaseEscaped = phaseMarkdownRegexSource(phaseNum);
+    // phase-id-owner: pre-existing hand-rolled Phase-heading pattern — grandfathered pending Phase 6 migration (ADR-4910 §8, epic #4906)
     const heading = roadmapContent.match(new RegExp(`^#{2,4}\\s*Phase\\s+${phaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}\\s*:\\s*([^\\n]+)`, 'im'));
     if (!heading)
         return null;
@@ -2776,7 +2898,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
@@ -3022,7 +3144,10 @@ 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.
-        const verificationStatus = readVerificationStatus(phaseFullDir, { runtime: (0, runtime_slash_cjs_1.resolveRuntime)(cwd) });
+        const verificationStatus = readVerificationStatus(phaseFullDir, {
+            runtime: (0, runtime_slash_cjs_1.resolveRuntime)(cwd),
+            convention: resolvePhaseIdConvention(cwd),
+        });
         // #3057 B3: the staleness check inside readVerificationStatus can itself
         // fail (fs / scanPhasePlans / clock error), in which case `status` above
         // was routed as if nothing were stale (unchanged fail-open routing) — but
@@ -3065,7 +3190,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
@@ -3118,12 +3243,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)
@@ -3160,7 +3378,7 @@ 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)
@@ -3205,14 +3423,24 @@ 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'));
+                    const phaseSectionMatch = currentMilestoneRoadmap.match(new RegExp(
+                    // phase-id-owner: pre-existing hand-rolled Phase-heading pattern — grandfathered pending Phase 6 migration (ADR-4910 §8, epic #4906)
+                    `(#{2,4}\\s*Phase\\s+${phaseEsc}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s][\\s\\S]*?)(?=#{2,4}\\s*Phase\\s+|$)`, '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
@@ -3224,16 +3452,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
@@ -3519,6 +3747,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
@@ -3534,6 +3790,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
@@ -3601,6 +3861,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`
@@ -3767,14 +4032,53 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                 const fmBody = frontmatterMod.stripFrontmatter(stateContent);
                 const bodyHasPhaseField = stateExtractField(fmBody, 'Current Phase') != null ||
                     stateExtractField(fmBody, 'Phase') != null;
-                const authoritativeFm = nextPhaseDisplayName
-                    ? bodyHasPhaseField || !nextPhaseNum
-                        ? { current_phase_name: nextPhaseDisplayName }
-                        : {
-                            current_phase: String(nextPhaseNum),
-                            current_phase_name: nextPhaseDisplayName,
+                // #4129: the POST-completion progress counters, derived from the very
+                // ROADMAP this transaction just mutated (still in memory — it hits disk
+                // only at writePlanningFileSet, AFTER this content was assembled).
+                // buildStateFrontmatter's disk scan inside syncAndPreserveStateMd
+                // reads the PRE-completion ROADMAP (and any stale-dated sibling
+                // verification), so without this intent the persisted counter failed
+                // to increment on the completing phase's own transaction. Routed
+                // through the #2736 authoritativeFm seam's object direction: the
+                // pre-preservation merge makes it the derived truth the ratchet
+                // compares, and the post-preservation re-assert (completedOnlyRaise)
+                // is a floor no preservation branch can drop below. clampPercent is
+                // completePhaseCore's own percent formula (state-transition.cts),
+                // reused so the frontmatter and the body `Progress:` line agree.
+                const postCompletionRoadmapScope = roadmapContent !== null
+                    ? extractCurrentMilestone(roadmapContent, cwd)
+                    : null;
+                const postCompletionRoadmapProgress = postCompletionRoadmapScope !== null
+                    ? deriveProgressFromRoadmapForIntent(postCompletionRoadmapScope)
+                    : null;
+                const authoritativeProgress = postCompletionRoadmapProgress && postCompletionRoadmapProgress.completedPhases !== null
+                    ? postCompletionRoadmapProgress.totalPhases !== null && postCompletionRoadmapProgress.totalPhases > 0
+                        ? {
+                            completed_phases: postCompletionRoadmapProgress.completedPhases,
+                            percent: clampPercentForIntent(postCompletionRoadmapProgress.completedPhases, postCompletionRoadmapProgress.totalPhases),
                         }
+                        : { completed_phases: postCompletionRoadmapProgress.completedPhases }
                     : undefined;
+                const authoritativeFm = authoritativeProgress
+                    ? {
+                        ...(nextPhaseDisplayName
+                            ? bodyHasPhaseField || !nextPhaseNum
+                                ? { current_phase_name: nextPhaseDisplayName }
+                                : {
+                                    current_phase: String(nextPhaseNum),
+                                    current_phase_name: nextPhaseDisplayName,
+                                }
+                            : {}),
+                        progress: authoritativeProgress,
+                    }
+                    : nextPhaseDisplayName
+                        ? bodyHasPhaseField || !nextPhaseNum
+                            ? { current_phase_name: nextPhaseDisplayName }
+                            : {
+                                current_phase: String(nextPhaseNum),
+                                current_phase_name: nextPhaseDisplayName,
+                            }
+                        : undefined;
                 // ADR-3408 §8.3 / #3469: this deliberately bypasses
                 // readModifyWriteStateMd (STATE.md is committed atomically with
                 // ROADMAP/REQUIREMENTS), so it calls the single write-seam
@@ -3953,4 +4257,5 @@ module.exports = {
     cmdPhaseListPlans,
     computeDependencyLevels,
     buildShortFormToId,
+    normalizeDependencyToken,
 };