@astrosheep/keiyaku 4.6.6 → 4.6.8

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 (217) hide show
  1. package/README.md +11 -0
  2. package/build/{integrations/marketplace → plugins}/.agents/plugins/marketplace.json +1 -1
  3. package/build/plugins/.claude-plugin/marketplace.json +5 -0
  4. package/build/{integrations/marketplace/plugins/keiyaku → plugins/claude}/.claude-plugin/plugin.json +1 -1
  5. package/build/{integrations/marketplace/plugins/keiyaku → plugins/codex}/.codex-plugin/plugin.json +1 -1
  6. package/build/plugins/codex/skills/keiyaku/SKILL.md +44 -0
  7. package/build/plugins/codex/skills/keiyaku-akuma/SKILL.md +130 -0
  8. package/build/plugins/codex/skills/keiyaku-akuma/references/automation.md +269 -0
  9. package/build/plugins/codex/skills/keiyaku-babysit/SKILL.md +65 -0
  10. package/build/plugins/codex/skills/keiyaku-bind/SKILL.md +216 -0
  11. package/build/plugins/codex/skills/keiyaku-bind/agents/openai.yaml +4 -0
  12. package/build/plugins/codex/skills/keiyaku-task/SKILL.md +104 -0
  13. package/build/plugins/codex/skills/keiyaku-workflow/SKILL.md +129 -0
  14. package/build/plugins/opencode/package.json +6 -0
  15. package/build/plugins/opencode/skills/keiyaku/SKILL.md +44 -0
  16. package/build/plugins/opencode/skills/keiyaku-akuma/SKILL.md +130 -0
  17. package/build/plugins/opencode/skills/keiyaku-akuma/references/automation.md +269 -0
  18. package/build/plugins/opencode/skills/keiyaku-babysit/SKILL.md +65 -0
  19. package/build/plugins/opencode/skills/keiyaku-bind/SKILL.md +216 -0
  20. package/build/plugins/opencode/skills/keiyaku-bind/agents/openai.yaml +4 -0
  21. package/build/plugins/opencode/skills/keiyaku-task/SKILL.md +104 -0
  22. package/build/plugins/opencode/skills/keiyaku-workflow/SKILL.md +129 -0
  23. package/build/{integrations → plugins}/pi/keiyaku.ts +0 -5
  24. package/build/skills/keiyaku/SKILL.md +44 -0
  25. package/build/skills/keiyaku-akuma/SKILL.md +130 -0
  26. package/build/skills/keiyaku-akuma/references/automation.md +269 -0
  27. package/build/skills/keiyaku-babysit/SKILL.md +65 -0
  28. package/build/skills/keiyaku-bind/SKILL.md +216 -0
  29. package/build/skills/keiyaku-bind/agents/openai.yaml +4 -0
  30. package/build/skills/keiyaku-task/SKILL.md +104 -0
  31. package/build/skills/keiyaku-workflow/SKILL.md +129 -0
  32. package/build/src/akuma/akuma-call.d.ts +2 -0
  33. package/build/src/akuma/akuma-call.js +8 -2
  34. package/build/src/akuma/akuma-instance.d.ts +12 -1
  35. package/build/src/akuma/akuma-instance.js +31 -9
  36. package/build/src/akuma/akuma-observe.d.ts +4 -0
  37. package/build/src/akuma/akuma-observe.js +14 -0
  38. package/build/src/akuma/akuma-owner.d.ts +6 -2
  39. package/build/src/akuma/akuma-owner.js +32 -10
  40. package/build/src/akuma/akuma-selection-execution.d.ts +3 -1
  41. package/build/src/akuma/akuma-selection-execution.js +2 -1
  42. package/build/src/akuma/akuma-wait.d.ts +2 -1
  43. package/build/src/akuma/akuma-wait.js +4 -1
  44. package/build/src/akuma/akuma.d.ts +35 -5
  45. package/build/src/akuma/akuma.js +8 -10
  46. package/build/src/akuma/archetype.d.ts +7 -15
  47. package/build/src/akuma/archetype.js +36 -35
  48. package/build/src/akuma/body.d.ts +6 -3
  49. package/build/src/akuma/body.js +41 -30
  50. package/build/src/akuma/call-request.d.ts +18 -10
  51. package/build/src/akuma/call-request.js +10 -3
  52. package/build/src/akuma/caller.d.ts +39 -0
  53. package/build/src/akuma/caller.js +36 -0
  54. package/build/src/akuma/dispatch-association.d.ts +0 -1
  55. package/build/src/akuma/dispatch-association.js +0 -3
  56. package/build/src/akuma/heart/facts.d.ts +16 -12
  57. package/build/src/akuma/heart/facts.js +8 -0
  58. package/build/src/akuma/heart/index.d.ts +2 -7
  59. package/build/src/akuma/heart/index.js +3 -17
  60. package/build/src/akuma/heart/rows.d.ts +3 -3
  61. package/build/src/akuma/heart/soul.d.ts +1 -1
  62. package/build/src/akuma/heart/soul.js +5 -24
  63. package/build/src/akuma/heart/storage.d.ts +5 -0
  64. package/build/src/akuma/heart/storage.js +7 -3
  65. package/build/src/akuma/identity.d.ts +0 -1
  66. package/build/src/akuma/identity.js +2 -5
  67. package/build/src/akuma/index.d.ts +5 -2
  68. package/build/src/akuma/index.js +1 -0
  69. package/build/src/akuma/nuke.js +6 -28
  70. package/build/src/akuma/projection.d.ts +0 -11
  71. package/build/src/akuma/provider-recipe.d.ts +7 -6
  72. package/build/src/akuma/provider-recipe.js +1 -1
  73. package/build/src/akuma/provider.d.ts +6 -10
  74. package/build/src/akuma/provider.js +6 -7
  75. package/build/src/akuma/providers/acp/events.js +5 -18
  76. package/build/src/akuma/providers/acp/index.js +2 -3
  77. package/build/src/akuma/providers/claude/events.js +35 -60
  78. package/build/src/akuma/providers/claude/index.d.ts +2 -2
  79. package/build/src/akuma/providers/claude/index.js +2 -3
  80. package/build/src/akuma/providers/codex-app-server/index.js +2 -2
  81. package/build/src/akuma/providers/decode.d.ts +25 -0
  82. package/build/src/akuma/providers/decode.js +44 -0
  83. package/build/src/akuma/providers/execution-environment.d.ts +2 -1
  84. package/build/src/akuma/providers/execution-environment.js +3 -0
  85. package/build/src/akuma/providers/grok-build/index.js +6 -22
  86. package/build/src/akuma/providers/index.js +2 -0
  87. package/build/src/akuma/providers/lifecycle.d.ts +9 -0
  88. package/build/src/akuma/providers/lifecycle.js +10 -0
  89. package/build/src/akuma/providers/opencode-sdk/events.js +1 -14
  90. package/build/src/akuma/providers/opencode-sdk/index.js +10 -17
  91. package/build/src/akuma/providers/opencode-sdk/session.js +1 -3
  92. package/build/src/akuma/providers/paseo/events.d.ts +25 -0
  93. package/build/src/akuma/providers/paseo/events.js +157 -0
  94. package/build/src/akuma/providers/paseo/index.d.ts +9 -0
  95. package/build/src/akuma/providers/paseo/index.js +353 -0
  96. package/build/src/akuma/providers/pi/events.js +5 -15
  97. package/build/src/akuma/publication.d.ts +2 -0
  98. package/build/src/akuma/publication.js +5 -0
  99. package/build/src/akuma/request-lifecycle.d.ts +3 -0
  100. package/build/src/akuma/request-lifecycle.js +25 -4
  101. package/build/src/akuma/requests.d.ts +3 -1
  102. package/build/src/akuma/requests.js +32 -0
  103. package/build/src/akuma/selection-observation.d.ts +72 -2
  104. package/build/src/akuma/selection-observation.js +0 -6
  105. package/build/src/akuma/selection-owner-port.d.ts +1 -1
  106. package/build/src/akuma/selection-owner-port.js +16 -5
  107. package/build/src/akuma/selection-request.d.ts +2 -0
  108. package/build/src/akuma/selection-request.js +2 -1
  109. package/build/src/akuma/turn-drive.js +2 -5
  110. package/build/src/akuma-body.js +4 -2
  111. package/build/src/cli/akuma-caller.d.ts +3 -0
  112. package/build/src/cli/akuma-caller.js +21 -0
  113. package/build/src/cli/commands/akuma-grammar.js +7 -12
  114. package/build/src/cli/commands/akuma.js +18 -16
  115. package/build/src/cli/commands/contract-grammar.d.ts +2 -1
  116. package/build/src/cli/commands/contract-grammar.js +13 -15
  117. package/build/src/cli/commands/contract-help.d.ts +2 -1
  118. package/build/src/cli/commands/contract-help.js +31 -1
  119. package/build/src/cli/commands/contract.js +24 -53
  120. package/build/src/cli/commands/install.js +3 -3
  121. package/build/src/cli/commands/task.js +18 -35
  122. package/build/src/cli/parse.d.ts +2 -2
  123. package/build/src/cli/render/catalog.d.ts +2 -5
  124. package/build/src/cli/render/contract-history.js +3 -6
  125. package/build/src/cli/render/contract.js +15 -50
  126. package/build/src/cli/render/receipt.js +3 -10
  127. package/build/src/cli/render/task.d.ts +4 -6
  128. package/build/src/cli/render/task.js +9 -26
  129. package/build/src/cli/runtime.d.ts +1 -1
  130. package/build/src/cli/runtime.js +11 -17
  131. package/build/src/cli/selectors.d.ts +3 -6
  132. package/build/src/cli/selectors.js +22 -53
  133. package/build/src/dispatch/index.d.ts +3 -3
  134. package/build/src/dispatch/index.js +1 -2
  135. package/build/src/git/observe.d.ts +6 -2
  136. package/build/src/git/observe.js +6 -2
  137. package/build/src/index.d.ts +6 -6
  138. package/build/src/index.js +2 -2
  139. package/build/src/kanshi/index.d.ts +1 -1
  140. package/build/src/kanshi/read.js +21 -6
  141. package/build/src/library/address.js +2 -4
  142. package/build/src/library/akuma-creation.d.ts +5 -1
  143. package/build/src/library/akuma-creation.js +33 -51
  144. package/build/src/library/akumas.d.ts +5 -4
  145. package/build/src/library/akumas.js +13 -9
  146. package/build/src/library/bind.d.ts +14 -14
  147. package/build/src/library/bind.js +11 -7
  148. package/build/src/library/contract-address.d.ts +9 -0
  149. package/build/src/library/contract-address.js +71 -0
  150. package/build/src/library/contract-composition.d.ts +4 -7
  151. package/build/src/library/contract-composition.js +6 -18
  152. package/build/src/library/contract-creation.d.ts +3 -5
  153. package/build/src/library/contract-creation.js +19 -17
  154. package/build/src/library/contract-execution.js +18 -23
  155. package/build/src/library/contract-outcomes.d.ts +2 -14
  156. package/build/src/library/contract-outcomes.js +2 -13
  157. package/build/src/library/contract-types.d.ts +36 -2
  158. package/build/src/library/delivery.d.ts +0 -2
  159. package/build/src/library/delivery.js +2 -5
  160. package/build/src/library/keiyaku.d.ts +0 -5
  161. package/build/src/library/keiyaku.js +6 -12
  162. package/build/src/library/outcome.d.ts +500 -499
  163. package/build/src/library/outcome.js +10 -0
  164. package/build/src/library/reconcile.js +8 -16
  165. package/build/src/library/refusal.d.ts +2 -2
  166. package/build/src/library/repo.d.ts +3 -2
  167. package/build/src/library/repo.js +10 -5
  168. package/build/src/library/selection.d.ts +4 -4
  169. package/build/src/library/selection.js +12 -9
  170. package/build/src/plugin/akuma-signals.d.ts +12 -11
  171. package/build/src/plugin/akuma-signals.js +40 -20
  172. package/build/src/plugin/public.d.ts +32 -2
  173. package/build/src/plugin/runtime.d.ts +1 -0
  174. package/build/src/plugin/runtime.js +35 -24
  175. package/build/src/protocol/amend.js +3 -2
  176. package/build/src/protocol/attempt.js +3 -8
  177. package/build/src/protocol/bind.d.ts +2 -2
  178. package/build/src/protocol/bind.js +1 -1
  179. package/build/src/protocol/deliver.js +3 -3
  180. package/build/src/protocol/operations.d.ts +1 -3
  181. package/build/src/protocol/operations.js +0 -8
  182. package/build/src/protocol/outcome.d.ts +1 -2
  183. package/build/src/protocol/outcome.js +1 -13
  184. package/build/src/protocol/placement.js +3 -10
  185. package/build/src/protocol/read/status.js +31 -70
  186. package/build/src/protocol/reintegrate.js +3 -10
  187. package/build/src/protocol/review.js +3 -3
  188. package/build/src/protocol/run.d.ts +5 -1
  189. package/build/src/protocol/run.js +3 -3
  190. package/build/src/runtime/proc/windows-launch.exe +0 -0
  191. package/package.json +12 -8
  192. package/plugins/pi/keiyaku.ts +57 -0
  193. package/skills/keiyaku/SKILL.md +44 -0
  194. package/skills/keiyaku-akuma/SKILL.md +130 -0
  195. package/skills/keiyaku-akuma/references/automation.md +269 -0
  196. package/skills/keiyaku-babysit/SKILL.md +65 -0
  197. package/skills/keiyaku-bind/SKILL.md +216 -0
  198. package/skills/keiyaku-bind/agents/openai.yaml +4 -0
  199. package/skills/keiyaku-task/SKILL.md +104 -0
  200. package/skills/keiyaku-workflow/SKILL.md +129 -0
  201. package/build/integrations/marketplace/.claude-plugin/marketplace.json +0 -5
  202. package/build/integrations/marketplace/plugins/keiyaku/package.json +0 -17
  203. package/build/src/cli/commands/amend.d.ts +0 -12
  204. package/build/src/cli/commands/amend.js +0 -10
  205. package/build/src/cli/commands/bind.d.ts +0 -11
  206. package/build/src/cli/commands/bind.js +0 -23
  207. package/build/src/dispatch/association.d.ts +0 -1
  208. package/build/src/dispatch/association.js +0 -1
  209. /package/build/{integrations/marketplace/plugins/keiyaku → plugins/claude}/skills/keiyaku/SKILL.md +0 -0
  210. /package/build/{integrations/marketplace/plugins/keiyaku → plugins/claude}/skills/keiyaku-akuma/SKILL.md +0 -0
  211. /package/build/{integrations/marketplace/plugins/keiyaku → plugins/claude}/skills/keiyaku-akuma/references/automation.md +0 -0
  212. /package/build/{integrations/marketplace/plugins/keiyaku → plugins/claude}/skills/keiyaku-babysit/SKILL.md +0 -0
  213. /package/build/{integrations/marketplace/plugins/keiyaku → plugins/claude}/skills/keiyaku-bind/SKILL.md +0 -0
  214. /package/build/{integrations/marketplace/plugins/keiyaku → plugins/claude}/skills/keiyaku-bind/agents/openai.yaml +0 -0
  215. /package/build/{integrations/marketplace/plugins/keiyaku → plugins/claude}/skills/keiyaku-task/SKILL.md +0 -0
  216. /package/build/{integrations/marketplace/plugins/keiyaku → plugins/claude}/skills/keiyaku-workflow/SKILL.md +0 -0
  217. /package/build/{integrations/marketplace/plugins/keiyaku/opencode.js → plugins/opencode/index.js} +0 -0
@@ -0,0 +1,216 @@
1
+ ---
2
+ name: keiyaku-bind
3
+ description: >-
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
+ ---
7
+
8
+ # Before Binding A Keiyaku
9
+
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.
12
+
13
+ ## 1. What Must Be Clear Before Binding
14
+
15
+ Settle these facts first:
16
+
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
+
27
+ The Design section is a detailed design document. It may contain subsections
28
+ such as:
29
+
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: Mandatory Acceptance Boundary Check
43
+
44
+ Before every bind, identify the independently acceptable outcomes. For each
45
+ proposed part, ask whether it can be reviewed and accepted while another part
46
+ remains unfinished. If it can, you MUST bind it as a separate `kei`. Do not bind
47
+ an aggregate Contract containing independently acceptable outcomes.
48
+
49
+ A shared request, audit, theme, product name, worker, verification command, or
50
+ overlapping Region does NOT justify combining acceptance boundaries. Worker
51
+ assignment and Contract boundaries are separate decisions: one worker may
52
+ serve several Contracts, and several workers may contribute to one outcome.
53
+ A request to "open a kei" does not by itself instruct you to combine outcomes.
54
+
55
+ Keep parts together only when they jointly establish one outcome that cannot
56
+ be meaningfully accepted in parts. State that inseparability in Context and
57
+ make Criteria judge the same outcome. Do not manufacture inseparability by
58
+ writing one broad Objective around unrelated fixes.
59
+
60
+ - Use an Arc only for a chapter inside that one acceptance boundary; an Arc is
61
+ not separately accepted and MUST NOT substitute for an independent `kei`.
62
+ - Use a Task for decomposition or dependency memory that must outlive the
63
+ current conversation.
64
+
65
+ A `kei` owns one independently acceptable outcome and its delivery lifecycle. A
66
+ Task records decomposition or dependency memory; it may exist without a `kei`,
67
+ and it does not create a second acceptance or lifecycle. Associate a `kei` with
68
+ an existing Task only when that Task has real scheduling or dependency value.
69
+ Do not create a Task just to mirror a `kei`.
70
+
71
+ ### Parallel Work
72
+
73
+ Parallel work is the default.
74
+
75
+ - Bind and advance independent `kei`s in parallel. Each has its own acceptance
76
+ boundary and holder.
77
+ - Within one `kei`, run independent Tasks or Arc chapters in parallel whenever
78
+ their work can proceed independently. They converge on the one acceptance
79
+ boundary, which the holder owns.
80
+
81
+ Region overlap is planning information. It does not prevent parallel work and
82
+ is not a lock, ownership claim, exact diff, or dependency. Use `--after` only
83
+ when one result must exist before another can proceed because of a real logical
84
+ dependency. Do not add `--after` merely because work touches the same Region.
85
+
86
+ ## 2. Bind Syntax
87
+
88
+ Read the command's help for the complete option grammar:
89
+
90
+ ```bash
91
+ keiyaku -C <repo> bind --help
92
+ ```
93
+
94
+ Inspect declared Regions when planning parallel work:
95
+
96
+ ```bash
97
+ keiyaku -C <repo> region
98
+ keiyaku -C <repo> region <kei/...>
99
+ keiyaku -C <repo> region --path 'src/**' --path 'tests/**'
100
+ ```
101
+
102
+ These list active Regions, read one Contract's Region, or show active Regions
103
+ overlapping the supplied patterns. Overlap is coordination information only.
104
+
105
+ Bind from stdin with a heredoc or a saved Markdown file:
106
+
107
+ ~~~~bash
108
+ keiyaku -C <repo> bind - <<'KEIYAKU'
109
+ # <Delivery name>
110
+
111
+ ## Context
112
+ <Motivation, authority, baseline, and boundaries.>
113
+
114
+ ## Objective
115
+ <One observable, independently acceptable outcome.>
116
+
117
+ ## Design
118
+ ### Architecture
119
+ <Components, module boundaries, ownership, and connections.>
120
+
121
+ ### Interfaces And Behavior
122
+ <Public surfaces, inputs, outputs, success, and refusal behavior.>
123
+
124
+ ### Data And Persistence
125
+ <Data shape, identity, lifecycle facts, and persistence decisions.>
126
+
127
+ ### Approach And Flow
128
+ <Implementation approach, dependencies, ordering, concurrency, and failure.>
129
+
130
+ ### Pseudocode
131
+ <Algorithms and control flow.>
132
+
133
+ ## Region
134
+ <One repository-relative write pattern per nonblank line.>
135
+
136
+ ## Criteria
137
+ ### <observable acceptance condition>
138
+ <How to observe pass or refusal.>
139
+
140
+ ## Verification
141
+ ```bash timeout=5m
142
+ <commands runnable exactly as written>
143
+ ```
144
+ KEIYAKU
145
+ ~~~~
146
+
147
+ Use the narrowest justified Region patterns for likely writes. A trailing `/`
148
+ is directory shorthand for `/**`. Patterns may be fenced lines, list items, or
149
+ bare lines; those forms are combined. Region patterns are planning evidence,
150
+ not a prediction of the exact diff.
151
+
152
+ Verification is optional. Each declaration is a closed bash, zsh, or pwsh
153
+ fence containing commands runnable as written. Use separate fences when checks
154
+ need different timeouts or results. Use an explicit timeout for bounded
155
+ commands; `5m` is the normal baseline.
156
+
157
+ Verification runs only when the Contract selects the `verified` gate, against
158
+ the exact integration snapshot in a clean disposable worktree for that attempt.
159
+ `deliver` reuses current satisfied evidence or runs the declarations; unsatisfied
160
+ results and runtime stops prevent placement. `audit` runs declarations for a
161
+ prospective candidate. Without `verified`, no verb runs Verification and the
162
+ section is inert document text. `reviewed` independently requires review
163
+ evidence. Selected gates are checked at placement.
164
+
165
+ For an existing Task with real scheduling or dependency value:
166
+
167
+ ```bash
168
+ keiyaku -C <repo> bind --task <task/...> - < CONTRACT.md
169
+ ```
170
+
171
+ For a real logical dependency between Contracts:
172
+
173
+ ```bash
174
+ keiyaku -C <repo> bind --after <kei/...> - < CONTRACT.md
175
+ ```
176
+
177
+ Gate selection is part of binding:
178
+
179
+ ```bash
180
+ keiyaku -C <repo> bind --gates <name,...> - < CONTRACT.md
181
+ keiyaku -C <repo> bind --gates "" - < CONTRACT.md
182
+ keiyaku -C <repo> bind --gates reviewed - < CONTRACT.md
183
+ ```
184
+
185
+ Omitting `--gates` uses `gates.default`, or `reviewed` when no default group
186
+ exists. `--gates ""` selects no gates. Gates are named acceptance obligations,
187
+ not work assignments. Named gate groups and worktree hooks live in Settings;
188
+ see the README Configuration section or `keiyaku settings --help`.
189
+
190
+ ## 3. After Binding
191
+
192
+ Binding appoints one managed worktree for the `kei`. Read the receipt as the
193
+ handoff. Keep the complete `kei/...` identity and note:
194
+
195
+ - the holder;
196
+ - the appointed worktree path (absent when appointment lagged);
197
+ - the target;
198
+ - gates and prerequisites;
199
+ - whether the `kei` is ready or waiting.
200
+
201
+ Work in the appointed worktree. When appointment lags, the receipt carries no
202
+ path and the `kei` shows pending reconciliation instead. If the receipt is
203
+ waiting, the stated prerequisites remain; do not bind a duplicate Contract.
204
+
205
+ The holder now owns the lifecycle:
206
+
207
+ 1. Start the work directly or delegate Tasks, Arc chapters, Akumas, or Contract roles.
208
+ 2. Run independent work in parallel and let it converge on the one acceptance
209
+ boundary.
210
+ 3. Prepare and deliver the candidate.
211
+ 4. Coordinate verification, review evidence, gates, and prerequisites.
212
+ 5. Continue until the `kei` is accepted, amend terms while keeping the same
213
+ objective and acceptance boundary, or abandon it when either has changed.
214
+
215
+ Continue with `keiyaku-workflow` for this lifecycle. For Akuma invocation,
216
+ telling, waiting, permissions, and history, read `keiyaku-akuma`.
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "Keiyaku Bind"
3
+ short_description: "Author and bind a delivery Contract."
4
+ default_prompt: "Use $keiyaku-bind to author and bind this delivery."
@@ -0,0 +1,104 @@
1
+ ---
2
+ name: keiyaku-task
3
+ description: >-
4
+ Must read when using Tasks for durable work planning, decomposition, or
5
+ dependencies.
6
+ ---
7
+
8
+ # Keiyaku Task
9
+
10
+ A Task is durable planning memory. It records work, decomposition, and
11
+ relationships that must remain after the current conversation. Task is an
12
+ independent product; it is not a Contract, Arc, Akuma, permission, acceptance
13
+ boundary, or fulfillment lifecycle.
14
+
15
+ ## 1. When To Use A Task
16
+
17
+ Use a Task when the plan or dependency must outlive the current conversation.
18
+ Skip it when the work is small and no durable planning memory is needed.
19
+
20
+ - Use a `kei` for one independently acceptable outcome.
21
+ - Use an Arc for a chapter inside one `kei`.
22
+ - Use a Task for decomposition or dependency memory.
23
+ - Do not create a Task just to mirror a `kei`.
24
+
25
+ A Task may exist without a Contract. Associating a Task with a `kei` does not
26
+ transfer the Contract's holder, acceptance, or lifecycle to the Task.
27
+
28
+ ## 2. Relationships And Parallel Work
29
+
30
+ Independent Tasks may start and progress in parallel when their dependencies
31
+ allow it.
32
+
33
+ Use the relationships for their actual meanings:
34
+
35
+ - `needs` means this Task must wait for another Task to become terminal.
36
+ - `parent` groups decomposition; it does not create a dependency.
37
+ - `supersedes` points to work replaced by this Task.
38
+ - `relates` records a connection without affecting readiness.
39
+
40
+ Only `needs` orders work. Do not add it because Tasks touch the same Region or
41
+ because one Task is related to another. A terminal Task releases its dependents.
42
+ An `on_hold` Task is deliberately paused; it is neither ready nor blocked.
43
+
44
+ ## 3. Task Commands
45
+
46
+ Create and inspect Tasks:
47
+
48
+ ```bash
49
+ keiyaku task add "<title>"
50
+ keiyaku task add "<title>" --priority 1 --needs <task-id>
51
+ keiyaku task show <task-id>
52
+ keiyaku task ls
53
+ keiyaku task ready
54
+ keiyaku task blocked
55
+ keiyaku task tree <task-id>
56
+ keiyaku task doctor
57
+ ```
58
+
59
+ Use complete Task IDs for targeted commands. `ls`, `ready`, and `blocked` use
60
+ the current namespace; use `--world` to inspect the complete Task world.
61
+
62
+ Change lifecycle state:
63
+
64
+ ```bash
65
+ keiyaku task start <task-id>...
66
+ keiyaku task stop <task-id>
67
+ keiyaku task hold <task-id>...
68
+ keiyaku task resume <task-id>
69
+ keiyaku task done <task-id>...
70
+ keiyaku task drop <task-id>... --note "<reason>"
71
+ ```
72
+
73
+ Use `done` when the Task is complete. Use `drop` when it will not be done.
74
+ Both terminal states release dependent Tasks. Use `hold` for a deliberate pause,
75
+ not for an unresolved dependency; unresolved `needs` appear in `blocked`.
76
+
77
+ Update a Task without changing its lifecycle:
78
+
79
+ ```bash
80
+ keiyaku task update <task-id> --title "<title>"
81
+ keiyaku task update <task-id> --body "<body>"
82
+ keiyaku task update <task-id> --needs <task-id>
83
+ ```
84
+
85
+ Use `task compose -` when several Tasks and their relationships should be
86
+ planned or admitted together. Use `--plan` to inspect the composition without
87
+ writing it.
88
+
89
+ ## 4. After Creating A Task
90
+
91
+ Read the returned Task identity. Then:
92
+
93
+ 1. Start ready work.
94
+ 2. Run independent Tasks in parallel.
95
+ 3. Add or remove relationships when the plan changes.
96
+ 4. Hold work that is deliberately paused.
97
+ 5. Mark completed work `done`, or mark abandoned work `drop` with a reason.
98
+ 6. Use `ready`, `blocked`, `tree`, or `doctor` to rebuild the current view.
99
+
100
+ Task records planning memory. It does not perform the work, claim acceptance,
101
+ assign a holder, or decide what a Contract may accept.
102
+
103
+ Read `keiyaku-bind` for Contract authoring and `keiyaku-workflow` for Contract
104
+ lifecycle.
@@ -0,0 +1,129 @@
1
+ ---
2
+ name: keiyaku-workflow
3
+ description: >-
4
+ Must read before binding a `kei` (Contract) or when acting as its holder.
5
+ Use when deciding when to bind a kei, how to shape and hold it, how to
6
+ delegate its work, and how to accept, amend, or end it.
7
+ ---
8
+
9
+ # Keiyaku Workflow
10
+
11
+ The holder runs one Contract's fulfillment loop from preparation to completion.
12
+
13
+ ## 1. Prepare Before Binding
14
+
15
+ Before `bind`, settle the information that makes the `kei` truthful:
16
+
17
+ - objective and intended outcome;
18
+ - design and approach;
19
+ - affected Region;
20
+ - acceptance conditions;
21
+ - verification and required evidence;
22
+ - prerequisites;
23
+ - holder.
24
+
25
+ If the design, approach, or acceptance conditions are still open, do not bind.
26
+ Resolve them with their owner first. Private implementation details may remain
27
+ for the Deliverer; the public meaning and acceptance boundary may not.
28
+
29
+ Bind independent `kei`s in parallel. Do not split one acceptance boundary just
30
+ to create parallel work.
31
+
32
+ ## 2. Split the Work
33
+
34
+ - Separate `kei`s have independently acceptable outcomes.
35
+ - An Arc is a chapter of one `kei`; it is not separately accepted.
36
+ - A Task stores decomposition or dependencies that outlive this conversation.
37
+
38
+ Use `after` only when one `kei` requires another to be accepted first. Ordinary
39
+ overlap is not a dependency.
40
+
41
+ ## 3. Roles
42
+
43
+ A `kei` has three roles. They are responsibilities, not people, and one agent
44
+ may fill more than one of them, with one exception below.
45
+
46
+ - **Holder:** exactly one per `kei`. Owns the fulfillment loop and acceptance
47
+ until the Contract is accepted or abandoned. Handing work to others never
48
+ transfers this responsibility.
49
+ - **Deliverer:** produces the candidate in the appointed worktree and tenders
50
+ it with `deliver`.
51
+ - **Reviewer:** judges the complete Contract against its acceptance conditions
52
+ and records the verdict with `review`.
53
+
54
+ Review is independent when the Reviewer did not deliver the candidate under
55
+ review. That is the whole requirement. The holder may review its own `kei`; a
56
+ fresh Akuma is not what makes review independent. Keiyaku does not check who
57
+ reviews, so keeping the Reviewer apart from the Deliverer is the holder's duty.
58
+
59
+ Any role may be filled directly or handed to an Akuma. Hand one over when other
60
+ hands help the work, not to make review count.
61
+
62
+ ## 4. Lifecycle
63
+
64
+ Each act changes a different part of the world:
65
+
66
+ - **Bind:** Journal gains the Contract and its terms. Workspace appointment
67
+ names one managed worktree; the receipt reports its path. Appointment lag
68
+ leaves the bind admitted without a path and reports pending reconciliation.
69
+ `reconcile` retries workspace realization.
70
+ - **Work:** Changes and commits belong in the appointed worktree. Another
71
+ lane's claim can move the target beneath it. Check target movement before
72
+ audit; when it matters, merge the target branch (main when selected) in the
73
+ worktree and resolve conflicts there before auditing.
74
+ - **Audit:** Previews the candidate and target without tendering or claiming.
75
+ With `verified` selected, Verification runs for the captured subject and can
76
+ record an attestation. Without that gate, the section is inert text and no
77
+ verb runs Verification. A stopped run records no new verdict.
78
+ - **Deliver:** Captures a tender and integration against the observed target;
79
+ journal gains a delivered candidate. Ready prerequisites and gates trigger
80
+ placement and claim in this invocation; otherwise the candidate waits.
81
+ Changed candidate content stales earlier review. Identical content retains
82
+ review across rebase or target movement.
83
+ - **Review:** Records verdict evidence for the current document and worktree
84
+ content, even before delivery. Satisfied review requests placement: with a
85
+ delivered candidate, current gates, and ready prerequisites, it accepts in
86
+ this invocation. Unsatisfied review records testimony without placement.
87
+ - **Abandon:** Records the alternate terminal outcome without accepting. Accepted
88
+ and abandoned Contracts cannot be reopened.
89
+
90
+ Placement judges declared gates, not the producer's identity. Review does not
91
+ replace Verification; audit never requests placement. Read the final receipt
92
+ for stops and reconciliation lag after an admitted act.
93
+
94
+ ## 5. Handing A Role To An Akuma
95
+
96
+ This is the one commissioning map. `call --help` owns the exact action
97
+ vocabulary and default set. The flagship acting directly needs no grant.
98
+ Birth freezes an Akuma's actions; `--contract` records association, not
99
+ authority.
100
+
101
+ | Role | Grant at birth | Return |
102
+ | --- | --- | --- |
103
+ | Holder | The actions the delegated loop will perform; include `contract.review` when this holder will review. Commission with the `kei`, current Arc when one exists, appointed worktree, and holder duties. | Acceptance or abandonment, with receipts. |
104
+ | Deliverer | The ordinary baseline: every Task mutation, Contract audit and delivery, and Akuma management. `keiyaku -C <repo> call worker --alias @deliverer --contract <kei/...> --workdir <appointed-path> -` | The delivery receipt. |
105
+ | Reviewer | `--allowed contract.review`: `keiyaku -C <repo> call review-akuma --alias @reviewer --contract <kei/...> --workdir <appointed-path> --allowed contract.review -` | The verdict receipt. Without the grant, `not-allowed` refuses and no verdict is recorded. |
106
+
107
+ An Archetype's explicit allowed set replaces the ordinary baseline; check
108
+ `status` for effective actions. `tell` and `fork` cannot add a grant to a live
109
+ Akuma, so call a fresh one with the grant. Nested calls cannot exceed their
110
+ direct parent's actions.
111
+
112
+ Commission with a clear objective, current Arc when one exists, appointed
113
+ worktree, and expected result. Never ask the Akuma that delivered a candidate
114
+ to review it. Use `keiyaku-akuma` for invocation and observation, and command
115
+ help for exact syntax.
116
+
117
+ ## 6. Decide What Happens Next
118
+
119
+ The holder checks candidate, verification, review, prerequisites, and gates.
120
+
121
+ - A ready delivered candidate claims automatically on delivery or satisfied
122
+ review; no separate claim command is needed.
123
+ - Missing evidence or unfinished work calls for another commission or chapter.
124
+ - Amend when the objective and acceptance boundary remain the same but terms
125
+ must change.
126
+ - Abandon and bind a new `kei` when the objective or acceptance boundary changes.
127
+
128
+ Read `keiyaku-bind` for authoring, `keiyaku-akuma` for delegation, and
129
+ `keiyaku-babysit` for supervising multiple lanes.
@@ -0,0 +1,6 @@
1
+ {
2
+ "name": "keiyaku-harness",
3
+ "version": "4.6.7",
4
+ "type": "module",
5
+ "main": "./index.js"
6
+ }
@@ -0,0 +1,44 @@
1
+ ---
2
+ name: keiyaku
3
+ description: >-
4
+ Keiyaku is a CLI that records plans, writes handoff terms for deliveries,
5
+ and calls delegates. Use this skill when you need to figure out which
6
+ Keiyaku skill or command to reach for.
7
+ ---
8
+
9
+ # Keiyaku
10
+
11
+ ## Model
12
+
13
+ Keiyaku is three independent pillars, not a bundle: **Task** remembers plans
14
+ and dependencies, **Contract** makes acceptance standing and auditable,
15
+ **Akuma** invokes capability. Use any one alone; combine them only when the
16
+ work calls for it. Behind every Contract in flight there is one holder of its
17
+ fulfillment loop — whoever turns intent into commissions and returns into
18
+ decisions. The flagship holds it by default, and may hand a whole Contract's
19
+ loop to one Aku in a single commission; the harness serves both styles
20
+ equally. See `keiyaku-workflow` for the loop, `keiyaku-bind` for authoring,
21
+ `keiyaku-akuma` for invocation.
22
+
23
+ ## Quick Start
24
+
25
+ ```bash
26
+ keiyaku -C <repo> task add "title"
27
+ keiyaku -C <repo> task start <task-id>
28
+ keiyaku -C <repo> bind [--task <task-id>] -
29
+ keiyaku -C <repo> status
30
+ keiyaku -C <repo> deliver [<contract>|@<contract>]
31
+ keiyaku -C <repo> review [<contract>|@<contract>] --satisfied
32
+ ```
33
+
34
+ `-C` selects the invocation cwd and therefore the World. `--repo <path>` only
35
+ selects the Contract repository; it never retargets that World. `call
36
+ --workdir <path>` selects execution cwd (relative to the effective invocation
37
+ cwd). Without it, the call uses the invocation cwd; `--contract` associates a
38
+ Contract without selecting an execution directory.
39
+
40
+ `deliver`, `review`, and `audit` may take time after their leading admission.
41
+ Their witnessed progress is ephemeral stderr output; stdout remains one final
42
+ text or JSON result. Ctrl-C asks the owned operation to stop and waits for its
43
+ truthful final receipt, so it is not evidence that an already admitted action
44
+ was rolled back.
@@ -0,0 +1,130 @@
1
+ ---
2
+ name: keiyaku-akuma
3
+ description: >-
4
+ Use when the work involves Akuma or Aku, or when you want other hands on
5
+ it: delegating a job, or fanning out research, checks, or other parallel
6
+ work.
7
+ ---
8
+
9
+ # Keiyaku Akuma
10
+
11
+ Use Akumas to delegate work to another worker. `call` creates a new Akuma;
12
+ `tell` admits a Tell for an existing Akuma; `ask` admits one and observes its
13
+ exact answer. Keep the complete AkuId, such as `aku/worker/1234abcd`, when you
14
+ need to address the same worker later. An alias such as `@reviewer` is a
15
+ shorter, world-local name.
16
+
17
+ ## Call a new Akuma
18
+
19
+ ```bash
20
+ keiyaku call worker "Summarize the recent changes in src/cli"
21
+ keiyaku call worker --alias @reviewer --wait 10m - < brief.md
22
+ keiyaku call worker
23
+ ```
24
+
25
+ The prompt is optional for prompt-free birth. Otherwise it is the new Akuma's
26
+ first prompt: give it as one argument, or use `-` to read stdin, never both.
27
+ Calls are detached by default: they return the new identity after birth without
28
+ waiting for the first answer. Use explicit `--wait <duration>` when this
29
+ invocation should block while observing that initial work. `--wait` only bounds
30
+ this command; it never stops the Akuma. Read `call --help` for flag syntax,
31
+ defaults, and action vocabulary.
32
+ To hand a Contract role to an Akuma, use the grant table in `keiyaku-workflow`.
33
+
34
+ The selected Akuma name is a reusable worker configuration, not an individual.
35
+ Calling it again creates an independent Akuma. Use different names for
36
+ capabilities, not merely for parallelism.
37
+
38
+ ## Commission Context
39
+
40
+ `--contract` only records the association. It does not tell the Akuma the
41
+ Contract or worktree. Put them in the prompt explicitly:
42
+
43
+ ```bash
44
+ keiyaku call worker --contract kei/add-rate-limit-a1b2 --workdir /path/to/worktree - <<'EOF'
45
+ Contract: kei/add-rate-limit-a1b2
46
+ Worktree: /path/to/worktree
47
+ This Arc: implement the limiter and its tests
48
+ EOF
49
+ ```
50
+
51
+ `--contract` does not choose a worktree. Use `--workdir <path>` when needed.
52
+
53
+ ## Tell or ask an existing Akuma
54
+
55
+ ```bash
56
+ keiyaku tell @reviewer "The candidate moved; re-examine the worktree"
57
+ keiyaku tell @reviewer --interrupt - < new-priority.md
58
+ keiyaku ask @reviewer --wait 10m "What is your verdict?"
59
+ keiyaku ask @reviewer --schema verdict.schema.json - < question.md
60
+ ```
61
+
62
+ `tell` admits the next instruction and returns its admission receipt; it does
63
+ not await an answer. `ask` admits a Tell and observes that exact answer,
64
+ unbounded unless `--wait` limits observation. Both require a prompt and accept
65
+ `--interrupt` to put down current work before admitting the new Tell. Schema
66
+ belongs only to `ask`; `tell --schema` and `tell --wait` refuse and point to
67
+ `ask`. A deadline never withdraws an admitted Tell. Read `tell --help` and
68
+ `ask --help` for the complete flag grammar.
69
+
70
+ ## Observe work
71
+
72
+ ```bash
73
+ keiyaku wait @deliverer @reviewer
74
+ keiyaku wait --all --timeout 30m @deliverer @reviewer
75
+ ```
76
+
77
+ Use `wait` for one or more existing Akumas. The default is `--any`; use
78
+ `--all` for every selected Akuma. `--timeout` limits observation and does not
79
+ stop workers. A completed Akuma already counts, so repeating a wait can return
80
+ immediately. See `wait --help` for the complete grammar. Unlike `ask`, `wait`
81
+ observes existing Akuma-wide work, not the answer to a newly admitted Tell.
82
+
83
+ ## Inspect and retrieve results
84
+
85
+ ```bash
86
+ keiyaku status
87
+ keiyaku status @reviewer
88
+ keiyaku ls aku/
89
+ keiyaku ls "aku/*/*"
90
+ keiyaku history @reviewer --last
91
+ keiyaku history @reviewer --id turn/3
92
+ ```
93
+
94
+ `status` shows the roster or one Akuma's workdir and effective actions.
95
+ `ls aku/` shows callable names; `ls "aku/*/*"` shows born workers.
96
+ `history --last` reads the latest complete answer; `history --id` reads an
97
+ exact result named by status or wait. Use the complete AkuId when an alias may
98
+ move; see `history --help` for paging.
99
+
100
+ ## Stop and branch
101
+
102
+ ```bash
103
+ keiyaku kill @reviewer
104
+ keiyaku fork @reviewer --at turn/3
105
+ ```
106
+
107
+ `kill` stops current work without admitting a Tell, deleting the Akuma, or
108
+ removing its history. `fork` creates a new Akuma from one exact retained
109
+ answered history point; the source is unchanged, and providers that cannot
110
+ fork report that refusal. See `kill --help` and `fork --help` for the
111
+ complete grammar.
112
+
113
+ ## JavaScript automation
114
+
115
+ Use [Automation With The Akuma API](references/automation.md) for a
116
+ task-specific JavaScript coordinator, structured answers, or multi-worker
117
+ orchestration. The CLI is enough for one commission and its return. A
118
+ prompt-free birth followed by one input-bound ask uses the same identity:
119
+
120
+ ```ts
121
+ import { Akuma, Akumas, World } from "@astrosheep/keiyaku";
122
+
123
+ const root = await World.at(process.cwd());
124
+ const called = await Akumas.of(root).call({ archetype: "worker" });
125
+ const worker = Akuma.select(root, called.akuma);
126
+ const result = await worker.ask("Inspect the change");
127
+ console.log(result.observation);
128
+ ```
129
+
130
+ The automation guide covers schema-based answer handling and longer workflows.