@opengsd/gsd-core 1.10.0 → 1.12.0

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

@@ -0,0 +1,193 @@
+'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-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 = {
+  '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

@@ -0,0 +1,38 @@
+[
+  {
+    "path": "gsd-core/bin/lib/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/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."
+  },
+  {
+    "path": "tests/fixtures/brand-typing/bad-double-calibration.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."
+  },
+  {
+    "path": "tests/fixtures/brand-typing/bad-raw-against-budget.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."
+  },
+  {
+    "path": "tests/fixtures/brand-typing/bad-rebrand-calibrated-as-raw.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."
+  },
+  {
+    "path": "tests/fixtures/brand-typing/bad-unbranded-number-as-raw.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."
+  },
+  {
+    "path": "tests/fixtures/brand-typing/ok-correct-composition.cts",
+    "reason": "Positive-control counterpart to the bad-* must-not-compile fixtures (#3059); kept in the same exemption so the pair stays together."
+  }
+]

package/scripts/lint-eslint-glob-coverage.cjs

@@ -0,0 +1,340 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * lint-eslint-glob-coverage.cjs — ESLint `files:` glob coverage drift guard (#3059).
+ *
+ * ## What this enforces
+ *
+ * `eslint.config.mjs` is a flat config: a tracked source file is only linted
+ * if it matches at least one config object's `files:` glob (or a global,
+ * files-less block). A file matching NO glob resolves to zero reachable
+ * rules and `eslint .` silently exits 0 on it — the #3059 defect class (62
+ * tracked source files found with this shape). This guard walks every
+ * tracked `.cjs/.cts/.js/.mjs` source file, resolves its real ESLint config,
+ * and fails when a file resolves to zero rules and isn't a deliberately
+ * exempted, reasoned allowlist entry.
+ *
+ * This checks rule REACHABILITY (does at least one rule apply to this file
+ * at all, any severity), not rule SEVERITY (whether an applicable rule is
+ * `error` vs `warn` vs `off`) — severity coverage is a separate gate, #1885
+ * F17. A file with one `off` rule reachable still counts as "covered" here:
+ * it proves the file was deliberately targeted by a `files:` glob, which is
+ * the thing #3059 is about.
+ *
+ * ## Goodhart rationale
+ *
+ * A coverage metric is trivially gameable by padding the allowlist instead
+ * of fixing the glob, so every knob here is built to resist that:
+ *   - Every allowlist entry MUST carry a non-empty `reason` — an unreasoned
+ *     entry is indistinguishable from "quietly made the metric look better".
+ *   - The allowlist only ratchets DOWN: an entry whose path now resolves to
+ *     >=1 rule (`allowlist_stale`) is a failure, forcing prompt removal
+ *     rather than letting stale exemptions accumulate as free cover for
+ *     future accidental escapes at the same path.
+ *   - A tracked-file-count floor (`tracked_count_below_floor`) exists so a
+ *     broken or empty `git ls-files` (e.g. wrong cwd, detached worktree)
+ *     can't report a vacuous "0 escapes out of 0 checked" clean run.
+ *
+ * ## Ignored vs. unmatched (the discrimination this script makes)
+ *
+ * ESLint's `ignores:` blocks are the one legitimate "this file is not meant
+ * to be linted" decision (e.g. the ADR-457 tsc-emitted `.cjs` artifacts
+ * under `gsd-core/bin/lib/`) and must NOT be reported as uncovered. But
+ * `ESLint#isPathIgnored` cannot be trusted uniformly across extensions:
+ * for ESLint's default-lintable extensions (`.js`/`.mjs`/`.cjs`), it
+ * reports `true` only when the path matches an explicit `ignores:` glob —
+ * verified empirically: an unmatched top-level `.cjs` probe file reports
+ * `isPathIgnored() === false` with an empty resolved rule set, not `true`.
+ * For `.cts` (and any other non-default extension), flat config requires an
+ * EXPLICIT `files:` glob match to be linted at all; a `.cts` file matching
+ * no `files:` glob ALSO reports `isPathIgnored() === true` — indistinguishable,
+ * via this API, from a genuine `ignores:` entry (verified with a scratch
+ * `.cts` fixture under `tests/fixtures/`). This repo's `ignores:` list never
+ * contains a `.cts` path (ADR-457 retires only the emitted `.cjs`; the
+ * `.cts` source is always meant to stay linted), so for `.cts` specifically
+ * an `isPathIgnored() === true` verdict can only mean "matches no `files:`
+ * glob" and is therefore treated as UNCOVERED, not ignored. See
+ * `resolveFileCoverage` below.
+ *
+ * ## Why `bin/install.js` is NOT in the allowlist
+ *
+ * The allowlist below is exclusively for files that resolve to ZERO rules —
+ * it is a registry of accepted escapes, not a general-purpose "reasons for
+ * how a file is configured" log. The `bin/install.js` / `bin/gsd-mcp-server.js`
+ * / `scripts/build-hooks.js` family is deliberately covered by a minimal,
+ * 2-rule block in `eslint.config.mjs` per ADR-1703 (targeting only the
+ * portability defect surface, not a full style sweep of ~12k lines of
+ * generated code) — see the comment at that block in `eslint.config.mjs`.
+ * Because 2 rules is non-empty, that family already passes this guard
+ * without needing an allowlist entry, and adding one anyway would itself be
+ * flagged `allowlist_stale` (see the ratchet above). The allowlist exemption
+ * surface deliberately cannot be used to re-state a decision that is already
+ * recorded in the config; #3059 is the guard, ADR-1703 is the decision.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const ALLOWLIST_PATH = path.join(__dirname, 'lint-eslint-glob-coverage.allowlist.json');
+
+const SOURCE_EXT_RE = /\.(cjs|cts|js|mjs)$/;
+
+// ESLint's flat-config default-lintable extensions: a file with one of these
+// extensions that matches no `files:` glob still reports `isPathIgnored()
+// === false` (with an empty resolved rule set) — so for these extensions,
+// `isPathIgnored() === true` reliably means an explicit `ignores:` match.
+const DEFAULT_LINTABLE_EXT_RE = /\.(js|mjs|cjs)$/;
+
+const MIN_TRACKED_SOURCE_FILES = 500;
+
+/**
+ * Runs `git ls-files` and returns the tracked source files (repo-relative,
+ * POSIX-normalized, filtered to SOURCE_EXT_RE). Never throws: a git failure
+ * (non-zero exit or timeout) produces a degraded `{ ok: false }` result so
+ * callers can turn it into a `git_failed` violation instead of crashing.
+ *
+ * @param {object} [opts]
+ * @param {Function} [opts.execFile] - injectable sync exec function with the
+ *   `execFileSync(cmd, args, options)` signature; defaults to
+ *   `child_process.execFileSync`.
+ */
+function listTrackedSourceFiles({ execFile } = {}) {
+  const run = execFile || require('child_process').execFileSync;
+  let stdout;
+  try {
+    // The test runner and CI execute inside a container where this repo is
+    // owned by a different UID than the running user; bare `git ls-files`
+    // then refuses with "detected dubious ownership" unless the path is in
+    // `safe.directory`, and this guard degrades to a `git_failed` violation
+    // — exactly where it must run to be a useful gate (#3059). `-c
+    // safe.directory=*` scopes the override to THIS invocation only (it
+    // never writes to any config file, global or local), and the wildcard
+    // is fine here because this command only ever enumerates tracked paths
+    // in the repo the guard is already executing inside.
+    stdout = run('git', ['-c', 'safe.directory=*', 'ls-files'], {
+      cwd: ROOT,
+      encoding: 'utf8',
+      // 30s — `git ls-files` on this tree returns ~1175 paths in <1s; 30s is
+      // the CLAUDE.md git ceiling, generous for a cold index.
+      timeout: 30000,
+    });
+  } catch (err) {
+    return { ok: false, files: [], error: (err && err.message) || String(err) };
+  }
+
+  const files = String(stdout)
+    // CRLF-safe: `git ls-files` output may carry \r\n on a Windows checkout
+    // or a git config with core.autocrlf set (DEFECT.CRLF class).
+    .split(/\r?\n/)
+    .filter((line) => line.length > 0)
+    // Unconditional backslash normalization (never path.sep-gated): the
+    // guard's own process may run on any platform regardless of what
+    // produced the tracked-file listing.
+    .map((line) => line.replace(/\\/g, '/'))
+    .filter((line) => SOURCE_EXT_RE.test(line));
+
+  return { ok: true, files };
+}
+
+/** Loads and parses the allowlist JSON file. */
+function loadAllowlist() {
+  const raw = fs.readFileSync(ALLOWLIST_PATH, 'utf8');
+  return JSON.parse(raw);
+}
+
+/**
+ * Resolves the ESLint coverage verdict for a single tracked file. See the
+ * "Ignored vs. unmatched" header section for the extension-dependent
+ * discrimination rationale.
+ *
+ * @param {import('eslint').ESLint} eslint
+ * @param {string} relPath - repo-relative POSIX path
+ * @returns {Promise<{ ignored: boolean, ruleCount: number }>}
+ */
+async function resolveFileCoverage(eslint, relPath) {
+  const absPath = path.join(ROOT, relPath);
+  const ignored = await eslint.isPathIgnored(absPath);
+
+  if (ignored) {
+    if (DEFAULT_LINTABLE_EXT_RE.test(relPath)) {
+      // .js/.mjs/.cjs: isPathIgnored() only reports true for an explicit
+      // `ignores:` glob match — a recorded decision.
+      return { ignored: true, ruleCount: 0 };
+    }
+    // .cts (or any non-default extension): isPathIgnored() can't
+    // distinguish "explicit ignores: match" from "no files: glob matched
+    // it at all" — and this repo's ignores: list never targets .cts, so
+    // treat it as the latter (uncovered), never as ignored.
+    return { ignored: false, ruleCount: 0 };
+  }
+
+  const config = await eslint.calculateConfigForFile(absPath);
+  const ruleCount = config && config.rules ? Object.keys(config.rules).length : 0;
+  return { ignored: false, ruleCount };
+}
+
+/** Builds the default real-ESLint-backed resolveConfig function. */
+function createDefaultResolveConfig() {
+  const { ESLint } = require('eslint');
+  const eslint = new ESLint({ cwd: ROOT });
+  return (relPath) => resolveFileCoverage(eslint, relPath);
+}
+
+/**
+ * The pure coverage predicate. All I/O is injectable via `deps` so tests
+ * never need a temp repo, a real subprocess, or a real ESLint instance:
+ *
+ * @param {object} [deps]
+ * @param {string[] | { ok: boolean, files?: string[], error?: string }} [deps.trackedFiles]
+ *   Either a plain array of tracked source paths (success shorthand), or a
+ *   `listTrackedSourceFiles()`-shaped result object (so a git failure can be
+ *   injected directly). Defaults to a real `listTrackedSourceFiles()` call.
+ * @param {(relPath: string) => Promise<{ignored:boolean,ruleCount:number}> | {ignored:boolean,ruleCount:number}} [deps.resolveConfig]
+ *   Per-file coverage resolver. Defaults to a real ESLint instance.
+ * @param {Array<{path:string,reason?:string}>} [deps.allowlist] - defaults to
+ *   the real `loadAllowlist()`.
+ * @param {number} [deps.minTrackedFiles] - defaults to MIN_TRACKED_SOURCE_FILES.
+ * @returns {Promise<{ ok: boolean, escapes: Array<{path:string}>, violations: Array<{kind:string,path:string|null,detail:string}>, checked: number }>}
+ */
+async function checkGlobCoverage(deps = {}) {
+  const minTrackedFiles =
+    typeof deps.minTrackedFiles === 'number' ? deps.minTrackedFiles : MIN_TRACKED_SOURCE_FILES;
+
+  const violations = [];
+
+  let trackedResult;
+  if (deps.trackedFiles === undefined) {
+    trackedResult = listTrackedSourceFiles();
+  } else if (Array.isArray(deps.trackedFiles)) {
+    trackedResult = { ok: true, files: deps.trackedFiles };
+  } else {
+    trackedResult = deps.trackedFiles;
+  }
+
+  if (!trackedResult.ok) {
+    violations.push({
+      kind: 'git_failed',
+      path: null,
+      detail: trackedResult.error || 'listTrackedSourceFiles() failed',
+    });
+    return { ok: false, escapes: [], violations, checked: 0 };
+  }
+
+  const trackedFiles = trackedResult.files;
+
+  if (trackedFiles.length < minTrackedFiles) {
+    violations.push({
+      kind: 'tracked_count_below_floor',
+      path: null,
+      detail: `tracked source file count ${trackedFiles.length} is below the floor of ${minTrackedFiles} — a broken or empty git ls-files must never report a vacuous clean run`,
+    });
+  }
+
+  const trackedSet = new Set(trackedFiles);
+  const allowlist = deps.allowlist === undefined ? loadAllowlist() : deps.allowlist;
+
+  const seenAllowlistPaths = new Set();
+  const allowlistPathSet = new Set();
+  for (const entry of allowlist) {
+    const entryPath = entry && entry.path;
+
+    if (seenAllowlistPaths.has(entryPath)) {
+      violations.push({
+        kind: 'allowlist_duplicate',
+        path: entryPath,
+        detail: 'path appears more than once in the allowlist',
+      });
+    } else {
+      seenAllowlistPaths.add(entryPath);
+    }
+    allowlistPathSet.add(entryPath);
+
+    if (!Object.prototype.hasOwnProperty.call(entry, 'reason')) {
+      violations.push({
+        kind: 'allowlist_missing_reason',
+        path: entryPath,
+        detail: 'allowlist entry is missing a "reason" key',
+      });
+    } else if (typeof entry.reason !== 'string' || entry.reason.trim() === '') {
+      violations.push({
+        kind: 'allowlist_empty_reason',
+        path: entryPath,
+        detail: 'allowlist entry "reason" is empty or whitespace-only',
+      });
+    }
+
+    if (!trackedSet.has(entryPath)) {
+      violations.push({
+        kind: 'allowlist_missing_path',
+        path: entryPath,
+        detail: 'allowlisted path is not a tracked source file',
+      });
+    }
+  }
+
+  const resolveConfig = deps.resolveConfig || createDefaultResolveConfig();
+
+  const escapes = [];
+  let checked = 0;
+
+  for (const file of trackedFiles) {
+    checked += 1;
+    const result = await resolveConfig(file);
+    const isAllowlisted = allowlistPathSet.has(file);
+
+    if (result.ignored) {
+      // A recorded ESLint `ignores:` decision — never an escape, regardless
+      // of allowlist membership.
+      continue;
+    }
+
+    if (result.ruleCount === 0) {
+      if (isAllowlisted) continue;
+      escapes.push({ path: file });
+      violations.push({
+        kind: 'uncovered',
+        path: file,
+        detail: 'resolves to 0 reachable ESLint rules and is not allowlisted',
+      });
+    } else if (isAllowlisted) {
+      violations.push({
+        kind: 'allowlist_stale',
+        path: file,
+        detail: 'allowlisted path now resolves to >=1 ESLint rule — prune the entry, the allowlist only ratchets down',
+      });
+    }
+  }
+
+  return { ok: violations.length === 0, escapes, violations, checked };
+}
+
+if (require.main === module) {
+  checkGlobCoverage()
+    .then((result) => {
+      if (result.violations.length > 0) {
+        console.error(
+          `lint-eslint-glob-coverage: ${result.violations.length} violation(s) across ${result.checked} tracked source file(s) (${result.escapes.length} uncovered escape(s))`
+        );
+        for (const v of result.violations) {
+          console.error(`  [${v.kind}] ${v.path === null ? '(n/a)' : v.path}${v.detail ? ' — ' + v.detail : ''}`);
+        }
+        process.exitCode = 1;
+      } else {
+        console.log(`ok lint-eslint-glob-coverage: ${result.checked} tracked source file(s), 0 escapes`);
+      }
+    })
+    .catch((err) => {
+      console.error(err && err.stack ? err.stack : String(err));
+      process.exitCode = 1;
+    });
+}
+
+module.exports = {
+  checkGlobCoverage,
+  listTrackedSourceFiles,
+  loadAllowlist,
+  SOURCE_EXT_RE,
+  MIN_TRACKED_SOURCE_FILES,
+};

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(', ')}`
   );
 }