@opengsd/gsd-core 1.13.0 → 1.14.0

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

@@ -43,24 +43,31 @@ exports.STATE_FIELD_SCHEMA = exports.STATUS_LIFECYCLE_ENUM = void 0;
 /**
  * The seven CANONICAL values `normalizeStateStatus` (`src/state-document.cts`)
  * maps recognized raw status prose TO — the function's default fallback plus
- * each branch's literal output, in the order the function tests them. This is
- * NOT the raw body prose vocabulary `CONTEXT.md`'s "STATE.md Status Lifecycle
- * (ADR-2207)" entry documents (`Ready to plan` → `All phases complete` →
- * `<version> milestone complete` → `Awaiting next milestone`, plus the
- * handler-authored strings in `KNOWN_TEMPLATE_DEFAULTS['Status']`) — that is
- * free-form prose `normalizeStateStatus` READS.
+ * each vocabulary entry's literal output. This is NOT the raw body prose
+ * vocabulary `CONTEXT.md`'s "STATE.md Status Lifecycle (ADR-2207)" entry
+ * documents (`Ready to plan` → `All phases complete` → `<version> milestone
+ * complete` → `Awaiting next milestone`, plus the handler-authored strings
+ * in `KNOWN_TEMPLATE_DEFAULTS['Status']`) — that is free-form prose
+ * `normalizeStateStatus` READS.
  *
  * CORRECTED (#3873 phase-3 test-matrix row 26 — verified by executing
  * `normalizeStateStatus`, not by reading this docstring's prior claim):
  * this is NOT a closed set the `status` frontmatter key is restricted to at
- * runtime. `normalizeStateStatus` is deliberately LENIENT: its fallback is
- * `normalizedStatus = status || 'unknown'`, and when none of its
- * substring-match branches recognize the raw input, that fallback — the
- * caller's raw, UNRECOGNIZED prose — is returned unchanged. A status value
- * outside this seven-member set is not rejected, coerced, or normalized; it
- * passes straight through into the frontmatter. `STATUS_LIFECYCLE_ENUM` is
- * therefore the set of values the normalizer maps recognized input ONTO, not
- * a runtime-enforced closed vocabulary for the field.
+ * runtime. `normalizeStateStatus` is deliberately LENIENT: its fallback
+ * returns the caller's raw, UNRECOGNIZED prose unchanged — when none of its
+ * vocabulary entries recognize the whole-field input, that raw value is what
+ * the function returns. A status value outside this seven-member set is not
+ * rejected, coerced, or normalized; it passes straight through into the
+ * frontmatter. `STATUS_LIFECYCLE_ENUM` is therefore the set of values the
+ * normalizer maps recognized input ONTO, not a runtime-enforced closed
+ * vocabulary for the field.
+ *
+ * #4186: recognition is ANCHORED (whole-field match against the declared
+ * `STATUS_EXACT_TOKENS` / `STATUS_ANCHORED_PATTERNS` tables in
+ * `src/state-document.cts`), never a substring scan of the prose — prose
+ * merely CONTAINING a status word (a `.planning/` path, `verifica*`,
+ * `completezza`) passes through verbatim instead of being rewritten to a
+ * credible wrong token.
  */
 exports.STATUS_LIFECYCLE_ENUM = Object.freeze([
     'unknown',

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

@@ -36,6 +36,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 +49,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 +66,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
@@ -508,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
@@ -523,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
@@ -824,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');