@opengsd/gsd-core 1.9.1 → 1.11.0

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

@@ -0,0 +1,404 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * lint-health-diagnostic-rule-table.cjs — gate: enforces ADR-3180 §8.2's 1:1
+ * rule-code invariant and §8.5's fixture-proof invariant for
+ * `src/health-diagnostic.cts`'s RULES table (Phase 11, #3309).
+ *
+ * ## What this enforces
+ *
+ * 1. (§8.2 rule 1 — 1:1 code invariant) Every `rule.code` in RULES (exported
+ *    from the compiled `gsd-core/bin/lib/health-diagnostic.cjs`) is unique,
+ *    and every rule's `severity` is one of `SEVERITY`'s values. The severity
+ *    check exists only to confirm the compiled artifact was not hand-edited
+ *    to bypass the `Rule.severity` required field TypeScript already
+ *    enforces at compile time — "severity is a property of the RULE, never
+ *    the emit call."
+ * 2. (§8.5 — fixture-proof invariant) Every code in RULES has a paired test:
+ *    the code string (e.g. `'W001'`) appears as a literal AND within a
+ *    `describe(`/`test(` block whose title also names that exact code, in
+ *    one of the health-diagnostic test files
+ *    (`tests/health-diagnostic-rules/*.test.cjs`,
+ *    `tests/health-diagnostic.test.cjs`). A mere comment/string mention
+ *    outside a titled block does not count as coverage.
+ *
+ *    EXCEPTION — `PERMANENTLY_INERT_CODES` (below): a rule whose `check`
+ *    always returns `[]` BY DESIGN (the real check lives outside the rule
+ *    table entirely, because it needs ambient I/O `Rule.check` cannot
+ *    perform — §8.1 rule 1) can never satisfy a real fixture-proof, no
+ *    matter how many tests reference its code. Before this exception
+ *    existed, W024 "passed" this guard only because an unrelated test title
+ *    (the RULES-array shape assertion, "exports exactly 5 rules: W024, ...")
+ *    happened to contain the string "W024" — accidental coverage, not proof
+ *    the rule can fire. `PERMANENTLY_INERT_CODES` makes that exemption
+ *    explicit and auditable instead of relying on a coincidental title
+ *    match, and the PASS output now reports exempted codes SEPARATELY from
+ *    genuinely fixture-covered ones rather than folding them together.
+ * 3. (Phase 12, #3310 — S0NN pass) `cmdStateValidate` (src/state.cts) emits
+ *    7 coded diagnostics (S001-S007) built inline via a local
+ *    `stateDiagnostic()` helper — NOT `Rule`-table entries, so they are not
+ *    read from the compiled module the way RULES/CONSISTENCY_RULES are.
+ *    This third pass hardcodes that code list (`STATE_VALIDATE_CODES`,
+ *    below) and applies the SAME §8.5 fixture-proof check against
+ *    `tests/state.test.cjs`, reported in its own PASS/FAIL section —
+ *    mirroring the C0NN pass's structure, just with a hardcoded list
+ *    instead of a `Rule[]` array as the code source.
+ *
+ * Design: .gsd/phase/refactor-3309-health-diagnostic-rule-table/40-design.md
+ * ("The lint guard (§8.2 1:1 invariant + §8.5 fixture proof)").
+ *
+ * ## Deviation from the design doc's original plan
+ *
+ * The design doc assumed fixtures would live as separate files at
+ * `tests/fixtures/health-diagnostic/<code>.*`. That did not happen during
+ * implementation — all 8 rule-group test files
+ * (`tests/health-diagnostic-rules/*.test.cjs`) build fixtures INLINE via
+ * real temp directories (`createTempDir()` from `tests/helpers.cjs`) and a
+ * 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
+ * house style — rather than dynamically re-running fixture-building code
+ * this guard does not own.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const REPO_ROOT = path.join(__dirname, '..');
+const COMPILED_MODULE_REL = 'gsd-core/bin/lib/health-diagnostic.cjs';
+const COMPILED_MODULE_PATH = path.join(REPO_ROOT, COMPILED_MODULE_REL);
+const TEST_GROUP_DIR = path.join(REPO_ROOT, 'tests', 'health-diagnostic-rules');
+const SKELETON_TEST_FILE = path.join(REPO_ROOT, 'tests', 'health-diagnostic.test.cjs');
+
+// Phase 12 (#3310, ADR-3180 §8.4) — the C0NN namespace's own fixture-proof
+// test file. §8.5 extends to `CONSISTENCY_RULES`'s NEW codes only (C001-C004
+// — W006/W007 are already fixture-proofed above, against the SAME `Rule`
+// objects; re-checking them here would be redundant, not additional
+// coverage).
+const CONSISTENCY_TEST_FILE = path.join(REPO_ROOT, 'tests', 'health-diagnostic-rules', 'consistency.test.cjs');
+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.
+const STATE_VALIDATE_TEST_FILE = path.join(REPO_ROOT, 'tests', 'state.test.cjs');
+const STATE_VALIDATE_CODES = ['S001', 'S002', 'S003', 'S004', 'S005', 'S006', 'S007'];
+
+// Matches `describe(`/`test(`/`it(` calls whose first argument is a string
+// literal, capturing that literal as the block's title. Line/regex-based
+// (not full AST) per this repo's existing lint-guard house style
+// (scripts/lint-planning-snapshot-bypass-drift.cjs's scanCode precedent).
+const TITLED_BLOCK_RE = /\b(describe|test|it)\(\s*(['"`])((?:\\.|(?!\2)[^\\])*)\2/g;
+
+// Rule codes whose `check` is a documented PERMANENT no-op (always returns
+// `[]`) because the real check requires ambient I/O forbidden inside a
+// `Rule.check(snapshot)` (§8.1 rule 1) — the real check runs elsewhere,
+// outside the rule table. These can never be proven via a real
+// diagnostic-firing fixture, so they are exempted from the §8.5 fixture-proof
+// invariant explicitly here rather than via an accidental test-title match.
+// Adding an entry is a deliberate, reviewed decision — see each reason.
+const PERMANENTLY_INERT_CODES = new Map([
+  [
+    'W024',
+    'readStateHeadFreshness requires a git-log shell-out, forbidden ambient I/O for Rule.check ' +
+      '(§8.1 rule 1) — the real check runs in cmdValidateHealth itself, outside the rule table ' +
+      '(src/verify.cts). This rule-table entry is a permanent no-op by design, not a fixture gap.',
+  ],
+]);
+
+/**
+ * Load the compiled health-diagnostic module. Throws a clear ExitError
+ * (not a raw MODULE_NOT_FOUND) if `npm run build:lib` has not run.
+ */
+function loadCompiledModule(compiledPath = COMPILED_MODULE_PATH) {
+  if (!fs.existsSync(compiledPath)) {
+    throw new ExitError(
+      2,
+      `lint-health-diagnostic-rule-table: compiled artifact not found at ${COMPILED_MODULE_REL}.\n` +
+        'Run `npm run build:lib` first.',
+    );
+  }
+  return require(compiledPath);
+}
+
+/**
+ * §8.2 rule 1 — 1:1 code invariant: every rule.code is unique, and every
+ * rule's severity is a member of SEVERITY's values.
+ *
+ * @param {Array<{code: string, severity: string}>} rules
+ * @param {Record<string, string>} severity  SEVERITY export (code -> value)
+ * @returns {{duplicates: Array<{code: string, count: number}>, badSeverities: Array<{code: string, severity: unknown}>}}
+ */
+function checkOneToOneInvariant(rules, severity) {
+  const severityValues = new Set(Object.values(severity));
+  const counts = new Map();
+  const badSeverities = [];
+
+  for (const rule of rules) {
+    counts.set(rule.code, (counts.get(rule.code) || 0) + 1);
+    if (!severityValues.has(rule.severity)) {
+      badSeverities.push({ code: rule.code, severity: rule.severity });
+    }
+  }
+
+  const duplicates = [...counts.entries()]
+    .filter(([, count]) => count > 1)
+    .map(([code, count]) => ({ code, count }));
+
+  return { duplicates, badSeverities };
+}
+
+/**
+ * Extracts every `describe(`/`test(`/`it(` block title found in `text`.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+function extractTitledBlocks(text) {
+  const titles = [];
+  TITLED_BLOCK_RE.lastIndex = 0;
+  let match;
+  while ((match = TITLED_BLOCK_RE.exec(text)) !== null) {
+    titles.push(match[3]);
+  }
+  return titles;
+}
+
+/**
+ * True iff `code` appears verbatim, as a whole token, inside at least one of
+ * `titles`. Whole-token match guards against a shorter code accidentally
+ * substring-matching inside an unrelated longer token.
+ *
+ * @param {string} code
+ * @param {string[]} titles
+ */
+function codeAppearsInTitle(code, titles) {
+  const codeRe = new RegExp(`(?:^|[^A-Za-z0-9])${code}(?:$|[^A-Za-z0-9])`);
+  return titles.some((title) => codeRe.test(`|${title}|`));
+}
+
+/**
+ * Locates every health-diagnostic test file this guard scans for §8.5
+ * fixture-proof coverage.
+ *
+ * @param {string} repoRoot
+ * @returns {string[]} absolute paths, sorted
+ */
+function findHealthDiagnosticTestFiles(repoRoot = REPO_ROOT) {
+  const groupDir = path.join(repoRoot, 'tests', 'health-diagnostic-rules');
+  const files = [];
+  if (fs.existsSync(groupDir)) {
+    for (const entry of fs.readdirSync(groupDir)) {
+      if (entry.endsWith('.test.cjs')) {
+        files.push(path.join(groupDir, entry));
+      }
+    }
+  }
+  const skeletonTestFile = path.join(repoRoot, 'tests', 'health-diagnostic.test.cjs');
+  if (fs.existsSync(skeletonTestFile)) {
+    files.push(skeletonTestFile);
+  }
+  return files.sort();
+}
+
+/**
+ * §8.5 — fixture-proof invariant: for every code in `rules`, confirm at
+ * least one test file in `testFiles` has a `describe(`/`test(`/`it(` block
+ * whose title names that exact code — UNLESS the code is listed in
+ * `PERMANENTLY_INERT_CODES`, in which case it is reported separately as
+ * `exempted` (visibly, not folded into "covered") and never fails the guard
+ * regardless of test coverage.
+ *
+ * @param {Array<{code: string}>} rules
+ * @param {string[]} testFiles  absolute paths to *.test.cjs files to scan
+ * @param {Map<string, string>} inertCodes  PERMANENTLY_INERT_CODES (injectable for tests)
+ * @returns {{uncovered: string[], exempted: string[], testFilesScanned: string[]}}
+ */
+function checkFixtureProofInvariant(rules, testFiles, inertCodes = PERMANENTLY_INERT_CODES) {
+  const allTitles = [];
+  for (const file of testFiles) {
+    const text = fs.readFileSync(file, 'utf8');
+    allTitles.push(...extractTitledBlocks(text));
+  }
+
+  const uncovered = [];
+  const exempted = [];
+  for (const rule of rules) {
+    if (inertCodes.has(rule.code)) {
+      exempted.push(rule.code);
+      continue;
+    }
+    if (!codeAppearsInTitle(rule.code, allTitles)) {
+      uncovered.push(rule.code);
+    }
+  }
+
+  return { uncovered, exempted, testFilesScanned: testFiles };
+}
+
+function formatRepoRelative(absPath) {
+  return path.relative(REPO_ROOT, absPath).split(path.sep).join('/');
+}
+
+function main() {
+  const { RULES, CONSISTENCY_RULES, SEVERITY } = loadCompiledModule();
+
+  const { duplicates, badSeverities } = checkOneToOneInvariant(RULES, SEVERITY);
+
+  const testFiles = findHealthDiagnosticTestFiles(REPO_ROOT);
+  const { uncovered, exempted } = checkFixtureProofInvariant(RULES, testFiles);
+
+  // ─── C0NN check pass (Phase 12, #3310) — separate from the W/E/I pass
+  // above, own reporting section, does NOT re-check W006/W007's fixture
+  // proof (already covered above against the same `Rule` objects).
+  const consistencyNewRules = CONSISTENCY_RULES.filter((r) => CONSISTENCY_CODE_PREFIX_RE.test(r.code));
+  const { duplicates: consistencyDuplicates, badSeverities: consistencyBadSeverities } = checkOneToOneInvariant(
+    consistencyNewRules,
+    SEVERITY,
+  );
+  const consistencyTestFiles = fs.existsSync(CONSISTENCY_TEST_FILE) ? [CONSISTENCY_TEST_FILE] : [];
+  const { uncovered: consistencyUncovered } = checkFixtureProofInvariant(
+    consistencyNewRules,
+    consistencyTestFiles,
+    new Map(),
+  );
+
+  // ─── S0NN check pass (Phase 12, #3310) — separate from the W/E/I and C0NN
+  // passes above, own reporting section. Hardcoded code list (see the
+  // STATE_VALIDATE_CODES comment above) rather than read from a Rule[] array.
+  const stateValidateTestFiles = fs.existsSync(STATE_VALIDATE_TEST_FILE) ? [STATE_VALIDATE_TEST_FILE] : [];
+  const { uncovered: stateValidateUncovered } = checkFixtureProofInvariant(
+    STATE_VALIDATE_CODES.map((code) => ({ code })),
+    stateValidateTestFiles,
+    new Map(),
+  );
+
+  const problems = [];
+
+  if (duplicates.length > 0) {
+    const list = duplicates.map((d) => `  ${d.code} (${d.count} occurrences)`).join('\n');
+    problems.push(
+      `§8.2 rule 1 violated: ${duplicates.length} duplicated rule code(s) in RULES ` +
+        `(${COMPILED_MODULE_REL}):\n${list}\n` +
+        '  remedy: codes are append-only and 1:1 with a single Rule — rename or remove the duplicate.',
+    );
+  }
+
+  if (badSeverities.length > 0) {
+    const list = badSeverities
+      .map((b) => `  ${b.code}: severity=${JSON.stringify(b.severity)}`)
+      .join('\n');
+    problems.push(
+      `§8.2 rule 3 violated: ${badSeverities.length} rule(s) with a severity not in SEVERITY's values:\n${list}\n` +
+        '  remedy: severity is a property of the RULE — set it to SEVERITY.ERROR/WARNING/INFO.',
+    );
+  }
+
+  if (uncovered.length > 0) {
+    const scannedList = testFiles.map(formatRepoRelative).join('\n  ');
+    problems.push(
+      `§8.5 violated: ${uncovered.length} rule code(s) with no describe()/test() block naming them ` +
+        `(a comment or bare string mention does not count):\n  ${uncovered.join(', ')}\n\n` +
+        `  Searched these test files:\n  ${scannedList}\n\n` +
+        '  remedy: add or extend a describe()/test() title in the matching ' +
+        'tests/health-diagnostic-rules/<group>.test.cjs file so the block title ' +
+        `names the code verbatim (e.g. describe('${uncovered[0]} — ...', () => { ... })), ` +
+        'and drive the rule to fire against a real fixture built via createTempDir() + buildPlanningSnapshot() ' +
+        '(see tests/health-diagnostic-rules/root-existence.test.cjs).',
+    );
+  }
+
+  if (consistencyDuplicates.length > 0) {
+    const list = consistencyDuplicates.map((d) => `  ${d.code} (${d.count} occurrences)`).join('\n');
+    problems.push(
+      `§8.2 rule 1 violated (C0NN namespace): ${consistencyDuplicates.length} duplicated rule code(s) in ` +
+        `CONSISTENCY_RULES (${COMPILED_MODULE_REL}):\n${list}\n` +
+        '  remedy: codes are append-only and 1:1 with a single Rule — rename or remove the duplicate.',
+    );
+  }
+
+  if (consistencyBadSeverities.length > 0) {
+    const list = consistencyBadSeverities
+      .map((b) => `  ${b.code}: severity=${JSON.stringify(b.severity)}`)
+      .join('\n');
+    problems.push(
+      `§8.2 rule 3 violated (C0NN namespace): ${consistencyBadSeverities.length} rule(s) with a severity not ` +
+        `in SEVERITY's values:\n${list}\n` +
+        '  remedy: severity is a property of the RULE — set it to SEVERITY.ERROR/WARNING/INFO.',
+    );
+  }
+
+  if (consistencyUncovered.length > 0) {
+    problems.push(
+      `§8.5 violated (C0NN namespace): ${consistencyUncovered.length} rule code(s) with no describe()/test() ` +
+        `block naming them (a comment or bare string mention does not count):\n  ${consistencyUncovered.join(', ')}\n\n` +
+        `  Searched: ${formatRepoRelative(CONSISTENCY_TEST_FILE)}` +
+        (consistencyTestFiles.length === 0 ? ' (file not found)' : '') +
+        '\n\n  remedy: add or extend a describe()/test() title in tests/health-diagnostic-rules/consistency.test.cjs ' +
+        `so the block title names the code verbatim (e.g. describe('${consistencyUncovered[0]} — ...', () => { ... })), ` +
+        'and drive the rule to fire against a real fixture built via createTempDir() + buildPlanningSnapshot().',
+    );
+  }
+
+  if (stateValidateUncovered.length > 0) {
+    problems.push(
+      `§8.5 violated (S0NN namespace): ${stateValidateUncovered.length} code(s) with no describe()/test() ` +
+        `block naming them (a comment or bare string mention does not count):\n  ${stateValidateUncovered.join(', ')}\n\n` +
+        `  Searched: ${formatRepoRelative(STATE_VALIDATE_TEST_FILE)}` +
+        (stateValidateTestFiles.length === 0 ? ' (file not found)' : '') +
+        '\n\n  remedy: add or extend a describe()/test() title in tests/state.test.cjs ' +
+        `so the block title names the code verbatim (e.g. test('${stateValidateUncovered[0]}: ...', () => { ... })), ` +
+        'mirroring the existing `#3310 state validate — S0NN coded diagnostics` describe block.',
+    );
+  }
+
+  if (problems.length > 0) {
+    throw new ExitError(1, `${problems.join('\n\n')}\n`);
+  }
+
+  const coveredCount = RULES.length - exempted.length;
+  const exemptedDetail = exempted
+    .map((code) => `${code} (${PERMANENTLY_INERT_CODES.get(code)})`)
+    .join('; ');
+
+  console.log(
+    `lint-health-diagnostic-rule-table: PASS — ${RULES.length} rule code(s): ${coveredCount} covered by a ` +
+      `real fixture, ${exempted.length} exempted across ${testFiles.length} test file(s).` +
+      (exempted.length > 0 ? `\n  Exempted: ${exemptedDetail}` : ''),
+  );
+  console.log(
+    `lint-health-diagnostic-rule-table: PASS (C0NN namespace) — ${consistencyNewRules.length} new rule code(s) ` +
+      `(${consistencyNewRules.map((r) => r.code).join(', ')}), all fixture-covered in ` +
+      `${formatRepoRelative(CONSISTENCY_TEST_FILE)}.`,
+  );
+  console.log(
+    `lint-health-diagnostic-rule-table: PASS (S0NN namespace) — ${STATE_VALIDATE_CODES.length} code(s) ` +
+      `(${STATE_VALIDATE_CODES.join(', ')}), all fixture-covered in ` +
+      `${formatRepoRelative(STATE_VALIDATE_TEST_FILE)}.`,
+  );
+}
+
+runMain(main);
+
+module.exports = {
+  loadCompiledModule,
+  checkOneToOneInvariant,
+  extractTitledBlocks,
+  codeAppearsInTitle,
+  findHealthDiagnosticTestFiles,
+  checkFixtureProofInvariant,
+  PERMANENTLY_INERT_CODES,
+  COMPILED_MODULE_PATH,
+  TEST_GROUP_DIR,
+  SKELETON_TEST_FILE,
+  CONSISTENCY_TEST_FILE,
+  STATE_VALIDATE_TEST_FILE,
+  STATE_VALIDATE_CODES,
+};

package/scripts/lint-hooks-runtime-build-seam.cjs

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * lint-hooks-runtime-build-seam.cjs — every `hooks/**` file that requires a
+ * compiled runtime-library module (`gsd-core/bin/lib/*.cjs`) must also go
+ * through the self-healing build seam (`gsd-core/bin/ensure-runtime-build.cjs`,
+ * #2002) before that require can be reached (#3582).
+ *
+ * ## Why
+ *
+ * `gsd-core/bin/lib/*.cjs` are compiled from `src/*.cts` by `npm run
+ * build:lib` (ADR-457, "build-at-publish") and are gitignored. The npm
+ * package builds before publishing, so the artifacts exist on that path.
+ * `gsd-core/bin/gsd-tools.cjs` calls `ensureRuntimeBuild()` before requiring
+ * its own `./lib` — but a plugin-marketplace / git-clone install that never
+ * runs `npm run build:lib` materializes the raw tree with the compiled
+ * `./lib` absent, and NO hook self-healed before this issue. A hook that
+ * requires a compiled module directly dies at module load (or first call)
+ * with `Cannot find module`, and — in a guard whose own catch treats "cannot
+ * resolve" as fail-closed — that `Cannot find module` gets misreported as an
+ * unrelated "could not read or resolve …configuration" denial instead of the
+ * seam's own actionable message (#3050 lesson: a guard that cannot verify
+ * must not silently misreport why).
+ *
+ * ## What this enforces
+ *
+ * For every `.js`/`.cjs` file under `hooks/` (excluding the generated
+ * `hooks/dist/` build-output copy, which is not source): if the file's code
+ * (comments stripped) contains a `require(...)` of a path that names
+ * `gsd-core/bin/lib/<name>.cjs` (any relative-path spelling — `../gsd-core/…`,
+ * `../../gsd-core/…`, etc. — the segment `gsd-core/bin/lib/` plus a trailing
+ * `.cjs` is the discriminator, not the exact prefix), the SAME file must ALSO
+ * contain BOTH:
+ *   1. a `require(...)` of a path naming `gsd-core/bin/ensure-runtime-build.cjs`
+ *      (the seam module itself), AND
+ *   2. an actual INVOCATION `ensureRuntimeBuild(` — not merely a destructuring
+ *      import with no call, which would import the seam but never run it.
+ *
+ * File-level co-occurrence, not line-by-line ordering: this repo's hooks
+ * define helper functions in whatever order reads best and call them in a
+ * different order at runtime (e.g. `hooks/gsd-cursor-subagent-start.js`'s
+ * `resolveFallbackIsolation` is defined textually ABOVE the single
+ * `ensureRuntimeBuild()` call site in `evaluateRootIsolation`, which is its
+ * only caller) — a strict "seam call must appear on an earlier LINE than the
+ * require" check would false-positive on exactly that, real, correct
+ * pattern. This guard is therefore a drift ratchet at the file level ("did
+ * the seam get wired in at all"), not a full control-flow verifier; exact
+ * placement (does the call precede every reaching path) is a code-review
+ * concern, same tradeoff every other structural drift guard in this repo
+ * makes (see e.g. `lint-unreachable-guard-drift.cjs`'s own per-line, not
+ * per-flow, scope).
+ *
+ * ## What PASSES
+ *
+ * - A hook that never requires `gsd-core/bin/lib/*.cjs` at all (most of
+ *   `hooks/`) — nothing to check.
+ * - A hook that requires a compiled module AND requires + calls
+ *   `ensureRuntimeBuild()` somewhere in the same file.
+ * - A prose comment that mentions `gsd-core/bin/lib/…` without a real,
+ *   well-formed `require('....cjs')` call (comments are stripped before
+ *   scanning).
+ *
+ * ## What FAILS
+ *
+ * - A hook that requires a compiled `gsd-core/bin/lib/*.cjs` module but never
+ *   requires `ensure-runtime-build.cjs`, or requires it but never calls
+ *   `ensureRuntimeBuild(...)`.
+ *
+ * ## Known limitations (documented, not defects — read before trusting a green run)
+ *
+ * - **Literal-string matching only.** `REQUIRE_RE` matches `require(...)`
+ *   called with a single- OR double-quoted string literal argument. A
+ *   concatenated/computed path (`require(base + '/gsd-core/bin/lib/x.cjs')`),
+ *   a template literal (`` require(`${dir}/x.cjs`) ``), or `createRequire(...)`
+ *   / `require.resolve` used indirectly all evade `isCompiledLibRequire` and
+ *   `isSeamRequire` — none of them appear as a literal quoted `require(...)`
+ *   call, so a file using one of these forms scans as "requires nothing",
+ *   even if it genuinely needs the seam.
+ * - **`hooks/` only.** `scanRepo`'s `walk()` only descends `SCAN_ROOT`
+ *   (`hooks/`, minus `hooks/dist/`). A compiled `gsd-core/bin/lib/*.cjs`
+ *   require sitting inside a NON-hooks helper module that a hook file then
+ *   requires (directly or transitively) is invisible to this scan — the scan
+ *   only ever reads the hook file's OWN text, never follows its require
+ *   graph. Deliberate: this is a same-file drift ratchet ("did the hook wire
+ *   the seam in at all"), not a whole-program static analyzer.
+ *
+ * Because of both limits, a file that passes this lint is not a
+ * correctness proof — it is a co-occurrence heuristic that catches the
+ * exact regression shape #3582 fixed (a bare literal compiled-lib require
+ * with no seam call anywhere in the same hook file). Anything routed around
+ * a literal require or around `hooks/` needs a code-review check, not this
+ * script, to catch a missing self-heal.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const ROOT = path.join(__dirname, '..');
+const SCAN_ROOT = 'hooks';
+const SCAN_EXT = new Set(['.js', '.cjs']);
+// hooks/dist/ is a generated build-output copy (scripts/build-hooks.js),
+// gitignored and not source — never scanned.
+const EXCLUDE_DIR_NAMES = new Set(['dist']);
+
+// Line-based comment stripper (deliberately NOT the naive two-regex
+// `/\*[\s\S]*?\*\//g` then `//` approach other tests in this repo use for
+// simpler files): this module's own source comments legitimately spell
+// `gsd-core/bin/lib/*.cjs` (a glob) inside a `//` line, which forms a bare
+// `/*` token — a whole-text block-comment regex applied naively would read
+// that as an OPENING block comment and swallow everything up to the next
+// unrelated `*/` anywhere later in the file, silently deleting real code
+// (verified while authoring this guard: it ate the very require() line the
+// guard exists to check for). Processing line-by-line and stripping a
+// trailing `//` comment BEFORE ever checking that line's remainder for `/*`
+// means a `/*`-shaped token inside a `//` comment is never seen at all.
+function stripComments(text) {
+  const lines = text.split(/\r?\n/);
+  const out = [];
+  let inBlock = false;
+  for (const raw of lines) {
+    let line = raw;
+    if (inBlock) {
+      const end = line.indexOf('*/');
+      if (end === -1) { out.push(''); continue; }
+      line = line.slice(end + 2);
+      inBlock = false;
+    }
+    if (line.trim().startsWith('//')) { out.push(''); continue; }
+    // Strip a trailing `//` comment (not a `://` URL) BEFORE any `/*` check
+    // on the remainder — see the function header for why this ordering
+    // matters.
+    const trailing = /(^|[^:])\/\/.*$/.exec(line);
+    if (trailing) line = line.slice(0, trailing.index + trailing[1].length);
+    // Same-line and newly-opened block comments in what remains.
+    for (;;) {
+      const start = line.indexOf('/*');
+      if (start === -1) break;
+      const end = line.indexOf('*/', start + 2);
+      if (end !== -1) {
+        line = line.slice(0, start) + line.slice(end + 2);
+        // keep scanning from the same position in case of a second
+        // same-line block comment
+      } else {
+        line = line.slice(0, start);
+        inBlock = true;
+        break;
+      }
+    }
+    out.push(line);
+  }
+  return out.join('\n');
+}
+
+// Captures the quoted path of every require(...) call. Single bounded
+// negated-class quantifier per alternative, no nesting.
+const REQUIRE_RE = /require\(\s*(['"])([^'"]+)\1\s*\)/g;
+
+function isCompiledLibRequire(requirePath) {
+  return requirePath.includes('gsd-core/bin/lib/') && requirePath.endsWith('.cjs');
+}
+
+function isSeamRequire(requirePath) {
+  return requirePath.endsWith('gsd-core/bin/ensure-runtime-build.cjs');
+}
+
+// An actual invocation, not merely a `{ ensureRuntimeBuild }` destructuring
+// import — the identifier immediately followed by `(`.
+const SEAM_CALL_RE = /\bensureRuntimeBuild\s*\(/;
+
+/**
+ * Pure: scan one file's contents for the violation described above.
+ * Returns `{ compiledLibRequires: string[], hasSeamRequire: boolean,
+ * hasSeamCall: boolean }`. `compiledLibRequires` is `[]` when the file
+ * requires no compiled module — the caller treats that as "nothing to
+ * check" regardless of the other two fields.
+ */
+function scanFile(text) {
+  const code = stripComments(text);
+  const compiledLibRequires = [];
+  let hasSeamRequire = false;
+  let m;
+  REQUIRE_RE.lastIndex = 0;
+  while ((m = REQUIRE_RE.exec(code)) !== null) {
+    const requirePath = m[2];
+    if (isCompiledLibRequire(requirePath)) compiledLibRequires.push(requirePath);
+    if (isSeamRequire(requirePath)) hasSeamRequire = true;
+  }
+  const hasSeamCall = SEAM_CALL_RE.test(code);
+  return { compiledLibRequires, hasSeamRequire, hasSeamCall };
+}
+
+function walk(dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out; // missing root is not an error here — caller decides
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory() && EXCLUDE_DIR_NAMES.has(entry.name)) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...walk(full));
+    } else if (entry.isFile() && SCAN_EXT.has(path.extname(entry.name))) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+/**
+ * Scan `root`'s hooks/ tree and return every violating file.
+ * @param {string} root  repo root (or a fixture root for tests)
+ * @returns {{ file: string, compiledLibRequires: string[], missing: string[] }[]}
+ */
+function scanRepo(root) {
+  const violations = [];
+  for (const full of walk(path.join(root, SCAN_ROOT))) {
+    const text = fs.readFileSync(full, 'utf8');
+    const { compiledLibRequires, hasSeamRequire, hasSeamCall } = scanFile(text);
+    if (compiledLibRequires.length === 0) continue;
+    if (hasSeamRequire && hasSeamCall) continue;
+    const missing = [];
+    if (!hasSeamRequire) missing.push('require(".../gsd-core/bin/ensure-runtime-build.cjs")');
+    if (!hasSeamCall) missing.push('a call to ensureRuntimeBuild(...)');
+    violations.push({
+      file: path.relative(root, full).split(path.sep).join('/'),
+      compiledLibRequires,
+      missing,
+    });
+  }
+  return violations;
+}
+
+function main() {
+  const violations = scanRepo(ROOT);
+  if (violations.length > 0) {
+    const detail = violations
+      .map((v) => (
+        `  ${v.file}\n` +
+        `    requires: ${v.compiledLibRequires.join(', ')}\n` +
+        `    missing: ${v.missing.join(' AND ')}`
+      ))
+      .join('\n');
+    throw new ExitError(
+      1,
+      `lint-hooks-runtime-build-seam: ${violations.length} hooks/ file(s) require a compiled\n` +
+        `gsd-core/bin/lib/*.cjs module without also self-healing via\n` +
+        `ensureRuntimeBuild() from gsd-core/bin/ensure-runtime-build.cjs first (#3582) — on a\n` +
+        `plugin-marketplace/git-clone install that never ran \`npm run build:lib\`, that\n` +
+        `require crashes (or is silently misreported) instead of self-building:\n\n${detail}\n`,
+    );
+  }
+  console.log('ok lint-hooks-runtime-build-seam: every hooks/ compiled-lib require goes through ensureRuntimeBuild()');
+}
+
+module.exports = { scanFile, scanRepo, walk, stripComments, isCompiledLibRequire, isSeamRequire, SEAM_CALL_RE };
+
+if (require.main === module) runMain(main);