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.
Files changed (139) hide show
  1. package/LICENSE +201 -0
  2. package/NOTICE +23 -0
  3. package/README.md +152 -2
  4. package/README.zh-CN.md +152 -0
  5. package/bin/proofdeck.js +191 -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 +72 -0
  89. package/daemon.js +1148 -0
  90. package/docs/assets/demo.gif +0 -0
  91. package/docs/assets/logo-512.png +0 -0
  92. package/docs/assets/logo.svg +31 -0
  93. package/docs/assets/social-preview.png +0 -0
  94. package/docs/demo-run.mjs +61 -0
  95. package/docs/render-demo.py +94 -0
  96. package/docs/render-logo.py +101 -0
  97. package/docs/task-book.md +58 -0
  98. package/e2e/verify-acceptance.mjs +150 -0
  99. package/e2e/verify-antifraud.mjs +128 -0
  100. package/e2e/verify-caps.mjs +46 -0
  101. package/e2e/verify-checkpoint.mjs +208 -0
  102. package/e2e/verify-firstclass.mjs +110 -0
  103. package/e2e/verify-judge.mjs +52 -0
  104. package/e2e/verify-lease.mjs +95 -0
  105. package/e2e/verify-replay.mjs +92 -0
  106. package/e2e/verify-resilience.mjs +323 -0
  107. package/e2e/verify-review.mjs +86 -0
  108. package/e2e/verify-scheduling.mjs +110 -0
  109. package/e2e/verify-schema-evolution.mjs +107 -0
  110. package/e2e/verify-sla-digest.mjs +105 -0
  111. package/guard.js +97 -0
  112. package/lib/adapters/codex.js +206 -0
  113. package/lib/billing-convert.js +57 -0
  114. package/lib/board.js +46 -0
  115. package/lib/caps.js +35 -0
  116. package/lib/checkpoint.js +130 -0
  117. package/lib/gating.js +218 -0
  118. package/lib/guard-core.mjs +108 -0
  119. package/lib/http.js +161 -0
  120. package/lib/judge.js +89 -0
  121. package/lib/lease.js +93 -0
  122. package/lib/notify.js +56 -0
  123. package/lib/platform.js +120 -0
  124. package/lib/replay.js +68 -0
  125. package/lib/review.js +40 -0
  126. package/lib/runner.js +152 -0
  127. package/lib/schedule.js +59 -0
  128. package/lib/sla.js +42 -0
  129. package/lib/spans.js +36 -0
  130. package/lib/starve.js +43 -0
  131. package/lib/store.js +109 -0
  132. package/lib/supply.js +101 -0
  133. package/lib/usage.js +103 -0
  134. package/lib/verify.js +223 -0
  135. package/lib/watchdog-core.mjs +68 -0
  136. package/lib/watchdog-worker.mjs +75 -0
  137. package/package.json +55 -4
  138. package/scripts/run-daemon.sh +18 -0
  139. 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
- # Temporary Holding Version
1
+ <div align="center">
2
+ <img src="docs/assets/logo.svg" width="150" alt="ProofDeck logo">
2
3
 
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.
4
+ <h1>ProofDeck</h1>
5
+
6
+ <p><strong>Verification-first task board &amp; 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).
@@ -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)。