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.
- package/LICENSE +201 -0
- package/NOTICE +23 -0
- package/README.md +97 -2
- package/README.zh-CN.md +89 -0
- package/bin/proofdeck.js +126 -0
- package/board/LICENSE +201 -0
- package/board/README.md +473 -0
- package/board/README.zh-CN.md +424 -0
- package/board/dist/_chk.db-shm +0 -0
- package/board/dist/_chk.db-wal +0 -0
- package/board/dist/adapters.d.ts +40 -0
- package/board/dist/adapters.d.ts.map +1 -0
- package/board/dist/adapters.js +124 -0
- package/board/dist/adapters.js.map +1 -0
- package/board/dist/board.d.ts +628 -0
- package/board/dist/board.d.ts.map +1 -0
- package/board/dist/board.js +2767 -0
- package/board/dist/board.js.map +1 -0
- package/board/dist/cli.d.ts +3 -0
- package/board/dist/cli.d.ts.map +1 -0
- package/board/dist/cli.js +1663 -0
- package/board/dist/cli.js.map +1 -0
- package/board/dist/config.d.ts +57 -0
- package/board/dist/config.d.ts.map +1 -0
- package/board/dist/config.js +99 -0
- package/board/dist/config.js.map +1 -0
- package/board/dist/db.d.ts +9 -0
- package/board/dist/db.d.ts.map +1 -0
- package/board/dist/db.js +506 -0
- package/board/dist/db.js.map +1 -0
- package/board/dist/git.d.ts +35 -0
- package/board/dist/git.d.ts.map +1 -0
- package/board/dist/git.js +147 -0
- package/board/dist/git.js.map +1 -0
- package/board/dist/index.d.ts +18 -0
- package/board/dist/index.d.ts.map +1 -0
- package/board/dist/index.js +13 -0
- package/board/dist/index.js.map +1 -0
- package/board/dist/mcp-config.d.ts +26 -0
- package/board/dist/mcp-config.d.ts.map +1 -0
- package/board/dist/mcp-config.js +88 -0
- package/board/dist/mcp-config.js.map +1 -0
- package/board/dist/mcp.d.ts +3 -0
- package/board/dist/mcp.d.ts.map +1 -0
- package/board/dist/mcp.js +949 -0
- package/board/dist/mcp.js.map +1 -0
- package/board/dist/quickstart.d.ts +75 -0
- package/board/dist/quickstart.d.ts.map +1 -0
- package/board/dist/quickstart.js +156 -0
- package/board/dist/quickstart.js.map +1 -0
- package/board/dist/serve.d.ts +10 -0
- package/board/dist/serve.d.ts.map +1 -0
- package/board/dist/serve.js +445 -0
- package/board/dist/serve.js.map +1 -0
- package/board/dist/signing.d.ts +18 -0
- package/board/dist/signing.d.ts.map +1 -0
- package/board/dist/signing.js +26 -0
- package/board/dist/signing.js.map +1 -0
- package/board/dist/sync.d.ts +49 -0
- package/board/dist/sync.d.ts.map +1 -0
- package/board/dist/sync.js +158 -0
- package/board/dist/sync.js.map +1 -0
- package/board/dist/types.d.ts +359 -0
- package/board/dist/types.d.ts.map +1 -0
- package/board/dist/types.js +20 -0
- package/board/dist/types.js.map +1 -0
- package/board/docs/adr/0001-shared-worktree-collision.md +102 -0
- package/board/docs/adr/0001-shared-worktree-collision.zh-CN.md +90 -0
- package/board/docs/attribution.md +123 -0
- package/board/docs/attribution.zh-CN.md +104 -0
- package/board/docs/development-workflow.md +81 -0
- package/board/docs/development-workflow.zh-CN.md +75 -0
- package/board/docs/diagrams/banner.png +0 -0
- package/board/docs/diagrams/banner.svg +1 -0
- package/board/docs/diagrams/before-after.png +0 -0
- package/board/docs/diagrams/before-after.svg +1 -0
- package/board/docs/diagrams/governance-chain.png +0 -0
- package/board/docs/diagrams/governance-chain.svg +1 -0
- package/board/docs/diagrams/value-flow.png +0 -0
- package/board/docs/diagrams/value-flow.svg +1 -0
- package/board/docs/entry-point.md +81 -0
- package/board/docs/entry-point.zh-CN.md +65 -0
- package/board/docs/kanban.png +0 -0
- package/board/docs/octoryn-mark.png +0 -0
- package/board/docs/registry-metadata.md +34 -0
- package/board/docs/registry-metadata.zh-CN.md +30 -0
- package/board/package.json +87 -0
- package/config.example.json +71 -0
- package/daemon.js +1112 -0
- package/docs/assets/demo.gif +0 -0
- package/docs/demo-run.mjs +61 -0
- package/docs/render-demo.py +94 -0
- package/e2e/verify-acceptance.mjs +150 -0
- package/e2e/verify-antifraud.mjs +128 -0
- package/e2e/verify-caps.mjs +46 -0
- package/e2e/verify-checkpoint.mjs +208 -0
- package/e2e/verify-firstclass.mjs +110 -0
- package/e2e/verify-judge.mjs +52 -0
- package/e2e/verify-lease.mjs +95 -0
- package/e2e/verify-replay.mjs +92 -0
- package/e2e/verify-resilience.mjs +323 -0
- package/e2e/verify-review.mjs +86 -0
- package/e2e/verify-scheduling.mjs +110 -0
- package/e2e/verify-schema-evolution.mjs +107 -0
- package/e2e/verify-sla-digest.mjs +105 -0
- package/guard.js +97 -0
- package/lib/adapters/codex.js +206 -0
- package/lib/billing-convert.js +57 -0
- package/lib/board.js +46 -0
- package/lib/caps.js +35 -0
- package/lib/checkpoint.js +130 -0
- package/lib/gating.js +218 -0
- package/lib/guard-core.mjs +108 -0
- package/lib/http.js +161 -0
- package/lib/judge.js +89 -0
- package/lib/lease.js +93 -0
- package/lib/notify.js +56 -0
- package/lib/platform.js +120 -0
- package/lib/replay.js +68 -0
- package/lib/review.js +40 -0
- package/lib/runner.js +152 -0
- package/lib/schedule.js +59 -0
- package/lib/sla.js +42 -0
- package/lib/spans.js +36 -0
- package/lib/starve.js +43 -0
- package/lib/store.js +109 -0
- package/lib/supply.js +101 -0
- package/lib/usage.js +103 -0
- package/lib/verify.js +223 -0
- package/lib/watchdog-core.mjs +68 -0
- package/lib/watchdog-worker.mjs +75 -0
- package/package.json +55 -4
- package/scripts/run-daemon.sh +18 -0
- 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":"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"}
|
|
@@ -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.
|