@astrosheep/keiyaku 0.1.65 → 0.1.68

package/README.md

@@ -1,105 +1,150 @@
-# 🤝 Keiyaku
+# Keiyaku
 
-**Keiyaku** is an MCP server designed for the **Architect-Minion workflow**. It enforces a strict, review-driven protocol for iterative coding tasks.
+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.
 
-Instead of messy, unstructured chat, Keiyaku turns every task into a formal "Keiyaku": a branch-based, multi-round journey with a clear beginning, a traced middle, and a definitive end.
+This README is for users of the tool (MCP clients). It intentionally does not document repo maintenance workflows.
 
-## 🚀 Why Keiyaku?
+## Philosophy
 
-- **Zero Mess**: Every task lives in its own `keiyaku/*` branch. Your main branch stays pristine.
-- **Traceable Logic**: Every iteration is documented in `KEIYAKU_TRACE.md`. You can literally see the AI's "learning curve" (or mistakes).
-- **Strict Guardrails**: No "Done" until you say so. No merging until the criteria are met.
-- **Human-in-the-Loop**: Designed for humans who actually want to review the code before it hits production.
+Keiyaku is opinionated on purpose:
 
-## 🔄 The Lifecycle
+- 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).
 
-The workflow is a simple, non-negotiable loop:
+## When To Use Which Tool
 
-1.  **Start**: Initiate the keiyaku. Creates a branch, locks the mission in `KEIYAKU.md`, and starts Round 1.
-2.  **Iterate** (N times): Review the work, give feedback, and launch the next round.
-3.  **Verdict**: The final verdict. `DONE` (merge & clean) or `DROP` (nuke the branch).
+- 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).
 
-> Note: Tool names are preset-dependent. The defaults are shown in the next section.
+## How It Works
 
-## 🛠 Available Tools
+Keiyaku formalizes a task into:
 
-| Tool | Action | Description |
-| :--- | :--- | :--- |
-| **`summon`** | Start | Define the goal, rules, and criteria. Starts the first round. |
-| **`drive`** | Iterate | Provide feedback based on the previous round's output. |
-| **`ask`** | Reason | Pure read-only analysis session. No code changes, just brain power. |
-| **`present`** | Finish | Finalize the task. Requires a quality check (the "Oath"). |
-| **`help`** | Help | Show the current rules + preset usage guide. |
+- 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
 
-## 🎨 Flavor Your Workflow
+Default workflow:
 
-Bored with generic tool names? Keiyaku supports **Term Presets**.
+`ask` (anytime) | `summon` -> [`drive` | `ask`]* -> `petition`
 
-### How to set
+Typical loop:
 
-Set `KEIYAKU_TERM_PRESET` in the MCP server env (recommended), or in your shell before launching the server.
+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.
 
-- **Valid values**: `default`, `pocket`, `mischief` (case-insensitive). If omitted, defaults to `default`.
+## Tools (Default Preset)
 
-- **`default`**: `summon` → `drive` → `present` (Professional)
-- **`pocket`**: `choose_you` → `command` → `capture` (Gotta code 'em all)
-- **`mischief`**: `oi` → `neh` → `yoshi` (For those who like a little attitude)
+Keiyaku registers the following MCP tools:
 
-`ask` is also renamed by preset (`ask` / `pokedex` / `eeto`). `help` stays `help` across presets.
+- `summon`: start a contract, create/enter a `keiyaku/*` branch, run round 1
+- `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
 
-### What it changes (and what it doesn't)
+Term presets: currently only `default` is supported (`KEIYAKU_TERM_PRESET=default`).
 
-- **Changes**: tool names/titles/descriptions, the "identity" label, and the set of allowed profile display names (see next section).
-- **Doesn't change**: core behavior (branching, protocol files, verdict rules).
+## Install / Run
 
-### Choose a profile name
+Global install:
 
-Each run/round can pick a profile via tool input `name`, or globally via `KEIYAKU_SUBAGENT_NAME_OVERRIDE`.
-
-- `default`: `B-tier`, `A-tier`, `S-tier` (also accepts internal names `agent-a|agent-b|agent-c`)
-- `pocket`: `grub`, `sparky`, `titan`
-- `mischief`: `imp`, `minion`, `mastermind`
-
-### Prevent nested subagents
-
-Set `KEIYAKU_DISABLE_SUBAGENT_SPAWN=1` to block any subagent spawn attempts in the current process.
-Keiyaku automatically injects this env var into spawned Codex/Gemini runs so they cannot recursively trigger another Keiyaku subagent run.
+```bash
+npm install -g @astrosheep/keiyaku
+keiyaku --version
+```
 
-## 📦 Setup
+Via npx:
 
-### 1. Install
 ```bash
-npm install -g keiyaku
+npx -y @astrosheep/keiyaku --version
 ```
 
-### 2. Configure MCP (Example: Claude Desktop)
-Add this to your `claude_desktop_config.json`:
+## MCP Setup
+
+### Claude Desktop (stdio)
 
 ```json
 {
   "mcpServers": {
     "keiyaku": {
       "command": "npx",
-      "args": ["-y", "keiyaku"],
-      "env": {
-        "KEIYAKU_TERM_PRESET": "mischief" 
-      }
+      "args": ["-y", "@astrosheep/keiyaku"]
     }
   }
 }
 ```
 
-## 📜 Protocol Files
+### 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
+```
+
+Endpoint: `http://127.0.0.1:3000/mcp`
+
+## What Gets Written To Your Repo
+
+Keiyaku writes protocol artifacts into the target repository:
+
+- `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)
+
+If you do not want these tracked, add:
 
-When a keiyaku is active, two files are maintained in your repo:
-- `KEIYAKU.md`: The immutable "Constitution" of the task.
-- `KEIYAKU_TRACE.md`: The history of every round, feedback, and result.
+- `.keiyaku/draft/`
+- `.keiyaku/response/`
 
-Project-level law lives in:
-- `.keiyaku/base-rules.md`: Global rules inherited by every keiyaku.
-- `ask` also injects `.keiyaku/base-rules.md` as **reference rules context** (it may be unrelated to some asks).
+to `.gitignore`.
+
+## Key Environment Variables
+
+Server / transport:
+
+- `KEIYAKU_MCP_TRANSPORT`: `stdio` (default) or `streamable-http`
+- `KEIYAKU_MCP_HTTP_HOST`: default `127.0.0.1`
+- `KEIYAKU_MCP_HTTP_PORT`: default `3000`
+
+Preset / naming:
+
+- `KEIYAKU_TERM_PRESET`: only `default` is supported
+- `KEIYAKU_SUBAGENT_NAME_OVERRIDE`: overrides the default subagent display name
+
+Subagent execution:
+
+- `KEIYAKU_DISABLE_SUBAGENT_SPAWN`: when `1`, blocks Keiyaku MCP server startup
+- `KEIYAKU_FAKE_SUBAGENT`: `0` | `1` | `abort-wait` (stub subagent execution)
+- `KEIYAKU_AGENT_[A|B|C]_PROVIDER`: `codex` | `gemini` | `opencode`
+- `KEIYAKU_AGENT_[A|B|C]_MODEL`: optional model override for that profile
+- `KEIYAKU_AGENT_[A|B|C]_REASONING_EFFORT`: `low` | `medium` | `high` (codex only)
+- `KEIYAKU_AGENT_[A|B|C]_COMMAND`: program name override (single token)
+
+Workflow:
+
+- `KEIYAKU_INCREMENTAL_DIFF_MODE`: `targeted` (default) | `stat` | `unified`
+- `KEIYAKU_CLOSE_OATH`: overrides the required petition oath template
+
+Print the full env template with defaults:
+
+```bash
+keiyaku dump-env
+```
 
-*Note: These files are automatically cleaned up (or committed) when you `present` (or preset equivalent) the keiyaku.*
+## License
 
----
-"Keep your branches clean and your minions in line." — Mischief preset
+MIT