@devrik-tools/claude-gates 0.7.2 → 0.9.0

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

@@ -0,0 +1,285 @@
+// circuit-breaker PostToolUse tracker — records a delegation attempt AFTER it was allowed
+// by all PreToolUse hooks (including this gate's own). A delegation rejected by another
+// gate (intent-flow, brief-before-delegate, etc.) never reaches PostToolUse, so it does
+// not inflate the retry counter. Without this split, the PreToolUse gate counted rejected
+// delegations as retries and tripped the breaker on the corrected second attempt.
+
+import { createHash } from 'node:crypto';
+import { isGateEnabled } from '../../lib/config.mjs';
+import {
+  allow,
+  delegationPromptOf,
+  readHookPayload,
+  sessionIdOf,
+  toolInputOf,
+  toolNameOf,
+  toolInGroups,
+} from '../../lib/hook-io.mjs';
+import {
+  readSessionState,
+  writeSessionState,
+} from '../../lib/session-state.mjs';
+
+const GATE_ID = 'circuit-breaker';
+const CONFIG_KEY = 'requireCircuitBreakerOnDelegation';
+
+const MAX_ENTRIES_PER_KEY = 12;
+const MIN_TOKEN_LENGTH = 2;
+
+const SECTION_HEADING_NAMES = [
+  'scope',
+  'steps',
+  'haceres',
+  'output',
+  'criteria',
+  'criterio',
+  'handoff',
+  'out of scope',
+  'in scope',
+  'que no',
+  'que si',
+  'que sí',
+  'edge cases',
+  'casos borde',
+];
+
+function headingNamePattern(name) {
+  return new RegExp(
+    name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/ /g, '\\s+'),
+    'i',
+  );
+}
+
+const HEADING_NAME_PATTERNS = SECTION_HEADING_NAMES.map(headingNamePattern);
+
+function indexOfSectionMarker(text) {
+  let earliest = -1;
+  for (const namePattern of HEADING_NAME_PATTERNS) {
+    const match = namePattern.exec(text);
+    if (!match) continue;
+    const after = text.slice(match.index + match[0].length);
+    if (!/^\s*:/.test(after)) continue;
+    if (earliest === -1 || match.index < earliest) earliest = match.index;
+  }
+  return earliest;
+}
+
+const LEVEL_LINE_PATTERNS = [
+  new RegExp('^level\\s*:?$', 'i'),
+  new RegExp('^nivel\\s*:?$', 'i'),
+];
+
+function stripLeadingMarkup(line) {
+  return line
+    .trim()
+    .replace(/^#{1,4}\s*/, '')
+    .replace(/^[-*]\s*/, '')
+    .replace(/^\*\*/, '');
+}
+
+function isScaffoldingLine(line) {
+  const stripped = stripLeadingMarkup(line);
+  if (LEVEL_LINE_PATTERNS.some((pattern) => pattern.test(stripped)))
+    return true;
+  return HEADING_NAME_PATTERNS.some((namePattern) => {
+    const match = namePattern.exec(stripped);
+    return (
+      match &&
+      match.index === 0 &&
+      /^\s*:?$/.test(stripped.slice(match[0].length))
+    );
+  });
+}
+
+const GOAL_HEADING_PATTERN = /^(objetivo|goal|meta):(.*)$/i;
+const IN_SCOPE_HEADING_PATTERN = /^(que\s+s[ií]|in\s+scope|lo\s+pedido)\b/i;
+
+function isEndOfInScope(line) {
+  const stripped = stripLeadingMarkup(line);
+  return HEADING_NAME_PATTERNS.some((namePattern) => {
+    const match = namePattern.exec(stripped);
+    return match && match.index === 0;
+  });
+}
+
+function contentAfterHeading(line) {
+  const colon = line.indexOf(':');
+  return colon === -1 ? '' : line.slice(colon + 1).trim();
+}
+
+const STOP_WORDS = new Set(
+  (
+    'de la el los las un una unos unas y o a en del al lo que se su sus por para con como es son ser este esta ' +
+    'esto ese esa eso mas si no ni pero cuando donde cual cuales hay hace hacer debe deben debes puede pueden ' +
+    'the of to and in for on with a an is are be it its this that'
+  ).split(' '),
+);
+
+function stripDiacritics(text) {
+  return text.normalize('NFD').replace(/\p{M}/gu, '');
+}
+
+function tokenize(text) {
+  return stripDiacritics(String(text).toLowerCase())
+    .split(/[^a-z0-9]+/)
+    .filter(
+      (token) => token.length >= MIN_TOKEN_LENGTH && !STOP_WORDS.has(token),
+    );
+}
+
+const WINDOWS_DRIVE_PATH_PATTERN = /[A-Za-z]:[\\/][^\s"'`,;)\]]+/g;
+const KNOWN_EXTENSIONS = [
+  'mjs',
+  'cjs',
+  'json',
+  'jsx',
+  'js',
+  'mts',
+  'cts',
+  'tsx',
+  'ts',
+  'vue',
+  'md',
+  'py',
+  'sh',
+  'ps1',
+  'yaml',
+  'yml',
+  'toml',
+  'sql',
+  'css',
+  'html',
+];
+const KNOWN_EXTENSION_FILENAME_PATTERN = new RegExp(
+  `[\\w-]+\\.(?:${KNOWN_EXTENSIONS.join('|')})\\b`,
+  'g',
+);
+const PATH_LIKE_RUN_PATTERN = /[\w./\\-]+/g;
+const TRAILING_PUNCTUATION = new Set(['.', ',', ';', ':', ')', ']']);
+
+function looksLikeRelativePath(run) {
+  return /[\\/]/.test(run) && !/^[\\/]+$/.test(run);
+}
+
+function stripTrailingPunctuation(text) {
+  let end = text.length;
+  while (end > 0 && TRAILING_PUNCTUATION.has(text[end - 1])) end -= 1;
+  return text.slice(0, end);
+}
+
+function mentionedPaths(prompt) {
+  const found = new Set();
+  const text = String(prompt);
+  const fixedShapeMatches = [
+    WINDOWS_DRIVE_PATH_PATTERN,
+    KNOWN_EXTENSION_FILENAME_PATTERN,
+  ].flatMap((pattern) => text.match(pattern) ?? []);
+  const relativePathMatches = (text.match(PATH_LIKE_RUN_PATTERN) ?? []).filter(
+    looksLikeRelativePath,
+  );
+  for (const raw of [...fixedShapeMatches, ...relativePathMatches]) {
+    const normalized = stripTrailingPunctuation(
+      stripDiacritics(raw.toLowerCase()).replace(/\\/g, '/'),
+    );
+    const base = normalized.split('/').filter(Boolean).pop();
+    if (base && /[a-z0-9]/.test(base)) found.add(base);
+  }
+  return [...found].sort();
+}
+
+function identityText(prompt) {
+  const lines = String(prompt).split(/\r?\n/);
+  const parts = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const strippedLine = stripLeadingMarkup(lines[index])
+      .replace(/\*\*\s*/g, '')
+      .replace(' :', ':');
+    const goal = strippedLine.match(GOAL_HEADING_PATTERN);
+    if (goal) {
+      const goalText = goal[2].trim();
+      const cut = indexOfSectionMarker(goalText);
+      parts.push(cut > 0 ? goalText.slice(0, cut) : goalText);
+      continue;
+    }
+    if (IN_SCOPE_HEADING_PATTERN.test(strippedLine)) {
+      parts.push(contentAfterHeading(strippedLine));
+      for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
+        if (isEndOfInScope(lines[cursor])) break;
+        parts.push(lines[cursor]);
+      }
+    }
+  }
+  return parts.join(' ').trim();
+}
+
+function textWithoutScaffolding(prompt) {
+  return String(prompt)
+    .split(/\r?\n/)
+    .filter((line) => !isScaffoldingLine(line))
+    .join(' ')
+    .trim();
+}
+
+function identitySignature(prompt) {
+  const identity =
+    identityText(prompt) || textWithoutScaffolding(prompt) || String(prompt);
+  const tokens = tokenize(identity);
+  const features = [];
+  if (tokens.length >= 2) {
+    for (let index = 0; index < tokens.length - 1; index += 1)
+      features.push(`${tokens[index]} ${tokens[index + 1]}`);
+  } else {
+    features.push(...tokens);
+  }
+  for (const path of mentionedPaths(prompt))
+    features.push(`path:${path}`, `path:${path}`);
+  return features;
+}
+
+function identityKey(signature) {
+  return createHash('sha256').update(signature.join(' ')).digest('hex');
+}
+
+function occurrencesFor(state, key) {
+  const value = state[key];
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry) => entry && Array.isArray(entry.signature));
+}
+
+function main() {
+  const rawPayload = readHookPayload();
+  if (rawPayload === null) allow();
+  const toolName = toolNameOf(rawPayload) ?? '';
+  if (!toolInGroups(toolName, ['delegation'])) allow();
+
+  const cwd = process.cwd();
+  if (!isGateEnabled(CONFIG_KEY, false, cwd)) allow();
+
+  const toolInput = toolInputOf(rawPayload);
+  const prompt = delegationPromptOf(toolInput);
+  if (!prompt.trim()) allow();
+
+  const sessionId = sessionIdOf(rawPayload);
+  const stateOptions = { cwd };
+  const state = readSessionState(GATE_ID, sessionId, {}, stateOptions);
+  const signature = identitySignature(prompt);
+  const key = identityKey(signature);
+
+  const occurrences = [
+    ...occurrencesFor(state, key),
+    { signature, seenAt: Date.now() },
+  ].slice(-MAX_ENTRIES_PER_KEY);
+  writeSessionState(
+    GATE_ID,
+    sessionId,
+    { ...state, [key]: occurrences },
+    stateOptions,
+  );
+  allow();
+}
+
+try {
+  main();
+} catch {
+  allow();
+}

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

@@ -1,15 +1,23 @@
-import { readdirSync } from 'node:fs';
-import { join } from 'node:path';
+// dependency-skills — a dependency that is NEW to the project must be covered by a skill.
+// Only the delta counts: a rewrite of package.json that keeps every existing dependency is
+// not "adding" anything, so the gate compares what will be written (or installed from the
+// shell) against the package.json already on disk. A version bump is never a new dependency.
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { basename, isAbsolute, join } from 'node:path';
+import { projectRootOf } from '../../lib/config.mjs';
 import {
   runGate,
   deny,
   toolInGroups,
   writtenPathOf,
   writtenContentOf,
+  shellCommandOf,
 } from '../../lib/hook-io.mjs';
 
 const GATE_ID = 'dependency-skills';
 const CONFIG_KEY = 'requireSkillForNewDependency';
+const PACKAGE_FILE = 'package.json';
 
 const DEFAULT_DEPS_WITHOUT_OWN_API = [
   'clsx',
@@ -22,6 +30,15 @@ const DEFAULT_DEPS_WITHOUT_OWN_API = [
   'regenerator-runtime',
 ];
 
+const INSTALL_COMMANDS = [
+  { manager: 'npm', verbs: ['i', 'install', 'add'] },
+  { manager: 'pnpm', verbs: ['add'] },
+  { manager: 'yarn', verbs: ['add'] },
+  { manager: 'bun', verbs: ['add'] },
+];
+const REGISTRY_NAME_PATTERN = /^(?:@[\w.-]+\/)?[\w.-]+$/;
+const SEGMENT_SEPARATOR = /&&|\|\||[;|\n]/;
+
 function normalize(name) {
   return name.replace(/^@/, '').replace(/\//g, '-').toLowerCase();
 }
@@ -31,21 +48,23 @@ function isExempt(dependencyName, dependenciesWithoutOwnApi) {
   return dependenciesWithoutOwnApi.includes(dependencyName);
 }
 
+// statSync (not Dirent.isDirectory) so a skill installed as a junction/symlink counts.
 function listSkillDirectories(skillsDirectoryPath) {
   try {
-    return readdirSync(skillsDirectoryPath, { withFileTypes: true })
-      .filter((entry) => entry.isDirectory())
-      .map((entry) => entry.name);
+    return readdirSync(skillsDirectoryPath).filter((name) => {
+      try {
+        return statSync(join(skillsDirectoryPath, name)).isDirectory();
+      } catch {
+        return false;
+      }
+    });
   } 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.
+// A skill covers a dependency when its normalized name equals the dependency's or contains
+// it as a whole `-` segment; bidirectional substring matching let `rip` cover `stripe`.
 function skillNameMatches(normalizedDependency, skillDirectoryName) {
   const normalizedSkill = normalize(skillDirectoryName);
   if (normalizedSkill === normalizedDependency) return true;
@@ -59,25 +78,100 @@ function hasMatchingSkill(dependencyName, skillDirectories) {
   );
 }
 
-function needsSkillReview(dependencyName, parameters, skillDirectories) {
-  if (isExempt(dependencyName, parameters.depsWithoutOwnApi)) return false;
-  return !hasMatchingSkill(dependencyName, skillDirectories);
+function dependencyNamesOf(parsed) {
+  if (!parsed || typeof parsed !== 'object') return [];
+  const names = new Set();
+  for (const field of ['dependencies', 'devDependencies']) {
+    const block = parsed[field];
+    if (!block || typeof block !== 'object' || Array.isArray(block)) continue;
+    for (const name of Object.keys(block)) names.add(name);
+  }
+  return [...names];
 }
 
-/** Parsed `package.json` dependency names, or null when it cannot be read yet. */
-function dependencyNamesIn(content) {
-  let parsed;
+function parseJsonOrNull(text) {
   try {
-    parsed = JSON.parse(content);
+    return JSON.parse(text);
   } 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);
+}
+
+function readTextOrEmpty(path) {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function applyEdit(base, edit) {
+  const oldString = String(edit.old_string ?? '');
+  const newString = String(edit.new_string ?? '');
+  if (!oldString) return base || newString;
+  if (edit.replace_all) return base.split(oldString).join(newString);
+  const at = base.indexOf(oldString);
+  if (at === -1) return base;
+  return base.slice(0, at) + newString + base.slice(at + oldString.length);
+}
+
+function writtenPackageText(toolInput, diskText) {
+  if (Array.isArray(toolInput.edits)) {
+    return toolInput.edits.reduce(
+      (text, edit) => applyEdit(text, edit ?? {}),
+      diskText,
+    );
+  }
+  if (typeof toolInput.old_string === 'string')
+    return applyEdit(diskText, toolInput);
+  return writtenContentOf(toolInput);
+}
+
+function packageNameOf(token) {
+  const versionAt = token.indexOf('@', token.startsWith('@') ? 1 : 0);
+  const name = versionAt === -1 ? token : token.slice(0, versionAt);
+  return REGISTRY_NAME_PATTERN.test(name) ? name : null;
+}
+
+function installedPackagesIn(command) {
+  const names = [];
+  for (const segment of command.split(SEGMENT_SEPARATOR)) {
+    const [manager = '', verb = '', ...rest] = segment.trim().split(/\s+/);
+    const spec = INSTALL_COMMANDS.find(
+      (candidate) => candidate.manager === manager.toLowerCase(),
+    );
+    if (!spec || !spec.verbs.includes(verb)) continue;
+    for (const token of rest) {
+      if (token.startsWith('-')) continue;
+      const name = packageNameOf(token);
+      if (name) names.push(name);
+    }
+  }
+  return names;
+}
+
+function resolveAgainst(root, path) {
+  return isAbsolute(path) ? path : join(root, path);
+}
+
+/** Dependencies the call introduces, or null when the written JSON is not parseable yet. */
+function newDependenciesOf(toolName, toolInput, root) {
+  if (toolInGroups(toolName, ['shell'])) {
+    const names = installedPackagesIn(shellCommandOf(toolInput));
+    if (names.length === 0) return [];
+    const disk = dependencyNamesOf(
+      parseJsonOrNull(readTextOrEmpty(join(root, PACKAGE_FILE))),
+    );
+    return names.filter((name) => !disk.includes(name));
+  }
+  if (!toolInGroups(toolName, ['write'])) return [];
+  const filePath = writtenPathOf(toolInput);
+  if (basename(filePath) !== PACKAGE_FILE) return [];
+  const diskText = readTextOrEmpty(resolveAgainst(root, filePath));
+  const written = parseJsonOrNull(writtenPackageText(toolInput, diskText));
+  if (written === null) return null;
+  const disk = dependencyNamesOf(parseJsonOrNull(diskText));
+  return dependencyNamesOf(written).filter((name) => !disk.includes(name));
 }
 
 runGate(
@@ -87,27 +181,21 @@ runGate(
     enabledByDefault: true,
     defaultParams: {
       depsWithoutOwnApi: DEFAULT_DEPS_WITHOUT_OWN_API,
-      projectSkillsDir: '.claude/skills',
+      projectSkillsDir: join('.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;
+  ({ toolName, toolInput, parameters, cwd }) => {
+    const root = projectRootOf(cwd) ?? cwd;
+    const newDependencies = newDependenciesOf(toolName, toolInput, root);
+    if (!newDependencies || newDependencies.length === 0) return;
 
     const skillDirectories = listSkillDirectories(
-      join(process.cwd(), parameters.projectSkillsDir),
+      resolveAgainst(root, parameters.projectSkillsDir),
     );
-
-    const unmatched = dependencyNames.filter((name) =>
-      needsSkillReview(name, parameters, skillDirectories),
+    const unmatched = newDependencies.filter(
+      (name) =>
+        !isExempt(name, parameters.depsWithoutOwnApi) &&
+        !hasMatchingSkill(name, skillDirectories),
     );
     if (unmatched.length === 0) return;
 
@@ -121,10 +209,3 @@ runGate(
     );
   },
 );
-
-// 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.

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

@@ -1,9 +1,17 @@
+// diagnosis-before-patch — a timeout/deadline/retry value that CHANGES gets a reminder to
+// bring the evidence first. Only a change counts: a new file, or a value that stays as it
+// is on disk, is not a symptom being patched. Advisory only, never a block.
+
+import { readFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { projectRootOf } from '../../lib/config.mjs';
 import {
   runGate,
   warn,
   toolInGroups,
   writtenContentOf,
   writtenPathOf,
+  compileRegexList,
 } from '../../lib/hook-io.mjs';
 
 const GATE_ID = 'diagnosis-before-patch';
@@ -17,9 +25,57 @@ const DEFAULT_TIMEOUT_PATTERNS = [
   String.raw`\b(query_?timeout|hard_?deadline)\b`,
 ];
 
-function extractText(toolName, toolInput) {
-  if (!toolInGroups(toolName, ['write'])) return '';
-  return writtenContentOf(toolInput);
+// From a pattern hit, the key and the numeric value that follows it (value may be empty).
+const ASSIGNMENT_PATTERN = /^([\w.$-]+)\s*[:=]?\s*['"]?([\d.]*)/;
+const ASSIGNMENT_WINDOW = 200;
+
+function assignmentsIn(text, patterns) {
+  const values = new Map();
+  for (const pattern of patterns) {
+    const global = new RegExp(pattern.source, `${pattern.flags}g`);
+    for (const match of text.matchAll(global)) {
+      const slice = text.slice(match.index, match.index + ASSIGNMENT_WINDOW);
+      const assignment = ASSIGNMENT_PATTERN.exec(slice);
+      if (!assignment) continue;
+      const [, key, value] = assignment;
+      if (!values.has(key)) values.set(key, value);
+    }
+  }
+  return values;
+}
+
+function changedKeys(before, after) {
+  const changes = [];
+  for (const [key, value] of after) {
+    if (before.has(key) && before.get(key) !== value)
+      changes.push({ key, from: before.get(key), to: value });
+  }
+  return changes;
+}
+
+function readTextOrNull(path) {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+// Edit-style tools carry old/new pairs; anything else is compared with the file on disk.
+function beforeAfterPairs(toolInput, root) {
+  if (Array.isArray(toolInput.edits)) {
+    return toolInput.edits.map((edit) => [
+      String(edit?.old_string ?? ''),
+      String(edit?.new_string ?? ''),
+    ]);
+  }
+  if (typeof toolInput.old_string === 'string') {
+    return [[toolInput.old_string, writtenContentOf(toolInput)]];
+  }
+  const path = writtenPathOf(toolInput);
+  if (!path) return [];
+  const onDisk = readTextOrNull(isAbsolute(path) ? path : join(root, path));
+  return onDisk === null ? [] : [[onDisk, writtenContentOf(toolInput)]];
 }
 
 runGate(
@@ -27,32 +83,38 @@ runGate(
     id: GATE_ID,
     configKey: CONFIG_KEY,
     enabledByDefault: true,
+    severity: 'warn',
     defaultParams: {
       timeoutPatterns: DEFAULT_TIMEOUT_PATTERNS,
     },
   },
-  ({ toolName, toolInput, parameters }) => {
-    const text = extractText(toolName, toolInput);
-    if (!text) return;
+  ({ toolName, toolInput, parameters, cwd }) => {
+    if (!toolInGroups(toolName, ['write'])) return;
+    const { patterns } = compileRegexList(parameters.timeoutPatterns);
+    if (patterns.length === 0) return;
 
-    const patterns = parameters.timeoutPatterns.map(
-      (source) => new RegExp(source, 'i'),
+    const root = projectRootOf(cwd) ?? cwd;
+    const changes = beforeAfterPairs(toolInput, root).flatMap(
+      ([before, after]) =>
+        changedKeys(
+          assignmentsIn(before, patterns),
+          assignmentsIn(after, patterns),
+        ),
     );
-    const matched = patterns
-      .map((pattern) => pattern.exec(text))
-      .find((match) => match !== null);
-    if (!matched) return;
+    if (changes.length === 0) return;
 
     const filePath = writtenPathOf(toolInput) || '(unknown path)';
+    const described = changes
+      .map((change) => `${change.key}: ${change.from} -> ${change.to}`)
+      .join(', ');
     warn(
       CONFIG_KEY,
-      `You are writing '${matched[0].trim()}' into ${filePath} — a timeout/deadline/retry ` +
-        'value. Before changing a value to fix a symptom ("X is slow/fails"), confirm you ' +
-        'have the evidence that proves the cause: a log line from the failing provider/' +
-        "process, not a hypothesis. If you don't have that log line yet, get it before " +
-        'writing this change — do not guess a new number. A timeout should measure ' +
-        'inactivity, not total time: a process that is still progressing should not be cut ' +
-        'off. This is a warning, not a block — the write proceeds either way.',
+      `You are changing a timeout/deadline/retry value in ${filePath} (${described}). ` +
+        'Before changing a value to fix a symptom ("X is slow/fails"), confirm you have ' +
+        'the evidence that proves the cause: a log line from the failing provider/process, ' +
+        "not a hypothesis. If you don't have that log line yet, get it before writing this " +
+        'change — do not guess a new number. A timeout should measure inactivity, not total ' +
+        'time. This is a warning, not a block — the write proceeds either way.',
     );
   },
 );

package/plugins/gates/hooks/gates/engram-first/index.mjs

@@ -0,0 +1,41 @@
+import { deny, runGate } from '../../lib/hook-io.mjs';
+import {
+  DEFAULT_PARAMS,
+  GATE_ID,
+  isResearchTool,
+  queryOf,
+  readState,
+} from './shared.mjs';
+
+const CONFIG_KEY = 'requireEngramBeforeResearch';
+
+const TOPIC_EXCERPT_LENGTH = 80;
+
+function denyResearchWithoutMemory(toolName, toolInput) {
+  const topic = queryOf(toolInput);
+  const suggestion = topic
+    ? ` (e.g. mem_search "${topic.slice(0, TOPIC_EXCERPT_LENGTH)}")`
+    : '';
+  deny(
+    CONFIG_KEY,
+    `${toolName} was called before any engram lookup in this session. Persistent memory is the ` +
+      `first source: call mem_search with the topic you are about to research${suggestion}. ` +
+      'If it returns nothing, research with context7 (libraries) or the web, then mem_save what ' +
+      'you learned before ending the turn.',
+  );
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: { ...DEFAULT_PARAMS },
+  },
+  ({ toolName, toolInput, sessionId, parameters, cwd }) => {
+    if (!isResearchTool(toolName, parameters)) return;
+    const state = readState(sessionId, cwd);
+    if (state.memSearchCount > 0) return;
+    denyResearchWithoutMemory(toolName, toolInput);
+  },
+);