@opengsd/gsd-core 1.13.0 → 1.15.0

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

@@ -25,6 +25,7 @@ exports.getFieldClassification = getFieldClassification;
 exports.getPreserveWhenUnchangedFields = getPreserveWhenUnchangedFields;
 exports.openStateTransaction = openStateTransaction;
 exports.rebuildStateTransaction = rebuildStateTransaction;
+exports.createStateWriteIntent = createStateWriteIntent;
 exports.applyPreserveWhenUnchanged = applyPreserveWhenUnchanged;
 exports.applyStatePreservation = applyStatePreservation;
 exports.transitionCore = transitionCore;
@@ -36,6 +37,11 @@ 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 pattern_cjs_1 = require("./pattern.cjs");
+// #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).
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningScopeMod = require("./planning-scope.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const stateMdSchemaMod = require("./state-md-schema.cjs");
 const { STATE_FIELD_SCHEMA } = stateMdSchemaMod;
@@ -44,12 +50,13 @@ function formatProgressMachineSegment(percent) {
     // ADR-3180 Decision 7: rounding and the 100 ceiling belong to the
     // completion-ratio kernel. The floor is added here because this helper is
     // also fed persisted frontmatter values (hand-editable, unlike the
-    // count-shaped entries into that kernel), and `'░'.repeat` throws on a
-    // negative count. Bar and printed percent use the clamped value so the two
-    // halves of the segment can never disagree.
+    // count-shaped entries into that kernel). Bar and printed percent use the
+    // clamped value so the two halves of the segment can never disagree.
+    // #4294: the CELL count is the render kernel's — `renderProgressBar` holds a
+    // sub-100 percent one cell short of full, so `[██████████]` beside `95%`
+    // cannot recur here as a seventh inline copy of the rounding.
     const clamped = Math.max(0, (0, phase_lifecycle_cjs_1.clampPercentFromFraction)(percent / 100));
-    const filled = Math.round(clamped / 10);
-    return `[${'█'.repeat(filled)}${'░'.repeat(10 - filled)}] ${clamped}%`;
+    return `[${(0, phase_lifecycle_cjs_1.renderProgressBar)(clamped, 10)}] ${clamped}%`;
 }
 // Consumers (a future STATE.md writer that bypasses all three reintroduces the
 // #4213 divergence class): `cmdStateUpdateProgress` and `syncCore`'s progress
@@ -60,11 +67,29 @@ function formatProgressMachineSegment(percent) {
 // `syncCore`'s call here.
 function stateReplaceProgressPercent(content, percent) {
     const body = stripFrontmatter(content);
-    // #2177: bold `**Progress:**` anywhere in the body wins outright; the plain
-    // `^Progress:` form is the fallback only when no bold line exists, so an
-    // earlier free-text line starting with `Progress:` cannot capture the
-    // rewrite ahead of the real status line.
-    const boldProgressPattern = /(\*\*Progress:\*\*[ \t]*)([^\r\n]*)/i;
+    // #2177: bold `**Progress:**` takes priority over the plain `^Progress:`
+    // form, so an earlier free-text line starting with `Progress:` cannot
+    // capture the rewrite ahead of the real status line.
+    //
+    // #4243 (follow-up to #4453, maintainer ruling 2026-09-07): the bold form
+    // is also ANCHORED to line start, with same-line leading whitespace only —
+    // the exact idiom #4453 applied to stateReplaceField's bold branch. The
+    // pre-fix pattern carried no `^` and no `m` flag, so a bold percent-ish
+    // label quoted MID-SENTENCE inside prose (an Accumulated Context bullet
+    // mentioning `**Progress:**`) captured the machine-segment rewrite and
+    // destroyed the rest of its line, silently, while the real Progress line
+    // stayed stale — every caller (cmdStateUpdateProgress, syncCore's percent
+    // arm, applyPostSyncPreservation) feeds the whole document. #2177's own
+    // recorded requirements are unaffected: the frontmatter is stripped before
+    // matching (its defect was the YAML `progress:` key shadowing the body
+    // line), the suffix-preserving machine-segment swap is untouched, and the
+    // bold-beats-plain priority now governs LINE-START forms. The leading class
+    // is `[ \t]*`, deliberately NOT `\s*` — `^\s*\*\*` can consume the newlines
+    // before the label into the match and drop them on rebuild (#4010's
+    // same-line confinement hazard). `$` is explicit-and-inert (`[^\r\n]*`
+    // never crosses line terminators) and documents that the match ends at
+    // end-of-line.
+    const boldProgressPattern = /^([ \t]*\*\*Progress:\*\*[ \t]*)([^\r\n]*)$/im;
     const plainProgressPattern = /^(Progress:[ \t]*)([^\r\n]*)/im;
     const pattern = boldProgressPattern.test(body)
         ? boldProgressPattern
@@ -377,6 +402,28 @@ function openStateTransaction(init) {
 function rebuildStateTransaction(init) {
     return createStateTransaction('rebuild', init, 'rebuildStateTransaction');
 }
+/**
+ * Extend an existing StateTransaction into a StateWriteIntent. The base
+ * transaction is REQUIRED — an absent base is a construction failure, mirroring
+ * `createStateTransaction`'s ADR-3473 §8.6 posture (do not tolerate null). `scope`
+ * defaults to the conservative `'narrow'`; `assertions` defaults to none. Frozen
+ * so an intent, like a transaction, cannot be mutated after construction.
+ */
+function createStateWriteIntent(transaction, init = {}) {
+    if (transaction === null || typeof transaction !== 'object' || Array.isArray(transaction)) {
+        const err = new Error('createStateWriteIntent: a base StateTransaction is required (build it with ' +
+            'openStateTransaction / rebuildStateTransaction first). Per ADR-4629 §8.1, an absent ' +
+            'transaction is a construction failure — do not tolerate null.');
+        err.code = 'STATE_WRITE_INTENT_TRANSACTION_REQUIRED';
+        throw err;
+    }
+    const assertions = Object.freeze((init.assertions ?? []).map((a) => Object.freeze({ field: a.field, requirement: a.requirement })));
+    return Object.freeze({
+        ...transaction,
+        assertions,
+        scope: init.scope ?? 'narrow',
+    });
+}
 /**
  * ADR-3408 §8.2: an unenforced `preserve-when-unchanged` row throws. Both
  * ends of this invariant are gsd-core's own source — a declared row the
@@ -508,6 +555,72 @@ function preservedValuesEqual(a, b) {
     }
     return a === b;
 }
+/**
+ * #4129: the resync-arm progress merge. A resyncing write whose scan MEASURED
+ * something no longer wholesale-replaces the curated block — the declared
+ * `progress-ratchet` mergeStrategy ("completed_plans/completed_phases only ever
+ * ratchet UP toward the derived value (#2969)", state-md-schema.cts) now holds
+ * on the write path too, matching what the read path (`shouldPreserveExistingProgress`)
+ * has always enforced. Rules, mirroring the `deriveProgressKeys` branch above:
+ *
+ * - total_plans / total_phases always take the derived value (#2440 — totals
+ *   correct in BOTH directions).
+ * - completed_plans / completed_phases take the derived value only when it is
+ *   strictly GREATER (#2969's `>` not `>=`); else the curated value survives
+ *   (a hand-corrected or previously-correct counter can never be re-derived
+ *   downward — the #4129 clobber).
+ * - any other key keeps the curated value (the existing branch's convention).
+ * - percent is RECOMPUTED from the merged counters through the single kernel
+ *   (`computeProgressPercent`), because either side's stored percent was
+ *   computed against that side's counters and the merged block may mix them
+ *   (curated completed, derived totals). Recomputation runs ONLY when the
+ *   derived block itself carried a percent — an upstream withhold
+ *   (#1761 milestone-unbounded, #3217 scope) nulled percent deliberately and
+ *   this merge must not resurrect it.
+ *
+ * Frontmatter scalars arrive as STRINGS ("2", not 2), so every comparison
+ * coerces through `toFiniteNumber` — never a `typeof === 'number'` test
+ * (scanMeasuredSomething's own convention).
+ */
+function mergeResyncProgressRatchet(curatedRecord, derivedRecord) {
+    const merged = { ...derivedRecord };
+    for (const [key, value] of Object.entries(curatedRecord)) {
+        if (key === 'total_plans' || key === 'total_phases' || key === 'percent')
+            continue;
+        if (key === 'completed_plans' || key === 'completed_phases') {
+            const derivedNum = (0, state_document_cjs_2.toFiniteNumber)(derivedRecord[key]) ?? -Infinity;
+            const curatedNum = (0, state_document_cjs_2.toFiniteNumber)(value) ?? -Infinity;
+            // Ratchet up only (strictly greater, #2969); else keep curated.
+            if (derivedNum > curatedNum)
+                continue;
+            // Numerically EQUAL keeps the derived value VERBATIM. The two sides
+            // arrive in different scalar shapes (the re-parsed derived block
+            // carries string totals "2" while the curated snapshot carries numbers
+            // 2), and substituting the curated spelling over an equal derived one
+            // is a no-op in substance but a shape churn the §8.7 reporting loop
+            // would surface as a phantom `preserved-over-disagreeing-derived`
+            // warning (it diffs structurally). Only a curated counter that is
+            // STRICTLY greater replaces the derived value.
+            if (derivedNum === curatedNum)
+                continue;
+            merged[key] = value;
+        }
+        else {
+            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;
+        }
+    }
+    return merged;
+}
 /**
  * Executor for `preservation: 'preserve-always'` (ADR-3408 §8.1). Only
  * `progress` carries this policy today. Preserves #3242/#1446/#2440/#2969
@@ -523,25 +636,39 @@ function applyPreserveAlways(field, cls, ctx) {
     const derived = ctx.postFm[field];
     const derivedMeasured = scanMeasuredSomething(cls, derived);
     const curatedMeasured = scanMeasuredSomething(cls, curated);
-    // On a resyncing write the fresh derivation is authoritative — UNLESS it
-    // measured nothing while the curated block did (#3756), AND the caller did
-    // not explicitly name a progress-affecting field this write. The
-    // unmeasured-scan guard exists to stop an INCIDENTAL resync (e.g. `state
-    // add-decision`, whose `resync` defaults true for reasons that have
-    // nothing to do with `progress`) from dropping a real curated block when a
-    // milestone-scoped disk scan measures nothing (#3756's archived-milestone
-    // case). It must not also block a write the user pointed AT `progress` on
-    // purpose: `preserve-always`'s own contract is "never overwrite unless the
-    // caller explicitly names this field" (FIELD_CLASSIFICATION doc comment),
-    // and `state update Progress` / `state patch Progress=...` are exactly
-    // that naming — the resync they trigger must win even when the disk scan
-    // it also drives (e.g. because there are no phase dirs at all) reads as
-    // "unmeasured" (tests/frontmatter.test.cjs: "state.update \"Progress\"
-    // resyncs progress frontmatter from the updated body", pre-existing, #3242).
-    if (ctx.resync && (derivedMeasured || !curatedMeasured || ctx.explicitProgressField))
+    // On a resyncing write the fresh derivation is authoritative in two cases
+    // (#3756 / ADR-3473 §8.6, unchanged): when the caller EXPLICITLY named a
+    // progress-affecting field (`preserve-always`'s contract is "never
+    // overwrite unless the caller explicitly names this field" — `state update
+    // Progress` is exactly that naming, pre-existing #3242 behavior), and when
+    // the derivation measured something the curated block did not (an
+    // unmeasured CURATED block is not worth protecting). The unmeasured-DERIVED
+    // guard also stands: an incidental resync (e.g. `state add-decision`, whose
+    // `resync` defaults true for reasons that have nothing to do with
+    // `progress`) that measured nothing must not drop a real curated block
+    // (#3756's archived-milestone case) — that falls through to the wholesale
+    // restore below.
+    //
+    // #4129 narrows the remaining arm. A resyncing write whose scan MEASURED
+    // something while the curated block is also real previously wholesale-
+    // replaced the curated block with the derived one — no monotonic guard, so
+    // any under-counting derivation (a stale-dated verification, #2348) silently
+    // reverted every hand-correction and every correct value an earlier write
+    // had persisted, while the read path (`shouldPreserveExistingProgress`)
+    // kept reporting the higher stored counters. That arm now falls through to
+    // `mergeResyncProgressRatchet` — the declared `progress-ratchet`
+    // mergeStrategy, finally enforced on the write path: totals derived both
+    // directions (#2440), completed counters up-only (#2969), percent
+    // recomputed from the merged counters.
+    if (ctx.resync && (ctx.explicitProgressField || (derivedMeasured && !curatedMeasured)))
         return;
     let next;
-    if (cls.mergeStrategy === 'progress-ratchet' && ctx.deriveProgressKeys && derived && derivedMeasured) {
+    if (cls.mergeStrategy === 'progress-ratchet' && ctx.resync && derived && derivedMeasured && curatedMeasured) {
+        // #4129 resync arm — see mergeResyncProgressRatchet's doc. Reached only
+        // after the early-out above, so curatedMeasured is guaranteed true here.
+        next = mergeResyncProgressRatchet(curated, (derived ?? {}));
+    }
+    else if (cls.mergeStrategy === 'progress-ratchet' && ctx.deriveProgressKeys && derived && derivedMeasured) {
         // #2440: total_plans and total_phases always take the derived (post-sync)
         // value even under !resync. This is used by cmdStatePlannedPhase where
         // total_plans must correct upward after plans are added. For body-only
@@ -824,7 +951,17 @@ function beginPhaseCore(content, intent, deps) {
         const focusLabel = intent.phaseName
             ? `Phase ${intent.phaseNumber} — ${intent.phaseName}`
             : `Phase ${intent.phaseNumber}`;
-        const focusPattern = /(\*\*Current focus:\*\*\s*).*/i;
+        // #4469: anchored to line start with same-line whitespace only, mirroring
+        // #4243/PR #4453's fix to stateReplaceField's bold branch. The pre-fix
+        // pattern carried no `^`/`m` and used `\s*` (crosses newlines), so a bold
+        // `**Current focus:**` quoted mid-sentence elsewhere in the body (e.g. an
+        // Accumulated Context bullet) matched first and had the rest of its line
+        // silently overwritten with the new focus label -- the same #4010
+        // data-loss class. `[ \t]*` (not `\s*`) avoids consuming the newlines
+        // before the label into the match; `$` documents the match ends at
+        // end-of-line (inert here since `.` never crosses line terminators
+        // without `/s`, which is not set).
+        const focusPattern = /^([ \t]*\*\*Current focus:\*\*[ \t]*)(.*)$/im;
         if (focusPattern.test(body)) {
             body = body.replace(focusPattern, (_match, prefix) => `${prefix}${focusLabel}`);
             updated.push('Current focus');
@@ -1534,8 +1671,22 @@ function completePhaseCore(content, intent, deps) {
         body = statusAfter;
         updated.push('Status');
     }
-    // Current Plan — reset for the next phase.
-    const planAfter = (0, state_document_cjs_1.stateReplaceFieldWithFallback)(body, 'Current Plan', 'Plan', 'Not started');
+    // Current Plan — reset for the next phase. #4823: when a Current Position
+    // section exists (the canonical layout, #2956 locator), the reset is scoped
+    // to it — the whole-body fallback 'Plan' run matched any hard-wrapped prose
+    // line starting with `plan:` anywhere in the document and rewrote it to
+    // 'Not started', silently destroying narrative. Legacy sectionless layouts
+    // (fields at top level, no section) keep the whole-body behavior unchanged:
+    // there is no section to scope to, and their fields are the intended
+    // targets.
+    let planAfter;
+    const positionScope = (0, state_document_cjs_1.stateCurrentPositionSlice)(body);
+    if (positionScope !== null) {
+        planAfter = (0, markdown_sectionizer_cjs_1.withSection)(body, (h) => (h.level === 2 || h.level === 3) && h.text.trim().toLowerCase() === 'current position', (sectionBody) => (0, state_document_cjs_1.stateReplaceFieldWithFallback)(sectionBody, 'Current Plan', 'Plan', 'Not started'), { levelBounded: true });
+    }
+    else {
+        planAfter = (0, state_document_cjs_1.stateReplaceFieldWithFallback)(body, 'Current Plan', 'Plan', 'Not started');
+    }
     if (planAfter !== body) {
         body = planAfter;
         updated.push('Current Plan');