@opengsd/gsd-core 1.18.0 → 1.20.0

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

@@ -19,6 +19,7 @@ exports.STATE_MD_SECTIONS = exports.FRONTMATTER_BODY_SOURCE = exports.FIELD_CLAS
 exports.formatProgressMachineSegment = formatProgressMachineSegment;
 exports.stateReplaceProgressPercent = stateReplaceProgressPercent;
 exports.beginFrontmatterReassembly = beginFrontmatterReassembly;
+exports.isSessionScopedBodyField = isSessionScopedBodyField;
 exports.getFrontmatterBodySource = getFrontmatterBodySource;
 exports.frontmatterKeyForBodyField = frontmatterKeyForBodyField;
 exports.getFieldClassification = getFieldClassification;
@@ -30,13 +31,18 @@ exports.applyPreserveWhenUnchanged = applyPreserveWhenUnchanged;
 exports.applyStatePreservation = applyStatePreservation;
 exports.transitionCore = transitionCore;
 exports.sliceCurrentPositionSection = sliceCurrentPositionSection;
+exports.isStatePastPhase = isStatePastPhase;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const frontmatter = require("./frontmatter.cjs");
 const state_document_cjs_1 = require("./state-document.cjs");
 const state_document_cjs_2 = require("./state-document.cjs");
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 const phase_lifecycle_cjs_1 = require("./phase-lifecycle.cjs");
+const roadmap_progress_cjs_1 = require("./roadmap-progress.cjs");
 const pattern_cjs_1 = require("./pattern.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-id.cjs is an export= CommonJS module
+const phaseIdMod = require("./phase-id.cjs");
+const { comparePhaseNum } = phaseIdMod;
 // #4129: the completion-ratio kernel for the resync-arm ratchet's percent
 // (planning-scope's SCOPE — state-document's own dependency, no cycle here:
 // state-document never imports this module).
@@ -246,6 +252,13 @@ exports.FRONTMATTER_BODY_SOURCE = Object.freeze(FRONTMATTER_BODY_SOURCE_KEY_ORDE
  * docstring). `updateCore` was still doing the whole-body replace.
  */
 const SESSION_SCOPED_KEYS = new Set(['stopped_at', 'paused_at']);
+/**
+ * #4998 review: the `## Session` fields with no frontmatter key. `state-snapshot`
+ * reads them from the session section only, with fenced blocks blanked, so
+ * `state update` / `state patch` write them there too — never a fenced example
+ * above the live line, and never an archive section's copy.
+ */
+const SESSION_BODY_FIELDS = new Set(['resume file', 'last session', 'last date']);
 /**
  * The `(primary, fallback)` label pair for a session-scoped frontmatter KEY.
  */
@@ -257,7 +270,8 @@ function sessionLabelsForKey(key) {
 }
 /**
  * The same pair, resolved from a BODY LABEL the caller named (`Stopped At`,
- * `Stopped at`, `Paused At`). `null` for anything else.
+ * `Stopped at`, `Paused At`, or a SESSION_BODY_FIELDS label as named). `null`
+ * for anything else.
  *
  * Deliberately does NOT accept a frontmatter key. An earlier cut resolved both
  * spellings through one function and used it for the write, which made
@@ -268,7 +282,13 @@ function sessionLabelsForKey(key) {
  */
 function sessionLabelsForBodyField(field) {
     const key = frontmatterKeyForBodyField(field);
-    return key === null ? null : sessionLabelsForKey(key);
+    if (key !== null)
+        return sessionLabelsForKey(key);
+    return SESSION_BODY_FIELDS.has(field.trim().toLowerCase()) ? { primary: field, fallback: null } : null;
+}
+/** #4998 review: whether `state update` / `state patch` write the body field `field` inside the session section. */
+function isSessionScopedBodyField(field) {
+    return sessionLabelsForBodyField(field) !== null;
 }
 /**
  * Would a session-scoped write actually land? Asks by attempting the real write
@@ -643,18 +663,24 @@ function mergeResyncProgressRatchet(curatedRecord, derivedRecord) {
             merged[key] = value;
         }
     }
-    if ((0, state_document_cjs_2.toFiniteNumber)(derivedRecord.percent) !== null) {
-        const recomputed = (0, state_document_cjs_2.computeProgressPercent)((0, state_document_cjs_2.toFiniteNumber)(merged.completed_plans), (0, state_document_cjs_2.toFiniteNumber)(merged.total_plans), (0, state_document_cjs_2.toFiniteNumber)(merged.completed_phases), (0, state_document_cjs_2.toFiniteNumber)(merged.total_phases), planningScopeMod.SCOPE.COMPLETE);
-        // Same verbatim rule for percent: assign only when the recomputed value
-        // numerically differs, so a string-spelled derived percent ("67") is not
-        // churned into a number-spelled 67 (phantom-divergence noise, not a
-        // change).
-        if (recomputed !== null && recomputed !== (0, state_document_cjs_2.toFiniteNumber)(merged.percent)) {
-            merged.percent = recomputed;
-        }
-    }
+    recomputeMergedProgressPercent(merged, derivedRecord);
     return merged;
 }
+/**
+ * Make `merged.percent` the progress computation over the counters `merged` actually carries (#5619,
+ * #4129). Only when the derived side measured a percent: a derivation that withheld one (an incomplete
+ * scope, #1761/#3217) stays withheld, never invented. Same verbatim rule as the counters: assign only
+ * when the recomputed value numerically differs, so a string-spelled derived percent ("67") is not
+ * churned into a number-spelled 67 (phantom-divergence noise, not a change).
+ */
+function recomputeMergedProgressPercent(merged, derivedRecord) {
+    if ((0, state_document_cjs_2.toFiniteNumber)(derivedRecord.percent) === null)
+        return;
+    const recomputed = (0, state_document_cjs_2.computeProgressPercent)((0, state_document_cjs_2.toFiniteNumber)(merged.completed_plans), (0, state_document_cjs_2.toFiniteNumber)(merged.total_plans), (0, state_document_cjs_2.toFiniteNumber)(merged.completed_phases), (0, state_document_cjs_2.toFiniteNumber)(merged.total_phases), planningScopeMod.SCOPE.COMPLETE);
+    if (recomputed !== null && recomputed !== (0, state_document_cjs_2.toFiniteNumber)(merged.percent)) {
+        merged.percent = recomputed;
+    }
+}
 /**
  * Executor for `preservation: 'preserve-always'` (ADR-3408 §8.1). Only
  * `progress` carries this policy today. Preserves #3242/#1446/#2440/#2969
@@ -719,18 +745,23 @@ function applyPreserveAlways(field, cls, ctx) {
             // completed after the plan count grew) — ratcheting UP only, never
             // deriving downward (preserves the #3242 curated-progress protection
             // for cases unrelated to plan-count growth, e.g. a deleted SUMMARY).
-            // percent also takes the derived value — the resync recomputed it from
-            // disk counts, and a stale curated percent would be incoherent against
-            // the ratcheted-up completed counts (e.g. 54/54 at 93%).
+            // percent is recomputed over the counters actually written (#5619): the
+            // disk-derived percent is only coherent with the DERIVED counters, and a
+            // stale curated percent would be incoherent against the ratcheted-up
+            // completed counts (e.g. 54/54 at 93%).
             const ratchetUpKeys = new Set(['completed_plans', 'completed_phases']);
             for (const [key, value] of Object.entries(curatedRecord)) {
                 if (key === 'total_plans' || key === 'total_phases' || key === 'percent')
                     continue;
                 if (ratchetUpKeys.has(key)) {
-                    const derivedNum = typeof derivedRecord[key] === 'number' ? derivedRecord[key] : -Infinity;
-                    const curatedNum = typeof value === 'number' ? value : -Infinity;
+                    // Frontmatter scalars arrive as STRINGS ("2", not 2): coerce through
+                    // `toFiniteNumber`, never a `typeof === 'number'` test (#5619 — that
+                    // test made both sides -Infinity and the ratchet unreachable).
+                    const derivedNum = (0, state_document_cjs_2.toFiniteNumber)(derivedRecord[key]) ?? -Infinity;
+                    const curatedNum = (0, state_document_cjs_2.toFiniteNumber)(value) ?? -Infinity;
                     // Take the derived value only when it ratchets up (strictly
-                    // greater — #2969's `>` not `>=`); else keep curated.
+                    // greater — #2969's `>` not `>=`); else keep curated, with its
+                    // spelling, on a tie too.
                     if (derivedNum > curatedNum)
                         continue;
                     merged[key] = value;
@@ -740,6 +771,7 @@ function applyPreserveAlways(field, cls, ctx) {
                 }
             }
         }
+        recomputeMergedProgressPercent(merged, derivedRecord);
         next = merged;
     }
     else {
@@ -876,7 +908,36 @@ exports.STATE_MD_SECTIONS = {
  * Phases 2–7 add cases for the remaining 9 intent kinds. A missing case is
  * a compile-time error (the function would not return on that path).
  */
+/**
+ * The transitions that rewrite single-line body fields (`Status:`, `Current focus:`, `Plan:` …) with
+ * plain line-anchored patterns. Those patterns match a fenced EXAMPLE of a field as readily as the
+ * live line (#5460), so these run over the document body with fenced blocks hidden.
+ * `milestone*`, `prune` and `rebuild` restructure sections or re-derive the document and are not
+ * field-by-field writers.
+ */
+const FENCE_MASKED_TRANSITIONS = new Set([
+    'beginPhase', 'advancePlan', 'completePhase', 'plannedPhase', 'patch', 'update', 'sync',
+]);
 function transitionCore(content, intent, deps) {
+    if (!FENCE_MASKED_TRANSITIONS.has(intent.kind))
+        return transitionCoreUnmasked(content, intent, deps);
+    // Only the body is masked: a fence opener inside a frontmatter block scalar must not swallow the
+    // closing `---` (the frontmatter is not where the live fields are written).
+    const body = stripFrontmatter(content);
+    if (!content.endsWith(body))
+        return transitionCoreUnmasked(content, intent, deps);
+    const prefix = content.slice(0, content.length - body.length);
+    const fenceMask = (0, markdown_sectionizer_cjs_1.maskFences)(body);
+    const result = transitionCoreUnmasked(prefix + fenceMask.masked, intent, deps);
+    const restored = fenceMask.restore(result.content);
+    // Cannot happen short of a writer bug (a transition dropped or duplicated a placeholder line); a
+    // refusal is the one outcome that cannot report a rewrite that did not land.
+    if (restored === null) {
+        throw new Error(`${intent.kind}: fenced code blocks could not be restored after the edit; refusing to write STATE.md`);
+    }
+    return { ...result, content: restored };
+}
+function transitionCoreUnmasked(content, intent, deps) {
     switch (intent.kind) {
         case 'beginPhase':
             return beginPhaseCore(content, intent, deps);
@@ -980,7 +1041,7 @@ function beginPhaseCore(content, intent, deps) {
             tryField('Current Phase Name', intent.phaseName);
         }
         tryField('Current Plan', String(startPlan));
-        if (intent.planCount) {
+        if (intent.planCount != null) {
             tryField('Total Plans in Phase', String(intent.planCount));
         }
         // **Current focus:** body text line (#1104).
@@ -1104,7 +1165,9 @@ function mutateCurrentPositionFirstTime(body, intent, today, updated) {
     const span = locateCurrentPosition(body);
     if (span === null)
         return body;
-    let sectionBody = body.slice(span.start, span.end);
+    // #5460: the section's fenced examples are hidden while the live lines are rewritten.
+    const fenceMask = (0, markdown_sectionizer_cjs_1.maskFences)(body.slice(span.start, span.end));
+    let sectionBody = fenceMask.masked;
     // Phase line — inline first, then pipe-table fallback (#1257).
     const phaseLabel = `${intent.phaseNumber}${intent.phaseName ? ` (${intent.phaseName})` : ''} — EXECUTING`;
     if (/^Phase:/m.test(sectionBody)) {
@@ -1116,7 +1179,7 @@ function mutateCurrentPositionFirstTime(body, intent, today, updated) {
             sectionBody = replaced;
     }
     // Plan line.
-    const planValue = `${intent.startPlan} of ${intent.planCount || '?'}`;
+    const planValue = `${intent.startPlan} of ${intent.planCount ?? '?'}`;
     if (/^Plan:/m.test(sectionBody)) {
         sectionBody = sectionBody.replace(/^Plan:.*$/m, `Plan: ${planValue}`);
     }
@@ -1146,8 +1209,11 @@ function mutateCurrentPositionFirstTime(body, intent, today, updated) {
         if (replaced !== null)
             sectionBody = replaced;
     }
+    const restored = fenceMask.restore(sectionBody);
+    if (restored === null)
+        return body;
     updated.push('Current Position');
-    return body.slice(0, span.start) + sectionBody + body.slice(span.end);
+    return body.slice(0, span.start) + restored + body.slice(span.end);
 }
 /**
  * Resume ## Current Position mutation: only update Last activity line
@@ -1158,7 +1224,8 @@ function mutateCurrentPositionResume(body, intent, today, updated) {
     const span = locateCurrentPosition(body);
     if (span === null)
         return body;
-    let sectionBody = body.slice(span.start, span.end);
+    const fenceMask = (0, markdown_sectionizer_cjs_1.maskFences)(body.slice(span.start, span.end));
+    let sectionBody = fenceMask.masked;
     const resumeActivity = `Last activity: ${today} — Phase ${intent.phaseNumber} execution resumed (wave continue)`;
     if (/^Last activity:/im.test(sectionBody)) {
         sectionBody = sectionBody.replace(/^Last activity:.*$/im, resumeActivity);
@@ -1173,7 +1240,10 @@ function mutateCurrentPositionResume(body, intent, today, updated) {
             updated.push('Last activity (resume)');
         }
     }
-    return body.slice(0, span.start) + sectionBody + body.slice(span.end);
+    const restored = fenceMask.restore(sectionBody);
+    if (restored === null)
+        return body;
+    return body.slice(0, span.start) + restored + body.slice(span.end);
 }
 const PLAN_SHAPE_N = /^(\d+)(?:\s.*)?$/;
 const PLAN_SHAPE_N_OF_M = /^(\d+)\s+of\s+(\d+)(?:\s.*)?$/;
@@ -1230,7 +1300,8 @@ function mutateCurrentPositionForAdvance(content, fields, statusDefaults, lastAc
     const span = locateCurrentPosition(content);
     if (span === null)
         return content;
-    let sectionBody = content.slice(span.start, span.end);
+    const fenceMask = (0, markdown_sectionizer_cjs_1.maskFences)(content.slice(span.start, span.end));
+    let sectionBody = fenceMask.masked;
     let mutated = false;
     // #3395: Phase is always replaced when a caller passes it — system-derived,
     // not executor-authored (same rule as Plan below). plannedPhaseCore uses
@@ -1343,7 +1414,10 @@ function mutateCurrentPositionForAdvance(content, fields, statusDefaults, lastAc
     }
     if (!mutated)
         return content;
-    return content.slice(0, span.start) + sectionBody + content.slice(span.end);
+    const restored = fenceMask.restore(sectionBody);
+    if (restored === null)
+        return content;
+    return content.slice(0, span.start) + restored + content.slice(span.end);
 }
 // ----------------------------------------------------------------------------
 // advancePlan — intent implementation (Phase 2)
@@ -1642,6 +1716,29 @@ function nextPhaseWording(disk) {
             return { status: 'Ready to plan', currentPlan: 'Not started', stoppedAt: 'ready to plan' };
     }
 }
+/**
+ * #5165: is STATE.md already positioned PAST phase `phaseNum`? True when its
+ * current phase (frontmatter `current_phase`, else the body `Current Phase` /
+ * `Phase` field's leading phase token) compares greater than `phaseNum`.
+ * Re-completing a phase STATE has already moved past must not rewind the
+ * position; the caller combines this with "the phase is already complete in
+ * ROADMAP.md" so a first-time out-of-order completion (#2028) still
+ * transitions. An unparseable or absent current phase is "not past".
+ */
+function isStatePastPhase(content, phaseNum, sourcePath) {
+    const fm = extractFrontmatter(content, sourcePath);
+    const fromFm = fm['current_phase'];
+    let raw = typeof fromFm === 'string' || typeof fromFm === 'number' ? String(fromFm) : null;
+    if (raw === null || raw.trim() === '') {
+        const body = stripFrontmatter(content);
+        raw = (0, state_document_cjs_1.stateExtractField)(body, 'Current Phase') || (0, state_document_cjs_1.stateExtractField)(body, 'Phase') || null;
+    }
+    // `Phase 4` / `phase 4 of 9` name phase 4 as surely as `4 of 9` does.
+    const m = raw === null ? null : /^\s*(?:phase\s+)?(\d+(?:\.\d+)*)/i.exec(raw);
+    if (!m)
+        return false;
+    return comparePhaseNum(m[1], String(phaseNum)) > 0;
+}
 /**
  * Apply a `completePhase` transition to STATE.md content.
  *
@@ -1669,6 +1766,12 @@ function completePhaseCore(content, intent, deps) {
     const updated = [];
     const today = deps.clock.localToday();
     const nextWording = nextPhaseWording(intent.isLastPhase ? null : intent.nextPhaseDisk ?? null);
+    // #5165: the milestone the caller resolved (ROADMAP-bound identity first) wins;
+    // else the milestone STATE asserts. It scopes the roadmap-derived counters
+    // below to that milestone's Progress-table rows, the same milestone
+    // `phase complete` scopes its frontmatter progress to.
+    const currentMilestone = (0, roadmap_progress_cjs_1.milestoneVersionOf)(intent.milestone)
+        ?? (0, roadmap_progress_cjs_1.milestoneVersionOf)(extractFrontmatter(content, deps.sourcePath)['milestone']);
     // Consult the field-classification table for the frontmatter keys this
     // transition touches (same guard beginPhaseCore applies). A missing row is a
     // substrate defect — fail loudly rather than silently re-encoding policy.
@@ -1812,7 +1915,7 @@ function completePhaseCore(content, intent, deps) {
         let derivedTotalPhases = null;
         const roadmapContent = deps.roadmapProvider ? deps.roadmapProvider() : null;
         if (roadmapContent) {
-            const derived = (0, phase_lifecycle_cjs_1.deriveProgressFromRoadmap)(roadmapContent);
+            const derived = (0, phase_lifecycle_cjs_1.deriveProgressFromRoadmap)(roadmapContent, currentMilestone);
             // #4901: completed counters only ratchet up, like the frontmatter twin
             // (applyAuthoritativeProgressSubkeys, completedOnlyRaise). A derivation
             // that lands BELOW the recorded counter read a narrower scope than the
@@ -1933,8 +2036,16 @@ function plannedPhaseCore(content, intent, deps) {
     // Phase is system-derived, always replaced (Knuth invariant does not apply);
     // Status / Last activity stay template-aware.
     const beforePos = body;
+    // #5369: with no --name the label reuses the curated frontmatter name (when it is a real one), so the
+    // body line and the frontmatter agree on it (the #3834 reassert keeps that name in frontmatter). A
+    // status fragment a pre-fix write left there is never copied back into the name slot.
+    const curatedName = existingFm['current_phase_name'];
+    const labelName = intent.phaseName
+        ?? (typeof curatedName === 'string' && curatedName.trim() !== '' && !phaseIdMod.isPlannedPhaseStatusPhrase(curatedName)
+            ? curatedName.trim()
+            : null);
     body = mutateCurrentPositionForAdvance(body, {
-        phase: `${intent.phaseNumber}${intent.phaseName ? ` (${intent.phaseName})` : ''} — READY TO EXECUTE`,
+        phase: `${intent.phaseNumber}${labelName ? ` (${labelName})` : ''} — READY TO EXECUTE`,
         status: 'Ready to execute',
         lastActivity: `${today} — Phase ${intent.phaseNumber} planning complete`,
     }, statusDefaults, lastActivityDefaults);
@@ -2255,7 +2366,20 @@ function patchCore(content, intent) {
         // `^field:` pattern — e.g. `status` matching both the frontmatter key
         // and a `Status:` body line). Frontmatter is only consulted when the
         // body has no match for this key.
-        const replaced = (0, state_document_cjs_1.stateReplaceField)(body, field, value);
+        // #4998: a session field is written the way `state update` writes it —
+        // inside the session section, never a fenced example there — so the
+        // patch agrees with the session readers the frontmatter sync uses.
+        const sessionWriteLabels = sessionLabelsForBodyField(field);
+        let replaced;
+        if (sessionWriteLabels) {
+            const inSession = (0, state_document_cjs_1.stateReplaceFieldInSession)(body, sessionWriteLabels.primary, sessionWriteLabels.fallback, value);
+            // Unchanged is a miss only when the field is absent: one already holding
+            // the value matched (#4488), as stateReplaceField reports it.
+            replaced = inSession !== body || sessionSourceExists(body, sessionWriteLabels) ? inSession : null;
+        }
+        else {
+            replaced = (0, state_document_cjs_1.stateReplaceField)(body, field, value);
+        }
         if (replaced !== null) {
             body = replaced;
             updated.push(field);
@@ -2321,10 +2445,10 @@ function updateCore(content, intent) {
     const sessionWriteLabels = sessionLabelsForBodyField(intent.field);
     let result;
     if (sessionWriteLabels) {
-        // Replace-only by contract: unchanged content means the field is not in the
-        // session section, which is a miss, not a write.
+        // Replace-only by contract: the session writer never inserts a missing field.
         const replaced = (0, state_document_cjs_1.stateReplaceFieldInSession)(body, sessionWriteLabels.primary, sessionWriteLabels.fallback, intent.value);
-        result = replaced === body ? null : replaced;
+        // A field already holding the value matched; unchanged with no field is the miss (#4488).
+        result = replaced !== body || sessionSourceExists(body, sessionWriteLabels) ? replaced : null;
     }
     else {
         result = (0, state_document_cjs_1.stateReplaceField)(body, intent.field, intent.value);