@opengsd/gsd-core 1.12.0 → 1.13.0

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

@@ -75,6 +75,215 @@ const bulletTitledColonRe = /^\s*-\s+\*\*D-([A-Za-z0-9][A-Za-z0-9_-]*)(?:\s*\[([
  * shape without hardcoding the `D`.
  */
 const boldLeadInBulletRe = /^\s*-\s+\*\*[A-Z]+[0-9]*-[A-Za-z0-9]/m;
+/**
+ * #3939: a decision bullet's DECLARATION line — the `- **D-NN … **` bold lead-in
+ * the three grammars above anchor on — may wrap across a line break. Physical
+ * line breaks inside a bullet are markdown-insignificant, and GSD's own
+ * discuss-phase writer emits the wrapped shape whenever a decision title runs
+ * past the wrap column. All three grammars require the closing `**` in the same
+ * string as the `- **D-` anchor, so a wrapped declaration matched none of them
+ * and fell to the #1365 parse-miss guard, forcing `could-not-parse` (which
+ * hard-blocks `check.decision-coverage-plan`) on a well-formed CONTEXT.md.
+ *
+ * The repair is confined to how the LOGICAL bullet is assembled — the grammars
+ * themselves are untouched, so every single-line form parses exactly as before.
+ */
+const decisionBulletStartRe = /^\s*-\s+\*\*D-/;
+/**
+ * A line that opens a new BLOCK-LEVEL construct, and therefore terminates the
+ * bullet above it: a list marker of any family (`-`, `*`, `+`, `1.`, `1)`), an
+ * ATX heading, a blockquote, or a table row. Joining never reaches across one of
+ * these (nor across a blank/whitespace-only line, checked separately), so a
+ * declaration whose bold run genuinely never closes cannot absorb the block
+ * below it and get "closed" by an unrelated inline `**` — it stays a parse-miss
+ * and still fails loud, which #1365's contract requires.
+ *
+ * The four MARKER families demand trailing whitespace so that a continuation
+ * line opening with emphasis (`*in* the header.** …`) is text, not a bullet.
+ * The table-row alternative deliberately does not: CommonMark tables may open
+ * flush (`|Col1|Col2|`), and a leading `|` is never ordinary decision prose.
+ * A `- ` line at ANY indent stops the join: a deeper one is #3169 nested
+ * elaboration, which the main loop folds into the open decision itself.
+ *
+ * DELIBERATE DIVERGENCE from the sectionizer seam (ADR-1372): `iterateBullets`
+ * recognises only the `N. ` ordered-list form (`numberedRe`,
+ * src/markdown-sectionizer.cts), while this set also stops at the `N) ` form.
+ * That is intentional and one-directional — this regex answers "may the join
+ * cross this line?", where recognising MORE block openers is the conservative
+ * answer (a missed terminator can manufacture a decision; a spare one can only
+ * make a malformed bullet fail loud, which #1365 already wants). `N)` is a
+ * CommonMark ordered-list marker, so a join must not reach across it whether or
+ * not the seam's own bullet iterator yields it. Both forms are pinned by tests,
+ * and a drift test asserts the seam still does NOT treat `N)` as a bullet, so
+ * this divergence stays visible if either side moves.
+ *
+ * Accepted over-termination: continuation prose that happens to open with
+ * digits-then-`.`/`)` ("10. really keeps going") or a literal `|` stops the join
+ * early, so such a bullet fails loud rather than parsing. That is the same
+ * markdown ambiguity every line-oriented reader carries, and this direction of
+ * the trade is the one #1365 asks for — fail loud, never guess.
+ */
+const blockConstructRe = /^(?:[-*+]\s|\d+[.)]\s|#{1,6}\s|>\s|\|)/;
+/**
+ * The id-adjacent `[tags]` REGION of a logical bullet, as far as it has been
+ * assembled. Matching means the region is still unsettled, in one of two ways:
+ * capture group 1 is present when the bracket is open (group 1 is the content
+ * seen so far), and absent when the id has been read but no `[` has followed
+ * yet — so a bracket may still open on the next absorbed line.
+ *
+ * A NON-match means the region is settled for good: the bracket closed, or
+ * something other than `[` followed the id. Either way the join no longer has
+ * to watch for a splice.
+ *
+ * The id character class is deliberately looser than the grammars' (it admits
+ * an empty id, so a bare `- **D-` still counts as unsettled). This regex only
+ * answers "may an id-adjacent bracket still open here?", where recognising MORE
+ * shapes is the conservative direction: an over-broad match can only make a
+ * malformed bullet fail loud, while a missed one silently re-classifies.
+ *
+ * Only the ID-ADJACENT bracket matters: that is the one the three grammars turn
+ * into `tags` (and therefore into `trackable`). A `[` further along the title is
+ * ordinary text and does not restrict the join.
+ */
+const tagRegionRe = /^\s*-\s+\*\*D-[A-Za-z0-9_-]*\s*(?:\[([^\]]*))?$/;
+/**
+ * #3939 (review): would folding `next` onto a lead-in whose `[tags]` bracket is
+ * still open splice the inserted space INTO a tag token?
+ *
+ * Tags are comma-split and trimmed, so a space landing next to a delimiter
+ * (`[`, `,`, `]`) changes nothing — `[informational,` + `deferred]` is still
+ * exactly `[informational, deferred]`. A space landing anywhere else splits one
+ * token into two (`[defer` + `red]` → `defer red`), which would not fail; it
+ * would parse to a DIFFERENT tag, silently flipping `trackable` on a gate that
+ * decides whether a decision must be covered. Refusing to join there leaves the
+ * bullet unchanged, so it reaches the #1365 parse-miss guard and fails loud —
+ * a wrong answer about coverage is worse than a blocked gate.
+ *
+ * `tail` is the bracket content accumulated so far, `next` the trimmed
+ * continuation line.
+ */
+function wouldSpliceTagToken(tail, next) {
+    const before = tail.trimEnd();
+    if (before === '' || before.endsWith(',') || before.endsWith('['))
+        return false;
+    return !(next.startsWith(',') || next.startsWith(']'));
+}
+/**
+ * True when the bullet's own bold lead-in — the FIRST bold run on the line —
+ * is still open at end-of-line. Deliberately asks only about that first run
+ * (not `**`-parity over the whole string), because that is the run the three
+ * grammars anchor on: a balanced inline `**bold**` later in the body must not
+ * make a terminated lead-in look open.
+ */
+function boldLeadInIsUnterminated(text) {
+    const open = text.indexOf('**');
+    if (open === -1)
+        return false;
+    return text.indexOf('**', open + 2) === -1;
+}
+/**
+ * Fold a decision bullet whose bold lead-in wraps into ONE logical line, so the
+ * declaration grammars see the whole lead-in (#3939).
+ *
+ * Bounded and fail-loud-preserving: a wrapped declaration absorbs following
+ * lines only until its lead-in closes, and a blank/whitespace-only line, a new
+ * block-level construct (`blockConstructRe`), or the end of the block stops it.
+ * If the lead-in never closes, the original line is emitted UNCHANGED — a
+ * genuinely malformed bullet (e.g. an unterminated bold run) still reaches the
+ * parse-miss guard and still fails loud, exactly as #1365 requires. Non-decision
+ * lines pass through untouched, so continuation lines (#1372 FIX) and nested
+ * cross-reference bullets (#3169) are handled by the main loop as before.
+ *
+ * The joined line keeps the FIRST physical line's leading whitespace, so the
+ * `indentWidth` signal #3169 depends on is unchanged. Absorbed lines are
+ * trimmed and re-joined with a single space, which is what a soft line break
+ * means in markdown — so the join reproduces the rendered one-line text rather
+ * than concatenating the raw bytes.
+ *
+ * One place that equivalence does not hold is inside the id-adjacent `[tags]`
+ * bracket, where an inserted space can split a tag token and silently flip
+ * `trackable`. The join stops there instead (`wouldSpliceTagToken`), leaving the
+ * bullet to fail loud.
+ *
+ * Absorption stops at the first `**` on a continuation line, so an inline
+ * `**bold**` INSIDE a wrapped title closes the run early. That is deliberate:
+ * the result is byte-identical to what the same bullet written on one physical
+ * line parses to (the text past the early close re-attaches through the main
+ * loop's continuation folding), which is the whole contract here — wrapping is
+ * markdown-insignificant, never a second grammar.
+ */
+function joinWrappedBoldLeadIns(lines) {
+    const joined = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (!decisionBulletStartRe.test(line) || !boldLeadInIsUnterminated(line)) {
+            joined.push(line);
+            continue;
+        }
+        // Absorbed lines accumulate as SEGMENTS joined by a single space, and each
+        // new segment is searched on its own: the lead-in is known to be open at the
+        // end of the declaration line, and the inserted space means a closing `**`
+        // can never straddle a segment boundary, so the first `**` in any later
+        // segment is the close. Scanning per segment (rather than re-searching the
+        // accumulated string, which forces a rope flatten every iteration) keeps a
+        // long unterminated run linear on the plan gate's hot path.
+        const segments = [line];
+        // Bracket content accumulated while the id-adjacent `[tags]` bracket is
+        // still open; null when it is not open. O(1) per segment.
+        let tagTail = null;
+        // The logical text assembled so far, kept ONLY while the id-adjacent
+        // bracket has yet to open, so a bracket that opens on ANY absorbed line
+        // arms the splice guard — not just one that opens on the declaration line.
+        // Null once the region settles (the bracket opened and `tagTail` took over,
+        // or the id was followed by something else), so this never re-walks a long
+        // absorption: a non-empty segment that is not a bracket-open settles the
+        // region immediately, which bounds the string to a single extra join.
+        let tagRegion = null;
+        const declRegion = tagRegionRe.exec(line);
+        if (declRegion !== null) {
+            if (declRegion[1] === undefined)
+                tagRegion = line;
+            else
+                tagTail = declRegion[1];
+        }
+        let scan = i + 1;
+        let closed = false;
+        while (scan < lines.length) {
+            const trimmed = lines[scan].trim();
+            if (trimmed === '' || blockConstructRe.test(trimmed))
+                break;
+            if (tagTail !== null && wouldSpliceTagToken(tagTail, trimmed))
+                break;
+            segments.push(trimmed);
+            scan += 1;
+            if (tagTail !== null) {
+                tagTail = trimmed.indexOf(']') === -1 ? trimmed : null;
+            }
+            else if (tagRegion !== null) {
+                tagRegion = `${tagRegion} ${trimmed}`;
+                const opened = tagRegionRe.exec(tagRegion);
+                if (opened === null)
+                    tagRegion = null;
+                else if (opened[1] !== undefined) {
+                    tagTail = opened[1];
+                    tagRegion = null;
+                }
+            }
+            if (trimmed.indexOf('**') !== -1) {
+                closed = true;
+                break;
+            }
+        }
+        if (closed) {
+            joined.push(segments.join(' '));
+            i = scan - 1;
+        }
+        else {
+            joined.push(line);
+        }
+    }
+    return joined;
+}
 /**
  * Parse decision lines from a block of text (the inner text of a <decisions>
  * or markdown-header section body). Returns the extracted decisions and a count
@@ -83,9 +292,12 @@ const boldLeadInBulletRe = /^\s*-\s+\*\*[A-Z]+[0-9]*-[A-Za-z0-9]/m;
  * FIX B (#1365): parseMisses > 0 means the caller must treat the result as
  * could-not-parse even when some decisions were extracted — a silent drop is
  * worse than a fail-loud signal.
+ *
+ * #3939: physical lines are folded into logical bullets first, so a declaration
+ * whose bold lead-in wraps is matched as the one bullet it is.
  */
 function parseDecisionLines(block) {
-    const lines = block.split(/\r?\n/);
+    const lines = joinWrappedBoldLeadIns(block.split(/\r?\n/));
     const out = [];
     let category = '';
     let inDiscretion = false;

package/gsd-core/bin/lib/edge-probe.cjs

@@ -110,6 +110,15 @@ function validateRequirement(requirement) {
     if (r.shapes == null && !(typeof r.text === 'string' && r.text.trim())) {
         throw new Error(`requirement ${requirement.id} text must be a non-empty string when no shapes override is provided`);
     }
+    // text_en (#3717) is optional, but when present it must be a non-empty string. An empty
+    // string is NOT caught by `??` (only null/undefined are), so an unvalidated `text_en: ''`
+    // would silently win `text_en ?? text` and classify against '' — the same fail-open shape
+    // #1110/#2773 already exist to eliminate, just moved one field over. Validated
+    // unconditionally (not gated on whether `shapes` will make it unused) so bad data fails
+    // closed even when it happens to be dead for this particular call.
+    if (r.text_en != null && !(typeof r.text_en === 'string' && r.text_en.trim())) {
+        throw new Error(`requirement ${requirement.id} text_en must be a non-empty string when present`);
+    }
 }
 /** Validate an edge resolution against the edge verification vocabulary. */
 function validateResolution(resolution) {
@@ -135,7 +144,11 @@ function proposeEdges(requirement) {
         shapes = requirement.shapes;
     }
     else {
-        shapes = classifyShape(requirement.text);
+        // #3717: prefer the English translation when present — SHAPE_CUES are English-only
+        // word-boundary patterns, so a non-English `text` (e.g. response_language projects)
+        // would otherwise classify to zero shapes. validateRequirement (called above) has
+        // already guaranteed text_en, if present, is a non-empty string.
+        shapes = classifyShape(requirement.text_en ?? requirement.text);
         if (shapes.length === 0) {
             // Prose present but no shape cue matched. Do NOT silently drop it (#1110): an
             // edge-relevant requirement whose phrasing missed every cue would otherwise vanish from

package/gsd-core/bin/lib/file-overlap-partitioner.cjs

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * File-overlap partitioner — shared greedy first-fit stage assignment (#3674).
+ *
+ * Extracted from `claude-orchestration.cts`'s `partitionStages` (#1143), which
+ * emits sequential Workflow `parallel()` stage barriers so that no two plans
+ * sharing a `files_modified` entry ever cohabit a stage. This module is the
+ * SAME algorithm, generalized: it depends on no `Plan`/`Wave` interface from
+ * `claude-orchestration.cts` (or any other caller-specific shape), so a future
+ * consumer (quick-batch, #3675 / ADR-1239 "Quick-batch binding") can partition
+ * its own planned-path items without pulling in orchestration internals.
+ *
+ * This is a pure, behavior-preserving extraction (#3674's acceptance bar is
+ * byte-identical output for `claude-orchestration.cts`'s existing callers —
+ * not an improvement). Explicitly OUT of scope, per the #3674 design lock:
+ *   - dependency-DAG ordering — this module only ever sees a flat item list
+ *     and file-overlap; a caller resolves dependency order before calling in
+ *     (same contract `partitionStages` already had);
+ *   - path normalization — file entries are compared by exact string equality
+ *     only. `Foo.ts` vs `foo.ts`, or `src/a.ts` vs `src\a.ts`, are treated as
+ *     DISTINCT files. This is deliberate, not a gap to "fix" during extraction;
+ *   - filesystem access — this module never reads a path off disk.
+ *
+ * Zero external dependencies. Pure function. Never throws on well-typed input.
+ */
+/**
+ * Partition `items` into a near-minimal number of sequential stages (via
+ * greedy first-fit — not guaranteed optimal for arbitrary overlap graphs, but
+ * correct: no two items sharing a file ever cohabit a stage) such that no two
+ * items in the same stage share a file. Each item goes into the earliest
+ * stage where it does not overlap any item already there, in input order.
+ *
+ * An item with an EMPTY `files` array declares no files; it overlaps nothing
+ * and coalesces into stage 0 (mirrors `partitionStages`' original behavior —
+ * this module cannot guard against undeclared concurrent writes; a caller
+ * must declare `files` accurately).
+ *
+ * File comparison is EXACT STRING EQUALITY — no path normalization, no
+ * case-folding, no separator canonicalization. Duplicate `id`s in the input
+ * are NOT deduplicated; each item is placed independently, in input order.
+ *
+ * Deterministic: identical input (including input order) always yields an
+ * identical partition.
+ */
+function partitionByFileOverlap(items) {
+    const stages = [];
+    for (const item of items) {
+        const fileSet = new Set(item.files);
+        let placed = false;
+        for (const stage of stages) {
+            let overlap = false;
+            for (const f of fileSet) {
+                if (stage.files.has(f)) {
+                    overlap = true;
+                    break;
+                }
+            }
+            if (!overlap) {
+                stage.items.push(item);
+                for (const f of fileSet)
+                    stage.files.add(f);
+                placed = true;
+                break;
+            }
+        }
+        if (!placed) {
+            stages.push({ items: [item], files: new Set(fileSet) });
+        }
+    }
+    return stages.map((s) => s.items.map((i) => i.id));
+}
+module.exports = {
+    partitionByFileOverlap,
+};

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

@@ -652,46 +652,137 @@ function countTopLevelKeyShapedLines(region) {
  *   key its deduplication. Optional because this function has 50-odd call sites and several
  *   hold only an in-memory string; those dedup on a content digest instead.
  */
-function extractFrontmatter(content, sourcePath) {
+/**
+ * The frontmatter REGION of a document: the text between the opening `---`
+ * fence at byte 0 and its closing fence.
+ *
+ * One fence parser, not two (#3850 review round 2, B1). `extractFrontmatter`
+ * and `frontmatterListEntries` need the identical answer to "where does the
+ * frontmatter start and stop" — same BOM tolerance (#2977), same byte-0-only
+ * fence rule, same CR handling before the closing fence — and differ only in
+ * what they do with the region text afterwards. A second copy of this logic is
+ * the `DEFECT.GENERATIVE-FIX` shape: it silently stops agreeing the first time
+ * either is taught something.
+ *
+ * `terminated: false` is the fence-opened-but-never-closed case. It is not an
+ * error here because the two callers disagree about it: `extractFrontmatter`
+ * runs the #1882 truncation probe over the region and may warn, while
+ * `frontmatterListEntries` has no array to return and gives up. So the shape
+ * is reported and the decision is left to them.
+ *
+ * `content` is returned alongside because it is the BOM-STRIPPED text, and a
+ * caller reporting on the document (the truncation diagnostic) must describe
+ * the same bytes the offsets were computed against.
+ */
+function frontmatterRegion(content) {
     // #2977: tolerate a single leading UTF-8 BOM (U+FEFF), which Windows tooling
-    // (PowerShell `>`/`Out-File` on PS 5.1, several editors) writes by default. Without this
-    // strip, the byte-0 `startsWith('---')` fence check below fails on the BOM and the whole
-    // parse collapses to {} — every frontmatter field silently disappears, and the engine
-    // proceeds as though the file had no frontmatter at all. The BOM is a single codepoint;
-    // stripping it here restores byte-0 alignment so the rest of the function is unchanged.
-    // Scope: BOM only. Arbitrary non-BOM content before the fence (leading whitespace/blank
-    // line/comment) is a separate product-intent decision (tolerate vs diagnose) left to a
-    // future change — this fix does not broaden the byte-0 fence rule beyond the BOM.
-    if (content.charCodeAt(0) === 0xFEFF) {
+    // (PowerShell `>`/`Out-File` on PS 5.1, several editors) writes by default.
+    // Without this strip, the byte-0 `startsWith('---')` fence check below fails
+    // on the BOM and the whole parse collapses — every frontmatter field silently
+    // disappears, and the engine proceeds as though the file had no frontmatter
+    // at all. The BOM is a single codepoint; stripping it here restores byte-0
+    // alignment. Scope: BOM only. Arbitrary non-BOM content before the fence
+    // (leading whitespace/blank line/comment) is a separate product-intent
+    // decision (tolerate vs diagnose) left to a future change.
+    if (content.charCodeAt(0) === 0xFEFF)
         content = content.slice(1);
-    }
-    // Match frontmatter only at byte 0 — a `---` block later in the document
-    // body (YAML examples, horizontal rules) must never be treated as frontmatter.
+    // Match frontmatter only at byte 0 — a `---` block later in the document body
+    // (YAML examples, horizontal rules) must never be treated as frontmatter.
     const headerEnd = content.startsWith('---\r\n') ? 5 : content.startsWith('---\n') ? 4 : -1;
     if (headerEnd === -1)
-        return {};
+        return null;
     const closingLineStart = content.indexOf('\n---', headerEnd);
     if (closingLineStart === -1) {
-        const region = content.slice(headerEnd);
-        const keyCount = countKeysBeforeTruncation(region);
-        if (keyCount >= UNTERMINATED_KEY_THRESHOLD && isFrontmatterShaped(region)) {
+        return { region: content.slice(headerEnd), terminated: false, content };
+    }
+    const yamlEnd = content[closingLineStart - 1] === '\r' ? closingLineStart - 1 : closingLineStart;
+    return { region: content.slice(headerEnd, yamlEnd), terminated: true, content };
+}
+function extractFrontmatter(content, sourcePath) {
+    // Fence location (BOM strip, byte-0 rule, CR handling) lives in
+    // `frontmatterRegion` so this and `frontmatterListEntries` cannot drift
+    // apart on where the frontmatter is.
+    const found = frontmatterRegion(content);
+    if (!found)
+        return {};
+    if (!found.terminated) {
+        const keyCount = countKeysBeforeTruncation(found.region);
+        if (keyCount >= UNTERMINATED_KEY_THRESHOLD && isFrontmatterShaped(found.region)) {
             warnUnusableInput({
                 reason: UNUSABLE_REASON.FRONTMATTER_UNTERMINATED,
                 source: sourcePath,
-                content,
+                content: found.content,
             });
         }
         return {};
     }
-    const yamlEnd = content[closingLineStart - 1] === '\r' ? closingLineStart - 1 : closingLineStart;
-    const region = content.slice(headerEnd, yamlEnd);
     try {
-        return parseGuardedYamlRegion(region);
+        return parseGuardedYamlRegion(found.region);
     }
     catch {
         return unparseableResult();
     }
 }
+/**
+ * The entries of a top-level frontmatter ARRAY key, VERBATIM — as the values
+ * YAML actually describes rather than the display-flattened strings
+ * `extractFrontmatter` returns (#3850).
+ *
+ * `extractFrontmatter` renders each object entry for HUMANS —
+ * `normalizeParsedValue` maps `{test, resolution}` to `"test: …, resolution: …"`
+ * via `flattenObjectListItem`. That is the right contract for a reader printing
+ * a list, and the wrong one for a reader that needs to branch on a specific
+ * field: `status`, `resolution` and `reason` are recoverable from that string
+ * only by re-parsing prose, which cannot distinguish a real `resolution:` field
+ * from the same text inside a quoted `truth:`.
+ *
+ * This returns the same entries BEFORE that display step, off the same
+ * `extractFrontmatter` parse path — same BOM strip (#2977), same byte-0 fence
+ * rule (shared via `frontmatterRegion`), same anchor/alias and sentinel guards,
+ * same ambiguous-colon repair. It is deliberately NOT a second parser: a
+ * hand-rolled fence regex or entry slicer re-loses whatever the real one
+ * learned, which is the `DEFECT.GENERATIVE-FIX` shape.
+ *
+ * EVERY element is returned, at its own index, whatever its type (#3850 review
+ * round 3, Blocker). An earlier revision filtered to objects, which compacted
+ * the array: a caller numbering entries by array position then numbered the
+ * SURVIVORS, so a list mixing object and non-object entries lost rows outright
+ * and mis-numbered the rest — the same silently-vanishing-row defect this whole
+ * issue exists to close, triggered by entry shape instead of file status.
+ * Deciding what a non-object entry MEANS is a caller's judgement (the two
+ * readers in `uat.cts` answer it differently and both are right for their own
+ * vocabulary); dropping it is nobody's.
+ *
+ * Returns `null` when the document has no frontmatter, the frontmatter is
+ * unterminated or unparseable, the key is absent, or the key is not an array —
+ * "nothing to iterate" cases the caller should not have to tell apart.
+ */
+function frontmatterListEntries(content, key) {
+    const found = frontmatterRegion(content);
+    if (!found || !found.terminated)
+        return null;
+    let raw;
+    try {
+        refuseAnchorsAndAliases(found.region);
+        refuseIfSentinelPresent(found.region);
+        raw = restoreNullBytesDeep(loadWithAmbiguousColonRepair(escapeNullBytesForParse(found.region)));
+    }
+    catch {
+        // Same posture as `extractFrontmatter`: an unparseable region is "no
+        // frontmatter", never a throw into a caller that was only reading a field.
+        return null;
+    }
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const value = raw[key];
+    // `Array.isArray` narrows an `unknown` to `any[]`, and returning that
+    // unchecked is how `any` escapes a guarded parser into every caller. The
+    // element type genuinely IS unknown here — that is the point of this
+    // function — so say so.
+    if (!Array.isArray(value))
+        return null;
+    return value;
+}
 /**
  * Escape a string for emission inside a YAML double-quoted scalar (#1779). ADR-3473 §8.1
  * (#3881): routed through the vendored js-yaml's `dump()` (forced double-quoted style) rather
@@ -816,6 +907,22 @@ function agentScalarNeedsDoubleQuoting(s) {
         return true;
     return false;
 }
+/**
+ * #4053 — Quote a numeric-looking scalar that is not all-digit (`22.10`,
+ * `1.0`, `1e3`, `0x1F`) so a spec YAML reader keeps it a string: bare `22.10`
+ * reloads as the float 22.1 and collides with `22.1`, a different phase.
+ *
+ * All-digit strings stay bare as a deliberate, scoped trade-off — not a
+ * safety guarantee. A leading-zero value (`02`, `017`) also mis-parses under
+ * a spec reader (to 2, 17). It is left unquoted because zero-padded ids
+ * (`plan: 01`, `phase: 02`) are the pervasive GSD convention, quoting them
+ * all is the blanket quoting #4053 asked to avoid, and the loss is padding
+ * rather than identity: `02` and `2` normalize to the same phase; `22.1` and
+ * `22.10` do not.
+ */
+function generalScalarNeedsNumericQuoting(s) {
+    return YAML_NUMERIC_RE.test(s) && !/^\d+$/.test(s);
+}
 function reconstructFrontmatter(obj) {
     const lines = [];
     // #3257: read the full-line-comment channel (set by parseGuardedYamlRegion when comments
@@ -899,13 +1006,13 @@ function reconstructFrontmatter(obj) {
                 else {
                     // eslint-disable-next-line @typescript-eslint/no-base-to-string
                     const sv = String(subval);
-                    lines.push(`  ${subkey}: ${sv.includes(':') || sv.includes('#') || scalarNeedsDoubleQuoting(sv) ? `"${escapeDoubleQuotedScalar(sv)}"` : sv}`);
+                    lines.push(`  ${subkey}: ${sv.includes(':') || sv.includes('#') || scalarNeedsDoubleQuoting(sv) || generalScalarNeedsNumericQuoting(sv) ? `"${escapeDoubleQuotedScalar(sv)}"` : sv}`);
                 }
             }
         }
         else {
             const sv = String(value);
-            if (sv.includes(':') || sv.includes('#') || sv.startsWith('[') || sv.startsWith('{') || scalarNeedsDoubleQuoting(sv)) {
+            if (sv.includes(':') || sv.includes('#') || sv.startsWith('[') || sv.startsWith('{') || scalarNeedsDoubleQuoting(sv) || generalScalarNeedsNumericQuoting(sv)) {
                 lines.push(`${key}: "${escapeDoubleQuotedScalar(sv)}"`);
             }
             else {
@@ -1529,6 +1636,13 @@ module.exports = {
     stripFrontmatter,
     noOpObjectListSetError,
     parseMustHavesBlock,
+    // #3850: an array key's entries as parsed OBJECTS, for a caller that must
+    // branch on an entry's `status:`/`resolution:` rather than print it. Off the
+    // same parse path as `extractFrontmatter`, minus only the display flattening.
+    frontmatterListEntries,
+    // #3850: the display rendering itself, so a caller deriving a name from those
+    // objects produces the byte-identical string `extractFrontmatter` would have.
+    flattenObjectListItem,
     FRONTMATTER_SCHEMAS,
     cmdFrontmatterGet,
     cmdFrontmatterSet,

package/gsd-core/bin/lib/gap-checker.cjs

@@ -36,6 +36,9 @@ const { scanPhasePlans } = planScanMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
 const { scopeToPhase } = phaseIdMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningScopeMod = require("./planning-scope.cjs");
+const { SCOPE } = planningScopeMod;
 /**
  * Parse REQ-IDs from REQUIREMENTS.md content.
  *
@@ -303,6 +306,7 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
             summary: 'workflow.post_planning_gaps disabled — skipping post-planning gap analysis',
             counts: { total: 0, covered: 0, uncovered: 0 },
             phase_dir_read_error: null,
+            phase_dir_scope: SCOPE.COMPLETE,
         };
     }
     const absPhaseDir = node_path_1.default.isAbsolute(phaseDir) ? phaseDir : node_path_1.default.join(cwd, phaseDir);
@@ -325,19 +329,20 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
     }
     // Read the phase directory once; reuse the listing for both context detection
     // and plan-file enumeration (avoids redundant readdirSync calls).
-    let phaseDirFiles = [];
-    // #3885 (ADR-3473 §8.5): the existsSync guard above already means a catch
-    // here is NEVER "genuinely absent" (ENOENT) — this directory exists, so any
-    // failure to list it is a real read error (EACCES/EIO/...) and must be
-    // named, not folded into the same `[]` an absent directory produces.
-    let phaseDirReadError = null;
-    try {
-        if (node_fs_1.default.existsSync(absPhaseDir))
-            phaseDirFiles = node_fs_1.default.readdirSync(absPhaseDir);
-    }
-    catch (err) {
-        phaseDirReadError = `Could not read phase directory ${formatDiagnosticToken(absPhaseDir)}: ${formatDiagnosticToken(err?.message ?? String(err))}`;
-    }
+    //
+    // #4014 (epic #3473 B4): findContextMdIn's directory-string form now owns
+    // the listing + ENOENT-vs-other discrimination, retiring the local
+    // existsSync-guarded readdirSync try/catch — ENOENT (genuinely absent)
+    // and a successful-but-empty read both resolve to SCOPE.COMPLETE with an
+    // empty listing, exactly like the existsSync guard's short-circuit did.
+    const { files: phaseDirFiles, scope: phaseDirScope } = findContextMdIn(absPhaseDir);
+    // #3885 (ADR-3473 §8.5): `phaseDirReadError` stays additive for the
+    // shipped `phase_dir_read_error` JSON field — derived from `phaseDirScope`
+    // rather than from its own caught error, since findContextMdIn's
+    // directory-string form reports SCOPE, not the raw errno message.
+    const phaseDirReadError = phaseDirScope === SCOPE.UNREADABLE
+        ? `Could not read phase directory ${formatDiagnosticToken(absPhaseDir)}`
+        : null;
     // #3511-class: scope the raw listing to this phase dir before the
     // phase-numbered -CONTEXT.md predicate. `phaseDirFiles` itself stays raw —
     // it is also reused below only as a `.length > 0` guard ahead of
@@ -405,6 +410,7 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
                 summary: coverageSummary + '; extracted 0 of N — possible format mismatch',
                 counts: { total: rows.length, covered, uncovered },
                 phase_dir_read_error: phaseDirReadError,
+                phase_dir_scope: phaseDirScope,
             };
         }
         return {
@@ -414,6 +420,7 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
             summary: 'extracted 0 of N — possible format mismatch',
             counts: { total: 0, covered: 0, uncovered: 0 },
             phase_dir_read_error: phaseDirReadError,
+            phase_dir_scope: phaseDirScope,
         };
     }
     // #1365: if no items at all, surface a clean no-check message.
@@ -431,6 +438,7 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
             summary: 'no requirements or decisions to check',
             counts: { total: 0, covered: 0, uncovered: 0 },
             phase_dir_read_error: phaseDirReadError,
+            phase_dir_scope: phaseDirScope,
         };
     }
     const rows = sortRows([
@@ -449,6 +457,7 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
         summary,
         counts: { total: rows.length, covered, uncovered },
         phase_dir_read_error: phaseDirReadError,
+        phase_dir_scope: phaseDirScope,
     };
 }
 function cmdGapAnalysis(cwd, args, raw) {