@astrosheep/keiyaku 0.1.76 → 0.1.78

package/README.md

@@ -1,148 +1,140 @@
 # Keiyaku
 
-Keiyaku is an MCP server that runs a contract-style workflow for AI-assisted coding in Git repos: isolate work on a dedicated `keiyaku/*` branch, iterate in rounds with review, then submit a final petition for judgment.
+MCP server。AI 的代码改动跑在独立 branch 上，task 写进 repo，没你许可不准结束。
 
-This README is for users of the tool (MCP clients). It intentionally does not document repo maintenance workflows.
-
-## Philosophy
+```bash
+npm install -g @astrosheep/keiyaku
+```
 
-Keiyaku is opinionated on purpose:
+---
 
-- Isolation over “chat edits”: work happens on a dedicated `keiyaku/*` branch so your base branch stays clean.
-- Explicit contracts: the goal/rules/criteria live in `KEIYAKU.md` so “what are we doing?” is always answered by a file, not a scrolling chat.
-- Review-driven iteration: you drive the rounds; the tool optimizes for diffs and verification, not vibes.
-- Verdict-gated finish: the contract ends via `petition` (CLAIM/FORFEIT) so “done” is an explicit decision with gates (oath + scores).
+## 装之前
 
-## When To Use Which Tool
+少一个都别来问为什么不能用：
 
-- Use `ask` for investigation: summarize, locate relevant code, run tests/scripts, debug a failure. No branch required.
-- Use `summon`/`drive` for non-trivial code changes that should be isolated and iterated.
-- Use `petition` only when you believe the criteria are met (CLAIM) or when you want to discard the contract (FORFEIT).
+- **Git repo**，worktree 干净的。脏的不给用。
+- **MCP client**。Claude Desktop、Claude Code、随便什么 stdio 的。
+- **Subagent CLI**。[`claude`](https://docs.anthropic.com/en/docs/claude-code) 或 [`gemini`](https://github.com/google-gemini/gemini-cli)，装好，登录好。Keiyaku 自己不跑代码，全丢给 subprocess。没装 = 什么都不会发生。
 
-## How It Works
+---
 
-Keiyaku formalizes a task into:
+## 配置
 
-- A signed contract (`KEIYAKU.md`) that defines goal, rules, and verification criteria
-- A round trace (`KEIYAKU_TRACE.md`) that records iterations
-- A final petition (`petition`) that requests a CLAIM or FORFEIT verdict
+Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 
-Default workflow:
+```json
+{
+  "mcpServers": {
+    "keiyaku": {
+      "command": "npx",
+      "args": ["-y", "@astrosheep/keiyaku"]
+    }
+  }
+}
+```
 
-`ask` (anytime) | `summon` -> [`drive` | `ask`]* -> `petition`
+重启 client。打开 git repo。跑 `status`。完了。
 
-Typical loop:
+---
 
-1. `summon`: provide `title`, `goal`, `criteria` (plus any rules/context). Repo must be clean.
-2. Review the round output and repo diff.
-3. `drive`: issue the next directive (fixes, refinements, tests, cleanup).
-4. `ask`: optionally verify independently (tests, static checks, targeted inspection).
-5. `petition`:
-   - `CLAIM` to request acceptance (requires oath + 0-10 scores).
-   - `FORFEIT` to abandon and discard the contract.
+## 流程
 
-## Tools (Default Preset)
+```
+ask (随时)  |  summon → [drive | ask]* → petition
+```
 
-Keiyaku registers the following MCP tools:
+---
 
-- `summon`: start a contract, create/enter a `keiyaku/*` branch, and write the initial protocol files
-- `drive`: run the next round (mutates the repo)
-- `ask`: stateless delegation (analysis, running tests/scripts, debugging). No keiyaku branch required.
-- `petition`: submit `CLAIM` or `FORFEIT` to close the contract (verdict-gated)
-- `status`: read-only contract/protocol status and readiness hints
-- `help`: usage guide and protocol notes
+## 工具
 
-Term presets: currently only `default` is supported (`KEIYAKU_TERM_PRESET=default`).
+**`ask`** — 问东西用的。不开 branch，不建 contract，随便用。
 
-## Install / Run
+```
+retry 逻辑在哪？跑一下那个文件的 unit test。
+```
 
-Global install:
+---
 
-```bash
-npm install -g @astrosheep/keiyaku
-keiyaku --version
-```
+**`summon`** — 开 branch，写 contract。repo 必须干净。
 
-Via npx:
+criteria 写多具体，结果就有多具体。写 "make it better" 就别怪 AI 自由发挥。
 
-```bash
-npx -y @astrosheep/keiyaku --version
+```
+summon:
+  title: "Retry logic for HTTP client"
+  goal: "5xx failures retry up to 3 times with exponential backoff"
+  criteria:
+    - Retry unit tests pass
+    - Public API unchanged
+    - Existing tests still pass
 ```
 
-## MCP Setup
+---
 
-### Claude Desktop (stdio)
+**`drive`** — 下一轮。看完 diff，说哪里不对，再跑一轮。
 
-```json
-{
-  "mcpServers": {
-    "keiyaku": {
-      "command": "npx",
-      "args": ["-y", "@astrosheep/keiyaku"]
-    }
-  }
-}
 ```
-
-### Streamable HTTP
-
-```bash
-KEIYAKU_MCP_TRANSPORT=streamable-http \
-KEIYAKU_MCP_HTTP_HOST=127.0.0.1 \
-KEIYAKU_MCP_HTTP_PORT=3000 \
-npx -y @astrosheep/keiyaku
+Backoff 是 1.5x，应该 2x。改掉，test 也更新。
 ```
 
-Endpoint: `http://127.0.0.1:3000/mcp`
+---
 
-## What Gets Written To Your Repo
+**`petition`** — 结束 task。
 
-Keiyaku writes protocol artifacts into the target repository:
+`CLAIM` = 我验证过了，criteria 全过了。`FORFEIT` = 不要了，全部丢掉。
 
-- `KEIYAKU.md`: the active contract (goal/rules/criteria)
-- `KEIYAKU_TRACE.md`: round-by-round trace
-- `KEIYAKU.draft.md`: optional recovery draft when start fails
-- `.keiyaku/response/*.md`: persisted responses for `summon`, `drive`, and `ask`
-- `.keiyaku/draft/*`: internal drafts (used for recovery and workflow safety)
+要打分 (0–10)，要宣誓。gate 是真的会拒绝你的。没检查就别来。
 
-If you do not want these tracked, add:
+---
 
-- `.keiyaku/draft/`
-- `.keiyaku/response/`
+**`status`** — 现在什么状态，什么在挡路。
 
-to `.gitignore`.
+**`help`** — 完整参考。
 
-## Key Environment Variables
+---
 
-Server / transport:
+## 写进 repo 的东西
 
-- `KEIYAKU_MCP_TRANSPORT`: `stdio` (default) or `streamable-http`
-- `KEIYAKU_MCP_HTTP_HOST`: default `127.0.0.1`
-- `KEIYAKU_MCP_HTTP_PORT`: default `3000`
+| 文件 | |
+|------|--|
+| `KEIYAKU.md` | 当前 contract |
+| `KEIYAKU_TRACE.md` | 每轮记录 |
+| `KEIYAKU.draft.md` | summon 失败时的恢复用 draft |
+| `.keiyaku/response/*.md` | 每轮输出 |
 
-Preset / naming:
+不想 track 就加 `.gitignore`：
 
-- `KEIYAKU_TERM_PRESET`: only `default` is supported
-- `KEIYAKU_SUBAGENT_NAME_OVERRIDE`: overrides the default subagent display name
+```gitignore
+.keiyaku/draft/
+.keiyaku/response/
+```
 
-Subagent execution:
+---
 
-- `KEIYAKU_DISABLE_SUBAGENT_SPAWN`: when `1`, blocks Keiyaku MCP server startup
-- `KEIYAKU_FAKE_SUBAGENT`: `0` | `1` | `abort-wait` (stub subagent execution)
-- `KEIYAKU_SUBAGENT_EXEC_TIMEOUT_MS`: total execution timeout for all providers
-- `KEIYAKU_SUBAGENT_EXEC_IDLE_TIMEOUT_MS`: idle timeout for all providers, reset by subprocess output or streamed SDK events
+## 进阶
 
-Workflow:
+```bash
+keiyaku dump-env
+```
 
-- `KEIYAKU_INCREMENTAL_DIFF_MODE`: `targeted` (default) | `stat` | `unified`
-- `KEIYAKU_CLOSE_OATH`: overrides the required petition oath template
+| 变量 | 默认值 | |
+|------|--------|--|
+| `KEIYAKU_MCP_TRANSPORT` | `stdio` | `stdio` 或 `streamable-http` |
+| `KEIYAKU_MCP_HTTP_PORT` | `3000` | HTTP 端口 |
+| `KEIYAKU_SUBAGENT_EXEC_TIMEOUT_MS` | — | 执行超时 |
+| `KEIYAKU_SUBAGENT_EXEC_IDLE_TIMEOUT_MS` | — | 空闲超时 |
+| `KEIYAKU_INCREMENTAL_DIFF_MODE` | `targeted` | `targeted` \| `stat` \| `unified` |
+| `KEIYAKU_FAKE_SUBAGENT` | `0` | `1` = 测试用 stub |
 
-Print the full env template with defaults:
+HTTP transport：
 
 ```bash
-keiyaku dump-env
+KEIYAKU_MCP_TRANSPORT=streamable-http \
+KEIYAKU_MCP_HTTP_HOST=127.0.0.1 \
+KEIYAKU_MCP_HTTP_PORT=3000 \
+npx -y @astrosheep/keiyaku
 ```
 
-## License
+---
 
 MIT