@pareto4/pp-core 1.11.1 → 1.12.0

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

@@ -15,6 +15,11 @@ exports.stateReplaceFieldWithFallback = stateReplaceFieldWithFallback;
 exports.normalizeStateStatus = normalizeStateStatus;
 exports.computeProgressPercent = computeProgressPercent;
 exports.shouldPreserveExistingProgress = shouldPreserveExistingProgress;
+exports.reconcileCompletedPhases = reconcileCompletedPhases;
+exports.matchCurrentPositionSection = matchCurrentPositionSection;
+exports.extractPositionalField = extractPositionalField;
+exports.holdNewerActivityDate = holdNewerActivityDate;
+exports.diffFrontmatterFields = diffFrontmatterFields;
 exports.normalizeProgressNumbers = normalizeProgressNumbers;
 exports.isStateTemplateDefault = isStateTemplateDefault;
 exports.stateReplaceFieldIfTemplate = stateReplaceFieldIfTemplate;
@@ -76,17 +81,20 @@ function stateExtractField(content, fieldName) {
         return tableMatch[4].trim();
     return null;
 }
+// The value separator is `[ \t]*`, as in stateExtractField: `\s*` crossed a newline, so an
+// EMPTY field consumed the next line. An empty field's prefix ends at the colon, so the
+// writer supplies the single space the format puts there.
 function stateReplaceField(content, fieldName, newValue) {
     const escaped = escapeRegex(fieldName);
     // Bold inline format: **FieldName:** value
-    const boldPattern = new RegExp(`(\\*\\*${escaped}:\\*\\*\\s*)(.*)`, 'i');
+    const boldPattern = new RegExp(`(\\*\\*${escaped}:\\*\\*[ \\t]*)(.*)`, 'i');
     if (boldPattern.test(content)) {
-        return content.replace(boldPattern, (_match, prefix) => `${prefix}${newValue}`);
+        return content.replace(boldPattern, (_match, prefix) => `${prefix}${/[ \t]$/.test(prefix) ? '' : ' '}${newValue}`);
     }
     // Plain line-start format: FieldName: value
-    const plainPattern = new RegExp(`(^${escaped}:\\s*)(.*)`, 'im');
+    const plainPattern = new RegExp(`(^${escaped}:[ \\t]*)(.*)`, 'im');
     if (plainPattern.test(content)) {
-        return content.replace(plainPattern, (_match, prefix) => `${prefix}${newValue}`);
+        return content.replace(plainPattern, (_match, prefix) => `${prefix}${/[ \t]$/.test(prefix) ? '' : ' '}${newValue}`);
     }
     // Pipe-table format: | FieldName | value |
     // Preserve the surrounding pipe/whitespace structure; only swap the value cell.
@@ -146,6 +154,20 @@ function computeProgressPercent(completedPlans, totalPlans, completedPhases, tot
     const phaseFraction = hasPhaseData ? (completedPhases ?? 0) / (totalPhases ?? 1) : 1;
     return Math.min(100, Math.round(Math.min(planFraction, phaseFraction) * 100));
 }
+/**
+ * Decide whether a stored `progress` block must survive a re-derivation on the
+ * read path (`state json`).
+ *
+ * #3242 Bug A: a curated cross-milestone aggregate legitimately counts phases and
+ * plans the local disk scan cannot see, and its signature is a larger TOTAL — so a
+ * block whose `total_phases` or `total_plans` exceeds the derived one is kept whole.
+ *
+ * 261007-ixt D-1: a block whose totals do NOT exceed the derived ones but whose
+ * `completed_*` / `percent` are higher is not curation — it is the inflated count
+ * the writer used to store (a phase whose plans all have summaries, counted
+ * Complete while its ROADMAP row read `Built`). Preserving it would re-report the
+ * false number on every read, so the derived value wins.
+ */
 function shouldPreserveExistingProgress(existingProgress, derivedProgress) {
     if (!existingProgress || typeof existingProgress !== 'object')
         return false;
@@ -154,9 +176,104 @@ function shouldPreserveExistingProgress(existingProgress, derivedProgress) {
     const existing = existingProgress;
     const derived = derivedProgress;
     return (existingProgressExceedsDerived(existing, derived, 'total_phases') ||
-        existingProgressExceedsDerived(existing, derived, 'completed_phases') ||
-        existingProgressExceedsDerived(existing, derived, 'total_plans') ||
-        existingProgressExceedsDerived(existing, derived, 'completed_plans'));
+        existingProgressExceedsDerived(existing, derived, 'total_plans'));
+}
+/**
+ * The ONE owner of `completed_phases` (261007-ixt D-1).
+ *
+ * The disk scan counts a phase complete when every PLAN has a SUMMARY — that is
+ * BUILT. The ROADMAP progress table's Status column says whether a phase is
+ * COMPLETE. When the table yields a count, the record may not claim more than it
+ * grants, so the result is the smaller of the two; when the table is silent
+ * (`null`), the disk count stands. A forged or stale table can only LOWER the
+ * count, never inflate it.
+ */
+function reconcileCompletedPhases(diskCompletedPhases, roadmapCompletedPhases) {
+    if (roadmapCompletedPhases === null || !Number.isFinite(roadmapCompletedPhases))
+        return diskCompletedPhases;
+    return Math.min(diskCompletedPhases, roadmapCompletedPhases);
+}
+/**
+ * Match the `## Current Position` section of a STATE.md body. Group 1 is the
+ * section body (up to the next `##` heading or the end). The same pattern text
+ * `updateCurrentPositionFields` and the milestone/complete-phase writers use, so
+ * the reader and the writers agree on what the section is.
+ */
+function matchCurrentPositionSection(body) {
+    return body.match(/##\s*Current Position\s*\n([\s\S]*?)(?=\n##|$)/i);
+}
+/**
+ * Read a POSITIONAL source field (`Phase`, `Status`, `Last activity`) for the
+ * frontmatter writer (261007-ixt D-2).
+ *
+ * `stateExtractField` prefers a bold `**Field:**` ANYWHERE in the body over a
+ * line-start `Field:`, so a `**Status:**` in a historical log entry shadowed the
+ * `## Current Position` line the engine itself maintains. The position section is
+ * where the current position lives: read it first, and fall back to the whole
+ * body only when the section is absent or does not carry the field (so documents
+ * without the section keep their reading).
+ */
+function extractPositionalField(body, fieldName, fallbackFieldName) {
+    const section = matchCurrentPositionSection(body);
+    if (section) {
+        const scoped = stateExtractField(section[1], fieldName)
+            ?? (fallbackFieldName ? stateExtractField(section[1], fallbackFieldName) : null);
+        if (scoped !== null)
+            return scoped;
+    }
+    return stateExtractField(body, fieldName)
+        ?? (fallbackFieldName ? stateExtractField(body, fallbackFieldName) : null);
+}
+const ISO_DATE_PREFIX = /^(\d{4}-\d{2}-\d{2})/;
+/**
+ * A record date never moves backwards (261007-ixt W3a). `last_activity` is re-derived
+ * from the body's `Last activity:` line on every write; when that line lags the
+ * frontmatter (measured on the pre-close v1.1 record: 2026-09-21 rewritten to
+ * 2026-09-20 by `state record-session`), the older date would overwrite the newer
+ * one. When both values start with an ISO date and the derived one is OLDER, the
+ * stored `last_activity` and its `last_activity_desc` are kept as a pair. Returns the
+ * frontmatter to write; the input is not modified.
+ */
+function holdNewerActivityDate(existingFm, derivedFm) {
+    const stored = typeof existingFm['last_activity'] === 'string' ? existingFm['last_activity'].match(ISO_DATE_PREFIX) : null;
+    const derived = typeof derivedFm['last_activity'] === 'string' ? derivedFm['last_activity'].match(ISO_DATE_PREFIX) : null;
+    if (!stored || !derived || derived[1] >= stored[1])
+        return derivedFm;
+    const held = { ...derivedFm, last_activity: existingFm['last_activity'] };
+    if (existingFm['last_activity_desc'] !== undefined)
+        held['last_activity_desc'] = existingFm['last_activity_desc'];
+    else
+        delete held['last_activity_desc'];
+    return held;
+}
+function flattenFrontmatterForDiff(fm) {
+    const out = {};
+    if (!fm || typeof fm !== 'object')
+        return out;
+    for (const [key, value] of Object.entries(fm)) {
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            for (const [sub, subValue] of Object.entries(value)) {
+                out[`${key}.${sub}`] = subValue;
+            }
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+/**
+ * The dotted frontmatter keys (one level of nesting flattened, e.g.
+ * `progress.percent`) whose value differs between two parsed frontmatter objects,
+ * sorted. Keys present on only one side are included; nothing is excluded —
+ * `last_updated` included — because a report that omits a key it changed is the
+ * defect 261007-ixt D-3 closes.
+ */
+function diffFrontmatterFields(before, after) {
+    const a = flattenFrontmatterForDiff(before);
+    const b = flattenFrontmatterForDiff(after);
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    return [...keys].filter((key) => JSON.stringify(a[key]) !== JSON.stringify(b[key])).sort();
 }
 function normalizeProgressNumbers(progress) {
     if (!progress || typeof progress !== 'object')