@devrik-tools/claude-gates 0.4.0 → 0.7.0

package/plugins/gates/hooks/doctor.mjs

@@ -1,207 +1,207 @@
-// doctor — SessionStart hook. Validates the environment claude-gates needs and speaks
-// ONLY on failure: node's version (node:sqlite and other built-ins the plugin relies on
-// need >=22.5.0, read from this package's own engines.node when reachable, else a
-// hard-coded fallback) and that every gate script the registry declares actually exists
-// on disk (a plugin installed half — e.g. copied without a file, or a stale global
-// install) fails silently otherwise: hooks.json references a script that is not there,
-// and Claude Code just skips it without telling anyone).
-//
-// justification: no existing tool covers this. wiring-check.mjs (same family) checks
-// registry vs hooks.json vs disk cross-consistency; doctor.mjs checks the runtime
-// environment itself (node version) plus the same "script exists" fact from the angle
-// of "can this plugin even run", so a broken environment is caught before any gate is
-// invoked and blocks something for the wrong reason.
-//
-// Fail-safe: every check is wrapped so a doctor bug never blocks a session from
-// starting — worst case it silently skips a check rather than throwing.
-
-import { existsSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const STDIN_FILE_DESCRIPTOR = 0;
-const SESSION_START_EVENT = 'SessionStart';
-const CONFIG_KEY = 'validateEnvironmentOnStart';
-const DEFAULT_MIN_NODE_VERSION = '22.5.0';
-
-const HOOKS_DIRECTORY = dirname(fileURLToPath(import.meta.url));
-const REPOSITORY_ROOT = join(HOOKS_DIRECTORY, '..', '..', '..');
-const PACKAGE_JSON_PATH = join(REPOSITORY_ROOT, 'package.json');
-const REGISTRY_PATH = join(REPOSITORY_ROOT, 'registry.json');
-
-// Same config lookup as the other session hooks (see session-tasks.mjs / register-requests.mjs):
-// kept local and dependency-free so this plugin works standalone.
-const PROJECT_ROOT_MARKERS = ['.git', '.ai'];
-const PROJECT_CONFIG = join('.ai', 'config.json');
-const GLOBAL_CONFIG = join('.claude', 'claude-gates', 'config.json');
-
-const BOM_CHAR_CODE = 0xfeff;
-
-/** Strips a UTF-8 BOM a Windows editor/tool may have written before the JSON. */
-function stripBom(text) {
-  return text.charCodeAt(0) === BOM_CHAR_CODE ? text.slice(1) : text;
-}
-
-function readJson(path) {
-  try {
-    return JSON.parse(stripBom(readFileSync(path, 'utf8')));
-  } catch {
-    return null;
-  }
-}
-
-function projectRootOf(startDirectory) {
-  let current = startDirectory;
-  while (true) {
-    if (
-      PROJECT_ROOT_MARKERS.some((marker) => existsSync(join(current, marker)))
-    ) {
-      return current;
-    }
-    const parent = dirname(current);
-    if (parent === current) return null;
-    current = parent;
-  }
-}
-
-/** The doctor gate config entry (project overrides global), or null. */
-function doctorConfig(startDirectory) {
-  const root = projectRootOf(startDirectory);
-  const projectData = root ? readJson(join(root, PROJECT_CONFIG)) : null;
-  const globalData = readJson(join(homedir(), GLOBAL_CONFIG));
-  const layer = projectData?.gates ?? globalData?.gates ?? {};
-  const entry = layer[CONFIG_KEY];
-  if (typeof entry === 'boolean') return { enabled: entry };
-  if (entry && typeof entry === 'object') return entry;
-  return null;
-}
-
-function readPayload() {
-  try {
-    return JSON.parse(readFileSync(STDIN_FILE_DESCRIPTOR, 'utf8'));
-  } catch {
-    return {};
-  }
-}
-
-const VERSION_SEGMENT_COUNT = 3; // major, minor, patch
-
-/** Parses "22.5.0" (or "v22.5.0") into [22, 5, 0]; null when unparseable. */
-function parseVersion(raw) {
-  const withoutPrefix = String(raw ?? '').replace(/^v/, '');
-  const segments = withoutPrefix.split('.').slice(0, VERSION_SEGMENT_COUNT);
-  if (segments.length < VERSION_SEGMENT_COUNT) return null;
-  const numbers = segments.map((segment) => Number(/^\d+/.exec(segment)?.[0]));
-  return numbers.some((n) => Number.isNaN(n)) ? null : numbers;
-}
-
-/** True when `actual` >= `required`, comparing major.minor.patch lexicographically. */
-function versionAtLeast(actual, required) {
-  const a = parseVersion(actual);
-  const r = parseVersion(required);
-  if (!a || !r) return true; // can't parse: don't fail the session over a doctor bug
-  for (let index = 0; index < VERSION_SEGMENT_COUNT; index += 1) {
-    if (a[index] > r[index]) return true;
-    if (a[index] < r[index]) return false;
-  }
-  return true;
-}
-
-/** The first "x.y.z"-shaped token inside an engines.node range string (">=22.5.0" -> "22.5.0"). */
-function firstVersionToken(engineRange) {
-  for (const token of engineRange.split(/\s+/)) {
-    const digits = token.replace(/[^\d.]/g, '');
-    if (parseVersion(digits)) return digits;
-  }
-  return null;
-}
-
-/** The minimum node version this install requires: package.json's engines.node, else the fallback. */
-function minNodeVersionRequired(configuredMin) {
-  if (configuredMin) return configuredMin;
-  const packageManifest = readJson(PACKAGE_JSON_PATH);
-  const engineRange = packageManifest?.engines?.node;
-  const token = engineRange ? firstVersionToken(engineRange) : null;
-  return token ?? DEFAULT_MIN_NODE_VERSION;
-}
-
-function checkNodeVersion(minVersion) {
-  if (versionAtLeast(process.version, minVersion)) return null;
-  return (
-    `node ${process.version} is below the required >=${minVersion}. ` +
-    'Some gates (e.g. node:sqlite-backed task tracking) will not work until node is upgraded.'
-  );
-}
-
-/** Every script the registry's PreToolUse/Stop gates (folder-style: gates/<id>/index.mjs) declare. */
-function missingFolderGateScripts() {
-  const registry = readJson(REGISTRY_PATH);
-  if (!registry?.families) return []; // can't read the registry: nothing to report
-
-  const problems = [];
-  for (const family of registry.families) {
-    const pluginName = family.plugin ?? 'gates';
-    const pluginHooksDirectory = join(
-      REPOSITORY_ROOT,
-      'plugins',
-      pluginName,
-      'hooks',
-    );
-    for (const gate of family.gates ?? []) {
-      const scriptPath = join(pluginHooksDirectory, gate.script);
-      if (!existsSync(scriptPath)) {
-        problems.push(
-          `${gate.id} (expected ${join('plugins', pluginName, 'hooks', gate.script)})`,
-        );
-      }
-    }
-  }
-  return problems;
-}
-
-function speak(context) {
-  process.stdout.write(
-    JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: SESSION_START_EVENT,
-        additionalContext: context,
-      },
-    }),
-  );
-}
-
-function main() {
-  const payload = readPayload();
-  const cwd = payload.cwd || process.cwd();
-
-  const config = doctorConfig(cwd);
-  if (config && config.enabled === false) return; // gate turned off for this project
-
-  const problems = [];
-
-  const minVersion = minNodeVersionRequired(config?.minNodeVersion);
-  const versionProblem = checkNodeVersion(minVersion);
-  if (versionProblem) problems.push(versionProblem);
-
-  const missingScripts = missingFolderGateScripts();
-  if (missingScripts.length > 0) {
-    problems.push(
-      `${missingScripts.length} gate script(s) declared in registry.json are missing on disk: ${missingScripts.join(
-        ', ',
-      )}`,
-    );
-  }
-
-  if (problems.length === 0) return; // environment is healthy: stay silent
-
-  speak(
-    `[doctor] claude-gates environment check failed:\n- ${problems.join('\n- ')}`,
-  );
-}
-
-try {
-  main();
-} catch {
-  // A doctor bug must never block session start.
-}
+// doctor — SessionStart hook. Validates the environment claude-gates needs and speaks
+// ONLY on failure: node's version (node:sqlite and other built-ins the plugin relies on
+// need >=22.5.0, read from this package's own engines.node when reachable, else a
+// hard-coded fallback) and that every gate script the registry declares actually exists
+// on disk (a plugin installed half — e.g. copied without a file, or a stale global
+// install) fails silently otherwise: hooks.json references a script that is not there,
+// and Claude Code just skips it without telling anyone).
+//
+// justification: no existing tool covers this. wiring-check.mjs (same family) checks
+// registry vs hooks.json vs disk cross-consistency; doctor.mjs checks the runtime
+// environment itself (node version) plus the same "script exists" fact from the angle
+// of "can this plugin even run", so a broken environment is caught before any gate is
+// invoked and blocks something for the wrong reason.
+//
+// Fail-safe: every check is wrapped so a doctor bug never blocks a session from
+// starting — worst case it silently skips a check rather than throwing.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const STDIN_FILE_DESCRIPTOR = 0;
+const SESSION_START_EVENT = 'SessionStart';
+const CONFIG_KEY = 'validateEnvironmentOnStart';
+const DEFAULT_MIN_NODE_VERSION = '22.5.0';
+
+const HOOKS_DIRECTORY = dirname(fileURLToPath(import.meta.url));
+const REPOSITORY_ROOT = join(HOOKS_DIRECTORY, '..', '..', '..');
+const PACKAGE_JSON_PATH = join(REPOSITORY_ROOT, 'package.json');
+const REGISTRY_PATH = join(REPOSITORY_ROOT, 'registry.json');
+
+// Same config lookup as the other session hooks (see session-tasks.mjs / register-requests.mjs):
+// kept local and dependency-free so this plugin works standalone.
+const PROJECT_ROOT_MARKERS = ['.git', '.ai'];
+const PROJECT_CONFIG = join('.ai', 'config.json');
+const GLOBAL_CONFIG = join('.claude', 'claude-gates', 'config.json');
+
+const BOM_CHAR_CODE = 0xfeff;
+
+/** Strips a UTF-8 BOM a Windows editor/tool may have written before the JSON. */
+function stripBom(text) {
+  return text.charCodeAt(0) === BOM_CHAR_CODE ? text.slice(1) : text;
+}
+
+function readJson(path) {
+  try {
+    return JSON.parse(stripBom(readFileSync(path, 'utf8')));
+  } catch {
+    return null;
+  }
+}
+
+function projectRootOf(startDirectory) {
+  let current = startDirectory;
+  while (true) {
+    if (
+      PROJECT_ROOT_MARKERS.some((marker) => existsSync(join(current, marker)))
+    ) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+/** The doctor gate config entry (project overrides global), or null. */
+function doctorConfig(startDirectory) {
+  const root = projectRootOf(startDirectory);
+  const projectData = root ? readJson(join(root, PROJECT_CONFIG)) : null;
+  const globalData = readJson(join(homedir(), GLOBAL_CONFIG));
+  const layer = projectData?.gates ?? globalData?.gates ?? {};
+  const entry = layer[CONFIG_KEY];
+  if (typeof entry === 'boolean') return { enabled: entry };
+  if (entry && typeof entry === 'object') return entry;
+  return null;
+}
+
+function readPayload() {
+  try {
+    return JSON.parse(readFileSync(STDIN_FILE_DESCRIPTOR, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+const VERSION_SEGMENT_COUNT = 3; // major, minor, patch
+
+/** Parses "22.5.0" (or "v22.5.0") into [22, 5, 0]; null when unparseable. */
+function parseVersion(raw) {
+  const withoutPrefix = String(raw ?? '').replace(/^v/, '');
+  const segments = withoutPrefix.split('.').slice(0, VERSION_SEGMENT_COUNT);
+  if (segments.length < VERSION_SEGMENT_COUNT) return null;
+  const numbers = segments.map((segment) => Number(/^\d+/.exec(segment)?.[0]));
+  return numbers.some((n) => Number.isNaN(n)) ? null : numbers;
+}
+
+/** True when `actual` >= `required`, comparing major.minor.patch lexicographically. */
+function versionAtLeast(actual, required) {
+  const a = parseVersion(actual);
+  const r = parseVersion(required);
+  if (!a || !r) return true; // can't parse: don't fail the session over a doctor bug
+  for (let index = 0; index < VERSION_SEGMENT_COUNT; index += 1) {
+    if (a[index] > r[index]) return true;
+    if (a[index] < r[index]) return false;
+  }
+  return true;
+}
+
+/** The first "x.y.z"-shaped token inside an engines.node range string (">=22.5.0" -> "22.5.0"). */
+function firstVersionToken(engineRange) {
+  for (const token of engineRange.split(/\s+/)) {
+    const digits = token.replace(/[^\d.]/g, '');
+    if (parseVersion(digits)) return digits;
+  }
+  return null;
+}
+
+/** The minimum node version this install requires: package.json's engines.node, else the fallback. */
+function minNodeVersionRequired(configuredMin) {
+  if (configuredMin) return configuredMin;
+  const packageManifest = readJson(PACKAGE_JSON_PATH);
+  const engineRange = packageManifest?.engines?.node;
+  const token = engineRange ? firstVersionToken(engineRange) : null;
+  return token ?? DEFAULT_MIN_NODE_VERSION;
+}
+
+function checkNodeVersion(minVersion) {
+  if (versionAtLeast(process.version, minVersion)) return null;
+  return (
+    `node ${process.version} is below the required >=${minVersion}. ` +
+    'Some gates (e.g. node:sqlite-backed task tracking) will not work until node is upgraded.'
+  );
+}
+
+/** Every script the registry's PreToolUse/Stop gates (folder-style: gates/<id>/index.mjs) declare. */
+function missingFolderGateScripts() {
+  const registry = readJson(REGISTRY_PATH);
+  if (!registry?.families) return []; // can't read the registry: nothing to report
+
+  const problems = [];
+  for (const family of registry.families) {
+    const pluginName = family.plugin ?? 'gates';
+    const pluginHooksDirectory = join(
+      REPOSITORY_ROOT,
+      'plugins',
+      pluginName,
+      'hooks',
+    );
+    for (const gate of family.gates ?? []) {
+      const scriptPath = join(pluginHooksDirectory, gate.script);
+      if (!existsSync(scriptPath)) {
+        problems.push(
+          `${gate.id} (expected ${join('plugins', pluginName, 'hooks', gate.script)})`,
+        );
+      }
+    }
+  }
+  return problems;
+}
+
+function speak(context) {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: SESSION_START_EVENT,
+        additionalContext: context,
+      },
+    }),
+  );
+}
+
+function main() {
+  const payload = readPayload();
+  const cwd = payload.cwd || process.cwd();
+
+  const config = doctorConfig(cwd);
+  if (config && config.enabled === false) return; // gate turned off for this project
+
+  const problems = [];
+
+  const minVersion = minNodeVersionRequired(config?.minNodeVersion);
+  const versionProblem = checkNodeVersion(minVersion);
+  if (versionProblem) problems.push(versionProblem);
+
+  const missingScripts = missingFolderGateScripts();
+  if (missingScripts.length > 0) {
+    problems.push(
+      `${missingScripts.length} gate script(s) declared in registry.json are missing on disk: ${missingScripts.join(
+        ', ',
+      )}`,
+    );
+  }
+
+  if (problems.length === 0) return; // environment is healthy: stay silent
+
+  speak(
+    `[doctor] claude-gates environment check failed:\n- ${problems.join('\n- ')}`,
+  );
+}
+
+try {
+  main();
+} catch {
+  // A doctor bug must never block session start.
+}

package/plugins/gates/hooks/gates/atomic-commit/index.mjs

@@ -0,0 +1,229 @@
+// atomic-commit — denies a `git commit` that is not atomic: one that mixes too many distinct
+// NATURES of change (code + tests + deps + config in one shot) or stages more reviewable files
+// than a commit should carry. It never commits or groups for you (that is a tool, not a gate,
+// and the user already has guard-autocommit for it); it only OBJECTS when the staged set is not
+// a cohesive, reviewable unit, so the split happens before the commit lands.
+//
+// justification: no existing gate covers this. lint-commit/staged-lint run the linter on a
+// commit; no-coauthor reads the message; none look at the SHAPE of the staged set. This is the
+// first gate that judges whether a commit is atomic.
+//
+// ── How it decides (deterministic) ───────────────────────────────────────────────────
+// On a real `git commit`, it lists the staged files and classifies each by nature (deps,
+// generated, assets, docs, config, types, tests, tooling, or code). Docs/assets/generated do
+// NOT count toward the size or the mix — they are legitimately committed alongside anything and
+// are not reviewed line by line (same rule guard-autocommit uses). Among the files that DO
+// count, it blocks when either:
+//   · the number of distinct counted natures exceeds `maxNatures` (default 2 — e.g. code+tests
+//     is fine, but code+tests+deps+config in one commit is not atomic), or
+//   · the number of counted files exceeds `maxFiles` (default 12) — too large to review.
+// A commit that is already scoped (`--amend`, a merge, or the escape hatch) is left alone.
+//
+// ── What a project can configure (params) ───────────────────────────────────────────
+//   maxFiles     max counted files in one commit. Default 12.
+//   maxNatures   max distinct counted natures in one commit. Default 2.
+//   escapeHatch  substring in the command that allows one deliberately broad commit.
+//                Default '[wip]'.
+//   natures      the classification table (name + regex source + counts flag). Replaces the
+//                built-in list wholesale.
+//
+// ── Fail-safe shape ──────────────────────────────────────────────────────────────────
+// Not a commit, an --amend, or nothing staged: allow (silent). git not queryable: allow (the
+// gate cannot judge and must not block a legitimate commit on a git error). Otherwise: deny
+// with the offending mix/size and how to split.
+
+import { spawnSync } from 'node:child_process';
+import { runGate, deny, toolInGroups } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'atomic-commit';
+const CONFIG_KEY = 'blockNonAtomicCommits';
+
+const SHELL_GROUPS = ['shell'];
+const DEFAULT_MAX_FILES = 12;
+const DEFAULT_MAX_NATURES = 2;
+const DEFAULT_ESCAPE_HATCH = '[wip]';
+
+// Nature table, evaluated in order (first match wins), mirroring guard-autocommit's catalog so
+// a project that uses both sees the same grouping. `counts:false` = committed alongside anything
+// and not counted toward size/mix (docs, assets, generated artifacts).
+const DEFAULT_NATURES = [
+  {
+    name: 'deps',
+    source: String.raw`(^|/)(package\.json|package-lock\.json|pnpm-lock\.yaml|yarn\.lock|requirements\.txt|Cargo\.lock|go\.sum)$`,
+    counts: true,
+  },
+  {
+    name: 'generated',
+    source: String.raw`(^|/)(dist|build|coverage|__snapshots__)/|\.snap$|baseline.*\.json$`,
+    counts: false,
+  },
+  {
+    name: 'assets',
+    source: String.raw`\.(png|jpe?g|gif|svg|webp|ico|woff2?|ttf|otf|eot|mp[34]|wav|webm|pdf)$`,
+    counts: false,
+  },
+  {
+    name: 'docs',
+    source: String.raw`\.(md|mdx|txt|adoc|rst|org|log|csv|tsv)$`,
+    counts: false,
+  },
+  {
+    name: 'config',
+    source: String.raw`(^|/)(tsconfig.*\.json|.*\.config\.[cm]?[jt]s|\.eslintrc.*|\.prettierrc.*|\.editorconfig|Dockerfile|docker-compose\.ya?ml|\.gitattributes|\.gitignore)$`,
+    counts: true,
+  },
+  {
+    name: 'types',
+    source: String.raw`(^|/)(types?|interfaces?|models?|schemas?)/|\.d\.ts$`,
+    counts: true,
+  },
+  {
+    name: 'tests',
+    source: String.raw`(^|/)(tests?|__tests__|spec)/|\.(test|spec)\.[cm]?[jt]sx?$`,
+    counts: true,
+  },
+  {
+    name: 'tooling',
+    source: String.raw`(^|/)(scripts|hooks|\.ai|\.claude|\.github)/`,
+    counts: true,
+  },
+];
+const DEFAULT_NATURE = { name: 'code', counts: true };
+
+// git-global-option normalization, shared with the other commit gates.
+const GIT_OPTION_WITH_VALUE = String.raw`(?:-[Cc]|--git-dir|--work-tree|--namespace|--exec-path|--config-env)(?:\s+|=)\S+`;
+const GIT_FLAG_OPTION = String.raw`--(?:paginate|no-pager|bare|no-optional-locks)|-p`;
+const GIT_GLOBAL_OPTION_PATTERN = new RegExp(
+  String.raw`\bgit\s+(?:${GIT_OPTION_WITH_VALUE}|${GIT_FLAG_OPTION})\s+`,
+  'i',
+);
+const GIT_COMMIT_PATTERN = /\bgit\s+commit\b/i;
+// An --amend or a merge commit is a deliberate, already-scoped operation — not this gate's.
+const EXEMPT_COMMIT_PATTERN = /--amend\b|\bgit\s+merge\b/i;
+
+function normalizeGitOptions(command) {
+  let previous;
+  let normalized = command;
+  do {
+    previous = normalized;
+    normalized = normalized.replace(GIT_GLOBAL_OPTION_PATTERN, 'git ');
+  } while (normalized !== previous);
+  return normalized;
+}
+
+function isPlainCommit(command) {
+  const normalized = normalizeGitOptions(command);
+  return (
+    GIT_COMMIT_PATTERN.test(normalized) &&
+    !EXEMPT_COMMIT_PATTERN.test(normalized)
+  );
+}
+
+function commandTextFrom(toolInput) {
+  return String(toolInput.CommandLine ?? toolInput.command ?? '');
+}
+
+/** The staged files (added/copied/modified/renamed), or [] when git cannot be queried. */
+function stagedFiles(cwd) {
+  const result = spawnSync(
+    'git',
+    ['diff', '--cached', '--name-only', '--diff-filter=ACMR'],
+    { cwd, encoding: 'utf8' },
+  );
+  if (result.status !== 0 || !result.stdout) return [];
+  return result.stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .map((line) => line.replace(/\\/g, '/'));
+}
+
+function compileNatures(natures) {
+  return natures.map((nature) => ({
+    name: nature.name,
+    counts: nature.counts !== false,
+    pattern: (() => {
+      try {
+        return new RegExp(nature.source, 'i');
+      } catch {
+        return null;
+      }
+    })(),
+  }));
+}
+
+function natureOf(filePath, compiledNatures) {
+  for (const nature of compiledNatures) {
+    if (nature.pattern && nature.pattern.test(filePath)) return nature;
+  }
+  return DEFAULT_NATURE;
+}
+
+/** Classifies the staged files: the counted (reviewable) ones and the distinct natures among
+ * them. Docs/assets/generated (counts:false) are excluded from both. */
+function classifyStaged(files, compiledNatures) {
+  const counted = [];
+  const countedNatures = new Set();
+  for (const file of files) {
+    const nature = natureOf(file, compiledNatures);
+    if (!nature.counts) continue;
+    counted.push(file);
+    countedNatures.add(nature.name);
+  }
+  return { counted, countedNatures };
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: false,
+    defaultParams: {
+      maxFiles: DEFAULT_MAX_FILES,
+      maxNatures: DEFAULT_MAX_NATURES,
+      escapeHatch: DEFAULT_ESCAPE_HATCH,
+      natures: DEFAULT_NATURES,
+    },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    if (!toolInGroups(toolName, SHELL_GROUPS)) return;
+
+    const command = commandTextFrom(toolInput);
+    if (!isPlainCommit(command)) return;
+
+    const escapeHatch = parameters.escapeHatch ?? DEFAULT_ESCAPE_HATCH;
+    if (escapeHatch && command.includes(escapeHatch)) return;
+
+    const cwd = process.cwd();
+    const files = stagedFiles(cwd);
+    if (files.length === 0) return; // nothing staged (or git unqueryable): nothing to judge
+
+    const compiledNatures = compileNatures(
+      parameters.natures ?? DEFAULT_NATURES,
+    );
+    const { counted, countedNatures } = classifyStaged(files, compiledNatures);
+
+    const maxFiles = parameters.maxFiles ?? DEFAULT_MAX_FILES;
+    const maxNatures = parameters.maxNatures ?? DEFAULT_MAX_NATURES;
+
+    if (countedNatures.size > maxNatures) {
+      deny(
+        GATE_ID,
+        `This commit mixes ${countedNatures.size} kinds of change ` +
+          `(${[...countedNatures].join(', ')}) — a commit should be one cohesive change ` +
+          `(max ${maxNatures}). Split it: stage and commit one nature at a time (e.g. the ` +
+          `code, then its tests, then deps). Docs/assets/generated files do not count. ` +
+          `Add "${escapeHatch}" to the command for one deliberately broad commit.`,
+      );
+    }
+
+    if (counted.length > maxFiles) {
+      deny(
+        GATE_ID,
+        `This commit stages ${counted.length} reviewable files (max ${maxFiles}) — too large ` +
+          `to review as one unit. Split it into smaller, cohesive commits (docs/assets/` +
+          `generated files are not counted). Add "${escapeHatch}" for one deliberately broad commit.`,
+      );
+    }
+  },
+);