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.
Files changed (134) hide show
  1. package/LICENSE +201 -0
  2. package/NOTICE +23 -0
  3. package/README.md +97 -2
  4. package/README.zh-CN.md +89 -0
  5. package/bin/proofdeck.js +126 -0
  6. package/board/LICENSE +201 -0
  7. package/board/README.md +473 -0
  8. package/board/README.zh-CN.md +424 -0
  9. package/board/dist/_chk.db-shm +0 -0
  10. package/board/dist/_chk.db-wal +0 -0
  11. package/board/dist/adapters.d.ts +40 -0
  12. package/board/dist/adapters.d.ts.map +1 -0
  13. package/board/dist/adapters.js +124 -0
  14. package/board/dist/adapters.js.map +1 -0
  15. package/board/dist/board.d.ts +628 -0
  16. package/board/dist/board.d.ts.map +1 -0
  17. package/board/dist/board.js +2767 -0
  18. package/board/dist/board.js.map +1 -0
  19. package/board/dist/cli.d.ts +3 -0
  20. package/board/dist/cli.d.ts.map +1 -0
  21. package/board/dist/cli.js +1663 -0
  22. package/board/dist/cli.js.map +1 -0
  23. package/board/dist/config.d.ts +57 -0
  24. package/board/dist/config.d.ts.map +1 -0
  25. package/board/dist/config.js +99 -0
  26. package/board/dist/config.js.map +1 -0
  27. package/board/dist/db.d.ts +9 -0
  28. package/board/dist/db.d.ts.map +1 -0
  29. package/board/dist/db.js +506 -0
  30. package/board/dist/db.js.map +1 -0
  31. package/board/dist/git.d.ts +35 -0
  32. package/board/dist/git.d.ts.map +1 -0
  33. package/board/dist/git.js +147 -0
  34. package/board/dist/git.js.map +1 -0
  35. package/board/dist/index.d.ts +18 -0
  36. package/board/dist/index.d.ts.map +1 -0
  37. package/board/dist/index.js +13 -0
  38. package/board/dist/index.js.map +1 -0
  39. package/board/dist/mcp-config.d.ts +26 -0
  40. package/board/dist/mcp-config.d.ts.map +1 -0
  41. package/board/dist/mcp-config.js +88 -0
  42. package/board/dist/mcp-config.js.map +1 -0
  43. package/board/dist/mcp.d.ts +3 -0
  44. package/board/dist/mcp.d.ts.map +1 -0
  45. package/board/dist/mcp.js +949 -0
  46. package/board/dist/mcp.js.map +1 -0
  47. package/board/dist/quickstart.d.ts +75 -0
  48. package/board/dist/quickstart.d.ts.map +1 -0
  49. package/board/dist/quickstart.js +156 -0
  50. package/board/dist/quickstart.js.map +1 -0
  51. package/board/dist/serve.d.ts +10 -0
  52. package/board/dist/serve.d.ts.map +1 -0
  53. package/board/dist/serve.js +445 -0
  54. package/board/dist/serve.js.map +1 -0
  55. package/board/dist/signing.d.ts +18 -0
  56. package/board/dist/signing.d.ts.map +1 -0
  57. package/board/dist/signing.js +26 -0
  58. package/board/dist/signing.js.map +1 -0
  59. package/board/dist/sync.d.ts +49 -0
  60. package/board/dist/sync.d.ts.map +1 -0
  61. package/board/dist/sync.js +158 -0
  62. package/board/dist/sync.js.map +1 -0
  63. package/board/dist/types.d.ts +359 -0
  64. package/board/dist/types.d.ts.map +1 -0
  65. package/board/dist/types.js +20 -0
  66. package/board/dist/types.js.map +1 -0
  67. package/board/docs/adr/0001-shared-worktree-collision.md +102 -0
  68. package/board/docs/adr/0001-shared-worktree-collision.zh-CN.md +90 -0
  69. package/board/docs/attribution.md +123 -0
  70. package/board/docs/attribution.zh-CN.md +104 -0
  71. package/board/docs/development-workflow.md +81 -0
  72. package/board/docs/development-workflow.zh-CN.md +75 -0
  73. package/board/docs/diagrams/banner.png +0 -0
  74. package/board/docs/diagrams/banner.svg +1 -0
  75. package/board/docs/diagrams/before-after.png +0 -0
  76. package/board/docs/diagrams/before-after.svg +1 -0
  77. package/board/docs/diagrams/governance-chain.png +0 -0
  78. package/board/docs/diagrams/governance-chain.svg +1 -0
  79. package/board/docs/diagrams/value-flow.png +0 -0
  80. package/board/docs/diagrams/value-flow.svg +1 -0
  81. package/board/docs/entry-point.md +81 -0
  82. package/board/docs/entry-point.zh-CN.md +65 -0
  83. package/board/docs/kanban.png +0 -0
  84. package/board/docs/octoryn-mark.png +0 -0
  85. package/board/docs/registry-metadata.md +34 -0
  86. package/board/docs/registry-metadata.zh-CN.md +30 -0
  87. package/board/package.json +87 -0
  88. package/config.example.json +71 -0
  89. package/daemon.js +1112 -0
  90. package/docs/assets/demo.gif +0 -0
  91. package/docs/demo-run.mjs +61 -0
  92. package/docs/render-demo.py +94 -0
  93. package/e2e/verify-acceptance.mjs +150 -0
  94. package/e2e/verify-antifraud.mjs +128 -0
  95. package/e2e/verify-caps.mjs +46 -0
  96. package/e2e/verify-checkpoint.mjs +208 -0
  97. package/e2e/verify-firstclass.mjs +110 -0
  98. package/e2e/verify-judge.mjs +52 -0
  99. package/e2e/verify-lease.mjs +95 -0
  100. package/e2e/verify-replay.mjs +92 -0
  101. package/e2e/verify-resilience.mjs +323 -0
  102. package/e2e/verify-review.mjs +86 -0
  103. package/e2e/verify-scheduling.mjs +110 -0
  104. package/e2e/verify-schema-evolution.mjs +107 -0
  105. package/e2e/verify-sla-digest.mjs +105 -0
  106. package/guard.js +97 -0
  107. package/lib/adapters/codex.js +206 -0
  108. package/lib/billing-convert.js +57 -0
  109. package/lib/board.js +46 -0
  110. package/lib/caps.js +35 -0
  111. package/lib/checkpoint.js +130 -0
  112. package/lib/gating.js +218 -0
  113. package/lib/guard-core.mjs +108 -0
  114. package/lib/http.js +161 -0
  115. package/lib/judge.js +89 -0
  116. package/lib/lease.js +93 -0
  117. package/lib/notify.js +56 -0
  118. package/lib/platform.js +120 -0
  119. package/lib/replay.js +68 -0
  120. package/lib/review.js +40 -0
  121. package/lib/runner.js +152 -0
  122. package/lib/schedule.js +59 -0
  123. package/lib/sla.js +42 -0
  124. package/lib/spans.js +36 -0
  125. package/lib/starve.js +43 -0
  126. package/lib/store.js +109 -0
  127. package/lib/supply.js +101 -0
  128. package/lib/usage.js +103 -0
  129. package/lib/verify.js +223 -0
  130. package/lib/watchdog-core.mjs +68 -0
  131. package/lib/watchdog-worker.mjs +75 -0
  132. package/package.json +55 -4
  133. package/scripts/run-daemon.sh +18 -0
  134. 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
- # Temporary Holding Version
1
+ # ProofDeck
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **A verification-first task board and orchestrator for coding-agent fleets.**
4
+
5
+ Agents claim done. ProofDeck demands proof.
6
+
7
+ [![CI](https://github.com/kumu314/proofdeck/actions/workflows/ci.yml/badge.svg)](https://github.com/kumu314/proofdeck/actions/workflows/ci.yml)
8
+ [![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
9
+ ![node](https://img.shields.io/badge/node-%E2%89%A522.5-green.svg)
10
+
11
+ ![A fake "done" — count=1 where the acceptance said ≥3 — gets rejected by the real verify engine](docs/assets/demo.gif)
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.
@@ -0,0 +1,89 @@
1
+ # ProofDeck
2
+
3
+ **验证优先的编码 agent 舰队任务板与编排器。**
4
+
5
+ Agent 说 done,ProofDeck 要证据。
6
+
7
+ ![一次"假完成"(验收要 count≥3,产物只有 1)被真实验证引擎当场拒绝](docs/assets/demo.gif)
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)的修改版发行。
@@ -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); }