docket-agent 0.1.0

package/src/lib/compile.js

@@ -0,0 +1,140 @@
+// Compile loops into the context file your agent already reads.
+// The point of owning the context: a model switch is a recompile, not a re-teach.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { ACTIONS } from './loop.js';
+
+export const TARGETS = {
+  claude: { file: 'CLAUDE.md', label: 'Claude Code' },
+  agents: { file: 'AGENTS.md', label: 'AGENTS.md (ChatGPT/Codex, Zed, …)' },
+  gemini: { file: 'GEMINI.md', label: 'Gemini CLI' },
+  cursor: { file: path.join('.cursor', 'rules', 'docket.mdc'), label: 'Cursor rules' },
+  raw: { file: null, label: 'stdout' },
+};
+
+const BEGIN = '<!-- docket:begin — generated by `docket compile`, do not edit by hand -->';
+const END = '<!-- docket:end -->';
+
+// Loop prose is rendered verbatim into a file we later re-parse by marker,
+// so the markers must never appear in rendered content. A zero-width space
+// after "docket" keeps quoted markers readable but inert.
+function neutralizeMarkers(text) {
+  return text.replace(/<!--\s*docket:/g, '<!-- docket​:');
+}
+
+function bulletList(items, indent = '') {
+  return items.map((i) => `${indent}- ${i}`).join('\n');
+}
+
+// One source of truth for how a warrant reads, shared by `docket show`,
+// the compiler, and the MCP context tool — the human must review the same
+// rules the agent operates under.
+export function warrantLines(loop) {
+  const lines = [];
+  for (const action of ACTIONS) {
+    const list = loop.warrant[action];
+    lines.push({
+      label: action,
+      text: list.length ? list.join('; ') : '(nothing — ask first)',
+      kind: 'action',
+    });
+  }
+  if (loop.warrant.ask.length) {
+    lines.push({ label: 'ask', text: loop.warrant.ask.join('; '), kind: 'ask' });
+  }
+  if (loop.warrant.never.length) {
+    lines.push({ label: 'never', text: loop.warrant.never.join('; '), kind: 'never' });
+  }
+  return lines;
+}
+
+export function renderLoop(loop) {
+  const lines = [];
+  lines.push(`### Loop: ${loop.name}`);
+  if (loop.description) lines.push('', `*${loop.description}*`);
+
+  if (loop.brief) {
+    lines.push('', '**Brief — know this before you start:**', '', loop.brief);
+  }
+  if (loop.procedure) {
+    lines.push('', '**Procedure — how this work is done:**', '', loop.procedure);
+  }
+
+  lines.push('', '**Warrant — what you may do on your own:**', '');
+  for (const row of warrantLines(loop)) {
+    const label =
+      row.kind === 'ask' ? 'always ask before' : row.kind === 'never' ? 'never, even with approval' : row.label;
+    lines.push(`- ${label}: ${row.text}`);
+  }
+  lines.push(
+    '',
+    'Anything not listed above requires asking a human first. Silence is never permission.'
+  );
+
+  if (loop.reserved.length) {
+    lines.push('', '**Reserved — stays human, do not touch:**', '', bulletList(loop.reserved));
+  }
+
+  if (loop.record.length) {
+    lines.push(
+      '',
+      '**Record — when you finish (or stop), report:**',
+      '',
+      bulletList(loop.record)
+    );
+  }
+  return neutralizeMarkers(lines.join('\n'));
+}
+
+export function renderBlock(loops) {
+  const body = loops.map(renderLoop).join('\n\n---\n\n');
+  const header = [
+    '## Docket loops',
+    '',
+    'These loops define what you should remember, how the work happens, what you',
+    'may do on your own, where you must stop, and what evidence you owe. Boundaries',
+    'are not suggestions. When the warrant says ask, stop and ask.',
+  ].join('\n');
+  return `${BEGIN}\n${header}\n\n${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.
+function findBlock(text) {
+  const beginRe = /^<!-- docket:begin[^\n]*-->/m;
+  const beginMatch = beginRe.exec(text);
+  if (!beginMatch) return null;
+  const endIdx = text.lastIndexOf(`\n${END}`);
+  if (endIdx === -1 || endIdx < beginMatch.index) {
+    throw new Error(
+      `found a docket:begin marker without a matching docket:end — the file was ` +
+        `edited by hand inside the managed block. Fix or remove the block, then recompile.`
+    );
+  }
+  return { start: beginMatch.index, end: endIdx + 1 + END.length };
+}
+
+export function compileToFile(rootDir, target, loops) {
+  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);
+  let existing = '';
+  if (fs.existsSync(filePath)) existing = fs.readFileSync(filePath, 'utf8');
+
+  let next;
+  const found = findBlock(existing);
+  if (found) {
+    next = existing.slice(0, found.start) + block + existing.slice(found.end);
+  } else if (existing.trim()) {
+    next = existing.replace(/\s*$/, '\n\n') + block + '\n';
+  } else {
+    next = block + '\n';
+  }
+
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, next);
+  return filePath;
+}

package/src/lib/loop.js

@@ -0,0 +1,198 @@
+// Loop file parsing and validation.
+//
+// A loop is one recurring task wrapped in five layers:
+//   brief     — what the agent must know before it starts   (markdown body)
+//   procedure — how this job is done properly               (markdown body)
+//   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)
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseYaml } from './yaml.js';
+
+export const ACTIONS = ['read', 'draft', 'change', 'send'];
+export const VERDICTS = ['allow', 'ask', 'deny'];
+export const LOOP_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+export const LOOP_EXT = '.loop.md';
+export const SPEC_VERSION = 1;
+
+export class LoopError extends Error {}
+
+export function splitFrontmatter(text) {
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!m) {
+    throw new LoopError(
+      'loop file must start with a `---` YAML frontmatter block (see spec/SPEC.md)'
+    );
+  }
+  return { frontmatter: m[1], body: m[2] };
+}
+
+// Only headings literally named Brief or Procedure delimit sections; every
+// other line — subheadings, other sections, comments inside fenced code
+// blocks — is content and stays with the section it appears in. Prose the
+// human wrote must never be silently dropped from the compiled context.
+export function extractSections(body) {
+  const sections = {};
+  let current = null;
+  let inFence = false;
+  for (const line of body.split(/\r?\n/)) {
+    if (/^\s*(```|~~~)/.test(line)) inFence = !inFence;
+    const h = inFence ? null : line.match(/^#{1,3}\s+(brief|procedure)\s*$/i);
+    if (h) {
+      current = h[1].toLowerCase();
+      sections[current] ??= [];
+    } else if (current) {
+      sections[current].push(line);
+    }
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(sections)) {
+    out[k] = v.join('\n').trim();
+  }
+  return out;
+}
+
+function asStringList(value, where) {
+  if (value === null || value === undefined) return [];
+  if (!Array.isArray(value)) {
+    throw new LoopError(`\`${where}\` must be a list`);
+  }
+  return value.map((v) => {
+    if (typeof v !== 'string' || !v.trim()) {
+      throw new LoopError(`\`${where}\` entries must be non-empty strings`);
+    }
+    return v.trim();
+  });
+}
+
+export function parseLoop(text, { file } = {}) {
+  const { frontmatter, body } = splitFrontmatter(text);
+  let meta;
+  try {
+    meta = parseYaml(frontmatter);
+  } catch (err) {
+    throw new LoopError(`${file ? file + ': ' : ''}${err.message}`);
+  }
+  if (!meta || typeof meta !== 'object' || Array.isArray(meta)) {
+    throw new LoopError('frontmatter must be a YAML map');
+  }
+  if (typeof meta.name !== 'string' || !LOOP_NAME_RE.test(meta.name)) {
+    throw new LoopError('`name` is required and must be lowercase letters, digits, and dashes');
+  }
+  if (file) {
+    const base = path.basename(file);
+    if (base.endsWith(LOOP_EXT) && base !== `${meta.name}${LOOP_EXT}`) {
+      throw new LoopError(
+        `${base}: frontmatter says \`name: ${meta.name}\` but the file is named ${base} — ` +
+          `they must match, or record entries get attributed to a loop that cannot be loaded`
+      );
+    }
+  }
+  const version = meta.version ?? SPEC_VERSION;
+  if (version !== SPEC_VERSION) {
+    throw new LoopError(
+      `loop declares version ${version}, but this docket only understands version ${SPEC_VERSION} — upgrade docket`
+    );
+  }
+
+  const warrantSrc = meta.warrant ?? {};
+  if (typeof warrantSrc !== 'object' || Array.isArray(warrantSrc)) {
+    throw new LoopError('`warrant` must be a map of action lists');
+  }
+  const warrant = {};
+  for (const action of ACTIONS) {
+    warrant[action] = asStringList(warrantSrc[action], `warrant.${action}`);
+  }
+  warrant.ask = asStringList(warrantSrc.ask, 'warrant.ask');
+  warrant.never = asStringList(warrantSrc.never, 'warrant.never');
+
+  for (const key of Object.keys(warrantSrc)) {
+    if (![...ACTIONS, 'ask', 'never'].includes(key)) {
+      throw new LoopError(
+        `warrant.${key} is not a thing — actions are read/draft/change/send, plus ask/never lists`
+      );
+    }
+  }
+
+  const sections = extractSections(body);
+  const loop = {
+    name: meta.name,
+    description: typeof meta.description === 'string' ? meta.description : '',
+    version,
+    warrant,
+    reserved: asStringList(meta.reserved, 'reserved'),
+    record: asStringList(meta.record, 'record'),
+    brief: sections.brief ?? '',
+    procedure: sections.procedure ?? '',
+    file: file ?? null,
+  };
+  return loop;
+}
+
+export function findDocketDir(startDir = process.cwd()) {
+  let dir = path.resolve(startDir);
+  for (;;) {
+    const candidate = path.join(dir, '.docket');
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export function requireDocketDir(startDir = process.cwd()) {
+  const dir = findDocketDir(startDir);
+  if (!dir) {
+    throw new LoopError('no .docket directory found — run `docket init` first');
+  }
+  return dir;
+}
+
+export function loopsDir(docketDir) {
+  return path.join(docketDir, 'loops');
+}
+
+export function loopFile(docketDir, name) {
+  return path.join(loopsDir(docketDir), `${name}${LOOP_EXT}`);
+}
+
+export function loopNames(docketDir) {
+  const dir = loopsDir(docketDir);
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith(LOOP_EXT))
+    .map((f) => f.slice(0, -LOOP_EXT.length))
+    .sort();
+}
+
+export function loopExists(docketDir, name) {
+  return LOOP_NAME_RE.test(name) && fs.existsSync(loopFile(docketDir, name));
+}
+
+export function listLoops(docketDir) {
+  const dir = loopsDir(docketDir);
+  if (!fs.existsSync(dir)) return [];
+  const loops = [];
+  for (const entry of fs.readdirSync(dir).sort()) {
+    if (!entry.endsWith(LOOP_EXT)) continue;
+    const file = path.join(dir, entry);
+    loops.push(parseLoop(fs.readFileSync(file, 'utf8'), { file }));
+  }
+  return loops;
+}
+
+export function loadLoop(docketDir, name) {
+  const file = loopFile(docketDir, name);
+  if (!fs.existsSync(file)) {
+    // Names come from filenames, not parses, so one broken sibling loop
+    // can't mask the real "no such loop" message.
+    const available = loopNames(docketDir);
+    throw new LoopError(
+      `no loop named "${name}"${available.length ? ` — have: ${available.join(', ')}` : ' — create one with \`docket new\`'}`
+    );
+  }
+  return parseLoop(fs.readFileSync(file, 'utf8'), { file });
+}

package/src/lib/pkg.js

@@ -0,0 +1,5 @@
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+export const VERSION = require('../../package.json').version;

package/src/lib/record.js

@@ -0,0 +1,177 @@
+// The record: an append-only, hash-chained log of what the agent saw, did,
+// left alone, and where it stopped. Each entry commits to the previous one,
+// so `docket record verify` detects any edit, deletion, or reordering.
+//
+// Storage is a plain JSONL file — human-readable, diff-able, yours.
+//
+// Known limitation (by construction, documented in the spec): truncating the
+// TAIL of the file leaves a valid shorter chain. Pin the head hash somewhere
+// the log can't reach (a password manager, a commit, another machine) and
+// check it with `docket record verify --head <hash>`.
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const GENESIS = 'GENESIS';
+
+// The evidentiary fields a note entry may carry. Every writer (CLI, MCP)
+// filters through collectRecordFields so the audit schema has one owner.
+export const RECORD_FIELDS = ['saw', 'did', 'skipped', 'stopped', 'note'];
+
+export function collectRecordFields(source) {
+  const fields = {};
+  const dropped = [];
+  for (const key of RECORD_FIELDS) {
+    if (!(key in source) || source[key] === undefined) continue;
+    if (typeof source[key] === 'string' && source[key].trim()) {
+      fields[key] = source[key].trim();
+    } else {
+      dropped.push(key); // present but empty/non-string — surface, never silently drop
+    }
+  }
+  return { fields, dropped };
+}
+
+export function recordFile(docketDir) {
+  return path.join(docketDir, 'record.jsonl');
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalize).join(',')}]`;
+  if (value && typeof value === 'object') {
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalize(value[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export function hashEntry(entry, prev) {
+  const { hash, ...rest } = entry;
+  return (
+    'sha256:' +
+    crypto.createHash('sha256').update(`${prev}\n${canonicalize(rest)}`).digest('hex')
+  );
+}
+
+export function readRecords(docketDir) {
+  const file = recordFile(docketDir);
+  if (!fs.existsSync(file)) return [];
+  const entries = [];
+  for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    entries.push(JSON.parse(line));
+  }
+  return entries;
+}
+
+// Read only the final entry, without parsing the whole file — appends are
+// the hot path (every warrant check writes one) and the log grows
+// unbounded over months of agent use.
+export function readLastRecord(docketDir) {
+  const file = recordFile(docketDir);
+  if (!fs.existsSync(file)) return null;
+  const size = fs.statSync(file).size;
+  if (size === 0) return null;
+  const fd = fs.openSync(file, 'r');
+  try {
+    let chunkSize = 64 * 1024;
+    for (;;) {
+      const start = Math.max(0, size - chunkSize);
+      const buf = Buffer.alloc(size - start);
+      fs.readSync(fd, buf, 0, buf.length, start);
+      const text = buf.toString('utf8');
+      const lines = text.split('\n').filter((l) => l.trim());
+      if (lines.length === 0) return null;
+      // Walk backward to the last parseable line: the tail line may be a
+      // partial interrupted write, and the chunk-head line may be cut off.
+      for (let j = lines.length - 1; j >= 0; j--) {
+        try {
+          return JSON.parse(lines[j]);
+        } catch {
+          // not a complete entry — try the line before it
+        }
+      }
+      if (start === 0) return null;
+      chunkSize *= 4;
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+export function appendRecord(docketDir, fields) {
+  const last = readLastRecord(docketDir);
+  const prev = last ? last.hash : GENESIS;
+  const entry = {
+    seq: last ? last.seq + 1 : 1,
+    ts: new Date().toISOString(),
+    ...fields,
+    prev,
+  };
+  entry.hash = hashEntry(entry, prev);
+  fs.appendFileSync(recordFile(docketDir), JSON.stringify(entry) + '\n');
+  return entry;
+}
+
+// One writer for warrant-check evidence, whoever asked (CLI or MCP) —
+// the audit schema for checks is defined here and nowhere else.
+export function recordCheck(docketDir, loopName, action, target, result, extra = {}) {
+  return appendRecord(docketDir, {
+    loop: loopName,
+    kind: 'check',
+    action,
+    target,
+    verdict: result.verdict,
+    rule: result.rule,
+    ...extra,
+  });
+}
+
+// Returns { ok, count, head, brokenAt, problem }.
+export function verifyRecord(docketDir, { expectHead } = {}) {
+  const entries = readRecords(docketDir);
+  let prev = GENESIS;
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    if (entry.seq !== i + 1) {
+      return {
+        ok: false,
+        count: entries.length,
+        head: null,
+        brokenAt: i + 1,
+        problem: `entry ${i + 1} has seq ${entry.seq} — an entry was removed, added, or reordered`,
+      };
+    }
+    if (entry.prev !== prev) {
+      return {
+        ok: false,
+        count: entries.length,
+        head: null,
+        brokenAt: entry.seq,
+        problem: `entry ${entry.seq} does not chain to the previous entry`,
+      };
+    }
+    if (hashEntry(entry, prev) !== entry.hash) {
+      return {
+        ok: false,
+        count: entries.length,
+        head: null,
+        brokenAt: entry.seq,
+        problem: `entry ${entry.seq} was modified after it was written`,
+      };
+    }
+    prev = entry.hash;
+  }
+  const head = entries.length ? prev : GENESIS;
+  if (expectHead && head !== expectHead && !head.startsWith(expectHead)) {
+    return {
+      ok: false,
+      count: entries.length,
+      head,
+      brokenAt: entries.length,
+      problem: `chain is internally consistent but its head is ${head.slice(0, 23)}…, not the pinned ${expectHead.slice(0, 23)}… — entries were likely truncated from the tail`,
+    };
+  }
+  return { ok: true, count: entries.length, head, brokenAt: null, problem: null };
+}

package/src/lib/ui.js

@@ -0,0 +1,20 @@
+// Tiny ANSI helpers. Colors only when writing to a TTY (or FORCE_COLOR).
+
+const on =
+  process.env.FORCE_COLOR === '1' ||
+  (process.stdout.isTTY && process.env.NO_COLOR === undefined && process.env.FORCE_COLOR !== '0');
+
+const wrap = (open, close) => (s) => (on ? `\x1b[${open}m${s}\x1b[${close}m` : String(s));
+
+export const bold = wrap(1, 22);
+export const dim = wrap(2, 22);
+export const red = wrap(31, 39);
+export const green = wrap(32, 39);
+export const yellow = wrap(33, 39);
+export const cyan = wrap(36, 39);
+
+export const VERDICT_STYLE = {
+  allow: { color: green, badge: 'ALLOW' },
+  ask: { color: yellow, badge: 'ASK' },
+  deny: { color: red, badge: 'DENY' },
+};

package/src/lib/warrant.js

@@ -0,0 +1,142 @@
+// The warrant engine: answers "what exactly is the agent allowed to do here?"
+// BEFORE the action happens, deterministically, from a file the human wrote.
+//
+// Verdict order (first match wins):
+//   1. `never`  → deny   (hard stop, no override)
+//   2. `ask`    → ask    (human approval required)
+//   3. action's allow list → allow
+//   4. anything unlisted   → ask   (silence is never permission)
+//
+// Matching is ASYMMETRIC by design. ask/never patterns match fuzzily in both
+// directions — an ambiguous target escalates. Allow patterns match strictly:
+// the target must cover everything the pattern names, so a vague target
+// ("email") can never inherit permission from a specific allow entry
+// ("status email to the team"). A phrasing difference may cause an
+// unnecessary ask; it must never cause an accidental allow.
+
+import { ACTIONS } from './loop.js';
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Filler words carry no permission semantics; matching keys on content words.
+const STOPWORDS = new Set([
+  'a', 'an', 'the', 'any', 'anything', 'anyone', 'this', 'that', 'these', 'those',
+  'to', 'of', 'for', 'with', 'without', 'on', 'in', 'at', 'by', 'about', 'into',
+  'it', 'its', 'is', 'are', 'be', 'will', 'even', 'my', 'your', 'our', 'their',
+]);
+
+// Light stemming, candidate-set style: two words match when any of their
+// suffix-stripped forms coincide ("quotes"→{quote,quot} meets "quote"→{quote},
+// "contacting" meets "contact"). No dictionary — just enough to keep
+// phrasing from deciding permission.
+function stemCandidates(word) {
+  const c = new Set([word]);
+  const base = word.replace(/'s$/, '');
+  c.add(base);
+  for (const suffix of ['ing', 'ed', 'es', 's']) {
+    if (base.endsWith(suffix) && base.length - suffix.length >= 3) {
+      c.add(base.slice(0, -suffix.length));
+    }
+  }
+  return c;
+}
+
+function sameWord(a, b) {
+  for (const cand of stemCandidates(a)) {
+    if (stemCandidates(b).has(cand)) return true;
+  }
+  return false;
+}
+
+function contentWords(s) {
+  return s.split(/[^a-z0-9']+/).filter((w) => w && !STOPWORDS.has(w));
+}
+
+function subset(inner, outer) {
+  return inner.every((iw) => outer.some((ow) => sameWord(iw, ow)));
+}
+
+// A pattern splits into alternatives on commas, " or ", and " and " —
+// natural-language lists ("secrets, tokens, or passwords") are lists.
+function alternatives(pattern) {
+  return pattern
+    .split(/\s*,\s*|\s+or\s+|\s+and\s+/)
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+// Pattern semantics (case-insensitive throughout):
+//  - contains `*` → glob over the whole target (author-explicit, both modes)
+//  - all stopwords ("anything") → matches every target (its plain meaning)
+//  - otherwise, per alternative:
+//      cautious mode (ask/never): substring either direction, or content-word
+//        subset either direction — ambiguity escalates to the human.
+//      strict mode (allow): the target must contain the pattern — as a
+//        substring or as a content-word superset. The reverse never allows.
+export function matchPattern(pattern, target, { strict = false } = {}) {
+  const p = pattern.trim().toLowerCase();
+  const t = target.trim().toLowerCase();
+  if (!p || !t) return false;
+  if (p.includes('*')) {
+    const re = new RegExp(`^${p.split('*').map(escapeRe).join('.*')}$`);
+    return re.test(t);
+  }
+  const tWords = contentWords(t);
+  return alternatives(p).some((alt) => {
+    const pWords = contentWords(alt);
+    if (!pWords.length) return true; // "anything" means anything
+    if (t.includes(alt)) return true;
+    if (subset(pWords, tWords)) return true;
+    if (strict) return false;
+    return alt.includes(t) || (tWords.length > 0 && subset(tWords, pWords));
+  });
+}
+
+function firstMatch(patterns, target, opts) {
+  for (const pattern of patterns) {
+    if (matchPattern(pattern, target, opts)) return pattern;
+  }
+  return null;
+}
+
+export function checkWarrant(loop, action, target) {
+  if (!ACTIONS.includes(action)) {
+    throw new Error(`unknown action "${action}" — actions are: ${ACTIONS.join(', ')}`);
+  }
+  const b = loop.warrant;
+
+  const never = firstMatch(b.never, target);
+  if (never) {
+    return {
+      verdict: 'deny',
+      rule: `never: ${never}`,
+      reason: `"${target}" matches a hard stop. The loop says this never happens, with or without approval.`,
+    };
+  }
+
+  const ask = firstMatch(b.ask, target);
+  if (ask) {
+    return {
+      verdict: 'ask',
+      rule: `ask: ${ask}`,
+      reason: `"${target}" always needs human approval in this loop.`,
+    };
+  }
+
+  const allow = firstMatch(b[action], target, { strict: true });
+  if (allow) {
+    return {
+      verdict: 'allow',
+      rule: `${action}: ${allow}`,
+      reason: `"${target}" is within the ${action} warrant.`,
+    };
+  }
+
+  return {
+    verdict: 'ask',
+    rule: 'default',
+    reason: `"${target}" is not listed under \`${action}\`. Unlisted means ask — silence is never permission.`,
+  };
+}