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
@@ -0,0 +1,86 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * tb-flow.mjs —— 开局装载块(P4 · 档 A / 档 B 的同一个入口)
4
+ *
5
+ * 用法:
6
+ * node scripts/tb-flow.mjs start [--project <id>] [--cwd <dir>] [--json]
7
+ * node scripts/tb-flow.mjs snippet [--project <id>] # 打给项目 AGENTS.md 用的片段
8
+ * node scripts/tb-flow.mjs check # 只自检(不读写库)
9
+ *
10
+ * 数据源:`--data-dir` > `$TB_DATA_DIR` > 默认(与 Web / CLI / MCP 同一份 `taskboard.sqlite`)。
11
+ *
12
+ * **只读**:本脚本不建卡、不改状态、不写评论、不写审计 —— 它只把"现在该干什么"打印出来。
13
+ * 与 MCP prompt `taskboard.flow` 共用 `src/mcp/flow-block.mjs`,输出**逐字节相同**。
14
+ */
15
+ import path from "node:path";
16
+ import { fileURLToPath } from "node:url";
17
+
18
+ import { buildAgentsSnippet, buildFlowBlock, readSkill, SKILL_PATH } from "../src/mcp/flow-block.mjs";
19
+ import { openStore } from "../src/core/store.mjs";
20
+ import { resolveDataDir } from "../src/core/config.mjs";
21
+
22
+ const argv = process.argv.slice(2);
23
+ const has = (name) => argv.includes(name);
24
+ const argOf = (name) => {
25
+ const i = argv.indexOf(name);
26
+ return i >= 0 && i + 1 < argv.length ? argv[i + 1] : null;
27
+ };
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";
29
+
30
+ if (has("--help") || has("-h")) {
31
+ process.stdout.write(`tb-flow · 任务看板开局装载块
32
+ 用法:
33
+ node scripts/tb-flow.mjs start [--project <id>] [--cwd <dir>] [--json] [--data-dir <dir>]
34
+ node scripts/tb-flow.mjs snippet [--project <id>]
35
+ node scripts/tb-flow.mjs check
36
+ 只读脚本:不建卡 / 不改状态 / 不写评论。数据源同 Web/CLI(--data-dir > $TB_DATA_DIR > 默认)。
37
+ `);
38
+ process.exit(0);
39
+ }
40
+
41
+ if (command === "check") {
42
+ const skill = readSkill();
43
+ process.stdout.write(`skill: ${skill.relPath} · name=${skill.meta.name} · version=${skill.meta.version} · requires_contract=${skill.meta.requires_contract}\n`);
44
+ process.stdout.write(`八步段落: ${skill.steps.split("\n").filter((l) => l.startsWith("| **S")).length} 行 · 硬规则: ${skill.rules.split("\n").filter((l) => /^\d+\./.test(l)).length} 条\n`);
45
+ process.exit(0);
46
+ }
47
+
48
+ if (command === "snippet") {
49
+ process.stdout.write(`${buildAgentsSnippet({ project: argOf("--project"), pkgPath: path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..") })}\n`);
50
+ process.exit(0);
51
+ }
52
+
53
+ if (command !== "start") {
54
+ process.stderr.write(`未知子命令:${command}(可用:start / snippet / check)\n`);
55
+ process.exit(2);
56
+ }
57
+
58
+ const dataDir = argOf("--data-dir") ?? resolveDataDir({ env: process.env });
59
+ const store = openStore({ dataDir, env: process.env });
60
+ try {
61
+ const block = buildFlowBlock({ store, project: argOf("--project"), cwd: argOf("--cwd") ?? process.cwd() });
62
+ if (has("--json")) {
63
+ process.stdout.write(`${JSON.stringify({
64
+ project: block.project,
65
+ contract: block.contract,
66
+ gaps: block.gaps,
67
+ nextStep: block.nextStep,
68
+ skill: { ...block.skill, path: SKILL_PATH },
69
+ dataDir: store.dataDir,
70
+ block: block.text,
71
+ }, null, 2)}\n`);
72
+ } else {
73
+ process.stdout.write(block.text);
74
+ process.stderr.write(`[tb-flow] dataDir=${store.dataDir} · 只读 · 与 MCP prompt taskboard.flow 同源\n`);
75
+ }
76
+ } catch (error) {
77
+ process.stderr.write(`${error?.code ?? "ERROR"}: ${error?.message ?? String(error)}\n`);
78
+ if (error?.code === "PROJECT_NOT_FOUND") {
79
+ // 默认数据目录是临时目录 ⇒ 用户几乎总会撞这一下。把「怎么指到真库」直接写出来。
80
+ process.stderr.write(`提示:当前数据目录是 ${store.dataDir}(不含该项目)。看板在别的目录时显式带 --data-dir,例如:\n`);
81
+ process.stderr.write(` node scripts/tb-flow.mjs start --project <id> --data-dir .data\n`);
82
+ }
83
+ process.exit(error?.code === "PROJECT_NOT_FOUND" ? 3 : 1);
84
+ } finally {
85
+ try { store.close(); } catch { /* ignore */ }
86
+ }
@@ -0,0 +1,89 @@
1
+ ---
2
+ name: taskboard-flow
3
+ version: 1
4
+ updated: 2026-10-29
5
+ applies_to: [dsh-main-session, claude-code, codex, hermes, other-coding-agents]
6
+ requires_contract: v1
7
+ ---
8
+
9
+ # taskboard-flow · 任务看板主流程(八步)
10
+
11
+ > **这一层只教顺序、判据与失败处置,不持有任何业务规则副本。**
12
+ > 数据在 `taskboard.sqlite`,门与错误码在 `src/mcp/`(L2 契约层)与 `src/core/`(L3 内核)。
13
+ > 机器规范(唯一真源,随包):`spec/norms/*.md` —— 用 `norm_get` 取正文 + `digest`,**不要凭记忆**。
14
+
15
+ ---
16
+
17
+ ## 一句话开局
18
+
19
+ | 档 | 谁用 | 怎么做 | 要不要改宿主 |
20
+ | --- | --- | --- | --- |
21
+ | **A 开局提示词** | 人,在 dsh 主会话里新开一轮工作 | 把 `node scripts/tb-flow.mjs start` 的输出整块贴进会话;或让 MCP 客户端取 prompt `taskboard.flow`(同一个生成器,输出逐字节相同) | ❌ 不用 |
22
+ | **B 外部 agent 约定开局** | Claude Code / Codex 在**项目仓库**里开工 | 项目根 `AGENTS.md` 写一段「开工先跑 `<taskboard>/scripts/tb-flow.mjs start`,把输出当本轮上下文」;片段用 `tb-flow snippet` 打印 | ❌ 不用 |
23
+ | **C 宿主自动注入** | dsh 会话创建即注入 | **未启用**(须报批改 `~/.dsh/**` 并重载宿主)。接口形状已定死,见 [`references/injection.md`](./references/injection.md) | ✅ 须报批 |
24
+
25
+ ---
26
+
27
+ ## 八步(每步六栏:入口 / 前置门 / 判据 / 证据落点 / 失败处置 / 对应 FR)
28
+
29
+ <!-- flow-block:steps -->
30
+ | # | 步骤 | 入口 | 前置门 | 判据 | 证据落点 | 失败处置 | 对应 FR |
31
+ | --- | --- | --- | --- | --- | --- | --- | --- |
32
+ | **S0** | 绑定与对照 | `flow_start` · `project_info` · `workbench_audit` · `tb-flow start` | 会话归属(主会话,或已批准关联的会话) | 拿到 `project` + `contract_version` + `gaps`(未归因卡 / 未绑定主会话 / 待确认候选);**这一步不做任何写操作** | 无(只读) | `PROJECT_NOT_FOUND` ⇒ 先建项目 / 显式带 `project`;`gaps.unboundSession` ⇒ 回看板「重建/绑定主会话」 | FR-91 / FR-99 |
33
+ | **S1** | 需求文档与条目 | `requirement_list` · `requirement_upsert` | 需求文档 digest 与契约一致 | 一条条目**只讲一件事**;`draft` 未确认的条目不得建卡;改条目必须带 `expected_version` | `requirement_items` | `MISSING_VERSION` / `VERSION_CONFLICT` ⇒ 重新 `requirement_list` 拿新 `version` 再提交(**不许覆盖**) | FR-35 / FR-36 |
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
+ | **S3** | 授权开工(人) | 看板「启动执行」/ 人点 | 归因门 → 授权门 | `backlog → todo` 由**人**点;执行侧不得自我授权 | `task_events`(`set-status`,`actor=human`) | 执行侧想推 ⇒ `AUTHORIZATION_REQUIRED`;卡还没归因 ⇒ 先回 S2 | FR-40 / FR-84 |
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 |
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
+ | **S7** | 验收收口(人) | 看板「完成」/ 人点 | 评审门 `review_state==='approved'`(或显式 `skipReview`) | `in_review → done` **只由人**;执行侧写 `done` 一律被拒 | `governance_audit`(`actor=human`) | `REVIEW_NOT_APPROVED` ⇒ 先评审通过;`GOVERNANCE_AGENT_DONE` ⇒ 这不是执行侧该做的事 | FR-83 / FR-99 |
40
+ <!-- /flow-block:steps -->
41
+
42
+ ---
43
+
44
+ ## 随时可用的两个只读入口
45
+
46
+ 八步之外,这两件随时可查、**不改变任何状态**:
47
+
48
+ | 工具 | 什么时候用 | 它回答什么 |
49
+ | --- | --- | --- |
50
+ | `project_info` | 想一眼看项目全貌(S0 之外的中途确认也行) | 任务 / 条目按状态计数 + 契约版本与基线是否漂移 |
51
+ | `workbench_audit` | 怀疑"哪里在漏"时(交接、回归、发版前) | 四类漂移各自多少条:`contract-stale`(谁在用旧契约)/ `unattributed`(未归因卡)/ `unbound-session`(主会话没绑)/ `candidate-flood`(候选超阈值) |
52
+
53
+ > 这两个是**盘点**,不是流程步骤:`workbench_audit.ok === true` 只代表"没有已知漂移",
54
+ > 不代表"该做的事都做完了" —— 后者要看 `flow_start.nextStep`。
55
+
56
+ ---
57
+
58
+ ## 五条硬规则(都由门守,不靠自觉)
59
+
60
+ <!-- flow-block:rules -->
61
+ 1. **`done` 只能人点** —— `card_progress` 写 `done` ⇒ `GOVERNANCE_AGENT_DONE`。
62
+ 2. **`backlog → todo` 是人工授权** —— `card_create` 只接受 `backlog` ⇒ 其它值 `AUTHORIZATION_REQUIRED`。
63
+ 3. **建卡必须归因** —— 无 `requirement` 且无 `unattributed_reason` ⇒ `REQUIREMENT_REQUIRED`。
64
+ 4. **回填必须带证据 + 规范摘要** —— `EVIDENCE_REQUIRED` / `NORM_DIGEST_REQUIRED` / `NORM_STALE`。
65
+ 5. **人工校验任务不得被执行侧改状态** —— `HUMAN_REVIEW_NOT_EXECUTABLE`。
66
+
67
+ > 这五条不是"建议":它们是 MCP 入参形状与内核门的一部分。**照做不会更慢,绕过会直接失败。**
68
+ <!-- /flow-block:rules -->
69
+
70
+ ---
71
+
72
+ ## 我不做的事(防第二真源)
73
+
74
+ - ❌ **不存**任何项目数据 / 卡片状态 / 条目列表 —— 一律现取(`flow_start` / `requirement_list`)。
75
+ - ❌ **不写**某个项目的具体规范 —— 那是 `spec/norms/` + 项目 `<workspace>/AGENTS.md` 的事,本技能只给**顺序与指针**。
76
+ - ❌ **不定义**错误码语义 —— 错误码在 L2/L3;本技能只说「见到 X 该做什么」。
77
+ - ❌ **不替代** `AGENTS.md` —— 后者管「在这个仓库干活的规矩」,本技能管「跑这条主流程的顺序」。
78
+
79
+ ---
80
+
81
+ ## 参考
82
+
83
+ | 文件 | 内容 |
84
+ | --- | --- |
85
+ | [`references/steps/S0.md`](./references/steps/S0.md) … [`S7.md`](./references/steps/S7.md) | 每步的详细做法、命令示例、判据读数长什么样 |
86
+ | [`references/errors.md`](./references/errors.md) | 错误码 → 该做什么(含"别重试同一请求"的那些) |
87
+ | [`references/injection.md`](./references/injection.md) | 三档装载的细节 + 分层注入策略(档 C 预埋,未启用) |
88
+ | `spec/norms/flow.md` | 机器版主流程(运行时唯一真源,随包;`norm_get { norm:"flow" }`) |
89
+ | `spec/norms/card-update.md` | 卡片更新规范(`card_progress` 的 `norm_digest` 就取它) |
@@ -0,0 +1,61 @@
1
+ # 错误码 → 该做什么
2
+
3
+ > 错误码由 L2(`src/mcp/`)与 L3(`src/core/`)产生,**本文件只是索引**:
4
+ > 真正权威的是代码里的抛出点。见到不认识的码,先 `grep -n "<CODE>" src/` 再动手。
5
+
6
+ ## 一、协议层 vs 工具层(先分清这个,再看具体码)
7
+
8
+ | 层 | 长什么样 | 含义 |
9
+ | --- | --- | --- |
10
+ | 协议层 | JSON-RPC `error.code`(如 `-32602`) | **调用姿势错了**:未知工具、参数结构不对 |
11
+ | 工具层 | `result.isError: true` + `{ code, message, details }` | **业务上被拒了**:门没过、形状不对、状态冲突 |
12
+
13
+ 分不清这两层的后果:把「参数写错」当成「服务挂了」而不停重试。
14
+
15
+ ## 二、建卡 / 归因 / 授权
16
+
17
+ | 错误码 | 意思 | 该做什么 | 能不能原样重试 |
18
+ | --- | --- | --- | --- |
19
+ | `REQUIREMENT_REQUIRED` | 没归因也没声明不归因 | 补 `requirement`,或显式 `unattributed_reason` | ❌ 改了参数再发 |
20
+ | `USAGE_ERROR` | `requirement` 与 `unattributed_reason` 同时给了 | 二选一 | ❌ |
21
+ | `AUTHORIZATION_REQUIRED` | 想直接建进 `todo`(或执行侧想自我授权) | 建进 `backlog`,之后请人授权 | ❌ |
22
+ | `DEPENDENCY_CROSS_PROJECT` | 条目/前置卡属于别的项目 | 回到正确项目 | ❌ |
23
+ | `TASK_NOT_FOUND` | 引用的卡不存在 | 核对编号(`project-123` 或 uuid) | ❌ |
24
+ | `INVALID_TITLE` / `INVALID_STATUS` / `INVALID_PRIORITY` | 字段值不合法 | 按 `details.allowed` 改 | ❌ |
25
+
26
+ ## 三、回填进度
27
+
28
+ | 错误码 | 意思 | 该做什么 | 能不能原样重试 |
29
+ | --- | --- | --- | --- |
30
+ | `EVIDENCE_REQUIRED` | `evidence[]` 空 / 没传 | 给至少一条 `{kind, ref}` | ❌ |
31
+ | `EVIDENCE_INVALID` | `kind` 不在四类里,或 `ref` 为空 | 按 `details.allowedKinds` / `index` 改 | ❌ |
32
+ | `NORM_DIGEST_REQUIRED` | 没带 `norm_digest` | `norm_get { norm: "card-update" }` 取 `digest` | ❌ |
33
+ | `NORM_STALE` | 你用的是旧规范 | 读 `details.body`(最新正文)后重新回填 | ❌(但**不需要人介入**) |
34
+ | `GOVERNANCE_AGENT_DONE` | 执行侧写 `done` | 交人点完成(S7) | ❌ 永不 |
35
+ | `HUMAN_REVIEW_NOT_EXECUTABLE` | 人工校验任务被执行侧改状态 | 走人工结论入口 | ❌ 永不 |
36
+
37
+ ## 四、需求条目 / 需求变更
38
+
39
+ | 错误码 | 意思 | 该做什么 | 能不能原样重试 |
40
+ | --- | --- | --- | --- |
41
+ | `MISSING_VERSION` | 改条目没带 `expected_version` | 先 `requirement_list` 取 `version` | ❌ |
42
+ | `VERSION_CONFLICT` | 条目已被改过 | 重新取 `version`,**合并**后再提交 | ❌ |
43
+ | `CHANGE_NEEDS_APPROVAL` | `apply:true` 但没带 `change_id` | 先预览 | ❌ |
44
+ | `CHANGE_ID_MISMATCH` | 预览后条目被改 / 补丁换了 | 重新预览拿新 `change_id` | ❌ |
45
+ | `CHANGE_REASON_REQUIRED` | 变更没写理由 | 补 `reason` | ❌ |
46
+
47
+ ## 五、契约 / 项目
48
+
49
+ | 错误码 | 意思 | 该做什么 | 能不能原样重试 |
50
+ | --- | --- | --- | --- |
51
+ | `CONTRACT_STALE` | 契约版本对不上(**切 `reject` 档后才会出现**) | 用 `details.snapshot.contractVersion` 重试;`details.changed[]` 告诉你**哪份文件变了** | ✅ 换版本号后 |
52
+ | `NORM_NOT_FOUND` | 规范 id 写错 / 规范文件缺失 | 按 `details.allowed` 改 | ❌ |
53
+ | `PROJECT_NOT_FOUND` | 项目不存在 / cwd 不在任何项目里 | 显式传 `project` | ❌ |
54
+
55
+ ## 六、只有这三类**值得等一等再试**
56
+
57
+ 1. **上游/宿主临时故障**(`host-unavailable`、投递超时)—— 等几秒到几分钟;
58
+ 2. **`CONTRACT_STALE`** —— 换个 `contract_version` 立刻可以重试;
59
+ 3. **`VERSION_CONFLICT`** —— 重读后合并再试(**不是原样重试**)。
60
+
61
+ 其余全部属于「**输入就不对**」:原样重试只会烧掉时间,而且往往会把同一个错误刷进审计。
@@ -0,0 +1,70 @@
1
+ # 三档装载 + 分层注入策略(档 C 预埋,未启用)
2
+
3
+ ## 一、三档从侵入性低到高
4
+
5
+ | 档 | 场景 | 机制 | 现状 |
6
+ | --- | --- | --- | --- |
7
+ | **A 开局提示词** | 人在 dsh 主会话新开一轮 | 贴 `node scripts/tb-flow.mjs start` 的输出(或 MCP prompt `taskboard.flow`,同一生成器) | ✅ 已可用 |
8
+ | **B 外部 agent 约定开局** | Claude Code / Codex 在**项目仓库**里开工 | 项目 `AGENTS.md` 一段「开工先跑 `<taskboard>/scripts/tb-flow.mjs start`」;片段用 `tb-flow snippet` 打印 | ✅ 已可用 |
9
+ | **C 宿主自动注入** | dsh 会话一创建就注入流程 | 宿主插件在 `sessionController` 创建会话时注入 | ⏸ **未启用**(须报批改 `~/.dsh/**` + 重载宿主) |
10
+
11
+ ### 档 B 的 `AGENTS.md` 片段(`tb-flow snippet` 的输出)
12
+
13
+ ```markdown
14
+ ## 开工(任务看板主流程)
15
+
16
+ 本项目用 taskboard-workbench 管任务。**动代码之前**先跑:
17
+
18
+ node <taskboard-workbench>/scripts/tb-flow.mjs start --project <项目id>
19
+
20
+ 把输出的「装载块」当本轮上下文:里面的 `nextStep` 就是本轮该先做的事,
21
+ `gaps` 告诉你哪里还欠账。流程细节见
22
+ `<taskboard-workbench>/skills/taskboard-flow/SKILL.md`。
23
+ ```
24
+
25
+ > 三条边界:① 片段**只指路**,不复制八步正文(避免第二真源);② 路径写成占位符 —— 每个项目装在哪不一样;
26
+ > ③ 这段**不覆盖**项目自己的 `AGENTS.md` 规矩,只是「开工第一步」。
27
+
28
+ ## 二、档 C 的接口形状(已定死,未接线)
29
+
30
+ | 预埋项 | 内容 | 现在生效吗 |
31
+ | --- | --- | --- |
32
+ | `flow_inject_policy` | `off` / `main-only` / `main+exec` / `all`(**默认 `off`**) | ✅ 是一个"配置位",但**没有任何代码读它去注入** |
33
+ | 审计表 | `flow_injections(session_id, project_id, policy, contract_version, digest, injected_at)` | ✅ 表在(P1 建的),`recordFlowInjection` / `listFlowInjections` 可用 |
34
+ | 接入位 | 「会话创建 → 注入」的 hook 点 | ⏸ **只在本文件文档化,不写任何 `~/.dsh/**` 补丁** |
35
+
36
+ ### 接入位长什么样(将来接线时的位置)
37
+
38
+ ```
39
+ 宿主 sessionController.createSession()
40
+ └─ 若 flow_inject_policy !== "off"
41
+ ├─ 取 buildFlowBlock()(与本档 A/B 同一个生成器,见 src/mcp/flow-block.mjs)
42
+ ├─ 按会话层级选版本(见下)
43
+ └─ recordFlowInjection({ projectId, sessionId, policy, contractVersion, digest })
44
+ ```
45
+
46
+ **关键:注入内容必须由同一个生成器产出** —— 否则宿主注入的、人贴的、agent 自己拉的会是三份不同的说明书。
47
+
48
+ ## 三、分层注入策略(按会话角色给不同长度)
49
+
50
+ | 会话类型 | 注入什么 | 为什么 |
51
+ | --- | --- | --- |
52
+ | **项目主会话** | 完整版:八步全文 + 五条硬规则 + 错误码索引 | 它要做判断、要拆卡、要回填 |
53
+ | **执行 / 关联会话** | **摘要版(≤ 300 tokens)**:当前步 + 两道门 + 常见错误码处置 | 它只需要"别把 done 写了"这类护栏 |
54
+ | **子 agent 会话** | **不注入** | 子 agent 由父会话派活,注入只会稀释它自己的任务上下文 |
55
+
56
+ 摘要版的形状(将来由生成器按 `policy` 剪裁,不另写一份):
57
+
58
+ ```
59
+ 任务看板主流程(摘要)
60
+ 当前步:<S?,来自 flow_start.nextStep>
61
+ 两条门:done 只能人点(GOVERNANCE_AGENT_DONE)· backlog→todo 是人工授权(AUTHORIZATION_REQUIRED)
62
+ 回填要带:evidence[](file/command/url/reading)+ norm_digest(norm_get "card-update")
63
+ 契约:<contract_version>(用旧版本会落 contract-warn)
64
+ ```
65
+
66
+ ## 四、为什么档 C 现在不做
67
+
68
+ - 它会碰 `~/.dsh/profiles/**` 与宿主重载 —— 属 AGENTS.md §3 明令须先报批的范围;
69
+ - A + B 已经覆盖了「人开局」与「外部 agent 约定开局」两个真实场景;
70
+ - 插件包形态(市场安装)定下来之后再接,能少返工一次。
@@ -0,0 +1,31 @@
1
+ # S0 · 绑定与对照
2
+
3
+ ## 目标
4
+ 在**动手之前**确认三件事:这是哪个项目、用的是哪版契约、现在缺什么。
5
+
6
+ ## 命令
7
+ ```bash
8
+ node scripts/tb-flow.mjs start # 人贴进会话的装载块(档 A)
9
+ node scripts/tb-flow.mjs start --json # 机器读
10
+ ```
11
+ MCP:`flow_start { project?, cwd? }` · `project_info { project }` · `workbench_audit { project }`
12
+
13
+ > 三个都是只读。`project_info` 看全貌计数,`workbench_audit` 看四类漂移(`contract-stale` /
14
+ > `unattributed` / `unbound-session` / `candidate-flood`)。
15
+
16
+ ## 判据(读数长什么样)
17
+ - `project.id` 与你要动的项目一致(不一致 ⇒ 显式带 `project`);
18
+ - `contract.version` 形如 `v1-xxxxxxxxxxxx`,且 `contract.baselineStale === false`(`true` ⇒ 规范或需求文档刚变过,先读 `changed[]`);
19
+ - `gaps` 三个数看清楚:`unattributedTasks` / `unboundSession` / `pendingCandidates`;
20
+ - `nextStep.step` 给出 S1–S7 里的一个 —— **这就是本轮该先做的事**。
21
+
22
+ ## 失败处置
23
+ | 现象 | 处置 |
24
+ | --- | --- |
25
+ | `PROJECT_NOT_FOUND` | 项目还没建,或 `cwd` 不在任何项目工作区 ⇒ 显式传 `project` |
26
+ | `gaps.unboundSession === true` | 项目主会话没绑定 ⇒ 回看板「重建/绑定主会话」,否则投递会落空 |
27
+ | `pendingCandidates > 20` | 先确认/丢弃候选(`candidate-flood`),否则条目化会灌进一堆文件清单行 |
28
+
29
+ ## 别做的事
30
+ - 这一步**只读**:不要在这里建卡、改状态、写评论。
31
+ - 不要凭记忆说"规范我知道" —— `norm_get` 一屏就能读完,`digest` 还是后续写操作的通行证。
@@ -0,0 +1,28 @@
1
+ # S1 · 需求文档与条目
2
+
3
+ ## 目标
4
+ 把「要做什么」写成**一条一件事**的需求条目;确认过再往下走。
5
+
6
+ ## 命令
7
+ MCP:
8
+ ```
9
+ requirement_list { project }
10
+ requirement_upsert { project, title, description, acceptance } # 新建
11
+ requirement_upsert { project, id, expected_version, title } # 改(必须带 version)
12
+ ```
13
+
14
+ ## 判据
15
+ - 一条条目只讲一件事("顺便把 X 也做了"要拆成两条);
16
+ - `status` 不是 `draft` 才算确认过(`draft` 不得建卡);
17
+ - 改条目返回的 `item.version` 与上次不同 ⇒ 确实改成了。
18
+
19
+ ## 失败处置
20
+ | 错误码 | 该怎么办 |
21
+ | --- | --- |
22
+ | `MISSING_VERSION` | 改条目没带 `expected_version` ⇒ 先 `requirement_list` 取 `version` 再提交 |
23
+ | `VERSION_CONFLICT` | 别人改过了 ⇒ 重新取 `version`,**在你的改动上合并**,别把人家的改动覆盖掉 |
24
+ | `DEPENDENCY_CROSS_PROJECT` | 条目属于别的项目 ⇒ 回到正确项目 |
25
+
26
+ ## 别做的事
27
+ - 不要用 `requirement_upsert` 改需求**正文**——正文属需求文档,条目是它的投影。
28
+ - 不要靠"条目名字看起来对"挑条目:`requirement_list` 会给你 `tasks.total`,没卡的条目才是待拆的。
@@ -0,0 +1,31 @@
1
+ # S2 · 分拆成卡
2
+
3
+ ## 目标
4
+ 把条目拆成**可执行、可验收、可归因**的卡。
5
+
6
+ ## 命令
7
+ ```
8
+ card_create {
9
+ project, title, requirement, # requirement 必填(或 unattributed_reason)
10
+ acceptance, verifyCommand, # FR-94:建卡时就写验收标准与复核动作
11
+ dependsOn: ["-12"] # 可选:前置卡,建卡后真成依赖边
12
+ }
13
+ ```
14
+
15
+ ## 判据
16
+ - `attribution.kind === "requirement"`(不是 `explicit-skip`);
17
+ - `card.status === "backlog"`(新卡只能待办池);
18
+ - `dependsOn` 回显的边数与你要的一致;
19
+ - `duplicates` 非空 ⇒ 已有同名未终态卡,**先确认是不是重复**再继续。
20
+
21
+ ## 失败处置
22
+ | 错误码 | 该怎么办 |
23
+ | --- | --- |
24
+ | `REQUIREMENT_REQUIRED` | 没给 `requirement` 也没给 `unattributed_reason` ⇒ 补一个;真不需要归属就显式写理由(落审计,可盘点) |
25
+ | `AUTHORIZATION_REQUIRED` | 想直接建进 `todo` ⇒ 不行:`backlog → todo` 是人工授权 |
26
+ | `DEPENDENCY_CROSS_PROJECT` / `TASK_NOT_FOUND` | 前置卡挂错项目或编号写错 —— **这次建卡没有发生**(依赖先解析,不会留半张卡) |
27
+ | `USAGE_ERROR`(两个都给) | `requirement` 与 `unattributed_reason` 只能二选一 |
28
+
29
+ ## 别做的事
30
+ - 不要一次建十张卡再回头补验收标准 —— `acceptance` / `verifyCommand` 建卡时就要写。
31
+ - 不要用 `unattributed_reason` 当"懒得找条目"的捷径:它会被 `workbench_audit` 盘点出来。
@@ -0,0 +1,22 @@
1
+ # S3 · 授权开工(人)
2
+
3
+ ## 目标
4
+ 把卡从待办池放行。**这一步只有人能做**。
5
+
6
+ ## 谁来做
7
+ 看板上的「启动执行」/ 拖拽 / 人点 —— 不是 agent,也不是 MCP 工具。
8
+
9
+ ## 判据
10
+ - 卡 `status` 从 `backlog` 变 `todo`;
11
+ - `task_events` 里有 `set-status`,`actor=human`;
12
+ - 卡此时已有归因(`requirement_id` 非空),否则下一步派发会被 `EXECUTION_NOT_ATTRIBUTED` 拒。
13
+
14
+ ## 失败处置
15
+ | 现象 | 处置 |
16
+ | --- | --- |
17
+ | 执行侧尝试推进 ⇒ `AUTHORIZATION_REQUIRED` | 这是设计:执行侧不得自我授权。请人点 |
18
+ | 卡还没归因就想授权 | 先回 S2 补归因,再请人授权 |
19
+
20
+ ## 别做的事
21
+ - 不要用 `card_progress` 试图把卡推到 `todo` —— 它走执行侧状态门,只接受 `in_progress` / `in_review` / `blocked` / `canceled`。
22
+ - 不要"先授权再想清楚要做什么":授权意味着占用执行资源。
@@ -0,0 +1,25 @@
1
+ # S4 · 派发 / 执行
2
+
3
+ ## 目标
4
+ 让卡真正跑起来,并且跑的过程可追踪。
5
+
6
+ ## 命令 / 入口
7
+ - 看板「派发团队」/「交项目主会话执行」(需要宿主会话通道;独立进程实例会如实置灰并给替代出口);
8
+ - 执行侧推进状态用 MCP `card_progress { card, status: "in_progress", evidence, norm_digest }`。
9
+
10
+ ## 判据
11
+ - 卡 `in_progress` 且有认领心跳(离开 `in_progress` 会自动释放认领);
12
+ - 人工校验任务(`labels` 含人工校验)**不会被执行侧改状态**;
13
+ - 每次状态变化都有 `task_events` 留痕。
14
+
15
+ ## 失败处置
16
+ | 错误码 | 该怎么办 |
17
+ | --- | --- |
18
+ | `HUMAN_REVIEW_NOT_EXECUTABLE` | 这是人在环任务 ⇒ 交人做结论(continue / change-requirement / close),执行侧别碰 |
19
+ | `EXECUTION_NOT_ATTRIBUTED` | 卡没有归属条目 ⇒ 回 S2 |
20
+ | `host-unavailable` | 当前是**独立进程**实例(没有宿主会话通道)⇒ 换到 DSH 内的 `/integrations/taskboard-workbench`,或按返回的 `prompt` 手工投递 |
21
+ | 卡长时间 `in_progress` 无心跳 | 看护会判 `stalled`;先看它的最后一条证据评论,别急着重派 |
22
+
23
+ ## 别做的事
24
+ - 不要为了"看起来在跑"而重复派发 —— 同一张卡重复派发会抢锁。
25
+ - 不要在派发前跳过 `dependsOn`:受阻卡派发了也只会被依赖门挡住。
@@ -0,0 +1,36 @@
1
+ # S5 · 回填进度 + 证据
2
+
3
+ ## 目标
4
+ 把"做到哪了"写成**别人能复核**的证据,而不是一句"已完成"。
5
+
6
+ ## 命令
7
+ ```
8
+ card_progress {
9
+ card,
10
+ status: "in_progress" | "in_review" | "blocked" | "canceled", # 可选
11
+ evidence: [
12
+ { kind: "command", ref: "npm test", note: "900/900 pass" },
13
+ { kind: "file", ref: "src/mcp/tools.mjs:210", note: "注册表新增 5 个工具" },
14
+ { kind: "reading", ref: "gaps.unattributedTasks=0" }
15
+ ],
16
+ norm_digest: "<norm_get {norm:'card-update'} 返回的 digest>"
17
+ }
18
+ ```
19
+
20
+ ## 判据
21
+ - `evidence[].kind` ∈ `file` / `command` / `url` / `reading`,`ref` 非空;
22
+ - 返回 `comment.deduped === false`(第二次同样证据会是 `true`,不会刷重复评论);
23
+ - `card.statusAfter` 与你期望的一致;
24
+ - 评论正文里有 `【MCP 证据】hash=…` —— 这就是事后复核的锚点。
25
+
26
+ ## 失败处置
27
+ | 错误码 | 该怎么办 |
28
+ | --- | --- |
29
+ | `EVIDENCE_REQUIRED` / `EVIDENCE_INVALID` | 补形状,不要改成"详见上文" |
30
+ | `NORM_DIGEST_REQUIRED` | 先 `norm_get { norm: "card-update" }`,用返回的 `digest` |
31
+ | `NORM_STALE` | 规范换版了 ⇒ 读返回体里的 `body` 再回填(**它已经把最新正文给你了**) |
32
+ | `GOVERNANCE_AGENT_DONE` | 想写 `done` ⇒ 不行,完成只能人点(回 S7 交人) |
33
+
34
+ ## 别做的事
35
+ - 不要把 `npm test` 的"退出码 0"写成"全部通过":说清楚跑了多少条。
36
+ - 不要用同一条证据反复回填不同卡 —— 去重是按**卡 + 这批证据**算的,换卡就算新证据。
@@ -0,0 +1,30 @@
1
+ # S6 · 需求变更
2
+
3
+ ## 目标
4
+ 需求改了,先把**影响面**摆出来,再决定改不改。
5
+
6
+ ## 命令(两步,必须按顺序)
7
+ ```
8
+ # ① 预览:不落地,只给影响面 + change_id
9
+ requirement_change { project, requirement, patch: { acceptance: "…" }, reason: "客户改了口径" }
10
+
11
+ # ② 落地:拿第①步的 change_id
12
+ requirement_change { project, requirement, patch: <同一个 patch>, reason: <同一个 reason>,
13
+ change_id: "<第①步返回>", apply: true }
14
+ ```
15
+
16
+ ## 判据
17
+ - 第①步 `applied === false`、`needs_approval === true`,且 `affected_cards` 列出这条需求下**未终态**的卡;
18
+ - 第②步 `applied === true`,`before` / `after` 与补丁一致;
19
+ - `governance_audit` 里有一条 `requirement-change`,`reason` 是你写的那句。
20
+
21
+ ## 失败处置
22
+ | 错误码 | 该怎么办 |
23
+ | --- | --- |
24
+ | `CHANGE_NEEDS_APPROVAL` | 直接 `apply:true` 没带 `change_id` ⇒ 先预览 |
25
+ | `CHANGE_ID_MISMATCH` | 预览之后条目被改过,或你把补丁换了 ⇒ **重新预览**,别硬猜 |
26
+ | `CHANGE_REASON_REQUIRED` | `reason` 必填:没有理由的变更事后无法复盘 |
27
+
28
+ ## 别做的事
29
+ - 不要跳过影响面直接改:`affected_cards` 是你唯一能看见"谁白做了"的时刻。
30
+ - 不要指望 `done` 卡自动重开 —— 它们**不会**;需要复查就新建一张卡。
@@ -0,0 +1,23 @@
1
+ # S7 · 验收收口(人)
2
+
3
+ ## 目标
4
+ 把卡真正关掉。**这一步只有人能做。**
5
+
6
+ ## 谁来做
7
+ 看板的「完成」按钮 / 人点。评审门(`review_state === 'approved'`)或显式 `skipReview` 才放行。
8
+
9
+ ## 判据
10
+ - `in_review → done`;
11
+ - `governance_audit` 里 `actor=human`;
12
+ - 卡上有 S5 的证据评论(没有证据就被收口,说明流程漏了一步)。
13
+
14
+ ## 失败处置
15
+ | 错误码 / 现象 | 处置 |
16
+ | --- | --- |
17
+ | `REVIEW_NOT_APPROVED` | 评审没通过 ⇒ 先过评审;确需跳过评审,必须**人**显式 `skipReview: true`(会落 `review_skipped` 审计) |
18
+ | `GOVERNANCE_AGENT_DONE` | 执行侧/agent 在写 `done` ⇒ 停手,交人 |
19
+ | `HUMAN_REVIEW_CANNOT_DONE` | 人工校验任务不得置完成 ⇒ 用人工结论入口(continue / change-requirement / close) |
20
+
21
+ ## 别做的事
22
+ - 不要"先 done 再补证据" —— 证据是收口的前置,不是事后装饰。
23
+ - 不要代替人点完成:这是本仓最硬的一条红线。
@@ -0,0 +1,36 @@
1
+ ---
2
+ norm_id: acceptance
3
+ version: 2
4
+ updated: 2026-10-29
5
+ applies_to: ["*"]
6
+ ---
7
+ # acceptance · 验收口径(机器版)
8
+
9
+ ## 三层判据
10
+
11
+ | 层 | 命令 | 通过线 |
12
+ |---|---|---|
13
+ | 单测 | `npm test` | **全绿**(0 fail),条数只增不减 |
14
+ | 语法 | `node --check`(全量 `.mjs`/`.js`) | 0 fail |
15
+ | 隔离验证台 | `node tools/bench-<name>.mjs` | 断言全 PASS;浏览器类须**沙箱外**跑(沙箱内 `SKIP` 退出码 2) |
16
+
17
+ > 浏览器类正路:`bash ~/.codex/skills/codex-local-env-fix/scripts/chrome-outside.sh -- node tools/bench-<name>.mjs`
18
+ > (沙箱里 spawn Chrome 必崩,与参数/内核/版本无关 —— 见全局 AGENTS §7)
19
+
20
+ ## 反向对照(防止「测试跟着实现改」)
21
+
22
+ 每条守卫断言都要有**反证入口**:注入旧口径/坏实现 ⇒ 断言必须转红。
23
+ 只证明「现在绿」不算验收,要证明「坏了会红」。
24
+
25
+ ## 证据是否合格
26
+
27
+ - ✅ `命令 + 输出摘要 + 时间`,例如 `npm test → 866/866 PASS`。
28
+ - ✅ `文件路径 + 行号`,改动点能落到具体位置。
29
+ - ❌ 「已修复」「跑通了」「应该没问题」。
30
+ - ❌ 只有截图没有读数(截图证明「长这样」,不证明「逻辑对」)。
31
+
32
+ ## 不允许的验收方式
33
+
34
+ - 用 `--force` / `-y` 跳过确认。
35
+ - 改测试来让红变绿(除非口径变更并已人工拍板)。
36
+ - 把沙箱内的浏览器失败当产品缺陷(先判 `CODEX_SANDBOX`)。
@@ -0,0 +1,39 @@
1
+ ---
2
+ norm_id: card-update
3
+ version: 1
4
+ updated: 2026-10-29
5
+ applies_to: ["*"]
6
+ ---
7
+ # card-update · 卡片更新规范(机器版)
8
+
9
+ ## 状态怎么走
10
+
11
+ ```
12
+ backlog ──人授权──▶ todo ──派发──▶ in_progress ──回填──▶ in_review ──人验收──▶ done
13
+ ▲ ▲ │ │
14
+ └── 驳回/返工 ◀───────┴────────────────────┘ └── 返工 ──▶ in_progress
15
+ in_progress ──阻断──▶ blocked ──解除──▶ todo(依赖类)/ in_progress(其它)
16
+ ```
17
+
18
+ - **`in_review → done`** 必须 `review_state === 'approved'`;人可显式 `skipReview: true`。
19
+ - **`blocked`** 分两类:`dependency`(回到 `todo` 等父卡,不进人工队列)/ 其它(进 `blocked`,同因复发达阈值转人工兜底)。
20
+ - **`canceled`** 不是完成:不得计入完成度。
21
+
22
+ ## 每条回填必须带证据
23
+
24
+ | 字段 | 要求 |
25
+ |---|---|
26
+ | `body` | 说清「改了什么 / 为什么 / 影响面」,不要写「已完成」 |
27
+ | 证据 | 至少一条可复核读数:**命令 + 输出摘要** 或 **文件路径 + 行号** |
28
+ | 验证 | 与 `gate.config.verifyCommand` 一致(默认 `npm test`) |
29
+
30
+ ## 禁止
31
+
32
+ - 执行侧写 `done`(`GOVERNANCE_AGENT_DONE`)。
33
+ - 「先改状态、事后再补证据」——回填与状态推进要同时到。
34
+ - 用评论代替事件:状态变化必须落 `task_events`。
35
+ - 把多件事塞进一张卡(一张卡=一件事,便于收口与追因)。
36
+
37
+ ## 卡面字段最小集
38
+
39
+ `title`(动词开头的短句)· `requirementId`(必填或显式豁免理由)· `owner` · `labels`(`kind/work` · `kind/review` · 领域标签)· `acceptance`(验收要点,可核验)。