@opengsd/gsd-core 1.10.0 → 1.12.0

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

@@ -15,8 +15,15 @@
  * file I/O, and the disk-scan wrap it.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.STATE_MD_SECTIONS = exports.FIELD_CLASSIFICATION = void 0;
+exports.STATE_MD_SECTIONS = exports.FRONTMATTER_BODY_SOURCE = exports.FIELD_CLASSIFICATION = void 0;
+exports.beginFrontmatterReassembly = beginFrontmatterReassembly;
+exports.getFrontmatterBodySource = getFrontmatterBodySource;
+exports.frontmatterKeyForBodyField = frontmatterKeyForBodyField;
 exports.getFieldClassification = getFieldClassification;
+exports.getPreserveWhenUnchangedFields = getPreserveWhenUnchangedFields;
+exports.openStateTransaction = openStateTransaction;
+exports.rebuildStateTransaction = rebuildStateTransaction;
+exports.applyPreserveWhenUnchanged = applyPreserveWhenUnchanged;
 exports.applyStatePreservation = applyStatePreservation;
 exports.transitionCore = transitionCore;
 exports.sliceCurrentPositionSection = sliceCurrentPositionSection;
@@ -26,10 +33,53 @@ const state_document_cjs_1 = require("./state-document.cjs");
 const state_document_cjs_2 = require("./state-document.cjs");
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 const phase_lifecycle_cjs_1 = require("./phase-lifecycle.cjs");
+const pattern_cjs_1 = require("./pattern.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
-const phaseIdMod = require("./phase-id.cjs");
-const { extractFrontmatter, reconstructFrontmatter, stripFrontmatter } = frontmatter;
-const { escapeRegex } = phaseIdMod;
+const stateMdSchemaMod = require("./state-md-schema.cjs");
+const { STATE_FIELD_SCHEMA } = stateMdSchemaMod;
+const { extractFrontmatter, reconstructFrontmatter, stripFrontmatter, FRONTMATTER_UNPARSEABLE } = frontmatter;
+/**
+ * ADR-3473 §8.1 (#3881, consequence 2 wiring): does `existingFm` carry the
+ * `FRONTMATTER_UNPARSEABLE` marker `extractFrontmatter` sets when a
+ * frontmatter-fenced region exists but failed to parse (malformed YAML, or a
+ * refused anchor/alias/merge key)? A plain `Object.keys(existingFm).length >
+ * 0` check cannot distinguish that case from "no frontmatter block at all" —
+ * both parse to `{}` — so every `hasFrontmatter`-gated reassemble below would
+ * silently drop the raw frontmatter block on the next write. The marker is a
+ * non-enumerable-to-Object.keys Symbol key, so this check is additive and
+ * never fires for the genuinely-empty case.
+ */
+function isUnparseableFrontmatter(existingFm) {
+    return existingFm[FRONTMATTER_UNPARSEABLE] === true;
+}
+/**
+ * ADR-3473 §8.1 (#3881): the exact bytes `stripFrontmatter` removed from the
+ * front of `content` to produce `strippedBody` — i.e. `content`'s raw
+ * frontmatter-fenced prefix, verbatim, whether or not it parsed. Reassembling
+ * with this prefix (instead of dropping it under `hasFrontmatter === false`)
+ * is what preserves an UNPARSEABLE frontmatter block across a write; it is a
+ * no-op difference from `content` itself when `strippedBody === content`
+ * (nothing was stripped).
+ */
+function rawFrontmatterPrefix(content, strippedBody) {
+    return content.slice(0, content.length - strippedBody.length);
+}
+function beginFrontmatterReassembly(content, sourcePath) {
+    const existingFm = extractFrontmatter(content, sourcePath);
+    const hasFrontmatter = Object.keys(existingFm).length > 0;
+    const body = stripFrontmatter(content);
+    // ADR-3473 §8.1 (#3881): computed from the ORIGINAL content/body pair, before any caller
+    // reassigns `body` further — the captured prefix is always the exact bytes stripped from
+    // the ORIGINAL content, regardless of what the caller does with `body` afterward.
+    const fmPrefix = rawFrontmatterPrefix(content, body);
+    const unparseableFm = isUnparseableFrontmatter(existingFm);
+    const reassemble = (b) => hasFrontmatter
+        ? `---\n${reconstructFrontmatter(existingFm)}\n---\n\n${b}`
+        : unparseableFm
+            ? `${fmPrefix}${b}`
+            : b;
+    return { existingFm, hasFrontmatter, body, fmPrefix, unparseableFm, reassemble };
+}
 // Stop predicate for section-body slicing: a level-2+ heading ends the section.
 const STOP_H2_PLUS = (lv) => lv >= 2;
 /**
@@ -46,32 +96,150 @@ const STOP_H2_PLUS = (lv) => lv >= 2;
  * (`FIELD_CLASSIFICATION['toString']` returns undefined, not the inherited
  * function). Use `getFieldClassification()` for lookups.
  */
-exports.FIELD_CLASSIFICATION = Object.freeze(Object.assign(Object.create(null), {
-    // Schema
-    gsd_state_version: { source: 'free', preservation: 'derive' },
-    // Milestone (external — from ROADMAP.md)
-    milestone: { source: 'external', preservation: 'preserve-if-placeholder' },
-    milestone_name: { source: 'external', preservation: 'preserve-if-placeholder' },
-    // Phase / plan position (body-derived)
-    current_phase: { source: 'body', preservation: 'preserve-when-unchanged' },
-    current_phase_name: { source: 'curated', preservation: 'preserve-always' }, // #1743, #1695
-    current_plan: { source: 'body', preservation: 'preserve-when-unchanged' },
-    // Status / lifecycle (body-derived; #1230 delta heuristic applies)
-    status: { source: 'body', preservation: 'preserve-when-unchanged' },
-    stopped_at: { source: 'body', preservation: 'preserve-when-unchanged' },
-    paused_at: { source: 'body', preservation: 'preserve-when-unchanged' },
-    // Activity log
-    last_updated: { source: 'free', preservation: 'derive' }, // realClock.nowIso()
-    last_activity: { source: 'body', preservation: 'derive' }, // always refresh on transition
-    last_activity_desc: { source: 'body', preservation: 'preserve-when-unchanged' },
-    // Progress block (disk-derived, except the curated progress ratchet)
-    progress: { source: 'curated', preservation: 'preserve-always' }, // #3242, #1446
-    'progress.total_phases': { source: 'disk', preservation: 'derive' },
-    'progress.completed_phases': { source: 'disk', preservation: 'derive' },
-    'progress.total_plans': { source: 'disk', preservation: 'derive' },
-    'progress.completed_plans': { source: 'disk', preservation: 'derive' },
-    'progress.percent': { source: 'disk', preservation: 'derive' },
-}));
+/**
+ * #3873 (ADR-3473 §8.8): PROJECTED from `STATE_FIELD_SCHEMA`
+ * (`src/state-md-schema.cts`) rather than hand-maintained here. Byte-identical
+ * to the pre-#3873 literal table — same 19 keys, same key ORDER (walks
+ * `Object.keys(STATE_FIELD_SCHEMA)` directly; see that module's row-order
+ * comment for why this is the one projection allowed to do that), same
+ * per-row shape (`{source, preservation, guard?, mergeStrategy?}`, in that
+ * key order, `guard`/`mergeStrategy` present only when the schema row carries
+ * them — never as an `undefined` own-property), same frozen null-prototype
+ * container. Pinned by `tests/state-transition.test.cjs`'s
+ * `fieldClassificationProjectionMatchesTodaysTable`, whose comparand is
+ * today's literal copied VERBATIM into the test (never re-derived from this
+ * schema — see that test's own docstring on why a self-referential parity
+ * test proves nothing).
+ */
+exports.FIELD_CLASSIFICATION = Object.freeze(Object.keys(STATE_FIELD_SCHEMA).reduce((acc, key) => {
+    const row = STATE_FIELD_SCHEMA[key];
+    const projected = { source: row.source, preservation: row.preservation };
+    if (row.guard !== undefined)
+        projected.guard = row.guard;
+    if (row.mergeStrategy !== undefined)
+        projected.mergeStrategy = row.mergeStrategy;
+    acc[key] = projected;
+    return acc;
+}, Object.create(null)));
+/**
+ * Which BODY field feeds each frontmatter key.
+ *
+ * `FIELD_CLASSIFICATION` above answers "who wins when frontmatter and body
+ * disagree"; this answers "and what is the body one called". They are separate
+ * questions and this one is display/routing knowledge, not preservation policy,
+ * so it does not widen the ADR-3408-governed table.
+ *
+ * #3699: `state update stopped_at …` reported `Field "stopped_at" not found in
+ * STATE.md` — byte-identical to what a genuinely absent field reports. The key
+ * IS present; it is a projection of a body field, and the message pointed away
+ * from the route that works. Naming the source is what makes the two cases
+ * distinguishable.
+ *
+ * Transcribed from `buildStateFrontmatter` (`state.cts`), which is the real
+ * deriver. That makes this a SECOND copy of knowledge that already exists, so it
+ * ships with a parity test asserting this key set equals the body-derived key set
+ * the builder actually emits (CLAUDE.md → Generative Fix Divergence). Keys the
+ * builder derives from disk, an external file, or the clock have no body source
+ * and are deliberately ABSENT here rather than mapped to a lie.
+ */
+/**
+ * #3873 (ADR-3473 §8.8): PROJECTED from `STATE_FIELD_SCHEMA`
+ * (`src/state-md-schema.cts`)'s `bodySource` field, in this EXPLICIT key
+ * order. This order is NOT `STATE_FIELD_SCHEMA`'s own row order filtered down
+ * to the body-sourced keys — the pre-#3873 literal already put `status`
+ * before `stopped_at`/`paused_at` here while `FRONTMATTER_KEY_TO_BODY_LABEL`
+ * (`src/state.cts`) put it AFTER them, i.e. the two pre-existing tables
+ * disagreed with each other's order too, and this projection must reproduce
+ * ITS table's order specifically. Byte-identical to the pre-#3873 literal —
+ * same 8 keys, same order, same frozen null-prototype container with frozen
+ * per-key arrays. Pinned by `tests/state-transition.test.cjs`'s
+ * `bodySourceProjectionMatchesTodaysTable`.
+ */
+const FRONTMATTER_BODY_SOURCE_KEY_ORDER = Object.freeze([
+    'current_phase',
+    'current_phase_name',
+    'current_plan',
+    'status',
+    'stopped_at',
+    'paused_at',
+    'last_activity',
+    'last_activity_desc',
+]);
+exports.FRONTMATTER_BODY_SOURCE = Object.freeze(FRONTMATTER_BODY_SOURCE_KEY_ORDER.reduce((acc, key) => {
+    const row = STATE_FIELD_SCHEMA[key];
+    acc[key] = Object.freeze([...(row.bodySource ?? [])]);
+    return acc;
+}, Object.create(null)));
+/**
+ * The frontmatter keys whose body source lives inside `## Session`.
+ *
+ * #3374 established that these fields must be written where the reader reads
+ * them: `buildStateFrontmatter` harvests `Stopped At` / `Paused At` from the
+ * session section only, so 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" (`stateReplaceFieldInSession`'s own
+ * docstring). `updateCore` was still doing the whole-body replace.
+ */
+const SESSION_SCOPED_KEYS = new Set(['stopped_at', 'paused_at']);
+/**
+ * The `(primary, fallback)` label pair for a session-scoped frontmatter KEY.
+ */
+function sessionLabelsForKey(key) {
+    if (!SESSION_SCOPED_KEYS.has(key))
+        return null;
+    const labels = exports.FRONTMATTER_BODY_SOURCE[key];
+    return { primary: labels[0], fallback: labels[1] ?? null };
+}
+/**
+ * The same pair, resolved from a BODY LABEL the caller named (`Stopped At`,
+ * `Stopped at`, `Paused At`). `null` for anything else.
+ *
+ * Deliberately does NOT accept a frontmatter key. An earlier cut resolved both
+ * spellings through one function and used it for the write, which made
+ * `state update stopped_at …` write the BODY line through the session writer —
+ * silently defeating the "frontmatter keys are not directly writable" contract
+ * this whole change exists to state, and reporting `updated: false` while having
+ * written. The write may only ever be reached by naming a body field.
+ */
+function sessionLabelsForBodyField(field) {
+    const key = frontmatterKeyForBodyField(field);
+    return key === null ? null : sessionLabelsForKey(key);
+}
+/**
+ * Would a session-scoped write actually land? Asks by attempting the real write
+ * with a throwaway value and seeing whether anything moved.
+ *
+ * Deliberately reuses the writer rather than re-deriving "where is the session
+ * section" — a separate scope check could disagree with the writer, and a
+ * presence check that disagrees with the write it guards is the whole bug class
+ * here. `stateReplaceFieldInSession` is replace-only and pure, so probing costs
+ * nothing and the result is discarded.
+ */
+function sessionSourceExists(body, labels) {
+    return (0, state_document_cjs_1.stateReplaceFieldInSession)(body, labels.primary, labels.fallback, '\u0000probe') !== body;
+}
+/**
+ * Own-property body-source lookup. `null` for a key with no body source (a
+ * disk/external/clock-derived key) and for anything not a frontmatter key.
+ */
+function getFrontmatterBodySource(field) {
+    if (!Object.prototype.hasOwnProperty.call(exports.FRONTMATTER_BODY_SOURCE, field))
+        return null;
+    return exports.FRONTMATTER_BODY_SOURCE[field];
+}
+/**
+ * Reverse lookup: the frontmatter key a body field feeds, or `null`.
+ * Lets a failed body-field update name the frontmatter key that still carries a
+ * value (#3699 case D), instead of reporting a bare absence.
+ */
+function frontmatterKeyForBodyField(bodyField) {
+    const wanted = bodyField.trim().toLowerCase();
+    for (const key of Object.keys(exports.FRONTMATTER_BODY_SOURCE)) {
+        if (exports.FRONTMATTER_BODY_SOURCE[key].some((f) => f.toLowerCase() === wanted))
+            return key;
+    }
+    return null;
+}
 /**
  * Own-property classification lookup. Returns `null` for unknown fields
  * (including inherited prototype methods like `toString`/`valueOf`).
@@ -82,103 +250,398 @@ function getFieldClassification(field) {
     return exports.FIELD_CLASSIFICATION[field];
 }
 /**
- * Pure, table-driven post-sync preservation. Mutates `postFm` in place to
- * mirror the pre-consolidation inline block (which also mutated in place) and
- * returns whether any field was restored.
+ * #3836: the single source of truth for "which frontmatter keys carry the
+ * `preserve-when-unchanged` policy" — read straight off `FIELD_CLASSIFICATION`
+ * rather than re-typed as a hand-maintained literal array at each consumer.
+ * `cmdStateJson` (`state.cts`) previously hardcoded a 6-field list that had
+ * already drifted from this table by one row (`last_activity_desc`, #3258) —
+ * exactly the "second table parallel to the first" shape ADR-3473 exists to
+ * remove. `progress`/`milestone`/`milestone_name` carry a different
+ * preservation policy (`preserve-always` / `preserve-if-placeholder`) and are
+ * naturally excluded by the filter, not by a separate exclusion list.
  */
-function applyStatePreservation(input) {
-    const { preFm, postFm, preFmSnapshot, resync } = input;
-    let mutated = false;
-    // Curated progress ratchet (#3242/#1446; closes the #1264 class by routing
-    // the policy through the table). Restored only when the table says preserve-
-    // always AND this transition is not re-deriving from disk (!resync). sync and
-    // the lifecycle transitions pass resync=true and recompute; patch/update and
-    // body-only writes pass resync=false and keep the curated counters.
-    const progressCls = getFieldClassification('progress');
-    if (progressCls !== null &&
-        progressCls.preservation === 'preserve-always' &&
-        !resync &&
-        preFm &&
-        preFm['progress']) {
-        // #2440: when the caller opts in (deriveProgressKeys), total_plans and
-        // total_phases always take the derived (post-sync) value even under !resync.
-        // This is used by cmdStatePlannedPhase where total_plans must correct upward
-        // after plans are added. For body-only writes (state.update/patch without
-        // the flag), the wholesale restore preserves everything as before — the
-        // #3242 Bug A protection stays fully in force.
-        if (input.deriveProgressKeys && postFm['progress']) {
-            const curated = preFm['progress'];
-            const derived = (postFm['progress'] ?? {});
-            const merged = { ...derived };
-            if (curated) {
-                // #2440: total_plans and total_phases always take the derived value.
-                // #2969: completed_plans and completed_phases take the derived value
-                // when it is GREATER than the curated value (gap-closure plans that
-                // completed after the plan count grew) — ratcheting UP only, never
-                // deriving downward (preserves the #3242 curated-progress protection
-                // for cases unrelated to plan-count growth, e.g. a deleted SUMMARY).
-                // percent also takes the derived value — the resync recomputed it from
-                // disk counts, and a stale curated percent would be incoherent against
-                // the ratcheted-up completed counts (e.g. 54/54 at 93%).
-                const ratchetUpKeys = new Set(['completed_plans', 'completed_phases']);
-                for (const [key, value] of Object.entries(curated)) {
-                    if (key === 'total_plans' || key === 'total_phases' || key === 'percent')
+function getPreserveWhenUnchangedFields() {
+    return Object.keys(exports.FIELD_CLASSIFICATION).filter((field) => exports.FIELD_CLASSIFICATION[field].preservation === 'preserve-when-unchanged');
+}
+/**
+ * Shared constructor body for `openStateTransaction` / `rebuildStateTransaction`
+ * (ADR-3473 §8.6 Decision 2/3). Validates `init.snapshot` and freezes the
+ * result so nothing downstream can mutate a transaction after construction
+ * (this is what makes the aliasing fix in `applyPreserveAlways`'s clone hold:
+ * the snapshot a caller passed in cannot be rewritten out from under it).
+ *
+ * `{}` and a null-prototype object are BOTH legal snapshots (Decision 2 / row
+ * 15 of the behavior table): `extractFrontmatter` returns `{}` for a document
+ * with no frontmatter or an unterminated one and never returns null or throws
+ * (`src/frontmatter.cts`), so `{}` is the honest snapshot of a real document —
+ * and `/gsd-health --repair`, which runs precisely when STATE.md is broken,
+ * depends on that staying legal. What is NOT legal is the snapshot being
+ * ABSENT (`null`/`undefined`/an array/a non-object): that is the caller
+ * forgetting to read the pre-write document at all, a construction failure,
+ * not a data question. Conflating "absent" with "empty" would turn the repair
+ * path's normal case into a hard throw.
+ */
+function createStateTransaction(kind, init, ctorName) {
+    if (init === null || typeof init !== 'object' || Array.isArray(init)) {
+        const err = new Error(`${ctorName}: expected an init object, got ${init === null ? 'null' : typeof init}. ` +
+            'Per ADR-3473 §8.6 / Decision 2, an absent init is a construction failure, distinct from ' +
+            'a legal empty snapshot ({}) — do not "fix" this by tolerating null.');
+        err.code = 'STATE_TRANSACTION_SNAPSHOT_REQUIRED';
+        err.constructorName = ctorName;
+        throw err;
+    }
+    const snapshot = init.snapshot;
+    if (snapshot === null || snapshot === undefined || typeof snapshot !== 'object' || Array.isArray(snapshot)) {
+        const err = new Error(`${ctorName}: init.snapshot is required and must be a non-array object (frontmatter map). ` +
+            `Per ADR-3473 §8.6 / Decision 2, an ABSENT snapshot is a construction failure — this is NOT ` +
+            'the same as a legal EMPTY snapshot ({}), which every executor accepts and simply finds ' +
+            'nothing to restore from (extractFrontmatter returns {} for a document with no parseable ' +
+            'frontmatter, and /gsd-health --repair depends on that staying legal). Pass {} explicitly ' +
+            'when the document truly has none; do not tolerate null/undefined here.');
+        err.code = 'STATE_TRANSACTION_SNAPSHOT_REQUIRED';
+        err.constructorName = ctorName;
+        throw err;
+    }
+    return Object.freeze({
+        kind,
+        snapshot,
+        resync: init.resync === true,
+        deriveProgressKeys: init.deriveProgressKeys === true,
+        bodyDeltas: init.bodyDeltas,
+        explicitProgressField: init.explicitProgressField === true,
+    });
+}
+/**
+ * ADR-3473 §8.6's `open()`: the default write-path transaction. Carries the
+ * pre-write snapshot and applies preservation (`applyStatePreservation` runs
+ * its full dispatch loop against it) — this is every STATE.md write EXCEPT
+ * the two sanctioned exceptions below.
+ */
+function openStateTransaction(init) {
+    return createStateTransaction('open', init, 'openStateTransaction');
+}
+/**
+ * ADR-3473 §8.6's `rebuild()`: the TYPED expression of ADR-3408 §8.3's closed
+ * list of sanctioned exceptions to the preservation pipeline. Exactly two
+ * callers may construct this: `cmdStateSync` (`state sync` re-derives
+ * frontmatter FROM the body per #905 — the body is authoritative and
+ * preservation would fight it) and `REGENERATE_STATE` (`/gsd-health --repair`'s
+ * factory reset — the whole point is to replace what's there). The snapshot
+ * is still carried (for §8.7's reporting) but `applyStatePreservation` skips
+ * its dispatch loop entirely for a `rebuild` transaction.
+ *
+ * This list is NOT debt to be paid down later — it is a closed, deliberate
+ * set. Adding a third caller is an amendment to ADR-3408 §8.3, not a call site
+ * convenience.
+ */
+function rebuildStateTransaction(init) {
+    return createStateTransaction('rebuild', init, 'rebuildStateTransaction');
+}
+/**
+ * ADR-3408 §8.2: an unenforced `preserve-when-unchanged` row throws. Both
+ * ends of this invariant are gsd-core's own source — a declared row the
+ * *caller code* forgot to wire via `bodyDeltas` — so it is a programming
+ * error, unreachable from any user document. The bright line, stated because
+ * conflating its two sides would be severe: a drifted, malformed, or
+ * unparseable user STATE.md NEVER reaches this throw (§8.5 governs that case
+ * with preserve-and-warn); this fires only when the *caller* omitted a
+ * `bodyDeltas` entry for a row the table itself declares. Getting this
+ * backwards turns every desynced project's `phase.complete` into a hard
+ * failure.
+ */
+function throwUnwiredRow(field) {
+    const err = new Error(`applyStatePreservation: preserve-when-unchanged row ${JSON.stringify(field)} reached the ` +
+        'executor with no wired ctx.bodyDeltas entry. This is an internal invariant violation (ADR-3408 ' +
+        '§8.2) — the caller (readModifyWriteStateMd) forgot to supply this field\'s body-source delta. ' +
+        'Add a bodyDeltas entry for this field per ADR-3408 §8.3, or remove the row from ' +
+        'FIELD_CLASSIFICATION if the field no longer needs this policy.');
+    err.code = 'STATE_PRESERVATION_UNWIRED_ROW';
+    err.field = field;
+    throw err;
+}
+/**
+ * Executor for `preservation: 'preserve-when-unchanged'` (ADR-3408 §8.1). The
+ * #1230 delta heuristic: restore the pre-write frontmatter snapshot when this
+ * write did not change the field's body source, and the snapshot is a real
+ * (non-empty-after-trim) curated value the derived value should not clobber.
+ *
+ * Every row carrying this policy — status, stopped_at, current_phase_name,
+ * current_phase, current_plan, paused_at, last_activity_desc — is honored by
+ * this ONE executor; `cls.guard` is the only field-specific variation (the
+ * closed vocabulary of ADR-3408 Decision 1).
+ *
+ * Exported (ADR-3408 §8.5 / D3) so `cmdStateJson` (state.cts) — a read-only
+ * path with no transform of its own — can route its stale-vs-fresh decision
+ * through the SAME executor the write path uses, rather than maintaining a
+ * third private copy of this policy. `cmdStateJson` calls this directly
+ * (not the full `applyStatePreservation` dispatch loop) so its read stays
+ * scoped to exactly the fields it has always governed and never touches
+ * `progress` or `milestone*`, which are different policies with their own
+ * read-path rules (`shouldPreserveExistingProgress`, `preserve-if-placeholder`).
+ */
+function applyPreserveWhenUnchanged(field, cls, ctx) {
+    // 1. A declared row with no wired delta is an internal invariant violation
+    // — throw (ADR-3408 §8.2). Never reached for a user-document defect: the
+    // production caller (readModifyWriteStateMd) wires every preserve-when-
+    // unchanged row unconditionally.
+    const delta = ctx.bodyDeltas ? ctx.bodyDeltas[field] : undefined;
+    if (!delta)
+        throwUnwiredRow(field);
+    // 2. Only a real, non-whitespace-only curated string is worth restoring
+    // (#3468: tightened from `.length > 0` to a trimmed check — a whitespace-
+    // only snapshot is not a real curated value).
+    const snapshot = ctx.snapshot[field];
+    if (typeof snapshot !== 'string' || snapshot.trim().length === 0)
+        return;
+    // 3. Closed-vocabulary guard: status's 'unknown' sentinel is never restored.
+    // Exact-match, case-sensitive — 'Unknown' is a real value and IS restored.
+    if (cls.guard === 'non-sentinel-unknown' && snapshot === 'unknown')
+        return;
+    // 4. The body source changed this write → the freshly-derived value wins.
+    if (delta.pre !== delta.post)
+        return;
+    // 5. Already correct → no-op (avoid a spurious `mutated=true`).
+    if (ctx.postFm[field] === snapshot)
+        return;
+    // 6. Restore.
+    ctx.postFm[field] = snapshot;
+    ctx.mutated = true;
+}
+/**
+ * The closed set of `progress` keys whose non-zero value means "a real
+ * measurement happened" (ADR-3473 §8.6 / #3756).
+ */
+const PROGRESS_TOTAL_KEYS = ['total_phases', 'total_plans'];
+/**
+ * Did this row's derived (or curated) value represent a REAL measurement?
+ *
+ * For a `progress-ratchet` row (today, only `progress`): an empty
+ * milestone-scoped scan is "nothing was measured", not "zero is done"
+ * (#3756, and the convention #3233 established — `computeProgressPercent`
+ * already returns `null` for an empty denominator). Only the TOTALS decide:
+ * `completed_*` being zero is normal for a real project, so it is
+ * deliberately excluded from this check. A non-object / absent / negative /
+ * non-numeric total is NOT a measurement, so it degrades TOWARD preservation,
+ * never toward deletion — `toFiniteNumber` (not a raw `=== 0`/`> 0` test)
+ * because frontmatter scalars arrive as STRINGS (`"0"`, not `0`).
+ *
+ * For any other row (no `progress-ratchet` strategy) the question is
+ * meaningless, so it answers `true` and behavior is unchanged — this
+ * function is only ever consulted from inside the `preserve-always` /
+ * `progress-ratchet` branch below.
+ */
+function scanMeasuredSomething(cls, value) {
+    if (cls.mergeStrategy !== 'progress-ratchet')
+        return true;
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const rec = value;
+    return PROGRESS_TOTAL_KEYS.some((k) => ((0, state_document_cjs_2.toFiniteNumber)(rec[k]) ?? 0) > 0);
+}
+/**
+ * Deep-clone a curated value before it re-enters `postFm` (ADR-3473 §8.6,
+ * "Defects fixed inline" / aliasing). `structuredClone` is a Node built-in;
+ * this repo takes no external deps for it. WHY a clone and not a reference
+ * assignment: the transaction's `snapshot` is now the SAME object §8.7's
+ * reporting will diff against. Assigning the nested curated object by
+ * reference would make `postFm.progress` alias that snapshot, so a later
+ * in-place mutation of `postFm` would silently rewrite the snapshot too, and
+ * the diff would report "no change" for a field that did change.
+ */
+function cloneCurated(value) {
+    return structuredClone(value);
+}
+/**
+ * Structural equality for a restored value vs. what `postFm` already held
+ * (ADR-3473 §8.6, "Defects fixed inline" / #948 no-op-write family).
+ * `JSON.stringify` compare when either side is an object (the `progress`
+ * block), `===` otherwise. WHY: `applyPreserveAlways` previously set
+ * `ctx.mutated = true` unconditionally at its tail, even when it restored a
+ * value identical to what was already there — driving a write that changes
+ * nothing but still bumps `last_updated` / restamps `state_head`.
+ * `applyPreserveWhenUnchanged` already guards this (its step 5); this brings
+ * the two executors into agreement.
+ */
+function preservedValuesEqual(a, b) {
+    if (typeof a === 'object' || typeof b === 'object') {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    return a === b;
+}
+/**
+ * Executor for `preservation: 'preserve-always'` (ADR-3408 §8.1). Only
+ * `progress` carries this policy today. Preserves #3242/#1446/#2440/#2969
+ * semantics byte-for-byte on every row the behavior table marks unchanged;
+ * ADR-3473 §8.6 fixes the #3756 defect (a resyncing write that measured
+ * nothing must not drop a real curated block) plus the two "Defects fixed
+ * inline" no-op-write / aliasing bugs.
+ */
+function applyPreserveAlways(field, cls, ctx) {
+    const curated = ctx.snapshot[field];
+    if (!curated)
+        return;
+    const derived = ctx.postFm[field];
+    const derivedMeasured = scanMeasuredSomething(cls, derived);
+    const curatedMeasured = scanMeasuredSomething(cls, curated);
+    // On a resyncing write the fresh derivation is authoritative — UNLESS it
+    // measured nothing while the curated block did (#3756), AND the caller did
+    // not explicitly name a progress-affecting field this write. The
+    // unmeasured-scan guard exists to stop an INCIDENTAL resync (e.g. `state
+    // add-decision`, whose `resync` defaults true for reasons that have
+    // nothing to do with `progress`) from dropping a real curated block when a
+    // milestone-scoped disk scan measures nothing (#3756's archived-milestone
+    // case). It must not also block a write the user pointed AT `progress` on
+    // purpose: `preserve-always`'s own contract is "never overwrite unless the
+    // caller explicitly names this field" (FIELD_CLASSIFICATION doc comment),
+    // and `state update Progress` / `state patch Progress=...` are exactly
+    // that naming — the resync they trigger must win even when the disk scan
+    // it also drives (e.g. because there are no phase dirs at all) reads as
+    // "unmeasured" (tests/frontmatter.test.cjs: "state.update \"Progress\"
+    // resyncs progress frontmatter from the updated body", pre-existing, #3242).
+    if (ctx.resync && (derivedMeasured || !curatedMeasured || ctx.explicitProgressField))
+        return;
+    let next;
+    if (cls.mergeStrategy === 'progress-ratchet' && ctx.deriveProgressKeys && derived && derivedMeasured) {
+        // #2440: total_plans and total_phases always take the derived (post-sync)
+        // value even under !resync. This is used by cmdStatePlannedPhase where
+        // total_plans must correct upward after plans are added. For body-only
+        // writes (state.update/patch without the flag), the wholesale restore
+        // below preserves everything as before — the #3242 Bug A protection
+        // stays fully in force.
+        const curatedRecord = curated;
+        const derivedRecord = (derived ?? {});
+        const merged = { ...derivedRecord };
+        if (curatedRecord) {
+            // #2440: total_plans and total_phases always take the derived value.
+            // #2969: completed_plans and completed_phases take the derived value
+            // when it is GREATER than the curated value (gap-closure plans that
+            // completed after the plan count grew) — ratcheting UP only, never
+            // deriving downward (preserves the #3242 curated-progress protection
+            // for cases unrelated to plan-count growth, e.g. a deleted SUMMARY).
+            // percent also takes the derived value — the resync recomputed it from
+            // disk counts, and a stale curated percent would be incoherent against
+            // the ratcheted-up completed counts (e.g. 54/54 at 93%).
+            const ratchetUpKeys = new Set(['completed_plans', 'completed_phases']);
+            for (const [key, value] of Object.entries(curatedRecord)) {
+                if (key === 'total_plans' || key === 'total_phases' || key === 'percent')
+                    continue;
+                if (ratchetUpKeys.has(key)) {
+                    const derivedNum = typeof derivedRecord[key] === 'number' ? derivedRecord[key] : -Infinity;
+                    const curatedNum = typeof value === 'number' ? value : -Infinity;
+                    // Take the derived value only when it ratchets up (strictly
+                    // greater — #2969's `>` not `>=`); else keep curated.
+                    if (derivedNum > curatedNum)
                         continue;
-                    if (ratchetUpKeys.has(key)) {
-                        const derivedNum = typeof derived[key] === 'number' ? derived[key] : -Infinity;
-                        const curatedNum = typeof value === 'number' ? value : -Infinity;
-                        // Take the derived value only when it ratchets up; else keep curated.
-                        if (derivedNum > curatedNum)
-                            continue;
-                        merged[key] = value;
-                    }
-                    else {
-                        merged[key] = value;
-                    }
+                    merged[key] = value;
+                }
+                else {
+                    merged[key] = value;
                 }
             }
-            postFm['progress'] = merged;
         }
-        else {
-            postFm['progress'] = preFm['progress'];
+        next = merged;
+    }
+    else {
+        next = cloneCurated(curated);
+    }
+    if (preservedValuesEqual(ctx.postFm[field], next))
+        return;
+    ctx.postFm[field] = next;
+    ctx.mutated = true;
+}
+/**
+ * Executor for `preservation: 'preserve-if-placeholder'` (ADR-3408 §8.1).
+ * `milestone` and `milestone_name` both carry this policy in the table, and
+ * both rows dispatch into this SAME executor body — no branch is selected by
+ * field name (ADR-3408 §8.1). The body always restores the name+version pair
+ * together (#948/#2135), ignoring which of the two rows triggered the call;
+ * this is deliberately safe because the executor is idempotent: whichever
+ * row fires first either performs the restore (after which the second row's
+ * call recomputes against already-restored state and finds nothing left to
+ * do) or finds no placeholder to restore (in which case the second row's
+ * call, seeing the same unchanged inputs, reaches the same conclusion). Two
+ * dispatches per write converge to the identical single-pass result, so the
+ * field argument itself is unused here — it exists only to satisfy the
+ * shared executor signature every policy branch in the dispatch loop shares.
+ */
+function applyPreserveIfPlaceholder(_field, _cls, ctx) {
+    const MILESTONE_PLACEHOLDER = 'milestone';
+    const derivedName = ctx.postFm['milestone_name'];
+    const derivedLooksLikeName = typeof derivedName === 'string'
+        && derivedName.length > 0
+        && derivedName !== MILESTONE_PLACEHOLDER
+        && !/^[\s—–:-]/.test(derivedName);
+    const snapshotName = ctx.snapshot['milestone_name'];
+    const snapshotNameIsReal = typeof snapshotName === 'string'
+        && snapshotName.length > 0
+        && snapshotName !== MILESTONE_PLACEHOLDER;
+    if (derivedLooksLikeName || !snapshotNameIsReal)
+        return;
+    if (ctx.postFm['milestone_name'] !== snapshotName) {
+        ctx.postFm['milestone_name'] = snapshotName;
+        ctx.mutated = true;
+    }
+    const snapshotVersion = ctx.snapshot['milestone'];
+    if (typeof snapshotVersion === 'string' && snapshotVersion.length > 0 &&
+        ctx.postFm['milestone'] !== snapshotVersion) {
+        ctx.postFm['milestone'] = snapshotVersion;
+        ctx.mutated = true;
+    }
+}
+/**
+ * Executor for `preservation: 'derive'`. Explicit no-op — the sync's
+ * freshly-derived value stands untouched. Naming this executor (rather than
+ * skipping `derive` rows by omission) is what makes ADR-3408 §8.2's throw
+ * decidable: "policy says do nothing" is now distinguishable from "nobody
+ * wired this", because every member of `FieldPreservation` reaches an
+ * executor.
+ */
+function applyDerive(_field, _cls, _ctx) {
+    // No-op by design — see docstring.
+}
+/**
+ * Pure, table-driven post-sync preservation (ADR-3408 §8.1). One loop over
+ * `FIELD_CLASSIFICATION`, dispatching on the row's `preservation` value —
+ * never on the field name. Mutates `postFm` in place to mirror the
+ * pre-#3468 inline block (which also mutated in place) and returns whether
+ * any field was restored.
+ */
+function applyStatePreservation(input) {
+    const { transaction } = input;
+    // A `rebuild()` transaction still carries the snapshot (§8.7's reporting
+    // needs it) but must not run preservation at all: `state sync` / `REGENERATE_STATE`
+    // exist to let the body / factory-reset win, and restoring curated values
+    // over that would re-lock exactly what the command was invoked to replace.
+    if (transaction.kind === 'rebuild') {
+        return { postFm: input.postFm, mutated: false };
+    }
+    const ctx = {
+        postFm: input.postFm,
+        snapshot: transaction.snapshot,
+        resync: transaction.resync,
+        deriveProgressKeys: transaction.deriveProgressKeys === true,
+        bodyDeltas: transaction.bodyDeltas,
+        mutated: false,
+        explicitProgressField: transaction.explicitProgressField === true,
+    };
+    for (const field of Object.keys(exports.FIELD_CLASSIFICATION)) {
+        const cls = getFieldClassification(field);
+        if (!cls)
+            continue;
+        if (cls.preservation === 'preserve-when-unchanged') {
+            applyPreserveWhenUnchanged(field, cls, ctx);
+        }
+        else if (cls.preservation === 'preserve-always') {
+            applyPreserveAlways(field, cls, ctx);
+        }
+        else if (cls.preservation === 'preserve-if-placeholder') {
+            applyPreserveIfPlaceholder(field, cls, ctx);
+        }
+        else if (cls.preservation === 'derive') {
+            applyDerive(field, cls, ctx);
         }
-        mutated = true;
-    }
-    // status — #1230 body-delta heuristic. Table: preserve-when-unchanged.
-    const statusCls = getFieldClassification('status');
-    if (statusCls !== null &&
-        statusCls.preservation === 'preserve-when-unchanged' &&
-        input.postBodyStatus === input.preBodyStatus &&
-        typeof preFmSnapshot['status'] === 'string' &&
-        preFmSnapshot['status'].length > 0 &&
-        preFmSnapshot['status'] !== 'unknown' &&
-        postFm['status'] !== preFmSnapshot['status']) {
-        postFm['status'] = preFmSnapshot['status'];
-        mutated = true;
-    }
-    // stopped_at — same #1230 body-delta heuristic. Table: preserve-when-unchanged.
-    const stoppedCls = getFieldClassification('stopped_at');
-    if (stoppedCls !== null &&
-        stoppedCls.preservation === 'preserve-when-unchanged' &&
-        input.postBodyStoppedAt === input.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;
-    }
-    // current_phase_name — curated (#1743/#1695). Table: preserve-always.
-    const phaseNameCls = getFieldClassification('current_phase_name');
-    if (phaseNameCls !== null &&
-        phaseNameCls.preservation === 'preserve-always' &&
-        input.postBodyPhaseSource === input.preBodyPhaseSource &&
-        typeof preFmSnapshot['current_phase_name'] === 'string' &&
-        preFmSnapshot['current_phase_name'].length > 0 &&
-        postFm['current_phase_name'] !== preFmSnapshot['current_phase_name']) {
-        postFm['current_phase_name'] = preFmSnapshot['current_phase_name'];
-        mutated = true;
-    }
-    return { postFm, mutated };
+    }
+    return { postFm: ctx.postFm, mutated: ctx.mutated };
 }
 // ----------------------------------------------------------------------------
 // Body section constants (ADR-1769 §6 — single writer after migration)
@@ -261,12 +724,14 @@ function beginPhaseCore(content, intent, deps) {
     // #1255: body-field replacements operate on body only (frontmatter stripped),
     // not on the full content. The YAML `status:` key matches `^Status:\s*`
     // before the body pipe-table row if full content is passed.
-    const existingFm = extractFrontmatter(content, deps.sourcePath);
-    const hasFrontmatter = Object.keys(existingFm).length > 0;
+    const { reassemble } = beginFrontmatterReassembly(content, deps.sourcePath);
+    // #3881 review, finding 5: `body` is deliberately a LITERAL `stripFrontmatter(content)`
+    // assignment here rather than the helper's own `body` (which the destructure above skips) —
+    // scripts/lint-state-write-path-drift.cjs's Axis 3 backward scan is a single-hop textual
+    // pattern match, not real dataflow, and only recognizes `body = stripFrontmatter(...)` written
+    // out at the call site. `stripFrontmatter` is pure and idempotent, so computing it here (in
+    // addition to the helper's own internal call) changes nothing observable.
     let body = stripFrontmatter(content);
-    const reassemble = (b) => hasFrontmatter
-        ? `---\n${reconstructFrontmatter(existingFm)}\n---\n\n${b}`
-        : b;
     const today = deps.clock.localToday();
     // Consult the field-classification table for the frontmatter keys this
     // transition touches (codex Phase 1 review: "table not consulted by
@@ -299,7 +764,7 @@ function beginPhaseCore(content, intent, deps) {
     // Extract from body (not full content) so the YAML `status:` key cannot
     // shadow the body Status field (#1255).
     const currentStatus = (0, state_document_cjs_1.stateExtractField)(body, 'Status') || '';
-    const isAlreadyExecuting = new RegExp(`Executing Phase\\s+${escapeRegex(String(intent.phaseNumber))}\\b`, 'i').test(currentStatus);
+    const isAlreadyExecuting = new RegExp(`Executing Phase\\s+${(0, pattern_cjs_1.escapeRegex)(String(intent.phaseNumber))}\\b`, 'i').test(currentStatus);
     // Status update (applies on both first-time and resume — Status is always refreshed).
     tryField('Status', `Executing Phase ${intent.phaseNumber}`);
     // Last Activity date — safe to refresh on resume (tracks when execute-phase ran).
@@ -507,6 +972,25 @@ function mutateCurrentPositionForAdvance(content, fields, statusDefaults, lastAc
         return content;
     let sectionBody = content.slice(span.start, span.end);
     let mutated = false;
+    // #3395: Phase is always replaced when a caller passes it — system-derived,
+    // not executor-authored (same rule as Plan below). plannedPhaseCore uses
+    // this so the transition that declares phase N planned also owns the `Phase:`
+    // line the frontmatter resync and `state json` re-derive current_phase from;
+    // before, the line survived stale from a previous phase and every
+    // body-derived consumer kept reading it (#948 class).
+    if (fields.phase) {
+        if (/^Phase:/m.test(sectionBody)) {
+            sectionBody = sectionBody.replace(/^Phase:.*$/m, `Phase: ${fields.phase}`);
+            mutated = true;
+        }
+        else {
+            const replaced = (0, state_document_cjs_1.stateReplaceField)(sectionBody, 'Phase', fields.phase);
+            if (replaced !== null) {
+                sectionBody = replaced;
+                mutated = true;
+            }
+        }
+    }
     if (fields.status) {
         const replaced = (0, state_document_cjs_1.stateReplaceFieldIfTemplate)(sectionBody, 'Status', statusDefaults, fields.status);
         if (replaced !== null && replaced !== sectionBody) {
@@ -564,12 +1048,35 @@ function advancePlanCore(content, deps) {
     // not on the full content. The YAML `status:` key matches `^Status:\s*`
     // before the body field if full content is passed (codex Phase 2 review:
     // HIGH blocking finding — same pattern beginPhaseCore already handles).
-    const existingFm = extractFrontmatter(content, deps.sourcePath);
-    const hasFrontmatter = Object.keys(existingFm).length > 0;
-    let body = stripFrontmatter(content);
-    const reassemble = (b) => hasFrontmatter
-        ? `---\n${reconstructFrontmatter(existingFm)}\n---\n\n${b}`
-        : b;
+    const { body: initialBody, reassemble } = beginFrontmatterReassembly(content, deps.sourcePath);
+    let body = initialBody;
+    // #3807: refuse a Current Position section carrying more than one `Phase:`
+    // entry BEFORE mutating. The plan fields below come from document-wide
+    // first-match extraction, so in a wave-log style section (one entry per
+    // completed wave) the FIRST entry's plan counter silently advanced — in the
+    // reporting incident, a hard-gated final plan 7→8 of 8 — while the entry
+    // the caller meant sat untouched below it, with advanced:true and no
+    // ambiguity signal. advance-plan now refuses before acting. Scoped via the
+    // #2956 canonical locator (stateCurrentPositionSlice — H2 or H3 heading,
+    // the same one cmdStateAdvancePlan's own milestone read uses); NO whole-body
+    // fallback — a legacy-format document with unrelated `Phase:` history lines
+    // elsewhere has no section to disambiguate and must keep its current
+    // behavior rather than be falsely refused.
+    const positionScope = (0, state_document_cjs_1.stateCurrentPositionSlice)(body);
+    if (positionScope !== null) {
+        const phaseCandidates = (positionScope.match(/^Phase:.*$/gm) || []);
+        if (phaseCandidates.length > 1) {
+            return {
+                content,
+                updated: [],
+                data: {
+                    error: true,
+                    reason: 'ambiguous_position_phase',
+                    phase_candidates: phaseCandidates.map((l) => l.trim()),
+                },
+            };
+        }
+    }
     // Parse plan number — legacy first, then compound.
     const legacyPlan = (0, state_document_cjs_1.stateExtractField)(content, 'Current Plan');
     const legacyTotal = (0, state_document_cjs_1.stateExtractField)(content, 'Total Plans in Phase');
@@ -676,6 +1183,7 @@ function completePhaseCore(content, intent, deps) {
         'current_plan',
         'last_activity',
         'last_activity_desc',
+        'stopped_at',
         'progress',
     ]) {
         const cls = getFieldClassification(fmKey);
@@ -686,12 +1194,8 @@ function completePhaseCore(content, intent, deps) {
     }
     // #1255: body-field replacements operate on body only (frontmatter stripped),
     // so the YAML `status:` / `current_phase:` keys cannot shadow the body fields.
-    const existingFm = extractFrontmatter(content, deps.sourcePath);
-    const hasFrontmatter = Object.keys(existingFm).length > 0;
-    let body = stripFrontmatter(content);
-    const reassemble = (b) => hasFrontmatter
-        ? `---\n${reconstructFrontmatter(existingFm)}\n---\n\n${b}`
-        : b;
+    const { body: initialBody, reassemble } = beginFrontmatterReassembly(content, deps.sourcePath);
+    let body = initialBody;
     // Current Phase — preserve the existing `of <total>` shape and the phase name
     // in parens (mirrors phase.cts:1675-1697 byte-for-behaviour).
     const phaseValue = intent.nextPhaseNum || intent.phaseNum;
@@ -720,8 +1224,8 @@ function completePhaseCore(content, intent, deps) {
         updated.push('Current Phase');
     }
     // Current Phase Name — only written when a next-phase display name is known
-    // (#1743/#1695: classified curated/preserve-always, so an absent name does
-    // NOT clear an existing curated value).
+    // (#1743/#1695: classified curated/preserve-when-unchanged, so an absent
+    // name does NOT clear an existing curated value).
     if (nextPhaseDisplayName) {
         const after = (0, state_document_cjs_1.stateReplaceField)(body, 'Current Phase Name', nextPhaseDisplayName);
         if (after) {
@@ -766,6 +1270,28 @@ function completePhaseCore(content, intent, deps) {
         body = ladAfter;
         updated.push('Last Activity Description');
     }
+    // Stopped At — #3374: write the continuity line this transition implies.
+    // The frontmatter `stopped_at` is a projection of this body line
+    // (source: 'body' in FIELD_CLASSIFICATION), and phase completion is exactly
+    // the event the line describes — leaving it stale made the post-sync harvest
+    // overwrite a fresher frontmatter value with pre-completion prose on every
+    // completion (#3374), and left the workflow's later prose refresh as a
+    // divergence source. Session-SCOPED replace (stateReplaceFieldInSession):
+    // the harvest reads only the session section, so the write must target the
+    // same scope — a whole-body replace let a decoy `**Stopped at:**` line in an
+    // unrelated section absorb the refresh. Replace-only (no insertion): a
+    // STATE.md with no session continuity line keeps its shape, and the
+    // unchanged body source then lets the preservation delta keep an existing
+    // frontmatter value. Last-phase wording reuses the ADR-2207 status phrase;
+    // milestone termination wording stays owned by milestoneCompleteCore.
+    const stoppedAtLine = intent.isLastPhase
+        ? `Phase ${intent.phaseNum} complete — all phases complete`
+        : `Phase ${intent.phaseNum} complete${intent.nextPhaseNum ? `, ready to plan Phase ${intent.nextPhaseNum}` : ''}`;
+    const stoppedAfter = (0, state_document_cjs_1.stateReplaceFieldInSession)(body, 'Stopped At', 'Stopped at', stoppedAtLine);
+    if (stoppedAfter !== body) {
+        body = stoppedAfter;
+        updated.push('Stopped At');
+    }
     // Progress block — re-derive completed/total phases from the roadmap when
     // available (milestone-wide source of truth), then recompute the percent.
     // Only runs when a Completed Phases field exists (the existing guard).
@@ -821,7 +1347,10 @@ function completePhaseCore(content, intent, deps) {
  * per-phase body fields after plan-phase runs: Status (template-aware — only
  * replaces handler-generated values, preserving executor-authored ones),
  * Total Plans in Phase, Last Activity (template-aware), Last Activity
- * Description, and the ## Current Position section. The adapter wraps this in
+ * Description, and the ## Current Position section — including its `Phase:`
+ * line, which this transition owns (#3395: the line is the body source
+ * `current_phase` re-derives from, so it must not survive stale from a
+ * previous phase). The adapter wraps this in
  * `readModifyWriteStateMd({ resync: false })` so the milestone-wide progress.*
  * frontmatter is NOT re-derived from a half-planned disk snapshot (#500 RC1).
  *
@@ -840,12 +1369,8 @@ function plannedPhaseCore(content, intent, deps) {
         }
     }
     // #1255: body-field replacements operate on body only.
-    const existingFm = extractFrontmatter(content, deps.sourcePath);
-    const hasFrontmatter = Object.keys(existingFm).length > 0;
-    let body = stripFrontmatter(content);
-    const reassemble = (b) => hasFrontmatter
-        ? `---\n${reconstructFrontmatter(existingFm)}\n---\n\n${b}`
-        : b;
+    const { existingFm, hasFrontmatter, body: initialBody, reassemble } = beginFrontmatterReassembly(content, deps.sourcePath);
+    let body = initialBody;
     const statusDefaults = state_document_cjs_2.KNOWN_TEMPLATE_DEFAULTS['Status'];
     const lastActivityDefaults = state_document_cjs_2.KNOWN_TEMPLATE_DEFAULTS['Last Activity'];
     // Status — template-aware (preserve executor-authored values).
@@ -874,9 +1399,20 @@ function plannedPhaseCore(content, intent, deps) {
         body = ladResult;
         updated.push('Last Activity Description');
     }
-    // ## Current Position section — Status + Last activity (template-aware).
+    // ## Current Position section — Phase + Status + Last activity.
+    // #3395: plannedPhaseCore owns the `Phase:` line for the same reason
+    // beginPhaseCore/completePhaseCore do — it is the body source the frontmatter
+    // resync and `state json` re-derive `current_phase` from. Before, a stale
+    // line from a previous phase survived this transition and every
+    // body-derived consumer kept reading it (the write path was already
+    // protected by the #3258 preserve-when-unchanged row; the source itself was
+    // never refreshed). The label mirrors beginPhaseCore's `N (Name) — EXECUTING`
+    // convention with this transition's status vocabulary ("Ready to execute").
+    // Phase is system-derived, always replaced (Knuth invariant does not apply);
+    // Status / Last activity stay template-aware.
     const beforePos = body;
     body = mutateCurrentPositionForAdvance(body, {
+        phase: `${intent.phaseNumber}${intent.phaseName ? ` (${intent.phaseName})` : ''} — READY TO EXECUTE`,
         status: 'Ready to execute',
         lastActivity: `${today} — Phase ${intent.phaseNumber} planning complete`,
     }, statusDefaults, lastActivityDefaults);
@@ -911,10 +1447,11 @@ function plannedPhaseCore(content, intent, deps) {
  * preserved.
  *
  * This is a destructive reset intent: it intentionally overwrites the curated
- * `progress` / `current_phase_name` fields (classified preserve-always) because
- * a new milestone starts from zero. That is the intent's contract, not a
- * violation of the field-classification table — the table governs the steady-
- * state RMW transitions; a milestone boundary is an explicit reset.
+ * `progress` (preserve-always) / `current_phase_name` (preserve-when-unchanged)
+ * fields because a new milestone starts from zero. That is the intent's
+ * contract, not a violation of the field-classification table — the table
+ * governs the steady-state RMW transitions; a milestone boundary is an
+ * explicit reset.
  *
  * The adapter wraps this in `acquireStateLock` + `platformWriteSync` (NOT
  * `readModifyWriteStateMd`) because milestoneSwitch rebuilds frontmatter
@@ -1076,12 +1613,8 @@ function milestoneCompleteCore(content, intent, deps) {
         }
     }
     // #1255: body-field replacements operate on body only.
-    const existingFm = extractFrontmatter(content, deps.sourcePath);
-    const hasFrontmatter = Object.keys(existingFm).length > 0;
-    let body = stripFrontmatter(content);
-    const reassemble = (b) => hasFrontmatter
-        ? `---\n${reconstructFrontmatter(existingFm)}\n---\n\n${b}`
-        : b;
+    const { body: initialBody, reassemble } = beginFrontmatterReassembly(content, deps.sourcePath);
+    let body = initialBody;
     // Status — `<version> milestone complete`.
     const statusAfter = (0, state_document_cjs_1.stateReplaceFieldWithFallback)(body, 'Status', null, `${version} milestone complete`);
     if (statusAfter !== body) {
@@ -1132,13 +1665,49 @@ function milestoneCompleteCore(content, intent, deps) {
  * Apply a `patch` transition to STATE.md content.
  *
  * Migrates `cmdStatePatch` (state.cts) onto the substrate. Applies each
- * caller-supplied `{field: value}` pair via `stateReplaceField` over the full
- * content (body + frontmatter — patch can target either), tracking which fields
- * were updated vs. not found.
+ * caller-supplied `{field: value}` pair, resolved BODY-FIRST:
+ *
+ * - A key that resolves against the STRIPPED body (via `stateReplaceField`,
+ *   case-insensitive on the field name) is applied there and reported
+ *   `updated` — this is the legitimate, documented case (display-cased body
+ *   fields — Status, Current Plan, Phase — which are never frontmatter
+ *   keys). It wins deterministically even when the same key also happens to
+ *   exist as a parsed frontmatter key (e.g. `status` matches both the
+ *   frontmatter key and a `Status:` body line) — frontmatter is inert for
+ *   that key.
+ * - Only when the body has no match is the key checked against parsed
+ *   frontmatter (determined structurally, never by a naming heuristic), and
+ *   routed through the seam: `FIELD_CLASSIFICATION` governs it. A CLASSIFIED
+ *   key (has a row, e.g. `current_phase`, `current_phase_name`) is NOT
+ *   writable by an arbitrary patch — policy owns it — and is reported
+ *   `failed`. An UNCLASSIFIED key (no row, e.g. a custom `risk_level`) is a
+ *   pass-through per Phase 1 behavior-table row 19 ("field absent from
+ *   FIELD_CLASSIFICATION → untouched pass-through"): it is applied directly
+ *   to the frontmatter object before reassembly and reported `updated`.
+ * - A key matching neither the body nor the frontmatter is reported `failed`.
+ *
+ * ADR-3408 §8.3(b): this used to run `stateReplaceField` over the FULL
+ * document (body + frontmatter), which — because `field` is an arbitrary,
+ * caller-supplied string, unlike every other `stateReplaceField` call site in
+ * this file, which passes a fixed Title-Case string literal that can never
+ * collide with a lowercase/snake_case YAML key — let a frontmatter-shaped
+ * patch key (e.g. `status`, `current_phase`) match and rewrite the YAML
+ * frontmatter block directly via `stateReplaceField`'s case-insensitive
+ * `^field:` line pattern, entirely outside `FIELD_CLASSIFICATION` and the
+ * write-seam preservation policy: a second, undeclared writer. The fix is
+ * that a CLASSIFIED frontmatter key no longer writes outside the declared
+ * policy table — not that every frontmatter-shaped key stops working.
+ * `.gsd/phase/refactor-3469-one-write-seam/40-design.md` row 9 requires
+ * frontmatter changes to route through the seam (still work, governed by
+ * FIELD_CLASSIFICATION), not to stop working outright. Body-shaped keys
+ * (`Status`, `Current Plan`, `Phase`, ...) are the LEGITIMATE case and are
+ * unaffected — they were always matched against the body text, and still are.
  *
  * The curated-field preservation that fixes #1743/#1695 is NOT in this core —
- * it lives in `readModifyWriteStateMd`'s post-sync delta (table-driven via
- * `getFieldClassification('current_phase_name').preservation === 'preserve-always'`).
+ * it lives in the write seam's post-sync delta (table-driven via
+ * `current_phase_name`'s `preserve-when-unchanged` row, ADR-3408 §8.1 —
+ * reclassified from `preserve-always` in #3468 to match its long-standing,
+ * delta-gated behavior).
  * `patch` consulting the table "refuses to overwrite" curated fields implicitly:
  * when the patch does not change a curated field's body source line, the
  * existing frontmatter value wins over the sync re-derivation. The adapter
@@ -1147,19 +1716,59 @@ function milestoneCompleteCore(content, intent, deps) {
  * `data.updated` / `data.failed` mirror the pre-migration CLI output shape.
  */
 function patchCore(content, intent) {
+    const { existingFm, hasFrontmatter, fmPrefix, unparseableFm } = beginFrontmatterReassembly(content);
+    // #3881 review, finding 5: see beginPhaseCore's identical comment above — `body` stays a
+    // literal `stripFrontmatter(content)` assignment here for scripts/lint-state-write-path-drift.cjs's
+    // Axis 3 single-hop backward scan.
+    let body = stripFrontmatter(content);
+    const fm = { ...existingFm };
     const updated = [];
     const failed = [];
-    let result = content;
     for (const [field, value] of Object.entries(intent.patches)) {
-        const replaced = (0, state_document_cjs_1.stateReplaceField)(result, field, value);
+        // Body-first: a key that resolves against a body field is the
+        // legitimate, documented case (display-cased body fields — Status,
+        // Current Plan, Phase — are never frontmatter keys) and wins
+        // deterministically even when the same key also happens to exist as a
+        // frontmatter key (case-insensitively, via stateReplaceField's
+        // `^field:` pattern — e.g. `status` matching both the frontmatter key
+        // and a `Status:` body line). Frontmatter is only consulted when the
+        // body has no match for this key.
+        const replaced = (0, state_document_cjs_1.stateReplaceField)(body, field, value);
         if (replaced !== null) {
-            result = replaced;
+            body = replaced;
             updated.push(field);
+            continue;
         }
-        else {
-            failed.push(field);
+        if (Object.prototype.hasOwnProperty.call(existingFm, field)) {
+            // Frontmatter-shaped key: route through the seam. A classified field
+            // is policy-owned — a raw patch may not bypass it. An unclassified
+            // field is an untouched pass-through (behavior-table row 19).
+            if (getFieldClassification(field) !== null) {
+                failed.push(field);
+            }
+            else {
+                fm[field] = value;
+                updated.push(field);
+            }
+            continue;
         }
-    }
+        failed.push(field);
+    }
+    if (updated.length === 0) {
+        // No field matched — return `content` VERBATIM (mirrors `updateCore`'s
+        // null-result branch): reassembling via stripFrontmatter/
+        // reconstructFrontmatter even when nothing changed can round-trip the
+        // frontmatter block to different bytes than the original (key order,
+        // formatting), which would falsely defeat `readModifyWriteStateMd`'s
+        // #948 no-op write guard for every patch that updates nothing, not just
+        // a frontmatter-shaped one.
+        return { content, updated, data: { updated, failed } };
+    }
+    const result = hasFrontmatter
+        ? `---\n${reconstructFrontmatter(fm)}\n---\n\n${body}`
+        : unparseableFm
+            ? `${fmPrefix}${body}`
+            : body;
     return { content: result, updated, data: { updated, failed } };
 }
 // ----------------------------------------------------------------------------
@@ -1174,16 +1783,77 @@ function patchCore(content, intent) {
  * Mirrors the pre-migration body-strip/reassemble contract.
  */
 function updateCore(content, intent) {
-    const existingFm = extractFrontmatter(content);
-    const hasFrontmatter = Object.keys(existingFm).length > 0;
+    const { existingFm, hasFrontmatter, reassemble } = beginFrontmatterReassembly(content);
+    // #3881 review, finding 5: see beginPhaseCore's identical comment above — `body` stays a
+    // literal `stripFrontmatter(content)` assignment here for scripts/lint-state-write-path-drift.cjs's
+    // Axis 3 single-hop backward scan.
     const body = stripFrontmatter(content);
-    const result = (0, state_document_cjs_1.stateReplaceField)(body, intent.field, intent.value);
+    // #3699 review: session-scoped fields are written through the session-scoped
+    // writer. A whole-body `stateReplaceField` matches the FIRST occurrence
+    // anywhere, so with no `Stopped At:` line in `## Session` but a stale one in
+    // `## Session Continuity Archive`, `state update "Stopped At" …` reported
+    // `updated: true` while rewriting the ARCHIVE line and leaving both the session
+    // section and the `stopped_at` frontmatter key untouched — a silent corruption
+    // of a historical record reported as success. #3374 already established this
+    // rule for the other writer; this one had not adopted it.
+    const sessionWriteLabels = sessionLabelsForBodyField(intent.field);
+    let result;
+    if (sessionWriteLabels) {
+        // Replace-only by contract: unchanged content means the field is not in the
+        // session section, which is a miss, not a write.
+        const replaced = (0, state_document_cjs_1.stateReplaceFieldInSession)(body, sessionWriteLabels.primary, sessionWriteLabels.fallback, intent.value);
+        result = replaced === body ? null : replaced;
+    }
+    else {
+        result = (0, state_document_cjs_1.stateReplaceField)(body, intent.field, intent.value);
+    }
     if (result === null) {
+        // #3699 case D — the frontmatter fallback.
+        //
+        // Normally frontmatter keys are NOT writable here: they are projections, and
+        // `buildStateFrontmatter` re-derives them from the body on every write, so a
+        // direct frontmatter write would be discarded. But when the body source line
+        // is absent entirely, there is nothing to derive FROM: the key's existing
+        // value survives on `preserve-when-unchanged`, and neither the frontmatter
+        // key nor the body field can be updated by any route. That document is
+        // unrepairable through `state update`, which is the gap this closes.
+        //
+        // Deliberately narrow — all three must hold:
+        //   (1) the field is a frontmatter key with a known body source,
+        //   (2) NO body source line exists, so the body route is genuinely unavailable
+        //       (this is what keeps case A, where the body route works, routing to the
+        //       body as before), and
+        //   (3) the frontmatter already carries the key, so this updates a value that
+        //       is really there rather than inventing one.
+        //
+        // The presence check in (2) is UNSCOPED on purpose, unlike the builder's
+        // `## Session` scoping for stopped_at/paused_at. The asymmetry is the safe
+        // direction: any `Stopped at:` line anywhere in the body — including one in an
+        // archive section — suppresses the fallback, so this never writes frontmatter
+        // while a body line the user could edit still exists.
+        const bodySource = getFrontmatterBodySource(intent.field);
+        const frontmatterCarriesKey = hasFrontmatter && Object.prototype.hasOwnProperty.call(existingFm, intent.field);
+        // The presence check asks the same question the WRITE asks, in the same
+        // scope. An earlier cut checked the whole body on the reasoning that any
+        // editable line should suppress the repair — but a line the reader never
+        // reads is not a source, and suppressing on it left the document
+        // unrepairable while pointing the user at a command that would rewrite the
+        // wrong line. Same scope for read, write and probe, or they disagree.
+        const sessionProbeLabels = sessionLabelsForKey(intent.field);
+        const bodySourceExists = sessionProbeLabels
+            ? sessionSourceExists(body, sessionProbeLabels)
+            : (bodySource ?? []).some((f) => (0, state_document_cjs_1.stateExtractField)(body, f) !== null);
+        if (bodySource && frontmatterCarriesKey && !bodySourceExists) {
+            const nextFm = { ...existingFm, [intent.field]: intent.value };
+            return {
+                content: `---\n${reconstructFrontmatter(nextFm)}\n---\n\n${body}`,
+                updated: [intent.field],
+                data: { updated: true, wroteFrontmatter: true },
+            };
+        }
         return { content, updated: [], data: { updated: false } };
     }
-    const reassembled = hasFrontmatter
-        ? `---\n${reconstructFrontmatter(existingFm)}\n---\n\n${result}`
-        : result;
+    const reassembled = reassemble(result);
     return { content: reassembled, updated: [intent.field], data: { updated: true } };
 }
 // Stop predicate for prune section slicing: a level-2 OR level-3 heading ends