@opengsd/gsd-core 1.9.1 → 1.11.0

package/gsd-core/bin/lib/smart-entry.cjs

@@ -57,10 +57,16 @@ const phaseLifecycle = require("./phase-lifecycle.cjs");
 const { deriveProgressFromRoadmap } = phaseLifecycle;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const stateDocument = require("./state-document.cjs");
-const { stateExtractField } = stateDocument;
+const { stateFieldValue } = stateDocument;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseId = require("./phase-id.cjs");
-const { comparePhaseNum, extractPhaseToken, normalizePhaseName, phaseTokenMatches } = phaseId;
+const { comparePhaseNum, extractPhaseToken, matchPhaseDirs, normalizePhaseName, stripProjectCodePrefix } = phaseId;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const stateMod = require("./state.cjs");
+const { readStateHeadFreshness } = stateMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const unusableInput = require("./unusable-input.cjs");
+const { warnUnusableInput, UNUSABLE_REASON } = unusableInput;
 // ─── Constants ────────────────────────────────────────────────────────────────
 /**
  * Staleness threshold for idle-stranded detection. A clean tree whose last
@@ -83,15 +89,6 @@ exports.SITUATIONS = Object.freeze([
     'unknown',
 ]);
 // ─── Detection ─────────────────────────────────────────────────────────────────
-/** Frontmatter scalar helper: prefer YAML frontmatter, fall back to body field. */
-function fmScalar(fm, body, key, bodyField) {
-    const v = fm[key];
-    if (typeof v === 'string' && v.trim())
-        return v.trim();
-    if (typeof v === 'number' || typeof v === 'boolean')
-        return String(v);
-    return stateExtractField(body, bodyField);
-}
 /** Read a scalar value from a nested frontmatter object (e.g. progress.total_phases). */
 function fmScalarKey(obj, key) {
     if (!obj || typeof obj !== 'object')
@@ -112,17 +109,115 @@ function parseIntOrNull(s) {
 }
 function phaseTokenFromDirName(name) {
     const token = extractPhaseToken(name);
-    return /^\d+(?:[A-Z])?(?:\.\d+)*(?:-|$)/i.test(token) ? token : null;
+    // #2528: the shape probe runs on the PROJECT-CODE-STRIPPED token. A prefixed
+    // directory tokenizes to `MEM-05-80-20`, which does not start with a digit,
+    // so the unstripped probe rejected it and the entry was dropped before any
+    // resolution ran — every phase in a project-coded plan was invisible here.
+    // The full token is still what is returned: `comparePhaseNum` strips the
+    // prefix itself, so the sort is unaffected, and `matchPhaseDirs` needs the
+    // real directory name.
+    const probe = stripProjectCodePrefix(token);
+    return /^\d+(?:[A-Z])?(?:\.\d+)*(?:-|$)/i.test(probe) ? token : null;
 }
 /**
  * Parse a `last_activity` value that may be an ISO date or a free-form string
  * into an epoch-ms timestamp. Returns null when unparseable.
+ *
+ * #2570: `last_activity` routinely carries a trailing " — <description>" — the
+ * shape `templates/state.md` itself prescribes (`Last activity: [YYYY-MM-DD] —
+ * [What happened]`), which gsd-core's own STATE.md mirrors into frontmatter.
+ * `Date.parse` on the whole string returns NaN, and because `staleActivity`
+ * treats null as "not stale" (fails open), the ONLY idle/staleness detector
+ * never fired on any project whose last_activity retained its description.
+ * Be liberal in what we accept (Postel): read the leading ISO date/time token
+ * when the value carries one, so the description suffix — whatever separator
+ * (em dash or hyphen) it uses — no longer silently blinds the detector; fall
+ * back to a whole-string parse for any other shape a hand edit might use.
  */
+/** Leading ISO date, with an optional time-of-day and offset. */
+const ISO_LEADING_RE = /^(\d{4})-(\d{2})-(\d{2})((?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?)/;
+/**
+ * A NAMED timezone designator at the start of the un-reconstructable remainder
+ * (#2571). ISO_LEADING_RE's offset group captures only `Z` / `±HH:MM`, so a
+ * named zone (GMT, EST, ...) is not in the leading token — it sits here.
+ * Reconstructing the token without it would let Date.parse read the time as
+ * LOCAL, shifting the instant by the host's offset (a wrong, host-dependent
+ * value), so a zone-shaped remainder must fail open (ADR-227).
+ *
+ * The shape is a short all-caps run (2–5 letters) that stands alone — the
+ * negative lookahead excludes the first letter of a Capitalised word like
+ * "Milestone", and an optional trailing offset is subsumed because the leading
+ * all-caps run already matches. Everything else — a lowercase or Capitalised
+ * description, a separator — is describable text and is reconstructed from the
+ * leading date.
+ *
+ * Consulted ONLY when the leading token captured a time-of-day (see the caller):
+ * a zone designator qualifies a clock time, so a BARE date can carry no zone
+ * hazard — reconstructing it is always just that date's UTC midnight, whatever
+ * trails it. Gating on the time keeps a description that merely opens with a
+ * tech acronym ("2026-06-08 CI green", "API refactor") on the reconstruct path
+ * instead of failing open. The prior "any letter" guard was too liberal — it
+ * failed open on every letter-led description and re-opened #2570.
+ */
+const ZONE_DESIGNATOR_RE = /^\s*[A-Z]{2,5}(?![A-Za-z])/;
+/**
+ * True only when y/m/d name a date that actually exists on the calendar.
+ *
+ * `Date.parse` validates shape but not value: it rolls an out-of-range day
+ * FORWARD rather than rejecting it (`2026-02-30` -> `2026-03-02`,
+ * `2026-04-31` -> `2026-05-01`). Shape-only validation would therefore
+ * propagate a different, wrong instant instead of failing safe — precisely
+ * what ADR-227 ("validate shape AND value; on failure of either layer coerce
+ * to the contract's safe default, never propagate") exists to prevent. A
+ * round-trip through Date.UTC detects the rollover: any component the
+ * constructor normalised comes back changed.
+ */
+function isRealCalendarDate(year, month, day) {
+    if (month < 1 || month > 12 || day < 1 || day > 31)
+        return false;
+    const probe = new Date(Date.UTC(year, month - 1, day));
+    return (probe.getUTCFullYear() === year &&
+        probe.getUTCMonth() === month - 1 &&
+        probe.getUTCDate() === day);
+}
 function parseActivityTimestamp(raw) {
     if (!raw)
         return null;
-    const ms = Date.parse(raw);
-    return Number.isNaN(ms) ? null : ms;
+    const trimmed = raw.trim();
+    const iso = trimmed.match(ISO_LEADING_RE);
+    if (iso) {
+        const [, year, month, day, time] = iso;
+        // Reject an impossible calendar date outright rather than letting
+        // Date.parse substitute a rolled-forward one. null = "no activity signal",
+        // the safe default staleActivity already fails open on.
+        if (!isRealCalendarDate(Number(year), Number(month), Number(day)))
+            return null;
+        // The date is real, so stay as liberal as before (Postel): a whole-string
+        // parse still wins when the engine can make sense of the value. Reading the
+        // token first would silently DROP a trailing zone name -- "2026-06-08
+        // 12:34:56 GMT" parses whole as 12:34:56Z but as local time from the token,
+        // shifting the instant by the host's UTC offset.
+        const whole = Date.parse(trimmed);
+        if (!Number.isNaN(whole))
+            return whole;
+        // Whole-string failed: the value carries a suffix the engine can't read as
+        // one instant (#2570). Reconstruct from the leading token UNLESS the remainder
+        // is a named zone the token dropped (GMT, EST, ...): reconstructing without it
+        // reads the time as LOCAL and shifts the instant by the host's offset, so a
+        // zone-shaped remainder fails open (ADR-227: never propagate a wrong instant;
+        // null is the base's not-stale default). An ordinary description -- the #2570
+        // template's " -- description", or a hand edit's bare-space/tab/colon suffix --
+        // carries no zone and IS reconstructed. See ZONE_DESIGNATOR_RE for the shape;
+        // the earlier "any letter" guard failed open on every description and re-opened
+        // #2570 for whitespace-separated suffixes.
+        const rest = trimmed.slice(iso[0].length);
+        if (time && ZONE_DESIGNATOR_RE.test(rest))
+            return null;
+        const ms = Date.parse(`${year}-${month}-${day}${time}`);
+        return Number.isNaN(ms) ? null : ms;
+    }
+    const direct = Date.parse(trimmed);
+    return Number.isNaN(direct) ? null : direct;
 }
 /** Read-only git signals. Any git error is swallowed → "no git signal". */
 function readGitSignals(cwd) {
@@ -134,6 +229,7 @@ function readGitSignals(cwd) {
                 maxBuffer: 4 * 1024 * 1024,
                 windowsHide: true,
                 stdio: ['pipe', 'pipe', 'pipe'],
+                timeout: 10_000,
             });
         }
         catch {
@@ -183,7 +279,16 @@ function detectVerifyFailed(cwd, currentPhaseRaw) {
     let targetDir;
     if (phaseToken) {
         const normalized = normalizePhaseName(phaseToken);
-        targetDir = entries.find((name) => phaseTokenMatches(name, normalized));
+        // #2528: the fourth directory-resolution site, and the one where a miss is
+        // silent — a phase whose directory cannot be found reports "not failed",
+        // which reads identically to a healthy phase. It must therefore apply the
+        // same canonical selection as the locator and the two command scans, or a
+        // dir like `05-80-20-cleanup` (phase 5 named "80/20 Cleanup") never
+        // surfaces its own failed verification. `entries` is already sorted, and
+        // `matchPhaseDirs` filters without reordering, so taking the first match
+        // preserves the previous `.find()` selection exactly.
+        const { matches } = matchPhaseDirs(entries, normalized);
+        targetDir = matches[0];
         if (!targetDir)
             return false;
     }
@@ -250,6 +355,9 @@ function detectSignals(cwd, now = Date.now) {
         stale_activity: false,
         roadmap_total_phases: null,
         roadmap_completed_phases: null,
+        // No STATE.md (or unreadable) → no stamp to compare. Unknown, not fresh.
+        state_commits_behind: null,
+        state_commit_stale: null,
     };
     if (!hasPlanning)
         return empty;
@@ -263,21 +371,29 @@ function detectSignals(cwd, now = Date.now) {
     //   - body prose:         `Phase: 3`, `**Status:** verifying`, `Total Phases: 5`
     // Read each field across every form, scalar-first then nested then body, so
     // the classifier works on real STATE.md files written by current GSD.
-    const statusRaw = fmScalar(fm, body, 'status', 'Status');
-    const pausedAtRaw = fmScalar(fm, body, 'paused_at', 'Paused At');
-    const lastActivityRaw = fmScalar(fm, body, 'last_activity', 'Last Activity');
+    const statusRaw = stateFieldValue(fm, body, 'status', 'Status').value;
+    const pausedAtRaw = stateFieldValue(fm, body, 'paused_at', 'Paused At').value;
+    const lastActivityRaw = stateFieldValue(fm, body, 'last_activity', 'Last Activity').value;
     // current_phase: scalar fm → nested (none) → body "Current Phase" → body "Phase".
     // The body `Phase:` field is the canonical location in prose-form STATE.md
     // (e.g. "Phase: 3" or "Phase: 3 — ui-review"); parse the leading number.
-    const currentPhaseRaw = fmScalar(fm, body, 'current_phase', 'Current Phase') ??
-        stateExtractField(body, 'Phase');
+    // #3187 / ADR-3180 Amendment 3 ("0.x split"): this read is DELIBERATELY
+    // unscoped — smart-entry classifies `gsd next` routing over the whole body,
+    // whereas state.cts's copies of this same field scope it to `## Current
+    // Position` (#1776/#2956). Those are two different questions sharing a
+    // name; folding the scoped read in here would silently change smart-entry's
+    // routing, an undisclosed Tier-2 change (design's Rejected #3). Both owner
+    // calls below intentionally pass the unscoped `body`, never a Current-
+    // Position slice.
+    const currentPhaseRaw = stateFieldValue(fm, body, 'current_phase', 'Current Phase').value ??
+        stateFieldValue(fm, body, null, 'Phase').value;
     // total_phases & percent: nested `progress:` object takes precedence in the
     // nested schema; scalar fm / body fields cover the flat schema.
     const progressFm = typeof fm.progress === 'object' ? fm.progress : null;
     const totalPhasesRaw = fmScalarKey(progressFm, 'total_phases') ??
-        fmScalar(fm, body, 'total_phases', 'Total Phases');
+        stateFieldValue(fm, body, 'total_phases', 'Total Phases').value;
     const progressRaw = fmScalarKey(progressFm, 'percent') ??
-        fmScalar(fm, body, 'progress', 'Progress');
+        stateFieldValue(fm, body, 'progress', 'Progress').value;
     // Blockers list: `- <text>` items under a `## Blockers` heading.
     const blockers = [];
     const blockersSection = (0, markdown_sectionizer_cjs_1.collectSection)(body, (h) => h.level === 2 && h.text.trim().toLowerCase() === 'blockers', { levelBounded: true });
@@ -290,7 +406,16 @@ function detectSignals(cwd, now = Date.now) {
     // Stale = no recorded activity for IDLE_STALE_MS. Used only by idle-stranded.
     // Computed here (with the clock seam) so the pure classify() stays a function
     // of (signals, staleActivity) and detectSignals owns all disk reads.
+    // #3099 (ADR-1411 amendment): if last_activity is present but unparseable,
+    // emit a diagnostic so the silent fallback (stale_activity: false) is visible.
+    // The fallback itself stays — continuity is correct, the silence was the defect.
     const lastActivityMs = parseActivityTimestamp(lastActivityRaw);
+    if (lastActivityRaw && lastActivityMs === null) {
+        warnUnusableInput({
+            reason: UNUSABLE_REASON.LAST_ACTIVITY_UNPARSEABLE,
+            source: paths.state,
+        });
+    }
     const staleActivity = lastActivityMs !== null && now() - lastActivityMs > IDLE_STALE_MS;
     // Verify-failed may be signalled either by STATE.md status or by a failed
     // STATUS: marker on the current phase's summary/verify artifact.
@@ -314,6 +439,11 @@ function detectSignals(cwd, now = Date.now) {
             /* ROADMAP.md unreadable — leave null; isComplete falls back to legacy. */
         }
     }
+    // #2573: commit-age freshness proxy. Derived through state.cjs's
+    // readStateHeadFreshness so the tri-state and the hash fence stay identical
+    // to validate.health's W024 — one derivation, two surfaces.
+    const stateHeadRaw = stateFieldValue(fm, body, 'state_head', 'State Head').value;
+    const freshness = readStateHeadFreshness(cwd, stateHeadRaw);
     return {
         current_phase: parseIntOrNull(currentPhaseRaw),
         total_phases: parseIntOrNull(totalPhasesRaw),
@@ -330,6 +460,8 @@ function detectSignals(cwd, now = Date.now) {
         stale_activity: staleActivity,
         roadmap_total_phases: roadmapTotalPhases,
         roadmap_completed_phases: roadmapCompletedPhases,
+        state_commits_behind: freshness.commits_behind,
+        state_commit_stale: freshness.commit_stale,
     };
 }
 // ─── Situation classification ─────────────────────────────────────────────────

package/gsd-core/bin/lib/state-command-router.cjs

@@ -144,7 +144,11 @@ function routeStateCommand({ state, args, cwd, raw, error }) {
             'signal-resume': () => state.cmdSignalResume(cwd, raw),
             'planned-phase': () => {
                 const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['phase', 'name', 'plans']);
-                state.cmdStatePlannedPhase(cwd, strArg(a, 'phase'), parsePlans(strArg(a, 'plans')), raw);
+                // #3395: --name was parsed here but never forwarded (the StateModule
+                // signature had no channel for it), so the argument was silently
+                // dropped. It now persists into the Current Position `Phase:` line and
+                // the authoritative current_phase_name, mirroring begin-phase.
+                state.cmdStatePlannedPhase(cwd, strArg(a, 'phase'), strArg(a, 'name'), parsePlans(strArg(a, 'plans')), raw);
             },
             validate: () => state.cmdStateValidate(cwd, raw),
             sync: () => {

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

@@ -10,8 +10,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KNOWN_STATUS_PATTERNS = exports.KNOWN_TEMPLATE_DEFAULTS = void 0;
 exports.stateExtractField = stateExtractField;
+exports.stateFieldValue = stateFieldValue;
+exports.stateCurrentPositionSlice = stateCurrentPositionSlice;
 exports.stateReplaceField = stateReplaceField;
 exports.stateReplaceFieldWithFallback = stateReplaceFieldWithFallback;
+exports.stateReplaceFieldInSession = stateReplaceFieldInSession;
 exports.normalizeStateStatus = normalizeStateStatus;
 exports.computeProgressPercent = computeProgressPercent;
 exports.shouldPreserveExistingProgress = shouldPreserveExistingProgress;
@@ -19,10 +22,12 @@ exports.normalizeProgressNumbers = normalizeProgressNumbers;
 exports.isStateTemplateDefault = isStateTemplateDefault;
 exports.stateReplaceFieldIfTemplate = stateReplaceFieldIfTemplate;
 const markdown_table_cjs_1 = require("./markdown-table.cjs");
-// Internal helpers
-function escapeRegex(str) {
-    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
+const phase_lifecycle_cjs_1 = require("./phase-lifecycle.cjs");
+const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
+const pattern_cjs_1 = require("./pattern.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-scope.cjs is an export= CommonJS module
+const planningScopeMod = require("./planning-scope.cjs");
+const { SCOPE } = planningScopeMod;
 function toFiniteNumber(value) {
     const number = Number(value);
     return Number.isFinite(number) ? number : null;
@@ -204,7 +209,7 @@ function locateFieldRow(content, fieldName) {
     return null;
 }
 function stateExtractField(content, fieldName) {
-    const escaped = escapeRegex(fieldName);
+    const escaped = (0, pattern_cjs_1.escapeRegex)(fieldName);
     // Bold inline format: **FieldName:** value
     const boldPattern = new RegExp(`\\*\\*${escaped}:\\*\\*[ \\t]*(.+)`, 'i');
     const boldMatch = content.match(boldPattern);
@@ -222,8 +227,107 @@ function stateExtractField(content, fieldName) {
         return hit.rawValue.trim();
     return null;
 }
+/**
+ * Single owner of the #1760 STATE.md field-extraction fallback chain: "read
+ * field F, preferring the YAML frontmatter scalar, falling back to the body
+ * field." Added for #3187 (epic #3180, ADR-3180 §7.7) to collapse three
+ * independent re-derivations of this chain — `src/smart-entry.cts`'s
+ * `fmScalar` closure, and `src/state.cts`'s `cmdStateSnapshot` and
+ * `cmdStatePrune` — onto one function, per ADR-3180 Decision 1 ("keep N
+ * copies with a parity test" is rejected: a parity test proves today's
+ * agreement, not that copy N+1 won't happen).
+ *
+ * Takes ALREADY-PARSED `fm` and `body` rather than raw STATE.md content: the
+ * heaviest caller, `cmdStateSnapshot`, reads roughly ten fields off one parse
+ * and must not re-parse frontmatter per field.
+ *
+ * `stateExtractField` (above) is deliberately left untouched — it has 20
+ * direct callers and a CRITICAL blast radius (ADR-3180 §7.7's Rejected #1) —
+ * so this function is additive: it calls `stateExtractField` rather than
+ * replacing it or changing its signature.
+ *
+ * Fallback ladder (unchanged from every prior copy this replaces):
+ *   1. `fm[fmKey]` is a non-empty (post-`.trim()`) string → that trimmed
+ *      string.
+ *   2. `fm[fmKey]` is a `number` or `boolean` → `String(fm[fmKey])`, so `0`
+ *      and `false` are VALUES, not absence.
+ *   3. Anything else (`null`, `undefined`, an object, an array, or an
+ *      empty/whitespace-only string) → fall through to
+ *      `stateExtractField(body, bodyField)`.
+ *
+ * `fmKey === null` skips steps 1–2 outright: for a caller whose chain has no
+ * frontmatter side for this particular field (e.g. `state.cts`'s body-only
+ * `Last Activity` / `Last activity` case-variant pair, which sits inside a
+ * function that DOES own a ladder for its other fields, so per this phase's
+ * function-scoped guard it must still route through this owner).
+ * `bodyField === null` skips step 3: for a caller whose "no frontmatter
+ * value" case falls through to an already-computed value instead of a fresh
+ * extractor call (e.g. `cmdStateSnapshot`'s `last_activity`, which falls to
+ * its already-parsed prose date rather than re-extracting the body).
+ *
+ * `scope` reports whether the chain ran over inputs it could actually
+ * consult (ADR-3180 Decision 2/§7.7 — mirrors `scanPhasePlans`'s
+ * scope-carrying result in `plan-scan.cts`; see `planning-scope.cjs`). This
+ * function's own ladder always runs to completion on whatever `fm`/`body` it
+ * is given, INCLUDING when the answer is `null` — a genuinely absent field is
+ * a real answer, not a failure to look (§7.7 behavior table row 4). So
+ * `scope` defaults to `SCOPE.COMPLETE` and is only ever something else when
+ * the CALLER passes `opts.scope`, because only the caller knows whether an
+ * input it handed in was itself degraded — e.g. `fm` came back `{}` from an
+ * unterminated frontmatter fence (`extractFrontmatter` swallows that parse
+ * failure), or `body` is an unscoped whole-document fallback because a
+ * required `## Current Position` section was not found (#2956). This
+ * function never invents a new `SCOPE` member — the enum is frozen at
+ * COMPLETE/TRUNCATED/UNSCOPED/UNREADABLE (`planning-scope.cjs`).
+ *
+ * #1760 is the fallback chain's origin.
+ */
+function stateFieldValue(fm, body, fmKey, bodyField, opts) {
+    const v = fmKey === null ? undefined : fm[fmKey];
+    let value;
+    if (typeof v === 'string' && v.trim()) {
+        value = v.trim();
+    }
+    else if (typeof v === 'number' || typeof v === 'boolean') {
+        value = String(v);
+    }
+    else {
+        value = bodyField === null ? null : stateExtractField(body, bodyField);
+    }
+    return { value, scope: opts?.scope ?? SCOPE.COMPLETE };
+}
+/**
+ * Match the "Current Position" section body from a STATE.md body. #2956: this
+ * is the Phase analogue of state.cts's matchSessionSection. `Phase` canonically
+ * lives under `## Current Position` (gsd-core/templates/state.md), so — like
+ * Stopped At / Paused At under `## Session` — it must be extracted from THAT
+ * section, not from the first `Phase:` / `**Phase:**` line anywhere in the
+ * body. Without the scope, a historical `Phase:` line in an archive section
+ * silently shadows the real one on every read/write, and because callers use
+ * this for routing (state.cts's current_phase) and for drift detection
+ * (gsd-tools.cjs's `drift-guard phase-status` CLI seam), a stale match either
+ * routes work to the wrong phase or fabricates a drift finding.
+ *
+ * Level-flexible: the canonical template uses an h2 `## Current Position`, the
+ * bootstrap template an h3 `### Current Position` (templates/state.md). Both
+ * must match — mirroring how matchSessionSection recognises `## Session` and
+ * `## Session Continuity`. Exact 'current position' text match (case-
+ * insensitive) excludes unrelated headings. Built on the `collectSection`
+ * seam, so it inherits that seam's CRLF tolerance (#2444 fix).
+ *
+ * This is the single owner of the scope — state.cts's private
+ * `matchCurrentPositionSection` delegates here rather than duplicating the
+ * logic, so the two consumers cannot drift apart.
+ *
+ * Returns the section body, or null (caller falls back to full-body search).
+ */
+function stateCurrentPositionSlice(body) {
+    const isCurrentPosition = (h) => (h.level === 2 || h.level === 3) && h.text.trim().toLowerCase() === 'current position';
+    const section = (0, markdown_sectionizer_cjs_1.collectSection)(body, isCurrentPosition, { levelBounded: true });
+    return section ? section.body : null;
+}
 function stateReplaceField(content, fieldName, newValue) {
-    const escaped = escapeRegex(fieldName);
+    const escaped = (0, pattern_cjs_1.escapeRegex)(fieldName);
     // Bold inline format: **FieldName:** value
     const boldPattern = new RegExp(`(\\*\\*${escaped}:\\*\\*\\s*)(.*)`, 'i');
     if (boldPattern.test(content)) {
@@ -253,6 +357,33 @@ function stateReplaceFieldWithFallback(content, primary, fallback, value) {
     }
     return content;
 }
+/**
+ * #3374: session-scoped variant of stateReplaceFieldWithFallback for the
+ * `## Session` continuity fields. The post-sync harvest (state.cts's
+ * matchSessionSection → buildStateFrontmatter) reads these fields ONLY from
+ * the session section, so a writer that refreshes one must target the same
+ * scope — a whole-body replace lets a decoy `**Stopped at:**` line in an
+ * unrelated (e.g. archive) section absorb the refresh while the harvested
+ * session value stays stale.
+ *
+ * Section preference mirrors the reader exactly: the normalized `## Session`
+ * block wins over the bootstrap `## Session Continuity` heading when both
+ * exist (legacy duplicate files); the continuity heading is only consulted
+ * when no canonical `## Session` section exists. `levelBounded` heading
+ * matching also excludes `## Session Continuity Archive` (the #2444 scoping).
+ *
+ * Replace-only (no insertion): returns `content` unchanged when no session
+ * section exists or the field is absent from it, so a STATE.md layout without
+ * the line keeps its shape and the post-sync preservation pass decides the
+ * frontmatter value (see #3374).
+ */
+function stateReplaceFieldInSession(content, primary, fallback, value) {
+    const isSession = (h) => h.level === 2 && h.text.trim().toLowerCase() === 'session';
+    const isSessionContinuity = (h) => h.level === 2 && h.text.trim().toLowerCase() === 'session continuity';
+    const hasCanonicalSession = (0, markdown_sectionizer_cjs_1.collectSection)(content, isSession, { levelBounded: true }) !== null;
+    const target = hasCanonicalSession ? isSession : isSessionContinuity;
+    return (0, markdown_sectionizer_cjs_1.withSection)(content, target, (sectionBody) => stateReplaceFieldWithFallback(sectionBody, primary, fallback, value));
+}
 function normalizeStateStatus(status, pausedAt) {
     let normalizedStatus = status || 'unknown';
     const statusLower = (status || '').toLowerCase();
@@ -279,7 +410,20 @@ function normalizeStateStatus(status, pausedAt) {
     }
     return normalizedStatus;
 }
-function computeProgressPercent(completedPlans, totalPlans, completedPhases, totalPhases) {
+/**
+ * ADR-3180 §7.6 rule 4 (#3217): `scope` is the `listMilestonePhaseDirs`-owner
+ * discriminator for the phase/plan set these four counts were derived from.
+ * A caller that cannot vouch for `scope === SCOPE.COMPLETE` must pass the
+ * scope it actually has — this function refuses to compose a percentage
+ * from counts whose scope says they are not a trustworthy answer, returning
+ * `null` (never `0`; see the module's already-existing "no data" `null`
+ * below, which this generalizes) exactly like its pre-existing "no data"
+ * case. `scope` is REQUIRED (no default) so a caller cannot silently opt out
+ * of rule 4 by omission.
+ */
+function computeProgressPercent(completedPlans, totalPlans, completedPhases, totalPhases, scope) {
+    if (scope !== SCOPE.COMPLETE)
+        return null;
     const hasPlanData = totalPlans !== null && totalPlans > 0 && completedPlans !== null;
     const hasPhaseData = totalPhases !== null && totalPhases > 0 && completedPhases !== null;
     if (!hasPlanData && !hasPhaseData)
@@ -288,7 +432,7 @@ function computeProgressPercent(completedPlans, totalPlans, completedPhases, tot
     // cannot track through intermediate boolean variables).
     const planFraction = hasPlanData ? (completedPlans ?? 0) / (totalPlans ?? 1) : 1;
     const phaseFraction = hasPhaseData ? (completedPhases ?? 0) / (totalPhases ?? 1) : 1;
-    return Math.min(100, Math.round(Math.min(planFraction, phaseFraction) * 100));
+    return (0, phase_lifecycle_cjs_1.clampPercentFromFraction)(Math.min(planFraction, phaseFraction));
 }
 function shouldPreserveExistingProgress(existingProgress, derivedProgress) {
     if (!existingProgress || typeof existingProgress !== 'object')