@devrik-tools/claude-gates 0.4.0 → 0.7.0

package/plugins/gates/hooks/gates/diagnosis-before-patch/index.mjs

@@ -1,43 +1,48 @@
-import { runGate, warn, toolInGroups, writtenContentOf } from '../../lib/hook-io.mjs';
-
-const GATE_ID = 'diagnosis-before-patch';
-const CONFIG_KEY = 'warnTimeoutChangeWithoutDiagnosis';
-
-const DEFAULT_TIMEOUT_PATTERNS = [
-  String.raw`\b[A-Z_]*TIMEOUT[A-Z_]*\s*[:=]\s*['"]?\d`,
-  String.raw`\b[A-Z_]*DEADLINE[A-Z_]*\s*[:=]\s*['"]?\d`,
-  String.raw`\b[A-Z_]*IDLE[A-Z_]*\s*[:=]\s*['"]?\d`,
-  String.raw`\b(max_?retry|retries|backoff)\b\s*[:=]\s*['"]?\d`,
-  String.raw`\b(query_?timeout|hard_?deadline)\b`,
-];
-
-function extractText(toolName, toolInput) {
-  if (!toolInGroups(toolName, ['write'])) return '';
-  return writtenContentOf(toolInput);
-}
-
-runGate(
-  {
-    id: GATE_ID,
-    configKey: CONFIG_KEY,
-    enabledByDefault: true,
-    defaultParams: {
-      timeoutPatterns: DEFAULT_TIMEOUT_PATTERNS,
-    },
-  },
-  ({ toolName, toolInput, parameters }) => {
-    const text = extractText(toolName, toolInput);
-    if (!text) return;
-
-    const patterns = parameters.timeoutPatterns.map(
-      (source) => new RegExp(source, 'i'),
-    );
-    const touchesTimeout = patterns.some((pattern) => pattern.test(text));
-    if (!touchesTimeout) return;
-
-    warn(
-      GATE_ID,
-      'Diagnosis before patch: you are adjusting a timeout/deadline/retry value. Before changing a value to fix a symptom ("X is slow/fails"), confirm you read the evidence that proves the cause (a log line from the failing provider/process, not a hypothesis). A timeout should measure inactivity, not total time: a process that is progressing should not be cut off.',
-    );
-  },
-);
+import {
+  runGate,
+  warn,
+  toolInGroups,
+  writtenContentOf,
+} from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'diagnosis-before-patch';
+const CONFIG_KEY = 'warnTimeoutChangeWithoutDiagnosis';
+
+const DEFAULT_TIMEOUT_PATTERNS = [
+  String.raw`\b[A-Z_]*TIMEOUT[A-Z_]*\s*[:=]\s*['"]?\d`,
+  String.raw`\b[A-Z_]*DEADLINE[A-Z_]*\s*[:=]\s*['"]?\d`,
+  String.raw`\b[A-Z_]*IDLE[A-Z_]*\s*[:=]\s*['"]?\d`,
+  String.raw`\b(max_?retry|retries|backoff)\b\s*[:=]\s*['"]?\d`,
+  String.raw`\b(query_?timeout|hard_?deadline)\b`,
+];
+
+function extractText(toolName, toolInput) {
+  if (!toolInGroups(toolName, ['write'])) return '';
+  return writtenContentOf(toolInput);
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: {
+      timeoutPatterns: DEFAULT_TIMEOUT_PATTERNS,
+    },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    const text = extractText(toolName, toolInput);
+    if (!text) return;
+
+    const patterns = parameters.timeoutPatterns.map(
+      (source) => new RegExp(source, 'i'),
+    );
+    const touchesTimeout = patterns.some((pattern) => pattern.test(text));
+    if (!touchesTimeout) return;
+
+    warn(
+      GATE_ID,
+      'Diagnosis before patch: you are adjusting a timeout/deadline/retry value. Before changing a value to fix a symptom ("X is slow/fails"), confirm you read the evidence that proves the cause (a log line from the failing provider/process, not a hypothesis). A timeout should measure inactivity, not total time: a process that is progressing should not be cut off.',
+    );
+  },
+);

package/plugins/gates/hooks/gates/feature-catalog/index.mjs

@@ -1,83 +1,83 @@
-// feature-catalog — enforces the machine-readable feature catalog's own invariants on
-// a write to that file: at most one feature `in_progress` at a time, and `done` is
-// never written directly (only a review/QA process closes a feature). Migrated from
-// ~/.claude/hooks/guard-feature-catalog.mjs.
-//
-// ── What a project can configure (params) ───────────────────────────────────────────
-//   catalogFileName   basename of the catalog file this gate watches for (default
-//                      feature_list.json). A write to any other file is ignored.
-//   maxInProgress     how many features may be `in_progress` simultaneously.
-// The defaults live here, in the source, so a project reads them and knows exactly what
-// its override replaces.
-//
-// ── Auto-off when the project never adopted the catalog ────────────────────────────
-// This gate only inspects the CONTENT being written to a file named `catalogFileName`.
-// A project that never uses that file never triggers it — there is nothing to disable
-// separately, the check is inert by construction rather than by a discovery pass.
-//
-// ── What is NOT configurable (base, non-negotiable) ─────────────────────────────────
-// Writing `status: done` directly is always denied, regardless of `maxInProgress`: only
-// a review/QA subagent or a validated automated process may close a feature, and this
-// gate has no way to tell who is writing, so it blocks the write itself.
-
-import {
-  runGate,
-  deny,
-  toolInGroups,
-  writtenContentOf,
-  writtenPathOf,
-} from '../../lib/hook-io.mjs';
-
-const GATE_ID = 'feature-catalog';
-const CONFIG_KEY = 'requireFeatureCatalog';
-
-const DEFAULT_CATALOG_FILE_NAME = 'feature_list.json';
-const DEFAULT_MAX_IN_PROGRESS = 1;
-
-const DONE_STATUS_PATTERN = /"status"\s*:\s*"done"|status\s*:\s*['"]done['"]/i;
-const IN_PROGRESS_STATUS_PATTERN = /"status"\s*:\s*"in_progress"/g;
-
-runGate(
-  {
-    id: GATE_ID,
-    configKey: CONFIG_KEY,
-    enabledByDefault: true,
-    defaultParams: {
-      catalogFileName: DEFAULT_CATALOG_FILE_NAME,
-      maxInProgress: DEFAULT_MAX_IN_PROGRESS,
-    },
-  },
-  ({ toolName, toolInput, parameters }) => {
-    if (!toolInGroups(toolName, ['write'])) return;
-
-    const target = writtenPathOf(toolInput);
-    const catalogFileName = String(
-      parameters.catalogFileName ?? DEFAULT_CATALOG_FILE_NAME,
-    );
-    if (!target.includes(catalogFileName)) return;
-
-    const content = writtenContentOf(toolInput);
-
-    // Base, non-negotiable: `done` is never written directly to the catalog.
-    if (DONE_STATUS_PATTERN.test(content)) {
-      deny(
-        GATE_ID,
-        `Writing 'status: done' directly to ${catalogFileName} is not allowed. ` +
-          'Only a review/QA subagent or a validated automated process may close a feature.',
-      );
-    }
-
-    const maxInProgress = Number(
-      parameters.maxInProgress ?? DEFAULT_MAX_IN_PROGRESS,
-    );
-    const inProgressCount = (content.match(IN_PROGRESS_STATUS_PATTERN) ?? [])
-      .length;
-    if (inProgressCount > maxInProgress) {
-      deny(
-        GATE_ID,
-        `${catalogFileName} would have ${inProgressCount} features 'in_progress'; ` +
-          `the maximum allowed is ${maxInProgress}.`,
-      );
-    }
-  },
-);
+// feature-catalog — enforces the machine-readable feature catalog's own invariants on
+// a write to that file: at most one feature `in_progress` at a time, and `done` is
+// never written directly (only a review/QA process closes a feature). Migrated from
+// ~/.claude/hooks/guard-feature-catalog.mjs.
+//
+// ── What a project can configure (params) ───────────────────────────────────────────
+//   catalogFileName   basename of the catalog file this gate watches for (default
+//                      feature_list.json). A write to any other file is ignored.
+//   maxInProgress     how many features may be `in_progress` simultaneously.
+// The defaults live here, in the source, so a project reads them and knows exactly what
+// its override replaces.
+//
+// ── Auto-off when the project never adopted the catalog ────────────────────────────
+// This gate only inspects the CONTENT being written to a file named `catalogFileName`.
+// A project that never uses that file never triggers it — there is nothing to disable
+// separately, the check is inert by construction rather than by a discovery pass.
+//
+// ── What is NOT configurable (base, non-negotiable) ─────────────────────────────────
+// Writing `status: done` directly is always denied, regardless of `maxInProgress`: only
+// a review/QA subagent or a validated automated process may close a feature, and this
+// gate has no way to tell who is writing, so it blocks the write itself.
+
+import {
+  runGate,
+  deny,
+  toolInGroups,
+  writtenContentOf,
+  writtenPathOf,
+} from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'feature-catalog';
+const CONFIG_KEY = 'requireFeatureCatalog';
+
+const DEFAULT_CATALOG_FILE_NAME = 'feature_list.json';
+const DEFAULT_MAX_IN_PROGRESS = 1;
+
+const DONE_STATUS_PATTERN = /"status"\s*:\s*"done"|status\s*:\s*['"]done['"]/i;
+const IN_PROGRESS_STATUS_PATTERN = /"status"\s*:\s*"in_progress"/g;
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: {
+      catalogFileName: DEFAULT_CATALOG_FILE_NAME,
+      maxInProgress: DEFAULT_MAX_IN_PROGRESS,
+    },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    if (!toolInGroups(toolName, ['write'])) return;
+
+    const target = writtenPathOf(toolInput);
+    const catalogFileName = String(
+      parameters.catalogFileName ?? DEFAULT_CATALOG_FILE_NAME,
+    );
+    if (!target.includes(catalogFileName)) return;
+
+    const content = writtenContentOf(toolInput);
+
+    // Base, non-negotiable: `done` is never written directly to the catalog.
+    if (DONE_STATUS_PATTERN.test(content)) {
+      deny(
+        GATE_ID,
+        `Writing 'status: done' directly to ${catalogFileName} is not allowed. ` +
+          'Only a review/QA subagent or a validated automated process may close a feature.',
+      );
+    }
+
+    const maxInProgress = Number(
+      parameters.maxInProgress ?? DEFAULT_MAX_IN_PROGRESS,
+    );
+    const inProgressCount = (content.match(IN_PROGRESS_STATUS_PATTERN) ?? [])
+      .length;
+    if (inProgressCount > maxInProgress) {
+      deny(
+        GATE_ID,
+        `${catalogFileName} would have ${inProgressCount} features 'in_progress'; ` +
+          `the maximum allowed is ${maxInProgress}.`,
+      );
+    }
+  },
+);

package/plugins/gates/hooks/gates/force-parallel/index.mjs

@@ -1,119 +1,134 @@
-// force-parallel — nudges toward parallelizing independent delegations. WARN-only: it
-// never denies, because a PreToolUse hook sees one tool call at a time and has no way to
-// know whether the delegations it observed COULD have been sent together — only that they
-// arrived one after another.
-//
-// justification: no existing tool covers this. brief-before-delegate/intent-flow/risk-level
-// gate the CONTENT of a single delegation prompt; none of them look across delegations in
-// the same session to notice a sequential pattern.
-//
-// ── Honest limitation (read before trusting this gate) ──────────────────────────────
-// A PreToolUse hook fires once per tool call, synchronously, with no visibility into what
-// the model is "thinking" or whether independent work existed to batch. This gate can only
-// count consecutive delegation calls that land close together in wall-clock time and warn
-// after a threshold — it cannot prove they were independent, and it cannot force the model
-// to have sent them in one message (Claude Code's own turn structure decides that, not a
-// hook). Treat the warning as a nudge for the NEXT delegation, never as proof of a missed
-// opportunity on the ones already sent.
-//
-// ── What a project can configure (params) ───────────────────────────────────────────
-//   sequentialThreshold      consecutive delegations (within the window) before warning.
-//   sequentialWindowMs       how close in time two delegations must land to count as the
-//                            same sequential run; a gap resets the count.
-//   sequentialJustifiedMarker  a marker token in the delegation prompt that escapes the
-//                            warning — a declared reason not to parallelize is a decision.
-// The defaults live here, in the source, so a project reads them and knows exactly what
-// its override replaces.
-//
-// ── State ─────────────────────────────────────────────────────────────────────────────
-// Per-session count + last-delegation timestamp, persisted at
-// os.tmpdir()/claude-gates/force-parallel/<sessionId>/state.json — process-local state
-// would not survive across the separate process each hook invocation spawns.
-
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { runGate, warn, toolInGroups, delegationPromptOf } from '../../lib/hook-io.mjs';
-
-const GATE_ID = 'force-parallel';
-const CONFIG_KEY = 'warnSequentialDelegations';
-
-const DELEGATION_GROUPS = ['delegation'];
-const DEFAULT_SEQUENTIAL_THRESHOLD = 3;
-const DEFAULT_SEQUENTIAL_WINDOW_MS = 120000;
-const DEFAULT_JUSTIFIED_MARKER = 'SEQUENTIAL-JUSTIFIED';
-
-const STATE_ROOT = join(tmpdir(), 'claude-gates', 'force-parallel');
-const STATE_FILE = 'state.json';
-const UNKNOWN_SESSION = 'unknown-session';
-
-function statePathFor(sessionId) {
-  const safeSessionId = String(sessionId || UNKNOWN_SESSION).replace(/[^\w-]/g, '_');
-  return join(STATE_ROOT, safeSessionId, STATE_FILE);
-}
-
-function readState(path) {
-  if (!existsSync(path)) return { count: 0, lastAt: 0 };
-  try {
-    const parsed = JSON.parse(readFileSync(path, 'utf8'));
-    return {
-      count: Number(parsed.count) || 0,
-      lastAt: Number(parsed.lastAt) || 0,
-    };
-  } catch {
-    return { count: 0, lastAt: 0 };
-  }
-}
-
-function writeState(path, state) {
-  mkdirSync(join(path, '..'), { recursive: true });
-  writeFileSync(path, JSON.stringify(state), 'utf8');
-}
-
-const WARN_MESSAGE =
-  'This is the {count}th delegation sent one-by-one within {windowSeconds}s. If the ' +
-  'remaining work is independent, launch the next batch together in a single message ' +
-  '(multiple tool calls) instead of one delegation per turn. If this delegation ' +
-  'genuinely depends on a prior result, ignore this and mark the prompt with ' +
-  '"{marker}" to skip the warning next time.';
-
-runGate(
-  {
-    id: GATE_ID,
-    configKey: CONFIG_KEY,
-    enabledByDefault: false,
-    defaultParams: {
-      sequentialThreshold: DEFAULT_SEQUENTIAL_THRESHOLD,
-      sequentialWindowMs: DEFAULT_SEQUENTIAL_WINDOW_MS,
-      sequentialJustifiedMarker: DEFAULT_JUSTIFIED_MARKER,
-    },
-  },
-  ({ toolName, toolInput, sessionId, parameters }) => {
-    if (!toolInGroups(toolName, DELEGATION_GROUPS)) return;
-
-    const marker = parameters.sequentialJustifiedMarker ?? DEFAULT_JUSTIFIED_MARKER;
-    const prompt = delegationPromptOf(toolInput);
-    if (prompt.includes(marker)) return; // declared reason not to parallelize: no warning
-
-    const threshold = parameters.sequentialThreshold ?? DEFAULT_SEQUENTIAL_THRESHOLD;
-    const windowMs = parameters.sequentialWindowMs ?? DEFAULT_SEQUENTIAL_WINDOW_MS;
-
-    const statePath = statePathFor(sessionId);
-    const state = readState(statePath);
-    const now = Date.now();
-
-    const withinWindow = now - state.lastAt <= windowMs;
-    const nextCount = withinWindow ? state.count + 1 : 1;
-
-    writeState(statePath, { count: nextCount, lastAt: now });
-
-    if (nextCount < threshold) return;
-
-    warn(
-      GATE_ID,
-      WARN_MESSAGE.replace('{count}', String(nextCount))
-        .replace('{windowSeconds}', String(Math.round(windowMs / 1000)))
-        .replace('{marker}', marker),
-    );
-  },
-);
+// force-parallel — nudges toward parallelizing independent delegations. WARN-only: it
+// never denies, because a PreToolUse hook sees one tool call at a time and has no way to
+// know whether the delegations it observed COULD have been sent together — only that they
+// arrived one after another.
+//
+// justification: no existing tool covers this. brief-before-delegate/intent-flow/risk-level
+// gate the CONTENT of a single delegation prompt; none of them look across delegations in
+// the same session to notice a sequential pattern.
+//
+// ── Honest limitation (read before trusting this gate) ──────────────────────────────
+// A PreToolUse hook fires once per tool call, synchronously, with no visibility into what
+// the model is "thinking" or whether independent work existed to batch. This gate can only
+// count consecutive delegation calls that land close together in wall-clock time and warn
+// after a threshold — it cannot prove they were independent, and it cannot force the model
+// to have sent them in one message (Claude Code's own turn structure decides that, not a
+// hook). Treat the warning as a nudge for the NEXT delegation, never as proof of a missed
+// opportunity on the ones already sent.
+//
+// ── What a project can configure (params) ───────────────────────────────────────────
+//   sequentialThreshold      consecutive delegations (within the window) before warning.
+//   sequentialWindowMs       how close in time two delegations must land to count as the
+//                            same sequential run; a gap resets the count.
+//   sequentialJustifiedMarker  a marker token in the delegation prompt that escapes the
+//                            warning — a declared reason not to parallelize is a decision.
+// The defaults live here, in the source, so a project reads them and knows exactly what
+// its override replaces.
+//
+// ── State ─────────────────────────────────────────────────────────────────────────────
+// Per-session count + last-delegation timestamp, persisted at
+// os.tmpdir()/claude-gates/force-parallel/<sessionId>/state.json — process-local state
+// would not survive across the separate process each hook invocation spawns.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  runGate,
+  warn,
+  toolInGroups,
+  delegationPromptOf,
+} from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'force-parallel';
+const CONFIG_KEY = 'warnSequentialDelegations';
+
+const DELEGATION_GROUPS = ['delegation'];
+const DEFAULT_SEQUENTIAL_THRESHOLD = 3;
+const DEFAULT_SEQUENTIAL_WINDOW_MS = 120000;
+const DEFAULT_JUSTIFIED_MARKER = 'SEQUENTIAL-JUSTIFIED';
+const MS_PER_SECOND = 1000;
+
+const STATE_ROOT = join(tmpdir(), 'claude-gates', 'force-parallel');
+const STATE_FILE = 'state.json';
+const UNKNOWN_SESSION = 'unknown-session';
+
+function statePathFor(sessionId) {
+  const safeSessionId = String(sessionId || UNKNOWN_SESSION).replace(
+    /[^\w-]/g,
+    '_',
+  );
+  return join(STATE_ROOT, safeSessionId, STATE_FILE);
+}
+
+function readState(path) {
+  if (!existsSync(path)) return { count: 0, lastAt: 0 };
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    return {
+      count: Number(parsed.count) || 0,
+      lastAt: Number(parsed.lastAt) || 0,
+    };
+  } catch {
+    return { count: 0, lastAt: 0 };
+  }
+}
+
+function writeState(path, state) {
+  mkdirSync(join(path, '..'), { recursive: true });
+  writeFileSync(path, JSON.stringify(state), 'utf8');
+}
+
+const WARN_MESSAGE =
+  'This is the {count}th delegation sent one-by-one within {windowSeconds}s. If the ' +
+  'remaining work is independent, launch the next batch together in a single message ' +
+  '(multiple tool calls) instead of one delegation per turn. If this delegation ' +
+  'genuinely depends on a prior result, ignore this and mark the prompt with ' +
+  '"{marker}" to skip the warning next time.';
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: false,
+    defaultParams: {
+      sequentialThreshold: DEFAULT_SEQUENTIAL_THRESHOLD,
+      sequentialWindowMs: DEFAULT_SEQUENTIAL_WINDOW_MS,
+      sequentialJustifiedMarker: DEFAULT_JUSTIFIED_MARKER,
+    },
+  },
+  ({ toolName, toolInput, sessionId, parameters }) => {
+    if (!toolInGroups(toolName, DELEGATION_GROUPS)) return;
+
+    const marker =
+      parameters.sequentialJustifiedMarker ?? DEFAULT_JUSTIFIED_MARKER;
+    const prompt = delegationPromptOf(toolInput);
+    if (prompt.includes(marker)) return; // declared reason not to parallelize: no warning
+
+    const threshold =
+      parameters.sequentialThreshold ?? DEFAULT_SEQUENTIAL_THRESHOLD;
+    const windowMs =
+      parameters.sequentialWindowMs ?? DEFAULT_SEQUENTIAL_WINDOW_MS;
+
+    const statePath = statePathFor(sessionId);
+    const state = readState(statePath);
+    const now = Date.now();
+
+    const withinWindow = now - state.lastAt <= windowMs;
+    const nextCount = withinWindow ? state.count + 1 : 1;
+
+    writeState(statePath, { count: nextCount, lastAt: now });
+
+    if (nextCount < threshold) return;
+
+    warn(
+      GATE_ID,
+      WARN_MESSAGE.replace('{count}', String(nextCount))
+        .replace(
+          '{windowSeconds}',
+          String(Math.round(windowMs / MS_PER_SECOND)),
+        )
+        .replace('{marker}', marker),
+    );
+  },
+);