docket-agent 0.1.0 → 0.2.1

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
 
@@ -202,6 +205,47 @@ The agent gets four tools:
 Warrant checks made by the agent land in the record too. *"Did the agent
 even ask?"* becomes a grep.
 
+## 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:
@@ -215,6 +259,32 @@ even ask?"* becomes a grep.
 Unwritten answers get guessed at. Written answers get enforced — the
 questions *are* the schema: brief, procedure, warrant, reserved, record.
 
+## It iterates itself — with a human veto
+
+The record knows where the warrant chafes: every time the agent hit an
+unlisted action, a default-ask was logged. `docket review` mines those and
+proposes the exact amendments:
+
+```console
+$ docket review
+2 proposed amendments — from repeated asks in the record
+
+  1. appeal — allow read: "state insurance regulations" (asked 4×)
+  2. appeal — allow draft: "timeline summary" (asked 2×)
+
+allow read: "state insurance regulations" in appeal? [y/N] y
+✓ appeal: read now covers "state insurance regulations"
+```
+
+Three rules keep it honest: the analysis is automatic but **applying is
+always a human keystroke** (an agent that widens its own permissions is the
+exact failure docket exists to prevent — it's in our red-team suite);
+anything on the `ask` or `never` lists is **never proposed**, however often
+it recurs — those are policy, not friction; and every approved amendment is
+**appended to the record**, so even the evolution of the rules is auditable.
+
+Run it weekly, or wire it into a cron — the proposals wait for you.
+
 ## Starter loops
 
 Seven templates, each a complete worked example (`docket templates`):
@@ -249,7 +319,7 @@ Read the [Loop File Spec](spec/SPEC.md) — it's short on purpose.
 - [ ] `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.1.0",
+  "version": "0.2.1",
   "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

@@ -181,12 +181,14 @@ Storage: `.docket/record.jsonl`, one JSON object per line, append-only.
 {"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:
+Three 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`.
+- `amend` — a human-approved warrant widening (`action`, `added`, `asks`),
+  written by `docket review`. Rule changes are evidence too.
 
 ### The hash chain
 
@@ -210,6 +212,14 @@ 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.)
 
+## Review
+
+`docket review` clusters repeated default-ask checks from the record and
+proposes the corresponding warrant additions. Implementations must not apply
+proposals without explicit human approval, must never propose targets that
+match the loop's `ask` or `never` lists, and must append an `amend` entry to
+the record for every applied change.
+
 ## Compiled context
 
 Loops are the source of truth; assistant-specific files are build artifacts.

package/src/cli.js

@@ -6,6 +6,7 @@ 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 { cmdReview } from './commands/review.js';
 import { cmdMcp } from './commands/mcp.js';
 
 const HELP = `
@@ -25,13 +26,18 @@ ${bold('Working with loops')}
                              ask the warrant: allow, ask, or deny?
                              (actions: read, draft, change, send)
 
+${bold('Iterating')}
+  ${cyan('review')} [--min 2] [--loop <name>] [--yes]
+                             propose warrant updates from repeated asks —
+                             you approve each one; approvals go on the record
+
 ${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]
+  ${cyan('compile')} [--target claude|agents|gemini|cursor|raw] [--loop <name>] [--write]
                              render loops into CLAUDE.md / AGENTS.md / Cursor rules
   ${cyan('mcp')}                        run the MCP server (stdio) for agent integration
 
@@ -70,6 +76,8 @@ export async function main(argv) {
       return cmdRecord(rest);
     case 'compile':
       return cmdCompile(rest);
+    case 'review':
+      return cmdReview(rest);
     case 'mcp':
       return cmdMcp(rest);
     default:

package/src/commands/record.js

@@ -16,6 +16,9 @@ function formatEntry(e) {
     const style = VERDICT_STYLE[e.verdict] ?? { color: (s) => s, badge: e.verdict };
     return `${head} ${style.color(style.badge.toLowerCase())} ${e.action} → "${e.target}" ${dim(`(${e.rule})`)}`;
   }
+  if (e.kind === 'amend') {
+    return `${head} amended warrant: ${e.action} now covers "${e.added}" ${dim(`(after ${e.asks} asks)`)}`;
+  }
   const parts = [];
   if (e.saw) parts.push(`saw: ${e.saw}`);
   if (e.did) parts.push(`did: ${e.did}`);