@opengsd/gsd-core 1.17.0 → 1.19.0

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

@@ -22,6 +22,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.locateProgressTable = locateProgressTable;
+exports.normalizeMilestoneToken = normalizeMilestoneToken;
+exports.milestoneVersionOf = milestoneVersionOf;
 exports.deriveProgressFromRoadmap = deriveProgressFromRoadmap;
 exports.clampPercentFromFraction = clampPercentFromFraction;
 exports.clampPercent = clampPercent;
@@ -68,6 +70,28 @@ function locateProgressTable(roadmapContent) {
     }
     return (0, markdown_table_cjs_1.findTableWithColumns)(scoped, ['Phase', 'Plans Complete', 'Status', 'Completed']);
 }
+/**
+ * #5165: a milestone token compared by identity, not spelling — `v1.1`, `V1.1`
+ * and ` 1.1 ` name one milestone. A hand-decorated Progress cell
+ * (`**v1.1**`, `` `v1.1` ``, `v1.1 (current)`) still names its first
+ * whitespace-separated token. Absent/blank tokens normalize to `''`.
+ */
+function normalizeMilestoneToken(value) {
+    // `[v1.1](ROADMAP.md#v11)` names its link text.
+    const unlinked = (milestoneVersionOf(value) ?? '').replace(/\[([^\]]*)\]\([^)]*\)/g, '$1');
+    const first = unlinked.split(/\s+/)[0] ?? '';
+    return first.replace(/^[*_`]+|[*_`:,;]+$/g, '').replace(/^v/i, '').toLowerCase();
+}
+/**
+ * #5165: a STATE.md `milestone:` frontmatter value as a trimmed version string,
+ * or null when it is absent, blank or not scalar text.
+ */
+function milestoneVersionOf(value) {
+    if (typeof value !== 'string' && typeof value !== 'number')
+        return null;
+    const text = String(value).trim();
+    return text === '' ? null : text;
+}
 /**
  * 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.
@@ -82,7 +106,7 @@ function locateProgressTable(roadmapContent) {
  * 5-column milestone-grouped variant that inserts a `Milestone` column ahead
  * of them).
  */
-function deriveProgressFromRoadmap(roadmapContent) {
+function deriveProgressFromRoadmap(roadmapContent, milestoneFilter) {
     let completedPhases = null;
     let totalPhases = null;
     let totalPlans = null;
@@ -95,10 +119,19 @@ function deriveProgressFromRoadmap(roadmapContent) {
     // `RoadmapProgress` contract (nulls = absent) is unchanged.
     const table = locateProgressTable(roadmapContent);
     if (table) {
-        const allRows = table.rows;
+        // #5165: the milestone-grouped Progress table (templates/roadmap.md) keeps
+        // every milestone's rows, shipped ones included. When the caller names the
+        // milestone and the table carries a `Milestone` column, count only that
+        // milestone's rows. A table without the column (or a caller without a
+        // milestone) keeps the whole-table behavior; a named milestone that matches
+        // no row yields nulls (nothing countable) rather than a foreign count.
+        const wantMilestone = normalizeMilestoneToken(milestoneFilter);
+        const scopedRows = wantMilestone !== '' && table.columns.includes('Milestone')
+            ? table.rows.filter((r) => normalizeMilestoneToken(r['Milestone']) === wantMilestone)
+            : table.rows;
         // Data rows only (exclude sentinel phases 0 and 999.x).
         // #3185: canonical sentinel predicate (SENTINEL_RANGES [0,999]) — this was a local 999-only literal that admitted Phase 0.
-        const dataRows = allRows.filter((r) => {
+        const dataRows = scopedRows.filter((r) => {
             const phase = (r['Phase'] ?? '').trim();
             return /^\d/.test(phase) && !isSentinelPhaseId(phase);
         });
@@ -110,7 +143,7 @@ function deriveProgressFromRoadmap(roadmapContent) {
         const completed = dataRows.filter((r) => (0, phase_status_cjs_1.parseRoadmapStatusCell)(r['Status']) === phase_status_cjs_1.WIRE_STATUS.COMPLETE).length;
         completedPhases = completed > 0 ? completed : null;
         let totalPlansSum = 0;
-        for (const r of allRows) {
+        for (const r of scopedRows) {
             const cell = (r['Plans Complete'] ?? '').trim();
             const m = /(\d+)\s*\/\s*(\d+)/.exec(cell);
             if (m)

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

@@ -54,13 +54,13 @@ const planningScopeMod = require("./planning-scope.cjs");
 const { SCOPE } = planningScopeMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- roadmap-parser.cjs is an export= CommonJS module
 const roadmapParserMod = require("./roadmap-parser.cjs");
-const { stripShippedMilestones, extractCurrentMilestone, currentMilestoneRawRanges, withPhaseSection, findMilestoneScopeHeadingLines } = roadmapParserMod;
+const { stripShippedMilestones, extractCurrentMilestone, currentMilestoneRawRanges, withPhaseSection, editOutsideShippedBlocks, findMilestoneScopeHeadingLines } = roadmapParserMod;
 // #4129: the single owner of "count the ROADMAP's milestone Complete rows"
 // (pure computation, no I/O — no cycle on this path) for the intent-first
 // progress counters the phase-complete transaction passes downstream.
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-lifecycle.cjs is an export= CommonJS module
 const phaseLifecycleMod = require("./phase-lifecycle.cjs");
-const { deriveProgressFromRoadmap: deriveProgressFromRoadmapForIntent, clampPercent: clampPercentForIntent } = phaseLifecycleMod;
+const { deriveProgressFromRoadmap: deriveProgressFromRoadmapForIntent, clampPercent: clampPercentForIntent, milestoneVersionOf, locateProgressTable, normalizeMilestoneToken } = phaseLifecycleMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-workspace.cjs is an export= CommonJS module
 const planningWorkspace = require("./planning-workspace.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- frontmatter.cjs is an export= CommonJS module
@@ -1067,6 +1067,62 @@ function describeGoalShapedTitle(description) {
     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:**.`);
 }
+/**
+ * Phase numbers the roadmap itself declares — a section header or a roadmap bullet — sentinels
+ * excluded. This is deliberately NOT the allocation set: allocation also counts on-disk directories
+ * and sibling-worktree phases so a new number cannot collide, but a `Depends on:` line has to point
+ * at something a reader of THIS roadmap can find (#5113).
+ */
+function roadmapDeclaredPhaseNums(rawContent) {
+    const { regex: headerPattern, phaseNumGroup } = buildPhaseHeadingScanRegex(PHASE_HEADING_BASELINE.LABEL_ONLY);
+    const bulletPattern = /^[ \t]*-[ \t]*\[[^\]]{0,200}\][ \t]*\*{0,2}Phase[ \t]+(\d+)(?=[:.\s*]|$)/gim;
+    const nums = new Set();
+    let m;
+    while ((m = headerPattern.exec(rawContent)) !== null) {
+        const num = parseInt(m[phaseNumGroup], 10);
+        if (!isSentinelPhaseId(num))
+            nums.add(num);
+    }
+    while ((m = bulletPattern.exec(rawContent)) !== null) {
+        const num = parseInt(m[1], 10);
+        if (!isSentinelPhaseId(num))
+            nums.add(num);
+    }
+    return [...nums];
+}
+/**
+ * The `**Depends on:**` line for a freshly added numeric phase: the nearest lower phase the roadmap
+ * declares, or `Nothing` when it declares none. It was `newId - 1` regardless, which named a phase
+ * that exists only on a sibling branch, as an orphan directory, or not at all when numbering has a
+ * gap (#5113). Custom-named phases carry no dependency line.
+ */
+function dependsOnLine(newPhaseId, declared) {
+    if (typeof newPhaseId !== 'number')
+        return '';
+    let nearest = null;
+    for (const n of declared)
+        if (n < newPhaseId && (nearest === null || n > nearest))
+            nearest = n;
+    return `\n**Depends on:** ${nearest === null ? 'Nothing' : `Phase ${nearest}`}`;
+}
+/**
+ * Splice a phase entry into `rawContent` at `at`, changing nothing else: the blank lines around the
+ * block and its line endings are the block's own, so the surrounding document is published byte for
+ * byte (#5113). `block` is LF text that starts and ends with a newline.
+ */
+function spliceRoadmapBlock(rawContent, atOffset, block) {
+    const eol = rawContent.includes('\r\n') ? '\r\n' : '\n';
+    // The insertion offset is found by searching for '\n---', which lands between the CR and the LF of
+    // a CRLF pair; splice before the pair instead of through it.
+    const at = rawContent[atOffset - 1] === '\r' && rawContent[atOffset] === '\n' ? atOffset - 1 : atOffset;
+    const before = rawContent.slice(0, at);
+    const after = rawContent.slice(at);
+    const body = block.replace(/^\n+/, '').replace(/\n+$/, '\n').replace(/\n/g, eol);
+    const blankBefore = before === '' || /(?:\r?\n){2}$/.test(before);
+    const lead = blankBefore ? '' : /\n$/.test(before) ? eol : eol + eol;
+    const tail = after === '' || /^\r?\n/.test(after) ? '' : eol;
+    return before + lead + body + tail + after;
+}
 /**
  * #3163: compute the byte offset in `rawContent` where a new `### Phase N:`
  * entry should be inserted — at the end of the active phase list, scoped to the
@@ -1169,7 +1225,7 @@ function collectSiblingWorktreePhaseNums(cwd, used) {
             timeout: 10_000,
             windowsHide: true,
             maxBuffer: 4 * 1024 * 1024,
-        });
+        }); // allow-index-refresh: lists worktrees from .git metadata, never opens the index
     }
     catch {
         return; // not a git repo / git unavailable — unchanged behavior
@@ -1310,13 +1366,11 @@ function cmdPhaseAdd(cwd, description, raw, customId) {
         const dirPath = node_path_1.default.join(planningDir(cwd), 'phases', _dirName);
         (0, shell_command_projection_cjs_1.platformEnsureDir)(dirPath);
         (0, shell_command_projection_cjs_1.platformWriteSync)(node_path_1.default.join(dirPath, '.gitkeep'), '');
-        const dependsOn = config.phase_naming === 'custom'
-            ? ''
-            : `\n**Depends on:** Phase ${typeof _newPhaseId === 'number' ? _newPhaseId - 1 : 'TBD'}`;
+        const dependsOn = config.phase_naming === 'custom' ? '' : dependsOnLine(_newPhaseId, roadmapDeclaredPhaseNums(rawContent));
         const phaseEntry = `\n### Phase ${_newPhaseId}: ${description}\n\n**Goal:** [To be planned]\n**Requirements**: TBD${dependsOn}\n**Plans:** 0 plans\n\nPlans:\n- [ ] TBD (run ${(0, runtime_slash_cjs_1.formatGsdSlash)('plan-phase', (0, runtime_slash_cjs_1.resolveRuntime)(cwd))} ${_newPhaseId} to break down)\n`;
         const insertAt = phaseEntryInsertOffset(rawContent, cwd);
-        const updatedContent = rawContent.slice(0, insertAt) + phaseEntry + rawContent.slice(insertAt);
-        (0, shell_command_projection_cjs_1.platformWriteSync)(roadmapPath, updatedContent);
+        const updatedContent = spliceRoadmapBlock(rawContent, insertAt, phaseEntry);
+        (0, shell_command_projection_cjs_1.platformWriteSync)(roadmapPath, updatedContent, { verbatim: true });
         return { newPhaseId: _newPhaseId, dirName: _dirName };
     });
     const titleWarning = describeGoalShapedTitle(description);
@@ -1432,12 +1486,10 @@ function cmdPhaseAddBatch(cwd, descriptions, raw) {
             const dirPath = node_path_1.default.join(planningDir(cwd), 'phases', dirName);
             (0, shell_command_projection_cjs_1.platformEnsureDir)(dirPath);
             (0, shell_command_projection_cjs_1.platformWriteSync)(node_path_1.default.join(dirPath, '.gitkeep'), '');
-            const dependsOn = config.phase_naming === 'custom'
-                ? ''
-                : `\n**Depends on:** Phase ${typeof newPhaseId === 'number' ? newPhaseId - 1 : 'TBD'}`;
+            const dependsOn = config.phase_naming === 'custom' ? '' : dependsOnLine(newPhaseId, roadmapDeclaredPhaseNums(rawContent));
             const phaseEntry = `\n### Phase ${newPhaseId}: ${description}\n\n**Goal:** [To be planned]\n**Requirements**: TBD${dependsOn}\n**Plans:** 0 plans\n\nPlans:\n- [ ] TBD (run ${(0, runtime_slash_cjs_1.formatGsdSlash)('plan-phase', (0, runtime_slash_cjs_1.resolveRuntime)(cwd))} ${newPhaseId} to break down)\n`;
             const insertAt = phaseEntryInsertOffset(rawContent, cwd);
-            rawContent = rawContent.slice(0, insertAt) + phaseEntry + rawContent.slice(insertAt);
+            rawContent = spliceRoadmapBlock(rawContent, insertAt, phaseEntry);
             added.push({
                 phase_number: typeof newPhaseId === 'number' ? newPhaseId : String(newPhaseId),
                 padded: typeof newPhaseId === 'number' ? String(newPhaseId).padStart(2, '0') : String(newPhaseId),
@@ -1447,7 +1499,7 @@ function cmdPhaseAddBatch(cwd, descriptions, raw) {
                 naming_mode: config.phase_naming,
             });
         }
-        (0, shell_command_projection_cjs_1.platformWriteSync)(roadmapPath, rawContent);
+        (0, shell_command_projection_cjs_1.platformWriteSync)(roadmapPath, rawContent, { verbatim: true });
         return added;
     });
     output({ phases: results, count: results.length }, raw);
@@ -1525,6 +1577,21 @@ function scanExistingDecimalPhaseNumbers(phasesDir, rawContent, base) {
     }
     return decimalSet;
 }
+/**
+ * #5599: true when `token` (a heading/bullet phase number such as "13.1.2") is
+ * a STRICT descendant of `ancestor` ("13"). Compared segment-wise so "130" is
+ * not inside "13", and digit segments compare numerically so a zero-padded
+ * "05.1" matches "5".
+ */
+function isPhaseTokenWithin(token, ancestor) {
+    const t = token.split('.');
+    const a = ancestor.split('.');
+    if (t.length <= a.length)
+        return false;
+    // Zero padding is not significant ("05" = "5", "03A" = "3A"); case is not either.
+    const canon = (segment) => segment.replace(/^0+(?=\d)/, '').toLowerCase();
+    return a.every((segment, i) => canon(segment) === canon(t[i]));
+}
 function cmdPhaseInsert(cwd, afterPhase, description, raw, allocation = 'nested') {
     if (!afterPhase || !description) {
         error('after-phase and description required for phase insert');
@@ -1586,6 +1653,11 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw, allocation = 'nested'
             const siblingNextDecimal = siblingDecimalSet.size === 0 ? 1 : Math.max(...siblingDecimalSet) + 1;
             _decimalPhase = `${parentBase}.${siblingNextDecimal}`;
         }
+        // #5599: the family whose subtree the new entry must land at the end of —
+        // the parent for a sibling allocation, the target itself for a nested one.
+        const subtreeRoot = allocation === 'sibling' && lastDotIndex !== -1
+            ? normalizedBase.slice(0, lastDotIndex)
+            : normalizedBase;
         const insertConfig = loadConfig(cwd);
         const projectCode = insertConfig.project_code || '';
         const pfx = projectCode ? `${projectCode}-` : '';
@@ -1623,13 +1695,17 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw, allocation = 'nested'
             }
             const bulletLineEnd = rawContent.indexOf(bulletMatchResult[0]) + bulletMatchResult[0].length;
             const afterBullet = rawContent.slice(bulletLineEnd);
-            const nextBulletMatch = afterBullet.match(/\r?\n-\s*\[[ x]\]\s*(?:\*\*)?Phase\s+\d/i);
-            let insertIdx;
-            if (nextBulletMatch) {
-                insertIdx = bulletLineEnd + nextBulletMatch.index;
-            }
-            else {
-                insertIdx = bulletLineEnd;
+            // #5599: land after the last bullet inside the allocation family's
+            // subtree, not before the first following bullet of any number (which is
+            // the target's own later decimal child when one exists).
+            const bulletRe = /\r?\n-\s*\[[ x]\]\s*(?:\*\*)?Phase\s+(?<tok>\d[^\s:*]*)[^\r\n]*/gi;
+            let insertIdx = bulletLineEnd;
+            for (const m of afterBullet.matchAll(bulletRe)) {
+                if (!isPhaseTokenWithin(m.groups.tok, subtreeRoot)) {
+                    insertIdx = bulletLineEnd + m.index;
+                    break;
+                }
+                insertIdx = bulletLineEnd + m.index + m[0].length;
             }
             updatedContent =
                 rawContent.slice(0, insertIdx) + bulletEntry + rawContent.slice(insertIdx);
@@ -1671,13 +1747,19 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw, allocation = 'nested'
             // preserved exactly as the prior literal had it — a pre-existing,
             // deliberately-unchanged asymmetry with the other sites in this file.
             const nextPhaseHeadingPrefix = `#{2,4}\\s+${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY, insertConvention)}`;
-            const nextPhaseMatch = afterHeader.match(new RegExp(`\\r?\\n${nextPhaseHeadingPrefix}\\d[\\d.]*`, 'i'));
-            let insertIdx;
-            if (nextPhaseMatch) {
-                insertIdx = headerIdx + headerMatch[0].length + nextPhaseMatch.index;
-            }
-            else {
-                insertIdx = rawContent.length;
+            // #5599: the boundary is the first following heading OUTSIDE the
+            // allocation family's subtree. Taking the first heading of any number
+            // spliced the new section above the target's own later decimal children
+            // (13, 13.2, 13.1, 14); the allocator already guarantees the new number
+            // exceeds every existing descendant, so "after the last descendant" is
+            // the numerically correct position.
+            const nextPhaseRe = new RegExp(`\\r?\\n${nextPhaseHeadingPrefix}(?<tok>\\d[^\\s:]*)`, 'gi');
+            let insertIdx = rawContent.length;
+            for (const m of afterHeader.matchAll(nextPhaseRe)) {
+                if (!isPhaseTokenWithin(m.groups.tok, subtreeRoot)) {
+                    insertIdx = headerIdx + headerMatch[0].length + m.index;
+                    break;
+                }
             }
             updatedContent =
                 rawContent.slice(0, insertIdx) + phaseEntry + rawContent.slice(insertIdx);
@@ -3061,6 +3143,42 @@ function formatRequirementsLineWarning(phaseNum, rawLine, analysis) {
             oversized,
     };
 }
+/**
+ * #4972: advisory gaps for the phase artifacts that active `verify:post` steps
+ * declared `onError: "halt"` and `produces` (SECURITY.md, VALIDATION.md).
+ * Missing file, an unresolved `status: draft`, or (SECURITY.md) `threats_open`
+ * above zero. Any other `status` spelling counts as closed — the audit skills
+ * do not pin one value, so this does not invent a vocabulary.
+ */
+function auditArtifactWarnings(cwd, phaseFullDir) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports -- lazy: loop-resolver pulls in the capability registry
+    const loopResolver = require('./loop-resolver.cjs');
+    const out = [];
+    const files = node_fs_1.default.readdirSync(phaseFullDir);
+    for (const hook of loopResolver.resolveActiveHooksForPoint(cwd, 'verify:post').activeHooks) {
+        if (hook.kind !== 'step' || hook.onError !== 'halt')
+            continue;
+        for (const artifact of hook.produces ?? []) {
+            if (!/^[A-Z][A-Z0-9-]*\.md$/.test(artifact))
+                continue;
+            const skill = hook.ref?.skill ?? hook.capId;
+            const found = files.filter((f) => f === artifact || f.endsWith(`-${artifact}`)).sort()[0];
+            if (!found) {
+                out.push(`${artifact}: missing — the ${hook.capId} audit (/gsd:${skill}) never ran for this phase, and a verify:post step cannot block the close (#4972)`);
+                continue;
+            }
+            const fm = frontmatterMod.extractFrontmatter(node_fs_1.default.readFileSync(node_path_1.default.join(phaseFullDir, found), 'utf-8'));
+            if (typeof fm['status'] === 'string' && fm['status'].trim().toLowerCase() === 'draft') {
+                out.push(`${found}: status is still draft — the ${hook.capId} audit (/gsd:${skill}) was not completed (#4972)`);
+            }
+            const open = Number(fm['threats_open']);
+            if (artifact === 'SECURITY.md' && Number.isFinite(open) && open > 0) {
+                out.push(`${found}: ${open} threat(s) still open (#4972)`);
+            }
+        }
+    }
+    return out;
+}
 function cmdPhaseComplete(cwd, phaseNum, raw) {
     if (!phaseNum) {
         error('phase number required for phase complete');
@@ -3274,6 +3392,23 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
         /* best-effort, same posture as the #2245 pre-scan above: an unreadable
          * SUMMARY means one fewer advisory this run, never a blocked completion. */
     }
+    // #4972: a `verify:post` STEP declared `onError: "halt"` that produces a
+    // phase artifact (security -> SECURITY.md, nyquist -> VALIDATION.md) reads as
+    // a blocking precondition, but a step is advisory by construction (ADR-894
+    // "steps are additive, gates block") and the workflow only prints a line the
+    // operator can ignore — so a phase could close with the audit never run. This
+    // verb is the one place every close passes through, so it names the gap on
+    // the same ADVISORY `warnings[]` channel as the #2572 check above. Advisory,
+    // not a refusal: both capabilities are on by default, so a hard block here
+    // would stop every existing project's next phase close; the security
+    // threats-open gate at `ship:pre` is the enforced one and is untouched.
+    try {
+        warnings.push(...auditArtifactWarnings(cwd, phaseFullDir));
+    }
+    catch {
+        /* best-effort, same posture as the advisories above: an unresolvable hook
+         * set or unreadable artifact means one fewer advisory, never a blocked close. */
+    }
     let nextPhaseNum = null;
     let nextPhaseName = null;
     let isLastPhase = true;
@@ -3346,6 +3481,10 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
         const runPhaseCompleteTransaction = () => {
             const writes = [];
             let roadmapContent = null;
+            // #5165: the phase was ALREADY complete in the ROADMAP this transaction
+            // started from (read before any mutation below): its checklist box was
+            // checked, or its Progress-table row read Complete.
+            let phaseWasAlreadyComplete = false;
             if (node_fs_1.default.existsSync(roadmapPath)) {
                 const originalRoadmapContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
                 roadmapContent = originalRoadmapContent;
@@ -3383,6 +3522,12 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                 // 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');
+                // #5165: pre-mutation read of the same checklist line, checked this time.
+                const checkedBoxPattern = new RegExp(`^[ \\t]*(-\\s*\\[)[xX](\\]\\s*(?:\\*\\*)?\\s*Phase\\s+${phaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s][^\\n]*)`);
+                const originalMilestoneScope = extractCurrentMilestone(originalRoadmapContent, cwd);
+                phaseWasAlreadyComplete = originalMilestoneScope
+                    .split('\n')
+                    .some((line) => checkedBoxPattern.test(line));
                 // 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
@@ -3399,6 +3544,22 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                 const phaseCellRe = new RegExp(`^${phaseEscaped}\\.?(?:\\s|$)`, 'i');
                 const rowMatch = (row) => phaseCellRe.test((row['Phase'] ?? '').trim());
                 const dateShape = /^\d{4}-\d{2}-\d{2}$/;
+                // #5165: a ROADMAP whose checklist box was never ticked (or has none) but
+                // whose Progress-table row already reads Complete is just as complete. A
+                // milestone-grouped table (a `Milestone` column) is read only for the
+                // milestone ROADMAP binds, so a shipped milestone's same-numbered phase
+                // cannot count.
+                if (!phaseWasAlreadyComplete) {
+                    const progressTable = locateProgressTable(originalMilestoneScope);
+                    if (progressTable !== null) {
+                        const wantMilestone = progressTable.columns.includes('Milestone')
+                            ? normalizeMilestoneToken(roadmapParserMod.getMilestoneInfo(cwd).value?.version)
+                            : null;
+                        phaseWasAlreadyComplete = progressTable.rows.some((row) => rowMatch(row)
+                            && (0, phase_status_cjs_1.parseRoadmapStatusCell)(row['Status']) === phase_status_cjs_1.WIRE_STATUS.COMPLETE
+                            && (wantMilestone === null || (wantMilestone !== '' && normalizeMilestoneToken(row['Milestone']) === wantMilestone)));
+                    }
+                }
                 /**
                  * Within `text` (already scoped to one milestone window by the
                  * caller), scope further to the `## Progress` heading section (up to
@@ -3536,7 +3697,11 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                         const plansResult = (0, markdown_table_cjs_1.updateTableCell)(text, rowMatch, 'Plans Complete', ` ${summaryCount}/${planCount} `);
                         if (plansResult.ok)
                             text = plansResult.value;
-                        const statusResult = (0, markdown_table_cjs_1.updateTableCell)(text, rowMatch, 'Status', ` ${(0, phase_status_cjs_1.toRoadmapStatusCell)(phase_status_cjs_1.PHASE_STATUS.COMPLETE).padEnd(11)} `);
+                        // #5165: a Status cell that already reads Complete is left untouched —
+                        // re-padding it rewrote a cell the re-run had no business editing.
+                        const statusResult = (0, markdown_table_cjs_1.updateTableCell)(text, rowMatch, 'Status', (current) => (0, phase_status_cjs_1.parseRoadmapStatusCell)(current) === phase_status_cjs_1.WIRE_STATUS.COMPLETE
+                            ? current
+                            : ` ${(0, phase_status_cjs_1.toRoadmapStatusCell)(phase_status_cjs_1.PHASE_STATUS.COMPLETE).padEnd(11)} `);
                         if (statusResult.ok)
                             text = statusResult.value;
                         // Preserve only a valid ISO date (#1161: idempotent; self-heal
@@ -3562,12 +3727,15 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                             const planId = summaryFile.replace('-SUMMARY.md', '').replace('SUMMARY.md', '');
                             if (!planId)
                                 continue;
-                            const planEscaped = (0, pattern_cjs_1.escapeRegex)(planId);
+                            // #5542: only a summary paired with a live (non-superseded) plan
+                            // flips a row — the same pairing rule the counts use.
+                            if (!coreUtilsMod.summaryPairsWithAnyPlan(phaseInfo['plans'] ?? [], summaryFile))
+                                continue;
                             // ADR-5057 §6 (Phase 13, #5217): the per-plan flip is a bullet
                             // mutation, so it goes through `updateBullet` like the phase
                             // checkbox flip above — first matching bullet only, never a
                             // fenced line, never a mid-line occurrence.
-                            const planCheckboxPattern = new RegExp(`^(\\s*-\\s*\\[) (\\]\\s*(?:\\*\\*)?${planEscaped}(?:\\*\\*)?)`, 'i');
+                            const planCheckboxPattern = coreUtilsMod.planRowPattern(planId, { anchored: true });
                             b = (0, markdown_sectionizer_cjs_1.updateBullet)(b, (_bulletText, rawLine) => planCheckboxPattern.test(rawLine), (rawLine) => rawLine.replace(planCheckboxPattern, '$1x$2'));
                         }
                         return b;
@@ -3589,7 +3757,13 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                     }
                 }
                 else {
-                    roadmapContent = mutateMilestonePhase(roadmapContent);
+                    // #5543: the active milestone could not be resolved (no STATE
+                    // `milestone:`, no marker). Writing the whole document would let
+                    // `withPhaseSection` pick the first `### Phase N:` in document order,
+                    // which can sit inside a shipped `<details>` block. Hide the shipped
+                    // blocks from the mutation and restore them untouched; a ROADMAP with
+                    // no shipped block is mutated whole, as before.
+                    roadmapContent = editOutsideShippedBlocks(roadmapContent, mutateMilestonePhase);
                 }
                 writes.push({
                     filePath: roadmapPath,
@@ -4183,6 +4357,19 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
             }
             if (node_fs_1.default.existsSync(statePath)) {
                 const originalStateContent = (0, shell_command_projection_cjs_1.platformReadSync)(statePath) || '';
+                // #5165: the milestone STATE asserts (ROADMAP-bound identity first,
+                // else STATE's own frontmatter) scopes the post-completion progress
+                // derivation to that milestone's Progress-table rows.
+                const stateFm = frontmatterMod.extractFrontmatter(originalStateContent, statePath);
+                const storedMilestone = roadmapParserMod.getMilestoneInfo(cwd).value?.version
+                    ?? milestoneVersionOf(stateFm['milestone']);
+                // #5165: re-completing a phase that is already complete in ROADMAP.md
+                // while STATE has moved past it is a no-op for STATE's position —
+                // the transition, the metrics row and the authoritative current-phase
+                // pin would all rewind it. A first-time completion (box unchecked, or
+                // STATE not past N, #2028 out-of-order) still transitions.
+                const stateAlreadyPast = phaseWasAlreadyComplete
+                    && (0, state_transition_cjs_1.isStatePastPhase)(originalStateContent, phaseNum, statePath);
                 let stateContent = originalStateContent;
                 // ADR-1769 Phase 3: the STATE.md field-update policy (Current Phase
                 // shape/name, Status, Current Plan, Last Activity + Description, and
@@ -4197,8 +4384,10 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                 // NOT go through readModifyWriteStateMd because STATE.md is
                 // committed atomically with ROADMAP/REQUIREMENTS, ADR-3408 §8.3 /
                 // #3374 / #3469).
-                const nextPhaseDisplayName = phaseDisplayNameFromRoadmap(roadmapContent, nextPhaseNum) ??
-                    phaseDisplayNameFromSlug(nextPhaseName);
+                const nextPhaseDisplayName = stateAlreadyPast
+                    ? null
+                    : phaseDisplayNameFromRoadmap(roadmapContent, nextPhaseNum) ??
+                        phaseDisplayNameFromSlug(nextPhaseName);
                 // #4824: classify the SELECTED next phase from disk (the same ladder
                 // roadmap analyze uses) so the Status / Current Plan / Stopped-at
                 // handoff does not say "ready to plan" for a phase already planned or
@@ -4219,7 +4408,7 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                         /* best-effort: an unreadable next phase keeps `Ready to plan` */
                     }
                 }
-                const completeResult = (0, state_transition_cjs_1.transitionCore)(stateContent, {
+                const completeResult = stateAlreadyPast ? { content: stateContent } : (0, state_transition_cjs_1.transitionCore)(stateContent, {
                     kind: 'completePhase',
                     phaseNum,
                     nextPhaseNum,
@@ -4228,13 +4417,22 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                     planCount,
                     summaryCount,
                     nextPhaseDisk,
+                    // #5165: the body counter and the frontmatter progress below count the
+                    // SAME milestone's Progress rows.
+                    milestone: storedMilestone,
                 }, {
                     clock: clock_cjs_1.realClock,
-                    roadmapProvider: () => roadmapContent,
+                    // #4901: the body counter derives from the same current-milestone scope
+                    // as its frontmatter twin below (postCompletionRoadmapScope), not the
+                    // whole file, so the two writers cannot disagree on which
+                    // `## Progress` table they count.
+                    roadmapProvider: () => (roadmapContent !== null ? extractCurrentMilestone(roadmapContent, cwd) : null),
                     sourcePath: statePath,
                 });
                 stateContent = completeResult.content;
-                stateContent = updatePerformanceMetricsSection(stateContent, cwd, phaseNum, planCount, summaryCount);
+                if (!stateAlreadyPast) {
+                    stateContent = updatePerformanceMetricsSection(stateContent, cwd, phaseNum, planCount, summaryCount);
+                }
                 // #2736: the transition holds the next phase's exact display name in
                 // the intent; pass it as authoritative so the sync's prose
                 // re-derivation cannot rewrite current_phase_name to the name's own
@@ -4267,7 +4465,7 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                     ? extractCurrentMilestone(roadmapContent, cwd)
                     : null;
                 const postCompletionRoadmapProgress = postCompletionRoadmapScope !== null
-                    ? deriveProgressFromRoadmapForIntent(postCompletionRoadmapScope)
+                    ? deriveProgressFromRoadmapForIntent(postCompletionRoadmapScope, storedMilestone)
                     : null;
                 const authoritativeProgress = postCompletionRoadmapProgress && postCompletionRoadmapProgress.completedPhases !== null
                     ? postCompletionRoadmapProgress.totalPhases !== null && postCompletionRoadmapProgress.totalPhases > 0

package/gsd-core/bin/lib/planning-snapshot.cjs

@@ -129,7 +129,9 @@ function buildPhaseSnapshot(phasesDir, dir, convention) {
         dir,
         complete: completionResult.value.complete,
         verificationStatus: completionResult.value.verification.status,
-        verificationStatusError: statusError ? { file: statusError.file, message: statusError.message } : null,
+        verificationStatusError: statusError
+            ? { file: statusError.file, message: statusError.message, rawStatus: statusError.rawStatus }
+            : null,
         planCount: scanResult.planCount,
         summaryCount: scanResult.summaryCount,
         scope: worstScope(completionResult.scope, scanResult.scope),

package/gsd-core/bin/lib/planning-workspace.cjs

@@ -630,6 +630,22 @@ function findContextMdIn(absDirOrFiles) {
         return { file: null, files: [], scope: SCOPE.UNREADABLE };
     }
 }
+/**
+ * Is `name` the phase's requirements SPEC (#5629)? A plain `NN-SPEC.md`: the `-AI-SPEC.md` (AI design
+ * contract) and `-UI-SPEC.md` (UI design contract) variants have other purposes and never lock requirements.
+ * The one definition behind the init payloads' `has_spec` / `spec_path`, the discuss and plan-phase workflows
+ * (which read those fields) and the context-drift gate, so they cannot disagree about which file is "the SPEC".
+ */
+function isPhaseSpecFile(name) {
+    return name.endsWith('-SPEC.md') && !name.endsWith('-AI-SPEC.md') && !name.endsWith('-UI-SPEC.md');
+}
+/**
+ * The phase SPEC in an already-read directory listing, or `null`. The lexically first match, so the answer
+ * does not depend on the filesystem's readdir order. The caller's array is not reordered.
+ */
+function findPhaseSpecIn(files) {
+    return files.filter(isPhaseSpecFile).sort()[0] ?? null;
+}
 module.exports = {
     worktreesOptedOut,
     readScopedConfigValue,
@@ -655,6 +671,8 @@ module.exports = {
     diagnoseUnresolvedActiveWorkstream,
     describeUnresolvedWorkstreamReason,
     findContextMdIn,
+    isPhaseSpecFile,
+    findPhaseSpecIn,
     // Test seam (audit M1): inject a deterministic isPidAlive so the liveness-gated
     // steal decision is exercised without real pids. Mirrors capability-lock.cts.
     _setLockProbes(probes) {

package/gsd-core/bin/lib/pristine-baseline.cjs

@@ -34,6 +34,7 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_crypto_1 = __importDefault(require("node:crypto"));
 const node_child_process_1 = require("node:child_process");
+const read_only_git_env_cjs_1 = require("./read-only-git-env.cjs");
 /**
  * SHA-256 hex digest of a file's raw bytes. Byte-for-byte the same digest
  * install.js fileHash() records into manifests and backup-meta.json.
@@ -144,13 +145,20 @@ function isCleanRelativePosixPath(relPath) {
 }
 function gitExec(gitDir, args) {
     return (0, node_child_process_1.execFileSync)('git', args, {
+        // windowsHide (#685): a console-window flash per git call would spam the
+        // user on Windows for what is a background, read-only history walk. Kept
+        // high in the options so the completeness guard's 400-char scan finds it.
+        windowsHide: true,
         cwd: gitDir,
         encoding: 'utf8',
+        // #5048: every call here is a history/objects walk that never opens the
+        // index, so the variable is inert today — set anyway so a future `status` /
+        // `diff` caller inherits it. The block is owned by
+        // src/read-only-git-env.cts and shared with every other read-only seam.
+        // Parity: tests/git-optional-locks-parity.test.cjs.
+        env: (0, read_only_git_env_cjs_1.readOnlyGitEnv)(),
         timeout: GIT_SUBPROCESS_TIMEOUT_MS,
         maxBuffer: GIT_MAX_BUFFER_BYTES,
-        // windowsHide (#685): a console-window flash per git call would spam the
-        // user on Windows for what is a background, read-only history walk.
-        windowsHide: true,
         // stderr is discarded: "file absent in commit" is an expected walk outcome,
         // not operator-visible diagnostics.
         stdio: ['ignore', 'pipe', 'ignore'],