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/board/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.
@@ -0,0 +1,473 @@
1
+ ![Octopus Blackboard](docs/diagrams/banner.png)
2
+
3
+ # Octopus Blackboard
4
+
5
+ **A shared memory and coordination layer for AI coding agents.**
6
+
7
+ > Agents do not need another boss. They need a shared blackboard.
8
+
9
+ [简体中文](./README.zh-CN.md)
10
+
11
+ > **Part of [Octopus Core](https://github.com/octoryn) — the open infrastructure stack for governed AI.** One job per repo, along the agent lifecycle: [Scout](https://github.com/octoryn/octopus-scout) · [Observe](https://github.com/octoryn/octopus-observe) · [Experience](https://github.com/octoryn/octopus-experience) · [Blackboard](https://github.com/octoryn/octopus-blackboard) · [Runtime](https://github.com/octoryn/octopus-runtime) · [Replay](https://github.com/octoryn/octopus-replay) — with [Inspect](https://github.com/octoryn/octopus-inspect) governing every stage.
12
+ >
13
+ > **This repo — Blackboard · Coordinate:** Shared cognition for coding agents.
14
+
15
+ ![How it works: agents connect over MCP to a shared blackboard that records and exposes but never orchestrates, producing a conflict-aware kanban, AI attribution, a CI review gate, and a tamper-evident audit trail](docs/diagrams/value-flow.png)
16
+
17
+ ---
18
+
19
+ Claude Code, Codex, Gemini CLI, Cursor, and your local agents all work on the
20
+ same repo — but they are blind to each other. One refactors auth while another
21
+ rewrites the same file. Context is scattered across CLIs. Nobody can replay what
22
+ happened.
23
+
24
+ Octopus Blackboard is **not an orchestrator.** It does not schedule agents,
25
+ trigger them, or decide anything on their behalf. It is a passive, local-first
26
+ shared memory that answers six questions:
27
+
28
+ ```text
29
+ Who is working on what → agents, tasks, claims
30
+ What changed → files_changed
31
+ What was decided → decisions
32
+ What evidence exists → evidence
33
+ What risks are open → risks
34
+ What was left for whom → messages, handoffs
35
+ ```
36
+
37
+ Every agent only needs to be able to **read the board, write the board,
38
+ leave messages, and attach evidence.** That's the whole contract.
39
+
40
+ ## Why
41
+
42
+ ![Without a shared board, agents work blind — duplicate edits, no attribution, unseen conflicts. With Octopus Blackboard they share memory and produce a conflict-aware kanban, attribution, a review gate, and an audit trail](docs/diagrams/before-after.png)
43
+
44
+ Enterprises are not primarily afraid that agents aren't smart enough. They are
45
+ afraid that:
46
+
47
+ - Multiple AI tools edit the same code simultaneously
48
+ - Context is scattered across different CLIs
49
+ - There is no shared memory, no audit, no handoff
50
+ - There is no conflict awareness and no way to replay
51
+
52
+ The blackboard cuts straight through this. Every write appends a
53
+ **tamper-evident, hash-chained entry** to an append-only `timeline`, so the
54
+ entire history is auditable and replayable — and any after-the-fact edit to an
55
+ earlier entry breaks verification.
56
+
57
+ ## Get Started in 2 Minutes
58
+
59
+ Blackboard is the easiest way into the Octopus stack — pure coordination memory
60
+ that works today with just Claude Code and Cursor, no orchestrator required.
61
+ One command sets everything up:
62
+
63
+ ```bash
64
+ npx octopus-blackboard quickstart
65
+ ```
66
+
67
+ That single command: creates the local board (`.octoboard/`) if it isn't there,
68
+ **auto-detects your MCP client** (`.claude/` → Claude Code, `.cursor/` → Cursor,
69
+ … otherwise a generic snippet), prints the exact **paste-ready config** for it,
70
+ and proves the board works with one write + one read.
71
+
72
+ Then just:
73
+
74
+ 1. **Paste** the printed config block into the file it names.
75
+ 2. **Reload** your MCP client (restart it, or reopen the project).
76
+ 3. **You're done.** Ask your agent to call `board_status`, then
77
+ `board_note "hello"` — that's your first board action, on a shared,
78
+ tamper-evident timeline.
79
+
80
+ Re-running `quickstart` is always safe: it never clobbers an existing board or
81
+ its history. New to the idea of adopting a coordination layer *first*? See
82
+ [**Why adopt Blackboard first**](docs/entry-point.md).
83
+
84
+ ## Install
85
+
86
+ ```bash
87
+ npm install
88
+ npm run build # compiles to dist/
89
+ ```
90
+
91
+ Requires Node ≥ 22. The board is a single SQLite file under `.octoboard/`,
92
+ discovered by walking up from your working directory (like `.git`).
93
+
94
+ ## See it in action
95
+
96
+ [`examples/two-agents.sh`](./examples/two-agents.sh) plays out the flagship
97
+ scenario — Claude Code and Codex sharing one board on the same repo: a claim
98
+ conflict, a live same-file collision, a decision, attribution, a handoff that
99
+ lands in the other agent's inbox, an AI review, the human-approval CI gate
100
+ (blocked → passes), the accountability scorecard, blame→narrative, and a
101
+ verified hash chain with session signatures. Run it in an empty directory:
102
+
103
+ ```bash
104
+ bash examples/two-agents.sh # needs `octoboard` on PATH
105
+ ```
106
+
107
+ ## CLI
108
+
109
+ ```bash
110
+ octoboard init # create .octoboard/ here
111
+ octoboard status # who's on the board, right now
112
+
113
+ octoboard note "Codex is refactoring auth middleware"
114
+ octoboard claim trust-layer-policy-schema # claim work; warns on conflict
115
+ octoboard message claude "Review policy edge cases before merge"
116
+ octoboard decision "Use hash-chain audit log" --why "tamper-evidence"
117
+ octoboard risk "Migration may break audit replay" --severity high
118
+ octoboard file src/auth.ts --change modified --task trust-layer-policy-schema
119
+ octoboard handoff claude "Tests pass except policy replay" --task trust-layer-policy-schema
120
+
121
+ octoboard timeline # the full hash-chained history
122
+ octoboard verify # confirm the chain is intact
123
+ ```
124
+
125
+ Identity is set with `--as <agent>` or the `OCTOBOARD_AGENT` environment
126
+ variable. Point at a specific board with `--board <dir>` or `OCTOBOARD_DIR`.
127
+
128
+ ### Conflict awareness
129
+
130
+ The board never blocks — it *surfaces*. If two agents claim the same key, or
131
+ touch the same task's files, both writes are recorded and the second agent is
132
+ warned:
133
+
134
+ ```text
135
+ ⚠ CONFLICT: "trust-layer-policy-schema" is also held by codex. Both claims recorded.
136
+ ```
137
+
138
+ ## AI attribution & shared development memory
139
+
140
+ Git records who *pushed* a commit. It does not record which AI agent produced
141
+ the code, in which session, on which machine, whether another AI reviewed it, or
142
+ whether a human approved it. As AI-native development becomes common,
143
+ accountability must move beyond Git authorship.
144
+
145
+ The blackboard adds an attribution layer **on top of** Git — it never rewrites
146
+ history. Git stays the source of code; the blackboard becomes the source of
147
+ attribution.
148
+
149
+ ### Sessions
150
+
151
+ A session is one continuous execution of an agent, and the unit attribution
152
+ hangs off. Starting one makes every subsequent write attribute to it (the active
153
+ session is remembered across CLI invocations, per agent):
154
+
155
+ ```bash
156
+ export OCTOBOARD_AGENT=claude OCTOBOARD_PROVIDER=anthropic \
157
+ OCTOBOARD_MODEL=claude-opus-4-8 OCTOBOARD_CLI=claude-code
158
+
159
+ blackboard session start --label "auth work" # captures machine, branch, repo
160
+ blackboard claim policy-engine
161
+ blackboard file src/policy.ts --change modified
162
+ # ... make a git commit ...
163
+ blackboard link HEAD # attribute the commit's files
164
+ blackboard session stop
165
+ ```
166
+
167
+ Identity is fully provider-independent — `--provider`, `--model`, `--cli`, or
168
+ the matching `OCTOBOARD_*` env vars. Any AI CLI (local or cloud) can register
169
+ itself with no assumptions about a specific vendor.
170
+
171
+ ### Linking commits
172
+
173
+ `blackboard link <rev>` reads the files a commit touched (via Git) and records
174
+ one attribution per file for the active session. Optionally it writes an
175
+ additive `git notes` entry under `refs/notes/blackboard`:
176
+
177
+ ```bash
178
+ blackboard link HEAD --note
179
+ blackboard attribute <sha> --file src/x.ts --actor human --name Ran # manual
180
+ ```
181
+
182
+ ### Reviews
183
+
184
+ ```bash
185
+ blackboard review HEAD --by ai --name codex --outcome approved --note "tests pass"
186
+ blackboard review HEAD --by human --name Ran --outcome approved
187
+ ```
188
+
189
+ ### Querying the shared memory
190
+
191
+ ```bash
192
+ blackboard who src/auth.ts # git authors + AI sessions that touched it
193
+ blackboard who src/auth.ts --line 42 # which session introduced this line
194
+ blackboard explain HEAD # attribution + reviews + related decisions
195
+ blackboard commits claude-code # which commits came from an AI / CLI
196
+ blackboard unreviewed # AI commits never reviewed by a human
197
+ blackboard joint claude codex # files modified by BOTH agents
198
+ blackboard timeline --session <id> # per-session HH:MM timeline
199
+ ```
200
+
201
+ Example `explain`:
202
+
203
+ ```text
204
+ commit 5fa3095… Human Dev <a@b.c> add auth
205
+ produced by:
206
+ ai claude [claude-opus-4-8] — src/auth.ts
207
+ reviews:
208
+ human Ran: approved
209
+ git note: blackboard: produced by claude-code (claude-opus-4-8), session 75b2b7e7…
210
+ ```
211
+
212
+ Every attribution, review, session, and decision is also recorded in the
213
+ hash-chained `timeline`, so the full accountability history is tamper-evident
214
+ and replayable. `blackboard` and `octoboard` are the same command.
215
+
216
+ ## Governance & accountability chain
217
+
218
+ ![The accountability chain: agent does work → attribute the commit → export/import → CI gate blocks unreviewed AI → human approves → merge, all recorded on the tamper-evident timeline](docs/diagrams/governance-chain.png)
219
+
220
+ The point of attribution is to *enforce* something. The chain from work to a
221
+ merge gate:
222
+
223
+ ```text
224
+ agent work → commit attribution → export/import → CI check → human-review gate
225
+ ```
226
+
227
+ ### CI gate (`check`)
228
+
229
+ Turn queries into an enforceable gate. Read-only — it reports pass/fail and
230
+ exits non-zero; the CI system decides what to do. The blackboard never blocks.
231
+
232
+ ```bash
233
+ # In CI, on a PR branch — fail the build if any AI commit isn't human-APPROVED
234
+ # (a rejected / changes-requested review does not clear the gate):
235
+ blackboard check --range origin/main..HEAD --require-human-review
236
+ echo $? # 0 = pass, 1 = violations
237
+
238
+ blackboard check --verify-chain --require-attribution --range origin/main..HEAD
239
+ blackboard check # default gate: verify chain + require human review
240
+ ```
241
+
242
+ ### Portability (`export` / `import` / `trailers`)
243
+
244
+ Attribution is local-first; these make it survive `git push` into a team board
245
+ or CI:
246
+
247
+ ```bash
248
+ blackboard export --range origin/main..HEAD --out attribution.json # on the dev machine
249
+ blackboard import attribution.json # on the team board / CI
250
+ blackboard trailers HEAD # trailer lines for a commit message
251
+ ```
252
+
253
+ `import` is idempotent (keyed by row id). The bundle carries attributions,
254
+ reviews, sessions, and related decisions.
255
+
256
+ ### Subscribe (`watch`)
257
+
258
+ Complete the read/write/**subscribe**/message contract. Passive: it polls and
259
+ reports; it never pushes work.
260
+
261
+ ```bash
262
+ blackboard watch --for claude # only messages/handoffs/conflicts addressed to me
263
+ blackboard watch # the full stream
264
+ blackboard watch --once # one-shot poll (for scripts)
265
+ ```
266
+
267
+ ### Signed sessions (`sign` / `verify`)
268
+
269
+ Minimal identity (v0): each session gets an Ed25519 keypair (private key stays
270
+ local under `.octoboard/keys/`, gitignored). Signing the timeline head lets
271
+ `verify` distinguish **trusted** state from merely asserted:
272
+
273
+ ```bash
274
+ blackboard sign # sign the current head with the active session key
275
+ blackboard verify # chain integrity + which sessions have signed, trusted/stale
276
+ ```
277
+
278
+ A session auto-signs its head on `session stop`. A signature over a head becomes
279
+ **stale** the moment any earlier history is altered — so tampering is visible
280
+ even though the signature itself stays cryptographically valid. This is not yet
281
+ a full PKI (no key distribution or revocation).
282
+
283
+ ## Ingesting CLI transcripts
284
+
285
+ Populate the board from a CLI's session transcript instead of calling the API
286
+ by hand — file edits, decisions, and notes flow onto the active session:
287
+
288
+ ```bash
289
+ blackboard ingest ~/.claude/transcript.jsonl --format claude-code
290
+ blackboard ingest session.jsonl --format codex # also: gemini, grok
291
+ blackboard ingest events.json --format generic --dry-run
292
+ ```
293
+
294
+ `claude-code`/`codex`/`gemini`/`grok` use a conservative tool-use JSONL
295
+ heuristic (it finds file edits from `file_path`/`notebook_path` and
296
+ patch/write tool calls). `generic` reads a normalized schema — the stable
297
+ integration path for **any** CLI:
298
+
299
+ ```json
300
+ { "events": [
301
+ { "type": "file", "path": "src/auth.ts", "change": "modified" },
302
+ { "type": "decision", "title": "use ed25519", "rationale": "small keys" },
303
+ { "type": "note", "text": "left policy edge cases for review" }
304
+ ] }
305
+ ```
306
+
307
+ ## Team backend
308
+
309
+ Boards stay local-first; sync shares the portable attribution records (never a
310
+ board's private hash chain) into a team store — a shared file or Postgres.
311
+
312
+ ```bash
313
+ blackboard sync push --target /shared/team.json # file (shared drive)
314
+ blackboard sync pull --target postgres://host/blackboard # team database (needs `pg`)
315
+ ```
316
+
317
+ `export` signs the bundle with your active session key; `import` verifies it and
318
+ `import --require-signed` refuses unsigned or tampered bundles — so imported
319
+ attribution has origin authenticity, not just id-dedup.
320
+
321
+ Tamper-evidence goes further than the in-DB chain if you anchor the head
322
+ externally:
323
+
324
+ ```bash
325
+ blackboard anchor --git-note # record seq:hash on the commit (or --out file)
326
+ blackboard verify --against git-note # prove history wasn't truncated/altered
327
+ ```
328
+
329
+ Liveness and compliance:
330
+
331
+ ```bash
332
+ blackboard session heartbeat # mark your session alive (active vs stale)
333
+ # `blackboard file ...` now warns if another LIVE session is editing the same file
334
+
335
+ blackboard prune --before 2026-01-01T00:00:00Z # retention: drop old messages/
336
+ # evidence/file-changes (timeline kept)
337
+ blackboard redact 42 --reason PII # hide a timeline entry's content
338
+ ```
339
+
340
+ `prune` never touches the append-only timeline (the audit trail). `redact`
341
+ blanks the content across every read path — the timeline overlay *and* the
342
+ underlying source row (a message body, evidence note, etc.) so `inbox`/`status`/
343
+ the dashboard can't leak it — while keeping the hash chain valid. It is not
344
+ cryptographic erasure: the original summary stays in the timeline row so the
345
+ chain still verifies, so don't store secrets you must be able to destroy. For
346
+ tamper-evidence against an attacker with database write access, anchor the head
347
+ hash externally (a commit, a log, a second machine) — `verify` shows an
348
+ `unanchored` warning when it can't confirm the tail.
349
+
350
+ ## Tasks & kanban
351
+
352
+ Tasks are kanban cards — number, content, owner (which agent / CLI), project,
353
+ blast radius, risk, and live progress. **"Notifying an agent" is passive:**
354
+ assigning a task drops a "please look at task #N" message in that agent's inbox;
355
+ the agent reads it and decides to act — the board never launches anyone.
356
+
357
+ ![The read-only blackboard serve dashboard, a live kanban of tasks](docs/kanban.png)
358
+
359
+ *The live `blackboard serve` dashboard — read-only, auto-refreshing. Each card
360
+ shows the task number, progress bar, assignees, active-agent count (⚡), project,
361
+ and a risk-coloured border.*
362
+
363
+ ```bash
364
+ blackboard task add auth-mw --title "Refactor auth middleware" \
365
+ --project octopus-api --impact "src/auth.ts, src/db.ts" --risk high
366
+ blackboard assign 1 claude # → drops "please look at task #1 …" in claude's inbox
367
+ blackboard progress 1 40 # → moves #1 to in-progress, 40%
368
+ blackboard tasks # kanban view, grouped by status
369
+ blackboard task show 1 # full card: owner, project, impact, risk, files
370
+ ```
371
+
372
+ The read-only `serve` dashboard renders these as a live kanban (columns by
373
+ status; each card shows number, title, a progress bar, assignees, active-agent
374
+ count, project, and a risk-coloured left border). Agents drive it via the MCP
375
+ tools `board_task_define`, `board_assign`, `board_progress`, `board_tasks` — an
376
+ agent calls `board_progress` as it works so the bar moves in real time.
377
+
378
+ ## Visibility
379
+
380
+ ```bash
381
+ blackboard report # scorecard: review coverage %, AI/human ratio, per-agent
382
+ blackboard blame src/auth.ts 42 # trace a line → the session that wrote it, and its
383
+ # other work, decisions, and handoffs (blame → narrative)
384
+ blackboard serve # read-only local web dashboard (http://localhost:4319)
385
+ ```
386
+
387
+ The dashboard is dependency-free (`node:http`), strictly read-only (non-GET is
388
+ refused), and auto-refreshes: live timeline, sessions, conflict/attribution
389
+ state, and the accountability scorecard.
390
+
391
+ ## MCP server — connect any CLI
392
+
393
+ The blackboard speaks standard MCP over stdio, so **any** MCP-capable client
394
+ (Claude Code, Cursor, Codex, Gemini CLI, VS Code, Windsurf, …) can read and
395
+ write the board. Generate the exact config for your client in one step:
396
+
397
+ ```bash
398
+ blackboard mcp-config cursor # → ~/.cursor/mcp.json block
399
+ blackboard mcp-config claude-code # → project .mcp.json block
400
+ blackboard mcp-config codex # → ~/.codex/config.toml (TOML)
401
+ blackboard mcp-config gemini # → ~/.gemini/settings.json block
402
+ blackboard mcp-config vscode # → .vscode/mcp.json (servers block)
403
+ blackboard mcp-config # → generic mcpServers JSON (any client)
404
+ ```
405
+
406
+ Each prints where to paste it and the ready-to-use snippet, e.g.:
407
+
408
+ ```json
409
+ {
410
+ "mcpServers": {
411
+ "blackboard": {
412
+ "command": "npx",
413
+ "args": ["-y", "octopus-blackboard-mcp"],
414
+ "env": { "OCTOBOARD_AGENT": "cursor" }
415
+ }
416
+ }
417
+ }
418
+ ```
419
+
420
+ The agent identity defaults to the client name (so Cursor writes as `cursor`,
421
+ Codex as `codex`); override with `--agent`. The board is auto-discovered from
422
+ `.octoboard/` in the working directory, or pin it with `--dir`. Two CLIs
423
+ pointed at the same `.octoboard/` now share one board — that's the whole point.
424
+
425
+ Tools exposed — coordination: `board_status`, `board_timeline`, `board_note`,
426
+ `board_claim`, `board_task_define`, `board_task`, `board_tasks`, `board_assign`,
427
+ `board_progress`, `board_message`, `board_inbox`, `board_handoffs`,
428
+ `board_decision`, `board_evidence`, `board_file_changed`, `board_risk`,
429
+ `board_handoff`, `board_heartbeat`, `board_since`; attribution: `session_start`,
430
+ `session_stop`, `board_link`, `board_attribute`, `board_review`, `board_who`,
431
+ `board_explain`, `board_blame`, `board_unreviewed`, `board_report`; governance &
432
+ portability: `board_check`, `board_export`, `board_import`, `board_trailers`,
433
+ `board_sign`, `board_trust`, `board_prune`, `board_redact`, `board_ingest`. Each
434
+ accepts an optional `agent` argument to override the acting identity per call.
435
+
436
+ The recommended pattern: an agent calls `board_status` **before** starting work
437
+ to see what everyone else is doing, and writes as it goes.
438
+
439
+ ## Data model
440
+
441
+ | Layer | Tables | Purpose |
442
+ |---|---|---|
443
+ | **Who is present** | `agents`, `sessions` | provider-independent identity, session context |
444
+ | **What's happening** | `tasks`, `messages`, `handoffs` | coordination — claim, message, hand off |
445
+ | **Who produced what** | `attributions`, `reviews` | AI/human attribution & review, keyed by commit |
446
+ | **Settled facts** | `decisions`, `evidence`, `files_changed`, `risks`, `timeline` | auditable shared memory |
447
+
448
+ `timeline` is the append-only hash chain every other write also records into, so
449
+ the board and its audit log can never diverge.
450
+
451
+ ## Architecture
452
+
453
+ ```text
454
+ better-sqlite3 (local-first, default)
455
+ + MCP server (read / write board)
456
+ + CLI (octoboard ...)
457
+ + hash-chain audit log (the timeline)
458
+ + optional Postgres sync (planned)
459
+ + optional git / file watcher (planned)
460
+ ```
461
+
462
+ ## Status
463
+
464
+ Early MVP (v0.1). Working today: local SQLite board, CLI (`octoboard` /
465
+ `blackboard`), MCP server, a verifiable hash-chained timeline, first-class
466
+ sessions, provider-independent AI/human attribution keyed to Git commits,
467
+ reviews, and the query layer (`who`, `explain`, `commits`, `unreviewed`,
468
+ `joint`). Git integration is read-only plus additive `git notes` — history is
469
+ never rewritten. Postgres sync and change subscriptions are on the roadmap.
470
+
471
+ ## License
472
+
473
+ Apache-2.0 © Octoryn. See [LICENSE](./LICENSE).