@devrik-tools/claude-gates 0.1.0

package/plugins/gates/hooks/gates/no-reconfirm/index.mjs

@@ -0,0 +1,202 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { runGate, warn, TOOL_GROUPS } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'no-reconfirm';
+const CONFIG_KEY = 'requireNoReconfirmOfApproved';
+
+const DEFAULT_OVERLAP_THRESHOLD = 0.34;
+const MIN_SHARED_WORDS = 2;
+const MIN_SIGNIFICANT_WORD_LENGTH = 5;
+const QUESTION_PREVIEW_LENGTH = 100;
+const APPROVING_TURN_PREVIEW_LENGTH = 140;
+
+function wordBoundary(alternatives) {
+  return new RegExp(
+    `(?<![\\p{L}\\p{N}_])(${alternatives})(?![\\p{L}\\p{N}_])`,
+    'iu',
+  );
+}
+
+const APPROVAL_PATTERN = wordBoundary(
+  'go ahead|approved|i approve|authorized|proceed|do it|confirmed|i confirm|' +
+    'sounds good,? do it|yes,? (do it|go ahead|proceed)|ok,? (do it|go ahead|proceed)',
+);
+
+const STOP_WORDS = new Set([
+  'about',
+  'above',
+  'after',
+  'again',
+  'against',
+  'before',
+  'being',
+  'below',
+  'between',
+  'could',
+  'during',
+  'having',
+  'other',
+  'people',
+  'should',
+  'system',
+  'their',
+  'there',
+  'these',
+  'those',
+  'through',
+  'under',
+  'until',
+  'where',
+  'which',
+  'while',
+  'would',
+]);
+
+function isHumanTurn(event) {
+  if (event?.type !== 'user' || event?.userType !== 'external') return false;
+  const content = event?.message?.content;
+  if (typeof content === 'string') return true;
+  if (Array.isArray(content))
+    return content.every((block) => block?.type === 'text');
+  return false;
+}
+
+function textOf(event) {
+  const content = event.message.content;
+  if (typeof content === 'string') return content;
+  return content.map((block) => block.text || '').join(' ');
+}
+
+function humanTurnsFrom(transcriptPath) {
+  if (!transcriptPath || !existsSync(transcriptPath)) return null;
+
+  let raw;
+  try {
+    raw = readFileSync(transcriptPath, 'utf8');
+  } catch {
+    return null;
+  }
+
+  const turns = [];
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (isHumanTurn(event)) turns.push(textOf(event));
+  }
+  return turns;
+}
+
+function significantWords(text) {
+  const normalized = String(text)
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/[̀-ͯ]/g, '');
+  const words = normalized.match(/[a-z]+/g) || [];
+  return new Set(
+    words.filter(
+      (word) =>
+        word.length >= MIN_SIGNIFICANT_WORD_LENGTH && !STOP_WORDS.has(word),
+    ),
+  );
+}
+
+function topicOfQuestion(question) {
+  const header = String(question?.header || '');
+  const body = String(question?.question || '');
+  const optionLabels = (question?.options || [])
+    .map((option) => String(option?.label || ''))
+    .join(' ');
+  return `${header} ${body} ${optionLabels}`;
+}
+
+function turnThatAlreadyApprovedThisTopic(
+  humanTurns,
+  question,
+  overlapThreshold,
+) {
+  const topicWords = significantWords(topicOfQuestion(question));
+  if (topicWords.size === 0) return null;
+
+  for (const turn of humanTurns) {
+    if (!APPROVAL_PATTERN.test(turn)) continue;
+
+    const turnWords = significantWords(turn);
+    let shared = 0;
+    for (const word of topicWords) {
+      if (turnWords.has(word)) shared++;
+    }
+    const fraction = shared / topicWords.size;
+    if (shared >= MIN_SHARED_WORDS && fraction >= overlapThreshold) return turn;
+  }
+  return null;
+}
+
+function transcriptPathOf(rawPayload) {
+  try {
+    return JSON.parse(rawPayload)?.transcript_path;
+  } catch {
+    return null;
+  }
+}
+
+function noticeFor(question, approvingTurn) {
+  const questionPreview = String(question?.question || '').slice(
+    0,
+    QUESTION_PREVIEW_LENGTH,
+  );
+  const approvingTurnPreview = approvingTurn
+    .replace(/\s+/g, ' ')
+    .slice(0, APPROVING_TURN_PREVIEW_LENGTH);
+  return `Question "${questionPreview}" shares its topic with a turn where the user already gave explicit approval: "${approvingTurnPreview}". If it is the same decision, do not re-ask — proceed.`;
+}
+
+function collectReconfirmationNotices(questions, humanTurns, overlapThreshold) {
+  const notices = [];
+  for (const question of questions) {
+    const approvingTurn = turnThatAlreadyApprovedThisTopic(
+      humanTurns,
+      question,
+      overlapThreshold,
+    );
+    if (approvingTurn) notices.push(noticeFor(question, approvingTurn));
+  }
+  return notices;
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: {
+      overlapThreshold: DEFAULT_OVERLAP_THRESHOLD,
+    },
+  },
+  ({ toolName, toolInput, parameters, rawPayload }) => {
+    if (!TOOL_GROUPS.question.includes(toolName)) return;
+
+    const questions = Array.isArray(toolInput?.questions)
+      ? toolInput.questions
+      : [];
+    if (questions.length === 0) return;
+
+    const transcriptPath = transcriptPathOf(rawPayload);
+    if (!transcriptPath) return;
+
+    const humanTurns = humanTurnsFrom(transcriptPath);
+    if (humanTurns === null || humanTurns.length === 0) return; // no readable transcript: cannot verify
+
+    const notices = collectReconfirmationNotices(
+      questions,
+      humanTurns,
+      parameters.overlapThreshold,
+    );
+    if (notices.length === 0) return;
+    warn(GATE_ID, notices.join('\n\n'));
+  },
+);

package/plugins/gates/hooks/gates/no-reconfirm/test.mjs

@@ -0,0 +1,131 @@
+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 newProject({ config } = {}) {
+  const project = mkdtempSync(join(tmpdir(), 'no-reconfirm-'));
+  mkdirSync(join(project, '.git'));
+  if (config) {
+    mkdirSync(join(project, '.ai'));
+    writeFileSync(join(project, '.ai', 'config.json'), JSON.stringify(config));
+  }
+  return project;
+}
+
+function writeTranscript(project, events) {
+  const transcriptPath = join(project, 'transcript.jsonl');
+  writeFileSync(
+    transcriptPath,
+    events.map((event) => JSON.stringify(event)).join('\n'),
+  );
+  return transcriptPath;
+}
+
+function humanTurn(text) {
+  return { type: 'user', userType: 'external', message: { content: text } };
+}
+
+function askQuestion(transcriptPath, question) {
+  return {
+    tool_name: 'AskUserQuestion',
+    transcript_path: transcriptPath,
+    tool_input: { questions: [question] },
+  };
+}
+
+function runGateIn(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 isWarn(result) {
+  return result?.hookSpecificOutput?.additionalContext !== undefined;
+}
+
+test('warns when re-asking a topic the user already approved', () => {
+  const project = newProject();
+  const transcriptPath = writeTranscript(project, [
+    humanTurn('go ahead, migrate the authentication database schema now'),
+  ]);
+  const question = {
+    header: 'Migration',
+    question: 'Should I migrate the authentication database schema?',
+    options: [],
+  };
+  assert.ok(isWarn(runGateIn(project, askQuestion(transcriptPath, question))));
+});
+
+test('allows a genuinely new question with no prior approval overlap', () => {
+  const project = newProject();
+  const transcriptPath = writeTranscript(project, [humanTurn('hello there')]);
+  const question = {
+    header: 'Deploy',
+    question: 'Should I deploy to production now?',
+    options: [],
+  };
+  assert.equal(runGateIn(project, askQuestion(transcriptPath, question)), null);
+});
+
+test('disabled by config: the gate does not run', () => {
+  const project = newProject({
+    config: { gates: { requireNoReconfirmOfApproved: false } },
+  });
+  const transcriptPath = writeTranscript(project, [
+    humanTurn('go ahead, migrate the authentication database schema now'),
+  ]);
+  const question = {
+    header: 'Migration',
+    question: 'Should I migrate the authentication database schema?',
+    options: [],
+  };
+  assert.equal(runGateIn(project, askQuestion(transcriptPath, question)), null);
+});
+
+test('degrades to allow when transcript_path is missing or unreadable', () => {
+  const project = newProject();
+  const question = {
+    header: 'Migration',
+    question: 'Should I migrate now?',
+    options: [],
+  };
+  assert.equal(
+    runGateIn(project, {
+      tool_name: 'AskUserQuestion',
+      tool_input: { questions: [question] },
+    }),
+    null,
+  );
+});
+
+test('overlapThreshold override changes sensitivity', () => {
+  const project = newProject({
+    config: {
+      gates: {
+        requireNoReconfirmOfApproved: { enabled: true, overlapThreshold: 0.99 },
+      },
+    },
+  });
+  const transcriptPath = writeTranscript(project, [
+    humanTurn('go ahead, migrate the authentication schema'),
+  ]);
+  const question = {
+    header: 'Migration',
+    question:
+      'Should I migrate the authentication database schema now with backups?',
+    options: [],
+  };
+  assert.equal(runGateIn(project, askQuestion(transcriptPath, question)), null);
+});

package/plugins/gates/hooks/gates/protected-paths/index.mjs

@@ -0,0 +1,147 @@
+// protected-paths — denies writes and mutating shell commands that target a path
+// containing one of the project's protected fragments (.env, lockfiles, the harness
+// itself). Migrated from ~/.claude/hooks/guard-protected-paths.mjs: that guard protected
+// hardcoded "code directories" (src, tests) to force delegation through a Leader role.
+// This gate keeps only the path-protection mechanism — sensitive files no write should
+// ever touch — and drops the Leader-role/delegation policy, which is a different concern.
+//
+// ── What a project can configure (params) ───────────────────────────────────────────
+//   protectedPaths     path fragments (case-insensitive) that no write or mutating
+//                       command may target. Replaces the built-in list wholesale.
+//   mutatingCommands    shell command names treated as mutating, so a merely-reading
+//                       command that mentions a protected path (echo, cat, grep) is
+//                       never denied. 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.
+
+import { runGate, deny, TOOL_GROUPS } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'protected-paths';
+const CONFIG_KEY = 'blockWritesToProtectedPaths';
+
+const WRITE_TOOLS = new Set(TOOL_GROUPS.write);
+const SHELL_TOOLS = new Set(TOOL_GROUPS.shell);
+
+const DEFAULT_PROTECTED_PATHS = [
+  '.env',
+  'package-lock.json',
+  'yarn.lock',
+  'pnpm-lock.yaml',
+  'hooks/',
+];
+
+const DEFAULT_MUTATING_COMMANDS = [
+  'touch',
+  'rm',
+  'cp',
+  'mv',
+  'sed\\s+-i',
+  'tee',
+  'install',
+  'chmod',
+  'chown',
+  'truncate',
+];
+
+function escapeRegExp(fragment) {
+  return fragment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** The path a write tool targets, across the field names different tools use. */
+function writeTargetFrom(toolInput) {
+  return String(
+    toolInput.TargetFile ??
+      toolInput.target_file ??
+      toolInput.file_path ??
+      toolInput.path ??
+      '',
+  );
+}
+
+function isProtectedPath(path, protectedPaths) {
+  const normalized = path.toLowerCase();
+  return protectedPaths.some((fragment) =>
+    normalized.includes(fragment.toLowerCase()),
+  );
+}
+
+function buildCommandPatterns(protectedPaths, mutatingCommands) {
+  const pathAlternation = protectedPaths.map(escapeRegExp).join('|');
+  const mutatingAlternation = mutatingCommands.join('|');
+  const wordBoundary = String.raw`\b`;
+  const redirectPrefix = String.raw`>>?\s*\S*`;
+  return {
+    mutatingCommand: new RegExp(
+      `${wordBoundary}(${mutatingAlternation})${wordBoundary}`,
+      'i',
+    ),
+    protectedTarget: new RegExp(`(${pathAlternation})`, 'i'),
+    redirectToProtected: new RegExp(
+      `${redirectPrefix}(${pathAlternation})`,
+      'i',
+    ),
+  };
+}
+
+/** The write-tool branch: deny when the target path matches a protected fragment. */
+function checkWrite(toolInput, protectedPaths) {
+  const target = writeTargetFrom(toolInput);
+  if (target && isProtectedPath(target, protectedPaths)) {
+    deny(
+      GATE_ID,
+      `Writing to '${target}' is not allowed: it matches a protected path (${protectedPaths.join(', ')}).`,
+    );
+  }
+}
+
+/** The shell-tool branch: deny a mutating command whose target matches a protected path. */
+function checkShellCommand(toolInput, protectedPaths, mutatingCommands) {
+  const command = String(toolInput.CommandLine ?? toolInput.command ?? '');
+  if (!command.trim()) return;
+
+  const { mutatingCommand, protectedTarget, redirectToProtected } =
+    buildCommandPatterns(protectedPaths, mutatingCommands);
+
+  const targetsProtected =
+    redirectToProtected.test(command) ||
+    (mutatingCommand.test(command) && protectedTarget.test(command));
+
+  if (targetsProtected) {
+    deny(
+      GATE_ID,
+      `This command targets a protected path (${protectedPaths.join(', ')}) with a mutating operation. ` +
+        'Reading (echo/cat/grep) is fine; modifying it is not.',
+    );
+  }
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: {
+      protectedPaths: DEFAULT_PROTECTED_PATHS,
+      mutatingCommands: DEFAULT_MUTATING_COMMANDS,
+    },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    const isWrite = WRITE_TOOLS.has(toolName);
+    const isShell = SHELL_TOOLS.has(toolName);
+    if (!isWrite && !isShell) return;
+
+    const protectedPaths = parameters.protectedPaths ?? [];
+    if (protectedPaths.length === 0) return;
+
+    if (isWrite) {
+      checkWrite(toolInput, protectedPaths);
+      return;
+    }
+
+    checkShellCommand(
+      toolInput,
+      protectedPaths,
+      parameters.mutatingCommands ?? [],
+    );
+  },
+);

package/plugins/gates/hooks/gates/protected-paths/test.mjs

@@ -0,0 +1,75 @@
+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');
+
+// Runs the gate as its own process (it calls process.exit), feeding a payload on stdin
+// from inside a temp project so the gate's config lookup is isolated. Returns the parsed
+// stdout, or null when the gate allowed (no output).
+function runGate(payload, { config } = {}) {
+  const project = mkdtempSync(join(tmpdir(), 'protected-paths-'));
+  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(filePath) {
+  return { tool_name: 'Write', tool_input: { file_path: filePath } };
+}
+function bash(command) {
+  return { tool_name: 'Bash', tool_input: { command } };
+}
+function isDeny(result) {
+  return result?.hookSpecificOutput?.permissionDecision === 'deny';
+}
+
+test('denies writing to .env and a mutating shell command targeting it', () => {
+  assert.ok(isDeny(runGate(write('/repo/.env'))));
+  assert.ok(isDeny(runGate(bash('rm .env'))));
+  assert.ok(isDeny(runGate(bash('touch package-lock.json'))));
+});
+
+test('allows an innocuous write and a read-only command mentioning a protected path', () => {
+  assert.equal(runGate(write('/repo/src/index.js')), null);
+  assert.equal(runGate(bash('echo "reading .env for debugging"')), null);
+  assert.equal(runGate(bash('cat .env')), null);
+});
+
+test('disabled by config: the gate does not run', () => {
+  assert.equal(
+    runGate(write('/repo/.env'), {
+      config: { gates: { blockWritesToProtectedPaths: false } },
+    }),
+    null,
+  );
+});
+
+test('project protectedPaths replaces the built-in list', () => {
+  const config = {
+    gates: {
+      blockWritesToProtectedPaths: {
+        enabled: true,
+        protectedPaths: ['secrets.yaml'],
+      },
+    },
+  };
+  // .env no longer protected under the override
+  assert.equal(runGate(write('/repo/.env'), { config }), null);
+  assert.ok(isDeny(runGate(write('/repo/secrets.yaml'), { config })));
+});

package/plugins/gates/hooks/gates/recurrence-lock/index.mjs

@@ -0,0 +1,64 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { runGate, deny, TOOL_GROUPS } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'recurrence-lock';
+const CONFIG_KEY = 'blockRegisteredRecurrences';
+
+// The source guard (guard-reincidence-lock.mjs) reads pending recurrences
+// from a full tracking module (../scripts/memory/recurrences.mjs) with
+// close/decide/pending subcommands. That infrastructure belongs to another
+// project and does not exist here. This gate only reads a plain state file
+// at .ai/reincidencias.json if present, with the shape:
+//   { classes: [{ class, occurrences: [...], status }] }
+// If neither the module nor the file exists, it allows silently — there is
+// nothing to enforce without a recurrence record.
+function loadOpenRecurrences(projectRoot, thresholdAppearances) {
+  const filePath = join(projectRoot, '.ai', 'reincidencias.json');
+  if (!existsSync(filePath)) return [];
+
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return [];
+  }
+
+  const classes = Array.isArray(parsed?.classes) ? parsed.classes : [];
+  return classes.filter((entry) => {
+    const occurrenceCount = Array.isArray(entry?.occurrences)
+      ? entry.occurrences.length
+      : 0;
+    const status = String(entry?.status ?? '').toLowerCase();
+    const isClosed = status === 'closed' || status === 'cerrada';
+    return occurrenceCount >= thresholdAppearances && !isClosed;
+  });
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: {
+      thresholdAppearances: 2,
+    },
+  },
+  ({ toolName, parameters }) => {
+    const isExecution = TOOL_GROUPS.execution.includes(toolName);
+    const isDelegation = TOOL_GROUPS.delegation.includes(toolName);
+    if (!isExecution && !isDelegation) return;
+
+    const openRecurrences = loadOpenRecurrences(
+      process.cwd(),
+      parameters.thresholdAppearances,
+    );
+    if (openRecurrences.length === 0) return;
+
+    const names = openRecurrences.map((entry) => entry.class).join(', ');
+    deny(
+      GATE_ID,
+      `Registered recurring issue classes are still open and at/above threshold: ${names}. Resolve or close them before proceeding.`,
+    );
+  },
+);