docket-agent 0.2.0 → 0.3.0

package/README.md

@@ -7,7 +7,10 @@
 Before your agent acts, it checks a one-page rule file you wrote: allow, ask,
 or deny. After, it leaves a tamper-evident record. Anything you didn't write
 down, the agent must ask about. Plain Markdown in your repo; works with
-Claude, Codex, Cursor, and any MCP client.
+Claude, ChatGPT/Codex, Gemini, Cursor, OpenClaw, Hermes, and any MCP client.
+
+**Install:** `npm install -g docket-agent` · **Docs:**
+[shahcolate.github.io/docket/docs.html](https://shahcolate.github.io/docket/docs.html)
 
 Zero dependencies · plain Markdown + JSONL · MIT
 
@@ -176,6 +179,42 @@ $ docket compile --target cursor --write    # → .cursor/rules/docket.mdc
 Same loops, every tool. **A model switch is a recompile, not a re-teach** —
 try the new tool, point it at the same files, keep working.
 
+## Fifty loops, flat context
+
+Compiling every brief and procedure into the context file stops scaling
+around a handful of loops — the rules start crowding out the work. So
+**rules scale on disk, not in context**:
+
+```console
+$ docket compile --index --target claude --write
+✓ compiled index of 23 loops → CLAUDE.md
+```
+
+`--index` compiles the protocol plus **one line per loop** — name,
+description, and the loop's `triggers` — instead of the loops themselves.
+The agent routes each task to its loop, then pulls just that loop in full:
+
+```console
+$ docket match "draft an appeal for my denied claim"
+1 candidate loop for "draft an appeal for my denied claim"
+
+  appeal                 Build the appeal, cite the policy — stop before send.
+                         score 14 — name: appeal · trigger: denied claim, denial letter
+
+$ docket match "wire funds to a vendor"
+NO LOOP  "wire funds to a vendor"
+  No loop covers this task. Work outside a loop defaults to ask
+```
+
+Routing is deterministic and scored — loop name, author-written `triggers`
+phrases, warrant targets, description overlap — and it **fails closed**: no
+match doesn't mean "best guess", it means *stop and ask*, exit code `2`,
+same as the warrant. And enforcement never needed context residency at all:
+the warrant check runs outside the model and injects the one matched rule
+exactly when it becomes relevant. What stays resident is a table of
+contents; the window holds one open chapter; the checker never forgets any
+of it.
+
 ## Agents can use it natively (MCP)
 
 `docket mcp` is a zero-config MCP server. Add it to Claude Code:
@@ -190,11 +229,12 @@ or to any MCP client:
 { "mcpServers": { "docket": { "command": "npx", "args": ["docket-agent", "mcp"] } } }
 ```
 
-The agent gets four tools:
+The agent gets five tools:
 
 | Tool | What it does |
 |---|---|
 | `docket_list_loops` | discover your loops |
+| `docket_match_loop` | route a task to the loop that covers it — ranked, fail-closed |
 | `docket_loop_context` | pull a loop's five layers before starting |
 | `docket_warrant_check` | allow / ask / deny, **before** acting — auto-logged |
 | `docket_record` | add a verifiable record entry when it finishes or stops |
@@ -202,6 +242,76 @@ The agent gets four tools:
 Warrant checks made by the agent land in the record too. *"Did the agent
 even ask?"* becomes a grep.
 
+## Make it mechanical (Claude Code hooks)
+
+Compiled context tells the agent the rules; MCP makes checking cheap. For
+the tool calls you actually fear, make the warrant **mechanical** — wire it
+into Claude Code's permission system as a PreToolUse hook, in
+`.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Write|Edit",
+        "hooks": [{ "type": "command", "command": "npx docket-agent hook claude" }]
+      }
+    ]
+  }
+}
+```
+
+Every matched tool call now passes through the warrant *before it runs*:
+**deny** blocks the call and tells the model why, **ask** makes Claude Code
+prompt you, and **allow** stays silent — docket only ever *tightens* the
+gate; it never bypasses Claude Code's own permission prompts. Without
+`--loop` the hook routes each call with the same scoring as `docket match`
+and stays out of the way when no loop claims the call (pin one loop with
+`--loop <name>`; add `--strict` to force an ask instead). Every check lands
+on the record with `via: "hook"` — enforcement and evidence in one move.
+
+## OpenClaw and Hermes
+
+**[OpenClaw](https://docs.openclaw.ai)** injects your workspace's `AGENTS.md`
+into the agent's system prompt at the start of every session — so compile
+straight into the workspace (fitting, given the story that opens this README):
+
+```console
+$ cd ~/.openclaw/workspace
+$ npx docket-agent init
+$ npx docket-agent new followup --template client-follow-up
+$ npx docket-agent compile --target agents --write
+```
+
+Docket only manages its own marked block inside `AGENTS.md` — your existing
+rules, `SOUL.md`, and the rest of the workspace stay untouched. OpenClaw can
+also run the MCP server for native checks and record entries: add `docket`
+as an MCP server in your OpenClaw config with
+`command: npx, args: ["-y", "docket-agent", "mcp", "--dir", "~/.openclaw/workspace"]`.
+
+**[Hermes](https://hermes-agent.nousresearch.com/docs/)** (Nous Research)
+reads `AGENTS.md` context files too — run the same three commands in the
+directory Hermes works from. For native tools, add docket under the MCP
+servers section of `~/.hermes/config.yaml`:
+
+```yaml
+docket:
+  command: npx
+  args: ["-y", "docket-agent", "mcp", "--dir", "/path/to/your/project"]
+```
+
+Any other agent that reads `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, or speaks
+MCP gets the same treatment — one loop file, every agent under the same
+warrant.
+
+## Documentation
+
+The full guide — concepts, loop-file reference, the verdict algorithm,
+matching semantics, record internals, CLI reference, and per-tool setup —
+lives at **[the docs site](https://shahcolate.github.io/docket/docs.html)**.
+The normative format definition is the [Loop File Spec](spec/SPEC.md).
+
 ## Five questions, then the loop exists
 
 `docket new <name>` interviews you:
@@ -271,11 +381,11 @@ Read the [Loop File Spec](spec/SPEC.md) — it's short on purpose.
 
 ## Roadmap
 
+- [x] `docket check` as a Claude Code PreToolUse hook — shipped as `docket hook claude`
 - [ ] Signed record heads (attest the chain tip, share the attestation)
-- [ ] `docket check` as a Claude Code PreToolUse hook recipe
 - [ ] Loop inheritance (`extends:`) for team baselines
 - [ ] Record export → human-readable work summaries
-- [ ] Adapters: OpenAI custom instructions, Gemini, Windsurf
+- [ ] Adapters: OpenAI custom instructions, Windsurf
 
 ## Contributing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docket-agent",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The permission layer and paper trail for AI agents. Your agent checks a rule file before it acts - allow, ask, or deny - and leaves a tamper-evident record after.",
   "type": "module",
   "bin": {

package/spec/SPEC.md

@@ -67,6 +67,7 @@ in frontmatter because tools enforce structure well.
 | `description` | string | no | one line, shown in listings and compiled context |
 | `version` | number | no | spec version, default `1` |
 | `warrant` | map | no | see below |
+| `triggers` | list of strings | no | phrases that mark a task as this loop's job; used only for routing (see below) |
 | `reserved` | list of strings | no | what stays with the human, always |
 | `record` | list of strings | no | what the agent must report when it finishes or stops |
 
@@ -170,6 +171,43 @@ system degrades toward the human, never away.
 `docket check` exits `0` for allow, `2` for ask, `3` for deny (and `1` for
 usage errors), so shells, hooks, and CI can gate on the warrant directly.
 
+## Routing: which loop covers this task?
+
+With more than a handful of loops, the agent should not hold every brief and
+procedure in context — it holds an index and pulls one loop at a time (see
+*Compiled context* below). Something then has to answer "which one?", and it
+must be deterministic: `docket match "<task>"` / the `docket_match_loop` MCP
+tool.
+
+Scoring is lexical, integer-weighted, and reuses the warrant's cautious
+matcher (patterns split into alternatives; content words compare under
+stemming):
+
+| Signal | Weight | Notes |
+|---|---|---|
+| loop `name`, read as a phrase (dashes as spaces) | +5 | qualifies on its own |
+| each matching `triggers` entry | +4 | qualifies on its own |
+| each matching warrant pattern (any list) | +1 | capped at +3 per loop |
+| each distinct content word shared with `description` | +1 | capped at +3 per loop |
+
+Candidates need a score of **3** or more; they rank by score, then name, and
+implementations should return a short list (default 3) for the agent — or the
+human — to make the final pick from.
+
+Two rules matter more than the weights:
+
+- **The asymmetry principle inverts at routing time.** The warrant matches
+  allow-entries strictly because a false allow is an incident. Routing
+  matches generously because a false candidate costs one extra index line —
+  and a routing miss is still caught downstream by the warrant.
+- **Retrieval fails closed.** When nothing clears the bar, the answer is not
+  "best guess" — it is *no loop covers this task, ask the human*. `docket
+  match` exits `2` (the same exit as an `ask` verdict) so hooks can gate on
+  it; `0` means matched, `1` a usage error.
+
+Routing is advisory and read-only: a match is not an action, so it is not
+written to the record. The warrant checks that follow are.
+
 ## The record
 
 The record is the audit half of the trust story: *what did the agent see,
@@ -244,9 +282,30 @@ and (with `--write`) inserts or replaces that block in the target file:
 Content outside the markers is never touched. Because every target renders
 from the same loops, moving to a new tool is a recompile, not a re-teach.
 
+### The index: rules scale on disk, not in context
+
+The full render puts every brief and procedure in the agent's context on
+every turn — O(loops × loop size), which crowds out the actual work as loops
+accumulate. `docket compile --index` renders the same managed block in
+**tiers** instead:
+
+- **Tier 0 — protocol** (invariant with loop count): find the loop, load it,
+  check the warrant before acting, ask when nothing covers the task.
+- **Tier 1 — index**: one line per loop — name, description, triggers. The
+  routing table.
+- **Tier 2 — the active loop**: loaded on demand via `docket compile --loop
+  <name>` or `docket_loop_context`, only for the task at hand.
+
+Enforcement never needed residency at all: the warrant check runs outside the
+model, and its verdict text carries the one matched rule into the
+conversation exactly when it becomes relevant. The index and the full render
+use the same markers, so switching modes replaces the block rather than
+stacking a second one. `docket compile` prints a token estimate and suggests
+`--index` when the full render grows past a few thousand tokens.
+
 ## MCP tools
 
-`docket mcp` serves four tools over stdio (newline-delimited JSON-RPC,
+`docket mcp` serves five tools over stdio (newline-delimited JSON-RPC,
 protocol `2024-11-05`). MCP hosts often spawn servers with a cwd far from
 your project, so the server resolves its project from `--dir <path>` (or
 `DOCKET_DIR`), falling back to walking up from cwd — and it always answers
@@ -256,6 +315,7 @@ before the handshake.
 | Tool | Purpose |
 |---|---|
 | `docket_list_loops` | discover the loops |
+| `docket_match_loop` | route a task to the loop that covers it (ranked, fail-closed) |
 | `docket_loop_context` | fetch a loop's five layers before starting work |
 | `docket_warrant_check` | get an allow/ask/deny verdict **before** acting; auto-recorded as a `check` entry |
 | `docket_record` | append a `note` entry to the record |

package/src/cli.js

@@ -4,10 +4,12 @@ import { cmdInit } from './commands/init.js';
 import { cmdNew, cmdTemplates } from './commands/new.js';
 import { cmdList, cmdShow } from './commands/list.js';
 import { cmdCheck } from './commands/check.js';
+import { cmdMatch } from './commands/match.js';
 import { cmdRecord } from './commands/record.js';
 import { cmdCompile } from './commands/compile.js';
 import { cmdReview } from './commands/review.js';
 import { cmdMcp } from './commands/mcp.js';
+import { cmdHook } from './commands/hook.js';
 
 const HELP = `
 ${bold('docket')} — brief the agent, warrant the actions, keep the record
@@ -22,6 +24,8 @@ ${bold('Getting started')}
 ${bold('Working with loops')}
   ${cyan('list')}                       list your loops
   ${cyan('show')} <loop>                print a loop's five layers
+  ${cyan('match')} <task…>              which loop covers this task? ranked, with why —
+                             exit 0 = matched, 2 = no loop covers it (ask)
   ${cyan('check')} <loop> <action> <target>
                              ask the warrant: allow, ask, or deny?
                              (actions: read, draft, change, send)
@@ -37,9 +41,14 @@ ${bold('The record')}
   ${cyan('record verify')}             verify the hash chain end to end
 
 ${bold('Portability')}
-  ${cyan('compile')} [--target claude|agents|cursor|raw] [--loop <name>] [--write]
+  ${cyan('compile')} [--target claude|agents|gemini|cursor|raw] [--loop <name>] [--index] [--write]
                              render loops into CLAUDE.md / AGENTS.md / Cursor rules
+                             (--index: one line per loop + the protocol, instead of
+                             full loops — keeps context flat as rule count grows)
   ${cyan('mcp')}                        run the MCP server (stdio) for agent integration
+  ${cyan('hook')} claude [--loop <name>] [--strict]
+                             Claude Code PreToolUse hook: gate tool calls on
+                             the warrant — deny blocks, ask prompts the human
 
 ${dim('Every loop answers five questions: what must it know, how is the work')}
 ${dim('done, what may it do without asking, where does it stop, and what')}
@@ -70,6 +79,8 @@ export async function main(argv) {
       return cmdList(rest);
     case 'show':
       return cmdShow(rest);
+    case 'match':
+      return cmdMatch(rest);
     case 'check':
       return cmdCheck(rest);
     case 'record':
@@ -80,6 +91,8 @@ export async function main(argv) {
       return cmdReview(rest);
     case 'mcp':
       return cmdMcp(rest);
+    case 'hook':
+      return cmdHook(rest);
     default:
       console.error(`docket: unknown command "${command}" — try \`docket help\``);
       return 1;

package/src/commands/compile.js

@@ -1,11 +1,16 @@
 import path from 'node:path';
 import { parseArgs } from '../lib/args.js';
 import { requireDocketDir, listLoops, loadLoop } from '../lib/loop.js';
-import { renderBlock, compileToFile, TARGETS } from '../lib/compile.js';
+import { renderBlock, renderIndexBlock, compileToFile, TARGETS } from '../lib/compile.js';
 import { dim, green } from '../lib/ui.js';
 
+// Above this, the full render starts crowding out the actual work — suggest
+// the index. ~4 chars per token is close enough to warn honestly.
+const TOKEN_HINT_AT = 2500;
+const estimateTokens = (text) => Math.round(text.length / 4);
+
 export function cmdCompile(argv) {
-  const { flags } = parseArgs(argv, { booleans: ['write'] });
+  const { flags } = parseArgs(argv, { booleans: ['write', 'index'] });
   const target = flags.target ?? 'raw';
   if (!TARGETS[target]) {
     console.error(`docket: unknown target "${target}" — targets: ${Object.keys(TARGETS).join(', ')}`);
@@ -20,26 +25,51 @@ export function cmdCompile(argv) {
     );
     return 1;
   }
+  if (flags.loop && flags.index) {
+    console.error(
+      'docket: --index compiles the routing table over all loops; --loop previews one full loop — pick one'
+    );
+    return 1;
+  }
   const loops = flags.loop ? [loadLoop(docketDir, flags.loop)] : listLoops(docketDir);
   if (!loops.length) {
     console.error('docket: no loops to compile — create one with `docket new <name>`');
     return 1;
   }
 
+  const block = flags.index ? renderIndexBlock(loops) : renderBlock(loops);
+  // The hint goes to stderr so `docket compile > file` stays clean.
+  const hintIndex = () => {
+    if (flags.index || flags.loop) return;
+    const tokens = estimateTokens(block);
+    if (tokens < TOKEN_HINT_AT) return;
+    console.error(
+      dim(
+        `  ~${tokens} tokens will sit in the agent's context on every turn — \`docket compile --index\`\n` +
+          `  compiles the protocol plus one line per loop instead; full loops load on demand`
+      )
+    );
+  };
+
   if (!flags.write || target === 'raw') {
-    console.log(renderBlock(loops));
+    console.log(block);
     if (flags.write && target === 'raw') {
       console.error(dim('(raw target always prints to stdout)'));
     }
+    hintIndex();
     return 0;
   }
 
   const rootDir = path.dirname(docketDir);
-  const file = compileToFile(rootDir, target, loops);
+  const file = compileToFile(rootDir, target, loops, { index: flags.index });
+  const what = flags.index
+    ? `index of ${loops.length} loop${loops.length === 1 ? '' : 's'}`
+    : `${loops.length} loop${loops.length === 1 ? '' : 's'}`;
   console.log(
     green('✓') +
-      ` compiled ${loops.length} loop${loops.length === 1 ? '' : 's'} → ${path.relative(process.cwd(), file)} ${dim(`(${TARGETS[target].label})`)}`
+      ` compiled ${what} → ${path.relative(process.cwd(), file)} ${dim(`(${TARGETS[target].label})`)}`
   );
   console.log(dim('  re-run after editing loops; the docket block is replaced in place'));
+  hintIndex();
   return 0;
 }

package/src/commands/hook.js

@@ -0,0 +1,148 @@
+// `docket hook claude` — the warrant as a Claude Code PreToolUse hook.
+//
+// The compiled context makes the rules known; the MCP tools make checking
+// cheap; this makes it MECHANICAL. Claude Code pipes every matched tool call
+// here as JSON before it runs; docket answers in the hook protocol:
+//
+//   deny  → the call is blocked, the reason goes back to the model
+//   ask   → Claude Code prompts the human before running the call
+//   allow → we stay SILENT (exit 0, no output)
+//
+// Silence on allow is deliberate: emitting an "allow" decision would bypass
+// Claude Code's own permission prompts. Docket must only ever tighten the
+// gate, never loosen it — a docket allow means "the warrant has no
+// objection", not "skip the other locks".
+
+import { parseArgs } from '../lib/args.js';
+import { findDocketDir, listLoops, loadLoop, loopExists, loopNames } from '../lib/loop.js';
+import { checkWarrant } from '../lib/warrant.js';
+import { matchLoops } from '../lib/match.js';
+import { recordCheck } from '../lib/record.js';
+
+// Verbs for the tools Claude Code ships. Anything not listed — Bash, MCP
+// tools, tools that don't exist yet — is treated as `send`, the most
+// consequential verb: its allow list is the one loop authors keep shortest,
+// so unknown tools fall toward ask, never toward allow.
+const ACTION_FOR_TOOL = {
+  Read: 'read',
+  Glob: 'read',
+  Grep: 'read',
+  LS: 'read',
+  NotebookRead: 'read',
+  WebFetch: 'read',
+  WebSearch: 'read',
+  TodoRead: 'read',
+  Write: 'change',
+  Edit: 'change',
+  MultiEdit: 'change',
+  NotebookEdit: 'change',
+  TodoWrite: 'change',
+};
+const DEFAULT_ACTION = 'send';
+
+// The warrant matches plain words, so give it the most human part of the
+// tool input — the command, the path, the url — prefixed with the tool name.
+export function describeTarget(toolName, input) {
+  const detail =
+    input && typeof input === 'object'
+      ? [input.command, input.file_path, input.url, input.path, input.pattern, input.query, input.description]
+          .find((v) => typeof v === 'string' && v.trim())
+      : null;
+  const text = detail ?? (input && typeof input === 'object' ? JSON.stringify(input) : '');
+  return `${toolName}${text ? `: ${text}` : ''}`.slice(0, 300);
+}
+
+function emitDecision(verdict, reason) {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: verdict,
+        permissionDecisionReason: reason,
+      },
+    }) + '\n'
+  );
+}
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => (data += chunk));
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+// Exit codes follow the hook contract, not the warrant's: the DECISION rides
+// in the JSON on stdout. Exit 1 is "misconfigured" — Claude Code shows the
+// human our stderr without blocking the call.
+export async function cmdHook(argv) {
+  const { flags, positional } = parseArgs(argv, { booleans: ['strict'] });
+  if (positional[0] !== 'claude') {
+    console.error('usage: docket hook claude [--loop <name>] [--strict] [--dir <project>]');
+    return 1;
+  }
+
+  let event;
+  try {
+    event = JSON.parse(await readStdin());
+  } catch {
+    console.error('docket hook: stdin was not hook JSON — wire this command under hooks.PreToolUse');
+    return 1;
+  }
+  if (event.hook_event_name && event.hook_event_name !== 'PreToolUse') return 0;
+  const toolName = typeof event.tool_name === 'string' ? event.tool_name : '';
+  if (!toolName) return 0;
+
+  const startDir = flags.dir ?? process.env.DOCKET_DIR ?? event.cwd ?? process.cwd();
+  const docketDir = findDocketDir(startDir);
+  if (!docketDir) {
+    // Only loud when the config names a loop: a global hook in a project
+    // that doesn't use docket should cost nothing.
+    if (flags.loop) {
+      console.error(`docket hook: --loop ${flags.loop} given but no .docket directory found from ${startDir}`);
+      return 1;
+    }
+    return 0;
+  }
+
+  const action = ACTION_FOR_TOOL[toolName] ?? DEFAULT_ACTION;
+  const target = describeTarget(toolName, event.tool_input);
+
+  let loop;
+  if (flags.loop) {
+    if (!loopExists(docketDir, flags.loop)) {
+      console.error(
+        `docket hook: no loop named "${flags.loop}" — have: ${loopNames(docketDir).join(', ') || '(none)'}`
+      );
+      return 1;
+    }
+    loop = loadLoop(docketDir, flags.loop);
+  } else {
+    // No loop pinned in the config: route on the target. A routed loop
+    // governs; no route means no loop claims this call — pass through to
+    // Claude Code's own permissions (or ask, under --strict).
+    const [candidate] = matchLoops(listLoops(docketDir), target, { limit: 1 });
+    if (!candidate) {
+      if (flags.strict) {
+        emitDecision(
+          'ask',
+          `docket: no loop covers "${target}" and this project runs hooks in strict mode — a human must approve work outside the loops.`
+        );
+      }
+      return 0;
+    }
+    loop = candidate.loop;
+  }
+
+  const result = checkWarrant(loop, action, target);
+  recordCheck(docketDir, loop.name, action, target, result, { via: 'hook' });
+
+  if (result.verdict === 'deny') {
+    emitDecision('deny', `docket loop "${loop.name}" (${result.rule}): ${result.reason}`);
+  } else if (result.verdict === 'ask') {
+    emitDecision('ask', `docket loop "${loop.name}" (${result.rule}): ${result.reason}`);
+  }
+  return 0;
+}

package/src/commands/list.js

@@ -34,7 +34,11 @@ export function cmdShow(argv) {
     console.log();
   };
 
-  console.log(`${bold(cyan(loop.name))} — ${loop.description}\n${dim(loop.file)}\n`);
+  console.log(`${bold(cyan(loop.name))} — ${loop.description}\n${dim(loop.file)}`);
+  if (loop.triggers.length) {
+    console.log(dim(`triggers: ${loop.triggers.join(' · ')}`));
+  }
+  console.log();
   section('Brief — what it knows before it starts', loop.brief);
   section('Procedure — how the work is done', loop.procedure);
 

package/src/commands/match.js

@@ -0,0 +1,48 @@
+import { parseArgs } from '../lib/args.js';
+import { requireDocketDir, listLoops } from '../lib/loop.js';
+import { matchLoops } from '../lib/match.js';
+import { bold, cyan, dim, yellow } from '../lib/ui.js';
+
+// Exit codes mirror the warrant's contract: 0 = a loop covers this,
+// 2 = nothing does (which means ask), 1 = usage error. Hooks can gate on it.
+export function cmdMatch(argv) {
+  const { flags, positional } = parseArgs(argv);
+  const intent = positional.join(' ').trim();
+  if (!intent) {
+    console.error('usage: docket match <the task, in plain words…>');
+    return 1;
+  }
+  const limit = Number.parseInt(flags.limit ?? '3', 10);
+  if (!Number.isInteger(limit) || limit < 1) {
+    console.error('docket: --limit must be a positive integer');
+    return 1;
+  }
+
+  const docketDir = requireDocketDir();
+  const loops = listLoops(docketDir);
+  if (!loops.length) {
+    console.error('docket: no loops defined — create one with `docket new <name>`');
+    return 1;
+  }
+
+  const candidates = matchLoops(loops, intent, { limit });
+  if (!candidates.length) {
+    console.log(`${yellow(bold('NO LOOP'))}  "${intent}"`);
+    console.log('  No loop covers this task. Work outside a loop defaults to ask —');
+    console.log('  check with a human, or write the loop: docket new <name>');
+    return 2;
+  }
+
+  console.log(
+    bold(`${candidates.length} candidate loop${candidates.length === 1 ? '' : 's'}`) +
+      dim(` for "${intent}"`) +
+      '\n'
+  );
+  for (const c of candidates) {
+    const why = c.hits.map((h) => `${h.field}: ${h.pattern}`).join(' · ');
+    console.log(`  ${cyan(c.loop.name.padEnd(22))} ${c.loop.description}`);
+    console.log(dim(`  ${''.padEnd(22)} score ${c.score} — ${why}`));
+  }
+  console.log(dim('\nload the winner before working: docket show <loop> · docket compile --loop <loop>'));
+  return 0;
+}

package/src/commands/mcp.js

@@ -6,6 +6,7 @@ import readline from 'node:readline';
 import { parseArgs } from '../lib/args.js';
 import { requireDocketDir, listLoops, loadLoop, loopExists, loopNames, ACTIONS } from '../lib/loop.js';
 import { checkWarrant } from '../lib/warrant.js';
+import { matchLoops } from '../lib/match.js';
 import { appendRecord, collectRecordFields, recordCheck } from '../lib/record.js';
 import { renderLoop } from '../lib/compile.js';
 import { VERSION } from '../lib/pkg.js';
@@ -17,6 +18,22 @@ const TOOLS = [
       'List the loops the human has defined. Each loop is one recurring task with brief, procedure, warrant, record, and reserved layers.',
     inputSchema: { type: 'object', properties: {}, additionalProperties: false },
   },
+  {
+    name: 'docket_match_loop',
+    description:
+      'Find which loop covers a task BEFORE starting it. Give the task in plain words; returns the best-matching loops, ranked, with why each matched. Then call docket_loop_context on the one that fits. If nothing matches, no loop covers the task — ask the human instead of guessing.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        intent: {
+          type: 'string',
+          description: 'the task about to start, in plain words (e.g. "draft an appeal for the denied claim")',
+        },
+      },
+      required: ['intent'],
+      additionalProperties: false,
+    },
+  },
   {
     name: 'docket_loop_context',
     description:
@@ -77,6 +94,34 @@ export function handleToolCall(docketDir, name, args = {}) {
       if (!loops.length) return textResult('No loops defined yet.');
       return textResult(loops.map((l) => `${l.name}: ${l.description}`).join('\n'));
     }
+    case 'docket_match_loop': {
+      const intent = typeof args.intent === 'string' ? args.intent.trim() : '';
+      if (!intent) return textResult('give the task in plain words via `intent`', true);
+      const loops = listLoops(docketDir);
+      if (!loops.length) return textResult('No loops defined yet.');
+      const candidates = matchLoops(loops, intent);
+      if (!candidates.length) {
+        return textResult(
+          `No loop covers "${intent}". Do not guess or proceed without one — work outside a loop ` +
+            `defaults to ask. Tell the human what you want to do and which loop (if any) should own it.`
+        );
+      }
+      const lines = candidates.map(
+        (c, i) =>
+          `${i + 1}. ${c.loop.name} — ${c.loop.description || '(no description)'} ` +
+          `(score ${c.score}: ${c.hits.map((h) => `${h.field} ~ ${h.pattern}`).join(', ')})`
+      );
+      return textResult(
+        [
+          `Candidate loops for "${intent}":`,
+          '',
+          ...lines,
+          '',
+          'Call docket_loop_context on the loop that fits, and work under it. If none of these',
+          'actually covers the task, ask the human — do not guess.',
+        ].join('\n')
+      );
+    }
     case 'docket_loop_context': {
       const loop = loadLoop(docketDir, args.loop);
       return textResult(renderLoop(loop));

package/src/lib/compile.js

@@ -99,6 +99,39 @@ export function renderBlock(loops) {
   return `${BEGIN}\n${header}\n\n${body}\n${END}`;
 }
 
+// Tiered rendering, for when the full render outgrows the context window.
+// Rules scale on disk, not in context: what stays resident is the protocol
+// (invariant with loop count) plus a one-line-per-loop routing table. Full
+// loops load on demand — and enforcement never needed residency at all,
+// because the warrant check runs outside the model.
+export function renderIndexEntry(loop) {
+  const triggers = loop.triggers.length ? ` *(triggers: ${loop.triggers.join('; ')})*` : '';
+  return `- **${loop.name}** — ${loop.description || '(no description)'}${triggers}`;
+}
+
+export function renderIndexBlock(loops) {
+  const header = [
+    '## Docket loops (index)',
+    '',
+    `${loops.length} loop${loops.length === 1 ? ' is' : 's are'} defined. This is the index, not the rules — each`,
+    "loop's full brief, procedure, and warrant load on demand.",
+    '',
+    'Before starting any task:',
+    '',
+    '1. Find the loop that covers it below — by its triggers, or ask docket:',
+    '   `docket match "<the task in plain words>"` (MCP: `docket_match_loop`).',
+    '2. Load that loop in full — `docket compile --loop <name>` (MCP:',
+    '   `docket_loop_context`) — and follow its brief and procedure.',
+    '3. Before any read/draft/change/send that matters, check the warrant:',
+    '   `docket check <loop> <action> "<target>"` (MCP: `docket_warrant_check`).',
+    '',
+    'If no loop covers the task, stop and ask the human before proceeding.',
+    'Unlisted means ask. Silence is never permission.',
+  ].join('\n');
+  const body = loops.map(renderIndexEntry).join('\n');
+  return `${BEGIN}\n${header}\n\n${neutralizeMarkers(body)}\n${END}`;
+}
+
 // Locate the managed block: first BEGIN at a line start, LAST END at a line
 // start. Content is marker-neutralized at render time, so a matching END is
 // always a real one.
@@ -116,11 +149,13 @@ function findBlock(text) {
   return { start: beginMatch.index, end: endIdx + 1 + END.length };
 }
 
-export function compileToFile(rootDir, target, loops) {
+export function compileToFile(rootDir, target, loops, { index = false } = {}) {
   const spec = TARGETS[target];
   if (!spec || !spec.file) throw new Error(`target "${target}" cannot be written to a file`);
   const filePath = path.join(rootDir, spec.file);
-  const block = renderBlock(loops);
+  // Same markers either way, so switching between full and index render
+  // replaces the managed block instead of stacking a second one.
+  const block = index ? renderIndexBlock(loops) : renderBlock(loops);
   let existing = '';
   if (fs.existsSync(filePath)) existing = fs.readFileSync(filePath, 'utf8');
 

package/src/lib/loop.js

@@ -6,6 +6,9 @@
 //   warrant   — what it may read / draft / change / send    (frontmatter)
 //   record    — the evidence the agent owes when it stops   (frontmatter)
 //   reserved  — what stays with the human, always           (frontmatter)
+//
+// Plus optional routing metadata:
+//   triggers  — phrases that mark a task as this loop's job (frontmatter)
 
 import fs from 'node:fs';
 import path from 'node:path';
@@ -122,6 +125,7 @@ export function parseLoop(text, { file } = {}) {
     description: typeof meta.description === 'string' ? meta.description : '',
     version,
     warrant,
+    triggers: asStringList(meta.triggers, 'triggers'),
     reserved: asStringList(meta.reserved, 'reserved'),
     record: asStringList(meta.record, 'record'),
     brief: sections.brief ?? '',

package/src/lib/match.js

@@ -0,0 +1,88 @@
+// Loop routing: which loop covers this task?
+//
+// Rules scale on disk, not in context — the agent holds a one-line-per-loop
+// index and pulls one loop at a time, so something has to answer "which one?"
+// deterministically. Scoring is lexical and integer-weighted, reusing the
+// warrant's cautious matcher.
+//
+// The warrant's asymmetry principle inverts at routing time. Over-retrieval
+// costs one extra index line pulled into context; under-retrieval just means
+// the agent works without its procedure — and the warrant check still catches
+// the miss downstream. So matching is generous. But when NOTHING clears the
+// bar, the answer is not "best guess": it is "no loop covers this — ask".
+// Retrieval fails closed, exactly like the warrant.
+
+import { matchPattern, contentWords, sameWord } from './warrant.js';
+import { ACTIONS } from './loop.js';
+
+// Integer weights, most author-intentional signal first. A name or trigger
+// hit qualifies a loop on its own; description overlap and warrant-target
+// hits must accumulate to MIN_SCORE, so one shared word ("email") never
+// routes on its own.
+const WEIGHT = { name: 5, trigger: 4, warrant: 1, description: 1 };
+const WARRANT_CAP = 3;
+const DESCRIPTION_CAP = 3;
+export const MIN_SCORE = 3;
+
+// Distinct content words of `a` that also appear (under stemming) in `b`.
+function overlapCount(a, b) {
+  const aWords = [...new Set(contentWords(a.toLowerCase()))];
+  const bWords = contentWords(b.toLowerCase());
+  return aWords.filter((aw) => bWords.some((bw) => sameWord(aw, bw))).length;
+}
+
+export function scoreLoop(loop, intent) {
+  const hits = [];
+  let score = 0;
+
+  // The loop's own name, read as a phrase ("insurance-appeal" → "insurance appeal").
+  if (matchPattern(loop.name.replace(/-/g, ' '), intent)) {
+    score += WEIGHT.name;
+    hits.push({ field: 'name', pattern: loop.name });
+  }
+
+  // Triggers are the author saying "tasks like this are mine" — the loudest
+  // routing signal a loop file can carry.
+  for (const trigger of loop.triggers) {
+    if (matchPattern(trigger, intent)) {
+      score += WEIGHT.trigger;
+      hits.push({ field: 'trigger', pattern: trigger });
+    }
+  }
+
+  // Warrant targets are routing evidence too: a loop that names "denial
+  // letter" under read probably owns tasks about denial letters. Capped so a
+  // long warrant can't outshout an explicit trigger on another loop.
+  let warrantHits = 0;
+  for (const key of [...ACTIONS, 'ask', 'never']) {
+    for (const pattern of loop.warrant[key]) {
+      if (warrantHits >= WARRANT_CAP) break;
+      if (matchPattern(pattern, intent)) {
+        warrantHits += 1;
+        score += WEIGHT.warrant;
+        hits.push({ field: `warrant.${key}`, pattern });
+      }
+    }
+  }
+
+  const shared = overlapCount(intent, loop.description);
+  if (shared > 0) {
+    score += Math.min(shared, DESCRIPTION_CAP) * WEIGHT.description;
+    hits.push({
+      field: 'description',
+      pattern: `${shared} shared word${shared === 1 ? '' : 's'}`,
+    });
+  }
+
+  return { score, hits };
+}
+
+// Rank loops against an intent; only candidates at or above MIN_SCORE count.
+// Deterministic: score descending, then name — same intent, same ranking.
+export function matchLoops(loops, intent, { limit = 3 } = {}) {
+  return loops
+    .map((loop) => ({ loop, ...scoreLoop(loop, intent) }))
+    .filter((c) => c.score >= MIN_SCORE)
+    .sort((a, b) => b.score - a.score || a.loop.name.localeCompare(b.loop.name))
+    .slice(0, limit);
+}

package/src/lib/warrant.js

@@ -43,14 +43,14 @@ function stemCandidates(word) {
   return c;
 }
 
-function sameWord(a, b) {
+export function sameWord(a, b) {
   for (const cand of stemCandidates(a)) {
     if (stemCandidates(b).has(cand)) return true;
   }
   return false;
 }
 
-function contentWords(s) {
+export function contentWords(s) {
   return s.split(/[^a-z0-9']+/).filter((w) => w && !STOPWORDS.has(w));
 }
 

package/templates/client-follow-up.loop.md

@@ -2,6 +2,9 @@
 name: client-follow-up
 description: Follow up with a client with the whole history in the room — promises, tone, and the language they already approved.
 version: 1
+triggers:
+  - follow up with a client, client follow-up
+  - client email, client status update, check in with the account
 warrant:
   read:
     - account history

package/templates/cross-tool-memory.loop.md

@@ -2,6 +2,9 @@
 name: cross-tool-memory
 description: One context you own, readable from Claude, GPT, Kimi, or Codex — a model switch is a recompile, not a re-teach.
 version: 1
+triggers:
+  - update the shared memory, remember this across tools
+  - regenerate CLAUDE.md, AGENTS.md, or rules files
 warrant:
   read:
     - the loops in this .docket directory

package/templates/insurance-appeal.loop.md

@@ -2,6 +2,9 @@
 name: insurance-appeal
 description: Build the appeal, cite the policy, assemble the evidence packet — stop before send.
 version: 1
+triggers:
+  - insurance appeal, appeal a denial
+  - denied claim, denial letter, claim dispute
 warrant:
   read:
     - policy documents

package/templates/marketing-brain.loop.md

@@ -2,6 +2,9 @@
 name: marketing-brain
 description: Marketing memory that compounds week over week — the messaging that already worked, the objections that keep coming back, the founder's actual voice.
 version: 1
+triggers:
+  - marketing copy, launch post, landing page
+  - positioning, messaging, campaign draft
 warrant:
   read:
     - the positioning doc

package/templates/ticket-handoff.loop.md

@@ -2,6 +2,9 @@
 name: ticket-handoff
 description: Turn messy work into tickets another human — or another agent — can pick up cold: source, owner, status, blocker, warrant, record.
 version: 1
+triggers:
+  - file a ticket, create tickets from this
+  - handoff, hand this off, triage the backlog
 warrant:
   read:
     - the conversation or incident being handed off

package/templates/travel-morning.loop.md

@@ -2,6 +2,9 @@
 name: travel-morning
 description: Plan a morning in an unfamiliar city around how you actually travel — not how a guidebook thinks you should.
 version: 1
+triggers:
+  - plan a morning, plan the morning in a city
+  - itinerary, sightseeing plan, what to do before noon
 warrant:
   read:
     - maps and transit schedules

package/templates/weekly-planning.loop.md

@@ -2,6 +2,9 @@
 name: weekly-planning
 description: Propose the week — priorities, tradeoffs, and what has to move — but change nothing.
 version: 1
+triggers:
+  - plan the week, weekly plan, weekly planning
+  - review the calendar, sort out priorities for the week
 warrant:
   read:
     - calendar