@opengsd/gsd-core 1.14.0 → 1.16.0

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

@@ -32,7 +32,7 @@ bracketMilestoneIntroSrcFor, } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapParserMod = require("./roadmap-parser.cjs");
 // #3642: hasMilestoneSectioning no longer consumed here — its >=2 semantics answered sibling conflation, but this branch asks asserted-vs-section (>=1). It stays exported from roadmap-parser.cjs for its unit pins.
-const { getMilestoneInfo, extractCurrentMilestone, isMilestoneBoundedInRoadmap, hasAnyMilestoneSection } = roadmapParserMod;
+const { getMilestoneInfo, extractCurrentMilestone, isMilestoneBoundedInRoadmap, hasAnyMilestoneSection, classifyMilestoneScalar } = roadmapParserMod;
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
@@ -60,7 +60,7 @@ const coreUtilsMod = require("./core-utils.cjs");
 const planDependencyGraphMod = require("./plan-dependency-graph.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const verificationMod = require("./verification.cjs");
-const { isPhaseComplete } = verificationMod;
+const { isPhaseComplete, VerificationStatusError } = verificationMod;
 // #4129: the single owner of "count the ROADMAP's milestone Complete rows"
 // (phase-lifecycle.cts) — reused for the completed-phases numerator floor so
 // this scan cannot grow a second ROADMAP parser. Pure computation module (no
@@ -1080,7 +1080,7 @@ function computeUpdateProgressPreview(statePath, cwd) {
     const existingFm = extractFrontmatter(preContent, statePath);
     const preBody = stripFrontmatter(preContent);
     const storedMilestone = typeof existingFm['milestone'] === 'string' ? existingFm['milestone'] : null;
-    const builtFm = buildStateFrontmatter(preBody, cwd, storedMilestone, readStoredTotalPhases(existingFm), readStoredCompletedPhases(existingFm), readStoredTotalPlans(existingFm), readStoredCompletedPlans(existingFm));
+    const builtFm = buildStateFrontmatter(preBody, cwd, storedMilestone, readStoredTotalPhases(existingFm), readStoredCompletedPhases(existingFm), readStoredTotalPlans(existingFm), readStoredCompletedPlans(existingFm), isMilestoneExplicitlyNull(existingFm));
     const progress = builtFm['progress'];
     const percent = progress && typeof progress['percent'] === 'number' ? progress['percent'] : null;
     const completedPlans = progress && typeof progress['completed_plans'] === 'number' ? progress['completed_plans'] : null;
@@ -1609,10 +1609,31 @@ function cmdStateRecordSession(cwd, options, raw) {
     const updated = [];
     let sessionCreated = false;
     const divergedFields = [];
+    // #4763 (1): last-writer-wins stays (the recorded single-slot handoff design),
+    // but a displaced record is no longer silent. The pre-write session record is
+    // captured below and surfaced in the payload under `replacedRecord` whenever a
+    // replacement actually changes a non-empty prior value.
+    const priorRecord = {};
     // ADR-3473 §8.7 (#3872): caller-allocated out-param, filled with the
     // transaction's own pre-write snapshot + body by `applyPostSyncPreservation`.
     const preWriteState = {};
     readModifyWriteStateMd(statePath, (content) => {
+        // #4763 (1): read the pre-write session record. The capture mirrors the
+        // WRITER, not the snapshot reader: stateReplaceField replaces the FIRST
+        // case-insensitive label match anywhere in the document, so the capture is
+        // document-wide too — scoping it to ## Session would miss an archive-section
+        // line the writer actually displaced. Continuation lines join via
+        // stateFieldContinuation (the sanctioned joiner — stateExtractField alone is
+        // first-line-only), so a wrapped multi-line handoff is surfaced whole.
+        const capturePrior = (fieldName) => {
+            const first = (0, state_document_cjs_1.stateExtractField)(content, fieldName);
+            if (first === null)
+                return undefined;
+            const cont = (0, state_document_cjs_1.stateFieldContinuation)(content, fieldName);
+            return cont ? `${first}\n${cont}` : first;
+        };
+        priorRecord.stoppedAt = capturePrior('Stopped At');
+        priorRecord.resumeFile = capturePrior('Resume File');
         // Update Last session / Last Date
         let result = (0, state_document_cjs_1.stateReplaceField)(content, 'Last session', now);
         if (result) {
@@ -1836,6 +1857,27 @@ function cmdStateRecordSession(cwd, options, raw) {
         const result = { recorded: true, updated: reconciledUpdated };
         if (sessionCreated)
             result['created'] = true;
+        // #4763 (1): surface any non-empty prior record the write displaced. Gated
+        // on reconciledUpdated (the fields that actually persisted, post-#3957
+        // reconcile) rather than the pre-reconciliation updated[]. Only fields with
+        // real prior content differing from the caller's value count — same-value
+        // rewrites, the insert path (no prior label), and the #944 template-default
+        // DWIM (defaults match case-insensitively, so a case-variant 'none' →
+        // 'None' rewrite is normalization, not displacement) are excluded.
+        const isResumeTemplateDefault = priorRecord.resumeFile !== undefined
+            && state_document_cjs_1.KNOWN_TEMPLATE_DEFAULTS['Resume File'].some((d) => d.toLowerCase() === priorRecord.resumeFile?.toLowerCase());
+        const replacedRecord = {};
+        if (reconciledUpdated.includes('Stopped At') && priorRecord.stoppedAt
+            && priorRecord.stoppedAt !== options.stopped_at) {
+            replacedRecord['Stopped At'] = priorRecord.stoppedAt;
+        }
+        if (reconciledUpdated.includes('Resume File') && priorRecord.resumeFile
+            && !isResumeTemplateDefault
+            && priorRecord.resumeFile !== (options.resume_file ?? undefined)) {
+            replacedRecord['Resume File'] = priorRecord.resumeFile;
+        }
+        if (Object.keys(replacedRecord).length > 0)
+            result['replacedRecord'] = replacedRecord;
         output(result, raw, 'true');
     }
     else if (updated.length === 0) {
@@ -2350,6 +2392,112 @@ function countRoadmapPhaseHeadings(scope, convention, retiredPhaseNums, applyCon
     }
     return count;
 }
+/**
+ * The phase directories every STATE.md frontmatter rebuild scans, and the
+ * ROADMAP facts derived alongside them — the ONE owner of that set (#5118).
+ *
+ * `phaseDirs` is milestone-scoped (`listMilestonePhaseDirs`), drops retired
+ * phases (#1514) and holds exactly one directory per normalized phase key
+ * (Bug #2445, deterministic tie-break #3355). `buildStateFrontmatter` counts
+ * from it, and `statePhaseDirsToScan` hands it to `phase remove`'s pre-write
+ * validation, so the two cannot disagree about which reports a rebuild reads.
+ */
+function scanStatePhaseDirs(cwd, phasesDir, phaseConvention, storedMilestone, 
+// `quiet` suppresses ONLY the duplicate-phase-key stderr warning. A pre-write
+// validation pass that is followed by the real rebuild scan sets it, so the
+// one command prints the warning once (the rebuild scan owns the warning).
+options = {}) {
+    // Read the current-milestone ROADMAP scope once: it feeds both the
+    // heading-based phase count and the retired/folded-phase
+    // exclusion (#1514). Computed before the disk scan so retired phases
+    // can be dropped from the dir set too.
+    let roadmapScope = null;
+    let roadmapRaw = null;
+    let retiredPhaseNums = new Set();
+    try {
+        const roadmapPath = node_path_1.default.join(planningDir(cwd), 'ROADMAP.md');
+        roadmapRaw = (0, shell_command_projection_cjs_1.platformReadSync)(roadmapPath);
+        if (roadmapRaw !== null) {
+            roadmapScope = extractCurrentMilestone(roadmapRaw, cwd);
+            retiredPhaseNums = extractRetiredPhaseNumbers(roadmapScope, phaseConvention);
+        }
+    }
+    catch { /* fall through: no roadmap scope → no retired exclusion */ }
+    // #3017: scope the milestone filter to the STORED milestone when available,
+    // so a state.* write doesn't auto-derive (and mis-bind) to a different
+    // milestone's heading and clobber the stored value + progress counts.
+    // #3185 (ADR-3180 Decision 1): "which phase directories belong to the
+    // CURRENT (stored) milestone" — routed through the canonical owner
+    // instead of a hand-rolled readdirSync + isDirInMilestone filter
+    // (which also never excluded sentinels, unlike the owner).
+    const { value: allMatchingDirs, scope: phaseDirScope } = listMilestonePhaseDirs(phasesDir, {
+        cwd,
+        versionOverride: storedMilestone ?? null,
+        phaseIdConvention: phaseConvention,
+    });
+    // Bug #2445: when stale phase dirs from a prior milestone remain in
+    // .planning/phases/ alongside new dirs with the same phase number,
+    // de-duplicate by normalized phase number keeping exactly one dir
+    // per key (deterministic tie-break: see #3355 below). This prevents
+    // double-counting (e.g. two "Phase 1" dirs).
+    const seenPhaseNums = new Map(); // normalizedNum -> dirName
+    for (const dir of allMatchingDirs) {
+        // #1514: a retired/folded phase keeps a directory but no completion
+        // artifact; drop it from the disk phase set so it counts toward
+        // neither the denominator nor the numerator (mirrors the heading
+        // exclusion below). Project-code-aware via phaseKeyFromDir.
+        if (retiredPhaseNums.size > 0 && retiredPhaseNums.has(phaseKeyFromDir(dir, phaseConvention)))
+            continue;
+        // #3185: dedup grouping routed through the canonical phaseKeyFromDir
+        // (src/phase-id.cts) instead of a local leading-digits regex that
+        // diverged from extractPhaseToken/phaseKeyFromDir on
+        // project-code-prefixed dirs (whole dirname fell through as the key,
+        // so a `PROJ-05`/`PROJ-05-slug` pair never deduped) and on
+        // multi-segment milestone dirs. Same key surface used two lines
+        // above for the retiredPhaseNums exclusion, so both filters agree.
+        const key = phaseKeyFromDir(dir, phaseConvention);
+        if (!seenPhaseNums.has(key)) {
+            seenPhaseNums.set(key, dir);
+        }
+        else {
+            // #3355: the survivor of a same-milestone collision must be
+            // chosen from repository CONTENT, never from filesystem state.
+            // The pre-#3355 tie-break was `mtimeMs` — a checkout-order
+            // signal — so two byte-identical checkouts of the same commit
+            // that wrote the colliding dirs in a different order picked
+            // different survivors, and progress.total_plans /
+            // completed_plans drifted across clones and CI runs. The
+            // directory NAME is git-tracked content and a total order, so
+            // the lexicographically-first dir wins deterministically. The
+            // collision is still a project-level defect (duplicate phase
+            // number in scope), so it is surfaced on stderr instead of
+            // being silently resolved. The Bug #2445 invariant — exactly
+            // one survivor per normalized phase number — is unchanged.
+            const incumbent = seenPhaseNums.get(key);
+            const survivor = dir < incumbent ? dir : incumbent;
+            seenPhaseNums.set(key, survivor);
+            if (options.quiet !== true)
+                process.stderr.write(`gsd: warning — phase directories '${incumbent}' and '${dir}' both normalize to phase key '${key}' (duplicate phase number in .planning/phases/); keeping '${survivor}' by deterministic lexicographic order. (#3355)\n`);
+        }
+    }
+    return {
+        phaseDirs: [...seenPhaseNums.values()],
+        phaseDirScope,
+        roadmapScope,
+        roadmapRaw,
+        retiredPhaseNums,
+    };
+}
+/**
+ * #5038: does existing frontmatter assert an explicit null milestone, as
+ * opposed to omitting the `milestone:` key? `extractFrontmatter` parses under
+ * FAILSAFE_SCHEMA, so YAML null arrives as a string; classification is
+ * delegated to classifyMilestoneScalar.
+ */
+function isMilestoneExplicitlyNull(existingFm) {
+    const raw = existingFm['milestone'];
+    return typeof raw === 'string' && classifyMilestoneScalar(raw).explicitNull;
+}
 /**
  * Extract machine-readable fields from STATE.md markdown body and build
  * a YAML frontmatter object. Allows hooks and scripts to read state
@@ -2361,7 +2509,10 @@ function buildStateFrontmatter(bodyContent, cwd, storedMilestone, storedTotalPha
 // #3354/#3573 withhold condition the disk scan returns null for all four
 // counters, and these stored values are what the progress block falls back
 // to (else the keys are omitted).
-storedCompletedPhases, storedTotalPlans, storedCompletedPlans) {
+storedCompletedPhases, storedTotalPlans, storedCompletedPlans, 
+// #5038: explicit `milestone: null` (vs an absent key); withholds progress
+// counters on a sectioned ROADMAP without the unbound warning.
+milestoneExplicitlyNull) {
     // #2956: scope `Phase` extraction to ## Current Position (mirrors the read
     // path in cmdStateSnapshot and the Stopped At / Paused At ## Session scoping
     // below). Phase canonically lives in ## Current Position (templates/state.md);
@@ -2463,79 +2614,12 @@ storedCompletedPhases, storedTotalPlans, storedCompletedPlans) {
                 // on repeated buildStateFrontmatter invocations within the same process (#1967)
                 let cached = _diskScanCache.get(cwd);
                 if (!cached) {
-                    // Read the current-milestone ROADMAP scope once: it feeds both the
-                    // heading-based phase count below and the retired/folded-phase
-                    // exclusion (#1514). Computed before the disk scan so retired phases
-                    // can be dropped from the dir set too.
-                    let roadmapScope = null;
-                    let roadmapRaw = null;
-                    let retiredPhaseNums = new Set();
-                    try {
-                        const roadmapPath = node_path_1.default.join(planningDir(cwd), 'ROADMAP.md');
-                        roadmapRaw = (0, shell_command_projection_cjs_1.platformReadSync)(roadmapPath);
-                        if (roadmapRaw !== null) {
-                            roadmapScope = extractCurrentMilestone(roadmapRaw, cwd);
-                            retiredPhaseNums = extractRetiredPhaseNumbers(roadmapScope, phaseConvention);
-                        }
-                    }
-                    catch { /* fall through: no roadmap scope → no retired exclusion */ }
-                    // #3017: scope the milestone filter to the STORED milestone when available,
-                    // so a state.* write doesn't auto-derive (and mis-bind) to a different
-                    // milestone's heading and clobber the stored value + progress counts.
-                    // #3185 (ADR-3180 Decision 1): "which phase directories belong to the
-                    // CURRENT (stored) milestone" — routed through the canonical owner
-                    // instead of a hand-rolled readdirSync + isDirInMilestone filter
-                    // (which also never excluded sentinels, unlike the owner).
-                    const { value: allMatchingDirs, scope: phaseDirScope } = listMilestonePhaseDirs(phasesDir, {
-                        cwd,
-                        versionOverride: storedMilestone ?? null,
-                        phaseIdConvention: phaseConvention,
-                    });
-                    // Bug #2445: when stale phase dirs from a prior milestone remain in
-                    // .planning/phases/ alongside new dirs with the same phase number,
-                    // de-duplicate by normalized phase number keeping exactly one dir
-                    // per key (deterministic tie-break: see #3355 below). This prevents
-                    // double-counting (e.g. two "Phase 1" dirs).
-                    const seenPhaseNums = new Map(); // normalizedNum -> dirName
-                    for (const dir of allMatchingDirs) {
-                        // #1514: a retired/folded phase keeps a directory but no completion
-                        // artifact; drop it from the disk phase set so it counts toward
-                        // neither the denominator nor the numerator (mirrors the heading
-                        // exclusion below). Project-code-aware via phaseKeyFromDir.
-                        if (retiredPhaseNums.size > 0 && retiredPhaseNums.has(phaseKeyFromDir(dir, phaseConvention)))
-                            continue;
-                        // #3185: dedup grouping routed through the canonical phaseKeyFromDir
-                        // (src/phase-id.cts) instead of a local leading-digits regex that
-                        // diverged from extractPhaseToken/phaseKeyFromDir on
-                        // project-code-prefixed dirs (whole dirname fell through as the key,
-                        // so a `PROJ-05`/`PROJ-05-slug` pair never deduped) and on
-                        // multi-segment milestone dirs. Same key surface used two lines
-                        // above for the retiredPhaseNums exclusion, so both filters agree.
-                        const key = phaseKeyFromDir(dir, phaseConvention);
-                        if (!seenPhaseNums.has(key)) {
-                            seenPhaseNums.set(key, dir);
-                        }
-                        else {
-                            // #3355: the survivor of a same-milestone collision must be
-                            // chosen from repository CONTENT, never from filesystem state.
-                            // The pre-#3355 tie-break was `mtimeMs` — a checkout-order
-                            // signal — so two byte-identical checkouts of the same commit
-                            // that wrote the colliding dirs in a different order picked
-                            // different survivors, and progress.total_plans /
-                            // completed_plans drifted across clones and CI runs. The
-                            // directory NAME is git-tracked content and a total order, so
-                            // the lexicographically-first dir wins deterministically. The
-                            // collision is still a project-level defect (duplicate phase
-                            // number in scope), so it is surfaced on stderr instead of
-                            // being silently resolved. The Bug #2445 invariant — exactly
-                            // one survivor per normalized phase number — is unchanged.
-                            const incumbent = seenPhaseNums.get(key);
-                            const survivor = dir < incumbent ? dir : incumbent;
-                            seenPhaseNums.set(key, survivor);
-                            process.stderr.write(`gsd: warning — phase directories '${incumbent}' and '${dir}' both normalize to phase key '${key}' (duplicate phase number in .planning/phases/); keeping '${survivor}' by deterministic lexicographic order. (#3355)\n`);
-                        }
-                    }
-                    const phaseDirs = [...seenPhaseNums.values()];
+                    // The ROADMAP scope + the deduped, milestone-scoped disk phase set:
+                    // one owner (scanStatePhaseDirs, above buildStateFrontmatter) so the
+                    // #5118 pre-write validation in `phase remove` reads exactly this set.
+                    // #5038: an explicit-null `storedMilestone` is text, not a version;
+                    // pass a real null so it never reaches the phase-dir version filter.
+                    const { phaseDirs, phaseDirScope, roadmapScope, roadmapRaw, retiredPhaseNums, } = scanStatePhaseDirs(cwd, phasesDir, phaseConvention, milestoneExplicitlyNull ? null : storedMilestone);
                     let diskTotalPlans = 0;
                     let diskTotalSummaries = 0;
                     let diskCompletedPhases = 0;
@@ -2555,7 +2639,15 @@ storedCompletedPhases, storedTotalPlans, storedCompletedPlans) {
                         // #612: `phaseConvention` threaded so a bracket phase dir resolves
                         // and scopes its verification report like its legacy twin — the
                         // read-side half of the same thread cmdStateSync gets below.
-                        if (isPhaseComplete(phaseDir, { convention: phaseConvention }).value.complete)
+                        const completion = isPhaseComplete(phaseDir, { convention: phaseConvention });
+                        // #5118 (no write before the error): every STATE.md write rebuilds
+                        // this frontmatter BEFORE its write, so a report whose `status` is
+                        // outside the closed set fails the write here — the owner's error,
+                        // rethrown past the best-effort catch below, nothing persisted and
+                        // nothing cached.
+                        if (completion.value.statusError)
+                            throw completion.value.statusError;
+                        if (completion.value.complete)
                             diskCompletedPhases++;
                     }
                     // Count phase headings from ROADMAP — single source of truth for
@@ -2576,6 +2668,21 @@ storedCompletedPhases, storedTotalPlans, storedCompletedPlans) {
                         // phase-dir count only, and mark unbounded so percent is skipped
                         // downstream (mirrors the sync write-path guard).
                         let milestoneBounded = true;
+                        // #2828/#3642: distinguish a FLAT unmilestoned roadmap (no milestone
+                        // sectioning at all — only Phase headings) from a MILESTONED one
+                        // (milestone/version headings exist). Computed before the
+                        // boundedness gate so the explicit-null branch can use it (#5038).
+                        // #3642: the flat test uses the >=1 sibling (hasAnyMilestoneSection),
+                        // not the >=2 predicate. >=2 under-answers the question this branch
+                        // asks: with EXACTLY ONE milestone section and an asserted milestone
+                        // absent from the ROADMAP, >=2 read "flat" and the whole-document
+                        // count — which IS that single section's phases — was written as the
+                        // asserted milestone's total, silently clobbering the stored value.
+                        // The >=2 threshold governs SIBLING conflation; asserted-vs-section
+                        // needs only one section to go wrong. Zero sections (genuinely flat)
+                        // keeps the whole-document count, per #2828.
+                        const roadmapHasAnyMilestoneSection = roadmapRaw !== null
+                            && hasAnyMilestoneSection(roadmapRaw);
                         // #3216 fix (#1761 regression): use `assertedMilestoneVersion` —
                         // the version STATE.md actually asserts — not the scope-gated
                         // `milestone`. `milestone` is null on any non-COMPLETE identity
@@ -2593,27 +2700,19 @@ storedCompletedPhases, storedTotalPlans, storedCompletedPlans) {
                             // defect, design row 17).
                             milestoneBounded = isMilestoneBounded(roadmapRaw, String(assertedMilestoneVersion).trim(), phaseConvention);
                         }
-                        // #2828: distinguish a FLAT unmilestoned roadmap (no milestone sectioning
-                        // at all — only Phase headings) from a MILESTONED-but-unbounded one
-                        // (milestone/version headings exist but the asserted one isn't among them).
-                        // On a flat roadmap the whole-doc count is correct (no sibling milestones to
-                        // conflate); on a sectioned-but-unbounded one it conflates siblings (#1761),
-                        // so fall back to phaseDirs.length.
+                        else if (milestoneExplicitlyNull && roadmapRaw !== null && roadmapHasAnyMilestoneSection) {
+                            // #5038: explicit null on a sectioned ROADMAP: no section owns
+                            // the counts, so treat as unbound for the withhold gate (the
+                            // warning below is skipped, null is deliberate).
+                            milestoneBounded = false;
+                        }
+                        // #2828: on a flat roadmap the whole-doc count is correct (no
+                        // sibling milestones to conflate); on a sectioned-but-unbounded one
+                        // it conflates siblings (#1761), so fall back to phaseDirs.length.
                         // #3184: routed through the single owner (roadmap-parser.cjs) —
                         // deliberately weaker than isMilestoneBoundedInRoadmap above (no
                         // version-token requirement); see hasMilestoneSectioning's own
                         // doc comment for why that distinction is load-bearing.
-                        // #3642: the flat test uses the >=1 sibling (hasAnyMilestoneSection),
-                        // not the >=2 predicate. >=2 under-answers the question this branch
-                        // asks: with EXACTLY ONE milestone section and an asserted milestone
-                        // absent from the ROADMAP, >=2 read "flat" and the whole-document
-                        // count — which IS that single section's phases — was written as the
-                        // asserted milestone's total, silently clobbering the stored value.
-                        // The >=2 threshold governs SIBLING conflation; asserted-vs-section
-                        // needs only one section to go wrong. Zero sections (genuinely flat)
-                        // keeps the whole-document count, per #2828.
-                        const roadmapHasAnyMilestoneSection = roadmapRaw !== null
-                            && hasAnyMilestoneSection(roadmapRaw);
                         const safeToUseRoadmapCount = milestoneBounded
                             || (roadmapPhaseCount > 0 && !roadmapHasAnyMilestoneSection);
                         // #3354: the milestoned-but-unbounded sibling of the #2828/#3204
@@ -2631,7 +2730,8 @@ storedCompletedPhases, storedTotalPlans, storedCompletedPlans) {
                         // The degenerate un-sectioned zero-heading case keeps the
                         // phaseDirs.length fallback — with nothing declared anywhere else,
                         // the disk count is the only source and remains correct.
-                        const milestonedButUnbounded = !milestoneBounded && roadmapHasAnyMilestoneSection;
+                        // #5038: explicit null is withheld silently (explicitNullWithheld).
+                        const milestonedButUnbounded = !milestoneBounded && roadmapHasAnyMilestoneSection && !milestoneExplicitlyNull;
                         if (milestonedButUnbounded) {
                             process.stderr.write(`gsd: warning — milestone '${String(assertedMilestoneVersion ?? '').trim()}' is asserted in STATE.md but matches no ROADMAP heading, and the ROADMAP carries milestone section(s) — one (#3642) or several (#3354) — none matching it; the whole-document count would attribute a foreign section's phases to this milestone and the on-disk phase-directory count would understate the declared total, so the progress counters (total_phases, completed_phases, total_plans, completed_plans) are left at their stored values. (#3354/#3642/#4094)\n`);
                         }
@@ -2646,9 +2746,11 @@ storedCompletedPhases, storedTotalPlans, storedCompletedPlans) {
                         // value instead. Without an asserted milestone (fresh project,
                         // pre-roadmap) the disk count is still the only source and stays
                         // authoritative (the #3354 doctrine's degenerate case).
+                        // #5038: an explicit null is not an asserted milestone.
                         const roadmapAbsentWithAssertedMilestone = roadmapRaw === null &&
                             typeof storedMilestone === 'string' &&
-                            storedMilestone.trim() !== '';
+                            storedMilestone.trim() !== '' &&
+                            !milestoneExplicitlyNull;
                         if (roadmapAbsentWithAssertedMilestone) {
                             process.stderr.write(`gsd: warning — milestone '${storedMilestone.trim()}' is asserted in STATE.md but ROADMAP.md is absent or unreadable, so the phase-heading total cannot be derived; the on-disk phase-directory count would understate the declared total, so the progress counters (total_phases, completed_phases, total_plans, completed_plans) are left at their stored values. (#3573) (#4094)\n`);
                         }
@@ -2661,7 +2763,9 @@ storedCompletedPhases, storedTotalPlans, storedCompletedPlans) {
                         // Pre-#4094 only totalPhases was nulled here, so every resyncing
                         // write silently clobbered the three stored siblings with the
                         // under-scoped disk numbers.
-                        const diskCountsWithheld = milestonedButUnbounded || roadmapAbsentWithAssertedMilestone;
+                        // #5038: silent sibling of milestonedButUnbounded.
+                        const explicitNullWithheld = milestoneExplicitlyNull && !milestoneBounded && roadmapHasAnyMilestoneSection;
+                        const diskCountsWithheld = milestonedButUnbounded || roadmapAbsentWithAssertedMilestone || explicitNullWithheld;
                         // #4129: floor the completed-phases numerator at the ROADMAP's own
                         // milestone Complete-row count. The disk numerator counts ONLY
                         // phase dirs whose *-VERIFICATION.md routes `passed` (isPhaseComplete,
@@ -2754,9 +2858,13 @@ storedCompletedPhases, storedTotalPlans, storedCompletedPlans) {
              * crash `state show`; on failure this simply keeps whatever
              * frontmatter-derived totals/completedPhases/etc. were already set
              * above, a graceful degrade rather than a corrupted write (nothing is
-             * persisted from this block). */
+             * persisted from this block). #5118: an out-of-set verification
+             * report status is not a read failure to degrade over — rethrown. */
+        }
+        catch (err) {
+            if (err instanceof VerificationStatusError)
+                throw err;
         }
-        catch { /* intentionally empty */ }
     }
     // Derive percent from disk counts when available (ground truth).
     // Uses min(plan_fraction, phase_fraction) via computeProgressPercent so that
@@ -3173,7 +3281,7 @@ function syncStateFrontmatter(content, cwd, authoritativeFm, sanctionedPermanent
     // milestoned-but-unbounded withhold can preserve it across the write
     // (the derived progress sub-block replaces the stored one wholesale below,
     // so an omitted key would otherwise DELETE the stored value).
-    const derivedFm = buildStateFrontmatter(body, cwd, storedMilestone, readStoredTotalPhases(existingFm), readStoredCompletedPhases(existingFm), readStoredTotalPlans(existingFm), readStoredCompletedPlans(existingFm));
+    const derivedFm = buildStateFrontmatter(body, cwd, storedMilestone, readStoredTotalPhases(existingFm), readStoredCompletedPhases(existingFm), readStoredTotalPlans(existingFm), readStoredCompletedPlans(existingFm), isMilestoneExplicitlyNull(existingFm));
     // Preserve existing frontmatter status when body-derived status is 'unknown'.
     // This prevents a missing Status: field in the body from overwriting a
     // previously valid status (e.g., 'executing' → 'unknown').
@@ -4525,7 +4633,7 @@ function cmdStateJson(cwd, raw) {
     // reports the phase-directory count while the persisted file preserves the
     // stored total, exactly the write/read divergence #3354 closed for its shape.
     const storedMilestoneJson = typeof existingFm['milestone'] === 'string' ? existingFm['milestone'] : null;
-    const built = buildStateFrontmatter(body, cwd, storedMilestoneJson, readStoredTotalPhases(existingFm), readStoredCompletedPhases(existingFm), readStoredTotalPlans(existingFm), readStoredCompletedPlans(existingFm));
+    const built = buildStateFrontmatter(body, cwd, storedMilestoneJson, readStoredTotalPhases(existingFm), readStoredCompletedPhases(existingFm), readStoredTotalPlans(existingFm), readStoredCompletedPlans(existingFm), isMilestoneExplicitlyNull(existingFm));
     // ADR-3408 §8.5 / D3: route stopped_at / paused_at / status / current_phase /
     // current_phase_name / current_plan through the SAME `preserve-when-unchanged`
     // executor the write path uses (`applyPreserveWhenUnchanged`), instead of a
@@ -5521,7 +5629,13 @@ function cmdStateSync(cwd, options, raw) {
         // #612: `syncConvention` threaded — the write-side half of
         // buildStateFrontmatter's thread above, so `state sync` and `state json`
         // keep agreeing on completed_phases under the bracket convention.
-        if (isPhaseComplete(dirPath, { convention: syncConvention }).value.complete)
+        // #5118 (no write before the error): `state sync` writes STATE.md only
+        // after this scan, so an out-of-set report status fails it here, having
+        // written nothing.
+        const completion = isPhaseComplete(dirPath, { convention: syncConvention });
+        if (completion.value.statusError)
+            throw completion.value.statusError;
+        if (completion.value.complete)
             diskCompletedPhases++;
         // Track the highest phase with incomplete plans (or any plans)
         const phaseMatch = dir.match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE})`, 'i'));
@@ -5568,8 +5682,10 @@ function cmdStateSync(cwd, options, raw) {
     // set — leave Progress untouched (percent=null) rather than silently writing
     // fallback-derived wrong values. Projects without a milestone version (the common
     // sync-test shape) are unaffected: the gate only fires when a version is asserted.
-    const fmVersion = extractFrontmatter(content, statePath).milestone;
-    const versionStr = typeof fmVersion === 'string' && fmVersion.trim() ? fmVersion.trim() : null;
+    const syncFm = extractFrontmatter(content, statePath);
+    const fmVersion = syncFm.milestone;
+    const milestoneExplicitlyNull = isMilestoneExplicitlyNull(syncFm);
+    const versionStr = typeof fmVersion === 'string' && fmVersion.trim() && !milestoneExplicitlyNull ? fmVersion.trim() : null;
     let milestoneBounded = true;
     if (versionStr !== null && syncRoadmapRaw !== null) {
         // #3184: routed through the single owner (roadmap-parser.cjs) instead of
@@ -5578,6 +5694,10 @@ function cmdStateSync(cwd, options, raw) {
         // extension on top inside isMilestoneBounded.
         milestoneBounded = isMilestoneBounded(syncRoadmapRaw, versionStr, syncConvention);
     }
+    else if (milestoneExplicitlyNull && syncRoadmapRaw !== null && hasAnyMilestoneSection(syncRoadmapRaw)) {
+        // #5038: mirror buildStateFrontmatter's silent explicit-null withhold.
+        milestoneBounded = false;
+    }
     let percent = null;
     if (!milestoneBounded) {
         changes.push(`Progress: skipped — milestone ${versionStr} cannot be bounded to a versioned ROADMAP phase set (#1761)`);
@@ -6127,6 +6247,35 @@ function cmdStateCompletePhase(cwd, raw, overridePhase) {
     if (wrote)
         publishStateContract(cwd);
 }
+/**
+ * #5118 (no write before the error): throws `VerificationStatusError` when a
+ * verification report in the set every STATE.md write rebuilds its frontmatter
+ * from carries a `status` outside the closed set — and returns having done
+ * nothing else. It runs `buildStateFrontmatter` itself (the SAME disk scan,
+ * milestone scoping and dedupe every write performs), so a caller that writes
+ * OTHER files before STATE.md (`phase complete`, `phase remove`, `quick
+ * archive`, `validate health --repair`) refuses for exactly the phases the
+ * STATE.md write would refuse for — the set cannot drift from a second copy.
+ */
+function assertVerificationReportsReadable(bodyContent, cwd) {
+    buildStateFrontmatter(bodyContent, cwd);
+}
+/**
+ * The phase directory NAMES (under `.planning/phases/`) a STATE.md frontmatter
+ * rebuild scans — milestone-scoped, retired phases dropped, one per phase key
+ * (`scanStatePhaseDirs`). For a caller that must validate the reports a rebuild
+ * WILL read after it has removed a directory of its own (`phase remove`): it
+ * takes this set and drops the directory it is about to delete (#5118).
+ */
+function statePhaseDirsToScan(cwd) {
+    const phasesDir = planningPaths(cwd).phases;
+    if (!node_fs_1.default.existsSync(phasesDir))
+        return [];
+    // quiet: this is a pre-write validation pass, always followed by the real
+    // rebuild scan (buildStateFrontmatter), which owns the duplicate-phase-key
+    // stderr warning — so the command prints it once, not twice.
+    return scanStatePhaseDirs(cwd, phasesDir, resolvePhaseIdConvention(cwd), undefined, { quiet: true }).phaseDirs;
+}
 module.exports = {
     stateExtractField: state_document_cjs_1.stateExtractField,
     stateReplaceField: state_document_cjs_1.stateReplaceField,
@@ -6136,6 +6285,8 @@ module.exports = {
     writeStateMd,
     readModifyWriteStateMd,
     syncStateFrontmatter,
+    assertVerificationReportsReadable,
+    statePhaseDirsToScan,
     // #3374: the shared post-sync preservation pass (snapshots + table-driven
     // applyStatePreservation + #2736 re-assert).
     applyPostSyncPreservation,

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

@@ -35,6 +35,7 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const runtime_name_policy_cjs_1 = require("./runtime-name-policy.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const installProfiles = require("./install-profiles.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -61,6 +62,18 @@ const runtimeArtifactInstallPlan = require("./runtime-artifact-install-plan.cjs"
 const retiredArtifactCleanup = require("./retired-artifact-cleanup.cjs");
 const { assertDestWithinConfigHome } = runtimeArtifactInstallPlan;
 const SURFACE_FILE_NAME = '.gsd-surface.json';
+const INSTALL_MANIFEST_FILE_NAME = 'gsd-file-manifest.json';
+/** Read only the installer-owned relative-include style, failing closed. */
+function readRelativeIncludePrefix(runtimeConfigDir) {
+    try {
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(runtimeConfigDir, INSTALL_MANIFEST_FILE_NAME), 'utf8'));
+        const prefix = parsed?.['relativeIncludePrefix'];
+        return typeof prefix === 'string' ? prefix : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Read the surface state from a runtime config directory.
  *
@@ -339,9 +352,13 @@ function applySurface(runtimeConfigDir, layout, manifest, clusterMap, registry,
     // then projects the defaulted value to the boolean `_computePathPrefix`'s
     // existing `isGlobal: boolean` API requires.
     const _isGlobal = (0, install_scope_cjs_1.isGlobalScope)(layout.scope ?? 'global');
-    const _isOpencode = layout.runtime === 'opencode';
+    const _isOpencode = (0, runtime_name_policy_cjs_1.hostBehaviorsFor)(layout.runtime).opencodePathPrefix === true;
     const _isWindowsHost = (opts?.platform ?? process.platform) === 'win32';
-    const _pathPrefix = runtimeArtifactConversion._computePathPrefix({ isGlobal: _isGlobal, isOpencode: _isOpencode, isWindowsHost: _isWindowsHost, resolvedTarget: _resolvedTarget, homeDir: _homeDir });
+    // #4377: style is an install-time fact, not a process environment setting.
+    // A later gsd-tools surface apply runs in another process, so it must reuse
+    // the persisted, root-relative prefix the installer actually emitted.
+    const _relativeIncludePrefix = readRelativeIncludePrefix(runtimeConfigDir);
+    const _pathPrefix = runtimeArtifactConversion._computePathPrefix({ isGlobal: _isGlobal, isOpencode: _isOpencode, isWindowsHost: _isWindowsHost, resolvedTarget: _resolvedTarget, homeDir: _homeDir, projectRelative: !_isGlobal && typeof _relativeIncludePrefix === 'string', projectRelativePath: _relativeIncludePrefix, localDirName: runtimeArtifactConversion._localIncludeDirName(layout.runtime) });
     const _attribution = opts?.resolveAttribution ? opts.resolveAttribution(layout.runtime) : undefined;
     // #2875 Part 2 (row I1): layout.configDir is this call's install root.
     const agentCtx = { runtime: layout.runtime, pathPrefix: _pathPrefix, attribution: _attribution, targetDir: layout.configDir };