@opengsd/gsd-core 1.13.0 → 1.14.0

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

@@ -46,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',
@@ -80,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',
@@ -123,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'],
@@ -135,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
@@ -187,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'],
 };