@opengsd/gsd-core 1.18.0 → 1.20.0

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

@@ -29,10 +29,15 @@ const configLoaderMod = require("./config-loader.cjs");
 const { loadConfig } = configLoaderMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
-const { parsePhaseFromProse, PHASE_NUMBER_TOKEN_SOURCE, matchPhaseDirs, phaseKeyFromToken, phaseKeyFromDir, phaseHeadingPrefixSrcFor, PHASE_HEADING_BASELINE, isSentinelPhaseId, scopeToPhase, 
+const { parsePhaseFromProse, PHASE_NUMBER_TOKEN_SOURCE, phaseKeyFromToken, phaseKeyFromDir, phaseHeadingPrefixSrcFor, PHASE_HEADING_BASELINE, isSentinelPhaseId, scopeToPhase, 
 // #2761 M3: owns the bracket milestone intro and canonical pad2 spelling.
 bracketMilestoneIntroSrcFor, } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseIdDisplayMod = require("./phase-id-display.cjs");
+// #4304: phaseDisplayFor below renders through this adapter
+// instead of re-deriving the bracket numeric grammar locally.
+const { renderBracketPhaseDisplay } = phaseIdDisplayMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapParserMod = require("./roadmap-parser.cjs");
 // #3642: hasMilestoneSectioning no longer consumed here — its >=2 semantics answered sibling conflation, but this branch asks asserted-vs-section (>=1). It stays exported from roadmap-parser.cjs for its unit pins.
 const { getMilestoneInfo, extractCurrentMilestone, isMilestoneBoundedInRoadmap, hasAnyMilestoneSection, classifyMilestoneScalar } = roadmapParserMod;
@@ -55,6 +60,29 @@ const { extractFrontmatter, reconstructFrontmatter, stripFrontmatter, propagateC
 function isUnparseableFrontmatter(existingFm) {
     return existingFm[FRONTMATTER_UNPARSEABLE] === true;
 }
+/**
+ * Human-facing phase label for STATE.md descriptions. Identity-bearing fields
+ * such as Current Phase and the Current Position Phase row stay bare so their
+ * established readers remain byte-compatible; only descriptive text uses this
+ * renderer.
+ */
+function phaseDisplayFor(cwd, phaseNumber) {
+    if (resolvePhaseIdConvention(cwd) !== 'bracket')
+        return `Phase ${phaseNumber}`;
+    const config = loadConfig(cwd);
+    const project = typeof config['project_code'] === 'string' ? config['project_code'].trim() : '';
+    if (!project) {
+        error('phase_id_convention is "bracket" but project_code is missing in .planning/config.json');
+    }
+    const info = getMilestoneInfo(cwd);
+    const version = info.value?.version ?? '';
+    const display = renderBracketPhaseDisplay(version, phaseNumber, project);
+    if (display === null) {
+        error(`phase_id_convention is "bracket" but phase ${phaseNumber} cannot be rendered ` +
+            `(the active milestone ${JSON.stringify(version)} cannot be resolved, or the phase number is invalid)`);
+    }
+    return display;
+}
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const scanPhasePlans = require("./plan-scan.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -76,7 +104,7 @@ const planningScopeMod = require("./planning-scope.cjs");
 const { SCOPE } = planningScopeMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseLocatorMod = require("./phase-locator.cjs");
-const { listMilestonePhaseDirs } = phaseLocatorMod;
+const { phaseDirectoryOptions, listMilestonePhaseDirs, resolvePhaseDirectoryLookup, matchPhaseDirsForLookup } = phaseLocatorMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const stateTransitionMod = require("./state-transition.cjs");
 // #3873 (ADR-3473 §8.8): FRONTMATTER_KEY_TO_BODY_LABEL below is now a
@@ -92,6 +120,46 @@ const project_root_cjs_1 = require("./project-root.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const milestoneLockMod = require("./milestone-lock.cjs");
 const { transitionCore, applyStatePreservation, sliceCurrentPositionSection, stateReplaceProgressPercent, formatProgressMachineSegment } = stateTransitionMod;
+function replaceStateBodyField(content, statePath, field, value) {
+    const { body, reassemble } = stateTransitionMod.beginFrontmatterReassembly(content, statePath);
+    const replaced = (0, state_document_cjs_1.stateReplaceField)(body, field, value);
+    return replaced === null ? content : reassemble(replaced);
+}
+/**
+ * Rewrite a handler-authored field inside Current Position only when it still
+ * carries the exact value the transition just emitted. The equality guard
+ * preserves executor-authored prose under the transition module's Knuth rule.
+ */
+function replaceCurrentPositionFieldValue(content, statePath, field, expected, value) {
+    const { body, reassemble } = stateTransitionMod.beginFrontmatterReassembly(content, statePath);
+    const headings = (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(body);
+    const index = headings.findIndex((heading) => heading.level === 2 && /^current\s+position$/i.test(heading.text));
+    if (index === -1)
+        return content;
+    const heading = headings[index];
+    const lines = body.split('\n');
+    const headingLine = lines[heading.line - 1] ?? '';
+    const start = heading.offset + headingLine.length + 1;
+    let end = body.length;
+    for (let next = index + 1; next < headings.length; next++) {
+        if (headings[next].level < 2)
+            continue;
+        end = headings[next].offset;
+        if (end > 0 && body[end - 1] === '\n')
+            end -= 1;
+        if (end > 0 && body[end - 1] === '\r')
+            end -= 1;
+        end = Math.max(start, end);
+        break;
+    }
+    const section = body.slice(start, end);
+    if ((0, state_document_cjs_1.stateExtractField)(section, field) !== expected)
+        return content;
+    const replaced = (0, state_document_cjs_1.stateReplaceField)(section, field, value);
+    if (replaced === null)
+        return content;
+    return reassemble(body.slice(0, start) + replaced + body.slice(end));
+}
 // #3699: the frontmatter-key <-> body-field routing behind `state update`'s
 // failure explanation, and the classification table it falls back to.
 const { getFieldClassification, getFrontmatterBodySource, frontmatterKeyForBodyField } = stateTransitionMod;
@@ -374,6 +442,11 @@ function cmdStatePatch(cwd, patches, raw) {
         if (!fieldCheck.valid) {
             error(`state patch: ${fieldCheck.error}`);
         }
+        // #4998: as for `state update` — refused up front rather than listed
+        // under `failed` with no reason.
+        if (state_document_cjs_1.FIELD_LINE_BREAK_RE.test(`${patches[field]}`)) {
+            error(`state patch: the value for "${field}" must be a single line (no CR, LF, U+2028 or U+2029)`);
+        }
     }
     const statePath = planningPaths(cwd).state;
     try {
@@ -408,7 +481,20 @@ function cmdStatePatch(cwd, patches, raw) {
         // `applyStatePreservation` restored that this patch never named at all
         // (#3345's direction), a case the pre-#3471 version of this command never
         // covered.
-        const updated = reconcileReportedFields(statePath, preWriteState, precomputed.updated, divergedFields);
+        const reconciled = reconcileReportedFields(statePath, preWriteState, precomputed.updated, divergedFields, NO_SECTION_TARGETS, true);
+        // #4488, as in cmdStateUpdate: a field patchCore matched that already held
+        // the requested value changes no byte, so the reconcile above (which asks
+        // "what changed") drops it — alone (no snapshot at all) or beside a field
+        // that did change. It is updated when the persisted value is the requested
+        // one; a value the write pipeline discarded still differs and stays failed
+        // (trek-e review 5593733001, Minor 3).
+        const persisted = (0, shell_command_projection_cjs_1.platformReadSync)(statePath) || '';
+        const persistedFm = extractFrontmatter(persisted, statePath);
+        const persistedBody = stripFrontmatter(persisted);
+        const alreadyHeld = precomputed.updated.filter((field) => !reconciled.includes(field)
+            && !STATE_UPDATED_PROVENANCE_EXCLUSION.includes(field)
+            && readStateTarget(persistedFm, persistedBody, field, NO_SECTION_TARGETS, true)?.trim() === String(patches[field]).trim());
+        const updated = [...reconciled, ...alreadyHeld];
         const updatedSet = new Set(updated);
         const failed = Object.keys(patches).filter((field) => !updatedSet.has(field));
         const results = { updated, failed };
@@ -476,6 +562,11 @@ function cmdStateUpdate(cwd, field, value) {
     if (!fieldCheck.valid) {
         error(`state update: ${fieldCheck.error}`);
     }
+    // #4998: the field writers are single-line and refuse a line break, which
+    // the transition would otherwise report as "field not found".
+    if (state_document_cjs_1.FIELD_LINE_BREAK_RE.test(value)) {
+        error(`state update: the value for "${field}" must be a single line (no CR, LF, U+2028 or U+2029)`);
+    }
     const statePath = planningPaths(cwd).state;
     try {
         let updated = false;
@@ -527,7 +618,7 @@ function cmdStateUpdate(cwd, field, value) {
         // restored during this write that this command never touched at all
         // (#3345's direction) — reported separately from `updated` because this
         // command's contract is a single-field boolean, not a per-field array.
-        const reconciled = reconcileReportedFields(statePath, preWriteState, updated ? [field] : [], divergedFields);
+        const reconciled = reconcileReportedFields(statePath, preWriteState, updated ? [field] : [], divergedFields, NO_SECTION_TARGETS, true);
         // #4488: `updateCore` itself already told us whether it matched the field
         // (`updated`, captured above `readModifyWriteStateMd` runs it) — that is a
         // real signal, not a guess. `reconcileReportedFields` answers a DIFFERENT
@@ -711,17 +802,19 @@ function unsummarizedPlansForPositionPhase(cwd, positionPhase) {
     // as a real answer. This is a lookup of ONE phase token STATE.md names, not
     // a milestone enumeration, so the unscoped retry is in-contract.
     const convention = resolvePhaseIdConvention(cwd);
+    const lookup = resolvePhaseDirectoryLookup(cwd, positionPhase);
     const windowed = listMilestonePhaseDirs(phasesDir, { cwd, phaseIdConvention: convention });
     const candidateDirs = windowed.scope === SCOPE.COMPLETE ? windowed.value : [];
     // Canonical phase-token → directory matching (phase-id owner, #2562): both
     // sides of the comparison derived by the same function, never a local regex.
-    const { matches } = matchPhaseDirs(candidateDirs, positionPhase, convention);
+    const directoryContext = phaseDirectoryOptions(cwd);
+    const { matches } = matchPhaseDirsForLookup(candidateDirs, lookup, undefined, directoryContext);
     if (matches.length > 0)
         return scanOutstanding(phasesDir, matches[0]);
     const unscoped = listMilestonePhaseDirs(phasesDir);
     if (unscoped.scope !== SCOPE.COMPLETE)
         return null;
-    const retry = matchPhaseDirs(unscoped.value, positionPhase, convention);
+    const retry = matchPhaseDirsForLookup(unscoped.value, lookup, undefined, directoryContext);
     if (retry.matches.length === 0)
         return null;
     return scanOutstanding(phasesDir, retry.matches[0]);
@@ -770,7 +863,7 @@ function cmdStateAdvancePlan(cwd, raw) {
         // silently absorbed.
         const body = stripFrontmatter(content);
         const positionScope = matchCurrentPositionSection(body) ?? body;
-        const positionPhase = parseProsePhaseField((0, state_document_cjs_1.stateExtractField)(positionScope, 'Phase')).phase;
+        const positionPhase = parseProsePhaseField((0, state_document_cjs_1.stateExtractField)(positionScope, 'Phase'), resolvePhaseIdConvention(cwd), phaseDirectoryOptions(cwd)).phase;
         // #4093: a Current Position section with ZERO labeled fields has no
         // `Phase:` line either; frontmatter `current_phase` is the documented
         // survivor of body drift (the reporter's document still carried it, and
@@ -1283,7 +1376,7 @@ function cmdStateAddDecision(cwd, options, raw) {
     if (!phaseId) {
         const rawState = node_fs_1.default.readFileSync(statePath, 'utf-8');
         const fm = extractFrontmatter(rawState, statePath);
-        phaseId = resolveCurrentPhaseId(fm, stripFrontmatter(rawState)) ?? undefined;
+        phaseId = resolveCurrentPhaseId(fm, stripFrontmatter(rawState), resolvePhaseIdConvention(cwd), phaseDirectoryOptions(cwd)) ?? undefined;
     }
     const entry = `- [Phase ${phaseId || '?'}]: ${summaryText}${rationaleText ? ` — ${rationaleText}` : ''}`;
     let _added = false;
@@ -1412,8 +1505,14 @@ function cmdStateAddRoadmapEvolution(cwd, options, raw) {
     // Flatten line breaks so the entry is always a single Markdown bullet. The
     // dedupe + rendering contract is line-oriented; a multiline --note-file would
     // otherwise spill continuation lines outside the bullet and defeat dedupe.
-    // Internal spacing (e.g. dollar columns) is preserved.
-    const flatNote = noteText.replace(/\s*[\r\n]+\s*/g, ' ').trim();
+    // Internal spacing (e.g. dollar columns) is preserved. #4998: every
+    // FIELD_LINE_BREAK_RE character, so a U+2028/U+2029 cannot survive into the
+    // bullet and start a forged `**Field:**` line for the `m`-flag readers.
+    // Split and trimmed rather than one `\s*<break>+\s*` replace, which
+    // backtracks quadratically over a long whitespace run with no break in it
+    // (trek-e review 5608265301, Nit 5); the result is the same.
+    const flatNote = noteText.split(new RegExp(`${state_document_cjs_1.FIELD_LINE_BREAK_RE.source}+`))
+        .map((piece) => piece.trim()).filter(Boolean).join(' ');
     const actionText = (action && action.trim()) || 'changed';
     const afterText = after && after.trim() ? ` after Phase ${after.trim()}` : '';
     const urgentText = urgent ? ' (URGENT)' : '';
@@ -1428,7 +1527,7 @@ function cmdStateAddRoadmapEvolution(cwd, options, raw) {
     if (!phaseId) {
         const rawState = node_fs_1.default.readFileSync(statePath, 'utf-8');
         const fm = extractFrontmatter(rawState, statePath);
-        phaseId = resolveCurrentPhaseId(fm, stripFrontmatter(rawState)) ?? undefined;
+        phaseId = resolveCurrentPhaseId(fm, stripFrontmatter(rawState), resolvePhaseIdConvention(cwd), phaseDirectoryOptions(cwd)) ?? undefined;
     }
     const entry = `- Phase ${phaseId || '?'} ${actionText}${afterText}: ${flatNote}${urgentText}`;
     let duplicate = false;
@@ -1598,6 +1697,19 @@ function cmdStateResolveBlocker(cwd, text, raw) {
         declineNoOp(raw, 'resolved', `no blocker matching ${text} found in the Blockers section`, `state resolve-blocker skipped — no blocker matching ${formatDiagnosticToken(text)} found in the Blockers section.`);
     }
 }
+/**
+ * #4998 review (trek-e 5608265301, Minor 2): at most this many characters of a
+ * wrapped value's continuation are echoed back — it is STATE.md text, and its
+ * length is whatever the file holds.
+ */
+const SKIPPED_CONTINUATION_MAX_CHARS = 200;
+function boundedContinuation(text) {
+    if (text.length <= SKIPPED_CONTINUATION_MAX_CHARS)
+        return text;
+    // Never end on half a surrogate pair.
+    const end = /[\uD800-\uDBFF]/.test(text[SKIPPED_CONTINUATION_MAX_CHARS - 1]) ? SKIPPED_CONTINUATION_MAX_CHARS - 1 : SKIPPED_CONTINUATION_MAX_CHARS;
+    return `${text.slice(0, end)}…`;
+}
 function cmdStateRecordSession(cwd, options, raw) {
     // #4186: a bare invocation is a usage error, not a heartbeat write. The
     // pre-#4186 handler accepted zero arguments and still refreshed
@@ -1611,6 +1723,13 @@ function cmdStateRecordSession(cwd, options, raw) {
     if (!options.stopped_at && (options.resume_file === undefined || options.resume_file === null)) {
         error('stopped-at or resume-file required for state record-session');
     }
+    // #4998: every field this writes is single-line; a line break in a value
+    // would forge sibling lines (U+2028/U+2029 included — the readers' `m`-flag
+    // anchors match there too), so it is refused before anything is touched.
+    for (const [flag, value] of [['--stopped-at', options.stopped_at], ['--resume-file', options.resume_file]]) {
+        if (typeof value === 'string' && state_document_cjs_1.FIELD_LINE_BREAK_RE.test(value))
+            error(`state record-session: ${flag} must be a single line`);
+    }
     const statePath = planningPaths(cwd).state;
     if (!node_fs_1.default.existsSync(statePath)) {
         output({ error: 'STATE.md not found' }, raw, undefined);
@@ -1628,31 +1747,95 @@ function cmdStateRecordSession(cwd, options, raw) {
     // ADR-3473 §8.7 (#3872): caller-allocated out-param, filled with the
     // transaction's own pre-write snapshot + body by `applyPostSyncPreservation`.
     const preWriteState = {};
+    // #4998: fields left untouched because their existing value wraps onto the
+    // next line. The writers are single-line, so replacing such a field rewrote
+    // only its first line and orphaned the rest. Which lines continue a value and
+    // which are a separate note directly below it cannot be told apart, so the
+    // write leaves the field whole and says so rather than deleting either.
+    // Also (`line_separator`): a carried value the appended section leaves out.
+    const skippedFields = [];
+    const skipWrapped = (field, before, after) => {
+        const continuation = (0, state_document_cjs_1.editedLineContinuation)(before, after);
+        if (continuation === null)
+            return false;
+        skippedFields.push({ field, reason: 'wrapped_value', continuation: boundedContinuation(continuation) });
+        return true;
+    };
     readModifyWriteStateMd(statePath, (content) => {
+        // #4998 review (trek-e 5608265301, Major 1): every field written here is read
+        // from the session section when there is one (`## Session`, else `## Session
+        // Continuity` — matchSessionSection, state-snapshot, the frontmatter sync), so
+        // it is written there too. A line outside that section is not the field: a
+        // write that landed on it reported success while the synced value stayed
+        // stale. With no session section only `Stopped At` is read from the whole
+        // body (sessionFieldScope); `state-snapshot` reads Last session and Resume
+        // file from a session section alone, so with none they are not written in
+        // place but in the section appended below, as `state update`/`patch` refuse
+        // them (#4998 review, Minor 3). Located on the masked text (same offsets).
+        const readBodyWide = (fieldName) => fieldName.toLowerCase() === 'stopped at';
+        const sessionSection = () => {
+            const masked = (0, state_document_cjs_1.maskFencedLines)(content, { document: true });
+            return (0, markdown_sectionizer_cjs_1.collectSection)(masked, state_document_cjs_1.isSessionHeading, { levelBounded: true })
+                ?? (0, markdown_sectionizer_cjs_1.collectSection)(masked, state_document_cjs_1.isSessionContinuityHeading, { levelBounded: true });
+        };
+        const inSessionScope = (fieldName, write) => {
+            const section = sessionSection();
+            if (!section)
+                return readBodyWide(fieldName) ? (0, state_document_cjs_1.writeOutsideFences)(content, write, { document: true }) : null;
+            const body = (0, state_document_cjs_1.writeOutsideFences)(content.slice(section.bodyStart, section.bodyEnd), write);
+            return body === null ? null : (0, markdown_sectionizer_cjs_1.replaceSection)(content, section, body);
+        };
+        const sessionScopeText = (fieldName) => {
+            const masked = (0, state_document_cjs_1.maskFencedLines)(content, { document: true });
+            const section = sessionSection();
+            if (!section && !readBodyWide(fieldName))
+                return '';
+            return (0, state_document_cjs_1.readableBoldLabels)(section ? masked.slice(section.bodyStart, section.bodyEnd) : masked);
+        };
         // #4763 (1): read the pre-write session record. The capture mirrors the
-        // WRITER, not the snapshot reader: stateReplaceField replaces the FIRST
-        // case-insensitive label match anywhere in the document, so the capture is
-        // document-wide too — scoping it to ## Session would miss an archive-section
-        // line the writer actually displaced. Continuation lines join via
+        // WRITER: the first case-insensitive label match in the scope above, so a
+        // line the writer did not displace is not reported as displaced. Continuation lines join via
         // stateFieldContinuation (the sanctioned joiner — stateExtractField alone is
         // first-line-only), so a wrapped multi-line handoff is surfaced whole.
+        // #4998: a line inside a fenced block is an example, not a field — the
+        // writers below skip fences (`writeOutsideFences`), so the capture reads
+        // the same unfenced text they write.
+        // A `**Label**:` line the writer can replace is read too (readableBoldLabels).
         const capturePrior = (fieldName) => {
-            const first = (0, state_document_cjs_1.stateExtractField)(content, fieldName);
+            const visible = sessionScopeText(fieldName);
+            const first = (0, state_document_cjs_1.stateExtractField)(visible, fieldName);
             if (first === null)
                 return undefined;
-            const cont = (0, state_document_cjs_1.stateFieldContinuation)(content, fieldName);
+            const cont = (0, state_document_cjs_1.stateFieldContinuation)(visible, fieldName);
             return cont ? `${first}\n${cont}` : first;
         };
-        priorRecord.stoppedAt = capturePrior('Stopped At');
+        // #4998: with no body line, the frontmatter `stopped_at` is the only copy of
+        // the record, and the sync re-derives it from the line inserted below — a
+        // displacement like any other, so it is the prior record too.
+        const fmStoppedAt = extractFrontmatter(content)['stopped_at'];
+        priorRecord.stoppedAt = capturePrior('Stopped At')
+            ?? (typeof fmStoppedAt === 'string' && fmStoppedAt.trim() ? fmStoppedAt.trim() : undefined);
         priorRecord.resumeFile = capturePrior('Resume File');
+        // #4998: every in-place write skips fenced blocks, as the insertion
+        // below does — a fenced example line is never the occurrence replaced.
+        const replaceField = (fieldName, value) => inSessionScope(fieldName, (visible) => (0, state_document_cjs_1.stateReplaceField)(visible, fieldName, value));
+        // The template check reads the field the way the writer finds it: an
+        // authored `**Resume file**: plan.md` read as absent and was reset to None.
+        const replaceFieldIfTemplate = (fieldName, defaults, value) => {
+            const current = (0, state_document_cjs_1.stateExtractField)(sessionScopeText(fieldName), fieldName);
+            if (current !== null && current.trim() !== ''
+                && !defaults.some((d) => d.toLowerCase() === current.trim().toLowerCase()))
+                return content;
+            return inSessionScope(fieldName, (visible) => (0, state_document_cjs_1.stateReplaceFieldIfTemplate)(visible, fieldName, defaults, value)) ?? content;
+        };
         // Update Last session / Last Date
-        let result = (0, state_document_cjs_1.stateReplaceField)(content, 'Last session', now);
-        if (result) {
+        let result = replaceField('Last session', now);
+        if (result && !skipWrapped('Last session', content, result)) {
             content = result;
             updated.push('Last session');
         }
-        result = (0, state_document_cjs_1.stateReplaceField)(content, 'Last Date', now);
-        if (result) {
+        result = replaceField('Last Date', now);
+        if (result && !skipWrapped('Last Date', content, result)) {
             content = result;
             updated.push('Last Date');
         }
@@ -1667,13 +1850,13 @@ function cmdStateRecordSession(cwd, options, raw) {
         // section rewrite would reset an executor-authored resume file to None).
         let stoppedAtMatched = false;
         if (options.stopped_at) {
-            result = (0, state_document_cjs_1.stateReplaceField)(content, 'Stopped At', options.stopped_at);
+            result = replaceField('Stopped At', options.stopped_at);
             if (!result)
-                result = (0, state_document_cjs_1.stateReplaceField)(content, 'Stopped at', options.stopped_at);
+                result = replaceField('Stopped at', options.stopped_at);
             if (result) {
                 stoppedAtMatched = true;
-                if (result !== content) {
-                    content = result;
+                if (result !== content && !skipWrapped('Stopped At', content, result)) {
+                    content = (0, state_document_cjs_1.readableEditedBoldLabel)(content, result);
                     updated.push('Stopped At');
                 }
             }
@@ -1685,30 +1868,25 @@ function cmdStateRecordSession(cwd, options, raw) {
         const resumeFileDefaults = state_document_cjs_1.KNOWN_TEMPLATE_DEFAULTS['Resume File'];
         if (options.resume_file !== undefined && options.resume_file !== null) {
             // Caller explicitly passed a value — always honour it.
-            result = (0, state_document_cjs_1.stateReplaceField)(content, 'Resume File', options.resume_file);
+            result = replaceField('Resume File', options.resume_file);
             if (!result)
-                result = (0, state_document_cjs_1.stateReplaceField)(content, 'Resume file', options.resume_file);
-            if (result) {
-                content = result;
+                result = replaceField('Resume file', options.resume_file);
+            if (result && !skipWrapped('Resume File', content, result)) {
+                content = (0, state_document_cjs_1.readableEditedBoldLabel)(content, result);
                 updated.push('Resume File');
             }
         }
         else {
             // No explicit value — only set 'None' when existing value is also a known default
             // (i.e. not executor-authored).
-            const newRf = (0, state_document_cjs_1.stateReplaceFieldIfTemplate)(content, 'Resume File', resumeFileDefaults, 'None');
-            if (newRf !== content) {
+            let newRf = replaceFieldIfTemplate('Resume File', resumeFileDefaults, 'None');
+            // Try alternate capitalisation
+            if (newRf === content)
+                newRf = replaceFieldIfTemplate('Resume file', resumeFileDefaults, 'None');
+            if (newRf !== content && !skipWrapped('Resume File', content, newRf)) {
                 content = newRf;
                 updated.push('Resume File');
             }
-            else {
-                // Try alternate capitalisation
-                const newRfAlt = (0, state_document_cjs_1.stateReplaceFieldIfTemplate)(content, 'Resume file', resumeFileDefaults, 'None');
-                if (newRfAlt !== content) {
-                    content = newRfAlt;
-                    updated.push('Resume File');
-                }
-            }
         }
         // Bug #944: DWIM normalize/auto-create — when the caller supplied --stopped-at or
         // --resume-file but the body lacks the canonical labels (in-place replace
@@ -1735,8 +1913,12 @@ function cmdStateRecordSession(cwd, options, raw) {
         // identical value is already persisted on disk and must not trigger the
         // insertion rewrite below.
         const needsStoppedAt = options.stopped_at && !stoppedAtMatched;
-        const needsResumeFile = options.resume_file !== undefined && options.resume_file !== null && !updated.includes('Resume File');
-        const needsLastSession = !updated.includes('Last session') && !updated.includes('Last Date');
+        // #4998: a field skipped as wrapped is present, not missing.
+        const skipped = (field) => skippedFields.some((s) => s.field === field);
+        const needsResumeFile = options.resume_file !== undefined && options.resume_file !== null
+            && !updated.includes('Resume File') && !skipped('Resume File');
+        const needsLastSession = !updated.includes('Last session') && !updated.includes('Last Date')
+            && !skipped('Last session') && !skipped('Last Date');
         if (callerSuppliedValues && (needsStoppedAt || needsResumeFile || needsLastSession)) {
             const resumeValue = (options.resume_file !== undefined && options.resume_file !== null)
                 ? options.resume_file
@@ -1747,92 +1929,143 @@ function cmdStateRecordSession(cwd, options, raw) {
             // (workstream.cts, gsd2-import.cts, templates/state.md) instead emit
             // `## Session Continuity`. Treat each separately so we never append a
             // duplicate section alongside an existing one.
-            const existingCanonicalSession = /^## Session[ \t]*$/im.test(content);
-            const existingSessionContinuity = /^## Session Continuity[ \t]*$/im.test(content);
+            // #4998: a heading inside a fenced example is not a section. Detected
+            // with the locator the writers below and the readers use (#4998 review).
+            const headingScan = (0, state_document_cjs_1.maskFencedLines)(content, { document: true });
+            const existingCanonicalSession = (0, markdown_sectionizer_cjs_1.collectSection)(headingScan, state_document_cjs_1.isSessionHeading, { levelBounded: true }) !== null;
+            const existingSessionContinuity = (0, markdown_sectionizer_cjs_1.collectSection)(headingScan, state_document_cjs_1.isSessionContinuityHeading, { levelBounded: true }) !== null;
             // Track whether the chosen branch's rewrite actually matched. The detector
-            // regexes (existingCanonicalSession/existingSessionContinuity) are CRLF-
-            // tolerant ($ under /m treats \r as a line terminator); the writer regexes
-            // below must be too. If a writer regex silently fails to match (line-ending
+            // and the writer share one locator (CRLF-tolerant: the tokenizer strips
+            // a trailing \r). If the writer still fails to match (line-ending
             // mismatch, unexpected heading shape, ...), do NOT report success — the
             // caller would believe fields were persisted that were silently dropped
             // (#2450). The append branch always sets rewriteMatched=true (it always
             // mutates content).
             let rewriteMatched = false;
+            // `created` means a session section was added, as in record-metric and
+            // add-decision — not a field inserted into an existing one (#4998 review).
+            let sectionAppended = false;
+            // #4998: insert each missing field into `region`,
+            // in the section's own spelling and in template order (Last session →
+            // Stopped at → Resume file), beside the sibling it follows — a bold
+            // `**Stopped at:**` above plain `Last session:` lines is a line the
+            // template does not define. With no sibling present it goes right after
+            // the heading in bold, the pre-#4998 shape. Every existing line is kept.
+            // A heading at EOF with no line terminator gets one first, so its body
+            // exists to insert into rather than a field being glued onto it.
+            // The section is located on the masked text (same offsets): a fenced
+            // `## Session` example is not the section, and a ``` in a frontmatter
+            // block scalar does not hide the real one (Codex review round 2).
+            const insertIntoSection = (isTarget) => {
+                let section = (0, markdown_sectionizer_cjs_1.collectSection)((0, state_document_cjs_1.maskFencedLines)(content, { document: true }), isTarget, { levelBounded: true });
+                if (section && content[section.bodyStart - 1] !== '\n' && section.bodyStart >= content.length) {
+                    content += content.includes('\r\n') ? '\r\n' : '\n';
+                    section = (0, markdown_sectionizer_cjs_1.collectSection)((0, state_document_cjs_1.maskFencedLines)(content, { document: true }), isTarget, { levelBounded: true });
+                }
+                if (!section || content[section.bodyStart - 1] !== '\n')
+                    return;
+                const body = (0, state_document_cjs_1.insertMissingSessionFields)(content.slice(section.bodyStart, section.bodyEnd), [
+                    { label: 'Last session', needed: needsLastSession, value: now },
+                    { label: 'Stopped at', needed: !!needsStoppedAt, value: stoppedAtValue },
+                    { label: 'Resume file', needed: needsResumeFile, value: resumeValue },
+                ]);
+                content = (0, markdown_sectionizer_cjs_1.replaceSection)(content, section, body);
+                rewriteMatched = true;
+            };
             if (existingCanonicalSession) {
-                // Normalize in place: replace the ENTIRE BODY of the existing ## Session
-                // section (heading + all content up to the next ## heading or EOF) with
-                // canonical bold-label lines. The negative-lookahead per-line pattern
-                // `(?!^## )[\s\S]` consumes every line that doesn't start with "## ",
-                // which correctly stops at the next section boundary without consuming it.
-                // A trailing blank line is added so the next ## heading keeps its spacing.
-                //
-                // CRLF-tolerant (`\r?\n` after `[ \t]*`): the prior literal `\n` could not
-                // match a CRLF STATE.md (`---\r\n`), silently no-op'ing the replace while
-                // updated.push(...) reported success — #2450. The detector regex on the
-                // line above (`/^## Session[ \t]*$/im`) was already CRLF-tolerant, so the
-                // asymmetry armed the bug.
-                const canonicalReplacement = [
-                    '## Session',
-                    '',
-                    `**Last session:** ${now}`,
-                    `**Stopped at:** ${stoppedAtValue}`,
-                    `**Resume file:** ${resumeValue}`,
-                    '',
-                    '',
-                ].join('\n');
-                content = content.replace(/^(## Session[ \t]*\r?\n(?:(?!^## )[\s\S])*)/m, () => {
-                    rewriteMatched = true;
-                    return canonicalReplacement;
-                });
+                // #4998: insert the missing fields in place. This used to replace the
+                // whole section with three canonical lines, which deleted any wrapped
+                // value or note in it — and reset an authored Resume file to None.
+                insertIntoSection(state_document_cjs_1.isSessionHeading);
             }
             else if (existingSessionContinuity) {
                 // #1101: a `## Session Continuity` section already exists (bootstrap
                 // shape). Previously this fell through to the append branch and created
                 // a SECOND `## Session` block — a duplicate. Instead, insert only the
-                // canonical fields that are still missing, right after the heading,
+                // canonical fields that are still missing (#4998: beside their siblings),
                 // preserving the `## Session Continuity` heading and ALL existing lines
                 // (e.g. prose like "Next recommended action"). Fields already updated in
                 // place above (needs* false) are not re-inserted. A function replacement
                 // is used so `$`-bearing caller values are inserted literally (#3454).
                 //
-                // CRLF-tolerant (`\r?\n`): same #2450 fix as the canonical branch above.
-                const linesToInsert = [];
-                if (needsLastSession)
-                    linesToInsert.push(`**Last session:** ${now}`);
-                if (needsStoppedAt)
-                    linesToInsert.push(`**Stopped at:** ${stoppedAtValue}`);
-                if (needsResumeFile)
-                    linesToInsert.push(`**Resume file:** ${resumeValue}`);
-                if (linesToInsert.length > 0) {
-                    // Case-insensitive to match the `existingSessionContinuity` detection
-                    // above (#1101 review F3) — otherwise a lowercase heading would detect
-                    // but no-op the insert while still reporting the fields as updated.
-                    content = content.replace(/^(## Session Continuity[ \t]*\r?\n)/im, (_m, heading) => {
-                        rewriteMatched = true;
-                        return heading + linesToInsert.join('\n') + '\n';
-                    });
-                }
-                // No `else` branch: if linesToInsert.length === 0 the outer guard at
-                // :1144 (callerSuppliedValues && (needsStoppedAt || needsResumeFile
-                // || needsLastSession)) could not have fired, so this whole block is
-                // unreachable. Leaving `rewriteMatched = false` here is the fail-loud
-                // posture — a future change to the outer guard or needs* computation
-                // that makes this branch reachable will surface as a missing
-                // updated[] entry (silent recorded:false) rather than re-arming #2450.
+                // Heading match is case-insensitive and CRLF-tolerant like the
+                // `existingSessionContinuity` detection above (#1101 review F3, #2450):
+                // a detected heading the writer then misses would report fields as
+                // updated that were never written (`rewriteMatched` stays false).
+                insertIntoSection(state_document_cjs_1.isSessionContinuityHeading);
             }
             else {
                 // No session heading exists at all — append a new canonical section.
-                const scaffold = [
-                    '',
-                    '## Session',
-                    '',
-                    `**Last session:** ${now}`,
-                    `**Stopped at:** ${stoppedAtValue}`,
-                    `**Resume file:** ${resumeValue}`,
-                    '',
-                ].join('\n');
-                content = content.trimEnd() + '\n' + scaffold;
-                rewriteMatched = true;
+                // #4998: the appended section becomes the one the sync reads, so a
+                // field this call is not setting carries the value the sync reads
+                // today (a body line, a wrapped field's first line, a table row)
+                // rather than None or nothing — which dropped the frontmatter
+                // `stopped_at` and reset an authored Resume file. Later writes then
+                // land on these bold lines first. A field skipped above as wrapped
+                // carries its existing value too — Last session included — so a
+                // skipped field never comes back carrying the new value.
+                // Read from the body, as the sync does — never from frontmatter, and
+                // never from a fenced example.
+                const syncBody = (0, state_document_cjs_1.readableBoldLabels)((0, state_document_cjs_1.maskFencedLines)(stripFrontmatter(content)));
+                const carried = (fields, fallback) => {
+                    for (const field of fields) {
+                        const value = (0, state_document_cjs_1.stateExtractField)(syncBody, field);
+                        if (value !== null)
+                            return value;
+                    }
+                    return fallback;
+                };
+                const lastSessionValue = skipped('Last session') || skipped('Last Date')
+                    ? carried(['Last session', 'Last Date'], now)
+                    : now;
+                const scaffoldFields = [
+                    ['Last session', lastSessionValue],
+                    ['Stopped at', needsStoppedAt ? stoppedAtValue : carried(['Stopped At'], stoppedAtValue)],
+                    ['Resume file', needsResumeFile ? resumeValue : carried(['Resume File'], resumeValue)],
+                ];
+                // A document that ends inside an unclosed fence would swallow the
+                // appended section — nothing reads it there. Write nothing, and say so.
+                // The whole document is scanned on purpose: whether its tail is fenced
+                // depends on every delimiter before it (frontmatter excluded: YAML, not
+                // Markdown), and `scanFencedBlocks` reports
+                // an unclosed block only as its LAST record (the fence runs to EOF), so
+                // `closeLineIdx === -1` here means exactly "the tail is inside a fence".
+                if ((0, state_document_cjs_1.markdownFencedBlocks)(content.split('\n'), { document: true }).some((b) => b.closeLineIdx === -1)) {
+                    // Named only for a field this call writes (Last session always, the
+                    // others when passed) and not already written in place or skipped
+                    // for another reason (Codex review; trek-e review 5608265301, Minor 3).
+                    const fieldKey = (f) => (f === 'Last Date' ? 'last session' : f.toLowerCase());
+                    const requested = new Set(['last session']);
+                    if (options.stopped_at)
+                        requested.add('stopped at');
+                    if (options.resume_file !== undefined && options.resume_file !== null)
+                        requested.add('resume file');
+                    const settled = new Set([...updated, ...skippedFields.map((s) => s.field)].map(fieldKey));
+                    // A Stopped at already holding the value needs no write (Codex review).
+                    if (stoppedAtMatched)
+                        settled.add('stopped at');
+                    for (const [label] of scaffoldFields) {
+                        const key = fieldKey(label);
+                        if (requested.has(key) && !settled.has(key))
+                            skippedFields.push({ field: label, reason: 'unclosed_fence' });
+                    }
+                }
+                else {
+                    // A carried value holding a line separator (a hand-written table cell
+                    // can) would forge a line once written as a bold field: leave that
+                    // field out, and say so.
+                    const scaffoldLines = [];
+                    for (const [label, value] of scaffoldFields) {
+                        if (state_document_cjs_1.FIELD_LINE_BREAK_RE.test(value))
+                            skippedFields.push({ field: label, reason: 'line_separator' });
+                        else
+                            scaffoldLines.push(`**${label}:** ${value}`);
+                    }
+                    const scaffold = ['', '## Session', '', ...scaffoldLines, ''].join('\n');
+                    content = content.trimEnd() + '\n' + scaffold;
+                    rewriteMatched = true;
+                    sectionAppended = true;
+                }
             }
             // #2450 defensive invariant: only report sessionCreated/updated when the
             // chosen branch's rewrite actually mutated content. Unreachable when the
@@ -1848,7 +2081,7 @@ function cmdStateRecordSession(cwd, options, raw) {
             // same-line replace (CRLF-agnostic seam), so unconditional push is
             // correct. The class-defect防御 here is for the INSERT path only.
             if (rewriteMatched) {
-                sessionCreated = true;
+                sessionCreated = sectionAppended;
                 if (needsLastSession)
                     updated.push('Last session');
                 if (needsStoppedAt)
@@ -1863,22 +2096,48 @@ function cmdStateRecordSession(cwd, options, raw) {
     // bytes actually persisted (fix(#3351) generalized) and fold in any field
     // preservation restored that this transform never touched (#3345's
     // direction).
-    const reconciledUpdated = reconcileReportedFields(statePath, preWriteState, updated, divergedFields);
+    // #4998 review: read back where the fields were written — the session section.
+    const reconciledUpdated = reconcileReportedFields(statePath, preWriteState, updated, divergedFields, NO_SECTION_TARGETS, true);
+    // #4998: name every field left whole because its value wraps, and how to fix it.
+    const skippedRows = skippedFields;
+    const skippedDisclosure = skippedRows.map(({ field, reason, continuation }) => (reason === 'wrapped_value'
+        ? `state record-session left ${field} unchanged — its value continues onto the next line ` +
+            `(${formatDiagnosticToken(continuation ?? '')}), and a single-line write would leave that line behind. ` +
+            'Fold the value onto one line, or put a blank line before that line if it is a separate note, then re-run.'
+        : reason === 'line_separator'
+            ? `state record-session left ${field} out of the new ## Session section — its existing value holds a ` +
+                'line separator (U+2028/U+2029), which would split the line it is written on. Remove the separator, then re-run.'
+            : `state record-session did not write ${field} — STATE.md has no session section and ends inside an unclosed ` +
+                'code fence, which would swallow a new ## Session section. Close the fence, then re-run.'));
     if (reconciledUpdated.length > 0) {
         const result = { recorded: true, updated: reconciledUpdated };
         if (sessionCreated)
             result['created'] = true;
+        if (skippedRows.length > 0) {
+            result['skipped'] = skippedRows;
+            for (const line of skippedDisclosure)
+                process.stderr.write(`[gsd-tools] WARNING: ${line}\n`);
+        }
         // #4763 (1): surface any non-empty prior record the write displaced. Gated
         // on reconciledUpdated (the fields that actually persisted, post-#3957
         // reconcile) rather than the pre-reconciliation updated[]. Only fields with
         // real prior content differing from the caller's value count — same-value
-        // rewrites, the insert path (no prior label), and the #944 template-default
-        // DWIM (defaults match case-insensitively, so a case-variant 'none' →
-        // 'None' rewrite is normalization, not displacement) are excluded.
-        const isResumeTemplateDefault = priorRecord.resumeFile !== undefined
-            && state_document_cjs_1.KNOWN_TEMPLATE_DEFAULTS['Resume File'].some((d) => d.toLowerCase() === priorRecord.resumeFile?.toLowerCase());
+        // rewrites, the insert path with no prior record (no body label and, #4998,
+        // no frontmatter `stopped_at`), and the #944 template-default DWIM
+        // (defaults match case-insensitively, so a case-variant 'none' → 'None'
+        // rewrite is normalization, not displacement) are excluded.
+        // #4998: `None` is the same placeholder for Stopped At (the bootstrap
+        // writes it there too, body or frontmatter) — no record was displaced. Nor
+        // is the shipped template's whole-value `[...]` placeholder
+        // (`[Description of last completed action]`; #4998 review, Nit 7).
+        const isPlaceholder = (value) => value !== undefined
+            && (state_document_cjs_1.KNOWN_TEMPLATE_DEFAULTS['Resume File'].some((d) => d.toLowerCase() === value.toLowerCase())
+                || /^\[[^\]\n]*\]$/u.test(value.trim()));
+        const isResumeTemplateDefault = isPlaceholder(priorRecord.resumeFile);
+        const isStoppedAtPlaceholder = isPlaceholder(priorRecord.stoppedAt);
         const replacedRecord = {};
         if (reconciledUpdated.includes('Stopped At') && priorRecord.stoppedAt
+            && !isStoppedAtPlaceholder
             && priorRecord.stoppedAt !== options.stopped_at) {
             replacedRecord['Stopped At'] = priorRecord.stoppedAt;
         }
@@ -1891,6 +2150,10 @@ function cmdStateRecordSession(cwd, options, raw) {
             result['replacedRecord'] = replacedRecord;
         output(result, raw, 'true');
     }
+    else if (skippedRows.length > 0) {
+        // #4998: every field the call would have changed wraps — nothing written.
+        declineNoOp(raw, 'recorded', 'every session field to update was left unchanged — see skipped', skippedDisclosure.join('\n[gsd-tools] WARNING: '), { skipped: skippedRows });
+    }
     else if (updated.length === 0) {
         // Nothing was ever attempted — no --stopped-at/--resume-file supplied
         // and no existing Last session/Last Date/Stopped At/Resume File labels
@@ -1924,12 +2187,20 @@ function cmdStateRecordSession(cwd, options, raw) {
  * Returns the section body, or null.
  */
 function matchSessionSection(body) {
-    const isSession = (h) => h.level === 2 && h.text.trim().toLowerCase() === 'session';
-    const isSessionContinuity = (h) => h.level === 2 && h.text.trim().toLowerCase() === 'session continuity';
-    const section = (0, markdown_sectionizer_cjs_1.collectSection)(body, isSession, { levelBounded: true })
-        ?? (0, markdown_sectionizer_cjs_1.collectSection)(body, isSessionContinuity, { levelBounded: true });
+    const section = (0, markdown_sectionizer_cjs_1.collectSection)(body, state_document_cjs_1.isSessionHeading, { levelBounded: true })
+        ?? (0, markdown_sectionizer_cjs_1.collectSection)(body, state_document_cjs_1.isSessionContinuityHeading, { levelBounded: true });
     return section ? section.body : null;
 }
+/**
+ * #4998: where the session fields (Stopped At, Paused At) are read from — the
+ * session section, else the whole body — with fenced blocks blanked, because
+ * `state record-session` writes them outside fences (`writeOutsideFences`).
+ * A reader that still took a fenced example would sync it into frontmatter
+ * over the field the writer just wrote.
+ */
+function sessionFieldScope(body) {
+    return (0, state_document_cjs_1.maskFencedLines)(matchSessionSection(body) ?? body);
+}
 /**
  * Match the "Current Position" section body from a STATE.md body. #2956: this
  * is the Phase analogue of matchSessionSection. `Phase` canonically lives under
@@ -1995,26 +2266,27 @@ function preferNewerLastActivity(existingFm, derivedFm) {
         derivedFm['last_activity'] = exRaw;
     }
 }
-function parseProsePhaseField(value) {
+function parseProsePhaseField(value, convention, directoryContext) {
     // #2121 Phase 2 (#2125): delegate to the canonical anchored parser so this
     // module holds no independent prose phase-id regex. Drives #2111 — the
     // anchored parser returns { phase: null } for a "Milestone vX.Y complete"
     // body line (the old unanchored regex mined the minor-version digit, e.g.
     // v0.5 -> "5"), so syncStateFrontmatter's #905 guard preserves the real
     // current_phase instead of clobbering it.
-    return parsePhaseFromProse(value);
+    // #5626: under `milestone-prefixed` the id is the whole `M-NN`; the convention comes from its owner.
+    return parsePhaseFromProse(value, convention, directoryContext);
 }
-function resolveStatePhase(fm, body) {
+function resolveStatePhase(fm, body, convention, directoryContext) {
     const currentPositionScope = matchCurrentPositionSection(body) ?? body;
     const frontmatterRaw = (0, state_document_cjs_1.stateFieldValue)(fm, body, 'current_phase', null).value;
     const legacyRaw = (0, state_document_cjs_1.stateFieldValue)(fm, currentPositionScope, null, 'Current Phase').value;
     const currentPositionRaw = (0, state_document_cjs_1.stateFieldValue)(fm, currentPositionScope, null, 'Phase').value;
     const sources = {
-        frontmatter: parseProsePhaseField(frontmatterRaw).phase,
-        legacy_current_phase: parseProsePhaseField(legacyRaw).phase,
-        current_position_phase: parseProsePhaseField(currentPositionRaw).phase,
+        frontmatter: parseProsePhaseField(frontmatterRaw, convention, directoryContext).phase,
+        legacy_current_phase: parseProsePhaseField(legacyRaw, convention, directoryContext).phase,
+        current_position_phase: parseProsePhaseField(currentPositionRaw, convention, directoryContext).phase,
     };
-    const prosePhase = parseProsePhaseField(currentPositionRaw);
+    const prosePhase = parseProsePhaseField(currentPositionRaw, convention, directoryContext);
     return {
         phase: sources.frontmatter ?? sources.legacy_current_phase ?? sources.current_position_phase,
         name: (0, state_document_cjs_1.stateFieldValue)(fm, body, 'current_phase_name', null).value
@@ -2069,9 +2341,9 @@ function resolveStatePhase(fm, body) {
  * Reconcile the two only by giving `resolveStatePhase` an explicit scope
  * parameter — never by pointing this at it and dropping the difference.
  */
-function resolveCurrentPhaseId(fm, body) {
+function resolveCurrentPhaseId(fm, body, convention, directoryContext) {
     const positionSection = sliceCurrentPositionSection(body);
-    const prosePhase = positionSection !== null ? parseProsePhaseField((0, state_document_cjs_1.stateFieldValue)(fm, positionSection, null, 'Phase').value).phase : null;
+    const prosePhase = positionSection !== null ? parseProsePhaseField((0, state_document_cjs_1.stateFieldValue)(fm, positionSection, null, 'Phase').value, convention, directoryContext).phase : null;
     return (0, state_document_cjs_1.stateFieldValue)(fm, body, 'current_phase', 'Current Phase').value ?? prosePhase;
 }
 function parseProseLastActivityField(value) {
@@ -2109,7 +2381,8 @@ function cmdStateSnapshot(cwd, raw) {
     // so it is scopeable exactly like Stopped At under ## Session. Fall back to
     // full-body search only when no ## Current Position section exists, so files
     // with no section heading keep their current behaviour.
-    const resolvedPhase = resolveStatePhase(fm, body);
+    const directoryContext = phaseDirectoryOptions(cwd);
+    const resolvedPhase = resolveStatePhase(fm, body, resolvePhaseIdConvention(cwd), directoryContext);
     const currentPhase = resolvedPhase.phase;
     const currentPhaseName = resolvedPhase.name;
     const totalPhasesRaw = (0, state_document_cjs_1.stateFieldValue)(fm, body, 'total_phases', 'Total Phases').value;
@@ -2125,7 +2398,7 @@ function cmdStateSnapshot(cwd, raw) {
     // preferNewerLastActivity and the write seam in buildStateFrontmatter). The
     // write seam already scopes it to ## Session; this read seam must agree, so a
     // stale "Paused At:" in a Session Continuity Archive cannot win here either.
-    const sessionScope = matchSessionSection(body) ?? body;
+    const sessionScope = sessionFieldScope(body);
     const pausedAt = (0, state_document_cjs_1.stateFieldValue)(fm, sessionScope, 'paused_at', 'Paused At').value;
     // Parse numeric fields
     const totalPhases = totalPhasesRaw ? parseInt(totalPhasesRaw, 10) : null;
@@ -2168,7 +2441,8 @@ function cmdStateSnapshot(cwd, raw) {
     // `## Session Continuity` heading. See matchSessionSection for the anchoring.
     const sessionMatch = matchSessionSection(body);
     if (sessionMatch !== null) {
-        const sessionSection = sessionMatch;
+        // #4998: fenced example lines are not fields (as for sessionFieldScope).
+        const sessionSection = (0, state_document_cjs_1.maskFencedLines)(sessionMatch);
         // Accept both `**Last Date:**` (canonical template form) and `**Last session:**`
         // (the form written by the DWIM auto-create / normalize path added for #944).
         const lastDateMatch = sessionSection.match(/\*\*Last Date:\*\*\s*(.+)/i)
@@ -2279,7 +2553,7 @@ function isMilestoneBounded(roadmapRaw, milestone, convention) {
  * decimal, and project-code IDs are detected alike. Returns canonical keys
  * (see phaseKeyFromToken).
  */
-function extractRetiredPhaseNumbers(scope, convention) {
+function extractRetiredPhaseNumbers(scope, convention, directoryContext) {
     const retired = new Set();
     const isChecklistOrHeading = /^\s*(?:[-*+]\s*\[[ xX]\]|#{1,6}\s)/;
     // #612: the retirement filter has to widen with the counter it protects. The
@@ -2305,8 +2579,8 @@ function extractRetiredPhaseNumbers(scope, convention) {
         while ((s = strikeSpan.exec(line)) !== null) {
             const phaseRef = phaseRefRe.exec(s[1]);
             // Require a digit so struck prose like ~~Phase Overview~~ is ignored.
-            if (phaseRef && /\d/.test(phaseRef[1]))
-                retired.add(phaseKeyFromToken(phaseRef[1]));
+            if (phaseRef && (directoryContext?.phaseNaming === 'custom' || /\d/.test(phaseRef[1])))
+                retired.add(phaseKeyFromToken(phaseRef[1], directoryContext));
         }
     }
     return retired;
@@ -2350,7 +2624,7 @@ function extractRetiredPhaseNumbers(scope, convention) {
  * retain the bracket-id and bare-0 rules. Sharing the implementation therefore
  * cannot silently move either convention's total.
  */
-function countRoadmapPhaseHeadings(scope, convention, retiredPhaseNums, applyConventionTokenSentinelRules) {
+function countRoadmapPhaseHeadings(scope, convention, retiredPhaseNums, applyConventionTokenSentinelRules, directoryContext) {
     let count = 0;
     if (convention === 'bracket') {
         const introSrc = phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY, convention, true);
@@ -2381,7 +2655,7 @@ function countRoadmapPhaseHeadings(scope, convention, retiredPhaseNums, applyCon
                 continue;
             // #1514: retired/folded phases are struck through in the ROADMAP;
             // exclude them from the denominator (they can never be completed).
-            if (retiredPhaseNums.has(phaseKeyFromToken(token)))
+            if (retiredPhaseNums.has(phaseKeyFromToken(token, directoryContext)))
                 continue;
             count++;
         }
@@ -2397,7 +2671,7 @@ function countRoadmapPhaseHeadings(scope, convention, retiredPhaseNums, applyCon
             continue;
         if (applyConventionTokenSentinelRules && isSentinelPhaseId(token))
             continue;
-        if (retiredPhaseNums.has(phaseKeyFromToken(token)))
+        if (retiredPhaseNums.has(phaseKeyFromToken(token, directoryContext)))
             continue;
         count++;
     }
@@ -2425,12 +2699,14 @@ options = {}) {
     let roadmapScope = null;
     let roadmapRaw = null;
     let retiredPhaseNums = new Set();
+    let directoryContext = phaseDirectoryOptions(cwd, undefined, '');
     try {
         const roadmapPath = node_path_1.default.join(planningDir(cwd), 'ROADMAP.md');
         roadmapRaw = (0, shell_command_projection_cjs_1.platformReadSync)(roadmapPath);
         if (roadmapRaw !== null) {
             roadmapScope = extractCurrentMilestone(roadmapRaw, cwd);
-            retiredPhaseNums = extractRetiredPhaseNumbers(roadmapScope, phaseConvention);
+            directoryContext = { ...directoryContext, roadmap: roadmapRaw };
+            retiredPhaseNums = extractRetiredPhaseNumbers(roadmapScope, phaseConvention, directoryContext);
         }
     }
     catch { /* fall through: no roadmap scope → no retired exclusion */ }
@@ -2457,7 +2733,7 @@ options = {}) {
         // artifact; drop it from the disk phase set so it counts toward
         // neither the denominator nor the numerator (mirrors the heading
         // exclusion below). Project-code-aware via phaseKeyFromDir.
-        if (retiredPhaseNums.size > 0 && retiredPhaseNums.has(phaseKeyFromDir(dir, phaseConvention)))
+        if (retiredPhaseNums.size > 0 && retiredPhaseNums.has(phaseKeyFromDir(dir, phaseConvention, directoryContext)))
             continue;
         // #3185: dedup grouping routed through the canonical phaseKeyFromDir
         // (src/phase-id.cts) instead of a local leading-digits regex that
@@ -2466,7 +2742,7 @@ options = {}) {
         // so a `PROJ-05`/`PROJ-05-slug` pair never deduped) and on
         // multi-segment milestone dirs. Same key surface used two lines
         // above for the retiredPhaseNums exclusion, so both filters agree.
-        const key = phaseKeyFromDir(dir, phaseConvention);
+        const key = phaseKeyFromDir(dir, phaseConvention, directoryContext);
         if (!seenPhaseNums.has(key)) {
             seenPhaseNums.set(key, dir);
         }
@@ -2497,6 +2773,7 @@ options = {}) {
         roadmapScope,
         roadmapRaw,
         retiredPhaseNums,
+        directoryContext,
     };
 }
 /**
@@ -2531,7 +2808,7 @@ milestoneExplicitlyNull) {
     // section overwrites current_phase here, and the next read surfaces it. Fall
     // back to full-body search when no ## Current Position section exists.
     const currentPositionScope = matchCurrentPositionSection(bodyContent) ?? bodyContent;
-    const prosePhase = parseProsePhaseField((0, state_document_cjs_1.stateExtractField)(currentPositionScope, 'Phase'));
+    const prosePhase = parseProsePhaseField((0, state_document_cjs_1.stateExtractField)(currentPositionScope, 'Phase'), cwd ? resolvePhaseIdConvention(cwd) : null, cwd ? phaseDirectoryOptions(cwd) : undefined);
     const currentPhase = (0, state_document_cjs_1.stateExtractField)(bodyContent, 'Current Phase') ?? prosePhase.phase;
     const currentPhaseName = (0, state_document_cjs_1.stateExtractField)(bodyContent, 'Current Phase Name') ?? prosePhase.name;
     const currentPlan = (0, state_document_cjs_1.stateExtractField)(bodyContent, 'Current Plan');
@@ -2549,8 +2826,7 @@ milestoneExplicitlyNull) {
     // Fall back to full-body search only when no ## Session section exists.
     // #1101: prefer the canonical `## Session` block, falling back to the bootstrap
     // `## Session Continuity` heading. See matchSessionSection for the anchoring.
-    const sessionSectionMatch = matchSessionSection(bodyContent);
-    const sessionBodyScope = sessionSectionMatch ?? bodyContent;
+    const sessionBodyScope = sessionFieldScope(bodyContent);
     const stoppedAt = (0, state_document_cjs_1.stateExtractField)(sessionBodyScope, 'Stopped At') || (0, state_document_cjs_1.stateExtractField)(sessionBodyScope, 'Stopped at');
     // #2567: Paused At is a session field — scope it to ## Session too so a
     // stale "Paused At:" line in an archive section cannot overwrite the value.
@@ -2630,7 +2906,7 @@ milestoneExplicitlyNull) {
                     // #5118 pre-write validation in `phase remove` reads exactly this set.
                     // #5038: an explicit-null `storedMilestone` is text, not a version;
                     // pass a real null so it never reaches the phase-dir version filter.
-                    const { phaseDirs, phaseDirScope, roadmapScope, roadmapRaw, retiredPhaseNums, } = scanStatePhaseDirs(cwd, phasesDir, phaseConvention, milestoneExplicitlyNull ? null : storedMilestone);
+                    const { phaseDirs, phaseDirScope, roadmapScope, roadmapRaw, retiredPhaseNums, directoryContext, } = scanStatePhaseDirs(cwd, phasesDir, phaseConvention, milestoneExplicitlyNull ? null : storedMilestone);
                     let diskTotalPlans = 0;
                     let diskTotalSummaries = 0;
                     let diskCompletedPhases = 0;
@@ -2668,7 +2944,7 @@ milestoneExplicitlyNull) {
                     // fence-aware bracket strategy with #3185's canonical legacy
                     // sentinel predicate for this read-path call.
                     const roadmapPhaseCount = roadmapScope !== null
-                        ? countRoadmapPhaseHeadings(roadmapScope, phaseConvention, retiredPhaseNums, true)
+                        ? countRoadmapPhaseHeadings(roadmapScope, phaseConvention, retiredPhaseNums, true, directoryContext)
                         : 0;
                     cached = (() => {
                         // #1761 read-path: mirror the cmdStateSync guard (#1794). When the
@@ -2799,8 +3075,14 @@ milestoneExplicitlyNull) {
                         // — no second ROADMAP parser here. A ROADMAP without a canonical
                         // `## Progress` table resolves no table → floor inert (disk count
                         // stands), the owner's own answer to "what is countable".
+                        // #5165: the milestone-grouped `## Progress` table keeps every
+                        // milestone's rows and sits OUTSIDE any narrower roadmapScope, so the
+                        // floor names the milestone STATE asserts (assertedMilestoneVersion —
+                        // present on every resync path, unlike the optional storedMilestone
+                        // parameter) and the owner counts only that milestone's rows. No row
+                        // for it => nulls => the floor is inert and the disk count stands.
                         const roadmapCompletedPhases = roadmapScope !== null && safeToUseRoadmapCount && !diskCountsWithheld
-                            ? deriveProgressFromRoadmap(roadmapScope).completedPhases
+                            ? deriveProgressFromRoadmap(roadmapScope, assertedMilestoneVersion ?? storedMilestone).completedPhases
                             : null;
                         const flooredCompletedPhases = roadmapCompletedPhases !== null
                             ? Math.max(diskCompletedPhases, roadmapCompletedPhases)
@@ -3227,6 +3509,8 @@ function applyAuthoritativeProgressSubkeys(fm, intent, opts) {
     for (const [subkey, value] of Object.entries(intent)) {
         if (typeof value !== 'number' || !Number.isFinite(value))
             continue;
+        if (subkey === 'percent')
+            continue; // composed below, never applied raw (#5165)
         if (!getFieldClassification(`progress.${subkey}`))
             continue;
         const isCompletedCounter = subkey === 'completed_phases' || subkey === 'completed_plans';
@@ -3244,10 +3528,18 @@ function applyAuthoritativeProgressSubkeys(fm, intent, opts) {
     }
     // percent: applied only when a completed counter moved (coherent with the
     // counters that just landed) or when no percent exists to contradict.
+    // #5165 / ADR-4629 §8.5: `computeProgressPercent` is the one composition
+    // owner (min(plan fraction, phase fraction)) that every resyncing write uses.
+    // When the block carries the counters it needs, the percent is composed by
+    // that owner over the counters just landed, so a later resyncing write
+    // cannot move what this transition wrote. The intent's own percent (a
+    // phase-only fraction) is only the fallback for a block without plan counts.
     const intentPercent = intent['percent'];
     if (typeof intentPercent === 'number' && Number.isFinite(intentPercent) && (completedMoved || (0, state_document_cjs_1.toFiniteNumber)(base['percent']) === null)) {
-        if (!Object.is(base['percent'], intentPercent)) {
-            base['percent'] = intentPercent;
+        const composed = (0, state_document_cjs_1.computeProgressPercent)((0, state_document_cjs_1.toFiniteNumber)(base['completed_plans']), (0, state_document_cjs_1.toFiniteNumber)(base['total_plans']), (0, state_document_cjs_1.toFiniteNumber)(base['completed_phases']), (0, state_document_cjs_1.toFiniteNumber)(base['total_phases']), SCOPE.COMPLETE);
+        const nextPercent = composed !== null ? composed : intentPercent;
+        if (!Object.is(base['percent'], nextPercent)) {
+            base['percent'] = nextPercent;
             changed = true;
         }
     }
@@ -3831,7 +4123,10 @@ function assertStatePreservationOptions(options, caller) {
         throw err;
     }
 }
-function applyPostSyncPreservation(originalContent, transformedContent, syncedContent, statePath, options) {
+function applyPostSyncPreservation(originalContent, transformedContent, syncedContent, statePath, options, 
+// #5626: the project's phase-id convention, resolved by the caller from its cwd (null: unset). Trailing and
+// optional so `options` stays the fifth parameter the options guard and its callers rely on.
+phaseIdConvention = null, directoryContext) {
     assertStatePreservationOptions(options, 'applyPostSyncPreservation');
     const { resync, authoritativeFm, deriveProgressKeys, divergedFields, explicitProgressField, preWriteState } = options;
     // Bug #1230: delta heuristic — snapshot pre-transform body source fields so
@@ -3867,8 +4162,7 @@ function applyPostSyncPreservation(originalContent, transformedContent, syncedCo
     // mirroring buildStateFrontmatter's sessionBodyScope logic.
     // A stale "Stopped at:" in a non-Session section (e.g. Session Continuity
     // Archive prose) must not interfere with the delta comparison.
-    const preSessionMatch = matchSessionSection(preBody);
-    const preSessionScope = preSessionMatch ?? preBody;
+    const preSessionScope = sessionFieldScope(preBody);
     const preBodyStoppedAt = (0, state_document_cjs_1.stateExtractField)(preSessionScope, 'Stopped At') || (0, state_document_cjs_1.stateExtractField)(preSessionScope, 'Stopped at');
     // ADR-1769 Phase 6 / #1743 / #1695: snapshot the body source for the curated
     // current_phase_name (the `Phase:` line parseProsePhaseField harvests). When
@@ -3888,7 +4182,7 @@ function applyPostSyncPreservation(originalContent, transformedContent, syncedCo
     const preCurrentPositionScope = matchCurrentPositionSection(preBody) ?? preBody;
     const preBodyCurrentPlan = (0, state_document_cjs_1.stateExtractField)(preBody, 'Current Plan');
     const preBodyCurrentPhase = (0, state_document_cjs_1.stateExtractField)(preBody, 'Current Phase')
-        ?? parseProsePhaseField((0, state_document_cjs_1.stateExtractField)(preCurrentPositionScope, 'Phase')).phase;
+        ?? parseProsePhaseField((0, state_document_cjs_1.stateExtractField)(preCurrentPositionScope, 'Phase'), phaseIdConvention, directoryContext).phase;
     const preBodyPausedAt = (0, state_document_cjs_1.stateExtractField)(preSessionScope, 'Paused At');
     const preBodyLastActivityRaw = (0, state_document_cjs_1.stateExtractField)(preBody, 'Last Activity')
         ?? (0, state_document_cjs_1.stateExtractField)(preBody, 'Last activity');
@@ -3903,8 +4197,7 @@ function applyPostSyncPreservation(originalContent, transformedContent, syncedCo
     const postBodyStatus = (0, state_document_cjs_1.stateExtractField)(postBody, 'Status');
     // Bug #1230 / Change B: scope stopped_at delta to the ## Session section,
     // consistent with the pre-transform snapshot above and buildStateFrontmatter.
-    const postSessionMatch = matchSessionSection(postBody);
-    const postSessionScope = postSessionMatch ?? postBody;
+    const postSessionScope = sessionFieldScope(postBody);
     const postBodyStoppedAt = (0, state_document_cjs_1.stateExtractField)(postSessionScope, 'Stopped At') || (0, state_document_cjs_1.stateExtractField)(postSessionScope, 'Stopped at');
     // ADR-1769 Phase 6 / #1695: post-transform body Phase source for the
     // current_phase_name delta comparison.
@@ -3914,7 +4207,7 @@ function applyPostSyncPreservation(originalContent, transformedContent, syncedCo
     const postCurrentPositionScope = matchCurrentPositionSection(postBody) ?? postBody;
     const postBodyCurrentPlan = (0, state_document_cjs_1.stateExtractField)(postBody, 'Current Plan');
     const postBodyCurrentPhase = (0, state_document_cjs_1.stateExtractField)(postBody, 'Current Phase')
-        ?? parseProsePhaseField((0, state_document_cjs_1.stateExtractField)(postCurrentPositionScope, 'Phase')).phase;
+        ?? parseProsePhaseField((0, state_document_cjs_1.stateExtractField)(postCurrentPositionScope, 'Phase'), phaseIdConvention, directoryContext).phase;
     const postBodyPausedAt = (0, state_document_cjs_1.stateExtractField)(postSessionScope, 'Paused At');
     const postBodyLastActivityRaw = (0, state_document_cjs_1.stateExtractField)(postBody, 'Last Activity')
         ?? (0, state_document_cjs_1.stateExtractField)(postBody, 'Last activity');
@@ -4131,7 +4424,7 @@ function applyPostSyncPreservation(originalContent, transformedContent, syncedCo
 function syncAndPreserveStateMd(originalContent, transformedContent, statePath, cwd, options) {
     assertStatePreservationOptions(options, 'syncAndPreserveStateMd');
     const synced = syncStateFrontmatter(transformedContent, cwd, options.authoritativeFm);
-    return applyPostSyncPreservation(originalContent, transformedContent, synced, statePath, options);
+    return applyPostSyncPreservation(originalContent, transformedContent, synced, statePath, options, cwd ? resolvePhaseIdConvention(cwd) : null, cwd ? phaseDirectoryOptions(cwd) : undefined);
 }
 /**
  * Atomic read-modify-write for STATE.md.
@@ -4554,7 +4847,7 @@ function computeChangedFrontmatterFields(snapshotFm, persistedFm, bodyDeltas) {
  * the markdown-sectionizer seam (ADR-1372), never a hand-rolled regex.
  * Existing callers pass no `sectionTargets` and resolve exactly as before.
  */
-function readStateTarget(fm, body, field, sectionTargets) {
+function readStateTarget(fm, body, field, sectionTargets, sessionScope = false) {
     if (field === 'Current Position') {
         const section = stateTransitionMod.sliceCurrentPositionSection(body);
         return section !== null ? section.trim() : null;
@@ -4563,7 +4856,14 @@ function readStateTarget(fm, body, field, sectionTargets) {
         const section = (0, markdown_sectionizer_cjs_1.collectSection)(body, (h) => h.text === field);
         return section !== null ? section.body.trim() : null;
     }
-    const bodyValue = (0, state_document_cjs_1.stateExtractField)(body, field);
+    // #4998 review: no session writer changes a fenced example line, so a session
+    // field is read with fences blanked — an unchanged example above the live
+    // line hid the write and reported it missing. With `sessionScope` (`state
+    // update`, `state patch` and `state record-session`, which write inside the
+    // session section) it is read there; otherwise from the whole document.
+    const bodyValue = stateTransitionMod.isSessionScopedBodyField(field)
+        ? (0, state_document_cjs_1.stateExtractField)((0, state_document_cjs_1.readableBoldLabels)(sessionScope ? sessionFieldScope(body) : (0, state_document_cjs_1.maskFencedLines)(body)), field)
+        : (0, state_document_cjs_1.stateExtractField)(body, field);
     if (bodyValue !== null)
         return bodyValue;
     if (Object.prototype.hasOwnProperty.call(fm, field))
@@ -4591,7 +4891,7 @@ const NO_SECTION_TARGETS = new Set();
  * `STATE_FIELD_ABSENT` sentinel + `stateFieldValuesDiffer`) instead of a
  * second, parallel absence convention — one rule, reused, not duplicated.
  */
-function stateTargetChanged(snapshotFm, snapshotBody, persistedFm, persistedBody, field, sectionTargets) {
+function stateTargetChanged(snapshotFm, snapshotBody, persistedFm, persistedBody, field, sectionTargets, sessionScope = false) {
     const isDeclaredDerivedLeaf = field.includes('.') && Object.prototype.hasOwnProperty.call(FIELD_CLASSIFICATION, field);
     if (isDeclaredDerivedLeaf && !sectionTargets.has(field)) {
         const before = resolveFrontmatterPath(snapshotFm, field);
@@ -4603,8 +4903,8 @@ function stateTargetChanged(snapshotFm, snapshotBody, persistedFm, persistedBody
             return false;
         return stateFieldValuesDiffer(before, after);
     }
-    const before = readStateTarget(snapshotFm, snapshotBody, field, sectionTargets);
-    const after = readStateTarget(persistedFm, persistedBody, field, sectionTargets);
+    const before = readStateTarget(snapshotFm, snapshotBody, field, sectionTargets, sessionScope);
+    const after = readStateTarget(persistedFm, persistedBody, field, sectionTargets, sessionScope);
     if (before === null && after === null)
         return false;
     if (before === null || after === null)
@@ -4615,7 +4915,9 @@ function reconcileReportedFields(statePath, preWriteState, reported, divergedFie
 // ADR-4629 §8.2 / Decision 4 (C2): names in `reported` that are declared
 // `target: 'section'` assertions, measured as whole-section deltas. Omitted
 // by every pre-C2 caller, whose output is unchanged.
-sectionTargets = NO_SECTION_TARGETS) {
+sectionTargets = NO_SECTION_TARGETS, 
+// #4998 review: the caller writes session fields inside the session section.
+sessionScope = false) {
     void divergedFields; // ADR-3473 §8.7 D18: out-param only, not a candidate source here.
     if (preWriteState.fm === undefined || preWriteState.body === undefined)
         return [];
@@ -4624,7 +4926,7 @@ sectionTargets = NO_SECTION_TARGETS) {
     const persistedBody = stripFrontmatter(persisted);
     const snapshotFm = preWriteState.fm;
     const snapshotBody = preWriteState.body;
-    const changed = (field) => stateTargetChanged(snapshotFm, snapshotBody, persistedFm, persistedBody, field, sectionTargets);
+    const changed = (field) => stateTargetChanged(snapshotFm, snapshotBody, persistedFm, persistedBody, field, sectionTargets, sessionScope);
     // Candidate set = `reported` ∪ every frontmatter key (dotted-leaf
     // granularity) whose persisted value differs from the snapshot, minus the
     // provenance exclusion. A frontmatter-diff-discovered field is mapped
@@ -4789,8 +5091,9 @@ function stateSectionScopeUnits(units, sectionTargets) {
  * matching `readStateTarget`'s long-standing special case.
  */
 function verifyStateWriteIntent(intent, preContent, postContent, statePath, bodyDeltas) {
-    const pre = (0, shell_command_projection_cjs_1.normalizeContent)(statePath, preContent).content;
-    const post = (0, shell_command_projection_cjs_1.normalizeContent)(statePath, postContent).content;
+    // #5165: the write lands scoped to what it changed (platformWriteSync reads the file it replaces).
+    const pre = (0, shell_command_projection_cjs_1.normalizeContent)(statePath, preContent, { prior: preContent }).content;
+    const post = (0, shell_command_projection_cjs_1.normalizeContent)(statePath, postContent, { prior: preContent }).content;
     const preFm = extractFrontmatter(pre, statePath);
     const postFm = extractFrontmatter(post, statePath);
     const preBody = stripFrontmatter(pre);
@@ -4989,7 +5292,7 @@ function applyStateWriteIntent(statePath, intent, transformFn, cwd, options = {}
             return unwritten(verification);
         (0, shell_command_projection_cjs_1.platformWriteSync)(statePath, candidate);
         const reread = (0, shell_command_projection_cjs_1.platformReadSync)(statePath) || '';
-        if (reread !== (0, shell_command_projection_cjs_1.normalizeContent)(statePath, candidate).content) {
+        if (reread !== (0, shell_command_projection_cjs_1.normalizeContent)(statePath, candidate, { prior: pre }).content) {
             return Object.freeze({
                 ok: false,
                 reasons: Object.freeze([STATE_WRITE_INTENT_FAILURE.REREAD_MISMATCH]),
@@ -5049,13 +5352,13 @@ function cmdStateJson(cwd, raw) {
     // change untouched — and `milestone`/`milestone_name`
     // (preserve-if-placeholder) are out of D3's scope entirely.
     if (existingFm) {
-        const sessionScope = matchSessionSection(body) ?? body;
+        const sessionScope = sessionFieldScope(body);
         const positionScope = matchCurrentPositionSection(body) ?? body;
         const bodyStoppedAt = (0, state_document_cjs_1.stateExtractField)(sessionScope, 'Stopped At') || (0, state_document_cjs_1.stateExtractField)(sessionScope, 'Stopped at');
         const bodyPausedAt = (0, state_document_cjs_1.stateExtractField)(sessionScope, 'Paused At');
         const bodyPhaseSource = (0, state_document_cjs_1.stateExtractField)(body, 'Phase');
         const bodyCurrentPhase = (0, state_document_cjs_1.stateExtractField)(body, 'Current Phase')
-            ?? parseProsePhaseField((0, state_document_cjs_1.stateExtractField)(positionScope, 'Phase')).phase;
+            ?? parseProsePhaseField((0, state_document_cjs_1.stateExtractField)(positionScope, 'Phase'), resolvePhaseIdConvention(cwd), phaseDirectoryOptions(cwd)).phase;
         const bodyCurrentPlan = (0, state_document_cjs_1.stateExtractField)(body, 'Current Plan');
         const bodyStatus = (0, state_document_cjs_1.stateExtractField)(body, 'Status');
         // #3836: mirrors applyPostSyncPreservation's own derivation (state.cts
@@ -5116,7 +5419,7 @@ function cmdStateJson(cwd, raw) {
  * phase locator's own rule, so this agrees with `init` and `phase-plan-index`.
  */
 function firstPlanToRun(cwd, phaseNumber) {
-    const located = phaseLocatorMod.findPhaseInternal(cwd, String(phaseNumber));
+    const located = phaseLocatorMod.findPhaseInternal(cwd, String(phaseNumber), undefined, phaseDirectoryOptions(cwd));
     if (!located || !located.found)
         return null;
     const { plans, incomplete_plans: incomplete } = located;
@@ -5152,6 +5455,10 @@ function cmdStateBeginPhase(cwd, phaseNumber, phaseName, planCount, raw) {
     if (phaseNumber == null || String(phaseNumber).trim() === '') {
         error('phase required (--phase <N>)');
     }
+    if (resolvePhaseIdConvention(cwd) === 'bracket'
+        && (String(phaseNumber).startsWith('[') || String(phaseNumber).includes('-'))) {
+        error('state begin-phase --phase requires a bare phase number such as 02; qualified ids are not accepted.', ERROR_REASON.USAGE);
+    }
     const statePath = planningPaths(cwd).state;
     if (!node_fs_1.default.existsSync(statePath)) {
         output({ error: 'STATE.md not found' }, raw, undefined);
@@ -5215,7 +5522,22 @@ function cmdStateBeginPhase(cwd, phaseNumber, phaseName, planCount, raw) {
         if (result.data?.['resumed']) {
             delete rmwOptions.authoritativeFm;
         }
-        return result.content;
+        let transitioned = result.content;
+        if (resolvePhaseIdConvention(cwd) === 'bracket') {
+            const display = phaseDisplayFor(cwd, phaseNumber);
+            if (result.updated.includes('Last Activity Description')) {
+                transitioned = replaceStateBodyField(transitioned, statePath, 'Last Activity Description', `${display} execution started`);
+            }
+            if (result.updated.includes('Current focus')) {
+                transitioned = replaceStateBodyField(transitioned, statePath, 'Current focus', intent.phaseName ? `${display} — ${intent.phaseName}` : display);
+            }
+            const today = clock_cjs_1.realClock.localToday();
+            const activitySuffix = result.data?.['resumed']
+                ? 'execution resumed (wave continue)'
+                : 'execution started';
+            transitioned = replaceCurrentPositionFieldValue(transitioned, statePath, 'Last Activity', `${today} — Phase ${phaseNumber} ${activitySuffix}`, `${today} — ${display} ${activitySuffix}`);
+        }
+        return transitioned;
     }, cwd, rmwOptions);
     // ADR-3408 §8.4 (D4): reconcile `beginPhaseCore`'s own success list against
     // the bytes actually persisted (fix(#3351) generalized) and fold in any
@@ -5527,12 +5849,23 @@ function cmdStatePlannedPhase(cwd, phaseNumber, phaseName, planCount, raw) {
         if (!intent.phaseName) {
             const preFm = extractFrontmatter(content, statePath);
             const curatedName = preFm['current_phase_name'];
-            if (typeof curatedName === 'string' && curatedName.trim().length > 0) {
+            // #5369: a status fragment a pre-fix write left as the name is not curated; do not reassert it.
+            if (typeof curatedName === 'string' && curatedName.trim().length > 0 && !phaseIdMod.isPlannedPhaseStatusPhrase(curatedName)) {
                 rmwOptions.authoritativeFm = { current_phase_name: curatedName };
             }
         }
         const result = transitionCore(content, intent, deps);
         precomputedUpdated = result.updated;
+        if (resolvePhaseIdConvention(cwd) === 'bracket') {
+            const display = phaseDisplayFor(cwd, phaseNumber);
+            let transitioned = result.content;
+            if (result.updated.includes('Last Activity Description')) {
+                transitioned = replaceStateBodyField(transitioned, statePath, 'Last Activity Description', `${display} planning complete — ${planCount || '?'} plans ready`);
+            }
+            const today = clock_cjs_1.realClock.localToday();
+            transitioned = replaceCurrentPositionFieldValue(transitioned, statePath, 'Last Activity', `${today} — Phase ${phaseNumber} planning complete`, `${today} — ${display} planning complete`);
+            return transitioned;
+        }
         return result.content;
     }, cwd, rmwOptions);
     // ADR-3408 §8.4 (D4): reconcile `plannedPhaseCore`'s own success list
@@ -5756,7 +6089,8 @@ function cmdStateValidate(cwd, raw, opts = {}) {
     const { fm, body, scope: initialScope } = readStateFrontmatterScoped(content, statePath);
     const scope = initialScope;
     const status = (0, state_document_cjs_1.stateFieldValue)(fm, body, 'status', 'Status').value || '';
-    const resolvedPhase = resolveStatePhase(fm, body);
+    const directoryContext = phaseDirectoryOptions(cwd);
+    const resolvedPhase = resolveStatePhase(fm, body, resolvePhaseIdConvention(cwd), directoryContext);
     const currentPhase = resolvedPhase.phase;
     const totalPlansRaw = (0, state_document_cjs_1.stateFieldValue)(fm, body, 'total_plans_in_phase', 'Total Plans in Phase').value;
     const totalPlansInPhase = totalPlansRaw ? parseInt(totalPlansRaw, 10) : null;
@@ -5766,8 +6100,8 @@ function cmdStateValidate(cwd, raw, opts = {}) {
         emit({ valid: false, warnings, scope });
         return;
     }
-    const selectedPhaseKey = phaseKeyFromToken(currentPhase);
-    if (Object.values(resolvedPhase.sources).some(source => source !== null && phaseKeyFromToken(source) !== selectedPhaseKey)) {
+    const selectedPhaseKey = phaseKeyFromToken(currentPhase, directoryContext);
+    if (Object.values(resolvedPhase.sources).some(source => source !== null && phaseKeyFromToken(source, directoryContext) !== selectedPhaseKey)) {
         warnings.push(stateDiagnostic('S003', SEVERITY.WARNING, `Phase reference conflict: validating authoritative phase ${currentPhase}; align STATE.md phase sources`, 'Align STATE.md phase sources (frontmatter, Current Phase, Current Position Phase) on one phase'));
     }
     if (!node_fs_1.default.existsSync(phasesDir)) {
@@ -5796,7 +6130,7 @@ function cmdStateValidate(cwd, raw, opts = {}) {
     let phaseDirPath;
     try {
         const entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
-        const phaseDir = entries.find(entry => entry.isDirectory() && phaseKeyFromDir(entry.name, validateConvention) === selectedPhaseKey);
+        const phaseDir = entries.find(entry => entry.isDirectory() && phaseKeyFromDir(entry.name, validateConvention, directoryContext) === selectedPhaseKey);
         if (!phaseDir) {
             warnings.push(stateDiagnostic('S004', SEVERITY.WARNING, `Cannot validate phase drift: no phase directory matches phase ${currentPhase}`, 'Create a phase directory matching the current phase or correct current_phase'));
             emit({ valid: false, warnings, scope });
@@ -5954,6 +6288,7 @@ function cmdStateSync(cwd, options, raw) {
     // write branch can surface it identically.
     const existingSyncFm = extractFrontmatter(content, statePath);
     const syncFrontmatterWasUnparseable = isUnparseableFrontmatter(existingSyncFm);
+    let directoryContext = phaseDirectoryOptions(cwd, undefined, '');
     const changes = [];
     let modified = content;
     const phasesDir = planningPaths(cwd).phases;
@@ -5973,8 +6308,9 @@ function cmdStateSync(cwd, options, raw) {
         const roadmapRaw = (0, shell_command_projection_cjs_1.platformReadSync)(node_path_1.default.join(planningDir(cwd), 'ROADMAP.md'));
         if (roadmapRaw !== null) {
             syncRoadmapRaw = roadmapRaw;
+            directoryContext = { ...directoryContext, roadmap: roadmapRaw };
             syncRoadmapScope = extractCurrentMilestone(roadmapRaw, cwd);
-            syncRetiredPhaseNums = extractRetiredPhaseNumbers(syncRoadmapScope, syncConvention);
+            syncRetiredPhaseNums = extractRetiredPhaseNumbers(syncRoadmapScope, syncConvention, directoryContext);
         }
     }
     catch { /* fall through: no roadmap scope → no retired exclusion */ }
@@ -6011,7 +6347,7 @@ function cmdStateSync(cwd, options, raw) {
         entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true })
             .filter(e => e.isDirectory())
             .map(e => e.name)
-            .filter(name => !(syncRetiredPhaseNums.size > 0 && syncRetiredPhaseNums.has(phaseKeyFromDir(name, syncConvention))))
+            .filter(name => !(syncRetiredPhaseNums.size > 0 && syncRetiredPhaseNums.has(phaseKeyFromDir(name, syncConvention, directoryContext))))
             .filter(name => syncMilestonePhaseDirs === null || syncMilestonePhaseDirs.has(name))
             .sort();
     }
@@ -6079,7 +6415,7 @@ function cmdStateSync(cwd, options, raw) {
     // pre-existing legacy sync behavior while #3185 remains the read-path owner.
     let syncTotalPhases = null;
     const roadmapPhaseCount = syncRoadmapScope !== null
-        ? countRoadmapPhaseHeadings(syncRoadmapScope, syncConvention, syncRetiredPhaseNums, syncConvention === 'bracket')
+        ? countRoadmapPhaseHeadings(syncRoadmapScope, syncConvention, syncRetiredPhaseNums, syncConvention === 'bracket', directoryContext)
         : 0;
     if (roadmapPhaseCount > 0) {
         syncTotalPhases = Math.max(entries.length, roadmapPhaseCount);
@@ -6210,7 +6546,7 @@ function cmdStatePrune(cwd, options, raw) {
     const body = stripFrontmatter(rawState);
     // Prune needs an integer cutoff, so it parses the resolved id itself; a
     // non-numeric or absent id lands on 0 and prune bails, as before.
-    const currentPhase = parseInt(String(resolveCurrentPhaseId(fm, body)), 10) || 0;
+    const currentPhase = parseInt(String(resolveCurrentPhaseId(fm, body, resolvePhaseIdConvention(cwd), phaseDirectoryOptions(cwd))), 10) || 0;
     const cutoff = currentPhase - keepRecent;
     if (cutoff <= 0) {
         emit({ pruned: false, reason: `Only ${currentPhase} phases — nothing to prune with --keep-recent ${keepRecent}` }, raw, 'false');
@@ -6435,7 +6771,7 @@ function cmdStateRebuild(cwd, options, raw) {
  * that the phase execution is finished and the project is ready for the next phase.
  * Implements the `gsd state complete-phase` subcommand (issue #2735).
  */
-function resolvePhaseIdForCompletePhase(fm, body, overridePhase) {
+function resolvePhaseIdForCompletePhase(fm, body, overridePhase, directoryContext) {
     // #3187: route through the single #1760 fallback-chain owner (fm scalar
     // then body field) instead of two raw stateExtractField calls on
     // frontmatter-blind content — a STATE.md whose phase lives only in
@@ -6453,7 +6789,7 @@ function resolvePhaseIdForCompletePhase(fm, body, overridePhase) {
     // "Phase 0.5 complete". A canonical token at the start of the value
     // (3, 03, 3A, 3.3, 10.2, "3 of 5", "1 — Setup") is preserved; a milestone
     // closure line yields null, so the caller's "unable to resolve" guard fires.
-    return parsePhaseFromProse(candidate).phase;
+    return parsePhaseFromProse(candidate, undefined, directoryContext).phase;
 }
 function cmdStateCompletePhase(cwd, raw, overridePhase) {
     const statePath = planningPaths(cwd).state;
@@ -6485,7 +6821,8 @@ function cmdStateCompletePhase(cwd, raw, overridePhase) {
         output({ error: 'Unable to read STATE.md frontmatter; refusing to run complete-phase to avoid a destructive rollback (#3489). Fix or remove the malformed frontmatter and retry.' }, raw, undefined);
         return;
     }
-    const resolvedPhase = resolvePhaseIdForCompletePhase(fm, body, overridePhase);
+    const directoryContext = phaseDirectoryOptions(cwd);
+    const resolvedPhase = resolvePhaseIdForCompletePhase(fm, body, overridePhase, directoryContext);
     if (!resolvedPhase || /^phase$/i.test(resolvedPhase)) {
         output({ error: 'Unable to resolve current phase. Pass an explicit phase: state complete-phase --phase <N>' }, raw, undefined);
         return;
@@ -6502,7 +6839,7 @@ function cmdStateCompletePhase(cwd, raw, overridePhase) {
     const existingCurrentPhaseRaw = (0, state_document_cjs_1.stateFieldValue)(fm, body, 'current_phase', 'Current Phase').value || '';
     // #2125: same canonical parser as resolvePhaseIdForCompletePhase so the two
     // sites cannot diverge on the token they extract.
-    const existingCurrentPhase = parsePhaseFromProse(existingCurrentPhaseRaw).phase;
+    const existingCurrentPhase = parsePhaseFromProse(existingCurrentPhaseRaw, undefined, directoryContext).phase;
     if (existingCurrentPhase && existingCurrentPhase !== resolvedPhase) {
         output({ updated: [], phase: resolvedPhase, idempotent: true, note: 'phase already superseded; no-op' }, raw, 'false');
         return;
@@ -6535,6 +6872,7 @@ function cmdStateCompletePhase(cwd, raw, overridePhase) {
     const rmwOptions = { divergedFields, preWriteState };
     const wrote = readModifyWriteStateMd(statePath, (content) => {
         const currentPhase = resolvedPhase;
+        const currentPhaseDisplay = phaseDisplayFor(cwd, currentPhase);
         // Bug #1255: operate on body only so the YAML frontmatter `status:` key
         // cannot shadow the body Status field (pipe-table or inline).
         //
@@ -6564,7 +6902,7 @@ function cmdStateCompletePhase(cwd, raw, overridePhase) {
             updated.push({ kind: 'field', name: 'Last Activity' });
         }
         // Update Last Activity Description
-        const activityDesc = `Phase ${currentPhase} marked complete`;
+        const activityDesc = `${currentPhaseDisplay} marked complete`;
         result = (0, state_document_cjs_1.stateReplaceField)(body, 'Last Activity Description', activityDesc);
         if (result) {
             body = result;
@@ -6613,14 +6951,14 @@ function cmdStateCompletePhase(cwd, raw, overridePhase) {
                         posBody = replaced;
                 }
                 // Update Last activity line if present
-                const newActivity = `Last activity: ${today} — Phase ${currentPhase} marked complete`;
+                const newActivity = `Last activity: ${today} — ${currentPhaseDisplay} marked complete`;
                 if (/^Last activity:/im.test(posBody)) {
                     posBody = posBody.replace(/^Last activity:.*$/im, newActivity);
                 }
                 else {
                     // Pipe-table format in Current Position (#1255)
                     // Value must match the inline branch (date + narrative), not bare date.
-                    const activityValue = `${today} — Phase ${currentPhase} marked complete`;
+                    const activityValue = `${today} — ${currentPhaseDisplay} marked complete`;
                     const replaced = (0, state_document_cjs_1.stateReplaceField)(posBody, 'Last Activity', activityValue)
                         ?? (0, state_document_cjs_1.stateReplaceField)(posBody, 'Last activity', activityValue);
                     if (replaced !== null)
@@ -6729,6 +7067,9 @@ module.exports = {
     cmdStateBeginPhase,
     cmdStatePlannedPhase,
     cmdStateCompletePhase,
+    // #4304: the canonical write-path current-phase ladder, read by the bracket
+    // `phase remove` refusal before it deletes or renumbers that phase.
+    resolveCurrentPhaseId,
     cmdStateValidate,
     cmdStateSync,
     cmdStatePrune,