taskboard-workbench 0.3.1 → 0.3.3

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 (34) hide show
  1. package/CHANGELOG.md +101 -2
  2. package/index.js +112 -13
  3. package/package.json +6 -2
  4. package/scripts/tb-flow.mjs +109 -8
  5. package/skills/taskboard-flow/SKILL.md +2 -2
  6. package/skills/taskboard-flow/references/injection.md +76 -29
  7. package/skills/taskboard-flow/references/steps/S5.md +21 -1
  8. package/spec/docs/01-/351/241/271/347/233/256/345/274/200/345/261/200.md +63 -0
  9. package/spec/docs/02-/346/265/201/347/250/213/346/211/247/350/241/214/344/270/216/346/235/241/347/233/256.md +110 -0
  10. package/spec/docs/README.md +36 -0
  11. package/spec/docs/assets//346/235/241/347/233/256/350/257/246/346/203/205/346/250/241/346/235/277.md +105 -0
  12. package/spec/norms/item-detail.md +73 -0
  13. package/spec/norms/manifest.json +7 -0
  14. package/src/core/config.mjs +12 -3
  15. package/src/core/contract.mjs +17 -7
  16. package/src/core/data-dir-hint.mjs +52 -0
  17. package/src/core/docs-assets.mjs +135 -0
  18. package/src/core/errors.mjs +11 -0
  19. package/src/core/evidence.mjs +28 -0
  20. package/src/core/executor.mjs +27 -7
  21. package/src/core/executors.mjs +279 -0
  22. package/src/core/flow-inject.mjs +190 -0
  23. package/src/core/instance-lease.mjs +113 -0
  24. package/src/core/kickoff.mjs +289 -0
  25. package/src/core/norms.mjs +177 -0
  26. package/src/core/requirements.mjs +38 -0
  27. package/src/core/store.mjs +333 -36
  28. package/src/core/verify.mjs +39 -4
  29. package/src/mcp/flow-block.mjs +30 -0
  30. package/src/mcp/server.mjs +19 -6
  31. package/src/mcp/tools.mjs +99 -7
  32. package/src/server/api.mjs +361 -11
  33. package/web/app.js +1077 -82
  34. package/web/tokens.css +166 -28
package/CHANGELOG.md CHANGED
@@ -6,10 +6,109 @@
6
6
  版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
7
7
  每个版本对应一个 annotated tag(`vX.Y.Z`)与一条 GitHub Release;npm dist-tag 与 dsh 兼容区间随版本记录。
8
8
 
9
+ ## [0.3.3] - 2026-11-12
10
+
11
+ > 主题:**把「团队执行时缺的那几条路」补齐,并让两个宿主看见同一份库** —— 双宿主对齐(写者租约 + 数据目录自证)、
12
+ > 按卡选执行者、交付证据写入口双通道(含 `agents` 雏形与 WAL)、开局提示词注入当前项目、人工撤单入口,
13
+ > 外加四条团队执行期实测出来的缺陷修复。
14
+ > 版号按本仓既定口径走 **`0.3.x` patch**(`0.3.2` 已声明「`0.3.x` 期 patch 号承载修复 + 可选能力」,
15
+ > `0.4.0` 留给计划文档里预留的确认层 `acceptance_state`)—— 不另起 minor 线。
16
+ > 读数:`npm test` **1225 / 0** · `release-precheck` **EXIT=0** · tarball **86** 文件 · `schemaVersion` **14 → 15**。
17
+
18
+ ### 新增
19
+
20
+ - **双宿主数据对齐(卡 `-236`/`-237` / 需求 `R173`)** —— web 与 desktop **共用同一份库**,且界面能自证「连的是哪个库」:
21
+ 只读跟随者常驻条(`role=follower` 30s 刷新)、写者租约(同时只有一个写者)、`/api/health` 直接给 `dataDir` 与 `dbPath`。
22
+ - **按卡选执行者(卡 `-238` / 需求 `R174`)** —— 任务卡「启动执行」可按卡挑执行者(团队 / 宿主会话 / claude · codex · hermes 等 CLI),
23
+ 前端按注册表渲染图标并按 `id` 派发;**不传执行者 = 原口径**,升级后默认行为不变。
24
+ - **交付证据写入口双通道(卡 `-239`/`-241` / 需求 `R175`)** —— HTTP 与 MCP `card_evidence_submit` **同源**:
25
+ 同一个 store 方法、同一道四字段硬门、同一套错误码;`task_evidence` 增 `evidence_hash` 幂等索引(重复推送不再堆重复行),
26
+ 并落 `agents` / `agent_sessions` 雏形与 WAL(`schemaVersion` **14 → 15**)。
27
+ - **人工撤单入口(卡 `-252` / 需求 `R180`)** —— 抽屉标题栏新增 danger 档「取消任务(撤单)」:原因必填、页内 dialog 二次确认,
28
+ 撤单后把原因写成评论(此前「确认不执行」的卡在界面上根本没有出口,只能挂着)。
29
+
30
+ ### 修复
31
+
32
+ - **内嵌宿主下 `window.prompt` 直接报错(卡 `-240`/`-242` / 需求 `R176`)** —— 新建项目 / 返工说明 / 人工结论 / 需求标题
33
+ 四处取值出口改走**页内 dialog**(`askFields`),取消零副作用;`tests/no-prompt.test.mjs` 守结构门与「三条取消出口统一归 `null`」。
34
+ - **配置页「复制开局提示词」注入当前项目(卡 `-243` / 需求 `R177`)** —— 此前复制的是**默认项目**的开局语,新会话按错误目录开工;
35
+ 现按 `state.projectId` 现算,未设工作目录时**如实提示不猜路径**。
36
+ - **`requestReview` 缺省自动指派评审者(卡 `-244` / 需求 `R178`)** —— 此前只把 `review_state` 置 pending、`reviewer` 留空,
37
+ ⇒ `review_deadlock` 是**必然产物**;现按团队模板缺省指派(真机验证:不传 reviewer ⇒ 回读 `reviewer="reviewer"`)。
38
+ - **同态迁移不再写空转事件(卡 `-245` / 需求 `R178`)** —— `in_review → in_review` 不再追加 `status_changed`,事件流恢复成「状态真的变了」才算。
39
+ - **复核命令不可执行时判「不适用」,不再谎报失败(卡 `-249` / 需求 `R179`)** —— 命令里带未替换占位符(如 `<diff文件>`)时,
40
+ 此前跑出 `sh: syntax error` 并被记成「失败(退出码 2)」;现在 `applicable=false` 且明确说出是哪个占位符没替换。
41
+ - **发布门禁误报(测试夹具)** —— `tests/executors.test.mjs` / `tests/kickoff-prompt-project.test.mjs` 的假家目录写成真机路径形态,
42
+ 命中 L2「mac-home」规则使门禁转红;夹具改中性临时路径,门禁回到 `EXIT=0`。
43
+
44
+ ### 兼容性与升级注意
45
+
46
+ - **npm `latest` 升到 `0.3.3`**;`engines.dsh` 仍为 `>=0.2.1-rc.3`(本机验证形态 `0.2.2-rc.1`)。
47
+ - **`schemaVersion` 14 → 15**:首启自动迁移(`task_evidence` 补 `evidence_hash` 列 + 指纹索引,幂等)。
48
+ 回退到 `0.3.2` 读同一个库**不安全**(旧代码不认识新列),要回退请连同 `.data` 快照一起回。
49
+ - **证据写入变幂等**:同一张卡、同一份产物指纹重复推送只留一行 —— 依赖「每次 push 都新增一行」的外部统计口径需要改。
50
+ - **撤单不会自动解锁下游**:`isTaskReady` 仍只把 `done` 当完成(`canceled` 算未完成),口径待定,见卡 `-253` / 需求 `R181`(backlog)。
51
+
52
+ ## [0.3.2] - 2026-11-06
53
+
54
+ > 主题:**把三轮「卡上已收口、包里还没有」的改动一次补齐** —— `0.3.1` 之后又攒了开局长注入(P5 档 C)、
55
+ > 开局对齐(R170)、真机批注批(六条)与规范随包(`4c8f8a9`)四项进包变更,按 D7 攒批一次发。
56
+ > 版号 `0.3.2` 为 2026-11-06 拍板结果(`0.3.x` 期内 patch 号承载「修复 + 可选能力」,不另起 `0.4.0` 线;
57
+ > `0.4.0` 留给计划文档里预留的「确认层 `acceptance_state`」,那批尚未开工)。
58
+ > 读数:`npm test` **1143 / 0** · `release-precheck` **EXIT=0** · tarball **83** 文件 · `schemaVersion` **13 → 14**。
59
+
60
+ ### 新增
61
+
62
+ - **开局注入 · P5 档 C(卡 `-210` / 需求 `R128`,`ede1d01`)** —— 新模块 `src/core/flow-inject.mjs`;
63
+ 项目设置增 `flow_inject_policy`(`off` / `main-only` / `main+exec` / `all`),
64
+ 宿主 `createSession` 出口按 **policy × role** 分流:主会话拿完整流程块(逐字节等于 `tb-flow start`),
65
+ 执行会话拿摘要版,子代理不注入。**默认 `off` ⇒ 升级后行为零变化**,必须显式开。
66
+ 注入异常只回 `injection.reason`、**不阻断会话创建**(建会话失败比少注入一句严重得多)。
67
+ - **项目开局对齐 · 可直接进主对话(卡 `-229`/`-230`/`-231` / 需求 `R170`,`ede1d01`)** —— 新模块 `src/core/kickoff.mjs`:
68
+ 把「项目开局还缺什么」生成成**分步 todolist 正文**并投递进项目主会话;项目未绑主会话时抛新错误码
69
+ **`NO_MAIN_SESSION`**(冲突类,不是数据错误 —— 与「这件事做不到」区分开)。
70
+ - **需求条目简写 `R170`(卡 `-234` / 需求 `R171`,`ede1d01`)** —— 带项目上下文时可直接写简写;
71
+ **不带项目时不跨项目猜**,而是把各项目同序号的全标识列成候选。
72
+ `REQUIREMENT_NOT_FOUND` 收敛到唯一构造点,`details.hint` + `details.examples` 给**可直接照抄**的写法(报错即文档)。
73
+ - **兼容层与配置分离(卡 `-216`/`-218`/`-219`/`-220` / 需求 `R159`–`R161`,`4c8f8a9`)** ——
74
+ ① 需求条目 `detailState` 派生三态(`mirror` / `truncated` / `full`),列表胶囊 + 详情「完整性」字段(真实库 87/9/60);
75
+ ② `spec/norms/item-detail.md` 入册(`NORM_IDS` 5 → 6)+ 项目副本 `<工作区>/.taskboard/norms/` + 配置页「规范来源」卡片;
76
+ ③ `spec/docs/` 四份通用人读文档入包,配只读守卫 `tools/check-docs.mjs`;
77
+ ④ `GET|POST|PUT /api/projects/:id/docs` + 配置页「文档与规范位置」卡片:**包内默认 / 项目存放(可改)/ 生效来源**三栏都可见可改。
78
+ - **任务抽屉按钮分层(卡 `-224` / 需求 `R164`)** —— 标题栏拆 `.tb-drawer-actions`(卡片级动作)与
79
+ `.tb-drawer-utils`(全部收起 / 全屏 / 关闭)两段,中间画发丝线,位置不再由 `append` 顺序决定;
80
+ 并保证**全抽屉至多一个 primary**(此前一屏 5–7 个同权重蓝块,人看不出该点哪个)。只做呈现,不删按钮、不改回调。
81
+ - **真机批注四条(`-225`–`-228` / 需求 `R166`–`R169`)** —— 需求工具栏回归一栏;「引入的文件」按文件夹树呈现
82
+ (对齐 dsh 侧栏样式);配置页会话关联可直接跳转主会话 / 相关会话;配置页八步引导按**真实代码**重排
83
+ (此前「开局提示词」排在第八步,与实际流程不符)。
84
+ - **启动分步容错 + 常驻降级条(卡 `-222` / 需求 `R163`)** —— 启动改 `runBootStep` 分步执行:可降级步骤失败时**面板照常可用**,
85
+ 并在顶部留一条**不会自动消失**的说明条(带「重试」+ 失败原因)。与一次性 banner 分开 —— banner 到时会消失,用户就再也看不到"为什么少了一半数据"。
86
+
87
+ ### 修复
88
+
89
+ - **复核命令超限被静默截断(卡 `-232`,`ede1d01`)** —— 真机事故:`verifyCommand` 超过 300 字符时被 `slice(0,300)` **静默切开**,
90
+ 命令变成语法错误 ⇒ 自动复核**恒 exit 2**,人只会看到「自动复核失败」。改为**抛 `USAGE_ERROR` 并带上实际长度与上限**,
91
+ 不再截断(截断比报错危险得多:它把"存不进去"伪装成"跑不过")。全库 33 张带复核命令的卡里只有一张中招。
92
+ - **三台既有验证台 PASS 却不退出(卡 `-223`)** —— 只置 `process.exitCode` 而不 `process.exit()` 的台必须自己清句柄;
93
+ 实测漏的是 **CDP WebSocket** 与 server 的 keep-alive 连接 ⇒ 11/11 PASS 却被 `timeout` 杀成退出码 124。
94
+
95
+ ### 变更
96
+
97
+ - **`CHANGELOG [0.3.1]` 段事实修正(卡 `-213`,`34db1b4`)** —— 修正对 `0.3.0` 发布事实的描述,只改文案、不改已发布内容。
98
+
99
+ ### 兼容性与升级注意
100
+
101
+ - **`schemaVersion` 13 → 14**:新增 `project_settings.flow_inject_policy`。**老库打开即幂等补列**(默认 `off`),无需迁移脚本。
102
+ - **零新增运行期依赖**:`node --test` 仍是唯一门禁。`eslint` / `prettier` 是**可选**开发工具,**不随包发布**,
103
+ 未安装时 `npm run lint` 会报 command not found —— 属预期。
104
+ - **新错误码 `NO_MAIN_SESSION`**:调用方若按错误码分支,需认识这个新值(属冲突类,`EXIT.CONFLICT`)。
105
+ - **`engines.dsh` 仍为 `>=0.2.1-rc.3`**:本机已在 `0.2.1-rc.5` 上复跑宿主能力门 **9/9 PASS**;下限不动(floor 不是 pin)。
106
+ - **tarball 82 → 83 文件**:只增 `spec/norms/item-detail.md`。`tools/` 与 `.github/` 不在 `files` 白名单,开发工具不计入包内容。
107
+
9
108
  ## [0.3.1] - 2026-11-04
10
109
 
11
110
  > 主题:**7 笔攒批一次发**(`v0.3.0` 后连续攒到 6 项进包变更 + 1 项打包声明),把「卡上收口了、包里还没到」这段补齐。
12
- > npm `latest` 由 `0.2.0` 直接对齐到本版(跳过从未发布的 `0.3.0`,D7「攒批」口径的兑现)。
111
+ > 发布轨:`0.2.0` → `0.3.0` → **`0.3.1`** **连续发布**(三个版本都在 registry 上);D7「攒批」体现在 **`0.3.0` 之后又攒了 7 笔才发 `0.3.1`** —— 攒的是**变更**,不是跳过版本。
13
112
  > `npm test` **986 / 0**、`release-precheck` **EXIT=0**、tarball **75** 文件。
14
113
 
15
114
  ### 新增
@@ -50,7 +149,7 @@
50
149
 
51
150
  ### 兼容性与升级注意
52
151
 
53
- - **npm `latest` 由 `0.2.0` 跳到 `0.3.1`**:registry 上**不存在 `0.3.0`**,`changelog` 仍保留其条目(它对应 `v0.3.0` tag 与源码快照)。
152
+ - **npm `latest` = `0.3.1`**(`0.2.0` → `0.3.0` → `0.3.1` 连续发布,registry 三个版本都在)。若你从 `0.2.0` 直接升上来:`0.3.0` 的条目**同样适用**(`v0.3.0` tag 与源码快照仍在),`0.3.1` 是在它之上追加的 7 笔变更。
54
153
  - **`engines.dsh = ">=0.2.1-rc.3"`**:宿主低于此版本不再满足声明(此前未声明,等于默认可装)。本版是本机验证过的形态。
55
154
  - **契约门是行为变更**(上条 `-209`):升级后请重新核对 CI/脚本里的 `contract` 版本与摘要。
56
155
  - **`schemaVersion` 仍为 13**(本版无表结构变更,`-197` 引入的两表已在 `0.3.0` 就位)。
package/index.js CHANGED
@@ -5,8 +5,8 @@
5
5
  * 挂到独立命名空间 /integrations/taskboard-workbench 下,并同时托管 web/ 静态资源
6
6
  * (客户端面板通过同源脚本加载复用 web/app.js 的看板渲染)。
7
7
  *
8
- * 数据目录:插件配置 dataDir > 宿主 `ctx.get("config").dataDir` > TB_DATA_DIR > 系统临时目录
9
- * (默认不写代码仓库)。**不得直接读 `ctx.config`**:本插件 `inject` 只声明了 `webServer`,
8
+ * 数据目录:插件配置 dataDir > 宿主 `ctx.get("config").dataDir` > TB_DATA_DIR > `~/.dsh/data/taskboard-workbench`
9
+ * (默认不写代码仓库;2026-11-10 起不再落系统临时目录 —— 见 `src/core/config.mjs`)。**不得直接读 `ctx.config`**:本插件 `inject` 只声明了 `webServer`,
10
10
  * cordis 会对未声明属性抛「cannot get property "config" without inject」⇒ 装载期整条 entry
11
11
  * 不激活(2026-10-26 用隔离真宿主 `--from-default-profile` 复现;真实 profile 因为用户层
12
12
  * patch 显式给了 `config.dataDir`,把 `??` 右边短路掉,才一直没暴露)。
@@ -15,14 +15,19 @@ import { fileURLToPath, pathToFileURL } from "node:url";
15
15
  import { createRequire } from "node:module";
16
16
  import { existsSync, realpathSync } from "node:fs";
17
17
  import path from "node:path";
18
+ import os from "node:os";
18
19
 
19
20
  import { resolveDataDir } from "./src/core/config.mjs";
21
+ import { detectLegacyDataHint } from "./src/core/data-dir-hint.mjs";
20
22
  import { openStore } from "./src/core/store.mjs";
23
+ import { LEASE_HEARTBEAT_MS } from "./src/core/instance-lease.mjs";
21
24
  import { createRequestHandler, ensureDefaultProject, WEB_DIR } from "./src/server/server.mjs";
22
25
  import { createEventHub } from "./src/server/events.mjs";
23
26
  import { runExecutionLoop, listLoopProjects } from "./src/core/loop.mjs";
24
27
  import { createLlmElaborator } from "./src/host/ai-elaborator.mjs";
25
28
  import { createTeamEnginePort } from "./src/host/team-engine.mjs";
29
+ // P5 档 C(卡 `-210`):开局注入的唯一实现 —— 宿主建会话出口与 `tb-flow inject` 共用同一段判定。
30
+ import { injectFlow } from "./src/core/flow-inject.mjs";
26
31
 
27
32
  export const name = "taskboard-workbench";
28
33
  export const inject = ["webServer"];
@@ -34,19 +39,25 @@ export const PREFIX = "/integrations/taskboard-workbench";
34
39
  *
35
40
  * 对齐 agent-teams 的**懒取**模式:不在 apply 时 eager 取服务,而是每次调用时经 `getService(name)` 现取,
36
41
  * 因此服务在插件之后出现/被替换时自然生效(无需 eager 注入)。
37
- * - createSession({preset,cwd,title}):`sessionController.create()`(退回 `sessions.create`);`cwd` 透传工作区;
42
+ * - createSession({preset,cwd,title,role,projectId}):`sessionController.create()`(退回 `sessions.create`);`cwd` 透传工作区;
38
43
  * 宿主 `create()` **不收 title** ⇒ `title` 走**建完再 `rename()`**(改名失败如实回 `titleApplied:false` + 原因,不谎报);
39
44
  * **尝试**预置内容,失败不抛错。
45
+ * **P5 档 C(卡 `-210`)**:建完按项目 `flow_inject_policy` 做**开局注入**(`main`=完整版 / `exec`+`related`=摘要版 /
46
+ * `subagent`=不注入);注入异常**只回 `injection.reason`,不阻断会话创建**(见 `src/core/flow-inject.mjs`)。
40
47
  * - renameSession(id, title):会话改名(2026-10-23 命名约束的宿主出口)。
41
48
  * - sendPrompt(id, text):**任务下发**。经 `sessionController.prompt({mode:"queue"})` 把指令投递给该会话的 Agent。
42
49
  * - openSession(id):宿主侧无此能力(返回 ui-workspace-unavailable);会话切换由**客户端** uiWorkspace 完成(见 lib/client.js)。
43
50
  * - getCurrentSessionId():宿主工具面才有 `exec.agent?.id`,此处恒返回 null(接口占位)。
44
51
  */
45
- export function createHostSessionPort({ getService, getCtx } = {}) {
52
+ export function createHostSessionPort({ getService, getCtx, getStore } = {}) {
46
53
  const sessions = () => getService?.("sessions");
47
54
  const sessionController = () => getService?.("sessionController");
48
55
  const agents = () => getService?.("agents");
49
56
  const uiWorkspace = () => getService?.("uiWorkspace");
57
+ /** 注入用 store(懒取):宿主未给 store(单测 / 纯 adapter 用法)⇒ 一律不注入,行为与接线前完全一致。 */
58
+ const store = () => {
59
+ try { return getStore?.() ?? null; } catch { return null; }
60
+ };
50
61
  const mkRequestId = () =>
51
62
  (globalThis.crypto?.randomUUID?.() ?? `tb-${Date.now()}-${Math.random().toString(36).slice(2)}`);
52
63
  // ---- 作用域取服务(FR-71 投递修复)------------------------------------------
@@ -227,12 +238,33 @@ export function createHostSessionPort({ getService, getCtx } = {}) {
227
238
  const r = await renameSession(sessionId, title);
228
239
  return { titleApplied: Boolean(r.renamed), titleReason: r.renamed ? null : (r.reason ?? "rename-failed") };
229
240
  }
241
+ /**
242
+ * P5 档 C(卡 `-210`):建会话后的**开局注入**出口。
243
+ *
244
+ * 三条纪律:
245
+ * ① **绝不抛错**:`injectFlow()` 自身不抛,这里再兜一层 —— 注入失败只回 `injection.reason`,
246
+ * **会话创建照旧成功**(验收 ⑤:失败不改行为);
247
+ * ② **按 policy × role 分流**:判定在 `src/core/flow-inject.mjs`(唯一实现),这里只负责「把 store 和
248
+ * 投递通道递过去」;`role` 由调用方声明(主会话 `main` / 任务执行会话 `exec`)——
249
+ * **没声明就不注入**(宁可少注,不可错注;`role-unknown`);
250
+ * ③ **内容只有一处生成**:`injectFlow()` 内部调 `buildFlowBlock()`(完整版逐字节等于 `tb-flow start`)。
251
+ */
252
+ async function injectOpeningFlow({ sessionId, role, projectId, cwd }) {
253
+ const st = store();
254
+ if (!sessionId || !st) return { injected: false, reason: st ? "no-session" : "no-store" };
255
+ try {
256
+ return await injectFlow({ store: st, deliver, sessionId, role: role ?? null, projectId: projectId ?? null, cwd: cwd ?? null, policy: null, source: "createSession" });
257
+ } catch (error) {
258
+ console.error(`[taskboard-workbench] flow inject failed: ${error?.message ?? error}`);
259
+ return { injected: false, reason: error?.code ?? String(error?.message ?? error ?? "inject-error") };
260
+ }
261
+ }
230
262
  return {
231
263
  /** 动态可用性:能否建会话 / 投递指令。 */
232
264
  get available() {
233
265
  return typeof sessionController()?.create === "function" || typeof sessions()?.create === "function";
234
266
  },
235
- async createSession({ preset, cwd, title } = {}) {
267
+ async createSession({ preset, cwd, title, role = null, projectId = null } = {}) {
236
268
  const sc = (await scopedSessionController("tb-session:new")) ?? sessionController();
237
269
  if (typeof sc?.create === "function") {
238
270
  try {
@@ -244,7 +276,9 @@ export function createHostSessionPort({ getService, getCtx } = {}) {
244
276
  const sessionId = typeof created === "string" ? created : (created?.sessionId ?? created?.id ?? null);
245
277
  const named = await applyTitle(sessionId, title);
246
278
  const presetApplied = sessionId && preset ? (await deliver(sessionId, preset)).sent : false;
247
- return { sessionId, presetApplied, titleApplied: named.titleApplied, titleReason: named.titleReason };
279
+ // 开局注入排在「预置指令」之后:先给人/agent 看这一轮的任务,再补流程护栏(顺序可观测、可测)。
280
+ const injection = await injectOpeningFlow({ sessionId, role, projectId, cwd });
281
+ return { sessionId, presetApplied, titleApplied: named.titleApplied, titleReason: named.titleReason, injection };
248
282
  } catch (error) {
249
283
  console.error(`[taskboard-workbench] sessionController.create failed: ${error?.message ?? error}`);
250
284
  }
@@ -263,7 +297,8 @@ export function createHostSessionPort({ getService, getCtx } = {}) {
263
297
  }
264
298
  const namedFallback = await applyTitle(sessionId, title);
265
299
  const presetApplied = sessionId && preset ? (await deliver(sessionId, preset)).sent : false;
266
- return { sessionId, presetApplied, titleApplied: namedFallback.titleApplied, titleReason: namedFallback.titleReason };
300
+ const injection = await injectOpeningFlow({ sessionId, role, projectId, cwd });
301
+ return { sessionId, presetApplied, titleApplied: namedFallback.titleApplied, titleReason: namedFallback.titleReason, injection };
267
302
  },
268
303
  /**
269
304
  * 会话改名(2026-10-23 用户命名约束「【任务】/【项目】+ 时间/备注」的宿主出口)。
@@ -351,7 +386,12 @@ export function createHostSessionPort({ getService, getCtx } = {}) {
351
386
  const q = getService?.("sessionQuery");
352
387
  if (!q) return { sessionId, cwd: null, source: "unavailable" };
353
388
  try {
354
- const index = await sessionIndex();
389
+ // 卡 `-235`(需求 `R172`)· lint `no-undef` 抓到的真缺陷:原写 `await sessionIndex()`,
390
+ // 而那是**同一对象的方法**、不在当前作用域 ⇒ ReferenceError ⇒ 被下面的 `catch` 静默吞掉 ⇒
391
+ // 「先查持久化索引(带 TTL 缓存)」这条路径**从未生效**,每次都退到 readSession。
392
+ // 改为直接调上面那个闭包(`sessionIndex()` 方法体也是它),同源、同缓存,语义不变。
393
+ const built = await buildSessionIndex();
394
+ const index = built?.map ?? null;
355
395
  if (index?.has(sessionId)) {
356
396
  return { sessionId, cwd: index.get(sessionId)?.cwd ?? null, source: "sessionQuery.listSessions" };
357
397
  }
@@ -513,7 +553,8 @@ export function apply(ctx, config) {
513
553
  })();
514
554
  const runtime = createPluginRuntime({ dataDir: config?.dataDir ?? hostDataDir, aiElaborator });
515
555
  // 挂载宿主会话能力(懒取服务);api 层经 store.hostSessionPort 使用。
516
- runtime.store.hostSessionPort = createHostSessionPort({ getService: (name) => ctx?.get?.(name), getCtx: () => ctx });
556
+ // `getStore`:P5 档 C(卡 `-210`)注入用 —— 只读项目设置 + 写 `flow_injections` 审计;不给 store 则一律不注入。
557
+ runtime.store.hostSessionPort = createHostSessionPort({ getService: (name) => ctx?.get?.(name), getCtx: () => ctx, getStore: () => runtime.store });
517
558
  // 团队引擎端口(默认 P2 指令降级;TEAM_ENGINE=agent-teams 切 P1)。
518
559
  const teamEngineMode = config?.teamEngine ?? process.env.TEAM_ENGINE ?? "instruction";
519
560
  runtime.store.teamEnginePort = createTeamEnginePort({ getService: (name) => ctx?.get?.(name), mode: teamEngineMode });
@@ -566,17 +607,51 @@ export function apply(ctx, config) {
566
607
  disposed = false;
567
608
  registerRoutes(getWebServer());
568
609
  registerTools(ctx?.get?.("tools") ?? ctx?.tools);
610
+ // 卡 `-237`(需求 `R173`):**多实例单写者租约**。dsh web 与 dsh desktop 可以同时打开同一个库,
611
+ // 谁先抢到谁写;后起者降级为 follower(只读 + 不起执行循环 + 不做 boot 收口)。
612
+ let leaseRole = "writer";
613
+ let leaseOwner = null;
614
+ try {
615
+ const lease = runtime.store.acquireInstanceLease({ host: os.hostname(), pid: process.pid });
616
+ leaseRole = lease.role;
617
+ leaseOwner = lease.owner;
618
+ if (leaseRole !== "writer") {
619
+ console.log(`[taskboard-workbench] 只读跟随:另一实例正在写同一个库(${lease.owner?.host} · pid ${lease.owner?.pid} · ${runtime.store.dbPath})`);
620
+ } else if (lease.tookOver) {
621
+ console.log(`[taskboard-workbench] 写者租约接管:上一实例 ${lease.previous?.host} · pid ${lease.previous?.pid} 已过期`);
622
+ }
623
+ } catch (error) {
624
+ console.error(`[taskboard-workbench] 写者租约获取失败(按 writer 继续):${error?.message ?? error}`);
625
+ }
569
626
  // FR-82 收口(启动口径):上一进程留下的「进行中」尝试不会有人闭合 —— 启动时一次结清(**不看时长**)。
627
+ // **只有 writer 才做 boot 收口** —— 它分不清「上一进程」与「另一个还活着的进程」,
628
+ // follower 跑一次就会把对端正跑着的执行当孤儿结清(这正是 R173 的真机风险)。
629
+ if (leaseRole === "writer") {
630
+ try {
631
+ const rec = runtime.store.reconcileOrphanRuns({ boot: true });
632
+ if (rec.ended.length || rec.ghostClaims.length) {
633
+ console.log(`[taskboard-workbench] boot reconcile: 收口孤儿尝试 ${rec.ended.length} 条(${rec.ended.map((r) => `${r.identifier}#${r.attempt}→${r.outcome}`).join(", ")});清幽灵认领 ${rec.ghostClaims.length} 条`);
634
+ }
635
+ } catch (error) {
636
+ console.error(`[taskboard-workbench] boot reconcile failed: ${error?.message ?? error}`);
637
+ }
638
+ }
639
+ // 卡 `-236`(需求 `R173`):默认目录从系统临时目录搬到 `~/.dsh/data/taskboard-workbench` 之后,
640
+ // 老用户的卡还在旧目录 —— 只读对照一次,把「升级后看板全空」变成一条能看懂的提示。
641
+ // **不搬库、不删旧库**:搬数据属破坏性动作,交用户决定(提示里给两条明路)。
570
642
  try {
571
- const rec = runtime.store.reconcileOrphanRuns({ boot: true });
572
- if (rec.ended.length || rec.ghostClaims.length) {
573
- console.log(`[taskboard-workbench] boot reconcile: 收口孤儿尝试 ${rec.ended.length} 条(${rec.ended.map((r) => `${r.identifier}#${r.attempt}→${r.outcome}`).join(", ")});清幽灵认领 ${rec.ghostClaims.length} 条`);
643
+ const hint = detectLegacyDataHint({ dataDir: runtime.dataDir, activeTaskCount: runtime.store.stats().tasks });
644
+ if (hint) {
645
+ runtime.store.dataDirHint = hint;
646
+ console.warn(`[taskboard-workbench] 数据目录迁移提示:${hint.hint}`);
574
647
  }
575
648
  } catch (error) {
576
- console.error(`[taskboard-workbench] boot reconcile failed: ${error?.message ?? error}`);
649
+ console.error(`[taskboard-workbench] 迁移提示探测失败(忽略):${error?.message ?? error}`);
577
650
  }
578
651
  // 看板执行循环定时器(FR-70):仅对"已开启循环"的项目按活跃引擎自动派发待执行任务
579
652
  const loopTimer = setInterval(() => {
653
+ // 卡 `-237`:follower 不跑执行循环(否则同一张卡会被两个宿主同时派发)。
654
+ if (leaseRole !== "writer") return;
580
655
  // FR-77:回收失效认领(认领过期 / 心跳陈旧)——执行侧仍存活则延后,避免重复派发。
581
656
  try {
582
657
  const reclaimed = runtime.store.reclaimStaleClaims();
@@ -603,6 +678,28 @@ export function apply(ctx, config) {
603
678
  }
604
679
  }, 30000);
605
680
  loopTimer.unref?.();
681
+ // 卡 `-237`:心跳 15s。**follower 也每拍一次 acquire** —— 对端一退出(租约过期 45s)就能接管。
682
+ const leaseTimer = setInterval(() => {
683
+ try {
684
+ const next = runtime.store.acquireInstanceLease({ host: os.hostname(), pid: process.pid });
685
+ if (next.role === "writer" && leaseRole !== "writer") {
686
+ leaseRole = "writer";
687
+ leaseOwner = null;
688
+ console.log("[taskboard-workbench] 已接管写者租约(对端已过期),本窗口恢复读写");
689
+ try {
690
+ const rec = runtime.store.reconcileOrphanRuns({ boot: true });
691
+ if (rec.ended.length || rec.ghostClaims.length) console.log(`[taskboard-workbench] 接管收口:孤儿 ${rec.ended.length} 条 / 幽灵认领 ${rec.ghostClaims.length} 条`);
692
+ } catch (error) { console.error(`[taskboard-workbench] 接管收口失败:${error?.message ?? error}`); }
693
+ } else if (next.role !== "writer" && leaseRole === "writer") {
694
+ leaseRole = "follower";
695
+ leaseOwner = next.owner;
696
+ console.log(`[taskboard-workbench] 失去写者租约 → 只读跟随(${next.owner?.host} · pid ${next.owner?.pid})`);
697
+ }
698
+ } catch (error) {
699
+ console.error(`[taskboard-workbench] 租约心跳失败:${error?.message ?? error}`);
700
+ }
701
+ }, LEASE_HEARTBEAT_MS);
702
+ leaseTimer.unref?.();
606
703
  // 服务在插件 apply 之后才出现/被替换时,重新注册(agent-teams 同款做法)。
607
704
  const onService = (name) => {
608
705
  if (name === "webServer" || name === "httpServer") registerRoutes(getWebServer());
@@ -612,6 +709,8 @@ export function apply(ctx, config) {
612
709
  return () => {
613
710
  disposed = true;
614
711
  try { clearInterval(loopTimer); } catch (_) {}
712
+ try { clearInterval(leaseTimer); } catch (_) {}
713
+ try { runtime.store.releaseInstanceLease(); } catch (_) {}
615
714
  try {
616
715
  off?.();
617
716
  } catch (_) {}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "taskboard-workbench",
3
- "version": "0.3.1",
3
+ "version": "0.3.3",
4
4
  "type": "module",
5
5
  "description": "agent team 任务工作台:零依赖核心(node:sqlite)+ CLI + 本地 Web 看板 + DSH 内嵌插件",
6
6
  "license": "MIT",
@@ -50,6 +50,7 @@
50
50
  "cli",
51
51
  "spec/团队agent.md",
52
52
  "spec/norms",
53
+ "spec/docs",
53
54
  "scripts/tb-flow.mjs",
54
55
  "tools/seed.mjs",
55
56
  "tools/env-check.mjs"
@@ -65,7 +66,10 @@
65
66
  "flow": "node scripts/tb-flow.mjs",
66
67
  "seed": "node tools/seed.mjs",
67
68
  "test": "node --test",
68
- "env-check": "node tools/env-check.mjs"
69
+ "env-check": "node tools/env-check.mjs",
70
+ "lint": "eslint .",
71
+ "format": "prettier --write .",
72
+ "format:check": "prettier --check ."
69
73
  },
70
74
  "peerDependencies": {
71
75
  "@deepseek-ai/dsh-client-ui-layout": "*",
@@ -1,23 +1,33 @@
1
1
  #!/usr/bin/env node
2
2
  /**
3
- * tb-flow.mjs —— 开局装载块(P4 · 档 A / 档 B 的同一个入口)
3
+ * tb-flow.mjs —— 开局装载块(P4 档 A / 档 B 的同一个入口 + P5 档 C 的人工出口)
4
4
  *
5
5
  * 用法:
6
- * node scripts/tb-flow.mjs start [--project <id>] [--cwd <dir>] [--json]
6
+ * node scripts/tb-flow.mjs start [--project <id>] [--cwd <dir>] [--json]
7
7
  * node scripts/tb-flow.mjs snippet [--project <id>] # 打给项目 AGENTS.md 用的片段
8
8
  * node scripts/tb-flow.mjs check # 只自检(不读写库)
9
+ * node scripts/tb-flow.mjs inject --session <id> [--role main|exec|related] [--project <id>]
10
+ * [--host <url>] [--verify-bytes] [--json]
9
11
  *
10
12
  * 数据源:`--data-dir` > `$TB_DATA_DIR` > 默认(与 Web / CLI / MCP 同一份 `taskboard.sqlite`)。
11
13
  *
12
- * **只读**:本脚本不建卡、不改状态、不写评论、不写审计 —— 它只把"现在该干什么"打印出来。
14
+ * `start` / `snippet` / `check` **只读**:不建卡、不改状态、不写评论。
13
15
  * 与 MCP prompt `taskboard.flow` 共用 `src/mcp/flow-block.mjs`,输出**逐字节相同**。
16
+ *
17
+ * `inject`(P5 档 C · 卡 `-210`):把**同一份**装载块投进指定会话,并落 `flow_injections` 审计行。
18
+ * · 它是**人工一次性**投递(审计 `policy=manual`)—— 自动注入由宿主 `createSession()` 按项目
19
+ * `flow_inject_policy` 决定,两者共用 `src/core/flow-inject.mjs`,所以内容不会出现第二真源;
20
+ * · 必须有一个**带宿主会话通道**的实例在跑(默认 `http://127.0.0.1:3080`,可用 `--host` 指到隔离实例);
21
+ * · `--verify-bytes`:本地复算同一份正文的 sha256 与宿主回报的 `digest` 对拍(验收 ③ 的自检口)。
14
22
  */
15
23
  import path from "node:path";
16
24
  import { fileURLToPath } from "node:url";
17
25
 
18
- import { buildAgentsSnippet, buildFlowBlock, readSkill, SKILL_PATH } from "../src/mcp/flow-block.mjs";
26
+ import { buildAgentsSnippet, buildFlowBlock, buildFlowSummary, readSkill, SKILL_PATH } from "../src/mcp/flow-block.mjs";
19
27
  import { openStore } from "../src/core/store.mjs";
20
28
  import { resolveDataDir } from "../src/core/config.mjs";
29
+ import { resolveProject } from "../src/mcp/tools.mjs";
30
+ import { sha256 } from "../src/core/contract.mjs";
21
31
 
22
32
  const argv = process.argv.slice(2);
23
33
  const has = (name) => argv.includes(name);
@@ -25,7 +35,10 @@ const argOf = (name) => {
25
35
  const i = argv.indexOf(name);
26
36
  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : null;
27
37
  };
28
- const command = argv.find((a) => !a.startsWith("-") && argv[argv.indexOf(a) - 1] !== "--project" && argv[argv.indexOf(a) - 1] !== "--cwd" && argv[argv.indexOf(a) - 1] !== "--data-dir") ?? "start";
38
+ /** 只跳过**带值**的选项,别把 `--session` 后面的会话 id 当成子命令。 */
39
+ const VALUE_FLAGS = new Set(["--project", "--cwd", "--data-dir", "--session", "--host", "--role"]);
40
+ const command = argv.find((a, i) => !a.startsWith("-") && !VALUE_FLAGS.has(argv[i - 1] ?? "")) ?? "start";
41
+ const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
29
42
 
30
43
  if (has("--help") || has("-h")) {
31
44
  process.stdout.write(`tb-flow · 任务看板开局装载块
@@ -33,7 +46,11 @@ if (has("--help") || has("-h")) {
33
46
  node scripts/tb-flow.mjs start [--project <id>] [--cwd <dir>] [--json] [--data-dir <dir>]
34
47
  node scripts/tb-flow.mjs snippet [--project <id>]
35
48
  node scripts/tb-flow.mjs check
36
- 只读脚本:不建卡 / 不改状态 / 不写评论。数据源同 Web/CLI(--data-dir > $TB_DATA_DIR > 默认)。
49
+ node scripts/tb-flow.mjs inject --session <id> [--role main|exec|related] [--project <id>]
50
+ [--host <url>] [--verify-bytes] [--json]
51
+ 只读脚本:start / snippet / check 不建卡 / 不改状态 / 不写评论。
52
+ inject 是人工一次性投递(落 flow_injections 审计行,policy=manual),需要带宿主会话通道的实例在跑。
53
+ 数据源同 Web/CLI(--data-dir > $TB_DATA_DIR > 默认);--host 默认 $TB_HOST_URL 或 http://127.0.0.1:3080。
37
54
  `);
38
55
  process.exit(0);
39
56
  }
@@ -46,12 +63,96 @@ if (command === "check") {
46
63
  }
47
64
 
48
65
  if (command === "snippet") {
49
- process.stdout.write(`${buildAgentsSnippet({ project: argOf("--project"), pkgPath: path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..") })}\n`);
66
+ process.stdout.write(`${buildAgentsSnippet({ project: argOf("--project"), pkgPath: PKG_ROOT })}\n`);
50
67
  process.exit(0);
51
68
  }
52
69
 
70
+ if (command === "inject") {
71
+ const sessionId = argOf("--session");
72
+ if (!sessionId) {
73
+ process.stderr.write("缺 --session <id>:要投进哪个会话\n");
74
+ process.exit(2);
75
+ }
76
+ const role = argOf("--role");
77
+ if (role && !["main", "exec", "related", "subagent"].includes(role)) {
78
+ process.stderr.write(`--role 只能是 main / exec / related / subagent(收到 ${role})\n`);
79
+ process.exit(2);
80
+ }
81
+ const host = (argOf("--host") ?? process.env.TB_HOST_URL ?? "http://127.0.0.1:3080").replace(/\/+$/, "");
82
+ let store = null;
83
+ try {
84
+ // 只传 `--project` 且不要求逐字节复算时,**不打开本地库**(投递本身在宿主侧完成)。
85
+ let projectId = argOf("--project");
86
+ if (!projectId || has("--verify-bytes")) {
87
+ store = openStore({ dataDir: argOf("--data-dir") ?? resolveDataDir({ env: process.env }), env: process.env });
88
+ }
89
+ if (!projectId) {
90
+ projectId = resolveProject(store, { cwd: argOf("--cwd") ?? process.cwd() }).project.id;
91
+ }
92
+ const url = `${host}/integrations/taskboard-workbench/api/projects/${encodeURIComponent(projectId)}/flow/inject`;
93
+ let res;
94
+ try {
95
+ res = await fetch(url, {
96
+ method: "POST",
97
+ headers: { "content-type": "application/json", accept: "application/json" },
98
+ body: JSON.stringify({ sessionId, ...(role ? { role } : {}), source: "tb-flow-cli" }),
99
+ });
100
+ } catch (error) {
101
+ process.stderr.write(`HOST_UNREACHABLE: 连不上 ${url}(${error?.cause?.code ?? error?.message ?? error})\n`);
102
+ process.stderr.write("提示:inject 需要 DSH 内的任务工作台实例(或任意带宿主会话通道的实例);可用 --host 指到隔离验证实例。\n");
103
+ process.exit(4);
104
+ }
105
+ const payload = await res.json().catch(() => null);
106
+ if (!res.ok || !payload) {
107
+ process.stderr.write(`HTTP ${res.status}: ${payload?.error ?? payload?.message ?? "宿主未回可解析的 JSON"}\n`);
108
+ process.exit(1);
109
+ }
110
+
111
+ // 验收 ③ 的自检口:本地复算同一份正文,与宿主回报的 digest 对拍。
112
+ let verify = null;
113
+ if (has("--verify-bytes") && payload.digest) {
114
+ try {
115
+ const block = buildFlowBlock({ store, project: projectId });
116
+ const localText = payload.version === "summary" ? buildFlowSummary(block) : block.text;
117
+ const localDigest = sha256(localText);
118
+ verify = { localDigest, match: localDigest === payload.digest, version: payload.version ?? null };
119
+ } catch (error) {
120
+ verify = { localDigest: null, match: null, reason: error?.code ?? String(error?.message ?? error) };
121
+ }
122
+ }
123
+
124
+ if (has("--json")) {
125
+ process.stdout.write(`${JSON.stringify({ projectId, sessionId, host, ...payload, verify }, null, 2)}\n`);
126
+ } else if (payload.delivered) {
127
+ process.stdout.write(`已注入 ${sessionId}(policy=${payload.policy} · version=${payload.version} · ${payload.chars} 字符)\n`);
128
+ process.stdout.write(`project=${projectId} · contract=${payload.contractVersion} · digest=${payload.digest}\n`);
129
+ process.stdout.write(`审计行:flow_injections#${payload.injection?.id ?? "?"} · injected_at=${payload.injection?.injectedAt ?? "?"}\n`);
130
+ if (verify) process.stdout.write(`逐字节复算:${verify.match === true ? "一致" : verify.match === false ? "**不一致**" : `无法复算(${verify.reason})`}\n`);
131
+ } else {
132
+ process.stderr.write(`未投递:${payload.reason}${payload.nextAction ? ` —— ${payload.nextAction}` : ""}\n`);
133
+ if (payload.prompt) {
134
+ // 投不进去的最坏情况:至少把正文原样交给人(粘贴即可),不让人空手。
135
+ process.stderr.write("—— 以下是同一份正文,可直接粘贴到会话 ——\n");
136
+ process.stdout.write(payload.prompt);
137
+ if (!payload.prompt.endsWith("\n")) process.stdout.write("\n");
138
+ }
139
+ }
140
+ if (verify && verify.match === false) process.exit(6);
141
+ process.exit(payload.delivered ? 0 : 5);
142
+ } catch (error) {
143
+ process.stderr.write(`${error?.code ?? "ERROR"}: ${error?.message ?? String(error)}\n`);
144
+ if (error?.code === "PROJECT_NOT_FOUND") {
145
+ process.stderr.write(`提示:当前数据目录不含该项目;显式带 --project <id>,或用 --data-dir 指到真库。\n`);
146
+ process.exit(3);
147
+ }
148
+ process.exit(1);
149
+ } finally {
150
+ try { store?.close(); } catch { /* ignore */ }
151
+ }
152
+ }
153
+
53
154
  if (command !== "start") {
54
- process.stderr.write(`未知子命令:${command}(可用:start / snippet / check)\n`);
155
+ process.stderr.write(`未知子命令:${command}(可用:start / snippet / check / inject)\n`);
55
156
  process.exit(2);
56
157
  }
57
158
 
@@ -34,7 +34,7 @@ requires_contract: v1
34
34
  | **S2** | 分拆成卡 | `card_create` | 条目存在 + 同项目 + 归因硬门 | 返回 `attribution.kind="requirement"`;卡在 `backlog`;依赖真成边 | `tasks` + `task_events`(`created` / `attributed`) | `REQUIREMENT_REQUIRED` ⇒ 补 `requirement`,或显式 `unattributed_reason`(会落审计);`DEPENDENCY_CROSS_PROJECT` ⇒ 前置卡挂错项目;`AUTHORIZATION_REQUIRED` ⇒ 新卡只能进 `backlog` | FR-29 / FR-38 |
35
35
  | **S3** | 授权开工(人) | 看板「启动执行」/ 人点 | 归因门 → 授权门 | `backlog → todo` 由**人**点;执行侧不得自我授权 | `task_events`(`set-status`,`actor=human`) | 执行侧想推 ⇒ `AUTHORIZATION_REQUIRED`;卡还没归因 ⇒ 先回 S2 | FR-40 / FR-84 |
36
36
  | **S4** | 派发 / 执行 | 看板派发 · 宿主团队工具 · MCP `card_progress` 推进状态 | 归因 + 授权 + **人工校验门** | 卡进 `in_progress` 且带认领心跳;人工校验任务不得被执行侧改状态 | `team_runs` / claims / `task_events` | `HUMAN_REVIEW_NOT_EXECUTABLE` ⇒ 这是人在环任务,走人工结论入口;`EXECUTION_NOT_ATTRIBUTED` ⇒ 回 S2 补归因 | FR-41 / FR-42 / FR-85 |
37
- | **S5** | 回填进度 + 证据 | `card_progress` | `contract_version` 一致 + `norm_digest` 一致 | 每条进展带**可核验证据**(`file` / `command` / `url` / `reading`),不是「已完成」三个字;`in_review` 前必须有证据 | 评论(`【MCP 证据】hash=…`)+ 审计 | `EVIDENCE_REQUIRED` / `EVIDENCE_INVALID` ⇒ 按形状补;`NORM_DIGEST_REQUIRED` / `NORM_STALE` ⇒ 先 `norm_get {norm:"card-update"}` 再回填 | FR-94 / FR-50 |
37
+ | **S5** | 回填进度 + 证据 | `card_progress` · `card_evidence_submit` | `contract_version` 一致 + `norm_digest` 一致 | 每条进展带**可核验证据**(`file` / `command` / `url` / `reading`),不是「已完成」三个字;`in_review` 前必须有证据 | 评论(`【MCP 证据】hash=…`)+ 审计 | `EVIDENCE_REQUIRED` / `EVIDENCE_INVALID` ⇒ 按形状补;`NORM_DIGEST_REQUIRED` / `NORM_STALE` ⇒ 先 `norm_get {norm:"card-update"}` 再回填 | FR-94 / FR-50 |
38
38
  | **S6** | 需求变更 | `requirement_change` | 影响面已计算(`affected_cards`) | 先预览拿 `change_id`,确认影响面后带 `change_id` + `apply:true` 才落地;`done` 卡**不自动重开** | `governance_audit`(`requirement-change`,带 `reason`) | `CHANGE_NEEDS_APPROVAL` ⇒ 忘了先预览;`CHANGE_ID_MISMATCH` ⇒ 条目在预览后被改过,重新预览;`CHANGE_REASON_REQUIRED` ⇒ 补理由 | FR-39 / FR-100 |
39
39
  | **S7** | 验收收口(人) | 看板「完成」/ 人点 | 评审门 `review_state==='approved'`(或显式 `skipReview`) | `in_review → done` **只由人**;执行侧写 `done` 一律被拒 | `governance_audit`(`actor=human`) | `REVIEW_NOT_APPROVED` ⇒ 先评审通过;`GOVERNANCE_AGENT_DONE` ⇒ 这不是执行侧该做的事 | FR-83 / FR-99 |
40
40
  <!-- /flow-block:steps -->
@@ -84,6 +84,6 @@ requires_contract: v1
84
84
  | --- | --- |
85
85
  | [`references/steps/S0.md`](./references/steps/S0.md) … [`S7.md`](./references/steps/S7.md) | 每步的详细做法、命令示例、判据读数长什么样 |
86
86
  | [`references/errors.md`](./references/errors.md) | 错误码 → 该做什么(含"别重试同一请求"的那些) |
87
- | [`references/injection.md`](./references/injection.md) | 三档装载的细节 + 分层注入策略(档 C 预埋,未启用) |
87
+ | [`references/injection.md`](./references/injection.md) | 三档装载的细节 + 分层注入策略(档 C 已实现·默认 `off`) |
88
88
  | `spec/norms/flow.md` | 机器版主流程(运行时唯一真源,随包;`norm_get { norm:"flow" }`) |
89
89
  | `spec/norms/card-update.md` | 卡片更新规范(`card_progress` 的 `norm_digest` 就取它) |