@astrosheep/keiyaku 4.0.1 → 4.0.2

package/README.md

@@ -1,9 +1,141 @@
 # Keiyaku
 
-Keiyaku is 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
+
+```bash
+npm install -g @astrosheep/keiyaku
+```
+
+Node ≥ 22.19. Product law lives in [`docs/`](docs/README.md).

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

@@ -1,6 +1,6 @@
 {
   "name": "keiyaku",
-  "version": "0.1.0+codex.20260813114301",
+  "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,6 +1,6 @@
 {
   "name": "keiyaku",
-  "version": "0.1.0+codex.20260813114301",
+  "version": "0.1.0+codex.20260815181541",
   "description": "Use the Keiyaku contract, task, and Akuma CLI.",
   "author": {
     "name": "Keiyaku"

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

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

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

@@ -31,9 +31,9 @@ keiyaku -C <repo> review [<contract>|@<contract>] --satisfied
 ```
 
 ```bash
-keiyaku -C <cwd> call <akuma> [--contract <kei/...>] [--alias @name] [--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

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

@@ -5,49 +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 <cwd> call <akuma> [--contract <kei/...>] [--alias @name] [--wait [--timeout <duration>] | -d | --detach] [--json] -
-keiyaku -C <repo> wait <aku/...> [--timeout <duration>]
-keiyaku -C <repo> tell <aku/...> -
-keiyaku -C <repo> tell <aku/...> --interrupt -
-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. Its execution cwd is exactly `-C` (or the process cwd
-when omitted). Use `--repo <path>` only with a Contract or Dispatch reader that
-must use a different Git repository. 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.
-`tell --interrupt` puts down the current Body synchronously, then records the
-Tell for its successor. `kill` stops the current Body while preserving the
-Akuma's Heart, session, history, pending Tells, and Body Requests; a later Tell
-wakes the same Akuma.
+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

@@ -5,90 +5,130 @@ description: Author and bind one Keiyaku delivery Contract. Use when deciding wh
 
 # Keiyaku Bind
 
-Use bind when the work is a delivery decision rather than an investigation.
-The objective and delivery boundary should be clear, the expected write surface
-should be truthful, and every criterion should be decidable without inventing
-taste at review time. Investigate first when a plausible unresolved fact could
-change the objective, governing design, criteria, or delivery boundary.
-
-## Author The Terms
-
-Write for the implementer and reviewer. Include facts they cannot safely
-recover locally: the owner, boundary, data-flow direction, commit point, single
-authority, and forbidden parallel shapes. Leave ordinary helper names and
-equivalent local control flow to the implementation.
-
-A design statement earns its place when a test-green candidate could violate
-it. A criterion names one observable condition that can accept or reject the
-candidate. Keep the Region truthful and no broader than the intended write
-surface.
-
-Start from this complete shape:
-
-~~~markdown
-# <delivery name>
+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
-<established facts that frame the decision>
+<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 delivery outcome>
+<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
-<ownership, boundaries, and constraints a test-green candidate could violate>
+<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
 ```
-<expected write surface>
+<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
-### <criterion title>
-<one decidable acceptance condition>
+### <one observable condition>
+<One accept/reject observation with its method: run this, observe that.
+Decidable without consulting you.>
 
 ## Verification
-```bash
-<optional executable check>
+```bash timeout=<honest bound>
+<commands runnable exactly as written>
 ```
-~~~
+KEIYAKU
+~~~~
 
-Use an H1 title and the H2 sections shown above. `Verification` is optional.
-When a declaration needs a limit, put an explicit duration such as
-`bash timeout=5m` in its fence info string; omit it for an unbounded declaration.
-Keep extra rationale and investigation logs out of the Contract.
+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.
 
-## Bind
-
-Inspect the actual command surface before choosing inputs:
-
-```bash
-keiyaku -C <repo> bind --help
-```
-
-Bind the complete document through stdin. A Task is optional: a Contract is
-complete delivery authority on its own, and ordinary bounded delivery does not
-require creating planning state first. Use `--task` only when an existing Task
-already carries real scheduling, dependency, or coordination value and this
-Contract is specifically its delivery:
+For a saved document:
 
 ```bash
 keiyaku -C <repo> bind - < CONTRACT.md
 keiyaku -C <repo> bind --task <task/...> - < CONTRACT.md
 ```
 
-Do not create a Task merely to make `bind --task` available or to mirror the
-Contract objective. That adds a second lifecycle with no planning reader.
+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).
 
-Use `bind --help` as the installed command authority for optional target,
-workspace, prerequisite, gate-set, actor, and JSON inputs. Do not guess flags
-from an older installation or repository checkout.
+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. A post-admission lag does not erase the admitted
-Contract; read the typed facts, effects, and lag before acting.
+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`.