@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.
- package/build/integrations/marketplace/plugins/keiyaku/.claude-plugin/plugin.json +1 -1
- package/build/integrations/marketplace/plugins/keiyaku/.codex-plugin/plugin.json +1 -1
- package/build/integrations/marketplace/plugins/keiyaku/package.json +1 -1
- package/build/integrations/marketplace/plugins/keiyaku/skills/keiyaku/SKILL.md +3 -3
- package/build/integrations/marketplace/plugins/keiyaku/skills/keiyaku-akuma/SKILL.md +82 -163
- package/build/integrations/marketplace/plugins/keiyaku/skills/keiyaku-bind/SKILL.md +153 -78
- package/build/integrations/marketplace/plugins/keiyaku/skills/keiyaku-task/SKILL.md +68 -64
- package/build/integrations/marketplace/plugins/keiyaku/skills/keiyaku-workflow/SKILL.md +115 -146
- package/build/src/akuma/akuma-handle.d.ts +1 -0
- package/build/src/akuma/akuma-handle.js +4 -1
- package/build/src/akuma/akuma-observe.d.ts +6 -0
- package/build/src/akuma/akuma-observe.js +3 -1
- package/build/src/akuma/akuma.d.ts +1 -0
- package/build/src/akuma/akuma.js +1 -0
- package/build/src/akuma/fleet-execution.d.ts +7 -1
- package/build/src/akuma/fleet-execution.js +12 -11
- package/build/src/akuma/fleet-observation.d.ts +3 -0
- package/build/src/akuma/identity.js +11 -9
- package/build/src/alias/index.js +3 -3
- package/build/src/cli/commands/akuma-invoke.js +13 -4
- package/build/src/cli/commands/akuma.js +9 -15
- package/build/src/cli/commands/contract-help.d.ts +1 -0
- package/build/src/cli/commands/contract-help.js +1 -0
- package/build/src/cli/invoke.js +1 -1
- package/build/src/cli/render/akuma-activity.js +6 -1
- package/build/src/cli/render/akuma.d.ts +9 -0
- package/build/src/cli/render/akuma.js +48 -8
- package/build/src/identity/normalize.d.ts +3 -0
- package/build/src/identity/normalize.js +10 -0
- package/build/src/identity/selector.d.ts +1 -0
- package/build/src/identity/selector.js +15 -4
- package/build/src/library/address.js +2 -2
- package/build/src/library/akuma-creation.d.ts +1 -1
- package/build/src/library/akuma-creation.js +10 -52
- package/build/src/library/composition.d.ts +2 -1
- package/build/src/library/fleet.d.ts +2 -1
- package/build/src/library/fleet.js +7 -3
- package/build/src/library/keiyaku.d.ts +2 -1
- package/build/src/protocol/completion.js +9 -2
- package/package.json +1 -1
|
@@ -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
|
|
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,
|
|
48
|
-
|
|
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:
|
|
5
|
-
|
|
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
|
-
|
|
11
|
-
`
|
|
12
|
-
|
|
13
|
-
|
|
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
|
-
##
|
|
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
|
|
18
|
+
keiyaku -C <cwd> call <akuma-name> [--workdir <path>] [--alias <name>] [--allowed <product.action>]... [--schema <file>] [--wait <duration>] (<prompt> | -)
|
|
29
19
|
```
|
|
30
20
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
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
|
-
|
|
113
|
-
|
|
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
|
-
##
|
|
47
|
+
## Commission Context
|
|
117
48
|
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
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
|
-
`
|
|
126
|
-
|
|
127
|
-
|
|
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
|
|
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
|
-
|
|
140
|
-
|
|
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
|
-
##
|
|
72
|
+
## Observe work
|
|
143
73
|
|
|
144
74
|
```bash
|
|
145
|
-
keiyaku
|
|
146
|
-
keiyaku tell <aku/...|@alias> --interrupt (<prompt> | -)
|
|
75
|
+
keiyaku wait <selector>... [--any | --all] [--timeout <duration>]
|
|
147
76
|
```
|
|
148
77
|
|
|
149
|
-
|
|
150
|
-
for
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
167
|
-
|
|
168
|
-
|
|
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
|
-
|
|
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`
|
|
189
|
-
|
|
190
|
-
|
|
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
|
-
|
|
197
|
-
keiyaku fork <aku/...|@alias> --at <historyId> [--alias @name]
|
|
198
|
-
```
|
|
119
|
+
## JavaScript automation
|
|
199
120
|
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
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
|
-
|
|
5
|
-
|
|
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
|
|
8
|
+
# Before Binding A Keiyaku
|
|
9
9
|
|
|
10
|
-
|
|
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
|
-
|
|
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
|
-
|
|
15
|
+
Settle these facts first:
|
|
19
16
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
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
|
-
|
|
27
|
+
The Design section is a detailed design document. It may contain subsections
|
|
28
|
+
such as:
|
|
28
29
|
|
|
29
|
-
|
|
30
|
-
|
|
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
|
|
93
|
+
# <Delivery name>
|
|
35
94
|
|
|
36
95
|
## Context
|
|
37
|
-
<
|
|
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
|
|
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
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
<
|
|
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
|
-
<
|
|
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
|
-
### <
|
|
71
|
-
<
|
|
72
|
-
Decidable without consulting you.>
|
|
121
|
+
### <observable acceptance condition>
|
|
122
|
+
<How to observe pass or refusal.>
|
|
73
123
|
|
|
74
124
|
## Verification
|
|
75
|
-
```bash timeout
|
|
125
|
+
```bash timeout=5m
|
|
76
126
|
<commands runnable exactly as written>
|
|
77
127
|
```
|
|
78
128
|
KEIYAKU
|
|
79
129
|
~~~~
|
|
80
130
|
|
|
81
|
-
Use
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
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
|
-
|
|
87
|
-
|
|
88
|
-
|
|
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
|
|
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
|
-
|
|
98
|
-
|
|
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
|
-
##
|
|
174
|
+
## 3. After Binding
|
|
101
175
|
|
|
102
|
-
|
|
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
|
-
|
|
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
|
-
|
|
113
|
-
|
|
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
|
-
|
|
187
|
+
The holder now owns the lifecycle:
|
|
117
188
|
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
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
|
|
197
|
+
Continue with `keiyaku-workflow` for this lifecycle. For Akuma invocation,
|
|
198
|
+
telling, waiting, permissions, and history, read `keiyaku-akuma`.
|