docket-agent 0.1.0

package/spec/SPEC.md

@@ -0,0 +1,259 @@
+# The Loop File Spec — v0.1
+
+Status: draft. Breaking changes possible until v1.0; the `version` field in
+frontmatter exists so files can survive them.
+
+## Why a spec
+
+An agent's permissions shouldn't live in a prompt someone improvised at 11pm.
+A loop file is a small, human-writable document that answers, in order:
+
+1. What must the agent **know** before it starts?
+2. How is this work **supposed to be done**?
+3. What may it do **without asking**?
+4. Where does it have to **stop**?
+5. What **evidence** must it leave behind?
+
+Unwritten answers get guessed at. Written answers can be enforced — checked,
+compiled, and audited by tools.
+
+
+## File format
+
+A loop is a single file, `<name>.loop.md`, stored in `.docket/loops/`. It is
+Markdown with YAML frontmatter:
+
+```markdown
+---
+name: insurance-appeal
+description: Build the appeal, cite the policy — stop before send.
+version: 1
+warrant:
+  read:
+    - policy documents
+  draft:
+    - appeal letter
+  change: []
+  send: []
+  ask:
+    - anything addressed to the insurer
+  never:
+    - accepting or rejecting a settlement
+reserved:
+  - signing and sending
+record:
+  - every policy clause cited
+  - where the draft stopped
+---
+
+# Brief
+
+Prose. What the agent must know before it starts.
+
+# Procedure
+
+Prose. How this job is done properly.
+```
+
+Prose layers (brief, procedure) live in the Markdown body because humans
+write and diff prose well. Machine layers (warrant, record, reserved) live
+in frontmatter because tools enforce structure well.
+
+### Frontmatter fields
+
+| Field | Type | Required | Meaning |
+|---|---|---|---|
+| `name` | string | yes | `[a-z0-9][a-z0-9-]*`; must match the filename |
+| `description` | string | no | one line, shown in listings and compiled context |
+| `version` | number | no | spec version, default `1` |
+| `warrant` | map | no | 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 |
+
+### Body sections
+
+Headings (`#`, `##`, or `###`) named exactly `Brief` or `Procedure`
+(case-insensitive) open the prose layers. Every other line — subheadings,
+other headings, comments inside fenced code blocks — is **content** and
+belongs to the open section. Prose the human wrote is never silently dropped
+from the compiled context.
+
+`name` must match the filename (`<name>.loop.md`) and parsers must reject a
+mismatch — otherwise record entries get attributed to a loop that cannot be loaded.
+Parsers must also reject a `version` they don't understand rather than
+silently misreading a newer format.
+
+### YAML subset
+
+Frontmatter is parsed by a deliberately small YAML subset: nested maps, lists
+of scalars, quoted/unquoted scalars, booleans, numbers, `null`, `[]`, and `#`
+comments. No anchors, no multi-line scalars, no flow collections, no lists of
+maps. A grammar small enough to audit is part of the security posture.
+
+## The warrant
+
+Four verbs, in escalating order of consequence:
+
+| Verb | Meaning |
+|---|---|
+| `read` | look at it |
+| `draft` | produce it, but it goes nowhere on its own |
+| `change` | mutate state that stays inside the sandbox |
+| `send` | consequences leave the sandbox: email, publish, file, deploy, pay |
+
+Plus two cross-cutting lists:
+
+- `ask` — always requires human approval, whatever the verb.
+- `never` — does not happen, even with approval. A `never` is the human
+  pre-deciding under calm conditions what no amount of in-the-moment
+  persuasion may undo.
+
+### The verdict algorithm
+
+Given a loop, an action (one of the four verbs), and a target (a plain-language
+description of what the action touches), the verdict is the **first** rule
+that matches:
+
+1. target matches an entry in `never` → **deny**
+2. target matches an entry in `ask` → **ask**
+3. target matches an entry in the action's own list → **allow**
+4. otherwise → **ask**
+
+Rule 4 is the heart of the spec: **unlisted means ask. Silence is never
+permission.** An agent that encounters something the loop's author didn't
+anticipate has, by construction, encountered something that needs a human.
+
+### Pattern matching
+
+All matching is case-insensitive, and it is **asymmetric by design**:
+`ask`/`never` patterns match fuzzily in both directions, allow patterns match
+strictly. A phrasing difference may cause an unnecessary ask; it must never
+cause an accidental allow.
+
+Shared rules:
+
+- A pattern containing `*` is a glob over the entire target (author-explicit,
+  both modes).
+- Commas, ` or `, and ` and ` split a pattern into alternatives, each tried
+  separately — natural-language lists (`secrets, tokens, or passwords`) are
+  lists.
+- *Content words* exclude filler (`a`, `the`, `anything`, `to`, `of`, …).
+  Words compare under light candidate-set stemming (possessive `'s`, and
+  `-s`/`-es`/`-ed`/`-ing` when enough of the word remains), so `quotes`
+  matches `quote` and `contacting` matches `contact`.
+- An alternative whose words are all filler (`anything`) matches **every**
+  target — its plain meaning.
+
+Per alternative:
+
+- **Cautious mode** (`ask`, `never`): matches on substring in either
+  direction, or content-word subset in either direction. Ambiguity escalates
+  to the human.
+- **Strict mode** (allow lists): the target must *cover* the pattern —
+  contain it as a substring, or contain every one of its content words. The
+  reverse never allows: the target `email` does not match the allow entry
+  `status email to the team`.
+
+Known limitation: a target that embeds an allowed phrase plus extra intent
+(`status email to the team and also wire funds`) still covers the pattern.
+The check is a pre-action gate for cooperative agents, not a parser of
+compound intent — `ask` and `never` lists screen every target first, so list
+the consequences you fear there.
+
+Write `ask`/`never` patterns short and broad (`contacting the insurer`), and
+allow-list patterns as concrete nouns (`appeal letter`). When a check that
+should have matched falls through, the verdict is still `ask` (rule 4) — the
+system degrades toward the human, never away.
+
+### Exit codes
+
+`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.
+
+## The record
+
+The record is the audit half of the trust story: *what did the agent see,
+do, leave alone, and where did it stop?*
+
+Storage: `.docket/record.jsonl`, one JSON object per line, append-only.
+
+```json
+{"seq":3,"ts":"2026-07-03T10:15:00.000Z","loop":"insurance-appeal","kind":"check","action":"send","target":"appeal email to insurer","verdict":"ask","rule":"ask: anything addressed to the insurer","prev":"sha256:…","hash":"sha256:…"}
+```
+
+Two kinds today:
+
+- `check` — a warrant check, recorded automatically with its verdict. The
+  question "did the agent even ask?" becomes answerable.
+- `note` — a work entry with any of: `saw`, `did`, `skipped`, `stopped`,
+  `note`.
+
+### The hash chain
+
+Each entry commits to the previous one:
+
+```
+hash = "sha256:" + SHA256( prev + "\n" + canonical(entry minus hash) )
+```
+
+where `canonical` is JSON with lexicographically sorted keys, and `prev` is the
+previous entry's `hash` (the literal string `GENESIS` for entry 1). `seq` must
+increase by exactly 1.
+
+`docket record verify` recomputes the chain. Any edit, deletion, insertion,
+or reordering **inside** the log breaks it at a specific entry. One case the
+chain alone cannot see: truncating the tail leaves a valid shorter chain.
+That's why `verify` prints the current head hash — pin it somewhere the log
+can't reach (a password manager, a commit message, another machine) and check
+with `docket record verify --head <hash>`, which reports likely truncation
+when the heads disagree. The chain doesn't stop tampering — it's a plain
+file — it makes tampering **visible**, which is what an audit trail is for.
+(Cryptographically signing the head is on the roadmap.)
+
+## Compiled context
+
+Loops are the source of truth; assistant-specific files are build artifacts.
+`docket compile` renders loops into a fenced block:
+
+```
+<!-- docket:begin — generated by `docket compile`, do not edit by hand -->
+…
+<!-- docket:end -->
+```
+
+and (with `--write`) inserts or replaces that block in the target file:
+
+| Target | File |
+|---|---|
+| `claude` | `CLAUDE.md` |
+| `agents` | `AGENTS.md` (ChatGPT/Codex, Zed, …) |
+| `gemini` | `GEMINI.md` (Gemini CLI) |
+| `cursor` | `.cursor/rules/docket.mdc` |
+| `raw` | stdout |
+
+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.
+
+## MCP tools
+
+`docket mcp` serves four 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
+`initialize`, reporting a missing project as a tool error instead of dying
+before the handshake.
+
+| Tool | Purpose |
+|---|---|
+| `docket_list_loops` | discover the loops |
+| `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 |
+
+## What this spec refuses to do
+
+- **No secrets in loop files.** Loops are meant to be committed and shared.
+- **No execution.** A loop describes and constrains work; it is not a workflow
+  engine. The agent you already use does the work.
+- **No lock-in.** Everything is plain text in your repo. Deleting docket loses
+  you nothing but the tooling.

package/src/cli.js

@@ -0,0 +1,79 @@
+import { bold, cyan, dim } from './lib/ui.js';
+import { VERSION } from './lib/pkg.js';
+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 { cmdRecord } from './commands/record.js';
+import { cmdCompile } from './commands/compile.js';
+import { cmdMcp } from './commands/mcp.js';
+
+const HELP = `
+${bold('docket')} — brief the agent, warrant the actions, keep the record
+
+${bold('Usage:')} docket <command> [args]
+
+${bold('Getting started')}
+  ${cyan('init')}                       create a .docket directory here
+  ${cyan('new')} <name>                 create a loop (interactive, or --template <t>)
+  ${cyan('templates')}                  list the starter loop templates
+
+${bold('Working with loops')}
+  ${cyan('list')}                       list your loops
+  ${cyan('show')} <loop>                print a loop's five layers
+  ${cyan('check')} <loop> <action> <target>
+                             ask the warrant: allow, ask, or deny?
+                             (actions: read, draft, change, send)
+
+${bold('The record')}
+  ${cyan('record add')} <loop> [--did ..] [--saw ..] [--skipped ..] [--stopped ..] [--note ..]
+  ${cyan('record log')} [loop] [--n 20]
+  ${cyan('record verify')}             verify the hash chain end to end
+
+${bold('Portability')}
+  ${cyan('compile')} [--target claude|agents|cursor|raw] [--loop <name>] [--write]
+                             render loops into CLAUDE.md / AGENTS.md / Cursor rules
+  ${cyan('mcp')}                        run the MCP server (stdio) for agent integration
+
+${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')}
+${dim('evidence must it leave. Unwritten answers get guessed at.')}
+`;
+
+export async function main(argv) {
+  const [command, ...rest] = argv;
+  switch (command) {
+    case undefined:
+    case 'help':
+    case '--help':
+    case '-h':
+      console.log(HELP.trimEnd());
+      return 0;
+    case 'version':
+    case '--version':
+    case '-v':
+      console.log(VERSION);
+      return 0;
+    case 'init':
+      return cmdInit(rest);
+    case 'new':
+      return cmdNew(rest);
+    case 'templates':
+      return cmdTemplates(rest);
+    case 'list':
+      return cmdList(rest);
+    case 'show':
+      return cmdShow(rest);
+    case 'check':
+      return cmdCheck(rest);
+    case 'record':
+      return cmdRecord(rest);
+    case 'compile':
+      return cmdCompile(rest);
+    case 'mcp':
+      return cmdMcp(rest);
+    default:
+      console.error(`docket: unknown command "${command}" — try \`docket help\``);
+      return 1;
+  }
+}

package/src/commands/check.js

@@ -0,0 +1,41 @@
+import { parseArgs } from '../lib/args.js';
+import { requireDocketDir, loadLoop, ACTIONS } from '../lib/loop.js';
+import { checkWarrant } from '../lib/warrant.js';
+import { recordCheck } from '../lib/record.js';
+import { bold, dim, VERDICT_STYLE } from '../lib/ui.js';
+
+// Exit codes are part of the contract, so scripts and hooks can gate on them:
+//   0 = allow, 2 = ask, 3 = deny.
+const EXIT = { allow: 0, ask: 2, deny: 3 };
+
+export function cmdCheck(argv) {
+  const { flags, positional } = parseArgs(argv, { booleans: ['no-record', 'quiet'] });
+  const [loopName, action, ...targetParts] = positional;
+  const target = targetParts.join(' ');
+  if (!loopName || !action || !target) {
+    console.error('usage: docket check <loop> <read|draft|change|send> <target…>');
+    return 1;
+  }
+  if (!ACTIONS.includes(action)) {
+    console.error(`docket: "${action}" is not an action — use one of: ${ACTIONS.join(', ')}`);
+    return 1;
+  }
+  const docketDir = requireDocketDir();
+  const loop = loadLoop(docketDir, loopName);
+  const result = checkWarrant(loop, action, target);
+
+  // The check itself is evidence: record what was asked and what was answered.
+  if (!flags['no-record']) {
+    recordCheck(docketDir, loop.name, action, target, result, { via: 'cli' });
+  }
+
+  const style = VERDICT_STYLE[result.verdict];
+  if (!flags.quiet) {
+    console.log(`${style.color(bold(style.badge))}  ${action} → "${target}"`);
+    console.log(`  ${result.reason}`);
+    console.log(dim(`  rule: ${result.rule} · loop: ${loop.name} · exit ${EXIT[result.verdict]}`));
+  } else {
+    console.log(result.verdict);
+  }
+  return EXIT[result.verdict];
+}

package/src/commands/compile.js

@@ -0,0 +1,45 @@
+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 { dim, green } from '../lib/ui.js';
+
+export function cmdCompile(argv) {
+  const { flags } = parseArgs(argv, { booleans: ['write'] });
+  const target = flags.target ?? 'raw';
+  if (!TARGETS[target]) {
+    console.error(`docket: unknown target "${target}" — targets: ${Object.keys(TARGETS).join(', ')}`);
+    return 1;
+  }
+  const docketDir = requireDocketDir();
+  if (flags.loop && flags.write) {
+    // The managed block always holds every loop; writing just one would
+    // silently delete the rest from the agent's context file.
+    console.error(
+      'docket: --loop is for previewing one loop on stdout — --write always compiles all loops'
+    );
+    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;
+  }
+
+  if (!flags.write || target === 'raw') {
+    console.log(renderBlock(loops));
+    if (flags.write && target === 'raw') {
+      console.error(dim('(raw target always prints to stdout)'));
+    }
+    return 0;
+  }
+
+  const rootDir = path.dirname(docketDir);
+  const file = compileToFile(rootDir, target, loops);
+  console.log(
+    green('✓') +
+      ` compiled ${loops.length} loop${loops.length === 1 ? '' : 's'} → ${path.relative(process.cwd(), file)} ${dim(`(${TARGETS[target].label})`)}`
+  );
+  console.log(dim('  re-run after editing loops; the docket block is replaced in place'));
+  return 0;
+}

package/src/commands/init.js

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from '../lib/args.js';
+import { findDocketDir } from '../lib/loop.js';
+import { bold, cyan, dim, green } from '../lib/ui.js';
+
+const GITIGNORE_HINT = `# Docket keeps everything in plain files on purpose — commit them.
+# If a loop's Memory section holds things you don't want in git, move the
+# loop here and ignore it explicitly, e.g.:
+# loops/private-*.loop.md
+`;
+
+export function cmdInit(argv) {
+  const { flags } = parseArgs(argv, { booleans: ['quiet'] });
+  const root = path.resolve(flags.dir ?? process.cwd());
+  const dir = path.join(root, '.docket');
+  if (fs.existsSync(dir)) {
+    console.log(`already initialized: ${dir}`);
+    return 0;
+  }
+  // A .docket in an ancestor doesn't block a nested project — it would
+  // silently swallow this project's loops and record. Create locally, warn.
+  const ancestor = findDocketDir(root);
+  if (ancestor) {
+    console.log(
+      `note: ${ancestor} exists above this directory; commands run here will now use the new one`
+    );
+  }
+  fs.mkdirSync(path.join(dir, 'loops'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'README.md'), GITIGNORE_HINT);
+
+  if (!flags.quiet) {
+    console.log(green('✓') + ` created ${path.relative(process.cwd(), dir) || dir}`);
+    console.log(`
+${bold('A loop is one recurring task the agent does for you, wrapped in five layers.')}
+Before an agent touches anything, a loop answers:
+
+  1. What must it ${bold('know')} before it starts?
+  2. How is this work ${bold('supposed to be done')}?
+  3. What may it do ${bold('without asking')}?
+  4. Where does it have to ${bold('stop')}?
+  5. What ${bold('evidence')} must it leave behind?
+
+${dim('Unwritten answers get guessed at. Written answers get enforced.')}
+
+Next:
+  ${cyan('docket templates')}              see the starter loops
+  ${cyan('docket new my-loop')}            answer the five questions interactively
+  ${cyan('docket new appeal --template insurance-appeal')}
+  ${cyan('docket compile --target claude --write')}   put your loops in front of the agent
+`);
+  }
+  return 0;
+}

package/src/commands/list.js

@@ -0,0 +1,53 @@
+import { parseArgs } from '../lib/args.js';
+import { requireDocketDir, listLoops, loadLoop } from '../lib/loop.js';
+import { warrantLines } from '../lib/compile.js';
+import { bold, cyan, dim, red, yellow } from '../lib/ui.js';
+
+export function cmdList() {
+  const docketDir = requireDocketDir();
+  const loops = listLoops(docketDir);
+  if (!loops.length) {
+    console.log('no loops yet — create one with `docket new <name>`');
+    return 0;
+  }
+  console.log(bold(`${loops.length} loop${loops.length === 1 ? '' : 's'}`) + '\n');
+  for (const loop of loops) {
+    console.log(`  ${cyan(loop.name.padEnd(22))} ${loop.description}`);
+  }
+  console.log(dim('\ndetails: docket show <loop>'));
+  return 0;
+}
+
+export function cmdShow(argv) {
+  const { positional } = parseArgs(argv);
+  const name = positional[0];
+  if (!name) {
+    console.error('usage: docket show <loop>');
+    return 1;
+  }
+  const docketDir = requireDocketDir();
+  const loop = loadLoop(docketDir, name);
+
+  const section = (title, body) => {
+    console.log(bold(title));
+    console.log(body ? body.replace(/^/gm, '  ') : dim('  (empty)'));
+    console.log();
+  };
+
+  console.log(`${bold(cyan(loop.name))} — ${loop.description}\n${dim(loop.file)}\n`);
+  section('Brief — what it knows before it starts', loop.brief);
+  section('Procedure — how the work is done', loop.procedure);
+
+  console.log(bold('Warrant — what it may do on its own'));
+  for (const row of warrantLines(loop)) {
+    const label =
+      row.kind === 'ask' ? yellow('ask'.padEnd(7)) : row.kind === 'never' ? red('never'.padEnd(7)) : row.label.padEnd(7);
+    const text = row.text.startsWith('(') ? dim(row.text) : row.text;
+    console.log(`  ${label} ${text}`);
+  }
+  console.log(dim('  unlisted = ask. Silence is never permission.\n'));
+
+  section('Reserved — stays human', loop.reserved.map((j) => `- ${j}`).join('\n'));
+  section('Record — evidence it owes', loop.record.map((r) => `- ${r}`).join('\n'));
+  return 0;
+}