@devrik-tools/claude-gates 0.1.2 → 0.2.0

package/plugins/gates/hooks/gates/circuit-breaker/test.mjs

@@ -1,143 +1,161 @@
-import assert from 'node:assert/strict';
-import { execFileSync } from 'node:child_process';
-import { randomUUID } from 'node:crypto';
-import { mkdtempSync, mkdirSync, rmSync, 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');
-const STATE_ROOT = join(tmpdir(), 'claude-gates', 'circuit-breaker');
-
-function runGate(payload, { config } = {}) {
-  const project = mkdtempSync(join(tmpdir(), 'circuit-breaker-'));
-  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, sessionId, extra = {}) {
-  return {
-    tool_name: 'Agent',
-    session_id: sessionId,
-    tool_input: { prompt, subagent_type: 'worker-senior', ...extra },
-  };
-}
-function isDeny(result) {
-  return result?.hookSpecificOutput?.permissionDecision === 'deny';
-}
-
-const ENABLED = {
-  config: { gates: { requireCircuitBreakerOnDelegation: true } },
-};
-
-function freshSession() {
-  return `test-${randomUUID()}`;
-}
-
-function cleanupSession(sessionId) {
-  try {
-    rmSync(join(STATE_ROOT, sessionId), { recursive: true, force: true });
-  } catch {
-    // best-effort cleanup
-  }
-}
-
-test('cuts the same delegation retried without substantial change', () => {
-  const sessionId = freshSession();
-  try {
-    const prompt = [
-      'Objetivo: fix the circuit breaker false positive in guard scoring.',
-      '',
-      'QUE SI: update lib/scoring.mjs to fix the Dice threshold.',
-    ].join('\n');
-
-    assert.equal(runGate(delegate(prompt, sessionId), ENABLED), null);
-    assert.equal(runGate(delegate(prompt, sessionId), ENABLED), null);
-    assert.ok(isDeny(runGate(delegate(prompt, sessionId), ENABLED)));
-  } finally {
-    cleanupSession(sessionId);
-  }
-});
-
-test('does not accumulate two genuinely different tasks to the same subagent', () => {
-  const sessionId = freshSession();
-  try {
-    const taskA =
-      'Objetivo: fix the login redirect bug.\n\nQUE SI: update src/auth/redirect.js.';
-    const taskB =
-      'Objetivo: migrate the billing schema to the new payments table.\n\nQUE SI: update db/migrations/billing.sql.';
-
-    assert.equal(runGate(delegate(taskA, sessionId), ENABLED), null);
-    assert.equal(runGate(delegate(taskB, sessionId), ENABLED), null);
-    assert.equal(runGate(delegate(taskA, sessionId), ENABLED), null);
-    assert.equal(runGate(delegate(taskB, sessionId), ENABLED), null);
-  } finally {
-    cleanupSession(sessionId);
-  }
-});
-
-test('the retry/force escape hatch allows and resets the counter', () => {
-  const sessionId = freshSession();
-  try {
-    const prompt =
-      'Objetivo: fix the flaky test in the payment suite.\n\nQUE SI: stabilize test/payment.spec.js.';
-
-    assert.equal(runGate(delegate(prompt, sessionId), ENABLED), null);
-    assert.equal(runGate(delegate(prompt, sessionId), ENABLED), null);
-    assert.equal(
-      runGate(delegate(`${prompt}\n\nforce it, retry.`, sessionId), ENABLED),
-      null,
-    );
-    // Counter was reset: the same prompt again should not deny immediately.
-    assert.equal(runGate(delegate(prompt, sessionId), ENABLED), null);
-  } finally {
-    cleanupSession(sessionId);
-  }
-});
-
-test('disabled by config: the gate does not run', () => {
-  const sessionId = freshSession();
-  try {
-    const prompt =
-      'Objetivo: fix the login redirect bug.\n\nQUE SI: update src/auth/redirect.js.';
-    const disabled = {
-      config: { gates: { requireCircuitBreakerOnDelegation: false } },
-    };
-    assert.equal(runGate(delegate(prompt, sessionId), disabled), null);
-    assert.equal(runGate(delegate(prompt, sessionId), disabled), null);
-    assert.equal(runGate(delegate(prompt, sessionId), disabled), null);
-    assert.equal(runGate(delegate(prompt, sessionId), disabled), null);
-  } finally {
-    cleanupSession(sessionId);
-  }
-});
-
-test('project retryThreshold override cuts sooner', () => {
-  const sessionId = freshSession();
-  try {
-    const config = {
-      gates: {
-        requireCircuitBreakerOnDelegation: { enabled: true, retryThreshold: 2 },
-      },
-    };
-    const prompt =
-      'Objetivo: fix the login redirect bug.\n\nQUE SI: update src/auth/redirect.js.';
-    assert.equal(runGate(delegate(prompt, sessionId), { config }), null);
-    assert.ok(isDeny(runGate(delegate(prompt, sessionId), { config })));
-  } finally {
-    cleanupSession(sessionId);
-  }
-});
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { mkdtempSync, mkdirSync, rmSync, 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');
+const STATE_ROOT = join(tmpdir(), 'claude-gates', 'circuit-breaker');
+
+function runGate(payload, { config } = {}) {
+  const project = mkdtempSync(join(tmpdir(), 'circuit-breaker-'));
+  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, sessionId, extra = {}) {
+  return {
+    tool_name: 'Agent',
+    session_id: sessionId,
+    tool_input: { prompt, subagent_type: 'worker-senior', ...extra },
+  };
+}
+function isDeny(result) {
+  return result?.hookSpecificOutput?.permissionDecision === 'deny';
+}
+
+const ENABLED = {
+  config: { gates: { requireCircuitBreakerOnDelegation: true } },
+};
+
+function freshSession() {
+  return `test-${randomUUID()}`;
+}
+
+function cleanupSession(sessionId) {
+  try {
+    rmSync(join(STATE_ROOT, sessionId), { recursive: true, force: true });
+  } catch {
+    // best-effort cleanup
+  }
+}
+
+test('cuts the same delegation retried without substantial change', () => {
+  const sessionId = freshSession();
+  try {
+    const prompt = [
+      'Objetivo: fix the circuit breaker false positive in guard scoring.',
+      '',
+      'QUE SI: update lib/scoring.mjs to fix the Dice threshold.',
+    ].join('\n');
+
+    assert.equal(runGate(delegate(prompt, sessionId), ENABLED), null);
+    assert.equal(runGate(delegate(prompt, sessionId), ENABLED), null);
+    assert.ok(isDeny(runGate(delegate(prompt, sessionId), ENABLED)));
+  } finally {
+    cleanupSession(sessionId);
+  }
+});
+
+test('does not accumulate two genuinely different tasks to the same subagent', () => {
+  const sessionId = freshSession();
+  try {
+    const taskA =
+      'Objetivo: fix the login redirect bug.\n\nQUE SI: update src/auth/redirect.js.';
+    const taskB =
+      'Objetivo: migrate the billing schema to the new payments table.\n\nQUE SI: update db/migrations/billing.sql.';
+
+    assert.equal(runGate(delegate(taskA, sessionId), ENABLED), null);
+    assert.equal(runGate(delegate(taskB, sessionId), ENABLED), null);
+    assert.equal(runGate(delegate(taskA, sessionId), ENABLED), null);
+    assert.equal(runGate(delegate(taskB, sessionId), ENABLED), null);
+  } finally {
+    cleanupSession(sessionId);
+  }
+});
+
+test('the retry/force escape hatch allows and resets the counter', () => {
+  const sessionId = freshSession();
+  try {
+    const prompt =
+      'Objetivo: fix the flaky test in the payment suite.\n\nQUE SI: stabilize test/payment.spec.js.';
+
+    assert.equal(runGate(delegate(prompt, sessionId), ENABLED), null);
+    assert.equal(runGate(delegate(prompt, sessionId), ENABLED), null);
+    assert.equal(
+      runGate(delegate(`${prompt}\n\nforce it, retry.`, sessionId), ENABLED),
+      null,
+    );
+    // Counter was reset: the same prompt again should not deny immediately.
+    assert.equal(runGate(delegate(prompt, sessionId), ENABLED), null);
+  } finally {
+    cleanupSession(sessionId);
+  }
+});
+
+test('bilingual control: the Spanish override imperative resets the counter exactly like its English equivalent', () => {
+  const sessionId = freshSession();
+  try {
+    const prompt =
+      'Objetivo: fix the flaky test in the payment suite.\n\nQUE SI: stabilize test/payment.spec.js.';
+
+    assert.equal(runGate(delegate(prompt, sessionId), ENABLED), null);
+    assert.equal(runGate(delegate(prompt, sessionId), ENABLED), null);
+    assert.equal(
+      runGate(delegate(`${prompt}\n\nreintentalo, forzalo.`, sessionId), ENABLED),
+      null,
+    );
+    assert.equal(runGate(delegate(prompt, sessionId), ENABLED), null);
+  } finally {
+    cleanupSession(sessionId);
+  }
+});
+
+test('disabled by config: the gate does not run', () => {
+  const sessionId = freshSession();
+  try {
+    const prompt =
+      'Objetivo: fix the login redirect bug.\n\nQUE SI: update src/auth/redirect.js.';
+    const disabled = {
+      config: { gates: { requireCircuitBreakerOnDelegation: false } },
+    };
+    assert.equal(runGate(delegate(prompt, sessionId), disabled), null);
+    assert.equal(runGate(delegate(prompt, sessionId), disabled), null);
+    assert.equal(runGate(delegate(prompt, sessionId), disabled), null);
+    assert.equal(runGate(delegate(prompt, sessionId), disabled), null);
+  } finally {
+    cleanupSession(sessionId);
+  }
+});
+
+test('project retryThreshold override cuts sooner', () => {
+  const sessionId = freshSession();
+  try {
+    const config = {
+      gates: {
+        requireCircuitBreakerOnDelegation: { enabled: true, retryThreshold: 2 },
+      },
+    };
+    const prompt =
+      'Objetivo: fix the login redirect bug.\n\nQUE SI: update src/auth/redirect.js.';
+    assert.equal(runGate(delegate(prompt, sessionId), { config }), null);
+    assert.ok(isDeny(runGate(delegate(prompt, sessionId), { config })));
+  } finally {
+    cleanupSession(sessionId);
+  }
+});

package/plugins/gates/hooks/gates/dependency-skills/dependency-skills.edge.test.mjs

@@ -0,0 +1,69 @@
+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, skills } = {}) {
+  const project = mkdtempSync(join(tmpdir(), 'dependency-skills-edge-'));
+  mkdirSync(join(project, '.git'));
+  if (config) {
+    mkdirSync(join(project, '.ai'));
+    writeFileSync(join(project, '.ai', 'config.json'), JSON.stringify(config));
+  }
+  if (skills) {
+    for (const name of skills) {
+      mkdirSync(join(project, '.claude', 'skills', name), { recursive: true });
+    }
+  }
+  const out = execFileSync(process.execPath, [GATE], {
+    input: JSON.stringify(payload),
+    encoding: 'utf8',
+    cwd: project,
+    env: { ...process.env, HOME: project, USERPROFILE: project },
+  });
+  return out.trim() ? JSON.parse(out.trim()) : null;
+}
+
+function isWarn(result) {
+  return result?.hookSpecificOutput?.additionalContext !== undefined;
+}
+
+// FIXED: skillNameMatches no longer does bidirectional substring matching. A skill dir must
+// EQUAL the dependency or contain it as a whole `-`-segment, so an unrelated short name like
+// "rip" no longer satisfies "stripe" — the gate now correctly warns (no false exemption).
+test('FIXED: an unrelated skill directory name that is a substring of the dependency no longer satisfies the check', () => {
+  const package_ = JSON.stringify({ dependencies: { stripe: '1.0.0' } });
+  const result = runGate(writePackageJson(package_), { skills: ['rip'] });
+  assert.ok(isWarn(result), 'unrelated skill dir "rip" must NOT satisfy dependency "stripe"; the gate warns');
+
+  function writePackageJson(content) {
+    return { tool_name: 'Write', tool_input: { file_path: '/repo/package.json', content } };
+  }
+});
+
+test('OK: a genuinely matching skill segment still exempts (stripe-payments covers stripe)', () => {
+  const package_ = JSON.stringify({ dependencies: { stripe: '1.0.0' } });
+  const result = runGate(writePackageJson(package_), { skills: ['stripe-payments'] });
+  assert.equal(result, null, 'a skill whose name contains the dependency as a segment still covers it');
+
+  function writePackageJson(content) {
+    return { tool_name: 'Write', tool_input: { file_path: '/repo/package.json', content } };
+  }
+});
+
+// FIXED: content is now read through writtenContentOf, which covers write_to_file's `text`
+// field (and every other native/MCP shape). An unreviewed new dependency written via an MCP
+// write tool is no longer silently skipped.
+test('FIXED: write_to_file with a different content field name is now checked', () => {
+  const package_ = JSON.stringify({ dependencies: { stripe: '1.0.0' } });
+  const result = runGate({
+    tool_name: 'write_to_file',
+    tool_input: { file_path: '/repo/package.json', text: package_ },
+  });
+  assert.ok(isWarn(result), 'the new dependency written via write_to_file (text field) must now be caught');
+});

package/plugins/gates/hooks/gates/dependency-skills/index.mjs

@@ -1,118 +1,126 @@
-import { readdirSync } from 'node:fs';
-import { join } from 'node:path';
-import { runGate, warn, TOOL_GROUPS } from '../../lib/hook-io.mjs';
-
-const GATE_ID = 'dependency-skills';
-const CONFIG_KEY = 'requireSkillForNewDependency';
-
-const DEFAULT_DEPS_WITHOUT_OWN_API = [
-  'clsx',
-  'classnames',
-  'lodash.debounce',
-  'lodash.throttle',
-  'lodash.merge',
-  'tslib',
-  'core-js',
-  'regenerator-runtime',
-];
-
-function normalize(name) {
-  return name.replace(/^@/, '').replace(/\//g, '-').toLowerCase();
-}
-
-function isExempt(dependencyName, dependenciesWithoutOwnApi) {
-  if (dependencyName.startsWith('@types/')) return true;
-  return dependenciesWithoutOwnApi.includes(dependencyName);
-}
-
-function listSkillDirectories(skillsDirectoryPath) {
-  try {
-    return readdirSync(skillsDirectoryPath, { withFileTypes: true })
-      .filter((entry) => entry.isDirectory())
-      .map((entry) => entry.name);
-  } catch {
-    // No skills directory in this project — nothing to cross-check against.
-    return [];
-  }
-}
-
-function skillNameMatches(normalizedDependency, skillDirectoryName) {
-  const normalizedSkill = normalize(skillDirectoryName);
-  return (
-    normalizedDependency.includes(normalizedSkill) ||
-    normalizedSkill.includes(normalizedDependency)
-  );
-}
-
-function hasMatchingSkill(dependencyName, skillDirectories) {
-  const normalizedDependency = normalize(dependencyName);
-  return skillDirectories.some((skillDirectoryName) =>
-    skillNameMatches(normalizedDependency, skillDirectoryName),
-  );
-}
-
-function needsSkillReview(dependencyName, parameters, skillDirectories) {
-  if (isExempt(dependencyName, parameters.depsWithoutOwnApi)) return false;
-  return !hasMatchingSkill(dependencyName, skillDirectories);
-}
-
-/** Parsed `package.json` dependency names, or null when it cannot be read yet. */
-function dependencyNamesIn(content) {
-  let parsed;
-  try {
-    parsed = JSON.parse(content);
-  } catch {
-    // Mid-edit or partially written package.json — nothing reliable to check yet.
-    return null;
-  }
-  const dependencies = {
-    ...(parsed.dependencies ?? {}),
-    ...(parsed.devDependencies ?? {}),
-  };
-  return Object.keys(dependencies);
-}
-
-runGate(
-  {
-    id: GATE_ID,
-    configKey: CONFIG_KEY,
-    enabledByDefault: true,
-    defaultParams: {
-      depsWithoutOwnApi: DEFAULT_DEPS_WITHOUT_OWN_API,
-      projectSkillsDir: '.claude/skills',
-    },
-  },
-  ({ toolName, toolInput, parameters }) => {
-    if (!TOOL_GROUPS.write.includes(toolName)) return;
-
-    const filePath = toolInput?.file_path ?? '';
-    if (!filePath.replace(/\\/g, '/').endsWith('package.json')) return;
-
-    const content = toolInput?.content ?? toolInput?.new_string;
-    if (typeof content !== 'string') return;
-
-    const dependencyNames = dependencyNamesIn(content);
-    if (!dependencyNames || dependencyNames.length === 0) return;
-
-    const skillDirectories = listSkillDirectories(
-      join(process.cwd(), parameters.projectSkillsDir),
-    );
-
-    const unmatched = dependencyNames.filter((name) =>
-      needsSkillReview(name, parameters, skillDirectories),
-    );
-    if (unmatched.length === 0) return;
-
-    warn(
-      GATE_ID,
-      `New dependencies without a matching skill in ${parameters.projectSkillsDir}: ${unmatched.join(', ')}. Consider adding a skill documenting how to use them, or add them to depsWithoutOwnApi if they need none.`,
-    );
-  },
-);
-
-// Deliberately simplified vs. the source guard (guard-dependencies-skills.mjs):
-// dropped the hardcoded alias table (stripe -> stripe-payments, etc.) and the
-// .ai/skills-baseline.json freeze mechanism — that belongs to a separate
-// adopt-stack-and-skills.mjs script that does not exist in this repo. This
-// gate only does simple substring matching between dependency name and skill
-// directory name, both normalized.
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  runGate,
+  warn,
+  toolInGroups,
+  writtenPathOf,
+  writtenContentOf,
+} from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'dependency-skills';
+const CONFIG_KEY = 'requireSkillForNewDependency';
+
+const DEFAULT_DEPS_WITHOUT_OWN_API = [
+  'clsx',
+  'classnames',
+  'lodash.debounce',
+  'lodash.throttle',
+  'lodash.merge',
+  'tslib',
+  'core-js',
+  'regenerator-runtime',
+];
+
+function normalize(name) {
+  return name.replace(/^@/, '').replace(/\//g, '-').toLowerCase();
+}
+
+function isExempt(dependencyName, dependenciesWithoutOwnApi) {
+  if (dependencyName.startsWith('@types/')) return true;
+  return dependenciesWithoutOwnApi.includes(dependencyName);
+}
+
+function listSkillDirectories(skillsDirectoryPath) {
+  try {
+    return readdirSync(skillsDirectoryPath, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name);
+  } catch {
+    // No skills directory in this project — nothing to cross-check against.
+    return [];
+  }
+}
+
+// A skill covers a dependency when its normalized name equals the dependency's, or contains
+// it as a whole `-`-segment (a `stripe-payments` skill covers `stripe`). The old check was
+// bidirectional substring, so a skill dir `rip` "matched" `stripe` (rip ⊂ st-rip-e) — a false
+// exemption that silenced the warning for an unreviewed dependency.
+function skillNameMatches(normalizedDependency, skillDirectoryName) {
+  const normalizedSkill = normalize(skillDirectoryName);
+  if (normalizedSkill === normalizedDependency) return true;
+  return normalizedSkill.split('-').includes(normalizedDependency);
+}
+
+function hasMatchingSkill(dependencyName, skillDirectories) {
+  const normalizedDependency = normalize(dependencyName);
+  return skillDirectories.some((skillDirectoryName) =>
+    skillNameMatches(normalizedDependency, skillDirectoryName),
+  );
+}
+
+function needsSkillReview(dependencyName, parameters, skillDirectories) {
+  if (isExempt(dependencyName, parameters.depsWithoutOwnApi)) return false;
+  return !hasMatchingSkill(dependencyName, skillDirectories);
+}
+
+/** Parsed `package.json` dependency names, or null when it cannot be read yet. */
+function dependencyNamesIn(content) {
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    // Mid-edit or partially written package.json — nothing reliable to check yet.
+    return null;
+  }
+  const dependencies = {
+    ...(parsed.dependencies ?? {}),
+    ...(parsed.devDependencies ?? {}),
+  };
+  return Object.keys(dependencies);
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: {
+      depsWithoutOwnApi: DEFAULT_DEPS_WITHOUT_OWN_API,
+      projectSkillsDir: '.claude/skills',
+    },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    if (!toolInGroups(toolName, ['write'])) return;
+
+    const filePath = writtenPathOf(toolInput);
+    if (!filePath.replace(/\\/g, '/').endsWith('package.json')) return;
+
+    const content = writtenContentOf(toolInput);
+    if (!content) return;
+
+    const dependencyNames = dependencyNamesIn(content);
+    if (!dependencyNames || dependencyNames.length === 0) return;
+
+    const skillDirectories = listSkillDirectories(
+      join(process.cwd(), parameters.projectSkillsDir),
+    );
+
+    const unmatched = dependencyNames.filter((name) =>
+      needsSkillReview(name, parameters, skillDirectories),
+    );
+    if (unmatched.length === 0) return;
+
+    warn(
+      GATE_ID,
+      `New dependencies without a matching skill in ${parameters.projectSkillsDir}: ${unmatched.join(', ')}. Consider adding a skill documenting how to use them, or add them to depsWithoutOwnApi if they need none.`,
+    );
+  },
+);
+
+// Deliberately simplified vs. the source guard (guard-dependencies-skills.mjs):
+// dropped the hardcoded alias table (stripe -> stripe-payments, etc.) and the
+// .ai/skills-baseline.json freeze mechanism — that belongs to a separate
+// adopt-stack-and-skills.mjs script that does not exist in this repo. This
+// gate only does simple substring matching between dependency name and skill
+// directory name, both normalized.