@devrik-tools/claude-gates 0.7.2 → 0.9.0

package/plugins/gates/hooks/lib/session-state.mjs

@@ -0,0 +1,150 @@
+// session-state — per-session scratch state for gates that must remember something across
+// the separate process Claude Code spawns for every hook call (a retry counter, a timestamp,
+// a set of libraries already looked up). One implementation, so every stateful gate gets the
+// same guarantees:
+//
+//   - The session id is SANITIZED before it becomes a path segment: a payload carrying
+//     `../../x` or a number can neither escape the state root nor crash `path.join`.
+//   - A missing session id falls back to a bucket keyed by the PROJECT, not one global
+//     bucket shared by every session on the machine.
+//   - Writes are ATOMIC (temp file + rename), so a concurrent hook process never reads a
+//     half-written file.
+//   - Stale session directories are PRUNED opportunistically (older than `ttlMs`, default 7
+//     days), so %TEMP% does not accumulate one directory per session forever.
+//   - A read or write failure degrades to "no state" / "not persisted", never to a throw:
+//     a gate that cannot count must not block, and a warn-only gate must never deny
+//     because its temp directory was read-only.
+//
+// State lives under os.tmpdir()/claude-gates/<gateId>/<session>/state.json — never a path
+// that bakes in a username or a machine name.
+
+import { createHash } from 'node:crypto';
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+const STATE_ROOT = join(tmpdir(), 'claude-gates');
+const STATE_FILE = 'state.json';
+const NO_SESSION_PREFIX = 'no-session-';
+const MAX_SEGMENT_LENGTH = 80;
+const HASH_LENGTH = 12;
+const HOURS_PER_DAY = 24;
+const MINUTES_PER_HOUR = 60;
+const SECONDS_PER_MINUTE = 60;
+const MS_PER_SECOND = 1000;
+const MS_PER_DAY =
+  HOURS_PER_DAY * MINUTES_PER_HOUR * SECONDS_PER_MINUTE * MS_PER_SECOND;
+const DEFAULT_TTL_DAYS = 7;
+const DEFAULT_TTL_MS = DEFAULT_TTL_DAYS * MS_PER_DAY;
+// Pruning scans the gate's directory; doing it on every call would be wasteful, so it runs
+// on roughly one call in this many (cheap, and still bounds growth).
+const PRUNE_EVERY = 25;
+
+function shortHash(text) {
+  return createHash('sha256')
+    .update(String(text))
+    .digest('hex')
+    .slice(0, HASH_LENGTH);
+}
+
+/** A filesystem-safe, bounded segment for a session id; project-keyed when absent. */
+export function sessionSegmentFor(sessionId, cwd = process.cwd()) {
+  const raw = String(sessionId ?? '').trim();
+  if (!raw) return `${NO_SESSION_PREFIX}${shortHash(cwd)}`;
+  const safe = raw.replace(/[^\w-]/g, '_');
+  return safe.length > MAX_SEGMENT_LENGTH
+    ? `${safe.slice(0, MAX_SEGMENT_LENGTH - HASH_LENGTH - 1)}-${shortHash(raw)}`
+    : safe;
+}
+
+/** Where a gate's state for this session lives. */
+export function stateFileFor(gateId, sessionId, { cwd = process.cwd() } = {}) {
+  return join(
+    STATE_ROOT,
+    gateId,
+    sessionSegmentFor(sessionId, cwd),
+    STATE_FILE,
+  );
+}
+
+/** The persisted state object, or `fallback` when absent/corrupt/unreadable. */
+export function readSessionState(gateId, sessionId, fallback = {}, options) {
+  const path = stateFileFor(gateId, sessionId, options);
+  if (!existsSync(path)) return fallback;
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? parsed
+      : fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+function pruneStale(gateDirectory, ttlMs) {
+  try {
+    const cutoff = Date.now() - ttlMs;
+    for (const entry of readdirSync(gateDirectory, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const directory = join(gateDirectory, entry.name);
+      const file = join(directory, STATE_FILE);
+      const stamp = existsSync(file)
+        ? statSync(file).mtimeMs
+        : statSync(directory).mtimeMs;
+      if (stamp < cutoff) rmSync(directory, { recursive: true, force: true });
+    }
+  } catch {
+    // Pruning is housekeeping; failing at it never affects the gate.
+  }
+}
+
+/**
+ * Persists `state` atomically. Returns true when written, false when the write failed (the
+ * caller decides what "cannot persist" means for its rule — usually "cannot count").
+ */
+export function writeSessionState(
+  gateId,
+  sessionId,
+  state,
+  { cwd = process.cwd(), ttlMs = DEFAULT_TTL_MS } = {},
+) {
+  const path = stateFileFor(gateId, sessionId, { cwd });
+  const directory = dirname(path);
+  try {
+    mkdirSync(directory, { recursive: true });
+    const temporary = join(directory, `${STATE_FILE}.${process.pid}.tmp`);
+    writeFileSync(temporary, JSON.stringify(state), 'utf8');
+    renameSync(temporary, path);
+  } catch {
+    return false;
+  }
+  // Deterministic sampling on the clock, not Math.random: roughly one write in PRUNE_EVERY.
+  if (Date.now() % PRUNE_EVERY === 0) pruneStale(dirname(directory), ttlMs);
+  return true;
+}
+
+/**
+ * Read-modify-write in one call: `update(previous)` returns the next state, which is then
+ * persisted. Returns { state, persisted }.
+ */
+export function updateSessionState(
+  gateId,
+  sessionId,
+  fallback,
+  update,
+  options,
+) {
+  const previous = readSessionState(gateId, sessionId, fallback, options);
+  const next = update(previous);
+  const persisted = writeSessionState(gateId, sessionId, next, options);
+  return { state: next, persisted };
+}

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

@@ -85,7 +85,7 @@ export const RISK_SIGNAL_SOURCES = [
 // unsafe to trust this label/verb at all?").
 const MUTATION_RISK_TERMS =
   `${MONEY_TERMS}|${AUTH_TERMS}|credencial|credential|data|datos|borrar|delete|drop|` +
-  `write|escrib|${DESTRUCTIVE_DEPLOY_TERMS}`;
+  `write|escrib\\p{L}*|${DESTRUCTIVE_DEPLOY_TERMS}`;
 
 export const MUTATION_RISK_SIGNAL =
   withUnicodeWordBoundary(MUTATION_RISK_TERMS);
@@ -120,15 +120,14 @@ export const CONJECTURE = withUnicodeWordBoundary(CONJECTURE_SOURCES.join('|'));
 // to <file>" nearby is not flagged as depending on model memory.
 
 export const PERSISTENCE_VERB_SOURCES = [
-  'save|persist|store',
-  'guarda(?:l[oa])?|guard[aá]|persist[eií]|persistir|persistido|almacena|almacenar',
-  'escrib(?:e|í|i) .{0,20}en|escribir .{0,20}en|write .{0,20}(?:to|in)',
-  'anota|anotar|registra|registrar',
+  'sav(?:e|es|ed|ing)|persist\\p{L}*|stor(?:e|es|ed|ing)',
+  'guard\\p{L}*|almacen\\p{L}*',
+  'escrib\\p{L}* .{0,20}en|writ(?:e|es|ing) .{0,20}(?:to|in)',
+  'anot(?:a|á|ar|alo|en)|registr(?:a|á|ar|alo|en)',
 ];
 
-export const PERSISTENCE_VERB = new RegExp(
+export const PERSISTENCE_VERB = withUnicodeWordBoundary(
   PERSISTENCE_VERB_SOURCES.join('|'),
-  'iu',
 );
 
 // ── BUILD_INTENT: a request to CREATE a tool/helper (reuse-before-build) ─────────────
@@ -162,11 +161,17 @@ const BUILD_INTENT_MAX_GAP = 24;
  * followed by a tool noun), in Spanish or English. A method, not a bare regex, so each side
  * stays a small pattern and the "verb → noun proximity" rule is explicit. */
 export function isBuildIntent(text) {
-  const verbMatch = BUILD_VERB.exec(text);
-  if (!verbMatch) return false;
-  const after = text.slice(
-    verbMatch.index + verbMatch[0].length,
-    verbMatch.index + verbMatch[0].length + BUILD_INTENT_MAX_GAP,
+  const source = String(text ?? '');
+  const verbs = source.matchAll(
+    new RegExp(BUILD_VERB.source, `${BUILD_VERB.flags}g`),
   );
-  return BUILDABLE_NOUN.test(after);
+  for (const verbMatch of verbs) {
+    const start = verbMatch.index + verbMatch[0].length;
+    // Extend the window to the end of the word it lands in, so a noun is never cut in half
+    // ("components" must not match as "component" merely because the window ended there).
+    let end = start + BUILD_INTENT_MAX_GAP;
+    while (end < source.length && /[\p{L}\p{N}_]/u.test(source[end])) end += 1;
+    if (BUILDABLE_NOUN.test(source.slice(start, end))) return true;
+  }
+  return false;
 }

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

@@ -0,0 +1,148 @@
+// testing.mjs — the harness every gate test uses to run a gate exactly as Claude Code does:
+// as its own process, payload on stdin, inside a scratch project so config and state lookups
+// are isolated. One copy here instead of the same twenty lines pasted into every test file.
+//
+// Not imported by any gate at runtime; Node built-ins only.
+
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+/**
+ * A scratch project: a temp directory with a `.git` marker (so it is a project root), an
+ * optional `.ai/config.json`, and any extra files (`{ 'relative/path': content }`).
+ */
+export function makeProject({
+  prefix = 'gate-',
+  git = true,
+  config,
+  files = {},
+} = {}) {
+  const project = mkdtempSync(join(tmpdir(), prefix));
+  if (git) mkdirSync(join(project, '.git'));
+  if (config) {
+    mkdirSync(join(project, '.ai'), { recursive: true });
+    writeFileSync(join(project, '.ai', 'config.json'), JSON.stringify(config));
+  }
+  for (const [relative, content] of Object.entries(files)) {
+    const path = join(project, relative);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+  }
+  return project;
+}
+
+/**
+ * Runs a gate script against a payload and returns its parsed JSON output, or null when
+ * the gate allowed silently. `project` (or a fresh one built from `config`/`files`) is the
+ * cwd and the HOME, so global config never leaks in. The decision log is disabled unless
+ * `log` is true. Throws when the gate process exits non-zero (a crash is a test failure).
+ */
+export function runGateProcess(
+  gatePath,
+  payload,
+  {
+    project,
+    config,
+    files,
+    cwd,
+    environment = {},
+    log = false,
+    timeout = 15000,
+  } = {},
+) {
+  const root = project ?? makeProject({ config, files });
+  const options = {
+    input: typeof payload === 'string' ? payload : JSON.stringify(payload),
+    encoding: 'utf8',
+    cwd: cwd ?? root,
+    env: {
+      ...process.env,
+      HOME: root,
+      USERPROFILE: root,
+      CLAUDE_GATES_LOG: log ? '1' : '0',
+      ...environment,
+    },
+    timeout,
+  };
+  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. */
+export function decisionOf(result) {
+  if (!result) return null;
+  if (result.hookSpecificOutput?.permissionDecision === 'deny') return 'deny';
+  if (result.decision === 'block') return 'block';
+  if (typeof result.hookSpecificOutput?.additionalContext === 'string')
+    return 'warn';
+  return null;
+}
+
+export function isDeny(result) {
+  return decisionOf(result) === 'deny';
+}
+export function isWarn(result) {
+  return decisionOf(result) === 'warn';
+}
+export function isBlock(result) {
+  return decisionOf(result) === 'block';
+}
+
+/** The deny reason / warn context / block reason text, or ''. */
+export function messageOf(result) {
+  return (
+    result?.hookSpecificOutput?.permissionDecisionReason ??
+    result?.hookSpecificOutput?.additionalContext ??
+    result?.reason ??
+    ''
+  );
+}
+
+// ── Payload builders ────────────────────────────────────────────────────────────────
+export function bash(command, extra = {}) {
+  return { tool_name: 'Bash', tool_input: { command, ...extra } };
+}
+export function write(filePath, content = '', extra = {}) {
+  return {
+    tool_name: 'Write',
+    tool_input: { file_path: filePath, content, ...extra },
+  };
+}
+export function edit(filePath, newString, oldString = '', extra = {}) {
+  return {
+    tool_name: 'Edit',
+    tool_input: {
+      file_path: filePath,
+      old_string: oldString,
+      new_string: newString,
+      ...extra,
+    },
+  };
+}
+export function delegate(prompt, subagentType, extra = {}) {
+  const input = { prompt, ...extra };
+  if (subagentType !== undefined) input.subagent_type = subagentType;
+  return { tool_name: 'Agent', tool_input: input };
+}
+export function ask(question, options = [], extra = {}) {
+  return {
+    tool_name: 'AskUserQuestion',
+    tool_input: { questions: [{ question, options, ...extra }] },
+  };
+}
+export function withSession(payload, sessionId) {
+  return { ...payload, session_id: sessionId };
+}

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

@@ -0,0 +1,144 @@
+// tools.mjs — what counts as a "tool/helper" file and what counts as evidence that the
+// wheel was checked before building one. Shared by the discovery gates (reuse-before-build,
+// tool-map, audit-before-build), which previously carried three divergent copies of these
+// lists and three different audit-evidence regexes — so a build audited in Spanish was
+// allowed by one gate and never recorded by the other.
+//
+// Self-contained: Node built-ins only (plus signals.mjs, this plugin's own).
+
+import { withUnicodeWordBoundary } from './signals.mjs';
+
+/** Folder names (path segments) that mark a file as a tool/helper. */
+export const DEFAULT_TOOL_FOLDERS = [
+  'scripts',
+  'hooks',
+  'tools',
+  'gates',
+  'lib',
+  'utils',
+  'util',
+  'helpers',
+  'composables',
+  'components',
+  'services',
+  'shared',
+  'common',
+  'plugins',
+  'bin',
+];
+
+/** Extensions of code that can reinvent a wheel. */
+export const DEFAULT_TOOL_EXTENSIONS = [
+  '.mjs',
+  '.cjs',
+  '.js',
+  '.ts',
+  '.tsx',
+  '.jsx',
+  '.vue',
+  '.svelte',
+  '.py',
+  '.sh',
+  '.ps1',
+  '.go',
+  '.rs',
+];
+
+/** Regex sources; a new file whose basename matches any is a helper regardless of folder. */
+export const DEFAULT_TOOL_NAME_PATTERNS = [
+  String.raw`^use[A-Z]\w*\.`,
+  String.raw`(?:^|[-.])(?:helper|helpers|util|utils|service|wrapper|adapter|client|gate|hook|plugin)\.`,
+  String.raw`[A-Z]\w*(?:Helper|Util|Utils|Service|Wrapper|Adapter|Client)\.`,
+];
+
+/** File-name markers of a test or fixture: never a tool to reuse. */
+const TEST_FILE_PATTERNS = [
+  /(?:^|\/)(?:__tests__|__mocks__|__fixtures__|tests?|specs?|e2e|cypress)\//i,
+  /\.(?:test|spec|stories)\.[\w.]+$/i,
+  /(?:^|\/)test\.mjs$/i,
+];
+
+/** Whether a path is a test/spec/fixture file. */
+export function isTestPath(path) {
+  const normalized = String(path ?? '').replace(/\\/g, '/');
+  return TEST_FILE_PATTERNS.some((pattern) => pattern.test(normalized));
+}
+
+function segmentsOf(path) {
+  return String(path ?? '')
+    .replace(/\\/g, '/')
+    .split('/')
+    .filter(Boolean);
+}
+
+/** Whether any path SEGMENT (not substring) is one of `folders`, case-insensitively. */
+export function isUnderToolFolder(path, folders = DEFAULT_TOOL_FOLDERS) {
+  const wanted = new Set(folders.map((folder) => String(folder).toLowerCase()));
+  return segmentsOf(path)
+    .slice(0, -1)
+    .some((segment) => wanted.has(segment.toLowerCase()));
+}
+
+/** Whether the basename matches any of the tool-name patterns (invalid ones skipped). */
+export function hasToolName(path, patterns = DEFAULT_TOOL_NAME_PATTERNS) {
+  const base = segmentsOf(path).at(-1) ?? '';
+  return patterns.some((source) => {
+    try {
+      return new RegExp(source).test(base);
+    } catch {
+      return false;
+    }
+  });
+}
+
+/** Whether the path's extension is one of `extensions` (each with its leading dot). */
+export function hasToolExtension(path, extensions = DEFAULT_TOOL_EXTENSIONS) {
+  const lowered = String(path ?? '').toLowerCase();
+  return extensions.some((extension) =>
+    lowered.endsWith(String(extension).toLowerCase()),
+  );
+}
+
+/**
+ * Whether a written path is a tool/helper worth a reuse check: code by extension, not a
+ * test, and either under a tool folder or named like a helper.
+ */
+export function isToolPath(
+  path,
+  {
+    folders = DEFAULT_TOOL_FOLDERS,
+    extensions = DEFAULT_TOOL_EXTENSIONS,
+    namePatterns = DEFAULT_TOOL_NAME_PATTERNS,
+  } = {},
+) {
+  if (!path || !hasToolExtension(path, extensions)) return false;
+  if (isTestPath(path)) return false;
+  return isUnderToolFolder(path, folders) || hasToolName(path, namePatterns);
+}
+
+// Evidence that the wheel was checked, Spanish and English: a sentence stating that no
+// existing tool/helper covers this, or that the existing ones were audited/reviewed.
+const AUDIT_DONE_SOURCES = [
+  'no existing (?:tool|helper|script|gate|hook|utility|module|library|dependency)',
+  'no (?:tool|helper|script|gate|hook|utility) (?:covers|does|exists|handles)',
+  'nothing (?:existing|in the (?:repo|codebase|map)) covers',
+  'checked (?:the )?(?:tool map|existing (?:tools|helpers|code)|whether)',
+  'audited (?:the )?(?:tool map|existing|dependencies)',
+  'reuse (?:check|audit) done',
+  'justification:',
+  'no existe (?:una |un |ninguna |ning[uú]n )?(?:herramienta|helper|script|gate|hook|utilidad|m[oó]dulo|librer[ií]a|dependencia)',
+  'ning(?:una|[uú]n) (?:herramienta|helper|script|gate|hook|utilidad) (?:cubre|existe|hace|resuelve)',
+  'revis(?:é|e|amos|ado) (?:el mapa|las herramientas|el c[oó]digo existente|lo existente)',
+  'audit(?:é|e|amos|ado) (?:el mapa|las herramientas|lo existente|las dependencias)',
+  'justificaci[oó]n:',
+];
+
+/** Matches prose that states the reuse audit was done (ES + EN). */
+export const AUDIT_DONE_PATTERN = withUnicodeWordBoundary(
+  AUDIT_DONE_SOURCES.join('|'),
+);
+
+/** Whether the text carries an audit statement. */
+export function hasAuditEvidence(text) {
+  return AUDIT_DONE_PATTERN.test(String(text ?? ''));
+}

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

@@ -1,6 +1,6 @@
 {
   "name": "tasks",
-  "version": "0.7.2",
+  "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

@@ -112,12 +112,13 @@ function closeTask(
   if (!TERMINAL_STATUSES.has(status)) {
     return { error: `invalid terminal status: ${status}` };
   }
-  if (STATUS_REQUIRING_EVIDENCE.has(status) && !String(evidence ?? '').trim()) {
+  if (STATUS_REQUIRING_EVIDENCE.has(status) && evidence?.verified !== true) {
     return {
       error:
-        'closing a task as done requires evidence that it was attended and resolved ' +
-        '(test output, a diff, a verification note). Provide --evidence, or close it as ' +
-        'abandoned with a reason if it will not be finished.',
+        'closing a task as done requires VERIFIED evidence: a command that passed ' +
+        '(--check "<command>" [--expect <text>]) or a path that exists (--exists <path> ' +
+        '[--contains <text>]). Free text is not evidence. Close it as abandoned with a ' +
+        'reason if it will not be finished.',
     };
   }
   const activeCollection = readCollection(activePath);
@@ -128,8 +129,7 @@ function closeTask(
   task.status = status;
   task.closedAt = new Date().toISOString();
   task.closeReason = reason ?? '';
-  if (STATUS_REQUIRING_EVIDENCE.has(status))
-    task.evidence = String(evidence).trim();
+  if (STATUS_REQUIRING_EVIDENCE.has(status)) task.evidence = evidence;
 
   const historyCollection = readCollection(historyPath);
   historyCollection.tasks.push(task);
@@ -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);