docket-agent 0.1.0 → 0.2.0

package/README.md

@@ -215,6 +215,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`):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docket-agent",
-  "version": "0.1.0",
+  "version": "0.2.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

@@ -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,6 +26,11 @@ ${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]
@@ -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}`);