@opengsd/gsd-core 1.9.1 → 1.11.0

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

@@ -16,6 +16,7 @@ const ioMod = require("./io.cjs");
 const { output, error } = ioMod;
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 const validate_cjs_1 = require("./validate.cjs");
+const text_lines_cjs_1 = require("./text-lines.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const unusableInputMod = require("./unusable-input.cjs");
 const { UNUSABLE_REASON, warnUnusableInput } = unusableInputMod;
@@ -83,7 +84,7 @@ const UNTERMINATED_KEY_THRESHOLD = 2;
  * has a false-positive class the other closes.
  */
 function isFrontmatterShaped(region) {
-    const lines = region.split(/\r?\n/).filter((line) => line.trim() !== '');
+    const lines = (0, text_lines_cjs_1.splitLines)(region).filter((line) => line.trim() !== '');
     if (lines.length === 0)
         return false;
     return lines.every((line) => (/^\s*[a-zA-Z0-9_-]+:/.test(line) // key: value
@@ -91,6 +92,80 @@ function isFrontmatterShaped(region) {
         || /^\s+\S/.test(line) // indented continuation of a nested value
     ));
 }
+/**
+ * #3257: a Symbol-keyed channel that carries full-line (column-0 `#`) YAML
+ * comments through a parse → reconstruct round-trip. Comments are otherwise
+ * unrepresentable on the Frontmatter object (Record<string, ...>) and were
+ * silently dropped by reconstructFrontmatter. The Symbol is invisible to
+ * Object.entries / Object.keys / JSON.stringify / for-in, so every existing
+ * reader is unchanged; only reconstructFrontmatter reads it. Leading comments
+ * are attached to the top-level key that follows them; comments after the last
+ * key go to `trailing`. Only set when a comment is actually seen, so comment-less
+ * frontmatter parses byte-identically to before.
+ */
+const FULL_LINE_COMMENTS = Symbol('fullLineComments');
+/**
+ * Unescape the interior of a YAML double-quoted scalar — the exact inverse of
+ * `escapeDoubleQuoted` (#3497). The writer has escaped `\`/`"`/`\n`/`\t`/`\r`/
+ * `\xHH` since #1779, but the reader only stripped the delimiters, so
+ * parse(serialize(x)) ≠ x for any quoted scalar carrying a `"` or `\`: each
+ * read-modify-write round-trip doubled the backslashes (b → 2b+1), growing a
+ * repeatedly-synced field — and its document — without bound until tooling
+ * OOMed. Recognized escapes decode per YAML double-quoted semantics; an
+ * unrecognized `\c` is kept literally (backslash + char), matching the
+ * strip-only behavior hand-authored files had before this fix.
+ */
+function unescapeDoubleQuoted(s) {
+    let out = '';
+    for (let i = 0; i < s.length; i++) {
+        const ch = s[i];
+        if (ch !== '\\' || i === s.length - 1) {
+            out += ch;
+            continue;
+        }
+        const next = s[++i];
+        if (next === '\\' || next === '"') {
+            out += next;
+        }
+        else if (next === 'n') {
+            out += '\n';
+        }
+        else if (next === 't') {
+            out += '\t';
+        }
+        else if (next === 'r') {
+            out += '\r';
+        }
+        else if (next === 'x') {
+            const hex = s.slice(i + 1, i + 3);
+            if (/^[0-9a-fA-F]{2}$/.test(hex)) {
+                out += String.fromCharCode(parseInt(hex, 16));
+                i += 2;
+            }
+            else {
+                out += '\\x'; // not \xHH — keep literally
+            }
+        }
+        else {
+            out += '\\' + next; // unrecognized escape — keep literally
+        }
+    }
+    return out;
+}
+/**
+ * Strip the quote delimiters off a parsed YAML scalar, un-escaping the interior
+ * when the scalar is double-quoted (#3497 — the parse-side complement of
+ * `escapeDoubleQuoted`). Single-quoted scalars keep the historical strip-only
+ * behavior (the writer never emits them; `''` → `'` folding is out of scope).
+ * A scalar wrapped in double quotes un-escapes; anything else keeps the exact
+ * prior delimiter-strip behavior, including a stray unpaired boundary quote.
+ */
+function parseQuotedScalar(value) {
+    if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+        return unescapeDoubleQuoted(value.slice(1, -1));
+    }
+    return value.replace(/^["']|["']$/g, '');
+}
 /**
  * Parse one already-delimited YAML region into a Frontmatter object.
  *
@@ -100,12 +175,20 @@ function isFrontmatterShaped(region) {
  */
 function parseYamlRegion(yaml) {
     const frontmatter = {};
-    const lines = yaml.split(/\r?\n/);
+    const lines = (0, text_lines_cjs_1.splitLines)(yaml);
+    // #3257: pending column-0 full-line comments, attached to the next top-level key.
+    let pendingComments = [];
+    let commentChannel;
     const stack = [{ obj: frontmatter, key: null, indent: -1 }];
     for (const line of lines) {
         // Skip empty lines
         if (line.trim() === '')
             continue;
+        // #3257: capture column-0 full-line comments; attach them to the next top-level key.
+        if (/^#/.test(line)) {
+            pendingComments.push(line);
+            continue;
+        }
         // Calculate indentation (number of leading spaces)
         const indentMatch = line.match(/^(\s*)/);
         const indent = indentMatch ? indentMatch[1].length : 0;
@@ -118,6 +201,13 @@ function parseYamlRegion(yaml) {
         const keyMatch = line.match(/^(\s*)([a-zA-Z0-9_-]+):\s*(.*)/);
         if (keyMatch) {
             const key = keyMatch[2];
+            // #3257: attach any pending comments to this (top-level) key.
+            if (pendingComments.length) {
+                if (!commentChannel)
+                    commentChannel = { leading: {}, trailing: [] };
+                commentChannel.leading[key] = pendingComments;
+                pendingComments = [];
+            }
             const value = keyMatch[3].trim();
             if (value === '' || value === '[') {
                 // Key with no value or opening bracket — could be nested object or array
@@ -134,13 +224,13 @@ function parseYamlRegion(yaml) {
             }
             else {
                 // Simple key: value
-                current.obj[key] = value.replace(/^["']|["']$/g, '');
+                current.obj[key] = parseQuotedScalar(value);
                 current.key = null;
             }
         }
         else if (line.trim().startsWith('- ')) {
             // Array item
-            const itemValue = line.trim().slice(2).replace(/^["']|["']$/g, '');
+            const itemValue = parseQuotedScalar(line.trim().slice(2));
             // If current context is an empty object, convert to array
             if (typeof current.obj === 'object' && !Array.isArray(current.obj) && Object.keys(current.obj).length === 0) {
                 // Find the key in parent that points to this object and convert it
@@ -160,6 +250,15 @@ function parseYamlRegion(yaml) {
             }
         }
     }
+    // #3257: trailing comments (after the last key) + attach the channel if any comment was seen.
+    if (pendingComments.length) {
+        if (!commentChannel)
+            commentChannel = { leading: {}, trailing: [] };
+        commentChannel.trailing = pendingComments;
+    }
+    if (commentChannel) {
+        frontmatter[FULL_LINE_COMMENTS] = commentChannel;
+    }
     return frontmatter;
 }
 /**
@@ -195,6 +294,18 @@ function parseYamlRegion(yaml) {
  *   hold only an in-memory string; those dedup on a content digest instead.
  */
 function extractFrontmatter(content, sourcePath) {
+    // #2977: tolerate a single leading UTF-8 BOM (\uFEFF), 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) {
+        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.
     const headerEnd = content.startsWith('---\r\n') ? 5 : content.startsWith('---\n') ? 4 : -1;
@@ -261,9 +372,17 @@ function scalarNeedsDoubleQuoting(s) {
 }
 function reconstructFrontmatter(obj) {
     const lines = [];
+    // #3257: read the full-line-comment channel (set by parseYamlRegion when comments
+    // were present). Object.entries skips the Symbol key, so the data loop is unchanged.
+    const commentChannel = obj[FULL_LINE_COMMENTS];
     for (const [key, value] of Object.entries(obj)) {
         if (value === null || value === undefined)
             continue;
+        // #3257: re-emit this key's leading full-line comments before the key itself.
+        const leading = commentChannel?.leading[key];
+        if (leading)
+            for (const c of leading)
+                lines.push(c);
         if (Array.isArray(value)) {
             if (value.length === 0) {
                 lines.push(`${key}: []`);
@@ -336,8 +455,35 @@ function reconstructFrontmatter(obj) {
             }
         }
     }
+    // #3257: re-emit any trailing full-line comments (those after the last key).
+    if (commentChannel?.trailing?.length) {
+        for (const c of commentChannel.trailing)
+            lines.push(c);
+    }
     return lines.join('\n');
 }
+/**
+ * #3257: copy the full-line-comment channel from `source` onto `target`, filtering
+ * `leading` to keys still present in `target` (a deleted key's annotation goes with
+ * it — AC5). No-op when `source` carries no channel. Consumers that rebuild their
+ * target object fresh (syncStateFrontmatter builds derivedFm via buildStateFrontmatter
+ * and copies keys with Object.keys, which skips the Symbol) MUST call this before
+ * reconstructFrontmatter, or the channel parseYamlRegion attached to the extracted
+ * source is lost.
+ */
+function propagateCommentChannel(source, target) {
+    const channel = source[FULL_LINE_COMMENTS];
+    if (!channel)
+        return;
+    const filtered = { leading: {}, trailing: channel.trailing };
+    for (const [key, comments] of Object.entries(channel.leading)) {
+        if (key in target)
+            filtered.leading[key] = comments;
+    }
+    if (filtered.trailing.length || Object.keys(filtered.leading).length) {
+        target[FULL_LINE_COMMENTS] = filtered;
+    }
+}
 /**
  * Slice a frontmatter YAML body into per-top-level-key raw text segments. Each segment
  * runs from a column-0 `key:` line through the line before the next column-0 key (or the
@@ -347,7 +493,7 @@ function reconstructFrontmatter(obj) {
  * not modify (e.g. must_haves.artifacts / .prohibitions).
  */
 function sliceTopLevelFrontmatterSegments(yaml) {
-    const lines = yaml.split(/\r?\n/);
+    const lines = (0, text_lines_cjs_1.splitLines)(yaml);
     const segments = [];
     let current = null;
     for (const line of lines) {
@@ -411,7 +557,7 @@ function spliceFrontmatter(content, newObj) {
         // unrelated `must_haves` block. Keys absent from the original (genuinely new) are
         // regenerated and appended; keys absent from `newObj` are preserved (never silently
         // deleted by a set/merge).
-        const fmLines = fmBlock.split(/\r?\n/);
+        const fmLines = (0, text_lines_cjs_1.splitLines)(fmBlock);
         const inner = fmLines.slice(1, -1).join('\n'); // drop the opening `---` and closing `---`
         let originalParsed;
         try {
@@ -492,27 +638,27 @@ function parseMustHavesBlock(content, blockName) {
     if (!fmMatch)
         return [];
     const yaml = fmMatch[1];
-    // Find must_haves: first to detect its indentation level
-    const mustHavesMatch = yaml.match(/^(\s*)must_haves:\s*$/m);
-    if (!mustHavesMatch)
+    const yamlLines = (0, text_lines_cjs_1.splitLines)(yaml);
+    // Find must_haves: first to detect its indentation level. Split-then-scan
+    // (rather than a whole-string /m match) so a CRLF or blank-line boundary
+    // can never be absorbed into the indent capture (#3360) — see
+    // .gsd/phase/chore-3413-text-lines-seam/40-design.md.
+    const mustHavesLinePattern = /^(\s*)must_haves:\s*$/;
+    const mustHavesLineIndex = yamlLines.findIndex((line) => mustHavesLinePattern.test(line));
+    if (mustHavesLineIndex === -1)
         return [];
-    const mustHavesIndent = mustHavesMatch[1].length;
+    const mustHavesIndent = yamlLines[mustHavesLineIndex].match(/^(\s*)/)[1].length;
     // Find the block (e.g., "truths:", "artifacts:", "key_links:") under must_haves
     // It must be indented more than must_haves but we detect the actual indent dynamically
-    const blockPattern = new RegExp(`^(\\s+)${blockName}:\\s*$`, 'm');
-    const blockMatch = yaml.match(blockPattern);
-    if (!blockMatch)
+    const blockLinePattern = new RegExp(`^(\\s+)${blockName}:\\s*$`);
+    const blockLineIndex = yamlLines.findIndex((line) => blockLinePattern.test(line));
+    if (blockLineIndex === -1)
         return [];
-    const blockIndent = blockMatch[1].length;
+    const blockIndent = yamlLines[blockLineIndex].match(/^(\s*)/)[1].length;
     // The block must be nested under must_haves (more indented)
     if (blockIndent <= mustHavesIndent)
         return [];
-    // Find where the block starts in the yaml string
-    const blockStart = yaml.indexOf(blockMatch[0]);
-    if (blockStart === -1)
-        return [];
-    const afterBlock = yaml.slice(blockStart);
-    const blockLines = afterBlock.split(/\r?\n/).slice(1); // skip the header line
+    const blockLines = yamlLines.slice(blockLineIndex + 1); // skip the header line
     // List items are indented one level deeper than blockIndent
     // Continuation KVs are indented one level deeper than list items
     const items = [];
@@ -607,29 +753,64 @@ function parseMustHavesBlock(content, blockName) {
     return items;
 }
 // ─── Frontmatter CRUD commands ────────────────────────────────────────────────
+// Shared base for 'plan' and 'plan-gap-closure' below — a plain array reference (not
+// FRONTMATTER_SCHEMAS.plan.required) because the object literal that defines
+// FRONTMATTER_SCHEMAS cannot refer to itself mid-initialization (TDZ).
+const PLAN_REQUIRED_FIELDS = ['phase', 'plan', 'type', 'wave', 'depends_on', 'files_modified', 'autonomous', 'must_haves'];
+// `requiredValues` is optional per schema: when a field name is a key here, the
+// field must be PRESENT AND strictly equal (===) to the given value to satisfy
+// the schema — presence alone is not enough. Every other required field (no
+// entry in requiredValues) keeps the original presence-only contract.
 const FRONTMATTER_SCHEMAS = {
-    plan: { required: ['phase', 'plan', 'type', 'wave', 'depends_on', 'files_modified', 'autonomous', 'must_haves'] },
+    plan: { required: PLAN_REQUIRED_FIELDS },
+    // #2847: gap-closure plans carry every 'plan' field PLUS gap_closure — the flag
+    // execute-phase --gaps-only filters on. A separate schema (not a change to
+    // 'plan') so standard/reviews-mode plans stay unaffected: they validate against
+    // 'plan' and are never required to declare or be checked for gap_closure.
+    // Derived from PLAN_REQUIRED_FIELDS (never hand-duplicated) so the two can't drift.
+    //
+    // requiredValues.gap_closure = true (not just presence): --gaps-only filters
+    // strictly on gap_closure === true (execute-phase.md, partial-wave.md), so a
+    // plan carrying `gap_closure: false` would pass a presence-only check and
+    // still be silently skipped at execute time — the exact symptom #2847
+    // reports, one value away. Presence-only was flagged in review as a live
+    // reproduction of the bug this schema exists to close.
+    'plan-gap-closure': {
+        required: [...PLAN_REQUIRED_FIELDS, 'gap_closure'],
+        // extractFrontmatter parses every scalar as a string (FrontmatterValue has
+        // no boolean member — `gap_closure: true` in YAML becomes the JS string
+        // "true", not the boolean true), so the required value is the string here.
+        requiredValues: { gap_closure: 'true' },
+    },
     summary: { required: ['phase', 'plan', 'subsystem', 'tags', 'duration', 'completed'] },
     verification: { required: ['phase', 'verified', 'status', 'score'] },
 };
 /**
- * Strip ALL frontmatter blocks from the start of `content`.
+ * Strip frontmatter blocks from the start of `content`.
+ *
+ * Handles CRLF line endings and, by default, multiple stacked blocks
+ * (corruption recovery): greedily strips consecutive `---...---` blocks
+ * separated by optional whitespace, so a doubled/tripled frontmatter header
+ * (e.g. from a botched merge) is fully removed, not just the first block.
  *
- * Handles CRLF line endings and multiple stacked blocks (corruption
- * recovery): greedily strips consecutive `---...---` blocks separated by
- * optional whitespace, so a doubled/tripled frontmatter header (e.g. from a
- * botched merge) is fully removed, not just the first block.
+ * Pass `{ once: true }` to stop after the first block. Callers whose input is
+ * an arbitrary user-authored document — rather than a GSD artefact with a
+ * known doubling failure mode — need this: a body that opens with a
+ * thematic-break-delimited section is lexically indistinguishable from a
+ * second frontmatter block, and the greedy loop deletes it silently (#2703).
  *
  * Canonical home for this primitive (#2143 audit dedup): previously
  * duplicated byte-identically in both `state.cts` and `state-transition.cts`.
  */
-function stripFrontmatter(content) {
+function stripFrontmatter(content, opts = {}) {
     let result = content;
     while (true) {
         const stripped = result.replace(/^\s*---\r?\n[\s\S]*?\r?\n---\s*/, '');
         if (stripped === result)
             break;
         result = stripped;
+        if (opts.once)
+            break;
     }
     return result;
 }
@@ -750,10 +931,19 @@ function cmdFrontmatterValidate(cwd, filePath, schemaName, raw) {
     if (filePath.includes('\0')) {
         error('file path contains null bytes');
     }
-    const schema = FRONTMATTER_SCHEMAS[schemaName];
-    if (!schema) {
+    // Guard against prototype-chain keys (__proto__, constructor, toString, hasOwnProperty,
+    // valueOf, ...): a bare FRONTMATTER_SCHEMAS[schemaName] lookup resolves those to
+    // Object.prototype members instead of undefined, so a `!schema` check on the raw
+    // lookup never fires and the code crashes later on `schema.required.filter` with an
+    // uncaught TypeError instead of the intended "Unknown schema" message. Confirmed live
+    // with --schema __proto__. Now that --schema is agent-bound (agents/gsd-planner.md's
+    // $SCHEMA), this is reachable from prompt state, not just an unreachable literal.
+    // Checked and rejected BEFORE the lookup (rather than `?? undefined`-ing the lookup
+    // itself) so `schema`'s inferred type stays non-optional and needs no assertion below.
+    if (!Object.prototype.hasOwnProperty.call(FRONTMATTER_SCHEMAS, schemaName)) {
         error(`Unknown schema: ${schemaName}. Available: ${Object.keys(FRONTMATTER_SCHEMAS).join(', ')}`);
     }
+    const schema = FRONTMATTER_SCHEMAS[schemaName];
     const fullPath = node_path_1.default.isAbsolute(filePath) ? filePath : node_path_1.default.join(cwd, filePath);
     const content = (0, shell_command_projection_cjs_1.platformReadSync)(fullPath);
     if (!content) {
@@ -771,9 +961,25 @@ function cmdFrontmatterValidate(cwd, filePath, schemaName, raw) {
     // Pass the resolved path so a truncated file is named in the diagnostic and deduplicated
     // per file rather than per content digest (#1882, ADR-1411 wiring clause).
     const fm = extractFrontmatter(content, fullPath);
-    const missing = schema.required.filter(f => fm[f] === undefined);
-    const present = schema.required.filter(f => fm[f] !== undefined);
-    output({ valid: missing.length === 0, missing, present, schema: schemaName }, raw, missing.length === 0 ? 'valid' : 'invalid');
+    const requiredValues = schema.requiredValues || {};
+    // A field satisfies the schema when it is present AND — for fields with a
+    // requiredValues entry — strictly equal to that value. Absent and
+    // wrong-value both surface as `missing` (existing `missing`/`present`
+    // partition of `required` is unchanged — no consumer reads `present` to
+    // mean "physically exists regardless of value," confirmed by searching
+    // every caller before choosing this). But #2847 review: folding silently
+    // made "missing" misleading for a WRONG-valued field the plan author can
+    // plainly see in the file (e.g. `gap_closure: True`) — nothing told them
+    // the field is present but the VALUE is wrong, so they could loop trying
+    // to add a field that is already there. `invalidValue` names exactly that
+    // subset (present, but not the required value) so the message stays
+    // actionable without changing what `missing`/`present` mean.
+    const wrongValue = (f) => fm[f] !== undefined && Object.prototype.hasOwnProperty.call(requiredValues, f) && fm[f] !== requiredValues[f];
+    const satisfies = (f) => fm[f] !== undefined && !wrongValue(f);
+    const missing = schema.required.filter(f => !satisfies(f));
+    const present = schema.required.filter(f => satisfies(f));
+    const invalidValue = schema.required.filter(wrongValue);
+    output({ valid: missing.length === 0, missing, present, invalidValue, schema: schemaName }, raw, missing.length === 0 ? 'valid' : 'invalid');
 }
 module.exports = {
     extractFrontmatter,
@@ -793,4 +999,5 @@ module.exports = {
     cmdFrontmatterSet,
     cmdFrontmatterMerge,
     cmdFrontmatterValidate,
+    propagateCommentChannel,
 };

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

@@ -24,14 +24,18 @@ const node_path_1 = __importDefault(require("node:path"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const io = require("./io.cjs");
 const { output, error } = io;
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const phaseId = require("./phase-id.cjs");
-const { escapeRegex } = phaseId;
+const pattern_cjs_1 = require("./pattern.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
 const { planningPaths, planningDir, findContextMdIn } = planningWorkspace;
 const decisions_cjs_1 = require("./decisions.cjs");
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planScanMod = require("./plan-scan.cjs");
+const { scanPhasePlans } = planScanMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseIdMod = require("./phase-id.cjs");
+const { scopeToPhase } = phaseIdMod;
 /**
  * Parse REQ-IDs from REQUIREMENTS.md content.
  *
@@ -91,7 +95,7 @@ function parseRequirements(reqMd) {
 }
 function detectCoverage(items, planText) {
     return items.map(it => {
-        const re = new RegExp('\\b' + escapeRegex(it.id) + '\\b');
+        const re = new RegExp('\\b' + (0, pattern_cjs_1.escapeRegex)(it.id) + '\\b');
         return {
             source: it.source,
             item: it.id,
@@ -152,6 +156,38 @@ const PHASE_REQ_RANGE_RE = /^(.+-)(\d+)\.\.(.+-)(\d+)$/;
  * against pathological input like `X-1..X-100000` ballooning the comparison set.
  */
 const MAX_PHASE_REQ_RANGE = 1000;
+/**
+ * Shape filter applied to `--phase-req-ids` tokens AFTER range expansion
+ * (#3189). ROADMAP `**Requirements:**` lines routinely carry prose trailing
+ * the real ID list — locked-decision annotations, ambiguity scores,
+ * prohibitions, dates — and the function's own contract says callers may pass
+ * that roadmap value through verbatim. Without a shape filter every prose word
+ * survives the whitespace split and is reported as an individually-missing
+ * requirement, drowning the real coverage signal.
+ *
+ * The filter is intentionally wider than `ID_PATTERN` (which mandates a hyphen
+ * and so would reject the hyphen-less `R1`..`R8` family real roadmaps use).
+ * Three load-bearing details (#3189):
+ *
+ *   1. The digit lookahead `(?=.*\d)` matters. Without it ALL-CAPS prose tokens
+ *      that appear in annotations (`LOCKED`, `TBD`-as-prose, `NONE`-as-prose)
+ *      would pass and still reach the report as fake IDs. Every real
+ *      requirement ID carries a digit (`R1`, `SEL-01`, `P1-P3`).
+ *   2. It MUST run after `expandPhaseReqIdToken`. Filtering before would
+ *      discard the range tokens themselves (`SEL-01..SEL-03` matches no
+ *      single-ID shape), silently undoing the #1269 / #1419 range expansion.
+ *   3. It is NOT reusable as `ID_PATTERN`. `ID_PATTERN` mandates a hyphen,
+ *      so it rejects `R1`..`R8` and would leave only range-shaped tokens
+ *      standing — a silently-empty report, which is worse.
+ *
+ * Accepts both hyphen-less digit-bearing IDs (`R1`, `R8`) and prefix-hyphen
+ * IDs (`REQ-01`, `SEL-01`, `BACK-07`), including multi-segment prefixes
+ * (`REQ2-01`). Rejects prose (`LOCKED`), punctuation (`—`, `##`, `+`),
+ * dates, version-likes (`0.12;`), backtick fragments, and any token still
+ * containing `.` (so invalid range tokens returned literal by
+ * `expandPhaseReqIdToken` are dropped rather than surfaced as fake IDs).
+ */
+const PHASE_REQ_ID_SHAPE_RE = /^(?=.*\d)[A-Z][A-Z0-9]*(?:[-_][A-Za-z0-9]+)*$/;
 /**
  * Expand a single `--phase-req-ids` token in place. If it is a valid ascending
  * same-prefix numeric range (`<PREFIX>-NN..<PREFIX>-MM`, identical prefix both
@@ -212,6 +248,15 @@ function expandPhaseReqIdToken(token) {
  * spanning more than MAX_PHASE_REQ_RANGE IDs) stays literal — no partial
  * expansion, no guessing.
  *
+ * ID-shape filter (#3189): STRICTLY AFTER range expansion, every token is
+ * filtered through `PHASE_REQ_ID_SHAPE_RE`. ROADMAP `**Requirements:**` lines
+ * routinely carry prose trailing the real ID list (locked-decision annotations,
+ * ambiguity scores, prohibitions, dates); without the filter every prose word
+ * would be reported as an individually-missing requirement. Tokens that cannot
+ * be requirement IDs (prose, punctuation, dates, invalid range tokens left
+ * literal by `expandPhaseReqIdToken`) are dropped; an input whose every token
+ * is dropped collapses to `null` (skip semantics).
+ *
  * Tolerates JSON-array-ish input (`["REQ-01","REQ-02"]`) since callers may pass
  * the roadmap value through verbatim.
  */
@@ -229,7 +274,12 @@ function normalizePhaseReqIds(rawVal) {
     const ids = v.split(/[\s,]+/).map(s => s.trim()).filter(Boolean);
     // Expand range tokens (#1269) per-token AFTER the split, preserving input order.
     const expanded = ids.flatMap(expandPhaseReqIdToken);
-    return expanded.length === 0 ? null : expanded;
+    // #3189: drop tokens that cannot be requirement IDs (prose, punctuation,
+    // dates, invalid range tokens left literal by expandPhaseReqIdToken). MUST
+    // run after expand so valid ranges still expand (filtering before would
+    // discard `SEL-01..SEL-03` itself, undoing #1269 / #1419).
+    const filtered = expanded.filter(t => PHASE_REQ_ID_SHAPE_RE.test(t));
+    return filtered.length === 0 ? null : filtered;
 }
 function runGapAnalysis(cwd, phaseDir, options = {}) {
     const phaseReqIds = normalizePhaseReqIds(options.phaseReqIds);
@@ -268,7 +318,13 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
             phaseDirFiles = node_fs_1.default.readdirSync(absPhaseDir);
     }
     catch { /* unreadable */ }
-    const ctxFile = findContextMdIn(phaseDirFiles);
+    // #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
+    // scanPhasePlans's own plan-sequence-numbered enumeration, a different
+    // grammar that must not be scoped by phase number.
+    const scopedPhaseDirFiles = scopeToPhase(phaseDirFiles, node_path_1.default.basename(absPhaseDir));
+    const ctxFile = findContextMdIn(scopedPhaseDirFiles);
     const ctxPath = ctxFile ? node_path_1.default.join(absPhaseDir, ctxFile) : null;
     const ctxMd = ctxPath ? node_fs_1.default.readFileSync(ctxPath, 'utf-8') : '';
     // Use extractDecisions so gap-checker can distinguish could-not-parse from none-present.
@@ -278,7 +334,12 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
     let planText = '';
     try {
         if (phaseDirFiles.length > 0) {
-            const files = phaseDirFiles.filter(f => /-PLAN\.md$/.test(f));
+            // #3183 (lint-plan-count-drift): source the live plan-file list from
+            // the single owner (scanPhasePlans) instead of a local `-PLAN\.md$`
+            // filter on the already-read listing — picks up bare PLAN.md, nested
+            // plans/, and excludes superseded plans, none of which the prior
+            // root-only exact-suffix filter did.
+            const files = scanPhasePlans(absPhaseDir).planFiles;
             planText = files.map(f => {
                 try {
                     return node_fs_1.default.readFileSync(node_path_1.default.join(absPhaseDir, f), 'utf-8');

package/gsd-core/bin/lib/gate-predicate-evaluator.cjs

@@ -18,11 +18,10 @@
  * non-zero check-command exit, which the workflow's two-step gate contract treats
  * as a step-1 command failure (routed per the gate's `onError`).
  *
- * Built-in kind (v1): `command-exit-zero` — run a declared command in a bounded
- * `sh -c` subprocess at the project root, inheriting the process env; exit 0 =>
- * pass, non-zero => block, timeout => block. The production runBoundedShell
- * binding is shell-command-projection.execTool (bounded spawnSync). See ADR-2008
- * for the full sandbox contract.
+ * Built-in kinds: `command-exit-zero` runs a declared command in a bounded
+ * `sh -c` subprocess; `artifact-frontmatter-equals` compares a declared value
+ * with frontmatter read through injected artifact dependencies. See ADR-2008
+ * for the full contracts.
  *
  * This is a leaf pure module: no fs, no child_process, no config — the subprocess
  * seam is injected so the evaluator is trivially testable without spawning.
@@ -35,7 +34,7 @@ const COMMAND_MAX_OUTPUT_CHARS = 2000;
 /** Hard cap on the declared command length (defense-in-depth against ARGV overflow / abuse). */
 const COMMAND_MAX_LENGTH = 4096;
 /** Predicate kinds this evaluator recognises (extensible — add to KIND_TABLE). */
-const EVALUATOR_KINDS = Object.freeze(['command-exit-zero']);
+const EVALUATOR_KINDS = Object.freeze(['command-exit-zero', 'artifact-frontmatter-equals']);
 /** Placeholders interpolated into a declared command, in addition to sh's own vars. */
 const INTERPOLATION_VAR_NAMES = Object.freeze(['PHASE_NUMBER', 'PHASE_DIR', 'PHASE_REQ_IDS']);
 // ─── Helpers ──────────────────────────────────────────────────────────────────
@@ -102,9 +101,53 @@ function evaluateCommandExitZero(predicate, ctx, deps) {
         details: { kind: 'command-exit-zero', exitCode: res.exitCode, signal: res.signal },
     };
 }
+// ─── Kind: artifact-frontmatter-equals ──────────────────────────────────────────
+function evaluateArtifactFrontmatterEquals(predicate, ctx, deps) {
+    const artifactSuffix = predicate['artifact'];
+    if (!isNonEmptyString(artifactSuffix)) {
+        throw new Error('artifact-frontmatter-equals predicate requires a non-empty string "artifact"');
+    }
+    const field = predicate['field'];
+    if (!isNonEmptyString(field)) {
+        throw new Error('artifact-frontmatter-equals predicate requires a non-empty string "field"');
+    }
+    const expectedValue = predicate['equals'];
+    if (expectedValue === undefined) {
+        throw new Error('artifact-frontmatter-equals predicate requires an "equals" key');
+    }
+    const targetDir = isNonEmptyString(ctx.phaseDir) ? ctx.phaseDir : ctx.cwd;
+    const filePath = deps.findPhaseArtifact(targetDir, artifactSuffix);
+    if (!filePath) {
+        return {
+            block: true,
+            message: `Artifact matching ${artifactSuffix} not found in ${targetDir}`,
+            details: { kind: 'artifact-frontmatter-equals', artifactNotFound: true },
+        };
+    }
+    const fm = deps.readFrontmatter(filePath);
+    const actualValue = fm[field];
+    // eslint-disable-next-line @typescript-eslint/no-base-to-string
+    const expectedStr = typeof expectedValue === 'object' ? JSON.stringify(expectedValue) : String(expectedValue);
+    // eslint-disable-next-line @typescript-eslint/no-base-to-string
+    const actualStr = typeof actualValue === 'object' ? JSON.stringify(actualValue) : String(actualValue);
+    const matches = actualValue === expectedValue || (actualValue !== undefined && actualValue !== null && actualStr === expectedStr);
+    if (matches) {
+        return {
+            block: false,
+            message: `Frontmatter field "${field}" matches expected value (${expectedStr})`,
+            details: { kind: 'artifact-frontmatter-equals', match: true },
+        };
+    }
+    return {
+        block: true,
+        message: `Frontmatter field "${field}" in ${artifactSuffix} is ${actualStr}, expected ${expectedStr}`,
+        details: { kind: 'artifact-frontmatter-equals', match: false, actual: actualValue, expected: expectedValue },
+    };
+}
 // ─── Kind dispatch table ──────────────────────────────────────────────────────
 const KIND_TABLE = {
     'command-exit-zero': evaluateCommandExitZero,
+    'artifact-frontmatter-equals': evaluateArtifactFrontmatterEquals,
 };
 // ─── Public entry point ───────────────────────────────────────────────────────
 /**
@@ -133,6 +176,14 @@ function evaluatePredicate(predicate, context, deps) {
     if (typeof kind !== 'string' || kind.length === 0) {
         throw new Error('predicate.kind must be a non-empty string');
     }
+    if (kind === 'artifact-frontmatter-equals') {
+        if (typeof d.findPhaseArtifact !== 'function') {
+            throw new Error('predicate deps require a "findPhaseArtifact" function');
+        }
+        if (typeof d.readFrontmatter !== 'function') {
+            throw new Error('predicate deps require a "readFrontmatter" function');
+        }
+    }
     const handler = KIND_TABLE[kind];
     if (!handler) {
         throw new Error(`Unknown predicate kind: "${kind}". Known kinds: ${EVALUATOR_KINDS.join(', ')}`);