@astrosheep/keiyaku 2.9.9 → 2.9.11

package/README.md

@@ -1,223 +1,142 @@
 # 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.
+契約 — a contract.
 
-```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
-```
-
----
+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.
 
-## 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.
-
-```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`.
+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.
 
 ```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
+npm install -g @astrosheep/keiyaku
 ```
 
----
+Node ≥ 22.19, inside a git repository, with a clean worktree.
 
-**`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.
+## Shape of a deal
 
+```text
+task ─── bind ─── call ─── petition ─── claim
 ```
-# Retry backoff
-
-## Objective
-Implement retries with exponential backoff.
-
-## Brief
-Keep the public API unchanged. Commit the delivery work before sealing the arc.
-```
-
----
-
-**`petition`** — Seals the current a0 or open explicit arc and enters settlement.
 
-`CLAIM` = verified, all criteria pass. `FORFEIT` = abandon, throw everything away.
+`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.
 
-Oath required unless you explicitly bypass gates. Configured verification and reviewer gates will reject weak claims.
+`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.
 
----
+`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.
 
-**`status`** — Current state and what's blocking you.
+## What state looks like
 
-**`keiyaku guide`** — Workflow guide.
-
----
+`keiyaku status` renders the watchtower — 監視, kanshi. This is real output
+from this repository:
 
-## What Gets Written to the Repo
+```text
+kanshi ─────────────────────────────────────────────────────── 現世 b4c38cc
 
-| File | |
-|------|--|
-| `KEIYAKU.md` | Active contract |
-| `.keiyaku/draft/*.md` | Recovery input if bind/stdin execution fails |
-| `.keiyaku/response/*.md` | Tool response history |
+keiyaku 2
+□ fridge Add task arrange for atomic existing-task reorganization   ▲2 · open 27m
+□ hermitcrab Let task commands select a contract workspace               bound 8m
 
-Don't want these tracked:
+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
 
-```gitignore
-.keiyaku/draft/
-.keiyaku/response/
+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
 ```
 
----
-
-## Configuration
+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).
 
-Keiyaku works with its builtin `akuma-codex` and `akuma-claude` profiles without a settings file. Inspect the effective catalog before launching an Akuma:
+## Surface
 
-```bash
-keiyaku akuma list
-keiyaku akuma show akuma-codex
-```
-
-### Akuma profiles
+| | |
+| --- | --- |
+| 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` |
 
-Akuma profiles are Markdown files. The filename is the profile name, YAML frontmatter configures the provider, and the Markdown body supplies the Akuma instructions.
+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.
 
-| 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 inside the repository. Dependencies keep their
+distinct meanings — `parent`, `needs`, `supersedes`, `relates-to` — and every
+mutation is validated and micro-committed on its own.
 
-`KEIYAKU_HOME` defaults to `~/.keiyaku`. A higher layer replaces the whole file; layers are not field-merged.
+## A devil is one file
 
-Minimal project profile:
+Filename is the name. Frontmatter selects the provider. The body is the
+instructions.
 
 ```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 is builtin, then `<KEIYAKU_HOME>/akuma/`,
+then `.keiyaku/akuma/`; a higher layer replaces the file whole, never
+field-merges.
 
-| 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` selects 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.
+## What it writes
 
-### Environment
+| | |
+| --- | --- |
+| `KEIYAKU.md` | the active contract |
+| `.keiyaku/` | devils, settings, task board, response history |
 
-```bash
-keiyaku dump-env
+```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.
+## Law
 
----
+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.
+
+Keiyaku is early and experimental. Breaking changes are intentional, and the
+current version is the only version.
 
-MIT
+MIT.