proofdeck 0.0.0-stage → 0.1.1
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 +152 -2
- package/README.zh-CN.md +152 -0
- package/bin/proofdeck.js +191 -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 +72 -0
- package/daemon.js +1148 -0
- package/docs/assets/demo.gif +0 -0
- package/docs/assets/logo-512.png +0 -0
- package/docs/assets/logo.svg +31 -0
- package/docs/assets/social-preview.png +0 -0
- package/docs/demo-run.mjs +61 -0
- package/docs/render-demo.py +94 -0
- package/docs/render-logo.py +101 -0
- package/docs/task-book.md +58 -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,153 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
|
+
<img src="docs/assets/logo.svg" width="150" alt="ProofDeck logo">
|
|
2
3
|
|
|
3
|
-
|
|
4
|
+
<h1>ProofDeck</h1>
|
|
5
|
+
|
|
6
|
+
<p><strong>Verification-first task board & orchestrator for coding-agent fleets.</strong><br>
|
|
7
|
+
<em>Agents claim done. ProofDeck demands proof.</em></p>
|
|
8
|
+
|
|
9
|
+
<p>
|
|
10
|
+
<a href="https://github.com/kumu314/proofdeck/actions/workflows/ci.yml"><img src="https://github.com/kumu314/proofdeck/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
|
|
11
|
+
<a href="https://www.npmjs.com/package/proofdeck"><img src="https://img.shields.io/npm/v/proofdeck.svg" alt="npm"></a>
|
|
12
|
+
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="license"></a>
|
|
13
|
+
<img src="https://img.shields.io/badge/node-%E2%89%A522.5-green.svg" alt="node ≥22.5">
|
|
14
|
+
<img src="https://img.shields.io/badge/platform-Windows%20%7C%20Linux-lightgrey.svg" alt="platform">
|
|
15
|
+
</p>
|
|
16
|
+
|
|
17
|
+
<p>
|
|
18
|
+
<a href="#quick-start">Quick start</a> ·
|
|
19
|
+
<a href="#why">Why</a> ·
|
|
20
|
+
<a href="#architecture">Architecture</a> ·
|
|
21
|
+
<a href="#the-five-check-families">Checks</a> ·
|
|
22
|
+
<a href="./README.zh-CN.md">中文文档</a>
|
|
23
|
+
</p>
|
|
24
|
+
</div>
|
|
25
|
+
|
|
26
|
+
<div align="center">
|
|
27
|
+
<img src="docs/assets/demo.gif" width="720" alt="A fake done gets rejected by the real verify engine">
|
|
28
|
+
<p><sub><b>The gate in 7 seconds:</b> an agent claims <i>done</i> on 1 item where acceptance said ≥3 — the real verify engine rejects it, the task returns to open, a verify event lands in the hash chain. Rendered from an actual run; nothing fabricated.</sub></p>
|
|
29
|
+
</div>
|
|
30
|
+
|
|
31
|
+
## Why
|
|
32
|
+
|
|
33
|
+
One coding agent (Claude Code, Codex CLI, Gemini CLI, …) → you review everything it does, and review works. **Several agents in parallel → review becomes the bottleneck**, and two failure modes compound:
|
|
34
|
+
|
|
35
|
+
| Failure mode | What it looks like | Industry context |
|
|
36
|
+
|---|---|---|
|
|
37
|
+
| **False affirmatives** | A fallback makes it "work"; tests pass; the flaw ships | *Reward hacking* — active research area (ImpossibleBench 2025, Anthropic 2026) |
|
|
38
|
+
| **Silent death** | Stalls, exits 0 with nothing done, burns budget in a loop | Nobody notices until the deadline |
|
|
39
|
+
|
|
40
|
+
ProofDeck's answer is to make **acceptance criteria a first-class column on every task** and refuse "done" that lacks evidence — then wrap that gate in everything a fleet needs.
|
|
41
|
+
|
|
42
|
+
## The gate — how `done` gets proven
|
|
43
|
+
|
|
44
|
+
1. **Declare.** Every task carries machine-checkable acceptance criteria.
|
|
45
|
+
2. **Verify.** On completion a fail-closed engine runs them — five check families, unknown check types are FAIL, never skip.
|
|
46
|
+
3. **Judge.** When machine checks aren't enough, an LLM judge reviews the trajectory against the criteria.
|
|
47
|
+
4. **Record.** The verdict lands in an **append-only sha256 hash chain** — who claimed, who verified, when, with evidence.
|
|
48
|
+
5. **React.** Failed tasks retry with backoff, park for human review, or route to another agent by capability. Never silently done.
|
|
49
|
+
|
|
50
|
+
## Features
|
|
51
|
+
|
|
52
|
+
| Area | What you get |
|
|
53
|
+
|---|---|
|
|
54
|
+
| **Board** | Shared SQLite-backed task board with an MCP surface — any MCP-speaking agent reads/writes it |
|
|
55
|
+
| **Evidence** | Append-only sha256 chain over tasks/notes/messages/verify events; `verifyChain()` head anchoring |
|
|
56
|
+
| **Orchestration** | Priority lanes with aging · automatic retry with backoff · supply breaker · capability routing (`needs` × face capabilities) |
|
|
57
|
+
| **Judgment** | LLM judge (V1.5) with acceptance-only mode; human (V3) and cross-review (V2) escalation |
|
|
58
|
+
| **Observability** | Full event replay (time travel to any seq) · OpenTelemetry-style spans · per-run usage ledger |
|
|
59
|
+
| **Ops** | SLA due-dates · owner digest · leases · watchdog · offline-first (one SQLite file, no cloud) |
|
|
60
|
+
|
|
61
|
+
## Quick start
|
|
62
|
+
|
|
63
|
+
Requirements: **Node ≥ 22.5** (native `node:sqlite`; `better-sqlite3` fallback for older runtimes), Windows or Linux.
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
npx proofdeck init # scaffold: daemon.config.json + .proofdeck/ + control.token
|
|
67
|
+
# edit daemon.config.json — point agents.codex.script at a CLI you have
|
|
68
|
+
npx proofdeck daemon # start the daemon (board + control plane + scheduler)
|
|
69
|
+
npx proofdeck status # board head, task counts, acceptance coverage
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
From a git checkout:
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
git clone https://github.com/kumu314/proofdeck && cd proofdeck
|
|
76
|
+
npm install # zero native module deps
|
|
77
|
+
node bin/proofdeck.js init && node bin/proofdeck.js daemon
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Define a task with acceptance criteria, dispatch your agent, and watch the gate. Any agent that speaks MCP can read/write the board.
|
|
81
|
+
|
|
82
|
+
**Task books.** A task's instruction text lives in a file under `briefs/` with a small ```bridge fence carrying dispatch metadata (`auto`, `risk`, …); the card references it by path. The gate reads the book before dispatch — full format and gotchas in [docs/task-book.md](./docs/task-book.md).
|
|
83
|
+
|
|
84
|
+
## Architecture
|
|
85
|
+
|
|
86
|
+
```
|
|
87
|
+
┌───────────────────────────────────────────┐
|
|
88
|
+
│ ProofDeck │
|
|
89
|
+
human ──define──────▶│ daemon: claim → run face → verify gate │
|
|
90
|
+
agents ◀──MCP────────│ │ │
|
|
91
|
+
(CLI faces) ──run──▶│ ├─ V1 checks (fail-closed) │
|
|
92
|
+
│ ├─ V1.5 LLM judge │
|
|
93
|
+
│ ├─ retry / breaker / routing │
|
|
94
|
+
│ ▼ │
|
|
95
|
+
│ blackboard: SQLite WAL + append-only │
|
|
96
|
+
│ sha256 hash chain (tasks, notes, verify │
|
|
97
|
+
│ events, messages — tamper-evident) │
|
|
98
|
+
└───────────────────────────────────────────┘
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
| Component | File | Role |
|
|
102
|
+
|---|---|---|
|
|
103
|
+
| Board | `board/` | Vendored, modified [octopus-blackboard](https://github.com/octoryn/octopus-blackboard) fork — hash chain, MCP, acceptance/verification schema (see [NOTICE](./NOTICE)) |
|
|
104
|
+
| Verify engine | `lib/verify.js` | Fail-closed check runner, task-column-first acceptance |
|
|
105
|
+
| LLM judge | `lib/judge.js` | V1.5 trajectory review; unavailable judge fails open |
|
|
106
|
+
| Scheduler | `lib/schedule.js` | P0–P3 lanes, aging, retry policy (pure, unit-tested) |
|
|
107
|
+
| Routing | `lib/caps.js` | `needs` × face-capability matching |
|
|
108
|
+
| Replay | `lib/replay.js` | Fold timeline to any seq, diff against now |
|
|
109
|
+
| Platform | `lib/platform.js` | Dual-OS process primitives (killTree / getProcessInfo) |
|
|
110
|
+
| Adapters | `lib/adapters/` | One small module per agent face; `codex.js` is the reference implementation |
|
|
111
|
+
|
|
112
|
+
## The five check families
|
|
113
|
+
|
|
114
|
+
| Check | Asserts | Example |
|
|
115
|
+
|---|---|---|
|
|
116
|
+
| `fileExists` | File exists, ≥ `minBytes` | a rendered artifact actually shipped |
|
|
117
|
+
| `countAtLeast` | JSON value (number/array length) ≥ `min` | `report.count ≥ 3` |
|
|
118
|
+
| `countOccurrences` | Literal substring count ≥ `minCount` | changelog mentions the fix |
|
|
119
|
+
| `countMatches` | JSON-path match count ≥ `min` | every item has a status field |
|
|
120
|
+
| `referencesExist` | Files referenced in JSON exist | every asset in the manifest is on disk |
|
|
121
|
+
|
|
122
|
+
Unknown check types are **FAIL** — a typo in acceptance criteria never silently passes.
|
|
123
|
+
|
|
124
|
+
## Design principles
|
|
125
|
+
|
|
126
|
+
- **Fail closed.** Missing acceptance is flagged on every dispatch, never skipped.
|
|
127
|
+
- **Evidence over vibes.** Verification results are hash-chain events, not chat messages.
|
|
128
|
+
- **The board is the truth.** Agents come and go; the append-only timeline remembers.
|
|
129
|
+
- **Boring storage.** One SQLite file per deployment — no cloud, no telemetry.
|
|
130
|
+
- **Prompts via stdin, never argv.** Long CJK text corrupts through some shells (a production lesson).
|
|
131
|
+
|
|
132
|
+
## Testing
|
|
133
|
+
|
|
134
|
+
13 e2e suites run against real boards — verification, anti-fraud, judge, scheduling, resilience (watchdog/guard), replay, SLA/digest, lease, schema evolution:
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
npm test # native backend
|
|
138
|
+
OCTOBOARD_BACKEND=better-sqlite3 npm test # fallback backend
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
CI runs the full matrix on Windows + ubuntu, both backends — the native cell installs with `--omit=optional`, proving zero-native-dependency installs.
|
|
142
|
+
|
|
143
|
+
## Status
|
|
144
|
+
|
|
145
|
+
`v0.1.0`. Daily-production-proven on Windows (a personal multi-agent fleet, hundreds of tasks). Linux is CI-validated (13/13) with thinner real-world mileage — rough edges expected, reports welcome.
|
|
146
|
+
|
|
147
|
+
## Contributing & security
|
|
148
|
+
|
|
149
|
+
[CONTRIBUTING.md](./CONTRIBUTING.md) — PRs need CI green and pasted evidence, same standard as our agents. Security disclosures via [SECURITY.md](./SECURITY.md) (private reporting, 7-day response). Releases tagged — see [CHANGELOG.md](./CHANGELOG.md).
|
|
150
|
+
|
|
151
|
+
## License
|
|
152
|
+
|
|
153
|
+
[Apache-2.0](./LICENSE). Includes a modified distribution of [octopus-blackboard](https://github.com/octoryn/octopus-blackboard) by Ran Tao / octoryn — see [NOTICE](./NOTICE).
|
package/README.zh-CN.md
ADDED
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
<img src="docs/assets/logo.svg" width="150" alt="ProofDeck logo">
|
|
3
|
+
|
|
4
|
+
<h1>ProofDeck</h1>
|
|
5
|
+
|
|
6
|
+
<p><strong>验证优先的编码 agent 舰队任务板与编排器。</strong><br>
|
|
7
|
+
<em>Agent 说 done,ProofDeck 要证据。</em></p>
|
|
8
|
+
|
|
9
|
+
<p>
|
|
10
|
+
<a href="https://github.com/kumu314/proofdeck/actions/workflows/ci.yml"><img src="https://github.com/kumu314/proofdeck/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
|
|
11
|
+
<a href="https://www.npmjs.com/package/proofdeck"><img src="https://img.shields.io/npm/v/proofdeck.svg" alt="npm"></a>
|
|
12
|
+
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="license"></a>
|
|
13
|
+
<img src="https://img.shields.io/badge/node-%E2%89%A522.5-green.svg" alt="node ≥22.5">
|
|
14
|
+
<img src="https://img.shields.io/badge/platform-Windows%20%7C%20Linux-lightgrey.svg" alt="platform">
|
|
15
|
+
</p>
|
|
16
|
+
|
|
17
|
+
<p>
|
|
18
|
+
<a href="#快速开始">快速开始</a> ·
|
|
19
|
+
<a href="#为什么">为什么</a> ·
|
|
20
|
+
<a href="#架构">架构</a> ·
|
|
21
|
+
<a href="#五类检查族">检查族</a> ·
|
|
22
|
+
<a href="./README.md">English</a>
|
|
23
|
+
</p>
|
|
24
|
+
</div>
|
|
25
|
+
|
|
26
|
+
<div align="center">
|
|
27
|
+
<img src="docs/assets/demo.gif" width="720" alt="假完成被真实验证引擎当场拒绝">
|
|
28
|
+
<p><sub><b>7 秒看懂门禁:</b>agent 在验收要求 count≥3 的任务上只交付了 1 项就声称 <i>done</i>——真实验证引擎当场拒绝,任务退回 open 重新派发,验证事件落进哈希链。内容来自真实运行渲染,无任何虚构。</sub></p>
|
|
29
|
+
</div>
|
|
30
|
+
|
|
31
|
+
## 为什么
|
|
32
|
+
|
|
33
|
+
只跑一个编码 agent(Claude Code、Codex CLI、Gemini CLI……)时,你会 review 它的每一步,review 是有效的。但你一旦**并行跑好几个**,review 就成了瓶颈,两种失败模式叠加:
|
|
34
|
+
|
|
35
|
+
| 失败模式 | 典型表现 | 业界语境 |
|
|
36
|
+
|---|---|---|
|
|
37
|
+
| **虚假确认** | 加个 fallback 让代码"能跑",测试也过了,缺陷照样上线 | *reward hacking*——活跃研究课题(ImpossibleBench 2025、Anthropic 2026) |
|
|
38
|
+
| **静默死亡** | 卡住、rc=0 但什么都没干、预算烧进死循环 | 截止日期前没人发现 |
|
|
39
|
+
|
|
40
|
+
ProofDeck 的答案是:**把验收标准做成每张任务的一等公民**,拒绝没有证据的"done"——再在这道门禁外面套上整支舰队需要的一切。
|
|
41
|
+
|
|
42
|
+
## 门禁——"done" 如何被证明
|
|
43
|
+
|
|
44
|
+
1. **声明。** 每张任务携带机器可校验的验收标准。
|
|
45
|
+
2. **验证。** 完成时 fail-closed 引擎执行验收——五类检查,未知类型一律 FAIL,绝不跳过。
|
|
46
|
+
3. **复核。** 机器检查不够时,LLM judge 依据验收标准复核轨迹。
|
|
47
|
+
4. **记账。** 判定连同"谁认领、谁验证、何时"写进**追加式 sha256 哈希链**。
|
|
48
|
+
5. **响应。** 失败任务按退避重试、转人工复核、或按能力路由给其他 agent——绝不静默标记完成。
|
|
49
|
+
|
|
50
|
+
## 特性总览
|
|
51
|
+
|
|
52
|
+
| 领域 | 能力 |
|
|
53
|
+
|---|---|
|
|
54
|
+
| **黑板** | SQLite 共享任务板 + MCP 面——任何说 MCP 的 agent 可读写 |
|
|
55
|
+
| **证据** | 任务/注记/消息/验证事件的追加式 sha256 链;`verifyChain()` 锚定校验 |
|
|
56
|
+
| **编排** | 带 aging 的优先级车道 · 指数退避自动重试 · 供应熔断 · 能力路由(`needs` × 面能力) |
|
|
57
|
+
| **判定** | LLM judge(V1.5,acceptance-only 模式);人工(V3)与交叉评审(V2)升级 |
|
|
58
|
+
| **观测** | 全量事件回放(时间旅行到任意 seq)· OpenTelemetry 风格 span · 单轮用量台账 |
|
|
59
|
+
| **运维** | SLA 到期 · owner 摘要 · 租约 · 看门狗 · 离线优先(一个 SQLite 文件,无云依赖) |
|
|
60
|
+
|
|
61
|
+
## 快速开始
|
|
62
|
+
|
|
63
|
+
环境要求:**Node ≥ 22.5**(原生 `node:sqlite`;旧运行时用 `better-sqlite3` 回退),Windows 或 Linux。
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
npx proofdeck init # 脚手架:daemon.config.json + .proofdeck/ + control.token
|
|
67
|
+
# 编辑 daemon.config.json —— 把 agents.codex.script 指向你有的 CLI
|
|
68
|
+
npx proofdeck daemon # 起守护(黑板 + 控制面 + 调度器)
|
|
69
|
+
npx proofdeck status # 看板块 head、任务统计、验收覆盖
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
从 git 检出运行:
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
git clone https://github.com/kumu314/proofdeck && cd proofdeck
|
|
76
|
+
npm install # 零原生模块依赖
|
|
77
|
+
node bin/proofdeck.js init && node bin/proofdeck.js daemon
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
给任务写上验收标准、派出你的 agent,然后看门禁工作。任何说 MCP 的 agent 都能读写黑板。
|
|
81
|
+
|
|
82
|
+
**任务书。** 任务的题面放在 `briefs/` 下的文件里,带一小段 ```bridge 围栏块承载派发元数据(`auto`、`risk`……),卡面只放文件指针。门禁在派发前会读任务书做风险评估——完整格式与坑位见 [docs/task-book.md](./docs/task-book.md)。
|
|
83
|
+
|
|
84
|
+
## 架构
|
|
85
|
+
|
|
86
|
+
```
|
|
87
|
+
┌───────────────────────────────────────────┐
|
|
88
|
+
│ ProofDeck │
|
|
89
|
+
人 ──定义任务────────▶│ 守护:认领 → 跑面 → 验证门禁 │
|
|
90
|
+
agents ◀──MCP────────│ │ │
|
|
91
|
+
(CLI 面) ──运行─────▶│ ├─ V1 检查(fail-closed) │
|
|
92
|
+
│ ├─ V1.5 LLM judge │
|
|
93
|
+
│ ├─ 重试 / 熔断 / 能力路由 │
|
|
94
|
+
│ ▼ │
|
|
95
|
+
│ 黑板:SQLite WAL + 追加式 sha256 哈希链 │
|
|
96
|
+
│ (任务/注记/验证事件/消息——防篡改可取证)│
|
|
97
|
+
└───────────────────────────────────────────┘
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
| 组件 | 文件 | 职责 |
|
|
101
|
+
|---|---|---|
|
|
102
|
+
| 黑板 | `board/` | [octopus-blackboard](https://github.com/octoryn/octopus-blackboard) 修改版发行——哈希链、MCP 面、验收/验证 schema(见 [NOTICE](./NOTICE)) |
|
|
103
|
+
| 验证引擎 | `lib/verify.js` | fail-closed 检查执行器,任务列优先的验收读取 |
|
|
104
|
+
| LLM judge | `lib/judge.js` | V1.5 轨迹复核;judge 不可用时优雅跳过 |
|
|
105
|
+
| 调度核 | `lib/schedule.js` | P0–P3 车道、aging、重试策略(纯函数、单测覆盖) |
|
|
106
|
+
| 路由 | `lib/caps.js` | `needs` × 面能力匹配 |
|
|
107
|
+
| 回放 | `lib/replay.js` | 折叠时间线到任意 seq,与当前态 diff |
|
|
108
|
+
| 平台 | `lib/platform.js` | 双 OS 进程原语(killTree / getProcessInfo) |
|
|
109
|
+
| 适配器 | `lib/adapters/` | 每个 agent 面一个小模块;`codex.js` 是参考实现 |
|
|
110
|
+
|
|
111
|
+
## 五类检查族
|
|
112
|
+
|
|
113
|
+
| 检查 | 断言 | 示例 |
|
|
114
|
+
|---|---|---|
|
|
115
|
+
| `fileExists` | 文件存在且 ≥ `minBytes` | 渲染产物真的出货了 |
|
|
116
|
+
| `countAtLeast` | JSON 值(数字/数组长度)≥ `min` | `report.count ≥ 3` |
|
|
117
|
+
| `countOccurrences` | 字面量子串出现次数 ≥ `minCount` | changelog 里提到了本次修复 |
|
|
118
|
+
| `countMatches` | JSON 路径匹配数 ≥ `min` | 每个条目都有 status 字段 |
|
|
119
|
+
| `referencesExist` | JSON 里引用的文件都存在 | manifest 里每个资产都在盘上 |
|
|
120
|
+
|
|
121
|
+
未知检查类型一律 **FAIL**——验收标准里的拼写错误永远不会静默放行。
|
|
122
|
+
|
|
123
|
+
## 设计原则
|
|
124
|
+
|
|
125
|
+
- **Fail closed。** 缺验收标准的任务每次派发都被标注提示,绝不静默跳过。
|
|
126
|
+
- **证据而非感觉。** 验证结果是哈希链事件,不是聊天记录。
|
|
127
|
+
- **黑板即真相。** Agent 来来去去;追加式时间线记得一切。
|
|
128
|
+
- **无聊的存储。** 每次部署一个 SQLite 文件——无云、无遥测。
|
|
129
|
+
- **题面走 stdin,绝不走 argv。** 长中文文本过某些 shell 会被搅坏(生产线换来的教训)。
|
|
130
|
+
|
|
131
|
+
## 测试
|
|
132
|
+
|
|
133
|
+
13 套端到端套件打在真实黑板上——验证、防刷分、judge、调度、韧性(看门狗/guard)、回放、SLA/摘要、租约、schema 演进:
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
npm test # 原生后端
|
|
137
|
+
OCTOBOARD_BACKEND=better-sqlite3 npm test # 回退后端
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
CI 在 Windows + ubuntu × 双后端四格矩阵上跑全套;native 格用 `--omit=optional` 安装——在干净机器上实证"零原生依赖"。
|
|
141
|
+
|
|
142
|
+
## 状态
|
|
143
|
+
|
|
144
|
+
`v0.1.0`。Windows 上日常生产淬炼(个人多 agent 舰队,数百张任务)。Linux 已 CI 验证(13/13)但真实里程较薄——遇到坑请报 issue。
|
|
145
|
+
|
|
146
|
+
## 参与贡献与安全
|
|
147
|
+
|
|
148
|
+
[CONTRIBUTING.md](./CONTRIBUTING.md)——PR 需要 CI 绿 + 贴出证据,和我们的 agent 一个标准。安全披露走 [SECURITY.md](./SECURITY.md)(私有报告,7 天响应)。发版打 tag——见 [CHANGELOG.md](./CHANGELOG.md)。
|
|
149
|
+
|
|
150
|
+
## 许可
|
|
151
|
+
|
|
152
|
+
[Apache-2.0](./LICENSE)。含 [octopus-blackboard](https://github.com/octoryn/octopus-blackboard)(Ran Tao / octoryn)修改版发行——见 [NOTICE](./NOTICE)。
|