@astrosheep/keiyaku 2.9.10 → 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 +87 -36
- package/build/.tsbuildinfo +1 -1
- package/build/generated/version.js +2 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,50 +1,98 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Keiyaku
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
契約 — a contract.
|
|
4
4
|
|
|
5
|
-
Keiyaku
|
|
5
|
+
Keiyaku is a CLI for coding agents. Not a developer tool with AI features: the
|
|
6
|
+
intended reader of every command, receipt, and error message is a model. If a
|
|
7
|
+
human is typing `keiyaku` by hand, something upstream has already gone wrong.
|
|
8
|
+
|
|
9
|
+
The premise is old. Work you delegate to something more capable than
|
|
10
|
+
accountable should be written down first. So here, a change begins as a
|
|
11
|
+
contract, runs on an isolated branch, and lands only after settlement. The
|
|
12
|
+
workers are called akuma — 悪魔, devils. This is not branding. It is a
|
|
13
|
+
reminder of the failure mode.
|
|
6
14
|
|
|
7
15
|
```bash
|
|
8
16
|
npm install -g @astrosheep/keiyaku
|
|
9
17
|
```
|
|
10
18
|
|
|
11
|
-
Node ≥ 22.19
|
|
19
|
+
Node ≥ 22.19, inside a git repository, with a clean worktree.
|
|
12
20
|
|
|
13
|
-
##
|
|
21
|
+
## Shape of a deal
|
|
14
22
|
|
|
15
23
|
```text
|
|
16
|
-
|
|
17
|
-
───────► 📋 ───────► ⛓ ───────► 😈 ───────► ⚖ ───────► ✓ main
|
|
18
|
-
the ask the contract devil at work judgement it lands
|
|
24
|
+
task ─── bind ─── call ─── petition ─── claim
|
|
19
25
|
```
|
|
20
26
|
|
|
21
|
-
|
|
27
|
+
`bind` opens a contract — Title, Context, Objective, Design, Scope,
|
|
28
|
+
Criteria — and an isolated branch. A devil honors the letter of the criteria,
|
|
29
|
+
not their spirit; the contract is where precision happens.
|
|
22
30
|
|
|
23
|
-
|
|
31
|
+
`call` projects a devil into the contract's worktree. While it runs: `tell` it
|
|
32
|
+
things, `wait` on it, `kill` it. A finished run leaves an artifact; `revive`
|
|
33
|
+
starts a new devil from one.
|
|
24
34
|
|
|
25
|
-
|
|
35
|
+
`petition` seals the delivery and enters settlement. Gates run, a reviewer
|
|
36
|
+
reads, and then exactly one of two things happens: claim, and it lands on
|
|
37
|
+
main — or forfeit, and the branch is gone. There is no third outcome and no
|
|
38
|
+
quiet one.
|
|
26
39
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
keiyaku status
|
|
30
|
-
|
|
40
|
+
## What state looks like
|
|
41
|
+
|
|
42
|
+
`keiyaku status` renders the watchtower — 監視, kanshi. This is real output
|
|
43
|
+
from this repository:
|
|
44
|
+
|
|
45
|
+
```text
|
|
46
|
+
kanshi ─────────────────────────────────────────────────────── 現世 b4c38cc
|
|
47
|
+
|
|
48
|
+
keiyaku 2
|
|
49
|
+
□ fridge Add task arrange for atomic existing-task reorganization ▲2 · open 27m
|
|
50
|
+
□ hermitcrab Let task commands select a contract workspace bound 8m
|
|
51
|
+
|
|
52
|
+
akuma 2
|
|
53
|
+
◆ worker-default/e03addad compose-impl @fridge up 27m · active 2s
|
|
54
|
+
09:12│ told “Root review found contract-significant gaps. Continue …” — 5m12s…
|
|
55
|
+
⋮ 12 more
|
|
56
|
+
09:17│ said “The grouped verifier stream detached again, so I’m rerunning …”
|
|
57
|
+
│ ran $ node --test tests/unit/task-compose.test.ts — 38s
|
|
58
|
+
+ 10 failed · 159 done · 4 killed
|
|
59
|
+
|
|
60
|
+
task 120
|
|
61
|
+
▶ P1 centralize-repository-ledger-test-construction … in_progress · active 14h
|
|
62
|
+
▶ P0 windows-common-commands-must-eliminate-git-proc… in_progress · active 3d
|
|
63
|
+
+ 108 ready · 9 blocked
|
|
31
64
|
```
|
|
32
65
|
|
|
33
|
-
|
|
66
|
+
The rendering is itself under contract. `◆` may only mean a projection asserted
|
|
67
|
+
alive — liveness is never inferred from output freshness. `⋮ 12 more` counts
|
|
68
|
+
exactly twelve omitted rows. Durations are measured, exit codes are real, and a
|
|
69
|
+
command that never finished says `never finished`. An agent parses this screen
|
|
70
|
+
without heuristics because every glyph has one meaning, in writing, in
|
|
71
|
+
[`docs/keiyaku-v3/product/ui-copy.md`](docs/keiyaku-v3/product/ui-copy.md).
|
|
72
|
+
|
|
73
|
+
## Surface
|
|
34
74
|
|
|
35
75
|
| | |
|
|
36
76
|
| --- | --- |
|
|
37
|
-
|
|
|
38
|
-
|
|
|
39
|
-
|
|
|
40
|
-
|
|
|
41
|
-
|
|
|
77
|
+
| contract | `bind` `arc` `amend` `renew` `audit` `petition` `forfeit` `log` |
|
|
78
|
+
| devils | `call` `tell` `wait` `kill` `revive` `status` `history` |
|
|
79
|
+
| roster | `akuma list` `akuma show` |
|
|
80
|
+
| tasks | `task add/show/ls/log/start/stop/hold/resume/done/drop/update/doctor` |
|
|
81
|
+
| system | `guide` `completion` `dump-env` |
|
|
82
|
+
|
|
83
|
+
Conventions an agent can rely on everywhere: a literal `-` selects stdin for
|
|
84
|
+
long bodies; `--json` exists where structure matters; a rejected command names
|
|
85
|
+
the legal grammar instead of guessing intent; `keiyaku <cmd> --help` is the
|
|
86
|
+
single source of syntax.
|
|
42
87
|
|
|
43
|
-
Tasks are a file-backed board
|
|
88
|
+
Tasks are a file-backed board inside the repository. Dependencies keep their
|
|
89
|
+
distinct meanings — `parent`, `needs`, `supersedes`, `relates-to` — and every
|
|
90
|
+
mutation is validated and micro-committed on its own.
|
|
44
91
|
|
|
45
|
-
##
|
|
92
|
+
## A devil is one file
|
|
46
93
|
|
|
47
|
-
|
|
94
|
+
Filename is the name. Frontmatter selects the provider. The body is the
|
|
95
|
+
instructions.
|
|
48
96
|
|
|
49
97
|
```markdown
|
|
50
98
|
---
|
|
@@ -55,10 +103,12 @@ description: Repository implementation agent
|
|
|
55
103
|
Make scoped changes and run relevant tests.
|
|
56
104
|
```
|
|
57
105
|
|
|
58
|
-
Providers: `codex-sdk
|
|
59
|
-
Resolution
|
|
106
|
+
Providers: `codex-sdk`, `codex-app-server`, `claude-agent-sdk`,
|
|
107
|
+
`opencode-sdk`, `pi`. Resolution is builtin, then `<KEIYAKU_HOME>/akuma/`,
|
|
108
|
+
then `.keiyaku/akuma/`; a higher layer replaces the file whole, never
|
|
109
|
+
field-merges.
|
|
60
110
|
|
|
61
|
-
`.keiyaku/settings.json`
|
|
111
|
+
`.keiyaku/settings.json` selects roles and gates, nothing else:
|
|
62
112
|
|
|
63
113
|
```json
|
|
64
114
|
{
|
|
@@ -68,24 +118,25 @@ Resolution: builtin < `<KEIYAKU_HOME>/akuma/` < `.keiyaku/akuma/` — a higher c
|
|
|
68
118
|
}
|
|
69
119
|
```
|
|
70
120
|
|
|
71
|
-
##
|
|
121
|
+
## What it writes
|
|
72
122
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
| Path | |
|
|
123
|
+
| | |
|
|
76
124
|
| --- | --- |
|
|
77
125
|
| `KEIYAKU.md` | the active contract |
|
|
78
|
-
| `.keiyaku/` |
|
|
126
|
+
| `.keiyaku/` | devils, settings, task board, response history |
|
|
79
127
|
|
|
80
128
|
```gitignore
|
|
81
129
|
.keiyaku/draft/
|
|
82
130
|
.keiyaku/response/
|
|
83
131
|
```
|
|
84
132
|
|
|
85
|
-
##
|
|
133
|
+
## Law
|
|
86
134
|
|
|
87
|
-
|
|
135
|
+
Product and architecture law is registered in
|
|
136
|
+
[`docs/keiyaku-v3/`](docs/keiyaku-v3/README.md). A document is normative only
|
|
137
|
+
if the registry lists it; age, location, and confident prose grant nothing.
|
|
88
138
|
|
|
89
|
-
Keiyaku is early and experimental
|
|
139
|
+
Keiyaku is early and experimental. Breaking changes are intentional, and the
|
|
140
|
+
current version is the only version.
|
|
90
141
|
|
|
91
|
-
MIT.
|
|
142
|
+
MIT.
|