@astrosheep/keiyaku 4.0.0 → 4.0.2

package/README.md

@@ -1,16 +1,141 @@
-# Keiyaku v4
+# Keiyaku
 
-Keiyaku v4 is a clean implementation of an agent-facing contract workflow.
+**Keiyaku is not designed for you, but for your frontier model.**
 
-The first milestone is intentionally narrow: a Git-backed facts kernel with
-per-contract append-only journals, Git-tree evidence, atomic path-set CAS,
-and tests that prove clone and garbage-collection durability.
+**Current world:** frontier models are formidable — and expensive. Cheap
+models work fine, but they drift, and they always report success. And
+human attention is the scarcest of the three.
 
-No v3 runtime code is wired into this repository.
+So Keiyaku gives each of the three the right job.
+
+**The frontier gets an exoskeleton, not a cage.** It breaks goals apart,
+authors explicit contracts, commands a fleet in parallel. Its limited
+context goes to decision-grade signal — the state of every contract,
+never individual workers. A worker can drift, stall, or lie; a contract
+cannot.
+
+**The workers get contracts, not trust.** Terms in bytes before the
+first edit; every delivery judged mechanically against the diff.
+Whatever drifted or lied never reaches the board.
+
+**You step back.** Delegate when possible — by default, everything goes
+to the frontier; the verbs are its to type. Steer when necessary — the
+top was never handed over. The wheel stays yours.
+
+---
+
+## What a contract looks like
+
+```markdown
+# Ship typed Task query
+
+## Context
+Task reads scan documents ad hoc.
+
+## Objective
+One typed query surface over the whole board.
+
+## Design
+A single evaluator over persisted facts.
+
+## Region
+```
+src/task/**
+tests/task-*.test.ts
+```
+
+## Criteria
+### Query is typed
+The CLI parses a predicate; the evaluator never sees a raw shell string.
+
+### Reads stay Task-owned
+Query reads only Task facts. No Contract. No Akuma.
+
+## Verification
+```bash
+npm test
+```
+```
+
+## What a deal looks like
+
+```bash
+keiyaku bind - < keiyaku.md     # terms written; an isolated worktree appears
+keiyaku call worker -           # a worker goes in
+keiyaku deliver                 # tendered; Verification runs; gates judge
+keiyaku review --satisfied      # attested; main moves with a commit receipt
+```
+
+## What the journal records
+
+One real deal, pulled from this repo's own journal:
+
+```text
+$ keiyaku audit kei/add-acp-provider-and-grok-build-profile
+
+accepted audit kei/add-acp-provider-and-grok-build-profile head=0508f7eb9cb738bcab06060b13ff1a96d36e3754
+report {"reworks":1,"reviews":2,"timeline":[
+  {"kind":"bind","at":"2026-08-14T08:18:36.224Z"},
+  {"kind":"deliver","at":"2026-08-14T13:02:08.339Z"},
+  {"kind":"attestation","gate":"reviewed","verdict":"unsatisfied","summary":
+   "Implementation review found no blocking code issues; authenticated official
+    Grok smoke remains unavailable because this host has no grok binary."},
+  {"kind":"attestation","gate":"verified","verdict":"satisfied","summary":"[1 bash exit 0] …"}]}
+```
+
+The review said no — with a reason, in bytes, on the journal. The deal
+did not land until the gates had current evidence.
+
+## The board
+
+`keiyaku status` is the one screen. A slice of this repository, right now:
+
+```text
+kanshi ─ 7 keiyaku · 18 akuma · 286 task ─ /Users/astrosheep/Developer/keiyaku-v4 main 9cfdca6017633e51827b9b2eba3c76a7fe08e05f
+
+keiyaku 7
+⧗ kei/add-acp-provider-and-grok-build-profile pending-delivery
+  worktree · integration c5cafef6 · -> refs/heads/main
+  ! reviewed
+⧗ kei/align-task-cli-truth-promises waiting
+  ? reviewed
+  held by task/align-task-cli-truth-promises-for-ready-compose
+
+akuma 18
+● aku/expert-akuma/a7aafc9e running
+  alias @process-custody-lead
+  keiyaku kei/make-process-custody-capability-honest (active)
+○ aku/design-akuma/cc53ef08 asleep
+  alias @timeline-design
+? aku/grok/95d90b7d stranded
+  alias @acp-provider-impl
+
+task 8 · 5 ready · 2 held
+● task/align-task-cli-truth-promises-for-ready-compose in_progress
+  Align Task CLI truth promises for ready compose and world absence
+  P0 · keiyaku kei/align-task-cli-truth-promises (active)
+```
+
+Marks accelerate scanning; the words carry the state.
+
+## The worker
+
+```markdown
+---
+provider: claude-agent-sdk
+model: claude-sonnet-4-5
+access: write
+description: Repository implementation agent
+---
+Make scoped changes and run relevant tests.
+```
+
+One Markdown file, one worker. `keiyaku call worker` summons it.
 
 ## Install
 
-```sh
+```bash
 npm install -g @astrosheep/keiyaku
-keiyaku --help
 ```
+
+Node ≥ 22.19. Product law lives in [`docs/`](docs/README.md).

package/build/integrations/marketplace/plugins/keiyaku/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "keiyaku",
-  "version": "0.1.0",
-  "description": "Use the Keiyaku v4 contract, task, and Akuma CLI.",
+  "version": "0.1.0+codex.20260815181541",
+  "description": "Use the Keiyaku contract, task, and Akuma CLI.",
   "author": { "name": "Keiyaku" },
   "skills": "./skills/"
 }

package/build/integrations/marketplace/plugins/keiyaku/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "keiyaku",
-  "version": "0.1.0",
-  "description": "Use the Keiyaku v4 contract, task, and Akuma CLI.",
+  "version": "0.1.0+codex.20260815181541",
+  "description": "Use the Keiyaku contract, task, and Akuma CLI.",
   "author": {
     "name": "Keiyaku"
   },
@@ -9,10 +9,10 @@
   "interface": {
     "displayName": "Keiyaku",
     "shortDescription": "Use Keiyaku in Codex.",
-    "longDescription": "Keiyaku adds the v4 agent-facing workflow CLI.",
+    "longDescription": "Keiyaku adds the agent-facing workflow CLI.",
     "developerName": "Keiyaku",
     "category": "Productivity",
     "capabilities": [],
-    "defaultPrompt": "Use Keiyaku v4 to coordinate this work."
+    "defaultPrompt": "Use Keiyaku to coordinate this work."
   }
 }

package/build/integrations/marketplace/plugins/keiyaku/opencode.js

@@ -1,11 +1,11 @@
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 
-const skills = ["keiyaku", "keiyaku-task", "keiyaku-workflow", "keiyaku-akuma"]
+const skills = ["keiyaku", "keiyaku-task", "keiyaku-bind", "keiyaku-workflow", "keiyaku-akuma"]
   .map((name) => fileURLToPath(new URL(`./skills/${name}/SKILL.md`, import.meta.url)));
 
 export default {
-  id: "keiyaku-v4",
+  id: "keiyaku",
   server: async () => ({
     config: async (config) => {
       const instructions = config.instructions ?? (config.instructions = []);

package/build/integrations/marketplace/plugins/keiyaku/package.json

@@ -1,6 +1,6 @@
 {
-  "name": "keiyaku-v4-harness",
-  "version": "0.1.0",
+  "name": "keiyaku-harness",
+  "version": "0.1.0+codex.20260815181541",
   "type": "module",
   "main": "./opencode.js",
   "keywords": ["pi-package"],

package/build/integrations/marketplace/plugins/keiyaku/skills/keiyaku/SKILL.md

@@ -11,24 +11,32 @@ read `<command> --help` before using flags.
 ## Model
 
 - `task` is planning; see `keiyaku-task`.
-- A Contract is delivery authority; see `keiyaku-workflow`.
+- A Contract is delivery authority; see `keiyaku-bind` to author and bind one,
+  then `keiyaku-workflow` for the remaining lifecycle.
 - An Akuma is a callable worker; see `keiyaku-akuma`.
 
+Settings owns named gate sets. Omitting `--gates` selects `gates.default`, or
+freezes an empty gate list when that entry is absent. `--gates <name>` selects
+one configured set; it does not add a literal gate word.
+
 ## Quick Start
 
 ```bash
 keiyaku -C <repo> task add "title"
 keiyaku -C <repo> task start <task-id>
-keiyaku -C <repo> bind -
+keiyaku -C <repo> bind [--task <task-id>] -
 keiyaku -C <repo> status
 keiyaku -C <repo> deliver [<contract>|@<contract>]
 keiyaku -C <repo> review [<contract>|@<contract>] --satisfied
 ```
 
 ```bash
-keiyaku -C <repo> call <akuma> [--contract <kei/...>] [--alias @name] [--workdir <path>] [--wait [--timeout <duration>] | -d | --detach] [--json] -
-keiyaku -C <repo> wait <aku/...>
-keiyaku -C <repo> tell <aku/...> -
+keiyaku -C <cwd> call <akuma-name> [--contract <kei/...>] [--alias @name] [--wait <duration> | -d | --detach] [--json] (<prompt> | -)
+keiyaku -C <repo> wait <akuma-selector>... [--any | --all]
+keiyaku -C <repo> tell <aku/...|@alias> (<prompt> | -)
 ```
 
+`-C` is the invocation and Akuma execution cwd. Add `--repo <path>` only when
+a Contract or Dispatch reader must use a different Git repository.
+
 Use text by default; add `--json` when a script needs structured output.

package/build/integrations/marketplace/plugins/keiyaku/skills/keiyaku-akuma/SKILL.md

@@ -5,46 +5,105 @@ description: Use when delegating work to, supervising, steering, inspecting, for
 
 # Keiyaku Akuma
 
-An Akuma is a durable callable worker projection. Its complete id is
-`aku/<archetype>/<hex8>`; keep that id for recovery.
+An Akuma is a durable callable worker. Its complete identity is
+`aku/<archetype>/<hex8>` — keep it; it is how you address the same worker
+later. An Alias is a movable world-local selector usable wherever a direct id
+is accepted; the identity underneath never changes.
 
-## Choose A Verb
+## Start One
 
 ```bash
-keiyaku -C <repo> call <akuma> [--contract <kei/...>] [--alias @name] [--workdir <path>] [--wait [--timeout <duration>] | -d | --detach] [--json] -
-keiyaku -C <repo> wait <aku/...> [--timeout <duration>]
-keiyaku -C <repo> tell <aku/...> -
-keiyaku -C <repo> interrupt <aku/...> -
-keiyaku -C <repo> history <aku/...>
-keiyaku -C <repo> fork <aku/...> --at <historyId>
-keiyaku -C <repo> kill <aku/...>
+keiyaku -C <cwd> call <akuma-name> [--alias @name] [--wait <duration> | -d | --detach] [--json] (<prompt> | -)
 ```
 
-`call` starts from an Archetype, requires a final stdin body, and waits up to
-five minutes by default. Use `-d` or `--detach` to return after birth. `tell` continues
-the same projection, including after it has answered. `fork` starts a child
-from one exact retained answered-turn coordinate and leaves the source alone.
-`interrupt` puts down the current body synchronously, then records the tell;
-it is not terminal kill. `kill` records death and returns typed physical
-evidence.
+Give the worker's initial prompt as one argument (quote it when it contains
+spaces), or use final `-` to read it from stdin. These forms are mutually
+exclusive. Decide up front whether you will stay:
 
-## Observe
+- The default observes up to five minutes and writes the complete answer when
+  it arrives inside that window. `--wait <duration>` replaces that window.
+- `-d` / `--detach` returns right after birth with the AkuId. Use it when the
+  work outlives your attention; come back with `wait`.
+
+`--alias @name` assigns that world-local selector to the born Akuma. If the
+Alias already points elsewhere, it moves to the born Akuma. The worker's
+execution cwd is exactly `-C <path>`, or your own cwd when `-C` is omitted.
+
+## Archetypes
+
+An Archetype is a Markdown file at `~/.keiyaku/akuma/<name>.md`. Its
+frontmatter selects the provider and may declare `model`, `effort`,
+`readonly`, `network`, and `description`; the body is an optional system
+prompt, and an empty body keeps the harness default. Write a new one when no
+existing file grants the permissions and stance the work needs; a worker never
+outgrows its Archetype mid-life.
+
+## Watch
+
+```bash
+keiyaku status                            # deep fleet observation
+keiyaku status <aku/...|@alias>           # one worker's snapshot
+keiyaku ls aku/                           # shallow catalog; also aku/<archetype>/ and "aku/*/*"
+keiyaku wait <selector>... [--any | --all] [--timeout <duration>] [--json]
+```
+
+`wait` accepts complete ids, aliases, and Akuma globs, resolved once into a
+stable deduplicated set. One member needs no mode; two or more require exactly
+one of `--any` or `--all`. A timeout returns the current real snapshot — never
+a fabricated timeout state — and `--any` leaves the unfinished members
+running.
+
+## Steer
 
 ```bash
-keiyaku -C <repo> status
-keiyaku -C <repo> status <aku/...>
-keiyaku -C <repo> wait <aku/...> --timeout 5m
-keiyaku -C <repo> history <aku/...> --before <index>
-keiyaku -C <repo> history <aku/...> --since <index>
-keiyaku -C <repo> history <aku/...> --last
+keiyaku tell <aku/...|@alias> (<prompt> | -)
+keiyaku tell <aku/...|@alias> --interrupt (<prompt> | -)
 ```
 
-Bare `status` shows the compact fleet. Exact `status <aku/...>` and `wait`
-share the public status carrier; a wait timeout returns the current snapshot,
-not a fabricated timeout state. History cursors are persistent activity
-sequences and `--before`/`--since` are exclusive. `--last` writes only the
-complete answer bytes. Use `--json` when a script needs the typed values.
+Give `tell` one prompt argument (quote it when it contains spaces) or final `-`
+for stdin, never both.
+`tell` continues the same worker: it steers a live Body in place, or — when
+none is running, including after an answer — records the message durably and
+wakes a successor. `tell --interrupt` puts down the current Body synchronously
+first, then hands the message to the successor; it is not a kill. Choose plain
+`tell` when the current attempt should finish with your guidance folded in;
+choose `--interrupt` when the current attempt itself is the problem.
+
+## Take The Answer
+
+```bash
+keiyaku history <aku/...|@alias> --last
+keiyaku history <aku/...|@alias> [--before <N> | --since <N>] [--limit <N>]
+```
+
+`--last` writes exactly the complete answer bytes of the latest answered turn
+and says so plainly when no answer exists yet. Snapshot rows elsewhere may
+clip long text; the terminal answer from `call`/`wait` and the bytes from
+`--last` are never clipped — when you need the full result, take it from one
+of those. Cursor reads page the activity timeline; `--before` and `--since`
+are exclusive sequence cursors. `--limit` defaults to 50 and accepts at most
+5000 semantic rows.
+
+## Stop
+
+```bash
+keiyaku kill <selector>...
+```
+
+`kill` accepts the same id, alias, and glob selectors as `wait`. It stops the
+current Body and records that it did; everything else survives — Heart,
+session, history, pending Tells, and Body Requests — so a later `tell` wakes
+the same worker where it left off. Killing pauses a worker; nothing is
+deleted.
+
+## Branch
+
+```bash
+keiyaku fork <aku/...|@alias> --at <historyId> [--alias @name]
+```
 
-Read the exact command help for duration syntax and provider-specific Archetype
-configuration. Do not use old `follow`, plural wait, `--after`, or `--at`
-index forms; they are not root commands.
+`fork` starts a child from one exact retained answered-turn coordinate and
+leaves the source untouched. It is a provider capability, not a guarantee:
+when the provider cannot fork from that turn, the command refuses rather than
+fabricating a fresh start. Take the `historyId` from `history` output; it must
+name an answered turn.

package/build/integrations/marketplace/plugins/keiyaku/skills/keiyaku-bind/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: keiyaku-bind
+description: Author and bind one Keiyaku delivery Contract. Use when deciding whether a bounded delivery is ready for Contract terms, writing those terms for an implementer, binding an existing Task with `bind --task`, choosing bind inputs, or interpreting the bind receipt and worktree handoff.
+---
+
+# Keiyaku Bind
+
+A Contract records a decision that already exists; writing terms does not
+produce one. You supply **all high-level design and public-surface facts this
+Keiyaku creates or changes**, and **all** pseudocode where ordering matters.
+The worker is a cheap executor: every choice you leave open, it resolves —
+possibly the way you like least, discovered at review and billed at review
+prices.
+
+## Before You Bind
+
+Bind is the last step of an investigation, never the first step of an idea.
+
+- Design the delivery to the depth you could implement it yourself, against
+  the code as it is — not as you remember it. An unknown surfacing while
+  you design is the next investigation, not a detail for the worker.
+- Walk the implementation path once, end to end. A step you cannot walk is
+  an unresolved fact.
+- Observe active Contracts whose Regions intersect yours. Region overlap is a
+  prompt signal only; it does not by itself imply a logical conflict. The
+  caller decides autonomously whether to proceed in parallel or serialize.
+- A decision settled elsewhere binds only its explicit words; converting it
+  into concrete shape is your job, and a question it left open goes back to
+  its decider, never to the worker.
+- If the delivery must land documentation, you can draft its exact sentence
+  now. Cannot draft means unresolved design — "the worker will sort out the
+  docs" is a design gap in disguise.
+
+Split complex work wherever independently acceptable delivery boundaries
+exist. When a complex Keiyaku cannot be split without breaking one acceptance
+boundary, bind one Contract and plan its fulfillment as explicit arcs. Treat
+each arc as a chapter as in a work of literature, not as a task sequence.
+Commission one current chapter at a time; never hand the whole undifferentiated
+Contract to one Deliverer and trust it to finish everything in one pass.
+Continue with `keiyaku-workflow` for the arc document and command.
+
+Two tests close the gate:
+
+- **Substitution.** Two workers who never met each deliver test-green from
+  your terms. If any external reader could tell the deliveries apart, that
+  fact is undecided — decide it and write it.
+- **Rework.** For each blank: "if the worker picks what I like least, do I
+  demand rework?" Yes — write it. No — write nothing.
+
+Public — anything visible outside the diff — is always yours to pin.
+Private — helper names, decomposition, control flow — is the worker's;
+its freedom comes from your genuine indifference, not from omission.
+
+## Author And Bind
+
+`keiyaku -C <repo> bind --help` lists the options; only the heredoc is
+stdin. Each section states what it must contain:
+
+~~~~bash
+keiyaku -C <repo> bind - <<'KEIYAKU'
+# <Delivery name — one decision, active voice; source of the kei/... identity>
+
+## Context
+<Premises: coordinates of the governing decision or document, and facts a
+reader would otherwise re-derive wrongly. Never narrative. If Objective and
+Design read the same without a sentence here, delete it.>
+
+## Objective
+<One observable end-state, judged done/not-done without reading Design.
+If "and" joins independently acceptable outcomes, bind two Contracts. A
+single outcome may still require several arcs during fulfillment.>
+
+## Design
+<The closed decisions. A statement belongs here exactly when a test-green
+candidate could still violate it: which module owns the change; the exact
+public surface — each type with its fields, each verb with its success,
+refusal, and error arms and their reason words; the persisted format; which
+way data flows and where it commits or refuses; which parallel shapes are
+forbidden. Helper names and equivalent control flow do not belong here —
+they are the worker's.>
+
+```text
+<pseudocode — only where ordering matters>
+```
+
+## Region
+```
+<intended write patterns — planning evidence for overlap detection, never
+ownership or the exact diff. Narrow enough that overlap is a real signal;
+directory patterns end with `/`.>
+```
+
+## Criteria
+### <one observable condition>
+<One accept/reject observation with its method: run this, observe that.
+Decidable without consulting you.>
+
+## Verification
+```bash timeout=<honest bound>
+<commands runnable exactly as written>
+```
+KEIYAKU
+~~~~
+
+Each declaration may set an individual timeout in its fence info string, using
+an explicit duration unit such as `bash timeout=5m`. Omit it for an unbounded
+declaration; there is no Verification-wide timeout.
+
+For a saved document:
+
+```bash
+keiyaku -C <repo> bind - < CONTRACT.md
+keiyaku -C <repo> bind --task <task/...> - < CONTRACT.md
+```
+
+Use `--task` only for an existing Task with scheduling or dependency value;
+do not create one just to mirror the Contract.
+
+## Authority Order
+
+> Settled upstream decisions and their documentation → this Contract → worker
+> brief (zero authority) → review evidence (witnessed fact, never law).
+
+Gaps flow upstream, never down: a design gap found by a worker or reviewer
+returns to you, never filled silently downstream.
+
+## Read The Receipt
+
+Treat the receipt as the handoff. Keep the complete `kei/...` identity, work
+in the reported managed worktree when one was created, and retain the target
+and gate facts it reports. A waiting receipt means prerequisites remain; it
+is not a second authoring workflow.
+
+Continue the delivery with `keiyaku-workflow`.

package/build/integrations/marketplace/plugins/keiyaku/skills/keiyaku-bind/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Keiyaku Bind"
+  short_description: "Author and bind a delivery Contract."
+  default_prompt: "Use $keiyaku-bind to author and bind this delivery."

package/build/integrations/marketplace/plugins/keiyaku/skills/keiyaku-task/SKILL.md

@@ -7,7 +7,13 @@ description: "Use when planning work in a Keiyaku v4 repo: add tasks, wire depen
 
 Task is a directory-context planning product. It is separate from Contract
 delivery and Akuma execution. A task records intent; `start` does not execute
-it and no task command binds a Contract.
+it and no task command binds a Contract. Task use is optional: create one only
+when planning needs a durable reader such as priority, dependencies, readiness,
+or coordination across deliveries. Do not create one as boilerplate before
+binding a Contract. Contract `bind --task <task/...>` optionally associates an
+existing Task through Settlement-owned TaskHolder: claim settles the current
+held Task to `done`, and abandon releases it. Task Markdown carries no Contract
+field.
 
 ## Lifecycle
 
@@ -55,8 +61,37 @@ keiyaku task update <task-id> --title <text>
 keiyaku task namespace [<namespace>]
 ```
 
-Use `--json` on any command when a script must inspect the typed result. Use
-`task compose -` for one atomic tree/graph edit; read its command help for the
-composition grammar. Relations are explicit facts: `needs` orders work,
-`parent` groups it, `supersedes` navigates replacement, and `relates` does not
-affect readiness.
+Use `--json` on any command when a script must inspect the typed result.
+Relations are explicit facts: `needs` orders work, `parent` groups it,
+`supersedes` navigates replacement, and `relates` does not affect readiness.
+
+## Batch Create Or Modify
+
+Use `task compose -` to create and modify multiple Tasks in one planning
+document:
+
+```bash
+keiyaku task compose - <<'EOF'
+ns=feature
++ Parent pri=0
+Parent body.
+  + Child needs=@task/existing
+@task/existing pri=1 relates+=@task/other
+Replacement body.
+EOF
+```
+
+- Optional first line `ns=<segment/...>` selects the allocation namespace;
+  `ns=` selects root.
+- `+ <title>` creates a Task. `@task/<id>` modifies an existing Task.
+- Two spaces of indentation assign the preceding shallower Task as `parent`.
+- Inline assignments are `pri=`, `parent=`, `needs=`, `supersedes=`, and
+  `relates=`. Relation values are comma-separated `@task/...` references.
+- `=` replaces or clears a field. `+=` appends only to `needs`, `supersedes`,
+  or `relates`.
+- Prose after a node replaces its body; bare `body=` clears it. Prefix body
+  lines beginning with `+ `, `@task/`, or `\` with one `\`.
+
+Compose does not change Task lifecycle state. Each changed Task is admitted
+independently; an incomplete result returns a canonical draft for the remaining
+batch.