@opengsd/gsd-core 1.12.0 → 1.14.0

package/scripts/lib/shellcheck-fetch.cjs

@@ -0,0 +1,247 @@
+'use strict';
+
+/**
+ * shellcheck-fetch.cjs
+ *
+ * Dependency-free replacement for the `shellcheck` npm package (removed in
+ * #4120 — its extraction step pulled in `decompress@4.2.1`, which carries an
+ * unpatched CRITICAL zip-slip vulnerability, GHSA-mp2f-45pm-3cg9, CVSS 9.1,
+ * plus two moderate findings, with no patched version available upstream).
+ *
+ * This module fetches a PINNED koalaman/shellcheck release directly from
+ * GitHub releases (never "latest" — see SHELLCHECK_VERSION below), extracts
+ * the single `shellcheck` binary from the release's `.tar.gz` asset using
+ * only Node's built-in `https`/`zlib` modules plus a small hand-written tar
+ * reader (no third-party archive library), and caches the extracted binary
+ * for reuse across runs.
+ *
+ * Zip-slip defense: unlike `decompress`, which wrote extracted files using
+ * PATHS TAKEN FROM THE ARCHIVE (the exact defect class in GHSA-mp2f-45pm-
+ * 3cg9 — a malicious archive entry named e.g. `../../etc/passwd` gets
+ * written there verbatim), this reader NEVER uses an archive-supplied name
+ * as a filesystem path. `extractFileFromTar` only ever returns the matched
+ * entry's raw byte content; the caller (`resolveShellcheckBin`) writes those
+ * bytes to a path it constructs itself (`<cacheDir>/shellcheck`), and the
+ * archive's own name field is used only for a string-equality/suffix CHECK
+ * (`name === targetName || name.endsWith('/' + targetName)`), never
+ * interpolated into a path passed to `fs.writeFileSync`/`fs.mkdirSync`/etc.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const zlib = require('node:zlib');
+const https = require('node:https');
+const { ExitError } = require('./cli-exit.cjs');
+
+// Pinned explicitly — verified against `koalaman/shellcheck`'s GitHub
+// releases API as the current latest tag at the time this was written
+// (2026-08-31). Never resolved dynamically ("latest") — a moving target
+// would make this lint's exact ShellCheck version, and therefore its exact
+// finding set against scripts/lint-workflow-shellcheck-baseline.json,
+// non-reproducible across runs/machines/CI.
+const SHELLCHECK_VERSION = 'v0.11.0';
+
+const ROOT = path.join(__dirname, '..', '..');
+const CACHE_DIR = path.join(ROOT, 'node_modules', '.cache', 'shellcheck', SHELLCHECK_VERSION);
+const CACHED_BIN_PATH = path.join(CACHE_DIR, 'shellcheck');
+
+// process.arch -> the arch token ShellCheck's release asset names use.
+// Only the two architectures that actually matter for this repo (per
+// .github/workflows/test.yml: the lint-tests job that runs this script only
+// runs on ubuntu-latest, which is x86_64; and Apple Silicon dev machines are
+// aarch64) are supported — anything else fails with a clear error rather
+// than guessing.
+const ARCH_MAP = { x64: 'x86_64', arm64: 'aarch64' };
+
+const MAX_REDIRECTS = 5;
+
+// Bounds each individual HTTP hop (the initial request AND every redirect
+// hop get their own fresh 30s budget, rather than one shared budget across
+// the whole redirect chain) — a stalled connection on any single hop is
+// caught in a bounded time, mirroring lint-workflow-shellcheck.cjs's own
+// SHELLCHECK_TIMEOUT_MS bound on the ShellCheck subprocess. A bare `timeout`
+// option on the request does NOT abort it by itself — Node only emits a
+// 'timeout' event, which must be handled by destroying the request (see the
+// `req.on('timeout', ...)` below).
+const DOWNLOAD_TIMEOUT_MS = 30_000;
+
+/**
+ * Issue one real HTTPS request. Exists as its own function purely so tests
+ * can inject a fake in its place (see `httpsGetFollowingRedirects`'s
+ * `requestFn` parameter) — production callers never pass an override, so
+ * the real download path always uses this exact implementation.
+ */
+function defaultRequestFn(url, options, callback) {
+  return https.get(url, options, callback);
+}
+
+/**
+ * GET `url` following HTTP redirects manually — `https.get` does NOT follow
+ * redirects automatically, and GitHub release asset URLs redirect through
+ * `objects.githubusercontent.com`. Resolves with the full response body as a
+ * Buffer once a 200 response is received.
+ *
+ * `requestFn` defaults to a real `https.get`-based transport
+ * (`defaultRequestFn`) and is only ever overridden in tests, so calling this
+ * with zero/one arg from `resolveShellcheckBin` is unchanged behavior.
+ */
+function httpsGetFollowingRedirects(url, redirectsLeft = MAX_REDIRECTS, requestFn = defaultRequestFn) {
+  return new Promise((resolve, reject) => {
+    const req = requestFn(
+      url,
+      { headers: { 'User-Agent': 'gsd-core-shellcheck-fetch' }, timeout: DOWNLOAD_TIMEOUT_MS },
+      (res) => {
+        const status = res.statusCode || 0;
+        if (status >= 300 && status < 400 && res.headers.location) {
+          res.resume(); // drain so the socket can be reused/closed
+          if (redirectsLeft <= 0) {
+            reject(new Error(`too many redirects fetching ${url}`));
+            return;
+          }
+          const next = new URL(res.headers.location, url).toString();
+          httpsGetFollowingRedirects(next, redirectsLeft - 1, requestFn).then(resolve, reject);
+          return;
+        }
+        if (status !== 200) {
+          res.resume();
+          reject(new Error(`unexpected HTTP ${status} fetching ${url}`));
+          return;
+        }
+        const chunks = [];
+        res.on('data', (chunk) => chunks.push(chunk));
+        res.on('end', () => resolve(Buffer.concat(chunks)));
+        res.on('error', reject);
+      },
+    );
+    req.on('error', reject);
+    // `timeout` in the options above only ARMS a timer — Node emits a
+    // 'timeout' event on the request but does not abort it. Without this
+    // handler the request (and this Promise) would hang indefinitely past
+    // the configured bound on a stalled connection.
+    req.on('timeout', () => {
+      req.destroy(new Error(`timed out after ${DOWNLOAD_TIMEOUT_MS}ms fetching ${url}`));
+    });
+  });
+}
+
+/**
+ * Find the entry named (or path-ending-in) `targetName` inside a raw
+ * (already gunzipped) POSIX tar byte stream and return its content as a
+ * Buffer, or `null` if not found.
+ *
+ * Tar format: a sequence of 512-byte headers — name at offset 0/length 100,
+ * size at offset 124/length 12 (octal ASCII), typeflag at offset 156 — each
+ * followed by that many content bytes, padded up to the next 512-byte
+ * boundary, terminated by an all-zero 512-byte block. This deliberately
+ * implements only enough to locate ONE known entry name (no general
+ * multi-file extraction, no symlink handling, no GNU long-name `@LongLink`
+ * entries — ShellCheck's own release tarballs never need them) — see this
+ * module's header comment for why the entry's NAME is never used as a
+ * filesystem path.
+ */
+function extractFileFromTar(buffer, targetName) {
+  let offset = 0;
+  while (offset + 512 <= buffer.length) {
+    const header = buffer.subarray(offset, offset + 512);
+    if (header.every((b) => b === 0)) break; // end-of-archive marker
+    const name = header.subarray(0, 100).toString('utf8').replace(/\0.*$/, '');
+    const sizeRaw = header.subarray(124, 136).toString('utf8').replace(/\0.*$/, '').trim();
+    const size = sizeRaw === '' ? 0 : parseInt(sizeRaw, 8);
+    const typeflag = String.fromCharCode(header[156]);
+    const dataStart = offset + 512;
+    const isRegularFile = typeflag === '0' || typeflag === '\0';
+    if (isRegularFile && (name === targetName || name.endsWith(`/${targetName}`))) {
+      return buffer.subarray(dataStart, dataStart + size);
+    }
+    const contentBlocks = Math.ceil(size / 512);
+    offset = dataStart + contentBlocks * 512;
+  }
+  return null;
+}
+
+/**
+ * Resolve the local path to a working, executable `shellcheck` binary,
+ * downloading and caching the pinned release on first use. Subsequent calls
+ * (same version) reuse the cached binary with no network activity — mirrors
+ * the `fs.accessSync(bin, F_OK | X_OK)` cache-check pattern already used by
+ * this script's own `runShellcheck`.
+ */
+async function resolveShellcheckBin() {
+  try {
+    fs.accessSync(CACHED_BIN_PATH, fs.constants.F_OK | fs.constants.X_OK);
+    return CACHED_BIN_PATH;
+  } catch {
+    // not cached yet — fall through to download
+  }
+
+  if (process.platform === 'win32') {
+    throw new ExitError(
+      1,
+      'lint-workflow-shellcheck: automatic ShellCheck download is not supported on Windows yet ' +
+        '(this lint only ever runs in the ubuntu-latest lint-tests CI job — see .github/workflows/test.yml — ' +
+        'so this is an honest platform gap, not expected to be hit in CI).',
+    );
+  }
+  const platform = process.platform === 'darwin' || process.platform === 'linux' ? process.platform : null;
+  if (!platform) {
+    throw new ExitError(
+      1,
+      `lint-workflow-shellcheck: unsupported platform '${process.platform}' for ShellCheck auto-download ` +
+        `(supported: linux, darwin).`,
+    );
+  }
+  const arch = ARCH_MAP[process.arch];
+  if (!arch) {
+    throw new ExitError(
+      1,
+      `lint-workflow-shellcheck: unsupported architecture '${process.arch}' for ShellCheck auto-download ` +
+        `(supported: x86_64 [node arch 'x64'], aarch64 [node arch 'arm64']).`,
+    );
+  }
+
+  const assetName = `shellcheck-${SHELLCHECK_VERSION}.${platform}.${arch}.tar.gz`;
+  const url = `https://github.com/koalaman/shellcheck/releases/download/${SHELLCHECK_VERSION}/${assetName}`;
+
+  let gz;
+  try {
+    gz = await httpsGetFollowingRedirects(url);
+  } catch (e) {
+    throw new ExitError(1, `lint-workflow-shellcheck: failed to download ShellCheck (${url}): ${e.message}`);
+  }
+
+  let tarBuf;
+  try {
+    tarBuf = zlib.gunzipSync(gz);
+  } catch (e) {
+    throw new ExitError(1, `lint-workflow-shellcheck: failed to gunzip downloaded ShellCheck archive: ${e.message}`);
+  }
+
+  const entry = extractFileFromTar(tarBuf, 'shellcheck');
+  if (!entry) {
+    throw new ExitError(
+      1,
+      `lint-workflow-shellcheck: could not find a 'shellcheck' entry inside downloaded archive ${assetName}`,
+    );
+  }
+
+  fs.mkdirSync(CACHE_DIR, { recursive: true });
+  // Write to a per-process temp path and rename into place — avoids any
+  // other concurrent invocation observing (and trying to execute) a
+  // partially-written binary at the real cache path.
+  const tmpPath = path.join(CACHE_DIR, `.shellcheck.tmp-${process.pid}`);
+  fs.writeFileSync(tmpPath, entry);
+  fs.chmodSync(tmpPath, 0o755);
+  fs.renameSync(tmpPath, CACHED_BIN_PATH);
+
+  return CACHED_BIN_PATH;
+}
+
+module.exports = {
+  SHELLCHECK_VERSION,
+  CACHED_BIN_PATH,
+  MAX_REDIRECTS,
+  DOWNLOAD_TIMEOUT_MS,
+  extractFileFromTar,
+  httpsGetFollowingRedirects,
+  resolveShellcheckBin,
+};

package/scripts/lib/suite-detection.cjs

@@ -0,0 +1,32 @@
+'use strict';
+
+/**
+ * Suite classification by filename suffix (#4591 packaging fix — extracted
+ * from scripts/run-tests.cjs so a SHIPPED script, e.g.
+ * scripts/gen-platform-conformance-tier.cjs, can depend on it: run-tests.cjs
+ * itself does not ship (it is a repo-development-only tool), so a shipped
+ * file requiring it directly is MODULE_NOT_FOUND in a published install
+ * (tests/packaging-shipped-scripts-require-only-shipped.test.cjs, #2858).
+ * run-tests.cjs re-exports suiteOf from here unchanged for full backward
+ * compatibility — this is a pure relocation, not a behavior change.
+ *
+ * A file with no suite suffix (plain `foo.test.cjs`) belongs to the `unit`
+ * suite and returns `null` here; a suite-tagged file (`foo.install.test.cjs`)
+ * returns its marker string.
+ */
+
+const { basename } = require('node:path');
+
+const MARKED_SUITES = ['integration', 'install', 'security', 'slow', 'qa'];
+
+function suiteOf(filename) {
+  const name = basename(filename);
+  if (!name.endsWith('.test.cjs')) return null;
+  const base = name.slice(0, -'.test.cjs'.length);
+  const lastDot = base.lastIndexOf('.');
+  if (lastDot === -1) return null;
+  const marker = base.slice(lastDot + 1);
+  return MARKED_SUITES.includes(marker) ? marker : null;
+}
+
+module.exports = { MARKED_SUITES, suiteOf };

package/scripts/lint-allow-test-rule-refs.allowlist.json

@@ -24,7 +24,6 @@
   "tests/code-review-pipeline-regression.test.cjs :: source-text-is-the-product",
   "tests/code-review.test.cjs :: source-text-is-the-product",
   "tests/codebuddy-install.test.cjs :: source-text-is-the-product",
-  "tests/codex-config.test.cjs :: source-text-is-the-product",
   "tests/command-contract.test.cjs :: source-text-is-the-product",
   "tests/commands.test.cjs :: source-text-is-the-product",
   "tests/config-field-docs.test.cjs :: docs-parity",
@@ -52,7 +51,6 @@
   "tests/frontmatter-cli.test.cjs :: source-text-is-the-product",
   "tests/gates-taxonomy.test.cjs :: source-text-is-the-product",
   "tests/git-base-branch.test.cjs :: source-text-is-the-product",
-  "tests/gsd-check-update-worker-platform-gate.test.cjs :: structural-regression-guard",
   "tests/gsd-researcher-app-aware.test.cjs :: source-text-is-the-product",
   "tests/gsd-researcher-flow-diagram.test.cjs :: source-text-is-the-product",
   "tests/gsd-settings-advanced.test.cjs :: source-text-is-the-product",
@@ -74,13 +72,11 @@
   "tests/next-safety-gates.test.cjs :: source-text-is-the-product",
   "tests/next-up-clear-order.test.cjs :: source-text-is-the-product",
   "tests/no-hardcoded-home-gsd-tools.test.cjs :: source-text-is-the-product",
-  "tests/orphaned-hooks.test.cjs :: structural-regression-guard",
   "tests/package-legitimacy-gate.test.cjs :: source-text-is-the-product",
   "tests/parallel-dependent-plans.test.cjs :: source-text-is-the-product",
   "tests/path-replacement.test.cjs :: source-text-is-the-product",
   "tests/phase.test.cjs :: source-text-is-the-product",
   "tests/phase6-capability-docs.test.cjs :: source-text-is-the-product",
-  "tests/phase6-capstone-conformance.test.cjs :: source-text-is-the-product",
   "tests/phase6-planning-capabilities.test.cjs :: source-text-is-the-product",
   "tests/plan-bounce.test.cjs :: source-text-is-the-product",
   "tests/plan-phase-drift-guard.test.cjs :: source-text-is-the-product",
@@ -105,7 +101,6 @@
   "tests/research-agent-profiles.test.cjs :: source-text-is-the-product",
   "tests/roadmap.test.cjs :: source-text-is-the-product",
   "tests/runtime-launcher-parity.test.cjs :: structural-regression-guard",
-  "tests/runtime-name-policy.test.cjs :: source-text-is-the-product",
   "tests/scan-command.test.cjs :: source-text-is-the-product",
   "tests/secret-scan-lint.security.test.cjs :: source-text-is-the-product",
   "tests/secure-phase.test.cjs :: source-text-is-the-product",
@@ -113,7 +108,6 @@
   "tests/security-scan.security.test.cjs :: source-text-is-the-product",
   "tests/seed-scan-new-milestone.test.cjs :: source-text-is-the-product",
   "tests/settings-integrations.test.cjs :: source-text-is-the-product",
-  "tests/settings-jsonc.test.cjs :: structural-regression-guard",
   "tests/skill-frontmatter-contract.test.cjs :: source-text-is-the-product",
   "tests/spawn-liveness-banner.test.cjs :: source-text-is-the-product",
   "tests/state.test.cjs :: source-text-is-the-product",

package/scripts/lint-allow-test-rule-refs.effective-ceiling.json

@@ -1,4 +1,4 @@
 {
-  "maxSites": 10,
+  "maxSites": 84,
   "grace": 2
 }

package/scripts/lint-allow-test-rule-refs.unverified-ceiling.json

@@ -1,3 +1,3 @@
 {
-  "maxFiles": 282
+  "maxFiles": 283
 }

package/scripts/lint-allowed-tools-parity.cjs

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * lint-allowed-tools-parity.cjs — catch `allowed-tools` frontmatter that
+ * declares `Bash` but omits `Grep` (#4394, follow-up to #3085).
+ *
+ * ## Why
+ *
+ * `gen-plugin-skills.cjs --check` already guarantees `skills/*` /SKILL.md`
+ * matches byte-for-byte what `commands/gsd/*.md` generates, so the two trees
+ * cannot silently diverge FROM EACH OTHER. Nothing guarded the shape #3085
+ * actually found: a command shipping `Bash` without `Grep` purely by
+ * omission, identical in both trees and therefore invisible to a parity
+ * check that only compares them to each other.
+ *
+ * That drift ran long enough for 29 of 71 skills to lack a tool most of
+ * their siblings already declared, and it surfaced through a manual audit
+ * rather than any gate. A command that can shell out but cannot Grep does
+ * not fail loudly — it quietly reaches for `Bash` + `grep` instead, which is
+ * slower, less structured, and (per `lint-portable-grep.cjs`) a portability
+ * hazard of its own on hosts without GNU grep.
+ *
+ * ## The rule
+ *
+ * A command whose `allowed-tools` includes `Bash` must also include `Grep`,
+ * unless it is on the exemption list below.
+ *
+ * Detection only. This lint never edits a command's `allowed-tools`.
+ *
+ * ## Why an exemption list rather than a heuristic
+ *
+ * The alternative — inferring from a command's body whether it "really"
+ * needs Grep — would make the rule's verdict depend on prose that changes
+ * constantly, and produce a lint whose failures nobody can predict. A short
+ * literal list keeps every exemption a reviewable one-line diff, and the
+ * staleness check below stops it becoming a dumping ground: an entry that no
+ * longer needs to be there fails just as loudly as a missing tool.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const ROOT = path.resolve(__dirname, '..');
+const DEFAULT_ROOT = 'commands/gsd';
+
+/**
+ * Commands allowed to declare `Bash` without `Grep`.
+ *
+ * Keyed by command stem (the filename without `.md`), with the reason inline
+ * so changing the set is a one-line, reviewable diff.
+ *
+ * #4394 named eight candidates from the #3085 review: the six `gsd-ns-*`
+ * namespace dispatchers, `gsd-help`, and `gsd-surface`. Seven of those turn
+ * out not to need an entry at all — they do not declare `Bash` in the first
+ * place, so the rule never reaches them:
+ *
+ *   ns-context/ns-ideate/ns-manage/ns-project/ns-review/ns-workflow  Read + Skill
+ *   help                                                             Read
+ *
+ * Listing them anyway would be seven pre-forgiven commands: the day one of
+ * them gained `Bash`, the omission it was granted an exemption for would
+ * pass silently. The staleness check in `scan()` below is what surfaced
+ * this, and it is why the list stays minimal — an exemption is a real
+ * suppression, not documentation.
+ */
+const EXEMPT = new Map([
+  // Toggles which skills are surfaced. Mutates the install tree through the
+  // installer's own seams rather than by searching project files, so `Bash`
+  // here is not standing in for a search it cannot perform.
+  ['surface', 'mutates the install surface via installer seams, not by searching the project'],
+]);
+
+/**
+ * Parse an `allowed-tools` frontmatter value.
+ *
+ * Handles both shapes the corpus uses: a YAML block sequence
+ *
+ *     allowed-tools:
+ *       - Read
+ *       - Bash
+ *
+ * and an inline scalar or flow sequence (`allowed-tools: Read, Bash` /
+ * `allowed-tools: [Read, Bash]`). Returns `null` when the key is absent,
+ * which is NOT a violation — a command with no `allowed-tools` at all
+ * declares no `Bash` either, so this rule has nothing to say about it.
+ *
+ * Deliberately not a YAML parser: the frontmatter here is a fixed, shallow
+ * shape, and pulling in a parser to read one list would be a dependency
+ * bought for a single key.
+ *
+ * @param {string} text  full file contents
+ * @returns {string[] | null}  declared tool names, or null when the key is absent
+ */
+function parseAllowedTools(text) {
+  const lines = String(text).split(/\r?\n/);
+  const keyIndex = lines.findIndex((l) => /^allowed-tools:/.test(l));
+  if (keyIndex === -1) return null;
+
+  const inline = lines[keyIndex].replace(/^allowed-tools:/, '').trim();
+  if (inline) {
+    return inline
+      .replace(/^\[/, '')
+      .replace(/\]$/, '')
+      .split(',')
+      .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
+      .filter(Boolean);
+  }
+
+  const tools = [];
+  for (let i = keyIndex + 1; i < lines.length; i += 1) {
+    const line = lines[i];
+    const item = line.match(/^\s*-\s+(.+?)\s*$/);
+    if (item) {
+      tools.push(item[1].replace(/^['"]|['"]$/g, ''));
+      continue;
+    }
+    // The first line that is neither a list item nor blank ends the block —
+    // the next frontmatter key, or the closing `---`.
+    if (line.trim() === '') continue;
+    break;
+  }
+  return tools;
+}
+
+/**
+ * List command stems under `dir`, sorted.
+ *
+ * @param {string} dir  absolute path to the commands directory
+ * @returns {{ stem: string, file: string }[]}
+ */
+function listCommands(dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isFile() && e.name.endsWith('.md'))
+    .map((e) => ({ stem: e.name.replace(/\.md$/, ''), file: path.join(dir, e.name) }))
+    .sort((a, b) => a.stem.localeCompare(b.stem));
+}
+
+/**
+ * Evaluate the corpus.
+ *
+ * Reports two independent failure classes, because an exemption list that
+ * can only ever grow rots into a list of things nobody re-examined:
+ *
+ *   - `violations`: declares Bash, omits Grep, not exempt.
+ *   - `staleExemptions`: on the list but no longer needs to be — either the
+ *     command is gone, or it no longer declares Bash without Grep. Removing
+ *     the entry is then a one-line diff, and the next omission in that
+ *     command is caught rather than silently pre-forgiven.
+ *
+ * @param {string} [root]  repo-relative commands directory
+ * @returns {{ scanned: number, violations: {stem: string, tools: string[]}[], staleExemptions: {stem: string, reason: string}[] }}
+ */
+function scan(root = DEFAULT_ROOT) {
+  const abs = path.isAbsolute(root) ? root : path.join(ROOT, root);
+  const commands = listCommands(abs);
+  const violations = [];
+  const seen = new Set();
+
+  for (const { stem, file } of commands) {
+    const tools = parseAllowedTools(fs.readFileSync(file, 'utf8'));
+    if (!tools) continue;
+    if (!tools.includes('Bash') || tools.includes('Grep')) continue;
+    seen.add(stem);
+    if (EXEMPT.has(stem)) continue;
+    violations.push({ stem, tools });
+  }
+
+  const present = new Set(commands.map((c) => c.stem));
+  const staleExemptions = [];
+  for (const [stem, reason] of EXEMPT) {
+    if (!present.has(stem)) {
+      staleExemptions.push({ stem, reason: `no such command (${reason})` });
+    } else if (!seen.has(stem)) {
+      staleExemptions.push({ stem, reason: `no longer declares Bash without Grep (${reason})` });
+    }
+  }
+
+  return { scanned: commands.length, violations, staleExemptions };
+}
+
+function main() {
+  const root = process.env.GSD_LINT_ALLOWED_TOOLS_ROOT || DEFAULT_ROOT;
+  const { scanned, violations, staleExemptions } = scan(root);
+
+  if (violations.length > 0 || staleExemptions.length > 0) {
+    const parts = [];
+    if (violations.length > 0) {
+      parts.push(
+        'lint-allowed-tools-parity: these commands declare `Bash` but not `Grep` (#4394).\n' +
+          'A command that can shell out but cannot Grep reaches for `Bash` + `grep` instead —\n' +
+          'slower, unstructured, and a portability hazard on hosts without GNU grep. Add `Grep`\n' +
+          'to the frontmatter, or add the command to EXEMPT in this script with a reason:\n' +
+          violations.map((v) => `  ${root}/${v.stem}.md  [${v.tools.join(', ')}]`).join('\n'),
+      );
+    }
+    if (staleExemptions.length > 0) {
+      parts.push(
+        'lint-allowed-tools-parity: these EXEMPT entries are stale — delete them so the next\n' +
+          'omission in those commands is caught rather than silently pre-forgiven:\n' +
+          staleExemptions.map((s) => `  ${s.stem}: ${s.reason}`).join('\n'),
+      );
+    }
+    throw new ExitError(1, parts.join('\n\n'));
+  }
+
+  console.log(
+    `ok lint-allowed-tools-parity: ${scanned} command(s) checked, ${EXEMPT.size} exemption(s) all still needed`,
+  );
+}
+
+module.exports = { parseAllowedTools, scan, EXEMPT, DEFAULT_ROOT };
+
+if (require.main === module) runMain(main);

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

@@ -31,6 +31,7 @@
  * `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',
@@ -45,6 +46,7 @@ const DOCS_GUARD_EXEMPT_BASELINE = [
   'codebuddy-upgrades.test.cjs',
   'commands.test.cjs',
   'commit-docs-bypass.test.cjs',
+  'compact-content-partition-guard.test.cjs',
   'complexity-trigger.test.cjs',
   'concurrency-safety.test.cjs',
   'cursor-imperative-reference.test.cjs',
@@ -79,6 +81,7 @@ const DOCS_GUARD_EXEMPT_BASELINE = [
   'repo-invariants.test.cjs',
   'require-issue-link-policy.test.cjs',
   'reviewer-manifest-body.test.cjs',
+  'reviewer-step-dispatch.test.cjs',
   'run-tests-harness.test.cjs',
   'runtime-name-policy.test.cjs',
   'security-prompt-injection.security.test.cjs',
@@ -103,6 +106,10 @@ const DOCS_GUARD_EXEMPT_BASELINE = [
  * 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'],
@@ -118,8 +125,12 @@ const DOCS_GUARD_EXEMPT_DOCS_PATHS = {
     'docs/how-to/some-unrelated-guide.md', 'docs/how-to/x.md', 'docs/some-unrelated-file.md',
     'docs/totally-unrelated.md',
   ],
+  // #4641: cites docs/adr/4641-windows-selector-consolidation.md in an
+  // explanatory comment describing why the retired `windows` scope must not
+  // be restored; the file never reads that (or any) docs/ file.
   '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/a.md', 'docs/adr', 'docs/adr/22-plan-drift-guard.md',
+    'docs/adr/4641-windows-selector-consolidation.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'],
@@ -130,6 +141,10 @@ const DOCS_GUARD_EXEMPT_DOCS_PATHS = {
   'commit-docs-bypass.test.cjs': [
     'docs/40-design.md', 'docs/CONFIGURATION.md', 'docs/readme.md', 'docs/tracked-var-mentioning',
   ],
+  // #4403: cites docs/PARTITION-RULES.md as a "see" pointer in the module docstring
+  // describing the operational spec this guard implements; the file never reads that
+  // (or any) docs/ file.
+  'compact-content-partition-guard.test.cjs': ['docs/PARTITION-RULES.md'],
   '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
@@ -182,11 +197,18 @@ const DOCS_GUARD_EXEMPT_DOCS_PATHS = {
   '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'],
+  // #4209: 'docs/spec.md' is a synthetic, never-read fake path proving dispatchReviewerLanes
+  // has no code-review-specific special-casing; 'docs/adr/456-test-rigor-architecture.md' is a
+  // prose citation in a code comment justifying the fast-check property tests below (#4209
+  // review). Neither is a real filesystem read — the file never reads any docs/ file.
+  'reviewer-step-dispatch.test.cjs': ['docs/adr/456-test-rigor-architecture.md', 'docs/spec.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'],
+  // #4186: the record-session usage-contract test cites the documented
+  // signature in docs/CLI-TOOLS.md in its explanatory comment.
+  'state.test.cjs': ['docs/CLI-TOOLS.md', 'docs/CONFIGURATION.md', 'docs/reference/state-md.md'],
   'worktree-safety.test.cjs': ['docs/SUMMARY.md'],
 };