@opengsd/gsd-core 1.7.0-rc.6 → 1.8.0

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

@@ -38,7 +38,7 @@ const phaseLocatorMod = require("./phase-locator.cjs");
 const { findPhaseInternal, getArchivedPhaseDirs } = phaseLocatorMod;
 // 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, getMilestonePhaseFilter } = roadmapParserMod;
+const { stripShippedMilestones, extractCurrentMilestone, getMilestonePhaseFilter, currentMilestoneRawRanges, withPhaseSection } = roadmapParserMod;
 // 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
@@ -49,6 +49,8 @@ const shell_command_projection_cjs_1 = require("./shell-command-projection.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");
+const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 // 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;
@@ -67,6 +69,56 @@ const looksLikePlanFile = (f) => /\.md$/i.test(f) &&
     /PLAN/i.test(f) &&
     !PLAN_OUTLINE_RE.test(f) &&
     !PLAN_PRE_BOUNCE_RE.test(f);
+/**
+ * Scope an `updateTableCell` call to the `## Traceability` (or
+ * `## Traceability Status`) heading's own section — up to the next H1/H2
+ * heading — instead of handing it the WHOLE REQUIREMENTS.md content.
+ *
+ * F1 (#2245 review, BLOCKER): `updateTableCell` binds to the FIRST GFM table
+ * found in whatever text it is given. The shipped requirements template
+ * (gsd-core/templates/requirements.md) puts an `## Out of Scope` table
+ * (`| Feature | Reason |`, no `Status` column) BEFORE `## Traceability` — so
+ * an unscoped whole-file call targets the Out-of-Scope table instead, fails
+ * with `{ok:false, reason:'unknown column: Status'}`, and the real
+ * Traceability row is never flipped, while the checkbox surface still flips
+ * and the command reports success (the #2140 silent-divergence class one
+ * level deeper). Mirrors `editProgressHeadingSlice` below, which scopes
+ * `## Progress` writes to that heading's own slice for the same reason.
+ *
+ * Falls back to running `updateTableCell` against the whole `text` when no
+ * `## Traceability` heading exists — matching the previous (unscoped)
+ * behaviour for a REQUIREMENTS.md whose traceability table sits under some
+ * other heading, or with no heading at all (never worse than before this fix).
+ */
+function updateTraceabilityCell(text, match, column, newValue) {
+    const headingMatch = text.match(/^##[ \t]+Traceability(?:[ \t]+Status)?\b/im);
+    if (!headingMatch || headingMatch.index === undefined) {
+        return (0, markdown_table_cjs_1.updateTableCell)(text, match, column, newValue);
+    }
+    const headingOffset = headingMatch.index;
+    const before = text.slice(0, headingOffset);
+    const fromHeading = text.slice(headingOffset);
+    const nextHeadingOffset = fromHeading.search(/\n#{1,2}[ \t]/);
+    const scoped = nextHeadingOffset >= 0 ? fromHeading.slice(0, nextHeadingOffset) : fromHeading;
+    const after = nextHeadingOffset >= 0 ? fromHeading.slice(nextHeadingOffset) : '';
+    const result = (0, markdown_table_cjs_1.updateTableCell)(scoped, match, column, newValue);
+    if (!result.ok)
+        return result;
+    return { ok: true, value: before + result.value + after };
+}
+/**
+ * Extract the MAJOR version segment from a version-ish string: "v1", "v1.3",
+ * "V1.0", and "1.0" all yield "1"; "v2" yields "2". Used (#2334 BLOCKER fix)
+ * to compare a `## v<N> ...` REQUIREMENTS.md heading against the current
+ * milestone's version at MAJOR-version granularity only — "v1" heading vs
+ * milestone "v1.3" is the SAME major version and must not be treated as a
+ * version mismatch. Returns null when `raw` has no leading digit run (not a
+ * version-shaped string), which the caller treats as "cannot resolve".
+ */
+function extractMajorVersion(raw) {
+    const m = raw.trim().match(/^v?(\d+)/i);
+    return m ? m[1] : null;
+}
 function describeNonCanonicalPlans(dirFiles, matchedFiles) {
     const matched = new Set(matchedFiles);
     const offenders = dirFiles.filter((f) => looksLikePlanFile(f) && !matched.has(f));
@@ -88,8 +140,13 @@ function extractCanonicalPlanId(filename) {
     // or a single-digit-plus-letter id ("3A"); a *bare* single digit is a slug word,
     // so "46-6-rs-…" is not paired into a "46-6" id while "3A-01" stays intact.
     const tokenRe = /^(?:\d{2,}[A-Z]?|\d[A-Z])(?:\.\d+)*$/i;
+    // #2232: the PAIRED plan component is a zero-padded continuation segment
+    // (exactly 2 digits), so a ≥3-digit slug word (a year) is not paired into a
+    // bogus "14-2026" id. The leading phase component keeps tokenRe's unbounded
+    // \d{2,} — phase numbers ≥100 are legitimate; only continuations are capped.
+    const planTokenRe = new RegExp(`^(?:${phaseIdMod.PHASE_CONTINUATION_SEGMENT_SOURCE}[A-Z]?|\\d[A-Z])(?:\\.\\d+)*$`, 'i');
     const phaseIdx = parts.findIndex((p) => tokenRe.test(p));
-    if (phaseIdx >= 0 && phaseIdx + 1 < parts.length && tokenRe.test(parts[phaseIdx + 1])) {
+    if (phaseIdx >= 0 && phaseIdx + 1 < parts.length && planTokenRe.test(parts[phaseIdx + 1])) {
         return `${parts[phaseIdx]}-${parts[phaseIdx + 1]}`;
     }
     return base;
@@ -313,9 +370,21 @@ function cmdFindPhase(cwd, phase, raw) {
                 .filter((e) => e.isDirectory())
                 .map((e) => e.name)
                 .sort((a, b) => comparePhaseNum(a, b));
-            const match = dirs.find((d) => phaseTokenMatches(d, normalized));
-            if (!match)
+            // #2237: fail loud when multiple directories match the same bare phase
+            // number — prevents cross-project file writes when unrelated projects
+            // share a .planning/phases/ tree.
+            const matches = dirs.filter((d) => phaseTokenMatches(d, normalized));
+            if (matches.length === 0)
                 continue;
+            if (matches.length > 1) {
+                output({
+                    ...notFound,
+                    ambiguous_matches: matches,
+                    warning: `Phase ${normalized} is ambiguous: ${matches.length} directories match (${matches.map(m => `"${m}"`).join(', ')}). Set a distinct project_code in .planning/config.json to scope resolution.`,
+                }, raw, '');
+                return;
+            }
+            const match = matches[0];
             const dirMatch = match.match(new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}(${PHASE_NUMBER_TOKEN_SOURCE})-?(.*)`, 'i')) || match.match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE})-?(.*)`, 'i'));
             const phaseNumber = dirMatch ? dirMatch[1] : normalized;
             const phaseName = dirMatch && dirMatch[2] ? dirMatch[2] : null;
@@ -552,6 +621,29 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
         result['warnings'] = warnings;
     output(result, raw);
 }
+// #2390 — phase.add title-shape heuristic. A description at or under this many
+// characters, and with no sentence-ending punctuation followed by more text,
+// reads as a short Title. Anything longer or multi-sentence reads as a Goal,
+// not a Title. phase.add still writes the phase verbatim (it never mangles
+// ROADMAP.md), but when the description looks goal-shaped the JSON result
+// gains a `warning` key naming the gap, so the caller — or the orchestrating
+// add-phase workflow — can split title vs. goal instead of the whole paragraph
+// landing silently in the `### Phase N:` header.
+const PHASE_ADD_TITLE_MAX_LEN = 80;
+const PHASE_ADD_MULTI_SENTENCE_RE = /[.!?]['")\]]?\s+\S/;
+function describeGoalShapedTitle(description) {
+    const trimmed = description.trim();
+    const tooLong = trimmed.length > PHASE_ADD_TITLE_MAX_LEN;
+    const multiSentence = PHASE_ADD_MULTI_SENTENCE_RE.test(trimmed);
+    if (!tooLong && !multiSentence)
+        return null;
+    const reasons = [
+        tooLong ? `${trimmed.length} chars (over the ${PHASE_ADD_TITLE_MAX_LEN}-char title threshold)` : null,
+        multiSentence ? 'multiple sentences' : null,
+    ].filter(Boolean).join(', ');
+    return (`description looks goal-shaped, not title-shaped (${reasons}). It was written verbatim ` +
+        `as the phase title; consider a short title with the detail moved to **Goal:**.`);
+}
 function cmdPhaseAdd(cwd, description, raw, customId) {
     if (!description) {
         error('description required for phase add');
@@ -639,6 +731,7 @@ function cmdPhaseAdd(cwd, description, raw, customId) {
         (0, shell_command_projection_cjs_1.platformWriteSync)(roadmapPath, updatedContent);
         return { newPhaseId: _newPhaseId, dirName: _dirName };
     });
+    const titleWarning = describeGoalShapedTitle(description);
     const result = {
         phase_number: typeof newPhaseId === 'number' ? newPhaseId : String(newPhaseId),
         padded: typeof newPhaseId === 'number' ? String(newPhaseId).padStart(2, '0') : String(newPhaseId),
@@ -647,7 +740,9 @@ function cmdPhaseAdd(cwd, description, raw, customId) {
         directory: toPosixPath(node_path_1.default.join(node_path_1.default.relative(cwd, planningDir(cwd)), 'phases', dirName)),
         naming_mode: config.phase_naming,
     };
-    output(result, raw, result.padded);
+    if (titleWarning)
+        result['warning'] = titleWarning;
+    output(result, raw, result['padded']);
 }
 function cmdPhaseAddBatch(cwd, descriptions, raw) {
     if (!Array.isArray(descriptions) || descriptions.length === 0) {
@@ -760,8 +855,27 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
         const phasesDir = node_path_1.default.join(planningDir(cwd), 'phases');
         const normalizedBase = normalizePhaseName(afterPhase);
         const decimalSet = new Set();
-        try {
-            const entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
+        // #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}${escapeRegex(normalizedBase)}\\.(\\d+)`);
             for (const dir of dirs) {
@@ -770,9 +884,6 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
                     decimalSet.add(parseInt(dm[1], 10));
             }
         }
-        catch {
-            /* intentionally empty */
-        }
         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) {
@@ -940,19 +1051,186 @@ function decrementRoadmapPaddedPhaseNumber(raw, removedInt) {
         return raw;
     return String(num - 1).padStart(raw.length, '0');
 }
+/**
+ * Return the RAW text of the `dataRowIndex`-th data row line (0-based, in
+ * file order — header and delimiter rows excluded) of the FIRST GFM table
+ * found in `sectionText`, or `null` when the table or that row doesn't exist.
+ *
+ * F8 (#2245 review, nit) support helper: addresses a table row by its
+ * STRUCTURAL position rather than by matching its (possibly non-unique)
+ * trimmed cell content — see the Progress-ordinal renumber's padding-recovery
+ * use below for why content-matching is unsafe here (two rows with identical
+ * trimmed Phase text, or a row whose already-rewritten new value coincides
+ * with another row's pre-edit text, would otherwise resolve to the wrong line).
+ */
+function findDataRowLine(sectionText, dataRowIndex) {
+    const lines = sectionText.split(/\r?\n/);
+    let headerIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        if (trimmed.startsWith('|') && trimmed.indexOf('|', 1) !== -1) {
+            headerIdx = i;
+            break;
+        }
+    }
+    if (headerIdx === -1)
+        return null;
+    let seen = -1;
+    for (let i = headerIdx + 2; i < lines.length; i++) {
+        if (!lines[i].trim().startsWith('|'))
+            break;
+        seen += 1;
+        if (seen === dataRowIndex)
+            return lines[i];
+    }
+    return null;
+}
 function updateRoadmapAfterPhaseRemoval(roadmapPath, targetPhase, isDecimal, removedInt, cwd) {
     withPlanningLock(cwd, () => {
         let content = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
         const escaped = escapeRegex(targetPhase);
-        content = content.replace(new RegExp(`\\n?(?<h>#{2,4})\\s*Phase\\s+${escaped}${OPTIONAL_PHASE_TAG_SOURCE}\\s*:[\\s\\S]*?(?=\\n\\k<h>(?!#)\\s+Phase\\s+[^\\n:]+\\s*:|$)`, 'i'), '');
+        // SECTION-DELETION (not a section-body edit) — removes the phase's ENTIRE
+        // detail section INCLUDING its own heading line. Migrated onto deleteSection
+        // (ADR-2143 §4 / markdown-sectionizer T7): it locates the target heading via
+        // tokenizeHeadings + this predicate, then splices out the range from that
+        // heading's own start through the next heading of the SAME-OR-HIGHER level —
+        // whatever that heading's text is. This fixes a data-loss bug in the prior
+        // hand-rolled regex, whose lookahead only recognised ANOTHER "Phase N:"
+        // heading as a stop boundary: removing the LAST phase in a roadmap left no
+        // such heading to stop at, so the lazy `[\s\S]*?` scan ran to EOF and swept
+        // away everything after it — including a trailing `## Progress` heading and
+        // its tracking table.
+        const phaseHeadingRe = new RegExp(`^Phase\\s+${escaped}${OPTIONAL_PHASE_TAG_SOURCE}\\s*:`, 'i');
+        content = (0, markdown_sectionizer_cjs_1.deleteSection)(content, (h) => h.level >= 2 && h.level <= 4 && phaseHeadingRe.test(h.text));
         content = content.replace(new RegExp(`\\n?-\\s*\\[[ x]\\]\\s*.*Phase\\s+${escaped}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s][^\\n]*`, 'gi'), '');
-        content = content.replace(new RegExp(`\\n?\\|\\s*${escaped}\\.?\\s[^|]*\\|[^\\n]*`, 'gi'), '');
+        // ROW-DELETION (not a cell update) — removes the WHOLE Progress-table row
+        // for a removed phase via deleteTableRow (ADR-2143 §7 row-removal sibling
+        // of updateTableCell). Scoped to the `## Progress` section — mirroring
+        // deriveProgressFromRoadmap's read-side scoping (phase-lifecycle.cts) —
+        // so a same-numbered row in an earlier, unrelated table (e.g. a
+        // `| Phase | Requirements | Count |` table preceding `## Progress`,
+        // #2012) is never touched. Matches the row by its FIRST cell only: for an
+        // integer removal, a zero-pad-insensitive leading-integer comparison
+        // (`01.`, `1.`, `1 `, bare `1` all match phase 1; a decimal sub-phase
+        // cell like `2.5` never matches an integer removal); for a decimal
+        // removal, the exact decimal token. This replaces the prior regex's
+        // `\.?\s` requirement, which silently left a COMPACT unpadded row (e.g.
+        // `|2|0/2|Planned|-|`) undeleted — its closing `|` follows the digit with
+        // no whitespace to match (#2245 audit) — and which was also unscoped to
+        // any particular table.
+        const progressHeadingMatch = content.match(/^##[ \t]+Progress\b/im);
+        if (progressHeadingMatch && progressHeadingMatch.index !== undefined) {
+            const headingOffset = progressHeadingMatch.index;
+            const before = content.slice(0, headingOffset);
+            const fromHeading = content.slice(headingOffset);
+            const nextHeadingOffset = fromHeading.search(/\n#{1,2}[ \t]/);
+            const progressSection = nextHeadingOffset >= 0 ? fromHeading.slice(0, nextHeadingOffset) : fromHeading;
+            const rest = nextHeadingOffset >= 0 ? fromHeading.slice(nextHeadingOffset) : '';
+            const matchRemovedProgressRow = (row) => {
+                const firstCellRaw = (Object.values(row)[0] ?? '').trim();
+                if (isDecimal) {
+                    return new RegExp(`^${escaped}\\.?(?:\\s|$)`, 'i').test(firstCellRaw);
+                }
+                const leadingMatch = firstCellRaw.match(/^0*(\d+)(\.\d+)?/);
+                if (!leadingMatch || leadingMatch[2])
+                    return false;
+                return parseInt(leadingMatch[1], 10) === removedInt;
+            };
+            const deleteResult = (0, markdown_table_cjs_1.deleteTableRow)(progressSection, matchRemovedProgressRow);
+            if (deleteResult.ok) {
+                content = before + deleteResult.value + rest;
+            }
+        }
         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*\([^)\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}`);
-            content = content.replace(/(\|\s*)(\d+)(\.\s)/g, (_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
+            // directly above). The prior whole-document regex
+            // `/(\|\s*)(\d+)(\.\s)/g` rewrote ANY `| N. ` cell anywhere in the
+            // file — including a same-shaped cell in an UNRELATED, earlier table
+            // (e.g. a `| Phase | Requirements | Count |` table, or a decoy table,
+            // preceding `## Progress`; #2245-class scoping defect, same family as
+            // the row-delete fix above). Scoped here to the `## Progress` section
+            // only, mirroring that same section-slice-then-splice-back pattern.
+            //
+            // Loops because updateTableCell only rewrites the FIRST matching row
+            // per call. `processedOrdinalRows` tracks by row INDEX (stable across
+            // iterations — this only edits cell content, it never inserts/deletes
+            // rows) so an already-decremented row's new value — which may still
+            // numerically exceed `removedInt` — is never re-selected and
+            // decremented a second time (matching on the row's CURRENT value alone,
+            // without this guard, would keep re-firing on each pass).
+            //
+            // `phaseCellShapeRe` is the exact digit+dot-space shape the old regex
+            // required: a decimal sub-phase ordinal like `2.5` (no whitespace
+            // between the dot and the next character) never matches it, so it is
+            // left untouched — identical decimal-safety to the prior behaviour.
+            //
+            // updateTableCell hands the callback the TRIMMED, UNESCAPED cell value
+            // only, so the row's original leading/trailing alignment padding is
+            // recovered by a narrow, anchored lookup within that row's OWN raw
+            // line — addressed by ROW INDEX (`matchedRowIndex`, via
+            // `findDataRowLine`), not by searching the whole section for content
+            // matching the trimmed value (F8 #2245 review: two rows with identical
+            // trimmed Phase text, or a row whose already-rewritten new value
+            // coincides with another row's pre-edit text, would otherwise resolve
+            // to the WRONG row's padding — the first/leftmost content match found).
+            // The lookup searches for `escapeCell(current)` (F3 #2245 review: the
+            // ESCAPED form, e.g. `Foo \| Bar`) — the raw line always carries the
+            // escaped form, so searching for the unescaped `current` would
+            // silently fail to find an escaped-pipe cell's own line — preserving
+            // every other byte of the row (ADR-2143 §7 byte-parity) while only the
+            // digits actually change.
+            const ordinalHeadingMatch = content.match(/^##[ \t]+Progress\b/im);
+            if (ordinalHeadingMatch && ordinalHeadingMatch.index !== undefined) {
+                const ordinalHeadingOffset = ordinalHeadingMatch.index;
+                const ordinalBefore = content.slice(0, ordinalHeadingOffset);
+                const ordinalFromHeading = content.slice(ordinalHeadingOffset);
+                const ordinalNextHeadingOffset = ordinalFromHeading.search(/\n#{1,2}[ \t]/);
+                let ordinalSection = ordinalNextHeadingOffset >= 0
+                    ? ordinalFromHeading.slice(0, ordinalNextHeadingOffset)
+                    : ordinalFromHeading;
+                const ordinalRest = ordinalNextHeadingOffset >= 0 ? ordinalFromHeading.slice(ordinalNextHeadingOffset) : '';
+                const phaseCellShapeRe = /^(\d+)(\.\s)/;
+                const processedOrdinalRows = new Set();
+                let matchedRowIndex = null;
+                for (;;) {
+                    matchedRowIndex = null;
+                    const cellResult = (0, markdown_table_cjs_1.updateTableCell)(ordinalSection, (row, index) => {
+                        if (processedOrdinalRows.has(index))
+                            return false;
+                        const m = phaseCellShapeRe.exec(row['Phase'] ?? '');
+                        if (!m)
+                            return false;
+                        const num = parseInt(m[1], 10);
+                        if (!Number.isInteger(num) || num <= removedInt || num === 999)
+                            return false;
+                        processedOrdinalRows.add(index);
+                        matchedRowIndex = index;
+                        return true;
+                    }, 'Phase', (current) => {
+                        const m = phaseCellShapeRe.exec(current);
+                        if (!m)
+                            return current;
+                        const decremented = decrementRoadmapPhaseNumber(m[1], removedInt);
+                        const newContent = `${decremented}${m[2]}${current.slice(m[0].length)}`;
+                        const targetLine = matchedRowIndex === null ? null : findDataRowLine(ordinalSection, matchedRowIndex);
+                        const padMatch = targetLine
+                            ? new RegExp(`^[ \\t]*\\|(\\s*)${escapeRegex((0, markdown_table_cjs_1.escapeCell)(current))}(\\s*)\\|`).exec(targetLine)
+                            : null;
+                        const leadPad = padMatch ? padMatch[1] : ' ';
+                        const trailPad = padMatch ? padMatch[2] : ' ';
+                        return `${leadPad}${(0, markdown_table_cjs_1.escapeCell)(newContent)}${trailPad}`;
+                    });
+                    if (!cellResult.ok)
+                        break;
+                    ordinalSection = cellResult.value;
+                }
+                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)}`);
@@ -990,8 +1268,18 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
         renamedDirs = renamed.renamedDirs;
         renamedFiles = renamed.renamedFiles;
     }
-    catch {
-        /* intentionally empty */
+    catch (e) {
+        // #2245 audit (was ERROR-HIDING): renameDecimalPhases/renameIntegerPhases
+        // rename subsequent phase directories ON DISK one at a time — a mid-loop
+        // failure leaves SOME directories already renumbered and others not, with
+        // no way to recover which (the callee's own renamedDirs/renamedFiles never
+        // reach this scope when it throws). Silently swallowing this and falling
+        // through to updateRoadmapAfterPhaseRemoval below used to rewrite
+        // ROADMAP.md's phase numbers assuming the ENTIRE renumbering succeeded,
+        // permanently desyncing ROADMAP.md from the actual (partially-renamed)
+        // on-disk directory names. Surface loud instead of compounding it.
+        const msg = e instanceof Error ? e.message : String(e);
+        error(`Failed to renumber phase directories after removing phase ${targetPhase}: ${msg}`);
     }
     updateRoadmapAfterPhaseRemoval(roadmapPath, targetPhase, isDecimal, parseInt(normalized, 10), cwd);
     const statePath = node_path_1.default.join(planningDir(cwd), 'STATE.md');
@@ -1085,7 +1373,7 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
     const roadmapPath = node_path_1.default.join(planningDir(cwd), 'ROADMAP.md');
     const statePath = node_path_1.default.join(planningDir(cwd), 'STATE.md');
     const phasesDir = node_path_1.default.join(planningDir(cwd), 'phases');
-    const today = clock_cjs_1.realClock.today();
+    const today = clock_cjs_1.realClock.localToday();
     const phaseInfoRaw = findPhaseInternal(cwd, phaseNum);
     if (!phaseInfoRaw) {
         error(`Phase ${phaseNum} not found`);
@@ -1130,7 +1418,11 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
         }
     }
     catch {
-        /* intentionally empty */
+        /* best-effort (#2245 audit): this is an ADVISORY pre-scan of UAT/
+         * VERIFICATION files for `warnings` in the phase-complete output — the
+         * actual completion GATE is readVerificationStatus below (a separate
+         * mechanism). A readdirSync/readFileSync failure here just means fewer
+         * warnings are surfaced this run, not a blocked or corrupted completion. */
     }
     let nextPhaseNum = null;
     let nextPhaseName = null;
@@ -1153,50 +1445,143 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                 // so completing an already-checked phase (idempotent re-run) checked the
                 // wrong phase's box. Mirrors the tight pattern used by phase-insert
                 // (`]\\s*(?:\\*\\*)?Phase`).
-                const checkboxPattern = new RegExp(`(-\\s*\\[)[ ](\\]\\s*(?:\\*\\*)?\\s*Phase\\s+${phaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s][^\\n]*)`, 'i');
-                roadmapContent = roadmapContent.replace(checkboxPattern, `$1x$2 (completed ${today})`);
-                const tableRowPattern = new RegExp(`^(\\|\\s*${phaseEscaped}\\.?\\s[^|]*(?:\\|[^\\n]*))$`, 'im');
-                // Scope the Progress-row search to the ## Progress section so the regex
-                // doesn't bind to an earlier table (e.g. | Phase | Requirements | Count |)
-                // whose rows also start with the phase number. (#2012)
-                const updateProgressRow = (fullRow) => {
-                    const cells = fullRow.split('|').slice(1, -1);
-                    const dateShape = /^\d{4}-\d{2}-\d{2}$/;
-                    if (cells.length === 5) {
-                        cells[2] = ` ${summaryCount}/${planCount} `;
-                        cells[3] = ' Complete    ';
-                        // Preserve only a valid ISO date (#1161: idempotent; self-heal garbage)
-                        const existingDate5 = cells[4].trim();
-                        cells[4] = dateShape.test(existingDate5) ? cells[4] : ` ${today} `;
-                    }
-                    else if (cells.length === 4) {
-                        cells[1] = ` ${summaryCount}/${planCount} `;
-                        cells[2] = ' Complete    ';
-                        // Preserve only a valid ISO date (#1161: idempotent; self-heal garbage)
-                        const existingDate4 = cells[3].trim();
-                        cells[3] = dateShape.test(existingDate4) ? cells[3] : ` ${today} `;
+                // #2067/#2200: line-anchored (^, optional leading indent) so an
+                // inline / backticked prose literal cannot match. Milestone-scoped below
+                // (mutateMilestonePhase) so a Backlog entry or a same-numbered shipped-
+                // milestone phase cannot be flipped either.
+                // ADR-2143 §4 note / #2245 audit: this is the phase-LIST checkbox — it
+                // lives in the milestone's `- [ ] Phase N: …` checklist, OUTSIDE any
+                // `### Phase N` detail section, so there is no section for
+                // withPhaseSection to bind to. Migrated onto the sectionizer's
+                // `updateBullet` bullet-write seam: the pattern itself is unchanged,
+                // only the "find the right line, splice it back" plumbing moved off a
+                // 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
+                // withPhaseSection instead.
+                //
+                // #2245 review Fix 6: this is behaviour-preserving for GSD-GENERATED
+                // inputs (the only shape ROADMAP.md ever actually has), NOT byte-parity
+                // across every conceivable input. `updateBullet` is fence-aware — a
+                // checkbox-shaped line inside a fenced (``` / ~~~) code block is never
+                // offered to `match`/`transform` — whereas the retired whole-slice
+                // `.replace()` had no such fence tracking and would have flipped a
+                // bullet-shaped line inside a fence too. That divergence has no live
+                // bug because a GSD-authored ROADMAP.md milestone checklist never puts
+                // its own `- [ ] Phase N: …` entries inside a fenced code block, but it
+                // is a real (and correct) behavioural difference on pathological input.
+                const checkboxPattern = new RegExp(`^[ \\t]*(-\\s*\\[)[ ](\\]\\s*(?:\\*\\*)?\\s*Phase\\s+${phaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s][^\\n]*)`, 'i');
+                // Progress table row: update Plans Complete/Status/Completed columns BY
+                // COLUMN NAME (handles 4- or 5-column RoadmapProgress tables) via the
+                // markdown-table seam (ADR-2143 §7) — supersedes the prior ordinal
+                // cells[]-index regex. Applied inside mutateMilestonePhase below (per
+                // milestone window), further scoped to the ## Progress heading within
+                // that window so the row lookup doesn't bind to an earlier table (e.g.
+                // | Phase | Requirements | Count |) whose rows also start with the
+                // phase number (#2012).
+                // #2245 Blocker 4: optional dot must be followed by whitespace-or-end,
+                // not dot-OR-whitespace-OR-end as alternatives — the prior form let a
+                // bare "." satisfy the whole lookahead, so completing phase "2"
+                // over-matched a decimal sub-phase row like "2.5 Extra". Matches "2",
+                // "2.", "2 Alpha"; rejects "2.5 Extra".
+                const phaseCellRe = new RegExp(`^${phaseEscaped}\\.?(?:\\s|$)`, 'i');
+                const rowMatch = (row) => phaseCellRe.test((row['Phase'] ?? '').trim());
+                const dateShape = /^\d{4}-\d{2}-\d{2}$/;
+                /**
+                 * Within `text` (already scoped to one milestone window by the
+                 * caller), scope further to the `## Progress` heading section (up to
+                 * the next `#`/`##` heading) when present, run `edit` against just
+                 * that slice, and splice the result back — falling back to the whole
+                 * `text` when no `## Progress` heading exists (mirrors phase-
+                 * lifecycle.cjs's deriveProgressFromRoadmap read-side scoping).
+                 */
+                const editProgressHeadingSlice = (text, edit) => {
+                    const progressMatch = text.match(/^##[ \t]+Progress\b/im);
+                    if (!progressMatch || progressMatch.index === undefined) {
+                        return edit(text);
                     }
-                    return '|' + cells.join('|') + '|';
+                    const headingOffset = progressMatch.index;
+                    const beforeHeading = text.slice(0, headingOffset);
+                    const fromHeading = text.slice(headingOffset);
+                    const nextHeading = fromHeading.search(/\n#{1,2}[ \t]/);
+                    const scoped = nextHeading >= 0 ? fromHeading.slice(0, nextHeading) : fromHeading;
+                    const after = nextHeading >= 0 ? fromHeading.slice(nextHeading) : '';
+                    return beforeHeading + edit(scoped) + after;
                 };
-                const progressIdx = roadmapContent.indexOf('## Progress');
-                if (progressIdx >= 0) {
-                    const beforeProgress = roadmapContent.slice(0, progressIdx);
-                    const progressSection = roadmapContent.slice(progressIdx);
-                    roadmapContent = beforeProgress + progressSection.replace(tableRowPattern, updateProgressRow);
+                // 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;
+                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)
+                // (primary section + optional Phase Details section). A bullet/heading in
+                // a shipped milestone, a Backlog section, or a backticked prose literal is
+                // outside the window and stays untouched. With no versioned active
+                // milestone, fall back to whole-content mutation (prior behaviour).
+                const mutateMilestonePhase = (slice) => {
+                    let s = slice;
+                    s = (0, markdown_sectionizer_cjs_1.updateBullet)(s, (_bulletText, rawLine) => checkboxPattern.test(rawLine), (rawLine) => rawLine.replace(checkboxPattern, `$1x$2 (completed ${today})`));
+                    s = editProgressHeadingSlice(s, (scoped) => {
+                        let text = scoped;
+                        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    ');
+                        if (statusResult.ok)
+                            text = statusResult.value;
+                        // Preserve only a valid ISO date (#1161: idempotent; self-heal
+                        // garbage). Ragged-tolerant (#2245 Blocker 2): decide via the
+                        // CURRENT Completed cell inside a single updateTableCell callback
+                        // (its own tolerant row scan) rather than gating on
+                        // findTableWithColumns (which requires the WHOLE table to parse —
+                        // a ragged SIBLING row elsewhere used to silently no-op this
+                        // row's date stamp too).
+                        const completedResult = (0, markdown_table_cjs_1.updateTableCell)(text, rowMatch, 'Completed', (current) => dateShape.test(current.trim()) ? current : ` ${today} `);
+                        if (completedResult.ok)
+                            text = completedResult.value;
+                        return text;
+                    });
+                    // ADR-2143 §4: the plan-count write and the per-plan checkbox flips
+                    // are both scoped to phase N's OWN detail section via
+                    // withPhaseSection — the edit callback below only ever sees that
+                    // 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`);
+                        for (const summaryFile of phaseInfoSummaries) {
+                            const planId = summaryFile.replace('-SUMMARY.md', '').replace('SUMMARY.md', '');
+                            if (!planId)
+                                continue;
+                            const planEscaped = escapeRegex(planId);
+                            const planCheckboxPattern = new RegExp(`(-\\s*\\[) (\\]\\s*(?:\\*\\*)?${planEscaped}(?:\\*\\*)?)`, 'i');
+                            b = b.replace(planCheckboxPattern, '$1x$2');
+                        }
+                        return b;
+                    });
+                    return s;
+                };
+                const milestoneRanges = currentMilestoneRawRanges(roadmapContent, cwd);
+                if (milestoneRanges) {
+                    // Splice later windows first so an earlier window's offsets are not
+                    // shifted by a length-changing mutation in a later window.
+                    const windows = [milestoneRanges.details, milestoneRanges.primary]
+                        .filter((w) => w !== null)
+                        .sort((a, b) => b.start - a.start);
+                    for (const w of windows) {
+                        roadmapContent =
+                            roadmapContent.slice(0, w.start)
+                                + mutateMilestonePhase(roadmapContent.slice(w.start, w.end))
+                                + roadmapContent.slice(w.end);
+                    }
                 }
                 else {
-                    roadmapContent = roadmapContent.replace(tableRowPattern, updateProgressRow);
-                }
-                const planCountPattern = new RegExp(`(#{2,4}\\s*Phase\\s+${phaseEscaped}(?:(?!\\n#{1,4}\\s)[\\s\\S])*?\\*\\*Plans:\\*\\*\\s*)[^\\n]+`, 'i');
-                roadmapContent = roadmapContent.replace(planCountPattern, `$1${summaryCount}/${planCount} plans complete`);
-                const phaseInfoSummaries = phaseInfo['summaries'];
-                for (const summaryFile of phaseInfoSummaries) {
-                    const planId = summaryFile.replace('-SUMMARY.md', '').replace('SUMMARY.md', '');
-                    if (!planId)
-                        continue;
-                    const planEscaped = escapeRegex(planId);
-                    const planCheckboxPattern = new RegExp(`(-\\s*\\[) (\\]\\s*(?:\\*\\*)?${planEscaped}(?:\\*\\*)?)`, 'i');
-                    roadmapContent = (roadmapContent).replace(planCheckboxPattern, '$1x$2');
+                    roadmapContent = mutateMilestonePhase(roadmapContent);
                 }
                 writes.push({
                     filePath: roadmapPath,
@@ -1212,22 +1597,74 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                     const reqMatch = sectionText.match(/\*\*Requirements:?\*\*[^\S\n]*:?[^\S\n]*([^\n]+)/i);
                     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
+                    // 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
+                    // real REQ-ID, so it is filtered out wherever a cited-ID list feeds
+                    // a warning (#2316-7 boundary).
+                    const isPlaceholderReqId = (id) => id.toUpperCase() === 'TBD';
+                    let citedReqIds = [];
+                    // #2316-1: Traceability-row writes that matched NO row (ghost or
+                    // otherwise) — the `if (reqUpdate.ok)` below previously had no
+                    // `else`, discarding this fact silently instead of surfacing it.
+                    const traceabilityWriteMisses = [];
                     if (reqMatch) {
-                        const reqIds = reqMatch[1]
+                        // #2334 HIGH 3: filter the tokenized capture to the REQ-ID SHAPE —
+                        // the SAME shape bodyReqIds (`\*\*([A-Z][A-Z0-9]*-\d+)\*\*`, below)
+                        // and tableReqIds (`([A-Z][A-Z0-9]*-\d+)`, below) already require —
+                        // so the ghost-ID / unregistered comparisons stay shape-symmetric.
+                        // Without this, `[^\n]+` split on `[,\s]+` turned EVERY word after
+                        // the ID list into a "cited REQ-ID": the shipped
+                        // `templates/roadmap.md:32` line
+                        // `**Requirements**: [REQ-01, REQ-02]  <!-- brackets optional, ... -->`
+                        // warned to register `<!--`, `brackets`, `optional`, `-->`, etc., and
+                        // `**Requirements:** None` warned to register the literal word
+                        // `None`. This subsumes the `TBD` placeholder special-case (`TBD`
+                        // does not match the REQ-ID shape either); `isPlaceholderReqId` is
+                        // kept below as a defensive no-op for any caller that still hands
+                        // it a raw token.
+                        const REQ_ID_SHAPE_RE = /^[A-Z][A-Z0-9]*-\d+$/i;
+                        citedReqIds = reqMatch[1]
                             .replace(/[\[\]]/g, '')
                             .split(/[,\s]+/)
                             .map((r) => r.trim())
-                            .filter(Boolean);
-                        for (const reqId of reqIds) {
+                            .filter(Boolean)
+                            .filter((r) => REQ_ID_SHAPE_RE.test(r));
+                        for (const reqId of citedReqIds) {
                             const reqEscaped = escapeRegex(reqId);
                             reqContent = reqContent.replace(new RegExp(`(-\\s*\\[)[ ](\\]\\s*\\*\\*${reqEscaped}\\*\\*)`, 'gi'), '$1x$2');
-                            reqContent = reqContent.replace(new RegExp(`(\\|\\s*${reqEscaped}\\s*\\|[^|]+\\|)\\s*(?:Pending|In Progress)\\s*(\\|)`, 'gi'), '$1 Complete $2');
+                            // Traceability row: | <REQ-ID> | Phase N | Pending|In Progress | ->
+                            // ... Complete | via the markdown-table seam (ADR-2143 §7). Match the
+                            // row by its FIRST cell's value (the requirement-ID column) regardless
+                            // of that column's HEADER name — real tables head it `REQ-ID`, others
+                            // `Requirement` (#2769/#2203); this mirrors the prior regex's first-cell
+                            // `\|\s*<id>\s*\|` anchor, not a by-name lookup. Object.values(row) is in
+                            // header order, so [0] is the first column. Case-insensitive.
+                            const reqRowMatch = (row) => (Object.values(row)[0] ?? '').trim().toLowerCase() === reqId.toLowerCase();
+                            // Ragged-tolerant (#2245 Blocker 2): drive the write purely off
+                            // updateTableCell's own tolerant row scan — a DIFFERENT
+                            // requirement's row elsewhere in the same table having a
+                            // mismatched cell count must never silently no-op THIS
+                            // requirement's write. The "only flip Pending/In Progress ->
+                            // Complete" gate is folded into the newValue callback so one
+                            // updateTableCell call both probes and writes.
+                            const reqUpdate = updateTraceabilityCell(reqContent, reqRowMatch, 'Status', (current) => /^(?:pending|in progress)$/i.test(current.trim()) ? ' Complete ' : current);
+                            if (reqUpdate.ok) {
+                                reqContent = reqUpdate.value;
+                            }
+                            else if (!isPlaceholderReqId(reqId)) {
+                                traceabilityWriteMisses.push(reqId);
+                            }
                         }
                     }
                     // #1159 (Defect B): collect requirement IDs only from ACTIVE sections.
                     // Requirements under headings whose text contains "deferred", "backlog",
-                    // "future", or "v2" (case-insensitive) are explicitly out of current scope
-                    // and must not be flagged as missing from the Traceability table.
+                    // "future", or an OFF-milestone `v<N>` (case-insensitive) are explicitly
+                    // out of current scope and must not be flagged as missing from the
+                    // Traceability table.
                     //
                     // Strategy: walk lines, track heading depth, and toggle a "deferred" flag
                     // when a heading matching the pattern is encountered.  A sub-heading (higher
@@ -1235,7 +1672,47 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                     // opens a same-or-shallower heading that does NOT match the pattern.
                     // Lines inside fenced code blocks (``` or ~~~) are treated as content, not
                     // headings, to avoid false deferred-section detection from code examples.
-                    const DEFERRED_HEADING_RE = /\b(?:deferred|backlog|future|v\d+)\b/i;
+                    //
+                    // #2334 BLOCKER fix (regresses closed bug #1159 against GSD's OWN
+                    // shipped template): #2316-4a dropped the bare `v\d+` alternative
+                    // entirely to stop it over-matching an ACTIVE heading like "## v1
+                    // Requirements" — but the shipped `templates/requirements.md:35`
+                    // scaffold ships `## v2 Requirements` / "Deferred to future release"
+                    // as its ONLY deferred marker, and `v\d+` was the ONLY alternative
+                    // that ever matched a bare version heading (the deferred-ness lives
+                    // in body prose, not the heading text). Dropping it regressed #1159
+                    // for every project scaffolded from the shipped template.
+                    //
+                    // Fix: make the `v<N>` alternative MILESTONE-AWARE instead of
+                    // deleting it. A `## v<N> ...` heading is deferred ONLY when `<N>`
+                    // (MAJOR version only — "v1" vs milestone "v1.3" is the SAME major
+                    // version) does not match the CURRENT milestone's major version,
+                    // resolved via `stateExtractField` against STATE.md's `milestone:`
+                    // frontmatter field (the same seam `getMilestoneInfo`/state.cts's
+                    // frontmatter builder already use — no bespoke frontmatter parsing).
+                    // "## v1 Requirements" while the milestone is v1.x is the ACTIVE
+                    // milestone's own section (#2316's original ask) and must NOT be
+                    // swallowed; "## v2 Requirements" while the milestone is v1.x is a
+                    // genuinely future milestone (#1159's ask, and the literal shipped-
+                    // template shape) and MUST stay suppressed. `deferred`/`backlog`/
+                    // `future` are unaffected by milestone resolution — a genuinely
+                    // deferred heading always spells one of those words too (see
+                    // #2316-5 regression guard: "## Deferred v2 Requirements", "##
+                    // Future Backlog", "## Deferred", "## Backlog", "## Future").
+                    //
+                    // Fail-safe: when the milestone version cannot be resolved at all
+                    // (no STATE.md, or no `milestone:` field), fall back to the OLD
+                    // pre-#2316-4a behavior and treat every `v\d+` heading as deferred.
+                    // A false "deferred" here only ever SUPPRESSES a warning — strictly
+                    // safer than spamming a warning on every v\d+-headed scaffold when
+                    // we cannot tell whether it names the active milestone.
+                    const DEFERRED_KEYWORD_RE = /\b(?:deferred|backlog|future)\b/i;
+                    const HEADING_VERSION_RE = /\bv(\d+)(?:\.\d+)*\b/i;
+                    const stateRawForMilestone = node_fs_1.default.existsSync(statePath) ? node_fs_1.default.readFileSync(statePath, 'utf-8') : null;
+                    const currentMilestoneRaw = stateRawForMilestone
+                        ? stateExtractField(stateRawForMilestone, 'milestone')
+                        : null;
+                    const currentMilestoneMajor = currentMilestoneRaw ? extractMajorVersion(currentMilestoneRaw) : null;
                     const bodyReqIds = [];
                     // deferredDepth: the heading level that opened the current deferred block,
                     // or 0 when we are in an active section.
@@ -1259,11 +1736,21 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                             }
                             // Heading at same level or shallower than current deferred opener,
                             // or no active deferred block yet.
-                            if (DEFERRED_HEADING_RE.test(text)) {
+                            if (DEFERRED_KEYWORD_RE.test(text)) {
                                 deferredDepth = depth; // enter a deferred block
                             }
                             else {
-                                deferredDepth = 0; // back in an active section
+                                const versionMatch = text.match(HEADING_VERSION_RE);
+                                if (versionMatch) {
+                                    const headingMajor = versionMatch[1];
+                                    deferredDepth =
+                                        currentMilestoneMajor === null || headingMajor !== currentMilestoneMajor
+                                            ? depth // unresolved milestone (fail-safe) or off-milestone version -> deferred
+                                            : 0; // same major version as the current milestone -> active
+                                }
+                                else {
+                                    deferredDepth = 0; // back in an active section
+                                }
                             }
                             continue;
                         }
@@ -1283,7 +1770,11 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                         ? reqContent.slice(traceabilityHeadingMatch.index)
                         : '';
                     const tableReqIds = new Set();
-                    const tableRowPat = /^\|\s*([A-Z][A-Z0-9]*-\d+)\s*\|/gm;
+                    // #2203: match REQ-IDs in any pipe-delimited cell (not just the first
+                    // column) so a traceability table that leads with a status column (e.g.
+                    // | ☐ | REQ-01 | …) is parsed correctly instead of reporting every row
+                    // as missing.
+                    const tableRowPat = /\|\s*([A-Z][A-Z0-9]*-\d+)\s*\|/g;
                     let tableMatch;
                     while ((tableMatch = tableRowPat.exec(traceabilitySection)) !== null) {
                         tableReqIds.add(tableMatch[1]);
@@ -1292,8 +1783,68 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                     if (unregistered.length > 0) {
                         warnings.push(`REQUIREMENTS.md: ${unregistered.length} REQ-ID(s) found in body but missing from Traceability table: ${unregistered.join(', ')} — add them manually to keep traceability in sync`);
                     }
+                    // #2316-1: ghost REQ-IDs — cited by ROADMAP's own **Requirements:**
+                    // line for this phase, but registered NOWHERE in REQUIREMENTS.md
+                    // (neither its body nor its Traceability table). The `unregistered`
+                    // check above only ever compares REQUIREMENTS.md's own body against
+                    // its own Traceability table; it never consults `citedReqIds`, so an
+                    // ID that ROADMAP cites but REQUIREMENTS.md never defines at all was
+                    // previously invisible to every guard. `TBD` (the phase.add/-batch/
+                    // -insert placeholder) is excluded — see #2316-7 boundary.
+                    //
+                    // #2334 HIGH 2: classify "ghost" by PROBING THE ACTUAL WRITE
+                    // SURFACES this same function just wrote to (:1947 checkbox,
+                    // :1967 Traceability row) — case-insensitively — mirroring
+                    // milestone.cts's `notFound`/`hasRow`/`doneCheckbox` classification
+                    // (src/milestone.cts:117-141,209-215), instead of set-differencing
+                    // `bodyReqIds` (deferred-filtered, case-sensitive, bold-only) and
+                    // `tableReqIds` (case-sensitive) against `citedReqIds`. Those two
+                    // indexes can disagree with the writes: an ID under a `##
+                    // Deferred` heading gets its checkbox ticked by the write loop
+                    // above but is deliberately EXCLUDED from `bodyReqIds` by the
+                    // deferred-heading filter (#1159), so the old set-diff reported it
+                    // as an unregistered ghost in the SAME response that just ticked
+                    // its checkbox; a case-mismatched citation (`known-01` vs
+                    // `**KNOWN-01**`) lands its write via the writes' case-insensitive
+                    // regexes but failed the old set-diff's case-SENSITIVE
+                    // `Array.includes`/`Set.has`. An ID whose checkbox OR Traceability
+                    // row actually matched is registered — not a ghost — regardless of
+                    // which section (deferred or not) it lives under.
+                    const reqIsRegisteredAnywhere = (id) => {
+                        const reqEscaped = escapeRegex(id);
+                        // Surface 1 — checkbox, EITHER state (`[ ]` or `[x]`), case-
+                        // insensitive: existence check, not the write's space-only match.
+                        if (new RegExp(`-\\s*\\[[ xX]\\]\\s*\\*\\*${reqEscaped}\\*\\*`, 'i').test(reqContent)) {
+                            return true;
+                        }
+                        // Surface 2 — Traceability row exists at all (any Status value),
+                        // via the SAME no-op-probe-through-updateTraceabilityCell
+                        // technique milestone.cts's `hasRow` uses (:210-214): a case-
+                        // insensitive first-cell match, regardless of current Status.
+                        const rowProbeMatch = (row) => (Object.values(row)[0] ?? '').trim().toLowerCase() === id.toLowerCase();
+                        return updateTraceabilityCell(reqContent, rowProbeMatch, 'Status', (current) => current).ok;
+                    };
+                    const ghostReqIds = citedReqIds.filter((id) => !isPlaceholderReqId(id) && !reqIsRegisteredAnywhere(id));
+                    if (ghostReqIds.length > 0) {
+                        warnings.push(`ROADMAP Phase ${phaseNum} cites REQ-ID(s) not registered anywhere in REQUIREMENTS.md (neither body nor Traceability table): ${ghostReqIds.join(', ')} — add them to REQUIREMENTS.md or correct the ROADMAP citation`);
+                    }
+                    // #2316-1 cont.: a cited ID whose Traceability-row write matched no
+                    // row for a reason OTHER than being a ghost (e.g. a malformed table)
+                    // still deserves a warning instead of a silent discard — but skip
+                    // IDs already reported above as ghosts to avoid a duplicate message
+                    // for the same root cause.
+                    const traceabilityWriteFailures = traceabilityWriteMisses.filter((id) => !ghostReqIds.includes(id));
+                    if (traceabilityWriteFailures.length > 0) {
+                        warnings.push(`REQUIREMENTS.md: Traceability row write skipped for REQ-ID(s) cited by ROADMAP (no matching row found): ${traceabilityWriteFailures.join(', ')}`);
+                    }
                     writes.push({ filePath: reqPath, before: originalReqContent, after: reqContent });
-                    requirementsUpdated = true;
+                    // #2316-3: `requirements_updated` must reflect whether REQUIREMENTS.md
+                    // content actually CHANGED, not merely that the file existed in the
+                    // transaction — mirrors the `writes.push({filePath,before,after})`
+                    // diff-tracking pattern used for the ROADMAP write above. A phase
+                    // whose citations match nothing (ghost REQ-IDs only) must report
+                    // `false`, not a bare "the file was present" `true`.
+                    requirementsUpdated = reqContent !== originalReqContent;
                 }
             }
             try {
@@ -1319,7 +1870,13 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                 }
             }
             catch {
-                /* intentionally empty */
+                /* best-effort (#2245 audit): stage 1 of a deliberate 3-stage
+                 * cascading fallback for locating the next phase (disk dirs → roadmap
+                 * headings/checkboxes → lowest-outstanding-checkbox override, #2028
+                 * below). A disk-scan failure here is indistinguishable from "found
+                 * nothing on disk" and correctly falls through to stage 2, which
+                 * derives the same information independently from ROADMAP.md content
+                 * — not a silent data-loss path. */
             }
             if (isLastPhase && roadmapContent !== null) {
                 try {
@@ -1355,10 +1912,13 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                     }
                 }
                 catch {
-                    /* intentionally empty */
+                    /* best-effort (#2245 audit): stage 2 of the next-phase cascade
+                     * (see stage 1's comment above) — a failure here just leaves
+                     * isLastPhase as stage 1 left it; stage 3 (#2028) below runs next
+                     * regardless and provides a further, independent override. */
                 }
             }
-            // #2028: don't stamp "Milestone complete" when a LOWER-numbered phase is
+            // #2028: don't stamp "All phases complete" when a LOWER-numbered phase is
             // still outstanding. The two blocks above only clear isLastPhase when a
             // HIGHER-numbered phase exists, so completing the numerically-highest phase
             // out of order (e.g. Phase 10 before Phase 9) wrongly read as milestone-end.
@@ -1396,7 +1956,11 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                     }
                 }
                 catch {
-                    /* intentionally empty */
+                    /* best-effort (#2245 audit): stage 3 (#2028) of the next-phase
+                     * cascade — a failure here simply leaves isLastPhase/nextPhaseNum
+                     * as stages 1-2 already determined them; this stage only ever
+                     * overrides toward "not last" when it finds a genuinely lower
+                     * outstanding phase, never the reverse. */
                 }
             }
             if (node_fs_1.default.existsSync(statePath)) {