@opengsd/gsd-core 1.15.0 → 1.16.0

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

@@ -6,7 +6,7 @@
  * the legacy `## Task N` heading fallback — including the optional `tracker-id`
  * attribute, ADR-3646 Phase 1, read verbatim and never split here), planned-file
  * extraction, and the frontmatter-derived scheduling metadata (`wave`,
- * `depends_on`, `autonomous`, `agent_hint`, `files_modified`).
+ * `depends_on`, `autonomous`, `agent_hint`, `files_modified`, `gap_closure`).
  *
  * WHY THIS IS A LEAF MODULE. This logic was written inline inside
  * `cmdPhasePlanIndex` (`src/phase.cts`). Two commands in two different families
@@ -32,9 +32,23 @@
  * ADR-457 build-at-publish: source in src/plan-document.cts, compiled to
  * gsd-core/bin/lib/plan-document.cjs (gitignored).
  */
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const frontmatterMod = require("./frontmatter.cjs");
-const { extractFrontmatter } = frontmatterMod;
+// #5026 / ADR-4910 §1 absorption: the 7 frontmatter-derived scheduling fields
+// below, plus `objective` as an 8th (see `frontmatterField`'s own docblock),
+// read through `planning-document.cts`'s seam
+// (`readFrontmatterFieldsFromSource`) rather than calling `frontmatter.cts`'s
+// `extractFrontmatter` directly. This module has no canonical `.planning/`-root
+// artifact basename to gate `parsePlanningDoc` on (`*-PLAN.md` lives nested
+// under `.planning/phase/*/plans/`, and two of the five real callers hold only
+// in-memory content with no path at all), so it uses the entry point shaped
+// for exactly that: content in hand, no filename, no other `PlanningDoc`
+// capability (sections/tables/checklists) this module needs. The BULK form
+// (`readFrontmatterFieldsFromSource`, not the single-key
+// `readFrontmatterFieldFromSource`) is used deliberately: `parsePlanDocument`
+// reads several keys off the SAME document, and the single-key entry point
+// would independently re-detect the frontmatter span and re-parse the full
+// YAML once per key. See both functions' docblocks in `planning-document.cts`
+// for the full reasoning.
+const planning_document_cjs_1 = require("./planning-document.cjs");
 // ─── Frozen vocabularies ──────────────────────────────────────────────────────
 /**
  * How a task row was expressed in the document. `auto` is the ordinary
@@ -203,23 +217,80 @@ function extractObjective(content) {
 function planIdFromFile(planFile) {
     return planFile.replace('-PLAN.md', '').replace('PLAN.md', '');
 }
+/**
+ * The frontmatter keys `parsePlanDocument` reads: the 7 scheduling fields
+ * this absorption originally scoped (`wave`, `depends_on`, `autonomous`,
+ * `files_modified`/`files-modified`, `files_deleted`/`files-deleted`,
+ * `agent_hint`, `type` — 9 key spellings across those 7 fields), PLUS
+ * `objective` as an 8th field. `objective` is read through this SAME
+ * frontmatter-key-read path — not a deliberate exclusion, as an earlier
+ * revision of this comment claimed — because `parsePlanDocument`'s return
+ * statement below falls back to `frontmatterField(content, 'objective')`
+ * whenever the `<objective>` XML tag (`extractObjective`, unrelated and
+ * untouched by this absorption) is absent; it is included here simply
+ * because reading it is the exact same pattern as the other seven, and the
+ * migration below naturally covers it. `gap_closure` (#4924) is a 9th field,
+ * absorbed onto this same bulk-read seam by this fix rather than left on the
+ * removed `fm[key]` object-property read it was rebased in against.
+ */
+const FRONTMATTER_READ_KEYS = [
+    'wave',
+    'depends_on',
+    'autonomous',
+    'files_modified',
+    'files-modified',
+    'files_deleted',
+    'files-deleted',
+    'agent_hint',
+    'type',
+    'objective',
+    'gap_closure',
+];
+/**
+ * Read one top-level frontmatter key out of an already-bulk-read
+ * `Record<string, NodeRead>` (`readFrontmatterFieldsFromSource`'s return
+ * value, computed ONCE per `parsePlanDocument` call — see
+ * `FRONTMATTER_READ_KEYS`), unwrapped to the SAME shape a direct `fm[key]`
+ * object-property read would give: the field's value, or `undefined` when it
+ * is absent, the document has no frontmatter, or the frontmatter is
+ * unparseable — `readFrontmatterFieldsFromSource` reports all three of those
+ * as an `ok: false` result per key, and `extractFrontmatter`'s own object
+ * would likewise simply lack the key in every one of those cases.
+ */
+function frontmatterField(fields, key) {
+    const read = fields[key];
+    return read?.ok ? read.value : undefined;
+}
 /**
  * Parse one plan document.
  *
  * @param content  Raw `*-PLAN.md` text.
- * @param planPath Optional path, used only to name the file in `extractFrontmatter`'s
- *                 truncated-frontmatter diagnostic (#1882). Callers that do not have
- *                 one omit it — this default IS the shape production uses from the
- *                 read-only query path.
+ * @param planPath Historically the path passed to `extractFrontmatter`'s
+ *                 truncated-frontmatter diagnostic (#1882) — a stderr-only
+ *                 side channel, never part of this function's return value.
+ *                 #5026: the 9 frontmatter fields below (7 scheduling fields,
+ *                 plus `objective` and `gap_closure`) now read through
+ *                 `readFrontmatterFieldFromSource`, which has no path
+ *                 parameter, so this diagnostic's file-naming/dedup key is a
+ *                 documented, accepted side-effect-only regression (falls
+ *                 back to content-digest dedup, the same fallback
+ *                 `extractFrontmatter` already uses for the two real callers
+ *                 that never had a path to give it). Kept for call-site
+ *                 signature compatibility only.
  */
-function parsePlanDocument(content, planPath = '') {
-    const fm = extractFrontmatter(content, planPath);
+function parsePlanDocument(content, _planPath = '') {
     const xmlTasks = parseXmlTasks(content);
     const tasks = xmlTasks.length > 0 ? xmlTasks : parseMarkdownTasks(content);
-    const parsedWave = parseInt(fm['wave'], 10);
+    // Detect the frontmatter span and parse its YAML ONCE (#5026 follow-up: the
+    // prior per-key `frontmatterField(content, key)` calls each independently
+    // re-detected the span and re-parsed the full YAML from scratch — 10x
+    // redundant detection+parse per call). Every `frontmatterField` read below
+    // shares this SAME parsed result.
+    const fields = (0, planning_document_cjs_1.readFrontmatterFieldsFromSource)(content, FRONTMATTER_READ_KEYS);
+    const parsedWave = parseInt(frontmatterField(fields, 'wave'), 10);
     const declaredWave = Number.isNaN(parsedWave) ? null : parsedWave;
     let dependsOn = [];
-    const fmDeps = fm['depends_on'];
+    const fmDeps = frontmatterField(fields, 'depends_on');
     if (Array.isArray(fmDeps)) {
         dependsOn = fmDeps.map(String);
     }
@@ -227,37 +298,38 @@ function parsePlanDocument(content, planPath = '') {
         dependsOn = [fmDeps];
     }
     let autonomous = true;
-    if (fm['autonomous'] !== undefined) {
+    const fmAutonomous = frontmatterField(fields, 'autonomous');
+    if (fmAutonomous !== undefined) {
         // eslint-disable-next-line @typescript-eslint/no-base-to-string -- FrontmatterValue comparison
-        autonomous = fm['autonomous'] === 'true' || String(fm['autonomous']) === 'true';
+        autonomous = fmAutonomous === 'true' || String(fmAutonomous) === 'true';
     }
     let filesModified = [];
-    const fmFiles = fm['files_modified'] || fm['files-modified'];
+    const fmFiles = frontmatterField(fields, 'files_modified') || frontmatterField(fields, 'files-modified');
     if (fmFiles) {
         // eslint-disable-next-line @typescript-eslint/no-base-to-string -- FrontmatterValue scalar-to-string
         filesModified = Array.isArray(fmFiles) ? fmFiles.map(String) : [String(fmFiles)];
     }
     let filesDeleted = [];
-    const fmDeleted = fm['files_deleted'] || fm['files-deleted'];
+    const fmDeleted = frontmatterField(fields, 'files_deleted') || frontmatterField(fields, 'files-deleted');
     if (fmDeleted) {
         // eslint-disable-next-line @typescript-eslint/no-base-to-string -- FrontmatterValue scalar-to-string
         filesDeleted = Array.isArray(fmDeleted) ? fmDeleted.map(String) : [String(fmDeleted)];
     }
     let agentHint = null;
-    const fmAgentHint = fm['agent_hint'];
+    const fmAgentHint = frontmatterField(fields, 'agent_hint');
     if (fmAgentHint !== undefined) {
         // eslint-disable-next-line @typescript-eslint/no-base-to-string -- FrontmatterValue scalar-to-string
         const hintStr = String(fmAgentHint).trim();
         agentHint = hintStr !== '' ? hintStr : null;
     }
     let planType = null;
-    const fmType = fm['type'];
+    const fmType = frontmatterField(fields, 'type');
     if (fmType !== undefined) {
         // eslint-disable-next-line @typescript-eslint/no-base-to-string -- FrontmatterValue scalar-to-string
         planType = String(fmType);
     }
     return {
-        objective: extractObjective(content) || fm['objective'] || null,
+        objective: extractObjective(content) || frontmatterField(fields, 'objective') || null,
         type: planType,
         declaredWave,
         dependsOn,
@@ -265,6 +337,8 @@ function parsePlanDocument(content, planPath = '') {
         agentHint,
         filesModified,
         filesDeleted,
+        // extractFrontmatter yields every scalar as a string, so YAML `true` is 'true'.
+        gapClosure: frontmatterField(fields, 'gap_closure') === 'true',
         tasks,
         taskCount: tasks.length,
     };

package/gsd-core/bin/lib/plan-drift-guard.cjs

@@ -137,6 +137,11 @@ const PHASE_STATUS_RANKS = Object.freeze({
     'phase complete': 2,
     // ROADMAP.md "## Progress" table Status column vocabulary
     'not started': 0,
+    // #5060: `roadmap update-plan-progress`'s own written token (Phase Status
+    // Module's `toRoadmapStatusCell`) for a phase with plans but no summaries
+    // yet — rank 1, the same "work has started" rank as STATE's "ready to
+    // execute" / "in progress".
+    'planned': 1,
     'complete': 2,
     'deferred': 0,
 });

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

@@ -34,16 +34,21 @@ exports.PLANNING_ARTIFACTS = void 0;
 exports.parsePlanningDoc = parsePlanningDoc;
 exports.findField = findField;
 exports.readNode = readNode;
+exports.readFrontmatterField = readFrontmatterField;
+exports.readFrontmatterFieldFromSource = readFrontmatterFieldFromSource;
+exports.readFrontmatterFieldsFromSource = readFrontmatterFieldsFromSource;
 exports.setFieldValue = setFieldValue;
 exports.hasUnreadableNodes = hasUnreadableNodes;
 exports.serialize = serialize;
+exports.replaceProse = replaceProse;
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 const markdown_table_cjs_1 = require("./markdown-table.cjs");
 const artifacts_cjs_1 = require("./artifacts.cjs");
 // `frontmatter.cts` uses `export =` (CJS-style single export object), so it
 // is imported as a default import (esModuleInterop), not a named import.
 const frontmatter_cjs_1 = __importDefault(require("./frontmatter.cjs"));
-const { frontmatterRegion } = frontmatter_cjs_1.default;
+const frontmatter_fence_cjs_1 = require("./frontmatter-fence.cjs");
+const { extractFrontmatter, FRONTMATTER_UNPARSEABLE } = frontmatter_cjs_1.default;
 /**
  * Canonical `.planning/` root artifact basenames this seam recognises,
  * derived from the SAME registry `isCanonicalPlanningFile` consults
@@ -79,46 +84,28 @@ function splitLinesInfo(source) {
     return out;
 }
 /**
- * Locate the frontmatter block, if any, by COMPOSING `frontmatter.cts`'s
- * `frontmatterRegion` — the fence-detection grammar (byte-0 rule, BOM strip,
- * `\n---` search, CR handling) lives there, once, and this seam never
- * re-derives it (ADR-4910 Decision 1).
+ * Locate the frontmatter block, if any, from `locateFrontmatterFence` — the
+ * one owner of the fence grammar (byte-0 rule, BOM tolerance, whole-line
+ * closing fence, an adjacent empty block), which every frontmatter reader and
+ * writer also reads; this seam never re-derives it (ADR-4910 Decision 1).
  *
- * `frontmatterRegion` reports the YAML body's own bounds (`region`,
- * `terminated`, and the possibly BOM-stripped `content`), not this seam's
- * `Span` shape (an absolute byte range into the UNSTRIPPED `source`,
- * inclusive of both fences). This adapter translates one into the other by
- * reading ONLY the two boundary characters `frontmatterRegion` already
- * anchored (whether the YAML end / closing fence sit on a CRLF line) — it
- * does not re-scan for the fences themselves.
+ * The span is an absolute range into `source`, from the opening fence (after
+ * any BOM) through the closing fence line's text, plus that line's CR when it
+ * ends in CRLF. Found while implementing #5105: the previous adapter re-derived
+ * the closing fence's end from the YAML region's length and was one character
+ * long on an adjacent empty block (`---\n---\n`), which has no line of its own
+ * before the closer.
  */
 function findFrontmatterSpan(source) {
-    const found = frontmatterRegion(source);
-    if (!found)
+    const fence = (0, frontmatter_fence_cjs_1.locateFrontmatterFence)(source);
+    if (!fence)
         return null;
-    // `found.content` may be `source` with a single leading BOM stripped;
-    // every offset below is relative to `found.content`, so translate back to
-    // `source` coordinates by the same delta.
-    const bomDelta = source.length - found.content.length;
-    const content = found.content;
-    if (!found.terminated) {
-        return { span: { start: bomDelta, end: bomDelta + content.length }, terminated: false };
+    const start = fence.bom.length;
+    if (!fence.closed) {
+        return { span: { start, end: source.length }, terminated: false };
     }
-    // `frontmatterRegion` already did fence DETECTION — `found` being non-null
-    // and `terminated` IS that result. It reports only the YAML body's bounds
-    // (`region`), not an absolute span, so recover the closing fence's end
-    // from `region`'s length. The one thing still read directly here is the
-    // opening fence's fixed-width line ending (`\n` vs `\r\n`), needed to
-    // translate `region`'s length into a `content` offset — not a re-scan for
-    // the fence itself.
-    const headerEnd = content.startsWith('---\r\n') ? 5 : 4;
-    const yamlEnd = headerEnd + found.region.length;
-    const closingLineStart = content[yamlEnd] === '\r' ? yamlEnd + 1 : yamlEnd;
-    const fenceLineStart = closingLineStart + 1;
-    let fenceEnd = fenceLineStart + 3;
-    if (content[fenceEnd] === '\r')
-        fenceEnd += 1;
-    return { span: { start: bomDelta, end: bomDelta + fenceEnd }, terminated: true };
+    const end = fence.closingFenceEnd + (source[fence.closingFenceEnd] === '\r' ? 1 : 0);
+    return { span: { start, end }, terminated: true };
 }
 /** Build the set of 0-based line indices that fall inside a fenced code
  * block (opening/closing delimiter lines included), so `**Label:**`/table/
@@ -311,7 +298,10 @@ function parsePlanningDoc(source, artifact) {
         frontmatterEnd = fm.span.end;
     }
     if (source.length === 0) {
-        return { ok: true, value: { source, artifact, nodes: [], staged: new Map() } };
+        return {
+            ok: true,
+            value: { source, artifact, nodes: [], staged: new Map() },
+        };
     }
     const lines = splitLinesInfo(source);
     // Sections: one per heading, in document order — every heading is its own
@@ -333,7 +323,10 @@ function parsePlanningDoc(source, artifact) {
     }
     nodes.push(...scanBodyNodes(source, lines, frontmatterEnd));
     nodes.sort((a, b) => a.span.start - b.span.start);
-    return { ok: true, value: { source, artifact, nodes, staged: new Map() } };
+    return {
+        ok: true,
+        value: { source, artifact, nodes, staged: new Map() },
+    };
 }
 /** Find the id of the (first, document-order) `boldField` node whose label
  * exactly matches `label`, or `null` when none does. */
@@ -359,11 +352,206 @@ function readNode(doc, id) {
     }
     return { ok: true, value: doc.source.slice(node.span.start, node.span.end) };
 }
+/**
+ * Parse a frontmatter block's own span TEXT (fences included) via
+ * `frontmatter.cts`'s `extractFrontmatter`, exactly ONCE, returning either the
+ * parsed object or a `{ ok: false }` marker for the `FRONTMATTER_UNPARSEABLE`
+ * case. Split out of the single-key lookup below (#5026 follow-up) so a
+ * caller reading MULTIPLE keys off the SAME region
+ * (`readFrontmatterFieldsFromSource`) detects the span and parses its YAML
+ * once, not once per key — this function is the one and only place that
+ * detect-then-parse step happens; every reader (single-key or bulk) composes
+ * it rather than re-deriving it.
+ */
+function parseFrontmatterRegion(regionText) {
+    // A CRLF block's span ends on its closing fence line's CR (`findFrontmatterSpan`). That CR is
+    // half a line ending, not part of the fence: a `---` line ended by a lone CR does not close a
+    // block, so the text is parsed without it.
+    const fm = extractFrontmatter(regionText.endsWith('\r') ? regionText.slice(0, -1) : regionText);
+    if (fm[FRONTMATTER_UNPARSEABLE] === true) {
+        return { ok: false };
+    }
+    return { ok: true, value: fm };
+}
+/**
+ * Shared core of `readFrontmatterField` / `readFrontmatterFieldFromSource` /
+ * `readFrontmatterFieldsFromSource`: given an ALREADY-PARSED frontmatter
+ * result (`parseFrontmatterRegion`'s output) and the `Span` to report on
+ * failure, shape one `key`'s lookup as a `NodeRead`. Every reader composes
+ * this SAME shaping step — neither may duplicate it (the exact
+ * `DEFECT.GENERATIVE-FIX` class this epic exists to close).
+ *
+ * A region that failed to parse as YAML (`extractFrontmatter` reports this by
+ * returning `{}` carrying the `FRONTMATTER_UNPARSEABLE` Symbol, per that
+ * module's own documented contract) → `{ ok: false, reason:
+ * 'unparseable-frontmatter', span }`. A parseable region whose key is simply
+ * absent → `{ ok: false, reason: 'field-not-found', span }` —
+ * `extractFrontmatter` itself has no notion of "field not found" (a missing
+ * key just reads `undefined` off its returned object), so this reason string
+ * is this seam's own, not a passthrough of an upstream contract.
+ */
+function shapeFrontmatterField(parsed, span, key) {
+    if (!parsed.ok) {
+        return { ok: false, reason: 'unparseable-frontmatter', span };
+    }
+    const value = parsed.value[key];
+    if (value === undefined) {
+        return { ok: false, reason: 'field-not-found', span };
+    }
+    return { ok: true, value };
+}
+/** Single-key lookup: parse `regionText` once (`parseFrontmatterRegion`) and
+ * shape `key`'s result (`shapeFrontmatterField`). Used by `readFrontmatterField`
+ * and `readFrontmatterFieldFromSource`, which each already have the region's
+ * own text and span in hand; a caller reading several keys off one region
+ * should use `readFrontmatterFieldsFromSource` instead, to avoid re-parsing
+ * once per key. */
+function lookupFrontmatterField(regionText, span, key) {
+    return shapeFrontmatterField(parseFrontmatterRegion(regionText), span, key);
+}
+/**
+ * Read one top-level frontmatter key off an already-parsed `PlanningDoc`,
+ * composing `frontmatter.cts`'s `extractFrontmatter` rather than
+ * reimplementing YAML parsing (ADR-4910 Decision 1's precedent — the same
+ * composition `frontmatterRegion` already uses).
+ *
+ * No `FrontmatterNode` in `doc.nodes` (there is at most one per document) →
+ * `{ ok: false, reason: 'no-frontmatter', span: {0,0} }`, mirroring
+ * `findField`'s own not-found span convention (`readNode`'s unknown-id case).
+ *
+ * A `FrontmatterNode` is only ever pushed onto `doc.nodes` when its fence was
+ * terminated (`parsePlanningDoc` fails the whole document, before any node
+ * exists, on an unterminated fence) — so the "opened but never closed" case
+ * `extractFrontmatter` also handles is never reachable from an already-parsed
+ * `PlanningDoc` through this function. See `lookupFrontmatterField` for the
+ * unparseable-frontmatter / field-not-found / present result shapes.
+ */
+function readFrontmatterField(doc, key) {
+    const node = doc.nodes.find((n) => n.kind === 'frontmatter');
+    if (!node) {
+        return { ok: false, reason: 'no-frontmatter', span: { start: 0, end: 0 } };
+    }
+    const raw = doc.source.slice(node.span.start, node.span.end);
+    return lookupFrontmatterField(raw, node.span, key);
+}
+/**
+ * Read one top-level frontmatter key directly off raw `source` text, with no
+ * `PlanningDoc`/artifact-kind gate involved (#5026). `parsePlanningDoc`'s
+ * artifact-kind gate exists to distinguish "this document records nothing"
+ * from "wrong kind entirely" for a caller that might hand it any
+ * `.planning/`-root file, including a non-markdown one (config.json,
+ * state.json, …) — a risk that does not exist for a caller (`plan-document.
+ * cts`) that is ONLY ever invoked on real `*-PLAN.md` content, never on
+ * anything else, and is never given a canonical root-artifact basename to
+ * gate on in the first place (`*-PLAN.md` lives nested under
+ * `.planning/phase/*\/plans/`, never at the `.planning/` root
+ * `PLANNING_ARTIFACTS` enumerates — confirmed by execution:
+ * `isCanonicalPlanningFile('01-PLAN.md')` is `false`). This entry point
+ * routes around that gate rather than through it, for exactly that caller
+ * shape: content in hand, no filename to check, no need for any other
+ * `PlanningDoc` capability (sections/tables/checklists) this seam offers.
+ *
+ * Locates the frontmatter span via `findFrontmatterSpan` — the SAME
+ * `locateFrontmatterFence`-reading helper `parsePlanningDoc` itself uses to
+ * build a `FrontmatterNode` — so this is not a second detection mechanism,
+ * only a bypass of the node-parsing pipeline neither this caller nor its
+ * content needs.
+ *
+ * No frontmatter fence at byte 0 at all → `{ ok: false, reason:
+ * 'no-frontmatter', span: {0,0} }`, the same shape `readFrontmatterField`
+ * returns for its own not-found case. An OPENED-but-never-closed fence is
+ * reachable here (unlike `readFrontmatterField`, which can only ever see an
+ * already-terminated frontmatter node): `extractFrontmatter` treats that
+ * region as if it had none (`{}`, no `FRONTMATTER_UNPARSEABLE` marker), so
+ * every key on it comes back `field-not-found` — matching exactly what a
+ * direct `extractFrontmatter(source)[key] === undefined` check already
+ * produces for that same input today. See `lookupFrontmatterField` for the
+ * unparseable-frontmatter / field-not-found / present result shapes.
+ */
+function readFrontmatterFieldFromSource(source, key) {
+    const found = findFrontmatterSpan(source);
+    if (!found) {
+        return { ok: false, reason: 'no-frontmatter', span: { start: 0, end: 0 } };
+    }
+    const raw = source.slice(found.span.start, found.span.end);
+    return lookupFrontmatterField(raw, found.span, key);
+}
+/**
+ * Read MULTIPLE top-level frontmatter keys off raw `source` text in ONE pass
+ * — the bulk sibling of `readFrontmatterFieldFromSource`, for a caller (added
+ * for `plan-document.cts`'s `parsePlanDocument`, #5026 follow-up) that needs
+ * several keys off the SAME document. Calling `readFrontmatterFieldFromSource`
+ * once per key each independently re-detects the frontmatter span AND
+ * re-parses the full frontmatter YAML from scratch (`findFrontmatterSpan` +
+ * `parseFrontmatterRegion`, both non-trivial scans) — this function detects
+ * the span and parses the YAML exactly ONCE, then shapes every requested key
+ * off that SAME parsed result.
+ *
+ * This is a second ENTRY POINT into the one shared detect-span +
+ * parse-YAML + shape-a-key pipeline (`findFrontmatterSpan` /
+ * `parseFrontmatterRegion` / `shapeFrontmatterField`), never a second parser:
+ * per-key result shapes are byte-identical to calling
+ * `readFrontmatterFieldFromSource` once per key (same `no-frontmatter` /
+ * `unparseable-frontmatter` / `field-not-found` / present shapes, same span).
+ */
+function readFrontmatterFieldsFromSource(source, keys) {
+    const found = findFrontmatterSpan(source);
+    const out = {};
+    if (!found) {
+        const span = { start: 0, end: 0 };
+        for (const key of keys)
+            out[key] = { ok: false, reason: 'no-frontmatter', span };
+        return out;
+    }
+    const raw = source.slice(found.span.start, found.span.end);
+    const parsed = parseFrontmatterRegion(raw);
+    for (const key of keys)
+        out[key] = shapeFrontmatterField(parsed, found.span, key);
+    return out;
+}
 /**
  * Stage a new value for a `boldField` node, returning a NEW `PlanningDoc`
  * (immutable — `doc` itself is never mutated). Refuses an id this doc did
- * not mint, and refuses any node kind other than `boldField` — only the
+ * not mint, and refuses any node kind other than `boldField` — only
  * `valueSpan` is ever writable this phase (ADR-4910 §1).
+ *
+ * #5007 / ADR-4910 Phase 6: a prior amendment here added a `{ allowSeparator:
+ * true }` escape hatch that spliced the caller's value across the FULL
+ * rest-of-line span (`valueSpan.start`..`trailingSpan.end`) to let a value
+ * legitimately containing the grammar's ` — ` trailing-separator token
+ * (`TRAILING_SEPARATOR_RE`) be written without triggering the round-trip
+ * refusal below. That option was REMOVED (still #5007, same phase) after a
+ * failing-first reproduction proved it only avoided the refusal AT WRITE
+ * TIME: the written bytes are correct, but `parseBoldFieldLine` splits on
+ * ` — ` unconditionally and without any escaping/metadata to distinguish
+ * "atomic value containing the token" from "value plus hand-annotation" —
+ * the same input shape either way. So the NEXT fresh `parsePlanningDoc` of
+ * that exact text (not the in-memory `doc` the option's own tests checked)
+ * silently re-truncates the value and demotes the rest to `trailingSpan`,
+ * with `findField`/`readNode` reporting a confident, wrong `ok: true`
+ * result and no error — reproduced live: staging `"Phase — COMPLETE"` this
+ * way, serializing, and re-parsing the output through a fresh
+ * `parsePlanningDoc` read back `"Phase"` via `readNode`, silently losing
+ * ` — COMPLETE`. This is exactly the #4917 finding-2 corruption this
+ * module's round-trip check exists to prevent, just moved one parse cycle
+ * downstream of where the check could still catch it. There is no escaping
+ * convention anywhere in this grammar (`BOLD_FIELD_RE`/`TRAILING_SEPARATOR_
+ * RE` are unconditional, unversioned regexes with no metadata channel), and
+ * `TRAILING_SEPARATOR_RE`'s split is relied on by every other reader of this
+ * seam (`findField`/`readNode`, used today for ROADMAP.md's `Plans`/
+ * `Depends on` fields) — narrowing or version-gating it here would be a
+ * grammar change with its own blast radius, not a local bug fix. Widening
+ * `setFieldValue`'s PUBLIC, shared contract to include a write path that is
+ * only safe for a caller who never reads the field back through this same
+ * module is an attractive nuisance: nothing stops a future `findField`/
+ * `readNode` caller from reaching for it and hitting this exact corruption.
+ * The one real caller (`stateReplaceField`, src/state-document.cts) never
+ * reads STATE.md fields back through `parsePlanningDoc`/`findField` (it uses
+ * `stateExtractField`'s own non-splitting regex instead), so it does its own
+ * local full-rest-of-line splice directly against `content`, using this
+ * module only to LOCATE the field's spans — keeping the dangerous affordance
+ * out of this shared seam's public surface entirely, rather than fixing it
+ * with a narrower version of the same false-safety option.
  */
 function setFieldValue(doc, id, value) {
     const node = doc.nodes.find((n) => n.id === id);
@@ -411,7 +599,10 @@ function setFieldValue(doc, id, value) {
     }
     const staged = new Map(doc.staged);
     staged.set(id, value);
-    return { ok: true, value: { source: doc.source, artifact: doc.artifact, nodes: doc.nodes, staged } };
+    return {
+        ok: true,
+        value: { source: doc.source, artifact: doc.artifact, nodes: doc.nodes, staged },
+    };
 }
 /** True when any node in `doc` failed to parse. */
 function hasUnreadableNodes(doc) {
@@ -455,5 +646,47 @@ function serialize(doc) {
     out += doc.source.slice(cursor);
     return { ok: true, value: out };
 }
+/**
+ * Replace every occurrence of the single-line literal `from` with `to` in the
+ * document's prose — the seam's answer to a verbatim cross-reference rewrite
+ * (ADR-5057 §6, Phase 13, #5217: the migration's "Phase 1:" -> "Phase 1-01:"
+ * substitution in PROJECT.md / STATE.md).
+ *
+ * Fenced code blocks are never rewritten (rows 9/14: fenced content is not a
+ * node), every other byte — each line's own terminator included — is copied
+ * from `doc.source`, and a substitution that changes nothing returns a doc
+ * whose `source` is byte-identical. The result is re-parsed so its node spans
+ * describe the new text. Refuses (Result failure, nothing written) when `from`
+ * is empty or spans a line break, or when `doc` already carries staged
+ * field edits (their spans address the pre-substitution text).
+ */
+function replaceProse(doc, from, to) {
+    if (typeof from !== 'string' || from.length === 0) {
+        return { ok: false, reason: 'replaceProse: `from` must be a non-empty string' };
+    }
+    if (typeof to !== 'string' || /[\r\n]/.test(from) || /[\r\n]/.test(to)) {
+        return { ok: false, reason: 'replaceProse: `from` and `to` must be single-line strings' };
+    }
+    if (doc.staged.size > 0) {
+        return { ok: false, reason: 'replaceProse: refused while field edits are staged' };
+    }
+    const lines = splitLinesInfo(doc.source);
+    const fenced = fencedLineIndices(lines);
+    let out = '';
+    let cursor = 0;
+    let changed = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (fenced.has(i) || !line.text.includes(from))
+            continue;
+        out += doc.source.slice(cursor, line.start) + line.text.split(from).join(to);
+        cursor = line.end;
+        changed = true;
+    }
+    if (!changed)
+        return { ok: true, value: doc };
+    out += doc.source.slice(cursor);
+    return parsePlanningDoc(out, doc.artifact);
+}
 // Consumers: require('../gsd-core/bin/lib/planning-document.cjs')
 // Named CJS exports are the canonical surface (ADR-457 .cts → .cjs build-at-publish).