@devrik-tools/claude-gates 0.8.0 → 1.0.0

package/plugins/gates/hooks/lib/capabilities.mjs

@@ -0,0 +1,401 @@
+// capabilities.mjs — the shared definition of "what AI capabilities does this project
+// have". Discovery is one implementation here, so the two halves of the capability pair
+// cannot drift apart, exactly like lib/tools.mjs serves reuse-before-build and tool-map:
+//   · capability-map (UserPromptSubmit) renders the catalog INTO the model's context;
+//   · skill-first (PreToolUse) reads the same catalog to judge whether the action about
+//     to run has a skill that already covers it.
+// Two gates deriving the catalog from two private copies of `readdirSync` was the drift
+// this module exists to prevent.
+//
+// The catalog IS the directory listing, never a hardcoded copy, so it is autosynced by
+// construction. Project roots are scanned BEFORE ~/.claude so a project capability
+// shadows a global one of the same name. `.agents/skills` and `.ai/skills` (home and
+// project) are scanned as skill-only roots because other installers write there.
+//
+// Node built-ins only: a gate importing this must keep working installed on its own.
+
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, extname, isAbsolute, join } from 'node:path';
+
+export const KIND_EXTENSIONS = Object.freeze({
+  agents: ['.md'],
+  commands: ['.md', '.toml'],
+});
+
+function isDirectory(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export 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.
+export 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 };
+}
+
+export 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()}…`;
+}
+
+export 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);
+}
+
+export 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)),
+  ];
+}
+
+export function fileRootsFor(root, kind, extraDirectories = []) {
+  return [
+    join(root, '.claude', kind),
+    join(homedir(), '.claude', kind),
+    ...extraDirectories.map((directory) => resolveExtra(root, directory)),
+  ];
+}
+
+function extraDirectoriesFor(kind, settings) {
+  if (kind === 'agents') return settings.extraAgentsDirs ?? [];
+  if (kind === 'commands') return settings.extraCommandsDirs ?? [];
+  return settings.extraSkillsDirs ?? [];
+}
+
+function collectKind(kind, root, settings) {
+  const extra = extraDirectoriesFor(kind, settings);
+  if (kind === 'skills')
+    return skillRootsFor(root, extra).flatMap(skillEntriesUnder);
+  const extensions = KIND_EXTENSIONS[kind];
+  if (!extensions) return [];
+  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.
+export 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));
+}
+
+/** The raw catalog `{ kind: [{ name, description, stamp }] }`, kinds with no entry omitted. */
+export 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;
+}
+
+// ── Relevance ───────────────────────────────────────────────────────────────────────
+// Which capabilities plausibly cover the action about to run. Deliberately a LEXICAL
+// heuristic over the catalog's own front matter, not a model call: a gate is a
+// deterministic process with no network, and a skill's `description` is already written
+// as its trigger ("Use when the user asks about…"), so it is the honest thing to match
+// against. Two independent signals, because each alone is weak:
+//   · the capability's NAME appearing in the action text — precise, near zero false
+//     positives, but silent whenever the model never names the skill (the common case);
+//   · TOKEN OVERLAP with the description — catches the unnamed case, at the cost of
+//     needing a threshold to stay quiet.
+// Honest limitation: no lexical rule recognizes a paraphrase that shares no vocabulary
+// with the description. This narrows the blind spot, it does not close it — which is why
+// the gate that consumes it ships off by default and clears on an explicit statement.
+
+const MIN_TOKEN_LENGTH = 4;
+const NAME_MATCH_SCORE = 100;
+const DEFAULT_MIN_TOKEN_OVERLAP = 3;
+const DEFAULT_MAX_MATCHES = 3;
+const MAX_TEXT_CHARS = 20000;
+
+// Words carrying no discriminating power in this domain: they appear in almost every
+// skill description AND in almost every prompt, so counting them as overlap would make
+// every action match every skill. ES + EN, matching lib/signals.mjs's bilingual scope.
+const STOPWORDS = new Set(
+  (
+    'this that they them then than with when what which while where whose whom about ' +
+    'into onto from over under after before during your yours their there these those ' +
+    'have has had having been being does doing done should would could must will shall ' +
+    'also only just very much more most less least other others same such each every ' +
+    'user users use uses used using make makes made need needs needed want wants ' +
+    'skill skills agent agents command commands claude anthropic tool tools ' +
+    'file files code codebase project projects repo repository directory folder ' +
+    'work works working task tasks thing things stuff item items step steps ' +
+    'help helps helping ask asks asked answer answers question questions ' +
+    'para pero como cuando donde porque aunque desde hasta sobre entre segun ' +
+    'este esta estos estas esto aquel aquella ellos ellas nosotros ustedes ' +
+    'tiene tienen tener teniendo hacer hace hacen hecho hacia siendo estar ' +
+    'debe deben debes puede pueden podes podemos quiere quieren necesita necesitan ' +
+    'usuario usuarios usar usando usa archivo archivos carpeta directorio ' +
+    'proyecto proyectos codigo tarea tareas cosa cosas paso pasos ' +
+    'cualquier cualquiera todos todas alguno alguna mismo misma otro otra ' +
+    'ayuda ayudar pregunta preguntas respuesta respuestas'
+  ).split(/\s+/),
+);
+
+const WORD_SEPARATOR = /[^\p{L}\p{N}]+/u;
+
+/** Distinctive lowercase tokens of a text: long enough, and not a domain stopword. */
+export function distinctiveTokens(text) {
+  const tokens = new Set();
+  for (const raw of String(text ?? '')
+    .slice(0, MAX_TEXT_CHARS)
+    .toLowerCase()
+    .split(WORD_SEPARATOR)) {
+    if (raw.length >= MIN_TOKEN_LENGTH && !STOPWORDS.has(raw)) tokens.add(raw);
+  }
+  return tokens;
+}
+
+function escapeRegExpSource(text) {
+  return String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// A capability's name is written `code-review` / `a11y_doctrine` but referred to in prose
+// as "code review", so both spellings must count as naming it.
+function namePattern(name) {
+  const spaced = String(name)
+    .split(/[-_]/)
+    .filter(Boolean)
+    .map(escapeRegExpSource)
+    .join('[\\s\\-_]*');
+  if (!spaced) return null;
+  try {
+    return new RegExp(`(?<![\\p{L}\\p{N}_])${spaced}(?![\\p{L}\\p{N}_])`, 'iu');
+  } catch {
+    return null;
+  }
+}
+
+function triggerTokensOf(entry) {
+  return distinctiveTokens(
+    `${String(entry.name).replace(/[-_]/g, ' ')} ${entry.description ?? ''}`,
+  );
+}
+
+// How many catalog entries mention each token. A token nearly every skill uses
+// ("analytics", "build") says almost nothing about WHICH skill fits, while a token only
+// one skill uses ("tooltip") is close to decisive — so ranking by a raw token count
+// hands the match to whichever skill happens to have the longest, most generic
+// description. Weighting each shared token by 1/frequency is what makes the deny name
+// the skill that actually fits: it is the ranking, not the threshold, so `minTokenOverlap`
+// keeps meaning a plain, predictable count of shared tokens.
+function documentFrequencies(tokenSets) {
+  const frequencies = new Map();
+  for (const tokens of tokenSets) {
+    for (const token of tokens)
+      frequencies.set(token, (frequencies.get(token) ?? 0) + 1);
+  }
+  return frequencies;
+}
+
+function scoreEntry(
+  entry,
+  triggerTokens,
+  actionTokens,
+  actionText,
+  frequencies,
+) {
+  const pattern = namePattern(entry.name);
+  const named = pattern !== null && pattern.test(actionText);
+  const shared = [];
+  let weight = 0;
+  for (const token of triggerTokens) {
+    if (!actionTokens.has(token)) continue;
+    shared.push(token);
+    weight += 1 / (frequencies.get(token) ?? 1);
+  }
+  // The rarest shared tokens first, so the deny message explains the match with the
+  // words that actually drove it.
+  shared.sort((a, b) => (frequencies.get(a) ?? 1) - (frequencies.get(b) ?? 1));
+  return {
+    named,
+    overlap: shared.length,
+    shared,
+    score: (named ? NAME_MATCH_SCORE : 0) + weight,
+  };
+}
+
+/**
+ * The capabilities that plausibly cover `actionText`, strongest first. A capability
+ * qualifies when the action NAMES it, or when it shares at least `minTokenOverlap`
+ * distinctive tokens with its description. Returns `[]` — the common, silent path —
+ * whenever nothing clears the bar.
+ */
+export function relevantCapabilities(actionText, entries, options = {}) {
+  const minTokenOverlap = options.minTokenOverlap ?? DEFAULT_MIN_TOKEN_OVERLAP;
+  const maxMatches = options.maxMatches ?? DEFAULT_MAX_MATCHES;
+  const text = String(actionText ?? '').slice(0, MAX_TEXT_CHARS);
+  if (!text.trim()) return [];
+  const actionTokens = distinctiveTokens(text);
+  if (actionTokens.size === 0) return [];
+
+  const named = (entries ?? []).filter((entry) => entry?.name);
+  const tokenSets = named.map(triggerTokensOf);
+  const frequencies = documentFrequencies(tokenSets);
+
+  const matches = [];
+  for (const [index, entry] of named.entries()) {
+    const scored = scoreEntry(
+      entry,
+      tokenSets[index],
+      actionTokens,
+      text,
+      frequencies,
+    );
+    if (!scored.named && scored.overlap < minTokenOverlap) continue;
+    matches.push({ name: entry.name, ...scored });
+  }
+  return matches.sort((a, b) => b.score - a.score).slice(0, maxMatches);
+}
+
+// ── The audit statement that clears the check ───────────────────────────────────────
+// One explicit sentence, in the written content or the delegation prompt, in ES or EN.
+// The point is not the wording: it is that a decision about skills was made and recorded
+// where a reader will see it, instead of the question never being asked.
+// An optional capability name may sit between the verb and the noun ("using the dataviz
+// skill"), so the name is allowed but never required.
+const AUDIT_NAME = String.raw`(?:the\s+)?(?:[\w./-]+\s+)?`;
+
+export const SKILL_AUDIT_PATTERN = new RegExp(
+  [
+    String.raw`(?:using|used|use|via|per|applying|apply)\s+${AUDIT_NAME}skills?\b`,
+    String.raw`\bskills?\s*[:=]\s*\S`,
+    String.raw`\bno\s+skills?\s+(?:covers?|applies|apply|matches|match|fits)\b`,
+    String.raw`\bskill[-\s]checked\b`,
+    String.raw`(?:ninguna|sin)\s+skill`,
+    String.raw`(?:usando|uso|use|aplicando)\s+(?:la\s+)?(?:[\w./-]+\s+)?skill`,
+    String.raw`\bskill\s+(?:relevante|aplicable)`,
+  ].join('|'),
+  'iu',
+);
+
+/** Whether a text carries the explicit statement that skills were considered. */
+export function hasSkillAuditEvidence(text) {
+  return SKILL_AUDIT_PATTERN.test(String(text ?? ''));
+}

package/plugins/gates/hooks/lib/hook-io.mjs

@@ -58,6 +58,11 @@ export const TOOL_GROUPS = Object.freeze({
   ],
   // Research surfaces: the web and documentation lookups the research gates sequence.
   research: ['WebSearch', 'WebFetch'],
+  // Observation tool for background processes.
+  monitor: ['Monitor'],
+  // Loading a packaged capability. Tracked (not blocked) so a gate can tell whether the
+  // model actually reached for a skill during this session.
+  skill: ['Skill'],
 });
 
 /** Every concrete tool name a set of groups expands to, de-duplicated. */
@@ -91,6 +96,8 @@ const MCP_GROUP_SIGNALS = Object.freeze({
   execution:
     /(?:write|edit|create|append|patch|replace|insert|modify|save|update|shell|bash|exec|run|command|terminal|process|spawn|cmd|powershell|sh)/i,
   research: /(?:search|fetch|browse|docs|documentation|library|lookup|query)/i,
+  monitor: /(?:monitor|observe|watch|stream|tail|follow|subscribe)/i,
+  skill: /(?:skill|capability|playbook)/i,
 });
 
 const MCP_TOOL_PREFIX = 'mcp__';
@@ -560,10 +567,10 @@ export function allow() {
 /** A Stop-hook block: makes the agent continue instead of ending the turn. */
 export function block(label, reason) {
   record(DECISIONS.BLOCK, reason);
-  process.stdout.write(
+  process.stderr.write(
     JSON.stringify({ decision: 'block', reason: `[${label}] ${reason}` }),
   );
-  process.exit(0);
+  process.exit(2);
 }
 
 export const SEVERITY = Object.freeze({ DENY: 'deny', WARN: 'warn' });

package/plugins/gates/hooks/lib/signals.mjs

@@ -175,3 +175,94 @@ export function isBuildIntent(text) {
   }
   return false;
 }
+
+// ── WORK_NATURE: what KIND of work a prompt is asking for ───────────────────────────
+// Used by capability-map to answer "did the nature of the work change?" — the trigger the
+// catalog injection was missing. Its previous re-injection rule fired only when the
+// CATALOG changed on disk, so a session that pivoted from debugging to designing kept
+// whatever stale reminder the throttle had last emitted.
+//
+// This is a coarse lexical classifier, and deliberately so: a wrong answer costs one
+// extra (harmless, never-blocking) injection of a catalog the model can ignore, so the
+// bar for a term is "does it usually signal this kind of work", not certainty. Order
+// matters for ties — the more specific natures are declared before the generic ones,
+// because `implement`'s verbs (write/create/add) also appear inside every other nature.
+
+const WORK_NATURE_TERMS = [
+  [
+    'debug',
+    'debug|debugg\\p{L}*|depur\\p{L}*|bug|bugs|error|errores|falla|fallas|fallando|' +
+      'broken|roto|rota|crash|crashes|traceback|stacktrace|reproduce|reproducir|' +
+      'arregl\\p{L}*|corrig\\p{L}*|corregir|fix|fixes|fixing|diagnos\\p{L}*',
+  ],
+  [
+    'test',
+    'test|tests|testing|prueba|pruebas|probar|spec|specs|coverage|cobertura|' +
+      'assert|asserts|asercion\\p{L}*|jest|vitest|mocha|pytest|e2e|fixture|fixtures',
+  ],
+  [
+    'review',
+    'review|reviews|revis\\p{L}*|auditor\\p{L}*|audit|audita|lint|linter|' +
+      'code review|pull request|diff',
+  ],
+  [
+    'release',
+    'deploy|desplieg\\p{L}*|release|publica|publicar|publish|ship|version|versionar|' +
+      'changelog|commit|merge|tag|rollout',
+  ],
+  [
+    'refactor',
+    'refactor\\p{L}*|simplif\\p{L}*|clean up|limpi\\p{L}*|renombr\\p{L}*|rename|' +
+      'extract|extraer|deduplicat\\p{L}*|reorganiz\\p{L}*|migrate|migrar',
+  ],
+  [
+    'design',
+    'design|dise[nñ]\\p{L}*|mockup|wireframe|layout|maqueta|estilo|estilos|' +
+      'css|tailwind|figma|paleta|palette|tipograf\\p{L}*|responsive',
+  ],
+  [
+    'docs',
+    'readme|changelog|documenta\\p{L}*|documentation|docstring|tutorial|guide|gu[ií]a|' +
+      'manual|comentar|comment|comments',
+  ],
+  [
+    'research',
+    'research|investig\\p{L}*|explor\\p{L}*|explore|averigu\\p{L}*|analiz\\p{L}*|' +
+      'analyze|analysis|compare|comparar|evalu\\p{L}*|study|estudiar|find out|' +
+      'entender|understand|search|buscar',
+  ],
+  [
+    'implement',
+    'implement\\p{L}*|build|construi\\p{L}*|construye|create|crear|crea|' +
+      'write|escrib\\p{L}*|add|agreg\\p{L}*|a[nñ]ad\\p{L}*|feature|funcionalidad|' +
+      'endpoint|componente|component|integra\\p{L}*',
+  ],
+];
+
+const GENERAL_WORK_NATURE = 'general';
+
+const WORK_NATURE_PATTERNS = WORK_NATURE_TERMS.map(([nature, terms]) => [
+  nature,
+  new RegExp(withUnicodeWordBoundary(terms).source, 'giu'),
+]);
+
+/**
+ * The dominant kind of work a text is asking for, or 'general' when nothing matches.
+ * Scored by how many nature terms occur, so a passing mention loses to a sustained one;
+ * ties go to whichever nature is declared first (most specific wins).
+ */
+export function workNatureOf(text) {
+  const source = String(text ?? '');
+  if (!source.trim()) return GENERAL_WORK_NATURE;
+  let best = GENERAL_WORK_NATURE;
+  let bestScore = 0;
+  for (const [nature, pattern] of WORK_NATURE_PATTERNS) {
+    pattern.lastIndex = 0;
+    const score = [...source.matchAll(pattern)].length;
+    if (score > bestScore) {
+      best = nature;
+      bestScore = score;
+    }
+  }
+  return best;
+}

package/plugins/gates/hooks/lib/testing.mjs

@@ -53,7 +53,7 @@ export function runGateProcess(
   } = {},
 ) {
   const root = project ?? makeProject({ config, files });
-  const out = execFileSync(process.execPath, [gatePath], {
+  const options = {
     input: typeof payload === 'string' ? payload : JSON.stringify(payload),
     encoding: 'utf8',
     cwd: cwd ?? root,
@@ -65,9 +65,20 @@ export function runGateProcess(
       ...environment,
     },
     timeout,
-  });
-  const trimmed = out.trim();
-  return trimmed ? JSON.parse(trimmed) : null;
+  };
+  try {
+    const out = execFileSync(process.execPath, [gatePath], options);
+    const trimmed = out.trim();
+    return trimmed ? JSON.parse(trimmed) : null;
+  } catch (error) {
+    if (error.status === 2) {
+      const stderr = String(error.stderr ?? '').trim();
+      const stdout = String(error.stdout ?? '').trim();
+      const source = stderr || stdout;
+      return source ? JSON.parse(source) : null;
+    }
+    throw error;
+  }
 }
 
 /** 'deny' | 'warn' | 'block' | null from a gate's parsed output. */

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

@@ -1,6 +1,6 @@
 {
   "name": "tasks",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Deterministic task tracking for Claude Code: persists tasks the model registers via the CLI, reminds of open tasks on a message counter, and lists active tasks on session start.",
   "author": {
     "name": "Devrik"

package/plugins/tasks/hooks/lib/task-store.mjs

@@ -170,6 +170,12 @@ export function openTaskStore(startDirectory) {
       writeCollection(activePath, collection);
       return task;
     },
+    /** Active sub-tasks whose parentId equals the given id. */
+    childrenOf(id) {
+      return readCollection(activePath).tasks.filter(
+        (task) => task.parentId === id,
+      );
+    },
     /** Merges fields into the active task with matching id. Null if not found. */
     update(id, fields) {
       const collection = readCollection(activePath);

package/plugins/tasks/hooks/register-requests.mjs

@@ -77,17 +77,44 @@ function readPayload() {
 
 // Asked on every message. The hook does not classify — it asks the model to, and the
 // model is the one that persists (via the CLI, which enforces the store's own rules,
-// e.g. evidence on close). This is legitimate: the hook is not depending on the model to
-// make something OCCUR deterministically; it is depending on the model's judgment for a
-// judgment call (whether this message describes a new task), same shape as ask-adoption.
+// e.g. evidence on close). Default to registering: the USER defines what is a task, not
+// the model. The model must not use judgment to skip what the user considers actionable.
 const CLASSIFY_PROMPT =
-  '[tasks] MANDATORY before you respond: judge whether the message you just received describes ' +
-  'a new actionable task (not a question, not small talk, not a follow-up on an already-registered ' +
-  'task). If it does, you MUST register it now, before writing your reply — run ' +
-  '`claude-gates task add "<title>" [--description <text>] [--size <size>]` from the project root ' +
-  "(or the CLI's absolute path if `claude-gates` is not on PATH). Do not defer this, do not decide " +
-  'to register it "later", do not silently skip it because the answer seems obvious. If it is not a ' +
-  'new task, skip registration — do not fabricate one.';
+  "[tasks] MANDATORY — before writing your reply, you MUST register the user's message as a " +
+  'task unless it is UNAMBIGUOUSLY one of these: (a) pure small talk with no request ("hello", ' +
+  '"thanks"), (b) a yes/no answer to a question YOU asked, (c) a message that says only "continue" ' +
+  'or "go ahead". Everything else is a task — including questions that require research, review ' +
+  'requests, error reports, follow-ups that add scope, corrections, and messages with multiple ' +
+  'requests (register one task per distinct request). DEFAULT TO REGISTERING: when in doubt, ' +
+  'register.\n\n' +
+  'VERIFICATION REQUIRED: every task MUST include a deterministic verification criterion. Use ' +
+  'one of these:\n' +
+  '  --verify-command "<shell command>" [--verify-expect <text>]  (command must exit 0 when done)\n' +
+  '  --verify-path <file-or-dir> [--verify-contains <text>]       (must exist when done)\n' +
+  'Examples:\n' +
+  '  claude-gates task add "Fix login bug" --verify-command "npm test -- --grep login" --verify-expect "passing"\n' +
+  '  claude-gates task add "Add config file" --verify-path "src/config.ts" --verify-contains "export"\n' +
+  'Pick the criterion that a machine can check: a test that passes, a file that exists, a grep ' +
+  'that matches. If the task is a question/research, use --verify-path for the file where the ' +
+  'answer will be written, or --verify-command "claude-gates task list" --verify-expect "done".\n\n' +
+  'SPLITTING (Depth Tree): tasks with size medium or larger MUST be split into sub-tasks before ' +
+  'implementation. SCOPE FIRST: if the task description is vague or you are unsure what files or ' +
+  'modules are affected, ASK THE USER to clarify the scope before splitting — do not guess. ' +
+  'Once scope is clear:\n' +
+  '  1. Each sub-task OWNS specific files (state in --description "OWNS: <paths>") — no overlap\n' +
+  '  2. Each sub-task is --size small and independently verifiable\n' +
+  '  3. Split at natural boundaries: one module, one function, one test file\n' +
+  '  4. Register parent first, then sub-tasks with --parent <parent-id>\n' +
+  'Example:\n' +
+  '  claude-gates task add "Refactor auth" --size large --verify-command "npm test" --verify-expect "passing"\n' +
+  '  claude-gates task add "Extract token validation" --parent <id> --size small ' +
+  '--verify-path "src/auth/validate.ts" --description "OWNS: src/auth/validate.ts"\n' +
+  '  claude-gates task add "Add token refresh" --parent <id> --size small ' +
+  '--verify-command "npm test -- --grep refresh" --description "OWNS: src/auth/refresh.ts"\n\n' +
+  'Run `claude-gates task add "<title>" [--description <text>] [--size <size>] --verify-command|--verify-path ...` ' +
+  "from the project root (or the CLI's absolute path if `claude-gates` is not on PATH). Do not defer " +
+  'this, do not decide to register it "later", do not silently skip it because the answer seems ' +
+  "obvious. The user's flow takes priority over your judgment of what deserves tracking.";
 
 function formatReminder(tasks) {
   const shown = tasks.slice(0, MAX_TASKS_SHOWN);