proofdeck 0.0.0-stage → 0.1.0
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/LICENSE +201 -0
- package/NOTICE +23 -0
- package/README.md +97 -2
- package/README.zh-CN.md +89 -0
- package/bin/proofdeck.js +126 -0
- package/board/LICENSE +201 -0
- package/board/README.md +473 -0
- package/board/README.zh-CN.md +424 -0
- package/board/dist/_chk.db-shm +0 -0
- package/board/dist/_chk.db-wal +0 -0
- package/board/dist/adapters.d.ts +40 -0
- package/board/dist/adapters.d.ts.map +1 -0
- package/board/dist/adapters.js +124 -0
- package/board/dist/adapters.js.map +1 -0
- package/board/dist/board.d.ts +628 -0
- package/board/dist/board.d.ts.map +1 -0
- package/board/dist/board.js +2767 -0
- package/board/dist/board.js.map +1 -0
- package/board/dist/cli.d.ts +3 -0
- package/board/dist/cli.d.ts.map +1 -0
- package/board/dist/cli.js +1663 -0
- package/board/dist/cli.js.map +1 -0
- package/board/dist/config.d.ts +57 -0
- package/board/dist/config.d.ts.map +1 -0
- package/board/dist/config.js +99 -0
- package/board/dist/config.js.map +1 -0
- package/board/dist/db.d.ts +9 -0
- package/board/dist/db.d.ts.map +1 -0
- package/board/dist/db.js +506 -0
- package/board/dist/db.js.map +1 -0
- package/board/dist/git.d.ts +35 -0
- package/board/dist/git.d.ts.map +1 -0
- package/board/dist/git.js +147 -0
- package/board/dist/git.js.map +1 -0
- package/board/dist/index.d.ts +18 -0
- package/board/dist/index.d.ts.map +1 -0
- package/board/dist/index.js +13 -0
- package/board/dist/index.js.map +1 -0
- package/board/dist/mcp-config.d.ts +26 -0
- package/board/dist/mcp-config.d.ts.map +1 -0
- package/board/dist/mcp-config.js +88 -0
- package/board/dist/mcp-config.js.map +1 -0
- package/board/dist/mcp.d.ts +3 -0
- package/board/dist/mcp.d.ts.map +1 -0
- package/board/dist/mcp.js +949 -0
- package/board/dist/mcp.js.map +1 -0
- package/board/dist/quickstart.d.ts +75 -0
- package/board/dist/quickstart.d.ts.map +1 -0
- package/board/dist/quickstart.js +156 -0
- package/board/dist/quickstart.js.map +1 -0
- package/board/dist/serve.d.ts +10 -0
- package/board/dist/serve.d.ts.map +1 -0
- package/board/dist/serve.js +445 -0
- package/board/dist/serve.js.map +1 -0
- package/board/dist/signing.d.ts +18 -0
- package/board/dist/signing.d.ts.map +1 -0
- package/board/dist/signing.js +26 -0
- package/board/dist/signing.js.map +1 -0
- package/board/dist/sync.d.ts +49 -0
- package/board/dist/sync.d.ts.map +1 -0
- package/board/dist/sync.js +158 -0
- package/board/dist/sync.js.map +1 -0
- package/board/dist/types.d.ts +359 -0
- package/board/dist/types.d.ts.map +1 -0
- package/board/dist/types.js +20 -0
- package/board/dist/types.js.map +1 -0
- package/board/docs/adr/0001-shared-worktree-collision.md +102 -0
- package/board/docs/adr/0001-shared-worktree-collision.zh-CN.md +90 -0
- package/board/docs/attribution.md +123 -0
- package/board/docs/attribution.zh-CN.md +104 -0
- package/board/docs/development-workflow.md +81 -0
- package/board/docs/development-workflow.zh-CN.md +75 -0
- package/board/docs/diagrams/banner.png +0 -0
- package/board/docs/diagrams/banner.svg +1 -0
- package/board/docs/diagrams/before-after.png +0 -0
- package/board/docs/diagrams/before-after.svg +1 -0
- package/board/docs/diagrams/governance-chain.png +0 -0
- package/board/docs/diagrams/governance-chain.svg +1 -0
- package/board/docs/diagrams/value-flow.png +0 -0
- package/board/docs/diagrams/value-flow.svg +1 -0
- package/board/docs/entry-point.md +81 -0
- package/board/docs/entry-point.zh-CN.md +65 -0
- package/board/docs/kanban.png +0 -0
- package/board/docs/octoryn-mark.png +0 -0
- package/board/docs/registry-metadata.md +34 -0
- package/board/docs/registry-metadata.zh-CN.md +30 -0
- package/board/package.json +87 -0
- package/config.example.json +71 -0
- package/daemon.js +1112 -0
- package/docs/assets/demo.gif +0 -0
- package/docs/demo-run.mjs +61 -0
- package/docs/render-demo.py +94 -0
- package/e2e/verify-acceptance.mjs +150 -0
- package/e2e/verify-antifraud.mjs +128 -0
- package/e2e/verify-caps.mjs +46 -0
- package/e2e/verify-checkpoint.mjs +208 -0
- package/e2e/verify-firstclass.mjs +110 -0
- package/e2e/verify-judge.mjs +52 -0
- package/e2e/verify-lease.mjs +95 -0
- package/e2e/verify-replay.mjs +92 -0
- package/e2e/verify-resilience.mjs +323 -0
- package/e2e/verify-review.mjs +86 -0
- package/e2e/verify-scheduling.mjs +110 -0
- package/e2e/verify-schema-evolution.mjs +107 -0
- package/e2e/verify-sla-digest.mjs +105 -0
- package/guard.js +97 -0
- package/lib/adapters/codex.js +206 -0
- package/lib/billing-convert.js +57 -0
- package/lib/board.js +46 -0
- package/lib/caps.js +35 -0
- package/lib/checkpoint.js +130 -0
- package/lib/gating.js +218 -0
- package/lib/guard-core.mjs +108 -0
- package/lib/http.js +161 -0
- package/lib/judge.js +89 -0
- package/lib/lease.js +93 -0
- package/lib/notify.js +56 -0
- package/lib/platform.js +120 -0
- package/lib/replay.js +68 -0
- package/lib/review.js +40 -0
- package/lib/runner.js +152 -0
- package/lib/schedule.js +59 -0
- package/lib/sla.js +42 -0
- package/lib/spans.js +36 -0
- package/lib/starve.js +43 -0
- package/lib/store.js +109 -0
- package/lib/supply.js +101 -0
- package/lib/usage.js +103 -0
- package/lib/verify.js +223 -0
- package/lib/watchdog-core.mjs +68 -0
- package/lib/watchdog-worker.mjs +75 -0
- package/package.json +55 -4
- package/scripts/run-daemon.sh +18 -0
- package/scripts/run-e2e.mjs +39 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
39
|
+
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
47
|
+
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
61
|
+
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
65
|
+
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or
|
|
95
|
+
Derivative Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work,
|
|
103
|
+
excluding those notices that do not pertain to any part of
|
|
104
|
+
the Derivative Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, excluding those notices that do not
|
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
|
111
|
+
of the following places: within a NOTICE text file distributed
|
|
112
|
+
as part of the Derivative Works; within the Source form or
|
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
|
114
|
+
within a display generated by the Derivative Works, if and
|
|
115
|
+
wherever such third-party notices normally appear. The contents
|
|
116
|
+
of the NOTICE file are for informational purposes only and
|
|
117
|
+
do not modify the License. You may add Your own attribution
|
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
120
|
+
that such additional attribution notices cannot be construed
|
|
121
|
+
as modifying the License.
|
|
122
|
+
|
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
|
124
|
+
may provide additional or different license terms and conditions
|
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
128
|
+
the conditions stated in this License.
|
|
129
|
+
|
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
133
|
+
this License, without any additional terms or conditions.
|
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
135
|
+
the terms of any separate license agreement you may have executed
|
|
136
|
+
with Licensor regarding such Contributions.
|
|
137
|
+
|
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
140
|
+
except as required for reasonable and customary use in describing the
|
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
142
|
+
|
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
|
152
|
+
|
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
|
158
|
+
incidental, or consequential damages of any character arising as a
|
|
159
|
+
result of this License or out of the use or inability to use the
|
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
162
|
+
other commercial damages or losses), even if such Contributor
|
|
163
|
+
has been advised of the possibility of such damages.
|
|
164
|
+
|
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
168
|
+
or other liability obligations and/or rights consistent with this
|
|
169
|
+
License. However, in accepting such obligations, You may act only
|
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
174
|
+
of your accepting any such warranty or additional liability.
|
|
175
|
+
|
|
176
|
+
END OF TERMS AND CONDITIONS
|
|
177
|
+
|
|
178
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
179
|
+
|
|
180
|
+
To apply the Apache License to your work, attach the following
|
|
181
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
182
|
+
replaced with your own identifying information. (Don't include
|
|
183
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
184
|
+
comment syntax for the file format. We also recommend that a
|
|
185
|
+
file or class name and description of purpose be included on the
|
|
186
|
+
same "printed page" as the copyright notice for easier
|
|
187
|
+
identification within third-party archives.
|
|
188
|
+
|
|
189
|
+
Copyright 2026 Octoryn
|
|
190
|
+
|
|
191
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
192
|
+
you may not use this file except in compliance with the License.
|
|
193
|
+
You may obtain a copy of the License at
|
|
194
|
+
|
|
195
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
196
|
+
|
|
197
|
+
Unless required by applicable law or agreed to in writing, software
|
|
198
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
199
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
200
|
+
See the License for the specific language governing permissions and
|
|
201
|
+
limitations under the License.
|
package/NOTICE
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
ProofDeck
|
|
2
|
+
Copyright 2026 kumu314
|
|
3
|
+
|
|
4
|
+
This product includes software derived from octopus-blackboard
|
|
5
|
+
(https://github.com/octoryn/octopus-blackboard), Copyright Ran Tao / octoryn,
|
|
6
|
+
licensed under the Apache License, Version 2.0.
|
|
7
|
+
|
|
8
|
+
The vendored distribution of that work lives in the board/ directory
|
|
9
|
+
(see board/LICENSE for the original license text). Modifications made in
|
|
10
|
+
this fork (2026-10) include:
|
|
11
|
+
|
|
12
|
+
- acceptance-first task schema (tasks.acceptance column and public
|
|
13
|
+
verification API)
|
|
14
|
+
- verification events written into the append-only sha256 hash chain
|
|
15
|
+
- dual SQLite backend: node:sqlite (DatabaseSync) preferred,
|
|
16
|
+
better-sqlite3 fallback, selectable via OCTOBOARD_BACKEND
|
|
17
|
+
- four-layer project partitioning (board / project / task / trace)
|
|
18
|
+
- related bug fixes and packaging changes
|
|
19
|
+
|
|
20
|
+
ProofDeck itself (everything outside board/) — the verification engine,
|
|
21
|
+
LLM judge, scheduling core, capability routing, replay, spans, digest,
|
|
22
|
+
and the daemon orchestration layer — is Copyright 2026 kumu314,
|
|
23
|
+
licensed under the Apache License, Version 2.0.
|
package/README.md
CHANGED
|
@@ -1,3 +1,98 @@
|
|
|
1
|
-
#
|
|
1
|
+
# ProofDeck
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**A verification-first task board and orchestrator for coding-agent fleets.**
|
|
4
|
+
|
|
5
|
+
Agents claim done. ProofDeck demands proof.
|
|
6
|
+
|
|
7
|
+
[](https://github.com/kumu314/proofdeck/actions/workflows/ci.yml)
|
|
8
|
+
[](./LICENSE)
|
|
9
|
+

|
|
10
|
+
|
|
11
|
+

|
|
12
|
+
|
|
13
|
+
> `board/` 目录内含 [octopus-blackboard](https://github.com/octoryn/octopus-blackboard)(Apache-2.0)的修改版发行,见 [NOTICE](./NOTICE)。中文说明:[README.zh-CN.md](./README.zh-CN.md)。
|
|
14
|
+
|
|
15
|
+
## Why
|
|
16
|
+
|
|
17
|
+
If you run one coding agent (Claude Code, Codex CLI, Gemini CLI, …) you review everything it does, and review works. The moment you run **several** agents in parallel, review becomes the bottleneck — and two failure modes compound:
|
|
18
|
+
|
|
19
|
+
- **False affirmatives.** The agent adds a fallback so the code "works", tests pass, and the flaw ships anyway. The industry has a name for the general problem: *reward hacking* — it is now an active research topic (ImpossibleBench, 2025; Anthropic's work on emergent misalignment from reward hacking, 2026).
|
|
20
|
+
- **Silent death.** An agent stalls, exits 0 with nothing done, or burns its budget on a dead-end loop. Nobody notices until the deadline.
|
|
21
|
+
|
|
22
|
+
ProofDeck's answer is to make **acceptance criteria a first-class column on every task** and to refuse "done" that lacks evidence:
|
|
23
|
+
|
|
24
|
+
1. Every task carries machine-checkable acceptance criteria.
|
|
25
|
+
2. On completion, a fail-closed verification engine runs them (file existence, occurrence counts, JSON-path matches, reference existence — five check families).
|
|
26
|
+
3. An LLM judge reviews the trajectory against the criteria when machine checks are not enough; its verdict lands in an **append-only sha256 hash chain** next to who claimed the task, who verified it, and when.
|
|
27
|
+
4. Tasks that fail are retried with backoff, parked for human review, or routed to a different agent by capability — never silently marked done.
|
|
28
|
+
|
|
29
|
+
Around that gate, ProofDeck runs the fleet: a shared SQLite-backed blackboard with MCP surface, priority lanes with aging, automatic retry with a supply breaker, SLA due-dates, digest emails, full event replay (time travel), and OpenTelemetry-style spans.
|
|
30
|
+
|
|
31
|
+
## Status
|
|
32
|
+
|
|
33
|
+
`v0.1.0-preview`. Battle-tested in daily production use (a personal multi-agent fleet; hundreds of tasks) **on Windows**. The POSIX layer is new and marked **beta**: CI runs the test matrix on ubuntu as well, but real-world macOS/Linux mileage is thin — expect rough edges and please report them.
|
|
34
|
+
|
|
35
|
+
## Quick start
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
npx proofdeck init # scaffold: daemon.config.json + .proofdeck/ + control.token
|
|
39
|
+
# edit daemon.config.json — point agents.codex.script at a CLI you have
|
|
40
|
+
npx proofdeck daemon # start the daemon (board + control plane + scheduler)
|
|
41
|
+
npx proofdeck status # board head, task counts, acceptance coverage
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
From a git checkout instead of npm:
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
git clone https://github.com/kumu314/proofdeck && cd proofdeck && npm install
|
|
48
|
+
node bin/proofdeck.js init && node bin/proofdeck.js daemon
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Any agent that speaks MCP can read/write the board (tasks, notes, messages, verification events).
|
|
52
|
+
|
|
53
|
+
## Architecture
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
┌───────────────────────────────────────────┐
|
|
57
|
+
│ ProofDeck │
|
|
58
|
+
human ──define──────▶│ daemon: claim → run face → verify gate │
|
|
59
|
+
agents ◀──MCP────────│ │ │
|
|
60
|
+
(CLI faces) ──run──▶│ ├─ V1 checks (fail-closed) │
|
|
61
|
+
│ ├─ V1.5 LLM judge │
|
|
62
|
+
│ ├─ retry / breaker / routing │
|
|
63
|
+
│ ▼ │
|
|
64
|
+
│ blackboard: SQLite WAL + append-only │
|
|
65
|
+
│ sha256 hash chain (tasks, notes, verify │
|
|
66
|
+
│ events, messages — tamper-evident) │
|
|
67
|
+
└───────────────────────────────────────────┘
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
- **board/** — vendored, modified distribution of octopus-blackboard: the shared task board with an append-only hash chain, MCP surface, and the acceptance/verification schema.
|
|
71
|
+
- **lib/** — verification engine (`verify.js`), LLM judge (`judge.js`), scheduling core with priority aging and retry policy (`schedule.js`), capability routing (`caps.js`), event replay (`replay.js`), spans, digest, leases, supply breaker.
|
|
72
|
+
- **Adapters** — each agent face is one small module (`lib/adapters/`); a generic CLI adapter (`codex.js`) is the reference implementation. Prompts are fed via stdin, never argv — long CJK text corrupts through some shells (a real cross-platform lesson from production).
|
|
73
|
+
|
|
74
|
+
## Design principles
|
|
75
|
+
|
|
76
|
+
- **Fail closed.** A task without acceptance criteria is not silently accepted — it is flagged, every dispatch, until it has them.
|
|
77
|
+
- **Evidence over vibes.** Verification results are events in a hash chain, not chat messages.
|
|
78
|
+
- **The board is the truth.** Agents come and go; the append-only timeline remembers.
|
|
79
|
+
- **Boring storage.** One SQLite file per deployment. `node:sqlite` natively, `better-sqlite3` as fallback (`OCTOBOARD_BACKEND=better-sqlite3`).
|
|
80
|
+
|
|
81
|
+
## Testing
|
|
82
|
+
|
|
83
|
+
15 end-to-end suites (verification, anti-fraud, judge, scheduling, resilience, replay, SLA/digest, …) run against real boards:
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
node e2e/verify-verify-firstclass.mjs # naming: verify-<topic>.mjs, see e2e/
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## Contributing & security
|
|
90
|
+
|
|
91
|
+
Contribution guide in [CONTRIBUTING.md](./CONTRIBUTING.md) — PRs need CI green
|
|
92
|
+
and evidence, same as our agents. Security disclosures via
|
|
93
|
+
[SECURITY.md](./SECURITY.md) (private reporting, 7-day response). Releases are
|
|
94
|
+
tagged; see [CHANGELOG.md](./CHANGELOG.md).
|
|
95
|
+
|
|
96
|
+
## License
|
|
97
|
+
|
|
98
|
+
Apache-2.0. See [LICENSE](./LICENSE) and [NOTICE](./NOTICE) — this project includes a modified distribution of [octopus-blackboard](https://github.com/octoryn/octopus-blackboard) by Ran Tao / octoryn.
|
package/README.zh-CN.md
ADDED
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# ProofDeck
|
|
2
|
+
|
|
3
|
+
**验证优先的编码 agent 舰队任务板与编排器。**
|
|
4
|
+
|
|
5
|
+
Agent 说 done,ProofDeck 要证据。
|
|
6
|
+
|
|
7
|
+

|
|
8
|
+
|
|
9
|
+
> 本仓库 `board/` 目录内含 [octopus-blackboard](https://github.com/octoryn/octopus-blackboard)(Apache-2.0)的修改版发行,见 [NOTICE](./NOTICE)。English: [README.md](./README.md)。
|
|
10
|
+
|
|
11
|
+
## 为什么
|
|
12
|
+
|
|
13
|
+
只跑一个编码 agent(Claude Code、Codex CLI、Gemini CLI……)时,你会 review 它的每一步,review 是有效的。但你一旦**并行跑好几个** agent,review 就成了瓶颈,而两种失败模式会叠加:
|
|
14
|
+
|
|
15
|
+
- **虚假确认(false affirmative)**。agent 加个 fallback 让代码"能跑",测试也过了,缺陷照样上线。业界给这类问题起了名字——*reward hacking*,它现在是活跃的研究课题(ImpossibleBench 2025;Anthropic 关于 reward hacking 引发的突现失调研究 2026)。
|
|
16
|
+
- **静默死亡**。agent 卡住、rc=0 但什么都没干、或把预算烧在死循环里——直到截止日期前都没人发现。
|
|
17
|
+
|
|
18
|
+
ProofDeck 的答案是:**把验收标准做成每张任务的一等公民**,并拒绝没有证据的"done":
|
|
19
|
+
|
|
20
|
+
1. 每张任务携带机器可校验的验收标准;
|
|
21
|
+
2. 完成时,fail-closed 验证引擎执行验收(文件存在、次数下限、JSON 路径断言、引用存在——五类检查);
|
|
22
|
+
3. 机器检查不够时,LLM judge 依据验收标准复核轨迹,它的判定连同"谁认领、谁验证、何时"一起写进**追加式 sha256 哈希链**;
|
|
23
|
+
4. 验证失败的任务按退避自动重试、转入人工复核、或按能力路由给另一个 agent——**绝不静默标记完成**。
|
|
24
|
+
|
|
25
|
+
在那道门禁周围,ProofDeck 负责整支舰队:SQLite 共享黑板(带 MCP 面)、带 aging 的优先级车道、自动重试与供应熔断、SLA 到期、摘要邮件、全量事件回放(时间旅行)、以及 OpenTelemetry 风格 span。
|
|
26
|
+
|
|
27
|
+
## 状态
|
|
28
|
+
|
|
29
|
+
`v0.1.0-preview`。在真实日常使用中淬炼(个人多 agent 舰队,数百张任务)——**Windows 为一等公民**。POSIX 层标记为 **beta**:CI 在 ubuntu 上跑完整测试矩阵(13/13 绿),但真实世界的 macOS/Linux 使用里程还薄——遇到坑请报 issue。
|
|
30
|
+
|
|
31
|
+
## 快速开始
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
npx proofdeck init # 脚手架:daemon.config.json + .proofdeck/ + control.token
|
|
35
|
+
# 编辑 daemon.config.json —— 把 agents.codex.script 指向你有的 CLI
|
|
36
|
+
npx proofdeck daemon # 起守护(黑板 + 控制面 + 调度器)
|
|
37
|
+
npx proofdeck status # 看板块 head、任务统计、验收覆盖
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
从 git 检出运行:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
git clone https://github.com/kumu314/proofdeck && cd proofdeck && npm install
|
|
44
|
+
node bin/proofdeck.js init && node bin/proofdeck.js daemon
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
任何说 MCP 的 agent 都能读写黑板(任务、注记、消息、验证事件)。
|
|
48
|
+
|
|
49
|
+
## 架构
|
|
50
|
+
|
|
51
|
+
```
|
|
52
|
+
┌───────────────────────────────────────────┐
|
|
53
|
+
│ ProofDeck │
|
|
54
|
+
人 ──定义任务────────▶│ 守护:认领 → 跑面 → 验证门禁 │
|
|
55
|
+
agents ◀──MCP────────│ │ │
|
|
56
|
+
(CLI 面) ──运行─────▶│ ├─ V1 检查(fail-closed) │
|
|
57
|
+
│ ├─ V1.5 LLM judge │
|
|
58
|
+
│ ├─ 重试 / 熔断 / 能力路由 │
|
|
59
|
+
│ ▼ │
|
|
60
|
+
│ 黑板:SQLite WAL + 追加式 sha256 哈希链 │
|
|
61
|
+
│ (任务/注记/验证事件/消息——防篡改可取证)│
|
|
62
|
+
└───────────────────────────────────────────┘
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
- **board/** —— octopus-blackboard 的修改版发行:共享任务板,追加式哈希链、MCP 面、验收/验证 schema。
|
|
66
|
+
- **lib/** —— 验证引擎(`verify.js`)、LLM judge(`judge.js`)、带优先级 aging 与重试策略的调度核(`schedule.js`)、能力路由(`caps.js`)、事件回放(`replay.js`)、span、摘要、租约、供应熔断。
|
|
67
|
+
- **适配器** —— 每个 agent 面就是一个小模块(`lib/adapters/`);通用 CLI 适配器(`codex.js`)是参考实现。题面经 stdin 喂入、绝不放 argv——长中文文本过某些 shell 会被搅坏(这是生产线换来的跨平台教训)。
|
|
68
|
+
|
|
69
|
+
## 设计原则
|
|
70
|
+
|
|
71
|
+
- **Fail closed。** 没有验收标准的任务不会被静默接受——每次派发都被标注提示,直到补上。
|
|
72
|
+
- **证据而非感觉。** 验证结果是哈希链里的事件,不是聊天记录。
|
|
73
|
+
- **黑板即真相。** Agent 来来去去;追加式时间线记得一切。
|
|
74
|
+
- **无聊的存储。** 每次部署一个 SQLite 文件。原生 `node:sqlite`,`better-sqlite3` 作回退(`OCTOBOARD_BACKEND=better-sqlite3`)。
|
|
75
|
+
|
|
76
|
+
## 测试
|
|
77
|
+
|
|
78
|
+
13 套端到端套件(验证、防刷分、judge、调度、韧性、回放、SLA/摘要……),打在真实黑板上:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
node scripts/run-e2e.mjs # 全量(node:sqlite 原生后端)
|
|
82
|
+
OCTOBOARD_BACKEND=better-sqlite3 node scripts/run-e2e.mjs # 回退后端
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
CI 在 Windows/ubuntu × 双后端四格矩阵上跑全套;native 格用 `--omit=optional` 安装——在干净机器上实证"零原生依赖"。
|
|
86
|
+
|
|
87
|
+
## 许可
|
|
88
|
+
|
|
89
|
+
Apache-2.0。见 [LICENSE](./LICENSE) 与 [NOTICE](./NOTICE)——本项目包含 [octopus-blackboard](https://github.com/octoryn/octopus-blackboard)(Ran Tao / octoryn)的修改版发行。
|
package/bin/proofdeck.js
ADDED
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// ProofDeck CLI — v0.1: init / daemon / status.
|
|
3
|
+
//
|
|
4
|
+
// init scaffold a project dir (daemon.config.json, .proofdeck board dir,
|
|
5
|
+
// control.token, workdirs/) and print the next steps
|
|
6
|
+
// daemon run the orchestration daemon against the current project dir
|
|
7
|
+
// (PROOFDECK_BASE=cwd; config from ./daemon.config.json)
|
|
8
|
+
// status one-shot board snapshot (head, task counts, verify counts)
|
|
9
|
+
//
|
|
10
|
+
// The package is self-contained: the vendored board lives next to this file
|
|
11
|
+
// (../board), so no extra downloads are needed after `npm i proofdeck`.
|
|
12
|
+
import { existsSync, mkdirSync, copyFileSync, writeFileSync, readFileSync } from "node:fs";
|
|
13
|
+
import { join, dirname, resolve } from "node:path";
|
|
14
|
+
import { fileURLToPath } from "node:url";
|
|
15
|
+
import { spawn } from "node:child_process";
|
|
16
|
+
import { randomBytes } from "node:crypto";
|
|
17
|
+
|
|
18
|
+
const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
|
|
19
|
+
const BOARD_PKG = join(PKG_ROOT, "board");
|
|
20
|
+
const EXAMPLE = join(PKG_ROOT, "config.example.json");
|
|
21
|
+
|
|
22
|
+
const say = (m = "") => console.log(m);
|
|
23
|
+
const ok = (m) => console.log("✅ " + m);
|
|
24
|
+
const warn = (m) => console.log("⚠️ " + m);
|
|
25
|
+
|
|
26
|
+
function usage() {
|
|
27
|
+
say(`ProofDeck — verification-first task board & orchestrator for coding-agent fleets
|
|
28
|
+
|
|
29
|
+
Usage:
|
|
30
|
+
proofdeck init [dir] Scaffold a project dir (default: current)
|
|
31
|
+
proofdeck daemon Run the daemon for the current project dir
|
|
32
|
+
proofdeck status Show board head / task / verify counts
|
|
33
|
+
proofdeck --version Print version
|
|
34
|
+
|
|
35
|
+
Docs: https://github.com/kumu314/proofdeck`);
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
function cmdInit(args) {
|
|
39
|
+
const dir = resolve(args[0] ?? ".");
|
|
40
|
+
const cfgPath = join(dir, "daemon.config.json");
|
|
41
|
+
if (existsSync(cfgPath) && !args.includes("--force")) {
|
|
42
|
+
warn(`${cfgPath} already exists — refusing to overwrite (pass --force to replace)`);
|
|
43
|
+
return 1;
|
|
44
|
+
}
|
|
45
|
+
mkdirSync(dir, { recursive: true });
|
|
46
|
+
|
|
47
|
+
const cfg = JSON.parse(readFileSync(EXAMPLE, "utf8"));
|
|
48
|
+
// Point the vendored board at the packaged copy so init works from anywhere.
|
|
49
|
+
cfg.board.package = BOARD_PKG.replace(/\\/g, "/");
|
|
50
|
+
cfg.board.dir = "./.proofdeck";
|
|
51
|
+
writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + "\n");
|
|
52
|
+
|
|
53
|
+
mkdirSync(join(dir, ".proofdeck"), { recursive: true });
|
|
54
|
+
mkdirSync(join(dir, "workdirs"), { recursive: true });
|
|
55
|
+
const tokenPath = join(dir, "control.token");
|
|
56
|
+
if (!existsSync(tokenPath)) writeFileSync(tokenPath, randomBytes(24).toString("hex") + "\n");
|
|
57
|
+
|
|
58
|
+
ok(`scaffolded ${dir}`);
|
|
59
|
+
say(` daemon.config.json ← edit agents.* to point at your CLI(s)`);
|
|
60
|
+
say(` .proofdeck/ ← board lives here (one SQLite file + audit chain)`);
|
|
61
|
+
say(` control.token ← local control-plane credential`);
|
|
62
|
+
say("");
|
|
63
|
+
say("Next:");
|
|
64
|
+
say(" 1) edit daemon.config.json — set agents.codex.script to your agent CLI");
|
|
65
|
+
say(" 2) proofdeck daemon (or: node daemon.js daemon.config.json)");
|
|
66
|
+
say(" 3) define a task with acceptance criteria, then watch the gate work");
|
|
67
|
+
return 0;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
async function cmdDaemon() {
|
|
71
|
+
const cfgPath = join(process.cwd(), "daemon.config.json");
|
|
72
|
+
if (!existsSync(cfgPath)) {
|
|
73
|
+
warn(`no daemon.config.json in ${process.cwd()} — run: proofdeck init`);
|
|
74
|
+
return 1;
|
|
75
|
+
}
|
|
76
|
+
const child = spawn(process.execPath, [join(PKG_ROOT, "daemon.js"), cfgPath], {
|
|
77
|
+
cwd: process.cwd(),
|
|
78
|
+
stdio: "inherit",
|
|
79
|
+
env: { ...process.env, PROOFDECK_BASE: process.cwd() },
|
|
80
|
+
});
|
|
81
|
+
// Long-running: hold the CLI until the daemon exits, then propagate its code.
|
|
82
|
+
return await new Promise((r) => child.on("exit", (code) => r(code ?? 0)));
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
async function cmdStatus() {
|
|
86
|
+
const cfgPath = join(process.cwd(), "daemon.config.json");
|
|
87
|
+
if (!existsSync(cfgPath)) {
|
|
88
|
+
warn(`no daemon.config.json in ${process.cwd()} — run: proofdeck init`);
|
|
89
|
+
return 1;
|
|
90
|
+
}
|
|
91
|
+
const cfg = JSON.parse(readFileSync(cfgPath, "utf8"));
|
|
92
|
+
const boardDir = resolve(process.cwd(), cfg.board.dir ?? ".proofdeck");
|
|
93
|
+
const pkg = cfg.board.package ?? BOARD_PKG;
|
|
94
|
+
const { Board } = await import(new URL("file://" + join(resolve(pkg), "dist", "board.js").replace(/\\/g, "/")).href);
|
|
95
|
+
const b = Board.open({ boardDir, agent: cfg.board.identity ?? "bridge" });
|
|
96
|
+
try {
|
|
97
|
+
const head = b.head();
|
|
98
|
+
const cards = b.listTaskCards();
|
|
99
|
+
const byStatus = {};
|
|
100
|
+
let verified = 0, withAcc = 0;
|
|
101
|
+
for (const c of cards) {
|
|
102
|
+
const t = c.task || {};
|
|
103
|
+
byStatus[t.status] = (byStatus[t.status] || 0) + 1;
|
|
104
|
+
if (t.acceptance != null) withAcc++;
|
|
105
|
+
}
|
|
106
|
+
const chain = b.verifyChain ? b.verifyChain() : null;
|
|
107
|
+
const events = b.timeline(2000);
|
|
108
|
+
verified = events.filter((e) => e.kind === "verify").length;
|
|
109
|
+
say(`board ${boardDir}`);
|
|
110
|
+
say(`head seq ${head.seq} chain ${chain?.ok ? "OK (anchored)" : "?"}${chain?.brokenAtSeq != null ? ` BROKEN @ ${chain.brokenAtSeq}` : ""}`);
|
|
111
|
+
say(`tasks ${cards.length} total — ${Object.entries(byStatus).map(([k, v]) => k + " " + v).join(" / ")}`);
|
|
112
|
+
say(`accept ${withAcc} task(s) carry acceptance verify events: ${verified}`);
|
|
113
|
+
} finally { try { b.close(); } catch { } }
|
|
114
|
+
return 0;
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
const [cmd, ...rest] = process.argv.slice(2);
|
|
118
|
+
if (!cmd || cmd === "-h" || cmd === "--help") { usage(); process.exit(0); }
|
|
119
|
+
else if (cmd === "--version" || cmd === "-v") {
|
|
120
|
+
const pkg = JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf8"));
|
|
121
|
+
console.log(pkg.version);
|
|
122
|
+
process.exit(0);
|
|
123
|
+
} else if (cmd === "init") process.exit(cmdInit(rest));
|
|
124
|
+
else if (cmd === "daemon") process.exit(await cmdDaemon());
|
|
125
|
+
else if (cmd === "status") process.exit(await cmdStatus());
|
|
126
|
+
else { warn(`unknown command: ${cmd}`); usage(); process.exit(1); }
|