flow-comet 1.6.2 → 1.6.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 (43) hide show
  1. package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
  2. package/.flow-comet/skills/flow-comet/SKILL.md +64 -46
  3. package/.flow-comet/skills/flow-comet/reference/KNOWN-ISSUES-template.md +1 -1
  4. package/.flow-comet/skills/flow-comet/reference/commit-discipline.md +32 -0
  5. package/.flow-comet/skills/flow-comet/reference/dirty-worktree.md +1 -1
  6. package/.flow-comet/skills/flow-comet/{GUIDANCE.md → reference/entry-detail.md} +18 -28
  7. package/.flow-comet/skills/flow-comet/reference/fix-loop.md +57 -0
  8. package/.flow-comet/skills/flow-comet/reference/platform-facts.md +58 -0
  9. package/.flow-comet/skills/flow-comet/reference/replan.md +23 -0
  10. package/.flow-comet/skills/flow-comet/scripts/comet-check.mjs +5 -4
  11. package/.flow-comet/skills/flow-comet/scripts/comet-hook-guard.mjs +260 -17
  12. package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +2714 -161
  13. package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +51 -4
  14. package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +13 -0
  15. package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +877 -10
  16. package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +52 -4
  17. package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +111 -4
  18. package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +108 -2
  19. package/.flow-comet/skills/flow-comet-archive/SKILL.md +10 -19
  20. package/.flow-comet/skills/flow-comet-change/SKILL.md +2 -3
  21. package/.flow-comet/skills/flow-comet-compose/SKILL.md +1 -1
  22. package/.flow-comet/skills/flow-comet-design/SKILL.md +6 -6
  23. package/.flow-comet/skills/flow-comet-execute/SKILL.md +58 -16
  24. package/.flow-comet/skills/flow-comet-integration/SKILL.md +8 -5
  25. package/.flow-comet/skills/flow-comet-open/SKILL.md +5 -1
  26. package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +1 -1
  27. package/.flow-comet/skills/flow-comet-plan/SKILL.md +8 -8
  28. package/.flow-comet/skills/flow-comet-review/SKILL.md +9 -12
  29. package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +59 -16
  30. package/.flow-comet/skills/flow-comet-task/SKILL.md +3 -2
  31. package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +3 -3
  32. package/.flow-comet/skills/flow-comet-verify/SKILL.md +8 -17
  33. package/README.md +4 -4
  34. package/package.json +1 -1
  35. package/scripts/dsh-bridge.mjs +59 -26
  36. package/scripts/prepare-env.mjs +165 -1
  37. package/.flow-comet/skills/flow-comet/reference/TEST-MATRIX.md +0 -116
  38. package/.flow-comet/skills/flow-comet/reference/composition-report.md +0 -65
  39. package/.flow-comet/skills/flow-comet/reference/dsh-platform.md +0 -184
  40. package/.flow-comet/skills/flow-comet/reference/resolved-skills.json +0 -661
  41. package/.flow-comet/skills/flow-comet/reference/skill-review.md +0 -13
  42. package/.flow-comet/skills/flow-comet/reference/subagents/script-author.md +0 -7
  43. package/.flow-comet/skills/flow-comet/reference/worktree-notes.md +0 -70
@@ -57,13 +57,7 @@ guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好
57
57
 
58
58
  4. **Auto-retry limit (R2.6)**: verify 失败自动重试 ≤ 3 次(机器计数 verifyFailures);第 4 次失败必须暂停问用户「继续修 / 停止」。Do not auto-retry beyond 3 times.
59
59
 
60
- 5. **LESSONS nomination**: Before archiving, scan all `*-SUMMARY.md` "decisions and deviations" sections and any `*-PROGRESS.md` "excluded solutions" sections. Apply nomination criteria:
61
- - Debugging/trial-and-error took > 30 minutes -> nominate.
62
- - Error is not task-specific, other tasks would hit it too -> nominate.
63
- - Reasonable probability of retry within 6 months -> nominate.
64
- - Otherwise do not nominate (avoid pollution).
65
- - Add qualifying lessons to `.specs/LESSONS.md` with next L-NNN number — 新条目编号 = 当前最大编号 + 1,插入 `## 条目区` 末尾(文件内升序,继续现有编号),**禁止文件尾追加与乱序插入**.
66
- - Check existing active lessons for superseded/deprecated status.
60
+ 5. **LESSONS nomination**: Before archiving, scan all `*-SUMMARY.md` "decisions and deviations" sections and any `*-PROGRESS.md` "excluded solutions" sections. 判据(三条判据 + 不提名兜底 + 编号续接与插入位置 + superseded 状态更新)见 `flow-comet-integration` 册的「LESSONS 提名」段——该段是判据的**单一权威**,本册不复述、以该册为准;提名结果按该册写回 `.specs/LESSONS.md`。
67
61
 
68
62
  The full verification protocol, UAT format, and failure diagnosis are in:
69
63
  - `flow-kit/prompts/7-integration.md` (INTEGRATION phase, verification + UAT sections)
@@ -87,18 +81,15 @@ This node is truly done when:
87
81
 
88
82
  ## 修复回路状态机路径
89
83
 
90
- review / verify 发现缺陷后的修复必须回到 `execute` 节点生命周期内完成,禁止驻留源节点「顺手修完」;引擎按以下路径强制闭环(`<源节点>` 为 review 或 verify):
84
+ verify 失败或发现缺陷后的修复必须回到 `execute` 节点生命周期内完成——**禁止驻留源节点「顺手修完」**(会被 BLOCKED)。要点:
91
85
 
92
- 1. **追加 Fix 任务**:在 `.specs/<change-id>/TASK.md` 的 `## Fix 任务` 段内追加编号修复任务(完整任务字段),**禁止文件尾追加**;任务集修订必须在 `entry` 之前完成。
93
- 2. **受控归位 execute**:运行 `workflow-state next`(完整命令:`node .claude/skills/flow-comet/scripts/workflow-state.mjs next`),或运行 `workflow-guard entry execute`(完整命令:`node .claude/skills/flow-comet/scripts/workflow-guard.mjs entry execute`)。处于 Fix 回退态(源节点驻留 + 存在 pending Fix 任务 + 当前路由判定为 execute)时,引擎把当前节点受控归位为 `execute`(`currentNode=execute`),并输出 `FIX-BATCH` 审计行(`next` 同时输出 `NODE: execute`);用 `workflow-state.mjs status` 确认 `stateCurrentNode` 已是 `execute` 再开工;若未归位,先按 `next` / `status` 的输出核对任务状态与路由,不要未经归位硬开工。
94
- 3. **执行修复**:按 execute 节点生命周期完成全部 Fix 任务(委托/直写规则不变);`entry execute` 刷新任务集签名,锁定追加后的任务集——归位后不得再增删任务或修改任务内容。
95
- 4. **跑 execute 四类出口**:`record execute` → `exit execute --apply`。四类出口门禁真实执行——**全任务 done / 逐任务 SUMMARY 完备 / 6 维自查 + 自检方法声明 / 任务集签名一致**;任一缺失即 BLOCKED 并给出恢复指引。通过后,引擎在 Fix 二次完成时把当前节点推回源节点(review 或 verify)。
96
- - **guard exit 回源审计行语义(Fix vs RETURN)**:真实修复回路二次完成保留 `FIX-BATCH: 回源节点 <源节点>`(真实 Fix 回炉的机器锚);正常多趟收尾(任务集签名全等且无 Fix 标记)输出中性 `RETURN: 回源节点 <源节点>`(非 Fix 回修);旧 state 缺闭合/修复证据(无签名事件且无 Fix 标记)输出 `RETURN: 回源节点 <源节点>(旧 state 缺闭合/修复证据,未分类)`,不冒充 Fix、不 BLOCK;上述分类只改审计行文本,路由与 state 写入零变化。此处 `RETURN:` 仅指审计行前缀,与子代理 handoff 的 Return Contract 无关。
97
- 5. **回源节点跑出口**:回到源节点后运行 `next`,Fix 回程豁免生效时应输出 `NODE: review` 或 `NODE: verify`(不会因源节点产物已存在而跳过);若仍输出后续节点,说明回程条件未满足,先核对状态机归属与任务状态,不要继续推进。随后执行 `entry <源节点>` → `exit <源节点> --apply` 跑源节点出口门禁(即 entry/exit 源节点);通过后继续正常路由(review → verify;verify → archive),必要时进入下一轮 Fix 闭环。
98
- - **`next` 回程审计行语义**:回程豁免行始终输出中性 `RETURN: 回程源节点 <源节点>`(源节点产物在场且未出口;保留源节点跑出口),不再输出 FIX-BATCH;受控归位行的 `FIX-BATCH: 归位 <execute 家族>` 保留(真实 Fix 回退行),两者不得混同。
99
- 6. **禁止绕过**:驻留源节点不归位、顺手改完后直接跑源节点 exit 收场会被 BLOCKED(存在未归位/未跑出口的修复回路),必须按上述路径恢复;不得用跳过归位或出口门禁的手段(含手动改写 `.flow-comet/flow-comet-state.json`)替代本路径。
86
+ 1. **追加 Fix 任务**:把修复任务(完整任务字段)追加到 `.specs/<change-id>/TASK.md` 的 `## Fix 任务` 段内,**禁止文件尾追加**;任务集修订须在 `entry` 之前完成。
87
+ 2. **受控归位 execute**:跑 `workflow-state next` 或 `workflow-guard entry execute` 触发受控归位(审计行 `FIX-BATCH: 归位`;`next` 同时输出 `NODE: execute`);用 `status` 确认 `stateCurrentNode` 已是 `execute` 再开工,未归位不得硬开工。
88
+ 3. **跑完 execute 四类出口**:`record execute` → `exit execute --apply`——全任务 done / 逐任务 SUMMARY 完备 / 6 维自查 + 自检方法声明 / 任务集签名一致,任一缺失即 BLOCKED;通过后引擎把当前节点推回 verify。
89
+ 4. **回源节点跑出口**:回到源节点后跑该节点出口门禁(`entry <源节点>` → `exit <源节点> --apply`),通过后继续 verify → archive 的正常路由,必要时进入下一轮 Fix 闭环。
90
+ 5. **禁止绕过**:驻留源节点不归位、顺手改完后直接跑源节点 exit 收场会被 BLOCKED;不得用跳过归位或出口门禁的手段(含手动改写 `.flow-comet/flow-comet-state.json`)替代本路径。
100
91
 
101
- **由受控重入打开的场景(archive 源)**:缺陷在归档后才暴露、且归档移动尚未发生时,可先由用户显式授权把工作归属退回 `execute` / `subagent-execute` / `review` / `verify` 之一,再按本节路径回到 execute 生命周期完成修复。重入命令:`node .claude/skills/flow-comet/scripts/workflow-state.mjs reenter <target> --authorized-by <source> --reason <text> [--continue-round <n>]`——每次调用都需要用户显式授权,每 change 上限 3 轮(达上限后凭显式续轮授权 `--continue-round <n>`(n ≥ 已用轮次 + 1)可继续并计入下一轮);重入前自动落 state 备份快照(`.specs/<change-id>/.reentry-backups/`);成功打印 `REENTRY: archive → <target>(授权源 <source>;第 n/3 轮;备份 <file>)` 与 `REASON: <text>` 行(续轮审计行为 `第 n 轮(显式授权续轮,上限 3)`),与 Fix 回炉的 `FIX-BATCH` 行、正常多趟收尾的 `RETURN` 行三态可区分。归档移动已发生或 change 已 `completed` 时重入 BLOCKED,须走人工处置或新 change,不得静默跳过。重入只改工作归属,不写任何闭合标记,也不跳过目标节点入口 / 出口与源节点出口门禁;重复调用同一目标为空操作(输出 `REENTRY: 空操作——…`,不备份、不计数、不改写 state)。
92
+ **何时读完整规格**:要核对完整判据——Fix 任务与任务集签名的时序、受控归位的完整判定条件、`FIX-BATCH` / `RETURN` 审计行三态语义与回源节点的回程豁免、绕过的失败面与恢复指引——读 `../flow-comet/reference/fix-loop.md`(**当你 verify 失败、要开修复回路把工作退回 execute 生命周期时读它**)。
102
93
 
103
94
  ## Entry Check
104
95
 
package/README.md CHANGED
@@ -28,7 +28,7 @@
28
28
  <p align="center">
29
29
  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js_%E2%89%A518-339933?style=flat&logo=node.js&logoColor=white" alt="Node.js 18+" /></a>
30
30
  <a href="https://github.com/baobaolaodie/flow-comet/actions"><img src="https://img.shields.io/github/actions/workflow/status/baobaolaodie/flow-comet/ci.yml?style=flat" alt="CI" /></a>
31
- <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-1.6.2-blue.svg" alt="Version" /></a>
31
+ <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-1.6.3-blue.svg" alt="Version" /></a>
32
32
  </p>
33
33
 
34
34
  ---
@@ -115,14 +115,14 @@ If you use skill-based disciplines like [superpowers](https://github.com/obra/su
115
115
  | Validation | Humans eyeball artifacts against the rules; TEST.md commands "should" run | Guards enforce required artifacts/sections at every node entry/exit; verify actually executes the TEST.md commands and counts failures |
116
116
  | Discipline enforcement | Rules are markdown text the model may ignore | Three defense layers: write whitelist physically blocks out-of-scope writes / coordinator prohibition / exit takeover detection |
117
117
  | Recovery | Depends on conversation memory; progress is lost across sessions | File-as-truth: re-derive the node from `.specs/` and auto-correct state; any session resumes correctly |
118
- | Parallel implementation | Humans coordinate multiple windows, easy to overstep | Subagents implement in isolated worktrees (coordinators cannot write source) and must return a verified contract (commit hash + evidence) |
118
+ | Parallel implementation | Humans coordinate multiple windows, easy to overstep | One delegation contract on every supported platform — write permission, commit isolation, verification isolation and integration discipline. The guard decides by the caller's identity, an isolated worktree is one implementation of write permission rather than a requirement, and the only platform difference is who builds the tree (per-platform channels and what is not yet covered: [Parallel delegation](docs/MECHANISM.md#parallel-delegation)). Subagents return a verified contract (commit hash + evidence) and the coordinator cannot write source |
119
119
  | Decision burden | A confirmation point at every stage, humans answer everything | Decisions are classified (user-decided / auto-handled / stop conditions / manual handover); humans only intervene at key points (scope, tech stack, breaking changes, review findings, archive) |
120
120
 
121
121
  ### Why pick flow-comet
122
122
 
123
123
  1. **Discipline goes from "self-discipline" to "machine-checked"** — every stage entry/exit has script validation: artifacts complete, sections filled, verify commands actually run, tasks stay in bounds.
124
124
  2. **No lost progress across sessions** — where you are is always derived from `.specs/` artifacts, never from conversation memory; reopen and continue from the right node.
125
- 3. **Implementation and coordination are physically separated** — implementation runs in fresh-context subagents inside isolated worktrees and must return a verified contract; the coordinator is banned from writing source, and the write whitelist blocks violations at the physical layer.
125
+ 3. **Implementation and coordination are separated, and the separation is enforced** — implementation runs in fresh-context subagents that must return a verified contract; the guard decides by the caller's identity before it resolves any path, so an isolated worktree is one way to provide write permission rather than a requirement, and the only platform difference is who builds the tree. The coordinator is banned from writing source, and the write whitelist blocks violations at the physical layer.
126
126
  4. **The native automation layer for flow-kit** — not a re-invention: artifact formats, rules, and stages are identical to flow-kit; a flow-kit project upgrades to a machine-driven flow by installing flow-comet, no migration needed.
127
127
  5. **Protocol-driven, minimal dependency, install-and-run** — the built-in 8-node flow works out of the box; any installed skill can be composed into a custom protocol on the same engine; Node.js 18+; the only third-party dependency is `@clack/prompts`, used exclusively by the installer's TTY multi-select (with an automatic readline fallback otherwise); one command installs it.
128
128
 
@@ -162,7 +162,7 @@ flow-comet automates the methodology of [flow-kit](https://github.com/rihebty/fl
162
162
  | [Usage](docs/USAGE.md) | The 8-node workflow, the per-node lifecycle and its commands, artifacts, branch mode, execution modes, user entry points |
163
163
  | [Core Mechanisms](docs/MECHANISM.md) | The behaviour contract, the three defense layers, guard validation, and custom protocols |
164
164
  | [Troubleshooting](docs/TROUBLESHOOTING.md) | Symptoms grouped by where they bite: installation, first run, a stuck node, platform |
165
- | [Versions](docs/VERSIONS.md) | Version semantics, the nine version surfaces, and the release checklist |
165
+ | [Versions](docs/VERSIONS.md) | Version semantics, the places that record the version, and the release checklist |
166
166
  | [CHANGELOG](CHANGELOG.md) | Per-version history |
167
167
  | [Contributing](CONTRIBUTING.md) | Contribution flow and the borrowing boundary |
168
168
  | [Security](SECURITY.md) | Reporting a vulnerability |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "flow-comet",
3
- "version": "1.6.2",
3
+ "version": "1.6.3",
4
4
  "description": "An automated execution engine that turns AI coding discipline into a verifiable state machine for the flow-kit 9-stage workflow, built for Claude Code, Codex, and DeepSeek Harness.",
5
5
  "type": "module",
6
6
  "files": [
@@ -16,6 +16,15 @@
16
16
  // spawn cwd 必须 = 会话项目根(相对 file_path 按 cwd 解析——
17
17
  // cwd≠项目根会 fail-open;不得以设 env 替代 cwd)。协议文件天然在
18
18
  // 项目内(skill 包 reference/ 随树复制)——无需 FLOW_COMET_PROTOCOL 机制。
19
+ // 5.5 身份信号透传(「D9 实现位置修订」/ ADR-014 决策 5):spawn 时注入 env
20
+ // FLOW_COMET_AGENT_DEPTH = agentDepth(exec) 的数字字符串(0 = 协调者/缺失,
21
+ // 正整数 = 子代理)**并同时注入桥接通道标记 FLOW_COMET_AGENT_DEPTH_SOURCE =
22
+ // 'dsh-bridge'**(2026-10-07 作用域收紧):守卫要求标记与深度**同时在场**才接受
23
+ // env 面身份——CC / Codex 生成的 hook 直接调守卫、不经本桥接,即使继承了深度变量
24
+ // 也不得据此走子代理路径。标记由本文件唯一注入,守卫侧按同一字面判据读取。
25
+ // 身份判定与最小保护集的**整条判据由守卫独占实现**;
26
+ // 桥接只搬运信号,不判保护集、不复制白名单逻辑(L-067 单一权威)。
27
+ // 子代理因此不在桥接侧短路:一律过守卫(AC-20 豁免收窄)。
19
28
  // 6. 决策映射:exit 0 → next() 放行;exit 2 → deny(BLOCK 消息 + 恢复指引
20
29
  // 透传);其它/异常 → fail-closed deny + WARN。
21
30
  //
@@ -23,12 +32,13 @@
23
32
  // - 不注册 fs/write-intent 槽位(single-slot 守卫瀑布无 deny 面,
24
33
  // 不 shadow 官方 dsh-fs-observation-policy);
25
34
  // - 不做 fs/observed 审计(v1 极薄);
26
- // - 不做技能注册/AGENTS.md 注入(安装器职责)。
35
+ // - 不做技能注册/AGENTS.md 注入(安装器职责);
36
+ // - 不做身份 / 保护集判定(守卫是唯一判定实现——本文件只透传 depth 信号)。
27
37
  //
28
38
  // 纯 ESM、零第三方依赖,仅使用 Node.js 内置模块。dsh 官方插件形态:
29
39
  // ESM 模块导出 { name, apply },ctx 由 dsh 注入。
30
40
  //
31
- // BRIDGE_VERSION: 1.6.2
41
+ // BRIDGE_VERSION: 1.6.3
32
42
 
33
43
  import { spawn } from 'node:child_process';
34
44
  import { existsSync, readFileSync, realpathSync } from 'node:fs';
@@ -40,7 +50,7 @@ import path from 'node:path';
40
50
  // 值语义 = 当前发布版本(随发布同步更新,与技能包 INSTALLED_VERSION 同值——
41
51
  // bridge-check 的版本一致性检查据此判定 loader 与项目副本同版)。
42
52
  export const name = 'dsh-flow-comet-bridge';
43
- export const version = '1.6.2';
53
+ export const version = '1.6.3';
44
54
 
45
55
  // guard 在项目内的相对路径常量(随 skill 包分发)。
46
56
  const HOOK_GUARD_REL = '.dsh/skills/flow-comet/scripts/comet-hook-guard.mjs';
@@ -98,12 +108,16 @@ export function mapToolInput(canonicalName, args) {
98
108
 
99
109
  // ---------------------------------------------------------------------------
100
110
  // 项目根包含性:Write/Edit 的 file_path 必须解析后仍位于 projectRoot 内。
101
- // 越界路径若交给 guard 子进程,writeTargetFromHookInput 会因 target=null
102
- // 跳过白名单判定(fail-open),因此必须在插件侧直接 fail-closed deny。
111
+ // 插件侧对越界路径直接 fail-closed deny 是**前置层**(该调用不进 guard 子进程),
112
+ // 不再是「补 guard fail-open」:guard 的写入目标解析已收敛为单一实现
113
+ // resolveWriteTarget(comet-hook-guard.mjs),越界返回 insideRunRoot=false /
114
+ // targetRel=null,「runRoot 外写入关断」与 Bash 分支同判拦截(ADR-014 决策 6)——
115
+ // 越界写不再静默放行。
103
116
  // Windows 8.3 短路径(如 LONGYI~1)与长路径在词法上不同,直接 path.relative
104
- // 会把项目内短路径误判为越界;因此先 realpath 展开已存在部分再执行包含性
105
- // 判断。realpathSync.native:Windows 上 fs.realpathSync(libuv)不展开 8.3
106
- // 短名,native 变体才会把 LONGYI~1 规范化为 LongYinHaHa(Windows 实证)。
117
+ // 会把项目内短路径误判为越界;该词法误判的失败方向现为 fail-closed(误 BLOCK),
118
+ // 不再是静默放行,故仍先 realpath 展开已存在部分再执行包含性判断(消误拦)。
119
+ // realpathSync.native:Windows 上 fs.realpathSync(libuv)不展开 8.3 短名,
120
+ // native 变体才会把 LONGYI~1 规范化为 LongYinHaHa(Windows 实证)。
107
121
  // ---------------------------------------------------------------------------
108
122
  export function realpathExistingPath(p) {
109
123
  try {
@@ -222,12 +236,12 @@ export function sessionCwd(exec) {
222
236
  return null;
223
237
  }
224
238
 
225
- // 代理身份分派(dsh 子代理=执行者):dsh 子代理 spawn/fork provider 的
239
+ // 代理身份读取(dsh 子代理=执行者):dsh 子代理 spawn/fork provider 的
226
240
  // childSessionMeta 把 delegationDepth=parentDepth+1 写入子代理 session header
227
241
  // (dsh-subagent 源码锚定,rc.6)——协调者=0/缺失,子代理>0。从 exec.agent.session
228
- // 读取(与 sessionCwd 同级字段),供监听侧区分执行者与协调者——子代理写源码是
229
- // 执行者职责(对应 CC worktree 子代理物理自由写),协调者走 guard 白名单拦截。
230
- // 非法值(NaN/负数/字符串/null/缺字段)一律按协调者处理(fail-closed 语义)。
242
+ // 读取(与 sessionCwd 同级字段)。本纯函数只负责**取值与归一化**(非法值一律 0,
243
+ // fail-closed 语义);身份语义的判定在守卫侧(经 runGuard 以 env 透传),
244
+ // 桥接不自行裁决身份放行(L-067)。
231
245
  export function agentDepth(exec) {
232
246
  const depth = exec?.agent?.session?.header?.delegationDepth;
233
247
  return typeof depth === 'number' && Number.isFinite(depth) && depth > 0 ? depth : 0;
@@ -274,8 +288,10 @@ export function mapGuardExit(code, stderr, stdout) {
274
288
 
275
289
  // ---------------------------------------------------------------------------
276
290
  // 判定核心子进程调用(stdin JSON {tool_name, tool_input} -> exit code)
291
+ // agentDepthValue = agentDepth(exec) 的归一化结果(0 = 协调者/缺失;正整数 = 子代理),
292
+ // 以 env FLOW_COMET_AGENT_DEPTH 透传给守卫——守卫侧与载荷 agent_id 归并为同一判据。
277
293
  // ---------------------------------------------------------------------------
278
- function runGuard(projectRoot, canonicalName, toolInput, signal) {
294
+ function runGuard(projectRoot, canonicalName, toolInput, signal, agentDepthValue) {
279
295
  return new Promise((resolve) => {
280
296
  const guardPath = resolveGuardPath(projectRoot);
281
297
  const child = spawn(
@@ -288,6 +304,17 @@ function runGuard(projectRoot, canonicalName, toolInput, signal) {
288
304
  stdio: ['pipe', 'pipe', 'pipe'],
289
305
  windowsHide: true,
290
306
  signal,
307
+ // 身份信号透传(「D9 实现位置修订」/ ADR-014 决策 5):depth 以数字字符串注入
308
+ // 子进程 env,由守卫与载荷 agent_id 归并为**同一判据**(守卫是身份与保护集的
309
+ // 唯一判定实现——桥接不复制保护集判定、不复制白名单逻辑,L-067)。
310
+ // 通道标记(2026-10-07 作用域收紧):与深度**成对**注入,作为「这次调用来自桥接」
311
+ // 的自证;守卫按精确等值校验——标记不在场时深度变量一律不作数(继承形态不成立)。
312
+ // 沿用既有 env 注入形态 {...process.env, VAR}(与 evolve.mjs 的协议 env 同形)。
313
+ env: {
314
+ ...process.env,
315
+ FLOW_COMET_AGENT_DEPTH: String(agentDepthValue),
316
+ FLOW_COMET_AGENT_DEPTH_SOURCE: 'dsh-bridge',
317
+ },
291
318
  },
292
319
  );
293
320
  let stdout = '';
@@ -396,7 +423,7 @@ export function apply(ctx) {
396
423
  return { kind: 'deny', reason };
397
424
  }
398
425
  // running(activeChange + status running/undefined):继续走既有第 5 步包含性校验、
399
- // 5.5 身份分派、第 6 步 guard 白名单——全部现状不变。
426
+ // 5.5 身份信号透传、第 6 步 guard 判定(身份与保护集统一由守卫裁决)。
400
427
 
401
428
  // 5. 包含性校验(Write/Edit):越界直接 deny,不进 guard。
402
429
  if (canonicalName === 'Write' || canonicalName === 'Edit') {
@@ -410,22 +437,22 @@ export function apply(ctx) {
410
437
  console.warn(reason);
411
438
  return { kind: 'deny', reason };
412
439
  }
413
- // 通过后传规范化长路径(realpath 展开 8.3 短路径)——guard 的
414
- // writeTargetFromHookInput 只做词法 path.relative,短路径会解析出
415
- // target=null 从而跳过白名单判定(fail-open)。
440
+ // 通过后传规范化长路径(realpath 展开 8.3 短路径)——guard 的写入目标解析
441
+ // resolveWriteTarget 只做词法 path.relative:短路径会被判为根外(targetRel=null),
442
+ // 失败方向是「runRoot 外写入关断」下的**误 BLOCK**(fail-closed),不再是
443
+ // target=null 跳过白名单判定的静默放行。
416
444
  const normalizedTarget = realpathExistingPath(path.resolve(projectRoot, mapped.target));
417
445
  mapped.target = normalizedTarget;
418
446
  mapped.input.file_path = normalizedTarget;
419
447
  }
420
448
 
421
- // 5.5 代理身份分派:delegationDepth > 0 = 子代理(执行者)——其写源码是
422
- // 执行者职责(对应 CC worktree 子代理物理隔离),跳过 guard 白名单判定直接
423
- // 放行;协调者(0/缺失)走原 guard 白名单(协调者禁令物理拦截保留)。
424
- // 形状 fail-closed 与项目根包含性校验在上方已对子代理同样执行——子代理也不得
425
- // 越界写项目根外/参数形状不符(fail-closed 纪律不因身份放宽)。
426
- if (agentDepth(exec) > 0) {
427
- return next();
428
- }
449
+ // 5.5 代理身份信号:agentDepth(exec) > 0 = 子代理(执行者)。桥接**不再短路**——
450
+ // 身份信号随守卫调用透传(env FLOW_COMET_AGENT_DEPTH + 通道标记
451
+ // FLOW_COMET_AGENT_DEPTH_SOURCE),身份判定与最小保护集
452
+ // 拦截的整条判据由守卫独占实现(「D9 实现位置修订」/ ADR-014 决策 5:保护集
453
+ // 判据不得出现第二份实现,L-067)。既有纪律保持:形状 fail-closed 与项目根
454
+ // 包含性校验在上方已执行——子代理也不得越界写项目根外 / 参数形状不符。
455
+ const agentDepthValue = agentDepth(exec);
429
456
 
430
457
  // 6. 项目本地 guard 调用。guard 文件缺失(安装未完成/被删除)-> WARN +
431
458
  // next() 放行(不阻断非 flow-comet 语义);spawn 异常(ENOENT 等)->
@@ -439,7 +466,13 @@ export function apply(ctx) {
439
466
  return next();
440
467
  }
441
468
 
442
- const decision = await runGuard(projectRoot, canonicalName, mapped.input, exec?.signal);
469
+ const decision = await runGuard(
470
+ projectRoot,
471
+ canonicalName,
472
+ mapped.input,
473
+ exec?.signal,
474
+ agentDepthValue,
475
+ );
443
476
  if (decision.kind === 'allow') {
444
477
  return next();
445
478
  }
@@ -26,12 +26,20 @@
26
26
  * 非破坏设计(T-FIX-13,2026-08-08 用户裁决):
27
27
  * - 默认(无 --purge):**不删除整个 .claude/(或 .agents/ / .dsh/)**——只精确覆盖生成物
28
28
  * (rules/ + skills/ 等),保留其他一切内容(commands/、自定义 hook、自定义 skill)。
29
+ * - **镜像面定向清理(2026-10-09 增补:升级路径缺陷修复)**:默认模式额外删除**生成物镜像
30
+ * 目录内**「权威源已不存在」的条目(改名 / 移出的文件,以及随之清空的目录)——只覆盖不删除
31
+ * 会让它们在副本里永久残留(实测后果:安装副本跑自身回归套件报 308/309,失败信息逐条指向
32
+ * 残留文件,而权威源同一命令 309/309)。删除面逐条限定在本次 copyTree 的目标根
33
+ * (`<skillRoot>/flow-comet*`),唯一判据 = 「权威源同一相对路径上不存在同类型条目」;
34
+ * 白名单之外(用户自有 skill、自定义文件、无命名空间的生成面)一律不触碰;fail-closed
35
+ * 情形(符号链接 / 类型冲突 / 清理后仍非空 / 归属不可判定)逐条打印保留原因,绝不静默。
29
36
  * - settings.local.json / .codex/hooks.json 采用**注入**方式:读现有配置 → 保留已有
30
37
  * 字段 → 过滤已管理的 comet hook → 合并新 hook → 写回。不覆盖用户已有配置。
31
38
  * - 显式 `--purge` 参数才允许删除生成物(打印删除清单 + 警告 + 需 --yes 二次确认)。
32
39
  * - 覆盖前打印将覆盖的生成物清单。
33
40
  *
34
- * 幂等:默认模式重复运行——rules/skills 覆盖一致;settings/hooks 注入幂等
41
+ * 幂等:默认模式重复运行——rules/skills 覆盖一致;镜像面定向清理零残留(第二次运行零删除项、
42
+ * 零报错);settings/hooks 注入幂等
35
43
  * (已管理的 comet-hook-guard 命令被过滤后重新合并,不产生重复条目);
36
44
  * AGENTS.md 托管区幂等替换(移除旧托管区后重新生成);
37
45
  * 运行时位置迁移幂等(旧件已搬走 → 跳过);.gitignore 纳管幂等(已有条目 → 保持原样)。
@@ -621,6 +629,156 @@ function applyPathReplacements(root, replacements) {
621
629
  return replaced;
622
630
  }
623
631
 
632
+ /**
633
+ * readdir(withFileTypes):仅「该路径确实不存在」返回 null——判定与 lstatIfExists 同口径
634
+ * (见 isMissingPathError:只有 ENOENT / ENOTDIR 算不存在,访问类故障原样抛出)。
635
+ * 供镜像清理复用:把「目录不可枚举」与「目录为空」两个分支分开,避免清理判定深嵌 try/catch。
636
+ */
637
+ function readdirIfExists(dir) {
638
+ try {
639
+ return fs.readdirSync(dir, { withFileTypes: true });
640
+ } catch (err) {
641
+ if (isMissingPathError(err)) return null;
642
+ throw err;
643
+ }
644
+ }
645
+
646
+ // ---------- 生成物镜像目录的定向清理(升级路径残留) ----------
647
+ //
648
+ // 缺陷形态(实测):copyTree 只覆盖、不删除 ⇒ 权威源里已删除或改名的文件在已有副本里永久残留。
649
+ // 一次改名 + 一次移出即可在三平台副本各留 8 条残留,且残留会让安装副本跑自身回归套件报
650
+ // 308/309(失败项的失败信息逐条指向残留文件),而权威源同一命令 309/309——落差纯由残留造成。
651
+ //
652
+ // 镜像白名单(唯一允许删除的路径集合,逐条由本次生成动作定义):本次真实 copyTree 的目标根
653
+ // `<skillRoot>/<name>`,其中 <name> ∈ 权威源 `skills/` 下的 `flow-comet*` 目录清单。
654
+ // 命名空间(flow-comet* 前缀)与安装位置(平台技能根)共同构成归属判据;白名单之外的一切路径
655
+ // **永不触碰**。两条 fail-closed 边界(不删,但必须可见):
656
+ // · 整个技能目录不在权威源清单里(`<skillRoot>/flow-comet-fork` 一类):安装器没有生成清单,
657
+ // 用户自建的同命名空间目录与「权威源已移除的技能」在结构上不可区分 ⇒ 归属不可判定,保留;
658
+ // 该形态由显式 `--purge` 处置。
659
+ // · `.claude/rules`(同为 copyTree 目标):路径不含命名空间,无法与用户自有规则文件区分 ⇒
660
+ // 不纳入删除面(同上,`--purge` 处置)。
661
+ //
662
+ // 删除判据只有一条:**权威源同一相对路径上不存在同类型条目**。fail-closed 情形逐条打印、绝不静默:
663
+ // · **镜像根自身**是符号链接/junction(不跟随、不删除——条目层检查拦不住根级穿越:根为链接时
664
+ // `readdirSync` 会跟随进链接目标,删除动作落在**项目之外**,而播报打印的是项目内的表象路径);
665
+ // · **镜像根的真实路径越出目标项目根**(realpath 包含性判据——根或其任一祖先段为链接时,
666
+ // 词法路径仍显示在项目内,只有解析后才能证否;无法证明「在项目内」一律不删);
667
+ // · 条目是符号链接(不跟随、不删除——防穿越到目标项目之外);
668
+ // · 权威源同路径在场但类型不同(文件 ↔ 目录):归属不可判定,留给复制阶段的既有语义;
669
+ // · 目录清理后仍非空(其中含非残留内容 = 用户文件)→ 只删残留子孙,目录本身保留。
670
+ // 幂等:重复运行零残留可删 ⇒ 零输出、零报错;删除动作逐条打印(输出可核对)。
671
+ /**
672
+ * realpath 解析:返回真实路径,**解析不出即 null**(路径不存在 / 悬空链接 / 权限或 IO 故障一视同仁)。
673
+ * 与 lstatIfExists「访问类故障原样抛出」的取舍不同——本函数只服务**删除前的包含性判据**,
674
+ * 调用方约定为 fail-closed(null ⇒ 不删并打印原因):解析不出就**证明不了**在项目内,
675
+ * 此时中止安装比静默放行危险,而静默放行又比不删危险。
676
+ * 优先 `realpathSync.native`:Windows 上 libuv 实现不展开 8.3 短名(实测 `LONGYI~1` 形态),
677
+ * 而词法形态不同的两侧直接比较会把项目内路径误判为越界——本仓既有同判据(dsh-bridge 的
678
+ * 包含性检查)已登记该平台事实,此处沿用同一取值口径(失败方向仍是 fail-closed:误判 = 不删)。
679
+ */
680
+ function realpathOrNull(target) {
681
+ try {
682
+ return fs.realpathSync.native(target);
683
+ } catch {
684
+ return null;
685
+ }
686
+ }
687
+
688
+ /**
689
+ * 真实路径包含性:`target` 解析后的真实路径是否仍在 `root` 解析后的真实路径之内。
690
+ * 两侧都先 realpath——根或祖先段是链接时词法路径会骗人(Windows 8.3 短名 / 平台临时目录链接同理)。
691
+ * 任一解析失败 ⇒ false(fail-closed);`path.relative` 的 `..` 前缀与绝对路径都判越界。
692
+ */
693
+ function isRealPathInside(target, root) {
694
+ const targetReal = realpathOrNull(target);
695
+ const rootReal = realpathOrNull(root);
696
+ if (targetReal === null || rootReal === null) return false;
697
+ const rel = path.relative(rootReal, targetReal);
698
+ return rel === '' || (rel !== '..' && !rel.startsWith('..' + path.sep) && !path.isAbsolute(rel));
699
+ }
700
+
701
+ function pruneMirrorEntries(srcRoot, dstRoot, report, projectRoot) {
702
+ // 根级 fail-closed(**进入递归/枚举之前**):镜像根自身是链接 ⇒ 不跟随;真实路径越出目标项目根
703
+ // ⇒ 不删。条目层的 entry.isSymbolicLink() 只覆盖根以下的条目,拦不住根级的符号链接/junction。
704
+ const rootStat = lstatIfExists(dstRoot);
705
+ if (rootStat === null) return; // 镜像根不在场(首次安装)——无残留可清
706
+ if (rootStat.isSymbolicLink()) {
707
+ report.skipped.push(`${dstRoot}(镜像根是符号链接/junction——不跟随、不删除,防穿越到目标项目之外)`);
708
+ return;
709
+ }
710
+ if (!isRealPathInside(dstRoot, projectRoot)) {
711
+ report.skipped.push(`${dstRoot}(真实路径 ${realpathOrNull(dstRoot) || '无法解析'} 越出目标项目根 ${realpathOrNull(projectRoot) || '无法解析'}——归属不可判定,不删)`);
712
+ return;
713
+ }
714
+ const entries = readdirIfExists(dstRoot);
715
+ if (entries === null) return; // TOCTOU:lstat 后、枚举前被移走——无残留可清(判定同 lstatIfExists 口径)
716
+ for (const entry of entries) {
717
+ const srcPath = path.join(srcRoot, entry.name);
718
+ const dstPath = path.join(dstRoot, entry.name);
719
+ if (entry.isSymbolicLink()) {
720
+ report.skipped.push(`${dstPath}(符号链接——不跟随、不删除)`);
721
+ continue;
722
+ }
723
+ const srcStat = lstatIfExists(srcPath);
724
+ const isDir = entry.isDirectory();
725
+ if (srcStat && isDir === srcStat.isDirectory()) {
726
+ // 权威源在场且同类型:目录递归下探,文件保留(内容由 copyTree 覆盖)
727
+ if (isDir) pruneMirrorEntries(srcPath, dstPath, report, projectRoot);
728
+ continue;
729
+ }
730
+ if (srcStat) {
731
+ report.skipped.push(`${dstPath}(权威源同路径类型不同——归属不可判定,不删)`);
732
+ continue;
733
+ }
734
+ if (isDir) {
735
+ // 权威源无该目录 ⇒ 其中全部条目都属残留:先递归清空,再连同目录本身移除
736
+ pruneMirrorEntries(srcPath, dstPath, report, projectRoot);
737
+ const left = readdirIfExists(dstPath);
738
+ if (left === null) continue; // 递归中已被移除(与其祖先同批)
739
+ if (left.length > 0) {
740
+ report.skipped.push(`${dstPath}(清理后仍非空——保留其中非残留内容)`);
741
+ continue;
742
+ }
743
+ fs.rmdirSync(dstPath);
744
+ report.removed.push(dstPath);
745
+ continue;
746
+ }
747
+ if (entry.isFile()) {
748
+ fs.rmSync(dstPath, { force: true });
749
+ report.removed.push(dstPath);
750
+ continue;
751
+ }
752
+ report.skipped.push(`${dstPath}(既非普通文件也非目录——不删)`);
753
+ }
754
+ }
755
+
756
+ /**
757
+ * 平台镜像清理总入口:对本次安装的每个技能镜像根(`<skillRoot>/<name>` ← `skills/<name>`)
758
+ * 做定向清理,逐条打印结果。无残留时零输出(幂等可核对:重复运行不再打印清理项);
759
+ * fail-closed 保留项以警告逐条打印——保留是**可见的决定**,不是静默跳过。
760
+ * `projectRoot` = 本次安装的目标项目根:**删除面的包含性上界**(镜像根 realpath 必须落在其内,
761
+ * 见 pruneMirrorEntries 的根级判据)。
762
+ */
763
+ function cleanStaleMirrorEntries(skillsSrc, skillRoot, skillNames, projectRoot) {
764
+ const report = { removed: [], skipped: [] };
765
+ for (const name of skillNames) {
766
+ pruneMirrorEntries(path.join(skillsSrc, name), path.join(skillRoot, name), report, projectRoot);
767
+ }
768
+ if (report.removed.length > 0) {
769
+ console.log(`[flow-comet] 镜像清理: 已删除 ${report.removed.length} 项(权威源已不存在的生成物)`);
770
+ for (const p of report.removed) {
771
+ console.log(` - 已删除: ${p}`);
772
+ }
773
+ }
774
+ if (report.skipped.length > 0) {
775
+ console.warn(`[flow-comet] 警告: 镜像清理保留 ${report.skipped.length} 项(fail-closed——无法判定归属即不删):`);
776
+ for (const p of report.skipped) {
777
+ console.warn(` - 保留: ${p}`);
778
+ }
779
+ }
780
+ }
781
+
624
782
  // ---------- 运行时文件位置迁移(旧命名空间 .comet/ → 新命名空间 .flow-comet/) ----------
625
783
 
626
784
  /**
@@ -1555,6 +1713,12 @@ async function main() {
1555
1713
  if (skillNames.length === 0) {
1556
1714
  throw new Error(`权威源中未找到任何 flow-comet* skill 目录: ${skillsSrc}`);
1557
1715
  }
1716
+ // 3.1 定向清理**先于复制**:镜像目录内「权威源已不存在」的条目(升级路径残留——见
1717
+ // cleanStaleMirrorEntries 的白名单与 fail-closed 说明;只覆盖不删除会让改名/移出的文件在
1718
+ // 副本里永久残留)。清理抛 EACCES / EPERM / EBUSY 时安装中止(错误 fatal,不吞)——此时
1719
+ // 尚未复制任何技能树,副本里不会留下「已复制但平台路径未替换、版本标识未写」的半成品树;
1720
+ // 清理判据只比对权威源与镜像现状,与复制是否已发生无关,故前置不改变删除面。
1721
+ cleanStaleMirrorEntries(skillsSrc, skillRoot, skillNames, target);
1558
1722
  for (const name of skillNames) {
1559
1723
  copyTree(path.join(skillsSrc, name), path.join(skillRoot, name), stats);
1560
1724
  stats.skills.push(name);
@@ -1,116 +0,0 @@
1
- # flow-comet 系统测试矩阵(TEST-MATRIX)
2
-
3
- > 定位:系统测试集(`system-test.mjs`)的设计文档——说明测试覆盖的机制面、测试载体与判定规则。
4
- > 运行:`node .flow-comet/skills/flow-comet/scripts/system-test.mjs`(权威源直接跑;安装副本路径同理)。
5
-
6
- ## 一、测试载体说明
7
-
8
- - **载体**:每个测试项 = 一个独立临时目录(`fs.mkdtemp`)+ 内置协议副本复制到 `<tmp>/reference/`(受保护路径要求协议文件位于 runRoot 内)+ **真实命令序列**(`init → record → guard entry/exit → handoff → hook` 的 `spawnSync` 调用)+ 断言退出码与输出关键词;测试项跑完 `rmSync` 清理。
9
- - **与引擎回归的关系**:`guard-self-test.mjs` 是引擎脚本的单元/场景级回归(fixture 构造为主,**场景数以套件自身输出为准**);本系统测试集是**系统级**(**A~L 共十二组,项数以套件自身输出为准**)——每个测试项走真实命令链路,验证机制在真实调用序列下生效(行为锚定归场景回归,集成正确性归系统测试)。
10
- - **归档源受控重入的锚登记**:引擎回归按四类锚覆盖——正例(授权全链路:备份 + 转移 + 审计事件 + 授权留痕)、负例(未授权 / 授权形态非法 fail-closed)、越界(目标白名单 / 协议 enabled / 源非 archive / 归档移动已发生 / 轮次上限)、恢复(拒绝 → 补全授权放行 → 重复同目标空操作);系统测试集由 H5~H8 覆盖真实命令链路(见 H 组)。两层锚均走 `reenter <target> --authorized-by <source> --reason <text>` 真实命令通道,判定逻辑单一权威。
11
-
12
- > **本文件刻意不记录具体计数**:计数随场景/测试项增减而变化,而本文件不在计数一致性自检的覆盖范围内——写死数字会静默过期(本项目已因此复发多次)。以两套件的实际输出为准(`ALL n SCENARIOS PASSED` 与系统测试的汇总行)。
13
- - **运行环境**:仅 node 内置模块(child_process/fs/os/path),无网络、无第三方依赖。
14
- - **输出纪律**:逐项 PASS/FAIL + 汇总(`SYSTEM TEST: N/M passed`);全过 exit 0,有 FAIL exit 1。测试项命名为公开面——零过程代号。
15
-
16
- ## 二、判定规则
17
-
18
- - **全部 PASS = 系统测试集完整通过**:与引擎回归套件(guard-self-test 全绿)构成统一测试集两级基线,方可进入下一级验证(CLI 冒烟)。
19
- - **任一 FAIL**:修复后重跑(修复只改权威源一处,重跑至全绿)。
20
- - **误通过 = 测试无效,必须修**:该拦截未拦截 / 该放行未放行,说明测试自身没守住机制边界——测试先于功能守边界,不许自欺("当时能过"不等于"现在正确")。
21
-
22
- ## 三、机制面覆盖矩阵(A~L 十二类)
23
-
24
- ### A. 状态机与路由
25
-
26
- 覆盖:init 全分支(状态写入/工件目录/同 id 重跑防护/分支模式)、status 节点推导与无活跃兜底、next 推进与状态漂移校正、next 未出口节点严格拦截、select 切换、advance 推进、record 基础证据、execution-mode 切换与记录、config 设置与非法值拒绝、多趟路由真实链路(并→串→交替与多波依赖)、plan 出口依赖环负例与恢复、多趟路由时序收敛、plan 出口文件依赖检出、修复回路闭环(review/verify 源受控归位 execute → 四类出口 → 回源节点出口;回程审计行按证据分为真实修复锚、正常多趟中性回程、旧态证据不足未分类三态;越界拦截与旧 change 渐进)。
27
-
28
- 测试项:A1 init 状态写入与工件目录创建 / A2 init 分支模式与非法前缀拒绝 / A3 init 同 id 重跑防护 / A4 status 节点推导与无活跃兜底 / A5 next 推进与状态漂移校正(进行中节点保护由引擎回归覆盖)/ A6 next 未出口节点严格拦截 / A7 select 切换与缺失拒绝 / A8 advance 节点推进 / A9 record 基础证据记录 / A10 execution-mode 切换与记录 / A11 config 配置与非法值拒绝 / A12 验证失败计数按 change 隔离(切换 change 后计数独立)/ A13 多趟路由真实链路(并→串→交替与多波依赖,NODE 行多次交替直至全部 done;正常多趟收尾输出中性回程行且不出现修复回程锚)/ A14 plan 出口依赖环负例(BLOCK 含 depends_on 恢复指引,按指引调环后恢复通过)/ A15 多趟路由时序收敛(逐节点 exit 后 next NODE 与 guard 出口 NODE 一致)/ A16 plan 出口文件依赖检出(写写重叠 BLOCK 与恢复 + 读写弱判 WARN)/ A17 多趟平行转换后 next 可达(各转换点 next NODE 与 guard 出口 NODE 一致)/ A18 漂移容忍 exit(execute 欠账经容错路径补齐)/ A19 路由诊断静默扩展(P→S 收尾无噪音 / 畸形块仍报)/ A20 directOverride 授权约束(自切 direct 无授权 BLOCK / 协调者授权通过) / A21 review 源 Fix 闭环:next 归位 execute → 出口回源 review → 审查出口真实执行;真实修复保留可检索回程锚(真实命令) / A22 verify 源 Fix 回程:回 verify 而非跳过 archive + verify 出口真实执行(真实命令) / A23 Fix 越界拦截与旧 change 渐进:源节点直接 exit BLOCK(新)/WARN(旧)不卡死;多波次修复、源节点未进入、旧态证据不足输出中性未分类回程的归因子场景(真实命令)。
29
-
30
- ### B. 声明机制
31
-
32
- 覆盖:skill-load 声明标记写入(协议归属)、非法参数拒绝不落标记、record 缺声明标记拦截、声明后记录通过、声明时间序自洽、损坏声明标记 fail-closed、委托范围条目豁免(有委托通过/无委托拦截)、exit 协议声明标记校验(真实链路通过/无标记·空协议·损坏拦截)、旧项目兼容(未激活声明机制照常通过)。
33
-
34
- 测试项:B1 声明标记写入 / B2 非法参数拒绝 / B3 缺声明标记拦截 / B4 声明后记录通过 / B5 声明时间序自洽 / B6 损坏标记 fail-closed / B7 委托范围条目豁免 / B8 exit 协议声明标记校验 / B9 旧项目兼容。
35
-
36
- ### C. 委托链路
37
-
38
- 覆盖:handoff 请求/结果/状态全链路(含提交校验与零提交资格——输出为空或全部可证明被 gitignore 可合法闭环;glob / 越界 / 非 git / tracked 的零提交声明一律拒绝,不得绕过提交子集校验、拦截时 state 字节零改写)、红绿证据时间序(先红后绿通过/补录拦截)、委托后 exit 证据键名契约与契约校验(通过/空交接拦截)。
39
-
40
- 测试项:C1 handoff 全链路(含零提交资格正例与越权负例)/ C2 红绿证据时间序 / C3 委托后 exit 契约校验。
41
-
42
- ### D. hook 写白名单
43
-
44
- 覆盖:open 阶段工件放行与源码拦截、execute 按执行模式收窄(subagent 只写 .specs/,direct 放宽)、归档阶段白名单与完成态放行。
45
-
46
- 测试项:D1 open 阶段白名单 / D2 execute 执行模式收窄 / D3 归档阶段白名单与完成态放行。
47
-
48
- ### E. 自定义协议
49
-
50
- 覆盖:自定义协议加载路由与节点推导(`--protocol`/env 加载)、自定义节点声明机制与出口全链路(含技能绑定)、内置特化校验对自定义协议不误触发。
51
-
52
- 测试项:E1 加载路由与节点推导 / E2 声明机制与出口全链路。
53
-
54
- ### F. 自动初始化
55
-
56
- 覆盖:上下文缺失提示且不自动生成、跳过记忆、新鲜上下文静默、生成协作全链路(7 段校验 + 扫描时间记录)。
57
-
58
- 测试项:F1 上下文缺失提示 / F2 跳过记忆 / F3 新鲜上下文静默 / F4 生成协作全链路。
59
-
60
- ### G. 分支模式
61
-
62
- 覆盖:init 建分支与一致性、归档入口分支校验、分支一致性失配警告。
63
-
64
- 测试项:G1 init 建分支与一致性 / G2 归档入口分支校验 / G3 一致性失配警告。
65
-
66
- ### H. verify 与归档
67
-
68
- 覆盖:验证命令真实执行与超时配置、归档完整流程(遗留清单 + 目录移动 + 完成态)、归档路径声明标记查找(先移目录后 exit 顺序下标记只存归档路径)、归档源受控重入真实命令链路(未授权 / 授权形态非法 fail-closed 且状态字节零改写;完整授权转移 + 嵌套证据 + 审计事件 + 备份指纹;幂等重放零改写与按备份手工回滚;轮次上限后 BLOCK 与人工裁决指引)、受控计划重校(replan)真实命令链路(任务集修订后出口被签名门禁 BLOCK 且零改写 → 授权 replan 重签 → 出口放行并正常路由;未授权 / 轮次不足 fail-closed 且零改写、上限后 BLOCK 与显式续轮放行)、强制推进留痕(advance 写 advance-forced 事件 + `status.forcedNodes` 派生可见)。
69
-
70
- 测试项:H1 验证命令真实执行与超时 / H2 归档完整流程 / H3 归档路径声明标记查找 / H4 归档后自动补声明标记写归档路径(不重建活动目录) / H5 受控重入:未授权调用 fail-closed 且状态字节零改写 / H6 受控重入:完整授权链路(转移 + 嵌套证据 + 审计事件 + 备份指纹 + 审计行) / H7 受控重入:幂等重放零改写与按备份手工回滚可执行 / H8 受控重入:上限 BLOCK、显式授权续轮与重入后闭环组合链路(真实命令) / H9 replan 解死锁:execute 相位修订任务集(含并行就绪任务)→ 重签 → 出口放行 → next 正常路由 / H10 replan 授权 fail-closed 与轮次上限:未授权零改写 · 第 4 次 BLOCK · 显式续轮放行(真实命令) / H11 advance 留痕:advance-forced 事件 + status.forcedNodes 派生可见(真实命令)。
71
-
72
- ### I. 异常路径
73
-
74
- 覆盖:损坏状态文件 fail-closed、缺工件出口拦截、非法参数拒绝、状态字段类型非法拦截。
75
-
76
- 测试项:I1 损坏状态文件 fail-closed / I2 缺工件出口拦截 / I3 非法参数拒绝 / I4 状态字段类型非法拦截。
77
-
78
- ### J. 文档一致性
79
-
80
- 覆盖:双语健康检查(英文文档零中文/中文文档零英文长句/双语镜像对称/版本场景数)、公开产物零代号检查(调用仓库本地工具;安装副本无仓库文档跳过)。注:本地工具为发布快照——开发窗口期场景数一致性子检查按结构检查放行,权威判定在引擎自测。
81
-
82
- 测试项:J1 双语健康检查 / J2 公开产物零代号检查。
83
-
84
- ### K. 安装器(版本标识 + 多平台)
85
-
86
- 覆盖:prepare-env 生成的版本标识(优先源仓库 git describe:发布版 = 精确 tag、开发态 = `<tag>-N-g<hash>`;无 git 时回退权威源随技能包分发的 INSTALLED_VERSION)精确反映源仓库状态;权威源文件与 CHANGELOG 首个版本段一致(CI release-consistency 同规则);多平台安装(平台描述符驱动:claude-code 默认零变化 / codex——技能落 `.agents/skills/`、SKILL 命令路径平台化替换、`.codex/hooks.json`(顶层 hooks 包裹层 + matcher `*`)注入、`config.toml [features] hooks` 启用、AGENTS.md 托管区、纯 codex 不生成 `.claude/`);hook 平台分支输出契约(codex = `{"decision":"block"}` deny 通道 + Bash 命令写入检测(PowerShell cmdlet / .NET File API / 重定向)、放行 `{}`;claude-code 文本输出不变);平台选择链(`--platform` 显式 / TTY 交互 / 无 TTY 探测 `.codex/`·`.claude/` / 默认 claude-code);purge 语义(缺 `--yes` 拒绝 / 重建 / 用户内容保留);平台描述符驱动防回归(main 统一调度——源码无平台分支标识,安装/清理逻辑全部封装在描述符条目;从源码提取平台逐一安装冒烟,未来新增平台自动纳入测试);dsh 平台面(三平台桥接——技能落 `.dsh/skills/`、路径替换/版本标识/AGENTS.md 托管区/purge 清理/桥接 loader 纯函数与流程态门/版本戳重装断言;分发面环境判据:权威源形态真跑完整断言,安装副本形态显式「不适用」并按结果标记计通过,不静默跳过)。
87
-
88
- 测试项:K1 安装器版本标识 / K2 codex 平台安装冒烟(技能/路径替换/hooks.json/AGENTS 托管区 + 非法 hooks.json fail-safe)/ K3 hook 平台分支 JSON 契约 + CC 分支不变 / K4 平台选择链(显式/无 TTY 探测/默认/未知平台拒绝)/ K5 purge 语义(缺 --yes 拒绝/重建/用户内容保留)/ K6 平台描述符驱动(全平台安装冒烟 + main 统一调度断言)/ K7 dsh 平台安装(技能/pathReplacements/版本标识/树一致)/ K8 dsh AGENTS.md 托管区(用户内容保留 + 幂等重装)/ K9 桥接 loader 源文件/语法/复制与托管块注入(读-合并-写)/ K10 dsh purge 清理恢复(缺 --yes 拒绝/删除后重建/用户内容保留/空目录清理)/ K11 桥接 loader 纯函数与 apply 分派断言(映射/包含性/退出映射/身份分派)/ K12 桥接 loader 流程态门断言(无 state/无 activeChange/completed 放行 · 非法 JSON/未知 status deny)/ K13 hook 注入形态无关断言(basename+项目根引用)+ 旧条目幂等升级 / K14 桥接 loader 版本戳重装断言(升级/降级方向与覆盖后新戳)+ dev 态载体 bridge-check 基础版本比较(剥离开发态后缀后同基础健康 / 基础版本失配仍 FAIL);分发面环境判据:权威源形态真跑,安装副本形态显式「不适用」并按结果标记计通过(不静默跳过)/ K15 桥接 loader 同源重装断言(首次安装后版本一致)/ K16 桥接 loader purge 后重建路径回归(loader 恢复与再装收敛)/ K17 状态迁移(旧布局项目安装后状态可读且流程可继续)/ K18 分发面(环境判据与包体边界 + bin 双入口——权威源真跑/副本显式不适用 + init 词元红线)。
89
-
90
- ### L. 执行遗漏防护(真实链路)
91
-
92
- 覆盖:进入证据(entry 记录 enteredNodes、正常流程 exit 无误报——真实链路中节点顺序检查先于进入警告,未 entry 场景由引擎回归覆盖)、空退出豁免(显式 emptyExitApproved 通过 / 无豁免仍拦截)、空仓库提示(init 在无提交仓库输出 EMPTY-REPO)。
93
-
94
- 测试项:L1 进入证据 / L2 空退出豁免 / L3 空仓库。
95
-
96
- ## 四、附:design 节点 required 自指核验结论
97
-
98
- **核验对象**:`workflow-protocol.json` 的 design 节点——`requiredSkillCalls` 含与 `implementation` 相同的技能(自指),对照 open / review 两模式核验(遗留核验项)。
99
-
100
- **三模式对照**:
101
-
102
- | 节点 | implementation | requiredSkillCalls | 含自身? |
103
- |---|---|---|---|
104
- | open | flow-comet-open | flow-comet-change, flow-comet-requirement | 否 |
105
- | design | flow-comet-design | flow-comet-design, flow-comet-ui-design | 是 |
106
- | review | flow-comet-review | flow-comet-review, flow-comet-test | 是 |
107
-
108
- **结论:设计如此,非缺陷。** 理由:
109
-
110
- 1. **协议承载型入口 vs 纯壳编排**:design 与 review 的入口技能即协议本体(flow-comet-design 承载 DESIGN 阶段协议,flow-comet-review 承载 REVIEW 阶段协议),其 `required` 列表 = 执行者必须加载并声明的协议技能集合,含自身是「入口即协议承载」的自然形态。open 是纯壳编排者(flow-comet-open 自身无协议文件,协议由 flow-comet-change / flow-comet-requirement 两个独立技能承载),故 required 不含自身——open 若含自身反而无法声明(没有对应协议文件可声明)。
111
- 2. **required 自条目是加载声明的载体**:执行者加载 flow-comet-design 后运行 `skill-load design flow-comet-design --prompt flow-kit/prompts/2-design.md` 写入声明标记——该标记同时满足记录校验(required-skill 条目须有对应标记)与节点 exit 的协议声明校验(design 节点要求 2-design.md 标记),两处复用同一文件,机械上自洽。
112
- 3. **review 同构佐证**:review 的 required(flow-comet-review + flow-comet-test)与其节点协议文件集(6-review.md + 5-test.md)一一对应——两个节点同构,是设计而非偶发。
113
- 4. **与 plan 节点修正不同类**:plan 节点那次修正的缺陷在 `implementation` 字段指向错误(指向协议技能而非节点入口技能),修正后确立「implementation = 节点入口、required = 需加载声明的协议技能」语义——design 的 implementation 指向正确,required 含自身不违反该语义。
114
- 5. **机械上无害**:required 条目在节点 exit 时自动补全,不产生额外拦截;删除反而破坏上述声明载体对应关系。
115
-
116
- **边界**:若未来把 design 重构为「壳 + 独立协议技能」双层结构(同 open),required 自条目随结构自然去除;当前形态保持,无需修复。