@devrik-tools/claude-gates 0.7.2 → 0.8.0

package/plugins/gates/hooks/gates/implementation-pipeline/index.mjs

@@ -1,34 +1,34 @@
-// implementation-pipeline — denies a delegation that sends a builder subagent straight
-// to writing code without the prompt declaring the pipeline stages around it:
-// definition (where the context came from), writing's own verification plan, and a
-// separate reviewer for validation/QA/closure. Migrated from
-// ~/.claude/hooks/guard-pipeline-de-implementacion.mjs.
+// implementation-pipeline — denies a STANDARD/HIGH-RISK implementation delegation whose
+// prompt does not declare the pipeline around the build: where the context came from
+// (definition), what is verified and how (writing), and who reviews the result (reviewer).
 //
-// ── What a project can configure (params) ───────────────────────────────────────────
-//   builderSubagents   subagent types that count as builders — the ones this gate
-//                       holds to the pipeline. Replaces the built-in list wholesale.
-//   exemptSubagents     subagent types exempt outright: read-only pipeline stages that
-//                       cannot be required to declare a pipeline around themselves.
-//                       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 ───────────────────────────
-// This gate only evaluates a delegation whose prompt declares a STANDARD/HIGH-RISK
-// level, uses an implementation verb, targets a builder subagent, and is not about the
-// harness itself. A prompt that only describes work, or that is read-only/exploratory,
-// never reaches the check.
+// Decisions: every non-exempt subagent is a builder — an absent or unknown subagent_type is
+// not a reason to skip the check, only the exempt list is. A negated mention ("do not write
+// tests", "no brief.md yet") does not satisfy a stage. Work on the agent harness itself
+// (.claude/, .ai/, CLAUDE.md...) is exempt; ordinary app paths such as src/hooks/ are not.
 
+import {
+  DEFAULT_EXEMPT_SUBAGENTS,
+  DEMANDING_LEVELS,
+  LEVELS,
+  allMatches,
+  isHarnessWork,
+  isImplementationRequest,
+  isSubagentNamedIn,
+  operativeLevelOf,
+} from '../../lib/delegation.mjs';
 import {
   runGate,
   deny,
   toolInGroups,
   delegationPromptOf,
 } from '../../lib/hook-io.mjs';
+import { withUnicodeWordBoundary } from '../../lib/signals.mjs';
 
 const GATE_ID = 'implementation-pipeline';
 const CONFIG_KEY = 'requireImplementationPipeline';
 
+// Kept for config compatibility: every non-exempt type is held to the pipeline.
 const DEFAULT_BUILDER_SUBAGENTS = [
   'frontend',
   'backend',
@@ -37,46 +37,11 @@ const DEFAULT_BUILDER_SUBAGENTS = [
   'general-purpose',
 ];
 
-const DEFAULT_EXEMPT_SUBAGENTS = [
-  'scout',
-  'explore',
-  'plan',
-  'revision',
-  'contraste',
-  'test-planner',
-  'qa',
-  'ui',
-  'ux',
-];
-
-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*',
+const NEGATION_LOOK_BACK = 15;
+const NEGATION_PATTERN = withUnicodeWordBoundary(
+  "no|not|don'?t|do not|sin|never",
 );
 
-/** 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 HIGH_RISK_PATTERN =
-  /(nivel|level|clasificaci[oó]n|classification)[^\n]{0,25}?\bHIGH-RISK\b/iu;
-
-const HARNESS_PATTERN =
-  /(\.claude[\\/]|hooks[\\/]|plugins[\\/]gates|settings\.json|[\\/]agents[\\/]\w|[\\/]rules[\\/]\w|[\\/]skills[\\/]\w)/i;
-
 // Several small patterns instead of one long alternation: a single big regex here
 // tripped the linter's regex-complexity limit. Any one matching counts as declared.
 const REVIEWER_NAME_PATTERN =
@@ -103,18 +68,26 @@ const DEFINITION_PATTERN =
 const WRITING_PATTERN =
   /\b(test|tests|prueba|pruebas|vitest|jest|playwright|typecheck|lint|verification|verificaci[oó]n|verification criteria)\b/i;
 
-/** The three pipeline stages this gate requires be declared, in this order. */
+function isNegated(prompt, match) {
+  const from = Math.max(0, match.index - NEGATION_LOOK_BACK);
+  return NEGATION_PATTERN.test(prompt.slice(from, match.index));
+}
+
+function hasAffirmativeMention(prompt, pattern) {
+  return allMatches(pattern, prompt).some((match) => !isNegated(prompt, match));
+}
+
 const REQUIRED_STAGES = [
   {
     id: 'definition',
-    isDeclared: (prompt) => DEFINITION_PATTERN.test(prompt),
+    isDeclared: (prompt) => hasAffirmativeMention(prompt, DEFINITION_PATTERN),
     missing:
       'DEFINITION: does not declare where the context came from (a prior scout, read-only exploration, or an already-written asserts/brief).',
     line: 'Verified context: <path to the cited asserts/brief> — or: a prior scout ran, findings at <path>.',
   },
   {
     id: 'writing',
-    isDeclared: (prompt) => WRITING_PATTERN.test(prompt),
+    isDeclared: (prompt) => hasAffirmativeMention(prompt, WRITING_PATTERN),
     missing:
       'WRITING: does not declare what is verified nor with what command. A builder does not validate its own work without a criterion written beforehand.',
     line: 'Verification: <exact command> and what is expected. Anything that cannot run is reported OMITTED, never PASS.',
@@ -128,19 +101,11 @@ const REQUIRED_STAGES = [
   },
 ];
 
-function isExempt(toolInput, prompt, builderSubagents, exemptSubagents) {
-  const subagentType = String(
-    toolInput.subagent_type ?? toolInput.subagentType ?? '',
-  ).toLowerCase();
-  if (exemptSubagents.includes(subagentType)) return true;
-  // An unknown type is not assumed to be a builder: the safe side here is not to
-  // invent requirements for agents this gate cannot classify.
-  if (subagentType && !builderSubagents.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 isExempt(toolInput, prompt, exemptSubagents) {
+  if (isSubagentNamedIn(toolInput, exemptSubagents)) return true;
+  if (!DEMANDING_LEVELS.has(operativeLevelOf(prompt))) return true;
+  if (!isImplementationRequest(prompt)) return true;
+  return isHarnessWork(prompt);
 }
 
 runGate(
@@ -158,19 +123,14 @@ runGate(
 
     const prompt = delegationPromptOf(toolInput);
     if (!prompt.trim()) return;
-
-    const builderSubagents =
-      parameters.builderSubagents ?? DEFAULT_BUILDER_SUBAGENTS;
-    const exemptSubagents =
-      parameters.exemptSubagents ?? DEFAULT_EXEMPT_SUBAGENTS;
-    if (isExempt(toolInput, prompt, builderSubagents, exemptSubagents)) return;
+    if (isExempt(toolInput, prompt, parameters.exemptSubagents)) return;
 
     const missingStages = REQUIRED_STAGES.filter(
       (stage) => !stage.isDeclared(prompt),
     );
     if (missingStages.length === 0) return;
 
-    const isHighRisk = HIGH_RISK_PATTERN.test(prompt);
+    const isHighRisk = operativeLevelOf(prompt) === LEVELS.HIGH_RISK;
     const details = missingStages.map((stage) => stage.missing).join(' ');
     const lines = missingStages.map((stage) => `  ${stage.line}`).join('\n');
 

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

@@ -1,81 +1,38 @@
-// intent-flow — denies an implementation delegation that has real intent to mutate a
-// high-impact area (money, auth, persisted data, public contract, irreversible...)
-// without declaring IN SCOPE / OUT OF SCOPE / EDGE CASES, and hard-denies whenever it
-// also leaves a high-impact UNKNOWN unresolved.
+// intent-flow — denies an implementation delegation with real intent to mutate a high-impact
+// area (money, auth, persisted data, public contract, irreversible...) unless it declares
+// IN SCOPE / OUT OF SCOPE / EDGE CASES, and hard-denies when it also leaves a high-impact
+// UNKNOWN unresolved.
 //
-// ── How this differs from brief-before-delegate ─────────────────────────────────────
-// brief-before-delegate asks "was the task thought through" (goal+steps+criterion).
-// This gate asks a different, complementary question: "was the SCOPE declared — what
-// is in, what is explicitly out, and what edge cases were considered — for work that
-// really intends to touch a sensitive area?" Both run on the same delegation prompt
-// independently; neither depends on the other's verdict.
-//
-// ── Two-stage intent check (not lexical match) ──────────────────────────────────────
-// Stage 1 (cheap prefilter): does the raw prompt contain BOTH an implementation verb
-// and a high-impact signal anywhere? If not, there is no candidate — allow immediately.
-// Stage 2 (confirmation, only on candidates): strip quoted/templated text, then require
-// near co-occurrence between an implementation verb and a high-impact signal, and
-// discard a verb whose immediate object is a documentary deliverable (a doc/report/
-// README/.md/.html describing the area is not mutating it). Only surviving (a)+(b)+(c)
-// counts as real intent.
-//
-// ── readOnlySubagents is a declared label, not a verified capability ────────────────
-// This hook cannot check what tools a named subagent actually has — the whitelist
-// exemption is void whenever the prompt itself carries a mutation-risk signal (money/
-// auth/data/write/deploy): the signal in the text outranks the label on the call.
+// Decisions: brief-before-delegate asks "was the task thought through"; this gate asks the
+// complementary "was the SCOPE declared" and the two never depend on each other. Intent is
+// judged by the lib's two-stage check (verb + signal co-occurrence outside quoted text, with a
+// documentary object discarded), not by a bare keyword hit. A read-only subagent name is a
+// declared label, void whenever the prompt itself carries a mutation-risk signal. An empty
+// `highImpactPatterns` means nothing is high-impact, so the gate stays silent.
 
+import {
+  DEFAULT_HIGH_IMPACT_PATTERNS,
+  DEFAULT_READ_ONLY_SUBAGENTS,
+  buildHighImpactPattern,
+  hasRealSensitiveMutation,
+  isExemptQuery,
+  isImplementationRequest,
+  isReadOnlySubagent,
+  promptExcerpt,
+  stripQuoted,
+} from '../../lib/delegation.mjs';
 import {
   runGate,
   deny,
   toolInGroups,
   delegationPromptOf,
 } from '../../lib/hook-io.mjs';
-import { MUTATION_RISK_SIGNAL } from '../../lib/signals.mjs';
+import { withUnicodeWordBoundary } from '../../lib/signals.mjs';
 
 const GATE_ID = 'intent-flow';
 const CONFIG_KEY = 'requireScopeListBeforeDelegating';
 
-const DEFAULT_READ_ONLY_SUBAGENTS = ['explore', 'claude-code-guide', 'plan'];
-const DEFAULT_HIGH_IMPACT_PATTERNS = [
-  'dinero|pago|cobro|money|payment',
-  'auth|autenticaci[oó]n|authentication|permiso|permission|token|sesi[oó]n|session|seguridad|security|PII',
-  'borrar|delete|drop|migraci[oó]n|migration|schema',
-  'contrato|contract|irreversible|producci[oó]n|production|API p[uú]blica|public api',
-];
-
 const MIN_REQUEST_LENGTH = 40;
-const CO_OCCURRENCE_WINDOW = 100;
-const VERB_OBJECT_WINDOW = 60;
-// How much of an over-length prompt to quote back in a denial message.
-const PROMPT_EXCERPT_LENGTH = 80;
-
-function withUnicodeWordBoundary(alternatives) {
-  return new RegExp(
-    `(?<![\\p{L}\\p{N}_])(${alternatives})(?![\\p{L}\\p{N}_])`,
-    'iu',
-  );
-}
-
-// A prompt-level signal that a whitelisted read-only subagent name should NOT be
-// trusted to exempt this call: the name is a declared label, never a verified
-// capability this hook can check, and real mutation risk in the text must win over it.
-// Deliberately broad — over-including only means this gate's check still runs.
-// Centralized in lib/signals.mjs (ES+EN) — see its header for the class this covers.
-const MUTATION_RISK_SIGNAL_PATTERN = MUTATION_RISK_SIGNAL;
-
-const IMPLEMENTATION_VERBS = withUnicodeWordBoundary(
-  'implementa|implementar|implement(á|é)|agreg(a|á)|agregar|añad(e|í)|añadir|cre(a|á)|crear|' +
-    'arregl(a|á)|arreglar|cambi(a|á)|cambiar|migr(a|á)|migrar|escrib(í|e) c[oó]digo|escribir c[oó]digo|' +
-    'corrige|corregir|correg(í|ir)|constru(ye|í)|construir|modific(a|á)|modificar|' +
-    'refactoriz(a|á)|refactorizar|elimin(a|á)|eliminar|reescrib(e|í)|reescribir|desplieg(a|á)|desplegar|' +
-    'implement|build|fix|migrate|modify|refactor|remove|rewrite|deploy',
-);
-
-const QUERY_VERBS = withUnicodeWordBoundary(
-  'explica|explic(á|ar)|qu[eé]|c[oó]mo|muestra|mostr(á|ar)|analiza|analiz(á|ar)|investiga|' +
-    'investig(á|ar)|revisa|revis(á|ar)|audita|audit(á|ar)|diagnostica|diagnostic(á|ar)|' +
-    'explain|what|how|show|analyze|investigate|review|audit|diagnose',
-);
 
 const IN_SCOPE_PATTERN = withUnicodeWordBoundary(
   'qu[eé] s[ií]|qu[eé] s[ií] entra|alcance|in scope|lo pedido|se va a hacer|incluye',
@@ -92,78 +49,6 @@ const UNRESOLVED_UNKNOWN_PATTERN = withUnicodeWordBoundary(
   'unknown|no se sabe|no sabemos|sin resolver|no est[aá] claro|no est[aá] definido|' +
     'a definir|por definir|desconocido|no est[aá] decidido',
 );
-const DOCUMENTARY_DELIVERABLE_PATTERN = withUnicodeWordBoundary(
-  'documento|documentaci[oó]n|reporte|informe|diagrama|readme|wiki|changelog|' +
-    'p[aá]gina de documentaci[oó]n|archivo html|p[aá]gina html|markdown|document|documentation|report',
-);
-const DOCUMENTARY_EXTENSION_PATTERN = /\.(md|html?|adoc)\b/iu;
-
-function isReadOnlySubagentName(toolInput, readOnlySubagents) {
-  const type = String(
-    toolInput.subagent_type ?? toolInput.subagentType ?? '',
-  ).toLowerCase();
-  return new Set(readOnlySubagents.map((name) => name.toLowerCase())).has(type);
-}
-
-/** A whitelisted subagent name exempts a call ONLY when the prompt carries no
- * mutation-risk signal. The name is a declared label, never a verified capability this
- * hook can check — a real risk signal in the text must win over it. */
-function isReadOnlySubagent(toolInput, prompt, readOnlySubagents) {
-  if (!isReadOnlySubagentName(toolInput, readOnlySubagents)) return false;
-  return !MUTATION_RISK_SIGNAL_PATTERN.test(prompt);
-}
-
-function isImplementationRequest(prompt) {
-  return IMPLEMENTATION_VERBS.test(prompt);
-}
-
-function isExemptQuery(prompt) {
-  if (isImplementationRequest(prompt)) return false; // implementation verb takes priority
-  return QUERY_VERBS.test(prompt);
-}
-
-function stripQuoted(text) {
-  return text
-    .replace(/```[\s\S]*?```/g, ' ')
-    .replace(/"[^"\n]{0,300}"/g, ' ')
-    .replace(/'[^'\n]{0,300}'/g, ' ');
-}
-
-function allMatches(pattern, text) {
-  const flags = pattern.flags.includes('g')
-    ? pattern.flags
-    : `${pattern.flags}g`;
-  return [...text.matchAll(new RegExp(pattern.source, flags))];
-}
-
-function verbProducesDocument(text, verbMatch) {
-  const from = verbMatch.index;
-  const to = from + verbMatch[0].length + VERB_OBJECT_WINDOW;
-  const objectOfVerb = text.slice(from, to);
-  return (
-    DOCUMENTARY_DELIVERABLE_PATTERN.test(objectOfVerb) ||
-    DOCUMENTARY_EXTENSION_PATTERN.test(objectOfVerb)
-  );
-}
-
-function hasRealSensitiveMutation(prompt, highImpactPattern) {
-  const isCandidate =
-    IMPLEMENTATION_VERBS.test(prompt) && highImpactPattern.test(prompt);
-  if (!isCandidate) return false; // stage 1: cheap, no stage 2 spent
-
-  const text = stripQuoted(prompt); // stage 2(a)
-  const verbs = allMatches(IMPLEMENTATION_VERBS, text);
-  const signals = allMatches(highImpactPattern, text);
-
-  for (const verb of verbs) {
-    if (verbProducesDocument(text, verb)) continue; // stage 2(c)
-    for (const signal of signals) {
-      if (Math.abs(signal.index - verb.index) <= CO_OCCURRENCE_WINDOW)
-        return true; // stage 2(b)
-    }
-  }
-  return false;
-}
 
 function missingSignals(prompt) {
   const missing = [];
@@ -189,11 +74,9 @@ function denyUnresolvedUnknown() {
 }
 
 function denyTooShortForScopeList(prompt) {
-  const excerpt = prompt.slice(0, PROMPT_EXCERPT_LENGTH);
-  const ellipsis = prompt.length > PROMPT_EXCERPT_LENGTH ? '…' : '';
   deny(
     CONFIG_KEY,
-    `This implementation request ("${excerpt}${ellipsis}") does not carry a scope list: missing IN ` +
+    `This implementation request ("${promptExcerpt(prompt)}") does not carry a scope list: missing IN ` +
       'SCOPE, OUT OF SCOPE and EDGE CASES. Add it to the prompt before relaunching.',
   );
 }
@@ -206,15 +89,6 @@ function denyMissingSignals(missing) {
   );
 }
 
-function buildHighImpactPattern(highImpactPatterns) {
-  return new RegExp(
-    (highImpactPatterns ?? []).map((source) => `(?:${source})`).join('|'),
-    'iu',
-  );
-}
-
-/** True when this delegation is exempt from the whole check: not a recognizable
- * implementation request, a read-only subagent, or an exempt query. */
 function isExempt(toolInput, prompt, readOnlySubagents) {
   if (!prompt.trim()) return true;
   if (isReadOnlySubagent(toolInput, prompt, readOnlySubagents)) return true;

package/plugins/gates/hooks/gates/library-docs/index.mjs

@@ -0,0 +1,262 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { builtinModules } from 'node:module';
+import { extname, isAbsolute, join, relative } from 'node:path';
+import { projectRootOf } from '../../lib/config.mjs';
+import {
+  deny,
+  runGate,
+  toolInGroups,
+  writtenContentOf,
+  writtenPathOf,
+} from '../../lib/hook-io.mjs';
+import { readSessionState } from '../../lib/session-state.mjs';
+
+export const GATE_ID = 'library-docs';
+export const CONFIG_KEY = 'requireDocsBeforeUsingNewLibrary';
+
+const DEFAULT_CODE_EXTENSIONS = [
+  '.js',
+  '.mjs',
+  '.cjs',
+  '.ts',
+  '.tsx',
+  '.jsx',
+  '.vue',
+  '.svelte',
+  '.py',
+];
+const DEFAULT_IGNORED_PACKAGES = [];
+const DEFAULT_MAX_SCAN_FILES = 500;
+const SKIPPED_DIRECTORIES = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  'coverage',
+  '.next',
+  'out',
+  'vendor',
+  '.ai',
+]);
+const NODE_BUILTINS = new Set(
+  builtinModules.map((name) => name.replace(/^node:/, '')),
+);
+const PYTHON_STDLIB = new Set(
+  (
+    'os sys re json pathlib typing datetime time math random subprocess collections itertools ' +
+    'functools logging unittest dataclasses enum io shutil tempfile argparse asyncio threading ' +
+    'socket http urllib csv hashlib base64 uuid copy abc contextlib glob string textwrap ' +
+    'statistics decimal fractions pprint traceback warnings inspect importlib pickle sqlite3 ' +
+    'xml html email struct queue signal platform getpass secrets zipfile tarfile gzip ' +
+    'configparser operator heapq bisect array weakref types numbers cmath ast dis gc atexit ' +
+    'select ssl ftplib smtplib mimetypes unicodedata locale gettext calendar zoneinfo ' +
+    'concurrent multiprocessing builtins __future__ dataclasses'
+  ).split(' '),
+);
+
+const JS_IMPORT_PATTERNS = [
+  /\bimport\s+['"]([^'"\n]+)['"]/g,
+  /\bfrom\s+['"]([^'"\n]+)['"]/g,
+  /\brequire\(\s*['"]([^'"\n]+)['"]\s*\)/g,
+  /\bimport\(\s*['"]([^'"\n]+)['"]\s*\)/g,
+];
+const PY_IMPORT_LINE = /^import\s+([\w.]+)/;
+const PY_FROM_LINE = /^from\s+([\w.]+)\s+import\b/;
+
+function pythonSpecifiers(content) {
+  const found = [];
+  for (const rawLine of String(content ?? '').split(/\r?\n/)) {
+    const line = rawLine.trim();
+    const match = PY_IMPORT_LINE.exec(line) ?? PY_FROM_LINE.exec(line);
+    if (match) found.push(match[1]);
+  }
+  return found;
+}
+
+function javascriptSpecifiers(content) {
+  const found = [];
+  for (const pattern of JS_IMPORT_PATTERNS) {
+    for (const match of String(content ?? '').matchAll(pattern))
+      found.push(match[1]);
+  }
+  return found;
+}
+
+function packageOf(specifier, isPython) {
+  if (isPython) return specifier.split('.')[0];
+  if (specifier.startsWith('@'))
+    return specifier.split('/').slice(0, 2).join('/');
+  return specifier.split('/')[0];
+}
+
+function isExternal(specifier, isPython) {
+  if (!specifier || specifier.startsWith('.') || specifier.startsWith('/'))
+    return false;
+  if (specifier.startsWith('node:') || specifier.startsWith('#')) return false;
+  if (isPython) return !PYTHON_STDLIB.has(packageOf(specifier, true));
+  if (NODE_BUILTINS.has(packageOf(specifier, false))) return false;
+  if (/^[a-z]:[\\/]/i.test(specifier)) return false;
+  return true;
+}
+
+export function importedPackagesOf(content, filePath) {
+  const isPython = extname(filePath).toLowerCase() === '.py';
+  const specifiers = isPython
+    ? pythonSpecifiers(content)
+    : javascriptSpecifiers(content);
+  const packages = new Set();
+  for (const raw of specifiers) {
+    const specifier = raw.trim();
+    if (isExternal(specifier, isPython))
+      packages.add(packageOf(specifier, isPython));
+  }
+  return [...packages];
+}
+
+function* codeFiles(directory, extensions, budget) {
+  const stack = [directory];
+  while (stack.length > 0 && budget.left > 0) {
+    const current = stack.pop();
+    let entries;
+    try {
+      entries = readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const path = join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (!SKIPPED_DIRECTORIES.has(entry.name) && !entry.name.startsWith('.'))
+          stack.push(path);
+      } else if (extensions.includes(extname(entry.name).toLowerCase())) {
+        budget.left -= 1;
+        yield path;
+        if (budget.left === 0) return;
+      }
+    }
+  }
+}
+
+function packagesUsedElsewhere(root, writtenPath, extensions, maxFiles) {
+  const used = new Set();
+  const budget = { left: maxFiles };
+  for (const file of codeFiles(root, extensions, budget)) {
+    if (relative(file, writtenPath) === '') continue;
+    let content;
+    try {
+      content = readFileSync(file, 'utf8');
+    } catch {
+      continue;
+    }
+    for (const name of importedPackagesOf(content, file)) used.add(name);
+  }
+  return used;
+}
+
+function existingImports(absolutePath) {
+  if (!existsSync(absolutePath)) return new Set();
+  try {
+    if (!statSync(absolutePath).isFile()) return new Set();
+    return new Set(
+      importedPackagesOf(readFileSync(absolutePath, 'utf8'), absolutePath),
+    );
+  } catch {
+    return new Set();
+  }
+}
+
+function tokensOf(name) {
+  const lowered = name.toLowerCase();
+  const short = lowered.startsWith('@') ? lowered.split('/')[1] : lowered;
+  return [lowered, short, short.replace(/[-_.]/g, '')].filter(Boolean);
+}
+
+function mentions(list, name) {
+  const haystack = list.map((entry) => String(entry).toLowerCase());
+  return tokensOf(name).some((token) =>
+    haystack.some((entry) => entry.includes(token)),
+  );
+}
+
+export function knowledgeStatus(state, name) {
+  const searched = mentions(state.memSearchHits ?? [], name);
+  const documentation = mentions(state.context7Lookups ?? [], name);
+  const saved = mentions(state.memSaves ?? [], name);
+  return {
+    searched,
+    documentation,
+    saved,
+    known: searched || (documentation && saved),
+  };
+}
+
+function remedyFor(name, status) {
+  const steps = [];
+  if (!status.searched && !status.documentation)
+    steps.push(`1) mem_search "${name} usage" (engram is the first source)`);
+  if (!status.documentation)
+    steps.push(
+      `2) if engram has nothing: context7 resolve-library-id "${name}" then get-library-docs for the API you need`,
+    );
+  if (status.documentation && !status.saved)
+    steps.push(
+      `3) mem_save what you learned about ${name} (title mentioning "${name}") so the next session reads it from engram`,
+    );
+  return steps.join('; ');
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: {
+      codeExtensions: DEFAULT_CODE_EXTENSIONS,
+      ignoredPackages: DEFAULT_IGNORED_PACKAGES,
+      maxScanFiles: DEFAULT_MAX_SCAN_FILES,
+    },
+  },
+  ({ toolName, toolInput, sessionId, parameters, cwd }) => {
+    if (!toolInGroups(toolName, ['write'])) return;
+    const writtenPath = writtenPathOf(toolInput);
+    if (
+      !writtenPath ||
+      !parameters.codeExtensions.includes(extname(writtenPath).toLowerCase())
+    )
+      return;
+    const root = projectRootOf(cwd) ?? cwd;
+    const absolutePath = isAbsolute(writtenPath)
+      ? writtenPath
+      : join(root, writtenPath);
+    const ignored = new Set(
+      parameters.ignoredPackages.map((name) => String(name).toLowerCase()),
+    );
+    const already = existingImports(absolutePath);
+    const candidates = importedPackagesOf(
+      writtenContentOf(toolInput),
+      writtenPath,
+    ).filter((name) => !already.has(name) && !ignored.has(name.toLowerCase()));
+    if (candidates.length === 0) return;
+    const usedElsewhere = packagesUsedElsewhere(
+      root,
+      absolutePath,
+      parameters.codeExtensions,
+      parameters.maxScanFiles,
+    );
+    const unknown = candidates.filter((name) => !usedElsewhere.has(name));
+    if (unknown.length === 0) return;
+    const state = readSessionState(GATE_ID, sessionId, {}, { cwd });
+    const blocked = unknown
+      .map((name) => ({ name, status: knowledgeStatus(state, name) }))
+      .filter((entry) => !entry.status.known);
+    if (blocked.length === 0) return;
+    const lines = blocked.map(
+      (entry) => `${entry.name}: ${remedyFor(entry.name, entry.status)}`,
+    );
+    deny(
+      CONFIG_KEY,
+      `This write introduces ${blocked.length} package(s) this project does not use anywhere yet, and nothing ` +
+        `in this session shows how to use them. Do not guess an API. ${lines.join(' | ')}. Then retry the write.`,
+    );
+  },
+);