taskboard-workbench 0.0.0-stage → 0.3.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 (75) hide show
  1. package/CHANGELOG.md +403 -0
  2. package/LICENSE +21 -0
  3. package/README.md +210 -2
  4. package/cli/tb.mjs +314 -0
  5. package/cordis.patch.yml +5 -0
  6. package/index.js +633 -0
  7. package/lib/client.js +522 -0
  8. package/package.json +96 -4
  9. package/scripts/tb-flow.mjs +86 -0
  10. package/skills/taskboard-flow/SKILL.md +89 -0
  11. package/skills/taskboard-flow/references/errors.md +61 -0
  12. package/skills/taskboard-flow/references/injection.md +70 -0
  13. package/skills/taskboard-flow/references/steps/S0.md +31 -0
  14. package/skills/taskboard-flow/references/steps/S1.md +28 -0
  15. package/skills/taskboard-flow/references/steps/S2.md +31 -0
  16. package/skills/taskboard-flow/references/steps/S3.md +22 -0
  17. package/skills/taskboard-flow/references/steps/S4.md +25 -0
  18. package/skills/taskboard-flow/references/steps/S5.md +36 -0
  19. package/skills/taskboard-flow/references/steps/S6.md +30 -0
  20. package/skills/taskboard-flow/references/steps/S7.md +23 -0
  21. package/spec/norms/acceptance.md +36 -0
  22. package/spec/norms/card-update.md +39 -0
  23. package/spec/norms/doc-editing.md +30 -0
  24. package/spec/norms/flow.md +45 -0
  25. package/spec/norms/manifest.json +41 -0
  26. package/spec/norms/project-defaults.md +33 -0
  27. package/spec//345/233/242/351/230/237agent.md +171 -0
  28. package/src/core/acceptance.mjs +62 -0
  29. package/src/core/advance.mjs +192 -0
  30. package/src/core/agent-teams.mjs +48 -0
  31. package/src/core/binding.mjs +44 -0
  32. package/src/core/config.mjs +22 -0
  33. package/src/core/contract.mjs +287 -0
  34. package/src/core/debug-dispatch.mjs +94 -0
  35. package/src/core/delivery.mjs +93 -0
  36. package/src/core/deps.mjs +53 -0
  37. package/src/core/diagnostics.mjs +648 -0
  38. package/src/core/domain.mjs +235 -0
  39. package/src/core/empty-state.mjs +240 -0
  40. package/src/core/errors.mjs +142 -0
  41. package/src/core/evidence.mjs +86 -0
  42. package/src/core/executor.mjs +645 -0
  43. package/src/core/human-review.mjs +773 -0
  44. package/src/core/intake.mjs +179 -0
  45. package/src/core/kickoff.mjs +147 -0
  46. package/src/core/loop.mjs +498 -0
  47. package/src/core/memory.mjs +193 -0
  48. package/src/core/next-step.mjs +377 -0
  49. package/src/core/notify.mjs +183 -0
  50. package/src/core/owner.mjs +41 -0
  51. package/src/core/requirements.mjs +292 -0
  52. package/src/core/review.mjs +82 -0
  53. package/src/core/session-naming.mjs +64 -0
  54. package/src/core/split-ask.mjs +107 -0
  55. package/src/core/store.mjs +3442 -0
  56. package/src/core/team.mjs +170 -0
  57. package/src/core/ticket-stage.mjs +150 -0
  58. package/src/core/verify.mjs +170 -0
  59. package/src/core/watchdog.mjs +144 -0
  60. package/src/host/ai-elaborator.mjs +26 -0
  61. package/src/host/team-engine.mjs +125 -0
  62. package/src/host/tool-surface.mjs +205 -0
  63. package/src/mcp/flow-block.mjs +173 -0
  64. package/src/mcp/server.mjs +156 -0
  65. package/src/mcp/tools.mjs +764 -0
  66. package/src/server/api.mjs +2050 -0
  67. package/src/server/events.mjs +32 -0
  68. package/src/server/kickoff.mjs +46 -0
  69. package/src/server/server.mjs +214 -0
  70. package/src/server/verify.mjs +112 -0
  71. package/tools/env-check.mjs +35 -0
  72. package/tools/seed.mjs +67 -0
  73. package/web/app.js +5337 -0
  74. package/web/index.html +15 -0
  75. package/web/tokens.css +1151 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,403 @@
1
+ # Changelog
2
+
3
+ `taskboard-workbench` 的全部对外版本变更记录。
4
+
5
+ 格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/),
6
+ 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
7
+ 每个版本对应一个 annotated tag(`vX.Y.Z`)与一条 GitHub Release;npm dist-tag 与 dsh 兼容区间随版本记录。
8
+
9
+ ## [0.3.0] - 2026-11-03
10
+
11
+ > 主题:让「待验收 → 确认」这段**先变得可信** —— 有度量、有事件、有单一口径、有结构化证据。
12
+ > 本版六张卡全部严格走看板全环(`-193` … `-198`,各带证据四节);`npm test` **974 / 0**、`release-precheck` **EXIT=0**。
13
+ > **未做**:npm publish / GitHub Release(另批);生产重载后的快照复评见 `docs/进度/`。
14
+
15
+ ### 新增
16
+
17
+ - **基线度量脚本 `tools/baseline-metrics.mjs`(卡 `-193` / 需求 `R146`)** —— 把「改善了多少」变成可复跑读数:
18
+ 快照 `.data/backup-20261103.sqlite`(sha256 `21182435…`)、**M1 拆两层**(当前在途滞留中位 **148.4h** vs 已完成周期中位 **19.1h**——
19
+ 只报一个会得出「改善 87%」的假结论)、`done` 事件覆盖 **74.2%**(漏 25.8%)、M2 **3.2**;M3/M4 **明标不可测、不写 0**。
20
+ - **阶段推导单一口径 `ticketStage()`(卡 `-196` / `-198` / 需求 `R149`)** —— 新模块 `src/core/ticket-stage.mjs`:
21
+ **不写第五套判断**,直接复用 `deriveNextStep` / `assessTask` / `latestAutoReview` / `evidenceFormatOk` 只做归一;
22
+ 显式区分 `format_ok`(四字段齐、无内容判定)与 `ready`(判定与证据/版本一致),判过又变 ⇒ `stale`。
23
+ `GET /api/tasks/:ref` 新增只读字段 `ticketStage`;任务抽屉显示交付阶段徽标,**`stale` 用警示色**。
24
+ **安全优先级**:`stale` 先于「只差你点完成」——判定过期时不许邀请人确认他没看过的那一版。
25
+ - **交付物证据结构化 + 授权快照(卡 `-197` / 需求 `R150`)** —— `task_evidence`(四字段:判定 / 偏离 / 边界 / 产物 + `artifact_refs` + actor + task_version)
26
+ 与 `task_mandates`(**append-only**:只有 insert,范围变大 = 新行)。**门在事务前**:四字段缺一即 `EVIDENCE_INCOMPLETE` 且零落库;
27
+ `artifact_refs` 一条解不开即整体 `unresolved`,不进 `format_ok`。授权快照覆盖**三条认领入口**
28
+ (`claimTask` / 看板 `PATCH→in_progress` / 团队通道 `teamSetTaskStatus→in_progress`)。
29
+
30
+ ### 修复
31
+
32
+ - **状态事件漏记(卡 `-194` / 需求 `R147`)** —— `teamSetTaskStatus` 与 `applyTeamTaskOutcome`(completed / failed)此前**直接写列不发事件**,
33
+ 实测 175 次完成类变更中 **46 次(26%)无 `status_changed`**;而诊断 / 看护 / 通知 / M1 度量**全部**建在事件流上。
34
+ 现两处落点补齐(同一状态重复写不产生假事件)。
35
+ - **待验收「发起评审」时间缺失(卡 `-195` / 需求 `R148`)** —— 实测 16 张 `in_review` 中 **10 张 `review_requested_at` 为空**,
36
+ M1 因此无从计算。现三条进 `in_review` 的路径(看板 PATCH / 执行侧与团队通道 / 团队回流)都补记,**幂等**(不覆盖首值)、
37
+ **不涨 version**(记账字段不污染乐观锁)。
38
+
39
+ ### 兼容性与升级注意
40
+
41
+ - **`schemaVersion` 12 → 13**:新增 `task_evidence` / `task_mandates` 两表,`create table if not exists` **可重入**;
42
+ 已在真实库副本上验证(连开两次 `schema=13`、217 条任务不变、无报错)。重启宿主即自动迁移。
43
+ - **`review_requested_at` 只对新增生效**:存量 10 张 `in_review` 空值**不自动回填**(属 P0①-b,需人工执行补发)。
44
+ - **`ticketStage` 是新增只读字段**:既有 `task` / `comments` / `reviewEvidence` 语义未变;详情 GET **零写副作用**(新增测试断言)。
45
+ - **`ready` / `stale` 两态暂不可达**:判定层(`decision_log`)属 0-C,未建表前 `decision` 显式 `null`,不伪造判定。
46
+ - 任务抽屉的「下一步 / 看护 / 诊断」三处旧判断**本版未合并**(沙箱内无浏览器验证台,盲删即静默删功能)⇒ 见 `R151`。
47
+
48
+ ## [0.2.3] - 2026-10-30
49
+
50
+ > 本版只有一条修复:**把「只影响人读」的错标改对**(数据一直是对的)。
51
+ > 触发:`-176` 证据评论登记的已知限制 —— `REQUIREMENT_SOURCES` 已含 `mcp`,但前端来源文案只认
52
+ > `intake / elaborated-ai / elaborated-rule`,其余一律回落「手工」。
53
+
54
+ ### 修复
55
+
56
+ - **需求条目来源标签:`mcp` 被错标为「手工」(卡 `-179` / 需求 `R134`)** ——
57
+ MCP 建的条目在**列表胶囊**与**详情「来源」字段**都显示成「手工」,人会以为是自己手工建的,
58
+ 进而误判「谁该补验收」。数据侧(`source="mcp"`)自 0.2.2 起就是对的,**只有人读的那一层在撒谎**。
59
+ 修:`web/app.js` 两处来源文案三元各补 `mcp → "MCP"` 分支(列表 `srcLabel` / 详情 `srcLabel`),
60
+ 其余四档文案(资料索引 / AI / 规则 / 兜底手工)**零改动**。
61
+ **守卫**:新增真渲染验证台 `tools/bench-req-source-label.mjs`(临时 `dataDir` + 随机端口 + 真 headless Chrome + CDP,
62
+ 读渲染后 DOM 的**列表胶囊**与**详情字段**实际文本,A/B/C/D 四条 + `TB_BENCH_WEB_DIR` 反向对照);
63
+ 配套 `tests/bench-req-source-label-coverage.test.mjs`(5 条)进 `npm test`:含**源码守卫**(两处三元都必须有 `mcp` 分支、
64
+ 兜底档必须仍是「手工」)+ 台子不被削薄(隔离形态 / 沙箱自检 / 五档种子 / 反向对照入口 / 退出码契约)。
65
+ **读数**:修复前 A/B 双红(`mcp=手工`、详情`手工`)→ 修复后 **4/4 PASS**(`mcp=MCP`,intake 详情仍「资料索引(引入)」);
66
+ 反向对照(注入旧口径)**2/4**(A/B 转红);源码守卫同样反向验证(删掉 `mcp` 分支 ⇒ 断言失败)。
67
+
68
+ ## [0.2.2] - 2026-10-29
69
+
70
+ > 本版是 **0.2.1 之后的第一个小版本**(未发布 npm / 未出 Release 时为「就绪」状态)。
71
+ > 主题:**把 0.2.1 收口时登记的四张隔离卡清掉**(软链漏扫 / 去重键陈旧 / 两条无约束写入口)。
72
+
73
+ ### 修复
74
+
75
+ - **intake 扫描器的符号链接静默漏扫(卡 `-175`)** —— `Dirent.isFile()` 对符号链接**恒为 false**,
76
+ 故 `walk()` 的 `isFile()/isDirectory()` 双分支把软链文档静默漏掉(本仓 `docs/团队agent.md → ../spec/团队agent.md`
77
+ 从未进索引,`docsTotal` 少 1 且无任何读数提示)。
78
+ 修:软链走 `stat` 跟随判类型 → `realpath` **越界判定**(必须仍在 root 内)→ **祖先链**环路保护;
79
+ 跳过的每一条进 `symlinks.skipped[{relPath,target,reason}]`(九种 reason),跟随的计入 `followed`,`files[]` 带 `symlink:true`。
80
+ 顺带删掉 `tools/audit-intake.mjs` 自带的 `findSymlinks()`(两份实现必然漂移,改读模块记账)。
81
+ **读数更正**:软链修完后 `docsTotal` 是 **391**(不是先前预估的 390)—— 用同版本差集实测钉住:
82
+ HEAD `390` ↔ 新版 `391`、`added=[docs/团队agent.md]`、`removed=[]`;口径漂移的原因是「390」按当时 2 份新文档算的,
83
+ 此后又落了 1 份进度文档。**登记到 0.2.2 发布时,基线应再按当次 docs 数量复算**(本轮收尾时为 392,因又新增 1 份轮次文档)。
84
+ - **改条目标题时 `norm_title` 不同步(卡 `-178`)** —— 标题去重键停在旧值 ⇒ 改名后
85
+ `confirmRequirementCandidates` 把同一条目当「新条目」再插一次。存量 `normTitleMismatch = 0`,属**防新增**。
86
+
87
+ ### 新增
88
+
89
+ - **acceptance 显式缺口标记(卡 `-176` / `-177` · 口径 X)** —— 两条无约束写入口(MCP `requirement_upsert` 与
90
+ HTTP `POST/PATCH /api/requirements/items`)此前「没给验收」与「给了空串」在调用方眼里都是成功。
91
+ 现:`acceptanceSet` 回包字段 **永远**反映写入后状态;缺省时落 `governance_audit`
92
+ (`action = requirement-acceptance-missing`,`reason` 记入口名)⇒「当初给没给验收」可事后 join 审计查出来。
93
+ **刻意不做**:不设必填、不改 schema(129 条里 99 条 `acceptance` 为空,必填会一刀切破「改标题」这类无关操作;
94
+ 审计 join 可查,schema 迁移不可逆)。审计只在**本次写入真碰 `acceptance`** 时落,避免每次改标题都添一行。
95
+ - **`REQUIREMENT_SOURCES` 补 `mcp`** —— MCP 建的条目不再落默认 `manual`,「人手建 / MCP 建」在库里可辨。
96
+
97
+ ### 已知限制(本版未做)
98
+
99
+ - 前端来源标签仍无 `mcp` 分支 ⇒ 列表里 MCP 建的条目会显示成「手工」(**数据正确、标签错标**,2 行改动,待 UI 卡)。
100
+ - MCP 回包不暴露 `source`(`requirementSnapshot` 只回内容字段)。
101
+
102
+ ## [0.2.1] - 2026-10-29
103
+
104
+ > 发版纪律(2026-10-29 起):`0.2.0` 已对外冻结,**此后任何产品代码改动都要走新版本号 + 本文件**,
105
+ > 不得静默混进工作区(否则「registry 上的 0.2.0」与工作区语义漂移)。
106
+ > 发布时把本节改成 `## [0.2.1] - <日期>` 并复查 `docs/发布与收录/02` §5.0 的顺序铁律。
107
+
108
+ ### 变更(口径)
109
+
110
+ - **条目化的失败语义与数量口径(卡 `-169` P4②)** —— 真机上一份「资料索引」类文档走规则拆解,
111
+ 产出 **4213 条**、落库 **100 条** `pending` 候选,其中 **0 条**是真需求(全是文件清单行)。
112
+ 两条根因一起改掉:
113
+
114
+ | 项 | 旧 | 新 |
115
+ | --- | --- | --- |
116
+ | `mode:"auto"` 在 AI 不可用时 | **静默跑规则并落库**,只加 `degraded:true` 标注 | **拒绝 `AI_UNAVAILABLE`、零落库**;要降级必须**显式** `{"mode":"auto","fallback":"rule"}` |
117
+ | `limit` | 默认 **100**,且 **body 传了也不生效** | **从 body 透传**,默认 **20**、硬顶 **200** |
118
+ | `mode:"rule"` | 一点就写,无预览 | 支持 `{"mode":"rule","dryRun":true}` ⇒ **只回预览、零落库**(HTTP 200) |
119
+
120
+ ⚠️ **这是有意的收紧**:宿主没配 LLM 之前,看板的「AI 拆解」会**明确报错**而不是"假装成功"。
121
+ 这正是要的 —— 把「其实没 AI」从「看起来成功」改成「明确失败」。
122
+
123
+ ### 新增
124
+
125
+ - **验证台 `tools/bench-market-install.mjs`(第 14 台,11 项)—— 市场安装形态验收**:
126
+ `npm pack` → 解包 → 装进**隔离 profile**(临时 `DSH_HOME`)→ 真 `dsh` 起宿主 → 真 HTTP。
127
+ 判据是「**插件化 = 拿到宿主会话通道**」:`host.capabilities` 非空 + `create/sessions` 在 +
128
+ **真建出项目主会话** + `scopeFactory=ready`;**反向对照**=同一份打包代码 `node src/server/server.mjs`
129
+ 独立起 ⇒ `capabilities === null`。它补的盲区:以往「插件能用」的证据全来自**仓库软链**,
130
+ `package.json#files[]` 少写一项也照样绿,而市场安装拿的是打包产物。
131
+ - **独立进程启动即声明形态**:`src/server/server.mjs` 多打一行
132
+ `[tb] mode=standalone · 无 DSH 宿主会话通道(投递/建会话/派发团队不可用;需要这些能力请用 DSH 内的 /integrations/taskboard-workbench)`,
133
+ 把「为什么按钮是灰的」提前到启动那一刻。
134
+
135
+ - **规则拆解「先预览再确认」**(前端):「规则拆解(先预览)」→ 页面内预览块(写多少条 / 前 10 条标题 /
136
+ 「规则拆解会把文件清单行也当需求」警示)→「确认写入 / 取消」。
137
+ **不用 `window.confirm`**:IAB 里原生弹窗会被自动拒绝 ⇒ 变成「点了没反应」(见 `docs/发布与收录/06` §E3)。
138
+ - **验证台 `tools/bench-elaborate-guard.mjs`**(第 13 台)—— 真 headless Chrome 读渲染后 DOM,**10 项**:
139
+ 两个按钮在 / 无 AI 点 AI 拆解⇒明确报错且零落库 / 点预览⇒预览块出现且零落库 / 真列 10 条 /
140
+ 「确认写入 20 条」/ 确认后落库 **20** 条 / 页面回报 `候选=20` / 预览块消失。
141
+ 含 `TB_BENCH_WEB_DIR` 反证入口(旧 web ⇒ **7/10 转红**)。
142
+ - **守卫测试 `tests/elaborate-guard.test.mjs`**(11 条):① 零落库 ② 显式 `fallback:"rule"` 才降级
143
+ ③ `dryRun` 零落库且 `preview` 非空 ④ `limit:5` 恰好 5 条 · 默认 20 · 硬顶 200 · 非法值报错
144
+ ⑤ `dryRun` 只对 `rule`、`fallback` 只接受 `rule`、`mode` 只接受三值 ⑥ 反向对照。
145
+
146
+ ### 变更(实现细节)
147
+
148
+ - AI 抛出的错误**保留上游 `code`**(如 `AI_OUTPUT_INVALID`)而不是一律压成 `AI_UNAVAILABLE` ——
149
+ 排障要能区分「没有 AI」和「AI 回了没法解析的东西」。
150
+ - `clampElaborateLimit` 放在 `src/core/requirements.mjs`(纯模块),`store.mjs` 转发 ——
151
+ 这样 `src/server/api.mjs` 取口径时不会把 `node:sqlite` 拽进纯路由层。
152
+
153
+ ### 新增(P1 · 契约快照与机器规范 · 卡 `-170`)
154
+
155
+ - **机器执行规范 `spec/norms/`(运行时唯一真源,随包分发)** —— 五份:
156
+ `flow`(八步 S0–S7 + 四道门 + 错误码处置)/ `card-update`(状态流转 + 回填证据 + 禁止项)/
157
+ `doc-editing`(每轮收尾 + 写入纪律 + 命名)/ `acceptance`(三层判据 + 反向对照 + 合格证据)/
158
+ `project-defaults`(只允许 3 类覆盖:`verifyCommand` / `workspacePath` / `notApplicable`)。
159
+ 每份带 `norm_id / version / updated / applies_to` frontmatter,`manifest.json` 记 `digest = sha256(正文)`。
160
+ `docs/规范/*.md` 仍是**给人读的开发文档**、永不入 git、**不作运行时真源**。
161
+ - **契约快照 `src/core/contract.mjs`(纯计算 + 纯读文件,不写库)** ——
162
+ `contract_version = f(需求文档 digest, 规范 digest×版本, 门配置)`;`diffContract` 能回答「**哪份文件变了**」
163
+ (`changed[]` 指到 `spec/norms/card-update.md` 这一级);`staleError` 固定 `409 CONTRACT_STALE` 形状:
164
+ `your_version` / `current_version` / `changed` / `snapshot` / `remedy`。
165
+ - **两个端点** —— `GET /api/projects/:id/contract`(**零副作用**:现算 + 与基线比对,不落库)·
166
+ `POST /api/projects/:id/contract/recheck`(重算并落基线,`project_contract` 的唯一写入点)。
167
+ - **构建工具 `tools/build-norms.mjs`** —— 生成 manifest;`--check` 供 CI / 守卫。**正文变了但 `version`
168
+ 没 bump ⇒ 硬拒写入(退出码 1,不覆盖 manifest)** —— 否则等于用 manifest 把守卫抹平。
169
+ - **两张表(schema `11 → 12`)** —— `project_contract`(每项目一行契约基线,**只是缓存不是真源**)·
170
+ `flow_injections`(装载块注入审计位;D3 档 C 推迟,默认 `off` 不写)。
171
+
172
+ ### 新增(P1.5 · D2 `warn` 档 · 2026-10-29)
173
+
174
+ - **写路径上的契约校验(内核层,不阻断)** —— `evaluateSubmittedContract()` 纯判据 +
175
+ `store` 在 `createTask` / `updateTask` / `addComment` / `createRequirementItem` / `updateRequirementItem`
176
+ 五条写路径上校验调用方带的 `contract`:
177
+ - **不带** `contract` ⇒ `skipped`(老客户端 / Web 零打扰,向后兼容);
178
+ - 版本或规范摘要不符 ⇒ **照常写入**,另落一条 `contract-warn` 审计
179
+ (`GET /api/governance/audit?action=contract-warn` 可查「谁在用旧规范干活」);
180
+ - 全符 ⇒ `ok`,**不制造审计噪声**。
181
+ - 为什么放内核:MCP / HTTP / CLI / Web / dsh-tool 五个入口都落到 `store`;放门面层就会
182
+ 「六个入口两种语义」(D2 拍板 B)。门面只做一件事:把 `body.contract` 原样透传。
183
+ - 测试 `tests/contract-warn.test.mjs` **4 条**:纯判据 / warn 不阻断且真落库 / 更新+评论两条路径同样受检 /
184
+ HTTP 透传 + 审计可查。
185
+
186
+ > **已知限制(P1.5 边界)**:目前是 **`warn` 档**(D2 拍板:先观测一周再切 `reject`)。
187
+ > 也就是说「用旧规范干活」现在**只留痕、不失败**;`409 CONTRACT_STALE` 的阻断要等切档时才生效。
188
+ > 另外 `project_contract` 目前只在手动 `recheck` 时落基线,需求文档变更时**不会自动 refresh**(随切档一起定)。
189
+
190
+ ### 新增(P2 · MCP 只读四工具 · 卡 `-170` · 2026-10-29)
191
+
192
+ - **MCP 契约层 `src/mcp/`(stdio,零依赖,零宿主改动)** —— `server.mjs` 是 newline-delimited
193
+ JSON-RPC 2.0 的 MCP server(`initialize` / `notifications/*` / `ping` / `tools/list` / `tools/call`),
194
+ `tools.mjs` 注册四个**只读**工具:
195
+ `flow_start`(开局 S0:项目 + `contract_version` + 三类缺口 + 下一步建议)·
196
+ `project_info`(按状态计数 + 契约是否漂移)·
197
+ `norm_get`(`spec/norms/*` 正文 + `sha256` digest;`norm="project"` 读 `<workspace>/AGENTS.md`)·
198
+ `workbench_audit`(`contract-stale` / `unattributed` / `unbound-session` / `candidate-flood` 四类漂移)。
199
+ - **三条实现口径**:① **stdio 而不是 HTTP** —— 不占端口、不碰 `:3080`、不写 `~/.dsh/**`、不需要重载宿主,
200
+ 每个 agent 会话一个进程;② **同一份 `taskboard.sqlite`**(`--data-dir` > `$TB_DATA_DIR` > 默认),
201
+ MCP 不是第二份数据;③ **只读到「连计数都不变」** —— 不调任何 `create/update/record*`,
202
+ 也不走 `resolveContext()`(它会 `ensureRequirementDoc`,属写操作)。
203
+ - **错误分层**:**协议层**用 JSON-RPC error(未知工具 ⇒ `-32602`),**工具层**用 `result.isError` +
204
+ `{code,message}`(如 `NORM_NOT_FOUND`)—— 混用的后果是客户端把「参数写错」当成「服务挂了」。
205
+ - **入口**:`node src/mcp/server.mjs --data-dir <dir>` · `npm run mcp` · `bin: tb-mcp` · `--print-tools`(清单自检)。
206
+ - 守卫测试 `tests/mcp-readonly.test.mjs` **A–H 八组**:握手 / 四工具且全 `readOnlyHint` / `flow_start` 缺口与
207
+ `nextStep` / `project_info` 计数 / `norm_get` 正文+digest+项目档+未知码 / `workbench_audit` 四类齐 /
208
+ **只读**(跑完一轮后 `projects/tasks/comments/ownedTasks/audit` 逐项不变)/ 协议层 `-32602`。
209
+
210
+ > **边界**:写工具(`card_create` / `card_progress` / `requirement_upsert` / `requirement_change`)属 **P3**,
211
+ > 本轮**不含**。也就是说 MCP 现在只能「读事实、报漂移」,**不能替人建卡或改状态**。
212
+
213
+ ### 新增(P3 · MCP 写四工具 + 条目列表 + `mcp-parity` · 卡 `-170` · 2026-10-29)
214
+
215
+ - **五个新工具(MCP 共 9 个)**:
216
+ `requirement_list`(只读:条目 + 内容版本 + 每条卡数)·
217
+ `requirement_upsert`(新建 / 改条目,改必带 `expected_version`)·
218
+ `requirement_change`(**先预览拿 `change_id` + 影响面**,带 `change_id` + `apply:true` 才落地)·
219
+ `card_create`(**归因硬门** + `unattributed_reason` 逃生口)·
220
+ `card_progress`(**`evidence[]` 非空** + **`norm_digest` 必填**)。
221
+ - **形状即约束(这次的四个「不可能」)**:
222
+ | 老毛病 | 现在怎么被挡住 |
223
+ | --- | --- |
224
+ | 建卡忘了归因 | `card_create` 无 `requirement` 且无 `unattributed_reason` ⇒ `REQUIREMENT_REQUIRED`(逃生口落 `attribution_skipped` 事件,可盘点) |
225
+ | 回填写「已完成」三个字 | `evidence[]` 非空且每项 `{kind∈file\|command\|url\|reading, ref}`;空 / 形状错 ⇒ `EVIDENCE_REQUIRED` / `EVIDENCE_INVALID` |
226
+ | 拿旧规范回填 | `norm_digest` 必填,与当前 `card-update` 不符 ⇒ `NORM_STALE`(**回带最新正文**,agent 自纠偏) |
227
+ | 改了需求忘了下游 | `requirement_change` 先回 `affected_cards` + `change_id`;条目预览后被改过 ⇒ `CHANGE_ID_MISMATCH` |
228
+ - **四条红线由门守,不由纪律守**:`done` 走执行侧状态门 ⇒ `GOVERNANCE_AGENT_DONE`;`card_create` 只接受
229
+ `backlog`(`backlog → todo` 是人工授权)⇒ `AUTHORIZATION_REQUIRED`;人工校验任务不得被执行侧改状态;
230
+ 同批证据按 `hash` 去重(重复回填不产生第二条评论)。
231
+ - **无状态 `change_id`**:`sha256(条目 + 改前内容版本 + 排序后的补丁)` —— 不建表、不存会话,
232
+ 条目一变 id 自动失效(比「存一张审批表」更难被绕过)。
233
+ - **`mcp-parity` 守卫 `tests/mcp-parity.test.mjs`(4 条)**:同一操作在 **HTTP 与 MCP** 上
234
+ 错误码必须相同(`REQUIREMENT_REQUIRED` / `DEPENDENCY_CROSS_PROJECT` / `GOVERNANCE_AGENT_DONE`),
235
+ 且**副作用同形**(状态 / 优先级 / 验收 / 复核动作 / 归属条目 / 事件序列 `created + attributed` 逐项相等)。
236
+ - 守卫 `tests/mcp-write.test.mjs`(**6 条** A–F):条目版本乐观锁 · 变更影响面门 · 归因/授权门 ·
237
+ 证据与 `norm_digest` 门 · `done` 红线 · **契约仍 `warn` 档**(带旧契约写入成功 + 只留 `contract-warn`)。
238
+
239
+ > **口径边界(有意为之)**:① `card_create` 的归因硬门只收紧 **MCP 这一个新入口**;内核全局档
240
+ > `TB_STRICT_ATTRIBUTION` 仍是默认 `warn`(翻默认会影响 Web / CLI / seed 全部存量调用方,属另一件事,须单独拍板)。
241
+ > ② `contract_version` 仍是 **`warn`** 档(D2 观察期内);写工具返回体带 `contract.verdict`,让 agent 自己知道用了旧规范。
242
+ > ③ `requirement_upsert` 的 `expected_version` 是**内容摘要**(`requirement_items` 没有 version 列),纯读、可重算。
243
+
244
+ ### 新增(P4 · `taskboard-flow` 技能包 + 开局档 A/B · 卡 `-170` · 2026-10-29)
245
+
246
+ - **技能包 `skills/taskboard-flow/`(随包分发,`npm run flow` 即用)** —— `SKILL.md` 是
247
+ **八步 × 六栏**的主流程表(入口 / 前置门 / 判据 / 证据落点 / 失败处置 / 对应 FR),
248
+ 外加「随时可用的两个只读入口」与**五条硬规则**;`references/steps/S0.md … S7.md` 给每步的命令与判据读数,
249
+ `references/errors.md` 是错误码 → 该做什么,`references/injection.md` 是装载细节与档 C 的接口形状。
250
+ **这一层只教顺序、判据与失败处置,不持有任何业务规则副本** —— 数据在 `taskboard.sqlite`,
251
+ 门在 `src/mcp/` 与 `src/core/`,规范在 `spec/norms/`。
252
+ - **装载块唯一生成器 `src/mcp/flow-block.mjs`** —— `readSkill()` / `buildFlowBlock()` / `buildAgentsSnippet()`。
253
+ 八步与硬规则**从 `SKILL.md` 的两个标记区间原样抽取**(`<!-- flow-block:steps -->` / `<!-- flow-block:rules -->`),
254
+ 不复制正文 ⇒ 「技能改了、装载块没跟上」这一类漂移在结构上不存在。
255
+ - **开局档 A(人贴)/ 档 B(外部 agent 约定)**:
256
+ - 档 A:`node scripts/tb-flow.mjs start` 的输出整块贴进 dsh 主会话;或让 MCP 客户端取 prompt **`taskboard.flow`**
257
+ —— **同一生成器、输出逐字节相同**;
258
+ - 档 B:项目根 `AGENTS.md` 写一段「开工先跑 `<taskboard>/scripts/tb-flow.mjs start`」,片段由
259
+ `tb-flow snippet` 打印(`--write` 只打印待粘贴内容,**不替人改文件**)。
260
+ - **MCP `prompts` 能力** —— `initialize` 声明 `prompts:{listChanged:false}`,新增 `prompts/list` 与
261
+ `prompts/get`(只认 `taskboard.flow`,未知名字 ⇒ **协议层 `-32602`**);启动日志带 `prompt=taskboard.flow skill=v1`。
262
+ - **CLI `scripts/tb-flow.mjs`(`bin: tb-flow` · `npm run flow`)** ——
263
+ `start [--project --cwd --json --data-dir]`(缺项目时按 `--cwd` / `basename` 猜,猜不到给 `PROJECT_NOT_FOUND` 并
264
+ 打印「怎么指定 `--data-dir`」)· `snippet`(打印档 B 的 `AGENTS.md` 片段)· `check`(自检 frontmatter 与八步完整性)。
265
+ `package.json#files[]` 增加 `skills/` 与 `scripts/tb-flow.mjs` —— 市场安装拿的是打包产物,少写一项就静默缺件。
266
+ - **`deriveFlowNext` / `projectGaps` / `resolveProject` 从 `tools.mjs` 导出**(`export`)—— 让 `flow-block.mjs`
267
+ 复用同一份「下一步」判据,而不是第二份实现。
268
+ - 守卫 `tests/skill-flow.test.mjs`(**6 条** A–F):frontmatter 五项齐全 · 八步连续且每格非空(六栏表头)·
269
+ **双向工具覆盖**(表里提到的工具都在注册表里,注册表里 9 个工具都必须在技能目录被提到)·
270
+ `requires_contract` 与 `CONTRACT_VERSION_PREFIX` 同源 · **档 A/B 同源**(进程内生成 ≡ MCP `prompts/get` ≡ CLI `start`,
271
+ 逐字节)· 真跑 S0→S2(无条目 ⇒ S1;建条目 ⇒ 建卡 ⇒ `nextStep.step === "S3"` 且 `humanAction === "authorize"`)。
272
+
273
+ > **口径边界(有意为之)**:① **档 C(宿主会话创建自动注入)未启用** —— D3 已拍板推迟到「工作台整体封装为插件包」
274
+ > 阶段,本轮只预埋接口(`flow_inject_policy` 配置位默认 `off`、`flow_injections` 审计表、`references/injection.md`),
275
+ > **没有任何代码读这个配置位去注入**;真要接必须先报批改 `~/.dsh/**` 并重载宿主。
276
+ > ② 技能**不进 `docs/规范/`**:后者是本仓库的开发文档、永不入 git,不是运行时真源。
277
+ > ③ 卡 `-170` 仍停在 `in_progress` —— P5 未定,不推 `in_review`。
278
+
279
+
280
+ ## [0.2.0] - 2026-10-29
281
+
282
+ > **本版是首个发布到 npm 的版本** —— `0.1.0` 只出过 GitHub Release 源码快照,未进 registry。
283
+ > 覆盖 2026-10-23 → 2026-10-29 的全部工作(需求正本 `FR-01…FR-100`,实现缺口 0)。
284
+
285
+ ### 新增
286
+
287
+ - **项目推进清单与决策回写(`FR-99`)** —— `GET /api/projects/:id/advance` 把五类待办
288
+ (`decide` / `blocked` / `review` / `accept` / `dispatch`)按「先解锁再推进」合一排序,每条带一句 `why` 与稳定
289
+ `decision_id`;清单是**纯投影**(同状态重复请求字节级一致,`done`/`canceled` 不出现);`?format=block` 产出
290
+ 可直接投给项目主会话的指令装载块,`POST …/advance/announce` 投放,`POST …/advance/:decisionId/decide` **幂等**回写。
291
+ - **项目记忆与多 agent 执行记忆归档(`FR-100`)** —— 三张记忆表 + 五个端点:按项目 / 会话 / agent 归档执行记忆,
292
+ 支持检索、合成装载与清理。
293
+ - **需求分拆「自动生成 + 按意见重生成」** —— `POST /api/requirements/items/:ref/split-ask` 走项目主会话,
294
+ **只投一条指令、零建卡零改状态**(因此可安全反复点);带修改意见时自动回带上一次草稿。
295
+ 生成的卡支持 `kind`(`work` / `review`,未知值报错而非静默丢弃)与**依赖边**(`序号|标题|owner|kind|依赖`)。
296
+ - **评审门** —— `in_review → done` 必须 `review_state === 'approved'`,否则 `REVIEW_NOT_APPROVED`(退出码 5;
297
+ 门在写之前 ⇒ 零副作用)。人仍可跳过评审,但须显式 `skipReview === true`(严格布尔),服务端落
298
+ `review_skipped` 事件与审计。
299
+ - **宿主能力位与能力门** —— `GET /api/health` 的 `host` 块补齐 8 个能力位(`createSession` / `sendPrompt` /
300
+ `openSession` / `listSessions` / `sessionExists` / `sessionOrigin` / `renameSession` / `sessionState`);
301
+ 前端按能力位置灰宿主依赖按钮并给常驻说明,**能力未知时不擅自禁用**;`host-unavailable` 的错误**同时回带
302
+ `prompt`**,可手工投递。
303
+ - **需求条目「任务 DAG」** —— 稳定拓扑序(Kahn,同层按创建序)+ 每节点 `blockedBy[]` + 依赖边 `reason`
304
+ (为什么卡)+ 节点可点直达该卡(按编号回源 `GET /api/tasks/:ref`,不再"列表里没有就归档了")。
305
+ - **需求条目详情抽屉** —— 按视口分级宽度 + 左缘拖拽 + 一键全屏,独立记忆键 `tb.reqDrawer.width`
306
+ (不与被任务侧共用的 `tb.drawer.width` 串扰),拖动中不落盘、松手才写。
307
+ - **需求条目列表** —— 完成度结论列(`无任务` / `可收口` / `待验收 N` / `受阻 N` / `N/M 收口` 五档,定宽对齐)+
308
+ 面板头「可收口 N」+ 点胶囊真滚到详情「关联任务完成情况」段 + 终态显式化(划掉 + 色条 + 降透明)。
309
+ - **自动复核第三态「不适用」** —— 非 Node 工作区不再把「命令不适用」谎报成「失败」(`applicable:false`,
310
+ 不跑命令、不改状态)。
311
+ - **发布门禁** —— `node tools/release-precheck.mjs`:tracked tree + `HEAD` 全历史的 L1/L2 敏感信息扫描、
312
+ `npm pack` 内容边界、`docs/`/`.archify/`/`.data/`/`AGENTS.md` 的 ignore 覆盖;配套 `SECURITY.md` 分级口径。
313
+ - **13 个隔离验证台**(`tools/bench-*.mjs`)—— 临时 `dataDir` + 随机端口 + 独立进程,跑真 headless Chrome /
314
+ 真 `dsh` / 真 `claude` 取证,**每个都带反向对照**(注入旧口径必须转红)。
315
+
316
+ ### 变更
317
+
318
+ - **建卡归因并入建卡事务** —— `createTask` 在同一事务内校验 `requirementId`,跨项目/条目不存在 ⇒ **整笔回滚、
319
+ 不占编号**;`POST /api/tasks` 读 `requirementId`;CLI 增 `task create --requirement` 与 `task attribution`。
320
+ 默认**软提醒**,`TB_STRICT_ATTRIBUTION=1` 才升级为硬门。归因门(`EXECUTION_NOT_ATTRIBUTED`)保持不变。
321
+ - **需求视图「引入的文件」按文件夹呈现**(`FR-96`)—— 单链合并、目录排在根级文件之前、叶子 `title` 不丢、
322
+ 默认折叠。
323
+ - **待验收卡处置入口收敛**(`FR-89`)—— 已通过卡只保留「完成」一处,操作区不再出现裸「下一列」,
324
+ 改为「指回下一步」;进行中卡仍保留普通「下一列」(反向对照守住)。
325
+ - **`web/app.js` 支持两种宿主形态** —— 宿主能力未知 / 宿主不可用都按「能力位 + 常驻提示」呈现,
326
+ 不再把**能力缺失**呈现为**临时故障**(旧文案「检查宿主会话通道后重试」会让人无限重试一个永不成立的条件)。
327
+
328
+ ### 修复
329
+
330
+ - **断线无提示、重连后不重取**(`FR-20`)—— WebSocket 断开给常驻提示并按 `readyState` 分流,
331
+ 重连成功后复用 `reload()` 重新取数(验证台 11/11,含反向对照)。
332
+ - **「申报人工校验」点了没反应** —— 抽屉内提示被 `.banner` 遮挡(z-index 40 → 60)。
333
+ - **需求条目详情「太过靠右」** —— `.tb-req-drawer` 死钉 `min(560px, …)`,与 `.tb-drawer` **特异性相同又排在
334
+ 后面** ⇒ 盖掉按视口分级与拖拽/全屏(同一个抽屉壳:任务侧有能力、需求侧被一行旧 CSS 钉死)。
335
+ - **建卡可绕过归因** —— Web / CLI / 工具面三个入口原先都拿不到 `requirementId` ⇒ 派生出无归因卡,
336
+ 启动执行与派发团队时被 `EXECUTION_NOT_ATTRIBUTED` 拒。
337
+ - **CLI 失败被记成「成功」的相邻问题** —— 失败记账与分类重做:配额/鉴权类(不重试,置受阻 + 审计)与
338
+ 瞬时故障(按阈值重试)分流。
339
+ - **需求分拆的两处「界面承诺 ≠ 实现」** —— `kind` 被 `assertSplitTasks` 静默丢弃;按钮写「+ 依赖」而 UI
340
+ 根本没有依赖输入(一条边都建不出来)。
341
+ - **DAG 节点点不开** —— 纯展示 `div` 改可点 `button`,并修掉「列表里查不到就提示可能已归档」的死路。
342
+ - **`node --test` 临时目录泄漏** —— 跑完残留临时目录。
343
+ - **优雅重启永远不退出(留孤儿)** —— `server.close(cb)` 只停止接受新连接、要等既有连接全部结束才回调;
344
+ 而前端常开 `new EventSource('/api/events')`(SSE 长连接),**回调永不触发** ⇒ SIGTERM 之后进程挂着不退、
345
+ 继续持有 `.data/taskboard.sqlite`,下一个实例起来就形成**同库双写者**,再下次重启还要撞 `EADDRINUSE`。
346
+ 修:`server.closeAllConnections?.()` 强制断开 SSE / keep-alive + **3 s 兜底 `process.exit(0)`**;
347
+ 守卫 `tests/server-graceful-shutdown.test.mjs`(3 条:挂 SSE 必须秒退 / 无连接也要退 / 源码双要素)。
348
+
349
+ ### 测试
350
+
351
+ - `npm test`(`node --test`)**853 / 853 · 0 fail · 0 skipped**(`0.1.0` 时为 678)。
352
+ - 13 个浏览器 / 真进程验证台全部带**反向对照**,且全部在 `npm test` 内(不是游离脚本)。
353
+
354
+ ### 已知限制
355
+
356
+ - 执行侧外部 CLI(如 `claude`)**没有强制的文件写入边界**:`--add-dir` 只表达授权目录,**不阻止越界写**,
357
+ 且 `--allowedTools` 含 `Bash` ⇒ shell 重定向不受目录模型约束。该约束是**指令级**的
358
+ (实证:`tools/bench-cli-write-boundary.mjs`)。
359
+ - **独立进程形态**(`node src/server/server.mjs` 直起、非 DSH 插件)**天生没有宿主会话通道**,
360
+ `/api/health` 的 `host.capabilities` 为 `null`。此时宿主依赖动作按能力位置灰并给出说明,
361
+ `host-unavailable` 会回带 `prompt` 供手工投递。这属**形态差异**,不是缺陷。
362
+ - `docs/` 过程文档不随仓库与包发布,只在本地维护。
363
+
364
+ ### 口径裁定
365
+
366
+ - **`FR-52` 验收②** 的「外部 CLI 配额不足 ⇒ 回退为成员自行执行并注明原因」**裁定为以实装为准**
367
+ (命中配额/鉴权类错误 ⇒ 熔断置「受阻」+ 停止自动重试 + 审计 + 明确原因)。理由:key 失效时让每个成员
368
+ 各回退一次只会把一次明确故障放大成 N 次,且会掩盖真实故障。条款原文保留,裁决记录见
369
+ `docs/需求文档.md` 文末变更记录 2026-10-29 条。
370
+
371
+ [0.2.0]: https://github.com/SilenZerOrz/taskboard-workbench/releases/tag/v0.2.0
372
+
373
+ ## [0.1.0] - 2026-10-23
374
+
375
+ > ⚠️ **本版未发布到 npm。** 它只对应一次 **GitHub Release** 的源码快照(tag 指向初始化提交),
376
+ > registry 上从未出现过 `taskboard-workbench@0.1.0`。**首个 npm 版本是 `0.2.0`。**
377
+
378
+ **对外首个版本(初始版本)**。此前仓库仅内部私有演进(`private: true`),
379
+ 所有历史修改不构成对外语义,故对外发布自 `0.1.0` 起算。
380
+
381
+ ### 新增
382
+
383
+ - **本地任务工作台核心**:零运行时依赖(`node:sqlite`)的多项目 / 任务 / 需求条目存储,含状态机、
384
+ 认领锁与心跳、失败会计与熔断、诊断与尝试记录 / 事件流。
385
+ - **看板与呈现**:列看板(含列内拖拽排序)、关键词搜索、Markdown 呈现与内容安全、
386
+ 需求视图「引入的文件」按文件夹树呈现。
387
+ - **执行与编排**:看板侧 CLI 执行器(`cli:claude`)、派发引擎选择(活跃执行者 / 团队模板回落)、
388
+ 执行看护与通知订阅 / 唤醒。
389
+ - **DSH 内嵌插件**:`dsh.bundle.patch` + `dsh.client`(web 平台侧栏 / 布局 / 槽位注入),
390
+ 会话内「任务工作台」中心标签页。
391
+ - **CLI**:`tb` 命令(`bin` 暴露)与本地 Web 服务(`npm start`)。
392
+
393
+ ### 测试
394
+
395
+ - `npm test`(`node --test`)全量单测全绿。
396
+
397
+ ### 已知限制
398
+
399
+ - `docs/` 过程文档不随仓库与包发布,只在本地维护。
400
+ - 执行侧外部 CLI(如 `claude`)**没有强制的文件写入边界**:`--add-dir` 只表达授权目录,
401
+ 不阻止越界写;该约束是指令级的。
402
+
403
+ [0.1.0]: https://github.com/SilenZerOrz/taskboard-workbench/releases/tag/v0.1.0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 SilenZerOrz
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.