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

package/gsd-core/bin/lib/plan-scan.cjs

@@ -12,14 +12,69 @@ const node_path_1 = require("node:path");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const coreUtils = require("./core-utils.cjs");
 const { countMatchedSummaries } = coreUtils;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const frontmatterMod = require("./frontmatter.cjs");
+const { extractFrontmatter } = frontmatterMod;
 // Excluded derivative files
 const PLAN_OUTLINE_RE = /-OUTLINE\.md$/i;
 const PLAN_PRE_BOUNCE_RE = /\.pre-bounce\.md$/i;
+const PLAN_REVIEW_RE = /-PLAN-REVIEW\.md$/i;
+// #2349: a plan's frontmatter always sits at byte 0 and closes well before the
+// body, so only a bounded prefix is ever needed to read the `status` marker.
+// Capping the read keeps scanPhasePlans — which loops over every phase directory
+// on hot paths (state sync/validate, roadmap progress) — from slurping a
+// pathologically large committed plan file into memory just to inspect one key.
+const PLAN_FRONTMATTER_READ_CAP = 64 * 1024;
+/**
+ * #2349: a plan whose frontmatter declares `status: superseded` was deliberately
+ * reassigned or never executed — its work moved to a later plan, so it can never
+ * gain a matching `*-SUMMARY.md`. Like a retired phase (#1514, one level up), such
+ * a plan must be excluded from BOTH the plan and summary counts; otherwise a phase
+ * with a deliberately-unexecuted plan reads `completed: false` forever, pinning the
+ * milestone below 100%. Reading only the frontmatter `status` key is the same seam
+ * verify.cts / phase.cts already use for plan metadata; a plan without the marker is
+ * counted exactly as before.
+ *
+ * This is the only path in scanPhasePlans that opens file *contents* (the rest is
+ * filename matching), so it is hardened accordingly: `statSync().isFile()` rejects
+ * anything that is not a regular file — a directory, socket, or a symlink resolving
+ * to a device such as `/dev/zero` (a git-committable DoS vector; cf. #2378/#2383) —
+ * BEFORE any open, and the read is bounded to a fixed prefix. Fail-safe throughout:
+ * a non-regular or unreadable plan is treated as a normal (counted) plan, never
+ * silently dropped.
+ */
+function isPlanSuperseded(planFullPath) {
+    let content;
+    try {
+        const st = (0, node_fs_1.statSync)(planFullPath); // follows symlinks → resolves to the target's real type
+        if (!st.isFile())
+            return false;
+        const length = Math.min(st.size, PLAN_FRONTMATTER_READ_CAP);
+        if (length === 0)
+            return false;
+        const fd = (0, node_fs_1.openSync)(planFullPath, 'r');
+        try {
+            const buf = Buffer.allocUnsafe(length);
+            const bytesRead = (0, node_fs_1.readSync)(fd, buf, 0, length, 0);
+            content = buf.toString('utf8', 0, bytesRead);
+        }
+        finally {
+            (0, node_fs_1.closeSync)(fd);
+        }
+    }
+    catch {
+        return false;
+    }
+    const status = extractFrontmatter(content)['status'];
+    return typeof status === 'string' && status.trim().toLowerCase() === 'superseded';
+}
 function isRootPlanFile(fileName) {
     if (PLAN_OUTLINE_RE.test(fileName))
         return false;
     if (PLAN_PRE_BOUNCE_RE.test(fileName))
         return false;
+    if (PLAN_REVIEW_RE.test(fileName))
+        return false;
     if (fileName.endsWith('-PLAN.md') || fileName === 'PLAN.md')
         return true;
     // A summary is never a plan. Reject summaries before the loose /PLAN/i
@@ -72,7 +127,16 @@ function scanPhasePlans(phaseDir) {
         }
         catch { /* ignore unreadable nested layout */ }
     }
-    const planFiles = rootPlanFiles.concat(nestedPlanFiles);
+    const allPlanFiles = rootPlanFiles.concat(nestedPlanFiles);
+    // #2349: drop plans explicitly marked `status: superseded` from the plan set
+    // BEFORE counting, so they inflate neither the denominator (planCount) nor,
+    // via countMatchedSummaries below, the numerator (summaryCount). Plans without
+    // the marker are untouched, so behaviour is byte-for-behaviour identical for
+    // every existing phase — only a phase carrying the new marker changes.
+    const supersededPlanFiles = allPlanFiles.filter((f) => isPlanSuperseded((0, node_path_1.join)(phaseDir, f)));
+    const planFiles = supersededPlanFiles.length === 0
+        ? allPlanFiles
+        : allPlanFiles.filter((f) => !supersededPlanFiles.includes(f));
     const summaryFiles = rootSummaryFiles.concat(nestedSummaryFiles);
     const planCount = planFiles.length;
     // Count only summaries that are the PLAN→SUMMARY partner of an existing plan
@@ -84,7 +148,14 @@ function scanPhasePlans(phaseDir) {
     return {
         planCount,
         summaryCount,
-        completed: planCount > 0 && summaryCount >= planCount,
+        // #2349: gate completion on whether the phase had ANY plans on disk
+        // (allPlanFiles), NOT on the post-exclusion planCount. A phase whose plans
+        // were ALL marked superseded has planCount 0, but it is NOT an unplanned
+        // empty phase — there is simply no remaining work, so it must read complete
+        // (0 >= 0) rather than being pinned below 100% forever, which is the very
+        // failure this fix removes. A genuinely empty phase (no plans authored)
+        // still has allPlanFiles.length 0 and stays not-completed, exactly as before.
+        completed: allPlanFiles.length > 0 && summaryCount >= planCount,
         hasNestedPlans,
         planFiles,
         summaryFiles,

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

@@ -14,6 +14,7 @@
  *   - ./phase-id.cjs        (escapeRegex, phaseMarkdownRegexSource)
  *   - ./planning-workspace.cjs (planningDir)
  *   - ./shell-command-projection.cjs (platformReadSync)
+ *   - ./markdown-sectionizer.cjs (tokenizeHeadings, stripTaggedBlocks, withSection)
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -173,6 +174,56 @@ function replaceInCurrentMilestone(content, pattern, replacement) {
     const after = content.slice(offset);
     return before + after.replace(pattern, replacement);
 }
+/**
+ * Resolve a single phase's detail-section heading (`### Phase N: …`, any level
+ * 1–6, via the #2121 phase-id source) and run `edit` against ONLY that
+ * section's body. Delegates to `withSection` (markdown-sectionizer.cjs), so a
+ * per-phase ROADMAP edit is structurally bounded to that phase's own section —
+ * it cannot escape into a sibling phase, a shipped-milestone `<details>` block,
+ * or a backticked prose literal (ADR-2143 §4).
+ *
+ * `content` is expected to already be scoped to the current milestone's raw
+ * range(s) by the caller (see `currentMilestoneRawRanges`) — `withPhaseSection`
+ * composes with that milestone-level scoping rather than replacing it.
+ *
+ * The matched phase number must be delimited by whitespace, a colon, an
+ * open-paren tag, or end-of-heading — never a bare `\b`. A trailing `\b` sits
+ * between the last digit and a following `.` or letter, so it would let a
+ * query for phase `1` prefix-match a decimal sub-phase heading like
+ * `### Phase 1.1: Sub` or a distinct suffixed phase like `### Phase 1A: …`.
+ *
+ * The phase token must additionally anchor to the START of the heading text
+ * (after an optional leading `[tag]`, mirroring `findRoadmapPhaseInContent`
+ * below) — never merely appear anywhere in it. Without this anchor, a query
+ * for phase `1` would match a SIBLING phase whose own TITLE happens to
+ * mention "Phase 1" (e.g. `### Phase 3: Migrate off Phase 1 legacy pipeline`),
+ * and — because `collectSection` picks the first matching heading in document
+ * order — that sibling would be hijacked instead of the real Phase 1 section.
+ *
+ * The section body is bounded by `{ levelBounded: false }`: it ends at the
+ * next ATX heading of ANY level, not merely a heading at or above the phase
+ * heading's own level. Real ROADMAPs are not guaranteed to use a uniform
+ * phase-heading level, so a level-bounded stop could fold a deeper sibling
+ * heading (e.g. a `####` phase following a `###` phase) into this phase's
+ * body and let `edit` reach into it.
+ */
+function withPhaseSection(content, phaseId, edit) {
+    const src = phaseMarkdownRegexSource(phaseId);
+    const headingRe = new RegExp(`^\\s*(?:\\[[^\\]]{1,200}\\]\\s*)?Phase\\s+${src}(?=[\\s:(]|$)`, 'i');
+    return (0, markdown_sectionizer_cjs_1.withSection)(content, (h) => headingRe.test(h.text), edit, { levelBounded: false });
+}
+// ─── Roadmap phase lookup ─────────────────────────────────────────────────────
+// #2199: a bullet/checkbox phase entry, e.g. `- [ ] **Phase 36 — Authentication**`
+// (the bundled roadmapper emits this in bullet-house-style ROADMAPs). The number
+// is captured in group 1, the name in group 2; the separator may be an em-dash,
+// en-dash, hyphen, or colon. Used as a fallback when no ATX heading matches, and
+// to count phases in a milestone that uses the bullet form.
+const BULLET_PHASE_LINE_PATTERN = /^\s*[-*]\s+(?:\[[ xX]\]\s+)?\*\*Phase\s+([\w][\w.-]*)(?:\s*\([^)\n]{0,200}\))?\s*[—–:\-]\s*(.+?)\*\*/im;
+/** Build a bullet-phase-line regex pinned to a specific phase number (#2199). */
+function bulletPhaseLineFor(phaseNum, phaseSource) {
+    const num = phaseSource ?? phaseMarkdownRegexSource(phaseNum);
+    return new RegExp(`^\\s*[-*]\\s+(?:\\[[ xX]\\]\\s+)?\\*\\*Phase\\s+(${num})${OPTIONAL_PHASE_TAG_SOURCE}\\s*[—–:\\-]\\s*(.+?)\\*\\*`, 'im');
+}
 function findRoadmapPhaseInContent(content, phaseNum, phaseSource) {
     // #1729: OPTIONAL_PHASE_TAG_SOURCE after the number tolerates a pre-colon ( ) tag.
     const headingPattern = new RegExp(`^(?:\\[[^\\]]{1,200}\\]\\s*)?Phase\\s+${phaseSource ?? phaseMarkdownRegexSource(phaseNum)}${OPTIONAL_PHASE_TAG_SOURCE}:\\s*(.+)$`, 'i');
@@ -198,6 +249,22 @@ function findRoadmapPhaseInContent(content, phaseNum, phaseSource) {
         section,
     };
 }
+function findRoadmapBulletPhaseInContent(content, phaseNum, phaseSource) {
+    // #2199: bullet/checkbox entry fallback (`- [ ] **Phase N — name**`). Returns
+    // the single bullet line as the section (no multi-line body) — used only as a
+    // last resort, AFTER heading lookup on scoped + full content has failed, so a
+    // heading with a Requirements/Goal section always wins.
+    const bulletMatch = content.match(bulletPhaseLineFor(phaseNum, phaseSource));
+    if (!bulletMatch)
+        return null;
+    return {
+        found: true,
+        phase_number: String(phaseNum),
+        phase_name: bulletMatch[2].trim(),
+        goal: null,
+        section: bulletMatch[0].trim(),
+    };
+}
 function getRoadmapPhaseInternal(cwd, phaseNum) {
     if (!phaseNum)
         return null;
@@ -221,12 +288,35 @@ function getRoadmapPhaseInternal(cwd, phaseNum) {
             if (fullResult)
                 return fullResult;
         }
+        // #2199: no ATX heading matched on scoped or full content — fall back to a
+        // bullet/checkbox entry (em-dash/en-dash/hyphen/colon separator). Last resort
+        // so a bullet never pre-empts a heading that carries the Requirements section.
+        for (const source of roadmapPhaseLookupSources(phaseNum)) {
+            const scopedBullet = findRoadmapBulletPhaseInContent(content, phaseNum, source);
+            if (scopedBullet)
+                return scopedBullet;
+            const fullBullet = findRoadmapBulletPhaseInContent(fullContent, phaseNum, source);
+            if (fullBullet)
+                return fullBullet;
+        }
         return null;
     }
     catch {
         return null;
     }
 }
+/**
+ * Strip a leading delimiter run (whitespace, em/en-dash, colon, hyphen) from a
+ * milestone-name capture. Markdown headings commonly take the shape
+ * `## vX.Y — Name` or `## vX.Y: Name`; the raw capture includes the delimiter
+ * because `.trim()` only removes whitespace, not punctuation. A name beginning
+ * with punctuation is a delimiter-led fragment, not the curated name (#2135).
+ * NOTE: do not strip `#` — a name beginning with `#` is a heading-parse failure
+ * that should stay loud rather than be silently cleaned.
+ */
+function stripLeadingDelimiter(s) {
+    return s.replace(/^[\s—–:-]+/, '').trim();
+}
 function getMilestoneInfo(cwd) {
     try {
         const roadmap = (0, shell_command_projection_cjs_1.platformReadSync)(node_path_1.default.join(planningDir(cwd), 'ROADMAP.md'));
@@ -243,23 +333,39 @@ function getMilestoneInfo(cwd) {
                         stateVersion = m[1].trim();
                 }
             }
-            catch { /* intentionally empty */ }
+            catch {
+                /* best-effort (#2245 audit): platformReadSync re-throws for a non-ENOENT
+                 * failure (e.g. EACCES) reading STATE.md. Consulting STATE.md's
+                 * `milestone:` field is an OPTIONAL enhancement here — on failure this
+                 * function already falls back to ROADMAP-only heuristics below, the
+                 * same fallback path taken when STATE.md simply doesn't exist. */
+            }
         }
         if (stateVersion) {
             const escapedVer = escapeRegex(stateVersion);
-            const headingMatch = roadmap.match(new RegExp(`##[^\\n]*${escapedVer}[:\\s]+([^\\n(]+)`, 'i'));
-            if (headingMatch) {
-                if (!headingMatch[0].includes('✅')) {
-                    return { version: stateVersion, name: headingMatch[1].trim() };
-                }
+            // #2135: consult the 🚧 name-bearing marker FIRST. It is the only construct
+            // guaranteed to carry the milestone's curated name adjacent to its version
+            // (the active-milestone bullet). A `##` heading is often nameless
+            // ("## vX.Y — Active Milestone") and, when unanchored, was matched
+            // spuriously on a copy quoted inside backticks in this very bullet.
+            const listMatch = roadmap.match(new RegExp(`🚧\\s*\\*?\\*?${escapedVer}\\s+([^*\\n]+)`, 'i'));
+            if (listMatch) {
+                const name = stripLeadingDelimiter(listMatch[1]);
+                if (name)
+                    return { version: stateVersion, name };
             }
-            else {
-                const listMatch = roadmap.match(new RegExp(`🚧\\s*\\*?\\*?${escapedVer}\\s+([^*\\n]+)`, 'i'));
-                if (listMatch) {
-                    return { version: stateVersion, name: listMatch[1].trim() };
-                }
-                return { version: stateVersion, name: 'milestone' };
+            // Fall back to the `##` heading — ANCHORED to line start (`^` + `m` flag)
+            // so a heading quoted inside backticks or prose mid-line can no longer
+            // match. Skip shipped (✅) headings.
+            const headingMatch = roadmap.match(new RegExp(`^##[^\\n]*${escapedVer}[:\\s]+([^\\n(]+)`, 'im'));
+            if (headingMatch && !headingMatch[0].includes('✅')) {
+                // Strip a leading delimiter — `.trim()` removes whitespace, not the
+                // em-dash/colon that conventionally separates version from name.
+                const name = stripLeadingDelimiter(headingMatch[1]);
+                if (name)
+                    return { version: stateVersion, name };
             }
+            return { version: stateVersion, name: 'milestone' };
         }
         const inProgressMatch = roadmap.match(/🚧\s*\*\*v(\d+(?:\.\d+)+)\s+([^*]+)\*\*/);
         if (inProgressMatch) {
@@ -374,8 +480,26 @@ function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention) {
             if (pm && !/^999\b/.test(pm[1]))
                 milestonePhaseNums.add(pm[1]);
         }
+        // #2199: also count bullet/checkbox phase entries (`- [ ] **Phase N — name**`)
+        // so a bullet-house-style ROADMAP populates the milestone phase set instead of
+        // collapsing to a zero-count pass-all filter.
+        {
+            let bm;
+            const scanner = new RegExp(BULLET_PHASE_LINE_PATTERN.source, 'gim');
+            while ((bm = scanner.exec(roadmap)) !== null) {
+                if (!/^999\b/.test(bm[1]))
+                    milestonePhaseNums.add(bm[1]);
+            }
+        }
+    }
+    catch {
+        /* best-effort (#2245 audit): the real throw source is platformReadSync
+         * at the top of this try (re-throws for a non-ENOENT read failure). On
+         * any failure milestonePhaseNums stays empty, which below already
+         * degrades to the same pass-all filter this function returns when a
+         * ROADMAP genuinely has zero recognizable phase headings — a safe,
+         * non-corrupting (over-inclusive, never under-inclusive) degrade. */
     }
-    catch { /* intentionally empty */ }
     if (milestonePhaseNums.size === 0) {
         const passAll = (() => true);
         passAll.phaseCount = 0;
@@ -387,12 +511,15 @@ function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention) {
         return id.split('-').map(seg => seg.replace(/^0+(?=\d)/, '') || '0').join('-');
     }
     const roadmapUsesHyphenedIds = [...normalized].some(n => n.includes('-'));
-    // #2043: milestone-prefixed sub-phase components must be zero-padded (≥2 digits)
-    // — "-\d{2,}" instead of "-0*\d+" — so a single-digit slug word after the phase
+    // #2043: milestone-prefixed sub-phase components must be zero-padded — so a
+    // single-digit slug word after the phase
     // number (e.g. dir "46-6-rs-…") captures "46" and is not silently excluded from
-    // the milestone as a bogus "46-6" id.
+    // the milestone as a bogus "46-6" id. #2232: the continuation width is exactly 2
+    // (PHASE_CONTINUATION_SEGMENT_SOURCE), so a year-leading slug word (dir
+    // "14-2026-photos-…") captures "14" and is not excluded as a bogus "14-2026" id.
+    // Built via new RegExp (no /i — the [A-Za-z] letter class does real case handling).
     const numericRe = roadmapUsesHyphenedIds
-        ? /^0*(\d+(?:-\d{2,})*[A-Za-z]?(?:\.\d+)*)/
+        ? new RegExp(`^0*(\\d+(?:-${phaseIdModule.PHASE_CONTINUATION_SEGMENT_SOURCE})*[A-Za-z]?(?:\\.\\d+)*)`)
         // phase-id-owner: the [A-Za-z] letter class does real case handling here — this regex carries NO /i flag; kept literal, not source-byte-equal to the canonical PHASE_NUMBER_TOKEN_SOURCE.
         : /^0*(\d+[A-Za-z]?(?:\.\d+)*)/;
     function isDirInMilestone(dirName) {
@@ -414,6 +541,85 @@ function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention) {
     isDirInMilestone.missingExplicitVersion = missingExplicitVersion;
     return isDirInMilestone;
 }
+/**
+ * #2200: raw [start,end) offsets of the current milestone's region(s) in ROADMAP
+ * content, for scoping write-path mutations (phase-checkbox flip, Plans-count
+ * writer) so they cannot touch a backticked prose literal, a Backlog entry, or a
+ * same-numbered phase in a shipped milestone.
+ *
+ * Mirrors the region selection in `extractCurrentMilestone` (version detection →
+ * active heading → next milestone boundary → optional Phase Details section).
+ * Returns null when there is no versioned active milestone; callers then fall
+ * back to whole-content mutation (the prior behaviour).
+ *
+ * NOTE: keep the region logic here in sync with extractCurrentMilestone.
+ */
+function currentMilestoneRawRanges(content, cwd) {
+    if (!cwd)
+        return null;
+    let version = null;
+    try {
+        const statePath = node_path_1.default.join(planningDir(cwd), 'STATE.md');
+        const stateRaw = (0, shell_command_projection_cjs_1.platformReadSync)(statePath);
+        if (stateRaw !== null) {
+            const milestoneMatch = stateRaw.match(/^milestone:\s*(.+)/m);
+            if (milestoneMatch)
+                version = milestoneMatch[1].trim();
+        }
+    }
+    catch { /* ignore */ }
+    if (!version) {
+        const inProgressMatch = content.match(/(?:🚧|🔄)\s*\*\*v(\d+\.\d+)\s/);
+        if (inProgressMatch)
+            version = 'v' + inProgressMatch[1];
+    }
+    if (!version)
+        return null;
+    const escapedVersion = escapeRegex(version);
+    const sectionPattern = new RegExp(`(^#{1,3}\\s+(?!Phase\\s+\\S).*${escapedVersion}\\b[^\\n]*)`, 'gmi');
+    const headingMatches = [...content.matchAll(sectionPattern)];
+    if (headingMatches.length === 0)
+        return null;
+    const closedMarkerPattern = /\b(?:CLOSED|ARCHIVED|ABANDONED|SHIPPED|FAILED)\b|✅|🗄/i;
+    const activeMarkerPattern = /\b(?:STARTED|ACTIVE|WIP)\b|in\s+progress|🚧|🔄/i;
+    const isClosed = (h) => closedMarkerPattern.test(h) && !activeMarkerPattern.test(h);
+    const firstMatch = headingMatches[0];
+    const selected = headingMatches.find((m) => !isClosed(m[1])) || firstMatch;
+    const sectionStart = selected.index ?? 0;
+    const computeSectionEnd = (headingText, headingStart) => {
+        const level = (headingText.match(/^(#{1,3})\s/) ?? ['', '#'])[1].length;
+        const afterHeading = headingStart + headingText.length;
+        for (const h of (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(content)) {
+            if (h.offset <= headingStart)
+                continue;
+            if (h.offset < afterHeading)
+                continue;
+            if (h.level > level)
+                continue;
+            if (/^Phase\s+\S/i.test(h.text))
+                continue;
+            if (!/v\d+\.\d+|✅|📋|🚧/i.test(h.text))
+                continue;
+            return h.offset;
+        }
+        return content.length;
+    };
+    const sectionEnd = computeSectionEnd(selected[0], sectionStart);
+    const selectedVersionToken = selected[1].match(/v\d+(?:\.\d+)+(?:[-.][A-Za-z0-9]+)*/i)?.[0];
+    const detailsVersionBoundary = selectedVersionToken
+        ? new RegExp(`${escapeRegex(selectedVersionToken)}(?![\\w.-])`, 'i')
+        : null;
+    const detailsMatch = headingMatches.find((m) => /\(Phase\s+Details\)/i.test(m[1]) &&
+        !isClosed(m[1]) &&
+        (!detailsVersionBoundary || detailsVersionBoundary.test(m[1])) &&
+        (m.index ?? 0) >= sectionEnd);
+    let details = null;
+    if (detailsMatch) {
+        const detailsStart = detailsMatch.index ?? 0;
+        details = { start: detailsStart, end: computeSectionEnd(detailsMatch[0], detailsStart) };
+    }
+    return { primary: { start: sectionStart, end: sectionEnd }, details };
+}
 module.exports = {
     stripShippedMilestones,
     extractCurrentMilestone,
@@ -421,4 +627,6 @@ module.exports = {
     getRoadmapPhaseInternal,
     getMilestoneInfo,
     getMilestonePhaseFilter,
+    currentMilestoneRawRanges,
+    withPhaseSection,
 };

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

@@ -25,6 +25,7 @@ const { findPhaseInternal } = phaseLocatorMod;
 const roadmapParserModule = require("./roadmap-parser.cjs");
 const { stripShippedMilestones, extractCurrentMilestone, replaceInCurrentMilestone } = roadmapParserModule;
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
+const markdown_table_cjs_1 = require("./markdown-table.cjs");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
@@ -169,9 +170,19 @@ function getRoadmapPhaseWithFallback(cwd, phaseNum) {
     if (/^999(?:\.|$)/.test(stripProjectCodePrefix(phaseNum)))
         return null;
     const roadmapPath = planningPaths(cwd).roadmap;
-    if (!node_fs_1.default.existsSync(roadmapPath))
-        return null;
-    const rawContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
+    // Read directly rather than gating on fs.existsSync: existsSync returns false
+    // on EACCES/EIO too, which would mask an UNREADABLE roadmap as "missing" and
+    // let a blocking gate certify empty scope (#2365 review). Honor the documented
+    // contract — null only when genuinely absent (ENOENT), otherwise throw.
+    let rawContent;
+    try {
+        rawContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return null;
+        throw err;
+    }
     const milestoneContent = extractCurrentMilestone(rawContent, cwd);
     const fullContent = stripShippedMilestones(rawContent);
     // #2121/#2114: iterate the shared lookup-source list (exact → numeric →
@@ -297,29 +308,32 @@ function cmdRoadmapAnalyze(cwd, raw) {
         let summaryCount = 0;
         let hasContext = false;
         let hasResearch = false;
-        try {
-            const dirMatch = _phaseDirNames.find(d => phaseTokenMatches(d, normalized));
-            if (dirMatch) {
-                const counts = countPhasePlansAndSummaries(node_path_1.default.join(phasesDir, dirMatch));
-                planCount = counts.planCount;
-                summaryCount = counts.summaryCount;
-                hasContext = counts.hasContext;
-                hasResearch = counts.hasResearch;
-                if (summaryCount >= planCount && planCount > 0)
-                    diskStatus = 'complete';
-                else if (summaryCount > 0)
-                    diskStatus = 'partial';
-                else if (planCount > 0)
-                    diskStatus = 'planned';
-                else if (hasResearch)
-                    diskStatus = 'researched';
-                else if (hasContext)
-                    diskStatus = 'discussed';
-                else
-                    diskStatus = 'empty';
-            }
+        // DEAD catch removed (#2245 audit): _phaseDirNames.find(...) is a pure
+        // array lookup on an already-resolved string array, and
+        // countPhasePlansAndSummaries is itself fully defensive (its own
+        // readdirSync is self-guarded, and it delegates to scanPhasePlans, which
+        // never throws) — nothing in this block can throw, so the try/catch could
+        // never be triggered.
+        const dirMatch = _phaseDirNames.find(d => phaseTokenMatches(d, normalized));
+        if (dirMatch) {
+            const counts = countPhasePlansAndSummaries(node_path_1.default.join(phasesDir, dirMatch));
+            planCount = counts.planCount;
+            summaryCount = counts.summaryCount;
+            hasContext = counts.hasContext;
+            hasResearch = counts.hasResearch;
+            if (summaryCount >= planCount && planCount > 0)
+                diskStatus = 'complete';
+            else if (summaryCount > 0)
+                diskStatus = 'partial';
+            else if (planCount > 0)
+                diskStatus = 'planned';
+            else if (hasResearch)
+                diskStatus = 'researched';
+            else if (hasContext)
+                diskStatus = 'discussed';
+            else
+                diskStatus = 'empty';
         }
-        catch { /* intentionally empty */ }
         // Check ROADMAP checkbox status.
         // #3537: padding-tolerant fragment — the heading discovered above may use
         // a different padding than the summary-bullet checkbox below it (mixed
@@ -392,6 +406,39 @@ function cmdRoadmapAnalyze(cwd, raw) {
     output(result, raw, undefined);
 }
 // ─── cmdRoadmapUpdatePlanProgress ─────────────────────────────────────────────
+/**
+ * Scope a ROADMAP.md content string down to its "Progress table" writable
+ * slice, run `edit` against just that slice, then splice the result back into
+ * the original content (ADR-2143 §7). Layered scoping:
+ *   1. Milestone scope — everything after the LAST `</details>` close tag
+ *      (mirrors `replaceInCurrentMilestone`), so a same-numbered phase row in
+ *      an archived milestone is never touched.
+ *   2. Heading scope — within that milestone slice, the `## Progress` heading
+ *      section (up to the next `#`/`##` heading) when present, else the whole
+ *      milestone slice (mirrors phase-lifecycle.cjs's `deriveProgressFromRoadmap`
+ *      read-side scoping, #2012 decoy avoidance — a differently-headed table
+ *      sharing the same column names must not be picked up instead).
+ * `edit` always returns a string and never fails — a no-op edit (table/row not
+ * found within the scoped slice) simply returns its input unchanged, mirroring
+ * the prior regex `.replace()`'s no-match-is-a-no-op semantics.
+ */
+function editProgressTableSlice(content, edit) {
+    const lastDetailsClose = content.lastIndexOf('</details>');
+    const milestoneOffset = lastDetailsClose === -1 ? 0 : lastDetailsClose + '</details>'.length;
+    const before = content.slice(0, milestoneOffset);
+    const milestoneSlice = content.slice(milestoneOffset);
+    const progressMatch = milestoneSlice.match(/^##[ \t]+Progress\b/im);
+    if (!progressMatch || progressMatch.index === undefined) {
+        return before + edit(milestoneSlice);
+    }
+    const headingOffset = progressMatch.index;
+    const beforeHeading = milestoneSlice.slice(0, headingOffset);
+    const fromHeading = milestoneSlice.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 before + beforeHeading + edit(scoped) + after;
+}
 function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
     if (!phaseNum) {
         error('phase number required for roadmap update-plan-progress');
@@ -418,7 +465,7 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
     const verificationPassed = readVerificationStatus(phaseDir).status === 'passed';
     const isComplete = summaryCount >= planCount && verificationPassed;
     const status = isComplete ? 'Complete' : summaryCount > 0 ? 'In Progress' : 'Planned';
-    const today = clock_cjs_1.realClock.today();
+    const today = clock_cjs_1.realClock.localToday();
     if (!node_fs_1.default.existsSync(roadmapPath)) {
         output({ updated: false, reason: 'ROADMAP.md not found', plan_count: planCount, summary_count: summaryCount }, raw, 'no roadmap');
         return;
@@ -427,32 +474,46 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
     withPlanningLock(cwd, () => {
         let roadmapContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
         const phasePattern = phaseMarkdownRegexSource(phaseNum);
-        // Progress table row: update Plans/Status/Date columns (handles 4 or 5 column tables)
-        const tableRowPattern = new RegExp(`^(\\|\\s*${phasePattern}\\.?\\s[^|]*(?:\\|[^\\n]*))$`, 'im');
-        roadmapContent = roadmapContent.replace(tableRowPattern, (fullRow) => {
-            const cells = fullRow.split('|').slice(1, -1); // drop leading/trailing empty from split
-            const dateShape = /^\d{4}-\d{2}-\d{2}$/;
-            if (cells.length === 5) {
-                // 5-col: Phase | Milestone | Plans | Status | Completed
-                cells[2] = ` ${summaryCount}/${planCount} `;
-                cells[3] = ` ${status.padEnd(11)}`;
-                // Preserve only a valid ISO date (#1161: idempotent; self-heal garbage)
-                const existingDate5 = cells[4].trim();
-                cells[4] = isComplete
-                    ? (dateShape.test(existingDate5) ? cells[4] : ` ${today} `)
-                    : '  ';
-            }
-            else if (cells.length === 4) {
-                // 4-col: Phase | Plans | Status | Completed
-                cells[1] = ` ${summaryCount}/${planCount} `;
-                cells[2] = ` ${status.padEnd(11)}`;
-                // Preserve only a valid ISO date (#1161: idempotent; self-heal garbage)
-                const existingDate4 = cells[3].trim();
-                cells[3] = isComplete
-                    ? (dateShape.test(existingDate4) ? cells[3] : ` ${today} `)
-                    : '  ';
-            }
-            return '|' + cells.join('|') + '|';
+        // Progress table row: update Plans Complete/Status/Completed columns BY
+        // COLUMN NAME (handles 4- or 5-column RoadmapProgress tables regardless of
+        // Milestone-column presence) via the markdown-table seam (ADR-2143 §7) —
+        // supersedes the prior ordinal cells[]-index regex. Scoped to the current
+        // milestone's `## Progress` table (editProgressTableSlice above).
+        // #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" (replicates OLD's `\.?\s` intent on the now-TRIMMED
+        // cell value, where end-of-string is the trimmed equivalent of "no more
+        // characters after the optional dot").
+        const phaseCellRe = new RegExp(`^${phasePattern}\\.?(?:\\s|$)`, 'i');
+        const rowMatch = (row) => phaseCellRe.test((row['Phase'] ?? '').trim());
+        const dateShape = /^\d{4}-\d{2}-\d{2}$/;
+        roadmapContent = editProgressTableSlice(roadmapContent, (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', ` ${status.padEnd(11)}`);
+            if (statusResult.ok)
+                text = statusResult.value;
+            // Preserve only a valid ISO date (#1161: idempotent; self-heal garbage).
+            // Ragged-tolerant (#2245 Blocker 2): probe the CURRENT Completed cell via
+            // a no-op updateTableCell write (its own tolerant row scan) rather than
+            // findTableWithColumns (which requires the WHOLE table to parse — a
+            // ragged SIBLING row elsewhere used to silently no-op this row's date
+            // stamp/clear too). The decision (write vs no-op) is folded into the
+            // newValue callback so a single updateTableCell call both reads and
+            // writes.
+            const completedResult = (0, markdown_table_cjs_1.updateTableCell)(text, rowMatch, 'Completed', (current) => {
+                if (isComplete) {
+                    return dateShape.test(current.trim()) ? current : ` ${today} `;
+                }
+                return '  ';
+            });
+            if (completedResult.ok)
+                text = completedResult.value;
+            return text;
         });
         // Update plan count in phase detail section.
         // Three recognised forms (all tolerated; canonical template uses the first):