@opengsd/gsd-core 1.11.0 → 1.13.0

package/scripts/lint-docs-guard-registration.exempt-baseline.cjs

@@ -0,0 +1,198 @@
+'use strict';
+
+/**
+ * Pinned baseline for scripts/lint-docs-guard-registration.cjs's
+ * `docs-guard-exempt` identity ratchet — mirrors
+ * scripts/lint-allow-test-rule-refs.cjs's `allow-test-rule` ratchet
+ * (scripts/lib/allowlist-ratchet.cjs, ADR-456's pattern).
+ *
+ * Every test file basename here is a KNOWN, already-reviewed
+ * `// docs-guard-exempt: <reason>` marker. Nothing caps how many files may
+ * carry the marker in the abstract, but ADDING a new one anywhere in
+ * tests/*.test.cjs fails `lint-docs-guard-registration` until this baseline
+ * is deliberately updated — so a new exemption always shows up as a
+ * reviewable diff here, instead of silently opting a file out of the
+ * docs-guard registration requirement with zero signal.
+ *
+ * A file listed here that no longer exists, or no longer carries a real
+ * `docs-guard-exempt:` marker in its first 20 lines, is reported STALE and
+ * must be pruned (ratchet-down, same as the sibling gate).
+ *
+ * Seeded 2026-08-23 (#3753 security follow-up FIX 2) from every real marker
+ * found via scripts/lint-docs-guard-registration.cjs's own `findExemption`
+ * scan of tests/*.test.cjs — derived, not retyped from memory.
+ *
+ * Extended 2026-08-23 (#3753 correctness follow-up): the reader-detection
+ * fixes (Defects A/B/C) surfaced 86 previously-undetected docs/ readers. 40
+ * were genuine docs-content guards (added to DOCS_GUARD_TESTS in
+ * scripts/docs-guard-registry.cjs); the 46 added here touch a docs/ path
+ * only incidentally (fixture data, external URL citations, comment-only
+ * mentions, metadata labels, or scan-exclusion lists) — see each file's own
+ * `docs-guard-exempt:` marker for its specific reason.
+ */
+const DOCS_GUARD_EXEMPT_BASELINE = [
+  'adr-612-bracket-phase-counting.test.cjs',
+  'adr-parser.test.cjs',
+  'adr-parser.unit.test.cjs',
+  'agent-marker-documentation-guard.test.cjs',
+  'antigravity-upgrades.test.cjs',
+  'capability-cli.test.cjs',
+  'capability-validator-task-content-resolver.test.cjs',
+  'ci-docs-guard-registry.test.cjs',
+  'ci-test-scope.test.cjs',
+  'cline-install.test.cjs',
+  'code-review-depth.test.cjs',
+  'code-review-pipeline-regression.test.cjs',
+  'codebuddy-upgrades.test.cjs',
+  'commands.test.cjs',
+  'commit-docs-bypass.test.cjs',
+  'complexity-trigger.test.cjs',
+  'concurrency-safety.test.cjs',
+  'cursor-imperative-reference.test.cjs',
+  'declarative-reference-antigravity.test.cjs',
+  'declarative-reference-zcode.test.cjs',
+  'emitted-attribution.test.cjs',
+  'eslint-rules.test.cjs',
+  'estimate-calibrate.test.cjs',
+  'gen-context-index.test.cjs',
+  'gen-registry.test.cjs',
+  'gsd-agent-isolation-guard.test.cjs',
+  'hermes-dispatch-upgrade.test.cjs',
+  'install-minimal-hooks.test.cjs',
+  'install-runtime-artifacts.test.cjs',
+  'installer-migration-config-root-marker.test.cjs',
+  'installer-migration-pi-extension-ext.test.cjs',
+  'installer-migrations.test.cjs',
+  'kimi-upgrades.test.cjs',
+  'lint-allow-test-rule-refs.test.cjs',
+  'lint-docs-command-form.test.cjs',
+  'lint-docs-required.test.cjs',
+  'manifest-version-sync.test.cjs',
+  'milestone-archive.test.cjs',
+  'model-resolver.test.cjs',
+  'new-project-mvp-prompt.test.cjs',
+  'onboard-command.test.cjs',
+  'opencode-command-dir-plural.test.cjs',
+  'phase.test.cjs',
+  'pr-branch-planning-filter.test.cjs',
+  'precommit-alias-drift-hook.test.cjs',
+  'removed-but-needed-lint.test.cjs',
+  'repo-invariants.test.cjs',
+  'require-issue-link-policy.test.cjs',
+  'reviewer-manifest-body.test.cjs',
+  'run-tests-harness.test.cjs',
+  'runtime-name-policy.test.cjs',
+  'security-prompt-injection.security.test.cjs',
+  'shipped-reference-cites.test.cjs',
+  'state.test.cjs',
+  'worktree-safety.test.cjs',
+];
+
+/**
+ * Security follow-up FIX 3: a per-file fingerprint of every distinct
+ * `docs/...` path TOKEN referenced by each baselined file (derived via
+ * scripts/lint-docs-guard-registration.cjs's `extractDocsPathReferences`,
+ * never retyped from memory). A baselined file whose live fingerprint
+ * DIFFERS from the recorded one here fails the lint — the exemption's
+ * premise ("this file doesn't really guard shipped docs content") may no
+ * longer hold and a human must re-confirm it before the entry is updated.
+ * Keeping this a plain, sorted, diffable path list (not a hash) is
+ * deliberate: a reviewer can see exactly WHAT changed from the PR diff
+ * alone.
+ *
+ * Seeded 2026-08-23 alongside DOCS_GUARD_EXEMPT_BASELINE above, from the
+ * exact same scan.
+ */
+const DOCS_GUARD_EXEMPT_DOCS_PATHS = {
+  // #2761: cites docs/adr/612-bracket-phase-id-convention.md in an explanatory
+  // comment describing ADR-612's Decision 1; the file never reads that (or any)
+  // docs/ file — every read call it makes targets a tmpdir .planning fixture.
+  'adr-612-bracket-phase-counting.test.cjs': ['docs/adr/612-bracket-phase-id-convention.md'],
+  'adr-parser.test.cjs': ['docs/adr/0001.md', 'docs/adr/0002.md', 'docs/adr/0010.md', 'docs/adr/NNNN.md'],
+  'adr-parser.unit.test.cjs': ['docs/adr/0001.md', 'docs/adr/0099.md', 'docs/adr/NNNN.md'],
+  'agent-marker-documentation-guard.test.cjs': ['docs/reference', 'docs/reference/workflow-fragments.md'],
+  'antigravity-upgrades.test.cjs': ['docs/cli', 'docs/cli/gcli-migration', 'docs/cli/permissions'],
+  'capability-cli.test.cjs': ['docs/reference/gsd-capability-command.md'],
+  // #3970: cites docs/adr/3646-per-task-content-resolution-seam.md in an
+  // explanatory comment describing ADR-3646's Decision 3; the file never
+  // reads that (or any) docs/ file.
+  'capability-validator-task-content-resolver.test.cjs': ['docs/adr/3646-per-task-content-resolution-seam.md'],
+  'ci-docs-guard-registry.test.cjs': [
+    'docs/AGENTS.md', 'docs/COMMANDS.md', 'docs/INVENTORY.md', 'docs/a.md', 'docs/adr',
+    'docs/adr/0001-example.md', 'docs/adrenaline.md', 'docs/bar.md', 'docs/foo.md', 'docs/how-to/foo.md',
+    'docs/how-to/some-unrelated-guide.md', 'docs/how-to/x.md', 'docs/some-unrelated-file.md',
+    'docs/totally-unrelated.md',
+  ],
+  'ci-test-scope.test.cjs': [
+    'docs/a.md', 'docs/adr', 'docs/adr/22-plan-drift-guard.md', 'docs/how-to/configure-model-profiles.md',
+    'docs/installer-migrations.md', 'docs/ja-JP', 'docs/ja-JP/USAGE.md', 'docs/usage.md', 'docs/x.md',
+  ],
+  'cline-install.test.cjs': ['docs/guide.md'],
+  'code-review-depth.test.cjs': ['docs/src/auth/x.ts'],
+  'code-review-pipeline-regression.test.cjs': ['docs/DEVELOPMENT.md'],
+  'codebuddy-upgrades.test.cjs': ['docs/cli/sub-agents'],
+  'commands.test.cjs': ['docs/x.md'],
+  'commit-docs-bypass.test.cjs': [
+    'docs/40-design.md', 'docs/CONFIGURATION.md', 'docs/readme.md', 'docs/tracked-var-mentioning',
+  ],
+  'complexity-trigger.test.cjs': ['docs/readme.md'],
+  // #3884: cites docs/CLI-TOOLS.md:736 in an explanatory comment describing
+  // the real `frontmatter get <file> [--field key]` CLI shape; the file
+  // never reads that (or any) docs/ file.
+  'concurrency-safety.test.cjs': ['docs/CLI-TOOLS.md'],
+  'cursor-imperative-reference.test.cjs': ['docs/sdk/typescript'],
+  'declarative-reference-antigravity.test.cjs': ['docs/cli/features'],
+  'declarative-reference-zcode.test.cjs': ['docs/reference/host-integration-capability-matrix.md'],
+  'emitted-attribution.test.cjs': ['docs/README.md', 'docs/tests', 'docs/tests/helpers/install-shared.cjs'],
+  // #3914: cites docs/adr/3889-process-exit-contract.md ~:350-362 in an
+  // explanatory comment describing the intentional computed-property
+  // boundary move; the file never reads that (or any) docs/ file.
+  'eslint-rules.test.cjs': ['docs/adr/3889-process-exit-contract.md', 'docs/readme.md'],
+  'estimate-calibrate.test.cjs': [
+    'docs/adr', 'docs/adr/2629-phase-effort-estimation-calibration.md', 'docs/reference',
+    'docs/reference/planning-artifacts.md',
+  ],
+  'gen-context-index.test.cjs': ['docs/CONTEXT-INDEX.json', 'docs/INVENTORY-MANIFEST.json'],
+  'gen-registry.test.cjs': ['docs/registries', 'docs/registries/reviewers.json'],
+  'gsd-agent-isolation-guard.test.cjs': ['docs/adr/1239-...md', 'docs/adr/1239-gsd-embeddable-orchestration-engine.md'],
+  'hermes-dispatch-upgrade.test.cjs': ['docs/guides/delegation-patterns.md'],
+  'install-minimal-hooks.test.cjs': ['docs/en/hooks', 'docs/en/users/features/hooks'],
+  'install-runtime-artifacts.test.cjs': ['docs/CONFIGURATION.md', 'docs/adr/58-...md', 'docs/adr/58-runtime-install-policy-module.md', 'docs/cli/slash-commands'],
+  'installer-migration-config-root-marker.test.cjs': ['docs/installer-migrations.md'],
+  'installer-migration-pi-extension-ext.test.cjs': ['docs/installer-migrations.md'],
+  'installer-migrations.test.cjs': ['docs/installer-migrations.md'],
+  'kimi-upgrades.test.cjs': ['docs/reference/host-integration-capability-matrix.md'],
+  'lint-allow-test-rule-refs.test.cjs': ['docs/readme.md'],
+  'lint-docs-command-form.test.cjs': ['docs/adr', 'docs/adr/999-example.md', 'docs/how-to/example.md'],
+  'lint-docs-required.test.cjs': [
+    'docs/COMMANDS.md', 'docs/USER-GUIDE.md', 'docs/adr', 'docs/adr/0001-foo.md', 'docs/adr/0099-new.md',
+    'docs/agents', 'docs/agents/triage-labels.md',
+  ],
+  'manifest-version-sync.test.cjs': [],
+  // #3884: re-confirmed — the added docs/CLI-TOOLS.md:458 reference is the
+  // same class as the existing docs/TESTING-SUITES.md one (a placement-note
+  // / explanatory comment citing documented CLI behavior for context, never
+  // a read target); the exemption's premise still holds for both.
+  'milestone-archive.test.cjs': ['docs/CLI-TOOLS.md', 'docs/TESTING-SUITES.md'],
+  'model-resolver.test.cjs': ['docs/TESTING-SUITES.md'],
+  'new-project-mvp-prompt.test.cjs': ['docs/CONFIGURATION.md'],
+  'onboard-command.test.cjs': ['docs/adr/0001-runtime.md'],
+  'opencode-command-dir-plural.test.cjs': ['docs/commands'],
+  'phase.test.cjs': ['docs/adr/3524-...md', 'docs/adr/3524-cjs-sdk-hard-seam.md'],
+  'pr-branch-planning-filter.test.cjs': ['docs/readme.md'],
+  'precommit-alias-drift-hook.test.cjs': ['docs/adr/0174-...md', 'docs/adr/0174-retire-gsd-sdk-package-boundary.md'],
+  'removed-but-needed-lint.test.cjs': [
+    'docs/README.md', 'docs/getting-started.md', 'docs/gsd-new-workspace.md', 'docs/setup.md', 'docs/some-doc.md',
+  ],
+  'repo-invariants.test.cjs': ['docs/FEATURES.md', 'docs/workflows/README'],
+  'require-issue-link-policy.test.cjs': ['docs/-prefixed', 'docs/CONFIGURATION.md', 'docs/a.md', 'docs/b.md', 'docs/guide.md'],
+  'reviewer-manifest-body.test.cjs': ['docs/how-to/ship-a-reviewer-lane.md'],
+  'run-tests-harness.test.cjs': ['docs/TESTING-SUITES.md'],
+  'runtime-name-policy.test.cjs': ['docs/customize/skills'],
+  'security-prompt-injection.security.test.cjs': ['docs/notes.md'],
+  'shipped-reference-cites.test.cjs': [],
+  'state.test.cjs': ['docs/CONFIGURATION.md', 'docs/reference/state-md.md'],
+  'worktree-safety.test.cjs': ['docs/SUMMARY.md'],
+};
+
+module.exports = { DOCS_GUARD_EXEMPT_BASELINE, DOCS_GUARD_EXEMPT_DOCS_PATHS };

package/scripts/lint-eslint-glob-coverage.allowlist.json

@@ -7,6 +7,10 @@
     "path": "src/vendor/re2js.d.cts",
     "reason": "Vendored third-party type declaration (#3477): a .d.cts carries no executable code, so no ESLint rule is meaningful; the vendored .cjs it describes is globally ignored as verbatim upstream output. Freshness is enforced by scripts/lint-vendored-deps.cjs, not by lint rules."
   },
+  {
+    "path": "src/vendor/js-yaml.d.cts",
+    "reason": "Vendored third-party type declaration (ADR-3473 §8.1, #3881): a .d.cts carries no executable code, so no ESLint rule is meaningful; the vendored js-yaml .cjs it describes is globally ignored as verbatim upstream output (gsd-core/bin/lib/vendor/**). Freshness is enforced by scripts/lint-vendored-deps.cjs, not by lint rules — same precedent as src/vendor/re2js.d.cts above."
+  },
   {
     "path": "tests/fixtures/brand-typing/bad-calibrated-as-sample-basis.cts",
     "reason": "Deliberate MUST-NOT-COMPILE type-error fixture (#3059): type-aware linting would fail by design; it exists to prove the compiler rejects it."

package/scripts/{lint-fix-has-regression-test.cjs → lint-fix-has-regression-tests.cjs}

@@ -2,10 +2,16 @@
 'use strict';
 
 /**
- * lint-fix-has-regression-test.cjs — gate: every fix(#NNNN) commit must
+ * lint-fix-has-regression-tests.cjs — gate: every fix(#NNNN) commit must
  * include at least one behavioral test file (tests/*.test.cjs) that is NOT
  * an auto-generated fixture/baseline.
  *
+ * Renamed (was `lint-fix-has-regression-test.cjs`, singular): the old
+ * basename matched Node's `*-test.EXT` test-collection pattern, so the
+ * remote push-gate runner collected and executed this SOURCE file as a
+ * test while GitHub CI (which globs only tests/**\/*.test.cjs) never saw
+ * it — see scripts/lint-source-test-name-collision.cjs.
+ *
  * ## Why
  *
  * CONTRIBUTING.md:47: "Fix it. Write a test that would have caught the bug."
@@ -82,7 +88,7 @@ function getChangedTestFiles(baseRef) {
 
 function main() {
   if (process.env.GSD_SKIP_REGRESSION_TEST_GATE === '1') {
-    console.log('lint-fix-has-regression-test: SKIPPED (GSD_SKIP_REGRESSION_TEST_GATE=1)');
+    console.log('lint-fix-has-regression-tests: SKIPPED (GSD_SKIP_REGRESSION_TEST_GATE=1)');
     return;
   }
 
@@ -92,12 +98,12 @@ function main() {
   try {
     fixCommits = getFixCommits(baseRef);
   } catch {
-    console.log(`lint-fix-has-regression-test: no fix/feat commits found vs ${baseRef}, skipping`);
+    console.log(`lint-fix-has-regression-tests: no fix/feat commits found vs ${baseRef}, skipping`);
     return;
   }
 
   if (fixCommits.length === 0) {
-    console.log('lint-fix-has-regression-test: no fix/feat commits, passing');
+    console.log('lint-fix-has-regression-tests: no fix/feat commits, passing');
     return;
   }
 
@@ -113,7 +119,7 @@ function main() {
       .map((c) => `  ${c.sha} ${c.subject}`)
       .join('\n');
     throw new ExitError(1,
-      `lint-fix-has-regression-test: ${fixCommits.length} fix/feat commit(s) but ZERO behavioral test files (*.test.cjs) in the diff.\n` +
+      `lint-fix-has-regression-tests: ${fixCommits.length} fix/feat commit(s) but ZERO behavioral test files (*.test.cjs) in the diff.\n` +
       `Auto-generated fixtures (tests/fixtures/, *-baseline.json) do NOT count.\n\n` +
       `Fix commits:\n${commitList}\n\n` +
       `CONTRIBUTING.md:47: "Write a test that would have caught the bug."\n` +
@@ -123,7 +129,7 @@ function main() {
   }
 
   console.log(
-    `lint-fix-has-regression-test: PASS — ${fixCommits.length} fix/feat commit(s), ` +
+    `lint-fix-has-regression-tests: PASS — ${fixCommits.length} fix/feat commit(s), ` +
     `${testFiles.length} behavioral test file(s): ${testFiles.join(', ')}`
   );
 }

package/scripts/lint-health-diagnostic-rule-table.cjs

@@ -58,7 +58,7 @@
  * real, non-mocked `buildPlanningSnapshot(tmpCwd)` call (see
  * `tests/health-diagnostic-rules/root-existence.test.cjs`). This guard
  * therefore verifies the fixture-proof invariant STATICALLY against the
- * test files' own text — mirroring `scripts/lint-fix-has-regression-test.cjs`'s
+ * test files' own text — mirroring `scripts/lint-fix-has-regression-tests.cjs`'s
  * house style — rather than dynamically re-running fixture-building code
  * this guard does not own.
  */
@@ -82,14 +82,70 @@ const CONSISTENCY_TEST_FILE = path.join(REPO_ROOT, 'tests', 'health-diagnostic-r
 const CONSISTENCY_CODE_PREFIX_RE = /^C\d{3}$/;
 
 // Phase 12 (#3310, ADR-3180 §8.5 extension) — the S0NN namespace's own
-// fixture-proof pass. These 7 codes are NOT collected in any exported
-// `Rule[]` array: `cmdStateValidate` (src/state.cts) builds `Diagnostic[]`
-// directly via a local `stateDiagnostic()` helper, not via the rule-table
-// evaluator (out of scope for the RULES/CONSISTENCY_RULES-keyed passes
-// above). The list is therefore hardcoded here instead of read from the
-// compiled module.
+// fixture-proof pass. These codes are NOT collected in any exported `Rule[]`
+// array: `cmdStateValidate` (src/state.cts) builds `Diagnostic[]` directly via
+// a local `stateDiagnostic()` helper, not via the rule-table evaluator (out of
+// scope for the RULES/CONSISTENCY_RULES-keyed passes above).
+//
+// #3696: the list is DISCOVERED from the source, not hardcoded. It used to be a
+// literal `['S001', ..., 'S007']`, which is precisely the shape ADR-3180
+// Decision 4(a) forbids — "guards discover call sites by whole-repo scan, never
+// by an allowlist of known files" — because such a guard can only ever be as
+// complete as the author's recall. Adding S008/S009 to `cmdStateValidate` left
+// this pass reporting a confident, green "7 code(s), all fixture-covered" while
+// two new codes had no fixture requirement at all: a zero it did not earn. The
+// scan below cannot report a code it has not read out of the source.
 const STATE_VALIDATE_TEST_FILE = path.join(REPO_ROOT, 'tests', 'state.test.cjs');
-const STATE_VALIDATE_CODES = ['S001', 'S002', 'S003', 'S004', 'S005', 'S006', 'S007'];
+const STATE_VALIDATE_SOURCE_FILE = path.join(REPO_ROOT, 'src', 'state.cts');
+// `g` is required by String.prototype.matchAll, which (unlike .exec) does not
+// carry lastIndex across calls — so this constant is safe to share.
+// #3696 review: `\s*` before `(` too. Requiring no space silently dropped a
+// `stateDiagnostic ('S010', …)` call site from the discovered set, and since the
+// fail-closed check below only fires on a FULLY empty result, a partial miss
+// escaped the fixture-proof check entirely — the same "only as complete as the
+// author's recall" failure this rewrite exists to prevent.
+const STATE_DIAGNOSTIC_CALL_RE = /\bstateDiagnostic\s*\(\s*(['"`])(S\d{3})\1/g;
+
+/**
+ * Every S0NN code `cmdStateValidate` can emit, read off its
+ * `stateDiagnostic(...)` call sites in `sourceText`.
+ *
+ * Takes the source TEXT rather than reading the path itself, so the discovery
+ * rule is exercisable against controlled fixtures — including the fail-closed
+ * path below, which is the branch that matters and which a path-reading
+ * function could only be tested on by mutating the real `src/state.cts`.
+ *
+ * Fails closed. An empty result means the helper was renamed or its call shape
+ * changed, and a guard that answers "0 codes, all covered" to that is worse than
+ * no guard — so it raises instead. Line/regex-based (not full AST) per this
+ * repo's existing lint-guard house style, same as TITLED_BLOCK_RE below.
+ */
+function discoverStateValidateCodes(sourceText, sourceLabel = formatRepoRelative(STATE_VALIDATE_SOURCE_FILE)) {
+  const codes = [...sourceText.matchAll(STATE_DIAGNOSTIC_CALL_RE)].map((m) => m[2]);
+  const unique = [...new Set(codes)].sort();
+  if (unique.length === 0) {
+    throw new ExitError(
+      1,
+      `lint-health-diagnostic-rule-table: found no stateDiagnostic() call sites in ${sourceLabel}.\n`
+        + '  This pass discovers the S0NN code set from those call sites (#3696), so an empty\n'
+        + '  result means the helper was renamed or its call shape changed — not that there are\n'
+        + '  no codes. Update STATE_DIAGNOSTIC_CALL_RE to match the new shape.\n',
+    );
+  }
+  return unique;
+}
+
+function readStateValidateSource() {
+  if (!fs.existsSync(STATE_VALIDATE_SOURCE_FILE)) {
+    throw new ExitError(
+      1,
+      `lint-health-diagnostic-rule-table: cannot discover S0NN codes — ${formatRepoRelative(STATE_VALIDATE_SOURCE_FILE)} not found.\n`,
+    );
+  }
+  return fs.readFileSync(STATE_VALIDATE_SOURCE_FILE, 'utf8');
+}
+
+const STATE_VALIDATE_CODES = discoverStateValidateCodes(readStateValidateSource());
 
 // Matches `describe(`/`test(`/`it(` calls whose first argument is a string
 // literal, capturing that literal as the block's title. Line/regex-based
@@ -401,4 +457,5 @@ module.exports = {
   CONSISTENCY_TEST_FILE,
   STATE_VALIDATE_TEST_FILE,
   STATE_VALIDATE_CODES,
+  discoverStateValidateCodes,
 };

package/scripts/lint-mutation-test-derivation-drift.cjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * scripts/lint-mutation-test-derivation-drift.cjs
+ *
+ * #3881 follow-up ("one YAML parser" mutation-matrix piece 2): guards the
+ * derivation engine in scripts/mutation-matrix.cjs against the exact drift
+ * class PR #3888 shipped — a test file added on a branch that directly
+ * `require()`s a covered module's built artifact AND names itself after that
+ * module (`<module>.test.cjs` / `<module>.property.test.cjs` /
+ * `<module>-anything.test.cjs`), yet is never wired into that module's
+ * mutation shard.
+ *
+ * `scripts/mutation-matrix.cjs`'s `computeModuleTests` already derives most of
+ * a module's `tests` array automatically from exactly that (require + naming)
+ * signal, so a NEWLY drifting file of that shape is normally impossible — it
+ * would be auto-included the moment it exists. What this guard catches is the
+ * one case the derivation cannot self-correct: a file matching BOTH signals
+ * that the module's own `excludeTests` withholds. `excludeTests` entries are
+ * a deliberate, reasoned decision (see mutation-matrix.cjs's per-module
+ * comments) — this guard does not second-guess that decision, but it DOES
+ * verify every such file is EITHER accounted for in `tests` (auto-derived or
+ * `extraTests`) OR named in `excludeTests`. A file satisfying both signals
+ * that is in NEITHER list is exactly the drift #3888 shipped: nobody made a
+ * decision about it at all.
+ *
+ * Pure core (`findDrift`) so tests can drive it against a synthetic COVERED +
+ * requiring-files map without touching the real tests/ tree; `main()` wires
+ * it to the real repo for `npm run lint:ci`.
+ */
+
+const path = require('node:path');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+/**
+ * Pure: for every module in `covered`, every file in `requiringFiles[module]`
+ * that ALSO matches the module's naming rule must be present in either
+ * `covered[module].tests` (already `tests/`-prefixed, as computeModuleTests
+ * emits it) or `covered[module].excludeTests` (bare basenames). Anything
+ * matching both signals but present in neither is reported as drift.
+ *
+ * @param {object} covered - mutation-matrix.cjs's COVERED (post `computeModuleTests`)
+ * @param {(moduleName: string) => string[]} findRequiringTestFiles - basenames requiring the module's artifact
+ * @param {(moduleName: string, file: string) => boolean} matchesModuleNamingRule
+ * @returns {{module: string, file: string}[]}
+ */
+function findDrift(covered, findRequiringTestFiles, matchesModuleNamingRule) {
+  const drift = [];
+  for (const [moduleName, entry] of Object.entries(covered)) {
+    const testsSet = new Set((entry.tests || []).map((t) => path.basename(t)));
+    const excludeSet = new Set(entry.excludeTests || []);
+    for (const file of findRequiringTestFiles(moduleName)) {
+      if (!matchesModuleNamingRule(moduleName, file)) continue;
+      if (testsSet.has(file) || excludeSet.has(file)) continue;
+      drift.push({ module: moduleName, file });
+    }
+  }
+  return drift;
+}
+
+function main() {
+  const {
+    COVERED,
+    findRequiringTestFiles,
+    matchesModuleNamingRule,
+  } = require('./mutation-matrix.cjs');
+
+  const drift = findDrift(COVERED, findRequiringTestFiles, matchesModuleNamingRule);
+
+  if (drift.length === 0) {
+    console.log(`ok mutation-test-derivation-drift: every module-named test file requiring a covered module has an explicit disposition (${Object.keys(COVERED).length} modules checked)`);
+    return;
+  }
+
+  console.error('mutation-test-derivation-drift: test file(s) require a covered module and match its naming rule, but have no disposition in scripts/mutation-matrix.cjs (neither auto-derived/extraTests nor excludeTests):');
+  for (const d of drift) {
+    console.error(`  [${d.module}] tests/${d.file}`);
+  }
+  console.error('\n  remedy: in scripts/mutation-matrix.cjs, either let it auto-derive (do nothing further if it already appears in COVERED[<module>].tests), or add it to extraTests, or add a REASONED excludeTests entry explaining why it is deliberately withheld from the mutation shard.');
+  throw new ExitError(1);
+}
+
+module.exports = { findDrift };
+
+if (require.main === module) runMain(main);

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

@@ -62,20 +62,35 @@
  * outstanding WORK wants the live set"): a LOOKUP, DIAGNOSTIC or ARCHIVAL
  * pass wants the physical set; only "which phases belong to this milestone"
  * wants the scoped set.
- *   - `src/roadmap.cts` `cmdRoadmapAnalyze`: builds `_phaseDirNames` as a
- *     heading->directory LOOKUP INDEX, not a milestone enumeration. It must
- *     see the PHYSICAL set so a heading already scoped by
- *     `extractCurrentMilestoneScoped` can find its directory; filtering it
- *     through the owner would scope the same set twice.
+ *   - `src/roadmap.cts` `cmdRoadmapAnalyze` — MIGRATED (#3882, ADR-3473 §8.2):
+ *     `_phaseDirNames`, a heading->directory LOOKUP INDEX (not a milestone
+ *     enumeration; must see the PHYSICAL set so a heading already scoped by
+ *     `extractCurrentMilestoneScoped` can find its directory), now calls
+ *     `listAllPhaseDirs(phasesDir, { includeSentinels: true })` instead of a
+ *     hand-rolled `readdirSync` — no longer exempted, since there is nothing
+ *     left in this function for either detector to catch.
+ *   - `src/init.cts` `cmdInitMilestoneOp`'s `diskPhaseDirs` — MIGRATED (#3882,
+ *     ADR-3473 §8.2): the same heading->directory LOOKUP INDEX shape as
+ *     `cmdRoadmapAnalyze`'s `_phaseDirNames` above, now calls
+ *     `listAllPhaseDirs(phasesDir, { includeSentinels: true })`. Its sibling
+ *     readdirSync (the no-ROADMAP-headings-found fallback) was already routed
+ *     through `listMilestonePhaseDirs` before this phase and remains so — no
+ *     longer exempted; the function's other former exemption reason
+ *     (`detectHasPriorPhases`/`detectUiPhaseActive`, unrelated call sites in
+ *     the same file) is unaffected.
  *   - `src/verify.cts` `cmdValidateHealth`: a project-wide HEALTH-CHECK sweep
  *     (config drift, phase-directory naming, duplicate-directory collisions,
  *     unsummarized-plan detection) — same "sweep everything, report gaps"
  *     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` `cmdVerifySchemaDrift`: resolves ONE caller-supplied
+ *   - `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/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.
@@ -117,8 +132,10 @@
  *     `--include-archived` merge are phase LOCATION and archive
  *     enumeration, not current-milestone enumeration; both legitimately
  *     read the physical set. Its ENUMERATION path routes through the owner.
- *   - `src/roadmap-parser.cts` `getMilestonePhaseFilter` and its #3262-extracted
- *     set-building owner `scanMilestonePhaseIds` (the same two heading/
+ *   - `src/roadmap-parser.cts` `getMilestonePhaseFilter` and its shared
+ *     set-building implementation `scanMilestonePhaseIdSets` (the public
+ *     `scanMilestonePhaseIds` wrapper remains a directly iterable Set; the
+ *     same two heading/
  *     #3577 `collectTablePhaseRows` — the table-scan sibling feeding the same
  *     membership set; its local 999-only exclusion mirrors the owner's
  *     deliberate NOT-isSentinelPhaseId choice (a leading 0 is a real decimal
@@ -131,6 +148,18 @@
  *     ("00.1" is a real phase, not milestone 0). This scan asks a narrower
  *     question — "which phase ids does this milestone's window declare" —
  *     where only the 999 icebox range is excluded.
+ *   - `src/state.cts` `countRoadmapPhaseHeadings`: its bracket branch composes
+ *     bracket-milestone sentinel detection through `isSentinelPhaseId`, but
+ *     retains a separate bare-token `999` rule. That rule intentionally does
+ *     NOT use the convention-blind canonical predicate: the latter also reads
+ *     leading `0`/`00.1` as milestone-0 sentinels, while a legacy-spelled bare
+ *     zero token inside an opted-in bracket project is a real mid-migration
+ *     phase. This is the state-counter twin of the roadmap-parser exemption.
+ *     The guard has no per-detector exemption scope: it ORs the enumeration
+ *     and sentinel detectors before consulting this function-only map. The
+ *     whole-function exemption is therefore accepted; it is bounded because
+ *     this counter performs no phases-directory `readdirSync` and needs the
+ *     exemption only for its intentional bare-token `999` sentinel literal.
  *   - `src/state.cts` `cmdStateValidate` ("Gate 1: Validate STATE.md against
  *     filesystem"): resolves ONE directory — the disk match for STATE.md's
  *     own `Current Phase` field — by prefix, a single-phase LOOKUP, not an
@@ -280,17 +309,19 @@ 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', 'roadmap.cts'), new Set(['cmdRoadmapAnalyze'])],
-  [path.join('src', 'verify.cts'), new Set(['cmdValidateHealth', 'cmdVerifySchemaDrift'])],
-  [path.join('src', 'init.cts'), new Set(['detectHasPriorPhases', 'detectUiPhaseActive', 'cmdInitMilestoneOp'])],
+  [path.join('src', 'verify.cts'), new Set(['cmdValidateHealth', 'resolvePhaseDirByToken'])],
+  [path.join('src', 'init.cts'), new Set(['detectHasPriorPhases', 'detectUiPhaseActive'])],
   [path.join('src', 'milestone.cts'), new Set(['archivePhaseDirectories', 'cmdMilestoneComplete', 'cmdPhasesClear'])],
-  [path.join('src', 'phase.cts'), new Set(['cmdPhasesList', 'cmdPhaseNextDecimal', 'cmdPhasePlanIndex', 'cmdPhaseInsert', 'renameDecimalPhases', 'renameIntegerPhases'])],
+  // #3849: collectSiblingWorktreePhaseNums reads a SIBLING worktree's phases dir —
+  // a different checkout listMilestonePhaseDirs (cwd-scoped) cannot serve; the
+  // allocators' own on-disk scans stay unexempted.
+  [path.join('src', 'phase.cts'), new Set(['cmdPhasesList', 'cmdPhaseNextDecimal', 'cmdPhasePlanIndex', 'cmdPhaseInsert', 'renameDecimalPhases', 'renameIntegerPhases', 'collectSiblingWorktreePhaseNums'])],
   [path.join('src', 'audit.cts'), new Set(['listAuditPhaseTargets'])],
   [path.join('src', 'commands.cts'), new Set(['cmdHistoryDigest'])],
-  [path.join('src', 'state.cts'), new Set(['cmdStateValidate', 'cmdStateSync', 'cmdStateRebuild'])],
+  [path.join('src', 'state.cts'), new Set(['cmdStateValidate', 'cmdStateSync', 'cmdStateRebuild', 'countRoadmapPhaseHeadings'])],
   [path.join('src', 'roadmap-upgrade.cts'), new Set(['computeMigrationPlan'])],
   [path.join('src', 'smart-entry.cts'), new Set(['detectVerifyFailed'])],
-  [path.join('src', 'roadmap-parser.cts'), new Set(['getMilestonePhaseFilter', 'scanMilestonePhaseIds', 'collectTablePhaseRows'])],
+  [path.join('src', 'roadmap-parser.cts'), new Set(['getMilestonePhaseFilter', 'scanMilestonePhaseIdSets', 'collectTablePhaseRows'])],
   [path.join('src', 'planning-snapshot.cts'), new Set(['buildAllPhaseDirNamesField'])],
 ]);