@pareto4/pp-core 1.11.1 → 1.12.0

package/pp-core/bin/lib/state.cjs

@@ -19,10 +19,10 @@ const configLoaderMod = require("./config-loader.cjs");
 const { loadConfig } = configLoaderMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
-const { escapeRegex } = phaseIdMod;
+const { escapeRegex, normalizePhaseName } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapParserMod = require("./roadmap-parser.cjs");
-const { getMilestoneInfo, getMilestonePhaseFilter, extractCurrentMilestone } = roadmapParserMod;
+const { getDeclaredMilestoneInfo, getMilestonePhaseFilter, extractCurrentMilestone, getClosedMilestonePhaseDirFilter } = roadmapParserMod;
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
@@ -33,6 +33,9 @@ const frontmatter = require("./frontmatter.cjs");
 const { extractFrontmatter, reconstructFrontmatter } = frontmatter;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const scanPhasePlans = require("./plan-scan.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseLifecycleMod = require("./phase-lifecycle.cjs");
+const { deriveProgressFromRoadmap } = phaseLifecycleMod;
 const state_document_cjs_1 = require("./state-document.cjs");
 const STATE_PROGRESS_RESYNC_FIELDS = new Set([
     'Progress',
@@ -73,8 +76,13 @@ function cmdStateLoad(cwd, raw) {
     const configExists = node_fs_1.default.existsSync(node_path_1.default.join(planDir, 'config.json'));
     const roadmapExists = node_fs_1.default.existsSync(node_path_1.default.join(planDir, 'ROADMAP.md'));
     const stateExists = stateRaw.length > 0;
+    // Pack 6 D-07: the emitted config is display-safe for its remote coordinate
+    // key (config.cjs's projection); `config` itself stays raw. Lazily required
+    // so this module's load graph is unchanged.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { redactConfigCoordinates } = require('./config.cjs');
     const result = {
-        config,
+        config: redactConfigCoordinates('', config),
         state_raw: stateRaw,
         state_exists: stateExists,
         roadmap_exists: roadmapExists,
@@ -172,20 +180,26 @@ function cmdStatePatch(cwd, patches, raw) {
         const results = { updated: [], failed: [] };
         const shouldResync = shouldResyncStateProgress(Object.keys(patches));
         // Use atomic read-modify-write to prevent lost updates from concurrent agents
-        readModifyWriteStateMd(statePath, (content) => {
+        const fmReport = readModifyWriteStateMd(statePath, (content) => {
+            // Patch the BODY only, as cmdStateUpdate does. The plain-line pattern is
+            // case-insensitive, so on the whole file `Status` matched the frontmatter
+            // `status:` line first; the re-derivation then restored it from the untouched
+            // body, and the verb reported a write it never made.
+            let body = stripFrontmatter(content);
+            const head = content.slice(0, content.length - body.length);
             for (const [field, value] of Object.entries(patches)) {
-                const result = (0, state_document_cjs_1.stateReplaceField)(content, field, value);
+                const result = (0, state_document_cjs_1.stateReplaceField)(body, field, value);
                 if (result) {
-                    content = result;
+                    body = result;
                     results.updated.push(field);
                 }
                 else {
                     results.failed.push(field);
                 }
             }
-            return content;
+            return head + body;
         }, cwd, { resync: shouldResync });
-        output(results, raw, results.updated.length > 0 ? 'true' : 'false');
+        output({ ...results, frontmatter_updated: fmReport.frontmatter_updated }, raw, results.updated.length > 0 ? 'true' : 'false');
     }
     catch {
         error('STATE.md not found');
@@ -208,7 +222,7 @@ function cmdStateUpdate(cwd, field, value) {
         const shouldResync = shouldResyncStateProgress([field]);
         // Preserve curated progress for body-only updates, but allow fields that
         // directly project into progress.* frontmatter to rebuild after mutation.
-        readModifyWriteStateMd(statePath, (content) => {
+        const fmReport = readModifyWriteStateMd(statePath, (content) => {
             const body = stripFrontmatter(content);
             const result = (0, state_document_cjs_1.stateReplaceField)(body, field, value);
             if (result) {
@@ -222,10 +236,10 @@ function cmdStateUpdate(cwd, field, value) {
             return content;
         }, cwd, { resync: shouldResync });
         if (updated) {
-            output({ updated: true }, false, undefined);
+            output({ updated: true, frontmatter_updated: fmReport.frontmatter_updated }, false, undefined);
         }
         else {
-            output({ updated: false, reason: `Field "${field}" not found in STATE.md` }, false, undefined);
+            output({ updated: false, reason: `Field "${field}" not found in STATE.md`, frontmatter_updated: fmReport.frontmatter_updated }, false, undefined);
         }
     }
     catch {
@@ -349,7 +363,7 @@ function cmdStateAdvancePlan(cwd, raw) {
     }
     const today = clock_cjs_1.realClock.today();
     let result = null;
-    readModifyWriteStateMd(statePath, (content) => {
+    const fmReport = readModifyWriteStateMd(statePath, (content) => {
         // Try legacy separate fields first, then compound "Plan: X of Y" format
         const legacyPlan = (0, state_document_cjs_1.stateExtractField)(content, 'Current Plan');
         const legacyTotal = (0, state_document_cjs_1.stateExtractField)(content, 'Total Plans in Phase');
@@ -410,15 +424,121 @@ function cmdStateAdvancePlan(cwd, raw) {
         return content;
     }, cwd);
     if (!result || result['error']) {
-        output({ error: 'Cannot parse Current Plan or Total Plans in Phase from STATE.md' }, raw, undefined);
+        output({ error: 'Cannot parse Current Plan or Total Plans in Phase from STATE.md', frontmatter_updated: fmReport.frontmatter_updated }, raw, undefined);
         return;
     }
+    const advanceResult = { ...result, frontmatter_updated: fmReport.frontmatter_updated };
     if (result['advanced'] === false) {
-        output(result, raw, 'false');
+        output(advanceResult, raw, 'false');
     }
     else {
-        output(result, raw, 'true');
+        output(advanceResult, raw, 'true');
+    }
+}
+// ─── Section placeholders (261008-mwk follow-up) ─────────────────────────────
+// A markdown table's header row and separator row, each matched within its own
+// line — the one owner for the writer (record-metric) and the reader
+// (state-snapshot's Decisions Made table). The separator class is `[-|: \t]`,
+// never `[-|\s]`: a class that admits `\n` ran past the blank line under an
+// empty table, so the "table body" began at the NEXT section. record-metric then
+// wrote its row into that section (and, with `None yet` there, deleted the
+// section's heading), and state-snapshot read the next section's table rows as
+// decisions.
+const TABLE_SEPARATOR_ROW = String.raw `\|[-|: \t]+`;
+const TABLE_HEAD_ROWS = String.raw `\n\|[^\n]+\n${TABLE_SEPARATOR_ROW}\n`;
+const TABLE_SEPARATOR_LINE_RE = new RegExp(String.raw `^${TABLE_SEPARATOR_ROW}\s*$`);
+// ─── record-metric's table (261008-mwk follow-up 2) ──────────────────────────
+// The canonical per-plan metrics table: the STATE.md template carries it under
+// `**By Plan:**`, and record-metric's section-absent scaffold writes it.
+const METRICS_TABLE_HEADER = '| Plan | Duration | Tasks | Files |';
+const METRICS_TABLE_SEPARATOR = '|------|----------|-------|-------|';
+function tableCells(line) {
+    return line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim());
+}
+// One row in the table's OWN column shape, derived from its header: a column is
+// filled only when its header names a value record-metric holds (Phase, Plan,
+// Duration, Tasks, Files); any other column gets `-`. When only one of Phase/Plan
+// exists it carries the `Phase N PM` identifier (the upstream row convention).
+function metricRowFor(header, m) {
+    const names = header.map((h) => h.toLowerCase());
+    const id = `Phase ${m.phase} P${m.plan}`;
+    const hasPhase = names.includes('phase');
+    const hasPlan = names.includes('plan');
+    const cells = names.map((n) => {
+        if (n === 'phase')
+            return hasPlan ? m.phase : id;
+        if (n === 'plan')
+            return hasPhase ? m.plan : id;
+        if (n === 'duration')
+            return m.duration;
+        if (n === 'tasks')
+            return `${m.tasks || '-'} tasks`;
+        if (n === 'files')
+            return `${m.files || '-'} files`;
+        return '-';
+    });
+    return `| ${cells.join(' | ')} |`;
+}
+// Finds record-metric's table: the first table under `## Performance Metrics`
+// whose header has a Duration column. Its body is the run of `|` rows (and any
+// placeholder lines) directly under the separator — never prose that follows.
+// When the section has no such table, `insertAt` is where the By Plan table is
+// created: right after the section's last table, or under the heading if the
+// section has none (D-9 revised).
+function locateMetricsTable(content) {
+    const lines = content.split('\n');
+    const start = lines.findIndex((l) => /^#{2,3}\s*Performance Metrics\s*$/i.test(l.trimEnd()));
+    if (start === -1)
+        return { kind: 'no-section' };
+    const level = lines[start].match(/^#+/)[0].length;
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i++) {
+        const h = lines[i].match(/^(#{1,6})\s/);
+        if (h && h[1].length <= level) {
+            end = i;
+            break;
+        }
     }
+    let insertAt = start + 1;
+    for (let i = start + 1; i + 1 < end; i++) {
+        if (!lines[i].trimStart().startsWith('|') || !TABLE_SEPARATOR_LINE_RE.test(lines[i + 1].trim()))
+            continue;
+        const header = tableCells(lines[i]);
+        let j = i + 2;
+        while (j < end && (lines[j].trimStart().startsWith('|') || (lines[j].trim() !== '' && isPlaceholderLine(lines[j]))))
+            j++;
+        if (header.some((h) => h.toLowerCase() === 'duration'))
+            return { kind: 'table', lines, header, bodyStart: i + 2, bodyEnd: j };
+        insertAt = j;
+        i = j - 1;
+    }
+    return { kind: 'no-table', lines, insertAt };
+}
+// The one owner of "this line is a template placeholder, not an entry". A line
+// counts only when the WHOLE line (an optional `- ` / `* ` list marker aside) is
+// `None`, `None yet` or `No decisions yet`, with an optional trailing period.
+// Before this owner, add-blocker, add-decision, add-roadmap-evolution and
+// record-metric each matched those words anywhere in the section: `None yet.`
+// became a leftover `yet.` line, `- None yet` left a lone `-`, an existing entry
+// such as `- Nonexistent endpoint returns 500` was rewritten to `- xistent …`,
+// and record-metric dropped every row of a table in which any row mentioned
+// `None yet`.
+const SECTION_PLACEHOLDER_RE = /^\s*(?:[-*]\s+)?(?:none(?:\s+yet)?|no decisions yet)\.?\s*$/i;
+function isPlaceholderLine(line) {
+    return SECTION_PLACEHOLDER_RE.test(line);
+}
+// A table row is a placeholder when at least one cell is a placeholder and every
+// other cell is empty or `-` (e.g. `| None yet | | | |`).
+function isPlaceholderTableRow(line) {
+    const t = line.trim();
+    if (!t.startsWith('|'))
+        return false;
+    const cells = t.replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim());
+    return cells.some(isPlaceholderLine) && cells.every((c) => c === '' || c === '-' || isPlaceholderLine(c));
+}
+// Remove placeholder lines whole; every other line is kept byte for byte.
+function stripPlaceholderLines(body) {
+    return body.split('\n').filter((line) => !isPlaceholderLine(line) && !isPlaceholderTableRow(line)).join('\n');
 }
 function cmdStateRecordMetric(cwd, options, raw) {
     const statePath = planningPaths(cwd).state;
@@ -431,44 +551,61 @@ function cmdStateRecordMetric(cwd, options, raw) {
         output({ error: 'phase, plan, and duration required' }, raw, undefined);
         return;
     }
-    let _recorded = false;
+    let recorded = false;
     let created = false;
-    readModifyWriteStateMd(statePath, (content) => {
-        // Find Performance Metrics section and its table
-        const metricsPattern = /(##\s*Performance Metrics[\s\S]*?\n\|[^\n]+\n\|[-|\s]+\n)([\s\S]*?)(?=\n##|\n$|$)/i;
-        const metricsMatch = content.match(metricsPattern);
-        const newRow = `| Phase ${phase} P${plan} | ${duration} | ${tasks || '-'} tasks | ${files || '-'} files |`;
-        if (metricsMatch) {
-            let tableBody = metricsMatch[2].trimEnd();
-            if (tableBody.trim() === '' || tableBody.includes('None yet')) {
-                tableBody = newRow;
-            }
-            else {
-                tableBody = tableBody + '\n' + newRow;
-            }
-            _recorded = true;
-            return content.replace(metricsPattern, (_match, header) => `${header}${tableBody}\n`);
-        }
-        // Section absent — DWIM: auto-create canonical ## Performance Metrics scaffold,
-        // then append the row. Matches state begin-phase / advance-plan DWIM behavior.
+    let tableCreated = false;
+    const fmReport = readModifyWriteStateMd(statePath, (content) => {
+        const place = locateMetricsTable(content);
+        const metric = { phase, plan, duration, tasks, files };
+        if (place.kind === 'table') {
+            // 261008-mwk follow-up 2: the row goes INSIDE the table, in the table's own
+            // column shape; placeholder rows in the body are dropped, every other row kept.
+            const body = place.lines.slice(place.bodyStart, place.bodyEnd).filter((l) => !isPlaceholderLine(l) && !isPlaceholderTableRow(l));
+            const next = [
+                ...place.lines.slice(0, place.bodyStart),
+                ...body,
+                metricRowFor(place.header, metric),
+                ...place.lines.slice(place.bodyEnd),
+            ];
+            recorded = true;
+            return next.join('\n');
+        }
+        if (place.kind === 'no-table') {
+            // D-9 revised: a Performance Metrics section with no Duration table (e.g. a
+            // STATE.md from the template before it carried `**By Plan:**`) gets the same
+            // By Plan table the template and the section-absent scaffold carry, placed after
+            // the section's last table (or under the heading) — never after prose, never
+            // in another table's shape.
+            const block = ['', '**By Plan:**', '', METRICS_TABLE_HEADER, METRICS_TABLE_SEPARATOR, metricRowFor(tableCells(METRICS_TABLE_HEADER), metric)];
+            const following = place.lines[place.insertAt];
+            if (following !== undefined && following.trim() !== '')
+                block.push('');
+            recorded = true;
+            tableCreated = true;
+            return [...place.lines.slice(0, place.insertAt), ...block, ...place.lines.slice(place.insertAt)].join('\n');
+        }
+        // Section absent — DWIM: auto-create the canonical ## Performance Metrics
+        // scaffold, then append the row. Matches state begin-phase / advance-plan DWIM behavior.
         const scaffold = [
             '',
             '## Performance Metrics',
             '',
-            '| Phase | Plan | Duration | Notes |',
-            '|-------|------|----------|-------|',
-            newRow,
+            METRICS_TABLE_HEADER,
+            METRICS_TABLE_SEPARATOR,
+            metricRowFor(tableCells(METRICS_TABLE_HEADER), metric),
             '',
         ].join('\n');
-        _recorded = true;
+        recorded = true;
         created = true;
         return content.trimEnd() + '\n' + scaffold;
     }, cwd);
-    // Auto-create fallback guarantees recorded === true; no else branch needed.
-    const result = { recorded: true, phase, plan, duration };
+    const result = { recorded, phase, plan, duration };
+    if (tableCreated)
+        result['table_created'] = true;
     if (created)
         result['created'] = true;
-    output(result, raw, 'true');
+    result['frontmatter_updated'] = fmReport.frontmatter_updated;
+    output(result, raw, recorded ? 'true' : 'false');
 }
 function cmdStateUpdateProgress(cwd, raw) {
     const statePath = planningPaths(cwd).state;
@@ -476,20 +613,23 @@ function cmdStateUpdateProgress(cwd, raw) {
         output({ error: 'STATE.md not found' }, raw, undefined);
         return;
     }
-    // Count summaries across current milestone phases only (outside lock — read-only)
+    // Count summaries across current milestone phases only (outside lock — read-only).
+    // 261007-ixt D-9: from the same milestone scan as the frontmatter block, so a closed
+    // milestone's leftover directories are not counted here either. When every directory
+    // belongs to a closed milestone, the disk says nothing about the current one and the
+    // bar is left as it is.
     const phasesDir = planningPaths(cwd).phases;
     let totalPlans = 0;
     let totalSummaries = 0;
     if (node_fs_1.default.existsSync(phasesDir)) {
-        const isDirInMilestone = getMilestonePhaseFilter(cwd);
-        const phaseDirs = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true })
-            .filter(e => e.isDirectory()).map(e => e.name)
-            .filter(isDirInMilestone);
-        for (const dir of phaseDirs) {
-            const { planCount, summaryCount } = scanPhasePlans(node_path_1.default.join(phasesDir, dir));
-            totalPlans += planCount;
-            totalSummaries += summaryCount;
+        _diskScanCache.delete(cwd);
+        const scan = scanMilestoneDisk(cwd);
+        if (scan === CLOSED_MILESTONE_ONLY) {
+            output({ updated: false, reason: 'No phase directory belongs to the current milestone', frontmatter_updated: [] }, raw, 'false');
+            return;
         }
+        totalPlans = scan ? scan.totalPlans : 0;
+        totalSummaries = scan ? scan.completedPlans : 0;
     }
     const percent = totalPlans > 0 ? Math.min(100, Math.round(totalSummaries / totalPlans * 100)) : 0;
     const barWidth = 10;
@@ -499,25 +639,31 @@ function cmdStateUpdateProgress(cwd, raw) {
     let updated = false;
     const _totalPlans = totalPlans;
     const _totalSummaries = totalSummaries;
-    readModifyWriteStateMd(statePath, (content) => {
+    const fmReport = readModifyWriteStateMd(statePath, (content) => {
+        // 261007-ixt: `Progress:` is a BODY field. On the whole file the case-insensitive
+        // multi-line plain pattern matched the YAML `progress:` key first and replaced it
+        // with the bar — deleting the block's first key (`total_phases`) — while the body
+        // was untouched and the result said `updated: true`. Edit the body only.
+        const body = stripFrontmatter(content);
+        const head = content.slice(0, content.length - body.length);
         // Try **Progress:** bold format first, then plain Progress: format
         const boldProgressPattern = /(\*\*Progress:\*\*\s*).*/i;
-        const plainProgressPattern = /^(Progress:\s*).*/im;
-        if (boldProgressPattern.test(content)) {
+        const plainProgressPattern = /^(Progress:[ \t]*).*/im;
+        if (boldProgressPattern.test(body)) {
             updated = true;
-            return content.replace(boldProgressPattern, (_match, prefix) => `${prefix}${progressStr}`);
+            return head + body.replace(boldProgressPattern, (_match, prefix) => `${prefix}${progressStr}`);
         }
-        else if (plainProgressPattern.test(content)) {
+        else if (plainProgressPattern.test(body)) {
             updated = true;
-            return content.replace(plainProgressPattern, (_match, prefix) => `${prefix}${progressStr}`);
+            return head + body.replace(plainProgressPattern, (_match, prefix) => `${prefix}${progressStr}`);
         }
         return content;
     }, cwd);
     if (updated) {
-        output({ updated: true, percent, completed: _totalSummaries, total: _totalPlans, bar: progressStr }, raw, progressStr);
+        output({ updated: true, percent, completed: _totalSummaries, total: _totalPlans, bar: progressStr, frontmatter_updated: fmReport.frontmatter_updated }, raw, progressStr);
     }
     else {
-        output({ updated: false, reason: 'Progress field not found in STATE.md' }, raw, 'false');
+        output({ updated: false, reason: 'Progress field not found in STATE.md', frontmatter_updated: fmReport.frontmatter_updated }, raw, 'false');
     }
 }
 function cmdStateAddDecision(cwd, options, raw) {
@@ -544,14 +690,14 @@ function cmdStateAddDecision(cwd, options, raw) {
     const entry = `- [Phase ${phase || '?'}]: ${summaryText}${rationaleText ? ` — ${rationaleText}` : ''}`;
     let _added = false;
     let created = false;
-    readModifyWriteStateMd(statePath, (content) => {
+    const fmReport = readModifyWriteStateMd(statePath, (content) => {
         // Find Decisions section (various heading patterns)
         const sectionPattern = /(###?\s*(?:Decisions|Decisions Made|Accumulated.*Decisions)\s*\n)([\s\S]*?)(?=\n###?|\n##[^#]|$)/i;
         const match = content.match(sectionPattern);
         if (match) {
             let sectionBody = match[2];
             // Remove placeholders
-            sectionBody = sectionBody.replace(/None yet\.?\s*\n?/gi, '').replace(/No decisions yet\.?\s*\n?/gi, '');
+            sectionBody = stripPlaceholderLines(sectionBody);
             sectionBody = sectionBody.trimEnd() + '\n' + entry + '\n';
             _added = true;
             return content.replace(sectionPattern, (_match, header) => `${header}${sectionBody}`);
@@ -573,6 +719,7 @@ function cmdStateAddDecision(cwd, options, raw) {
     const result = { added: true, decision: entry };
     if (created)
         result['created'] = true;
+    result['frontmatter_updated'] = fmReport.frontmatter_updated;
     output(result, raw, 'true');
 }
 function cmdStateAddBlocker(cwd, text, raw) {
@@ -597,12 +744,12 @@ function cmdStateAddBlocker(cwd, text, raw) {
     const entry = `- ${blockerText}`;
     let _added = false;
     let created = false;
-    readModifyWriteStateMd(statePath, (content) => {
+    const fmReport = readModifyWriteStateMd(statePath, (content) => {
         const sectionPattern = /(###?\s*(?:Blockers|Blockers\/Concerns|Concerns)\s*\n)([\s\S]*?)(?=\n###?|\n##[^#]|$)/i;
         const match = content.match(sectionPattern);
         if (match) {
             let sectionBody = match[2];
-            sectionBody = sectionBody.replace(/None\.?\s*\n?/gi, '').replace(/None yet\.?\s*\n?/gi, '');
+            sectionBody = stripPlaceholderLines(sectionBody);
             sectionBody = sectionBody.trimEnd() + '\n' + entry + '\n';
             _added = true;
             return content.replace(sectionPattern, (_match, header) => `${header}${sectionBody}`);
@@ -623,6 +770,7 @@ function cmdStateAddBlocker(cwd, text, raw) {
     const result = { added: true, blocker: blockerText };
     if (created)
         result['created'] = true;
+    result['frontmatter_updated'] = fmReport.frontmatter_updated;
     output(result, raw, 'true');
 }
 function cmdStateAddRoadmapEvolution(cwd, options, raw) {
@@ -666,7 +814,7 @@ function cmdStateAddRoadmapEvolution(cwd, options, raw) {
     // Section boundaries mirror the sibling handlers (add-decision/add-blocker):
     // a trailing CR on a CRLF STATE.md is absorbed by the lazy body and trimmed,
     // so following sections are preserved without data loss (see the CRLF test).
-    readModifyWriteStateMd(statePath, (content) => {
+    const fmReport = readModifyWriteStateMd(statePath, (content) => {
         const accPattern = /(##\s*Accumulated Context\s*\n)([\s\S]*?)(?=\n##[^#]|$)/i;
         const accMatch = content.match(accPattern);
         if (accMatch) {
@@ -683,7 +831,7 @@ function cmdStateAddRoadmapEvolution(cwd, options, raw) {
                     duplicate = true;
                     return content;
                 }
-                subBody = subBody.replace(/None yet\.?\s*\n?/gi, '');
+                subBody = stripPlaceholderLines(subBody);
                 subBody = subBody.trimEnd() + '\n' + entry + '\n';
                 const newAccBody = accBody.replace(subPattern, (_m, header) => `${header}${subBody}`);
                 return content.replace(accPattern, () => `${accHeader}${newAccBody}`);
@@ -710,7 +858,7 @@ function cmdStateAddRoadmapEvolution(cwd, options, raw) {
         return content.trimEnd() + '\n' + scaffold;
     }, cwd);
     if (duplicate) {
-        output({ added: false, reason: 'duplicate', entry }, raw, 'false');
+        output({ added: false, reason: 'duplicate', entry, frontmatter_updated: fmReport.frontmatter_updated }, raw, 'false');
         return;
     }
     const result = { added: true, entry };
@@ -718,6 +866,7 @@ function cmdStateAddRoadmapEvolution(cwd, options, raw) {
         result['created'] = true;
     if (subsectionCreated)
         result['subsection_created'] = true;
+    result['frontmatter_updated'] = fmReport.frontmatter_updated;
     output(result, raw, 'true');
 }
 function cmdStateResolveBlocker(cwd, text, raw) {
@@ -731,7 +880,7 @@ function cmdStateResolveBlocker(cwd, text, raw) {
         return;
     }
     let resolved = false;
-    readModifyWriteStateMd(statePath, (content) => {
+    const fmReport = readModifyWriteStateMd(statePath, (content) => {
         const sectionPattern = /(###?\s*(?:Blockers|Blockers\/Concerns|Concerns)\s*\n)([\s\S]*?)(?=\n###?|\n##[^#]|$)/i;
         const match = content.match(sectionPattern);
         if (match) {
@@ -753,10 +902,10 @@ function cmdStateResolveBlocker(cwd, text, raw) {
         return content;
     }, cwd);
     if (resolved) {
-        output({ resolved: true, blocker: text }, raw, 'true');
+        output({ resolved: true, blocker: text, frontmatter_updated: fmReport.frontmatter_updated }, raw, 'true');
     }
     else {
-        output({ resolved: false, reason: 'Blockers section not found in STATE.md' }, raw, 'false');
+        output({ resolved: false, reason: 'Blockers section not found in STATE.md', frontmatter_updated: fmReport.frontmatter_updated }, raw, 'false');
     }
 }
 function cmdStateRecordSession(cwd, options, raw) {
@@ -768,7 +917,7 @@ function cmdStateRecordSession(cwd, options, raw) {
     const now = clock_cjs_1.realClock.nowIso();
     const updated = [];
     let sessionCreated = false;
-    readModifyWriteStateMd(statePath, (content) => {
+    const fmReport = readModifyWriteStateMd(statePath, (content) => {
         // Update Last session / Last Date
         let result = (0, state_document_cjs_1.stateReplaceField)(content, 'Last session', now);
         if (result) {
@@ -920,15 +1069,16 @@ function cmdStateRecordSession(cwd, options, raw) {
                 updated.push('Resume File');
         }
         return content;
-    }, cwd);
+    }, cwd, { stoppedAtSetByCaller: !!options.stopped_at });
     if (updated.length > 0) {
         const result = { recorded: true, updated };
         if (sessionCreated)
             result['created'] = true;
+        result['frontmatter_updated'] = fmReport.frontmatter_updated;
         output(result, raw, 'true');
     }
     else {
-        output({ recorded: false, reason: 'No session fields found in STATE.md' }, raw, 'false');
+        output({ recorded: false, reason: 'No session fields found in STATE.md', frontmatter_updated: fmReport.frontmatter_updated }, raw, 'false');
     }
 }
 /**
@@ -941,6 +1091,28 @@ function cmdStateRecordSession(cwd, options, raw) {
  * excludes `## Session Continuity Archive` (preserving the #2444 scoping).
  * Returns the match whose group 1 is the section body, or null.
  */
+/**
+ * Replace ONE Session-block field's value on its own line (13-REVIEW WR-05).
+ * `stateReplaceField`'s patterns use `\s*` after the colon, which also matches
+ * a newline: with an empty `Stopped at:` it overwrote the NEXT line
+ * (`Resume file: …`), and the following reset then found no `Resume file:` at
+ * all. Here the gap is `[ \t]*` and the value `.*`, so a match never leaves
+ * its line; an empty value gains one space. Bold (`**Field:**`) first, then the
+ * plain line-start form — the same two forms, in the same order, the shared
+ * helper reads. `fieldName` is a fixed literal at every call site.
+ */
+function replaceSessionLine(section, fieldName, value) {
+    const escaped = escapeRegex(fieldName);
+    for (const pattern of [
+        new RegExp(`(\\*\\*${escaped}:\\*\\*)([ \\t]*)(.*)`, 'i'),
+        new RegExp(`^(${escaped}:)([ \\t]*)(.*)$`, 'im'),
+    ]) {
+        if (pattern.test(section)) {
+            return section.replace(pattern, (_m, label, gap) => `${label}${gap || ' '}${value}`);
+        }
+    }
+    return null;
+}
 function matchSessionSection(body) {
     return body.match(/(?:^|\n)##[ \t]*Session[ \t]*\n([\s\S]*?)(?=\n##|$)/i)
         || body.match(/(?:^|\n)##[ \t]*Session Continuity[ \t]*\n([\s\S]*?)(?=\n##|$)/i);
@@ -948,7 +1120,15 @@ function matchSessionSection(body) {
 function parseProsePhaseField(value) {
     if (!value)
         return { phase: null, name: null };
-    const phaseMatch = value.match(/\b(\d+[A-Z]?(?:\.\d+)*)\b/i);
+    // 261007-ixt D-2: a phase id is read only from the START of the value (optionally
+    // after the word `Phase`) — the forms the engine writes (`11 (name) — EXECUTING`,
+    // `08 — COMPLETE`). The unanchored search took the `1` out of `Milestone v1.1
+    // complete`, the line `milestone complete` itself writes, and rewound the pointer
+    // ten phases. A version string is not a phase id; anything that does not start
+    // with one is prose, so the name is refused too and the stored values stand.
+    const phaseMatch = value.match(/^\s*(?:phase\s+)?(\d+[A-Z]?(?:\.\d+)*)\b/i);
+    if (!phaseMatch)
+        return { phase: null, name: null };
     const parenName = value.match(/\(([^)]+)\)/);
     const dashName = value.match(/—\s*([^(\n]+?)(?:\s*\(|$)/);
     const rawName = parenName?.[1] ?? dashName?.[1] ?? null;
@@ -1018,7 +1198,7 @@ function cmdStateSnapshot(cwd, raw) {
     const progressPercent = progressRaw ? parseInt(progressRaw.replace('%', ''), 10) : null;
     // Extract decisions table
     const decisions = [];
-    const decisionsMatch = body.match(/##\s*Decisions Made[\s\S]*?\n\|[^\n]+\n\|[-|\s]+\n([\s\S]*?)(?=\n##|\n$|$)/i);
+    const decisionsMatch = body.match(new RegExp(String.raw `##\s*Decisions Made[\s\S]*?${TABLE_HEAD_ROWS}([\s\S]*?)(?=\n##|\n$|$)`, 'i'));
     if (decisionsMatch) {
         const tableBody = decisionsMatch[1];
         const rows = tableBody.trim().split('\n').filter(r => r.includes('|'));
@@ -1071,6 +1251,12 @@ function cmdStateSnapshot(cwd, raw) {
         if (resumeFileMatch)
             session.resume_file = resumeFileMatch[1].trim();
     }
+    // 261007-rly D-10: the stored stopped_at is the record (the writers hold it,
+    // state json reports it); the Session line beneath it may be stale. Same
+    // frontmatter-first rule as the scalars above (#3265).
+    const storedStoppedAt = fmScalar('stopped_at');
+    if (storedStoppedAt)
+        session.stopped_at = storedStoppedAt;
     const result = {
         current_phase: currentPhase,
         current_phase_name: currentPhaseName,
@@ -1089,21 +1275,231 @@ function cmdStateSnapshot(cwd, raw) {
     output(result, raw, undefined);
 }
 // ─── State Frontmatter Sync ──────────────────────────────────────────────────
+/**
+ * The roadmap side of reconcileCompletedPhases (261007-ixt D-1): how many phases
+ * the ROADMAP progress table marks `Complete`, or null when no table speaks.
+ * Current-milestone scope first; the whole file minus `<details>` only when the
+ * scope is silent — that fallback can only RAISE the count, which the min() then
+ * discards. A detected progress table that marks no row Complete yields 0, not
+ * null: a table that lists the phases and grants none must not be read as silence,
+ * or the first Built phase of a milestone would be counted Complete.
+ */
+function roadmapCompletedPhases(roadmapRaw, roadmapScope) {
+    // The phases the current milestone's scope names. A progress table may also carry a
+    // shipped milestone's rows (the template's milestone-grouped layout keeps them, with a
+    // Milestone column): those rows grant nothing to this milestone.
+    const scopedIds = new Set();
+    const headingPattern = /#{2,4}\s*Phase\s+([\w][\w.-]*)\s*:/gi;
+    let hm;
+    while ((hm = headingPattern.exec(roadmapScope)) !== null) {
+        if (/\d/.test(hm[1]))
+            scopedIds.add(normalizePhaseName(hm[1]));
+    }
+    const fromText = (text) => {
+        const table = countCompleteProgressRows(text, scopedIds);
+        if (table !== null)
+            return table;
+        const derived = deriveProgressFromRoadmap(text);
+        if (derived.completedPhases !== null)
+            return derived.completedPhases;
+        return derived.totalPhases !== null ? 0 : null;
+    };
+    const scoped = fromText(roadmapScope);
+    if (scoped !== null)
+        return scoped;
+    return fromText(extractCurrentMilestone(roadmapRaw));
+}
+/**
+ * Column-aware read of a ROADMAP progress table: the header row names the `Phase` and
+ * `Status` columns, so a table with a Milestone column (pp-core/templates/roadmap.md's
+ * milestone-grouped layout) is read as well as the four-column one. Counts the data
+ * rows whose Status cell is `Complete`, among the rows whose phase is in `phaseIds`
+ * (all rows when `phaseIds` is empty). Returns null when no such table is present, or
+ * when the table lists none of `phaseIds` — a table that says nothing about this
+ * milestone's phases is silence, not a grant of zero.
+ */
+function countCompleteProgressRows(text, phaseIds) {
+    const cellsOf = (line) => {
+        const t = line.trim();
+        if (!t.startsWith('|'))
+            return null;
+        return t.replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim());
+    };
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i + 1 < lines.length; i++) {
+        const header = cellsOf(lines[i]);
+        if (!header)
+            continue;
+        const phaseCol = header.findIndex((c) => /^phase$/i.test(c));
+        const statusCol = header.findIndex((c) => /^status$/i.test(c));
+        const separator = cellsOf(lines[i + 1]);
+        if (phaseCol === -1 || statusCol === -1 || !separator || !separator.every((c) => /^:?-+:?$/.test(c)))
+            continue;
+        let listed = 0;
+        let complete = 0;
+        for (let j = i + 2; j < lines.length; j++) {
+            const cells = cellsOf(lines[j]);
+            if (!cells)
+                break;
+            const id = cells[phaseCol] ?? '';
+            if (!/^\d/.test(id))
+                continue;
+            if (phaseIds.size > 0 && !phaseIds.has(normalizePhaseName(id)))
+                continue;
+            listed++;
+            if (/^complete$/i.test(cells[statusCol] ?? ''))
+                complete++;
+        }
+        return listed > 0 ? complete : null;
+    }
+    return null;
+}
+/**
+ * Read the milestone-scoped ROADMAP once and return the two counts the progress
+ * block takes from it: the digit-bearing phase headings (single source of truth
+ * for total_phases, #549 — numeric 01/05.1 and project codes PROJ-42, never the
+ * pure-word `## Phase Overview:`) and the progress table's Complete count (D-1).
+ * Consumed by buildStateFrontmatter and cmdStateSync so both report one percent.
+ */
+function readRoadmapCounts(cwd, roadmapOverride) {
+    let phaseHeadingCount = 0;
+    let completedPhases = null;
+    try {
+        const roadmapPath = node_path_1.default.join(planningDir(cwd), 'ROADMAP.md');
+        const roadmapRaw = typeof roadmapOverride === 'string' ? roadmapOverride : (0, shell_command_projection_cjs_1.platformReadSync)(roadmapPath);
+        if (roadmapRaw !== null) {
+            const roadmapScope = extractCurrentMilestone(roadmapRaw, cwd);
+            const phaseHeadingPattern = /#{2,4}\s*Phase\s+([\w][\w.-]*)\s*:/gi;
+            let m;
+            while ((m = phaseHeadingPattern.exec(roadmapScope)) !== null) {
+                if (/\d/.test(m[1]))
+                    phaseHeadingCount++;
+            }
+            completedPhases = roadmapCompletedPhases(roadmapRaw, roadmapScope);
+        }
+    }
+    catch { /* fall through: callers use the disk counts */ }
+    return { phaseHeadingCount, completedPhases };
+}
+/**
+ * The current milestone's progress as the disk and the ROADMAP report it — the
+ * ONE scan both progress surfaces read (the frontmatter block in
+ * buildStateFrontmatter and the body `Progress:` bar in cmdStateSync), so they
+ * cannot count different directories (261007-ixt D-1; before this, state sync
+ * scanned every directory under phases/, prior milestones included, while the
+ * frontmatter scanned only the milestone's). Returns null when there is no phases
+ * directory or the scan fails. Raw counts only: each consumer reconciles
+ * completed phases through reconcileCompletedPhases.
+ *
+ * Cached per cwd per process (#1967) unless a ROADMAP override is given — that is
+ * the text a transaction is ABOUT to write (phase complete flips the row to
+ * Complete in the same file set as STATE.md), so its counts must neither come
+ * from nor go into the cache.
+ */
+/**
+ * scanMilestoneDisk's answer when every candidate directory belongs to a CLOSED
+ * milestone (261007-ixt D-9): the disk holds nothing about the current milestone, so
+ * no consumer derives anything from it — distinct from `null` (no phases directory,
+ * or the scan failed), which keeps each consumer's long-standing fallback.
+ */
+const CLOSED_MILESTONE_ONLY = 'closed-milestone-only';
+function scanMilestoneDisk(cwd, roadmapOverride) {
+    try {
+        const phasesDir = planningPaths(cwd).phases;
+        if (!node_fs_1.default.existsSync(phasesDir))
+            return null;
+        const useCache = typeof roadmapOverride !== 'string';
+        const cached = useCache ? _diskScanCache.get(cwd) : undefined;
+        if (cached)
+            return cached;
+        const isDirInMilestone = getMilestonePhaseFilter(cwd);
+        // 261007-ixt D-9: a directory a closed milestone's archived ROADMAP names (and the
+        // current scope does not) is that milestone's, never the current one's.
+        const isDirInClosedMilestone = getClosedMilestonePhaseDirFilter(cwd);
+        const inMilestoneDirs = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true })
+            .filter(e => e.isDirectory()).map(e => e.name)
+            .filter(isDirInMilestone);
+        const allMatchingDirs = inMilestoneDirs.filter(dir => !isDirInClosedMilestone(dir));
+        // Every candidate belonged to a closed milestone: the disk holds nothing about the
+        // current one, so nothing is derived and the stored block stands (the #905 fallback
+        // on write, the same fallback in cmdStateJson on read). Counting zero instead would
+        // overwrite a true closed-milestone record with 0/0.
+        if (inMilestoneDirs.length > 0 && allMatchingDirs.length === 0)
+            return CLOSED_MILESTONE_ONLY;
+        // Bug #2445: when stale phase dirs from a prior milestone remain in
+        // .planning/phases/ alongside new dirs with the same phase number,
+        // de-duplicate by normalized phase number keeping the most recently
+        // modified dir. This prevents double-counting (e.g. two "Phase 1" dirs).
+        const seenPhaseNums = new Map(); // normalizedNum -> dirName
+        for (const dir of allMatchingDirs) {
+            const m = dir.match(/^0*(\d+[A-Za-z]?(?:\.\d+)*)/);
+            const key = m ? m[1].toLowerCase() : dir;
+            if (!seenPhaseNums.has(key)) {
+                seenPhaseNums.set(key, dir);
+            }
+            else {
+                // Keep the dir that is newer on disk (more likely current milestone)
+                try {
+                    const existing = node_path_1.default.join(phasesDir, seenPhaseNums.get(key));
+                    const candidate = node_path_1.default.join(phasesDir, dir);
+                    if (node_fs_1.default.statSync(candidate).mtimeMs > node_fs_1.default.statSync(existing).mtimeMs) {
+                        seenPhaseNums.set(key, dir);
+                    }
+                }
+                catch { /* keep existing on stat error */ }
+            }
+        }
+        const phaseDirs = [...seenPhaseNums.values()];
+        let diskTotalPlans = 0;
+        let diskTotalSummaries = 0;
+        let diskCompletedPhases = 0;
+        for (const dir of phaseDirs) {
+            const { planCount, summaryCount, completed } = scanPhasePlans(node_path_1.default.join(phasesDir, dir));
+            diskTotalPlans += planCount;
+            diskTotalSummaries += summaryCount;
+            if (completed)
+                diskCompletedPhases++;
+        }
+        // ONE read of the ROADMAP feeds both counts it contributes: the phase
+        // headings (total_phases, #549) and the progress table's Complete rows (the
+        // cap on completed_phases, D-1). When the ROADMAP is unreadable both fall
+        // through: phaseDirs.length and the disk count.
+        const roadmap = readRoadmapCounts(cwd, roadmapOverride);
+        const scan = {
+            totalPhases: roadmap.phaseHeadingCount > 0
+                ? Math.max(phaseDirs.length, roadmap.phaseHeadingCount)
+                : phaseDirs.length,
+            diskCompletedPhases,
+            roadmapCompletedPhases: roadmap.completedPhases,
+            totalPlans: diskTotalPlans,
+            completedPlans: diskTotalSummaries,
+        };
+        if (useCache)
+            _diskScanCache.set(cwd, scan);
+        return scan;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Extract machine-readable fields from STATE.md markdown body and build
  * a YAML frontmatter object. Allows hooks and scripts to read state
  * reliably via `state json` instead of fragile regex parsing.
  */
-function buildStateFrontmatter(bodyContent, cwd) {
-    const prosePhase = parseProsePhaseField((0, state_document_cjs_1.stateExtractField)(bodyContent, 'Phase'));
+function buildStateFrontmatter(bodyContent, cwd, roadmapOverride) {
+    // 261007-ixt D-2: the three positional source fields are read from ## Current
+    // Position first (extractPositionalField), so history elsewhere in the body
+    // cannot stand in for the current position.
+    const prosePhase = parseProsePhaseField((0, state_document_cjs_1.extractPositionalField)(bodyContent, 'Phase'));
     const currentPhase = (0, state_document_cjs_1.stateExtractField)(bodyContent, 'Current Phase') ?? prosePhase.phase;
     const currentPhaseName = (0, state_document_cjs_1.stateExtractField)(bodyContent, 'Current Phase Name') ?? prosePhase.name;
     const currentPlan = (0, state_document_cjs_1.stateExtractField)(bodyContent, 'Current Plan');
     const totalPhasesRaw = (0, state_document_cjs_1.stateExtractField)(bodyContent, 'Total Phases');
     const totalPlansRaw = (0, state_document_cjs_1.stateExtractField)(bodyContent, 'Total Plans in Phase');
-    const status = (0, state_document_cjs_1.stateExtractField)(bodyContent, 'Status');
+    const status = (0, state_document_cjs_1.extractPositionalField)(bodyContent, 'Status');
     const progressRaw = (0, state_document_cjs_1.stateExtractField)(bodyContent, 'Progress');
-    const rawLastActivity = (0, state_document_cjs_1.stateExtractField)(bodyContent, 'Last Activity') ?? (0, state_document_cjs_1.stateExtractField)(bodyContent, 'Last activity');
+    const rawLastActivity = (0, state_document_cjs_1.extractPositionalField)(bodyContent, 'Last Activity', 'Last activity');
     const proseLastActivity = parseProseLastActivityField(rawLastActivity);
     const lastActivity = proseLastActivity.date ?? rawLastActivity;
     const lastActivityDesc = (0, state_document_cjs_1.stateExtractField)(bodyContent, 'Last Activity Description') ?? proseLastActivity.description;
@@ -1121,9 +1517,14 @@ function buildStateFrontmatter(bodyContent, cwd) {
     let milestoneName = null;
     if (cwd) {
         try {
-            const info = getMilestoneInfo(cwd);
-            milestone = info.version;
-            milestoneName = info.name;
+            // 261007-ixt W4: a stored record carries only a DECLARED milestone. When nothing
+            // declares one, no milestone key is derived (an absent key is no claim), rather
+            // than the first version the ROADMAP happens to mention.
+            const info = getDeclaredMilestoneInfo(cwd);
+            if (info) {
+                milestone = info.version;
+                milestoneName = info.name;
+            }
         }
         catch { /* intentionally empty */ }
     }
@@ -1131,93 +1532,23 @@ function buildStateFrontmatter(bodyContent, cwd) {
     let completedPhases = null;
     let totalPlans = totalPlansRaw ? parseInt(totalPlansRaw, 10) : null;
     let completedPlans = null;
+    // 261007-ixt D-9: every phase directory belongs to a closed milestone → derive no
+    // progress block at all (not even from body `Total Phases:` / `Progress:` fields), so
+    // syncStateFrontmatter keeps the stored one rather than a partial or zeroed block.
+    let closedMilestoneOnly = false;
     if (cwd) {
-        try {
-            const phasesDir = planningPaths(cwd).phases;
-            if (node_fs_1.default.existsSync(phasesDir)) {
-                // Use cached disk scan when available — avoids N+1 readdirSync calls
-                // on repeated buildStateFrontmatter invocations within the same process (#1967)
-                let cached = _diskScanCache.get(cwd);
-                if (!cached) {
-                    const isDirInMilestone = getMilestonePhaseFilter(cwd);
-                    const allMatchingDirs = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true })
-                        .filter(e => e.isDirectory()).map(e => e.name)
-                        .filter(isDirInMilestone);
-                    // Bug #2445: when stale phase dirs from a prior milestone remain in
-                    // .planning/phases/ alongside new dirs with the same phase number,
-                    // de-duplicate by normalized phase number keeping the most recently
-                    // modified dir. This prevents double-counting (e.g. two "Phase 1" dirs).
-                    const seenPhaseNums = new Map(); // normalizedNum -> dirName
-                    for (const dir of allMatchingDirs) {
-                        const m = dir.match(/^0*(\d+[A-Za-z]?(?:\.\d+)*)/);
-                        const key = m ? m[1].toLowerCase() : dir;
-                        if (!seenPhaseNums.has(key)) {
-                            seenPhaseNums.set(key, dir);
-                        }
-                        else {
-                            // Keep the dir that is newer on disk (more likely current milestone)
-                            try {
-                                const existing = node_path_1.default.join(phasesDir, seenPhaseNums.get(key));
-                                const candidate = node_path_1.default.join(phasesDir, dir);
-                                if (node_fs_1.default.statSync(candidate).mtimeMs > node_fs_1.default.statSync(existing).mtimeMs) {
-                                    seenPhaseNums.set(key, dir);
-                                }
-                            }
-                            catch { /* keep existing on stat error */ }
-                        }
-                    }
-                    const phaseDirs = [...seenPhaseNums.values()];
-                    let diskTotalPlans = 0;
-                    let diskTotalSummaries = 0;
-                    let diskCompletedPhases = 0;
-                    for (const dir of phaseDirs) {
-                        const phaseDir = node_path_1.default.join(phasesDir, dir);
-                        const { planCount, summaryCount, completed } = scanPhasePlans(phaseDir);
-                        diskTotalPlans += planCount;
-                        diskTotalSummaries += summaryCount;
-                        if (completed)
-                            diskCompletedPhases++;
-                    }
-                    // Count phase headings from ROADMAP using a digit-containing pattern
-                    // that matches both numeric phases (01, 05.1) and project-code phases
-                    // (PROJ-42, CK-05) but excludes pure-word section headers like
-                    // `## Phase Overview:` or `## Phase Details:` — single source of
-                    // truth for total_phases (#549).
-                    let roadmapPhaseCount = 0;
-                    try {
-                        const roadmapPath = node_path_1.default.join(planningDir(cwd), 'ROADMAP.md');
-                        const roadmapRaw = (0, shell_command_projection_cjs_1.platformReadSync)(roadmapPath);
-                        if (roadmapRaw !== null) {
-                            const roadmapScope = extractCurrentMilestone(roadmapRaw, cwd);
-                            const phaseHeadingPattern = /#{2,4}\s*Phase\s+([\w][\w.-]*)\s*:/gi;
-                            let m;
-                            while ((m = phaseHeadingPattern.exec(roadmapScope)) !== null) {
-                                // Only count tokens that contain at least one digit — excludes
-                                // pure-word section headings (Overview, Details) while keeping
-                                // numeric phases (01, 05.1) and project-code IDs (PROJ-42).
-                                if (/\d/.test(m[1]))
-                                    roadmapPhaseCount++;
-                            }
-                        }
-                    }
-                    catch { /* fall through: phaseDirs.length used as sole count */ }
-                    cached = {
-                        totalPhases: roadmapPhaseCount > 0
-                            ? Math.max(phaseDirs.length, roadmapPhaseCount)
-                            : phaseDirs.length,
-                        completedPhases: diskCompletedPhases,
-                        totalPlans: diskTotalPlans,
-                        completedPlans: diskTotalSummaries,
-                    };
-                    _diskScanCache.set(cwd, cached);
-                }
-                totalPhases = cached.totalPhases;
-                completedPhases = cached.completedPhases;
-                totalPlans = cached.totalPlans;
-                completedPlans = cached.completedPlans;
-            }
+        const scan = scanMilestoneDisk(cwd, roadmapOverride);
+        if (scan === CLOSED_MILESTONE_ONLY) {
+            closedMilestoneOnly = true;
+        }
+        else if (scan) {
+            totalPhases = scan.totalPhases;
+            // 261007-ixt D-1: the disk scan counts BUILT phases; the ROADMAP table says
+            // which are COMPLETE. The record claims no more than the table grants.
+            completedPhases = (0, state_document_cjs_1.reconcileCompletedPhases)(scan.diskCompletedPhases, scan.roadmapCompletedPhases);
+            totalPlans = scan.totalPlans;
+            completedPlans = scan.completedPlans;
         }
-        catch { /* intentionally empty */ }
     }
     // Derive percent from disk counts when available (ground truth).
     // Uses min(plan_fraction, phase_fraction) via computeProgressPercent so that
@@ -1253,6 +1584,13 @@ function buildStateFrontmatter(bodyContent, cwd) {
     if (lastActivityDesc)
         fm['last_activity_desc'] = lastActivityDesc;
     const progress = {};
+    if (closedMilestoneOnly) {
+        totalPhases = null;
+        completedPhases = null;
+        totalPlans = null;
+        completedPlans = null;
+        progressPercent = null;
+    }
     if (totalPhases !== null)
         progress['total_phases'] = totalPhases;
     if (completedPhases !== null)
@@ -1280,12 +1618,23 @@ function stripFrontmatter(content) {
     }
     return result;
 }
-function syncStateFrontmatter(content, cwd) {
+/**
+ * @param roadmapOverride  ROADMAP text to count from instead of the file on disk —
+ *   for a caller that writes ROADMAP.md and STATE.md as one file set (phase
+ *   complete), so the frontmatter reflects the roadmap the transaction commits.
+ */
+function syncStateFrontmatter(content, cwd, roadmapOverride, activityFieldSetByCaller, stoppedAtFieldSetByCaller) {
     // Read existing frontmatter BEFORE stripping — it may contain values
     // that the body no longer has (e.g., Status field removed by an agent).
     const existingFm = extractFrontmatter(content);
     const body = stripFrontmatter(content);
-    const derivedFm = buildStateFrontmatter(body, cwd);
+    // 261007-ixt D-10: a body `Last activity:` line that lags the frontmatter must not move
+    // the record's date backwards — on every writer path, guarded or not. The hold is for
+    // a DERIVED date only: when the calling verb itself set the `Last activity` field
+    // (`state update "Last activity" …`), that explicit value flows to the frontmatter so
+    // the body and the frontmatter agree.
+    const built = buildStateFrontmatter(body, cwd, roadmapOverride);
+    const derivedFm = activityFieldSetByCaller ? built : (0, state_document_cjs_1.holdNewerActivityDate)(existingFm, built);
     // Preserve existing frontmatter status when body-derived status is 'unknown'.
     // This prevents a missing Status: field in the body from overwriting a
     // previously valid status (e.g., 'executing' → 'unknown').
@@ -1328,6 +1677,31 @@ function syncStateFrontmatter(content, cwd) {
     if (!derivedFm['stopped_at'] && existingFm['stopped_at']) {
         derivedFm['stopped_at'] = existingFm['stopped_at'];
     }
+    // 261007-rly D-7: THE stopped_at hold, one owner for every writer
+    // (writeStateMd, readModifyWriteStateMd, phase complete's transaction). A stored
+    // stopped_at is an operator-authored record; a write that did not change the
+    // Session-scoped `Stopped at:` line must not replace it with whatever that line
+    // says — measured on the v1.1 close, where the stale "Phase 12 context gathered"
+    // replaced the handover note (todos/done/milestone-complete-writes-a-poor-
+    // milestone-record.md). This is the #1230 delta heuristic, which used to live
+    // only in readModifyWriteStateMd: when THIS write changed the line
+    // (`state record-session --stopped-at`, `milestone complete --stopped-at`) the
+    // caller passes true and the new value flows. Undefined holds — fail-safe for a
+    // future caller that forgets the flag. The absent-derived #905 fallback above
+    // stays as it was; the two agree whenever both apply.
+    if (!stoppedAtFieldSetByCaller &&
+        typeof existingFm['stopped_at'] === 'string' &&
+        existingFm['stopped_at'].length > 0 &&
+        derivedFm['stopped_at'] !== existingFm['stopped_at']) {
+        derivedFm['stopped_at'] = existingFm['stopped_at'];
+    }
+    // 261007-ixt W4: when nothing declares a current milestone, the writer derives
+    // no milestone — the stored one (and its name) stands, as for the keys above.
+    if (!derivedFm['milestone'] && existingFm['milestone']) {
+        derivedFm['milestone'] = existingFm['milestone'];
+        if (existingFm['milestone_name'])
+            derivedFm['milestone_name'] = existingFm['milestone_name'];
+    }
     if (!derivedFm['paused_at'] && existingFm['paused_at']) {
         derivedFm['paused_at'] = existingFm['paused_at'];
     }
@@ -1488,16 +1862,47 @@ function withStateLock(statePath, fn) {
  * @param clock
  *   Optional clock seam; defaults to realClock. Passed through to acquireStateLock.
  */
-function writeStateMd(statePath, content, cwd, clock) {
+/** The positional `Last activity` source field — the one D-10's hold compares. */
+function lastActivityField(body) {
+    return (0, state_document_cjs_1.extractPositionalField)(body, 'Last Activity', 'Last activity');
+}
+/**
+ * The Session-scoped `Stopped At` source field — the one the stopped_at hold
+ * compares (261007-rly D-7). Exactly the scope buildStateFrontmatter derives
+ * `stopped_at` from (#2444/#1101): the `## Session` / `## Session Continuity`
+ * section, else the whole body.
+ */
+function sessionStoppedAtField(body) {
+    const sessionMatch = matchSessionSection(body);
+    const scope = sessionMatch ? sessionMatch[1] : body;
+    return (0, state_document_cjs_1.stateExtractField)(scope, 'Stopped At') || (0, state_document_cjs_1.stateExtractField)(scope, 'Stopped at');
+}
+function writeStateMd(statePath, content, cwd, clock, options) {
     // Invalidate disk scan cache before computing new frontmatter — the write
     // may create new PLAN/SUMMARY files that buildStateFrontmatter must see.
     // Safe for any calling pattern, not just short-lived CLI processes (#1967).
     if (cwd)
         _diskScanCache.delete(cwd);
-    const synced = syncStateFrontmatter(content, cwd);
     const lockPath = acquireStateLock(statePath, clock);
     try {
+        // 261007-ixt D-3: diff against the file ON DISK, not the caller's `content` —
+        // a caller may have edited the frontmatter text itself (a case-insensitive
+        // `Status:` replace lands on the YAML `status:` line), and a file that did not
+        // exist (health --repair) has no frontmatter to compare. The report describes
+        // what this write changed on disk.
+        const onDisk = (0, shell_command_projection_cjs_1.platformReadSync)(statePath);
+        const before = onDisk === null ? {} : extractFrontmatter(onDisk);
+        // D-10: did the caller set the Last activity field (vs. the file on disk)?
+        const activityFieldSetByCaller = onDisk !== null &&
+            lastActivityField(stripFrontmatter(onDisk)) !== lastActivityField(stripFrontmatter(content));
+        // 261007-rly D-7: did the caller change the Session-scoped Stopped at line?
+        // An explicit value (milestone complete --stopped-at) flows even when the
+        // Session line already read the same text.
+        const stoppedAtFieldSetByCaller = options?.stoppedAtSetByCaller === true || (onDisk !== null &&
+            sessionStoppedAtField(stripFrontmatter(onDisk)) !== sessionStoppedAtField(stripFrontmatter(content)));
+        const synced = syncStateFrontmatter(content, cwd, undefined, activityFieldSetByCaller, stoppedAtFieldSetByCaller);
         (0, shell_command_projection_cjs_1.platformWriteSync)(statePath, synced);
+        return { written: true, frontmatter_updated: (0, state_document_cjs_1.diffFrontmatterFields)(before, extractFrontmatter(synced)) };
     }
     finally {
         releaseStateLock(lockPath);
@@ -1543,14 +1948,31 @@ function readModifyWriteStateMd(statePath, transformFn, cwd, options, clock) {
         // key in the frontmatter block cannot shadow the body field we are tracking.
         const preBody = stripFrontmatter(content);
         const preFmSnapshot = extractFrontmatter(content);
-        const preBodyStatus = (0, state_document_cjs_1.stateExtractField)(preBody, 'Status');
-        // Bug #1230 / Change B: scope stopped_at delta to the ## Session section,
-        // mirroring buildStateFrontmatter's sessionBodyScope logic (line ~1172).
-        // A stale "Stopped at:" in a non-Session section (e.g. Session Continuity
-        // Archive prose) must not interfere with the delta comparison.
-        const preSessionMatch = matchSessionSection(preBody);
-        const preSessionScope = preSessionMatch ? preSessionMatch[1] : preBody;
-        const preBodyStoppedAt = (0, state_document_cjs_1.stateExtractField)(preSessionScope, 'Stopped At') || (0, state_document_cjs_1.stateExtractField)(preSessionScope, 'Stopped at');
+        // 261007-ixt D-2: the delta unit reads each source field exactly as the
+        // derivation does (extractPositionalField), so "this write did not change the
+        // field the key derives from" is judged on the same line the key comes from.
+        const preBodyStatus = (0, state_document_cjs_1.extractPositionalField)(preBody, 'Status');
+        // Bug #1230 / Change B: the stopped_at delta is scoped to the ## Session
+        // section, read through the same owner the derivation uses (261007-rly D-7).
+        const preBodyStoppedAt = sessionStoppedAtField(preBody);
+        // 2026-09-20: the SAME #1230 delta contract, extended to the position-derived
+        // fields. #1230 applied it to `status` and `stopped_at` only; `current_phase`,
+        // `current_phase_name` and `last_activity_desc` are ALSO re-derived from the
+        // body by syncStateFrontmatter and were left without it. Measured consequence:
+        // on a STATE.md whose ## Current Position had drifted behind its frontmatter,
+        // a write that never touched that section still propagated the stale body into
+        // frontmatter — observed moving `current_phase` from 10 to 09 and restoring a
+        // two-phase-old `last_activity_desc`, while the command exited 0. Snapshot the
+        // whole section: these three fields all derive from it, so one scope is the
+        // honest delta unit.
+        // Delta unit is the SOURCE FIELD each frontmatter key derives from, exactly as
+        // #1230 used stateExtractField(preBody, 'Status') — not the enclosing section.
+        // A section-scoped delta is too coarse: these verbs legitimately rewrite the
+        // `Status:` line inside ## Current Position, which would disable the guard for
+        // every other field in it. (Measured: the first attempt at this fix did
+        // precisely that and the clobber still reproduced.)
+        const preBodyPhaseField = (0, state_document_cjs_1.extractPositionalField)(preBody, 'Phase');
+        const preBodyActivityField = (0, state_document_cjs_1.extractPositionalField)(preBody, 'Last Activity', 'Last activity');
         const modified = transformFn(content);
         // Bug #948: no-op guard — if the transform produced no change, do NOT write
         // the file. An unconditional write would bump `last_updated`, reset
@@ -1560,9 +1982,13 @@ function readModifyWriteStateMd(statePath, transformFn, cwd, options, clock) {
         // content already returns the mutated string, and callers that detect a
         // no-op explicitly return the original content unchanged.
         if (modified === content) {
-            return;
+            return { written: false, frontmatter_updated: [] };
         }
-        let synced = syncStateFrontmatter(modified, cwd);
+        // D-10: the transform set the Last activity field iff the field differs.
+        // 261007-rly D-7: likewise the Session-scoped Stopped at line — the hold for
+        // stopped_at lives in syncStateFrontmatter now, keyed on this delta.
+        let synced = syncStateFrontmatter(modified, cwd, undefined, lastActivityField(stripFrontmatter(modified)) !== preBodyActivityField, options?.stoppedAtSetByCaller === true ||
+            sessionStoppedAtField(stripFrontmatter(modified)) !== preBodyStoppedAt);
         // Compute postFm once and apply BOTH the progress-restore (when !resync)
         // AND the status/stopped_at preservation (#1230) before reconstructing.
         // This avoids double-wrapping the frontmatter block.
@@ -1571,12 +1997,9 @@ function readModifyWriteStateMd(statePath, transformFn, cwd, options, clock) {
         // Use `modified` (not `synced`): syncStateFrontmatter only rewrites the frontmatter block, so the body is identical in both — and we need the body the transform produced.
         // Strip frontmatter so the YAML status key cannot shadow the body field.
         const postBody = stripFrontmatter(modified);
-        const postBodyStatus = (0, state_document_cjs_1.stateExtractField)(postBody, 'Status');
-        // Bug #1230 / Change B: scope stopped_at delta to the ## Session section,
-        // consistent with the pre-transform snapshot above and buildStateFrontmatter.
-        const postSessionMatch = matchSessionSection(postBody);
-        const postSessionScope = postSessionMatch ? postSessionMatch[1] : postBody;
-        const postBodyStoppedAt = (0, state_document_cjs_1.stateExtractField)(postSessionScope, 'Stopped At') || (0, state_document_cjs_1.stateExtractField)(postSessionScope, 'Stopped at');
+        const postBodyStatus = (0, state_document_cjs_1.extractPositionalField)(postBody, 'Status');
+        const postBodyPhaseField = (0, state_document_cjs_1.extractPositionalField)(postBody, 'Phase');
+        const postBodyActivityField = (0, state_document_cjs_1.extractPositionalField)(postBody, 'Last Activity', 'Last activity');
         let mutated = false;
         const postFm = extractFrontmatter(synced);
         if (needsProgressRestore) {
@@ -1601,13 +2024,33 @@ function readModifyWriteStateMd(statePath, transformFn, cwd, options, clock) {
             postFm['status'] = preFmSnapshot['status'];
             mutated = true;
         }
-        // Bug #1230: same delta heuristic for stopped_at.
-        if (postBodyStoppedAt === preBodyStoppedAt &&
-            typeof preFmSnapshot['stopped_at'] === 'string' &&
-            preFmSnapshot['stopped_at'].length > 0 &&
-            postFm['stopped_at'] !== preFmSnapshot['stopped_at']) {
-            postFm['stopped_at'] = preFmSnapshot['stopped_at'];
-            mutated = true;
+        // Bug #1230's stopped_at copy of this heuristic moved into syncStateFrontmatter
+        // (261007-rly D-7), where writeStateMd reaches it too; it is passed the same
+        // Session-scoped delta above.
+        // 2026-09-20: position-derived fields get the same treatment as status and
+        // stopped_at above. When THIS write did not change the ## Current Position
+        // section, a frontmatter value that was set deliberately must not be reverted
+        // to whatever a stale section happens to derive. Conservative by construction:
+        // it only ever RESTORES a pre-existing frontmatter value, and only when the
+        // body source it derives from is byte-identical before and after.
+        const preserveFm = (key) => {
+            const prev = preFmSnapshot[key];
+            if (typeof prev === 'string' && prev.length > 0 && postFm[key] !== prev) {
+                postFm[key] = prev;
+                mutated = true;
+            }
+        };
+        // `current_phase` / `current_phase_name` derive from the body's `Phase:` field
+        // (parseProsePhaseField). If this write did not change that field, a
+        // deliberately-set frontmatter value must survive.
+        if (postBodyPhaseField === preBodyPhaseField) {
+            preserveFm('current_phase');
+            preserveFm('current_phase_name');
+        }
+        // `last_activity_desc` derives from the `Last activity:` field
+        // (parseProseLastActivityField().description).
+        if (postBodyActivityField === preBodyActivityField) {
+            preserveFm('last_activity_desc');
         }
         if (mutated) {
             const yamlStr = reconstructFrontmatter(postFm);
@@ -1615,6 +2058,9 @@ function readModifyWriteStateMd(statePath, transformFn, cwd, options, clock) {
             synced = `---\n${yamlStr}\n---\n\n${body}`;
         }
         (0, shell_command_projection_cjs_1.platformWriteSync)(statePath, synced);
+        // 261007-ixt D-3: diffed AFTER the #1230/25c9760 guards and the resync:false
+        // restore, so the report describes the frontmatter that hit the disk.
+        return { written: true, frontmatter_updated: (0, state_document_cjs_1.diffFrontmatterFields)(preFmSnapshot, extractFrontmatter(synced)) };
     }
     finally {
         releaseStateLock(lockPath);
@@ -1632,14 +2078,26 @@ function cmdStateJson(cwd, raw) {
     // Always rebuild from body + disk so progress counters reflect current state.
     // Returning cached frontmatter directly causes stale percent/completed_plans
     // when SUMMARY files were added after the last STATE.md write (#1589).
-    const built = buildStateFrontmatter(body, cwd);
+    // 261007-ixt W3a: the same date hold the writer applies, so read and write agree.
+    const built = (0, state_document_cjs_1.holdNewerActivityDate)(existingFm, buildStateFrontmatter(body, cwd));
     // Preserve frontmatter-only fields that cannot be recovered from the body.
-    if (existingFm && existingFm['stopped_at'] && !built['stopped_at']) {
+    // 261007-rly D-7: a stored stopped_at wins over the Session line whenever it
+    // exists — the writer holds it there (syncStateFrontmatter), so the read agrees.
+    if (existingFm && typeof existingFm['stopped_at'] === 'string' && existingFm['stopped_at'].length > 0) {
+        built['stopped_at'] = existingFm['stopped_at'];
+    }
+    else if (existingFm && existingFm['stopped_at'] && !built['stopped_at']) {
         built['stopped_at'] = existingFm['stopped_at'];
     }
     if (existingFm && existingFm['paused_at'] && !built['paused_at']) {
         built['paused_at'] = existingFm['paused_at'];
     }
+    // 261007-ixt W4: the same milestone fallback syncStateFrontmatter applies.
+    if (existingFm && !built['milestone'] && existingFm['milestone']) {
+        built['milestone'] = existingFm['milestone'];
+        if (existingFm['milestone_name'])
+            built['milestone_name'] = existingFm['milestone_name'];
+    }
     // Preserve existing status when body-derived status is 'unknown' (same logic as syncStateFrontmatter).
     if (built['status'] === 'unknown' && existingFm && existingFm['status'] && existingFm['status'] !== 'unknown') {
         built['status'] = existingFm['status'];
@@ -1661,6 +2119,12 @@ function cmdStateJson(cwd, raw) {
     if (existingFm && (0, state_document_cjs_1.shouldPreserveExistingProgress)(existingFm['progress'], built['progress'])) {
         built['progress'] = (0, state_document_cjs_1.normalizeProgressNumbers)(existingFm['progress']);
     }
+    // 261007-ixt D-9: when the disk derives no progress block (e.g. every phase dir
+    // belongs to a closed milestone), report the stored one — the same #905 fallback
+    // syncStateFrontmatter applies on write, so the read and the write agree.
+    if (existingFm && !built['progress'] && existingFm['progress']) {
+        built['progress'] = (0, state_document_cjs_1.normalizeProgressNumbers)(existingFm['progress']);
+    }
     output(built, raw, JSON.stringify(built, null, 2));
 }
 /**
@@ -1677,7 +2141,7 @@ function cmdStateBeginPhase(cwd, phaseNumber, phaseName, planCount, raw) {
     }
     const today = clock_cjs_1.realClock.today();
     const updated = [];
-    readModifyWriteStateMd(statePath, (content) => {
+    const fmReport = readModifyWriteStateMd(statePath, (content) => {
         // Bug #1255: all body-field replacements must operate on the body only
         // (frontmatter stripped), not on the full content.  When the full content is
         // passed to stateReplaceField the YAML `status: planning` key matches the
@@ -1848,7 +2312,7 @@ function cmdStateBeginPhase(cwd, phaseNumber, phaseName, planCount, raw) {
         }
         return reassemble(body);
     }, cwd);
-    output({ updated, phase: phaseNumber, phase_name: phaseName || null, plan_count: planCount || null }, raw, updated.length > 0 ? 'true' : 'false');
+    output({ updated, phase: phaseNumber, phase_name: phaseName || null, plan_count: planCount || null, frontmatter_updated: fmReport.frontmatter_updated }, raw, updated.length > 0 ? 'true' : 'false');
 }
 /**
  * Write a WAITING.json signal file when GSD hits a decision point.
@@ -1899,26 +2363,66 @@ function cmdSignalResume(cwd, raw) {
 // ─── Gate Functions (STATE.md consistency enforcement) ────────────────────────
 /**
  * Update the ## Performance Metrics section in STATE.md content.
- * Increments Velocity totals and upserts a By Phase table row.
+ * Recomputes the Velocity total and upserts a By Phase table row.
  * Returns modified content string.
+ *
+ * `Total plans completed` is a COUNT, NOT AN ACCUMULATOR (D-08-40,
+ * 08-VERIFICATION.md SC4): the number of executed plans — `*-SUMMARY.md` files —
+ * across the CURRENT MILESTONE's phase directories, recomputed on every call.
+ *
+ * It used to be `prevTotal + summaryCount`, read back out of the STATE text.
+ * That is wrong because this function is not called once per phase:
+ * `execute-phase.md` § update_roadmap runs `phase complete` on EVERY execute
+ * run, including the gap-closure re-runs a phase performs when verification
+ * returns findings — this workstream's own phase 8 did two (plans 08-10 and
+ * 08-11). MEASURED 2026-09-19 on a clean fixture, re-completing an
+ * already-complete phase carried the total 2 → 4 → 6 while ROADMAP.md stayed
+ * byte-identical: a silently corrupted stored record, the CLAUDE.md arm.
+ *
+ * The walk is the SAME milestone-scoped one `cmdStateUpdateProgress` already
+ * reports as `completed` (`scanMilestoneDisk` — the milestone filter, the #2445
+ * de-dup and the 261007-ixt D-9 closed-milestone exclusion), so STATE's counters cannot disagree — D-08-14's
+ * spirit. A missing phases directory counts 0. `summaryCount` stays a parameter:
+ * the By Phase row below is per-phase and still uses it, and that upsert was
+ * already idempotent — only the Velocity total accumulated.
  */
 function updatePerformanceMetricsSection(content, cwd, phaseNum, planCount, summaryCount) {
-    // Update Velocity: Total plans completed
-    const totalMatch = content.match(/Total plans completed:\s*(\d+|\[N\])/);
-    const prevTotal = totalMatch && totalMatch[1] !== '[N]' ? parseInt(totalMatch[1], 10) : 0;
-    const newTotal = prevTotal + summaryCount;
-    content = content.replace(/Total plans completed:\s*(\d+|\[N\])/, `Total plans completed: ${newTotal}`);
+    // Update Velocity: Total plans completed — the milestone's disk truth.
+    // 261007-ixt D-9: the walk IS scanMilestoneDisk now (the one update-progress and the
+    // frontmatter block read), so a closed milestone's leftover directories are excluded
+    // here too. When every directory belongs to a closed milestone the disk says nothing
+    // about the current one and the stored total is left as it is.
+    let newTotal = 0;
+    const phasesDir = planningPaths(cwd).phases;
+    if (node_fs_1.default.existsSync(phasesDir)) {
+        _diskScanCache.delete(cwd);
+        const scan = scanMilestoneDisk(cwd);
+        newTotal = scan === CLOSED_MILESTONE_ONLY ? null : (scan ? scan.completedPlans : 0);
+    }
+    if (newTotal !== null) {
+        content = content.replace(/Total plans completed:\s*(\d+|\[N\])/, `Total plans completed: ${newTotal}`);
+    }
     // Update By Phase table — upsert row for this phase
     const byPhaseMatch = content.match(byPhaseTablePattern);
     if (byPhaseMatch) {
         let tableBody = byPhaseMatch[2].trim();
-        const phaseRowPattern = new RegExp(`^\\|\\s*${escapeRegex(String(phaseNum))}\\s*\\|.*$`, 'm');
-        const newRow = `| ${phaseNum} | ${summaryCount} | - | - |`;
-        if (phaseRowPattern.test(tableBody)) {
+        // The row for this phase is found by phase IDENTITY, not by the literal argument:
+        // `phase complete 4` must update a row spelled `04` (and vice versa), never append
+        // a second row for the same phase. The row keeps its own id spelling.
+        const wanted = normalizePhaseName(String(phaseNum));
+        const lines = tableBody.split('\n');
+        const rowIdx = lines.findIndex((line) => {
+            const cell = /^\|\s*([^|]*?)\s*\|/.exec(line);
+            return cell !== null && /^[A-Za-z0-9.-]+$/.test(cell[1]) && normalizePhaseName(cell[1]) === wanted;
+        });
+        if (rowIdx !== -1) {
             // Update existing row
-            tableBody = tableBody.replace(phaseRowPattern, newRow);
+            const rowId = /^\|\s*([^|]*?)\s*\|/.exec(lines[rowIdx])[1];
+            lines[rowIdx] = `| ${rowId} | ${summaryCount} | - | - |`;
+            tableBody = lines.join('\n');
         }
         else {
+            const newRow = `| ${phaseNum} | ${summaryCount} | - | - |`;
             // Remove placeholder row and add new row
             tableBody = tableBody.replace(/^\|\s*-\s*\|\s*-\s*\|\s*-\s*\|\s*-\s*\|$/m, '').trim();
             tableBody = tableBody ? tableBody + '\n' + newRow : newRow;
@@ -1945,7 +2449,7 @@ function cmdStatePlannedPhase(cwd, phaseNumber, planCount, raw) {
     // milestone-wide progress.* frontmatter from a half-planned disk snapshot —
     // doing so tramples curated/known-good counters. Route through the body-only
     // write contract (resync:false), the same guard state.update uses. (#500 RC1)
-    readModifyWriteStateMd(statePath, (content) => {
+    const fmReport = readModifyWriteStateMd(statePath, (content) => {
         // Bug #1257: all body-field replacements must operate on the body only
         // (frontmatter stripped), not on the full content. When the full content is
         // passed to stateReplaceFieldIfTemplate the YAML `status: planning` key matches
@@ -1989,13 +2493,31 @@ function cmdStatePlannedPhase(cwd, phaseNumber, planCount, raw) {
             }
         }
         // Update Current Position section
+        // The Current Position write MUST be accounted for. Until 2026-09-20 it was
+        // not: this was the only one of the four `updated`-reporting state verbs
+        // that called updateCurrentPositionFields without pushing to `updated`
+        // (cmdStateCompletePhase pushes 'Current Position'; cmdStateBeginPhase
+        // pushes 'Current focus'; cmdStateRecordSession tracks its own fields).
+        //
+        // WHY THAT MATTERED, measured: the transform still changed the body, so the
+        // no-op guard (#948) did not fire, the file WAS written, and
+        // syncStateFrontmatter then re-derived frontmatter from the body. On a
+        // STATE.md whose body had drifted behind its frontmatter, that propagated
+        // the STALE body into frontmatter — observed moving `current_phase` from 10
+        // to 09 and restoring a two-phase-old `last_activity_desc` — while this
+        // command exited 0 and reported `updated: []`. Every cheap check said
+        // "success, nothing changed"; only a cp→diff saw it. An unreported write is
+        // the dangerous half, so the report is now complete.
+        const beforePosition = body;
         body = updateCurrentPositionFields(body, {
             status: 'Ready to execute',
             lastActivity: `${today} — Phase ${phaseNumber} planning complete`,
         });
+        if (body !== beforePosition)
+            updated.push('Current Position');
         return reassemble(body);
     }, cwd, { resync: false });
-    output({ updated, phase: phaseNumber, plan_count: planCount }, raw, updated.length > 0 ? 'true' : 'false');
+    output({ updated, phase: phaseNumber, plan_count: planCount, frontmatter_updated: fmReport.frontmatter_updated }, raw, updated.length > 0 ? 'true' : 'false');
 }
 /**
  * Bug #2630: reset STATE.md for a new milestone cycle.
@@ -2029,11 +2551,27 @@ function cmdStateMilestoneSwitch(cwd, version, name, raw) {
             const preface = body.trim().length > 0 ? body : '# Project State\n';
             newBody = `${preface.trimEnd()}\n\n## Current Position\n${resetPositionBody}`;
         }
+        // The Session block must move with the milestone. Left alone, its `Stopped at:`
+        // still names the PREVIOUS milestone's stop point while this write drops the
+        // frontmatter `stopped_at`; the next writer (state.planned-phase, measured
+        // 2026-10-09 on vault-assurance) then derives `stopped_at` from that stale
+        // line and records "Phase 12 context gathered" against a milestone whose
+        // first phase is 13. Reset the stop point and the resume pointer here, and
+        // record the same stop point in frontmatter, so body and frontmatter agree.
+        const switchStoppedAt = `Milestone ${version} started`;
+        const sessionMatch = matchSessionSection(newBody);
+        if (sessionMatch && sessionMatch.index !== undefined) {
+            const section = sessionMatch[0];
+            let resetSection = replaceSessionLine(section, 'Stopped At', switchStoppedAt) ?? section;
+            resetSection = replaceSessionLine(resetSection, 'Resume File', 'None') ?? resetSection;
+            newBody = newBody.slice(0, sessionMatch.index) + resetSection + newBody.slice(sessionMatch.index + section.length);
+        }
         const fm = {
             gsd_state_version: existingFm['gsd_state_version'] || '1.0',
             milestone: version,
             milestone_name: resolvedName,
             status: 'planning',
+            stopped_at: switchStoppedAt,
             last_updated: clock_cjs_1.realClock.nowIso(),
             last_activity: today,
             progress: {
@@ -2126,11 +2664,19 @@ function cmdStateSync(cwd, options, raw) {
     const verify = options && options.verify;
     const content = node_fs_1.default.readFileSync(statePath, 'utf-8');
     const changes = [];
-    let modified = content;
+    // 261007-ixt: the fields below are BODY fields, so they are read and replaced in
+    // the body only. stateReplaceField's plain pattern is case-insensitive and
+    // multi-line, so on the whole file `Progress` matched the YAML `progress:` key
+    // first: the bar was written into the frontmatter (then discarded by the
+    // resync), the body bar never moved, and `changes` reported an update that did
+    // not land. Measured on a STATE.md with a frontmatter progress block.
+    const syncBody = stripFrontmatter(content);
+    const syncHead = content.slice(0, content.length - syncBody.length);
+    let modified = syncBody;
     const today = clock_cjs_1.realClock.today();
     const phasesDir = planningPaths(cwd).phases;
     if (!node_fs_1.default.existsSync(phasesDir)) {
-        output({ synced: true, changes: [], dry_run: !!verify }, raw, undefined);
+        output({ synced: true, changes: [], dry_run: !!verify, frontmatter_updated: [] }, raw, undefined);
         return;
     }
     // Scan all phases
@@ -2142,23 +2688,16 @@ function cmdStateSync(cwd, options, raw) {
             .sort();
     }
     catch {
-        output({ synced: true, changes: [], dry_run: !!verify }, raw, undefined);
+        output({ synced: true, changes: [], dry_run: !!verify, frontmatter_updated: [] }, raw, undefined);
         return;
     }
-    let totalDiskPlans = 0;
-    let totalDiskSummaries = 0;
-    let diskCompletedPhases = 0;
     let highestIncompletePhase = null;
     let _highestIncompletePhaseNum = null;
     let highestIncompletePhaseplanCount = 0;
     let _highestIncompletePhaseSummaryCount = 0;
     for (const dir of entries) {
         const dirPath = node_path_1.default.join(phasesDir, dir);
-        const { planCount: plans, summaryCount: summaries, completed } = scanPhasePlans(dirPath);
-        totalDiskPlans += plans;
-        totalDiskSummaries += summaries;
-        if (completed)
-            diskCompletedPhases++;
+        const { planCount: plans, summaryCount: summaries } = scanPhasePlans(dirPath);
         // Track the highest phase with incomplete plans (or any plans)
         const phaseMatch = dir.match(/^(\d+[A-Z]?(?:\.\d+)*)/i);
         if (phaseMatch && plans > 0) {
@@ -2178,33 +2717,6 @@ function cmdStateSync(cwd, options, raw) {
             }
         }
     }
-    // Determine total phases from ROADMAP (may be larger than realized disk dirs).
-    // Mirrors the logic in buildStateFrontmatter so both report consistent percents (#3242 Bug B).
-    let syncTotalPhases = null;
-    try {
-        let roadmapPhaseCount = 0;
-        const roadmapPath = node_path_1.default.join(planningDir(cwd), 'ROADMAP.md');
-        const roadmapRaw = (0, shell_command_projection_cjs_1.platformReadSync)(roadmapPath);
-        if (roadmapRaw !== null) {
-            const roadmapScope = extractCurrentMilestone(roadmapRaw, cwd);
-            const phaseHeadingPattern = /#{2,4}\s*Phase\s+([\w][\w.-]*)\s*:/gi;
-            let m;
-            while ((m = phaseHeadingPattern.exec(roadmapScope)) !== null) {
-                // Only count tokens that contain at least one digit — excludes
-                // pure-word section headings (Overview, Details) while keeping
-                // numeric phases (01, 05.1) and project-code IDs (PROJ-42).
-                if (/\d/.test(m[1]))
-                    roadmapPhaseCount++;
-            }
-        }
-        if (roadmapPhaseCount > 0) {
-            syncTotalPhases = Math.max(entries.length, roadmapPhaseCount);
-        }
-        else {
-            syncTotalPhases = entries.length;
-        }
-    }
-    catch { /* intentionally empty */ }
     // Sync Total Plans in Phase
     if (highestIncompletePhase) {
         const currentPlansField = (0, state_document_cjs_1.stateExtractField)(modified, 'Total Plans in Phase');
@@ -2218,11 +2730,21 @@ function cmdStateSync(cwd, options, raw) {
     // Sync Progress — use shared helper so formula stays in one place (#3242 Bug B).
     // computeProgressPercent applies min(plan_fraction, phase_fraction) so unrealised
     // ROADMAP phases cap the reported percent rather than allowing a false 100%.
+    // 261007-ixt D-1: the body bar reads the SAME milestone scan as the frontmatter
+    // block (scanMilestoneDisk) and takes completed phases from the same owner, so
+    // the two surfaces cannot disagree. Fresh scan: sync re-derives from disk.
+    _diskScanCache.delete(cwd);
+    const syncScanRaw = scanMilestoneDisk(cwd);
+    const syncScan = syncScanRaw === CLOSED_MILESTONE_ONLY ? null : syncScanRaw;
     const percent = (() => {
-        const p = (0, state_document_cjs_1.computeProgressPercent)(totalDiskSummaries, totalDiskPlans, diskCompletedPhases, syncTotalPhases);
+        const p = syncScan
+            ? (0, state_document_cjs_1.computeProgressPercent)(syncScan.completedPlans, syncScan.totalPlans, (0, state_document_cjs_1.reconcileCompletedPhases)(syncScan.diskCompletedPhases, syncScan.roadmapCompletedPhases), syncScan.totalPhases)
+            : null;
         return p !== null ? p : 0;
     })();
-    const currentProgress = (0, state_document_cjs_1.stateExtractField)(modified, 'Progress');
+    // D-9: nothing on disk is the current milestone's → the bar is left as it is rather
+    // than written as 0%.
+    const currentProgress = syncScanRaw === CLOSED_MILESTONE_ONLY ? null : (0, state_document_cjs_1.stateExtractField)(modified, 'Progress');
     if (currentProgress) {
         const currentPercent = parseInt(currentProgress.replace(/[^\d]/g, ''), 10);
         if (currentPercent !== percent) {
@@ -2246,13 +2768,15 @@ function cmdStateSync(cwd, options, raw) {
         modified = result;
     }
     if (verify) {
-        output({ synced: false, changes, dry_run: true }, raw, undefined);
+        output({ synced: false, changes, dry_run: true, frontmatter_updated: [] }, raw, undefined);
         return;
     }
-    if (changes.length > 0 || modified !== content) {
-        writeStateMd(statePath, modified, cwd);
+    const nextContent = syncHead + modified;
+    let frontmatterUpdated = [];
+    if (changes.length > 0 || nextContent !== content) {
+        frontmatterUpdated = writeStateMd(statePath, nextContent, cwd).frontmatter_updated;
     }
-    output({ synced: true, changes, dry_run: false }, raw, undefined);
+    output({ synced: true, changes, dry_run: false, frontmatter_updated: frontmatterUpdated }, raw, undefined);
 }
 /**
  * Prune old entries from STATE.md sections that grow unboundedly (#1970).
@@ -2277,7 +2801,7 @@ function cmdStatePrune(cwd, options, raw) {
     const currentPhase = parseInt(currentPhaseRaw, 10) || 0;
     const cutoff = currentPhase - keepRecent;
     if (cutoff <= 0) {
-        emit({ pruned: false, reason: `Only ${currentPhase} phases — nothing to prune with --keep-recent ${keepRecent}` }, raw, 'false');
+        emit({ pruned: false, reason: `Only ${currentPhase} phases — nothing to prune with --keep-recent ${keepRecent}`, frontmatter_updated: [] }, raw, 'false');
         return;
     }
     const archivePath = node_path_1.default.join(node_path_1.default.dirname(statePath), 'STATE-ARCHIVE.md');
@@ -2396,10 +2920,11 @@ function cmdStatePrune(cwd, options, raw) {
             sections: result.archivedSections.map(s => ({ section: s.section, entries_would_archive: s.count })),
             total_would_archive: totalPruned,
             note: totalPruned > 0 ? 'Run without --dry-run to actually prune' : 'Nothing to prune',
+            frontmatter_updated: [],
         }, raw, totalPruned > 0 ? 'true' : 'false');
         return;
     }
-    readModifyWriteStateMd(statePath, (content) => {
+    const fmReport = readModifyWriteStateMd(statePath, (content) => {
         const result = prunePass(content);
         archived.push(...result.archivedSections);
         return result.newContent;
@@ -2425,6 +2950,7 @@ function cmdStatePrune(cwd, options, raw) {
         sections: archived.map(s => ({ section: s.section, entries_archived: s.count })),
         total_archived: totalPruned,
         archive_file: totalPruned > 0 ? 'STATE-ARCHIVE.md' : null,
+        frontmatter_updated: fmReport.frontmatter_updated,
     }, raw, totalPruned > 0 ? 'true' : 'false');
 }
 /**
@@ -2467,12 +2993,12 @@ function cmdStateCompletePhase(cwd, raw, overridePhase) {
     const existingCurrentPhaseMatch = String(existingCurrentPhaseRaw).match(/(\d+[A-Z]?(?:\.\d+)*)/i);
     const existingCurrentPhase = existingCurrentPhaseMatch ? existingCurrentPhaseMatch[1] : null;
     if (existingCurrentPhase && existingCurrentPhase !== resolvedPhase) {
-        output({ updated: [], phase: resolvedPhase, idempotent: true, note: 'phase already superseded; no-op' }, raw, 'false');
+        output({ updated: [], phase: resolvedPhase, idempotent: true, note: 'phase already superseded; no-op', frontmatter_updated: [] }, raw, 'false');
         return;
     }
     const today = clock_cjs_1.realClock.today();
     const updated = [];
-    readModifyWriteStateMd(statePath, (content) => {
+    const fmReport = readModifyWriteStateMd(statePath, (content) => {
         const currentPhase = resolvedPhase;
         // Bug #1255: operate on body only so the YAML frontmatter `status:` key
         // cannot shadow the body Status field (pipe-table or inline).
@@ -2548,7 +3074,7 @@ function cmdStateCompletePhase(cwd, raw, overridePhase) {
         }
         return reassemble(body);
     }, cwd);
-    output({ updated, phase: resolvedPhase }, raw, updated.length > 0 ? 'true' : 'false');
+    output({ updated, phase: resolvedPhase, frontmatter_updated: fmReport.frontmatter_updated }, raw, updated.length > 0 ? 'true' : 'false');
 }
 module.exports = {
     stateExtractField: state_document_cjs_1.stateExtractField,
@@ -2559,6 +3085,7 @@ module.exports = {
     writeStateMd,
     readModifyWriteStateMd,
     syncStateFrontmatter,
+    matchSessionSection,
     withStateLock,
     updatePerformanceMetricsSection,
     cmdStateLoad,