@opengsd/gsd-core 1.7.0-rc.6 → 1.8.0

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

@@ -153,11 +153,14 @@ function shouldPreserveExistingProgress(existingProgress, derivedProgress) {
         return false;
     const existing = existingProgress;
     const derived = derivedProgress;
-    // total_phases is intentionally excluded from the ratchet: it must always
-    // take the freshly derived value so it can correct downward (#1446).
-    // Only completed_phases, total_plans, and completed_plans keep ratchet behaviour.
+    // total_phases (#1446) and total_plans (#2440) are intentionally excluded
+    // from the ratchet: both must always take the freshly derived value so they
+    // can correct in BOTH directions. total_plans legitimately moves up (a new
+    // phase adds plans) and down (milestone reorganization removes phases).
+    // Ratcheting it freezes stale values. Only completed_phases and
+    // completed_plans keep ratchet behaviour — they are monotonic (once a
+    // phase/plan is complete, it stays complete).
     return (existingProgressExceedsDerived(existing, derived, 'completed_phases') ||
-        existingProgressExceedsDerived(existing, derived, 'total_plans') ||
         existingProgressExceedsDerived(existing, derived, 'completed_plans'));
 }
 function normalizeProgressNumbers(progress) {

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

@@ -28,7 +28,7 @@ const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 const phase_lifecycle_cjs_1 = require("./phase-lifecycle.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
-const { extractFrontmatter, reconstructFrontmatter } = frontmatter;
+const { extractFrontmatter, reconstructFrontmatter, stripFrontmatter } = frontmatter;
 const { escapeRegex } = phaseIdMod;
 // Stop predicate for section-body slicing: a level-2+ heading ends the section.
 const STOP_H2_PLUS = (lv) => lv >= 2;
@@ -100,7 +100,28 @@ function applyStatePreservation(input) {
         !resync &&
         preFm &&
         preFm['progress']) {
-        postFm['progress'] = preFm['progress'];
+        // #2440: when the caller opts in (deriveProgressKeys), 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 writes (state.update/patch without
+        // the flag), the wholesale restore preserves everything as before — the
+        // #3242 Bug A protection stays fully in force.
+        if (input.deriveProgressKeys && postFm['progress']) {
+            const curated = preFm['progress'];
+            const derived = (postFm['progress'] ?? {});
+            const merged = { ...derived };
+            if (curated) {
+                for (const [key, value] of Object.entries(curated)) {
+                    if (key !== 'total_plans' && key !== 'total_phases') {
+                        merged[key] = value;
+                    }
+                }
+            }
+            postFm['progress'] = merged;
+        }
+        else {
+            postFm['progress'] = preFm['progress'];
+        }
         mutated = true;
     }
     // status — #1230 body-delta heuristic. Table: preserve-when-unchanged.
@@ -226,7 +247,7 @@ function beginPhaseCore(content, intent, deps) {
     const reassemble = (b) => hasFrontmatter
         ? `---\n${reconstructFrontmatter(existingFm)}\n---\n\n${b}`
         : b;
-    const today = deps.clock.today();
+    const today = deps.clock.localToday();
     // Consult the field-classification table for the frontmatter keys this
     // transition touches (codex Phase 1 review: "table not consulted by
     // transitionCore"). The table tracks FRONTMATTER keys (lowercase: `status`,
@@ -284,8 +305,8 @@ function beginPhaseCore(content, intent, deps) {
             updated.push('Current focus');
         }
         // ## Current Position section mutation (#1104, #1365).
-        // ADR-1372 T6: tokenizeHeadings + offset splicing (replaceSection adoption
-        // deferred to a later phase). Mirrors state.cts:2261-2324 byte-for-behaviour.
+        // `locateCurrentPosition` (fence-aware, tokenizeHeadings-based) locates
+        // the section; mirrors state.cts:2261-2324 byte-for-behaviour.
         body = mutateCurrentPositionFirstTime(body, intent, today, updated);
     }
     else {
@@ -338,6 +359,20 @@ function sliceCurrentPositionSection(body) {
  * First-time ## Current Position mutation: update Phase / Plan / Status /
  * Last activity lines. Mirrors state.cts:2261-2324 byte-for-behaviour
  * (inline regex first, pipe-table fallback via stateReplaceField — #1257).
+ *
+ * F2 (#2245 review, MAJOR): a prior revision of this function used
+ * `collectSection`/`replaceSection` here, whose default `levelBounded: true`
+ * only stops the section at the next heading of level <= the opener's own
+ * level (H1/H2 for a `##`-opened section) — an H3+ subsection nested under
+ * `## Current Position` was NOT a stop boundary and got folded into
+ * `sectionBody`, so the field regexes below (which run with the `m` flag,
+ * matching ANY line start in the body) could clobber a same-named line
+ * inside that subsection (the #2130/#2067/#2080 truncation/clobber class).
+ * Restored to the fence-aware `locateCurrentPosition` locator (which stops
+ * at ANY heading level >= 2, `STOP_H2_PLUS` — H2 through H6) + manual splice,
+ * exactly matching the `mutateCurrentPositionResume`/
+ * `mutateCurrentPositionForAdvance` siblings below, both of which use
+ * `locateCurrentPosition` directly.
  */
 function mutateCurrentPositionFirstTime(body, intent, today, updated) {
     const span = locateCurrentPosition(body);
@@ -414,25 +449,6 @@ function mutateCurrentPositionResume(body, intent, today, updated) {
     }
     return body.slice(0, span.start) + sectionBody + body.slice(span.end);
 }
-/**
- * Strip ALL frontmatter blocks from the start of `content`.
- *
- * TODO (ADR-1769 follow-up): move to `frontmatter.cjs` or `state-document.cjs`
- * so it's a shared primitive. Inlined here in Phase 1 to avoid touching
- * `state.cjs` (which is the migration target itself) and to keep the Phase 1
- * diff contained. Body is byte-identical to `state.cts:1653 stripFrontmatter`
- * (same CRLF + stacked-block handling).
- */
-function stripFrontmatter(content) {
-    let result = content;
-    while (true) {
-        const stripped = result.replace(/^\s*---\r?\n[\s\S]*?\r?\n---\s*/, '');
-        if (stripped === result)
-            break;
-        result = stripped;
-    }
-    return result;
-}
 /**
  * Update fields within the ## Current Position section for advancePlan.
  * Mirrors `updateCurrentPositionFields` (state.cts:496) byte-for-behaviour:
@@ -502,7 +518,7 @@ function mutateCurrentPositionForAdvance(content, fields, statusDefaults, lastAc
  * adapter to construct CLI output.
  */
 function advancePlanCore(content, deps) {
-    const today = deps.clock.today();
+    const today = deps.clock.localToday();
     // #1255: body-field replacements operate on body only (frontmatter stripped),
     // not on the full content. The YAML `status:` key matches `^Status:\s*`
     // before the body field if full content is passed (codex Phase 2 review:
@@ -591,8 +607,8 @@ function advancePlanCore(content, deps) {
  * Migrates the inline STATE.md transform that lived inside `cmdPhaseComplete`
  * (phase.cts) onto the substrate. Owns the field-classification-governed body
  * mutations: Current Phase (preserving the `of total` shape and phase name),
- * Current Phase Name, Status (`Milestone complete` on the last phase, else
- * `Ready to plan`), Current Plan (`Not started`), Last Activity + Description,
+ * Current Phase Name, Status (`All phases complete` on the last phase, else
+ * `Ready to plan` per ADR-2207), Current Plan (`Not started`), Last Activity + Description,
  * and the Completed/Total Phases + Progress percent block (re-derived from the
  * roadmap via the injected `roadmapProvider`).
  *
@@ -608,7 +624,7 @@ function advancePlanCore(content, deps) {
  */
 function completePhaseCore(content, intent, deps) {
     const updated = [];
-    const today = deps.clock.today();
+    const today = deps.clock.localToday();
     // 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.
@@ -672,8 +688,10 @@ function completePhaseCore(content, intent, deps) {
             updated.push('Current Phase Name');
         }
     }
-    // Status — `Milestone complete` on the final phase, otherwise `Ready to plan`.
-    const statusValue = intent.isLastPhase ? 'Milestone complete' : 'Ready to plan';
+    // Status — `All phases complete` on the final phase (ADR-2207), otherwise
+    // `Ready to plan`. Milestone termination (`<version> milestone complete`) is
+    // owned solely by the milestone-close verb (milestoneCompleteCore).
+    const statusValue = intent.isLastPhase ? 'All phases complete' : 'Ready to plan';
     const statusAfter = (0, state_document_cjs_1.stateReplaceFieldWithFallback)(body, 'Status', null, statusValue);
     if (statusAfter !== body) {
         body = statusAfter;
@@ -762,7 +780,7 @@ function completePhaseCore(content, intent, deps) {
  */
 function plannedPhaseCore(content, intent, deps) {
     const updated = [];
-    const today = deps.clock.today();
+    const today = deps.clock.localToday();
     for (const fmKey of ['status', 'last_activity', 'last_activity_desc']) {
         const cls = getFieldClassification(fmKey);
         if (cls === null) {
@@ -840,7 +858,7 @@ function plannedPhaseCore(content, intent, deps) {
  * directly and must not run the steady-state `syncStateFrontmatter` post-sync.
  */
 function milestoneSwitchCore(content, intent, deps) {
-    const today = deps.clock.today();
+    const today = deps.clock.localToday();
     const updated = [
         'milestone',
         'milestone_name',
@@ -903,6 +921,70 @@ function milestoneSwitchCore(content, intent, deps) {
 // ----------------------------------------------------------------------------
 // milestoneComplete — intent implementation (Phase 5)
 // ----------------------------------------------------------------------------
+/**
+ * Replace a section's ENTIRE body with `newBody`, discarding whatever was
+ * there — the "wholesale reset" write pattern used by milestoneComplete's
+ * closure write (## Current Position / ## Operator Next Steps). Retires the
+ * fence-blind raw regex `(##\s*<heading>\s*\n)([\s\S]*?)(?=\n##|$)`, which a
+ * literal `##` inside a fenced code block in the section body could fool into
+ * stopping early (the #2130/#2067/#2080 truncation class) — heading location
+ * here goes through `tokenizeHeadings`, which is fence-aware.
+ *
+ * Byte-parity note: the retired regex's greedy `\s*` (before its mandatory
+ * `\n`) swallowed any blank line(s) immediately after the heading into the
+ * discarded match, and its non-greedy body match always left exactly ONE
+ * newline unconsumed before the next heading (or EOF), regardless of how many
+ * blank lines originally separated the section from what followed. Both
+ * edges are reproduced explicitly (rather than delegated to `collectSection`'s
+ * `trimEnd()`-based body, which trims a *different* amount and would drift
+ * the surrounding blank-line count) so `newBody`'s own leading/trailing
+ * formatting is exactly what appears in the output.
+ *
+ * Returns `null` when no heading matches `headingPredicate` (mirrors the
+ * retired regex's `pattern.test(body)` miss) — callers fall back to their own
+ * append-a-new-section path.
+ */
+function resetSectionVerbatim(content, headingPredicate, newBody) {
+    const headings = (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(content);
+    const idx = headings.findIndex(headingPredicate);
+    if (idx === -1)
+        return null;
+    const target = headings[idx];
+    const lines = content.split('\n');
+    const headingLineEnd = target.offset + lines[target.line - 1].length + 1;
+    // Swallow blank line(s) immediately after the heading (mirrors the retired
+    // regex's greedy `\s*` folding them into the discarded match).
+    //
+    // F7 (#2245 review, nit): recognise a CRLF blank line (`\r\n`), not only a
+    // bare LF — a lone `content[bodyStart] === '\n'` check never advances past
+    // a `\r` byte, so on a CRLF STATE.md the blank line right after the
+    // heading fell into the DISCARDED [bodyStart, bodyEnd) span instead of the
+    // KEPT prefix, silently dropping one blank line (contradicting this
+    // function's own byte-parity docstring).
+    let bodyStart = headingLineEnd;
+    while (bodyStart < content.length) {
+        if (content[bodyStart] === '\n') {
+            bodyStart += 1;
+            continue;
+        }
+        if (content[bodyStart] === '\r' && content[bodyStart + 1] === '\n') {
+            bodyStart += 2;
+            continue;
+        }
+        break;
+    }
+    // Stop at the next heading of level >= 2 (mirrors the retired regex's
+    // literal `##` lookahead, which matches any ATX heading two-or-more levels
+    // deep); leave exactly one newline unconsumed before it, or run to EOF.
+    let bodyEnd = content.length;
+    for (let j = idx + 1; j < headings.length; j++) {
+        if (STOP_H2_PLUS(headings[j].level)) {
+            bodyEnd = headings[j].offset - 1;
+            break;
+        }
+    }
+    return content.slice(0, bodyStart) + newBody + content.slice(bodyEnd);
+}
 /**
  * Apply a `milestoneComplete` transition to STATE.md content.
  *
@@ -917,17 +999,11 @@ function milestoneSwitchCore(content, intent, deps) {
  * runtime-specific next-milestone slash command, injecting it via
  * `intent.nextMilestoneCommand` so the core stays pure.
  *
- * The two section resets use raw regex (with the pre-seam `allow-adhoc-markdown`
- * waivers carried from milestone.cts) rather than tokenizeHeadings because the
- * `## Operator Next Steps` section is non-canonical (not in STATE_MD_SECTIONS)
- * and the existing behavior + its tests pin the exact regex semantics. A future
- * collectSection migration (#1372) can swap both to section primitives.
- *
  * Behavior is byte-for-byte with the pre-migration milestone.cts:314-353 block.
  */
 function milestoneCompleteCore(content, intent, deps) {
     const updated = [];
-    const today = deps.clock.today();
+    const today = deps.clock.localToday();
     const version = intent.version;
     for (const fmKey of ['status', 'last_activity', 'last_activity_desc']) {
         const cls = getFieldClassification(fmKey);
@@ -963,22 +1039,22 @@ function milestoneCompleteCore(content, intent, deps) {
     }
     // ## Current Position reset — stop resume/progress flows pointing at closed
     // execution instructions.
-    const positionPattern = /(##\s*Current Position\s*\n)([\s\S]*?)(?=\n##|$)/i; // allow-adhoc-markdown: pre-seam section write-modify carried from milestone.cts; pending collectSection migration #1372
     const closedPositionBody = `\nPhase: Milestone ${version} complete\n` +
         `Plan: —\n` +
         `Status: Awaiting next milestone\n` +
         `Last activity: ${today} — Milestone ${version} completed and archived\n\n`;
-    if (positionPattern.test(body)) {
-        body = body.replace(positionPattern, (_m, header) => `${header}${closedPositionBody}`);
+    const positionReset = resetSectionVerbatim(body, (h) => h.level === 2 && /^current\s+position$/i.test(h.text), closedPositionBody);
+    if (positionReset !== null) {
+        body = positionReset;
     }
     else {
         body = `${body.trimEnd()}\n\n## Current Position\n${closedPositionBody}`;
     }
     updated.push('Current Position');
     // ## Operator Next Steps — normalize stale tails that can persist after close.
-    const operatorPattern = /(##\s*Operator Next Steps\s*\n)([\s\S]*?)(?=\n##|$)/i; // allow-adhoc-markdown: pre-seam section write-modify carried from milestone.cts; pending collectSection migration #1372
-    if (operatorPattern.test(body)) {
-        body = body.replace(operatorPattern, `$1\n- Start the next milestone with ${intent.nextMilestoneCommand}\n\n`);
+    const operatorReset = resetSectionVerbatim(body, (h) => h.level === 2 && /^operator\s+next\s+steps$/i.test(h.text), `\n- Start the next milestone with ${intent.nextMilestoneCommand}\n\n`);
+    if (operatorReset !== null) {
+        body = operatorReset;
     }
     else {
         body = `${body.trimEnd()}\n\n## Operator Next Steps\n\n- Start the next milestone with ${intent.nextMilestoneCommand}\n`;
@@ -1175,7 +1251,7 @@ function pruneCore(content, intent) {
  * (rather than silently writing fallback-derived wrong values).
  */
 function syncCore(content, intent, deps) {
-    const today = deps.clock.today();
+    const today = deps.clock.localToday();
     const changes = [];
     let modified = content;
     const updated = [];