@opengsd/gsd-core 1.15.0 → 1.16.0

package/scripts/lint-frontmatter-scalar-broad-grep.cjs

@@ -17,10 +17,22 @@
  * `passed+gaps_found+human_needed` instead of `passed` and blocking a
  * passed phase).
  *
- * The fix-forward is to scope the grep to the leading frontmatter block and
- * take only the first match:
+ * The fix-forward for a scalar with no owning query is to scope the grep to
+ * the leading frontmatter block and take only the first match:
  *   sed -n '/^---$/,/^---$/p' "$f" | grep -m1 "^<key>:" | cut -d: -f2 | tr -d ' '
  *
+ * ## Rule `verification-status-raw-read` (#5118, ADR-5057 Phase 4)
+ *
+ * A VERIFICATION report's `status` HAS an owning query — its closed enum,
+ * staleness check and routing live in src/verification.cts. Reading that
+ * scalar with awk / sed / grep `^status:` (scoped to the frontmatter or not)
+ * bypasses all three (transition.md's awk read was W15 in the #5118 census),
+ * so it is red even when frontmatter-scoped. The fix-forward is the owner:
+ *   gsd_run query verification.status "$PHASE_DIR" --pick status
+ * `findRawVerificationStatusReadsInBlock` flags a logical line (backslash
+ * continuations joined) that names a `*VERIFICATION*` path or variable and
+ * reads `^status` with awk, sed or grep.
+ *
  * ## What this scans
  *
  * Every fenced ```bash / ```sh code block in `gsd-core/workflows/*.md`,
@@ -68,6 +80,17 @@ const FRONTMATTER_SCOPE_RE = /\^---[\s\S]{0,300}?---/;
 
 const ALLOW_RE = /#\s*lint-allow:\s*frontmatter-scalar-broad-grep/;
 
+const RULE_BROAD_GREP = 'frontmatter-scalar-broad-grep';
+const RULE_VERIFICATION_RAW_READ = 'verification-status-raw-read';
+
+// #5118: a VERIFICATION report path or variable (`*-VERIFICATION.md`,
+// `$VERIFICATION_FILE`, `${VERIFICATION_PATH}`), a raw `^status` pattern, and
+// the text tool doing the read. Case-INsensitive (#5118 review): a lower-case
+// `$verification_file` / `*-verification.md` read is the same bypass.
+const VERIFICATION_PATH_RE = /verification/i;
+const RAW_STATUS_PATTERN_RE = /\^status\b/;
+const RAW_READ_TOOL_RE = /(^|[\s|;&(`$])(awk|gawk|sed|grep|egrep)\s/;
+
 // `| head -1` / `| head -n 1` immediately after the grep is functionally
 // equivalent to `-m1` for this check: frontmatter always precedes the body
 // in these generated reports, so the first grep match is always the
@@ -163,12 +186,63 @@ function findBroadGrepsInBlock(lines) {
     }
 
     if (pipedToTokenTool || comparedLater) {
-      findings.push({ lineIndex: i, key, snippet: line.trim() });
+      findings.push({ lineIndex: i, key, snippet: line.trim(), rule: RULE_BROAD_GREP });
     }
   }
   return findings;
 }
 
+/**
+ * Join backslash-continued physical lines into logical lines, remembering the
+ * index of each logical line's FIRST physical line.
+ * @param {string[]} lines
+ * @returns {{ lineIndex: number, text: string }[]}
+ */
+function logicalLines(lines) {
+  const out = [];
+  let current = null;
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    const continued = /\\\s*$/.test(line);
+    const piece = continued ? line.replace(/\\\s*$/, ' ') : line;
+    if (current === null) current = { lineIndex: i, text: piece };
+    else current.text += piece;
+    if (!continued) {
+      out.push(current);
+      current = null;
+    }
+  }
+  if (current !== null) out.push(current);
+  return out;
+}
+
+/**
+ * Pure (#5118): find every raw read of a VERIFICATION report's `status` in a
+ * single fenced bash/sh block — awk / sed / grep over a `*VERIFICATION*`
+ * path with a `^status` pattern, whether or not it is frontmatter-scoped.
+ * The owner query (`gsd_run query verification.status …`) carries no
+ * `^status` pattern and is never flagged. Returns
+ * `{ lineIndex, key, snippet, rule }[]` (lineIndex = the logical line's first
+ * physical line).
+ * @param {string[]} lines
+ * @returns {{ lineIndex: number, key: string, snippet: string, rule: string }[]}
+ */
+function findRawVerificationStatusReadsInBlock(lines) {
+  const findings = [];
+  for (const { lineIndex, text } of logicalLines(lines)) {
+    if (!VERIFICATION_PATH_RE.test(text)) continue;
+    if (!RAW_STATUS_PATTERN_RE.test(text)) continue;
+    if (!RAW_READ_TOOL_RE.test(text)) continue;
+    findings.push({
+      lineIndex,
+      key: 'status',
+      snippet: text.replace(/\s+/g, ' ').trim(),
+      rule: RULE_VERIFICATION_RAW_READ,
+    });
+  }
+  return findings;
+}
+
 function walkMarkdown(dir) {
   const out = [];
   let entries;
@@ -198,12 +272,18 @@ function scan(roots = DEFAULT_ROOTS) {
     for (const file of walkMarkdown(abs)) {
       const blocks = extractBashBlocks(fs.readFileSync(file, 'utf8'));
       for (const block of blocks) {
-        for (const finding of findBroadGrepsInBlock(block.lines)) {
+        const rawReads = findRawVerificationStatusReadsInBlock(block.lines);
+        const rawReadLines = new Set(rawReads.map((f) => f.lineIndex));
+        // A raw VERIFICATION `status` read is reported once, under its own
+        // rule, not a second time as a broad grep.
+        const broad = findBroadGrepsInBlock(block.lines).filter((f) => !rawReadLines.has(f.lineIndex));
+        for (const finding of [...rawReads, ...broad]) {
           offenders.push({
             file: path.relative(ROOT, file),
             line: block.startLine + finding.lineIndex,
             key: finding.key,
             snippet: finding.snippet,
+            rule: finding.rule,
           });
         }
       }
@@ -217,21 +297,47 @@ function main() {
   const roots = rootsEnv ? rootsEnv.split(path.delimiter).filter(Boolean) : DEFAULT_ROOTS;
   const offenders = scan(roots);
   if (offenders.length > 0) {
-    const detail = offenders.map((o) => `  ${o.file}:${o.line}  ${o.snippet}`).join('\n');
-    throw new ExitError(
-      1,
-      'lint-frontmatter-scalar-broad-grep: `grep "^key:"` over the whole file, compared to an\n'
-        + 'exact token, with no frontmatter scoping and no -m1 (DEFECT.FRONTMATTER-SCALAR-BROAD-GREP).\n'
-        + 'A body line beginning `key:` is enough to break this. Scope to the frontmatter block:\n'
-        + '  sed -n \'/^---$/,/^---$/p\' "$f" | grep -m1 "^<key>:" | cut -d: -f2 | tr -d \' \'\n'
-        + 'or add `# lint-allow: frontmatter-scalar-broad-grep — <reason>` if this is a genuine\n'
-        + 'whole-body scan:\n'
-        + detail,
-    );
+    const detailFor = (rule) => offenders
+      .filter((o) => o.rule === rule)
+      .map((o) => `  ${o.file}:${o.line}  ${o.snippet}`)
+      .join('\n');
+    const sections = [];
+    const rawReads = detailFor(RULE_VERIFICATION_RAW_READ);
+    if (rawReads) {
+      sections.push(
+        `[${RULE_VERIFICATION_RAW_READ}] a VERIFICATION report's \`status\` read with awk/sed/grep\n`
+          + '(DEFECT.FRONTMATTER-SCALAR-BROAD-GREP, #5118). It bypasses the closed VerificationStatus\n'
+          + 'enum, the staleness check and the routing table. Read it through its owner:\n'
+          + '  gsd_run query verification.status "$PHASE_DIR" --pick status\n'
+          + rawReads,
+      );
+    }
+    const broad = detailFor(RULE_BROAD_GREP);
+    if (broad) {
+      sections.push(
+        `[${RULE_BROAD_GREP}] \`grep "^key:"\` over the whole file, compared to an exact token,\n`
+          + 'with no frontmatter scoping and no -m1 (DEFECT.FRONTMATTER-SCALAR-BROAD-GREP).\n'
+          + 'A body line beginning `key:` is enough to break this. Scope a scalar that has no owning\n'
+          + 'query to the frontmatter block (a VERIFICATION `status` always goes through its owner):\n'
+          + '  sed -n \'/^---$/,/^---$/p\' "$f" | grep -m1 "^<key>:" | cut -d: -f2 | tr -d \' \'\n'
+          + 'or add `# lint-allow: frontmatter-scalar-broad-grep — <reason>` if this is a genuine\n'
+          + 'whole-body scan:\n'
+          + broad,
+      );
+    }
+    throw new ExitError(1, `lint-frontmatter-scalar-broad-grep:\n${sections.join('\n')}`);
   }
   console.log(`ok lint-frontmatter-scalar-broad-grep: no un-scoped frontmatter-scalar greps in ${roots.length} root(s)`);
 }
 
-module.exports = { findBroadGrepsInBlock, extractBashBlocks, scan, DEFAULT_ROOTS };
+module.exports = {
+  findBroadGrepsInBlock,
+  findRawVerificationStatusReadsInBlock,
+  extractBashBlocks,
+  scan,
+  DEFAULT_ROOTS,
+  RULE_BROAD_GREP,
+  RULE_VERIFICATION_RAW_READ,
+};
 
 if (require.main === module) runMain(main);

package/scripts/lint-phase-enumeration-drift.cjs

@@ -84,13 +84,16 @@
  *     shape as `collectDiskPhases` and the `audit.cts` scanners; it must see
  *     every phase directory regardless of milestone window to catch a
  *     naming/duplicate defect wherever it lives.
- *   - `src/verify.cts` `resolvePhaseDirByToken`: resolves ONE caller-supplied
- *     `phase` argument to its directory (falling back to an exact-name
- *     match) — a single-phase LOOKUP, not a current-milestone enumeration.
- *     Originally `cmdVerifySchemaDrift`'s own inline block; #3348 lifted it
- *     into this shared helper (also used by the new `cmdVerifyContextDrift`)
- *     without changing what question it asks, so the exemption moved with
- *     the call site rather than multiplying.
+ *   - `src/gate-phase-context.cts` `resolvePhaseDirByToken`: resolves ONE
+ *     caller-supplied `phase` argument to its directory (falling back to an
+ *     exact-name match) — a single-phase LOOKUP, not a current-milestone
+ *     enumeration. Originally `cmdVerifySchemaDrift`'s own inline block;
+ *     #3348 lifted it into this shared helper (also used by the context-drift
+ *     check) without changing what question it asks, so the exemption moved
+ *     with the call site rather than multiplying. #5219 (ADR-5057 §4) moved
+ *     both checks into gate modules and the helper beside `resolvePhaseDir`
+ *     in the gate phase-context module (it is not `resolvePhaseDir`: it
+ *     lists ONE given phases directory and nothing else).
  *   - `src/init.cts` `detectHasPriorPhases`: answers "has this project EVER
  *     completed a phase", explicitly excluding the current one. A history
  *     probe across all milestones, not a current-milestone enumeration.
@@ -309,7 +312,8 @@ const OWNER_FILES = new Set([
 // `lint-milestone-window-drift.cjs`'s FUNCTION_SCOPED_EXEMPTIONS mechanism.
 // See the header comment for the full written reason behind each entry.
 const FUNCTION_SCOPED_EXEMPTIONS = new Map([
-  [path.join('src', 'verify.cts'), new Set(['cmdValidateHealth', 'resolvePhaseDirByToken'])],
+  [path.join('src', 'verify.cts'), new Set(['cmdValidateHealth'])],
+  [path.join('src', 'gate-phase-context.cts'), new Set(['resolvePhaseDirByToken'])],
   [path.join('src', 'init.cts'), new Set(['detectHasPriorPhases', 'detectUiPhaseActive'])],
   [path.join('src', 'milestone.cts'), new Set(['archivePhaseDirectories', 'cmdMilestoneComplete', 'cmdPhasesClear'])],
   // #3849: collectSiblingWorktreePhaseNums reads a SIBLING worktree's phases dir —

package/scripts/lint-phase-id-drift.cjs

@@ -283,6 +283,34 @@ function findPhaseHeadingScanLiteralDrift(text) {
   return out;
 }
 
+/**
+ * Scan the authored source tree (`src/**\/*.cts`, the same `SCAN_DIRS` root
+ * and `phase-id.cts` owner exemption that `scanRepo` applies to this
+ * detector — the heading-scan literal is a `src/**\/*.cts` defect, not a
+ * markdown one, unlike its sibling wrappers below) for unsanctioned
+ * hand-rolled heading-scan literals. Returns [{ file, line, found }] with
+ * repo-relative paths.
+ */
+function scanMarkdownPhaseHeadingScanLiteral(root) {
+  const violations = [];
+  for (const dir of SCAN_DIRS) {
+    for (const file of walk(path.join(root, dir), [])) {
+      const rel = path.relative(root, file);
+      if (EXEMPT.has(rel)) continue;
+      let text;
+      try {
+        text = fs.readFileSync(file, 'utf8');
+      } catch {
+        continue;
+      }
+      for (const d of findPhaseHeadingScanLiteralDrift(text)) {
+        violations.push({ file: rel, kind: 'phase-heading-scan-literal', ...d });
+      }
+    }
+  }
+  return violations;
+}
+
 // #4634: ban base-10-forced shell arithmetic (`$((10#...))`) on a variable
 // that still carries a possibly-decimal/multi-segment phase id — this
 // construct is exactly the pattern that breaks on a value like `08.5`. The
@@ -857,6 +885,7 @@ module.exports = {
   findNameValidityDrift,
   findBranchSlugFallbackDrift,
   findPhaseHeadingScanLiteralDrift,
+  scanMarkdownPhaseHeadingScanLiteral,
   findShellPhaseArithDrift,
   findSingleSegmentPhaseRegexDrift,
   findLetterlessPhaseMirrorDrift,

package/scripts/lint-planning-document-positive-control.cjs

@@ -0,0 +1,329 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * PlanningDoc positive-control lint (ADR-4910 §7, "Every parser ships a
+ * positive control per accepted grammar", epic #4906 Phase 6 / #5007).
+ *
+ * `NodeKind` (`src/planning-document.cts`, compiled to
+ * `gsd-core/bin/lib/planning-document.cjs`) is the single-source union naming
+ * every grammar `parsePlanningDoc` accepts: `frontmatter` / `section` /
+ * `boldField` / `table` / `checklist`. This lint asserts one positive-control
+ * fixture per declared grammar, under `tests/fixtures/planning-document/`,
+ * each of which must round-trip through the real `parsePlanningDoc` and
+ * actually produce a node of that kind — not merely "the parser didn't
+ * throw". Per CONTRIBUTING.md's fixture-provenance rule (#2371), every
+ * fixture here is authored independently, never copied from
+ * `src/planning-document.cts`'s own docstring examples or from
+ * `tests/planning-document.test.cjs`'s existing fixtures.
+ *
+ * The `accepted` set (`NodeKind`) is a TypeScript-only type, erased by
+ * compilation — it carries no runtime value in the built `.cjs` seam. So this
+ * lint reads it directly out of `src/planning-document.cts`'s own source
+ * text (the `export type NodeKind = ...;` declaration), the same way
+ * `scripts/lint-phase-id-drift.cjs` reads source text for its own literal
+ * checks — NOT by importing a type, which is impossible from a `.cjs`
+ * script. This is what makes the guarantee live: a NEW grammar kind added to
+ * `NodeKind` with no registry entry fails this lint immediately, before any
+ * fixture is even written, closing the "parser without one fails the build"
+ * requirement in ADR-4910 §7.
+ *
+ * Modeled on `scripts/lint-table-schema-drift.cjs`'s registry/exit-code/
+ * error-message structure — a hardcoded `{grammar -> fixture file}` map,
+ * exit 0 clean / exit 1 with a per-entry reason on drift, wired into
+ * `lint:ci` — but the ASSERTION is stricter than that script's verbatim-
+ * substring check: proof the grammar is genuinely *accepted* (the fixture
+ * parses without error and yields a node of that kind), per ADR-4910 §7's
+ * own text, not just "a string appears somewhere".
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const PLANNING_DOCUMENT_SRC = path.join('src', 'planning-document.cts');
+const PLANNING_DOCUMENT_LIB = path.join('gsd-core', 'bin', 'lib', 'planning-document.cjs');
+const FIXTURE_DIR = path.join('tests', 'fixtures', 'planning-document');
+
+// grammar kind (must match a `NodeKind` union member verbatim) -> the ONE
+// canonical positive-control fixture file (relative to FIXTURE_DIR) that
+// proves that grammar is accepted (ADR-4910 §7).
+const POSITIVE_CONTROL_REGISTRY = {
+  frontmatter: 'frontmatter.md',
+  section: 'section.md',
+  boldField: 'boldfield.md',
+  table: 'table.md',
+  checklist: 'checklist.md',
+};
+
+// Any real entry from `PLANNING_ARTIFACTS` satisfies `parsePlanningDoc`'s
+// artifact-kind gate equally — the specific name does not affect which
+// grammars a fixture's BODY is recognised as containing.
+const FIXTURE_ARTIFACT_NAME = 'ROADMAP.md';
+
+// Test-only env var name. `resolveRegistry` below JSON-parses this (when set)
+// and shallow-merges it over `POSITIVE_CONTROL_REGISTRY`, so a test can spawn
+// THIS SAME, otherwise-unmodified, script file as a real child process
+// against a deliberately broken registry entry (a missing entry, or one
+// pointed at a nonexistent fixture) — proving the lint genuinely fails the
+// build, per ADR-4910 §7's "a parser without one fails the build" guarantee
+// — without ever touching the real registry or fixture files.
+//
+// This env var alone is NEVER sufficient to activate the override — a bare
+// `process.env` lookup would mean a stray, accidentally-inherited copy of
+// this variable (a leftover shell `export`, a misconfigured CI environment,
+// a compromised dependency's postinstall script) could silently swap the
+// registry in a REAL `npm run lint:ci` / `npm run lint:planning-document-
+// positive-control` invocation, with nothing in the code enforcing otherwise
+// (flagged by both the security review and the code-review Standards axis
+// on #5007 Phase 6: the old comment asserted "no real invocation ever sets
+// this" as a convention, not a fact the code made true).
+//
+// What now makes it true, by construction: `scanRepo` only reads this env
+// var via `resolveRegistry` when its caller ALSO passes `allowOverride ===
+// true`, which `main()` only does when the `--test-registry-override` CLI
+// flag is present in argv (see `parseArgs`). The test file spawns this
+// script as a real child process (`tests/helpers/process-seam.cjs`'s
+// `runNode`, over `spawnSync`) — a process boundary that can only carry data
+// in via `env`/`argv`, so the override cannot be passed as an in-process
+// function parameter here the way it can be for the pure functions below.
+// Requiring BOTH the env var and the CLI flag closes the gap: neither
+// `lint:ci` nor `lint:planning-document-positive-control` (see package.json)
+// ever passes `--test-registry-override` in their fixed argv, and unlike an
+// env var, a CLI flag is never accidentally "leaked" into a fixed npm-script
+// invocation. See tests/lint-planning-document-positive-control.test.cjs.
+const TEST_REGISTRY_OVERRIDE_ENV_VAR = 'LINT_PLANNING_DOCUMENT_POSITIVE_CONTROL_TEST_REGISTRY_OVERRIDE';
+
+/** CLI flag gate for the test-only override (see `TEST_REGISTRY_OVERRIDE_ENV_VAR`
+ * above). Must be passed explicitly in argv — never inferred from env — for
+ * `resolveRegistry`'s env-var override to be honored at all. */
+const TEST_REGISTRY_OVERRIDE_CLI_FLAG = '--test-registry-override';
+
+/** Resolve the registry to scan against: the real hardcoded registry, unless
+ * BOTH `allowOverride` is `true` (only ever set by the
+ * `--test-registry-override` CLI flag, see `TEST_REGISTRY_OVERRIDE_CLI_FLAG`)
+ * AND the test-only override env var is set and parses as JSON, in which
+ * case its keys are shallow-merged on top (see
+ * `TEST_REGISTRY_OVERRIDE_ENV_VAR`). Without `allowOverride === true`, the
+ * env var is never even read. */
+function resolveRegistry(env, allowOverride) {
+  if (!allowOverride) return POSITIVE_CONTROL_REGISTRY;
+  const override = env[TEST_REGISTRY_OVERRIDE_ENV_VAR];
+  if (!override) return POSITIVE_CONTROL_REGISTRY;
+  try {
+    const parsed = JSON.parse(override);
+    return { ...POSITIVE_CONTROL_REGISTRY, ...parsed };
+  } catch {
+    return POSITIVE_CONTROL_REGISTRY;
+  }
+}
+
+/**
+ * Extract the live `NodeKind` union members from `planning-document.cts`'s
+ * own source text — the "accepted grammars" set (ADR-4910 §4a) — read
+ * directly from source (never from the compiled seam, which erases the TS
+ * type) so a newly added grammar kind is detected even before any registry
+ * entry or fixture exists for it.
+ *
+ * Pure: takes a `readFile(relPath) -> string|null` accessor so tests can
+ * inject a scratch source file without touching the real repo tree.
+ */
+function readLiveGrammarKinds(readFile) {
+  const text = readFile(PLANNING_DOCUMENT_SRC);
+  if (text == null) {
+    return { ok: false, reason: `cannot read ${PLANNING_DOCUMENT_SRC}` };
+  }
+  const m = /export type NodeKind\s*=\s*([^;]+);/.exec(text);
+  if (!m) {
+    return {
+      ok: false,
+      reason: `could not find 'export type NodeKind = ...;' in ${PLANNING_DOCUMENT_SRC} — has the type been renamed or removed?`,
+    };
+  }
+  const kinds = [...m[1].matchAll(/'([^']+)'/g)].map((mm) => mm[1]);
+  if (kinds.length === 0) {
+    return {
+      ok: false,
+      reason: `the 'NodeKind' union in ${PLANNING_DOCUMENT_SRC} matched but contained no string-literal members`,
+    };
+  }
+  return { ok: true, value: kinds };
+}
+
+/**
+ * Pure: given the live grammar-kind list, the hardcoded registry, a
+ * `readFixture(fileName) -> string|null` accessor, the real `parsePlanningDoc`
+ * function, and the artifact name to parse fixtures as, find every gap.
+ * Returns `[{ kind, fixture?, reason }]`; empty when clean.
+ *
+ * Checks, per live grammar kind:
+ *  1. a registry entry exists at all (the §7 "parser without one fails the
+ *     build" guarantee — this fires even with an EMPTY registry);
+ *  2. the registered fixture file exists and is readable;
+ *  3. the fixture parses successfully via the real parser;
+ *  4. the parsed document actually contains a node of that kind (proof the
+ *     grammar was recognised, not just "didn't throw").
+ * Also flags a registry entry naming a grammar the parser no longer
+ * declares (a stale entry), so the registry cannot silently drift wider
+ * than the parser either.
+ */
+function findPositiveControlGaps(liveKinds, registry, readFixture, parsePlanningDocFn, artifactName) {
+  const violations = [];
+
+  for (const kind of liveKinds) {
+    const fixtureName = registry[kind];
+    if (!fixtureName) {
+      violations.push({
+        kind,
+        reason:
+          `parser declares grammar '${kind}' (NodeKind) but POSITIVE_CONTROL_REGISTRY has no entry for it — ` +
+          'add one and a matching fixture under tests/fixtures/planning-document/',
+      });
+      continue;
+    }
+
+    const content = readFixture(fixtureName);
+    if (content == null) {
+      violations.push({
+        kind,
+        fixture: fixtureName,
+        reason: `fixture file not found or unreadable: ${path.join(FIXTURE_DIR, fixtureName)}`,
+      });
+      continue;
+    }
+
+    const result = parsePlanningDocFn(content, artifactName);
+    if (!result.ok) {
+      violations.push({
+        kind,
+        fixture: fixtureName,
+        reason: `fixture failed to parse via parsePlanningDoc: ${result.reason}`,
+      });
+      continue;
+    }
+
+    const hasKind = result.value.nodes.some((n) => n.kind === kind);
+    if (!hasKind) {
+      violations.push({
+        kind,
+        fixture: fixtureName,
+        reason: `fixture parsed successfully but produced no '${kind}' node — it does not actually exercise this grammar`,
+      });
+    }
+  }
+
+  for (const kind of Object.keys(registry)) {
+    if (!liveKinds.includes(kind)) {
+      violations.push({
+        kind,
+        fixture: registry[kind],
+        reason: `registry entry names grammar '${kind}', which is not in the parser's live NodeKind union — stale entry, remove it`,
+      });
+    }
+  }
+
+  return violations;
+}
+
+/**
+ * Load the built seam and the real source/fixture tree rooted at `root`, and
+ * run `findPositiveControlGaps` against them. Returns the same shape as
+ * `findPositiveControlGaps`. If the seam hasn't been built yet, or the
+ * `NodeKind` union can't be located, reports a single actionable violation
+ * rather than throwing.
+ *
+ * `allowOverride` (default `false`) must be explicitly `true` for the
+ * test-only env-var registry override to be honored at all — see
+ * `resolveRegistry` and `TEST_REGISTRY_OVERRIDE_ENV_VAR`'s header comment.
+ */
+function scanRepo(root, env, allowOverride = false) {
+  const readFile = (relPath) => {
+    try {
+      return fs.readFileSync(path.join(root, relPath), 'utf8');
+    } catch {
+      return null;
+    }
+  };
+  const readFixture = (fileName) => readFile(path.join(FIXTURE_DIR, fileName));
+
+  const live = readLiveGrammarKinds(readFile);
+  if (!live.ok) {
+    return [{ kind: null, reason: live.reason }];
+  }
+
+  const libPath = path.join(root, PLANNING_DOCUMENT_LIB);
+  let seam;
+  try {
+    seam = require(libPath);
+  } catch (e) {
+    return [
+      {
+        kind: null,
+        reason: `cannot load the planning-document seam at ${path.relative(root, libPath)} — run 'npm run build:lib' first (${e.message})`,
+      },
+    ];
+  }
+
+  const registry = resolveRegistry(env || process.env, allowOverride);
+  return findPositiveControlGaps(live.value, registry, readFixture, seam.parsePlanningDoc, FIXTURE_ARTIFACT_NAME);
+}
+
+/** Parse a bare `--root <path>` CLI override (defaults to the real repo root)
+ * and the `--test-registry-override` flag that gates `resolveRegistry`'s
+ * env-var override (see `TEST_REGISTRY_OVERRIDE_CLI_FLAG`'s header comment).
+ * No real invocation (`npm run lint:ci`, `npm run lint:planning-document-
+ * positive-control`) ever passes this flag. */
+function parseArgs(argv) {
+  let root = path.join(__dirname, '..');
+  let allowTestRegistryOverride = false;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--root' && argv[i + 1]) {
+      root = path.resolve(argv[i + 1]);
+      i += 1;
+    } else if (argv[i] === TEST_REGISTRY_OVERRIDE_CLI_FLAG) {
+      allowTestRegistryOverride = true;
+    }
+  }
+  return { root, allowTestRegistryOverride };
+}
+
+function main() {
+  const { root, allowTestRegistryOverride } = parseArgs(process.argv.slice(2));
+  const violations = scanRepo(root, process.env, allowTestRegistryOverride);
+  if (violations.length === 0) {
+    process.stdout.write(
+      'ok planning-document-positive-control: every declared PlanningDoc grammar has a passing positive-control fixture\n',
+    );
+    return;
+  }
+  process.stderr.write(
+    'planning-document-positive-control: PlanningDoc grammar(s) missing or failing a positive-control fixture (ADR-4910 §7).\n',
+  );
+  process.stderr.write(
+    'Add/fix a fixture under tests/fixtures/planning-document/ and register it in POSITIVE_CONTROL_REGISTRY in\n' +
+      'scripts/lint-planning-document-positive-control.cjs — each fixture must round-trip through parsePlanningDoc\n' +
+      'and yield a node of the declared kind.\n',
+  );
+  for (const v of violations) {
+    const id = v.kind ?? '?';
+    const loc = v.fixture ? ` (${path.join(FIXTURE_DIR, v.fixture)})` : '';
+    process.stderr.write(`  ${id}${loc}: ${v.reason}\n`);
+  }
+  process.exitCode = 1;
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  findPositiveControlGaps,
+  readLiveGrammarKinds,
+  resolveRegistry,
+  scanRepo,
+  parseArgs,
+  POSITIVE_CONTROL_REGISTRY,
+  FIXTURE_ARTIFACT_NAME,
+  PLANNING_DOCUMENT_SRC,
+  PLANNING_DOCUMENT_LIB,
+  FIXTURE_DIR,
+  TEST_REGISTRY_OVERRIDE_ENV_VAR,
+  TEST_REGISTRY_OVERRIDE_CLI_FLAG,
+};

package/scripts/lint-response-language-coverage.cjs

@@ -78,7 +78,10 @@ const EXACT_INLINE_DIRECTIVE_WORKFLOWS = new Set([
   'discuss-phase/modes/text.md',
   'discuss-phase/templates/context.md',
   'discuss-phase/templates/discussion-log.md',
+  'execute-phase/steps/code-review-disposition.md',
   'execute-phase/steps/codebase-drift-gate.md',
+  'execute-phase/steps/gap-closure-artifacts.md',
+  'execute-phase/steps/regression-gate.md',
   'execute-phase/steps/regression-gate-run.md',
   'execute-phase/steps/worktree-recovery-policy.md',
   'help/modes/brief.md',

package/scripts/lint-skill-deps.cjs

@@ -29,6 +29,8 @@ const { runMain } = require('./lib/cli-exit.cjs');
 
 const PROFILES_MODULE = path.join(__dirname, '..', 'gsd-core', 'bin', 'lib', 'install-profiles.cjs');
 const { PROFILES, loadSkillsManifest, resolveProfile } = require(PROFILES_MODULE);
+// The one frontmatter fence owner, from the same build:lib output as install-profiles.
+const { locateFrontmatterFence } = require('../gsd-core/bin/lib/frontmatter-fence.cjs');
 
 // ---------------------------------------------------------------------------
 // Argument parsing
@@ -58,9 +60,11 @@ function extractBodyReferences(body) {
 }
 
 function extractBody(content) {
-  const fmEnd = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n/m);
-  if (!fmEnd) return content;
-  return content.slice(fmEnd[0].length);
+  // The block is the one the one fence owner finds (found while implementing #5105);
+  // the body starts past the closing fence line and its line ending.
+  const fence = locateFrontmatterFence(content);
+  if (!fence || !fence.closed) return content;
+  return content.slice(fence.closingFenceEnd).replace(/^\r?\n/, '');
 }
 
 // ---------------------------------------------------------------------------

package/scripts/lint-test-file-count.allowlist.json

@@ -142,6 +142,7 @@
       "files": [
         "verify-archive-dirs-live-path.test.cjs",
         "verify-health.test.cjs",
+        "verify-lifecycle-writes-e2e.test.cjs",
         "verify-mvp-uat.test.cjs",
         "verify-npm-publish.test.cjs",
         "verify-test-quality.test.cjs",
@@ -150,7 +151,7 @@
         "verify.test.cjs"
       ],
       "issue": "#3813 — the live-path #1883 suite drives buildPlanningSnapshot in-process with an fs fault; the verify module suites are CLI-driving and cannot host an fs monkeypatch",
-      "justification": "verify-command-grounding added by #2401/#3678; allowlist follow-up landed with #3606 (base was red on this lane). #4546 adds verify-work-deferred-promotion (deferred-follow-up promotion writer contract + parity)."
+      "justification": "verify-command-grounding added by #2401/#3678; allowlist follow-up landed with #3606 (base was red on this lane). #4546 adds verify-work-deferred-promotion (deferred-follow-up promotion writer contract + parity). #5105 adds verify-lifecycle-writes-e2e.test.cjs (Phase 3 of #5056: end-to-end fixture proving the fixed post-fingerprint verbs leave an unchanged re-run fresh, plus its own pre-fix CONTROL — a distinct end-to-end concern from the existing per-verb unit suites)."
     },
     "install": {
       "files": [
@@ -293,6 +294,15 @@
       ],
       "issue": "4657",
       "justification": "The ui-consideration-probe cluster gains its workflow-prose contract file (tests/ui-consideration-probe-ui-phase-contract.test.cjs, #4657), mirroring the edge probe's split (edge-probe.test.cjs / edge-probe-docs-fixtures.test.cjs / edge-probe-spec-phase-contract.test.cjs). The contract file reads shipped gsd-core/workflows/ui-phase.md under the source-text-is-the-product exception, which the unit file deliberately does not carry (it asserts typed returns only)."
+    },
+    "verification": {
+      "files": [
+        "verification-append-audit.test.cjs",
+        "verification-overrides.test.cjs",
+        "verification-status.test.cjs"
+      ],
+      "issue": "5105",
+      "justification": "#5105 (Phase 3 of #5056) adds verification-append-audit.test.cjs for the new `verification.append-audit` verb (deny-by-default audit-block append/no-op, #4887) — a distinct concern from verification-status.test.cjs's status/fingerprint suite and verification-overrides.test.cjs's override handling."
     }
   }
 }