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
@@ -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).