taskboard-workbench 0.3.3 → 0.3.5

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/CHANGELOG.md CHANGED
@@ -6,6 +6,81 @@
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.5] - 2026-11-17
10
+
11
+ > 主题:**把「派给谁、谁在跑、跑完记在哪」这条链在界面上闭合成可读的事实** —— 执行会话从「认得出卡」
12
+ > 进到「认得出它属于哪个项目」,派发从「一律新建」改为「优先复用已绑定空闲会话」,
13
+ > 执行记录从散落字段收成抽屉里的一个聚合段;另修四条团队执行期实测出来的缺陷
14
+ > (撤单不解阻塞 / 诊断不复检 / 零心跳且状态分叉 / 尝试摘要读不到执行方结论)。
15
+ > 版号续走 `0.3.x` patch(`0.4.0` 仍留给计划文档里预留的确认层 `acceptance_state`)。
16
+ > 读数:`node --test` **1375 / 0** · `release-precheck` **EXIT=0** · tarball **89** 文件。
17
+
18
+ ### 新增
19
+
20
+ - **执行会话绑定态(卡 `-263` / 需求 `R187`)** —— 认领 / 启动执行写下的 `tasks.session_id` 此前只进 `tasks`,
21
+ 不进 `project_sessions`,于是执行会话打开工作台被 FR-63 绑定门**整视图挡住**。
22
+ 新增派生绑定:会话被某张在办卡引用 ⇒ `bound=true · role=executor · derived=true`,并**按任务所属项目**解析归属
23
+ (不被会话 cwd 带偏);任务终态后同一会话自动回到 `bound=false`。显式批准仍压过派生。
24
+ `/api/projects/:id/sessions` 的 `executors` 只列派生项,不与主会话 / 已批准重复。
25
+ - **派发目标选取(卡 `-264` / 需求 `R188`)** —— 「启动执行」不再一律新建会话:主会话空闲 ⇒
26
+ `mode=reuse-bound`(**零新建**、任务书明写「不需要再申请关联」、且**不冒充批准**写授权行);
27
+ 全部在跑 ⇒ 新建并同步落 `approved` 授权 + 审计 `authorize-exec-session(execute-click)`。
28
+ 判不准不猜(`live=false` ⇒ 新建并标 `why=liveness-unknown`);跨工作区排除;投递失败**回落**且如实标 `fallbackReason`。
29
+ 预览端点纯只读(`createSession/sendPrompt/openSession` 全 0)。
30
+ - **抽屉「执行记录」聚合段(卡 `-258` / `-268` / 需求 `R184`)** —— `task_evidence` 四节证据、最近一次尝试、
31
+ 产物清单收成一个段,不再散落在抽屉第 7 段与记账文案里。
32
+ - **团队任务 ↔ 看板卡只读映射(卡 `-247` / 需求 `R178` ④)** —— `team_tasks` 与 `.agent-teams` 此前零桥接,
33
+ 两套任务系统只能靠人脑对应;新增只读映射,每张卡可反查团队任务编号。
34
+ - **批量生成任务补全卡片详情(卡 `-273` / 需求 `R189`)** —— 「批量生成任务」此前只产出标题,卡片不可执行。
35
+ 现按规范 07 装配正文(acceptance 透传 + 七段骨架兜底),并配套 `tools/backfill-split-detail.mjs` 回填存量。
36
+
37
+ ### 变更
38
+
39
+ - **`taskboard_update_status` 状态取值统一英文枚举(卡 `-262` / 需求 `R186`)** —— 工具描述写中文
40
+ (待验收 / 受阻 / 取消),实现只认英文枚举,二者对不上时调用方按描述写必然被拒。描述、参数、报错、下发文案四处口径统一。
41
+ - **`README` 的 DSH 版本要求与 `engines` 对齐** —— 旧文案停留在 `0.2.0-rc.2`,`engines.dsh` 已是 `>=0.2.1-rc.3`。
42
+
43
+ ### 修复
44
+
45
+ - **撤单解除依赖阻塞(卡 `-253` / 需求 `R181`)** —— `isTaskReady` 只认 `done`,前置撤单后下游**永久受阻**,
46
+ 且无任何入口能解。现 `canceled` 视为不再阻塞。
47
+ - **诊断复检与假阳性收敛(卡 `-248` / 需求 `R178` ⑤)** —— 诊断只增不减(全库 `review_deadlock` 未解决 25 条,
48
+ 修复后仍 open)、且 heartbeat 为空即判停滞(5 张产物齐全的卡被误报)。现修复后自动重扫并 resolve;
49
+ 停滞判据先查 `changedPaths` / 产物是否存在再报。
50
+ - **执行期心跳与在途 run 闭合(卡 `-260` / `-269` / 需求 `R185`)** —— 实测「22 分 51 秒只有 1 次心跳」,
51
+ 且卡已进待验收而尝试仍显示「进行中 3 分 55 秒」。现周期心跳,进入 `in_review` 即闭合在途 run。
52
+ - **尝试摘要承载执行方结论(卡 `-259` / 需求 `R184`)** —— 摘要此前写死记账文案,读不出执行者说了什么;
53
+ 现承载真实结论,缺省显式标「执行方未回写摘要」。
54
+
55
+ ### 工具
56
+
57
+ - `tools/audit-data-norms.mjs` —— 条目 / 卡片骨架、长度、流程可见性**只读**核查(四个项目通用)。
58
+ - `tools/bench-session-binding.mjs` —— 执行会话绑定态 13 项,临时 dataDir + 随机端口 + 真 HTTP,不起浏览器。
59
+ - `tools/bench-dispatch-target.mjs` —— 派发目标选取 29 项,含记录型假宿主通道与 `TB_BENCH_DISPATCH_REVERSE` 反证入口。
60
+ - `tools/bench-exec-record.mjs` —— 抽屉执行记录聚合段(真 headless Chrome)。
61
+
62
+ ## [0.3.4] - 2026-11-12
63
+
64
+ > 主题:**把「谁来执行、由谁记账」这条口径钉死** —— CLI 执行者不再由看板自己 spawn,而是把确切的命令、
65
+ > 回写要求与红线交给**项目主会话**,卡片反馈回到同一个会话里,交付记录不再散落在看板进程;
66
+ > 外加一条 owner 与角色错配的诊断。
67
+ > 版号走 `0.3.x` patch(`0.4.0` 仍留给计划文档里预留的确认层 `acceptance_state`)。
68
+ > 读数:`node --test` **1245 / 0** · `release-precheck` **EXIT=0** · tarball **87** 文件。
69
+
70
+ ### 变更(行为口径)
71
+
72
+ - **CLI 执行改走项目主会话下发并跟踪(卡 `-257` / 需求 `R183`)** —— 除 dsh 宿主会话直接执行外,
73
+ 其他非绑定会话的 agent 执行者(claude / codex / hermes 等)一律交由**项目主会话**下发并跟踪,卡片任务反馈由主会话回写;
74
+ `/exec-cli` **默认不再 spawn**,改为投递一条含「哪张卡 / 确切命令 / 四节回写要求 / 不得置 done 的红线」的指令。
75
+ 三条边界:投递失败**不回落**直跑(如实回 `delivered:false`)· 无宿主回落直跑时**必在卡上留痕**「执行记录不在任何会话里」·
76
+ `direct:true` 保留为显式出口。卡 `session_id` 绑主会话 ⇒ **「打开执行会话」直达记录所在会话**。
77
+
78
+ ### 新增
79
+
80
+ - **owner 与角色错配诊断(卡 `-246` / 需求 `R178` ③)** —— owner 是自由文本,「执行卡被写成审查/规划岗」此前只能人肉发现。
81
+ 新增诊断 `owner-role-mismatch`(**medium**,只诊断不拦截,首选动作=改绑负责人)。
82
+ 判据**实测收窄**:宽口径在真机 4/4 误报 ⇒ 只认带 `kind/work` 标记的卡;真机 301 卡命中 0。
83
+
9
84
  ## [0.3.3] - 2026-11-12
10
85
 
11
86
  > 主题:**把「团队执行时缺的那几条路」补齐,并让两个宿主看见同一份库** —— 双宿主对齐(写者租约 + 数据目录自证)、
package/README.md CHANGED
@@ -69,7 +69,7 @@ node cli/tb.mjs project list # 或用 CLI 直接操作
69
69
  | 项 | 值 |
70
70
  | --- | --- |
71
71
  | Node.js | `>= 22.5.0`(依赖 `node:sqlite`) |
72
- | DSH | `0.2.0-rc.2` 线真机验证通过(`0.2.1-alpha.1` 历史走通) |
72
+ | DSH | `>=0.2.1-rc.3`(与 `package.json#engines.dsh` 一致);`0.2.2-rc.3` 真机验证通过 |
73
73
  | 运行时依赖 | 无(`dependencies` 为空) |
74
74
 
75
75
  ## 快速上手(CLI)
package/index.js CHANGED
@@ -669,6 +669,16 @@ export function apply(ctx, config) {
669
669
  } catch (error) {
670
670
  console.error(`[taskboard-workbench] run reconcile error: ${error?.message ?? error}`);
671
671
  }
672
+ // 卡 `-260`(R185):**经主会话下发的执行也打心跳**。
673
+ // `-257` 之后 CLI 执行器默认交项目主会话下发,服务端没有本地进程可挂心跳 —— 真机 `-248`
674
+ // 一条 22 分 51 秒的成功尝试 `heartbeats` 恒为 1。这里每拍(30s)只给「绑定的会话确实在跑
675
+ // (running / 有待消费消息)」的尝试打一拍,会话空闲则一拍都不打(不臆造)。
676
+ try {
677
+ const beat = runtime.store.heartbeatDispatchedRuns();
678
+ if (beat.length) console.log(`[taskboard-workbench] heartbeat ${beat.length} 张在途卡(主会话执行中)`);
679
+ } catch (error) {
680
+ console.error(`[taskboard-workbench] dispatched heartbeat error: ${error?.message ?? error}`);
681
+ }
672
682
  for (const project of listLoopProjects(runtime.store)) {
673
683
  runExecutionLoop({ store: runtime.store, events: runtime.events, projectId: project.id })
674
684
  .then((r) => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "taskboard-workbench",
3
- "version": "0.3.3",
3
+ "version": "0.3.5",
4
4
  "type": "module",
5
5
  "description": "agent team 任务工作台:零依赖核心(node:sqlite)+ CLI + 本地 Web 看板 + DSH 内嵌插件",
6
6
  "license": "MIT",
@@ -155,6 +155,24 @@
155
155
 
156
156
  **分域后仍不变的红线**:无论走哪条路 —— `done` 只能由人确认(执行侧可写 `in_progress` / `in_review` / `blocked` / `canceled`);`backlog` 不得开工;审查未过不解锁下游。
157
157
 
158
+ ### 8.2 团队任务 ↔ 看板卡映射(2026-11-12 · 只增不改 · 卡 `-247`)
159
+
160
+ **两套账本,各自记各自的**(本节只声明关系,不改任何一条既有定义):
161
+
162
+ | 侧 | 真源 | 与看板卡的关联 |
163
+ | --- | --- | --- |
164
+ | 工作台本地 | `team_runs` / `team_members` / `team_tasks` | `team_tasks.task_id → tasks(id)`(**真外键**) |
165
+ | 承载环境 agent-team 插件 | 工作区 `.agent-teams/<team>/team.json` | **无卡号字段**;卡号只以自由文本出现在任务描述/产出里 |
166
+
167
+ **本仓库提供的桥是「只读同步器」**(`src/core/team-bridge.mjs`):请求时现读 `.agent-teams/*/team.json`,用「**项目自有卡号在团队任务文本里全词命中**」推导卡 ↔ `t-id`,并回带**命中字段与片段**(`GET /api/projects/:id/team-bridge`;单卡反查在 `GET /api/tasks/:ref/team` 的 `bridge` 段)。
168
+
169
+ **四条硬口径**:
170
+
171
+ 1. **只读**:不写 `team_tasks`、不改 `.agent-teams/**`、不改 schema、不动历史数据;推导结果**不入库**(没有第二份真源,也就没有漂移)。
172
+ 2. **不写库的理由**:本地侧 `team_tasks` 挂着活跃锁(同一卡只允许一个活跃团队任务)⇒ 把插件团队写进去会把看板侧对**同一张卡**的合法派发挡成 `TASK_LOCKED`;且插件的 `completed` ≠ 看板的 `done`(后者只能人确认)⇒ 状态映射必然带歧义。
173
+ 3. **推导不是登记**:插件任务没有卡号字段 ⇒ 这是**文本反查**,不是真外键。界面与回包都如实标注「只读推导 + 命中字段」,**不冒充真登记**。
174
+ 4. **命中不到就明说**:反查不到 ⇒ 明文声明「**看板只展示、不参与团队状态**」—— 看板侧状态与团队侧状态互不影响,**看板的「完成」仍只能由人确认**。**不写**「没有团队在跑」(那是猜)。
175
+
158
176
  ---
159
177
 
160
178
  ## 九、智能体操作规范(随包)
@@ -0,0 +1,90 @@
1
+ /**
2
+ * CLI 执行器 · **经项目主会话下发**的指令构造(需求 `R183` / 卡 `-257`)。
3
+ *
4
+ * 背景(2026-11-12 真机 `-246`):服务端直接 `spawn claude -p` 时,执行过程与该会话无关 ——
5
+ * 人点「打开执行会话」只看得到项目主会话、里面一条记录都没有,`task_runs` 也只有
6
+ * `actor=cli-executor`、磁盘上更没有任何输出。用户拍板的口径由此而来:
7
+ *
8
+ * **除「DSH 宿主会话」直接执行外,其他 agent 执行者一律交给项目主会话下发并跟踪,
9
+ * 卡片的任务执行反馈也由主会话回写。**
10
+ *
11
+ * 所以这里生成的不是"给 CLI 的任务书"(那个是 `buildTaskPrompt`),而是**给主会话的派单指令**:
12
+ * 确切命令 + 回写要求 + 红线,三样都得写在正文里,否则主会话要么自己重写任务书(漂移),
13
+ * 要么跑完不写卡(看板又变成黑盒)。
14
+ */
15
+
16
+ /** 看板 API 基址(与 `kickoff.mjs` 的 `SETTINGS_BASE` 同一口径:DSH 内嵌命名空间)。 */
17
+ export const TB_API_BASE = "http://127.0.0.1:3080/integrations/taskboard-workbench";
18
+
19
+ /** 单引号包裹并转义 —— 命令里出现中文/空格/特殊符号时也能安全粘进 shell。 */
20
+ function shq(value) {
21
+ const s = String(value ?? "");
22
+ return `'${s.replaceAll("'", `'\\''`)}'`;
23
+ }
24
+
25
+ /**
26
+ * 拼出主会话要执行的那条 shell 命令。
27
+ *
28
+ * 两种投递形态(与 `executors.mjs` 的 `promptVia` 一一对应):
29
+ * - `stdin`(claude / codex):任务书走 heredoc,避免超长命令行;
30
+ * - `argv`(hermes `-z <prompt>`):任务书已经在参数里(`buildExecutorArgs` 拼好的),不再重复投递。
31
+ */
32
+ export function buildCliCommand({ plan }) {
33
+ const cli = plan?.cli ?? "";
34
+ const args = Array.isArray(plan?.args) ? plan.args : [];
35
+ const base = [cli, ...args].join(" ");
36
+ if (plan?.promptVia === "argv") return base;
37
+ const delim = `TB_PROMPT_${Math.random().toString(36).slice(2, 8).toUpperCase()}`;
38
+ return `${base} <<'${delim}'\n${plan?.prompt ?? ""}\n${delim}`;
39
+ }
40
+
41
+ /**
42
+ * 给项目主会话的派单指令。
43
+ *
44
+ * @param {object} input
45
+ * @param {object} input.task 任务卡(`identifier` / `title` / `acceptance` / `verifyCommand`)
46
+ * @param {object|null} input.project 项目(`workspacePath` 用作工作目录)
47
+ * @param {object} input.executor 执行者(`id` / `role`)
48
+ * @param {object} input.plan 执行计划(`cli` / `args` / `cwd` / `promptVia` / `prompt`)
49
+ * @param {string} input.apiBase 看板 API 基址(回写用)
50
+ */
51
+ export function buildMainSessionCliPrompt({ task, project, executor, plan, apiBase = TB_API_BASE }) {
52
+ const cwd = plan?.cwd ?? project?.workspacePath ?? "(未设置工作目录)";
53
+ const command = buildCliCommand({ plan });
54
+ const ref = task?.identifier ?? "";
55
+ const acceptance = String(task?.acceptance ?? "").trim();
56
+ const verify = String(task?.verifyCommand ?? "").trim();
57
+ return [
58
+ `# 派单:${ref} 由你(项目主会话)用 ${executor?.id ?? "CLI"} 执行并回写`,
59
+ ``,
60
+ `看板把这张卡交给**本会话**下发跟踪 —— 请**在这里**跑下面的命令,让执行记录留在本会话里,`,
61
+ `不要转手丢到别处静默跑完。`,
62
+ ``,
63
+ `## 这是哪张卡`,
64
+ `- 编号:${ref}`,
65
+ `- 标题:${task?.title ?? "(无标题)"}`,
66
+ acceptance ? `- 验收:${acceptance}` : `- 验收:(该卡未写验收标准 —— 跑完在证据里如实说明)`,
67
+ verify ? `- 复核动作:${verify}` : `- 复核动作:(沿用项目设置)`,
68
+ ``,
69
+ `## 执行命令(工作目录 ${cwd})`,
70
+ "```bash",
71
+ command,
72
+ "```",
73
+ ``,
74
+ `## 跑完之后(三件都做,缺一不合格)`,
75
+ `1. 把**四节证据**写进卡片(判定 / 偏离说明 / 边界自查 / 产物路径):`,
76
+ ` \`POST ${apiBase}/api/tasks/${ref}/evidence\``,
77
+ ` body 至少含 \`verdict\` \`deviation\` \`boundary\` \`artifacts\` 四个字段,\`actor\` 写 \`agent\`。`,
78
+ ` 若你有任务工作台的 MCP 工具,用 \`card_evidence_submit\`(同一道门、同一套错误码)。`,
79
+ `2. 把卡提交「待验收」:\`POST ${apiBase}/api/tasks/${ref}/execution/review\``,
80
+ `3. 失败就 \`POST ${apiBase}/api/tasks/${ref}/execution/fail\`,并在 body 里写清原因与错误尾段。`,
81
+ ``,
82
+ `## 红线`,
83
+ `- **不得置 done**(完成只能人点);`,
84
+ `- 不 commit、不 push、不改历史决策文档、不删既有数据;`,
85
+ `- 命令退出码非 0 或零改动时,照实写进证据,不要美化成"完成"。`,
86
+ ``,
87
+ `## 回报`,
88
+ `做完在本会话回一句:退出码 / 改了哪些文件 / 卡片当前状态。`,
89
+ ].join("\n");
90
+ }
@@ -14,7 +14,7 @@ import { BLOCK_RECURRENCE_LIMIT, DEFAULT_FAILURE_LIMIT, QUOTA_AUTH_ERROR_RE } fr
14
14
  import { STALL_THRESHOLD_MS, assessTask, latestProgressComment, runInFlight } from "./watchdog.mjs";
15
15
  import { REVIEW_IDLE_MS, detectReviewDeadlock } from "./review.mjs";
16
16
  import { categoryLabel, classifyHumanReview, isHumanReviewTask } from "./human-review.mjs";
17
- import { detectUntakenDelivery } from "./delivery.mjs";
17
+ import { detectUntakenDelivery, isConclusionComment } from "./delivery.mjs";
18
18
 
19
19
  /** 诊断类型(FR-79 验收里逐个点名的八类规则)。 */
20
20
  export const DIAGNOSTIC_KINDS = Object.freeze([
@@ -23,6 +23,8 @@ export const DIAGNOSTIC_KINDS = Object.freeze([
23
23
  "human_review_required",
24
24
  // 2026-10-22 补口:把「投递到会话但没交作业」从**静默回收**变成**可见 + 有恢复动作**。
25
25
  "delivery_untaken",
26
+ // 卡 `-246`(需求 `R178` ③):owner 是自由文本 ⇒「执行卡被写成审查/规划岗」这类越位只能人肉发现。
27
+ "owner-role-mismatch",
26
28
  ]);
27
29
 
28
30
  /** 严重度取值;high 最重(UI 用它排序与着色)。 */
@@ -185,8 +187,14 @@ function commonActions(ctx, { retryLabel = "退回待办(重新派发)", ret
185
187
  ];
186
188
  }
187
189
 
188
- /** 人工忽略留痕标记:`已忽略诊断「<kind>」…`(FR-79「忽略即消解且保留原文可回溯」)。 */
189
- const DISMISS_RE = /已忽略诊断[「"]?([a-zA-Z_]+)/;
190
+ /**
191
+ * 人工忽略留痕标记:`已忽略诊断「<kind>」…`(FR-79「忽略即消解且保留原文可回溯」)。
192
+ *
193
+ * 2026-11-12(卡 `-246`):字符类补上 `-` —— 新诊断 kind `owner-role-mismatch` **带连字符**,
194
+ * 原 `([a-zA-Z_]+)` 只会截到 `owner`,于是「忽略此项」写了留痕却压不住这条诊断(静默失效)。
195
+ * 既有 kind 全是 `[a-z_]+`,补 `-` 不改变它们的行为。
196
+ */
197
+ const DISMISS_RE = /已忽略诊断[「"]?([a-zA-Z_-]+)/;
190
198
 
191
199
  /**
192
200
  * 已被人工忽略的诊断类型(且忽略发生在最近一次进展之后)。
@@ -228,6 +236,167 @@ function evidenceText(e) {
228
236
  try { return JSON.stringify(e); } catch { return String(e); }
229
237
  }
230
238
 
239
+ // ---------------------------------------------------------------------------
240
+ // owner 与角色错配(卡 `-246` · 需求 `R178` ③)
241
+ // ---------------------------------------------------------------------------
242
+
243
+ /**
244
+ * owner 的角色词表(沿用团队编制口径:`src/core/team.mjs#TEAM_ROLES` 与 `web/app.js#OWNER_LABELS`)。
245
+ *
246
+ * owner 是**自由文本**(早期靠 `owner:<role>` 标签承载,见 `core/owner.mjs`),所以归一必须容忍
247
+ * 「开发 engineer」这类「中文 + 英文」写法,也不能把 `codex` / `agent-team:claude-cli` 当成角色。
248
+ */
249
+ export const OWNER_ROLE_TOKENS = Object.freeze([
250
+ "lead", "planner", "engineer", "tester", "reviewer", "archivist",
251
+ ]);
252
+
253
+ /**
254
+ * **不执行**的角色(卡 `-246` 任务书点名):规划 / 审查 / 归档。
255
+ * 执行岗是 `engineer`(开发)与 `tester`(测试)。
256
+ */
257
+ export const NON_EXECUTING_OWNER_ROLES = Object.freeze(["planner", "reviewer", "archivist"]);
258
+
259
+ /** 角色词 → 人读标签(与前端 `OWNER_LABELS` 同口径;core 不能引 web,故各存一份)。 */
260
+ export const OWNER_ROLE_LABELS = Object.freeze({
261
+ lead: "队长 lead", planner: "规划 planner", engineer: "开发 engineer",
262
+ tester: "测试 tester", reviewer: "评审 reviewer", archivist: "归档 archivist",
263
+ });
264
+
265
+ /**
266
+ * 看板自己的**卡类型标记**(`tasks` 表没有 kind 列,落在 labels 上 —— 见 store.mjs 分拆落库处):
267
+ * · `kind/work` = 工作项(要派出去执行/落地)
268
+ * · `kind/review` = 审查项(审别人的活)
269
+ */
270
+ export const CARD_KIND_WORK_LABEL = "kind/work";
271
+ export const CARD_KIND_REVIEW_LABEL = "kind/review";
272
+
273
+ /**
274
+ * owner → 角色词(纯函数)。取**首个命中**的角色词;命不中返回 `null`(自由文本不判角色)。
275
+ *
276
+ * 词边界匹配(而非子串):`reviewer` 不能被 `review` 命中、`codex` 不能被 `code` 命中。
277
+ * 「首个命中」按 `OWNER_ROLE_TOKENS` 的顺序(与团队编制表一致),含多个词时**保守取先出现的**。
278
+ */
279
+ export function ownerRole(owner) {
280
+ const text = String(owner ?? "").trim().toLowerCase();
281
+ if (text === "") return null;
282
+ for (const token of OWNER_ROLE_TOKENS) {
283
+ if (new RegExp(`(?:^|[^a-z])${token}(?:[^a-z]|$)`).test(text)) return token;
284
+ }
285
+ return null;
286
+ }
287
+
288
+ /**
289
+ * 这张卡**是不是执行类**(纯函数)。
290
+ *
291
+ * 判据:卡带看板自己的卡类型标记 `kind/work`,且没有 `kind/review`(两者同时出现=数据自相矛盾,不判)。
292
+ *
293
+ * **为什么不靠标题/描述猜**:看板没有别的字段能区分「要落地的执行卡」与「规划/文档卡」——
294
+ * 两者在 owner 上都可能是 planner。2026-11-12 真机库实测(`.data/taskboard.sqlite`,299 张卡):
295
+ * 宽判据「在途 + owner∈{planner,reviewer,archivist}」命中 4 张,**4/4 全是误报**
296
+ * (`scada-vibe-3/4/6/12` 全是 planner 的正经规划卡:需求条款化 / 条款迁移 / 决策单 / 需求补条)。
297
+ * ⇒ 按卡 `-246`「历史卡大面积误报 ⇒ 停,改判据」的处置,判据收窄到**看板自己有类型标记**的卡。
298
+ */
299
+ export function isExecutionClassCard(task) {
300
+ const labels = Array.isArray(task?.labels)
301
+ ? task.labels.map((l) => String(l ?? "").trim().toLowerCase())
302
+ : [];
303
+ if (!labels.includes(CARD_KIND_WORK_LABEL)) return false;
304
+ if (labels.includes(CARD_KIND_REVIEW_LABEL)) return false;
305
+ return true;
306
+ }
307
+
308
+ // ---------------------------------------------------------------------------
309
+ // 交付产物事实(卡 `-248` · 需求 `R178` ⑤ ·「heartbeat 空先查产物」)
310
+ // ---------------------------------------------------------------------------
311
+
312
+ /**
313
+ * 「卡上已有交付产物」的**评论侧标记**(看板自己的交付约定)。
314
+ *
315
+ * 为什么必须有评论这一路:真机(`scada-vibe-1…7`)的活是**宿主 agent team** 干的 ——
316
+ * 它只往卡上贴评论,**不写 `task_evidence`**(FR-106 的结构化证据行是 MCP/HTTP 入口才写的),
317
+ * **也不建 `task_runs` 尝试记录**(那条路不建尝试)。只认结构化证据 + 成功尝试 ⇒ 真机那批卡照样
318
+ * 被判「停滞 / 无人认领」—— 这正是需求条目 `R178` ⑤ 说的「判据只看 heartbeat / reviewer 空,
319
+ * 不看产物是否存在(真机:5 卡 `stalled`+`unclaimed` 高危 10 条,产物齐全)」。
320
+ *
321
+ * 标记只取「**交付动作**」与「**交付声明**」两类,刻意避开两类会误伤的说法:
322
+ * · 不取 `进度` / `反馈` 等**过程**词 —— 过程汇报不代表产物齐全;
323
+ * · 不取裸词 `产出` —— 看板自己的系统留痕「…将产出「评审死锁」诊断。」含这两个字。
324
+ */
325
+ export const ARTIFACT_COMMENT_MARKERS = Object.freeze([
326
+ "请求评审", // 「**请求评审(执行侧)**。产出:`…`」—— 交付动作本身
327
+ "人工验收", // 「请求人工验收」/「请人工验收」
328
+ "复审通过", // 「**复审通过,请求人工验收**」
329
+ "产出:", // 「产出:`路径`」—— 显式声明产物(带全角冒号,避开系统留痕里的「产出「」)
330
+ "证据(四节)", // 本仓四节交付格式
331
+ "证据回流",
332
+ "【证据",
333
+ "## 证据",
334
+ ]);
335
+
336
+ /**
337
+ * 交付产物事实查询(**只读**、纯判定、零写库)。
338
+ *
339
+ * 回答一个问题:**这张卡的活到底干了没有?** 三个来源,任一成立即视为「产物已交」:
340
+ * ① 结构化交付证据(FR-106 `task_evidence`:判定/偏离/边界/产物 四字段齐 + artifact_refs)——最硬;
341
+ * ② 成功尝试记录(`task_runs.outcome === "success"`)—— 执行器交了作业;
342
+ * ③ 交付证据评论(看板自己的交付约定,见 `ARTIFACT_COMMENT_MARKERS`)。
343
+ *
344
+ * **返工作废**:产物之后又出现「返工」事件(`changes_requested`)⇒ 那一版产物已被判不合格,
345
+ * 不再算数 —— 否则「返工之后没人接着干」这种**真停滞**会被吞掉(宁可假阳性不可漏报)。
346
+ *
347
+ * @returns {{delivered: boolean, at: string|null, source: string|null, summary: string, revoked: boolean}}
348
+ */
349
+ export function deliveredArtifacts(store, task, { comments = [], runs = [] } = {}) {
350
+ const empty = { delivered: false, at: null, source: null, summary: "", revoked: false };
351
+ if (!task) return empty;
352
+ const candidates = [];
353
+
354
+ // ① 结构化交付证据(FR-106)
355
+ try {
356
+ const ev = typeof store?.latestTaskEvidence === "function" ? store.latestTaskEvidence(task.identifier) : null;
357
+ if (ev && Array.isArray(ev.artifacts) && ev.artifacts.length > 0) {
358
+ candidates.push({ source: "evidence", at: ev.createdAt ?? null, summary: `结构化交付证据(${ev.artifacts.length} 项产物)` });
359
+ }
360
+ } catch { /* 取不到就当没有 */ }
361
+
362
+ // ② 成功尝试记录(执行器交了作业)
363
+ for (const run of Array.isArray(runs) ? runs : []) {
364
+ if (String(run?.outcome ?? "") !== "success") continue;
365
+ candidates.push({ source: "run-success", at: run.endedAt ?? run.startedAt ?? null, summary: `第 ${run.attempt ?? "?"} 次尝试执行成功` });
366
+ }
367
+
368
+ // ③ 交付证据评论(agent team / 人工贴证据走评论路径)
369
+ for (const c of Array.isArray(comments) ? comments : []) {
370
+ const body = String(c?.body ?? "");
371
+ if (!body) continue;
372
+ if (!isConclusionComment(body)) continue; // 系统留痕不是产物
373
+ if (!ARTIFACT_COMMENT_MARKERS.some((m) => body.includes(m))) continue;
374
+ candidates.push({ source: "delivery-comment", at: c?.createdAt ?? null, summary: "交付证据评论" });
375
+ }
376
+
377
+ if (!candidates.length) return empty;
378
+ const atOf = (c) => { const t = Date.parse(String(c.at ?? "")); return Number.isFinite(t) ? t : -Infinity; };
379
+ // 取**最近**的一份产物(返工判据要跟最新那份对齐)
380
+ const latest = candidates.reduce((a, b) => (atOf(b) > atOf(a) ? b : a));
381
+
382
+ // 返工作废:产物之后出现返工 ⇒ 那一版产物已被判不合格,不再算数
383
+ let reworkAt = -Infinity;
384
+ try {
385
+ const events = typeof store?.listTaskEvents === "function" ? store.listTaskEvents(task, { order: "desc", limit: 200 }) : [];
386
+ for (const e of Array.isArray(events) ? events : []) {
387
+ if (String(e?.type ?? "") !== "changes_requested") continue;
388
+ const t = Date.parse(String(e?.at ?? ""));
389
+ if (Number.isFinite(t) && t > reworkAt) reworkAt = t;
390
+ }
391
+ } catch { /* 取不到就当没返工 */ }
392
+
393
+ // 返工作废:产物之后出现返工 ⇒ 那一版产物已被判不合格,不再算数。
394
+ // 用 `>=` 而不是 `>`:返工与交付**可能落在同一毫秒**(评审 → 打回 → 立刻重投都是进程内连写),
395
+ // 用 `>` 会把「同一毫秒的返工」漏判成「产物仍有效」⇒ 真停滞被吞掉(宁可假阳性不可漏报)。
396
+ const revoked = Number.isFinite(reworkAt) && reworkAt >= atOf(latest);
397
+ return { delivered: !revoked, at: latest.at ?? null, source: latest.source, summary: latest.summary, revoked };
398
+ }
399
+
231
400
  export const DIAGNOSTIC_RULES = Object.freeze([
232
401
  {
233
402
  kind: "block_loop",
@@ -256,6 +425,12 @@ export const DIAGNOSTIC_RULES = Object.freeze([
256
425
  const { task, watchdog, dismissed } = ctx;
257
426
  if (dismissed.has("stalled")) return null;
258
427
  if (watchdog?.state !== "stalled") return null;
428
+ // 卡 `-248`(需求 `R178` ⑤ ·「heartbeat 空先查产物」):
429
+ // 「疑似停滞 N 分钟**无进展回报**」的前提是**没交过活**。若卡上已有交付产物(结构化证据 /
430
+ // 成功尝试 / 交付证据评论),那个前提不成立 ⇒ 不报。
431
+ // 不报还有一层安全理由:本诊断的首选动作是「退回待办(重新派发)」,对一张**已经交过活**的卡
432
+ // 再派一遍 = 让执行侧把做完的活重做一遍,正是 FR-86 说的同文件双写风险。
433
+ if (ctx.artifacts?.delivered) return null;
259
434
  const enc = encodeRef(task.identifier);
260
435
  const offline = watchdog.reason === "session-offline";
261
436
  return {
@@ -285,6 +460,10 @@ export const DIAGNOSTIC_RULES = Object.freeze([
285
460
  if (sessionState?.running) return null;
286
461
  if (!sessionState?.sessionId && runInFlight(currentRun, { now: ctx.now, thresholdMs: ctx.thresholds?.stallMs })) return null;
287
462
  if (claim?.locked && !claim?.expired) return null;
463
+ // 卡 `-248`(需求 `R178` ⑤ ·「heartbeat 空先查产物」):
464
+ // 本诊断的原文是「…**这条任务事实上没人干**」—— 若卡上已有交付产物,这句话**本身就是假的**
465
+ // (有人干了,只是没续认领 / 没改状态)⇒ 不报。真没产物时照报(宁可假阳性不可漏报)。
466
+ if (ctx.artifacts?.delivered) return null;
288
467
  const why = claim?.locked && claim?.expired ? "认领已过期" : claim?.locked ? "认领心跳陈旧" : "未被执行者认领";
289
468
  return {
290
469
  kind: "unclaimed", severity: "high",
@@ -468,6 +647,52 @@ export const DIAGNOSTIC_RULES = Object.freeze([
468
647
  };
469
648
  },
470
649
  },
650
+ {
651
+ /**
652
+ * 卡 `-246`(需求 `R178` ③):**owner 与角色错配** —— owner 是自由文本,不校验角色,
653
+ * 于是「这张执行卡的 owner 是 review/plan 岗」这类越位只能靠人肉发现。
654
+ *
655
+ * 判据(三条**全部**满足才报):
656
+ * ① **owner 越位**:owner 归一后命中不执行的角色 {planner, reviewer, archivist}
657
+ * (自由文本如 `codex` 不判 —— 判不准就不升级,FR-85 红线)。
658
+ * ② **卡是执行类**:卡带看板自己的卡类型标记 `kind/work`(`kind/review` 的审查卡不判)。
659
+ * ③ **卡在途**:`done` / `canceled` 不再提示 —— 收口卡的历史错配不影响当下。
660
+ *
661
+ * **只诊断、不拦截**(任务书「移出:硬拦截(会误伤历史卡)」):本规则不写库、不改状态、
662
+ * 不阻断建卡与派发,只产出一条 medium 提示 + 两个恢复动作(人工改绑 / 人工忽略)。
663
+ */
664
+ kind: "owner-role-mismatch",
665
+ evaluate(ctx) {
666
+ const { task, dismissed } = ctx;
667
+ if (dismissed.has("owner-role-mismatch")) return null;
668
+ const role = ownerRole(task.owner);
669
+ if (!role || !NON_EXECUTING_OWNER_ROLES.includes(role)) return null;
670
+ if (!isExecutionClassCard(task)) return null;
671
+ if (task.status === "done" || task.status === "canceled") return null;
672
+ const enc = encodeRef(task.identifier);
673
+ const roleLabel = OWNER_ROLE_LABELS[role] ?? role;
674
+ return {
675
+ kind: "owner-role-mismatch", severity: "medium",
676
+ title: `负责人与卡的类型错配:工作项的负责人是「${roleLabel}」`,
677
+ detail: `这张卡标着「工作项(${CARD_KIND_WORK_LABEL})」—— 是要派出去执行/落地的活;`
678
+ + `但负责人(owner)写的是「${roleLabel}」,那是**不执行**的角色(执行岗是 开发 engineer / 测试 tester)。\n`
679
+ + `越位的后果:这条活要么没人认领(owner 指向错岗),要么被当成审查/规划/归档处理。\n`
680
+ + `请人工确认:若确实由执行岗做 → 改绑负责人;若这张卡本来就是审查/规划/归档卡 → 忽略此项(不是缺陷)。`,
681
+ suggested: "reassign_owner",
682
+ actions: [
683
+ action("reassign_owner", "改绑负责人(执行岗 engineer)", {
684
+ kind: "primary", method: "PATCH", path: `/api/tasks/${enc}`,
685
+ body: { owner: "engineer", version: task.version },
686
+ hint: "按项目实际编制改(测试活填 tester);若这张卡本就是审查/规划/归档卡,请改用「忽略此项」。",
687
+ }),
688
+ action("dismiss", "忽略此项(owner 正确 / 卡不是执行卡)", {
689
+ path: `/api/tasks/${enc}/diagnostics/dismiss`, body: { kind: "owner-role-mismatch" },
690
+ hint: "写一条忽略留痕,原文可回溯",
691
+ }),
692
+ ],
693
+ };
694
+ },
695
+ },
471
696
  ]);
472
697
 
473
698
  /** 纯函数:按规则集产出诊断列表(按严重度 → kind 稳定排序)。 */
@@ -603,6 +828,9 @@ export function collectContext(store, task, { now = Date.now(), thresholds = DEF
603
828
  limitSource: limitOverride != null ? "task" : "default",
604
829
  },
605
830
  runs: attempts,
831
+ // 卡 `-248`:「heartbeat 空先查产物」的**前置事实**(只读、零写库)。
832
+ // `stalled` / `unclaimed` 两条规则先看它,再决定要不要报。
833
+ artifacts: deliveredArtifacts(store, task, { comments, runs: attempts }),
606
834
  // FR-83:评审死锁由**真实判定**给出(调用方可显式覆盖,便于单测/回放)
607
835
  review: review === null
608
836
  ? detectReviewDeadlock(store, task, { now, idleMs: thresholds.reviewIdleMs ?? REVIEW_IDLE_MS })
@@ -630,15 +858,43 @@ export function evaluateTaskDiagnostics(store, ref, { now = Date.now(), threshol
630
858
  return { task, diagnostics: saved.active, summary: summarizeDiagnostics(saved.active), resolved: saved.resolved };
631
859
  }
632
860
 
861
+ /**
862
+ * 复检:终态卡(`done` / `canceled`)的遗留诊断**只收口、不新增**(卡 `-248` · 需求 `R178` ⑤)。
863
+ *
864
+ * 为什么单独一个函数、而不是直接 `evaluateTaskDiagnostics`:
865
+ * · 终态卡**不该**再产出任何诊断(`owner-role-mismatch` 等规则本就排除 done/canceled);
866
+ * · 但库里可能留着上一轮 open 的行 —— 诊断是「只增不减」的,那些行会永远挂着。
867
+ * 真机读数(2026-11-12,只读):`scada-vibe-11`(`canceled`)的 `review_deadlock` 仍 open、
868
+ * `count=19`;本仓 6 张 `done` 卡共 11 行 `stalled`/`unclaimed`/`review_deadlock` 仍 open。
869
+ * · 收口走 `saveTaskDiagnostics(ref, [])` —— 与规则产出的诊断**同一张表、同一套字段**,
870
+ * `resolved_at` 留痕、历史可回溯(不删数据)。
871
+ */
872
+ function closeTerminalDiagnostics(store, task, { now } = {}) {
873
+ let open = [];
874
+ try { open = typeof store.listTaskDiagnostics === "function" ? store.listTaskDiagnostics(task) : []; } catch { open = []; }
875
+ if (!open.length) return [];
876
+ try {
877
+ const saved = store.saveTaskDiagnostics(task.identifier, [], { now });
878
+ return saved?.resolved ?? [];
879
+ } catch { return []; }
880
+ }
881
+
633
882
  /**
634
883
  * 项目级诊断:对"可能需要人介入"的任务逐个评估(进行中 / 受阻 / 待验收),
635
884
  * 返回 { rows, summary }。只读路径也可以调用(会同步落库,保证 count 有意义)。
885
+ *
886
+ * 卡 `-248`:**复检** —— 扫描集之外的终态卡(done/canceled)也走一遍,
887
+ * 把它们身上遗留的诊断**收口**(见 `closeTerminalDiagnostics`);这是「诊断只增不减」的正面修法。
636
888
  */
637
889
  export function projectDiagnostics(store, projectId, { now = Date.now(), thresholds = DEFAULT_THRESHOLDS, persist = true } = {}) {
638
890
  const statuses = new Set(["in_progress", "blocked", "in_review"]);
639
- const tasks = store.listTasks({ projectId }).filter((t) => statuses.has(t.status) || t.triageAt);
891
+ const tasks = store.listTasks({ projectId });
640
892
  const rows = [];
641
893
  for (const task of tasks) {
894
+ if (!(statuses.has(task.status) || task.triageAt)) {
895
+ if (persist) closeTerminalDiagnostics(store, task, { now });
896
+ continue;
897
+ }
642
898
  const r = evaluateTaskDiagnostics(store, task, { now, thresholds, persist });
643
899
  for (const d of r.diagnostics) rows.push({ ...d, identifier: task.identifier, title: task.title, status: task.status });
644
900
  }