@devrik-tools/claude-gates 0.8.0 → 1.0.0

package/cli/smoke-fixtures.json

@@ -136,8 +136,8 @@
     {
       "id": "force-parallel",
       "configKey": "warnSequentialDelegations",
-      "enabledByDefault": false,
-      "type": "warn",
+      "enabledByDefault": true,
+      "type": "deny",
       "payload": {
         "tool_name": "Task",
         "tool_input": {
@@ -145,7 +145,7 @@
         }
       },
       "needsState": true,
-      "note": "stateful: warns only on the 3rd consecutive delegation under one session."
+      "note": "stateful: denies only on the 3rd consecutive delegation under one session."
     },
     {
       "id": "feature-catalog",
@@ -413,6 +413,14 @@
       "needsState": true,
       "note": "side-effect only: records to .ai/tool-map.json, never denies/warns."
     },
+    {
+      "id": "skill-first",
+      "configKey": "requireSkillCheckBeforeActing",
+      "enabledByDefault": false,
+      "type": "deny",
+      "payload": null,
+      "needsState": true
+    },
     {
       "id": "forge-flow",
       "configKey": "requireForgeRunToEdit",
@@ -542,6 +550,48 @@
         }
       },
       "needsState": false
+    },
+    {
+      "id": "require-task-split",
+      "configKey": "requireTaskSplitBeforeImplementing",
+      "enabledByDefault": true,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Write",
+        "tool_input": {
+          "file_path": "src/x.js",
+          "content": "x"
+        }
+      },
+      "needsState": true,
+      "note": "needs an .ai/tasks/active.json with a medium+ task that has no children."
+    },
+    {
+      "id": "require-monitor",
+      "configKey": "requireMonitorForBackground",
+      "enabledByDefault": true,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Bash",
+        "tool_input": {
+          "command": "npm run build",
+          "run_in_background": true
+        }
+      },
+      "needsState": false
+    },
+    {
+      "id": "no-trivial-scripts",
+      "configKey": "blockTrivialInlineScripts",
+      "enabledByDefault": true,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Bash",
+        "tool_input": {
+          "command": "sed -i 's/old/new/' src/a.mjs"
+        }
+      },
+      "needsState": false
     }
   ]
 }

package/cli/task.mjs

@@ -16,6 +16,12 @@ import { verifyCommand, verifyPath } from './evidence.mjs';
 
 const DEFAULT_SIZE = 'unspecified';
 
+const VERIFY_USAGE =
+  'task add requires a deterministic verification criterion: ' +
+  '--verify-command "<command>" [--verify-expect <text>] (command that must exit 0 when done) ' +
+  'or --verify-path <path> [--verify-contains <text>] (file/dir that must exist when done). ' +
+  'This defines HOW the task will be verified as complete — free text is not enough.';
+
 function fail(message) {
   process.stderr.write(`${message}\n`);
   process.exit(EXIT_CODE.FAILURE);
@@ -31,18 +37,41 @@ function openStoreOrFail(cwd) {
   return store;
 }
 
+function buildVerifyCriteria(options) {
+  if (options.verifyCommand) {
+    return {
+      kind: 'command',
+      command: options.verifyCommand,
+      expect: options.verifyExpect ?? null,
+    };
+  }
+  if (options.verifyPath) {
+    return {
+      kind: 'path',
+      path: options.verifyPath,
+      contains: options.verifyContains ?? null,
+    };
+  }
+  return null;
+}
+
 function taskAdd(title, options, { cwd = process.cwd() } = {}) {
   if (!title || !title.trim()) fail('task add requires a non-empty title.');
+  const verify = buildVerifyCriteria(options);
+  if (!verify) fail(VERIFY_USAGE);
   const store = openStoreOrFail(cwd);
-  const task = store.add({
+  const task = {
     id: options.id || randomUUID(),
     title: title.trim(),
     description: options.description ?? '',
     status: STATUS.OPEN,
     size: options.size ?? DEFAULT_SIZE,
+    verify,
     createdAt: new Date().toISOString(),
     messages: [],
-  });
+  };
+  if (options.parent) task.parentId = options.parent;
+  store.add(task);
   process.stdout.write(`${JSON.stringify(task, null, 2)}\n`);
 }
 
@@ -80,9 +109,26 @@ function collectEvidence(options, cwd) {
   return null;
 }
 
+function autoVerifyFromTask(task, cwd) {
+  if (!task?.verify) return null;
+  const { kind, command, expect, path, contains } = task.verify;
+  if (kind === 'command' && command) {
+    return verifyCommand(command, { cwd, expect: expect ?? undefined });
+  }
+  if (kind === 'path' && path) {
+    return verifyPath(path, { cwd, contains: contains ?? undefined });
+  }
+  return null;
+}
+
 function taskClose(id, options, { cwd = process.cwd() } = {}) {
   const store = openStoreOrFail(cwd);
-  const evidence = collectEvidence(options, store.root);
+  let evidence = collectEvidence(options, store.root);
+  if (!evidence && options.evidence !== undefined) fail(EVIDENCE_USAGE);
+  if (!evidence) {
+    const task = store.active().find((entry) => entry.id === id);
+    evidence = autoVerifyFromTask(task, store.root);
+  }
   if (!evidence) fail(EVIDENCE_USAGE);
   if (!evidence.verified) {
     const output = evidence.outputTail ? `\n${evidence.outputTail}` : '';
@@ -121,10 +167,29 @@ export function registerTaskCommand(program) {
 
   task
     .command('add <title>')
-    .description('Register a new open task.')
+    .description(
+      'Register a new open task (requires a verification criterion).',
+    )
     .option('--id <id>', 'explicit task id (default: a generated uuid)')
     .option('--description <text>', 'longer description of the task')
     .option('--size <size>', 'rough size estimate (e.g. trivial, small, large)')
+    .option(
+      '--verify-command <command>',
+      'shell command that must exit 0 when the task is done',
+    )
+    .option(
+      '--verify-expect <text>',
+      'text the --verify-command output must contain',
+    )
+    .option(
+      '--verify-path <path>',
+      'file or directory that must exist when the task is done',
+    )
+    .option(
+      '--verify-contains <text>',
+      'text the --verify-path file must contain',
+    )
+    .option('--parent <id>', 'parent task id (makes this a sub-task)')
     .action((title, options) => taskAdd(title, options));
 
   task

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@devrik-tools/claude-gates",
-  "version": "0.8.0",
-  "description": "Installable, deterministic gates (hooks) for Claude Code: block destructive commands, protected paths, and enforce delegation/spec/quality rules. Configurable per project.",
+  "version": "1.0.0",
+  "description": "49 installable, deterministic gates (hooks) for Claude Code: block destructive commands and protected paths, enforce delegation/spec/quality/research rules, and track tasks that only close with verified evidence. Configurable per project.",
   "keywords": [
     "claude-code",
     "hooks",
@@ -9,7 +9,8 @@
     "guardrails",
     "pretooluse",
     "policy-enforcement",
-    "ai-agent"
+    "ai-agent",
+    "task-tracking"
   ],
   "type": "module",
   "bin": {
@@ -74,4 +75,4 @@
     "globals": "^17.11.0",
     "prettier": "^3.9.6"
   }
-}
+}

package/plugins/gates/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gates",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Deterministic gates for Claude Code: destructive-command blocks, protected paths, delegation briefs, spec-driven flow and session-start validation. Selection lives in config, not in code.",
   "author": {
     "name": "Devrik"

package/plugins/gates/hooks/gates/capability-map/index.mjs

@@ -9,17 +9,21 @@
 // ~/.claude/blurb-overrides.json and <project>/<blurbOverridesFile> (project wins per key).
 // `.agents/skills` and `.ai/skills` (home and project) are scanned as skill-only roots:
 // other installers write there. Never blocks; any failure injects nothing.
+//
+// Discovery itself lives in lib/capabilities.mjs, shared with skill-first (the PreToolUse
+// half that judges whether an action has a skill covering it): one catalog definition, so
+// what the model is TOLD it has and what a gate CHECKS it has can never disagree.
 
 import { createHash } from 'node:crypto';
-import {
-  mkdirSync,
-  readFileSync,
-  readdirSync,
-  statSync,
-  writeFileSync,
-} from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { basename, dirname, extname, isAbsolute, join } from 'node:path';
+import { dirname, join } from 'node:path';
+import {
+  buildRawCatalog,
+  firstClause,
+  mtimeMsOf,
+  truncateAtWordBoundary,
+} from '../../lib/capabilities.mjs';
 import {
   loadGateConfig,
   projectRootOf,
@@ -30,6 +34,7 @@ import {
   readSessionState,
   writeSessionState,
 } from '../../lib/session-state.mjs';
+import { workNatureOf } from '../../lib/signals.mjs';
 
 const STDIN_FILE_DESCRIPTOR = 0;
 const GATE_ID = 'capability-map';
@@ -48,13 +53,9 @@ const DEFAULT_PARAMS = Object.freeze({
   mapFile: join('.ai', 'capability-map.json'),
   blurbOverridesFile: join('.ai', 'blurb-overrides.json'),
   injectEveryMessages: 10,
+  reinjectOnWorkNatureChange: true,
 });
 
-const KIND_EXTENSIONS = {
-  agents: ['.md'],
-  commands: ['.md', '.toml'],
-};
-
 function readPayload() {
   try {
     return JSON.parse(readFileSync(STDIN_FILE_DESCRIPTOR, 'utf8'));
@@ -63,193 +64,6 @@ function readPayload() {
   }
 }
 
-function isDirectory(path) {
-  try {
-    return statSync(path).isDirectory();
-  } catch {
-    return false;
-  }
-}
-
-function mtimeMsOf(path) {
-  try {
-    return statSync(path).mtimeMs;
-  } catch {
-    return null;
-  }
-}
-
-// ── Front matter ────────────────────────────────────────────────────────────────────
-// A bare block-scalar indicator (`>`, `>-`, `|`, `|-`) means the value is on the following
-// indented lines; without this the blurb rendered as ">".
-const BLOCK_SCALAR_INDICATOR_PATTERN = /^[|>][+-]?\d*$/;
-
-function readBlockScalarValue(lines, startIndex) {
-  const parts = [];
-  for (let index = startIndex; index < lines.length; index += 1) {
-    const line = lines[index];
-    if (line.trim() === '---') break;
-    if (!/^[ \t]+\S/.test(line)) break;
-    parts.push(line.trim());
-  }
-  return parts.join(' ');
-}
-
-// Parsed line by line (no multi-line regex) so a large body can never backtrack.
-function parseFrontMatter(fileText) {
-  const lines = fileText.split(/\r?\n/);
-  if (lines[0]?.trim() !== '---') return { name: '', description: '' };
-  let name = '';
-  let description = '';
-  for (let index = 1; index < lines.length; index += 1) {
-    const line = lines[index];
-    if (line.trim() === '---') break;
-    const separator = line.indexOf(':');
-    if (separator < 0) continue;
-    const key = line.slice(0, separator).trim();
-    let value = line
-      .slice(separator + 1)
-      .trim()
-      .replace(/^["']|["']$/g, '');
-    if (BLOCK_SCALAR_INDICATOR_PATTERN.test(value)) {
-      value = readBlockScalarValue(lines, index + 1);
-    }
-    if (key === 'name') name = value;
-    else if (key === 'description') description = value;
-  }
-  return { name, description };
-}
-
-function truncateAtWordBoundary(text, maxChars) {
-  if (text.length <= maxChars) return text;
-  const budget = text.slice(0, maxChars - 1);
-  const lastSpace = budget.lastIndexOf(' ');
-  const cut = lastSpace > 0 ? budget.slice(0, lastSpace) : budget;
-  return `${cut.trimEnd()}…`;
-}
-
-function firstClause(description, maxClauseChars) {
-  if (!description) return '';
-  const sentenceEnd = description.indexOf('. ');
-  const clause =
-    sentenceEnd > 0 ? description.slice(0, sentenceEnd) : description;
-  return truncateAtWordBoundary(clause, maxClauseChars);
-}
-
-// ── Discovery ───────────────────────────────────────────────────────────────────────
-function filesUnder(directory, extensions) {
-  let names;
-  try {
-    names = readdirSync(directory);
-  } catch {
-    return [];
-  }
-  const files = [];
-  for (const name of names) {
-    const full = join(directory, name);
-    if (isDirectory(full)) files.push(...filesUnder(full, extensions));
-    else if (extensions.includes(extname(name).toLowerCase())) files.push(full);
-  }
-  return files;
-}
-
-function entryFor(file, fallbackName) {
-  const mtimeMs = mtimeMsOf(file);
-  if (mtimeMs === null) return null;
-  let content;
-  try {
-    content = readFileSync(file, 'utf8');
-  } catch {
-    return null;
-  }
-  const { name, description } = parseFrontMatter(content);
-  return {
-    name: name || fallbackName,
-    description,
-    stamp: `${file}:${mtimeMs}`,
-  };
-}
-
-function skillEntriesUnder(skillsRoot) {
-  let names;
-  try {
-    names = readdirSync(skillsRoot);
-  } catch {
-    return [];
-  }
-  return names
-    .filter((name) => isDirectory(join(skillsRoot, name)))
-    .map((name) => entryFor(join(skillsRoot, name, 'SKILL.md'), name))
-    .filter(Boolean);
-}
-
-function fileEntriesUnder(directory, extensions) {
-  return filesUnder(directory, extensions)
-    .map((file) => entryFor(file, basename(file, extname(file))))
-    .filter(Boolean);
-}
-
-function resolveExtra(root, directory) {
-  return isAbsolute(directory) ? directory : join(root, directory);
-}
-
-function skillRootsFor(root, extraDirectories) {
-  return [
-    join(root, '.claude', 'skills'),
-    join(root, '.agents', 'skills'),
-    join(root, '.ai', 'skills'),
-    join(homedir(), '.claude', 'skills'),
-    join(homedir(), '.agents', 'skills'),
-    join(homedir(), '.ai', 'skills'),
-    ...extraDirectories.map((directory) => resolveExtra(root, directory)),
-  ];
-}
-
-function fileRootsFor(root, kind, extraDirectories) {
-  return [
-    join(root, '.claude', kind),
-    join(homedir(), '.claude', kind),
-    ...extraDirectories.map((directory) => resolveExtra(root, directory)),
-  ];
-}
-
-function collectKind(kind, root, settings) {
-  if (kind === 'skills') {
-    return skillRootsFor(root, settings.extraSkillsDirs).flatMap(
-      skillEntriesUnder,
-    );
-  }
-  const extensions = KIND_EXTENSIONS[kind];
-  if (!extensions) return [];
-  const extra =
-    kind === 'agents' ? settings.extraAgentsDirs : settings.extraCommandsDirs;
-  return fileRootsFor(root, kind, extra).flatMap((directory) =>
-    fileEntriesUnder(directory, extensions),
-  );
-}
-
-// First occurrence wins, and project roots come first: a project capability shadows a
-// global one of the same name.
-function entriesForKind(kind, root, settings) {
-  const seen = new Set();
-  const unique = [];
-  for (const entry of collectKind(kind, root, settings)) {
-    if (seen.has(entry.name)) continue;
-    seen.add(entry.name);
-    unique.push(entry);
-  }
-  return unique.sort((a, b) => a.name.localeCompare(b.name));
-}
-
-function buildRawCatalog(root, settings) {
-  const catalog = {};
-  for (const kind of settings.kinds) {
-    const entries = entriesForKind(kind, root, settings);
-    if (entries.length > 0) catalog[kind] = entries;
-  }
-  return catalog;
-}
-
 // ── Blurbs, overrides and the fingerprint ───────────────────────────────────────────
 function blurbOverridePathsFor(root, blurbOverridesFile) {
   return [
@@ -355,12 +169,20 @@ function renderCatalog(catalog, kinds) {
   return `[capabilities] available (check before improvising something one of these covers):\n${sections.join('\n')}\n`;
 }
 
-// A changed catalog (or the first message of a session) injects immediately; otherwise
-// every Nth message.
-function injectionDecision(session, fingerprint, injectEveryMessages) {
+// Three reasons to inject, then the throttle. The catalog changing on disk was the only
+// content-driven trigger the gate had, which left the case the reminder is actually for:
+// the session PIVOTING to a different kind of work (debugging → designing → releasing)
+// with a catalog that never moved, so the model kept whatever the throttle last emitted
+// and the skills that matter for the new nature were never re-surfaced. The nature is a
+// coarse lexical read of the prompt (lib/signals.mjs), and being wrong costs one extra
+// injection of a never-blocking catalog — cheap enough to prefer over staying silent.
+function injectionDecision(session, fingerprint, nature, settings) {
   const changed = session.fingerprint !== fingerprint;
+  const pivoted =
+    settings.reinjectOnWorkNatureChange && session.workNature !== nature;
   const nextCount = (Number(session.messageCount) || 0) + 1;
-  const shouldInject = changed || nextCount >= injectEveryMessages;
+  const shouldInject =
+    changed || pivoted || nextCount >= settings.injectEveryMessages;
   return { shouldInject, messageCount: shouldInject ? 0 : nextCount };
 }
 
@@ -417,22 +239,28 @@ function syncMap(mapPath, rawCatalog, fingerprint, root, settings) {
   return catalog;
 }
 
-function shouldInjectNow(sessionId, root, fingerprint, injectEveryMessages) {
+function shouldInjectNow(sessionId, root, fingerprint, nature, settings) {
   const session = readSessionState(GATE_ID, sessionId, {}, { cwd: root });
   const { shouldInject, messageCount } = injectionDecision(
     session,
     fingerprint,
-    injectEveryMessages,
+    nature,
+    settings,
   );
   writeSessionState(
     GATE_ID,
     sessionId,
-    { fingerprint, messageCount },
+    { fingerprint, messageCount, workNature: nature },
     { cwd: root },
   );
   return shouldInject;
 }
 
+function promptOf(payload) {
+  const prompt = payload?.prompt ?? payload?.user_prompt ?? payload?.message;
+  return typeof prompt === 'string' ? prompt : '';
+}
+
 function run() {
   const payload = readPayload();
   const cwd = cwdOf(payload);
@@ -455,7 +283,8 @@ function run() {
     payload.session_id ?? null,
     root,
     fingerprint,
-    settings.injectEveryMessages,
+    workNatureOf(promptOf(payload)),
+    settings,
   );
   if (inject) process.stdout.write(renderCatalog(catalog, settings.kinds));
 }

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

@@ -30,7 +30,6 @@ const CONFIG_KEY = 'requireCircuitBreakerOnDelegation';
 const DEFAULT_RETRY_THRESHOLD = 2;
 const MIN_RETRY_THRESHOLD = 2;
 const DEFAULT_SIMILARITY_THRESHOLD = 0.6;
-const MAX_ENTRIES_PER_KEY = 12;
 const MAX_OVERRIDE_SENTENCE_WORDS = 8;
 const MIN_TOKEN_LENGTH = 2;
 
@@ -391,18 +390,12 @@ runGate(
       return;
     }
 
+    // Count includes the current attempt (+1) against stored occurrences.
+    // Recording happens in the PostToolUse tracker (track.mjs), not here: a
+    // delegation rejected by ANOTHER gate (running in parallel) must not inflate
+    // the counter — only delegations that actually launched count as attempts.
     const count =
       1 + similarOccurrenceCount(state, signature, similarityThreshold);
-    const occurrences = [
-      ...occurrencesFor(state, key),
-      { signature, seenAt: Date.now() },
-    ].slice(-MAX_ENTRIES_PER_KEY);
-    writeSessionState(
-      GATE_ID,
-      sessionId,
-      { ...state, [key]: occurrences },
-      stateOptions,
-    );
 
     const retryThreshold = Math.max(
       MIN_RETRY_THRESHOLD,