@astrosheep/keiyaku 4.5.27 → 4.5.28

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/build/integrations/marketplace/plugins/keiyaku/.claude-plugin/plugin.json +1 -1
  2. package/build/integrations/marketplace/plugins/keiyaku/.codex-plugin/plugin.json +1 -1
  3. package/build/integrations/marketplace/plugins/keiyaku/package.json +1 -1
  4. package/build/integrations/marketplace/plugins/keiyaku/skills/keiyaku/SKILL.md +3 -3
  5. package/build/integrations/marketplace/plugins/keiyaku/skills/keiyaku-akuma/SKILL.md +82 -163
  6. package/build/integrations/marketplace/plugins/keiyaku/skills/keiyaku-bind/SKILL.md +153 -78
  7. package/build/integrations/marketplace/plugins/keiyaku/skills/keiyaku-task/SKILL.md +68 -64
  8. package/build/integrations/marketplace/plugins/keiyaku/skills/keiyaku-workflow/SKILL.md +115 -146
  9. package/build/src/akuma/akuma-handle.d.ts +1 -0
  10. package/build/src/akuma/akuma-handle.js +4 -1
  11. package/build/src/akuma/akuma-observe.d.ts +6 -0
  12. package/build/src/akuma/akuma-observe.js +3 -1
  13. package/build/src/akuma/akuma.d.ts +1 -0
  14. package/build/src/akuma/akuma.js +1 -0
  15. package/build/src/akuma/fleet-execution.d.ts +7 -1
  16. package/build/src/akuma/fleet-execution.js +12 -11
  17. package/build/src/akuma/fleet-observation.d.ts +3 -0
  18. package/build/src/akuma/identity.js +11 -9
  19. package/build/src/alias/index.js +3 -3
  20. package/build/src/cli/commands/akuma-invoke.js +13 -4
  21. package/build/src/cli/commands/akuma.js +9 -15
  22. package/build/src/cli/commands/contract-help.d.ts +1 -0
  23. package/build/src/cli/commands/contract-help.js +1 -0
  24. package/build/src/cli/invoke.js +1 -1
  25. package/build/src/cli/render/akuma-activity.js +6 -1
  26. package/build/src/cli/render/akuma.d.ts +9 -0
  27. package/build/src/cli/render/akuma.js +48 -8
  28. package/build/src/identity/normalize.d.ts +3 -0
  29. package/build/src/identity/normalize.js +10 -0
  30. package/build/src/identity/selector.d.ts +1 -0
  31. package/build/src/identity/selector.js +15 -4
  32. package/build/src/library/address.js +2 -2
  33. package/build/src/library/akuma-creation.d.ts +1 -1
  34. package/build/src/library/akuma-creation.js +10 -52
  35. package/build/src/library/composition.d.ts +2 -1
  36. package/build/src/library/fleet.d.ts +2 -1
  37. package/build/src/library/fleet.js +7 -3
  38. package/build/src/library/keiyaku.d.ts +2 -1
  39. package/build/src/protocol/completion.js +9 -2
  40. package/package.json +1 -1
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "keiyaku",
3
- "version": "0.1.2",
3
+ "version": "4.5.28",
4
4
  "description": "Use the Keiyaku contract, task, and Akuma CLI.",
5
5
  "author": {
6
6
  "name": "Keiyaku"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "keiyaku",
3
- "version": "0.1.2+codex.20260905023250",
3
+ "version": "4.5.28+codex.20260905023250",
4
4
  "description": "Use the Keiyaku contract, task, and Akuma CLI.",
5
5
  "author": {
6
6
  "name": "Keiyaku"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "keiyaku-harness",
3
- "version": "0.1.2",
3
+ "version": "4.5.28",
4
4
  "type": "module",
5
5
  "main": "./opencode.js",
6
6
  "keywords": [
@@ -36,7 +36,7 @@ keiyaku -C <repo> review [<contract>|@<contract>] --satisfied
36
36
  ```
37
37
 
38
38
  ```bash
39
- keiyaku -C <cwd> call <akuma-name> [--contract <kei/...>] [--workdir <path>] [--alias @name] [--allowed <product.action>]... [--schema <file>] [--wait <duration> | -d | --detach] (<prompt> | -)
39
+ keiyaku -C <cwd> call <akuma-name> [--contract <kei/...>] [--workdir <path>] [--alias <name>] [--allowed <product.action>]... [--schema <file>] [--wait <duration>] (<prompt> | -)
40
40
  keiyaku -C <repo> wait <akuma-selector>... [--any | --all]
41
41
  keiyaku -C <repo> tell <aku/...|@alias> (<prompt> | -)
42
42
  ```
@@ -44,8 +44,8 @@ keiyaku -C <repo> tell <aku/...|@alias> (<prompt> | -)
44
44
  `-C` selects the invocation cwd and therefore the World. `--repo <path>` only
45
45
  selects the Contract repository; it never retargets that World. `call
46
46
  --workdir <path>` selects execution cwd (relative to the effective invocation
47
- cwd). Without it, a Contract call uses its appointed worktree and an
48
- unassociated call uses the invocation cwd.
47
+ cwd). Without it, the call uses the invocation cwd; `--contract` associates a
48
+ Contract without selecting an execution directory.
49
49
 
50
50
  Repeated `--allowed` values add actions to the selected Akuma's defaults. A
51
51
  nested call can use only actions permitted by its direct parent Soul.
@@ -1,206 +1,125 @@
1
1
  ---
2
2
  name: keiyaku-akuma
3
3
  description: >-
4
- Calling an Akuma: delegating scouting, mechanical chores, or fanned-out
5
- parallel work instead of doing it inline.
4
+ Calling an Akuma: delegate work to a new or existing worker, then observe,
5
+ guide, and collect the result.
6
6
  ---
7
7
 
8
8
  # Keiyaku Akuma
9
9
 
10
- An Akuma is a durable callable worker. Its complete identity is
11
- `aku/<akuma>/<hex8>` — keep it; it is how you address the same worker
12
- later. An Alias is a movable world-local selector usable wherever a direct id
13
- is accepted; the identity underneath never changes.
10
+ Use Akumas to delegate work to another worker. `call` creates a new Akuma;
11
+ `tell` gives an existing Akuma another prompt. Keep the complete AkuId, such
12
+ as `aku/worker/1234abcd`, when you need to address the same worker later. An
13
+ alias such as `@reviewer` is a shorter, world-local name.
14
14
 
15
- ## Automated Orchestration
16
-
17
- For task-specific JavaScript orchestration with the public Akuma API, read
18
- [Automation With The Akuma API](references/automation.md). It covers structured
19
- answers, semantic ranking and tournaments, adversarial verification, learning
20
- from corrections, bounded parallelism, and failure/reconnection handling.
21
- Use it when the flagship should write and run a program for this task rather
22
- than coordinate every delegation in conversation. The examples are adaptable
23
- techniques, not a fixed workflow or a built-in workflow runtime.
24
-
25
- ## Start One
15
+ ## Call a new Akuma
26
16
 
27
17
  ```bash
28
- keiyaku -C <cwd> call <akuma-name> [--workdir <path>] [--alias @name] [--allowed <product.action>]... [--schema <file>] [--wait <duration> | -d | --detach] (<prompt> | -)
18
+ keiyaku -C <cwd> call <akuma-name> [--workdir <path>] [--alias <name>] [--allowed <product.action>]... [--schema <file>] [--wait <duration>] (<prompt> | -)
29
19
  ```
30
20
 
31
- Give the worker's initial prompt as one argument (quote it when it contains
32
- spaces), or use final `-` to read it from stdin. These forms are mutually
33
- exclusive. Decide up front whether you will stay:
34
-
35
- - The default observes up to five minutes and writes the complete answer when
36
- it arrives inside that window. `--wait <duration>` replaces that window.
37
- - `-d` / `--detach` returns right after birth with the AkuId. Use it when the
38
- work outlives your attention; come back with `wait`.
39
-
40
- `--alias @name` assigns that world-local selector to the born Akuma. If the
41
- Alias already points elsewhere, it moves to the born Akuma. `-C` selects the
42
- invocation World; `--workdir <path>` selects the worker execution cwd relative
43
- to that invocation directory. Without `--workdir`, an unassociated call uses
44
- the invocation cwd, while a `--contract` call uses its appointed worktree.
45
-
46
- Repeated `--allowed` values add actions to the selected Akuma's defaults; they
47
- never narrow them. An omitted Archetype permits `akuma.*`, every `task.*`,
48
- `contract.audit`, and `contract.deliver`; `contract.review` requires an explicit
49
- Archetype or call-time grant. An explicit empty default permits none. A nested
50
- call can use only actions permitted by its direct parent Soul. Use `status
51
- <aku/...|@alias>` to inspect the born worker's frozen effective actions.
52
-
53
- ## Answer Schemas
54
-
55
- For a schema-bearing call or tell through the public API, pass the schema
56
- directly — `{ schema: z.object({ claim: z.string() }) }` — importing `z` from
57
- the package root next to `Akuma`. Any Standard Schema v1 value works the same
58
- way, and the explicit `Schema.zod(...)` and `Schema.json(...)` forms remain
59
- available for callers who want them.
60
-
61
- Keep an answer contract inside simple JSON shape vocabulary: objects, arrays,
62
- strings, numbers, booleans, enums, literals, and optional or nullable fields.
63
- Do not attach `.max`, `.min`, `.regex`, `.refine`, `.transform`, or other
64
- constraint methods. The provider must satisfy the contract, and a fragile or
65
- unrepresentable constraint fails the loop after submission; the seam refuses
66
- such a schema at submission and names the offending keyword instead. Enforce
67
- bounds, formats, and cross-field rules in ordinary caller code after the answer
68
- arrives, and treat a full JSON Schema through `Schema.json(...)` as the explicit
69
- waiver a caller signs only when it owns that risk.
70
-
71
- ## Akuma Names
72
-
73
- An Akuma name selects a reusable worker configuration, not an individual worker.
74
- Calling the same name multiple times creates independent workers with distinct
75
- AkuIds. Choose different names for different capabilities, not merely to run
76
- work in parallel.
77
-
78
- Each name fixes its own capability stance — provider, model, permissions —
79
- and a born Akuma keeps those selected defaults for its lifetime. A name may
80
- also ask for full host access, which disables only its provider's native
81
- command sandbox and never grants extra operating-system permissions; it
82
- cannot combine with a readonly restriction or a disabled network. `keiyaku ls
83
- aku/` lists the available names with their providers and descriptions. If none
84
- grants the permissions and stance the work needs, add a new Akuma name;
85
- `keiyaku settings --help` says where Akuma definitions live and what they may
86
- declare.
87
-
88
- ## Commission And Steer
89
-
90
- A call assembles a commission from independent inputs: the selected Akuma fixes
91
- capability stance for the identity's whole life; the `--contract` Dispatch
92
- associates standing terms; allowed actions set what the callee may do, subject
93
- to that Akuma's restrictions and the parent Soul's ceiling; the prompt carries
94
- the question. None of these implies another — association is not a seat, forwarded
95
- actions are not a seat, and no combination mints a role.
96
-
97
- The prompt and every later tell genuinely direct the callee's work: they choose
98
- the subject, scope, depth, risks, and deliverable of the round. They spend
99
- decisions already made and ask questions still open; they never change the
100
- Dispatch, the journal, or what counts as acceptance, and an expectation stated
101
- in a prompt is never evidence for the callee's own findings.
102
-
103
- A commission can be as large as a whole Contract's fulfillment loop: call one
104
- Aku with the Contract association, forward the actions the loop needs —
105
- including nested calls, which stay under this Soul's ceiling — and state the
106
- loop as the question. Steering that delegation afterwards goes to the holder,
107
- not around it.
108
-
109
- When that whole-loop worker must operate in the main repository rather than its
110
- Contract worktree, make that execution choice explicit:
21
+ The prompt is the new Akuma's first prompt. Give it as one argument, or use
22
+ `-` to read stdin, never both. Calls are detached by default: they return the
23
+ new identity after birth without waiting for the first answer. Use explicit
24
+ `--wait <duration>` when this invocation should block while observing that
25
+ initial work. `--wait` only bounds this command; it never stops the Akuma.
111
26
 
112
- ```bash
113
- keiyaku -C <repo> call worker --contract <kei/...> --workdir <repo> --allowed contract.deliver -d "Own this Contract loop."
27
+ Useful options:
28
+
29
+ - `--alias <name>` assigns a reusable world-local `@name` selector; `--alias @name` is also accepted. An existing alias moves to this Akuma.
30
+ - `--contract <kei/...>` associates the Akuma with a Contract; it never selects an execution directory.
31
+ - `--workdir <path>` chooses its execution directory; without it the call uses the invocation cwd.
32
+ - `--allowed <product.action>` adds actions subject to the Akuma's restrictions.
33
+ - `--schema <file>` requests a structured answer described by a JSON Schema.
34
+
35
+ The selected Akuma name is a reusable worker configuration, not an individual.
36
+ Calling it again creates an independent Akuma. Use different names for
37
+ capabilities, not merely for parallelism.
38
+
39
+ ## Public-library core example
40
+
41
+ ```ts
42
+ const akuma = await Akuma.birth({ path, archetype: "worker" });
43
+ const answer = await akuma.tell("Inspect the change");
44
+ console.log(answer);
114
45
  ```
115
46
 
116
- ## Watch
47
+ ## Commission Context
117
48
 
118
- ```bash
119
- keiyaku status # deep fleet observation
120
- keiyaku status <aku/...|@alias> # one worker's snapshot
121
- keiyaku ls aku/ # shallow catalog; also aku/<akuma>/ and "aku/*/*"
122
- keiyaku wait <selector>... [--any | --all] [--timeout <duration>]
49
+ `--contract` only records the association. It does not tell the Akuma the
50
+ Contract or worktree. Put them in the prompt explicitly:
51
+
52
+ ```text
53
+ Contract: <kei/...>
54
+ Worktree: <exact path>
55
+ This Arc: <what to do>
123
56
  ```
124
57
 
125
- `wait` accepts complete ids, aliases, and Akuma globs. Prefer one plural wait
126
- over separate waits. The default mode is any: the wait returns when any
127
- selected Akuma completes, and a member that already completed counts right
128
- away, so waiting again can return at once. Use `--all` to wait until every
129
- selected Akuma completes:
58
+ `--contract` does not choose a worktree. Use `--workdir <path>` when needed.
59
+
60
+ ## Tell an existing Akuma
130
61
 
131
62
  ```bash
132
- keiyaku -C <cwd> call worker --alias @projection -d "Inspect the projection."
133
- keiyaku -C <cwd> call worker --alias @host-boundary -d "Inspect the host boundary."
134
- keiyaku -C <cwd> wait @projection --timeout 5m
135
- keiyaku -C <cwd> wait @projection @host-boundary --timeout 5m # returns when either completes
136
- keiyaku -C <cwd> wait @projection @host-boundary --all --timeout 5m
63
+ keiyaku tell <aku/...|@alias> [--interrupt] [--schema <file>] [--wait <duration>] (<prompt> | -)
137
64
  ```
138
65
 
139
- Omitted mode behaves as `--any` and leaves the others alone. When the timeout
140
- expires, `wait` returns their current status without stopping them.
66
+ Use `tell` for the next instruction. Plain `tell` lets current work continue;
67
+ `--interrupt` asks the current Body to yield before the new prompt is handled.
68
+ Use `--wait <duration>` to wait for this Tell's answer. An admitted Tell is
69
+ not withdrawn when the wait ends. Use `--schema` when the answer must follow a
70
+ JSON Schema.
141
71
 
142
- ## Steer
72
+ ## Observe work
143
73
 
144
74
  ```bash
145
- keiyaku tell <aku/...|@alias> (<prompt> | -)
146
- keiyaku tell <aku/...|@alias> --interrupt (<prompt> | -)
75
+ keiyaku wait <selector>... [--any | --all] [--timeout <duration>]
147
76
  ```
148
77
 
149
- Give `tell` one prompt argument (quote it when it contains spaces) or final `-`
150
- for stdin, never both.
151
- `tell` continues the same worker: it steers a live Body in place, or — when
152
- none is running, including after an answer — records the message durably and
153
- wakes a successor. `tell --interrupt` puts down the current Body synchronously
154
- first, then hands the message to the successor; it is not a kill. Choose plain
155
- `tell` when the current attempt should finish with your guidance folded in;
156
- choose `--interrupt` when the current attempt itself is the problem.
78
+ Use `wait` for one or more existing Akumas. The default is `--any`; use
79
+ `--all` for every selected Akuma. `--timeout` limits observation and does not
80
+ stop workers. A completed Akuma already counts, so repeating a wait can return
81
+ immediately.
82
+
83
+ The three waiting forms have distinct subjects:
84
+
85
+ ```text
86
+ call --wait create an Akuma and observe its initial work
87
+ tell --wait deliver a Tell and observe that Tell's answer
88
+ wait observe existing Akumas
89
+ ```
157
90
 
158
- ## Take The Answer
91
+ ## Inspect and retrieve results
159
92
 
160
93
  ```bash
94
+ keiyaku status # current Akuma fleet
95
+ keiyaku status <aku/...|@alias> # one Akuma, including its execution workdir
96
+ keiyaku ls aku/ # names available to call
97
+ keiyaku ls aku/<akuma>/ # existing workers from one name
98
+ keiyaku ls "aku/*/*" # existing workers across names
161
99
  keiyaku history <aku/...|@alias> --last
162
100
  keiyaku history <aku/...|@alias> --id <historyId>
163
101
  keiyaku history <aku/...|@alias> [--before <N> | --since <N>] [--limit <N>]
164
102
  ```
165
103
 
166
- `--last` writes exactly the complete answer bytes of the latest answered turn
167
- and says so plainly when no answer exists yet. Snapshot rows elsewhere may
168
- clip long text; the terminal answer from `call`/`wait` and the bytes from
169
- `--last` are never clipped — when you need the full result, take it from one
170
- of those. Every completed answered or failed outcome carries one Heart-owned
171
- public `historyId` shaped as `turn/<positive-safe-integer>` in `status`, `wait`,
172
- and history output. Use `--id` with that same value to read exactly one retained
173
- outcome: text writes the complete answer or diagnostic bytes without clipping
174
- or framing. Provider-native history coordinates remain private. A malformed or
175
- unknown ID is a typed nonzero refusal. `--id` is mutually exclusive with
176
- `--last`, `--before`, `--since`, and `--limit`.
104
+ Use `history --last` for the latest complete answer. Use `--id` for one exact
105
+ answered result named by a status, wait, or history result. Use the complete
106
+ AkuId when an alias may move.
177
107
 
178
- Cursor reads page the activity timeline; `--before` and `--since` are exclusive
179
- sequence cursors. `--limit` defaults to 50 and accepts at most 5000 semantic
180
- rows.
181
-
182
- ## Stop
108
+ ## Stop and branch
183
109
 
184
110
  ```bash
185
111
  keiyaku kill <selector>...
112
+ keiyaku fork <aku/...|@alias> --at <historyId>
186
113
  ```
187
114
 
188
- `kill` accepts the same id, alias, and glob selectors as `wait`. It stops the
189
- current Body and records that it did; everything else survives — Heart,
190
- session, history, pending Tells, and Body Requests — so a later `tell` wakes
191
- the same worker where it left off. Killing pauses a worker; nothing is
192
- deleted.
193
-
194
- ## Branch
115
+ `kill` stops current work without deleting the Akuma or its history. `fork`
116
+ creates a new Akuma from one exact retained answered history point; the source
117
+ is unchanged, and providers that cannot fork report that refusal.
195
118
 
196
- ```bash
197
- keiyaku fork <aku/...|@alias> --at <historyId> [--alias @name]
198
- ```
119
+ ## JavaScript automation
199
120
 
200
- `fork` starts a child from one exact retained answered-turn coordinate and
201
- leaves the source untouched. It is a provider capability, not a guarantee:
202
- when the provider cannot fork from that turn, the command refuses rather than
203
- fabricating a fresh start. Pass the same public `historyId` exposed by status,
204
- wait, or history; Heart privately resolves the provider coordinate. The ID must
205
- name an answered outcome with a provider fork point. Failed outcomes are not
206
- forkable.
121
+ For a task-specific JavaScript program that coordinates Akumas, read
122
+ [Automation With The Akuma API](references/automation.md). `Akuma.birth`
123
+ creates an Akuma without a prompt; call `tell` on the returned handle to give
124
+ it its first prompt. Use `idle()` when a script must wait before sending
125
+ another schema Tell, and keep AkuIds in the script's own results.
@@ -1,123 +1,198 @@
1
1
  ---
2
2
  name: keiyaku-bind
3
3
  description: >-
4
- Use when deciding what must be in one Keiyaku Contract and how its work
5
- is divided into Arcs, or when writing or binding that Contract.
4
+ Must read before binding a `kei` (Contract). Use when deciding what belongs
5
+ in one `kei`, how to divide its work, and how to write or run `bind`.
6
6
  ---
7
7
 
8
- # Keiyaku Bind
8
+ # Before Binding A Keiyaku
9
9
 
10
- ## What Bind Records
10
+ Bind records a Contract whose objective, design, and acceptance boundary are
11
+ settled. Do not use it to leave an open design for someone else to decide.
11
12
 
12
- Bind journals decisions that have already been made. The Contract author
13
- arrives with the public outcome decided: Objective, Design, Region, Criteria,
14
- Verification. A design gap discovered while authoring goes back to whoever
15
- owns the decision — it is never forwarded into the worktree for a worker to
16
- resolve.
13
+ ## 1. What Must Be Clear Before Binding
17
14
 
18
- ## Author And Freedom
15
+ Settle these facts first:
19
16
 
20
- The author pins every public, high-level fact: surfaces, semantics, persisted
21
- shapes, the observable acceptance boundary. Private decomposition, helper
22
- names, and equivalent control flow belong to the Deliverer — and that freedom
23
- comes from the author genuinely not caring, never from the author not deciding.
24
- Criteria are observable accept/reject observations a Reviewer can judge without
25
- asking the author anything further.
17
+ - objective and intended outcome;
18
+ - architecture and module boundaries;
19
+ - detailed design and implementation approach;
20
+ - public interfaces, behavior, data, and persistence;
21
+ - ordering, concurrency, dependencies, and failure behavior;
22
+ - acceptance conditions;
23
+ - verification and required evidence;
24
+ - the affected Region;
25
+ - the one holder responsible for the `kei`.
26
26
 
27
- ## Author And Bind
27
+ The Design section is a detailed design document. It may contain subsections
28
+ such as:
28
29
 
29
- `keiyaku -C <repo> bind --help` lists the options; only the heredoc is
30
- stdin. Each section states what it must contain:
30
+ - Architecture: components, module boundaries, ownership, and connections;
31
+ - Interfaces And Behavior: public surfaces, inputs, outputs, success, and
32
+ refusal behavior;
33
+ - Data And Persistence: data shape, identity, lifecycle facts, and persistence;
34
+ - Approach And Flow: implementation approach, dependencies, ordering,
35
+ concurrency, and failure handling;
36
+ - Pseudocode: algorithms and control flow.
37
+
38
+ Record every design decision the implementation must follow. Add other Design
39
+ subsections when needed. Do not bind while the architecture, design, approach,
40
+ or acceptance conditions are open.
41
+
42
+ ### Contract Shape
43
+
44
+ - Bind separate `kei`s for outcomes that can be accepted independently.
45
+ - Use an Arc for a chapter inside one `kei`; an Arc is not separately accepted.
46
+ - Use a Task for decomposition or dependency memory that must outlive the
47
+ current conversation.
48
+
49
+ A `kei` owns one independently acceptable outcome and its delivery lifecycle. A
50
+ Task records decomposition or dependency memory; it may exist without a `kei`,
51
+ and it does not create a second acceptance or lifecycle. Associate a `kei` with
52
+ an existing Task only when that Task has real scheduling or dependency value.
53
+ Do not create a Task just to mirror a `kei`.
54
+
55
+ ### Parallel Work
56
+
57
+ Parallel work is the default.
58
+
59
+ - Bind and advance independent `kei`s in parallel. Each has its own acceptance
60
+ boundary and holder.
61
+ - Within one `kei`, run independent Tasks or Arc chapters in parallel whenever
62
+ their work can proceed independently. They converge on the one acceptance
63
+ boundary, which the holder owns.
64
+
65
+ Region overlap is planning information. It does not prevent parallel work and
66
+ is not a lock, ownership claim, exact diff, or dependency. Use `--after` only
67
+ when one result must exist before another can proceed because of a real logical
68
+ dependency. Do not add `--after` merely because work touches the same Region.
69
+
70
+ ## 2. Bind Syntax
71
+
72
+ Read the command's help for the complete option grammar:
73
+
74
+ ```bash
75
+ keiyaku -C <repo> bind --help
76
+ ```
77
+
78
+ Inspect declared Regions when planning parallel work:
79
+
80
+ ```bash
81
+ keiyaku -C <repo> region
82
+ keiyaku -C <repo> region <kei/...>
83
+ keiyaku -C <repo> region --path 'src/**' --path 'tests/**'
84
+ ```
85
+
86
+ These list active Regions, read one Contract's Region, or show active Regions
87
+ overlapping the supplied patterns. Overlap is coordination information only.
88
+
89
+ Bind from stdin with a heredoc or a saved Markdown file:
31
90
 
32
91
  ~~~~bash
33
92
  keiyaku -C <repo> bind - <<'KEIYAKU'
34
- # <Delivery name — one decision, active voice; source of the kei/... identity>
93
+ # <Delivery name>
35
94
 
36
95
  ## Context
37
- <Premises: coordinates of the governing decision or document, and facts a
38
- reader would otherwise re-derive wrongly. Never narrative. If Objective and
39
- Design read the same without a sentence here, delete it.>
96
+ <Motivation, authority, baseline, and boundaries.>
40
97
 
41
98
  ## Objective
42
- <One end-state you could watch happen, named at the level of intent and goal
43
- — above implementation detail, above spec recital. If "and" joins two
44
- outcomes that would each stand alone, bind two Contracts. Even an outcome
45
- that cannot split into two may still need arcs to organize its
46
- fulfillment.>
99
+ <One observable, independently acceptable outcome.>
47
100
 
48
101
  ## Design
49
- <The closed decisions. A statement belongs here exactly when a test-green
50
- candidate could still violate it: existing owner modules and entry points,
51
- what is reused or changed, the implementation approach, critical ordering, the
52
- exact public surface — each type with its fields, each verb with its success,
53
- refusal, and error arms and their reason words; the persisted format; which way
54
- data flows and where it commits or refuses; which parallel shapes are
55
- forbidden. Unresolved architectural choices are settled before binding. Private
56
- helper names and equivalent control flow remain the Deliverer's freedom.>
57
-
58
- ```text
59
- <pseudocode — only where ordering matters>
60
- ```
102
+ ### Architecture
103
+ <Components, module boundaries, ownership, and connections.>
104
+
105
+ ### Interfaces And Behavior
106
+ <Public surfaces, inputs, outputs, success, and refusal behavior.>
107
+
108
+ ### Data And Persistence
109
+ <Data shape, identity, lifecycle facts, and persistence decisions.>
110
+
111
+ ### Approach And Flow
112
+ <Implementation approach, dependencies, ordering, concurrency, and failure.>
113
+
114
+ ### Pseudocode
115
+ <Algorithms and control flow.>
61
116
 
62
117
  ## Region
63
- <one intended write pattern per line — the narrowest justified intended
64
- writes for this approach, not every potentially involved file. Planning evidence
65
- for overlap detection, never ownership or the exact diff. No broad directory
66
- fallback or redundant parent/child patterns; directory patterns end with `/`.
67
- Fenced lines, list items, and bare lines are equivalent and union.>
118
+ <One repository-relative write pattern per nonblank line.>
68
119
 
69
120
  ## Criteria
70
- ### <one observable condition>
71
- <One accept/reject observation with its method: run this, observe that.
72
- Decidable without consulting you.>
121
+ ### <observable acceptance condition>
122
+ <How to observe pass or refusal.>
73
123
 
74
124
  ## Verification
75
- ```bash timeout=<honest bound>
125
+ ```bash timeout=5m
76
126
  <commands runnable exactly as written>
77
127
  ```
78
128
  KEIYAKU
79
129
  ~~~~
80
130
 
81
- Use separate fences for checks that need separate timeouts or results. Fences
82
- run top-to-bottom, and later fences may use earlier outputs. Put setup/build
83
- before its consumers; use `&&` in one fence only when the consumer must stop
84
- if setup fails.
131
+ Use the narrowest justified Region patterns for likely writes. A trailing `/`
132
+ is directory shorthand for `/**`. Patterns may be fenced lines, list items, or
133
+ bare lines; those forms are combined. Region patterns are planning evidence,
134
+ not a prediction of the exact diff.
135
+
136
+ Verification is optional. Each declaration is a closed bash, zsh, or pwsh
137
+ fence containing commands runnable as written. Use separate fences when checks
138
+ need different timeouts or results. Use an explicit timeout for bounded
139
+ commands; `5m` is the normal baseline.
85
140
 
86
- Each declaration may set an individual timeout in its fence info string, using
87
- an explicit duration unit such as `bash timeout=5m`. Omit it for an unbounded
88
- declaration; there is no Verification-wide timeout.
141
+ Verification runs against the exact integration snapshot in a clean disposable
142
+ worktree for that attempt. It does not run in the author's worktree or the
143
+ target checkout. If the Contract declares Verification, `deliver` runs it when
144
+ no current `verified` attestation exists and otherwise reuses the current
145
+ attestation. A newly run unsatisfied result stops that delivery. `audit` runs
146
+ Verification for a prospective candidate. `--gates reviewed` requires review
147
+ evidence; it does not select or suppress Verification. Selected gates are
148
+ checked at placement.
89
149
 
90
- For a saved document:
150
+ For an existing Task with real scheduling or dependency value:
91
151
 
92
152
  ```bash
93
- keiyaku -C <repo> bind - < CONTRACT.md
94
153
  keiyaku -C <repo> bind --task <task/...> - < CONTRACT.md
95
154
  ```
96
155
 
97
- Use `--task` only for an existing Task with scheduling or dependency value;
98
- do not create one just to mirror the Contract.
156
+ For a real logical dependency between Contracts:
157
+
158
+ ```bash
159
+ keiyaku -C <repo> bind --after <kei/...> - < CONTRACT.md
160
+ ```
161
+
162
+ Gate selection is part of binding:
163
+
164
+ ```bash
165
+ keiyaku -C <repo> bind --gates <name,...> - < CONTRACT.md
166
+ keiyaku -C <repo> bind --gates "" - < CONTRACT.md
167
+ keiyaku -C <repo> bind --gates reviewed - < CONTRACT.md
168
+ ```
169
+
170
+ Omitting `--gates` uses `gates.default`, or `reviewed` when no default bundle
171
+ exists. `--gates ""` selects no gates. Gates are named acceptance obligations,
172
+ not work assignments.
99
173
 
100
- ## Authority Order
174
+ ## 3. After Binding
101
175
 
102
- Settled upstream decisions and their documentation → this Contract → commission
103
- and brief (directs the current round's work and questions; never terms, never
104
- acceptance) → review evidence (witnessed fact, never law). The journaled terms
105
- are the standing acceptance floor. A brief or tell genuinely commands what this
106
- round works on and what evidence it gathers; anything that must survive beyond
107
- the round as a placement condition enters the journal through bind or amend, or
108
- it is not acceptance.
176
+ Read the receipt as the handoff. Keep the complete `kei/...` identity and note:
109
177
 
110
- ## One Boundary, One Contract
178
+ - the holder;
179
+ - the reported worktree, if one was created;
180
+ - the target;
181
+ - gates and prerequisites;
182
+ - whether the `kei` is ready or waiting.
111
183
 
112
- One atomic acceptance boundary per Contract. Independent boundaries are
113
- separate Contracts; a boundary that cannot be split but is too large for one
114
- pass is chaptered with Arcs, and dispatch carries only the current Arc.
184
+ If a worktree was created, work there. If the receipt is waiting, the stated
185
+ prerequisites remain; do not bind a duplicate Contract.
115
186
 
116
- ## Read The Receipt
187
+ The holder now owns the lifecycle:
117
188
 
118
- Treat the receipt as the handoff. Keep the complete `kei/...` identity, work
119
- in the reported managed worktree when one was created, and retain the target
120
- and gate facts it reports. A waiting receipt means prerequisites remain; it
121
- is not a second authoring workflow.
189
+ 1. Start the work directly or delegate Tasks, Arc chapters, Akumas, or seats.
190
+ 2. Run independent work in parallel and let it converge on the one acceptance
191
+ boundary.
192
+ 3. Prepare and deliver the candidate.
193
+ 4. Coordinate verification, review evidence, gates, and prerequisites.
194
+ 5. Continue until the `kei` is claimed, amend terms while keeping the same
195
+ objective and acceptance boundary, or abandon it when either has changed.
122
196
 
123
- Continue the delivery with `keiyaku-workflow`.
197
+ Continue with `keiyaku-workflow` for this lifecycle. For Akuma invocation,
198
+ telling, waiting, permissions, and history, read `keiyaku-akuma`.