@devrik-tools/claude-gates 0.7.2 → 0.8.0

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

@@ -1,28 +1,44 @@
+// neutral-spanish — regional Spanish (voseo, Rioplatense lexicon) is denied in Spanish
+// prose. Only prose is scanned: a text-type file, or content carrying enough Spanish
+// function words to be Spanish — so an English "Author: Dale Carnegie" in code is not a
+// marker hit. A deliberate quote/fixture/log opts out with the escape-hatch marker.
+
+import { extname } from 'node:path';
 import {
   runGate,
   deny,
   toolInGroups,
   writtenContentOf,
+  writtenPathOf,
+  escapeRegExp,
 } from '../../lib/hook-io.mjs';
+import { withUnicodeWordBoundary } from '../../lib/signals.mjs';
 
 const GATE_ID = 'neutral-spanish';
 const CONFIG_KEY = 'warnNonNeutralSpanish';
 
 const MAX_REPORTED_MARKERS = 8;
-
-// Escape hatch: when a written file legitimately needs regional text (a literal quote, a
-// test fixture, a captured log, a data sample), placing this marker anywhere in the content
-// tells the gate the regional wording is intentional and lets the write through. A deny (as
-// opposed to the old warn) cannot "advise and let pass", so a legitimate case needs an
-// explicit, greppable opt-out — a marker the author writes on purpose, never one the agent
-// could infer. A project can override it via config (escapeHatch).
+const MIN_SPANISH_FUNCTION_WORDS = 3;
 const DEFAULT_ESCAPE_HATCH = 'neutral-spanish:allow';
+const DEFAULT_TEXT_EXTENSIONS = [
+  '.md',
+  '.mdx',
+  '.txt',
+  '.rst',
+  '.html',
+  '.htm',
+  '.adoc',
+  '.json',
+  '.yml',
+  '.yaml',
+];
+
+const SPANISH_FUNCTION_WORD = withUnicodeWordBoundary(
+  'que|de|la|el|los|las|para|con|una|por|como|también|está|más|este|esta|hay|muy|sin',
+);
 
 // Data strings, not identifiers — never add these to a cSpell dictionary.
 // neutral-spanish:allow — this list IS the marker data; the gate must not deny its own source.
-// Now that this gate DENIES (not warns), a marker must be unambiguously regional. Tokens that
-// also occur in neutral Spanish were removed: "de una" (matches "de una lista/vez"), "allá"
-// (standard across the whole language) — a false positive here blocks a legitimate write.
 const DEFAULT_REGIONAL_MARKERS = [
   'tenés',
   'podés',
@@ -54,9 +70,34 @@ const DEFAULT_REGIONAL_MARKERS = [
   'capaz que', // neutral-spanish:allow (marker data, not prose)
 ];
 
-function extractText(toolName, toolInput) {
-  if (!toolInGroups(toolName, ['write'])) return '';
-  return writtenContentOf(toolInput);
+function isSpanishProse(text) {
+  const global = new RegExp(
+    SPANISH_FUNCTION_WORD.source,
+    `${SPANISH_FUNCTION_WORD.flags}g`,
+  );
+  const distinct = new Set();
+  for (const match of text.matchAll(global)) {
+    distinct.add(match[0].toLowerCase());
+    if (distinct.size >= MIN_SPANISH_FUNCTION_WORDS) return true;
+  }
+  return false;
+}
+
+function hasTextExtension(path, textExtensions) {
+  const extension = extname(path).toLowerCase();
+  return textExtensions.some(
+    (candidate) => String(candidate).toLowerCase() === extension,
+  );
+}
+
+function markerHits(text, markers) {
+  const hits = [];
+  for (const marker of markers) {
+    if (typeof marker !== 'string' || marker.length === 0) continue;
+    if (withUnicodeWordBoundary(escapeRegExp(marker)).test(text))
+      hits.push(marker);
+  }
+  return hits;
 }
 
 runGate(
@@ -66,30 +107,27 @@ runGate(
     enabledByDefault: true,
     defaultParams: {
       regionalMarkers: DEFAULT_REGIONAL_MARKERS,
+      textExtensions: DEFAULT_TEXT_EXTENSIONS,
       escapeHatch: DEFAULT_ESCAPE_HATCH,
     },
   },
   ({ toolName, toolInput, parameters }) => {
-    const text = extractText(toolName, toolInput).toLowerCase();
+    if (!toolInGroups(toolName, ['write'])) return;
+    const text = writtenContentOf(toolInput);
     if (!text) return;
 
-    // Explicit opt-out for legitimate regional text (quote/fixture/log/data sample).
-    const escapeHatch = (
-      parameters.escapeHatch ?? DEFAULT_ESCAPE_HATCH
-    ).toLowerCase();
-    if (escapeHatch && text.includes(escapeHatch)) return;
+    const escapeHatch = parameters.escapeHatch ?? DEFAULT_ESCAPE_HATCH;
+    if (escapeHatch && text.toLowerCase().includes(escapeHatch.toLowerCase()))
+      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);
-    }
+    const path = writtenPathOf(toolInput);
+    if (
+      !hasTextExtension(path, parameters.textExtensions) &&
+      !isSpanishProse(text)
+    )
+      return;
 
+    const hits = markerHits(text, parameters.regionalMarkers);
     if (hits.length === 0) return;
 
     const unique = [...new Set(hits)].slice(0, MAX_REPORTED_MARKERS);
@@ -97,8 +135,8 @@ runGate(
       CONFIG_KEY,
       `Text being written contains regional Spanish markers: ${unique.join(', ')}. ` +
         'Rewrite in neutral Spanish before writing. If the regional wording is intentional ' +
-        `(a literal quote, a test fixture, a captured log, a data sample), add the marker ` +
-        `"${parameters.escapeHatch ?? DEFAULT_ESCAPE_HATCH}" somewhere in the content to allow it.`,
+        '(a literal quote, a test fixture, a captured log, a data sample), add the marker ' +
+        `"${escapeHatch}" somewhere in the content to allow it.`,
     );
   },
 );

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

@@ -1,59 +1,64 @@
+// never-assume — conjecture phrasing in a brief or in written code gets a reminder to verify.
+// Advisory only: a guess is a prompt to check, never a blocker. Every pattern (default or
+// configured) is word-bounded, so "might benefit" does not trip "might be".
+
 import {
   runGate,
   warn,
   toolInGroups,
   writtenContentOf,
   delegationPromptOf,
+  compileRegex,
 } from '../../lib/hook-io.mjs';
 import { CONJECTURE_SOURCES } from '../../lib/signals.mjs';
 
 const GATE_ID = 'never-assume';
 const CONFIG_KEY = 'requireVerificationBeforeAssuming';
 
-// Bilingual (ES+EN) conjecture phrasing, centralized in lib/signals.mjs so every gate
-// that needs to recognize unverified-assumption prose shares the same coverage. See
-// signals.mjs header for the ES/EN-only limitation.
-const DEFAULT_CONJECTURE_PATTERNS = CONJECTURE_SOURCES;
-
 function extractContent(toolName, toolInput) {
   if (toolInGroups(toolName, ['delegation']))
     return delegationPromptOf(toolInput);
   return writtenContentOf(toolInput);
 }
 
+// Same boundary as signals.withUnicodeWordBoundary, applied per source so an invalid
+// config entry is skipped instead of poisoning the whole alternation.
+function boundedPattern(source) {
+  if (typeof source !== 'string' || source.length === 0) return null;
+  return compileRegex(
+    `(?<![\\p{L}\\p{N}_])(?:${source})(?![\\p{L}\\p{N}_])`,
+    'iu',
+  );
+}
+
 runGate(
   {
     id: GATE_ID,
     configKey: CONFIG_KEY,
     enabledByDefault: false,
+    severity: 'warn',
     defaultParams: {
-      conjecturePatterns: DEFAULT_CONJECTURE_PATTERNS,
+      conjecturePatterns: CONJECTURE_SOURCES,
     },
   },
   ({ toolName, toolInput, parameters }) => {
-    const isWrite = toolInGroups(toolName, ['write']);
-    const isDelegation = toolInGroups(toolName, ['delegation']);
-    if (!isWrite && !isDelegation) return;
+    if (!toolInGroups(toolName, ['write', 'delegation'])) return;
 
     const content = extractContent(toolName, toolInput);
     if (!content) return;
 
-    const patterns = parameters.conjecturePatterns.map(
-      (source) => new RegExp(source, 'i'),
-    );
     const hits = [];
-    for (const pattern of patterns) {
-      const match = content.match(pattern);
+    for (const source of parameters.conjecturePatterns) {
+      const match = boundedPattern(source)?.exec(content);
       if (match) hits.push(match[0]);
     }
     if (hits.length === 0) return;
 
     warn(
       CONFIG_KEY,
-      `Content contains conjecture phrasing without stated verification: ${hits.join(', ')}. Verify before asserting instead of assuming.`,
+      `Content contains conjecture phrasing without stated verification: ${hits.join(', ')}. ` +
+        'Verify before asserting instead of assuming. This is advisory; to change the ' +
+        `phrases, set conjecturePatterns for ${CONFIG_KEY} in .ai/config.json.`,
     );
   },
 );
-
-// The source guard (guard-never-assume.mjs) is explicit: this never denies,
-// only warns — conjecture language is a prompt to verify, not a blocker.

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

@@ -1,117 +1,179 @@
-// no-blocking — denies syntactic forms of waiting in the foreground (sleeping, polling
-// loops, following unbounded output, foreground dev servers) on a real shell command and
-// on a delegation prompt (a subagent can be told "wait with sleep" in prose). Migrated
-// from ~/.claude/hooks/guard-no-blocking.mjs. Off by default: a project opts in, because
-// many legitimate workflows still need a bounded wait the project accepts as normal.
-//
-// This gate only recognizes SYNTACTIC forms of waiting — it never judges whether other
-// work was available meanwhile, because that is judgment, not a fact a regex can read.
-// A gate that misfires on the legitimate case gets disabled, taking every real catch
-// down with it.
-//
-// ── What a project can configure (params) ───────────────────────────────────────────
-//   blockingPatterns      regex sources (matched case-insensitively) of blocking/waiting
-//                         forms to deny. Replaces the built-in list wholesale.
-//   waitJustifiedMarker   a marker token that, present in the command with a reason,
-//                         escapes the block — a declared wait is a decision, not an
-//                         oversight. Replaces the built-in marker wholesale.
-// The defaults live here, in the source, so a project reads them and knows exactly what
-// its override replaces.
+// no-blocking — denies syntactic forms of waiting in the foreground (sleeping, polling loops,
+// following unbounded output, foreground dev servers, Windows pauses) on a real shell command
+// and on a delegation prompt that orders one. Off by default: a project opts in. Deliberate
+// limits: only SYNTACTIC waiting is recognized, never whether other work was available
+// meanwhile; each command segment is judged on its own, so a detach form (`&`, nohup,
+// Start-Job, --detach) exempts only the segment it is in, and only the real
+// `run_in_background: true` flag exempts the whole call — the words in the command do not.
 
+import { hasRealCommandIntent } from '../../lib/delegation.mjs';
 import {
-  runGate,
+  compileRegex,
+  delegationPromptOf,
   deny,
+  escapeRegExp,
+  normalizeRulePairs,
+  runGate,
+  shellCommandOf,
   toolInGroups,
-  delegationPromptOf,
 } from '../../lib/hook-io.mjs';
 
 const GATE_ID = 'no-blocking';
 const CONFIG_KEY = 'blockWaitingCommands';
 
 const DEFAULT_WAIT_JUSTIFIED_MARKER = 'WAIT-JUSTIFIED:';
+const DEFAULT_REASON = 'Blocking/waiting command is not allowed.';
 
-// systemd's log-follow command, assembled from fragments so the spell checker does not
-// read it as prose (the project keeps an empty dictionary by policy).
-const SYSTEMD_LOG_COMMAND = 'journal' + 'ctl';
+// Where a command may begin inside a segment or a sentence: the start, after a control word,
+// or after a separator a prompt may still carry.
+const COMMAND_START = String.raw`(?:^|[|;&(]\s*|\b(?:then|do|else)\s+)`;
+const FOLLOW_COMMANDS =
+  '(?:tail|journalctl|kubectl\\s+logs|docker(?:-compose|\\s+compose)?\\s+logs)';
 
-/** Blocking rules as `[regexSource, reason]`, matched case-insensitively. */
 const DEFAULT_BLOCKING_PATTERNS = [
   [
-    String.raw`(^|[|;&]\s*|\bthen\s+|\bdo\s+)(sleep|timeout)\s+\d`,
+    `${COMMAND_START}sleep\\s`,
     'Sleeping in the foreground spends the turn doing nothing. If waiting for something ' +
       'to finish, launch it in the background and move on to something else; if waiting ' +
       'on an external condition, use a monitor.',
   ],
+  [
+    `${COMMAND_START}timeout(?:\\.exe)?\\s+(?:/t\\s+)?\\d+(?:\\s+/nobreak)?\\s*$`,
+    "'timeout N' with no command is a sleep. Wrap a real command (timeout 120 npm test) " +
+      'or launch the wait in the background.',
+  ],
   [
     String.raw`\bStart-Sleep\b`,
     'Start-Sleep freezes the turn. Launch the work in the background and continue with ' +
       'whatever does not depend on it.',
   ],
   [
-    String.raw`(^|[|;&]\s*)wait\b|--wait\b|\bWait-Process\b|\bWait-Job\b`,
+    String.raw`${COMMAND_START}wait\b|\s--wait\b|\bWait-Process\b|\bWait-Job\b|\bStart-Process\b[^|;\n]*\s-Wait\b`,
     'Waiting for another process to finish blocks the whole turn. Launch it in the ' +
       'background and consume the result when it arrives, not before.',
   ],
   [
-    [
-      String.raw`\b(tail|`,
-      SYSTEMD_LOG_COMMAND,
-      String.raw`|kubectl\s+logs|docker\s+logs)\b[^|;&]*\s-{1,2}f\b`,
-    ].join(''),
+    String.raw`\b${FOLLOW_COMMANDS}\b[^|;&\n]*\s(?:-[a-z]*f[a-z]*|--follow)(?=\s|$)`,
     'Following live output never returns and takes the turn with it. Read the file once, ' +
       'or leave the following to a background process.',
   ],
   [
-    String.raw`(^|[|;&]\s*)watch\s+`,
+    `${COMMAND_START}watch\\s+`,
     "'watch' repeats forever and blocks. Run the command once; if a change genuinely " +
       'needs watching, use a monitor that does not take the turn.',
   ],
   [
-    String.raw`\b(until|while)\b[^\n]{0,80}\bdo\b[^\n]{0,80}\bsleep\b`,
+    String.raw`\b(?:until|while)\b[\s\S]{0,80}\bdo\b[\s\S]{0,80}\bsleep\b`,
     'A loop that sleeps waiting for something to change is foreground polling: it blocks ' +
       'and it spins. Use a monitor with the condition, or launch the work in the ' +
       'background and wait for its notification.',
   ],
   [
-    String.raw`\b(npm|pnpm|yarn|bun)\s+(run\s+)?(dev|start|serve|watch)\b`,
+    String.raw`\b(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?(?:dev|start|serve|watch)(?=\s|$)`,
     'A dev server does not end on its own: in the foreground it takes the turn until ' +
       'something kills it. Launch it in the background and keep working while it comes up.',
   ],
+  [
+    String.raw`${COMMAND_START}ping\b[^|;&\n]*\s-n\s+\d{2,}\b|${COMMAND_START}pause\b|\bRead-Host\b`,
+    'A ping loop, pause or Read-Host waits on the clock or on a keyboard nobody is at. ' +
+      'Remove the wait; if something must be awaited, do it in the background.',
+  ],
 ];
 
-// Marks that a command will not take the turn: backgrounded, detached, or bounded. The bare
-// `-d` token was removed: it matched any -d flag (e.g. `curl -d payload`), letting an
-// unrelated flag whitelist a genuine foreground `sleep`. Detached forms are now matched
-// explicitly (--detach, docker/compose -d at a word boundary before end/pipe), and PowerShell's
-// Start-Job / Start-Process -NoNewWindow backgrounding is recognized.
-// One big alternation trips the linter's regex-complexity check, so each background form is
-// its own short regex tested with `.some()` — matching EXACTLY what the combined pattern did
-// (verified case-by-case). Order does not matter: any one match means the command detaches.
-const NOT_TAKING_THE_TURN_FORMS = [
-  /&\s*$/i,
+// ── Shell segments ──────────────────────────────────────────────────────────────────
+// A lone `&` backgrounds the segment before it; `>&` and `&>` are redirections, not separators.
+const SEPARATOR_PATTERN = /(\|\||&&|\||;|\n|(?<!>)&(?![&>]))/;
+const SHELL_WRAPPER_PATTERN =
+  /^(?:sh|bash|zsh|dash|ksh)\s+(-\w+)\s+(?:"([^"]*)"|'([^']*)')/i;
+const DETACHED_SEGMENT_FORMS = [
   /\bnohup\b/i,
   /\bstart\s+\/b\b/i,
   /--detach\b/i,
-  /\b-d(?=\s*($|[|;&]))/i,
+  /^docker(?:-compose|\s+compose)?\b[^|;\n]*\s-d(?=\s|$)/i,
   /\bStart-Job\b/i,
-  /\bStart-Process\b[^|;\n]*-NoNewWindow\b/i,
-  /\brun_in_background\b/i,
 ];
 
-function detachesFromTurn(command) {
-  return NOT_TAKING_THE_TURN_FORMS.some((pattern) => pattern.test(command));
+function stripGrouping(text) {
+  let stripped = text.trim();
+  while (stripped.startsWith('(') || stripped.startsWith('$('))
+    stripped = stripped.replace(/^\$?\(/, '').trim();
+  while (stripped.endsWith(')')) stripped = stripped.slice(0, -1).trimEnd();
+  return stripped;
+}
+
+function shellSegments(command) {
+  const parts = String(command).split(SEPARATOR_PATTERN);
+  const segments = [];
+  for (let index = 0; index < parts.length; index += 2) {
+    const text = stripGrouping(parts[index]);
+    if (!text) continue;
+    const sentToBackground = parts[index + 1] === '&';
+    const wrapped = SHELL_WRAPPER_PATTERN.exec(text);
+    if (wrapped && wrapped[1].includes('c')) {
+      for (const inner of shellSegments(wrapped[2] ?? wrapped[3]))
+        segments.push({
+          text: inner.text,
+          detached: sentToBackground || inner.detached,
+        });
+      continue;
+    }
+    const detached =
+      sentToBackground ||
+      DETACHED_SEGMENT_FORMS.some((form) => form.test(text));
+    segments.push({ text, detached });
+  }
+  return segments;
+}
+
+// ── Rules ───────────────────────────────────────────────────────────────────────────
+function blockingRules(parameters) {
+  return normalizeRulePairs(parameters.blockingPatterns, DEFAULT_REASON)
+    .map(({ source, reason }) => ({ pattern: compileRegex(source), reason }))
+    .filter((rule) => rule.pattern !== null);
+}
+
+function isJustified(text, marker) {
+  if (!marker) return false;
+  const reasonAfterMarker = String.raw`\s*\S+\s+\S+`;
+  return new RegExp(`${escapeRegExp(marker)}${reasonAfterMarker}`, 'i').test(
+    text,
+  );
+}
+
+function denyBlocking(reason, marker, matched) {
+  deny(
+    CONFIG_KEY,
+    `${reason} (matched: "${matched.trim()}") Launch it with run_in_background: true, or ` +
+      `if this wait is genuinely justified add "${marker} <concrete reason>" to the command. ` +
+      'A declared wait is a decision; a silent one is an oversight.',
+  );
 }
 
-function compile(source) {
-  return new RegExp(source, 'i');
+function checkShellCommand(command, parameters, marker) {
+  const foreground = shellSegments(command)
+    .filter((segment) => !segment.detached)
+    .map((segment) => segment.text);
+  if (foreground.length === 0) return;
+  // The joined text lets a rule see a loop whose body sits in another segment.
+  const candidates =
+    foreground.length > 1 ? [...foreground, foreground.join('\n')] : foreground;
+  for (const { pattern, reason } of blockingRules(parameters)) {
+    for (const candidate of candidates) {
+      const match = pattern.exec(candidate);
+      if (match) denyBlocking(reason, marker, match[0]);
+    }
+  }
 }
 
-/** The text to inspect: a real command's command line, or the delegation prompt. */
-function commandTextFrom(toolName, toolInput) {
-  if (toolInGroups(toolName, ['shell'])) {
-    return String(toolInput.CommandLine ?? toolInput.command ?? '');
+function checkDelegationPrompt(prompt, parameters, marker) {
+  for (const { pattern, reason } of blockingRules(parameters)) {
+    if (hasRealCommandIntent(prompt, pattern))
+      denyBlocking(
+        `${reason} The delegation prompt orders the wait; a subagent must not do it either.`,
+        marker,
+        pattern.exec(prompt)?.[0] ?? '',
+      );
   }
-  return delegationPromptOf(toolInput);
 }
 
 runGate(
@@ -126,38 +188,17 @@ runGate(
   },
   ({ toolName, toolInput, parameters }) => {
     const isShell = toolInGroups(toolName, ['shell']);
-    const isDelegation = toolInGroups(toolName, ['delegation']);
-    if (!isShell && !isDelegation) return;
-
-    const command = commandTextFrom(toolName, toolInput);
-    if (!command.trim()) return;
-
-    // Already declared in the background: the turn stays free, which is all that matters.
+    if (!isShell && !toolInGroups(toolName, ['delegation'])) return;
+    const text = isShell
+      ? shellCommandOf(toolInput)
+      : delegationPromptOf(toolInput);
+    if (!text.trim()) return;
     if (toolInput.run_in_background === true) return;
-    if (detachesFromTurn(command)) return;
 
-    // A declared wait with its reason is a decision, not an oversight.
     const marker = String(parameters.waitJustifiedMarker ?? '');
-    if (marker) {
-      const escapedMarker = marker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-      const reasonAfterMarker = String.raw`\s*\S+\s+\S+`;
-      const justified = new RegExp(`${escapedMarker}${reasonAfterMarker}`, 'i');
-      if (justified.test(command)) return;
-    }
+    if (isJustified(text, marker)) return;
 
-    const blockingPairs = (parameters.blockingPatterns ?? []).map((entry) =>
-      Array.isArray(entry)
-        ? entry
-        : [entry, 'Blocking/waiting command is not allowed.'],
-    );
-    for (const [source, reason] of blockingPairs) {
-      if (compile(source).test(command)) {
-        deny(
-          CONFIG_KEY,
-          `${reason} If this wait is genuinely justified, add "${marker} <concrete reason>" ` +
-            'to the command and try again. A declared wait is a decision; a silent one is an oversight.',
-        );
-      }
-    }
+    if (isShell) checkShellCommand(text, parameters, marker);
+    else checkDelegationPrompt(text, parameters, marker);
   },
 );