@devrik-tools/claude-gates 0.7.2 → 0.8.0

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

@@ -0,0 +1,95 @@
+import {
+  allow,
+  mcpActionSegment,
+  mcpServerSegment,
+  readHookPayload,
+  sessionIdOf,
+  toolInputOf,
+  toolNameOf,
+  toolResponseOf,
+} from '../../lib/hook-io.mjs';
+import { updateSessionState } from '../../lib/session-state.mjs';
+
+const GATE_ID = 'library-docs';
+const ENGRAM_SERVERS = new Set(['engram', 'plugin_engram_engram']);
+const CONTEXT7_SERVERS = new Set(['context7', 'plugin_context7_context7']);
+const SAVE_ACTIONS = new Set(['mem_save', 'mem_session_summary', 'mem_update']);
+const NO_RESULT_PATTERN = /no memories found|no results|0 results/i;
+const MAX_ENTRIES = 40;
+const MAX_ENTRY_LENGTH = 300;
+
+function textOf(value) {
+  if (typeof value === 'string') return value;
+  try {
+    return JSON.stringify(value ?? '');
+  } catch {
+    return '';
+  }
+}
+
+function inputText(toolInput) {
+  if (!toolInput || typeof toolInput !== 'object') return '';
+  return [
+    toolInput.query,
+    toolInput.title,
+    toolInput.content,
+    toolInput.libraryName,
+    toolInput.context7CompatibleLibraryID,
+    toolInput.topic,
+  ]
+    .filter((value) => typeof value === 'string')
+    .join(' ');
+}
+
+function remember(list, entry) {
+  return [...(list ?? []), String(entry).slice(0, MAX_ENTRY_LENGTH)].slice(
+    -MAX_ENTRIES,
+  );
+}
+
+function classify(toolName) {
+  const server = mcpServerSegment(toolName).toLowerCase();
+  const action = mcpActionSegment(toolName).toLowerCase();
+  if (ENGRAM_SERVERS.has(server) && action === 'mem_search') return 'search';
+  if (ENGRAM_SERVERS.has(server) && SAVE_ACTIONS.has(action)) return 'save';
+  if (CONTEXT7_SERVERS.has(server)) return 'docs';
+  return null;
+}
+
+function main() {
+  const rawPayload = readHookPayload();
+  if (rawPayload === null) allow();
+  const toolName = toolNameOf(rawPayload) ?? '';
+  const kind = classify(toolName);
+  if (!kind) allow();
+  const toolInput = toolInputOf(rawPayload);
+  const response = textOf(toolResponseOf(rawPayload));
+  const text = inputText(toolInput);
+  updateSessionState(GATE_ID, sessionIdOf(rawPayload), {}, (state) => {
+    if (kind === 'search') {
+      const hit = response.length > 0 && !NO_RESULT_PATTERN.test(response);
+      return hit
+        ? {
+            ...state,
+            memSearchHits: remember(state.memSearchHits, `${text} ${response}`),
+          }
+        : state;
+    }
+    if (kind === 'save')
+      return { ...state, memSaves: remember(state.memSaves, text) };
+    return {
+      ...state,
+      context7Lookups: remember(
+        state.context7Lookups,
+        `${text} ${response.slice(0, MAX_ENTRY_LENGTH)}`,
+      ),
+    };
+  });
+  allow();
+}
+
+try {
+  main();
+} catch {
+  allow();
+}

package/plugins/gates/hooks/gates/lint-commit/index.mjs

@@ -1,99 +1,85 @@
-// lint-commit — denies `git commit` while the project's lint script fails. The gate never
-// invents a lint step: it only runs a `lint` script the project itself declared in
-// package.json (or an explicit override), so a project with no linter configured is left
-// alone (allow, silent).
-//
-// justification: no existing tool covers this. bash-commands (the other shell gate) only
-// pattern-matches the command text; it never SPAWNS a check. This is the first gate that
-// runs an external process as its verdict.
-//
-// ── What a project can configure (params) ───────────────────────────────────────────
-//   lintCommand     explicit command to run instead of autodetecting `npm run lint`.
-//                   null (default) means: read package.json's `scripts.lint`, and if
-//                   absent, allow — this gate does not invent a lint step.
-//   lintTimeoutMs   how long the lint run may take before it is treated as a failure.
-// The defaults live here, in the source, so a project reads them and knows exactly what
-// its override replaces.
-//
-// ── How it detects a commit ──────────────────────────────────────────────────────────
-// Reuses bash-commands' git-global-option normalization idea: `git -C <path> commit` or
-// `git -c user.name=x commit` must be caught the same as a bare `git commit`. Only a real
-// commit (not `git commit --help`, not a mention inside a delegation prompt describing one)
-// is gated — this runs on the shell tool only, not on delegation text, because spawning a
-// lint run for a prompt that merely MENTIONS a commit would be wasted work and a false
-// blocker on unrelated delegations.
-//
-// ── Why spawnSync + shell:true on Windows ────────────────────────────────────────────
-// `npm` is `npm.cmd` on Windows; resolving the concrete binary name per platform is more
-// fragile than letting the shell resolve it, so this always spawns through the shell.
-//
-// ── Fail-safe shape ───────────────────────────────────────────────────────────────────
-// No package.json, or package.json with no `scripts.lint` and no `lintCommand` override:
-// allow (nothing to enforce, never invented). Lint run exits non-zero: deny with the last
-// ~15 lines of its combined output. Lint run exits zero: allow.
+// lint-commit — denies a `git commit` while the project's lint script fails. It never invents
+// a lint step: only a `lint` script the project declared in package.json (or an explicit
+// lintCommand) runs, and only for a command segment that RUNS git commit (a `grep "git
+// commit"` is not one; a `--dry-run` writes nothing). The lint runs in the repo the commit
+// targets: `-C <path>` when given, else the project root of the cwd. Spawned through the
+// shell because `npm` is `npm.cmd` on Windows. A commit that cannot be evaluated (the lint
+// process fails to spawn) is denied: a commit gate must not silently permit.
 
 import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { runGate, deny, toolInGroups } from '../../lib/hook-io.mjs';
+import { join, resolve } from 'node:path';
+import { projectRootOf, readJsonOrNull } from '../../lib/config.mjs';
+import {
+  isDryRunCommit,
+  isGitCommit,
+  normalizeGitCommand,
+} from '../../lib/git.mjs';
+import {
+  deny,
+  runGate,
+  shellCommandOf,
+  toolInGroups,
+} from '../../lib/hook-io.mjs';
 
 const GATE_ID = 'lint-commit';
 const CONFIG_KEY = 'blockCommitWithFailingLint';
 
-const SHELL_GROUPS = ['shell'];
 const DEFAULT_LINT_TIMEOUT_MS = 60000;
 const OUTPUT_TAIL_LINES = 15;
 
-// One global git option at a time, stripped repeatedly — same normalization bash-commands
-// uses so `git -C /repo -c x=y commit` reduces to `git commit` before the pattern runs.
-const GIT_OPTION_WITH_VALUE = String.raw`(?:-[Cc]|--git-dir|--work-tree|--namespace|--exec-path|--config-env)(?:\s+|=)\S+`;
-const GIT_FLAG_OPTION = String.raw`--(?:paginate|no-pager|bare|no-optional-locks)|-p`;
-const GIT_GLOBAL_OPTION_PATTERN = new RegExp(
-  String.raw`\bgit\s+(?:${GIT_OPTION_WITH_VALUE}|${GIT_FLAG_OPTION})\s+`,
-  'i',
-);
-const GIT_COMMIT_PATTERN = /\bgit\s+commit\b/i;
-
-function normalizeGitOptions(command) {
-  let previous;
-  let normalized = command;
-  do {
-    previous = normalized;
-    normalized = normalized.replace(GIT_GLOBAL_OPTION_PATTERN, 'git ');
-  } while (normalized !== previous);
-  return normalized;
+// ── The commit segment ──────────────────────────────────────────────────────────────
+const SEGMENT_SEPARATOR = /;|&&|\|\||\||\n/;
+const ARGUMENT_PATTERN = /"([^"]*)"|'([^']*)'|(\S+)/g;
+const GIT_BINARY_TOKEN = /(?:^|[\\/])git(?:\.exe)?$/i;
+const WRAPPER_TOKEN = /^(?:\w+=\S*|command|sudo|env)$/i;
+
+function tokensOf(text) {
+  const tokens = [];
+  for (const match of text.matchAll(ARGUMENT_PATTERN))
+    tokens.push(match[1] ?? match[2] ?? match[3]);
+  return tokens;
 }
 
-function isGitCommit(command) {
-  return GIT_COMMIT_PATTERN.test(normalizeGitOptions(command));
+function runsGit(segment) {
+  const tokens = tokensOf(segment);
+  while (tokens.length > 0 && WRAPPER_TOKEN.test(tokens[0])) tokens.shift();
+  return tokens.length > 0 && GIT_BINARY_TOKEN.test(tokens[0]);
 }
 
-function commandTextFrom(toolInput) {
-  return String(toolInput.CommandLine ?? toolInput.command ?? '');
+function commitSegmentOf(command) {
+  for (const segment of String(command).split(SEGMENT_SEPARATOR)) {
+    if (!runsGit(segment)) continue;
+    const normalized = normalizeGitCommand(segment);
+    if (isGitCommit(normalized) && !isDryRunCommit(normalized)) return segment;
+  }
+  return null;
 }
 
-/** The project's declared lint command, or null when none is declared (never invented). */
-function resolveLintCommand(cwd, lintCommandOverride) {
-  if (lintCommandOverride) return lintCommandOverride;
-
-  const packageJsonPath = join(cwd, 'package.json');
-  if (!existsSync(packageJsonPath)) return null;
-
-  try {
-    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
-    if (packageJson?.scripts?.lint) return 'npm run lint';
-    return null;
-  } catch {
-    // Corrupt package.json is not this gate's problem to diagnose; do not invent a lint step.
-    return null;
+// `-C` BEFORE the subcommand is git's working directory; after `commit` it reuses a message.
+function commitDirectoryOf(segment) {
+  const tokens = tokensOf(segment);
+  const gitIndex = tokens.findIndex((token) => GIT_BINARY_TOKEN.test(token));
+  for (let index = gitIndex + 1; index < tokens.length; index += 1) {
+    if (tokens[index] === 'commit') return null;
+    if (tokens[index] === '-C') return tokens[index + 1] ?? null;
   }
+  return null;
+}
+
+// ── Lint ────────────────────────────────────────────────────────────────────────────
+function resolveLintCommand(lintDirectory, lintCommandOverride) {
+  if (typeof lintCommandOverride === 'string' && lintCommandOverride.trim())
+    return lintCommandOverride;
+  const packageJson = readJsonOrNull(join(lintDirectory, 'package.json'));
+  return packageJson?.scripts?.lint ? 'npm run lint' : null;
 }
 
 function tailLines(text, count) {
-  const lines = String(text)
+  return String(text)
     .split(/\r?\n/)
-    .filter((line) => line.length > 0);
-  return lines.slice(-count).join('\n');
+    .filter((line) => line.length > 0)
+    .slice(-count)
+    .join('\n');
 }
 
 function runLint(lintCommand, cwd, timeoutMs) {
@@ -115,37 +101,42 @@ runGate(
       lintTimeoutMs: DEFAULT_LINT_TIMEOUT_MS,
     },
   },
-  ({ toolName, toolInput, parameters }) => {
-    if (!toolInGroups(toolName, SHELL_GROUPS)) return;
-
-    const command = commandTextFrom(toolInput);
-    if (!isGitCommit(command)) return;
-
-    const cwd = process.cwd();
-    const lintCommand = resolveLintCommand(cwd, parameters.lintCommand);
-    if (!lintCommand) return; // no lint script declared anywhere: nothing to enforce
-
-    const timeoutMs = parameters.lintTimeoutMs ?? DEFAULT_LINT_TIMEOUT_MS;
-    const result = runLint(lintCommand, cwd, timeoutMs);
-
+  ({ toolName, toolInput, parameters, cwd }) => {
+    if (!toolInGroups(toolName, ['shell'])) return;
+
+    const segment = commitSegmentOf(shellCommandOf(toolInput));
+    if (segment === null) return;
+
+    const explicitDirectory = commitDirectoryOf(segment);
+    const lintDirectory = explicitDirectory
+      ? resolve(cwd, explicitDirectory)
+      : (projectRootOf(cwd) ?? cwd);
+    const lintCommand = resolveLintCommand(
+      lintDirectory,
+      parameters.lintCommand,
+    );
+    if (!lintCommand) return;
+
+    const result = runLint(
+      lintCommand,
+      lintDirectory,
+      parameters.lintTimeoutMs,
+    );
     if (result.error) {
-      // The lint process itself could not be spawned (bad shell, missing interpreter, or a
-      // timeout kill). A commit gate that cannot evaluate must not silently permit — deny
-      // with the spawn error so the user can fix the environment, not guess.
       deny(
         CONFIG_KEY,
-        `Could not run the lint command ("${lintCommand}"): ${result.error.message}. Fix ` +
-          'the lint setup or set lintCommand/blockCommitWithFailingLint in .ai/config.json.',
+        `Could not run the lint command ("${lintCommand}" in ${lintDirectory}): ` +
+          `${result.error.message}. Fix the lint setup, or set lintCommand under ` +
+          `${CONFIG_KEY} in .ai/config.json.`,
       );
     }
-
     if (result.status !== 0) {
       const combinedOutput =
         `${result.stdout ?? ''}\n${result.stderr ?? ''}`.trim();
       deny(
         CONFIG_KEY,
-        `Lint failed (exit ${result.status}) — commit blocked until it passes:\n` +
-          `${tailLines(combinedOutput, OUTPUT_TAIL_LINES)}`,
+        `Lint failed (exit ${result.status}, "${lintCommand}" in ${lintDirectory}) — ` +
+          `commit blocked until it passes:\n${tailLines(combinedOutput, OUTPUT_TAIL_LINES)}`,
       );
     }
   },

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

@@ -1,23 +1,24 @@
-// mandatory-flow — denies an implementation delegation when there is no live task
-// pointer on disk backed by a contract file. Declaring pipeline stages in prose (what
-// implementation-pipeline.mjs checks) is not the same as a live task actually existing
-// on disk; this gate checks the disk fact, not the prompt's wording. Migrated from
-// ~/.claude/hooks/guard-flujo-obligatorio.mjs.
+// mandatory-flow — denies a STANDARD/HIGH-RISK implementation delegation when no live task
+// exists on disk: a pointer file naming the active task slug, and a non-empty contract file
+// under that task's directory. Declaring stages in prose (implementation-pipeline) is not
+// the same as a task actually existing; this gate checks the disk fact.
 //
-// ── What a project can configure (params) ───────────────────────────────────────────
-//   activePointerPath   path (relative to the project root) to the file naming the
-//                        active task/pipeline slug.
-//   exemptSubagents      subagent types exempt outright (read-only pipeline stages).
-//                        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 ───────────────────────────
-// Only STANDARD/HIGH-RISK implementation delegations, on non-exempt subagents, not
-// about the harness itself, reach the disk check.
-
-import { existsSync, readFileSync } from 'node:fs';
-import { join, normalize, sep } from 'node:path';
+// Decisions: the contract root follows the pointer — `<dir of activePointerPath>/<slug>/` —
+// so a project that moves the pointer moves its tasks with it; an absolute pointer path is
+// honored as-is. A slug is a directory name, never a path (traversal is rejected). An empty
+// contract file is not a contract. Only the exempt list exempts a subagent type.
+
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join, normalize, sep } from 'node:path';
+import { projectRootOf } from '../../lib/config.mjs';
+import {
+  DEFAULT_EXEMPT_SUBAGENTS,
+  DEMANDING_LEVELS,
+  isHarnessWork,
+  isImplementationRequest,
+  isSubagentNamedIn,
+  operativeLevelOf,
+} from '../../lib/delegation.mjs';
 import {
   runGate,
   deny,
@@ -30,19 +31,6 @@ const CONFIG_KEY = 'requireLiveTaskWhenImplementing';
 
 const DEFAULT_ACTIVE_POINTER_PATH = join('.ai', 'pipeline', 'ACTIVA');
 
-const DEFAULT_EXEMPT_SUBAGENTS = [
-  'explore',
-  'plan',
-  'scout',
-  'revision',
-  'contraste',
-  'test-planner',
-  'qa',
-  'ui',
-  'ux',
-];
-
-/** Contract files that count as evidence a task's contract exists on disk. */
 const TASK_CONTRACT_FILES = [
   'asserts.md',
   'task.json',
@@ -51,58 +39,27 @@ const TASK_CONTRACT_FILES = [
   'acceptance.md',
 ];
 
-function withWordBoundary(alternation) {
-  return new RegExp(
-    `(?:^|[^\\p{L}\\p{N}_])(?:${alternation})(?:[^\\p{L}\\p{N}_]|$)`,
-    'iu',
-  );
+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);
 }
 
-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*',
-);
-
-/** 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 HARNESS_PATTERN =
-  /(\.claude[\\/]|hooks[\\/]|plugins[\\/]gates|settings\.json|[\\/]agents[\\/]\w|[\\/]rules[\\/]\w|[\\/]skills[\\/]\w)/i;
-
-function isExempt(toolInput, prompt, exemptSubagents) {
-  const subagentType = String(
-    toolInput.subagent_type ?? toolInput.subagentType ?? '',
-  ).toLowerCase();
-  if (exemptSubagents.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 fileExistsNonEmpty(path) {
+  try {
+    return existsSync(path) && statSync(path).size > 0;
+  } catch {
+    return false;
+  }
 }
 
 function hasTaskContract(taskDirectory) {
-  return TASK_CONTRACT_FILES.some((file) => {
-    try {
-      return existsSync(join(taskDirectory, file));
-    } catch {
-      return false;
-    }
-  });
+  return TASK_CONTRACT_FILES.some((file) =>
+    fileExistsNonEmpty(join(taskDirectory, file)),
+  );
 }
 
-/** The pointer file's trimmed content, or '' when it cannot be read or the slug
- * attempts path traversal. A slug is a directory name, not a path: rejecting any
- * segment separator or '..' closes off `join(cwd, '.ai', 'pipeline', slug)` escaping
- * that directory to accept an unrelated file elsewhere on disk as the task contract. */
 function readSlug(pointerPath) {
   let raw;
   try {
@@ -121,7 +78,6 @@ function readSlug(pointerPath) {
   return normalized;
 }
 
-/** Denies for whichever of the three live-task facts is missing, or does nothing. */
 function checkLiveTask(pointerPath) {
   if (!existsSync(pointerPath)) {
     deny(
@@ -136,20 +92,19 @@ function checkLiveTask(pointerPath) {
   if (!slug) {
     deny(
       CONFIG_KEY,
-      `${pointerPath} exists but is empty. An active-task pointer with no slug is not ` +
-        'a live task. Write the task slug into it before delegating.',
+      `${pointerPath} exists but names no valid task slug (empty, or a path instead of a ` +
+        'directory name). Write the task slug into it before delegating.',
     );
   }
 
-  const taskDirectory = join(process.cwd(), '.ai', 'pipeline', slug);
+  const taskDirectory = join(dirname(pointerPath), slug);
   if (!hasTaskContract(taskDirectory)) {
     deny(
       CONFIG_KEY,
-      `The active task '${slug}' has no contract on disk: none of ` +
-        `${TASK_CONTRACT_FILES.join(', ')} exists under ${taskDirectory}. ` +
-        `Write ONE of those files there before implementing (this gate's contract root is ` +
-        `.ai/pipeline/${slug}/ — a brief.md under .ai/features/${slug}/ satisfies a ` +
-        'different gate, sdd-specs, but NOT this one; if you already wrote a brief there, ' +
+      `The active task '${slug}' has no non-empty contract on disk: none of ` +
+        `${TASK_CONTRACT_FILES.join(', ')} exists (with content) under ${taskDirectory}. ` +
+        'Write ONE of those files there before implementing (a brief.md under ' +
+        `.ai/features/${slug}/ satisfies sdd-specs, not this gate; if you already wrote one, ` +
         `create a short asserts.md under ${taskDirectory} referencing it).`,
     );
   }
@@ -165,19 +120,17 @@ runGate(
       exemptSubagents: DEFAULT_EXEMPT_SUBAGENTS,
     },
   },
-  ({ toolName, toolInput, parameters }) => {
+  ({ toolName, toolInput, parameters, cwd }) => {
     if (!toolInGroups(toolName, ['delegation'])) return;
 
     const prompt = delegationPromptOf(toolInput);
     if (!prompt.trim()) return;
+    if (isExempt(toolInput, prompt, parameters.exemptSubagents)) return;
 
-    const exemptSubagents =
-      parameters.exemptSubagents ?? DEFAULT_EXEMPT_SUBAGENTS;
-    if (isExempt(toolInput, prompt, exemptSubagents)) return;
-
-    const activePointerPath = String(
-      parameters.activePointerPath ?? DEFAULT_ACTIVE_POINTER_PATH,
-    );
-    checkLiveTask(join(process.cwd(), activePointerPath));
+    const root = projectRootOf(cwd) ?? cwd;
+    const pointer =
+      String(parameters.activePointerPath ?? '').trim() ||
+      DEFAULT_ACTIVE_POINTER_PATH;
+    checkLiveTask(isAbsolute(pointer) ? pointer : join(root, pointer));
   },
 );