@astrosheep/keiyaku 2.9.8 → 2.9.10

package/README.md

@@ -1,223 +1,91 @@
-# Keiyaku
+# 契約 Keiyaku
 
-CLI for contract-style coding work in git repositories. AI code changes run on an isolated branch. Tasks are written into the repo. Nothing closes without your sign-off.
+**You don't prompt an agent. You sign a contract with a devil.**
 
-```bash
-npm install -g @astrosheep/keiyaku
-```
-
----
-
-## Before You Start
-
-Missing any of these? Don't come crying.
-
-- **Git repo.** Clean worktree. Dirty = refused.
-- **Supported providers.** `codex-sdk`, `codex-app-server`, `claude-agent-sdk`, `opencode-sdk`, and `pi`.
-
----
-
-## Setup
-
-Open a git repo. Run `keiyaku guide` and `keiyaku akuma list`. Then use `keiyaku <command> --help` for exact command formats.
-
----
-
-## Flow
-
-```
-bind -> delivery work -> petition
-optional: arc -> delivery work -> arc; renew on base drift
-```
-
----
-
-## Tools
-
-**`call NAME <BODY|->`** — Calls in an agent to do scoped work. When commissioned, call receives the current bind a0 or explicit arc intent. Body is a required literal or `-` for stdin; omitting body is an error even if stdin is piped. Add `--incognito` for a one-off run with no response history.
+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.
 
 ```bash
-keiyaku call worker-akuma "Implement the retry tests. Report touched files and verification."
-keiyaku call worker-akuma - < prompt.md
-```
-
----
-
-**`tell PROJECTION [--wait DURATION] [--] <BODY|->`** — Writes intent to a projection mailbox. Body is a required literal or `-` for stdin. Ordinary bodies need no `--`; use `--` only when the body looks like an option or address. `tell --wait` joins after acceptance without a mandatory separator.
-
-```bash
-keiyaku tell kaji/3f2a1c99 "run integration first"
-keiyaku tell kaji/3f2a1c99 - < direction.md
-keiyaku tell kaji/3f2a1c99 --wait 5m "run integration first"
-keiyaku tell kaji/3f2a1c99 -- --stop
-```
-
----
-
-**`revive ARTIFACT [BODY|-]`** — Starts a new helper projection from a retained response artifact. Omit body for the default continuation; pass a literal body or `-` for explicit stdin (blank explicit stdin fails).
-
-```bash
-keiyaku revive rsp_01ARZ3NDEKTSV4RRFFQ69G5FAV
-keiyaku revive rsp_01ARZ3NDEKTSV4RRFFQ69G5FAV "continue with the failing test"
-keiyaku revive rsp_01ARZ3NDEKTSV4RRFFQ69G5FAV - < continuation.md
-```
-
----
-
-**`akuma list` / `akuma show <name>`** — Inspect available helpers before choosing `keiyaku call NAME`.
-
-```bash
-keiyaku akuma list
-keiyaku akuma show akuma-codex
-```
-
----
-
-**`bind`** — Opens a branch and writes `KEIYAKU.md`. Repo must be clean. Bind supplies derived default intent a0.
-
-Vague criteria = vague results. Write "make it better" and don't blame anyone but yourself.
-
-```
-# Retry logic for HTTP client
-
-## Objective
-5xx failures retry up to 3 times with exponential backoff
-
-## Scope
-- src/http/**
-
-## Checks
-- Retry unit tests pass
-- Public API unchanged
-- Existing tests still pass
-```
-
----
-
-**`arc`** — Optional iteration boundary, not admission. Frames the next delivery intent; the first explicit arc seals a0, and later arcs seal the previous open explicit arc.
-
-```
-# Retry backoff
-
-## Objective
-Implement retries with exponential backoff.
-
-## Brief
-Keep the public API unchanged. Commit the delivery work before sealing the arc.
+npm install -g @astrosheep/keiyaku
 ```
 
----
-
-**`petition`** — Seals the current a0 or open explicit arc and enters settlement.
-
-`CLAIM` = verified, all criteria pass. `FORFEIT` = abandon, throw everything away.
-
-Oath required unless you explicitly bypass gates. Configured verification and reviewer gates will reject weak claims.
-
----
-
-**`status`** — Current state and what's blocking you.
+Node ≥ 22.19 · a git repo · a clean worktree. Dirty worktree = refused at the door.
 
-**`keiyaku guide`** — Workflow guide.
+## How a deal goes down
 
----
-
-## What Gets Written to the Repo
-
-| File | |
-|------|--|
-| `KEIYAKU.md` | Active contract |
-| `.keiyaku/draft/*.md` | Recovery input if bind/stdin execution fails |
-| `.keiyaku/response/*.md` | Tool response history |
-
-Don't want these tracked:
-
-```gitignore
-.keiyaku/draft/
-.keiyaku/response/
+```text
+   task            bind            call           petition          claim
+ ───────►  📋  ───────►  ⛓  ───────►  😈  ───────►  ⚖  ───────►  ✓ main
+  the ask     the contract    devil at work     judgement       it lands
 ```
 
----
+**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.
 
-## Configuration
+**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.
 
-Keiyaku works with its builtin `akuma-codex` and `akuma-claude` profiles without a settings file. Inspect the effective catalog before launching an Akuma:
+**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.
 
 ```bash
-keiyaku akuma list
-keiyaku akuma show akuma-codex
+keiyaku guide          # the walkthrough
+keiyaku status         # where you stand, what blocks you
+keiyaku <cmd> --help   # exact grammar, no folklore
 ```
 
-### Akuma profiles
+## The command surface
 
-Akuma profiles are Markdown files. The filename is the profile name, YAML frontmatter configures the provider, and the Markdown body supplies the Akuma instructions.
+| | |
+| --- | --- |
+| **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` |
 
-| Layer | Location | Precedence |
-|---|---|---|
-| Builtin | packaged with Keiyaku | lowest |
-| User | `<KEIYAKU_HOME>/akuma/<name>.md` | replaces the same builtin name |
-| Project | `.keiyaku/akuma/<name>.md` | highest |
+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_HOME` defaults to `~/.keiyaku`. A higher layer replaces the whole file; layers are not field-merged.
+## Rolling your own devil
 
-Minimal project profile:
+An akuma is one Markdown file. Filename is its name, frontmatter is its body, prose is its soul:
 
 ```markdown
 ---
 provider: codex-sdk
-description: Repository implementation agent
 model: gpt-5.4
-effort: high
-accessPolicy: write
-networkPolicy: disabled
-webSearchPolicy: disabled
-threadOptions.sandboxMode: workspace-write
+description: Repository implementation agent
 ---
-Follow the repository instructions, make scoped changes, and run relevant tests.
+Make scoped changes and run relevant tests.
 ```
 
-Provider fields:
+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.
 
-| Provider | Supported profile fields |
-|---|---|
-| `codex-sdk` | `description`, `model`, `profile`, `executable`, `effort`, `accessPolicy`, `networkPolicy`, `webSearchPolicy`, `threadOptions.*`, `config.*` |
-| `codex-app-server` | `description`, `model`, `profile`, `executable`, `config.*` |
-| `claude-agent-sdk` | `description`, `model`, `executable`, `effort`, `permissionMode`, `settingSources` |
-| `opencode-sdk` | `description`, `model`, `executable` |
-| `pi` | `description`, `model` |
-
-For `threadOptions.*`, JSON values such as arrays and objects are accepted. Keiyaku owns `workingDirectory` and `skipGitRepoCheck`, so profiles cannot set those paths.
-
-### Settings
-
-Settings select roles and workflow knobs; provider definitions do not belong in settings. Keiyaku loads user settings first and overlays project settings:
-
-- User: `<KEIYAKU_HOME>/settings.json`
-- Project: `.keiyaku/settings.json`
+`.keiyaku/settings.json` picks roles and gates, nothing else:
 
 ```json
 {
-  "default": "akuma-codex",
-  "reviewer": "akuma-claude",
-  "defaultBranch": "main",
-  "gate": {
-    "commands": [
-      { "label": "tests", "command": "npm", "args": ["test"] }
-    ]
-  }
+  "default": "worker-akuma",
+  "reviewer": "review-akuma",
+  "gate": { "commands": [{ "label": "tests", "command": "npm", "args": ["test"] }] }
 }
 ```
 
-The only settings keys are `default`, `reviewer`, `defaultBranch`, and `gate`. The former `agents` key is invalid; define profiles in an `akuma/` directory instead. `keiyaku status` reports invalid settings without hiding the rest of the board.
+## Paper trail
 
-### Environment
+Contracts leave marks — that's the point.
 
-```bash
-keiyaku dump-env
+| Path | |
+| --- | --- |
+| `KEIYAKU.md` | the active contract |
+| `.keiyaku/` | devil roster, settings, task board, response history |
+
+```gitignore
+.keiyaku/draft/
+.keiyaku/response/
 ```
 
-Keiyaku loads `<KEIYAKU_HOME>/.env`, then `.keiyaku/.env`; values already present in the process environment take precedence. `dump-env` is the authoritative template for supported keys and defaults.
+## Fine print
 
----
+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.
+
+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.
 
-MIT
+MIT. The devils are not.