@opengsd/gsd-core 1.15.0 → 1.16.0

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

@@ -30,6 +30,7 @@ const markdown_table_cjs_1 = require("./markdown-table.cjs");
 const phase_lifecycle_cjs_1 = require("./phase-lifecycle.cjs");
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 const pattern_cjs_1 = require("./pattern.cjs");
+const planning_document_cjs_1 = require("./planning-document.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-scope.cjs is an export= CommonJS module
 const planningScopeMod = require("./planning-scope.cjs");
 const { SCOPE } = planningScopeMod;
@@ -536,29 +537,106 @@ function joinFieldReplacement(prefix, newValue) {
 function stateReplaceField(content, fieldName, newValue) {
     const escaped = (0, pattern_cjs_1.escapeRegex)(fieldName);
     // Bold inline format: **FieldName:** value
-    // The label-to-value gap is same-line whitespace only (`[ \t]*`, mirroring the
-    // read side at stateExtractField). `\s*` here matched `\n`, so on an empty field
-    // `(.*)` captured the following line and the rebuild discarded it — the #4010
-    // data-loss. ADR-3180 §7.7 makes stateExtractField the same-line-confined owner;
-    // this aligns the writer to it.
     //
-    // #4243: the bold form is also ANCHORED to line start, with same-line leading
-    // whitespace only. The pre-fix pattern carried no `^` and no `m` flag, so a
-    // bold label quoted MID-SENTENCE inside prose — an Accumulated Context bullet
-    // mentioning `**Status:**` — captured the rewrite and destroyed the rest of
-    // its line, silently, whenever a whole-body caller fed this function every
-    // section (beginPhaseCore's tryField, advancePlanCore's Status/Current Plan
-    // writes). The plain branch below was always line-anchored; only the bold
-    // branch lagged. Anchoring reuses #4010's same-line confinement idiom (the
-    // leading class is `[ \t]*`, deliberately NOT the `\s*` the issue suggested —
-    // `^\s*\*\*` can consume the newlines before the label into the match and
-    // drop them on rebuild) and #4186's recognition-by-anchoring discipline: a
-    // write target must BE the whole declared line shape, never a substring
-    // guess inside prose. `$` is explicit-and-inert (`.` never crosses line
-    // terminators) and documents that the match ends at end-of-line.
-    const boldPattern = new RegExp(`^([ \\t]*\\*\\*${escaped}:\\*\\*[ \\t]*)(.*)$`, 'im');
-    if (boldPattern.test(content)) {
-        return content.replace(boldPattern, (_match, prefix) => joinFieldReplacement(prefix, newValue));
+    // #5007 (Phase 6 / ADR-4910 amendment): migrated off the hand-rolled
+    // `^([ \t]*\*\*${escaped}:\*\*[ \t]*)(.*)$` regex (which, per #4010/#4243
+    // below, already existed to fix real same-line-confinement and mid-prose
+    // data-loss bugs) onto `parsePlanningDoc` for LOCATING the field — same-
+    // line confinement AND fence/frontmatter exclusion (parseBoldFieldLine
+    // never matches inside a fenced block or frontmatter, which the removed
+    // regex could not tell apart from prose) — so this migration keeps
+    // #4010/#4243's fix and extends it, rather than replacing it with a
+    // weaker check.
+    //
+    // This does NOT go through the seam's `setFieldValue`/`serialize` write
+    // path. An earlier version of this migration did, via a since-removed
+    // `setFieldValue({ allowSeparator: true })` option (#5007) — that option
+    // spliced the caller's value across the FULL rest-of-line span
+    // (`valueSpan.start`..`trailingSpan.end`) to permit a value containing the
+    // grammar's ` — ` trailing-separator token (needed here: see the
+    // `${currentPhase} — COMPLETE` value below). It was removed after a
+    // failing-first reproduction proved it only avoided the write-time
+    // refusal: the bytes it writes are correct, but `parseBoldFieldLine`
+    // splits on ` — ` unconditionally on every read, with no escaping
+    // convention in this grammar to tell "atomic value containing the token"
+    // apart from "value plus hand-annotation". So the NEXT fresh
+    // `parsePlanningDoc` of that exact text — not the in-memory doc the
+    // option's own tests checked — silently re-truncates the value and
+    // demotes the rest to `trailingSpan`, with `findField`/`readNode`
+    // reporting a confident, wrong `ok: true` and no error. That is exactly
+    // the #4917 finding-2 corruption `setFieldValue`'s round-trip check
+    // exists to prevent, just moved one parse cycle downstream. This call
+    // site never reads STATE.md fields back through `parsePlanningDoc`/
+    // `findField` (reads go through `stateExtractField`'s own non-splitting
+    // regex, below), so it is safe HERE — but making that a shared, public
+    // option on the seam's `setFieldValue` was an attractive nuisance for any
+    // future `findField`/`readNode` caller (this same module already serves
+    // ROADMAP.md's `Plans`/`Depends on` fields that way). The full-rest-of-
+    // line splice is done locally, directly against `content`, instead —
+    // `parsePlanningDoc` is used only to locate the field's spans.
+    //
+    // Two deliberate deviations from a bare findField() call, both
+    // PRESERVING this function's own prior contract rather than adopting the
+    // seam's stricter defaults:
+    //
+    //  1. Label lookup here is case-INSENSITIVE (not findField's exact
+    //     match), mirroring the removed regex's `i` flag: callers in
+    //     state.cts/state-transition.cts pass a fieldName spelling that can
+    //     differ only in case from what a given template actually has (the
+    //     explicit 'Last Activity' / 'Last activity' fallback-call pairs at
+    //     those call sites), so a case-sensitive lookup would silently miss
+    //     matches the removed regex used to find.
+    //  2. Every write below replaces the FULL rest-of-line span
+    //     (`valueSpan.start`..`trailingSpan.end`) UNCONDITIONALLY, not only
+    //     when `newValue` contains the grammar's ` — ` separator token,
+    //     because `joinFieldReplacement` always discarded the OLD regex's
+    //     entire captured tail (`(.*)$` — both what the seam calls
+    //     `valueSpan` AND `trailingSpan`) and replaced it wholesale with the
+    //     new value. This call site never had a "preserve a hand-written
+    //     trailing annotation" contract, so writing anything narrower than
+    //     the full rest-of-line span here would be a NEW, untested behavior
+    //     this migration must not introduce as a side effect.
+    //
+    // Matching BOTH bold-placement spellings (`**Label:**` and `**Label**:`,
+    // `BOLD_FIELD_RE`) where the removed regex recognized only `**Label:**`
+    // is the same, already-precedented widening as the "Depends on"
+    // migration (src/phase.cts) — intentional, not scope creep.
+    //
+    // A parse failure, an absent/case-mismatched label, or a value containing
+    // a line break (\r/\n — would forge sibling structure on splice, the same
+    // hazard `setFieldValue` refuses unconditionally at #4917/ADR-4910
+    // Decision 2 & 4; this local splice has no seam call to inherit that
+    // refusal from, so it is re-checked here) falls through to the
+    // plain/pipe-table branches below unchanged — the same silent
+    // per-occurrence no-op-on-no-match contract the removed regex had for any
+    // input it didn't match.
+    const parsed = (0, planning_document_cjs_1.parsePlanningDoc)(content, 'STATE.md');
+    if (parsed.ok) {
+        let boldField = null;
+        for (const node of parsed.value.nodes) {
+            if (node.kind !== 'boldField')
+                continue;
+            if (node.label.toLowerCase() !== fieldName.toLowerCase())
+                continue;
+            boldField = node;
+            break;
+        }
+        if (boldField) {
+            // Replicates joinFieldReplacement's own `` `${newValue}` `` coercion
+            // (a caller may pass a non-string, e.g. a number, at the JS boundary
+            // even though the type signature says `string`) before the
+            // missing-separator normalization below: insert a single space when
+            // the existing label-to-value gap has none, so `**Status:**value`
+            // still becomes `**Status:** value` rather than gluing the two
+            // together.
+            const spacingText = parsed.value.source.slice(boldField.labelSpan.end, boldField.valueSpan.start);
+            const newValueStr = `${newValue}`;
+            const needsSeparator = newValueStr.length > 0 && !/[ \t]$/.test(spacingText);
+            const writeValue = `${needsSeparator ? ' ' : ''}${newValueStr}`;
+            if (!/[\r\n]/.test(writeValue)) {
+                return (content.slice(0, boldField.valueSpan.start) + writeValue + content.slice(boldField.trailingSpan.end));
+            }
+        }
     }
     // Plain line-start format: FieldName: value (same same-line confinement as above)
     const plainPattern = new RegExp(`(^${escaped}:[ \\t]*)(.*)`, 'im');

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;
@@ -2392,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
@@ -2403,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);
@@ -2505,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;
@@ -2597,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
@@ -2618,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
@@ -2635,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
@@ -2673,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`);
                         }
@@ -2688,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`);
                         }
@@ -2703,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,
@@ -2796,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
@@ -3215,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').
@@ -4567,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
@@ -5563,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'));
@@ -5610,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
@@ -5620,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)`);
@@ -6169,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,
@@ -6178,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
@@ -351,7 +352,7 @@ 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';
     // #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