@astrosheep/keiyaku 2.9.10 → 2.9.12

package/README.md

@@ -1,50 +1,87 @@
-# 契約 Keiyaku
+# Keiyaku
 
-**You don't prompt an agent. You sign a contract with a devil.**
+契約 — a contract.
 
-Keiyaku (契約, "contract") is a CLI where AI coding agents work under written terms: the change starts as a contract, runs on an isolated branch, and lands only after it survives your gates. The agents are called **akuma** (悪魔) — devils. Devils are excellent workers and terrible masters, which is why everything here is in writing.
+Keiyaku is an AI-first CLI: its user is a coding agent. Not a human writing
+specs for an agent to implement — an agent delegating to other agents,
+running the whole loop itself: writing the terms, calling the worker,
+supervising the run, settling the outcome.
+
+That is why it is a contract system rather than a spec system. A spec relies
+on someone with judgment reading it charitably; here both the worker and the
+judge are models, and a model honors what you wrote, not what you meant. So
+terms are binding, the worker — an akuma (悪魔, demon) — runs on an isolated
+branch, gates and a reviewer judge the diff against the criteria alone, and
+settlement is mechanical: the change lands on main with a commit-hash
+receipt, or the branch is deleted. No human needs to be in the loop for any
+step; nothing depends on anyone eyeballing anything.
 
 ```bash
 npm install -g @astrosheep/keiyaku
 ```
 
-Node ≥ 22.19 · a git repo · a clean worktree. Dirty worktree = refused at the door.
+Node ≥ 22.19, inside a git repository with a clean worktree.
 
-## How a deal goes down
+## One deal, end to end
 
-```text
-   task            bind            call           petition          claim
- ───────►  📋  ───────►  ⛓  ───────►  😈  ───────►  ⚖  ───────►  ✓ main
-  the ask     the contract    devil at work     judgement       it lands
-```
+```bash
+# Write the terms: Title, Context, Objective, Design & Approach, Scope, Criteria.
+# The criteria are read by the letter — precision goes here, not in prompts.
+keiyaku bind - < contract.md
 
-**1 · Put it in writing.** `keiyaku bind` opens the contract — Title, Context, Objective, Design, Scope, Criteria — and an isolated branch. Devils honor the letter, never the spirit. Write "make it better" and you deserve what you get.
+# Put an akuma on it. It works alone in the contract's own worktree.
+keiyaku call worker-akuma --detach "fulfill the contract"
 
-**2 · Summon.** `keiyaku call worker-akuma "..."` projects a devil into the contract's worktree. It works; you rule: steer it mid-flight with `tell`, sit in with `wait`, banish it with `kill`. A finished run leaves an artifact — `revive` raises a new devil from its remains.
+# It runs for as long as it needs. You are not its babysitter —
+# but you can be:
+keiyaku wait worker-akuma/3f21ab9e --timeout 10m
+keiyaku tell worker-akuma/3f21ab9e "criteria 3 also covers the CLI output"
+keiyaku kill worker-akuma/3f21ab9e        # death is not an error state
 
-**3 · Judgement.** `keiyaku petition` seals the work and enters settlement. Verification gates and a reviewer stand between the devil and your main branch. **Claim** what passes. **Forfeit** burns the rest. Nothing lands quietly.
+# Ask for judgment: gates run, a reviewer akuma reads the diff
+# against the criteria.
+keiyaku petition
 
-```bash
-keiyaku guide          # the walkthrough
-keiyaku status         # where you stand, what blocks you
-keiyaku <cmd> --help   # exact grammar, no folklore
+# claim  → the change lands on main, with a commit-hash receipt
+# forfeit → the branch is deleted; partial fulfillment is forfeiture
 ```
 
-## The command surface
+Every step appends to the contract's ledger. `keiyaku log` replays any deal,
+finished or dead, from its receipts.
 
-| | |
-| --- | --- |
-| **Contract** | `bind` `arc` `amend` `renew` `audit` `petition` `forfeit` `log` |
-| **Devils** | `call` `tell` `wait` `kill` `revive` `status` `history` |
-| **Roster** | `akuma list` `akuma show` |
-| **Tasks** | `task add/show/ls/log/start/stop/hold/resume/done/drop/update/doctor` |
-| **System** | `guide` `completion` `dump-env` |
+## The board
 
-Tasks are a file-backed board living in your repo: capture work, wire real dependency semantics (`parent` · `needs` · `supersedes` · `relates-to`), then promote a task into a contract when it's ready to bind.
+`keiyaku status` is the one screen of state. Real output:
 
-## Rolling your own devil
+```text
+kanshi ─────────────────────────────────────────────────────── 現世 b4c38cc
+
+keiyaku 2
+□ fridge Add task arrange for atomic existing-task reorganization   ▲2 · open 27m
+□ hermitcrab Let task commands select a contract workspace               bound 8m
+
+akuma 2
+◆ worker-default/e03addad compose-impl @fridge                 up 27m · active 2s
+09:12│ told    “Root review found contract-significant gaps. Continue …” — 5m12s…
+     ⋮ 12 more
+09:17│ said    “The grouped verifier stream detached again, so I’m rerunning …”
+     │ ran     $ node --test tests/unit/task-compose.test.ts — 38s
++ 10 failed · 159 done · 4 killed
+
+task 120
+▶ P1 centralize-repository-ledger-test-construction …   in_progress · active 14h
+▶ P0 windows-common-commands-must-eliminate-git-proc…   in_progress · active 3d
++ 108 ready · 9 blocked
+```
+
+Every glyph has exactly one meaning. `◆` is a projection asserted alive —
+never inferred from output freshness. Durations are measured, exit codes are
+real, and an agent parses this screen without heuristics.
+
+## An akuma is one Markdown file
 
-An akuma is one Markdown file. Filename is its name, frontmatter is its body, prose is its soul:
+Filename is the name, frontmatter picks the provider and model, the body is
+the standing instructions. That's all it takes to make one callable.
 
 ```markdown
 ---
@@ -55,10 +92,12 @@ description: Repository implementation agent
 Make scoped changes and run relevant tests.
 ```
 
-Providers: `codex-sdk` · `codex-app-server` · `claude-agent-sdk` · `opencode-sdk` · `pi`.
-Resolution: builtin < `<KEIYAKU_HOME>/akuma/` < `.keiyaku/akuma/` — a higher circle replaces the file whole.
+Providers: `codex-sdk`, `codex-app-server`, `claude-agent-sdk`,
+`opencode-sdk`, `pi` — one contract can be worked by any of them, and a
+finished run leaves an artifact that `revive` can continue from, even across
+sessions.
 
-`.keiyaku/settings.json` picks roles and gates, nothing else:
+`.keiyaku/settings.json` assigns roles and gates:
 
 ```json
 {
@@ -68,24 +107,26 @@ Resolution: builtin < `<KEIYAKU_HOME>/akuma/` < `.keiyaku/akuma/` — a higher c
 }
 ```
 
-## Paper trail
+## And the rest
 
-Contracts leave marks — that's the point.
-
-| Path | |
+| | |
 | --- | --- |
-| `KEIYAKU.md` | the active contract |
-| `.keiyaku/` | devil roster, settings, task board, response history |
+| contract | `bind` `arc` `amend` `renew` `audit` `petition` `forfeit` `log` |
+| akuma | `call` `tell` `wait` `kill` `revive` `status` `history` |
+| tasks | `task add/show/ls/log/start/stop/hold/resume/done/drop/update/doctor` |
+| system | `guide` `completion` `dump-env` |
 
-```gitignore
-.keiyaku/draft/
-.keiyaku/response/
-```
+`keiyaku task` is a file-backed planning board for work that isn't worth a
+contract yet — typed dependencies, one micro-commit per change, promotion
+into a contract when it's ready.
 
-## Fine print
+Conventions hold everywhere: a literal `-` reads stdin for long bodies,
+`--json` where structure matters, and a rejected command states the legal
+grammar instead of guessing intent. State lives in `KEIYAKU.md` (the active
+contract) and `.keiyaku/` (akuma, settings, task board, history).
 
-The full body of law — product and architecture — lives in [`docs/keiyaku-v3/`](docs/keiyaku-v3/README.md). Start at the authority registry; nothing outside it is normative.
+Full product documentation: [`docs/keiyaku-v3/`](docs/keiyaku-v3/README.md).
 
-Keiyaku is early and experimental, built for AI agents operating end to end, and optimized for rapid iteration. Breaking changes are intentional and unapologetic: the current version is the only version.
+Keiyaku is early and experimental — breaking changes are intentional.
 
-MIT. The devils are not.
+MIT.