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

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

@@ -21,6 +21,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 write_set_cjs_1 = require("./write-set.cjs");
+const markdown_table_cjs_1 = require("./markdown-table.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
 const { output, error } = ioMod;
@@ -36,6 +38,43 @@ const { extractOneLinerFromBody } = coreUtilsMod;
 const { planningPaths } = planningWorkspace;
 const { extractFrontmatter } = frontmatterMod;
 const { writeStateMd } = stateMod;
+/**
+ * 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 phase.cts's `editProgressHeadingSlice` scoping of
+ * `## Progress` writes to that heading's own slice.
+ *
+ * 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 };
+}
 function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
     if (!reqIdsRaw || reqIdsRaw.length === 0) {
         error('requirement IDs required. Usage: requirements mark-complete REQ-01,REQ-02 or REQ-01 REQ-02');
@@ -59,50 +98,135 @@ function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
     const updated = [];
     const alreadyComplete = [];
     const notFound = [];
+    // #2140: IDs reconciled on the checkbox surface only — a traceability table
+    // exists but has no row for the ID. Without this bucket the payload for a
+    // partial reconcile is byte-identical to a full one, and audit-milestone (which
+    // reads the table) still sees Pending while the CLI reported success.
+    const tableUnmatched = [];
+    // A traceability table is present if the file has a requirement-ID column
+    // header: "Requirement", "Requirement ID", or "REQ-ID" (#2769/#2203) — kept
+    // in sync with the positional first-cell rowMatch/hasRow below so a
+    // REQ-ID-headed table (the real-world format) participates in the
+    // write-set and the #2140 drift check below, not just the "Requirement"
+    // case. A REQUIREMENTS.md with no such table is legitimate (mid-roadmap),
+    // so a missing row only counts as drift when a table actually exists.
+    const hasTable = /^\|\s*(?:Requirement(?:\s*ID)?|REQ[-\s]?ID)\s*\|/im.test(reqContent);
+    // ADR-2143 §6 per-surface write-set, tracked PER requirement ID: a
+    // multi-ID batch must not OR one ID's surface outcome into another's —
+    // that is the exact #2140 class one level up (an ID whose traceability
+    // row is absent/unmatched must not have its partial write masked by a
+    // different ID in the same invocation that fully reconciled). Reported
+    // additively as `write_set` below — it does not change the existing
+    // marked_complete/already_complete/not_found/table_unmatched/updated
+    // computation, which stays byte-for-behaviour identical (#2140's tactical
+    // fix already surfaces the checkbox-only-partial-write case via
+    // table_unmatched; this only adds the structured ADR-2143 shape on top).
+    const writeSet = [];
     for (const reqId of reqIds) {
-        let found = false;
         const reqEscaped = escapeRegex(reqId);
-        // Update checkbox: - [ ] **REQ-ID** → - [x] **REQ-ID**
-        // Use replace() directly and compare — avoids test()+replace() global regex
+        // Surface 1 — the checkbox: - [ ] **REQ-ID** → - [x] **REQ-ID**
+        // Use replace() + compare to avoid the test()+replace() global regex
         // lastIndex bug where test() advances state and replace() misses matches.
         const checkboxPattern = new RegExp(`(-\\s*\\[)[ ](\\]\\s*\\*\\*${reqEscaped}\\*\\*)`, 'gi');
         const afterCheckbox = reqContent.replace(checkboxPattern, '$1x$2');
-        if (afterCheckbox !== reqContent) {
+        const checkboxHit = afterCheckbox !== reqContent;
+        if (checkboxHit)
             reqContent = afterCheckbox;
-            found = true;
+        // Surface 2 — the traceability row: | <REQ-ID> | Phase N | Pending | → ... Complete |
+        // via the markdown-table seam (ADR-2143 §7) — supersedes the prior ordinal
+        // regex. 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. Object.values(row) is in header order so [0] is the
+        // first column. Case-insensitive (mirrors the prior regex's 'i' flag).
+        const rowMatch = (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 ->
+        // Complete" gate is folded into the newValue callback so one
+        // updateTableCell call both probes the current value and writes.
+        let tableHit = false;
+        const tableUpdate = updateTraceabilityCell(reqContent, rowMatch, 'Status', (current) => {
+            if (/^pending$/i.test(current.trim())) {
+                tableHit = true;
+                return ' Complete ';
+            }
+            return current;
+        });
+        if (tableUpdate.ok) {
+            reqContent = tableUpdate.value;
         }
-        // Update traceability table: | REQ-ID | Phase N | Pending | → | REQ-ID | Phase N | Complete |
-        const tablePattern = new RegExp(`(\\|\\s*${reqEscaped}\\s*\\|[^|]+\\|)\\s*Pending\\s*(\\|)`, 'gi');
-        const afterTable = reqContent.replace(tablePattern, '$1 Complete $2');
-        if (afterTable !== reqContent) {
-            reqContent = afterTable;
-            found = true;
+        // ADR-2143 §6 per-ID write-set entries: this ID's checkbox surface is
+        // always tracked; the traceability surface is tracked only when the file
+        // has a traceability table at all (same `hasTable` gate the existing
+        // required-surface logic below uses) — omitted entirely, not a false
+        // `applied:false`, when no table is required of this file.
+        writeSet.push({ requirement: reqId, surface: 'checkbox', applied: checkboxHit });
+        if (hasTable) {
+            writeSet.push({ requirement: reqId, surface: 'traceability', applied: tableHit });
         }
-        if (found) {
+        // Coverage of the traceability surface for this ID (computed after any flip).
+        // hasRow keys on the ID's FIRST cell (the requirement-ID column, by position —
+        // see rowMatch above) so a bare mention of the ID in a non-traceability table
+        // does not masquerade as a real row.
+        // Ragged-tolerant (#2245 Blocker 2): same reasoning as the write above — a
+        // sibling row's raggedness must not blind this classification to a row
+        // that genuinely exists. Probe via a no-op updateTableCell write (its own
+        // tolerant scan) instead of findTableWithColumns (whole-table parse gate).
+        let currentStatusCell = '';
+        const statusProbe = updateTraceabilityCell(reqContent, rowMatch, 'Status', (current) => {
+            currentStatusCell = current;
+            return current;
+        });
+        const hasRow = statusProbe.ok;
+        const doneCheckbox = new RegExp(`-\\s*\\[x\\]\\s*\\*\\*${reqEscaped}\\*\\*`, 'i').test(reqContent);
+        const doneTable = Boolean(hasRow && /^complete$/i.test(currentStatusCell.trim()));
+        if (checkboxHit || tableHit) {
             updated.push(reqId);
         }
-        else {
-            // Check if already complete before declaring not_found.
-            // Non-global flag is fine here — we only need to know if a match exists.
-            const doneCheckbox = new RegExp(`-\\s*\\[x\\]\\s*\\*\\*${reqEscaped}\\*\\*`, 'i');
-            const doneTable = new RegExp(`\\|\\s*${reqEscaped}\\s*\\|[^|]+\\|\\s*Complete\\s*\\|`, 'i');
-            if (doneCheckbox.test(reqContent) || doneTable.test(reqContent)) {
-                alreadyComplete.push(reqId);
-            }
-            else {
-                notFound.push(reqId);
-            }
+        else if (doneTable || (doneCheckbox && !hasTable)) {
+            // Fully reconciled: the table row is Complete, OR the checkbox is done and
+            // there is no table to reconcile against. (A [x] checkbox with a Pending or
+            // absent row is NOT fully reconciled when a table exists — #2140.)
+            alreadyComplete.push(reqId);
+        }
+        else if (!doneCheckbox && !doneTable) {
+            notFound.push(reqId);
+        }
+        // else: doneCheckbox && hasTable && !doneTable — partially reconciled. It is
+        // neither updated, already_complete, nor not_found; the table_unmatched bucket
+        // below carries the truthful partial-reconcile signal.
+        // Surface traceability drift: checkbox reconciled (this run or before) but the
+        // table has no row for this ID. This is what makes a partial reconcile
+        // distinguishable from a full one (#2140).
+        if (hasTable && doneCheckbox && !hasRow) {
+            tableUnmatched.push(reqId);
         }
     }
     if (updated.length > 0) {
         (0, shell_command_projection_cjs_1.platformWriteSync)(reqPath, reqContent);
     }
+    // ADR-2143 §6: `writeSet` above already carries one WriteOutcome per
+    // (requirement, surface) this invocation could have written to — per ID,
+    // not ORed across the batch. `write_set` and `write_set_complete` are
+    // additive: they do not replace or gate `updated` / `marked_complete` /
+    // `already_complete` / `not_found` / `table_unmatched`, which remain
+    // computed exactly as before (see #2140 note above — that fix already
+    // surfaces a checkbox-only partial write via `table_unmatched`;
+    // `write_set_complete` is a structured, ADR-2143-shaped read of the SAME
+    // per-surface, per-ID facts, `false` if ANY id's ANY required surface did
+    // not apply, since `writeSetComplete` requires EVERY entry to have
+    // applied, never an OR across surfaces OR across IDs).
     output({
         updated: updated.length > 0,
         marked_complete: updated,
         already_complete: alreadyComplete,
         not_found: notFound,
+        table_unmatched: tableUnmatched,
         total: reqIds.length,
+        write_set: writeSet,
+        write_set_complete: (0, write_set_cjs_1.writeSetComplete)(writeSet),
     }, raw, `${updated.length}/${reqIds.length} requirements marked complete`);
 }
 function cmdMilestoneComplete(cwd, version, options, raw) {
@@ -120,10 +244,12 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     const milestonesPath = node_path_1.default.join(planningBase, 'MILESTONES.md');
     const archiveDir = node_path_1.default.join(planningBase, 'milestones');
     const phasesDir = planningPaths(cwd).phases;
-    const today = new Date().toISOString().split('T')[0];
+    const today = clock_cjs_1.realClock.localToday();
     const milestoneName = options.name || version;
-    // Ensure archive directory exists
-    (0, shell_command_projection_cjs_1.platformEnsureDir)(archiveDir);
+    // Ensure archive directory exists (skipped in dry-run — no mutations)
+    if (!options.dryRun) {
+        (0, shell_command_projection_cjs_1.platformEnsureDir)(archiveDir);
+    }
     // Scope stats and accomplishments to only the phases belonging to the
     // current milestone's ROADMAP.  Uses the shared filter from roadmap-parser.cjs
     // (same logic used by cmdPhasesList and other callers).
@@ -247,13 +373,62 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
                     }
                 }
                 catch {
-                    /* intentionally empty */
+                    /* best-effort (#2245 audit): one unreadable/malformed SUMMARY.md
+                     * must not abort the accomplishments/task-count roll-up for every
+                     * OTHER summary across every OTHER phase — it's simply excluded
+                     * from the milestone's shipped-summary text. */
                 }
             }
         }
     }
     catch {
-        /* intentionally empty */
+        /* best-effort (#2245 audit): mirrors the phaseDirEntries IIFE a few
+         * lines below this function (same phasesDir, same "try readdirSync,
+         * tolerate ENOENT" pattern) — phasesDir may legitimately not exist yet
+         * (e.g. milestone being force-completed before any phase directories
+         * were created). Degrades stats to phaseCount/totalPlans/totalTasks=0,
+         * accomplishments=[] rather than crash `milestone complete`. */
+    }
+    // #2118: --dry-run preview — compute what WOULD happen without mutating.
+    // The stats above are read-only; all mutations start at the archive section below.
+    if (options.dryRun) {
+        const phaseDirsToArchive = [];
+        if (options.archivePhases !== false) {
+            try {
+                const entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
+                for (const e of entries) {
+                    if (e.isDirectory() && isDirInMilestone(e.name)) {
+                        phaseDirsToArchive.push(e.name);
+                    }
+                }
+            }
+            catch { /* phasesDir missing — nothing to archive */ }
+        }
+        const dryRunResult = {
+            dry_run: true,
+            version,
+            name: milestoneName,
+            stats: { phases: phaseCount, plans: totalPlans, tasks: totalTasks },
+            accomplishments,
+            would_archive: {
+                roadmap: node_fs_1.default.existsSync(roadmapPath)
+                    ? { source: node_path_1.default.relative(cwd, roadmapPath).split(node_path_1.default.sep).join('/'), target: node_path_1.default.relative(cwd, node_path_1.default.join(archiveDir, `${version}-ROADMAP.md`)).split(node_path_1.default.sep).join('/') }
+                    : null,
+                requirements: node_fs_1.default.existsSync(reqPath)
+                    ? { source: node_path_1.default.relative(cwd, reqPath).split(node_path_1.default.sep).join('/'), target: node_path_1.default.relative(cwd, node_path_1.default.join(archiveDir, `${version}-REQUIREMENTS.md`)).split(node_path_1.default.sep).join('/') }
+                    : null,
+                audit: node_fs_1.default.existsSync(node_path_1.default.join(planningBase, `${version}-MILESTONE-AUDIT.md`))
+                    ? { source: node_path_1.default.relative(cwd, node_path_1.default.join(planningBase, `${version}-MILESTONE-AUDIT.md`)).split(node_path_1.default.sep).join('/'), target: node_path_1.default.relative(cwd, node_path_1.default.join(archiveDir, `${version}-MILESTONE-AUDIT.md`)).split(node_path_1.default.sep).join('/') }
+                    : null,
+                phases: phaseDirsToArchive,
+            },
+            would_update: {
+                milestones_md: node_path_1.default.relative(cwd, milestonesPath).split(node_path_1.default.sep).join('/'),
+                state_md: node_fs_1.default.existsSync(statePath) ? node_path_1.default.relative(cwd, statePath).split(node_path_1.default.sep).join('/') : null,
+            },
+        };
+        output(dryRunResult, raw);
+        return;
     }
     // Archive ROADMAP.md
     if (node_fs_1.default.existsSync(roadmapPath)) {
@@ -323,22 +498,33 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     let phasesArchived = false;
     // #1871: archive phase dirs by default on milestone complete (opt out via --no-archive-phases).
     if (options.archivePhases !== false) {
+        // #2245 audit (was ERROR-HIDING): retryRenameSync moves one phase dir at a
+        // time — a mid-loop failure (e.g. the Nth rename) used to leave
+        // `phasesArchived` at its `false` default even though the first N-1 dirs
+        // had ALREADY been moved to phaseArchiveDir on disk, silently
+        // under-reporting a real partial archive in the JSON result. archivedCount
+        // is now computed in a `finally` so it reflects whatever succeeded before
+        // any failure, instead of being lost with the swallowed exception.
+        let archivedCount = 0;
         try {
             const phaseArchiveDir = node_path_1.default.join(archiveDir, `${version}-phases`);
             (0, shell_command_projection_cjs_1.platformEnsureDir)(phaseArchiveDir);
             const phaseEntries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
             const phaseDirNames = phaseEntries.filter((e) => e.isDirectory()).map((e) => e.name);
-            let archivedCount = 0;
             for (const dir of phaseDirNames) {
                 if (!isDirInMilestone(dir))
                     continue;
                 (0, shell_command_projection_cjs_1.retryRenameSync)(node_path_1.default.join(phasesDir, dir), node_path_1.default.join(phaseArchiveDir, dir));
                 archivedCount++;
             }
-            phasesArchived = archivedCount > 0;
         }
         catch {
-            /* intentionally empty */
+            /* best-effort: phasesDir may not exist yet, or the archive rename loop
+             * failed partway — phasesArchived below still reflects whatever
+             * archivedCount succeeded before the failure. */
+        }
+        finally {
+            phasesArchived = archivedCount > 0;
         }
     }
     const result = {

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

@@ -137,7 +137,32 @@ function routePhaseCommand({ phase, args, cwd, raw, error }) {
                 return { ok: true, data: null };
             },
             complete: (_ctx) => {
-                phase.cmdPhaseComplete(cwd, args[2], raw);
+                // #2201: accept --phase N as well as the positional form (the state
+                // family already accepts --phase). An unrecognized flag is a usage
+                // error, not "Phase --phase not found".
+                let phaseNum = null;
+                for (let i = 2; i < args.length; i++) {
+                    if (args[i] === '--phase') {
+                        phaseNum = args[++i];
+                        if (!phaseNum || phaseNum.startsWith('--'))
+                            return makeInvalidArgs('--phase', '--phase requires a value');
+                    }
+                    else if (args[i].startsWith('--phase=')) {
+                        phaseNum = args[i].slice(8);
+                    }
+                    else if (args[i] === '--raw') {
+                        continue;
+                    }
+                    else if (args[i].startsWith('--')) {
+                        return makeInvalidArgs(args[i], `phase complete does not support ${args[i]}`);
+                    }
+                    else {
+                        phaseNum = args[i];
+                    }
+                }
+                if (!phaseNum)
+                    return makeInvalidArgs('--phase', 'phase number required (positional or --phase N)');
+                phase.cmdPhaseComplete(cwd, phaseNum, raw);
                 return { ok: true, data: null };
             },
             'uat-passed': (_ctx) => {
@@ -162,7 +187,30 @@ function routePhaseCommand({ phase, args, cwd, raw, error }) {
             },
             // #1437 — list plan files for a phase
             'list-plans': (_ctx) => {
-                phase.cmdPhaseListPlans(cwd, args[2], raw);
+                // #2201: accept --phase N as well as positional.
+                let phaseNum = null;
+                for (let i = 2; i < args.length; i++) {
+                    if (args[i] === '--phase') {
+                        phaseNum = args[++i];
+                        if (!phaseNum || phaseNum.startsWith('--'))
+                            return makeInvalidArgs('--phase', '--phase requires a value');
+                    }
+                    else if (args[i].startsWith('--phase=')) {
+                        phaseNum = args[i].slice(8);
+                    }
+                    else if (args[i] === '--raw') {
+                        continue;
+                    }
+                    else if (args[i].startsWith('--')) {
+                        return makeInvalidArgs(args[i], `phase list-plans does not support ${args[i]}`);
+                    }
+                    else {
+                        phaseNum = args[i];
+                    }
+                }
+                if (!phaseNum)
+                    return makeInvalidArgs('--phase', 'phase number required (positional or --phase N)');
+                phase.cmdPhaseListPlans(cwd, phaseNum, raw);
                 return { ok: true, data: null };
             },
         },

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

@@ -23,53 +23,79 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.deriveProgressFromRoadmap = deriveProgressFromRoadmap;
 exports.clampPercent = clampPercent;
+const markdown_table_cjs_1 = require("./markdown-table.cjs");
 /**
  * Derive completed_phases, total_phases, and total_plans from ROADMAP content.
  * Root cause fix for issue #4 — see gen-phase-lifecycle.mjs for full documentation.
+ *
+ * ADR-2143 §3 ("addressed by NAME, never ordinal"): the Progress table is
+ * located via the markdown-table seam's `findTableWithColumns`, which is
+ * column-NAME/order/count-invariant — it matches the first table whose header
+ * is a SUPERSET of the canonical `Phase` / `Plans Complete` / `Status` /
+ * `Completed` names, in any order, tolerating extra/injected unrelated
+ * columns (#2137's fast-check property test shuffles headers and injects
+ * columns and asserts the derived counts never change). This supersedes the
+ * earlier `findTableBySchema` exact-schema lookup, which required an exact
+ * canonical column SET+ORDER and returned all-null on any reordering or
+ * injection.
+ *
+ * Scoped to the `## Progress` section when the document has one (#2012 decoy
+ * avoidance — a differently-headed table sharing the same column names must
+ * not be picked up instead); a headingless milestone slice (#1445) falls back
+ * to scanning the whole input, preserving the "Progress table not under a
+ * `## Progress` heading, or not the first table in the document, still
+ * resolves" behaviour.
+ *
+ * Cells are read by column NAME (`r['Status']`, `r['Plans Complete']`,
+ * `r['Phase']`), fixing #2137 (the old position-based regex assumed "Status"
+ * was always the 3rd cell and "Plans Complete" the 2nd, which broke for the
+ * 5-column milestone-grouped variant that inserts a `Milestone` column ahead
+ * of them).
  */
 function deriveProgressFromRoadmap(roadmapContent) {
     let completedPhases = null;
     let totalPhases = null;
     let totalPlans = null;
-    try {
-        // Count Complete rows in the progress table (Status column = "Complete").
-        // Pattern: row where the phase cell starts with a digit (data row, not header),
-        // followed by any cell content, then a "Complete" status cell.
-        // Handles both short form ("| 4. |") and long form ("| 01. Foundation |").
-        // See phase-lifecycle.ts ~line 1655 for the original SDK pattern.
-        const tableCompletePattern = /\|\s*\d+[^|]*\|\s*[^|]*\|\s*Complete\s*\|/gi;
-        const completeMatches = roadmapContent.match(tableCompletePattern);
-        completedPhases = completeMatches ? completeMatches.length : null;
-        // Count total phase rows in the progress table.
-        // Identify the table by looking for Phase|...|Status|...|Completed header.
-        const progressTableMatch = roadmapContent.match(
-        // allow-adhoc-markdown: table-scoped regex with heading lookahead as stop; table parsing, out of seam scope; pending #1372
-        /\|\s*Phase\s*\|[^|]*\|[^|]*Status[^|]*\|[^|]*Completed[^|]*\|[\s\S]*?(?=\n\n|\n##|$)/i);
-        if (progressTableMatch) {
-            const tableText = progressTableMatch[0];
-            // Count data rows (rows starting with pipe then a phase number),
-            // excluding 999.x backlog phases. Mirrors init.cts /^999(?:\.|$)/ filter.
-            const dataRowPattern = /^\|\s*(\d+[^|]*)\|/gm;
-            let dataRowCount = 0;
-            let drm;
-            while ((drm = dataRowPattern.exec(tableText)) !== null) {
-                if (/^999\b/.test(drm[1].trim()))
-                    continue;
-                dataRowCount++;
-            }
-            totalPhases = dataRowCount > 0 ? dataRowCount : null;
-        }
-        // Sum plan counts from M/N columns in progress table
+    // ADR-2143 §5 (fail-loud, no null-swallow): this used to be wrapped in a
+    // try/catch that silently fell through to the existing (null) values on any
+    // thrown error. `findTableWithColumns`/`parseMarkdownTable` never throw —
+    // an unparseable or absent table resolves to `null` /
+    // `{ ok: false, reason }`, not an exception — so the catch was masking
+    // nothing but dead code paths. Removed per ADR-2143 §5; the public
+    // `RoadmapProgress` contract (nulls = absent) is unchanged.
+    //
+    // ADR-2143 §3: read the Progress table by column NAME (order/injection-invariant),
+    // via the markdown-table seam. Scope to the `## Progress` section when present
+    // (#2012 decoy avoidance); a headingless milestone slice (#1445) falls back to the
+    // whole input. Requires the canonical Phase/Plans Complete/Status/Completed columns
+    // in any order (extra columns ignored) — supersedes findTableBySchema's exact-schema lookup.
+    const progressMatch = roadmapContent.match(/^##[ \t]+Progress\b/im);
+    let scoped = roadmapContent;
+    if (progressMatch && progressMatch.index !== undefined) {
+        const afterHeading = roadmapContent.slice(progressMatch.index);
+        const nextHeading = afterHeading.search(/\n#{1,2}[ \t]/);
+        scoped = nextHeading >= 0 ? afterHeading.slice(0, nextHeading) : afterHeading;
+    }
+    const table = (0, markdown_table_cjs_1.findTableWithColumns)(scoped, ['Phase', 'Plans Complete', 'Status', 'Completed']);
+    if (table) {
+        const allRows = table.rows;
+        const completed = allRows.filter((r) => /^complete$/i.test((r['Status'] ?? '').trim())).length;
+        completedPhases = completed > 0 ? completed : null;
+        // Data rows only (exclude 999.x backlog phases). Mirrors init.cts /^999(?:\.|$)/ filter.
+        const dataRows = allRows.filter((r) => {
+            const phase = (r['Phase'] ?? '').trim();
+            return /^\d/.test(phase) && !/^999\b/.test(phase);
+        });
+        totalPhases = dataRows.length > 0 ? dataRows.length : null;
         let totalPlansSum = 0;
-        const planCellPattern = /\|\s*\d+[^|]*\|\s*(\d+)\/(\d+)\s*\|/gi;
-        let pm;
-        while ((pm = planCellPattern.exec(roadmapContent)) !== null) {
-            totalPlansSum += parseInt(pm[2], 10);
+        for (const r of allRows) {
+            const cell = (r['Plans Complete'] ?? '').trim();
+            const m = /(\d+)\s*\/\s*(\d+)/.exec(cell);
+            if (m)
+                totalPlansSum += parseInt(m[2], 10);
         }
-        if (totalPlansSum > 0)
-            totalPlans = totalPlansSum;
+        totalPlans = totalPlansSum > 0 ? totalPlansSum : null;
     }
-    catch { /* intentionally empty — fall through to existing values */ }
     return { completedPhases, totalPhases, totalPlans };
 }
 /**

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

@@ -34,9 +34,30 @@ const { planningDir } = planningWorkspace;
 function searchPhaseInDir(baseDir, relBase, normalized) {
     try {
         const dirs = readSubdirectories(baseDir, true);
-        const match = dirs.find(d => phaseTokenMatches(d, normalized));
-        if (!match)
+        const matches = dirs.filter(d => phaseTokenMatches(d, normalized));
+        if (matches.length === 0)
             return null;
+        // #2237: fail loud when multiple directories match the same bare phase
+        // number — this happens when unrelated projects share a .planning/phases/
+        // tree. Silently taking the first match risks cross-project file writes.
+        if (matches.length > 1) {
+            return {
+                found: false,
+                directory: '',
+                phase_number: normalized,
+                phase_name: null,
+                phase_slug: null,
+                plans: [],
+                summaries: [],
+                incomplete_plans: [],
+                has_research: false,
+                has_context: false,
+                has_verification: false,
+                has_reviews: false,
+                ambiguous_matches: matches,
+            };
+        }
+        const match = matches[0];
         const phaseToken = extractPhaseToken(match);
         const phaseNumber = phaseToken || normalized;
         const afterToken = match.slice(phaseToken ? phaseToken.length : 0).replace(/^-/, '');