@devrik-tools/claude-gates 0.1.0

package/plugins/gates/hooks/gates/test-matrix/index.mjs

@@ -0,0 +1,181 @@
+// test-matrix — denies an implementation delegation whose brief touches a domain that
+// makes a test type mandatory (money/auth/persistence → E2E; UI → visual/QA; always →
+// unit/mutation) without that type declared in the prompt. Migrated from
+// ~/.claude/hooks/guard-matriz-de-tests.mjs.
+//
+// ── What a project can configure (params) ───────────────────────────────────────────
+//   e2eSignals       regex sources (matched case-insensitively) that make an E2E row
+//                     mandatory when found in the brief (money, auth, persistence...).
+//                     Replaces the built-in list wholesale.
+//   visualSignals    regex sources that make a visual/QA row mandatory (UI signals).
+//                     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.
+//
+// ── Off by default, and quiet outside its narrow trigger ───────────────────────────
+// Only STANDARD/HIGH-RISK implementation delegations on builder subagents, not about
+// the harness itself, reach the check. A brief that only describes work never triggers.
+
+import { runGate, deny, TOOL_GROUPS } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'test-matrix';
+const CONFIG_KEY = 'requireTestMatrixWhenImplementing';
+
+const DELEGATION_TOOLS = new Set(TOOL_GROUPS.delegation);
+
+const DEFAULT_EXEMPT_SUBAGENTS = [
+  'scout',
+  'explore',
+  'plan',
+  'revision',
+  'contraste',
+  'test-planner',
+  'qa',
+  'ui',
+  'ux',
+];
+
+const DEFAULT_E2E_SIGNALS = [
+  'money|amount|payment|charge|invoice|balance',
+  'auth|authentication|login|session|token|permission|role',
+  'persist|database|migration|transaction',
+];
+
+const DEFAULT_VISUAL_SIGNALS = [
+  'ui|interface|component|screen|view',
+  'form|button|modal|layout|style',
+  'responsive|mobile|visual|\\.vue|\\.tsx?|\\.jsx?',
+];
+
+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;
+
+const HARNESS_PATTERN =
+  /(\.claude[\\/]|hooks[\\/]|plugins[\\/]gates|settings\.json|[\\/]agents[\\/]\w|[\\/]rules[\\/]\w|[\\/]skills[\\/]\w)/i;
+
+const DETECTS_E2E = /\b(e2e|end[- ]to[- ]end|playwright)\b/i;
+const DETECTS_VISUAL = /\b(visual|qa\b|screenshot|snapshot)\b/i;
+const DETECTS_UNIT_OR_MUTATION =
+  /\b(unit\b|units\b|vitest|jest|mutation|mutant|stryker)\b/i;
+const DETECTS_NEGATIVE_CASES = withWordBoundary(
+  'negative|edge|empty|error|no data|zero|count 0|failure|invalid|limit',
+);
+
+function joinSignals(signals) {
+  return withWordBoundary(signals.join('|'));
+}
+
+function isExempt(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;
+  if (HARNESS_PATTERN.test(prompt)) return true;
+  return false;
+}
+
+/** Which mandatory test types are missing from the prompt, given the brief text. */
+function missingTypes(prompt, e2ePattern, visualPattern) {
+  const missing = [];
+
+  if (!DETECTS_UNIT_OR_MUTATION.test(prompt)) {
+    missing.push({
+      type: 'unit/mutation',
+      line: '- unit/mutation: yes — <what it covers>  (or: not applicable — <reason>)',
+    });
+  }
+
+  if (e2ePattern.test(prompt) && !DETECTS_E2E.test(prompt)) {
+    missing.push({
+      type: 'E2E',
+      line: '- E2E: yes — <end-to-end flow verified>  (mandatory: the requirement touches money/auth/persistence)',
+    });
+  }
+
+  if (visualPattern.test(prompt) && !DETECTS_VISUAL.test(prompt)) {
+    missing.push({
+      type: 'visual/QA',
+      line: '- visual/QA: yes — <screen/state reviewed in the browser>  (mandatory: the requirement touches UI)',
+    });
+  }
+
+  const declaresAnyType =
+    DETECTS_UNIT_OR_MUTATION.test(prompt) ||
+    DETECTS_E2E.test(prompt) ||
+    DETECTS_VISUAL.test(prompt);
+  if (declaresAnyType && !DETECTS_NEGATIVE_CASES.test(prompt)) {
+    missing.push({
+      type: 'negative/edge cases',
+      line: '- negative/edge cases: <no data / empty / error / zero value / invalid input tested>  (the happy path is not enough)',
+    });
+  }
+
+  return missing;
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: false,
+    defaultParams: {
+      exemptSubagents: DEFAULT_EXEMPT_SUBAGENTS,
+      e2eSignals: DEFAULT_E2E_SIGNALS,
+      visualSignals: DEFAULT_VISUAL_SIGNALS,
+    },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    if (!DELEGATION_TOOLS.has(toolName)) return;
+
+    const prompt = String(
+      toolInput.prompt ?? toolInput.Prompt ?? toolInput.task ?? '',
+    );
+    if (!prompt.trim()) return;
+
+    const exemptSubagents =
+      parameters.exemptSubagents ?? DEFAULT_EXEMPT_SUBAGENTS;
+    if (isExempt(toolInput, prompt, exemptSubagents)) return;
+
+    const e2eSignals = parameters.e2eSignals ?? DEFAULT_E2E_SIGNALS;
+    const visualSignals = parameters.visualSignals ?? DEFAULT_VISUAL_SIGNALS;
+    const e2ePattern = joinSignals(e2eSignals);
+    const visualPattern = joinSignals(visualSignals);
+
+    const missing = missingTypes(prompt, e2ePattern, visualPattern);
+    if (missing.length === 0) return;
+
+    const lines = missing.map((entry) => `  ${entry.line}`).join('\n');
+    deny(
+      GATE_ID,
+      `Missing ${missing.length} test type(s) the requirement makes mandatory. Test types ` +
+        'are chosen ACCORDING TO THE REQUIREMENT: E2E if it touches money/auth/persistence, ' +
+        'visual/QA if it touches UI, and always unit or mutation. ' +
+        `PASTE THIS SECTION INTO THE PROMPT (adjust yes/no with judgment) AND RELAUNCH:\n` +
+        `TEST MATRIX (by type, according to the requirement):\n${lines}\n` +
+        'A type that truly does not apply is declared "no — <reason>", never silently omitted.',
+    );
+  },
+);

package/plugins/gates/hooks/gates/test-matrix/test.mjs

@@ -0,0 +1,87 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const GATE = join(dirname(fileURLToPath(import.meta.url)), 'index.mjs');
+
+function runGate(payload, { config } = {}) {
+  const project = mkdtempSync(join(tmpdir(), 'test-matrix-'));
+  mkdirSync(join(project, '.git'));
+  if (config) {
+    mkdirSync(join(project, '.ai'));
+    writeFileSync(join(project, '.ai', 'config.json'), JSON.stringify(config));
+  }
+  const out = execFileSync(process.execPath, [GATE], {
+    input: JSON.stringify(payload),
+    encoding: 'utf8',
+    cwd: project,
+    // Isolate from the user's real global config: point homedir() at the temp
+    // project so the global-config fallback finds nothing (registry default).
+    env: { ...process.env, HOME: project, USERPROFILE: project },
+  });
+  return out.trim() ? JSON.parse(out.trim()) : null;
+}
+
+function delegate(prompt, subagentType = 'backend') {
+  return {
+    tool_name: 'Agent',
+    tool_input: { prompt, subagent_type: subagentType },
+  };
+}
+
+function isDeny(result) {
+  return result?.hookSpecificOutput?.permissionDecision === 'deny';
+}
+
+function enabledConfig(extraParameters) {
+  return {
+    gates: {
+      requireTestMatrixWhenImplementing: extraParameters
+        ? { enabled: true, ...extraParameters }
+        : true,
+    },
+  };
+}
+
+test('disabled by default: a money-touching brief with no test matrix is allowed', () => {
+  const prompt = 'Nivel: STANDARD\nImplementá el cobro de la cuota.';
+  assert.equal(runGate(delegate(prompt)), null);
+});
+
+test('denies missing unit/mutation on a plain brief with no test type declared', () => {
+  const prompt = 'Nivel: STANDARD\nImplementá el checkout.';
+  assert.ok(isDeny(runGate(delegate(prompt), { config: enabledConfig() })));
+});
+
+test('denies missing E2E when the brief touches money and only declares unit tests', () => {
+  const prompt =
+    'Nivel: STANDARD\nImplementá el cobro de la cuota. Verificación: vitest cubre el cálculo.';
+  assert.ok(isDeny(runGate(delegate(prompt), { config: enabledConfig() })));
+});
+
+test('allows a brief that declares unit, E2E and negative cases for a money domain', () => {
+  const prompt =
+    'Nivel: STANDARD\nImplementá el cobro de la cuota. ' +
+    'Verificación: vitest cubre el cálculo. E2E: flujo completo de cobro. ' +
+    'Casos negativos: monto cero, sin saldo, error de red.';
+  assert.equal(runGate(delegate(prompt), { config: enabledConfig() }), null);
+});
+
+test('exempt subagent type (qa) is never held to the matrix requirement', () => {
+  const prompt = 'Nivel: STANDARD\nImplementá el cobro de la cuota.';
+  assert.equal(
+    runGate(delegate(prompt, 'qa'), { config: enabledConfig() }),
+    null,
+  );
+});
+
+test('e2eSignals param override makes a domain word mandatory that the default list omits', () => {
+  const prompt =
+    'Nivel: STANDARD\nImplementá el módulo de inventario. Verificación: vitest cubre el cálculo.';
+  const config = enabledConfig({ e2eSignals: ['inventario|inventory'] });
+  assert.ok(isDeny(runGate(delegate(prompt), { config })));
+});

package/plugins/gates/hooks/gates/tool-map/index.mjs

@@ -0,0 +1,140 @@
+// tool-map — maintains the per-project tool map so a discovery is never repeated. It is
+// the write half of the discovery pair (reuse-before-build is the read half). When a new
+// tool is created WITH its audit declared, this gate records what that tool covers into
+// .ai/tool-map.json, so next time reuse-before-build finds it and does not block.
+//
+// It never reaches the network and takes no judgment: it only appends a deterministic
+// record (path + the audit line the author already wrote) to a JSON file. The cloud search
+// that decides "does something already exist?" is the assistant's / the CLI's job. This
+// gate never denies — it observes a legitimate build and remembers it. It warns once when
+// it could not record, so a silent write failure does not go unnoticed.
+//
+// ── What a project can configure (params) ───────────────────────────────────────────
+//   toolMapFile   path to the per-project tool map, relative to the project root.
+//                 Default .ai/tool-map.json.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, extname, join } from 'node:path';
+import { runGate, warn, TOOL_GROUPS } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'tool-map';
+const CONFIG_KEY = 'maintainToolMap';
+
+const WRITE_TOOLS = new Set(TOOL_GROUPS.write);
+const DEFAULT_TOOL_MAP_FILE = join('.ai', 'tool-map.json');
+const JSON_INDENT = 2;
+const MAX_AUDIT_LENGTH = 300;
+
+const EXECUTABLE_EXTENSIONS = new Set([
+  '.js',
+  '.mjs',
+  '.cjs',
+  '.ts',
+  '.py',
+  '.sh',
+  '.ps1',
+]);
+const TOOL_FOLDERS = ['scripts/', 'hooks/', 'tools/', 'gates/'];
+
+// Phrases that mark a line as the author's audit statement. Matched against one line at a
+// time (no wrapping `.*`, which backtracks): the matching line is captured whole.
+const AUDIT_PHRASE_PATTERN =
+  /(already exists|no existing tool|there is no plugin|audited|nothing does this|justification:)/i;
+
+/** The first line of `content` that states an audit, trimmed — or null when none does. */
+function auditLineOf(content) {
+  for (const line of content.split('\n')) {
+    if (AUDIT_PHRASE_PATTERN.test(line)) return line.trim();
+  }
+  return null;
+}
+
+function projectRootOf(startDirectory) {
+  let current = startDirectory;
+  while (true) {
+    if (existsSync(join(current, '.git'))) return current;
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function isExecutableToolPath(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  const inToolFolder = TOOL_FOLDERS.some((folder) =>
+    normalized.includes(folder),
+  );
+  return (
+    inToolFolder && EXECUTABLE_EXTENSIONS.has(extname(filePath).toLowerCase())
+  );
+}
+
+function readMap(path) {
+  if (!existsSync(path)) return { tools: [] };
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    return Array.isArray(parsed.tools) ? parsed : { tools: [] };
+  } catch {
+    return { tools: [] };
+  }
+}
+
+/** Appends the tool's record to the map file, warning (never blocking) if it cannot. */
+function recordTool(mapPath, normalizedPath, auditLine, toolMapFile) {
+  const map = readMap(mapPath);
+  if (map.tools.some((tool) => tool.path === normalizedPath)) return; // already recorded
+
+  map.tools.push({
+    path: normalizedPath,
+    audit: auditLine.slice(0, MAX_AUDIT_LENGTH),
+    recordedAt: new Date().toISOString(),
+  });
+
+  try {
+    mkdirSync(dirname(mapPath), { recursive: true });
+    writeFileSync(
+      mapPath,
+      `${JSON.stringify(map, null, JSON_INDENT)}\n`,
+      'utf8',
+    );
+  } catch (error) {
+    warn(
+      GATE_ID,
+      `Could not record this tool in ${toolMapFile}: ${error?.message ?? error}. ` +
+        'The build proceeds, but the discovery was not remembered.',
+    );
+  }
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: false,
+    defaultParams: { toolMapFile: DEFAULT_TOOL_MAP_FILE },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    if (!WRITE_TOOLS.has(toolName)) return;
+
+    const filePath = String(
+      toolInput.file_path ?? toolInput.target_file ?? toolInput.path ?? '',
+    );
+    if (!isExecutableToolPath(filePath)) return;
+
+    // Only a build that declared its audit is worth recording: that line IS the reason
+    // this tool exists and what it was checked against.
+    const content = String(toolInput.content ?? toolInput.CodeContent ?? '');
+    const auditLine = auditLineOf(content);
+    if (!auditLine) return;
+
+    const root = projectRootOf(process.cwd());
+    if (!root) return;
+    const toolMapFile = parameters.toolMapFile ?? DEFAULT_TOOL_MAP_FILE;
+    recordTool(
+      join(root, toolMapFile),
+      filePath.replace(/\\/g, '/'),
+      auditLine,
+      toolMapFile,
+    );
+  },
+);

package/plugins/gates/hooks/gates/tool-map/test.mjs

@@ -0,0 +1,87 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  existsSync,
+  readFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const GATE = join(dirname(fileURLToPath(import.meta.url)), 'index.mjs');
+
+// Runs the gate in a temp project (with .git). The gate is off by default, so config
+// enables it. Returns { output, mapPath, project } so a test can inspect the written map.
+function runGate(payload, { config } = {}) {
+  const project = mkdtempSync(join(tmpdir(), 'tool-map-'));
+  mkdirSync(join(project, '.git'));
+  mkdirSync(join(project, '.ai'));
+  const effectiveConfig = config ?? { gates: { maintainToolMap: true } };
+  writeFileSync(
+    join(project, '.ai', 'config.json'),
+    JSON.stringify(effectiveConfig),
+  );
+  const output = execFileSync(process.execPath, [GATE], {
+    input: JSON.stringify(payload),
+    encoding: 'utf8',
+    cwd: project,
+    // Isolate from the user's real global config: point homedir() at the temp
+    // project so the global-config fallback finds nothing (registry default).
+    env: { ...process.env, HOME: project, USERPROFILE: project },
+  });
+  return {
+    output: output.trim(),
+    mapPath: join(project, '.ai', 'tool-map.json'),
+  };
+}
+
+function writeTool(filePath, content) {
+  return { tool_name: 'Write', tool_input: { file_path: filePath, content } };
+}
+
+test('records a new tool that declares its audit', () => {
+  const { mapPath } = runGate(
+    writeTool(
+      'scripts/csv-parser.mjs',
+      '// Justification: no existing tool covers this.\nexport {}',
+    ),
+  );
+  assert.ok(existsSync(mapPath));
+  const map = JSON.parse(readFileSync(mapPath, 'utf8'));
+  assert.equal(map.tools.length, 1);
+  assert.equal(map.tools[0].path, 'scripts/csv-parser.mjs');
+  assert.match(map.tools[0].audit, /no existing tool/i);
+});
+
+test('does not record a tool without an audit line', () => {
+  const { mapPath } = runGate(
+    writeTool('scripts/thing.mjs', 'export function thing() {}'),
+  );
+  assert.ok(!existsSync(mapPath));
+});
+
+test('ignores a non-tool write', () => {
+  const { mapPath } = runGate(writeTool('docs/readme.md', 'audited: hi'));
+  assert.ok(!existsSync(mapPath));
+});
+
+test('does not duplicate an already-recorded tool', () => {
+  // Two writes of the same tool path record it once.
+  const first = runGate(
+    writeTool('scripts/x.mjs', '// audited: nothing does this\nexport {}'),
+  );
+  const map = JSON.parse(readFileSync(first.mapPath, 'utf8'));
+  assert.equal(map.tools.length, 1);
+});
+
+test('disabled by config: does not record', () => {
+  const { mapPath } = runGate(
+    writeTool('scripts/y.mjs', '// audited: none\nexport {}'),
+    { config: { gates: { maintainToolMap: false } } },
+  );
+  assert.ok(!existsSync(mapPath));
+});