@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.
- package/README.md +93 -174
- package/build/.tsbuildinfo +1 -1
- package/build/agents/harness/control-types.js +18 -1
- package/build/agents/harness/index.js +2 -0
- package/build/agents/harness/outcome-error.js +81 -0
- package/build/agents/harness/projection.js +2 -1
- package/build/agents/harness/router.js +5 -1
- package/build/agents/providers/claude-agent-sdk/adapter.js +18 -4
- package/build/agents/providers/claude-agent-sdk/registration.js +11 -1
- package/build/agents/providers/claude-agent-sdk/session.js +19 -5
- package/build/agents/providers/codex-app-server/adapter.js +11 -6
- package/build/agents/providers/codex-app-server/events.js +67 -6
- package/build/agents/providers/codex-app-server/registration.js +11 -1
- package/build/agents/providers/opencode-sdk/adapter.js +8 -1
- package/build/agents/providers/opencode-sdk/events.js +24 -2
- package/build/agents/providers/opencode-sdk/registration.js +11 -1
- package/build/agents/providers/pi/checkpoint.js +9 -1
- package/build/agents/providers/pi/events.js +2 -0
- package/build/agents/providers/pi/registration.js +14 -1
- package/build/cli/commands/akuma/akuma/handler.js +1 -1
- package/build/cli/commands/akuma/akuma/meta.js +3 -3
- package/build/cli/commands/akuma/catalog.js +2 -2
- package/build/cli/commands/akuma/{view → show}/handler.js +5 -5
- package/build/cli/commands/akuma/{view → show}/meta.js +3 -3
- package/build/cli/commands/akuma.js +1 -1
- package/build/cli/commands/contract/amend/handler.js +5 -4
- package/build/cli/commands/contract/arc/handler.js +5 -4
- package/build/cli/commands/contract/audit/handler.js +2 -2
- package/build/cli/commands/contract/bind/handler.js +12 -3
- package/build/cli/commands/contract/bind/meta.js +45 -15
- package/build/cli/commands/contract/forfeit/handler.js +9 -5
- package/build/cli/commands/contract/log/handler.js +2 -2
- package/build/cli/commands/contract/petition/handler.js +34 -7
- package/build/cli/commands/contract/renew/handler.js +7 -7
- package/build/cli/commands/contract/renew/meta.js +3 -3
- package/build/cli/commands/metadata.js +10 -6
- package/build/cli/commands/projection/call/meta.js +1 -1
- package/build/cli/commands/projection/catalog.js +2 -0
- package/build/cli/commands/projection/history/handler.js +21 -0
- package/build/cli/commands/projection/history/meta.js +9 -0
- package/build/cli/commands/projection/shared.js +3 -4
- package/build/cli/commands/projection/status/handler.js +3 -3
- package/build/cli/commands/projection/wait/handler.js +20 -11
- package/build/cli/commands/task/add/handler.js +14 -5
- package/build/cli/commands/task/add/meta.js +2 -2
- package/build/cli/commands/task/catalog.js +4 -0
- package/build/cli/commands/task/done/handler.js +1 -4
- package/build/cli/commands/task/done/meta.js +1 -1
- package/build/cli/commands/task/drop/meta.js +1 -1
- package/build/cli/commands/task/hold/handler.js +3 -0
- package/build/cli/commands/task/hold/meta.js +8 -0
- package/build/cli/commands/task/log/handler.js +1 -1
- package/build/cli/commands/task/log/meta.js +2 -2
- package/build/cli/commands/task/resume/handler.js +3 -0
- package/build/cli/commands/task/resume/meta.js +8 -0
- package/build/cli/commands/task/shared.js +39 -14
- package/build/cli/commands/task/show/handler.js +1 -1
- package/build/cli/commands/task/show/meta.js +1 -1
- package/build/cli/commands/task/start/meta.js +1 -1
- package/build/cli/commands/task/stop/handler.js +1 -4
- package/build/cli/commands/task/stop/meta.js +1 -1
- package/build/cli/commands/task/update/handler.js +11 -3
- package/build/cli/commands/task/update/meta.js +3 -3
- package/build/cli/completion.js +3 -2
- package/build/cli/flags.js +51 -14
- package/build/cli/help.js +4 -1
- package/build/cli/index.js +40 -25
- package/build/cli/parse-flags.js +40 -7
- package/build/cli/parse-metadata.js +5 -2
- package/build/cli/parse-selectors.js +2 -3
- package/build/cli/parse.js +40 -6
- package/build/cli/projection-address.js +12 -10
- package/build/cli/render/amendment-warning.js +8 -0
- package/build/cli/render/arc.js +6 -2
- package/build/cli/render/audit.js +400 -81
- package/build/cli/render/kanshi.js +6 -1
- package/build/cli/render/lifecycle.js +56 -0
- package/build/cli/render/misc.js +24 -28
- package/build/cli/render/petition.js +5 -0
- package/build/cli/render/projection-activity.js +3 -2
- package/build/cli/render/projection-history.js +64 -0
- package/build/cli/render/shared.js +23 -9
- package/build/cli/render/status.js +9 -16
- package/build/cli/render/task.js +51 -26
- package/build/cli/render/terminal-failure.js +3 -1
- package/build/cli/render/wait.js +3 -5
- package/build/cli/subagent-guard.js +1 -1
- package/build/cli/types.js +1 -1
- package/build/config/env-keys.js +2 -0
- package/build/config/env.js +23 -0
- package/build/config/settings/schema.js +3 -1
- package/build/core/address-carrier.js +89 -0
- package/build/core/addressing.js +255 -196
- package/build/core/amend.js +115 -38
- package/build/core/amendment-criteria.js +17 -0
- package/build/core/amendment-warning.js +10 -0
- package/build/core/arc.js +184 -83
- package/build/core/audit/candidate.js +110 -9
- package/build/core/audit/coordinates.js +120 -65
- package/build/core/audit/evidence.js +19 -23
- package/build/core/audit/facade.js +34 -11
- package/build/core/audit/report.js +5 -5
- package/build/core/bind-reconciliation.js +390 -0
- package/build/core/bind-workspace.js +12 -20
- package/build/core/bind.js +242 -273
- package/build/core/call/call.js +1 -0
- package/build/core/call/context.js +46 -71
- package/build/core/call/prompt.js +6 -3
- package/build/core/context.js +49 -35
- package/build/core/contract-carrier-runtime.js +408 -0
- package/build/core/contract-carrier.js +270 -0
- package/build/core/contract-view.js +33 -27
- package/build/core/contract.js +5 -1
- package/build/core/derived-replay.js +207 -0
- package/build/core/draft.js +125 -57
- package/build/core/forfeit.js +113 -56
- package/build/core/identifier-slug.js +63 -13
- package/build/core/ids.js +4 -4
- package/build/core/lifecycle-history.js +35 -0
- package/build/core/lifecycle-recovery.js +117 -0
- package/build/core/lifecycle-runner.js +377 -0
- package/build/core/log.js +37 -11
- package/build/core/outcome-base.js +181 -0
- package/build/core/process-group.js +139 -0
- package/build/core/projection/generation/database.js +82 -7
- package/build/core/projection/generation/model.js +9 -36
- package/build/core/projection/generation/projection-generation-continuation.js +10 -22
- package/build/core/projection/generation/projection-generation-execution.js +6 -5
- package/build/core/projection/index.js +5 -4
- package/build/core/projection/projection-activity.js +27 -8
- package/build/core/projection/projection-alias.js +23 -10
- package/build/core/projection/projection-core.js +21 -7
- package/build/core/projection/projection-execution-observer.js +91 -39
- package/build/core/projection/projection-history.js +474 -0
- package/build/core/projection/projection-runner-lock.js +12 -0
- package/build/core/projection/projection-status-observation.js +365 -0
- package/build/core/projection/projection-status.js +21 -358
- package/build/core/projection/projection-terminal-failure.js +13 -8
- package/build/core/projection/projection-wait.js +7 -2
- package/build/core/projection/tell/launch-store.js +244 -0
- package/build/core/projection/tell/model.js +3 -3
- package/build/core/projection/tell/store.js +70 -118
- package/build/core/registry.js +22 -87
- package/build/core/renew-build.js +424 -0
- package/build/core/renew-plan.js +239 -0
- package/build/core/renew-rewrite.js +77 -0
- package/build/core/renew.js +295 -520
- package/build/core/repository-ledger/accepted-fold-read.js +19 -0
- package/build/core/repository-ledger/accepted-tail.js +116 -0
- package/build/core/repository-ledger/admission.js +38 -0
- package/build/core/repository-ledger/authoritative-transaction.js +1 -0
- package/build/core/repository-ledger/claim-evidence.js +147 -0
- package/build/core/repository-ledger/codec.js +297 -0
- package/build/core/repository-ledger/current-state-store.js +853 -0
- package/build/core/repository-ledger/fold-repository.js +375 -0
- package/build/core/repository-ledger/fold.js +248 -0
- package/build/core/repository-ledger/git-object-store.js +243 -0
- package/build/core/repository-ledger/history-read.js +15 -0
- package/build/core/repository-ledger/incremental-read.js +153 -0
- package/build/core/repository-ledger/index.js +15 -0
- package/build/core/repository-ledger/inventory-plan.js +75 -0
- package/build/core/repository-ledger/inventory.js +310 -0
- package/build/core/repository-ledger/publication-admission.js +125 -0
- package/build/core/repository-ledger/publication.js +353 -0
- package/build/core/repository-ledger/read-model.js +469 -0
- package/build/core/repository-ledger/transaction-membership.js +78 -0
- package/build/core/repository-ledger/traversal.js +404 -0
- package/build/core/repository-ledger/write-transaction.js +339 -0
- package/build/core/seal.js +168 -161
- package/build/core/settlement/claim-delivery.js +42 -215
- package/build/core/settlement/claim.js +235 -153
- package/build/core/settlement/index.js +4 -4
- package/build/core/settlement/petition-claim-gates.js +52 -33
- package/build/core/settlement/petition-forfeit.js +12 -5
- package/build/core/settlement/petition-head-guard.js +8 -5
- package/build/core/settlement/petition-preview.js +68 -56
- package/build/core/settlement/petition-window.js +50 -0
- package/build/core/settlement/petition.js +252 -131
- package/build/core/settlement/queue-read-model.js +72 -95
- package/build/core/settlement/queue-seat-allocation.js +35 -126
- package/build/core/settlement/queue.js +1 -1
- package/build/core/settlement/settlement.js +172 -80
- package/build/core/settlement/verdict.js +112 -66
- package/build/core/settlement/verification-coordination.js +305 -0
- package/build/core/settlement/verification-supervisor.js +275 -0
- package/build/core/settlement/verification.js +398 -31
- package/build/core/status/board.js +114 -119
- package/build/core/status/lifecycle.js +7 -80
- package/build/core/structured-query.js +23 -0
- package/build/core/target-ref.js +1 -1
- package/build/core/task/board.js +59 -24
- package/build/core/task/commands.js +181 -33
- package/build/core/task/coordinate.js +56 -0
- package/build/core/task/document.js +25 -9
- package/build/core/task/index.js +7 -4
- package/build/core/task/query.js +17 -27
- package/build/core/task/settlement-git.js +164 -179
- package/build/core/task/settlement-policy.js +15 -11
- package/build/core/task/source-board.js +31 -13
- package/build/core/task/task-bind-preparation.js +193 -0
- package/build/core/task/task-contract.js +102 -193
- package/build/core/task/task-file-transaction.js +171 -0
- package/build/core/task/task-git-runtime.js +76 -14
- package/build/core/task/task-git-store.js +68 -169
- package/build/core/task/task-store-repository.js +13 -6
- package/build/core/task/task-worktree.js +6 -33
- package/build/core/task/task.js +1 -1
- package/build/core/task/tree.js +3 -3
- package/build/core/task/validation.js +4 -3
- package/build/core/transcripts.js +93 -1
- package/build/core/worktree-bootstrap.js +44 -36
- package/build/core/worktree-path.js +210 -77
- package/build/flow-error.js +7 -7
- package/build/generated/version.js +2 -2
- package/build/git/core.js +76 -13
- package/build/git/refs.js +168 -46
- package/build/git/streaming-batch.js +73 -13
- package/package.json +1 -1
- package/skills/keiyaku/SKILL.md +1 -1
- package/skills/keiyaku-akuma/SKILL.md +3 -3
- package/skills/keiyaku-task/SKILL.md +4 -2
- package/skills/keiyaku-workflow/SKILL.md +88 -203
- package/build/core/entry.js +0 -305
- package/build/core/ledger-batch.js +0 -194
- package/build/core/ledger.js +0 -84
- package/build/core/projection/leash.js +0 -87
- package/build/core/ref-log.js +0 -119
- package/build/core/renew-session.js +0 -128
- package/build/core/status/ledger-batch.js +0 -1
- 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
|
|
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
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
-
|
|
14
|
-
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
|
|
18
|
-
- An arc is a
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
```
|
|
23
|
-
bound
|
|
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
|
-
##
|
|
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
|
-
|
|
50
|
-
|
|
51
|
-
|
|
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
|
-
|
|
33
|
+
Declare the smallest useful Scope:
|
|
54
34
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
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
|
|
71
|
-
|
|
72
|
-
--checks "pump tests green"
|
|
41
|
+
keiyaku bind - < contract.md
|
|
42
|
+
keiyaku bind --task TASK_ID - < contract.md
|
|
73
43
|
```
|
|
74
44
|
|
|
75
|
-
|
|
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
|
-
|
|
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
|
-
|
|
51
|
+
Use `-C DIR` to select the effective directory. A contract worktree carries its
|
|
52
|
+
contract identity:
|
|
83
53
|
|
|
84
54
|
```bash
|
|
85
|
-
keiyaku
|
|
86
|
-
|
|
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
|
-
|
|
91
|
-
that exact path:
|
|
59
|
+
From a repository hub, name the contract with `--contract ADDR` or `@ADDR`:
|
|
92
60
|
|
|
93
61
|
```bash
|
|
94
|
-
keiyaku
|
|
62
|
+
keiyaku -C /work/keiyaku --contract repair-status.01K... audit
|
|
95
63
|
```
|
|
96
64
|
|
|
97
|
-
|
|
98
|
-
|
|
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
|
|
68
|
+
## Drive The Work
|
|
101
69
|
|
|
102
70
|
```bash
|
|
103
|
-
keiyaku
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
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
|
-
|
|
114
|
-
|
|
115
|
-
|
|
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
|
-
|
|
118
|
-
|
|
84
|
+
Scope changes are ordered terms. Use flags for simple additions or one
|
|
85
|
+
`Scope Append` block for an ordered delta:
|
|
119
86
|
|
|
120
|
-
|
|
121
|
-
##
|
|
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
|
-
|
|
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
|
-
`
|
|
206
|
-
|
|
95
|
+
Later `!pattern` terms narrow earlier matches. Do not mix the block with
|
|
96
|
+
`--append-scope` flags.
|
|
207
97
|
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
```
|
|
98
|
+
After an explicit arc seal, commit any new work and open the next arc before
|
|
99
|
+
`renew` or `petition`.
|
|
211
100
|
|
|
212
|
-
|
|
101
|
+
## Review
|
|
213
102
|
|
|
214
|
-
|
|
215
|
-
|
|
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
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
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
|
-
|
|
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
|
-
|
|
232
|
-
-
|
|
233
|
-
|
|
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
|
|
242
|
-
|
|
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
|
-
|
|
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
|
|
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.
|
package/build/core/entry.js
DELETED
|
@@ -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
|
-
}
|