proofdeck 0.1.0 → 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.
package/README.md CHANGED
@@ -1,39 +1,67 @@
1
- # ProofDeck
2
-
3
- **A verification-first task board and orchestrator for coding-agent fleets.**
4
-
5
- Agents claim done. ProofDeck demands proof.
6
-
7
- [![CI](https://github.com/kumu314/proofdeck/actions/workflows/ci.yml/badge.svg)](https://github.com/kumu314/proofdeck/actions/workflows/ci.yml)
8
- [![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
9
- ![node](https://img.shields.io/badge/node-%E2%89%A522.5-green.svg)
10
-
11
- ![A fake "done" — count=1 where the acceptance said ≥3 — gets rejected by the real verify engine](docs/assets/demo.gif)
12
-
13
- > `board/` 目录内含 [octopus-blackboard](https://github.com/octoryn/octopus-blackboard)(Apache-2.0)的修改版发行,见 [NOTICE](./NOTICE)。中文说明:[README.zh-CN.md](./README.zh-CN.md)。
1
+ <div align="center">
2
+ <img src="docs/assets/logo.svg" width="150" alt="ProofDeck logo">
3
+
4
+ <h1>ProofDeck</h1>
5
+
6
+ <p><strong>Verification-first task board &amp; orchestrator for coding-agent fleets.</strong><br>
7
+ <em>Agents claim done. ProofDeck demands proof.</em></p>
8
+
9
+ <p>
10
+ <a href="https://github.com/kumu314/proofdeck/actions/workflows/ci.yml"><img src="https://github.com/kumu314/proofdeck/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
11
+ <a href="https://www.npmjs.com/package/proofdeck"><img src="https://img.shields.io/npm/v/proofdeck.svg" alt="npm"></a>
12
+ <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="license"></a>
13
+ <img src="https://img.shields.io/badge/node-%E2%89%A522.5-green.svg" alt="node ≥22.5">
14
+ <img src="https://img.shields.io/badge/platform-Windows%20%7C%20Linux-lightgrey.svg" alt="platform">
15
+ </p>
16
+
17
+ <p>
18
+ <a href="#quick-start">Quick start</a> ·
19
+ <a href="#why">Why</a> ·
20
+ <a href="#architecture">Architecture</a> ·
21
+ <a href="#the-five-check-families">Checks</a> ·
22
+ <a href="./README.zh-CN.md">中文文档</a>
23
+ </p>
24
+ </div>
25
+
26
+ <div align="center">
27
+ <img src="docs/assets/demo.gif" width="720" alt="A fake done gets rejected by the real verify engine">
28
+ <p><sub><b>The gate in 7 seconds:</b> an agent claims <i>done</i> on 1 item where acceptance said ≥3 — the real verify engine rejects it, the task returns to open, a verify event lands in the hash chain. Rendered from an actual run; nothing fabricated.</sub></p>
29
+ </div>
14
30
 
15
31
  ## Why
16
32
 
17
- If you run one coding agent (Claude Code, Codex CLI, Gemini CLI, …) you review everything it does, and review works. The moment you run **several** agents in parallel, review becomes the bottleneck — and two failure modes compound:
33
+ One coding agent (Claude Code, Codex CLI, Gemini CLI, …) → you review everything it does, and review works. **Several agents in parallel → review becomes the bottleneck**, and two failure modes compound:
18
34
 
19
- - **False affirmatives.** The agent adds a fallback so the code "works", tests pass, and the flaw ships anyway. The industry has a name for the general problem: *reward hacking* — it is now an active research topic (ImpossibleBench, 2025; Anthropic's work on emergent misalignment from reward hacking, 2026).
20
- - **Silent death.** An agent stalls, exits 0 with nothing done, or burns its budget on a dead-end loop. Nobody notices until the deadline.
35
+ | Failure mode | What it looks like | Industry context |
36
+ |---|---|---|
37
+ | **False affirmatives** | A fallback makes it "work"; tests pass; the flaw ships | *Reward hacking* — active research area (ImpossibleBench 2025, Anthropic 2026) |
38
+ | **Silent death** | Stalls, exits 0 with nothing done, burns budget in a loop | Nobody notices until the deadline |
21
39
 
22
- ProofDeck's answer is to make **acceptance criteria a first-class column on every task** and to refuse "done" that lacks evidence:
40
+ ProofDeck's answer is to make **acceptance criteria a first-class column on every task** and refuse "done" that lacks evidence — then wrap that gate in everything a fleet needs.
23
41
 
24
- 1. Every task carries machine-checkable acceptance criteria.
25
- 2. On completion, a fail-closed verification engine runs them (file existence, occurrence counts, JSON-path matches, reference existence — five check families).
26
- 3. An LLM judge reviews the trajectory against the criteria when machine checks are not enough; its verdict lands in an **append-only sha256 hash chain** next to who claimed the task, who verified it, and when.
27
- 4. Tasks that fail are retried with backoff, parked for human review, or routed to a different agent by capability — never silently marked done.
42
+ ## The gate — how `done` gets proven
28
43
 
29
- Around that gate, ProofDeck runs the fleet: a shared SQLite-backed blackboard with MCP surface, priority lanes with aging, automatic retry with a supply breaker, SLA due-dates, digest emails, full event replay (time travel), and OpenTelemetry-style spans.
44
+ 1. **Declare.** Every task carries machine-checkable acceptance criteria.
45
+ 2. **Verify.** On completion a fail-closed engine runs them — five check families, unknown check types are FAIL, never skip.
46
+ 3. **Judge.** When machine checks aren't enough, an LLM judge reviews the trajectory against the criteria.
47
+ 4. **Record.** The verdict lands in an **append-only sha256 hash chain** — who claimed, who verified, when, with evidence.
48
+ 5. **React.** Failed tasks retry with backoff, park for human review, or route to another agent by capability. Never silently done.
30
49
 
31
- ## Status
50
+ ## Features
32
51
 
33
- `v0.1.0-preview`. Battle-tested in daily production use (a personal multi-agent fleet; hundreds of tasks) **on Windows**. The POSIX layer is new and marked **beta**: CI runs the test matrix on ubuntu as well, but real-world macOS/Linux mileage is thin — expect rough edges and please report them.
52
+ | Area | What you get |
53
+ |---|---|
54
+ | **Board** | Shared SQLite-backed task board with an MCP surface — any MCP-speaking agent reads/writes it |
55
+ | **Evidence** | Append-only sha256 chain over tasks/notes/messages/verify events; `verifyChain()` head anchoring |
56
+ | **Orchestration** | Priority lanes with aging · automatic retry with backoff · supply breaker · capability routing (`needs` × face capabilities) |
57
+ | **Judgment** | LLM judge (V1.5) with acceptance-only mode; human (V3) and cross-review (V2) escalation |
58
+ | **Observability** | Full event replay (time travel to any seq) · OpenTelemetry-style spans · per-run usage ledger |
59
+ | **Ops** | SLA due-dates · owner digest · leases · watchdog · offline-first (one SQLite file, no cloud) |
34
60
 
35
61
  ## Quick start
36
62
 
63
+ Requirements: **Node ≥ 22.5** (native `node:sqlite`; `better-sqlite3` fallback for older runtimes), Windows or Linux.
64
+
37
65
  ```bash
38
66
  npx proofdeck init # scaffold: daemon.config.json + .proofdeck/ + control.token
39
67
  # edit daemon.config.json — point agents.codex.script at a CLI you have
@@ -41,14 +69,17 @@ npx proofdeck daemon # start the daemon (board + control plane + scheduler)
41
69
  npx proofdeck status # board head, task counts, acceptance coverage
42
70
  ```
43
71
 
44
- From a git checkout instead of npm:
72
+ From a git checkout:
45
73
 
46
74
  ```bash
47
- git clone https://github.com/kumu314/proofdeck && cd proofdeck && npm install
75
+ git clone https://github.com/kumu314/proofdeck && cd proofdeck
76
+ npm install # zero native module deps
48
77
  node bin/proofdeck.js init && node bin/proofdeck.js daemon
49
78
  ```
50
79
 
51
- Any agent that speaks MCP can read/write the board (tasks, notes, messages, verification events).
80
+ Define a task with acceptance criteria, dispatch your agent, and watch the gate. Any agent that speaks MCP can read/write the board.
81
+
82
+ **Task books.** A task's instruction text lives in a file under `briefs/` with a small ```bridge fence carrying dispatch metadata (`auto`, `risk`, …); the card references it by path. The gate reads the book before dispatch — full format and gotchas in [docs/task-book.md](./docs/task-book.md).
52
83
 
53
84
  ## Architecture
54
85
 
@@ -67,32 +98,56 @@ Any agent that speaks MCP can read/write the board (tasks, notes, messages, veri
67
98
  └───────────────────────────────────────────┘
68
99
  ```
69
100
 
70
- - **board/** — vendored, modified distribution of octopus-blackboard: the shared task board with an append-only hash chain, MCP surface, and the acceptance/verification schema.
71
- - **lib/** — verification engine (`verify.js`), LLM judge (`judge.js`), scheduling core with priority aging and retry policy (`schedule.js`), capability routing (`caps.js`), event replay (`replay.js`), spans, digest, leases, supply breaker.
72
- - **Adapters** — each agent face is one small module (`lib/adapters/`); a generic CLI adapter (`codex.js`) is the reference implementation. Prompts are fed via stdin, never argv — long CJK text corrupts through some shells (a real cross-platform lesson from production).
101
+ | Component | File | Role |
102
+ |---|---|---|
103
+ | Board | `board/` | Vendored, modified [octopus-blackboard](https://github.com/octoryn/octopus-blackboard) fork — hash chain, MCP, acceptance/verification schema (see [NOTICE](./NOTICE)) |
104
+ | Verify engine | `lib/verify.js` | Fail-closed check runner, task-column-first acceptance |
105
+ | LLM judge | `lib/judge.js` | V1.5 trajectory review; unavailable judge fails open |
106
+ | Scheduler | `lib/schedule.js` | P0–P3 lanes, aging, retry policy (pure, unit-tested) |
107
+ | Routing | `lib/caps.js` | `needs` × face-capability matching |
108
+ | Replay | `lib/replay.js` | Fold timeline to any seq, diff against now |
109
+ | Platform | `lib/platform.js` | Dual-OS process primitives (killTree / getProcessInfo) |
110
+ | Adapters | `lib/adapters/` | One small module per agent face; `codex.js` is the reference implementation |
111
+
112
+ ## The five check families
113
+
114
+ | Check | Asserts | Example |
115
+ |---|---|---|
116
+ | `fileExists` | File exists, ≥ `minBytes` | a rendered artifact actually shipped |
117
+ | `countAtLeast` | JSON value (number/array length) ≥ `min` | `report.count ≥ 3` |
118
+ | `countOccurrences` | Literal substring count ≥ `minCount` | changelog mentions the fix |
119
+ | `countMatches` | JSON-path match count ≥ `min` | every item has a status field |
120
+ | `referencesExist` | Files referenced in JSON exist | every asset in the manifest is on disk |
121
+
122
+ Unknown check types are **FAIL** — a typo in acceptance criteria never silently passes.
73
123
 
74
124
  ## Design principles
75
125
 
76
- - **Fail closed.** A task without acceptance criteria is not silently accepted — it is flagged, every dispatch, until it has them.
77
- - **Evidence over vibes.** Verification results are events in a hash chain, not chat messages.
126
+ - **Fail closed.** Missing acceptance is flagged on every dispatch, never skipped.
127
+ - **Evidence over vibes.** Verification results are hash-chain events, not chat messages.
78
128
  - **The board is the truth.** Agents come and go; the append-only timeline remembers.
79
- - **Boring storage.** One SQLite file per deployment. `node:sqlite` natively, `better-sqlite3` as fallback (`OCTOBOARD_BACKEND=better-sqlite3`).
129
+ - **Boring storage.** One SQLite file per deployment — no cloud, no telemetry.
130
+ - **Prompts via stdin, never argv.** Long CJK text corrupts through some shells (a production lesson).
80
131
 
81
132
  ## Testing
82
133
 
83
- 15 end-to-end suites (verification, anti-fraud, judge, scheduling, resilience, replay, SLA/digest, …) run against real boards:
134
+ 13 e2e suites run against real boards — verification, anti-fraud, judge, scheduling, resilience (watchdog/guard), replay, SLA/digest, lease, schema evolution:
84
135
 
85
136
  ```bash
86
- node e2e/verify-verify-firstclass.mjs # naming: verify-<topic>.mjs, see e2e/
137
+ npm test # native backend
138
+ OCTOBOARD_BACKEND=better-sqlite3 npm test # fallback backend
87
139
  ```
88
140
 
141
+ CI runs the full matrix on Windows + ubuntu, both backends — the native cell installs with `--omit=optional`, proving zero-native-dependency installs.
142
+
143
+ ## Status
144
+
145
+ `v0.1.0`. Daily-production-proven on Windows (a personal multi-agent fleet, hundreds of tasks). Linux is CI-validated (13/13) with thinner real-world mileage — rough edges expected, reports welcome.
146
+
89
147
  ## Contributing & security
90
148
 
91
- Contribution guide in [CONTRIBUTING.md](./CONTRIBUTING.md) — PRs need CI green
92
- and evidence, same as our agents. Security disclosures via
93
- [SECURITY.md](./SECURITY.md) (private reporting, 7-day response). Releases are
94
- tagged; see [CHANGELOG.md](./CHANGELOG.md).
149
+ [CONTRIBUTING.md](./CONTRIBUTING.md) — PRs need CI green and pasted evidence, same standard as our agents. Security disclosures via [SECURITY.md](./SECURITY.md) (private reporting, 7-day response). Releases tagged — see [CHANGELOG.md](./CHANGELOG.md).
95
150
 
96
151
  ## License
97
152
 
98
- Apache-2.0. See [LICENSE](./LICENSE) and [NOTICE](./NOTICE) — this project includes a modified distribution of [octopus-blackboard](https://github.com/octoryn/octopus-blackboard) by Ran Tao / octoryn.
153
+ [Apache-2.0](./LICENSE). Includes a modified distribution of [octopus-blackboard](https://github.com/octoryn/octopus-blackboard) by Ran Tao / octoryn — see [NOTICE](./NOTICE).
package/README.zh-CN.md CHANGED
@@ -1,35 +1,67 @@
1
- # ProofDeck
2
-
3
- **验证优先的编码 agent 舰队任务板与编排器。**
4
-
5
- Agent 说 done,ProofDeck 要证据。
6
-
7
- ![一次"假完成"(验收要 count≥3,产物只有 1)被真实验证引擎当场拒绝](docs/assets/demo.gif)
8
-
9
- > 本仓库 `board/` 目录内含 [octopus-blackboard](https://github.com/octoryn/octopus-blackboard)(Apache-2.0)的修改版发行,见 [NOTICE](./NOTICE)。English: [README.md](./README.md)。
1
+ <div align="center">
2
+ <img src="docs/assets/logo.svg" width="150" alt="ProofDeck logo">
3
+
4
+ <h1>ProofDeck</h1>
5
+
6
+ <p><strong>验证优先的编码 agent 舰队任务板与编排器。</strong><br>
7
+ <em>Agent 说 done,ProofDeck 要证据。</em></p>
8
+
9
+ <p>
10
+ <a href="https://github.com/kumu314/proofdeck/actions/workflows/ci.yml"><img src="https://github.com/kumu314/proofdeck/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
11
+ <a href="https://www.npmjs.com/package/proofdeck"><img src="https://img.shields.io/npm/v/proofdeck.svg" alt="npm"></a>
12
+ <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="license"></a>
13
+ <img src="https://img.shields.io/badge/node-%E2%89%A522.5-green.svg" alt="node ≥22.5">
14
+ <img src="https://img.shields.io/badge/platform-Windows%20%7C%20Linux-lightgrey.svg" alt="platform">
15
+ </p>
16
+
17
+ <p>
18
+ <a href="#快速开始">快速开始</a> ·
19
+ <a href="#为什么">为什么</a> ·
20
+ <a href="#架构">架构</a> ·
21
+ <a href="#五类检查族">检查族</a> ·
22
+ <a href="./README.md">English</a>
23
+ </p>
24
+ </div>
25
+
26
+ <div align="center">
27
+ <img src="docs/assets/demo.gif" width="720" alt="假完成被真实验证引擎当场拒绝">
28
+ <p><sub><b>7 秒看懂门禁:</b>agent 在验收要求 count≥3 的任务上只交付了 1 项就声称 <i>done</i>——真实验证引擎当场拒绝,任务退回 open 重新派发,验证事件落进哈希链。内容来自真实运行渲染,无任何虚构。</sub></p>
29
+ </div>
10
30
 
11
31
  ## 为什么
12
32
 
13
- 只跑一个编码 agent(Claude Code、Codex CLI、Gemini CLI……)时,你会 review 它的每一步,review 是有效的。但你一旦**并行跑好几个** agent,review 就成了瓶颈,而两种失败模式会叠加:
33
+ 只跑一个编码 agent(Claude Code、Codex CLI、Gemini CLI……)时,你会 review 它的每一步,review 是有效的。但你一旦**并行跑好几个**,review 就成了瓶颈,两种失败模式叠加:
14
34
 
15
- - **虚假确认(false affirmative)**。agent 加个 fallback 让代码"能跑",测试也过了,缺陷照样上线。业界给这类问题起了名字——*reward hacking*,它现在是活跃的研究课题(ImpossibleBench 2025;Anthropic 关于 reward hacking 引发的突现失调研究 2026)。
16
- - **静默死亡**。agent 卡住、rc=0 但什么都没干、或把预算烧在死循环里——直到截止日期前都没人发现。
35
+ | 失败模式 | 典型表现 | 业界语境 |
36
+ |---|---|---|
37
+ | **虚假确认** | 加个 fallback 让代码"能跑",测试也过了,缺陷照样上线 | *reward hacking*——活跃研究课题(ImpossibleBench 2025、Anthropic 2026) |
38
+ | **静默死亡** | 卡住、rc=0 但什么都没干、预算烧进死循环 | 截止日期前没人发现 |
17
39
 
18
- ProofDeck 的答案是:**把验收标准做成每张任务的一等公民**,并拒绝没有证据的"done":
40
+ ProofDeck 的答案是:**把验收标准做成每张任务的一等公民**,拒绝没有证据的"done"——再在这道门禁外面套上整支舰队需要的一切。
19
41
 
20
- 1. 每张任务携带机器可校验的验收标准;
21
- 2. 完成时,fail-closed 验证引擎执行验收(文件存在、次数下限、JSON 路径断言、引用存在——五类检查);
22
- 3. 机器检查不够时,LLM judge 依据验收标准复核轨迹,它的判定连同"谁认领、谁验证、何时"一起写进**追加式 sha256 哈希链**;
23
- 4. 验证失败的任务按退避自动重试、转入人工复核、或按能力路由给另一个 agent——**绝不静默标记完成**。
42
+ ## 门禁——"done" 如何被证明
24
43
 
25
- 在那道门禁周围,ProofDeck 负责整支舰队:SQLite 共享黑板(带 MCP 面)、带 aging 的优先级车道、自动重试与供应熔断、SLA 到期、摘要邮件、全量事件回放(时间旅行)、以及 OpenTelemetry 风格 span。
44
+ 1. **声明。** 每张任务携带机器可校验的验收标准。
45
+ 2. **验证。** 完成时 fail-closed 引擎执行验收——五类检查,未知类型一律 FAIL,绝不跳过。
46
+ 3. **复核。** 机器检查不够时,LLM judge 依据验收标准复核轨迹。
47
+ 4. **记账。** 判定连同"谁认领、谁验证、何时"写进**追加式 sha256 哈希链**。
48
+ 5. **响应。** 失败任务按退避重试、转人工复核、或按能力路由给其他 agent——绝不静默标记完成。
26
49
 
27
- ## 状态
50
+ ## 特性总览
28
51
 
29
- `v0.1.0-preview`。在真实日常使用中淬炼(个人多 agent 舰队,数百张任务)——**Windows 为一等公民**。POSIX 层标记为 **beta**:CI 在 ubuntu 上跑完整测试矩阵(13/13 绿),但真实世界的 macOS/Linux 使用里程还薄——遇到坑请报 issue。
52
+ | 领域 | 能力 |
53
+ |---|---|
54
+ | **黑板** | SQLite 共享任务板 + MCP 面——任何说 MCP 的 agent 可读写 |
55
+ | **证据** | 任务/注记/消息/验证事件的追加式 sha256 链;`verifyChain()` 锚定校验 |
56
+ | **编排** | 带 aging 的优先级车道 · 指数退避自动重试 · 供应熔断 · 能力路由(`needs` × 面能力) |
57
+ | **判定** | LLM judge(V1.5,acceptance-only 模式);人工(V3)与交叉评审(V2)升级 |
58
+ | **观测** | 全量事件回放(时间旅行到任意 seq)· OpenTelemetry 风格 span · 单轮用量台账 |
59
+ | **运维** | SLA 到期 · owner 摘要 · 租约 · 看门狗 · 离线优先(一个 SQLite 文件,无云依赖) |
30
60
 
31
61
  ## 快速开始
32
62
 
63
+ 环境要求:**Node ≥ 22.5**(原生 `node:sqlite`;旧运行时用 `better-sqlite3` 回退),Windows 或 Linux。
64
+
33
65
  ```bash
34
66
  npx proofdeck init # 脚手架:daemon.config.json + .proofdeck/ + control.token
35
67
  # 编辑 daemon.config.json —— 把 agents.codex.script 指向你有的 CLI
@@ -40,11 +72,14 @@ npx proofdeck status # 看板块 head、任务统计、验收覆盖
40
72
  从 git 检出运行:
41
73
 
42
74
  ```bash
43
- git clone https://github.com/kumu314/proofdeck && cd proofdeck && npm install
75
+ git clone https://github.com/kumu314/proofdeck && cd proofdeck
76
+ npm install # 零原生模块依赖
44
77
  node bin/proofdeck.js init && node bin/proofdeck.js daemon
45
78
  ```
46
79
 
47
- 任何说 MCP 的 agent 都能读写黑板(任务、注记、消息、验证事件)。
80
+ 给任务写上验收标准、派出你的 agent,然后看门禁工作。任何说 MCP 的 agent 都能读写黑板。
81
+
82
+ **任务书。** 任务的题面放在 `briefs/` 下的文件里,带一小段 ```bridge 围栏块承载派发元数据(`auto`、`risk`……),卡面只放文件指针。门禁在派发前会读任务书做风险评估——完整格式与坑位见 [docs/task-book.md](./docs/task-book.md)。
48
83
 
49
84
  ## 架构
50
85
 
@@ -62,28 +97,56 @@ node bin/proofdeck.js init && node bin/proofdeck.js daemon
62
97
  └───────────────────────────────────────────┘
63
98
  ```
64
99
 
65
- - **board/** —— octopus-blackboard 的修改版发行:共享任务板,追加式哈希链、MCP 面、验收/验证 schema。
66
- - **lib/** —— 验证引擎(`verify.js`)、LLM judge(`judge.js`)、带优先级 aging 与重试策略的调度核(`schedule.js`)、能力路由(`caps.js`)、事件回放(`replay.js`)、span、摘要、租约、供应熔断。
67
- - **适配器** —— 每个 agent 面就是一个小模块(`lib/adapters/`);通用 CLI 适配器(`codex.js`)是参考实现。题面经 stdin 喂入、绝不放 argv——长中文文本过某些 shell 会被搅坏(这是生产线换来的跨平台教训)。
100
+ | 组件 | 文件 | 职责 |
101
+ |---|---|---|
102
+ | 黑板 | `board/` | [octopus-blackboard](https://github.com/octoryn/octopus-blackboard) 修改版发行——哈希链、MCP 面、验收/验证 schema(见 [NOTICE](./NOTICE)) |
103
+ | 验证引擎 | `lib/verify.js` | fail-closed 检查执行器,任务列优先的验收读取 |
104
+ | LLM judge | `lib/judge.js` | V1.5 轨迹复核;judge 不可用时优雅跳过 |
105
+ | 调度核 | `lib/schedule.js` | P0–P3 车道、aging、重试策略(纯函数、单测覆盖) |
106
+ | 路由 | `lib/caps.js` | `needs` × 面能力匹配 |
107
+ | 回放 | `lib/replay.js` | 折叠时间线到任意 seq,与当前态 diff |
108
+ | 平台 | `lib/platform.js` | 双 OS 进程原语(killTree / getProcessInfo) |
109
+ | 适配器 | `lib/adapters/` | 每个 agent 面一个小模块;`codex.js` 是参考实现 |
110
+
111
+ ## 五类检查族
112
+
113
+ | 检查 | 断言 | 示例 |
114
+ |---|---|---|
115
+ | `fileExists` | 文件存在且 ≥ `minBytes` | 渲染产物真的出货了 |
116
+ | `countAtLeast` | JSON 值(数字/数组长度)≥ `min` | `report.count ≥ 3` |
117
+ | `countOccurrences` | 字面量子串出现次数 ≥ `minCount` | changelog 里提到了本次修复 |
118
+ | `countMatches` | JSON 路径匹配数 ≥ `min` | 每个条目都有 status 字段 |
119
+ | `referencesExist` | JSON 里引用的文件都存在 | manifest 里每个资产都在盘上 |
120
+
121
+ 未知检查类型一律 **FAIL**——验收标准里的拼写错误永远不会静默放行。
68
122
 
69
123
  ## 设计原则
70
124
 
71
- - **Fail closed。** 没有验收标准的任务不会被静默接受——每次派发都被标注提示,直到补上。
72
- - **证据而非感觉。** 验证结果是哈希链里的事件,不是聊天记录。
125
+ - **Fail closed。** 缺验收标准的任务每次派发都被标注提示,绝不静默跳过。
126
+ - **证据而非感觉。** 验证结果是哈希链事件,不是聊天记录。
73
127
  - **黑板即真相。** Agent 来来去去;追加式时间线记得一切。
74
- - **无聊的存储。** 每次部署一个 SQLite 文件。原生 `node:sqlite`,`better-sqlite3` 作回退(`OCTOBOARD_BACKEND=better-sqlite3`)。
128
+ - **无聊的存储。** 每次部署一个 SQLite 文件——无云、无遥测。
129
+ - **题面走 stdin,绝不走 argv。** 长中文文本过某些 shell 会被搅坏(生产线换来的教训)。
75
130
 
76
131
  ## 测试
77
132
 
78
- 13 套端到端套件(验证、防刷分、judge、调度、韧性、回放、SLA/摘要……),打在真实黑板上:
133
+ 13 套端到端套件打在真实黑板上——验证、防刷分、judge、调度、韧性(看门狗/guard)、回放、SLA/摘要、租约、schema 演进:
79
134
 
80
135
  ```bash
81
- node scripts/run-e2e.mjs # 全量(node:sqlite 原生后端)
82
- OCTOBOARD_BACKEND=better-sqlite3 node scripts/run-e2e.mjs # 回退后端
136
+ npm test # 原生后端
137
+ OCTOBOARD_BACKEND=better-sqlite3 npm test # 回退后端
83
138
  ```
84
139
 
85
- CI 在 Windows/ubuntu × 双后端四格矩阵上跑全套;native 格用 `--omit=optional` 安装——在干净机器上实证"零原生依赖"。
140
+ CI 在 Windows + ubuntu × 双后端四格矩阵上跑全套;native 格用 `--omit=optional` 安装——在干净机器上实证"零原生依赖"。
141
+
142
+ ## 状态
143
+
144
+ `v0.1.0`。Windows 上日常生产淬炼(个人多 agent 舰队,数百张任务)。Linux 已 CI 验证(13/13)但真实里程较薄——遇到坑请报 issue。
145
+
146
+ ## 参与贡献与安全
147
+
148
+ [CONTRIBUTING.md](./CONTRIBUTING.md)——PR 需要 CI 绿 + 贴出证据,和我们的 agent 一个标准。安全披露走 [SECURITY.md](./SECURITY.md)(私有报告,7 天响应)。发版打 tag——见 [CHANGELOG.md](./CHANGELOG.md)。
86
149
 
87
150
  ## 许可
88
151
 
89
- Apache-2.0。见 [LICENSE](./LICENSE) 与 [NOTICE](./NOTICE)——本项目包含 [octopus-blackboard](https://github.com/octoryn/octopus-blackboard)(Ran Tao / octoryn)的修改版发行。
152
+ [Apache-2.0](./LICENSE)。含 [octopus-blackboard](https://github.com/octoryn/octopus-blackboard)(Ran Tao / octoryn)修改版发行——见 [NOTICE](./NOTICE)。
package/bin/proofdeck.js CHANGED
@@ -14,6 +14,7 @@ import { join, dirname, resolve } from "node:path";
14
14
  import { fileURLToPath } from "node:url";
15
15
  import { spawn } from "node:child_process";
16
16
  import { randomBytes } from "node:crypto";
17
+ import net from "node:net";
17
18
 
18
19
  const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
19
20
  const BOARD_PKG = join(PKG_ROOT, "board");
@@ -27,14 +28,24 @@ function usage() {
27
28
  say(`ProofDeck — verification-first task board & orchestrator for coding-agent fleets
28
29
 
29
30
  Usage:
30
- proofdeck init [dir] Scaffold a project dir (default: current)
31
- proofdeck daemon Run the daemon for the current project dir
32
- proofdeck status Show board head / task / verify counts
33
- proofdeck --version Print version
31
+ proofdeck init [dir] Scaffold a project dir (default: current)
32
+ proofdeck daemon Run the daemon for the current project dir
33
+ proofdeck status Show board head / task / verify counts
34
+ proofdeck assign <key> <agent> Queue a task card to an agent face
35
+ proofdeck --version Print version
34
36
 
35
37
  Docs: https://github.com/kumu314/proofdeck`);
36
38
  }
37
39
 
40
+ function findFreePort(start = 8790, tries = 20) {
41
+ return new Promise((res) => {
42
+ const srv = net.createServer();
43
+ srv.once("error", () => (tries-- > 0 ? res(findFreePort(start + 1, tries)) : res(start)));
44
+ srv.once("listening", () => srv.close(() => res(start)));
45
+ srv.listen(start, "127.0.0.1");
46
+ });
47
+ }
48
+
38
49
  function cmdInit(args) {
39
50
  const dir = resolve(args[0] ?? ".");
40
51
  const cfgPath = join(dir, "daemon.config.json");
@@ -48,22 +59,75 @@ function cmdInit(args) {
48
59
  // Point the vendored board at the packaged copy so init works from anywhere.
49
60
  cfg.board.package = BOARD_PKG.replace(/\\/g, "/");
50
61
  cfg.board.dir = "./.proofdeck";
51
- writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + "\n");
52
-
53
- mkdirSync(join(dir, ".proofdeck"), { recursive: true });
54
- mkdirSync(join(dir, "workdirs"), { recursive: true });
55
- const tokenPath = join(dir, "control.token");
56
- if (!existsSync(tokenPath)) writeFileSync(tokenPath, randomBytes(24).toString("hex") + "\n");
57
-
58
- ok(`scaffolded ${dir}`);
59
- say(` daemon.config.json ← edit agents.* to point at your CLI(s)`);
60
- say(` .proofdeck/ ← board lives here (one SQLite file + audit chain)`);
61
- say(` control.token ← local control-plane credential`);
62
- say("");
63
- say("Next:");
64
- say(" 1) edit daemon.config.json — set agents.codex.script to your agent CLI");
65
- say(" 2) proofdeck daemon (or: node daemon.js daemon.config.json)");
66
- say(" 3) define a task with acceptance criteria, then watch the gate work");
62
+
63
+ // Per-face workdirs up front: agents spawn with -C <workdir>; a missing dir
64
+ // kills the face with os error 3 before it can say anything (dogfood finding).
65
+ const faces = Object.entries(cfg.agents ?? {});
66
+ for (const [name, face] of faces) {
67
+ if (face.workdir) face.workdir = join(dir, "workdirs", name).replace(/\\/g, "/");
68
+ }
69
+
70
+ // Free control-plane port: a fixed 8790 collides with any other ProofDeck on
71
+ // the machine (dogfood finding).
72
+ const port = findFreePort(cfg.http?.port ?? 8790);
73
+ return Promise.resolve(port).then((free) => {
74
+ if (cfg.http) cfg.http.port = free;
75
+ cfg.runtime ??= {};
76
+ cfg.runtime.autoAssign = true; // open+auto-flagged tasks queue to their face automatically
77
+
78
+ writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + "\n");
79
+
80
+ mkdirSync(join(dir, ".proofdeck"), { recursive: true });
81
+ mkdirSync(join(dir, "briefs"), { recursive: true });
82
+ for (const [name] of faces) mkdirSync(join(dir, "workdirs", name), { recursive: true });
83
+ const tokenPath = join(dir, "control.token");
84
+ if (!existsSync(tokenPath)) writeFileSync(tokenPath, randomBytes(24).toString("hex") + "\n");
85
+
86
+ // starter task book: the pointer-style brief with a ```bridge fence
87
+ const brief = join(dir, "briefs", "my-first-task.md");
88
+ if (!existsSync(brief)) {
89
+ writeFileSync(brief, [
90
+ "Write hello.md in the workspace containing the single line: it works.",
91
+ "",
92
+ "```bridge",
93
+ '{ "auto": "yes", "risk": "low", "impact": "low" }',
94
+ "```",
95
+ "",
96
+ ].join("\n"));
97
+ }
98
+
99
+ ok(`scaffolded ${dir} (control port: ${free})`);
100
+ say(` daemon.config.json ← edit agents.* to point at your CLI(s)`);
101
+ say(` briefs/my-first-task.md ← starter task book (pointer-style)`);
102
+ say(` .proofdeck/ ← board lives here (one SQLite file + audit chain)`);
103
+ say(` control.token ← local control-plane credential`);
104
+ say("");
105
+ say("Next:");
106
+ say(" 1) edit daemon.config.json — set agents.codex.script to your agent CLI");
107
+ say(" 2) define the task card (see briefs/my-first-task.md + docs/task-book.md):");
108
+ say(` description: "任务书:${join(dir, "briefs", "my-first-task.md").replace(/\\\\/g, "/")}"`);
109
+ say(" 3) proofdeck daemon (or: node daemon.js daemon.config.json)");
110
+ say(" 4) proofdeck assign my-first-task codex — or let autoAssign queue it");
111
+ say(" 5) proofdeck status — watch the verify gate work");
112
+ return 0;
113
+ });
114
+ }
115
+
116
+
117
+ async function cmdAssign(args) {
118
+ const [key, agent] = args;
119
+ if (!key || !agent) { warn("usage: proofdeck assign <key> <agent>"); return 1; }
120
+ const cfgPath = join(process.cwd(), "daemon.config.json");
121
+ if (!existsSync(cfgPath)) { warn(`no daemon.config.json in ${process.cwd()}`); return 1; }
122
+ const cfg = JSON.parse(readFileSync(cfgPath, "utf8"));
123
+ const boardDir = resolve(process.cwd(), cfg.board.dir ?? ".proofdeck");
124
+ const pkg = cfg.board.package ?? BOARD_PKG;
125
+ const { Board } = await import(new URL("file://" + join(resolve(pkg), "dist", "board.js").replace(/\\/g, "/")).href);
126
+ const b = Board.open({ boardDir, agent: cfg.board.identity ?? "bridge" });
127
+ try {
128
+ b.assign(cfg.board.identity ?? "bridge", key, agent);
129
+ ok(`queued ${key} → ${agent}`);
130
+ } finally { try { b.close(); } catch { } }
67
131
  return 0;
68
132
  }
69
133
 
@@ -120,7 +184,8 @@ else if (cmd === "--version" || cmd === "-v") {
120
184
  const pkg = JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf8"));
121
185
  console.log(pkg.version);
122
186
  process.exit(0);
123
- } else if (cmd === "init") process.exit(cmdInit(rest));
187
+ } else if (cmd === "init") process.exit(await cmdInit(rest));
188
+ else if (cmd === "assign") process.exit(await cmdAssign(rest));
124
189
  else if (cmd === "daemon") process.exit(await cmdDaemon());
125
190
  else if (cmd === "status") process.exit(await cmdStatus());
126
191
  else { warn(`unknown command: ${cmd}`); usage(); process.exit(1); }
@@ -14,6 +14,7 @@
14
14
  },
15
15
  "runtime": {
16
16
  "dryRun": false,
17
+ "autoAssign": true,
17
18
  "reconcileMs": 60000,
18
19
  "debounceMs": 50,
19
20
  "maxConcurrentTotal": 2,
package/daemon.js CHANGED
@@ -3,7 +3,7 @@
3
3
  // agent spawn -> automatic claim/progress/done/note write-back.
4
4
  // Board I/O exclusively via the shared octopus-blackboard Board library.
5
5
  import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } from "node:fs";
6
- import { join, dirname, resolve } from "node:path";
6
+ import { join, dirname, resolve, isAbsolute } from "node:path";
7
7
  import { fileURLToPath } from "node:url";
8
8
  import { spawn } from "node:child_process";
9
9
  import { Worker } from "node:worker_threads";
@@ -38,6 +38,13 @@ const cfgPath = process.argv[2] ? resolveCfg(process.argv[2]) : join(BASE, "daem
38
38
  function resolveCfg(p) { return p.includes(":") || p.startsWith("/") ? p : join(BASE, p); }
39
39
  const cfg = JSON.parse(readFileSync(cfgPath, "utf8"));
40
40
 
41
+ // workdir absolutization: a relative workdir gets double-resolved through the
42
+ // spawn chain (daemon cwd → agent cwd) and dies with os error 3 before the
43
+ // face can say anything (dogfood finding). Normalize against BASE at load.
44
+ for (const face of Object.values(cfg.agents ?? {})) {
45
+ if (face.workdir && !isAbsolute(face.workdir)) face.workdir = resolve(BASE, face.workdir);
46
+ }
47
+
41
48
  const ID = cfg.board.identity;
42
49
  const DAY = () => { const d = new Date(); return `${d.getFullYear()}${String(d.getMonth() + 1).padStart(2, "0")}${String(d.getDate()).padStart(2, "0")}`; };
43
50
  const LOGF = join(BASE, "logs", `daemon-${DAY()}.log`);
@@ -287,6 +294,35 @@ async function tick(why) {
287
294
  }
288
295
  store.save();
289
296
 
297
+ // 1.5) autoAssign(v0.1.1 上手路径修复):带 ```bridge auto 标记的 open 卡
298
+ // 无需手动 assign 事件——扫描后直接入队到第一个启用的面(gating 照常把关)。
299
+ // 关闭方式:runtime.autoAssign = false。
300
+ if (cfg.runtime?.autoAssign !== false) {
301
+ let auto = 0;
302
+ try {
303
+ await board.withBoard(cfg.board, (b) => {
304
+ for (const c of b.listTaskCards()) {
305
+ const t = c.task || {};
306
+ if (t.status !== "open") continue;
307
+ const key = t.key;
308
+ if (!key || store.s.runs[key] || store.s.finished[key] || store.s.pending[key]) continue;
309
+ if (Object.values(store.s.lanes ?? {}).some((l) => l.includes(key))) continue;
310
+ const fence = parseBridgeBlock(t.description ?? "");
311
+ if (!fence || !/^(yes|true|1)$/i.test(String(fence.auto ?? ""))) continue;
312
+ const agent = (enabledAgents.includes(fence.agent) && fence.agent) || enabledAgents[0];
313
+ if (!agent) continue;
314
+ if (store.queue(key, agent, { priority: fence.priority })) {
315
+ auto++;
316
+ log(`autoAssign ${key} -> ${agent} (fence auto flag)`);
317
+ }
318
+ }
319
+ });
320
+ } catch (e) {
321
+ log(`autoAssign scan error: ${e.message}`);
322
+ }
323
+ if (auto) store.save();
324
+ }
325
+
290
326
  // 2) schedule lanes (paused entirely while STOP is present)
291
327
  if (existsSync(STOP)) {
292
328
  if (store.s.lanes && Object.values(store.s.lanes).some((l) => l.length)) log("STOP present — scheduling paused");
Binary file
@@ -0,0 +1,31 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
2
+ <!-- ProofDeck logo: a deck card stamped with a proof seal, chained. -->
3
+ <defs>
4
+ <linearGradient id="cardbg" x1="0" y1="0" x2="1" y2="1">
5
+ <stop offset="0" stop-color="#1c2b2e"/>
6
+ <stop offset="1" stop-color="#172224"/>
7
+ </linearGradient>
8
+ </defs>
9
+
10
+ <!-- hash-chain dots leading into the card -->
11
+ <g fill="#a6d0b9" opacity="0.55">
12
+ <circle cx="70" cy="430" r="10"/>
13
+ <circle cx="108" cy="456" r="7"/>
14
+ <circle cx="142" cy="474" r="4.5"/>
15
+ </g>
16
+
17
+ <!-- the deck card, slightly stamped over -->
18
+ <g transform="rotate(-8 256 256)">
19
+ <rect x="96" y="96" width="320" height="320" rx="48" fill="url(#cardbg)" stroke="#e9c779" stroke-width="10"/>
20
+ <!-- proof seal: ring + check -->
21
+ <circle cx="256" cy="240" r="92" fill="none" stroke="#e9c779" stroke-width="12"/>
22
+ <circle cx="256" cy="240" r="74" fill="none" stroke="#a6d0b9" stroke-width="4" opacity="0.5"/>
23
+ <path d="M 214 244 L 246 276 L 306 204" fill="none" stroke="#a6d0b9" stroke-width="18" stroke-linecap="round" stroke-linejoin="round"/>
24
+ <!-- card footer rule: the "evidence line" -->
25
+ <line x1="170" y1="368" x2="342" y2="368" stroke="#e9c779" stroke-width="8" stroke-linecap="round" opacity="0.85"/>
26
+ <line x1="196" y1="388" x2="316" y2="388" stroke="#e9c779" stroke-width="5" stroke-linecap="round" opacity="0.45"/>
27
+ </g>
28
+
29
+ <!-- stamp notch: the deck was here -->
30
+ <circle cx="418" cy="118" r="9" fill="#e9c779" opacity="0.9"/>
31
+ </svg>
Binary file
@@ -0,0 +1,101 @@
1
+ #!/usr/bin/env python3
2
+ """Render ProofDeck logo/social-preview PNGs (supersampled for crisp edges)."""
3
+ from PIL import Image, ImageDraw, ImageFont
4
+ import os
5
+
6
+ HERE = os.path.dirname(__file__)
7
+ ASSETS = os.path.join(HERE, "assets")
8
+ os.makedirs(ASSETS, exist_ok=True)
9
+
10
+ GOLD = (233, 199, 121)
11
+ MINT = (166, 208, 185)
12
+ CARD = (28, 43, 46)
13
+ CARD2 = (23, 34, 36)
14
+ BG = (16, 26, 27)
15
+ INK = (237, 240, 223)
16
+ DIM = (140, 158, 152)
17
+
18
+ def font(size, bold=True):
19
+ paths = (["C:/Windows/Fonts/segoeuib.ttf", "C:/Windows/Fonts/arialbd.ttf"] if bold
20
+ else ["C:/Windows/Fonts/segoeui.ttf", "C:/Windows/Fonts/arial.ttf"])
21
+ for p in paths:
22
+ if os.path.exists(p):
23
+ return ImageFont.truetype(p, size)
24
+ return ImageFont.load_default()
25
+
26
+ def rounded_card(d, cx, cy, size, rot_anti=False):
27
+ """Draw the deck card (rotate applied on a square canvas via supersample coords)."""
28
+ # we draw axis-aligned here; rotation handled by drawing the whole logo rotated
29
+ half = size // 2
30
+ d.rounded_rectangle([cx - half, cy - half, cx + half, cy + half], radius=int(size * 0.15),
31
+ fill=CARD, outline=GOLD, width=10)
32
+
33
+ def seal(d, cx, cy, r):
34
+ d.ellipse([cx - r, cy - r, cx + r, cy + r], outline=GOLD, width=12)
35
+ r2 = r - 14
36
+ d.ellipse([cx - r2, cy - r2, cx + r2, cy + r2], outline=MINT, width=4)
37
+ # checkmark
38
+ pts = [(cx - r * 0.48, cy + r * 0.02), (cx - r * 0.12, cy + r * 0.42), (cx + r * 0.56, cy - r * 0.38)]
39
+ d.line(pts, fill=MINT, width=18, joint="curve")
40
+ for p in pts:
41
+ d.ellipse([p[0] - 9, p[1] - 9, p[0] + 9, p[1] + 9], fill=MINT)
42
+
43
+ def chain_dots(d, pts):
44
+ for (x, y, r, o) in pts:
45
+ c = MINT if o == 255 else (MINT[0], MINT[1], MINT[2])
46
+ d.ellipse([x - r, y - r, x + r, y + r], fill=(int(MINT[0] * o / 255), int(MINT[1] * o / 255), int(MINT[2] * o / 255)))
47
+
48
+ def draw_logo_square(scale=2, size_px=512):
49
+ S = size_px * scale
50
+ im = Image.new("RGBA", (S, S), (0, 0, 0, 0))
51
+ d = ImageDraw.Draw(im)
52
+ # rotate the whole emblem by drawing on a larger transparent canvas then rotating
53
+ emblem = Image.new("RGBA", (S, S), (0, 0, 0, 0))
54
+ ed = ImageDraw.Draw(emblem)
55
+ card_size = int(S * 0.62)
56
+ rounded_card(ed, S // 2, S // 2, card_size)
57
+ seal(ed, S // 2, int(S * 0.47), int(S * 0.18))
58
+ # evidence lines
59
+ ed.rounded_rectangle([int(S * 0.33), int(S * 0.72), int(S * 0.67), int(S * 0.745)],
60
+ radius=int(S * 0.012), fill=GOLD)
61
+ ed.rounded_rectangle([int(S * 0.38), int(S * 0.76), int(S * 0.62), int(S * 0.782)],
62
+ radius=int(S * 0.008), fill=(GOLD[0], GOLD[1], GOLD[2], 115))
63
+ # chain dots
64
+ chain_dots(ed, [(int(S * 0.14), int(S * 0.84), int(S * 0.02), 140),
65
+ (int(S * 0.21), int(S * 0.89), int(S * 0.014), 110),
66
+ (int(S * 0.27), int(S * 0.925), int(S * 0.009), 90)])
67
+ emblem = emblem.rotate(-8, resample=Image.BICUBIC, expand=False)
68
+ im.alpha_composite(emblem)
69
+ # gold notch
70
+ d.ellipse([int(S * 0.815), int(S * 0.2), int(S * 0.855), int(S * 0.24)], fill=GOLD)
71
+ return im.resize((size_px, size_px), Image.LANCZOS)
72
+
73
+ # 1) logo-512.png
74
+ logo = draw_logo_square(scale=2, size_px=512)
75
+ logo.save(os.path.join(ASSETS, "logo-512.png"))
76
+
77
+ # 2) social preview 1280x640
78
+ SPW, SPH = 1280, 640
79
+ S = 2
80
+ sp = Image.new("RGBA", (SPW * S, SPH * S), BG)
81
+ d = ImageDraw.Draw(sp)
82
+ # subtle vignette bands
83
+ for i, a in enumerate((18, 10)):
84
+ d.rounded_rectangle([40 * S + i * 22 * S, 40 * S + i * 22 * S, SPW * S - 40 * S - i * 22 * S, SPH * S - 40 * S - i * 22 * S],
85
+ radius=30 * S, outline=(GOLD[0], GOLD[1], GOLD[2], 0) if False else (46, 66, 68), width=3 * S)
86
+ logo_sq = draw_logo_square(scale=2, size_px=int(SPH * S * 0.78))
87
+ # paste logo at left
88
+ lx, ly = int(SPW * S * 0.06), int((SPH * S - logo_sq.height) // 2)
89
+ sp.alpha_composite(logo_sq, (lx, ly))
90
+ # wordmark
91
+ tx = lx + logo_sq.width + int(SPW * S * 0.055)
92
+ f_title = font(int(SPH * S * 0.17))
93
+ f_tag = font(int(SPH * S * 0.062), bold=False)
94
+ f_url = font(int(SPH * S * 0.042), bold=False)
95
+ d.text((tx, int(SPH * S * 0.24)), "ProofDeck", font=f_title, fill=INK)
96
+ d.text((tx + int(S * 6), int(SPH * S * 0.46)), "Agents claim done.", font=f_tag, fill=INK)
97
+ d.text((tx + int(S * 6), int(SPH * S * 0.545)), "ProofDeck demands proof.", font=f_tag, fill=MINT)
98
+ d.text((tx + int(S * 6), int(SPH * S * 0.72)), "github.com/kumu314/proofdeck", font=f_url, fill=DIM)
99
+ sp = sp.resize((SPW, SPH), Image.LANCZOS).convert("RGB")
100
+ sp.save(os.path.join(ASSETS, "social-preview.png"))
101
+ print("wrote", os.path.join(ASSETS, "logo-512.png"), "and", os.path.join(ASSETS, "social-preview.png"))
@@ -0,0 +1,58 @@
1
+ # Task books — how ProofDeck reads your tasks
2
+
3
+ A ProofDeck task has two halves:
4
+
5
+ 1. **The card** on the board — title + a **pointer** to the task book file.
6
+ 2. **The task book file** (under `briefs/`) — the actual instruction text plus a
7
+ ```bridge fence carrying the dispatch metadata.
8
+
9
+ Why a file? The gating layer evaluates the book's content (risk words, sandbox
10
+ requests, auto flags) before dispatch, and the file is what gets archived with
11
+ the run for audit. Inline descriptions are treated as pointers only.
12
+
13
+ ## Format
14
+
15
+ ```markdown
16
+ <instruction text for the agent>
17
+
18
+ ```bridge
19
+ { "auto": "yes", "risk": "low", "impact": "low" }
20
+ ```
21
+ ```
22
+
23
+ The fence fields:
24
+
25
+ | Field | Meaning |
26
+ |---|---|
27
+ | `auto` | `"yes"` → the gate may dispatch automatically (risk words still apply) |
28
+ | `risk` | `low` / `medium` / `high` / `critical` — must be in `gating.autoRisk` for auto dispatch |
29
+ | `impact` | metadata; `high`/`critical` hits `gating.blockImpact` |
30
+ | `agent` | optional — pin the task to a specific face (otherwise first enabled face / autoAssign) |
31
+ | `priority` | optional — `P0`…`P3` lane priority |
32
+ | `acceptance` | optional — inline acceptance override (otherwise the card's `acceptance` column is used) |
33
+ | `sandbox` | optional — override the face sandbox for this task (`danger` requires approval) |
34
+
35
+ ## Lifecycle
36
+
37
+ 1. `proofdeck init` scaffolds `briefs/` with a starter task book.
38
+ 2. Write the book, then put the pointer on a card:
39
+ `description: "任务书:D:/path/to/briefs/my-task.md"`
40
+ 3. Dispatch it: `proofdeck assign my-task codex` — or just leave it open;
41
+ `autoAssign` (default on) queues auto-flagged books automatically.
42
+ 4. The gate runs: risk words → auto/ask/soft; the face executes; the verify
43
+ engine checks acceptance; the verdict lands in the hash chain.
44
+
45
+ ## Gotchas (dogfood-tested)
46
+
47
+ - **No fence → parked.** A book without a ```bridge fence is parked with
48
+ "未找到可读的任务书文件" — the gate refuses to guess your intent.
49
+ - **Relative `workdir` dies twice.** Face workdirs are resolved against the
50
+ daemon BASE at load; the agent's own `-C` resolves again inside the workdir —
51
+ use absolute paths (init normalizes them for you).
52
+ - **Codex faces need API-key mode for custom providers.** ChatGPT-account auth
53
+ only serves OpenAI models. Give a face its own `CODEX_HOME` with
54
+ `preferred_auth_method = "apikey"` + a DeepSeek/magpie provider to mix
55
+ account-quota and API-quota faces on one machine.
56
+ - **Windows sandbox blocks shell writes by default.** For tasks that must run
57
+ shell commands, set the face `sandbox` accordingly (`workspace-write` allows
58
+ workspace writes; anything broader is gated).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "proofdeck",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Verification-first task board and orchestrator for coding-agent fleets. Agents claim done; ProofDeck demands proof.",
5
5
  "license": "Apache-2.0",
6
6
  "type": "module",