fix(#4998): read the decoded milestone scalar, so a quoted milestone stops gaining an escape layer

.changeset/sharp-pandas-squeak.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 5234
+---
+**A quoted `STATE.md` milestone no longer gains an escape layer per `state.*` write, and `state record-session` no longer orphans the rest of a wrapped session field** — a milestone containing a literal `"` was copied into `state.json` with one more layer of quotes and backslashes on every write. `record-session` rewrote only the first line of a field whose value wraps; it now leaves such a field whole and lists it under `skipped`. Missing session fields are inserted beside their siblings in the section's own plain or bold form, without rewriting the section, and a frontmatter-only `stopped_at` it replaces is reported in `replacedRecord` (#4998).

src/roadmap-parser.cts

@@ -59,6 +59,9 @@ import planningWorkspace = require('./planning-workspace.cjs');
 const { planningDir, resolvePhaseIdConvention } = planningWorkspace;
 import { platformReadSync } from './shell-command-projection.cjs';
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+import frontmatterMod = require('./frontmatter.cjs');
+const { rawFrontmatterField } = frontmatterMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 import unusableInputMod = require('./unusable-input.cjs');
 const { UNUSABLE_REASON, warnUnusableInput } = unusableInputMod;
 import { tokenizeHeadings, stripTaggedBlocks, withSection, stripFencedCode, collectSection } from './markdown-sectionizer.cjs';
@@ -1003,6 +1006,20 @@ function classifyMilestoneScalar(raw: string | null | undefined): { explicitNull
   return { explicitNull: false, version: trimmed };
 }
 
+/**
+ * #4998: STATE.md's `milestone:` scalar as the frontmatter parser DECODES it.
+ * The raw `^milestone:` line read captured the on-disk YAML text — quotes and
+ * escapes included — and that text was re-serialized as the value, adding one
+ * escape layer per `state.*` write. Falls back to the legacy line read only
+ * when there is no parseable frontmatter carrying a string `milestone` key.
+ */
+function readStateMilestoneScalar(stateRaw: string): string | null {
+  const field = rawFrontmatterField(stateRaw, 'milestone');
+  if (field && typeof field.value === 'string') return field.value;
+  const m = stateRaw.match(/^milestone:\s*(.+)/m);
+  return m ? m[1] : null;
+}
+
 /**
  * Extract the current milestone section from ROADMAP.md by positive lookup,
  * carrying a `scope` discriminator (ADR-3180 Decision 2) alongside the value.
@@ -1043,9 +1060,9 @@ function extractCurrentMilestoneScoped(content: string, cwd?: string, ws?: strin
     const statePath = path.join(planningDir(cwd, ws), 'STATE.md');
     const stateRaw = platformReadSync(statePath);
     if (stateRaw !== null) {
-      const milestoneMatch = stateRaw.match(/^milestone:\s*(.+)/m);
-      if (milestoneMatch) {
-        const classified = classifyMilestoneScalar(milestoneMatch[1]);
+      const milestoneScalar = readStateMilestoneScalar(stateRaw);
+      if (milestoneScalar !== null) {
+        const classified = classifyMilestoneScalar(milestoneScalar);
         version = classified.version;
         stateAssertsNoMilestone = classified.explicitNull;
       }
@@ -1882,9 +1899,9 @@ function getMilestoneInfo(cwd?: string): { value: MilestoneInfo | null; scope: S
         const statePath = path.join(planningDir(cwd), 'STATE.md');
         const stateRaw = platformReadSync(statePath);
         if (stateRaw !== null) {
-          const m = stateRaw.match(/^milestone:\s*(.+)/m);
-          if (m) {
-            const classified = classifyMilestoneScalar(m[1]);
+          const milestoneScalar = readStateMilestoneScalar(stateRaw);
+          if (milestoneScalar !== null) {
+            const classified = classifyMilestoneScalar(milestoneScalar);
             explicitlyNoMilestone = classified.explicitNull;
             stateVersion = classified.version;
           }
@@ -2343,9 +2360,9 @@ function currentMilestoneRawRanges(
     const statePath = path.join(planningDir(cwd), 'STATE.md');
     const stateRaw = platformReadSync(statePath);
     if (stateRaw !== null) {
-      const milestoneMatch = stateRaw.match(/^milestone:\s*(.+)/m);
-      if (milestoneMatch) {
-        const classified = classifyMilestoneScalar(milestoneMatch[1]);
+      const milestoneScalar = readStateMilestoneScalar(stateRaw);
+      if (milestoneScalar !== null) {
+        const classified = classifyMilestoneScalar(milestoneScalar);
         version = classified.version;
         stateAssertsNoMilestone = classified.explicitNull;
       }
@@ -2400,6 +2417,7 @@ export = {
   getRoadmapPhaseInternal,
   getMilestoneInfo,
   classifyMilestoneScalar,
+  readStateMilestoneScalar,
   getMilestonePhaseFilter,
   currentMilestoneRawRanges,
   withPhaseSection,

src/state-document.cts

@@ -377,26 +377,59 @@ export function stateFieldContinuation(content: string, fieldName: string): stri
   if (!match) return null;
 
   // `(.+)` stops at the line terminator, so the field's line ends where the
-  // match does. JS `.` excludes \r as well as \n, so on a CRLF document the \r
-  // sits just AFTER the match rather than inside it — hence the strip below
-  // before testing for the newline.
-  const afterValue = match.index + match[0].length;
+  // match does.
+  return continuationAfter(content, match.index + match[0].length);
+}
+
+/**
+ * #4998: the continuation (as `stateFieldContinuation` defines it) of the line
+ * a single-line field write CHANGED, located from the edit itself — the first
+ * byte where `before` and `after` differ — so it is always the occurrence the
+ * writer actually touched, whichever label grammar or occurrence it matched.
+ * `null` when nothing changed, the edited line is the last line, or it is a
+ * pipe-table row (a table cell cannot wrap).
+ */
+export function editedLineContinuation(before: string, after: string): string | null {
+  if (before === after) return null;
+  const limit = Math.min(before.length, after.length);
+  let i = 0;
+  while (i < limit && before.charCodeAt(i) === after.charCodeAt(i)) i++;
+  const lineStart = before.lastIndexOf('\n', i - 1) + 1;
+  if (before.slice(lineStart).trimStart().startsWith('|')) return null;
+  const lineEnd = before.indexOf('\n', i);
+  return lineEnd === -1 ? null : continuationAfter(before, lineEnd);
+}
+
+/** The continuation lines following the line that ends at `afterValue`. */
+function continuationAfter(content: string, afterValue: number): string | null {
+  // JS `.` excludes \r as well as \n, so on a CRLF document the \r sits just
+  // AFTER a `(.+)` match rather than inside it — hence the strip below before
+  // testing for the newline.
   const rest = content.slice(afterValue).replace(/^\r/, '');
   if (!rest.startsWith('\n')) return null; // end of file: nothing follows
 
-  const lines = rest.slice(1).split('\n').map((line) => line.replace(/\r$/, ''));
-  const continuation: string[] = [];
-  for (let i = 0; i < lines.length; i++) {
+  const lines = rest.slice(1).split('\n');
+  const continuation = lines.slice(0, continuationLineCount(lines)).map((line) => line.replace(/\r$/, '').trim());
+  return continuation.length ? continuation.join(' ') : null;
+}
+
+/**
+ * How many of `following` — the lines directly below a single-line field —
+ * continue its value rather than starting the next construct.
+ */
+export function continuationLineCount(following: string[]): number {
+  const lines = following.map((line) => line.replace(/\r$/, ''));
+  let i = 0;
+  for (; i < lines.length; i++) {
     const line = lines[i];
     if (!line.trim()) break;
     if (MD_STRUCTURE_LINE_RE.test(line)) break;
     if (STATE_SIBLING_FIELD_LINE_RE.test(line)) break;
     // Look ahead one line: a setext underline below makes THIS line a heading
     // title, so stop before consuming it rather than after.
     if (i + 1 < lines.length && SETEXT_UNDERLINE_RE.test(lines[i + 1])) break;
-    continuation.push(line.trim());
   }
-  return continuation.length ? continuation.join(' ') : null;
+  return i;
 }
 
 export function stateExtractField(content: string, fieldName: string): string | null {