@opengsd/gsd-core 1.18.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
@@ -1225,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
@@ -1577,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');
@@ -1638,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}-` : '';
@@ -1675,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);
@@ -1723,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);
@@ -3451,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;
@@ -3488,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
@@ -3504,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
@@ -3641,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
@@ -3667,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;
@@ -3694,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,
@@ -4288,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
@@ -4302,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
@@ -4324,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,
@@ -4333,6 +4417,9 @@ 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,
                     // #4901: the body counter derives from the same current-milestone scope
@@ -4343,7 +4430,9 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                     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
@@ -4376,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'],

package/gsd-core/bin/lib/read-only-git-env.cjs

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * read-only-git-env.cts — the single owner of the read-only git env block
+ * (#5048). CONTEXT.md / OS Shell Projection seam.
+ *
+ * By default `git status` refreshes the index and takes an *optional*
+ * `.git/index.lock` to write the refreshed copy back. That is a write the caller
+ * never asked for, and it turns a pure read into a contender for the lock a
+ * real `git add` / `git commit` needs — so a read-only statusline render can
+ * make a concurrent commit fail with
+ * `Unable to create '.git/index.lock': File exists`. `GIT_OPTIONAL_LOCKS=0`
+ * tells git to skip only those *optional* index operations. Nothing a read
+ * needs is lost: `git status` reads the index, it just doesn't need to rewrite
+ * it.
+ *
+ * ## Why this module exists
+ *
+ * The block used to be hand-written at every seam that spawns git for a read.
+ * Six copies of `{ ...process.env, GIT_OPTIONAL_LOCKS: '0' }` is six places to
+ * forget when a seam is added, and a probe that checks each seam for the literal
+ * value passes even when a seam stopped consulting the owner. One owner makes
+ * the drift structural instead: the parity test patches THIS function to a
+ * sentinel and asserts every seam's spawn carries the sentinel, so a seam that
+ * hand-writes the variable again fails red rather than passing quietly.
+ * (tests/git-optional-locks-parity.test.cjs, "#5048 every seam reads the shared
+ * owner".)
+ *
+ * ## Why the hook scripts require the built artifact
+ *
+ * `hooks/*.js` are staged as standalone files at install time, so they reach
+ * compiled `src/` modules through `../gsd-core/bin/lib/*.cjs` rather than a
+ * sibling hooks/-tree file — the same rule hooks/lib/git-cmd.js follows for
+ * token-scanner. They call `readOnlyGitEnv()` per spawn rather than snapshotting
+ * the result at module load, so a later `process.env` mutation is visible and the
+ * two behave identically.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readOnlyGitEnv = readOnlyGitEnv;
+/**
+ * Build the env for a read-only git spawn.
+ *
+ * @param base Environment to spread, `process.env` by default. Callers that
+ *   layer extra git variables on top (GIT_TERMINAL_PROMPT, a caller's own
+ *   overrides) pass them in `base`; callers that must let a caller-supplied
+ *   override win spread the result and apply their own keys afterwards.
+ * @returns A fresh object each call — never the cached `process.env`.
+ */
+function readOnlyGitEnv(base = process.env) {
+    const env = {};
+    for (const [key, value] of Object.entries(base)) {
+        // process.env carries undefined-valued keys on some platforms; spawn()
+        // rejects a non-string value rather than ignoring it.
+        if (value !== undefined)
+            env[key] = value;
+    }
+    env.GIT_OPTIONAL_LOCKS = '0';
+    return env;
+}

package/gsd-core/bin/lib/review-lane-descriptor.cjs

@@ -58,6 +58,7 @@ exports.DOCS_PARITY_VIOLATION = exports.LANE_SLUG_RE = exports.PARITY_VIOLATION
 exports.mergeReviewerLanes = mergeReviewerLanes;
 exports.checkReviewerLaneParity = checkReviewerLaneParity;
 exports.checkReviewerDocsParity = checkReviewerDocsParity;
+const text_lines_cjs_1 = require("./text-lines.cjs");
 /**
  * Argv placeholders (Phase 5b, #2799).
  *
@@ -576,6 +577,7 @@ exports.PARITY_VIOLATION = Object.freeze({
     REGISTRY_LANE_UNDECLARED: 'registry_lane_undeclared',
     DESCRIPTOR_LANE_NOT_IN_REGISTRY: 'descriptor_lane_not_in_registry',
     BESPOKE_LEG_PRESENT: 'bespoke_leg_present',
+    AVAILABILITY_FALLBACK_MISMATCH: 'availability_fallback_mismatch',
     DUPLICATE_SLUG: 'duplicate_slug',
     DUPLICATE_FLAG: 'duplicate_flag',
     DUPLICATE_SECTION: 'duplicate_section',
@@ -607,6 +609,10 @@ const LEG_MARKER_RE = /<!--\s*reviewer-lane:\s*([a-z0-9_-]+)\s*-->/g;
  * design principle of this module.
  */
 exports.LANE_SLUG_RE = /^[a-z0-9][a-z0-9_-]*$/;
+/** The workflow's availability call: `gsd_run review-lane availability ...` at command position. */
+const AVAILABILITY_CALL_RE = /^\s*gsd_run review-lane availability(?:\s|$)/;
+/** One `<slug>:missing` row in the printf fallback; slug is LANE_SLUG_RE's grammar capped at 32 chars. */
+const AVAILABILITY_FALLBACK_ROW_RE = /(?:'|\\n)([a-z0-9][a-z0-9_-]{0,31}):missing/g;
 /** Bounds of the step a bespoke leg marker could appear inside. */
 const INVOKE_STEP_RE = /<step name="invoke_reviewers">([\s\S]*?)<\/step>/;
 function sliceStep(workflowText, re) {
@@ -627,8 +633,10 @@ function countOccurrences(haystack, re) {
 }
 /**
  * Bidirectional parity across three surfaces: the descriptor, the roster
- * (`KNOWN_REVIEWER_SLUGS`), and the generated capability **registry** — plus one anti-parity
- * assertion against the workflow.
+ * (`KNOWN_REVIEWER_SLUGS`), and the generated capability **registry** — plus two assertions
+ * against the workflow: the anti-parity check, and the availability-fallback check (the workflow
+ * makes the availability call, has a fallback row per lane, and the fallback slug set equals the
+ * openai-http lanes).
  *
  * **Re-pointed by Phase 5b (#2799).** Through Phase 5a this function also required a literal
  * `<!-- reviewer-lane: <slug> -->` per lane inside `invoke_reviewers` and a literal
@@ -671,6 +679,7 @@ function checkReviewerLaneParity(input) {
     const seenSlug = new Set();
     const seenFlag = new Set();
     const seenSection = new Set();
+    const httpSlugs = new Set();
     // The declared parameter type says `ReviewerLane[]`, but this function is a
     // trust boundary — narrow from `unknown` rather than believing the annotation.
     const rawLanes = Array.isArray(descriptor) ? descriptor : [];
@@ -689,6 +698,8 @@ function checkReviewerLaneParity(input) {
         if (seenSlug.has(slug))
             add(exports.PARITY_VIOLATION.DUPLICATE_SLUG, slug);
         seenSlug.add(slug);
+        if (lane.transport === 'openai-http')
+            httpSlugs.add(slug);
         const flags = Array.isArray(lane.flags) ? lane.flags : [];
         for (const flag of flags) {
             if (typeof flag !== 'string')
@@ -740,6 +751,28 @@ function checkReviewerLaneParity(input) {
     for (const slug of markerSlugs.keys()) {
         add(exports.PARITY_VIOLATION.BESPOKE_LEG_PRESENT, slug);
     }
+    // --- the availability call's `||` fallback must name exactly the openai-http lanes ---
+    //
+    // review.md prints these rows only when an older gsd-tools lacks `review-lane availability`, so
+    // they are a second hand-kept copy of the roster. Checked only when the call is present.
+    // Anchored to the command position so a comment or prose mention cannot shadow the real call;
+    // a missing call is itself a violation (otherwise deleting it would silently skip this check).
+    const availabilityLine = (0, text_lines_cjs_1.splitLines)(workflowText).find((line) => AVAILABILITY_CALL_RE.test(line));
+    if (availabilityLine === undefined) {
+        add(exports.PARITY_VIOLATION.AVAILABILITY_FALLBACK_MISMATCH, 'no-call');
+    }
+    else {
+        if (!availabilityLine.includes('review-lane availability ||')) {
+            add(exports.PARITY_VIOLATION.AVAILABILITY_FALLBACK_MISMATCH, 'no-fallback');
+        }
+        const fallback = new Set(Array.from(availabilityLine.matchAll(AVAILABILITY_FALLBACK_ROW_RE), (m) => m[1]));
+        for (const slug of fallback)
+            if (!httpSlugs.has(slug))
+                add(exports.PARITY_VIOLATION.AVAILABILITY_FALLBACK_MISMATCH, slug);
+        for (const slug of httpSlugs)
+            if (!fallback.has(slug))
+                add(exports.PARITY_VIOLATION.AVAILABILITY_FALLBACK_MISMATCH, slug);
+    }
     return { ok: violations.length === 0, violations };
 }
 /* ------------------------------------------------------------------ *

package/gsd-core/bin/lib/review-lane-runner.cjs

@@ -32,6 +32,7 @@ exports.parseModelBanner = parseModelBanner;
 exports.parseTranscriptModel = parseTranscriptModel;
 exports.checkEgressHost = checkEgressHost;
 exports.probeLane = probeLane;
+exports.probeHttpLanes = probeHttpLanes;
 exports.writeReviewOrStub = writeReviewOrStub;
 exports.emptyOutputDiagnosis = emptyOutputDiagnosis;
 exports.handleOpencodeOutput = handleOpencodeOutput;
@@ -318,14 +319,18 @@ async function probeLane(plan, deps) {
             // Only a STRING config value names a host. `String(unknown)` would turn an object into the
             // literal '[object Object]' and probe that as a URL — a nonsense destination reported as
             // "unreachable" rather than as the misconfiguration it is.
+            // For openai-http, `plan.host` is already resolved by `resolveLanePlan` (config → default,
+            // unset sentinels like "null" handled) — probe the destination the run would use.
             const configured = deps.configGet(probe.hostConfigKey);
-            const base = (0, review_lane_invocation_cjs_1.normalizeHost)((typeof configured === 'string' ? configured : '') ||
-                (plan.transport === 'openai-http' ? plan.host : ''));
+            const base = (0, review_lane_invocation_cjs_1.normalizeHost)((plan.transport === 'openai-http' ? plan.host : '') || (typeof configured === 'string' ? configured : ''));
             if (!base) {
                 return { available: false, reason: review_lane_invocation_cjs_1.LANE_UNAVAILABLE.HOST_UNREACHABLE, detail: 'no host resolved' };
             }
-            const r = await deps.httpJson(`${base}${probe.path}`, { method: 'GET', timeoutMs: probe.timeoutMs });
-            return r.ok
+            // D7: reachable ⇒ available. Any HTTP answer (401 behind an auth proxy, 404, 3xx) proves a
+            // server is there; only a transport failure (status 0) does not. Redirects are not followed:
+            // a probe must not issue a request to a host the descriptor never named.
+            const r = await deps.httpJson(`${base}${probe.path}`, { method: 'GET', timeoutMs: probe.timeoutMs, probe: true });
+            return r.status > 0
                 ? { available: true }
                 : {
                     available: false,
@@ -341,6 +346,25 @@ async function probeLane(plan, deps) {
             };
     }
 }
+/**
+ * `<slug>:available|missing` rows for the openai-http lanes in `lanes` (all, or those in `selected`).
+ * Prerequisite binaries are not folded in: the caller reports `jq` separately. An unresolvable lane
+ * reads `missing` and its reason is returned in `warnings` rather than swallowed.
+ */
+async function probeHttpLanes(lanes, selected, resolve, deps) {
+    // Probes run concurrently (each has its own timeout); Promise.all keeps descriptor order, and
+    // warnings are collected from the results afterwards so their order never depends on resolve timing.
+    const results = await Promise.all(lanes
+        .filter((l) => l.transport === 'openai-http' && (selected.length === 0 || selected.includes(l.slug)))
+        .map(async (lane) => {
+        const r = resolve(lane);
+        const up = r.ok && (await probeLane({ ...r.plan, requiresBinaries: [] }, deps)).available;
+        return { row: `${lane.slug}:${up ? 'available' : 'missing'}`, warning: r.ok ? null : `${lane.slug}: ${r.detail}` };
+    }));
+    const rows = results.map((x) => x.row);
+    const warnings = results.flatMap((x) => (x.warning === null ? [] : [x.warning]));
+    return { rows, warnings };
+}
 /* ------------------------------------------------------------------ *
  * Empty-output policy (#2494 / #2605 / #2794)
  * ------------------------------------------------------------------ */
@@ -940,6 +964,11 @@ async function runOpenAiCompatible(plan, promptText, deps) {
     let model = plan.model;
     if (!model && plan.modelsUrl) {
         const listed = await deps.httpJson(plan.modelsUrl, { method: 'GET', timeoutMs: 2_000 });
+        // A redirect is a lane failure, not "discovery found nothing" (#5433): the host answered with
+        // somewhere else to go, so the configured URL is wrong and the completions request would be too.
+        if (listed.status >= 300 && listed.status < 400 && listed.error) {
+            return { review: '', rawBody: listed.error, model: recordedModel(plan.fallbackModel, exports.MODEL_SOURCE.REQUESTED) };
+        }
         if (listed.ok) {
             try {
                 const parsed = JSON.parse(listed.body);