@astrosheep/keiyaku 2.9.9 → 2.9.11

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 (230) hide show
  1. package/README.md +93 -174
  2. package/build/.tsbuildinfo +1 -1
  3. package/build/agents/harness/control-types.js +18 -1
  4. package/build/agents/harness/index.js +2 -0
  5. package/build/agents/harness/outcome-error.js +81 -0
  6. package/build/agents/harness/projection.js +2 -1
  7. package/build/agents/harness/router.js +5 -1
  8. package/build/agents/providers/claude-agent-sdk/adapter.js +18 -4
  9. package/build/agents/providers/claude-agent-sdk/registration.js +11 -1
  10. package/build/agents/providers/claude-agent-sdk/session.js +19 -5
  11. package/build/agents/providers/codex-app-server/adapter.js +11 -6
  12. package/build/agents/providers/codex-app-server/events.js +67 -6
  13. package/build/agents/providers/codex-app-server/registration.js +11 -1
  14. package/build/agents/providers/opencode-sdk/adapter.js +8 -1
  15. package/build/agents/providers/opencode-sdk/events.js +24 -2
  16. package/build/agents/providers/opencode-sdk/registration.js +11 -1
  17. package/build/agents/providers/pi/checkpoint.js +9 -1
  18. package/build/agents/providers/pi/events.js +2 -0
  19. package/build/agents/providers/pi/registration.js +14 -1
  20. package/build/cli/commands/akuma/akuma/handler.js +1 -1
  21. package/build/cli/commands/akuma/akuma/meta.js +3 -3
  22. package/build/cli/commands/akuma/catalog.js +2 -2
  23. package/build/cli/commands/akuma/{view → show}/handler.js +5 -5
  24. package/build/cli/commands/akuma/{view → show}/meta.js +3 -3
  25. package/build/cli/commands/akuma.js +1 -1
  26. package/build/cli/commands/contract/amend/handler.js +5 -4
  27. package/build/cli/commands/contract/arc/handler.js +5 -4
  28. package/build/cli/commands/contract/audit/handler.js +2 -2
  29. package/build/cli/commands/contract/bind/handler.js +12 -3
  30. package/build/cli/commands/contract/bind/meta.js +45 -15
  31. package/build/cli/commands/contract/forfeit/handler.js +9 -5
  32. package/build/cli/commands/contract/log/handler.js +2 -2
  33. package/build/cli/commands/contract/petition/handler.js +34 -7
  34. package/build/cli/commands/contract/renew/handler.js +7 -7
  35. package/build/cli/commands/contract/renew/meta.js +3 -3
  36. package/build/cli/commands/metadata.js +10 -6
  37. package/build/cli/commands/projection/call/meta.js +1 -1
  38. package/build/cli/commands/projection/catalog.js +2 -0
  39. package/build/cli/commands/projection/history/handler.js +21 -0
  40. package/build/cli/commands/projection/history/meta.js +9 -0
  41. package/build/cli/commands/projection/shared.js +3 -4
  42. package/build/cli/commands/projection/status/handler.js +3 -3
  43. package/build/cli/commands/projection/wait/handler.js +20 -11
  44. package/build/cli/commands/task/add/handler.js +14 -5
  45. package/build/cli/commands/task/add/meta.js +2 -2
  46. package/build/cli/commands/task/catalog.js +4 -0
  47. package/build/cli/commands/task/done/handler.js +1 -4
  48. package/build/cli/commands/task/done/meta.js +1 -1
  49. package/build/cli/commands/task/drop/meta.js +1 -1
  50. package/build/cli/commands/task/hold/handler.js +3 -0
  51. package/build/cli/commands/task/hold/meta.js +8 -0
  52. package/build/cli/commands/task/log/handler.js +1 -1
  53. package/build/cli/commands/task/log/meta.js +2 -2
  54. package/build/cli/commands/task/resume/handler.js +3 -0
  55. package/build/cli/commands/task/resume/meta.js +8 -0
  56. package/build/cli/commands/task/shared.js +39 -14
  57. package/build/cli/commands/task/show/handler.js +1 -1
  58. package/build/cli/commands/task/show/meta.js +1 -1
  59. package/build/cli/commands/task/start/meta.js +1 -1
  60. package/build/cli/commands/task/stop/handler.js +1 -4
  61. package/build/cli/commands/task/stop/meta.js +1 -1
  62. package/build/cli/commands/task/update/handler.js +11 -3
  63. package/build/cli/commands/task/update/meta.js +3 -3
  64. package/build/cli/completion.js +3 -2
  65. package/build/cli/flags.js +51 -14
  66. package/build/cli/help.js +4 -1
  67. package/build/cli/index.js +40 -25
  68. package/build/cli/parse-flags.js +40 -7
  69. package/build/cli/parse-metadata.js +5 -2
  70. package/build/cli/parse-selectors.js +2 -3
  71. package/build/cli/parse.js +40 -6
  72. package/build/cli/projection-address.js +12 -10
  73. package/build/cli/render/amendment-warning.js +8 -0
  74. package/build/cli/render/arc.js +6 -2
  75. package/build/cli/render/audit.js +400 -81
  76. package/build/cli/render/kanshi.js +6 -1
  77. package/build/cli/render/lifecycle.js +56 -0
  78. package/build/cli/render/misc.js +24 -28
  79. package/build/cli/render/petition.js +5 -0
  80. package/build/cli/render/projection-activity.js +3 -2
  81. package/build/cli/render/projection-history.js +64 -0
  82. package/build/cli/render/shared.js +23 -9
  83. package/build/cli/render/status.js +9 -16
  84. package/build/cli/render/task.js +51 -26
  85. package/build/cli/render/terminal-failure.js +3 -1
  86. package/build/cli/render/wait.js +3 -5
  87. package/build/cli/subagent-guard.js +1 -1
  88. package/build/cli/types.js +1 -1
  89. package/build/config/env-keys.js +2 -0
  90. package/build/config/env.js +23 -0
  91. package/build/config/settings/schema.js +3 -1
  92. package/build/core/address-carrier.js +89 -0
  93. package/build/core/addressing.js +255 -196
  94. package/build/core/amend.js +115 -38
  95. package/build/core/amendment-criteria.js +17 -0
  96. package/build/core/amendment-warning.js +10 -0
  97. package/build/core/arc.js +184 -83
  98. package/build/core/audit/candidate.js +110 -9
  99. package/build/core/audit/coordinates.js +120 -65
  100. package/build/core/audit/evidence.js +19 -23
  101. package/build/core/audit/facade.js +34 -11
  102. package/build/core/audit/report.js +5 -5
  103. package/build/core/bind-reconciliation.js +390 -0
  104. package/build/core/bind-workspace.js +12 -20
  105. package/build/core/bind.js +242 -273
  106. package/build/core/call/call.js +1 -0
  107. package/build/core/call/context.js +46 -71
  108. package/build/core/call/prompt.js +6 -3
  109. package/build/core/context.js +49 -35
  110. package/build/core/contract-carrier-runtime.js +408 -0
  111. package/build/core/contract-carrier.js +270 -0
  112. package/build/core/contract-view.js +33 -27
  113. package/build/core/contract.js +5 -1
  114. package/build/core/derived-replay.js +207 -0
  115. package/build/core/draft.js +125 -57
  116. package/build/core/forfeit.js +113 -56
  117. package/build/core/identifier-slug.js +63 -13
  118. package/build/core/ids.js +4 -4
  119. package/build/core/lifecycle-history.js +35 -0
  120. package/build/core/lifecycle-recovery.js +117 -0
  121. package/build/core/lifecycle-runner.js +377 -0
  122. package/build/core/log.js +37 -11
  123. package/build/core/outcome-base.js +181 -0
  124. package/build/core/process-group.js +139 -0
  125. package/build/core/projection/generation/database.js +82 -7
  126. package/build/core/projection/generation/model.js +9 -36
  127. package/build/core/projection/generation/projection-generation-continuation.js +10 -22
  128. package/build/core/projection/generation/projection-generation-execution.js +6 -5
  129. package/build/core/projection/index.js +5 -4
  130. package/build/core/projection/projection-activity.js +27 -8
  131. package/build/core/projection/projection-alias.js +23 -10
  132. package/build/core/projection/projection-core.js +21 -7
  133. package/build/core/projection/projection-execution-observer.js +91 -39
  134. package/build/core/projection/projection-history.js +474 -0
  135. package/build/core/projection/projection-runner-lock.js +12 -0
  136. package/build/core/projection/projection-status-observation.js +365 -0
  137. package/build/core/projection/projection-status.js +21 -358
  138. package/build/core/projection/projection-terminal-failure.js +13 -8
  139. package/build/core/projection/projection-wait.js +7 -2
  140. package/build/core/projection/tell/launch-store.js +244 -0
  141. package/build/core/projection/tell/model.js +3 -3
  142. package/build/core/projection/tell/store.js +70 -118
  143. package/build/core/registry.js +22 -87
  144. package/build/core/renew-build.js +424 -0
  145. package/build/core/renew-plan.js +239 -0
  146. package/build/core/renew-rewrite.js +77 -0
  147. package/build/core/renew.js +295 -520
  148. package/build/core/repository-ledger/accepted-fold-read.js +19 -0
  149. package/build/core/repository-ledger/accepted-tail.js +116 -0
  150. package/build/core/repository-ledger/admission.js +38 -0
  151. package/build/core/repository-ledger/authoritative-transaction.js +1 -0
  152. package/build/core/repository-ledger/claim-evidence.js +147 -0
  153. package/build/core/repository-ledger/codec.js +297 -0
  154. package/build/core/repository-ledger/current-state-store.js +853 -0
  155. package/build/core/repository-ledger/fold-repository.js +375 -0
  156. package/build/core/repository-ledger/fold.js +248 -0
  157. package/build/core/repository-ledger/git-object-store.js +243 -0
  158. package/build/core/repository-ledger/history-read.js +15 -0
  159. package/build/core/repository-ledger/incremental-read.js +153 -0
  160. package/build/core/repository-ledger/index.js +15 -0
  161. package/build/core/repository-ledger/inventory-plan.js +75 -0
  162. package/build/core/repository-ledger/inventory.js +310 -0
  163. package/build/core/repository-ledger/publication-admission.js +125 -0
  164. package/build/core/repository-ledger/publication.js +353 -0
  165. package/build/core/repository-ledger/read-model.js +469 -0
  166. package/build/core/repository-ledger/transaction-membership.js +78 -0
  167. package/build/core/repository-ledger/traversal.js +404 -0
  168. package/build/core/repository-ledger/write-transaction.js +339 -0
  169. package/build/core/seal.js +168 -161
  170. package/build/core/settlement/claim-delivery.js +42 -215
  171. package/build/core/settlement/claim.js +235 -153
  172. package/build/core/settlement/index.js +4 -4
  173. package/build/core/settlement/petition-claim-gates.js +52 -33
  174. package/build/core/settlement/petition-forfeit.js +12 -5
  175. package/build/core/settlement/petition-head-guard.js +8 -5
  176. package/build/core/settlement/petition-preview.js +68 -56
  177. package/build/core/settlement/petition-window.js +50 -0
  178. package/build/core/settlement/petition.js +252 -131
  179. package/build/core/settlement/queue-read-model.js +72 -95
  180. package/build/core/settlement/queue-seat-allocation.js +35 -126
  181. package/build/core/settlement/queue.js +1 -1
  182. package/build/core/settlement/settlement.js +172 -80
  183. package/build/core/settlement/verdict.js +112 -66
  184. package/build/core/settlement/verification-coordination.js +305 -0
  185. package/build/core/settlement/verification-supervisor.js +275 -0
  186. package/build/core/settlement/verification.js +398 -31
  187. package/build/core/status/board.js +114 -119
  188. package/build/core/status/lifecycle.js +7 -80
  189. package/build/core/structured-query.js +23 -0
  190. package/build/core/target-ref.js +1 -1
  191. package/build/core/task/board.js +59 -24
  192. package/build/core/task/commands.js +181 -33
  193. package/build/core/task/coordinate.js +56 -0
  194. package/build/core/task/document.js +25 -9
  195. package/build/core/task/index.js +7 -4
  196. package/build/core/task/query.js +17 -27
  197. package/build/core/task/settlement-git.js +164 -179
  198. package/build/core/task/settlement-policy.js +15 -11
  199. package/build/core/task/source-board.js +31 -13
  200. package/build/core/task/task-bind-preparation.js +193 -0
  201. package/build/core/task/task-contract.js +102 -193
  202. package/build/core/task/task-file-transaction.js +171 -0
  203. package/build/core/task/task-git-runtime.js +76 -14
  204. package/build/core/task/task-git-store.js +68 -169
  205. package/build/core/task/task-store-repository.js +13 -6
  206. package/build/core/task/task-worktree.js +6 -33
  207. package/build/core/task/task.js +1 -1
  208. package/build/core/task/tree.js +3 -3
  209. package/build/core/task/validation.js +4 -3
  210. package/build/core/transcripts.js +93 -1
  211. package/build/core/worktree-bootstrap.js +44 -36
  212. package/build/core/worktree-path.js +210 -77
  213. package/build/flow-error.js +7 -7
  214. package/build/generated/version.js +2 -2
  215. package/build/git/core.js +76 -13
  216. package/build/git/refs.js +168 -46
  217. package/build/git/streaming-batch.js +73 -13
  218. package/package.json +1 -1
  219. package/skills/keiyaku/SKILL.md +1 -1
  220. package/skills/keiyaku-akuma/SKILL.md +3 -3
  221. package/skills/keiyaku-task/SKILL.md +4 -2
  222. package/skills/keiyaku-workflow/SKILL.md +88 -203
  223. package/build/core/entry.js +0 -305
  224. package/build/core/ledger-batch.js +0 -194
  225. package/build/core/ledger.js +0 -84
  226. package/build/core/projection/leash.js +0 -87
  227. package/build/core/ref-log.js +0 -119
  228. package/build/core/renew-session.js +0 -128
  229. package/build/core/status/ledger-batch.js +0 -1
  230. package/build/core/status/reconciliation.js +0 -137
@@ -1,251 +1,136 @@
1
1
  ---
2
2
  name: keiyaku-workflow
3
- description: Use when driving a Keiyaku contract — bind to start isolated work, arc/renew mid-flight, petition for review, claim or forfeit to finish.
3
+ description: Use when driving a Keiyaku contract — bind isolated work, use arc/renew mid-flight, audit a candidate, petition to settle, or forfeit.
4
4
  allowed-tools: Bash(keiyaku *)
5
5
  ---
6
6
 
7
7
  # Keiyaku Workflow
8
8
 
9
- How a contract lives. Running akuma is the `keiyaku-akuma` skill; task planning is `keiyaku-task`.
10
-
11
- ## Core ideas
12
-
13
- - A contract is one delivery intent with one ledger, branch, and linked worktree.
14
- - Workers edit and test; the host reviews their dirty tree and commits accepted bytes.
15
- - `audit` reads one pinned candidate. `petition` is the settlement action.
16
- - Scope is the smallest closure of files currently expected to be written. Amend
17
- newly expected exact paths before delivery.
18
- - An arc is a named story chapter for one coherent stretch inside the contract.
19
-
20
- Lifecycle:
21
-
22
- ```
23
- bound → active → petitioned → claimed | forfeited
9
+ ## Mindset
10
+
11
+ - One contract carries one delivery intent through one ledger, branch, and
12
+ linked worktree.
13
+ - Scope is the expected write set for this delivery, not code ownership or a
14
+ permission boundary.
15
+ - Criteria state what must be true. Verification supplies executable evidence.
16
+ - Implementation happens in the linked worktree. Commit accepted bytes before
17
+ `arc`, `renew`, or `petition`.
18
+ - An arc is a coherent chapter of the same delivery. It keeps the contract,
19
+ worktree, branch, and final settlement.
20
+ - `audit` reports evidence for one pinned candidate. `petition` asks to settle.
21
+
22
+ ```text
23
+ bound -> active -> petitioned -> claimed | forfeited
24
24
  ```
25
25
 
26
- ## Before Bind
27
-
28
- `bind` begins implementation from a settled executable contract.
29
-
30
- Before binding, complete the fact and decision work needed to state the delivery:
31
-
32
- - reproduce or otherwise establish the motivating fact;
33
- - read the registered authority and locate the current owning modules;
34
- - settle inputs, outputs, state consequences, failure behavior, invariants, and
35
- forbidden expansion;
36
- - identify the smallest expected write set and account for known write overlap
37
- and delivery dependencies; ownership remains with the authority registry and
38
- its owning chapter;
39
- - write checks that prove the critical success path, the highest-risk rejection,
40
- and the relevant durability, concurrency, or recovery boundary.
41
-
42
- Use tasks, fact scans, and bare read-only exploration while gathering evidence
43
- and settling decisions. Task `ready` reports that its dependencies are
44
- satisfied; the coordinator promotes it after establishing semantic contract
45
- readiness. Bind when Objective, Scope, and Checks describe one complete
46
- implementation journey and contain every product or architecture decision the
47
- worker needs.
26
+ ## Bind
48
27
 
49
- After bind, the worker implements and verifies that contract. `amend` records
50
- new evidence or a change of intent that genuinely emerges during implementation
51
- or review, then implementation continues from the updated contract.
28
+ Bind when one implementation journey is decided: motivating facts, owning
29
+ modules, inputs and outputs, consequences, failure behavior, invariants,
30
+ forbidden expansion, write set, acceptance criteria, and decisive checks.
31
+ Use a task only when planning or dependencies need a durable place.
52
32
 
53
- ## Choosing Scope
33
+ Declare the smallest useful Scope:
54
34
 
55
- Scope names the files this contract is currently expected to write, not a
56
- territory the contract owns. Choose the narrowest form supported by the
57
- evidence, in this order:
58
-
59
- 1. When the write set is known, list exact repository-relative paths, one per
60
- line. This is the default and needs no justification.
61
- 2. When filenames are not yet known but changes are scattered within one
62
- directory, use a one-component wildcard for that component.
63
- 3. Use the recursive wildcard only for a real whole-subtree rewrite, migration,
64
- or generated-output operation. The Objective must state why the entire tree
65
- is expected to change.
66
-
67
- Known files use exact paths:
35
+ 1. exact paths when known;
36
+ 2. a one-component wildcard when names inside one directory are still open;
37
+ 3. a recursive wildcard only for a real subtree rewrite, migration, or
38
+ generated output.
68
39
 
69
40
  ```bash
70
- keiyaku bind --place fix-pump --objective "make the pump test pass" \
71
- --scope "src/pump.ts" --scope "tests/unit/pump.test.ts" \
72
- --checks "pump tests green"
41
+ keiyaku bind - < contract.md
42
+ keiyaku bind --task TASK_ID - < contract.md
73
43
  ```
74
44
 
75
- Unknown filenames within one component may use a one-component wildcard:
45
+ The contract document carries `Title`, `Context`, `Objective`, `Design`,
46
+ `Scope`, `Criteria`, and optional `Verification`. Add newly expected exact paths
47
+ with `amend`; do not pre-authorize a broad tree for convenience.
76
48
 
77
- ```bash
78
- keiyaku bind --place repair-pump-fixtures --objective "repair the affected pump fixtures" \
79
- --scope "tests/fixtures/pump/*" --checks "pump fixture tests green"
80
- ```
49
+ ## Select The Contract
81
50
 
82
- A recursive pattern is reserved for an actual whole-tree operation:
51
+ Use `-C DIR` to select the effective directory. A contract worktree carries its
52
+ contract identity:
83
53
 
84
54
  ```bash
85
- keiyaku bind --place regenerate-api-docs \
86
- --objective "regenerate API documentation because the generator changes every file under docs/generated" \
87
- --scope "docs/generated/**" --checks "generated API docs are current"
55
+ keiyaku -C .keiyaku/wt/cloud audit
56
+ keiyaku -C .keiyaku/wt/cloud log
88
57
  ```
89
58
 
90
- If implementation evidence later identifies one more expected file, amend with
91
- that exact path:
59
+ From a repository hub, name the contract with `--contract ADDR` or `@ADDR`:
92
60
 
93
61
  ```bash
94
- keiyaku amend --append-scope "src/pump/metrics.ts" - < amendment.md
62
+ keiyaku -C /work/keiyaku --contract repair-status.01K... audit
95
63
  ```
96
64
 
97
- Amend is cheap. Broad Scope consumes parallel coordination and weakens audit
98
- signal, so moving to a broader pattern needs a reason; moving narrower does not.
65
+ `bind -C DIR` creates a new contract in the selected repository. Full contract
66
+ ID is durable identity; slug and place are convenience addresses.
99
67
 
100
- ## The default flow
68
+ ## Drive The Work
101
69
 
102
70
  ```bash
103
- keiyaku bind --place fix-pump --objective "make the pump test pass" \
104
- --scope "src/pump.ts" --scope "tests/unit/pump.test.ts" \
105
- --checks "pump tests green"
106
- # or the same four fields as Markdown: keiyaku bind - < contract.md
107
- # (# <name> / ## Objective / ## Scope / ## Checks)
108
- # or promote one or more ready tasks:
109
- keiyaku bind --task fix-parser --task fix-parser-help - < contract.md
110
-
111
- cd .keiyaku/wt/fix-pump # worker edits/tests here and leaves a dirty tree
71
+ keiyaku arc - < arc.md
72
+ keiyaku renew
73
+ keiyaku amend - < amendment.md
74
+ keiyaku log
75
+ keiyaku status
76
+ ```
112
77
 
113
- # Back on the host after reviewing the worker's diff and test report:
114
- git -C .keiyaku/wt/fix-pump add -- <accepted-paths>
115
- git -C .keiyaku/wt/fix-pump commit -m "fix pump"
78
+ - `arc` seals one coherent chapter and opens the next. It is not a child
79
+ contract or a parallel worktree.
80
+ - `renew` rebases onto an advanced target. Re-run verification after it.
81
+ - `amend` records a changed intent, invariant, Scope, Criteria, or Verification
82
+ before implementation relies on that change.
116
83
 
117
- # Rehearse the exact pinned delivery before settlement:
118
- keiyaku @fix-pump audit
84
+ Scope changes are ordered terms. Use flags for simple additions or one
85
+ `Scope Append` block for an ordered delta:
119
86
 
120
- keiyaku petition - <<'EOF'
121
- ## Oath
122
- I made the pump test pass; ran the suite, all green.
123
- EOF
124
- # petition seals your work (a seal = your commits + intent frozen into one
125
- # reviewable unit; arc and renew also seal) and runs the settlement pipeline —
126
- # passes → claimed (merged to main); a gate fails → fix, petition again.
127
- # The oath is required (OATH_MISSING otherwise) and checked for presence, not content.
87
+ ````markdown
88
+ ## Scope Append
128
89
  ```
129
-
130
- A task is optional planning, not a prerequisite. Bind settled new work directly;
131
- use `--task` when promoting existing tracked planning after the same readiness
132
- judgment.
133
-
134
- That's the whole small case: bind → worker dirty-tree handoff → host review/commit → petition.
135
-
136
- Multi-bind tasks only when they are evidence for the same delivery intent, share
137
- one coherent write surface, and should settle together. This reduces competing
138
- contracts/worktrees; it does not replace `needs` or contract `--after` ordering.
139
-
140
- `audit` is read-only and never invokes an Akuma or settles the contract. Exit 0
141
- means it constructed the report, not that the candidate is acceptable. Use
142
- `--diff-budget BYTES` when bounded diff evidence is useful.
143
-
144
- Commissioned workers never write Git metadata. The host alone reviews and
145
- commits accepted bytes before `arc`, `renew`, or `petition`.
146
-
147
- Dispatch rule: every time a dispatcher sends a worker, whether through
148
- `keiyaku call` or any other agent tool, the prompt must explicitly tell that
149
- worker to read the worktree-root `.keiyaku/KEIYAKU.md` first and follow its
150
- objective, scope, and checks. The file is the contract-body carrier; do not
151
- copy its rendered body into a dispatch prompt.
152
-
153
- ## Review findings
154
-
155
- Review findings are evidence for diagnosis, not a queue of local patches. Before
156
- changing code, classify each finding as a contract hole, missing invariant or
157
- owner, execution slip, test gap, or provider/capability failure. A second
158
- finding in the same transition, a race that crosses module owners, or a finding
159
- that contradicts the contract is a root-cause signal: stop symptom patching,
160
- record the governing invariant and ownership correction with `amend`, and
161
- refactor the boundary before sending another tell or accepting another diff.
162
-
163
- A default review dispatch is:
164
-
165
- > First read the worktree-root `.keiyaku/KEIYAKU.md`. Review the candidate end
166
- > to end against the contract and repository law. On every review round, treat
167
- > the current candidate as a new complete implementation: reassess its overall
168
- > coherence and regression risks rather than checking only whether prior
169
- > findings were patched. Report material findings first. For each problem,
170
- > explain the underlying cause and recommend a root-cause correction direction,
171
- > not a patch-sized edit. If the evidence is insufficient, state what remains
172
- > unknown. Do not modify files or Git metadata.
173
-
174
- Add candidate-specific evidence only when it helps the reviewer judge coverage;
175
- do not copy the contract body or seed an expected defect. Reviewer suggestions
176
- inform the coordinator's judgment but do not amend the contract. The
177
- coordinator owns the final diagnosis; a worker may implement a settled
178
- correction but may not invent a new state machine or compatibility rule.
179
-
180
- Do not claim a contract while related findings remain unresolved merely because
181
- each individual test or patch passes. Re-run the focused interleaving or
182
- boundary evidence and an independent review against the corrected ownership
183
- model. Repeated tells that only add guards to the same disputed path are not
184
- progress; if the contract cannot express the required invariant, amend or
185
- forfeit and bind a coherent replacement.
186
-
187
- After a worker fixes review findings, prefer telling the same review projection
188
- to re-check those findings and the corrected candidate. Start a fresh reviewer
189
- only when the earlier projection is unavailable or incompatible, its context is
190
- no longer trustworthy, or a genuinely fresh independent perspective is useful.
191
- This is an efficiency preference, not an acceptance gate.
192
-
193
- ## Mid-flight commands (use when needed, skip otherwise)
194
-
195
- ```bash
196
- keiyaku arc - < arc.md # optional iteration boundary: seals the current intent, opens
197
- # the next. Markdown: # <title> / ## Objective / ## Brief.
198
- # Only needed when one contract has multiple distinct pushes.
199
- keiyaku renew # main moved under you → rebase onto it. Refuses on conflict
200
- # instead of guessing; resolve, then renew again.
201
- keiyaku amend - < amendment.md # scope/checks changed → update the paper before the code
202
- keiyaku log # this contract's history
90
+ src/new-owner.ts
91
+ !src/retired/**
203
92
  ```
93
+ ````
204
94
 
205
- `amend` accepts prose plus one optional ordered scope-pattern delta. Use either
206
- repeated flags:
95
+ Later `!pattern` terms narrow earlier matches. Do not mix the block with
96
+ `--append-scope` flags.
207
97
 
208
- ```sh
209
- keiyaku amend --append-scope "docs/api-reference.md" --append-scope "!docs/obsolete-api-reference.md" - < amendment.md
210
- ```
98
+ After an explicit arc seal, commit any new work and open the next arc before
99
+ `renew` or `petition`.
211
100
 
212
- or a document section:
101
+ ## Review
213
102
 
214
- ````markdown
215
- Clarify the newly expected documentation files.
103
+ Review the complete candidate against the contract and repository law on every
104
+ round. Findings identify a contract hole, missing owner or invariant, execution
105
+ slip, test gap, or provider failure. Correct the governing model when the owner,
106
+ flow, commit point, failure outcomes, obsolete paths, or proof matrix is wrong;
107
+ use `amend` when the contract must change.
216
108
 
217
- ## Scope Append
218
- ~~~
219
- docs/api-reference.md
220
- !docs/obsolete-api-reference.md
221
- ~~~
222
- ````
109
+ Ask reviewers for material findings with file references and root-cause
110
+ direction. Reviewers do not modify files or amend the contract. Keep related
111
+ findings open until the corrected candidate and focused boundary evidence have
112
+ been reviewed again.
223
113
 
224
- `Scope Append` appends ordered raw gitignore-subset lines in one column-zero
225
- tilde fence; direct input also accepts a matching backtick fence. `Scope Add`
226
- and Markdown bullets are rejected. A later
227
- `!pattern` can narrow earlier scope. Flags and a document Scope Append block
228
- are mutually exclusive; plain amendment prose plus flags is valid. Use
229
- `--append-scope PATTERN` when a lifecycle operation discovers one durable term.
114
+ ## Settle
230
115
 
231
- Gotchas:
232
- - `-C DIR` selects the effective working directory; repository discovery starts there.
233
- - Base drift blocks ordinary petition. `petition --renew` runs the same renew
234
- first and settles only after that renew succeeds; it never auto-opens an arc.
235
- - After an explicit `arc` seals, new loose commits need another `arc` before `renew`/`petition` accept them.
236
- - Not in the worktree? Address a contract with `--contract ADDR` (place, slug, or full id) or the `keiyaku @addr <verb>` prefix.
237
-
238
- ## Ending it
116
+ Before settlement, renew if the target moved, then rerun the declared evidence.
117
+ `audit` is read-only; exit 0 means it produced a report, not that the candidate
118
+ passed. Petition requires an oath and runs the settlement gates:
239
119
 
240
120
  ```bash
241
- keiyaku forfeit --reason "superseded by fix-pump-v2"
242
- # abandon: worktree destroyed, history kept. Manual only — nothing auto-forfeits.
121
+ keiyaku audit
122
+ keiyaku petition - <<'EOF'
123
+ ## Oath
124
+ I completed the contract and verified the submitted candidate.
125
+ EOF
243
126
  ```
244
127
 
245
- There is no `claim` command: claiming is the tail of a passing petition.
246
-
247
- ## Reading status
128
+ A passing petition claims into the target. A failed gate leaves the contract
129
+ available for correction. End a superseded delivery explicitly:
248
130
 
249
131
  ```bash
250
- keiyaku status # every contract row: state, place, what to do next
132
+ keiyaku forfeit --reason "superseded by CONTRACT"
251
133
  ```
134
+
135
+ Forfeit preserves history and removes the contract worktree. There is no
136
+ separate `claim` command.
@@ -1,305 +0,0 @@
1
- import { z } from "zod";
2
- const SHA_RE = /^[0-9a-f]{7,40}$/i;
3
- const ISO_UTC_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
4
- const CONTRACT_ID_RE = /^\S+$/;
5
- const SUBJECT_RE = /^keiyaku: (bind|arc|seal|amend|renew|petition|verdict|claim|forfeit|bootstrap) ([^\s]+)$/;
6
- const shaSchema = z.string().regex(SHA_RE, "expected git sha");
7
- const isoUtcSchema = z.string().regex(ISO_UTC_RE, "expected ISO 8601 UTC timestamp");
8
- const nonEmptyString = z.string().trim().min(1);
9
- const nonBlankString = z.string().refine((value) => value.trim().length > 0, "expected non-empty string");
10
- // Scope patterns are gitignore text: do not trim, or escaped trailing spaces (`foo\ `) are destroyed.
11
- const scopePatternString = z
12
- .string()
13
- .refine((value) => value.trim().length > 0, "expected non-empty scope pattern");
14
- // Catalog base (2-13 lowercase letters) or generation overflow base2, base3, ...
15
- const placeSchema = z.string().regex(/^[a-z]{2,13}(?:[2-9]|[1-9][0-9]+)?$/);
16
- export const entryKindSchema = z.enum([
17
- "bind",
18
- "arc",
19
- "seal",
20
- "amend",
21
- "renew",
22
- "petition",
23
- "verdict",
24
- "claim",
25
- "forfeit",
26
- "bootstrap",
27
- ]);
28
- const diffstatSchema = z
29
- .object({
30
- files: z.number().int().nonnegative(),
31
- insertions: z.number().int().nonnegative(),
32
- deletions: z.number().int().nonnegative(),
33
- })
34
- .strict();
35
- const scopeAuditSchema = z
36
- .object({
37
- violations: z.array(nonEmptyString),
38
- })
39
- .strict();
40
- export const fullBranchRefSchema = z
41
- .string()
42
- .regex(/^refs\/heads\/\S+$/, "expected full branch ref");
43
- export const bindBootstrapPlanSchema = z
44
- .object({
45
- command: z.array(nonEmptyString).min(1),
46
- timeoutMs: z.number().int().min(1).max(3_600_000),
47
- })
48
- .strict();
49
- export const bindEntryDataSchema = z
50
- .object({
51
- name: nonEmptyString,
52
- objective: nonEmptyString,
53
- scope: z.array(scopePatternString).min(1),
54
- checks: z.array(nonBlankString).min(1),
55
- extensions: z
56
- .array(z
57
- .object({
58
- title: nonBlankString,
59
- content: z.string(),
60
- })
61
- .strict()),
62
- base: shaSchema,
63
- target: fullBranchRefSchema,
64
- workspace: z.enum(["worktree", "here"]),
65
- after: z.array(nonEmptyString).optional(),
66
- place: placeSchema.nullable().optional(),
67
- bootstrap: bindBootstrapPlanSchema.optional(),
68
- })
69
- .strict();
70
- const bootstrapExitResultSchema = z
71
- .object({
72
- kind: z.literal("exit"),
73
- code: z.number().int().min(0).max(255),
74
- })
75
- .strict();
76
- const bootstrapSignalResultSchema = z
77
- .object({
78
- kind: z.literal("signal"),
79
- signal: z.string().min(1),
80
- })
81
- .strict();
82
- const bootstrapTimeoutResultSchema = z
83
- .object({
84
- kind: z.literal("timeout"),
85
- })
86
- .strict();
87
- const bootstrapSpawnResultSchema = z
88
- .object({
89
- kind: z.literal("spawn"),
90
- message: z.string(),
91
- })
92
- .strict();
93
- export const bootstrapResultSchema = z.discriminatedUnion("kind", [
94
- bootstrapExitResultSchema,
95
- bootstrapSignalResultSchema,
96
- bootstrapTimeoutResultSchema,
97
- bootstrapSpawnResultSchema,
98
- ]);
99
- export const bootstrapEntryDataSchema = z
100
- .object({
101
- result: bootstrapResultSchema,
102
- durationMs: z
103
- .number()
104
- .int()
105
- .nonnegative()
106
- .refine((value) => Number.isSafeInteger(value), "durationMs must be a safe integer"),
107
- stderrTail: z.string().optional(),
108
- stderrTruncated: z.boolean().optional(),
109
- })
110
- .strict();
111
- export const arcEntryDataSchema = z
112
- .object({
113
- arc: z.number().int().positive(),
114
- title: nonEmptyString,
115
- objective: nonEmptyString,
116
- brief: nonEmptyString,
117
- })
118
- .strict();
119
- export const sealEntryDataSchema = z
120
- .object({
121
- arc: z.number().int().nonnegative(),
122
- sealedBy: z.enum(["arc", "renew", "petition"]),
123
- oldFence: shaSchema,
124
- newFence: shaSchema,
125
- receipts: z.array(shaSchema),
126
- diffstat: diffstatSchema,
127
- scopeAudit: scopeAuditSchema,
128
- })
129
- .strict();
130
- export const amendEntryDataSchema = z
131
- .object({
132
- amendment: nonBlankString,
133
- scopeDelta: z
134
- .object({
135
- add: z.array(scopePatternString),
136
- })
137
- .strict()
138
- .optional(),
139
- })
140
- .strict();
141
- export const renewEntryDataSchema = z
142
- .object({
143
- oldBase: shaSchema,
144
- newBase: shaSchema,
145
- oldHead: shaSchema,
146
- newHead: shaSchema,
147
- })
148
- .strict();
149
- const positiveSafeSeatSchema = z
150
- .number()
151
- .int()
152
- .positive()
153
- .refine((value) => Number.isSafeInteger(value), "seat must be a positive safe integer");
154
- // Current petitions always carry target + seat. Legacy residuals omit both and
155
- // exist only for diagnostic/rejection paths — never for production writers.
156
- export const petitionEntryDataSchema = z.union([
157
- z
158
- .object({
159
- intent: z.literal("claim"),
160
- oath: nonEmptyString,
161
- target: fullBranchRefSchema,
162
- seat: positiveSafeSeatSchema,
163
- })
164
- .strict(),
165
- z
166
- .object({
167
- intent: z.literal("forfeit"),
168
- target: fullBranchRefSchema,
169
- seat: positiveSafeSeatSchema,
170
- })
171
- .strict(),
172
- z
173
- .object({
174
- intent: z.literal("claim"),
175
- oath: nonEmptyString,
176
- })
177
- .strict(),
178
- z
179
- .object({
180
- intent: z.literal("forfeit"),
181
- })
182
- .strict(),
183
- ]);
184
- export const verdictEntryDataSchema = z
185
- .object({
186
- result: z.enum(["approved", "rejected"]),
187
- summary: nonEmptyString,
188
- })
189
- .strict();
190
- export const claimEntryDataSchema = z
191
- .object({
192
- mergeCommit: shaSchema,
193
- })
194
- .strict();
195
- export const forfeitEntryDataSchema = z
196
- .object({
197
- reason: z.enum(["manual", "bind-failed"]),
198
- by: nonEmptyString,
199
- note: nonEmptyString.optional(),
200
- })
201
- .strict();
202
- function makeEntrySchema(kind, data, version = 1) {
203
- return z
204
- .object({
205
- v: z.literal(version),
206
- kind: z.literal(kind),
207
- contract: z.string().trim().regex(CONTRACT_ID_RE, "contract id cannot contain whitespace"),
208
- at: isoUtcSchema,
209
- actor: nonEmptyString,
210
- data,
211
- })
212
- .strict();
213
- }
214
- export const bindEntrySchema = makeEntrySchema("bind", bindEntryDataSchema);
215
- export const arcEntrySchema = makeEntrySchema("arc", arcEntryDataSchema);
216
- export const sealEntrySchema = makeEntrySchema("seal", sealEntryDataSchema, 2);
217
- export const amendEntrySchema = makeEntrySchema("amend", amendEntryDataSchema);
218
- export const renewEntrySchema = makeEntrySchema("renew", renewEntryDataSchema);
219
- export const petitionEntrySchema = makeEntrySchema("petition", petitionEntryDataSchema);
220
- export const verdictEntrySchema = makeEntrySchema("verdict", verdictEntryDataSchema);
221
- export const claimEntrySchema = makeEntrySchema("claim", claimEntryDataSchema);
222
- export const forfeitEntrySchema = makeEntrySchema("forfeit", forfeitEntryDataSchema);
223
- export const bootstrapEntrySchema = makeEntrySchema("bootstrap", bootstrapEntryDataSchema);
224
- export const ledgerEntrySchema = z.discriminatedUnion("kind", [
225
- bindEntrySchema,
226
- arcEntrySchema,
227
- sealEntrySchema,
228
- amendEntrySchema,
229
- renewEntrySchema,
230
- petitionEntrySchema,
231
- verdictEntrySchema,
232
- claimEntrySchema,
233
- forfeitEntrySchema,
234
- bootstrapEntrySchema,
235
- ]);
236
- export class LedgerEntryFormatError extends Error {
237
- code = "INVALID_LEDGER_ENTRY_FORMAT";
238
- constructor(message, options) {
239
- super(message, options);
240
- this.name = "LedgerEntryFormatError";
241
- }
242
- }
243
- export class LedgerEntrySchemaError extends Error {
244
- code = "INVALID_LEDGER_ENTRY_SCHEMA";
245
- constructor(message, options) {
246
- super(message, options);
247
- this.name = "LedgerEntrySchemaError";
248
- }
249
- }
250
- export function formatLedgerEntrySubject(entry) {
251
- return `keiyaku: ${entry.kind} ${entry.contract}`;
252
- }
253
- export function formatLedgerEntryCommitMessage(entry) {
254
- const result = ledgerEntrySchema.safeParse(entry);
255
- if (!result.success) {
256
- throw new LedgerEntrySchemaError(`ledger entry schema validation failed: ${result.error.message}`, {
257
- cause: result.error,
258
- });
259
- }
260
- return `${formatLedgerEntrySubject(result.data)}\n\n${JSON.stringify(result.data, null, 2)}\n`;
261
- }
262
- export function parseLedgerEntryCommitMessage(message) {
263
- const normalized = message.replace(/\r\n/g, "\n");
264
- const separatorIndex = normalized.indexOf("\n\n");
265
- if (separatorIndex < 0) {
266
- throw new LedgerEntryFormatError("ledger entry commit message must contain a blank line before the JSON body");
267
- }
268
- const subject = normalized.slice(0, separatorIndex).trim();
269
- const subjectMatch = SUBJECT_RE.exec(subject);
270
- if (!subjectMatch) {
271
- throw new LedgerEntryFormatError("ledger entry subject must match 'keiyaku: <kind> <contract>'");
272
- }
273
- const body = normalized.slice(separatorIndex + 2).trim();
274
- let parsed;
275
- try {
276
- parsed = JSON.parse(body);
277
- }
278
- catch (error) {
279
- throw new LedgerEntryFormatError("ledger entry JSON body is not valid JSON", { cause: error });
280
- }
281
- if (typeof parsed === "object" && parsed !== null && Object.hasOwn(parsed, "repoId")) {
282
- const { repoId: _legacyRepoId, ...current } = parsed;
283
- parsed = current;
284
- }
285
- if (typeof parsed === "object" && parsed !== null &&
286
- parsed.kind === "amend") {
287
- const data = parsed.data;
288
- const scopeDelta = typeof data === "object" && data !== null
289
- ? data.scopeDelta
290
- : undefined;
291
- if (typeof scopeDelta === "object" && scopeDelta !== null && Object.hasOwn(scopeDelta, "remove")) {
292
- throw new LedgerEntrySchemaError("ledger entry schema validation failed: scopeDelta.remove is obsolete; ledger row is corrupt");
293
- }
294
- }
295
- const result = ledgerEntrySchema.safeParse(parsed);
296
- if (!result.success) {
297
- throw new LedgerEntrySchemaError(`ledger entry schema validation failed: ${result.error.message}`, {
298
- cause: result.error,
299
- });
300
- }
301
- if (result.data.kind !== subjectMatch[1] || result.data.contract !== subjectMatch[2]) {
302
- throw new LedgerEntryFormatError("ledger entry subject does not match the JSON body");
303
- }
304
- return result.data;
305
- }