@opengsd/gsd-core 1.12.0 → 1.14.0

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

@@ -16,6 +16,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.STATE_MD_SECTIONS = exports.FRONTMATTER_BODY_SOURCE = exports.FIELD_CLASSIFICATION = void 0;
+exports.formatProgressMachineSegment = formatProgressMachineSegment;
+exports.stateReplaceProgressPercent = stateReplaceProgressPercent;
 exports.beginFrontmatterReassembly = beginFrontmatterReassembly;
 exports.getFrontmatterBodySource = getFrontmatterBodySource;
 exports.frontmatterKeyForBodyField = frontmatterKeyForBodyField;
@@ -34,10 +36,72 @@ 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;
 const { extractFrontmatter, reconstructFrontmatter, stripFrontmatter, FRONTMATTER_UNPARSEABLE } = frontmatter;
+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). 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));
+    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
+// intent (both in this module) plus the post-sync body reconciliation in
+// `applyPostSyncPreservation` (src/state.cts). `cmdStateSync` never reaches
+// that reconciliation — ADR-3408 §8.3: `state sync` lets the body win, so
+// preservation must NOT run — which is why its correctness comes from
+// `syncCore`'s call here.
+function stateReplaceProgressPercent(content, percent) {
+    const body = stripFrontmatter(content);
+    // #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
+        : plainProgressPattern.test(body)
+            ? plainProgressPattern
+            : null;
+    if (!pattern)
+        return null;
+    const machineSegment = /(?:\[[^\]\r\n]*\][ \t]*)?\d{1,3}%/;
+    const progress = formatProgressMachineSegment(percent);
+    const updatedBody = body.replace(pattern, (_match, prefix, value) => (`${prefix}${machineSegment.test(value) ? value.replace(machineSegment, progress) : progress}`));
+    return content.slice(0, content.length - body.length) + updatedBody;
+}
 /**
  * ADR-3473 §8.1 (#3881, consequence 2 wiring): does `existingFm` carry the
  * `FRONTMATTER_UNPARSEABLE` marker `extractFrontmatter` sets when a
@@ -468,6 +532,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
@@ -483,25 +613,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
@@ -784,7 +928,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');
@@ -955,6 +1109,46 @@ function mutateCurrentPositionResume(body, intent, today, updated) {
     }
     return body.slice(0, span.start) + sectionBody + body.slice(span.end);
 }
+const PLAN_SHAPE_N = /^(\d+)(?:\s.*)?$/;
+const PLAN_SHAPE_N_OF_M = /^(\d+)\s+of\s+(\d+)(?:\s.*)?$/;
+/**
+ * Parse a decimal group into a plan number, or `null` if it is not a value we
+ * are willing to do arithmetic on.
+ *
+ * `parseInt` is deliberately not used on the raw field: it truncates (`"2 of 5"`
+ * -> 2), accepts a sign (`"+2"`), and silently loses precision past
+ * `Number.MAX_SAFE_INTEGER`, where the number we report and the string we write
+ * back stop agreeing. The grammars above already exclude signs and trailing
+ * text, so the only remaining hazard is magnitude.
+ */
+function planNumberFrom(digits) {
+    const n = Number(digits);
+    return Number.isSafeInteger(n) ? n : null;
+}
+/**
+ * Advance the leading integer of a written plan value, preserving everything
+ * the author wrote around it: the zero-padding width ("04" -> "05") and any
+ * trailing remainder ("2 of 99" -> "3 of 99", and the `\r` of a CRLF file).
+ *
+ * The three parse branches disagree about the field NAME and about whether a
+ * total is carried inline, but they agree completely about this: only the
+ * leading digits are the plan number, and nothing else on the line belongs to
+ * this transition. Writing `String(newPlan)` instead — as the legacy branch
+ * did — discards the author's text on a branch nobody was reading.
+ *
+ * padStart never truncates, so 09 -> 10 widens rather than clipping.
+ */
+function bumpLeadingNumber(raw, next) {
+    const digits = /^\d+/.exec(raw);
+    // Total rather than pass-through. `raw.replace(/^\d+/, …)` returns the input
+    // unchanged when there are no leading digits, so `+2` advanced in `data` and
+    // wrote the file untouched — the command reported progress it had not made
+    // and could be re-run forever. The grammars make that unreachable today;
+    // returning null keeps it unreachable if a fourth branch is ever added.
+    if (!digits)
+        return null;
+    return raw.replace(/^\d+/, () => String(next).padStart(digits[0].length, '0'));
+}
 /**
  * Update fields within the ## Current Position section for advancePlan.
  * Mirrors `updateCurrentPositionFields` (state.cts:496) byte-for-behaviour:
@@ -1006,19 +1200,80 @@ function mutateCurrentPositionForAdvance(content, fields, statusDefaults, lastAc
             mutated = true;
         }
     }
-    if (fields.plan) {
+    if (fields.plan || fields.currentPlan) {
         // Plan is always replaced — system-derived, not executor-authored.
-        if (/^Plan:/m.test(sectionBody)) {
-            sectionBody = sectionBody.replace(/^Plan:.*$/m, `Plan: ${fields.plan}`);
-            mutated = true;
-        }
-        else {
-            const replaced = (0, state_document_cjs_1.stateReplaceField)(sectionBody, 'Plan', fields.plan);
+        //
+        // Which NAME to write is decided by what the SECTION carries, not by which
+        // header field the value was read from. Mirroring the header was wrong in
+        // both directions: a legacy header with a `Current Plan:` section line left
+        // the section a plan behind, and a hybrid header with a `Plan:` section line
+        // mutated nothing at all. The invariant is per-name — every site spelled
+        // `Current Plan` gets the `Current Plan` value, every `Plan` site gets the
+        // `Plan` value — so both are passed in and each is written where its own
+        // name appears.
+        //
+        // Title-Case LITERALS reach both the regex and stateReplaceField
+        // (ADR-3408 §8.3(b)): a literal cannot collide with a lowercase/snake_case
+        // frontmatter key, whatever the caller passed.
+        //
+        // The replacements go through a replacer FUNCTION, never a replacement
+        // string. `fields.plan` is derived from file content, and `String.replace`
+        // expands `$&`, `` $` `` and `$'` in a replacement string — a STATE.md
+        // carrying `Current Plan: 04 of 06 $&` would splice part of itself into the
+        // document. `stateReplaceField` already uses a function for this reason;
+        // these arms now agree with it.
+        // Each name is written INDEPENDENTLY, and each falls back on its own.
+        //
+        // Two defects lived in the previous shape, both of which produced the
+        // split-brain document this arm exists to prevent:
+        //
+        //   - The fallback was guarded by `!mutated`, and `mutated` is FUNCTION-wide
+        //     — already set by the `phase`/`status`/`lastActivity` arms above, which
+        //     `advancePlanCore` always populates. A section spelled `**Current
+        //     Plan:**` (bold) or as a pipe-table row therefore skipped its fallback
+        //     because an UNRELATED field had been refreshed, and the section stayed a
+        //     plan behind the header.
+        //   - The fallback then picked ONE name by ternary. In the legacy shape both
+        //     values are populated, so it always chose `Current Plan` and a
+        //     `**Plan:**` section line — which base did write — got nothing.
+        //
+        // `planWritten` is local, so nothing outside this arm can satisfy its guard.
+        let planWritten = false;
+        const writePlanField = (name, value) => {
+            if (!value)
+                return;
+            // Plain `Name:` line first. Title-Case LITERALS reach both the regex and
+            // stateReplaceField (ADR-3408 §8.3(b)), and the replacement goes through a
+            // replacer FUNCTION so a `$&` / `` $` `` / `$'` in the author's text is not
+            // expanded into the document.
+            if (name === 'Current Plan') {
+                if (/^Current Plan:/m.test(sectionBody)) {
+                    sectionBody = sectionBody.replace(/^Current Plan:.*$/m, () => `Current Plan: ${value}`);
+                    planWritten = true;
+                    return;
+                }
+                const replaced = (0, state_document_cjs_1.stateReplaceField)(sectionBody, 'Current Plan', value);
+                if (replaced !== null) {
+                    sectionBody = replaced;
+                    planWritten = true;
+                }
+                return;
+            }
+            if (/^Plan:/m.test(sectionBody)) {
+                sectionBody = sectionBody.replace(/^Plan:.*$/m, () => `Plan: ${value}`);
+                planWritten = true;
+                return;
+            }
+            const replaced = (0, state_document_cjs_1.stateReplaceField)(sectionBody, 'Plan', value);
             if (replaced !== null) {
                 sectionBody = replaced;
-                mutated = true;
+                planWritten = true;
             }
-        }
+        };
+        writePlanField('Current Plan', fields.currentPlan);
+        writePlanField('Plan', fields.plan);
+        if (planWritten)
+            mutated = true;
     }
     if (!mutated)
         return content;
@@ -1030,8 +1285,10 @@ function mutateCurrentPositionForAdvance(content, fields, statusDefaults, lastAc
 /**
  * Apply an `advancePlan` transition to STATE.md content.
  *
- * Parses Current Plan / Total Plans (legacy separate fields or compound
- * "Plan: X of Y" format), increments the plan number, updates body fields
+ * Parses Current Plan / Total Plans in any of three shapes — the legacy
+ * separate fields, the compound "Plan: X of Y", or the hybrid
+ * "Current Plan: X of Y" (legacy name, compound value, no Total Plans
+ * sibling) — increments the plan number, updates body fields
  * and the ## Current Position section. When currentPlan >= totalPlans,
  * takes the phase-complete branch (sets Status to "Phase complete — ready
  * for verification") instead of advancing.
@@ -1077,30 +1334,105 @@ function advancePlanCore(content, deps) {
             };
         }
     }
-    // Parse plan number — legacy first, then compound.
+    // Parse plan number — legacy pair first, then the hybrid, then compound.
+    //
+    // These branches decide ONE thing: which numbers the advance is computed
+    // from. They deliberately do not record which FIELD supplied them, because
+    // the write path no longer asks — every spelling is written back from its own
+    // raw text (#3791 review round 6, B1/M1). An earlier revision tracked a
+    // `planSourceField`/`planRawValue` pair here and then wrote the OTHER
+    // spelling from this one's numbers, which is precisely how a field ended up
+    // holding a value nothing had derived for it.
     const legacyPlan = (0, state_document_cjs_1.stateExtractField)(content, 'Current Plan');
     const legacyTotal = (0, state_document_cjs_1.stateExtractField)(content, 'Total Plans in Phase');
     const planField = (0, state_document_cjs_1.stateExtractField)(content, 'Plan');
-    let currentPlan;
-    let totalPlans;
-    let useCompoundFormat = false;
-    if (legacyPlan && legacyTotal) {
-        currentPlan = parseInt(legacyPlan, 10);
-        totalPlans = parseInt(legacyTotal, 10);
-    }
-    else if (planField) {
-        currentPlan = parseInt(planField, 10);
-        const ofMatch = planField.match(/of\s+(\d+)/);
-        totalPlans = ofMatch ? parseInt(ofMatch[1], 10) : NaN;
-        useCompoundFormat = true;
-    }
-    else {
-        currentPlan = NaN;
-        totalPlans = NaN;
-    }
-    if (isNaN(currentPlan) || isNaN(totalPlans)) {
+    // Every branch below reads its numbers out of an ANCHORED match's capture
+    // groups. Nothing here calls parseInt on a raw field value, so a value the
+    // grammar does not fully describe cannot half-parse into a plausible number.
+    const legacyNMatch = legacyPlan ? PLAN_SHAPE_N.exec(legacyPlan) : null;
+    const legacyNofMMatch = legacyPlan ? PLAN_SHAPE_N_OF_M.exec(legacyPlan) : null;
+    const totalNMatch = legacyTotal ? PLAN_SHAPE_N.exec(legacyTotal) : null;
+    const planNofMMatch = planField ? PLAN_SHAPE_N_OF_M.exec(planField) : null;
+    const planNMatch = planField ? PLAN_SHAPE_N.exec(planField) : null;
+    let parsedCurrent = null;
+    let parsedTotal = null;
+    if (legacyPlan && legacyTotal && (legacyNMatch || legacyNofMMatch) && totalNMatch) {
+        // Legacy pair wins whenever both fields are present and both are readable,
+        // even if the Current Plan value also carries an "of M" — the explicit
+        // sibling field is the stated intent, so it supplies the total.
+        parsedCurrent = planNumberFrom((legacyNMatch ?? legacyNofMMatch)[1]);
+        parsedTotal = planNumberFrom(totalNMatch[1]);
+    }
+    else if (legacyNofMMatch) {
+        // Hybrid: legacy field name, compound value, no readable Total Plans
+        // sibling. Written by hand (and by agents) often enough to be worth
+        // reading — #3784.
+        parsedCurrent = planNumberFrom(legacyNofMMatch[1]);
+        parsedTotal = planNumberFrom(legacyNofMMatch[2]);
+    }
+    else if (planNofMMatch) {
+        parsedCurrent = planNumberFrom(planNofMMatch[1]);
+        parsedTotal = planNumberFrom(planNofMMatch[2]);
+    }
+    // No branch for a bare `Plan: N` paired with a `Total Plans in Phase: M`
+    // sibling and no `Current Plan` at all (#3791 review round 6, M2). A revision
+    // of this PR accepted it; base did not (its `else if (planField)` arm had no
+    // `of M` match and errored via NaN), and it is out of #3784's scope, which is
+    // the hybrid `Current Plan: N of M`. It cannot be given the schema-row +
+    // forcing-test coupling the other shapes have, either: `Plan` is body-only,
+    // `buildStateFrontmatter` never reads it into frontmatter, so there is no
+    // `current_*` key to hang a row on. An accepted shape with no schema row and
+    // no forcing test is exactly the drift this diff is otherwise built to
+    // prevent, so the shape is refused and named in the error instead.
+    if (parsedCurrent === null || parsedTotal === null) {
         return { content: reassemble(body), updated: [], data: { error: true } };
     }
+    const currentPlan = parsedCurrent;
+    const totalPlans = parsedTotal;
+    // Each SPELLING's own plan number, read from its own value (#3791 review
+    // round 6, B1/M1). The parse above picks ONE field to advance FROM; these are
+    // what each field independently claims, and they are the only honest basis
+    // for writing that field back.
+    const legacyOwnCurrent = legacyNMatch || legacyNofMMatch
+        ? planNumberFrom((legacyNMatch ?? legacyNofMMatch)[1])
+        : null;
+    const planOwnCurrent = planNofMMatch || planNMatch
+        ? planNumberFrom((planNofMMatch ?? planNMatch)[1])
+        : null;
+    // A document carrying BOTH spellings with DIFFERENT plan numbers disagrees
+    // with itself, and no rule here can say which half is right. Refuse.
+    //
+    // This is the #3807 posture one field over: name the conflict, let the caller
+    // resolve it, never pick. The alternative shipped in an earlier revision of
+    // this PR and was the round-6 Blocker — with `Plan` as the parse source, the
+    // write path re-stamped `Current Plan`'s value with the number it had just
+    // derived from `Plan`, so `Current Plan: 7` beside `Plan: 2 of 5` silently
+    // became `Current Plan: 3`. A number with no relationship to the field it was
+    // written into, no error, no diagnostic.
+    //
+    // Placed BEFORE the phase-complete branch deliberately. Guarding only the
+    // normal advance leaves `Current Plan: 7` beside `Plan: 5 of 5` writing a
+    // terminal "Phase complete — ready for verification" into a document whose
+    // two spellings never agreed on where execution was.
+    //
+    // Differing TOTALS are NOT a disagreement about position and are preserved,
+    // not resolved: `Current Plan: 2` / `Total Plans in Phase: 5` beside
+    // `Plan: 2 of 9` advances to `3` and `3 of 9`. Reconciling the two totals
+    // would be this transition inventing an answer to a question nobody asked it.
+    if (legacyOwnCurrent !== null && planOwnCurrent !== null && legacyOwnCurrent !== planOwnCurrent) {
+        return {
+            content: reassemble(body),
+            updated: [],
+            data: {
+                error: true,
+                reason: 'ambiguous_plan_position',
+                plan_candidates: [
+                    `Current Plan: ${legacyPlan}`,
+                    `Plan: ${planField}`,
+                ],
+            },
+        };
+    }
     const updated = [];
     const statusDefaults = state_document_cjs_2.KNOWN_TEMPLATE_DEFAULTS['Status'];
     const lastActivityDefaults = state_document_cjs_2.KNOWN_TEMPLATE_DEFAULTS['Last Activity'];
@@ -1122,24 +1454,98 @@ function advancePlanCore(content, deps) {
     }
     // Normal advance branch.
     const newPlan = currentPlan + 1;
-    let planDisplayValue;
-    if (useCompoundFormat) {
-        planDisplayValue = planField.replace(/^\d+/, String(newPlan));
+    // The value each SPELLING should carry after the advance. A document may hold
+    // both names (a `Current Plan:` header and a `Plan:` line in the section, or
+    // the reverse), and each has always rendered differently — the legacy field
+    // holds a bare/padded number while the section's `Plan:` line holds the
+    // compound `N of M`.
+    //
+    // Each is advanced from ITS OWN raw text, never from the other's numbers
+    // (#3791 review round 6, B1/M1). `bumpLeadingNumber` replaces only the leading
+    // digits, so the field's zero-padding width, its own ` of M` and any trailing
+    // annotation all survive — which is what the changeset claims, and what the
+    // previous revision did only for whichever field happened to be the parse
+    // source. The other field it re-stamped from numbers that were never its own.
+    const advanceOwn = (raw, own) => {
+        if (raw === null)
+            return undefined;
+        // Present but unreadable (`Plan: TBD`). Leave it exactly as authored: this
+        // transition cannot advance what it cannot read, and writing a derived
+        // number over it is the fabrication B1 was filed for. Stale-and-untouched is
+        // honest; refusing the whole document because an unrelated line is
+        // unreadable would be a narrowing #3784 does not license.
+        if (own === null)
+            return undefined;
+        return bumpLeadingNumber(raw, newPlan) ?? undefined;
+    };
+    // Title-Case LITERALS to stateReplaceField (ADR-3408 §8.3(b)): a literal
+    // cannot collide with a lowercase/snake_case frontmatter key, so it is safe
+    // regardless of how the content argument was derived. `body` here is in fact
+    // `stripFrontmatter(content)`, but the write-path drift guard does not do
+    // dataflow tracking (by design), and satisfying its invariant by construction
+    // is better than asking a reader to re-derive that it holds.
+    // One value per SPELLING, then write both names everywhere they appear.
+    //
+    //   `Current Plan` — whatever the author wrote, advanced in place: padding
+    //                    and any ` of M` preserved.
+    //   `Plan`         — likewise, so its OWN total survives. `Plan: 2 of 9`
+    //                    beside a `Total Plans in Phase: 5` advances to
+    //                    `3 of 9`, not `3 of 5`: the two totals disagreeing is
+    //                    the document's business, not this transition's to
+    //                    reconcile.
+    //
+    // The two are deliberately different strings for the legacy shape, which is
+    // why this is a per-name value rather than one shared display value. Writing
+    // only the name the value was PARSED from is what left the other name stale:
+    // a `**Plan:** 2 of 6` header beside a `Current Plan:` line advanced one and
+    // not the other, in whichever direction the precedence happened to fall.
+    //
+    // Each write is a no-op when that name is absent (`stateReplaceField` returns
+    // null), so a document carrying only one spelling is unaffected — and
+    // `undefined` means "present but not advanceable", which is left untouched
+    // rather than overwritten.
+    const currentPlanDisplayValue = advanceOwn(legacyPlan, legacyOwnCurrent);
+    const planDisplayValue = planField === null
+        // No top-level `Plan:` field to advance, but the `## Current Position`
+        // section may still carry a `Plan:` line in a shape `stateExtractField`
+        // does not read. There is no raw text here to preserve, so it gets the
+        // compound rendering that line has always carried.
+        ? `${newPlan} of ${totalPlans}`
+        : advanceOwn(planField, planOwnCurrent);
+    if (currentPlanDisplayValue !== undefined) {
+        body = (0, state_document_cjs_1.stateReplaceField)(body, 'Current Plan', currentPlanDisplayValue) || body;
+    }
+    // Only touch `Plan` when the document actually declares one. Writing it
+    // unconditionally meant a `stateReplaceField` whose first match could be any
+    // `Plan:` line anywhere in the body — including prose outside
+    // `## Current Position` that was never a field. `planField` is the read of
+    // that same field from the top of this function, so the write is scoped to a
+    // document that has one.
+    if (planField !== null && planDisplayValue !== undefined) {
         body = (0, state_document_cjs_1.stateReplaceField)(body, 'Plan', planDisplayValue) || body;
     }
-    else {
-        planDisplayValue = `${newPlan} of ${totalPlans}`;
-        body = (0, state_document_cjs_1.stateReplaceField)(body, 'Current Plan', String(newPlan)) || body;
-    }
     body = (0, state_document_cjs_1.stateReplaceFieldIfTemplate)(body, 'Status', statusDefaults, 'Ready to execute') || body;
     body = (0, state_document_cjs_1.stateReplaceFieldIfTemplate)(body, 'Last Activity', lastActivityDefaults, today) || body;
     body = (0, state_document_cjs_1.stateReplaceFieldIfTemplate)(body, 'Last activity', lastActivityDefaults, today) || body;
     body = mutateCurrentPositionForAdvance(body, {
         status: 'Ready to execute',
         lastActivity: today,
+        // Both spellings, each with its own value. The section writes whichever
+        // name it actually carries; passing only the header's name is what left
+        // two sites disagreeing about where execution is.
         plan: planDisplayValue,
+        currentPlan: currentPlanDisplayValue,
     }, statusDefaults, lastActivityDefaults);
-    updated.push('Current Plan', 'Status', 'Last Activity', 'Current Position');
+    // Report `Current Plan` only when it actually moved. The write above is
+    // conditional now — a `Current Plan:` that is present but unreadable is left
+    // as authored — so an unconditional push here would report progress this
+    // transition had not made, which is the same sin `bumpLeadingNumber` returns
+    // null to avoid. `reconcileReportedFields` at the `state.cts` caller would
+    // catch it against the persisted bytes, but `transitionCore`'s own `updated`
+    // is consumed directly too and has to be true on its own.
+    if (currentPlanDisplayValue !== undefined)
+        updated.push('Current Plan');
+    updated.push('Status', 'Last Activity', 'Current Position');
     return {
         content: reassemble(body),
         updated,
@@ -2004,13 +2410,10 @@ function syncCore(content, intent, deps) {
         if (currentProgress) {
             const currentPercent = parseInt(currentProgress.replace(/[^\d]/g, ''), 10);
             if (currentPercent !== intent.percent) {
-                const barWidth = 10;
-                const filled = Math.round((intent.percent / 100) * barWidth);
-                const bar = '█'.repeat(filled) + '░'.repeat(barWidth - filled);
-                const progressStr = `[${bar}] ${intent.percent}%`;
-                changes.push(`Progress: ${currentProgress} -> ${progressStr}`);
-                const result = (0, state_document_cjs_1.stateReplaceField)(modified, 'Progress', progressStr);
+                const result = stateReplaceProgressPercent(modified, intent.percent);
                 if (result) {
+                    const progressStr = formatProgressMachineSegment(intent.percent);
+                    changes.push(`Progress: ${currentProgress} -> ${progressStr}`);
                     modified = result;
                     updated.push('Progress');
                 }