@devrik-tools/claude-gates 0.1.0

package/plugins/gates/hooks/gates/intent-flow/test.mjs

@@ -0,0 +1,136 @@
+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(), 'intent-flow-'));
+  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, extra = {}) {
+  return { tool_name: 'Agent', tool_input: { prompt, ...extra } };
+}
+function isDeny(result) {
+  return result?.hookSpecificOutput?.permissionDecision === 'deny';
+}
+
+const ENABLED = {
+  config: { gates: { requireScopeListBeforeDelegating: true } },
+};
+
+test('denies implementing a payment change with real intent and no scope list', () => {
+  const result = runGate(
+    delegate(
+      'Implementa el cobro del pago con la nueva pasarela de dinero para el checkout.',
+    ),
+    ENABLED,
+  );
+  assert.ok(isDeny(result));
+});
+
+test('allows the same request once IN SCOPE / OUT OF SCOPE / EDGE CASES are declared', () => {
+  const prompt = [
+    'Implementa el cobro del pago con la nueva pasarela de dinero para el checkout.',
+    '',
+    'QUE SI (alcance): integrar el nuevo proveedor de pago en el checkout.',
+    'QUE NO (fuera de alcance): no tocar el flujo de reembolsos.',
+    'EDGE CASES: no aplican casos borde adicionales.',
+  ].join('\n');
+  assert.equal(runGate(delegate(prompt), ENABLED), null);
+});
+
+test('denies hard when a high-impact request declares an unresolved unknown', () => {
+  const prompt = [
+    'Implementa el cobro del pago con la nueva pasarela; todavia no esta claro que hacer con reembolsos parciales, unknown.',
+    'QUE SI: cobro basico. QUE NO: reembolsos. EDGE CASES: ninguno.',
+  ].join('\n');
+  assert.ok(isDeny(runGate(delegate(prompt), ENABLED)));
+});
+
+test('allows a request mentioning payment only as documentation topic', () => {
+  assert.equal(
+    runGate(
+      delegate(
+        'Crea un documento README.md que explique como funciona el pago y la autenticacion del sistema para el equipo nuevo.',
+      ),
+      ENABLED,
+    ),
+    null,
+  );
+});
+
+test('allows a normal implementation request with no high-impact signal', () => {
+  assert.equal(
+    runGate(
+      delegate(
+        'Arregla el boton que no cambia de color al pasar el mouse en la pagina de inicio.',
+      ),
+      ENABLED,
+    ),
+    null,
+  );
+});
+
+test('allows a read-only subagent', () => {
+  assert.equal(
+    runGate(
+      delegate(
+        'Implementa el cobro del pago con la nueva pasarela de dinero.',
+        {
+          subagent_type: 'plan',
+        },
+      ),
+      ENABLED,
+    ),
+    null,
+  );
+});
+
+test('disabled by config: the gate does not run', () => {
+  assert.equal(
+    runGate(
+      delegate('Implementa el cobro del pago con la nueva pasarela de dinero.'),
+      {
+        config: { gates: { requireScopeListBeforeDelegating: false } },
+      },
+    ),
+    null,
+  );
+});
+
+test('project highImpactPatterns override narrows what counts as high-impact', () => {
+  const config = {
+    gates: {
+      requireScopeListBeforeDelegating: {
+        enabled: true,
+        highImpactPatterns: ['pagin[ao]ci[oó]n'],
+      },
+    },
+  };
+  const prompt =
+    'Implementa el cobro del pago con la nueva pasarela de dinero.';
+  // With the default patterns (money/payment), this same prompt is denied.
+  assert.ok(isDeny(runGate(delegate(prompt), ENABLED)));
+  // No longer matches "dinero/pago" as high-impact once overridden, so no scope list
+  // is required and the gate allows.
+  assert.equal(runGate(delegate(prompt), { config }), null);
+});

package/plugins/gates/hooks/gates/mandatory-flow/index.mjs

@@ -0,0 +1,166 @@
+// mandatory-flow — denies an implementation delegation when there is no live task
+// pointer on disk backed by a contract file. Declaring pipeline stages in prose (what
+// implementation-pipeline.mjs checks) is not the same as a live task actually existing
+// on disk; this gate checks the disk fact, not the prompt's wording. Migrated from
+// ~/.claude/hooks/guard-flujo-obligatorio.mjs.
+//
+// ── What a project can configure (params) ───────────────────────────────────────────
+//   activePointerPath   path (relative to the project root) to the file naming the
+//                        active task/pipeline slug.
+//   exemptSubagents      subagent types exempt outright (read-only pipeline stages).
+//                        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 non-exempt subagents, not
+// about the harness itself, reach the disk check.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { runGate, deny, TOOL_GROUPS } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'mandatory-flow';
+const CONFIG_KEY = 'requireLiveTaskWhenImplementing';
+
+const DELEGATION_TOOLS = new Set(TOOL_GROUPS.delegation);
+
+const DEFAULT_ACTIVE_POINTER_PATH = join('.ai', 'pipeline', 'ACTIVA');
+
+const DEFAULT_EXEMPT_SUBAGENTS = [
+  'explore',
+  'plan',
+  'scout',
+  'revision',
+  'contraste',
+  'test-planner',
+  'qa',
+  'ui',
+  'ux',
+];
+
+/** Contract files that count as evidence a task's contract exists on disk. */
+const TASK_CONTRACT_FILES = [
+  'asserts.md',
+  'task.json',
+  'spec.md',
+  'requirements.md',
+  'acceptance.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;
+
+const HARNESS_PATTERN =
+  /(\.claude[\\/]|hooks[\\/]|plugins[\\/]gates|settings\.json|[\\/]agents[\\/]\w|[\\/]rules[\\/]\w|[\\/]skills[\\/]\w)/i;
+
+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;
+}
+
+function hasTaskContract(taskDirectory) {
+  return TASK_CONTRACT_FILES.some((file) => {
+    try {
+      return existsSync(join(taskDirectory, file));
+    } catch {
+      return false;
+    }
+  });
+}
+
+/** The pointer file's trimmed content, or '' when it cannot be read. */
+function readSlug(pointerPath) {
+  try {
+    return readFileSync(pointerPath, 'utf8').trim();
+  } catch {
+    return '';
+  }
+}
+
+/** Denies for whichever of the three live-task facts is missing, or does nothing. */
+function checkLiveTask(pointerPath) {
+  if (!existsSync(pointerPath)) {
+    deny(
+      GATE_ID,
+      `This delegation is going to implement, but there is no live task: ${pointerPath} ` +
+        'does not exist. Start a task pointing to it before delegating, or declare ' +
+        'LEVEL: QUESTION/MICRO if this is not implementation.',
+    );
+  }
+
+  const slug = readSlug(pointerPath);
+  if (!slug) {
+    deny(
+      GATE_ID,
+      `${pointerPath} exists but is empty. An active-task pointer with no slug is not ` +
+        'a live task. Write the task slug into it before delegating.',
+    );
+  }
+
+  const taskDirectory = join(process.cwd(), '.ai', 'pipeline', slug);
+  if (!hasTaskContract(taskDirectory)) {
+    deny(
+      GATE_ID,
+      `The active task '${slug}' has no contract on disk: none of ` +
+        `${TASK_CONTRACT_FILES.join(', ')} exists under ${taskDirectory}. ` +
+        'Write the contract before implementing.',
+    );
+  }
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: false,
+    defaultParams: {
+      activePointerPath: DEFAULT_ACTIVE_POINTER_PATH,
+      exemptSubagents: DEFAULT_EXEMPT_SUBAGENTS,
+    },
+  },
+  ({ 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 activePointerPath = String(
+      parameters.activePointerPath ?? DEFAULT_ACTIVE_POINTER_PATH,
+    );
+    checkLiveTask(join(process.cwd(), activePointerPath));
+  },
+);

package/plugins/gates/hooks/gates/mandatory-flow/test.mjs

@@ -0,0 +1,119 @@
+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 makeProject() {
+  const project = mkdtempSync(join(tmpdir(), 'mandatory-flow-'));
+  mkdirSync(join(project, '.git'));
+  return project;
+}
+
+function writeProjectConfig(project, config) {
+  mkdirSync(join(project, '.ai'), { recursive: true });
+  writeFileSync(join(project, '.ai', 'config.json'), JSON.stringify(config));
+}
+
+function runGate(project, payload) {
+  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 enableGate(project) {
+  writeProjectConfig(project, {
+    gates: { requireLiveTaskWhenImplementing: true },
+  });
+}
+
+test('disabled by default: no pointer file needed', () => {
+  const project = makeProject();
+  const prompt = 'Nivel: STANDARD\nImplementá el checkout.';
+  assert.equal(runGate(project, delegate(prompt)), null);
+});
+
+test('denies implementing when no active-task pointer exists on disk', () => {
+  const project = makeProject();
+  enableGate(project);
+  const prompt = 'Nivel: STANDARD\nImplementá el checkout.';
+  assert.ok(isDeny(runGate(project, delegate(prompt))));
+});
+
+test('allows implementing when the active task has a contract on disk', () => {
+  const project = makeProject();
+  enableGate(project);
+  mkdirSync(join(project, '.ai', 'pipeline', 'checkout-flow'), {
+    recursive: true,
+  });
+  writeFileSync(join(project, '.ai', 'pipeline', 'ACTIVA'), 'checkout-flow');
+  writeFileSync(
+    join(project, '.ai', 'pipeline', 'checkout-flow', 'asserts.md'),
+    '# Asserts\n\nCriterio: cobrar bien.',
+  );
+  const prompt = 'Nivel: STANDARD\nImplementá el checkout.';
+  assert.equal(runGate(project, delegate(prompt)), null);
+});
+
+test('denies when the pointer names a task with no contract file', () => {
+  const project = makeProject();
+  enableGate(project);
+  mkdirSync(join(project, '.ai', 'pipeline', 'checkout-flow'), {
+    recursive: true,
+  });
+  writeFileSync(join(project, '.ai', 'pipeline', 'ACTIVA'), 'checkout-flow');
+  const prompt = 'Nivel: STANDARD\nImplementá el checkout.';
+  assert.ok(isDeny(runGate(project, delegate(prompt))));
+});
+
+test('exempt subagent type (qa) is never held to the live-task requirement', () => {
+  const project = makeProject();
+  enableGate(project);
+  const prompt = 'Nivel: STANDARD\nImplementá el checkout.';
+  assert.equal(runGate(project, delegate(prompt, 'qa')), null);
+});
+
+test('activePointerPath param override points the gate at a custom location', () => {
+  const project = makeProject();
+  writeProjectConfig(project, {
+    gates: {
+      requireLiveTaskWhenImplementing: {
+        enabled: true,
+        activePointerPath: join('.custom', 'ACTIVE'),
+      },
+    },
+  });
+  mkdirSync(join(project, '.ai', 'pipeline', 'checkout-flow'), {
+    recursive: true,
+  });
+  writeFileSync(join(project, '.ai', 'pipeline', 'ACTIVA'), 'checkout-flow');
+  writeFileSync(
+    join(project, '.ai', 'pipeline', 'checkout-flow', 'asserts.md'),
+    'Criterio: cobrar bien.',
+  );
+  const prompt = 'Nivel: STANDARD\nImplementá el checkout.';
+  // the default pointer exists and is well-formed, but the override points elsewhere,
+  // which does not exist: the gate must deny, proving the param actually took effect.
+  assert.ok(isDeny(runGate(project, delegate(prompt))));
+});

package/plugins/gates/hooks/gates/neutral-spanish/index.mjs

@@ -0,0 +1,85 @@
+import { runGate, warn } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'neutral-spanish';
+const CONFIG_KEY = 'warnNonNeutralSpanish';
+
+const MAX_REPORTED_MARKERS = 8;
+
+// Data strings, not identifiers — never add these to a cSpell dictionary.
+const DEFAULT_REGIONAL_MARKERS = [
+  'tenés',
+  'podés',
+  'querés',
+  'sabés',
+  'hacés',
+  'decís',
+  'venís',
+  'sos',
+  'fijate',
+  'mirá',
+  'pará',
+  'esperá',
+  'dale',
+  'mandale',
+  'contame',
+  'fíjate vos',
+  'acá',
+  'allá',
+  'laburo',
+  'laburar',
+  'quilombo',
+  'posta',
+  'che',
+  'boludo',
+  'pibe',
+  'guita',
+  'al pedo',
+  'un toque',
+  'capaz que',
+  'de una',
+];
+
+function extractText(toolName, toolInput) {
+  if (toolName === 'Write') return String(toolInput?.content ?? '');
+  if (toolName === 'Edit') return String(toolInput?.new_string ?? '');
+  if (toolName === 'MultiEdit' && Array.isArray(toolInput?.edits)) {
+    return toolInput.edits
+      .map((edit) => String(edit?.new_string ?? ''))
+      .join('\n');
+  }
+  return '';
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: {
+      regionalMarkers: DEFAULT_REGIONAL_MARKERS,
+    },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    const text = extractText(toolName, toolInput).toLowerCase();
+    if (!text) return;
+
+    const hits = [];
+    for (const marker of parameters.regionalMarkers) {
+      const escaped = marker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      // \p{L} (any Unicode letter) as the non-boundary class, instead of a hand-written
+      // accented-character set, so accented word boundaries are handled correctly without
+      // spelling out literal accented characters in the source (the project keeps its
+      // spell-check dictionary untouched, so no word list may lean on this being a string).
+      const pattern = new RegExp(`(^|[^\\p{L}])${escaped}([^\\p{L}]|$)`, 'iu');
+      if (pattern.test(text)) hits.push(marker);
+    }
+
+    if (hits.length === 0) return;
+
+    const unique = [...new Set(hits)].slice(0, MAX_REPORTED_MARKERS);
+    warn(
+      GATE_ID,
+      `Text being written contains regional Spanish markers: ${unique.join(', ')}. Prefer neutral Spanish unless this is a literal quote or data.`,
+    );
+  },
+);

package/plugins/gates/hooks/gates/neutral-spanish/test.mjs

@@ -0,0 +1,65 @@
+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(), 'neutral-spanish-'));
+  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 write(content) {
+  return {
+    tool_name: 'Write',
+    tool_input: { file_path: '/repo/notes.md', content },
+  };
+}
+function isWarn(result) {
+  return result?.hookSpecificOutput?.additionalContext !== undefined;
+}
+
+test('warns on Rioplatense voseo and lexicon', () => {
+  assert.ok(isWarn(runGate(write('vos tenés que revisar esto, dale'))));
+  assert.ok(isWarn(runGate(write('che, mirá el laburo que hicimos acá'))));
+});
+
+test('allows neutral Spanish', () => {
+  assert.equal(runGate(write('tienes que revisar esto, de acuerdo')), null);
+});
+
+test('disabled by config: the gate does not run', () => {
+  assert.equal(
+    runGate(write('vos tenés que revisar esto'), {
+      config: { gates: { warnNonNeutralSpanish: false } },
+    }),
+    null,
+  );
+});
+
+test('project regionalMarkers override replaces the built-in list', () => {
+  const config = {
+    gates: {
+      warnNonNeutralSpanish: { enabled: true, regionalMarkers: ['bacano'] },
+    },
+  };
+  assert.equal(runGate(write('vos tenés que revisar esto'), { config }), null);
+  assert.ok(isWarn(runGate(write('que bacano quedo esto'), { config })));
+});

package/plugins/gates/hooks/gates/never-assume/index.mjs

@@ -0,0 +1,55 @@
+import { runGate, warn, TOOL_GROUPS } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'never-assume';
+const CONFIG_KEY = 'requireVerificationBeforeAssuming';
+
+const DEFAULT_CONJECTURE_PATTERNS = [
+  'i assume',
+  'assuming that',
+  'probably',
+  'i guess',
+  'should be',
+  "i'll default to",
+];
+
+function extractContent(toolName, toolInput) {
+  if (TOOL_GROUPS.delegation.includes(toolName)) return toolInput?.prompt;
+  return toolInput?.content ?? toolInput?.new_string;
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: false,
+    defaultParams: {
+      conjecturePatterns: DEFAULT_CONJECTURE_PATTERNS,
+    },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    const isWrite = TOOL_GROUPS.write.includes(toolName);
+    const isDelegation = TOOL_GROUPS.delegation.includes(toolName);
+    if (!isWrite && !isDelegation) return;
+
+    const content = extractContent(toolName, toolInput);
+    if (typeof content !== 'string') return;
+
+    const patterns = parameters.conjecturePatterns.map(
+      (source) => new RegExp(source, 'i'),
+    );
+    const hits = [];
+    for (const pattern of patterns) {
+      const match = content.match(pattern);
+      if (match) hits.push(match[0]);
+    }
+    if (hits.length === 0) return;
+
+    warn(
+      GATE_ID,
+      `Content contains conjecture phrasing without stated verification: ${hits.join(', ')}. Verify before asserting instead of assuming.`,
+    );
+  },
+);
+
+// The source guard (guard-never-assume.mjs) is explicit: this never denies,
+// only warns — conjecture language is a prompt to verify, not a blocker.