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
@@ -0,0 +1,158 @@
1
+ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
2
+ import { dirname } from "node:path";
3
+ import { BUNDLE_VERSION } from "./board.js";
4
+ const EMPTY = () => ({
5
+ version: BUNDLE_VERSION,
6
+ exportedAt: "",
7
+ attributions: [],
8
+ reviews: [],
9
+ sessions: [],
10
+ decisions: [],
11
+ });
12
+ /** Merge `incoming` into `base`, deduping by row id. Returns [merged, added]. */
13
+ function mergeById(base, incoming) {
14
+ const merged = EMPTY();
15
+ merged.exportedAt = incoming.exportedAt || base.exportedAt;
16
+ const counts = {
17
+ attributions: 0,
18
+ reviews: 0,
19
+ sessions: 0,
20
+ decisions: 0,
21
+ };
22
+ for (const key of [
23
+ "attributions",
24
+ "reviews",
25
+ "sessions",
26
+ "decisions",
27
+ ]) {
28
+ const seen = new Set(base[key].map((r) => r.id));
29
+ const out = [...base[key]];
30
+ for (const row of incoming[key]) {
31
+ if (!seen.has(row.id)) {
32
+ seen.add(row.id);
33
+ out.push(row);
34
+ counts[key] += 1;
35
+ }
36
+ }
37
+ merged[key] = out;
38
+ }
39
+ return [merged, counts];
40
+ }
41
+ /** A shared JSON bundle file — e.g. on a network drive. */
42
+ export class FileSyncTarget {
43
+ path;
44
+ constructor(path) {
45
+ this.path = path;
46
+ }
47
+ read() {
48
+ if (!existsSync(this.path)) {
49
+ return EMPTY();
50
+ }
51
+ try {
52
+ const parsed = JSON.parse(readFileSync(this.path, "utf8"));
53
+ return { ...EMPTY(), ...parsed };
54
+ }
55
+ catch {
56
+ return EMPTY();
57
+ }
58
+ }
59
+ async push(bundle) {
60
+ const [merged, counts] = mergeById(this.read(), bundle);
61
+ mkdirSync(dirname(this.path), { recursive: true });
62
+ writeFileSync(this.path, JSON.stringify(merged, null, 2), "utf8");
63
+ return counts;
64
+ }
65
+ async pull() {
66
+ return this.read();
67
+ }
68
+ async close() {
69
+ /* nothing to close */
70
+ }
71
+ }
72
+ /**
73
+ * A Postgres team board. Records are stored one-row-per-record with a JSONB
74
+ * `data` column keyed by id, so the sync store never has to track the
75
+ * blackboard's evolving column set. Requires the optional `pg` dependency and a
76
+ * reachable connection URL.
77
+ */
78
+ export class PostgresSyncTarget {
79
+ url;
80
+ clientPromise = null;
81
+ constructor(url) {
82
+ this.url = url;
83
+ }
84
+ async client() {
85
+ if (this.clientPromise) {
86
+ return this.clientPromise;
87
+ }
88
+ this.clientPromise = (async () => {
89
+ let pg;
90
+ try {
91
+ // Non-literal specifier: `pg` is an optional dependency, so it is
92
+ // imported dynamically and typed loosely rather than resolved at build.
93
+ const mod = "pg";
94
+ pg = await import(mod);
95
+ }
96
+ catch {
97
+ throw new Error("Postgres sync requires the optional 'pg' package: npm install pg");
98
+ }
99
+ const Client = pg.default?.Client ?? pg.Client;
100
+ const client = new Client({ connectionString: this.url });
101
+ await client.connect();
102
+ for (const t of ["attributions", "reviews", "sessions", "decisions"]) {
103
+ await client.query(`CREATE TABLE IF NOT EXISTS bb_${t} (id TEXT PRIMARY KEY, data JSONB NOT NULL)`);
104
+ }
105
+ return client;
106
+ })();
107
+ return this.clientPromise;
108
+ }
109
+ async push(bundle) {
110
+ const client = await this.client();
111
+ const counts = {
112
+ attributions: 0,
113
+ reviews: 0,
114
+ sessions: 0,
115
+ decisions: 0,
116
+ };
117
+ for (const key of [
118
+ "attributions",
119
+ "reviews",
120
+ "sessions",
121
+ "decisions",
122
+ ]) {
123
+ for (const row of bundle[key]) {
124
+ const res = await client.query(`INSERT INTO bb_${key} (id, data) VALUES ($1, $2) ON CONFLICT (id) DO NOTHING`, [row.id, JSON.stringify(row)]);
125
+ counts[key] += res.rowCount ?? 0;
126
+ }
127
+ }
128
+ return counts;
129
+ }
130
+ async pull() {
131
+ const client = await this.client();
132
+ const bundle = EMPTY();
133
+ for (const key of [
134
+ "attributions",
135
+ "reviews",
136
+ "sessions",
137
+ "decisions",
138
+ ]) {
139
+ const res = await client.query(`SELECT data FROM bb_${key}`);
140
+ bundle[key] = res.rows.map((r) => typeof r.data === "string" ? JSON.parse(r.data) : r.data);
141
+ }
142
+ return bundle;
143
+ }
144
+ async close() {
145
+ if (this.clientPromise) {
146
+ const client = await this.clientPromise;
147
+ await client.end();
148
+ }
149
+ }
150
+ }
151
+ /** Build a target from a spec: a `postgres://` URL, or else a file path. */
152
+ export function createSyncTarget(spec) {
153
+ if (spec.startsWith("postgres://") || spec.startsWith("postgresql://")) {
154
+ return new PostgresSyncTarget(spec);
155
+ }
156
+ return new FileSyncTarget(spec);
157
+ }
158
+ //# sourceMappingURL=sync.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sync.js","sourceRoot":"","sources":["../src/sync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,cAAc,EAA0B,MAAM,YAAY,CAAC;AAyBpE,MAAM,KAAK,GAA4B,GAAG,EAAE,CAAC,CAAC;IAC5C,OAAO,EAAE,cAAc;IACvB,UAAU,EAAE,EAAE;IACd,YAAY,EAAE,EAAE;IAChB,OAAO,EAAE,EAAE;IACX,QAAQ,EAAE,EAAE;IACZ,SAAS,EAAE,EAAE;CACd,CAAC,CAAC;AAEH,iFAAiF;AACjF,SAAS,SAAS,CAChB,IAAuB,EACvB,QAA2B;IAE3B,MAAM,MAAM,GAAG,KAAK,EAAE,CAAC;IACvB,MAAM,CAAC,UAAU,GAAG,QAAQ,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU,CAAC;IAC3D,MAAM,MAAM,GAAe;QACzB,YAAY,EAAE,CAAC;QACf,OAAO,EAAE,CAAC;QACV,QAAQ,EAAE,CAAC;QACX,SAAS,EAAE,CAAC;KACb,CAAC;IACF,KAAK,MAAM,GAAG,IAAI;QAChB,cAAc;QACd,SAAS;QACT,UAAU;QACV,WAAW;KACH,EAAE,CAAC;QACX,MAAM,IAAI,GAAG,IAAI,GAAG,CAAE,IAAI,CAAC,GAAG,CAAsB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACvE,MAAM,GAAG,GAAG,CAAC,GAAI,IAAI,CAAC,GAAG,CAAsB,CAAC,CAAC;QACjD,KAAK,MAAM,GAAG,IAAI,QAAQ,CAAC,GAAG,CAAqB,EAAE,CAAC;YACpD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;gBACtB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBACjB,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACd,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACnB,CAAC;QACH,CAAC;QACA,MAAM,CAAC,GAAG,CAAe,GAAG,GAAG,CAAC;IACnC,CAAC;IACD,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAC1B,CAAC;AAED,2DAA2D;AAC3D,MAAM,OAAO,cAAc;IACI;IAA7B,YAA6B,IAAY;QAAZ,SAAI,GAAJ,IAAI,CAAQ;IAAG,CAAC;IAErC,IAAI;QACV,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3B,OAAO,KAAK,EAAE,CAAC;QACjB,CAAC;QACD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CACvB,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CACX,CAAC;YACvB,OAAO,EAAE,GAAG,KAAK,EAAE,EAAE,GAAG,MAAM,EAAE,CAAC;QACnC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,EAAE,CAAC;QACjB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAAyB;QAClC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,MAAM,CAAC,CAAC;QACxD,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACnD,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;QAClE,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,KAAK,CAAC,IAAI;QACR,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,KAAK;QACT,sBAAsB;IACxB,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,kBAAkB;IAGA;IAFrB,aAAa,GAAwB,IAAI,CAAC;IAElD,YAA6B,GAAW;QAAX,QAAG,GAAH,GAAG,CAAQ;IAAG,CAAC;IAEpC,KAAK,CAAC,MAAM;QAClB,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC,aAAa,CAAC;QAC5B,CAAC;QACD,IAAI,CAAC,aAAa,GAAG,CAAC,KAAK,IAAI,EAAE;YAC/B,IAAI,EAAO,CAAC;YACZ,IAAI,CAAC;gBACH,kEAAkE;gBAClE,wEAAwE;gBACxE,MAAM,GAAG,GAAG,IAAI,CAAC;gBACjB,EAAE,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC;YACzB,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,IAAI,KAAK,CACb,kEAAkE,CACnE,CAAC;YACJ,CAAC;YACD,MAAM,MAAM,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,CAAC,MAAM,CAAC;YAC/C,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,EAAE,gBAAgB,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;YAC1D,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;YACvB,KAAK,MAAM,CAAC,IAAI,CAAC,cAAc,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,CAAC,EAAE,CAAC;gBACrE,MAAM,MAAM,CAAC,KAAK,CAChB,iCAAiC,CAAC,6CAA6C,CAChF,CAAC;YACJ,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC,CAAC,EAAE,CAAC;QACL,OAAO,IAAI,CAAC,aAAa,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAAyB;QAClC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;QACnC,MAAM,MAAM,GAAe;YACzB,YAAY,EAAE,CAAC;YACf,OAAO,EAAE,CAAC;YACV,QAAQ,EAAE,CAAC;YACX,SAAS,EAAE,CAAC;SACb,CAAC;QACF,KAAK,MAAM,GAAG,IAAI;YAChB,cAAc;YACd,SAAS;YACT,UAAU;YACV,WAAW;SACH,EAAE,CAAC;YACX,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,GAAG,CAAqB,EAAE,CAAC;gBAClD,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,KAAK,CAC5B,kBAAkB,GAAG,yDAAyD,EAC9E,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAC9B,CAAC;gBACF,MAAM,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,QAAQ,IAAI,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,KAAK,CAAC,IAAI;QACR,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,KAAK,EAAE,CAAC;QACvB,KAAK,MAAM,GAAG,IAAI;YAChB,cAAc;YACd,SAAS;YACT,UAAU;YACV,WAAW;SACH,EAAE,CAAC;YACX,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,uBAAuB,GAAG,EAAE,CAAC,CAAC;YAC5D,MAAM,CAAC,GAAG,CAAe,GAAG,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CACnD,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CACzD,CAAC;QACJ,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC;YACxC,MAAM,MAAM,CAAC,GAAG,EAAE,CAAC;QACrB,CAAC;IACH,CAAC;CACF;AAED,4EAA4E;AAC5E,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,IAAI,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;QACvE,OAAO,IAAI,kBAAkB,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC"}
@@ -0,0 +1,359 @@
1
+ /**
2
+ * Domain types for the Octopus Blackboard — a shared memory and coordination
3
+ * layer for AI coding agents.
4
+ *
5
+ * The blackboard does NOT orchestrate, schedule, or trigger agents. It records
6
+ * what each agent chooses to write, and lets every other agent read it. Six
7
+ * questions it answers:
8
+ *
9
+ * Who is working on what → agents, tasks, claims
10
+ * What changed → files_changed
11
+ * What was decided → decisions
12
+ * What evidence exists → evidence
13
+ * What risks are open → risks
14
+ * What was left for whom → messages, handoffs
15
+ *
16
+ * Every mutation appends a tamper-evident entry to the `timeline` (a hash
17
+ * chain), so the whole history is replayable and auditable.
18
+ */
19
+ /**
20
+ * A participating AI system (or human), identified provider-independently. No
21
+ * assumptions about any specific vendor: any CLI can register itself with these
22
+ * fields. `name` is the stable board handle; the rest describe the system.
23
+ */
24
+ export interface Agent {
25
+ id: string;
26
+ /** Stable handle used on the board, e.g. "claude", "codex", "gemini". */
27
+ name: string;
28
+ /** Free-form product/kind label, e.g. "claude-code", "cursor". */
29
+ kind: string | null;
30
+ /** Vendor / origin, e.g. "anthropic", "openai", "google", "local". */
31
+ provider: string | null;
32
+ /** Model identifier, e.g. "claude-opus-4-8", "gpt-5", "llama-3.1-70b". */
33
+ model: string | null;
34
+ /** The CLI / surface, e.g. "claude-code", "codex-cli", "cursor". */
35
+ cli: string | null;
36
+ /** CLI or integration version. */
37
+ version: string | null;
38
+ createdAt: string;
39
+ lastSeen: string;
40
+ }
41
+ /**
42
+ * One continuous execution session for an agent — the unit attribution,
43
+ * reviews, and handoffs hang off of. Started with `session start`, closed with
44
+ * `session stop`; captures the machine and repository context it ran in.
45
+ */
46
+ export interface Session {
47
+ id: string;
48
+ agentName: string;
49
+ label: string | null;
50
+ machine: string | null;
51
+ workingDirectory: string | null;
52
+ gitBranch: string | null;
53
+ repository: string | null;
54
+ /** Ed25519 public key (PEM) for this session's signatures, if signing is on. */
55
+ publicKey: string | null;
56
+ /** Last liveness heartbeat; used to tell active sessions from stale ones. */
57
+ lastHeartbeat: string | null;
58
+ startedAt: string;
59
+ finishedAt: string | null;
60
+ project: string | null;
61
+ taskKey: string | null;
62
+ }
63
+ export type ActorType = "human" | "ai";
64
+ /**
65
+ * Who actually produced a change — the attribution Git cannot record. Bound to
66
+ * a commit (and optionally a file/hunk). For AI actors the provider/model/cli
67
+ * are denormalized so "which commits came from Claude Code" is a cheap query
68
+ * even after session rows change.
69
+ */
70
+ export interface Attribution {
71
+ id: string;
72
+ commit: string;
73
+ file: string | null;
74
+ hunk: string | null;
75
+ actorType: ActorType;
76
+ /** Agent handle or human name. */
77
+ actor: string;
78
+ provider: string | null;
79
+ model: string | null;
80
+ cli: string | null;
81
+ sessionId: string | null;
82
+ createdAt: string;
83
+ }
84
+ export type ReviewerType = "human" | "ai";
85
+ export type ReviewOutcome = "approved" | "changes-requested" | "rejected" | "commented";
86
+ /** Review responsibility for a commit — who reviewed it, and the outcome. */
87
+ export interface Review {
88
+ id: string;
89
+ commit: string;
90
+ reviewerType: ReviewerType;
91
+ reviewer: string;
92
+ sessionId: string | null;
93
+ outcome: ReviewOutcome;
94
+ note: string | null;
95
+ createdAt: string;
96
+ }
97
+ export type TaskStatus = "open" | "claimed" | "in-progress" | "blocked" | "done";
98
+ export type RiskLevel = "low" | "medium" | "high";
99
+ /**
100
+ * A unit of work. `key` is a human slug (unique) used to claim/hand off work;
101
+ * `number` is a stable, human-friendly id ("task #145"); `claimedBy` is the
102
+ * single agent currently holding it — the basis for conflict awareness. The
103
+ * kanban card fields (description/project/impact/riskLevel/progress) describe
104
+ * what it is, where, how big the blast radius is, and how far along it is.
105
+ */
106
+ export interface Task {
107
+ id: string;
108
+ key: string;
109
+ /** Stable human-friendly number, e.g. 145 (unique per board). */
110
+ number: number | null;
111
+ title: string | null;
112
+ /** What the task actually is (beyond the one-line title). */
113
+ description: string | null;
114
+ status: TaskStatus;
115
+ /** Which project/repo it belongs to. */
116
+ project: string | null;
117
+ /** Sub-line within a project (step 2). Nullable; purely additive. */
118
+ stream: string | null;
119
+ /** The change surface — files/areas this touches. */
120
+ impact: string | null;
121
+ /** How risky the change is. */
122
+ riskLevel: RiskLevel | null;
123
+ /**
124
+ * First-class machine-checkable acceptance spec (parsed JSON), set via
125
+ * defineTask; null on tasks defined before this column existed or without
126
+ * an acceptance spec.
127
+ */
128
+ acceptance: Record<string, unknown> | null;
129
+ /** Completion 0–100. */
130
+ progress: number;
131
+ createdBy: string | null;
132
+ claimedBy: string | null;
133
+ claimedAt: string | null;
134
+ releasedAt: string | null;
135
+ createdAt: string;
136
+ updatedAt: string;
137
+ }
138
+ /**
139
+ * A kanban card: a task plus the derived view — who's assigned, how many agents
140
+ * are actively on it, the files it has touched, and its linked risks.
141
+ */
142
+ export interface TaskCard {
143
+ task: Task;
144
+ assignees: string[];
145
+ activeAgents: number;
146
+ impactFiles: string[];
147
+ risks: Risk[];
148
+ }
149
+ /**
150
+ * A kanban card as returned inside a ProjectReport, extended with the task's own
151
+ * trace counts (the third level of the project -> stream -> task drilldown).
152
+ * `timeline` counts every row linked to the task by EITHER exact link it uses --
153
+ * `task_key` (notes/evidence scoped with --task) or `ref_table='tasks'` with
154
+ * `ref_id` = the task's UUID (claim/progress/complete, plus defineTask itself).
155
+ * The bridge stamps ref_id but not task_key, so counting task_key alone
156
+ * undercounts most cards.
157
+ */
158
+ export interface ProjectTaskCard extends TaskCard {
159
+ trace: {
160
+ timeline: number;
161
+ risks: number;
162
+ evidence: number;
163
+ sessions: number;
164
+ };
165
+ }
166
+ /**
167
+ * The trace entries attributable to one task (task -> trace, the fourth level of
168
+ * the drilldown). `total` may exceed `entries.length` when `limit` truncates.
169
+ */
170
+ export interface TaskTrace {
171
+ taskKey: string;
172
+ taskNumber: number;
173
+ total: number;
174
+ entries: TimelineEvent[];
175
+ }
176
+ /** A note left for another agent (to=null is a broadcast to the board). */
177
+ export interface Message {
178
+ id: string;
179
+ fromAgent: string;
180
+ toAgent: string | null;
181
+ body: string;
182
+ createdAt: string;
183
+ readAt: string | null;
184
+ }
185
+ /** A decision worth remembering — the "what was decided" of the board. */
186
+ export interface Decision {
187
+ id: string;
188
+ agentId: string;
189
+ sessionId: string | null;
190
+ title: string;
191
+ rationale: string | null;
192
+ /** Free-form evidence pointer (path, URL, log). */
193
+ evidence: string | null;
194
+ /** Commit shas this decision relates to. */
195
+ relatedCommits: string[];
196
+ /** Task keys this decision relates to. */
197
+ relatedTasks: string[];
198
+ createdAt: string;
199
+ }
200
+ /** A pointer to supporting evidence (a file, URL, log, test run). */
201
+ export interface Evidence {
202
+ id: string;
203
+ agentId: string;
204
+ ref: string;
205
+ note: string | null;
206
+ /** Optional link to what this evidence supports, e.g. "task:auth-mw". */
207
+ target: string | null;
208
+ /** SHA-256 of the referenced file's content at attach time, if it was a
209
+ * readable local file — so later tampering with the file is detectable. */
210
+ sha256: string | null;
211
+ /** Four-layer ownership: the project this register entry belongs to. */
212
+ project: string | null;
213
+ /** The task this register entry is scoped to, if any. */
214
+ taskKey: string | null;
215
+ /** Sedimentation kind: memory | skill | hook | lesson | playbook. */
216
+ kind: string | null;
217
+ createdAt: string;
218
+ }
219
+ /** Returned by `evidence()` when a project-scoped entry is refused (non-member, no taskKey). */
220
+ export interface EvidenceSkipped {
221
+ skipped: string;
222
+ project: string;
223
+ ref: string;
224
+ }
225
+ export type EvidenceStatus = "ok" | "changed" | "missing" | "unhashed";
226
+ /** Result of re-checking an evidence file against its attach-time hash. */
227
+ export interface EvidenceCheck {
228
+ id: string;
229
+ ref: string;
230
+ status: EvidenceStatus;
231
+ }
232
+ export type FileChangeKind = "added" | "modified" | "deleted";
233
+ /** A record that an agent touched a file (cooperative, not authoritative). */
234
+ export interface FileChange {
235
+ id: string;
236
+ agentId: string;
237
+ sessionId: string | null;
238
+ path: string;
239
+ change: FileChangeKind;
240
+ taskKey: string | null;
241
+ createdAt: string;
242
+ }
243
+ export type RiskSeverity = "low" | "medium" | "high";
244
+ export type RiskStatus = "open" | "mitigated" | "closed";
245
+ /** An open risk the next agent should be aware of before acting. */
246
+ export interface Risk {
247
+ id: string;
248
+ agentId: string;
249
+ title: string;
250
+ severity: RiskSeverity;
251
+ status: RiskStatus;
252
+ /** Task this risk is attached to, if any. */
253
+ taskKey: string | null;
254
+ createdAt: string;
255
+ /** Set when the card leaves `open`; cleared when it is reopened. */
256
+ resolvedAt: string | null;
257
+ resolvedBy: string | null;
258
+ }
259
+ /** A handoff: agent A passes context for some work to agent B. */
260
+ export interface Handoff {
261
+ id: string;
262
+ fromAgent: string;
263
+ toAgent: string;
264
+ fromSession: string | null;
265
+ toSession: string | null;
266
+ summary: string;
267
+ context: string | null;
268
+ relatedFiles: string[];
269
+ openQuestions: string[];
270
+ taskKey: string | null;
271
+ createdAt: string;
272
+ acceptedAt: string | null;
273
+ }
274
+ /**
275
+ * One entry in the append-only, hash-chained audit log. `hash` is computed
276
+ * over the entry plus the previous entry's hash, so any tampering with an
277
+ * earlier row breaks verification of every row after it.
278
+ */
279
+ export interface TimelineEvent {
280
+ id: string;
281
+ seq: number;
282
+ at: string;
283
+ actor: string;
284
+ /** The session this event belongs to, if one was active. */
285
+ sessionId: string | null;
286
+ kind: string;
287
+ refTable: string | null;
288
+ refId: string | null;
289
+ summary: string;
290
+ payload: unknown;
291
+ /**
292
+ * Step 2: four-layer ownership. Attached attributes — deliberately NOT part
293
+ * of `Board.computeHash`, so falsifying them does not break `verifyChain()`.
294
+ */
295
+ project: string | null;
296
+ taskKey: string | null;
297
+ prevHash: string;
298
+ hash: string;
299
+ }
300
+ /**
301
+ * Optional filters for task listings (step 2). Every field omitted = today's
302
+ * behaviour, so existing callers are unaffected.
303
+ */
304
+ export interface TaskFilters {
305
+ project?: string;
306
+ stream?: string;
307
+ }
308
+ /** Project lifecycle (step 2). Enforced by `Board.setProjectStatus`. */
309
+ export type ProjectStatus = "active" | "paused" | "archived";
310
+ /** A first-class project: board -> project -> task -> trace. */
311
+ export interface Project {
312
+ id: string;
313
+ key: string;
314
+ name: string;
315
+ description: string | null;
316
+ status: ProjectStatus;
317
+ /** Controlled stream vocabulary. Empty = no vocabulary declared, any stream accepted. */
318
+ streams: string[];
319
+ createdBy: string;
320
+ createdAt: string;
321
+ updatedAt: string;
322
+ }
323
+ /** A project plus live rollups (what `Board.listProjects()` returns). */
324
+ export interface ProjectSummary extends Project {
325
+ taskCount: number;
326
+ tasksByStatus: Record<string, number>;
327
+ }
328
+ /** Three-level aggregation: project -> tasks -> trace (step 2). */
329
+ export interface ProjectReport {
330
+ project: Project;
331
+ tasks: {
332
+ total: number;
333
+ byStatus: Record<string, number>;
334
+ cards: ProjectTaskCard[];
335
+ };
336
+ trace: {
337
+ messages: number;
338
+ decisions: number;
339
+ risks: number;
340
+ handoffs: number;
341
+ evidence: number;
342
+ filesChanged: number;
343
+ notes: number;
344
+ };
345
+ timeline: {
346
+ total: number;
347
+ firstSeq: number | null;
348
+ lastSeq: number | null;
349
+ };
350
+ }
351
+ /** A point-in-time read of the board, what `octoboard status` renders. */
352
+ export interface BoardStatus {
353
+ agents: Agent[];
354
+ openTasks: Task[];
355
+ unreadMessages: Message[];
356
+ openRisks: Risk[];
357
+ recentTimeline: TimelineEvent[];
358
+ }
359
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Domain types for the Octopus Blackboard — a shared memory and coordination
3
+ * layer for AI coding agents.
4
+ *
5
+ * The blackboard does NOT orchestrate, schedule, or trigger agents. It records
6
+ * what each agent chooses to write, and lets every other agent read it. Six
7
+ * questions it answers:
8
+ *
9
+ * Who is working on what → agents, tasks, claims
10
+ * What changed → files_changed
11
+ * What was decided → decisions
12
+ * What evidence exists → evidence
13
+ * What risks are open → risks
14
+ * What was left for whom → messages, handoffs
15
+ *
16
+ * Every mutation appends a tamper-evident entry to the `timeline` (a hash
17
+ * chain), so the whole history is replayable and auditable.
18
+ */
19
+ export {};
20
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG"}
@@ -0,0 +1,102 @@
1
+ **English** | [简体中文](0001-shared-worktree-collision.zh-CN.md)
2
+
3
+ # ADR 0001 — A shared Git working tree caused a review/release collision
4
+
5
+ - **Status:** Accepted
6
+ - **Date:** 2026-07-02
7
+ - **Context:** Multiple AI coding agents (Claude sessions) working on this repo.
8
+
9
+ ## Summary
10
+
11
+ Two AI sessions operated on the **same Git working tree** at the same time. One
12
+ session reviewed a feature branch (`feat/provenance-export`) and **rejected** it,
13
+ deleting the branch. Minutes later a second session **restored** that branch from
14
+ the reflog, committed a **0.2.0 release**, **fast-forward merged it into `main`**,
15
+ tagged **`v0.2.0`**, and **pushed to origin** — silently overriding the review
16
+ decision. npm was not published, so the blast radius stopped at Git/origin.
17
+
18
+ This ADR records the incident and adopts the workflow rules that prevent it. See
19
+ [development-workflow.md](../development-workflow.md) for the operational rules.
20
+
21
+ ## What happened (evidence)
22
+
23
+ All operations appear in **one shared `HEAD` reflog** — proof they ran in a single
24
+ working tree, not independent checkouts (an independent worktree/clone keeps its
25
+ own reflog). Timeline (local time, 2026-07-02):
26
+
27
+ | time | operation | actor signal |
28
+ | ---- | --------- | ------------ |
29
+ | 13:10:54 | reviewer checks out `main`, deletes `feat/provenance-export` (REJECT) | machine default identity |
30
+ | 13:12:40 | `feat/provenance-export` **recreated** from the reflog SHA `2fbac2c` | machine default identity |
31
+ | 13:15:25 | commit `7c3bf62` "release: 0.2.0" | `Octoryn <ran.tao@…>` + `Co-Authored-By: Claude` |
32
+ | 13:16:11 | amend → `e818e15` | `Octoryn <ran.tao@…>` |
33
+ | 13:16:17 | checkout `main` + **fast-forward merge** → `e818e15` | machine default identity |
34
+ | 13:17:01 | `origin/main` **update by push** → `e818e15`; tag `v0.2.0` pushed | — |
35
+
36
+ Corroborating facts:
37
+
38
+ - **One** clone on disk; `git worktree list` shows **one** worktree; no
39
+ `.git/worktrees/`.
40
+ - The 0.2.0 release commits carry a **different git identity**
41
+ (`Octoryn <ran.tao@outlook.com.au>`) than every prior commit
42
+ (`Octopus Core Pty Ltd <octoryn@octoryn-mbp.local>`), and a
43
+ `Co-Authored-By: Claude Opus 4.8` trailer — a second AI actor.
44
+
45
+ **Root cause:** a shared-mutable-state race. `HEAD`, the index, and the branch
46
+ namespace are global to a working tree. With two writers and no isolation or lock,
47
+ one session's `checkout` / `branch -D` / `commit` / `merge` changed the ground
48
+ under the other, between two of the reviewer's commands.
49
+
50
+ ## Decision
51
+
52
+ ### 1. Shared Git working trees are unsafe for multiple AI agents
53
+
54
+ A working tree has exactly one `HEAD`, one index, and one branch namespace — all
55
+ mutable, all global to that tree. Concurrent agents have no isolation: any agent's
56
+ ref or index operation is immediately visible to and destructive of the others'.
57
+ There is no lock and no ownership. This is the same class of bug as unsynchronised
58
+ threads sharing memory. **We will not run two agents in one working tree.**
59
+
60
+ ### 2. One AI session = one isolated worktree = one branch
61
+
62
+ Each session gets its own `git worktree add` (or its own clone) and works on a
63
+ single `agent/<session>/<topic>` branch. Isolated `HEAD`/index/branch means one
64
+ session physically **cannot** mutate another's state. This alone would have
65
+ prevented the incident. (In agent harnesses that support it, launch with
66
+ per-session worktree isolation.)
67
+
68
+ ### 3. `main` is not modified directly by agents
69
+
70
+ Agents commit only to their own branch and land through review — never a direct
71
+ commit, fast-forward, or push to `main`. A rejected branch resurrected and
72
+ fast-forwarded onto `main` is exactly the failure above. `main` should be
73
+ **branch-protected** so a review verdict is *enforced*, not advisory.
74
+
75
+ > A local `git branch -D` is **not** a durable rejection: any session can restore
76
+ > the ref from the reflog (as happened here). Rejection must be enforced by branch
77
+ > protection / required review, not by deleting a local ref.
78
+
79
+ ### 4. Release / tag / publish is a gated, single-owner action
80
+
81
+ Version bump, tag, `git push --tags`, and `npm publish` require **explicit human
82
+ approval** and go through one designated integrator (or CI release job). A release
83
+ must never be produced as a side-effect of one session while another is
84
+ mid-review. Tags are treated as immutable once pushed.
85
+
86
+ ## Consequences
87
+
88
+ - Agents pay a small setup cost (a worktree/clone per session). Cheap next to a
89
+ silently-overridden review and an unwanted tagged release.
90
+ - `main` and tags become trustworthy: what's there passed review and human-gated
91
+ release.
92
+ - Enforcement (branch protection, required review, merge queue) is a follow-up
93
+ action, tracked separately; this ADR sets the policy.
94
+
95
+ ## Notes
96
+
97
+ - **This incident does not itself decide the fate of v0.2.0.** Whether to keep,
98
+ revert, or supersede it with v0.2.1 is a separate human decision. No revert, tag
99
+ deletion, force-push, or npm publish was performed.
100
+ - The irony is intentional to record: this is precisely the coordination failure
101
+ Blackboard exists to *surface* — two agents, opposite decisions, shared state,
102
+ no mutual awareness — occurring one layer below Blackboard, in Git itself.