@devrik-tools/claude-gates 0.7.2 → 0.9.0

package/plugins/gates/hooks/gates/sdd-specs/index.mjs

@@ -1,33 +1,23 @@
-// sdd-specs — denies implementation (a write to the catalog moving a feature past
-// `spec_ready`, or a delegation prompt that implements) when the feature/task it targets
-// has no non-empty contract on disk (requirements/design/tasks or brief/asserts).
-// Migrated from ~/.claude/hooks/guard-sdd-specs.mjs.
+// sdd-specs — denies implementation (a catalog write moving a feature past `spec_ready`,
+// or a STANDARD/HIGH-RISK implementation delegation citing a feature) when the feature has
+// no non-empty contract on disk (requirements/design/tasks or brief/asserts).
 //
-// ── What a project can configure (params) ───────────────────────────────────────────
-//   catalogLocations   paths (relative to the project root) searched for the feature
-//                       catalog. Replaces the built-in list wholesale.
-//   exemptSubagents     subagent types exempt from the spec requirement (read-only
-//                       stages of the pipeline that cannot require a contract of
-//                       themselves). Replaces the built-in list wholesale.
-// The defaults live here, in the source, so a project reads them and knows exactly what
-// its override replaces.
-//
-// ── Auto-off when there is no SDD harness ───────────────────────────────────────────
-// This gate only acts once a catalog is found at one of `catalogLocations` (or the
-// project's own `.ai/config.json` declares adoption). A project that never adopted the
-// spec-driven harness has no catalog and no declared adoption, so every check below is
-// skipped and the write/delegation is allowed — imposing phases on a project that never
-// asked for them is the false positive that gets a gate disabled.
-//
-// ── Two surfaces inspected ───────────────────────────────────────────────────────────
-// A write to the catalog is checked against the catalog's own declared statuses: a
-// feature marked `spec_ready`/`in_progress`/`done` needs its contract tree in place. A
-// delegation prompt is checked when it declares a STANDARD/HIGH-RISK level and an
-// implementation verb: the contract tree must have non-empty requirements/design/tasks
-// (or brief/asserts) for the feature it targets.
+// Decisions: the gate is inert until a catalog exists at one of `catalogLocations` — a
+// project that never adopted the spec-driven harness must not be held to it. A delegation
+// citing several features is denied when ANY of them lacks a contract. The LAST declared
+// LEVEL governs, so a decoy MICRO before HIGH-RISK exempts nothing.
 
 import { existsSync, statSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { basename, dirname, isAbsolute, join } from 'node:path';
+import { projectRootOf } from '../../lib/config.mjs';
+import {
+  DEFAULT_EXEMPT_SUBAGENTS,
+  DEMANDING_LEVELS,
+  featureNamesCitedIn,
+  isImplementationRequest,
+  isSubagentNamedIn,
+  operativeLevelOf,
+} from '../../lib/delegation.mjs';
 import {
   runGate,
   deny,
@@ -41,27 +31,15 @@ const GATE_ID = 'sdd-specs';
 const CONFIG_KEY = 'requireSpecBeforeImplementing';
 
 const CATALOG_FILE_NAME = 'feature_list.json';
+const FEATURES_DIRECTORY = 'features';
 
 const DEFAULT_CATALOG_LOCATIONS = [
   join('.ai', CATALOG_FILE_NAME),
   CATALOG_FILE_NAME,
 ];
 
-const DEFAULT_EXEMPT_SUBAGENTS = [
-  'explore',
-  'plan',
-  'scout',
-  'revision',
-  'contraste',
-  'test-planner',
-  'qa',
-  'ui',
-  'ux',
-];
-
 const ADVANCED_STATUSES = new Set(['spec_ready', 'in_progress', 'done']);
 
-/** Files that count as a feature's contract; at least one must be non-empty. */
 const CONTRACT_FILES = [
   'requirements.md',
   'design.md',
@@ -70,29 +48,6 @@ const CONTRACT_FILES = [
   'asserts.md',
 ];
 
-function withWordBoundary(alternation) {
-  return new RegExp(
-    `(?<![\\p{L}\\p{N}_])(${alternation})(?![\\p{L}\\p{N}_])`,
-    'iu',
-  );
-}
-
-const IMPLEMENTATION_VERBS = withWordBoundary(
-  'implementa|implementar|implement(á|é)|agreg(a|á)|agregar|añad(e|í)|añadir|cre(a|á)|crear|' +
-    'arregl(a|á)|arreglar|cambi(a|á)|cambiar|migr(a|á)|migrar|' +
-    'corrige|corregir|correg(í|ir)|constru(ye|í)|construir|modific(a|á)|modificar|' +
-    'refactoriz(a|á)|refactorizar|elimin(a|á)|eliminar|reescrib(e|í)|reescribir|desplieg(a|á)|desplegar|' +
-    'escrib(í|e)|escribir|implement\\w*|writ(e|ing)|creat\\w*|fix\\w*|build\\w*|refactor\\w*|migrat\\w*|' +
-    'add\\w*|remov\\w*|delet\\w*|modify|modifies|modifying|rewrit\\w*',
-);
-
-/** Declared LEVEL near the word "level"/"classification" in Spanish or English, matching
- * the plugin-wide convention (see risk-level.mjs). */
-const DEMANDING_LEVEL_PATTERN =
-  /(nivel|level|clasificaci[oó]n|classification)[^\n]{0,25}?\b(STANDARD|HIGH-RISK)\b/iu;
-const EXEMPT_LEVEL_PATTERN =
-  /(nivel|level|clasificaci[oó]n|classification)[^\n]{0,25}?\b(QUESTION|MICRO)\b/iu;
-
 function fileExistsNonEmpty(path) {
   try {
     return existsSync(path) && statSync(path).size > 0;
@@ -101,32 +56,30 @@ function fileExistsNonEmpty(path) {
   }
 }
 
-function findCatalog(catalogLocations, writtenPath) {
-  const roots = [process.cwd()];
-  // A write can target a catalog that lives elsewhere than cwd (a monorepo subpackage's
-  // own .ai/feature_list.json): also resolve catalogLocations relative to the directory
-  // of the file actually being written, not only the process cwd.
-  if (writtenPath) roots.push(dirname(writtenPath));
-  for (const root of roots) {
+function resolveFrom(root, path) {
+  return isAbsolute(path) ? path : join(root, path);
+}
+
+function findCatalog(root, catalogLocations, writtenPath) {
+  const roots = [root];
+  // A monorepo subpackage keeps its own catalog next to the file being written.
+  if (writtenPath) roots.push(dirname(resolveFrom(root, writtenPath)));
+  for (const base of roots) {
     for (const relative of catalogLocations) {
-      const path = join(root, relative);
+      const path = resolveFrom(base, relative);
       if (existsSync(path)) return path;
     }
   }
   return null;
 }
 
-/** Discovers the contract tree root next to wherever the catalog lives, or `.ai/features`. */
-function contractTreeRootFor(catalogPath) {
-  const candidates = catalogPath
-    ? [join(dirname(catalogPath), 'features')]
-    : [];
-  candidates.push(join(process.cwd(), '.ai', 'features'));
-  candidates.push(join(process.cwd(), 'features'));
-  for (const candidate of candidates) {
-    if (existsSync(candidate)) return candidate;
-  }
-  return null;
+function contractTreeRootFor(root, catalogPath) {
+  const candidates = [
+    join(dirname(catalogPath), FEATURES_DIRECTORY),
+    join(root, '.ai', FEATURES_DIRECTORY),
+    join(root, FEATURES_DIRECTORY),
+  ];
+  return candidates.find((candidate) => existsSync(candidate)) ?? null;
 }
 
 function contractExistsFor(treeRoot, featureName) {
@@ -146,11 +99,7 @@ function parseJsonOrNull(text) {
   }
 }
 
-/** Denies the single first advanced-status feature in the new catalog content that has
- * no contract on disk, or does nothing when every advanced feature has one. A feature
- * object missing its `name` field is denied too (not silently skipped) — it is malformed
- * catalog data, not a feature this gate has decided has no obligations. */
-function denyIfAdvancedFeatureLacksContract(features, treeRoot) {
+function denyIfAdvancedFeatureLacksContract(features, treeRoot, fallbackRoot) {
   for (const feature of features) {
     if (!ADVANCED_STATUSES.has(feature?.status)) continue;
     if (!feature?.name) {
@@ -160,13 +109,9 @@ function denyIfAdvancedFeatureLacksContract(features, treeRoot) {
           `${JSON.stringify(feature)}. Every feature needs a 'name' so its contract tree ` +
           '(.ai/features/<name>/) can be located — add it before writing this status.',
       );
-      continue;
     }
     if (contractExistsFor(treeRoot, feature.name)) continue;
-    const featureDirectory = join(
-      treeRoot ?? join(process.cwd(), '.ai', 'features'),
-      feature.name,
-    );
+    const featureDirectory = join(treeRoot ?? fallbackRoot, feature.name);
     deny(
       CONFIG_KEY,
       `Feature '${feature.name}' is set to '${feature.status}' but has no non-empty ` +
@@ -176,70 +121,64 @@ function denyIfAdvancedFeatureLacksContract(features, treeRoot) {
   }
 }
 
-function checkCatalogWrite(toolInput, catalogPath, treeRoot) {
+function targetsCatalog(target, catalogLocations) {
+  const name = basename(target);
+  return catalogLocations.some((location) => basename(location) === name);
+}
+
+function checkCatalogWrite(
+  toolInput,
+  catalogLocations,
+  treeRoot,
+  fallbackRoot,
+) {
   const target = writtenPathOf(toolInput);
-  if (!catalogPath || !target.includes(CATALOG_FILE_NAME)) return;
+  if (!target || !targetsCatalog(target, catalogLocations)) return;
 
-  const rawContent = writtenContentOf(toolInput);
-  const parsed = parseJsonOrNull(rawContent);
+  const parsed = parseJsonOrNull(writtenContentOf(toolInput));
   if (parsed === null) {
-    // Fail-closed, not fail-open: a write whose content does not parse as JSON but
-    // still targets the catalog is suspicious on its own -- a spec_ready/done transition
-    // hidden behind a malformed payload must not be silently allowed through.
+    // Fail closed: a status transition hidden behind malformed JSON must not slip through.
     deny(
       CONFIG_KEY,
-      `The write to ${CATALOG_FILE_NAME} does not parse as JSON (JSON.parse threw). This ` +
+      `The write to ${basename(target)} does not parse as JSON (JSON.parse threw). This ` +
         'is a syntax problem in the content being written, not a missing-field one — check ' +
         'for a trailing comma, unquoted key, or unclosed bracket in what you are about to ' +
         'write. No filesystem exploration needed; the payload itself is the thing to fix.',
     );
   }
   const features = Array.isArray(parsed?.features) ? parsed.features : [];
-  denyIfAdvancedFeatureLacksContract(features, treeRoot);
+  denyIfAdvancedFeatureLacksContract(features, treeRoot, fallbackRoot);
 }
 
 function isExemptDelegation(toolInput, prompt, exemptSubagents) {
-  const subagentType = String(
-    toolInput.subagent_type ?? toolInput.subagentType ?? '',
-  ).toLowerCase();
-  if (exemptSubagents.includes(subagentType)) return true;
-  if (EXEMPT_LEVEL_PATTERN.test(prompt)) return true;
-  if (!DEMANDING_LEVEL_PATTERN.test(prompt)) return true;
-  if (!IMPLEMENTATION_VERBS.test(prompt)) return true;
-  return false;
+  if (isSubagentNamedIn(toolInput, exemptSubagents)) return true;
+  if (!DEMANDING_LEVELS.has(operativeLevelOf(prompt))) return true;
+  return !isImplementationRequest(prompt);
 }
 
-function featureNamesCitedIn(prompt) {
-  const pattern = /\.(?:ai)[\\/]features[\\/]([\w.@-]+)/gi;
-  const names = [];
-  let match;
-  while ((match = pattern.exec(prompt)) !== null) names.push(match[1]);
-  return names;
-}
-
-function checkDelegation(toolInput, treeRoot, exemptSubagents) {
+function checkDelegation(toolInput, treeRoot, fallbackRoot, exemptSubagents) {
   const prompt = delegationPromptOf(toolInput);
   if (!prompt.trim()) return;
   if (isExemptDelegation(toolInput, prompt, exemptSubagents)) return;
 
   const citedFeatures = featureNamesCitedIn(prompt);
-  if (citedFeatures.length === 0) return; // no citation: nothing this gate can check
+  if (citedFeatures.length === 0) return;
 
   const missing = citedFeatures.filter(
     (feature) => !contractExistsFor(treeRoot, feature),
   );
-  if (missing.length === citedFeatures.length) {
-    const root = treeRoot ?? join(process.cwd(), '.ai', 'features');
-    const fileList = missing
-      .map((feature) => `${feature} -> ${join(root, feature)}/`)
-      .join('\n  ');
-    deny(
-      CONFIG_KEY,
-      `This implementation delegation cites feature(s) with no contract on disk:\n  ${fileList}\n` +
-        `Write ONE of these files in each directory above (any one is enough): ` +
-        `${CONTRACT_FILES.join(', ')}. Then relaunch.`,
-    );
-  }
+  if (missing.length === 0) return;
+
+  const root = treeRoot ?? fallbackRoot;
+  const fileList = missing
+    .map((feature) => `${feature} -> ${join(root, feature)}/`)
+    .join('\n  ');
+  deny(
+    CONFIG_KEY,
+    `This implementation delegation cites feature(s) with no contract on disk:\n  ${fileList}\n` +
+      `Write ONE of these files in each directory above (any one is enough): ` +
+      `${CONTRACT_FILES.join(', ')}. Then relaunch.`,
+  );
 }
 
 runGate(
@@ -252,26 +191,34 @@ runGate(
       exemptSubagents: DEFAULT_EXEMPT_SUBAGENTS,
     },
   },
-  ({ toolName, toolInput, parameters }) => {
+  ({ toolName, toolInput, parameters, cwd }) => {
     const isWrite = toolInGroups(toolName, ['write']);
     const isDelegation = toolInGroups(toolName, ['delegation']);
     if (!isWrite && !isDelegation) return;
 
+    const root = projectRootOf(cwd) ?? cwd;
     const catalogLocations =
-      parameters.catalogLocations ?? DEFAULT_CATALOG_LOCATIONS;
+      parameters.catalogLocations.length > 0
+        ? parameters.catalogLocations
+        : DEFAULT_CATALOG_LOCATIONS;
     const catalogPath = findCatalog(
+      root,
       catalogLocations,
       isWrite ? writtenPathOf(toolInput) : null,
     );
-    if (!catalogPath) return; // no SDD harness adopted: stay silent
-
-    const treeRoot = contractTreeRootFor(catalogPath);
-
-    if (isWrite) checkCatalogWrite(toolInput, catalogPath, treeRoot);
-    if (isDelegation) {
-      const exemptSubagents =
-        parameters.exemptSubagents ?? DEFAULT_EXEMPT_SUBAGENTS;
-      checkDelegation(toolInput, treeRoot, exemptSubagents);
-    }
+    if (!catalogPath) return;
+
+    const treeRoot = contractTreeRootFor(root, catalogPath);
+    const fallbackRoot = join(root, '.ai', FEATURES_DIRECTORY);
+
+    if (isWrite)
+      checkCatalogWrite(toolInput, catalogLocations, treeRoot, fallbackRoot);
+    if (isDelegation)
+      checkDelegation(
+        toolInput,
+        treeRoot,
+        fallbackRoot,
+        parameters.exemptSubagents,
+      );
   },
 );

package/plugins/gates/hooks/gates/staged-lint/index.mjs

@@ -1,51 +1,53 @@
-// staged-lint — denies a `git commit` when the files YOU staged fail lint. It never lints the
-// whole repo (that would block you on pre-existing debt in files you never touched); it lints
-// ONLY the staged files — what this commit actually introduces — so a clean commit is never
-// held hostage by someone else's old lint errors, and you can never add NEW lint debt through
-// your own change.
-//
-// justification: no existing gate covers this. lint-commit runs the project's lint script over
-// the WHOLE project and blocks if anything fails — too broad: a repo with pre-existing debt can
-// never commit. This gate scopes the check to the staged set, so it enforces "your change is
-// clean" without demanding "the whole repo is clean".
-//
-// ── How it works ─────────────────────────────────────────────────────────────────────
-// On a real `git commit`, it asks git for the staged files (`git diff --cached --name-only
-// --diff-filter=ACM`), keeps the ones with a lintable extension, and runs the project's lint
-// command over exactly those paths. Non-zero exit → deny with the lint output. No staged
-// lintable file, or no lint command declared → allow (nothing to enforce, never invented).
-//
-// ── What a project can configure (params) ───────────────────────────────────────────
-//   lintCommand      the command to run; the staged paths are appended as arguments. Default
-//                    null → autodetect eslint (`npx eslint`) when the project has an eslint
-//                    config, else allow (never invent a linter).
-//   lintExtensions   which staged file extensions are linted. Default js/mjs/cjs/ts/tsx/jsx.
-//   lintTimeoutMs    how long the lint run may take before it counts as a failure.
-//   escapeHatch      substring in the command that skips the check for one commit. Default
-//                    '[skip-lint]'.
-//
-// ── Fail-safe shape ──────────────────────────────────────────────────────────────────
-// Not a commit: allow (silent). No staged lintable files, or no linter: allow. The lint run
-// cannot spawn: deny (a commit gate that cannot evaluate must not silently permit). Lint exits
-// non-zero: deny with the tail of its output. Lint exits zero: allow.
+// staged-lint — denies a `git commit` when the files THIS commit carries fail lint. It never
+// lints the whole repo (pre-existing debt in untouched files must not block you); it lints
+// what the commit will contain: the staged set plus whatever a `git add …` earlier in the
+// same command line or a `-a` flag stages before the commit runs. Only a command segment that
+// RUNS git commit counts; a `--dry-run` writes nothing. No lintable file, or no linter
+// declared or detected: allow — this gate never invents a linter. A lint run that cannot
+// spawn is denied: a commit gate must not silently permit.
 
 import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { extname, join } from 'node:path';
-import { runGate, deny, toolInGroups } from '../../lib/hook-io.mjs';
+import { projectRootOf, readJsonOrNull } from '../../lib/config.mjs';
+import {
+  effectiveCommitFiles,
+  isDryRunCommit,
+  isGitCommit,
+  normalizeGitCommand,
+} from '../../lib/git.mjs';
+import {
+  deny,
+  runGate,
+  shellCommandOf,
+  toolInGroups,
+} from '../../lib/hook-io.mjs';
 
 const GATE_ID = 'staged-lint';
 const CONFIG_KEY = 'blockCommitWithStagedLintErrors';
 
-const SHELL_GROUPS = ['shell'];
 const DEFAULT_LINT_TIMEOUT_MS = 60000;
 const OUTPUT_TAIL_LINES = 20;
 const DEFAULT_ESCAPE_HATCH = '[skip-lint]';
-const DEFAULT_LINT_EXTENSIONS = ['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx'];
+const DEFAULT_LINT_EXTENSIONS = [
+  '.js',
+  '.mjs',
+  '.cjs',
+  '.ts',
+  '.mts',
+  '.cts',
+  '.tsx',
+  '.jsx',
+  '.vue',
+  '.svelte',
+];
 const ESLINT_CONFIG_FILES = [
   'eslint.config.mjs',
   'eslint.config.js',
   'eslint.config.cjs',
+  'eslint.config.ts',
+  'eslint.config.mts',
+  'eslint.config.cts',
   '.eslintrc',
   '.eslintrc.js',
   '.eslintrc.cjs',
@@ -54,74 +56,57 @@ const ESLINT_CONFIG_FILES = [
   '.eslintrc.yaml',
 ];
 
-// Same git-global-option normalization lint-commit and no-coauthor use, so
-// `git -C /repo -c x=y commit` reduces to `git commit` before the pattern runs.
-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;
-
-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 isGitCommit(command) {
-  return GIT_COMMIT_PATTERN.test(normalizeGitOptions(command));
+// ── The commit segment ──────────────────────────────────────────────────────────────
+const SEGMENT_SEPARATOR = /;|&&|\|\||\||\n/;
+const ARGUMENT_PATTERN = /"([^"]*)"|'([^']*)'|(\S+)/g;
+const GIT_BINARY_TOKEN = /(?:^|[\\/])git(?:\.exe)?$/i;
+const WRAPPER_TOKEN = /^(?:\w+=\S*|command|sudo|env)$/i;
+
+function runsGit(segment) {
+  const tokens = [];
+  for (const match of segment.matchAll(ARGUMENT_PATTERN))
+    tokens.push(match[1] ?? match[2] ?? match[3]);
+  while (tokens.length > 0 && WRAPPER_TOKEN.test(tokens[0])) tokens.shift();
+  return tokens.length > 0 && GIT_BINARY_TOKEN.test(tokens[0]);
 }
 
-function commandTextFrom(toolInput) {
-  return String(toolInput.CommandLine ?? toolInput.command ?? '');
+function runsRealCommit(command) {
+  return String(command)
+    .split(SEGMENT_SEPARATOR)
+    .some((segment) => {
+      if (!runsGit(segment)) return false;
+      const normalized = normalizeGitCommand(segment);
+      return isGitCommit(normalized) && !isDryRunCommit(normalized);
+    });
 }
 
-/** The staged files added/copied/modified (not deleted), with an extension in scope. */
-function stagedFilesToLint(cwd, lintExtensions) {
-  const result = spawnSync(
-    'git',
-    ['diff', '--cached', '--name-only', '--diff-filter=ACM'],
-    { 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)
-    .filter((file) => lintExtensions.includes(extname(file).toLowerCase()));
+// ── Lint ────────────────────────────────────────────────────────────────────────────
+function normalizeExtension(extension) {
+  const text = String(extension).trim().toLowerCase();
+  return text.startsWith('.') ? text : `.${text}`;
 }
 
-/** The lint command to run, or null when none can be determined (never invented). */
-function resolveLintCommand(cwd, lintCommandOverride) {
-  if (lintCommandOverride) return lintCommandOverride;
-  const hasEslint = ESLINT_CONFIG_FILES.some((name) =>
-    existsSync(join(cwd, name)),
+function resolveLintCommand(root, lintCommandOverride) {
+  if (typeof lintCommandOverride === 'string' && lintCommandOverride.trim())
+    return lintCommandOverride;
+  const hasEslintFile = ESLINT_CONFIG_FILES.some((name) =>
+    existsSync(join(root, name)),
   );
-  return hasEslint ? 'npx eslint' : null;
+  const packageJson = readJsonOrNull(join(root, 'package.json'));
+  return hasEslintFile || packageJson?.eslintConfig ? 'npx eslint' : null;
 }
 
 function tailLines(text, count) {
-  const lines = String(text)
+  return String(text)
     .split(/\r?\n/)
-    .filter((line) => line.length > 0);
-  return lines.slice(-count).join('\n');
+    .filter((line) => line.length > 0)
+    .slice(-count)
+    .join('\n');
 }
 
-/** The lint command with the staged paths appended (quoted), so ONLY they are linted. */
-function lintCommandForFiles(lintCommand, files) {
+function runLintOverFiles(lintCommand, files, cwd, timeoutMs) {
   const quotedPaths = files.map((file) => `"${file}"`).join(' ');
-  return `${lintCommand} ${quotedPaths}`;
-}
-
-/** Runs the lint command over the staged files; returns the spawnSync result. */
-function runLintOverStaged(lintCommand, files, cwd, timeoutMs) {
-  return spawnSync(lintCommandForFiles(lintCommand, files), {
+  return spawnSync(`${lintCommand} ${quotedPaths}`, {
     cwd,
     shell: true,
     encoding: 'utf8',
@@ -129,25 +114,23 @@ function runLintOverStaged(lintCommand, files, cwd, timeoutMs) {
   });
 }
 
-/** Denies when the lint run could not spawn or reported failures; otherwise returns. */
 function denyIfLintFailed(result, lintCommand, escapeHatch) {
   if (result.error) {
     deny(
       CONFIG_KEY,
-      `Could not run the lint command ("${lintCommand}") over the staged files: ` +
-        `${result.error.message}. Fix the lint setup or set lintCommand/` +
+      `Could not run the lint command ("${lintCommand}") over the commit's files: ` +
+        `${result.error.message}. Fix the lint setup or set lintCommand under ` +
         `${CONFIG_KEY} in .ai/config.json.`,
     );
   }
   if (result.status !== 0) {
     const combinedOutput =
       `${result.stdout ?? ''}\n${result.stderr ?? ''}`.trim();
-    const outputTail = tailLines(combinedOutput, OUTPUT_TAIL_LINES);
     deny(
       CONFIG_KEY,
-      `The files you staged fail lint — commit blocked until your own changes are clean ` +
-        `(the rest of the repo is not checked). Fix them, or add "${escapeHatch}" to the ` +
-        `commit command for a deliberate exception:\n${outputTail}`,
+      `The files this commit carries fail lint — commit blocked until your own changes are ` +
+        `clean (the rest of the repo is not checked). Fix them, or add "${escapeHatch}" to ` +
+        `the commit command for a deliberate exception:\n${tailLines(combinedOutput, OUTPUT_TAIL_LINES)}`,
     );
   }
 }
@@ -164,24 +147,33 @@ runGate(
       escapeHatch: DEFAULT_ESCAPE_HATCH,
     },
   },
-  ({ toolName, toolInput, parameters }) => {
-    if (!toolInGroups(toolName, SHELL_GROUPS)) return;
+  ({ toolName, toolInput, parameters, cwd }) => {
+    if (!toolInGroups(toolName, ['shell'])) return;
 
-    const command = commandTextFrom(toolInput);
-    if (!isGitCommit(command)) return;
+    const command = shellCommandOf(toolInput);
+    if (!runsRealCommit(command)) return;
 
-    const escapeHatch = parameters.escapeHatch ?? DEFAULT_ESCAPE_HATCH;
+    const escapeHatch = String(parameters.escapeHatch ?? '');
     if (escapeHatch && command.includes(escapeHatch)) return;
 
-    const cwd = process.cwd();
-    const stagedFiles = stagedFilesToLint(cwd, parameters.lintExtensions);
-    if (stagedFiles.length === 0) return; // nothing you staged is in scope: nothing to enforce
+    const root = projectRootOf(cwd) ?? cwd;
+    const extensions = new Set(
+      parameters.lintExtensions.map(normalizeExtension),
+    );
+    const files = (effectiveCommitFiles(root, command) ?? []).filter((file) =>
+      extensions.has(extname(file).toLowerCase()),
+    );
+    if (files.length === 0) return;
 
-    const lintCommand = resolveLintCommand(cwd, parameters.lintCommand);
-    if (!lintCommand) return; // no linter declared/detected: never invent one
+    const lintCommand = resolveLintCommand(root, parameters.lintCommand);
+    if (!lintCommand) return;
 
-    const timeoutMs = parameters.lintTimeoutMs ?? DEFAULT_LINT_TIMEOUT_MS;
-    const result = runLintOverStaged(lintCommand, stagedFiles, cwd, timeoutMs);
+    const result = runLintOverFiles(
+      lintCommand,
+      files,
+      root,
+      parameters.lintTimeoutMs,
+    );
     denyIfLintFailed(result, lintCommand, escapeHatch);
   },
 );