@astrosheep/keiyaku 2.9.11 → 2.9.12

package/README.md

@@ -2,45 +2,56 @@
 
 契約 — a contract.
 
-Keiyaku is a CLI for coding agents. Not a developer tool with AI features: the
-intended reader of every command, receipt, and error message is a model. If a
-human is typing `keiyaku` by hand, something upstream has already gone wrong.
-
-The premise is old. Work you delegate to something more capable than
-accountable should be written down first. So here, a change begins as a
-contract, runs on an isolated branch, and lands only after settlement. The
-workers are called akuma — 悪魔, devils. This is not branding. It is a
-reminder of the failure mode.
+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, inside a git repository, with a clean worktree.
+Node ≥ 22.19, inside a git repository with a clean worktree.
 
-## Shape of a deal
+## One deal, end to end
 
-```text
-task ─── bind ─── call ─── petition ─── claim
-```
+```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
+
+# Put an akuma on it. It works alone in the contract's own worktree.
+keiyaku call worker-akuma --detach "fulfill the contract"
 
-`bind` opens a contract — Title, Context, Objective, Design, Scope,
-Criteria — and an isolated branch. A devil honors the letter of the criteria,
-not their spirit; the contract is where precision happens.
+# 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
 
-`call` projects a devil into the contract's worktree. While it runs: `tell` it
-things, `wait` on it, `kill` it. A finished run leaves an artifact; `revive`
-starts a new devil from one.
+# Ask for judgment: gates run, a reviewer akuma reads the diff
+# against the criteria.
+keiyaku petition
 
-`petition` seals the delivery and enters settlement. Gates run, a reviewer
-reads, and then exactly one of two things happens: claim, and it lands on
-main — or forfeit, and the branch is gone. There is no third outcome and no
-quiet one.
+# claim  → the change lands on main, with a commit-hash receipt
+# forfeit → the branch is deleted; partial fulfillment is forfeiture
+```
+
+Every step appends to the contract's ledger. `keiyaku log` replays any deal,
+finished or dead, from its receipts.
 
-## What state looks like
+## The board
 
-`keiyaku status` renders the watchtower — 監視, kanshi. This is real output
-from this repository:
+`keiyaku status` is the one screen of state. Real output:
 
 ```text
 kanshi ─────────────────────────────────────────────────────── 現世 b4c38cc
@@ -63,36 +74,14 @@ task 120
 + 108 ready · 9 blocked
 ```
 
-The rendering is itself under contract. `◆` may only mean a projection asserted
-alive — liveness is never inferred from output freshness. `⋮ 12 more` counts
-exactly twelve omitted rows. Durations are measured, exit codes are real, and a
-command that never finished says `never finished`. An agent parses this screen
-without heuristics because every glyph has one meaning, in writing, in
-[`docs/keiyaku-v3/product/ui-copy.md`](docs/keiyaku-v3/product/ui-copy.md).
-
-## Surface
-
-| | |
-| --- | --- |
-| 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` |
-
-Conventions an agent can rely on everywhere: a literal `-` selects stdin for
-long bodies; `--json` exists where structure matters; a rejected command names
-the legal grammar instead of guessing intent; `keiyaku <cmd> --help` is the
-single source of syntax.
+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.
 
-Tasks are a file-backed board inside the repository. Dependencies keep their
-distinct meanings — `parent`, `needs`, `supersedes`, `relates-to` — and every
-mutation is validated and micro-committed on its own.
+## An akuma is one Markdown file
 
-## A devil is one file
-
-Filename is the name. Frontmatter selects the provider. The body is the
-instructions.
+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
 ---
@@ -104,11 +93,11 @@ Make scoped changes and run relevant tests.
 ```
 
 Providers: `codex-sdk`, `codex-app-server`, `claude-agent-sdk`,
-`opencode-sdk`, `pi`. Resolution is builtin, then `<KEIYAKU_HOME>/akuma/`,
-then `.keiyaku/akuma/`; a higher layer replaces the file whole, never
-field-merges.
+`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` selects roles and gates, nothing else:
+`.keiyaku/settings.json` assigns roles and gates:
 
 ```json
 {
@@ -118,25 +107,26 @@ field-merges.
 }
 ```
 
-## What it writes
+## And the rest
 
 | | |
 | --- | --- |
-| `KEIYAKU.md` | the active contract |
-| `.keiyaku/` | devils, 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.
 
-## Law
+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).
 
-Product and architecture law is registered in
-[`docs/keiyaku-v3/`](docs/keiyaku-v3/README.md). A document is normative only
-if the registry lists it; age, location, and confident prose grant nothing.
+Full product documentation: [`docs/keiyaku-v3/`](docs/keiyaku-v3/README.md).
 
-Keiyaku is early and experimental. Breaking changes are intentional, and the
-current version is the only version.
+Keiyaku is early and experimental — breaking changes are intentional.
 
 MIT.