flow-comet 1.6.0 → 1.6.2

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/GUIDANCE.md +26 -5
  2. package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
  3. package/.flow-comet/skills/flow-comet/SKILL.md +51 -2
  4. package/.flow-comet/skills/flow-comet/reference/KNOWN-ISSUES-template.md +3 -3
  5. package/.flow-comet/skills/flow-comet/reference/TEST-MATRIX.md +15 -15
  6. package/.flow-comet/skills/flow-comet/reference/dsh-platform.md +19 -11
  7. package/.flow-comet/skills/flow-comet/reference/recovery.md +1 -7
  8. package/.flow-comet/skills/flow-comet/reference/workflow-protocol.json +1 -1
  9. package/.flow-comet/skills/flow-comet/reference/worktree-notes.md +21 -3
  10. package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +129 -3
  11. package/.flow-comet/skills/flow-comet/scripts/context-scan.mjs +396 -0
  12. package/.flow-comet/skills/flow-comet/scripts/contract-check.mjs +41 -31
  13. package/.flow-comet/skills/flow-comet/scripts/evolve.mjs +778 -0
  14. package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +5499 -596
  15. package/.flow-comet/skills/flow-comet/scripts/health.mjs +664 -0
  16. package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +1 -1
  17. package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +459 -11
  18. package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +58 -3
  19. package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +1024 -11
  20. package/.flow-comet/skills/flow-comet/scripts/time-utils.mjs +133 -0
  21. package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +285 -227
  22. package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +6 -4
  23. package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +515 -31
  24. package/.flow-comet/skills/flow-comet-archive/SKILL.md +2 -0
  25. package/.flow-comet/skills/flow-comet-change/SKILL.md +13 -1
  26. package/.flow-comet/skills/flow-comet-design/SKILL.md +6 -2
  27. package/.flow-comet/skills/flow-comet-dev/SKILL.md +3 -1
  28. package/.flow-comet/skills/flow-comet-evolve/SKILL.md +46 -11
  29. package/.flow-comet/skills/flow-comet-execute/SKILL.md +6 -4
  30. package/.flow-comet/skills/flow-comet-health/SKILL.md +57 -16
  31. package/.flow-comet/skills/flow-comet-integration/SKILL.md +2 -0
  32. package/.flow-comet/skills/flow-comet-open/SKILL.md +2 -0
  33. package/.flow-comet/skills/flow-comet-plan/SKILL.md +17 -6
  34. package/.flow-comet/skills/flow-comet-requirement/SKILL.md +2 -0
  35. package/.flow-comet/skills/flow-comet-review/SKILL.md +7 -5
  36. package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +12 -9
  37. package/.flow-comet/skills/flow-comet-task/SKILL.md +7 -3
  38. package/.flow-comet/skills/flow-comet-test/SKILL.md +2 -0
  39. package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +28 -3
  40. package/.flow-comet/skills/flow-comet-verify/SKILL.md +7 -5
  41. package/README.md +45 -119
  42. package/package.json +1 -1
  43. package/scripts/dsh-bridge.mjs +2 -2
@@ -91,14 +91,14 @@ flow-kit 9 阶段工作流的 workflow-kernel 实现。保留 flow-kit 的全部
91
91
  | verify | control | 集成验证 + UAT | flowkit.verify.v1 |
92
92
  | archive | control | 归档 + LESSONS | flowkit.archive.v1 |
93
93
 
94
- > **并行任务路由(节点顺序是动态的 · 多趟语义)**:TASK 含依赖已满足的 `parallel="true" status="pending"` 任务时路由到 subagent-execute——每趟委托全部依赖已满足的并行任务;子代理返回后重新判定:仍有可并行 pending 就再次进入 subagent-execute(委托节点可多次往返),存在串行 pending 时回 execute 消化一趟再循环。委托节点的完成 = 不存在依赖已满足的可并行 pending 且无串行残留;并行/串行交错的混排序列合法,唯一前置拦截是依赖环(plan 出口校验并附恢复指引)。全部为串行任务时走 execute,行为不变。`next` 的输出始终是权威——以 `NODE:` 输出为准,不按静态顺序推断。
94
+ > **并行任务路由(节点顺序是动态的 · 多趟语义)**:TASK 含依赖已满足的 `parallel="true" status="pending"` 任务时路由到 subagent-execute——每趟委托全部依赖已满足的并行任务;子代理返回后重新判定:仍有可并行 pending 就再次进入 subagent-execute(委托节点可多次往返),存在串行 pending 时回 execute 消化一趟再循环。委托节点的完成 = 不存在依赖已满足的可并行 pending 且无串行残留;并行/串行交错的混排序列合法,唯一前置拦截是依赖环(plan 出口校验并附恢复指引)。全部为串行任务时走 execute,行为不变。`next` 的输出始终是权威——以 `NODE:` 输出为准,不按静态顺序推断。direct 模式下 `parallel="true"` 任务仍必须由 subagent-execute 委托消化;direct 仅覆盖串行任务的主代理直写。
95
95
 
96
96
  ## Skill Bindings
97
97
 
98
98
  | 节点 | Implementation | Required Calls | Enforcement |
99
99
  |------|---------------|----------------|-------------|
100
100
  | open | flow-comet-open | flow-comet-change, flow-comet-requirement | guarded |
101
- | design | flow-comet-design | flow-comet-design, flow-comet-ui-design (advisory,不要求声明) | guarded |
101
+ | design | flow-comet-design | flow-comet-design, flow-comet-ui-design (guarded,仅前端适用——前端须先 skill-load 建标记 + record 载荷带 `required-skill:design.flow-comet-ui-design`;非前端不加载不声明;旧 change 渐进 WARN) | guarded |
102
102
  | plan | flow-comet-plan | flow-comet-task | guarded |
103
103
  | execute | flow-comet-execute | flow-comet-dev | guarded |
104
104
  | subagent-execute | flow-comet-subagent-execute | flow-comet-dev (handoff) | handoff-guarded |
@@ -117,7 +117,9 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load <node> <ski
117
117
 
118
118
  > **跑声明命令 ≠ 加载**:声明只把“哪次会话加载了哪个 skill、按哪份协议工作”写进状态供 exit/record 核对;真正加载只有第 1 步的 Skill 工具能做到。协议的引用示例:execute / subagent-execute 节点加载 flow-comet-dev 时用 `--prompt flow-kit/prompts/4-dev.md`(DEV 阶段协议),交付物按 `flow-kit/templates/SUMMARY.md` 模板填写并补写 `## 自检方法` 段。
119
119
 
120
- 节点退出(exit)与证据记录(record)会核对声明标记。声明如实记录执行者动作——加载了哪个 skill、按哪份协议工作——**不等于产出证明**;产出是否正确由产物结构校验与门禁把关。**技能加载前置门**:新 change 的 required 条目不再自动补写——handoff request / record 前必须已有本节点声明标记(先加载、再声明、后干活);声明标记自动补写仅对旧 change 兜底(按协议 requiredSkillCalls 代记,标记带 `auto: true`),手动声明仍推荐(如实记录加载动作与协议文件)。advisory 条目(如 flow-comet-ui-design,仅前端触发)不要求 skill-load 声明——record 只校验执行者实际声明的条目。
120
+ 节点退出(exit)与证据记录(record)会核对声明标记。声明如实记录执行者动作——加载了哪个 skill、按哪份协议工作——**不等于产出证明**;产出是否正确由产物结构校验与门禁把关。**技能加载前置门**:新 change 的 required 条目不再自动补写——handoff request / record 前必须已有本节点声明标记(先加载、再声明、后干活);声明标记自动补写仅对旧 change 兜底(按协议 requiredSkillCalls 代记,标记带 `auto: true`),手动声明仍推荐(如实记录加载动作与协议文件)。`flow-comet-ui-design` 与协议同等级(`guarded`)且**仅前端适用**:前端 change 须先加载并 `skill-load` 声明、record 载荷带 `required-skill:design.flow-comet-ui-design`(出口不再自动补写);非前端不加载不声明(出口输出可见的 `UI-DESIGN: skipped(非前端)`);旧 change 渐进,缺件仅 WARN。前端判据是**结构级**的:`CHANGE.md` 的「视觉调性」段在场,且段内的「不适用」标记成**结构形态**——**独立行**、居**行首**(可带列表符号 / 引用 / 加粗),或写在适用性类标签的**字段值位**;标记之后须成**词形边界**(紧跟空白、标点或行尾),命中即回显**命中片段**。段内其它位置顺带提到「不适用」不算标注,仍判前端。
121
+
122
+ > **侧命令**:`evolve`(架构沉淀同步)/ `health`(健康巡检)/ `context-scan`(上下文重扫)三条横向命令**不进 8 节点流程**——不路由、不 entry/exit、不写节点证据,一律由用户显式调用;触发词、命令面与落盘产物见主 `SKILL.md` 的「侧命令」小节(单一来源,本文不复述其命令表)。
121
123
 
122
124
  ## Guardrails And Evidence
123
125
 
@@ -152,6 +154,21 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load <node> <ski
152
154
  - If the guard fails, do not proceed — present the guard output and ask the user how to fix it.
153
155
  - If the user wants to redo a completed Node, reset its completion state and re-enter rather than creating a parallel path.
154
156
 
157
+ ### 受控重校(`replan` · execute 源)
158
+
159
+ 计划在执行中被证明有缺陷、任务集因此需要修订时,用受控重校重新校验并重签任务集——不跳节点、不重置任何完成态:
160
+
161
+ ```bash
162
+ node .claude/skills/flow-comet/scripts/workflow-state.mjs replan "<reason>" --authorized-by <source> [--continue-round <n>]
163
+ ```
164
+
165
+ - **何时用**:`currentNode` 停在 `execute` / `subagent-execute`,且任务集在进入该节点后被修订、出口因此报「签名不匹配」时;修订后的任务集必须自身合法。
166
+ - **授权**:每次调用都需要用户显式授权——`--authorized-by` 记录授权来源,位置参数记录原因;引擎把授权留痕写入当前节点的嵌套证据(`state.evidence.<node>.replanAuthorization`)。缺授权、值为空/纯空白或形态非法一律 BLOCKED,且 state 字节零改写。
167
+ - **上限与显式续轮**:每 change 最多 3 轮;第 4 次 BLOCKED 并给出「继续 / 停止」人工裁决指引。人工裁决「继续」须追加 `--continue-round <n>`(正整数,且 n ≥ 已用轮次 + 1)作显式续轮授权:满足则放行并计入下一轮,审计行打印续轮标记;未到上限即传该参数、或轮次不足一律 BLOCKED 且零改写。轮次与审计事件记入 `state.history`(事件类型 `replan-applied`),成功输出 `REPLAN: <node> 重新校验通过(授权源 <source>;第 n/3 轮;备份 <file>)` 与 `REASON: <text>` 两行。
168
+ - **备份**:改写前自动落 state 快照 `.specs/<change-id>/replan-backups/<UTC ISO>-pre-replan.json`(时间戳中的 `:` 替换为 `-`),并记录 sha256 指纹,供审查核验与手工回滚。
169
+ - **幂等与零改写**:目标形态已成立时的重复同形态调用 = 空操作(输出 `REPLAN: 空操作——…`,不备份、不计数、不写事件、不改写 state),不会静默跳过。
170
+ - **绝不豁免校验**:`replan` 只做「重新校验 + 重新签名」——判据与 plan 出口同源,处置按路径分列:**replan 重校**——任务块 / 每任务 `<verify>` / 任务图(依赖环 / 缺失依赖)任一不成立,或并行写冲突的写写(write∩write)成立,一律 BLOCKED(状态零改写);读写(read∩write)仅 WARN 不阻断;7 字段完整性只在「新模板形态(含 `<name>`)+ 新 change」缺字段时 BLOCKED,其余情形 WARN 渐进。**plan 出口**——任务块 / 每任务 `<verify>` 缺失一律 BLOCKED;任务图的依赖环 / 缺失依赖与并行写冲突的写写,对新 change BLOCKED、旧 change WARN 渐进;读写对新旧 change 均仅 WARN。它不是绕过签名门禁,而是把「签名不匹配」重新收敛为「匹配」。
171
+
155
172
  ### Evidence Recording
156
173
 
157
174
  After completing a Node:
@@ -163,13 +180,17 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs record <node-id> '{"su
163
180
 
164
181
  All artifacts in `.specs/<change-id>/`. Cross-change files in `.specs/` (CONTEXT.md, LESSONS.md, CHANGELOG.md).
165
182
 
183
+ > **模板权威**:工件段形以 `flow-kit/templates/**` 为唯一权威。
184
+ > **archive 定位与读法**:`.specs/archive/**` 是历史证据。**何时可读**:工作区文档明确要求(如断点续传 / 决策追溯),或某 guard 硬校验的约定在模板与 LESSONS 中查不到时;**读什么**:只取结构与证据;**不读什么**:不作为格式规范或决策依据,不得以归档工件对齐段形。
185
+
166
186
  ### Scripts
167
187
 
168
188
  > **命令路径的平台化**:本文件命令统一为**权威源设计形态** `node .claude/skills/flow-comet/scripts/...`。安装时由 prepare-env 按平台处理——Claude Code 平台零替换(即此形态);Codex 平台自动替换为 `node .agents/skills/flow-comet/scripts/...`(技能安装于 `.agents/skills/`,Codex 自动发现)。相对引用(`reference/`、`flow-kit/`)不替换——随技能目录整体复制,相对位置不变。手动复制(方案 C)仅面向 Claude Code;Codex 请用安装器。
169
189
 
170
190
  | 脚本 | 用途 |
171
191
  |------|------|
172
- | `workflow-state.mjs` | 状态管理:init/status/next/select/record/advance/skill-load/execution-mode/config/verify-fail(verify 失败计数,第 4 次 BLOCKED) |
192
+ | `workflow-state.mjs` | 状态管理:init/status/next/select/record/advance/skill-load/execution-mode/config/verify-fail(verify 失败计数,第 4 次 BLOCKED)/replan(计划重校重签) |
193
+ | `workflow-state.mjs replan` | 计划重校重签:`replan <reason> --authorized-by <source> [--continue-round <n>]` 在 execute / subagent-execute 相位重跑任务图与字段校验并重录任务集签名(仅这两个相位、每次显式授权、每 change 上限 3 轮、超限继续需显式续轮、缺授权或形态非法一律 BLOCKED 且零改写;写盘前落备份;重复同形态为空操作;只重校重签、绝不豁免校验) |
173
194
  | `workflow-guard.mjs` | 节点门禁:entry/exit/verify 检查 |
174
195
  | `workflow-handoff.mjs` | 子代理交接:request/result/status |
175
196
  | `comet-plan.mjs` | 兼容别名入口(内容为 workflow-state 的别名壳) |
@@ -193,4 +214,4 @@ All artifacts in `.specs/<change-id>/`. Cross-change files in `.specs/` (CONTEXT
193
214
 
194
215
  手动修改这些字段可能导致 guard 校验不一致。若需修正状态,使用 `workflow-state.mjs advance` 或 `workflow-state.mjs select`。
195
216
 
196
- The route, Output Schemas, required Skill calls, and recovery state are defined by `reference/workflow-protocol.json`. 恢复语义见 `reference/recovery.md`(workflow-run 为主模型,comet-overlay 为平台模型)。
217
+ The route, Output Schemas, required Skill calls, and recovery state are defined by `reference/workflow-protocol.json`. 恢复语义见 `reference/recovery.md`。
@@ -1 +1 @@
1
- 1.6.0
1
+ 1.6.2
@@ -73,6 +73,34 @@ description: "Use when the user wants the flow-comet managed workflow for flow-k
73
73
  | "跳过 entry 直接 exit,反正没检查" | 新 change 未 entry 直接 exit → BLOCKED(进入检查不可跳过);旧 change WARN 渐进 |
74
74
  | "SUMMARY 不写,任务先标 done" | 新 change done 任务缺 SUMMARY → BLOCKED(产物完整性强制);旧 change WARN 渐进 |
75
75
  | "subagent-execute 阶段,我直接改源码更快" | 协调者禁令:subagent-execute 阶段主会话禁止写源码(hook 白名单只允许 .specs/,Write/Edit 与 Bash 写命令均物理拦截),必须 worktree 委托子代理 |
76
+ | "用户要健康检查 / 同步架构,我给他 init 一个新 change" | 三条侧命令(evolve / health / context-scan)**不进 8 节点流程**——它们不路由、不 entry/exit、不写节点证据;按下方「侧命令」小节的命令面直接执行即可 |
77
+
78
+ ## 侧命令(横向命令 · 不进 8 节点流程)
79
+
80
+ 随包分发的三条**侧命令**不属于 8 节点流程:不参与节点路由,不被 `entry` / `exit` 门禁校验,也不会在流程里自动触发——一律由用户**显式调用**,涉及写入的动作要**人工逐项确认**。**上游对应物(只读基准,不修改)**:`flow-kit/prompts/{A-evolve,M-health,I-intel-scan}.md`——三条命令均已按本仓语义**显式覆盖**上游表述。**以下上游语义不采用**:① 把三条命令当作流程内的节点或自动触发项(上游各自成篇、不声明与 8 节点的关系)→ 本仓一律**显式调用**:不路由、不 `entry` / `exit`、不写节点证据;② 把三条命令的语义细则抄进入口册(同一口径两处表达)→ 本仓只在入口留**指针**,细则以各自技能册的「覆盖声明」为单一表达。**冲突处以各自技能册的「覆盖声明」与引擎实现为准**。用户表达下列意图时,**不要** `init` 新 change、**不要** `entry` / `exit` 任何节点,直接加载对应技能并按其协议执行:
81
+
82
+ | 命令 | 触发词(用户怎么说) | 用途 | 落盘产物 | 技能 |
83
+ |------|---------------------|------|---------|---------|
84
+ | `evolve` | 同步架构 / 整理沉淀 / evolve / 同步 CONTEXT | 扫归档 change 设计文档的架构沉淀段(`§9`)→ 候选清单 → **逐项** review 后 patch 项目级文档 | `.specs/evolve/<日期>-EVOLVE.md` | `flow-comet-evolve` |
85
+ | `health` | 健康检查 / health / 体检 / 技术债扫描 / 巡检 / 代码库健康度 | 确定性收集器出一份体检报告(代码体检工具在场时并入其 4 维结果并标注来源,缺席则显式降级声明) | `.specs/health/<日期>-HEALTH.md` | `flow-comet-health` |
86
+ | `context-scan` | 重扫上下文 / 刷新 CONTEXT / context-scan | 重跑上下文探测 → 与上次基线逐项比对(新增 / 消失 / 变更)→ 更新扫描时间 | `.specs/context-scan/<日期>-SCAN.md` | 无独立技能,按下方命令面直接执行 |
87
+
88
+ 命令面(路径随安装平台替换——见「Scripts」小节的平台化说明;`--root` 缺省为当前目录):
89
+
90
+ ```bash
91
+ node .claude/skills/flow-comet/scripts/evolve.mjs scan [--root <项目根>]
92
+ node .claude/skills/flow-comet/scripts/evolve.mjs apply <候选 id> [<候选 id> ...] [--root <项目根>] [--scanner <执行工具>]
93
+ node .claude/skills/flow-comet/scripts/health.mjs [--root <项目根>] [--stdout]
94
+ node .claude/skills/flow-comet/scripts/context-scan.mjs [--root <项目根>] [--stdout]
95
+ ```
96
+
97
+ **共同边界**:
98
+
99
+ - **只读优先**:任何写入都要显式参数或显式确认;侧命令不改业务代码,也不改 hook 判定语义。
100
+ - **不进 change 生命周期**:不写 `currentNode` / `completedNodes` / 节点证据,不替代任何节点产出。`evolve` 落 `last_evolve_at`、`context-scan` 落 `last_intel_scan`,两者都是**项目级元数据**,不是流程进展。
101
+ - **人工确认不可跳过**:`evolve` 的候选必须逐条 review 后才 `apply`,禁止一次性整批写入;`health` 只出报告与建议,是否立项由用户决定,它自己不开 change。
102
+ - **到期提示**:`node .claude/skills/flow-comet/scripts/workflow-state.mjs status` 在 `last_evolve_at` 距今 > 60 天,或该时刻之后新增 ≥ 5 个带 `§9` 的归档 change 时,输出一行 `EVOLVE-DUE:`(含上次沉淀时间与「建议显式调用 evolve」指引);未达阈值**零输出**(从未跑过 evolve、无该字段的项目同样不提示)。提示只是提醒——不自动加载也不自动执行 `evolve`,是否同步由用户决定。
103
+ - **时间纪律(侧命令的产物与判断同一口径)**:人可见时间戳一律**本地时间 + 显式偏移**(`YYYY-MM-DDTHH:mm:ss±HH:mm`;生成走 `time-utils.mjs` 单一权威,禁裸 `new Date()` 拼接);时间**比较一律 `Date.parse` 差值**(兼容历史 `Z` 形态,禁字符串字典序、禁目测字形);**判活与判时以文件 mtime 或 git 时间为准,`date` 与代理注册表不作基准**(归档窗口另取归档目录名的日期前缀)。这三条已写入**验证阶梯**的「环境 / 过程纪律」条,侧命令的报告、基线与到期判定都按它执行。
76
104
 
77
105
  ## Workflow Nodes
78
106
 
@@ -94,7 +122,7 @@ description: "Use when the user wants the flow-comet managed workflow for flow-k
94
122
  | 节点 | Implementation | Required Calls | Enforcement |
95
123
  |------|---------------|----------------|-------------|
96
124
  | open | flow-comet-open | flow-comet-change, flow-comet-requirement | guarded |
97
- | design | flow-comet-design | flow-comet-design, flow-comet-ui-design (advisory,不要求声明) | guarded |
125
+ | design | flow-comet-design | flow-comet-design, flow-comet-ui-design (guarded,仅前端适用——前端须先 skill-load 声明) | guarded |
98
126
  | plan | flow-comet-plan | flow-comet-task | guarded |
99
127
  | execute | flow-comet-execute | flow-comet-dev | guarded |
100
128
  | subagent-execute | flow-comet-subagent-execute | flow-comet-dev (handoff) | handoff-guarded |
@@ -104,6 +132,8 @@ description: "Use when the user wants the flow-comet managed workflow for flow-k
104
132
 
105
133
  **新 change 严格模式**:`init` 创建的 change 标记为"新"(`newChange: true`)——新 change 下全部内容级检查强制 BLOCKED(处置标记/缓存证据/波次散文/越权委托/SUMMARY 完整性/进入证据等);旧 change(历史遗留,无标记)保持渐进 WARN。执行者可通过 `status` 确认当前 change 的新旧。
106
134
 
135
+ > **design 行绑定的前端适用性**:`flow-comet-ui-design` 与协议一致为 `guarded`,但只对**前端 change** 适用——前端项目须先用 Skill 工具加载该技能,再运行 `skill-load design flow-comet-ui-design --prompt flow-kit/prompts/2a-ui-design.md` 建标记,并在 record 载荷带 `required-skill:design.flow-comet-ui-design`(design 出口不再自动补写该条目,缺工件或缺声明即 BLOCKED 并给出恢复路径);非前端项目不加载、不声明,出口打印可见的 `UI-DESIGN: skipped(非前端)` 后放行;旧 change 保持渐进,缺件仅 WARN。前端判据是**结构级**的:`CHANGE.md` 的「视觉调性」段在场,且段内的「不适用」标记成**结构形态**——该标记**独立行**、居**行首**(可带列表符号 / 引用 / 加粗),或写在适用性类标签(`适用性` / `适用范围` / `是否前端` / `视觉调性` / `前端` / `界面` / `适用`)的**字段值位**;标记之后须成**词形边界**(紧跟空白、标点或行尾),命中即回显**命中片段**自证。段内其它位置顺带提到「不适用」(如「不适用于暗色主题」)不算标注,仍判前端。
136
+
107
137
  **节点技能两层加载模型(入口层 · 双步硬规则)**:路由到节点后,以下两步**都不可跳过**:
108
138
 
109
139
  1. **用 Skill 工具加载该节点的 Implementation 技能**(见下方 Skill Bindings 表 Implementation 列,如 execute → flow-comet-execute)。**不得跳过**——只读取 SKILL.md 文件不叫加载;真正让该 skill 的指令生效的是 Skill 工具把它注入本次会话。
@@ -166,6 +196,21 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs reenter <target> --aut
166
196
  - **顺序**:命令成功后再写修复内容——archive 阶段写入白名单只放行 `.specs/<change-id>/KNOWN-ISSUES.md` 等少数路径;重入后写入权限跟随目标节点,此时才追加 Fix 任务 / 修改工件。
167
197
  - **边界**:归档移动已发生或 change 已 `completed` → BLOCKED,走人工处置或新 change / hotfix;重复调用同一目标 → 空操作(输出 `REENTRY: 空操作——…`,不备份、不计数、不改写 state),不会静默跳过。
168
198
 
199
+ ### 受控重校(`replan` · execute 源)
200
+
201
+ 计划在执行中被证明有缺陷、任务集因此需要修订时,用受控重校重新校验并重签任务集——不跳节点、不重置任何完成态:
202
+
203
+ ```bash
204
+ node .claude/skills/flow-comet/scripts/workflow-state.mjs replan "<reason>" --authorized-by <source> [--continue-round <n>]
205
+ ```
206
+
207
+ - **何时用**:`currentNode` 停在 `execute` / `subagent-execute`,且任务集在进入该节点后被修订、出口因此报「签名不匹配」时;修订后的任务集必须自身合法。
208
+ - **授权**:每次调用都需要用户显式授权——`--authorized-by` 记录授权来源,位置参数记录原因;引擎把授权留痕写入当前节点的嵌套证据(`state.evidence.<node>.replanAuthorization`)。缺授权、值为空/纯空白或形态非法一律 BLOCKED,且 state 字节零改写。
209
+ - **上限与显式续轮**:每 change 最多 3 轮;第 4 次 BLOCKED 并给出「继续 / 停止」人工裁决指引。人工裁决「继续」须追加 `--continue-round <n>`(正整数,且 n ≥ 已用轮次 + 1)作显式续轮授权:满足则放行并计入下一轮,审计行打印续轮标记;未到上限即传该参数、或轮次不足一律 BLOCKED 且零改写。轮次与审计事件记入 `state.history`(事件类型 `replan-applied`),成功输出 `REPLAN: <node> 重新校验通过(授权源 <source>;第 n/3 轮;备份 <file>)` 与 `REASON: <text>` 两行。
210
+ - **备份**:改写前自动落 state 快照 `.specs/<change-id>/replan-backups/<UTC ISO>-pre-replan.json`(时间戳中的 `:` 替换为 `-`),并记录 sha256 指纹,供审查核验与手工回滚。
211
+ - **幂等与零改写**:目标形态已成立时的重复同形态调用 = 空操作(输出 `REPLAN: 空操作——…`,不备份、不计数、不写事件、不改写 state),不会静默跳过。
212
+ - **绝不豁免校验**:`replan` 只做「重新校验 + 重新签名」——判据与 plan 出口同源,处置按路径分列:**replan 重校**——任务块 / 每任务 `<verify>` / 任务图(依赖环 / 缺失依赖)任一不成立,或并行写冲突的写写(write∩write)成立,一律 BLOCKED(状态零改写);读写(read∩write)仅 WARN 不阻断;7 字段完整性只在「新模板形态(含 `<name>`)+ 新 change」缺字段时 BLOCKED,其余情形 WARN 渐进。**plan 出口**——任务块 / 每任务 `<verify>` 缺失一律 BLOCKED;任务图的依赖环 / 缺失依赖与并行写冲突的写写,对新 change BLOCKED、旧 change WARN 渐进;读写对新旧 change 均仅 WARN。它不是绕过签名门禁,而是把「签名不匹配」重新收敛为「匹配」。
213
+
169
214
  ### Evidence Recording
170
215
 
171
216
  After completing a Node:
@@ -177,14 +222,18 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs record <node-id> '{"su
177
222
 
178
223
  All artifacts in `.specs/<change-id>/`. Cross-change files in `.specs/` (CONTEXT.md, LESSONS.md, CHANGELOG.md).
179
224
 
225
+ > **模板权威**:工件段形以 `flow-kit/templates/**` 为唯一权威。
226
+ > **archive 定位与读法**:`.specs/archive/**` 是历史证据。**何时可读**:工作区文档明确要求(如断点续传 / 决策追溯),或某 guard 硬校验的约定在模板与 LESSONS 中查不到时;**读什么**:只取结构与证据;**不读什么**:不作为格式规范或决策依据,不得以归档工件对齐段形。
227
+
180
228
  ### Scripts
181
229
 
182
230
  > **命令路径的平台化**:本文件命令统一为**权威源设计形态** `node .claude/skills/flow-comet/scripts/...`。安装时由 prepare-env 按平台处理——Claude Code 平台零替换(即此形态);Codex 平台自动替换为 `node .agents/skills/flow-comet/scripts/...`(技能安装于 `.agents/skills/`,Codex 自动发现)。相对引用(`reference/`、`flow-kit/`)不替换——随技能目录整体复制,相对位置不变。手动复制(方案 C)仅面向 Claude Code;Codex 请用安装器。
183
231
 
184
232
  | 脚本 | 用途 |
185
233
  |------|------|
186
- | `workflow-state.mjs` | 状态管理:init/status/next/select/record/advance/skill-load/execution-mode/config/verify-fail(verify 失败计数,第 4 次 BLOCKED)/reenter(archive 源受控重入) |
234
+ | `workflow-state.mjs` | 状态管理:init/status/next/select/record/advance/skill-load/execution-mode/config/verify-fail(verify 失败计数,第 4 次 BLOCKED)/reenter(archive 源受控重入)/replan(execute 源计划重校重签) |
187
235
  | `workflow-state.mjs reenter` | 归档后受控重入:`reenter <target> --authorized-by <source> --reason <text> [--continue-round <n>]` 把工作归属退回 execute / subagent-execute / review / verify 之一(仅 archive 源、归档移动前、每次显式用户授权、每 change 上限 3 轮,超限继续需显式续轮授权) |
236
+ | `workflow-state.mjs replan` | 计划重校重签:`replan <reason> --authorized-by <source> [--continue-round <n>]` 在 execute / subagent-execute 相位重跑任务图与字段校验并重录任务集签名(仅这两个相位、每次显式授权、每 change 上限 3 轮、超限继续需显式续轮、缺授权或形态非法一律 BLOCKED 且零改写;写盘前落备份;重复同形态为空操作;只重校重签、绝不豁免校验) |
188
237
  | `workflow-guard.mjs` | 节点门禁:entry/exit/verify 检查 |
189
238
  | `workflow-handoff.mjs` | 子代理交接:request/result/status |
190
239
  | `comet-plan.mjs` | 兼容别名入口(内容为 workflow-state 的别名壳) |
@@ -1,12 +1,12 @@
1
1
  # KNOWN-ISSUES(归档遗留清单模板)
2
2
 
3
3
  > 用途:归档节点使用——REVIEW.md 发现区标记为 `[转待办]` 的 Minor 发现 + 已知限制 → 归档时生成 KNOWN-ISSUES.md 置于 `.specs/archive/<日期>-<change-id>/` 下(归档输出 Schema 的必选产物;无遗留也显式写「无遗留问题」)。
4
- > 用法:按实际 change 修订本模板;「遗留清单」节记录本 change 结束后仍需跟进的事项,每项标注跟进动作与责任批次。
4
+ > 用法:按实际 change 修订本模板;「遗留清单」节记录本 change 结束后仍需跟进的事项,每项标注跟进动作与责任窗口。
5
5
  > 纪律:本模板为分发产物——零过程代号;归档实例(.specs/archive/ 下)不受此限。
6
6
 
7
7
  ## 遗留清单
8
8
 
9
- - **版本基线**:版本 1.4.2 + 144 场景数 + 系统测试 60 项(发布已对齐;后续发布按版本纪律同步全库变体)
9
+ - **版本基线**:不写死版本/计数——需要时读发布权威(`docs/VERSIONS.md` 与 `CHANGELOG.md` 的最新已发布版本段——不是 `[Unreleased]`)(主仓适用;安装副本可读 `skills/flow-comet/INSTALLED_VERSION`)
10
10
  - **初始化检测相关文档既有过程用语**:`reference/init-detection.md` 等含历史过程用语(历史遗留,由人工清单跟进;清理后删除本条目)
11
11
  - **待复查观察项**:验证过程中记录,未达修复优先级——后续迭代按需复查
12
12
  - **本地文档健康检查工具版本映射**:本地检查工具的版本/场景数一致性子检查用发布时快照,开发窗口期(版本未发布、场景数已增)会误报——由系统测试集的结构检查放行逻辑覆盖,权威判定在引擎自测
@@ -15,5 +15,5 @@
15
15
  ## 使用说明
16
16
 
17
17
  - **归档时**:把 REVIEW.md 发现区 `[转待办]` 的 Minor 条目与已知限制汇总为本清单;无遗留则写「无遗留问题」(KNOWN-ISSUES.md 为归档输出 Schema 必选产物,guard 校验存在性)
18
- - **跟进**:下一 change 或维护批次按清单逐项处置,处置后移除条目并注明处置结果
18
+ - **跟进**:下一 change 或维护窗口按清单逐项处置,处置后移除条目并注明处置结果
19
19
  - **验证**:归档流程的完整链路(遗留清单 + 目录移动 + 完成态)由系统测试集 H 面覆盖
@@ -15,7 +15,7 @@
15
15
 
16
16
  ## 二、判定规则
17
17
 
18
- - **全部 PASS = 级 2(系统测试集)完整通过**:与级 1 引擎回归(guard-self-test 全绿)构成统一测试集两级基线,方可进入下一级验证(CLI 冒烟)。
18
+ - **全部 PASS = 系统测试集完整通过**:与引擎回归套件(guard-self-test 全绿)构成统一测试集两级基线,方可进入下一级验证(CLI 冒烟)。
19
19
  - **任一 FAIL**:修复后重跑(修复只改权威源一处,重跑至全绿)。
20
20
  - **误通过 = 测试无效,必须修**:该拦截未拦截 / 该放行未放行,说明测试自身没守住机制边界——测试先于功能守边界,不许自欺("当时能过"不等于"现在正确")。
21
21
 
@@ -23,75 +23,75 @@
23
23
 
24
24
  ### A. 状态机与路由
25
25
 
26
- 覆盖:init 全分支(状态写入/工件目录/同 id 重跑防护/分支模式)、status 节点推导与无活跃兜底、next 推进与状态漂移校正、next 未出口节点严格拦截、select 切换、advance 推进、record 基础证据、execution-mode 切换与记录、config 设置与非法值拒绝、多趟路由真实链路(并→串→交替与多波依赖)、plan 出口依赖环负例与恢复、多趟路由时序收敛、plan 出口文件依赖检出、Fix 批次闭环(review/verify 源受控归位 execute → 四类出口 → 回源节点出口;回程审计行按证据分为真实修复锚、正常多趟中性回程、旧态证据不足未分类三态;越界拦截与旧 change 渐进)。
26
+ 覆盖:init 全分支(状态写入/工件目录/同 id 重跑防护/分支模式)、status 节点推导与无活跃兜底、next 推进与状态漂移校正、next 未出口节点严格拦截、select 切换、advance 推进、record 基础证据、execution-mode 切换与记录、config 设置与非法值拒绝、多趟路由真实链路(并→串→交替与多波依赖)、plan 出口依赖环负例与恢复、多趟路由时序收敛、plan 出口文件依赖检出、修复回路闭环(review/verify 源受控归位 execute → 四类出口 → 回源节点出口;回程审计行按证据分为真实修复锚、正常多趟中性回程、旧态证据不足未分类三态;越界拦截与旧 change 渐进)。
27
27
 
28
- 测试项(23):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(旧)不卡死;多波次修复、源节点未进入、旧态证据不足输出中性未分类回程的归因子场景(真实命令)。
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
29
 
30
30
  ### B. 声明机制
31
31
 
32
32
  覆盖:skill-load 声明标记写入(协议归属)、非法参数拒绝不落标记、record 缺声明标记拦截、声明后记录通过、声明时间序自洽、损坏声明标记 fail-closed、委托范围条目豁免(有委托通过/无委托拦截)、exit 协议声明标记校验(真实链路通过/无标记·空协议·损坏拦截)、旧项目兼容(未激活声明机制照常通过)。
33
33
 
34
- 测试项(9):B1 声明标记写入 / B2 非法参数拒绝 / B3 缺声明标记拦截 / B4 声明后记录通过 / B5 声明时间序自洽 / B6 损坏标记 fail-closed / B7 委托范围条目豁免 / B8 exit 协议声明标记校验 / B9 旧项目兼容。
34
+ 测试项:B1 声明标记写入 / B2 非法参数拒绝 / B3 缺声明标记拦截 / B4 声明后记录通过 / B5 声明时间序自洽 / B6 损坏标记 fail-closed / B7 委托范围条目豁免 / B8 exit 协议声明标记校验 / B9 旧项目兼容。
35
35
 
36
36
  ### C. 委托链路
37
37
 
38
38
  覆盖:handoff 请求/结果/状态全链路(含提交校验与零提交资格——输出为空或全部可证明被 gitignore 可合法闭环;glob / 越界 / 非 git / tracked 的零提交声明一律拒绝,不得绕过提交子集校验、拦截时 state 字节零改写)、红绿证据时间序(先红后绿通过/补录拦截)、委托后 exit 证据键名契约与契约校验(通过/空交接拦截)。
39
39
 
40
- 测试项(3):C1 handoff 全链路(含零提交资格正例与越权负例)/ C2 红绿证据时间序 / C3 委托后 exit 契约校验。
40
+ 测试项:C1 handoff 全链路(含零提交资格正例与越权负例)/ C2 红绿证据时间序 / C3 委托后 exit 契约校验。
41
41
 
42
42
  ### D. hook 写白名单
43
43
 
44
44
  覆盖:open 阶段工件放行与源码拦截、execute 按执行模式收窄(subagent 只写 .specs/,direct 放宽)、归档阶段白名单与完成态放行。
45
45
 
46
- 测试项(3):D1 open 阶段白名单 / D2 execute 执行模式收窄 / D3 归档阶段白名单与完成态放行。
46
+ 测试项:D1 open 阶段白名单 / D2 execute 执行模式收窄 / D3 归档阶段白名单与完成态放行。
47
47
 
48
48
  ### E. 自定义协议
49
49
 
50
50
  覆盖:自定义协议加载路由与节点推导(`--protocol`/env 加载)、自定义节点声明机制与出口全链路(含技能绑定)、内置特化校验对自定义协议不误触发。
51
51
 
52
- 测试项(2):E1 加载路由与节点推导 / E2 声明机制与出口全链路。
52
+ 测试项:E1 加载路由与节点推导 / E2 声明机制与出口全链路。
53
53
 
54
54
  ### F. 自动初始化
55
55
 
56
56
  覆盖:上下文缺失提示且不自动生成、跳过记忆、新鲜上下文静默、生成协作全链路(7 段校验 + 扫描时间记录)。
57
57
 
58
- 测试项(4):F1 上下文缺失提示 / F2 跳过记忆 / F3 新鲜上下文静默 / F4 生成协作全链路。
58
+ 测试项:F1 上下文缺失提示 / F2 跳过记忆 / F3 新鲜上下文静默 / F4 生成协作全链路。
59
59
 
60
60
  ### G. 分支模式
61
61
 
62
62
  覆盖:init 建分支与一致性、归档入口分支校验、分支一致性失配警告。
63
63
 
64
- 测试项(3):G1 init 建分支与一致性 / G2 归档入口分支校验 / G3 一致性失配警告。
64
+ 测试项:G1 init 建分支与一致性 / G2 归档入口分支校验 / G3 一致性失配警告。
65
65
 
66
66
  ### H. verify 与归档
67
67
 
68
- 覆盖:验证命令真实执行与超时配置、归档完整流程(遗留清单 + 目录移动 + 完成态)、归档路径声明标记查找(先移目录后 exit 顺序下标记只存归档路径)、归档源受控重入真实命令链路(未授权 / 授权形态非法 fail-closed 且状态字节零改写;完整授权转移 + 嵌套证据 + 审计事件 + 备份指纹;幂等重放零改写与按备份手工回滚;轮次上限后 BLOCK 与人工裁决指引)。
68
+ 覆盖:验证命令真实执行与超时配置、归档完整流程(遗留清单 + 目录移动 + 完成态)、归档路径声明标记查找(先移目录后 exit 顺序下标记只存归档路径)、归档源受控重入真实命令链路(未授权 / 授权形态非法 fail-closed 且状态字节零改写;完整授权转移 + 嵌套证据 + 审计事件 + 备份指纹;幂等重放零改写与按备份手工回滚;轮次上限后 BLOCK 与人工裁决指引)、受控计划重校(replan)真实命令链路(任务集修订后出口被签名门禁 BLOCK 且零改写 → 授权 replan 重签 → 出口放行并正常路由;未授权 / 轮次不足 fail-closed 且零改写、上限后 BLOCK 与显式续轮放行)、强制推进留痕(advance 写 advance-forced 事件 + `status.forcedNodes` 派生可见)。
69
69
 
70
- 测试项(8):H1 验证命令真实执行与超时 / H2 归档完整流程 / H3 归档路径声明标记查找 / H4 归档后自动补声明标记写归档路径(不重建活动目录) / H5 受控重入:未授权调用 fail-closed 且状态字节零改写 / H6 受控重入:完整授权链路(转移 + 嵌套证据 + 审计事件 + 备份指纹 + 审计行) / H7 受控重入:幂等重放零改写与按备份手工回滚可执行 / H8 受控重入:轮次上限后 BLOCK 与人工裁决指引。
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
71
 
72
72
  ### I. 异常路径
73
73
 
74
74
  覆盖:损坏状态文件 fail-closed、缺工件出口拦截、非法参数拒绝、状态字段类型非法拦截。
75
75
 
76
- 测试项(4):I1 损坏状态文件 fail-closed / I2 缺工件出口拦截 / I3 非法参数拒绝 / I4 状态字段类型非法拦截。
76
+ 测试项:I1 损坏状态文件 fail-closed / I2 缺工件出口拦截 / I3 非法参数拒绝 / I4 状态字段类型非法拦截。
77
77
 
78
78
  ### J. 文档一致性
79
79
 
80
80
  覆盖:双语健康检查(英文文档零中文/中文文档零英文长句/双语镜像对称/版本场景数)、公开产物零代号检查(调用仓库本地工具;安装副本无仓库文档跳过)。注:本地工具为发布快照——开发窗口期场景数一致性子检查按结构检查放行,权威判定在引擎自测。
81
81
 
82
- 测试项(2):J1 双语健康检查 / J2 公开产物零代号检查。
82
+ 测试项:J1 双语健康检查 / J2 公开产物零代号检查。
83
83
 
84
84
  ### K. 安装器(版本标识 + 多平台)
85
85
 
86
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
87
 
88
- 测试项(18):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 词元红线)。
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
89
 
90
90
  ### L. 执行遗漏防护(真实链路)
91
91
 
92
92
  覆盖:进入证据(entry 记录 enteredNodes、正常流程 exit 无误报——真实链路中节点顺序检查先于进入警告,未 entry 场景由引擎回归覆盖)、空退出豁免(显式 emptyExitApproved 通过 / 无豁免仍拦截)、空仓库提示(init 在无提交仓库输出 EMPTY-REPO)。
93
93
 
94
- 测试项(3):L1 进入证据 / L2 空退出豁免 / L3 空仓库。
94
+ 测试项:L1 进入证据 / L2 空退出豁免 / L3 空仓库。
95
95
 
96
96
  ## 四、附:design 节点 required 自指核验结论
97
97
 
@@ -1,20 +1,20 @@
1
1
  # dsh 平台锚定参考(dsh-platform)
2
2
 
3
3
  > 维护者参考文档:dsh 平台适配的版本锚定、安装形态、API 签名、桥接 loader 契约与验证记录模板。
4
- > 权威依据:`@.specs/deepseek-harness-platform/DESIGN.md`(D1~D10 / 7.1 / 7.2 / 7.3)、`@.specs/deepseek-harness-platform/REQUIREMENT.md`(AC-1~AC-7)、`@.specs/adr/ADR-005-dsh-install-via-installer.md`。
5
- > dsh 为 dev-preview:本文件锚定认证版本(0.1.5-rc.1,2026-09-10 全接缝运行时认证;历史锚 0.1.0-rc.6 → 0.1.1-rc.2 实测线);破坏性变更风险显式声明。
4
+ > 权威依据:`@.specs/archive/2026-08-18-deepseek-harness-platform/DESIGN.md`(D1~D10 / 7.1 / 7.2 / 7.3)、`@.specs/archive/2026-08-18-deepseek-harness-platform/REQUIREMENT.md`(AC-1~AC-7)、`@.specs/adr/ADR-005-dsh-install-via-installer.md`。
5
+ > dsh 为 dev-preview:本文件锚定认证版本(0.1.7-rc.2,2026-09-27 全接缝重认证;历史锚 0.1.0-rc.6 → 0.1.1-rc.2 → 0.1.5-rc.1);破坏性变更风险显式声明。
6
6
 
7
7
  ## 1. 版本锚定
8
8
 
9
9
  | 项 | 值 |
10
10
  |---|---|
11
- | 认证 dsh 版本 | `0.1.5-rc.1`(2026-09-10 全接缝运行时认证;历史锚 `0.1.0-rc.6` → `0.1.1-rc.2` 实测线) |
11
+ | 认证 dsh 版本 | `0.1.7-rc.2`(2026-09-27 全接缝重认证;历史锚 `0.1.0-rc.6` → `0.1.1-rc.2` → `0.1.5-rc.1`) |
12
12
  | 安装入口 | `node scripts/prepare-env.mjs --target <项目> --platform dsh`(或交互终端多选勾选 dsh)——唯一入口(D1) |
13
13
  | 重置/重新生成(purge——删除后重建到完整安装态,**不是卸载**) | `node scripts/prepare-env.mjs --target <项目> --purge --platform dsh --yes` |
14
14
  | npm 包 | **自 `1.5.0-rc.3` 起已发布**(`npm i -g flow-comet` → `fcomet init`,dist-tag `latest`)——分发的为**安装器**,非 dsh 插件包;旧 npm 插件包安装形态已废弃(verify 阶段推翻,见 ADR-005) |
15
15
  | 破坏性变更 | dev-preview 中 `tools/pre-execute` 签名 / skill 发现 rank / `DSH_HOME` 语义可能变化;低于锚定版本时拦截/发现可能失效 |
16
16
 
17
- > 版本不匹配时拦截可能失效——必须文档警示 + 级 3 实测兜底(D9)。
17
+ > 版本不匹配时拦截可能失效——必须文档警示 + 真实平台会话实测兜底(D9)。
18
18
 
19
19
  **bridge-check 版本比较语义(基础版本比较)**:桥接健康检查比较 loader 的 `// BRIDGE_VERSION:` 发布戳与技能包 `INSTALLED_VERSION` 时,两侧先剥离 git-describe 开发态后缀 `-<领先提交数>-g<hash>`、再按基础版本比较:
20
20
 
@@ -88,7 +88,7 @@ ctx.on('tools/pre-execute', async (exec, next) => {
88
88
  ### 激活(天然项目级)
89
89
 
90
90
  - 目录物理存在即激活——dsh 启动自动发现 `/flow-comet`(rank 100,chokidar 热发现免重启);未安装该目录的项目不可见(无痕迹判定、无 chicken-and-egg)。
91
- - dsh 对项目 AGENTS.md 的注入行为**已认证**(0.1.5-rc.1 headless 会话:项目根 AGENTS.md 作为上下文注入,托管区内容被会话逐字引用——见下方认证记录);**边界**:认证面向 headless profile,dsh-tui / web 运行时未验。
91
+ - dsh 对项目 AGENTS.md 的注入行为**已认证**(0.1.7-rc.2 headless 会话:项目根 AGENTS.md 作为上下文注入,托管区内容被会话逐字引用——见下方认证记录);**边界**:认证面向 headless profile,dsh-tui / web 运行时未验。
92
92
 
93
93
  ### 重置/重新生成(prepare-env --purge --yes——删除后重建,**不是卸载**)
94
94
 
@@ -109,7 +109,7 @@ ctx.on('tools/pre-execute', async (exec, next) => {
109
109
  3. **流程态门(B 方案——包含性仅运行中生效)**:读项目根 `.flow-comet/flow-comet-state.json`(UTF-8 BOM 容错;判定规则锚定 guard `comet-hook-guard.mjs` 的空闲态门——grep 锚点:`grep -n "if (!state.activeChange)"`):空闲(无 state / 无 `activeChange` / `status==='completed'`)→ 直接 `next()` 放行——跳过包含性校验与 guard 白名单(与 Claude Code / Codex 的 active-change 门语义对齐);解析失败 / 未知 status → WARN + fail-closed deny(不视为空闲放行);`activeChange` 存在且 `status==='running'` 或缺失(undefined)→ 继续下方包含性校验与 guard(现状不变)。
110
110
  - **空闲边界(refined)**:空闲 = 无 state / 无 activeChange / status==='completed' → 项目外写 next() 放行;解析失败 / 未知 status 保持 fail-closed deny(不视为空闲),与 Claude Code / Codex 的 guard 语义一致。
111
111
  4. **包含性校验**:Write/Edit 的 `file_path` 必须解析后位于项目根内——`realpathSync.native` 展开 Windows 8.3 短路径(词法 path.relative 会把项目内短路径误判为越界);**运行中**越界直接 deny(不进 guard——guard 侧 target=null 会跳过白名单判定 = fail-open);通过后传规范化长路径。
112
- 5. **代理身份分派(B1——dsh 子代理=执行者)**:读 `exec.agent.session.header.delegationDepth`(`agentDepth(exec)` 纯函数)——**>0 = 子代理(执行者)→ 跳过 guard 白名单判定直接 `next()` 放行**(子代理写源码是执行者职责,对应 Claude Code worktree 子代理物理自由写;形状 fail-closed 与项目根包含性校验已在上方对子代理同样执行,不因身份放宽);**0/缺失 = 协调者 → 走 guard 白名单判定**(协调者禁令物理拦截保留)。dsh 子代理系统在 dsh-base 自带(`tool-subagent`/`subagent-spawn-in-process` 等,headless/web/tui 全 profile 激活),`childSessionMeta` 写入 delegationDepth=parentDepth+1(dsh-subagent 源码锚定 rc.6);不识别此字段会导致 subagent 执行模式下子代理写源码被 guard 白名单(execute → `.specs/`)误拦(B1,DOGFOOD-REPORT 实证)。级 3 实测(2026-08-18 UAT-7):真实模型调 subagent → 子代理(delegationDepth:1)写 `scripts/` 放行、协调者(delegationDepth:0)写同路径被 deny 保留。
112
+ 5. **代理身份分派(B1——dsh 子代理=执行者)**:读 `exec.agent.session.header.delegationDepth`(`agentDepth(exec)` 纯函数)——**>0 = 子代理(执行者)→ 跳过 guard 白名单判定直接 `next()` 放行**(子代理写源码是执行者职责,对应 Claude Code worktree 子代理物理自由写;形状 fail-closed 与项目根包含性校验已在上方对子代理同样执行,不因身份放宽);**0/缺失 = 协调者 → 走 guard 白名单判定**(协调者禁令物理拦截保留)。dsh 子代理系统在 dsh-base 自带(`tool-subagent`/`subagent-spawn-in-process` 等,headless/web/tui 全 profile 激活),`childSessionMeta` 写入 delegationDepth=parentDepth+1(dsh-subagent 源码锚定 rc.6);不识别此字段会导致 subagent 执行模式下子代理写源码被 guard 白名单(execute → `.specs/`)误拦(B1,项目内验证记录实证)。真实平台会话实测(2026-08-18):真实模型调 subagent → 子代理(delegationDepth:1)写 `scripts/` 放行、协调者(delegationDepth:0)写同路径被 deny 保留。
113
113
  6. **判定调用**:`spawn node <项目根>/.dsh/skills/flow-comet/scripts/comet-hook-guard.mjs before_tool`,stdin JSON `{tool_name, tool_input}`;**spawn cwd 必须 = 会话项目根的长形态规范化(硬性)**(相对 file_path 按 cwd 解析,cwd≠项目根 = fail-open;8.3 短形态项目根若原样传入、而 file_path 已归一化为长形态时,guard 词法 path.relative 得 target=null → 白名单跳过 = fail-open——桥接修复已关闭,系统测试 K11 断言锁定;不得以设 env 替代 cwd);guard 文件缺失(安装未完成/被删除)→ WARN + `next()` 放行(不阻断非 flow-comet 语义);spawn 异常 → fail-closed deny + WARN。
114
114
  7. **决策映射**:exit 0 → `next()` 放行;exit 2 → `{kind:'deny', reason}`(BLOCK 消息 + 恢复指引透传);其它/异常 → fail-closed deny + WARN。
115
115
  - 协议文件:天然在项目内(skill 包 `reference/` 随树复制)——受保护读取满足,**无 FLOW_COMET_PROTOCOL 机制**。
@@ -117,7 +117,7 @@ ctx.on('tools/pre-execute', async (exec, next) => {
117
117
 
118
118
  ## 8. 验证记录模板
119
119
 
120
- > 级 3 / 级 4 执行后按此模板回填;发布前逐项闭环(DESIGN 7.3)。
120
+ > 实测执行后按此模板回填;发布前逐项闭环(DESIGN 7.3)。
121
121
 
122
122
  ### 环境
123
123
 
@@ -127,7 +127,7 @@ ctx.on('tools/pre-execute', async (exec, next) => {
127
127
  - profile:
128
128
  - 临时项目路径:
129
129
 
130
- ### 检查项(级 3 新形态命令——非旧插件冒烟形态)
130
+ ### 检查项(新形态命令——非旧插件冒烟形态)
131
131
 
132
132
  | # | 检查 | 结果 | 证据(命令/输出摘要) |
133
133
  |---|---|---|---|
@@ -154,13 +154,13 @@ ctx.on('tools/pre-execute', async (exec, next) => {
154
154
  - 遗留风险:
155
155
 
156
156
 
157
- ### rc.8 三态冒烟(2026-08-20)
157
+ ### rc.8 三态冒烟(2026-08-20)(历史)
158
158
 
159
159
  - 环境:dsh CLI 0.1.0-rc.8 / Harness 核心 rc.8 / dsh-tui 0.8.5
160
- - 结果:运行中协调者项目外 Write → deny;运行中子代理项目内 Write → next();空闲态(无 state)项目外 Write → next();解析失败/未知 status → fail-closed deny(当轮 system-test ALL PASSED,K11/K12 断言覆盖;当前基线 82/82)
160
+ - 结果:运行中协调者项目外 Write → deny;运行中子代理项目内 Write → next();空闲态(无 state)项目外 Write → next();解析失败/未知 status → fail-closed deny(当轮 system-test ALL PASSED,K11/K12 断言覆盖;当轮基线 82 项(历史))。**记录口径**:历史实测基线保留原始数字并在行内标注(历史)——历史数字是证据,删除不是修法(带标记即被计数过期判据豁免);指针语(「以套件自身输出为准」)只用于当前值。
161
161
  - 载体:prepare-env --platform dsh 经临时项目重推真实 ~/.dsh 桥接 loader,loader 与权威源 SHA-256 一致;真实交互式 TUI/Web 冒烟留待开放项
162
162
 
163
- ### 0.1.5-rc.1 全接缝认证(2026-09-10)
163
+ ### 0.1.5-rc.1 全接缝认证(2026-09-10)(历史)
164
164
 
165
165
  - 环境:dsh CLI 0.1.5-rc.1 / Node v24.14.1 / dsh-tui 0.10.0;headless profile;真实 `~/.dsh`(loader 与权威源逐字节一致)
166
166
  - 方式:真实 headless 会话逐接缝运行时检测——每场景独立运行,证据取会话日志(`session.v3.jsonl` 解压)与文件系统双重判定;配套无 skill 目录负向载体
@@ -174,3 +174,11 @@ ctx.on('tools/pre-execute', async (exec, next) => {
174
174
  - 安装链:bridge-check 四项全绿(loader 存在 / 托管块 insert 形态 / `file://` 目标可达 / 无重复注册)
175
175
  - 边界:认证面向 headless profile(自动化通道);dsh-tui / web 为静态证据(组合树含桥接行),交互式运行时留待日常使用或手动步骤清单;`str_replace_editor` 自 0.1.5-alpha.2 起为 opt-in(默认不挂载)
176
176
  - 结论:桥接与 workflow-kernel 均无需修改(完整认证记录见维护者归档)
177
+
178
+ ### 0.1.7-rc.2 全接缝重认证(2026-09-27)
179
+
180
+ - 版本线(历史锚):`0.1.0-rc.6` → `0.1.1-rc.2` → `0.1.5-rc.1` → `0.1.7-rc.2`(当前认证锚)
181
+ - 环境:dsh CLI `0.1.7-rc.2`;headless profile;真实 `~/.dsh`
182
+ - 结果:各接缝重认证通过
183
+ - 结论:桥接与 workflow-kernel 均无需修改
184
+ - 持续锚:`system-test` K9~K13 覆盖核心行为(loader 源文件与托管块注入 / 纯函数与身份分派 / 流程态门 / hook 注入形态与幂等升级)——后续版本升级以该套件持续回归为准
@@ -1,6 +1,6 @@
1
1
  # Workflow Recovery
2
2
 
3
- > 正文为中文;结构标题保留协议英文概念名(workflow-run / overlay)便于与协议字段对应。
3
+ > 正文为中文;结构标题保留协议英文概念名(workflow-run)便于与协议字段对应。
4
4
 
5
5
  ## 状态模型:workflow-run(主)
6
6
 
@@ -12,9 +12,3 @@
12
12
  ## 恢复指引(workflow-run)
13
13
 
14
14
  - 未 entry 直接 exit 被拦(新 change BLOCKED):先 `workflow-guard.mjs entry <node>` 再重试 exit——entry 的进入检查(协调者禁令/委托前检查/签名记录)是节点进入前置,不可跳过
15
-
16
- ## Overlay 模型(comet 平台模型,仅 compose/平台集成场景)
17
-
18
- - `comet-overlay`(`changes/*/.comet.yaml`)是 **comet 平台模型**,非 flow-comet 默认状态——hook 中以 `isCometOverlay(protocol)` 分支(`protocol.kind === 'comet-five-phase-overlay'`)识别并走 overlay 状态读取路径
19
- - 适用场景:通过 comet 平台把 flow-comet 当作 five-phase overlay 挂载时(compose 自定义协议 / 平台集成);此时状态由 overlay 文件承载,恢复时读 overlay 状态 + 对应 change 的产物
20
- - 默认协议(内置 8 节点)与绝大多数目标项目使用 workflow-run;两者不可互换——按实际加载的 protocol `state.kind` 选择恢复路径
@@ -77,7 +77,7 @@
77
77
  "skill": "flow-comet-ui-design",
78
78
  "operation": "require",
79
79
  "scope": "main",
80
- "enforcement": "advisory",
80
+ "enforcement": "guarded",
81
81
  "reason": "UI-DESIGN(仅前端)"
82
82
  }
83
83
  ],
@@ -37,11 +37,29 @@ git ls-tree <branch> <path> # 确认产物在目标仓库哪个分支、路
37
37
 
38
38
  测试载体(如演练项目)若 git 跟踪 `.flow-comet/flow-comet-state.json`(主仓 gitignore 它,载体可能不同),**恢复/回退操作不得用 `git reset --hard`**——会连带把运行时状态回退到历史版本,状态机倒退(端到端验证实证事故:回退后重跑 init + 重录证据恢复,耗时约 10 分钟)。恢复工件用精确 `git checkout -- <path>`(只回退指定文件),不用整树 reset。
39
39
 
40
- ## 4.5. Codex 平台的 worktree 委托差异(实测 2026-08-14)
40
+ ## 4.5. Codex 平台的原生多代理与当前支持面(依据 2026-09-30 记录订正)
41
41
 
42
- Codex 环境的子代理(spawn_agent)无 `isolation:"worktree"` 参数——自动 worktree 假定仅 Claude Code 适用。**受支持的工作流是串行执行:Codex 不使用并行委托**——任务逐个走 `execute` 节点交付(写边界天然互斥),直到守卫也能识别手工 worktree 路径为止(属机制变更,尚未落地)。**手工 `git worktree add <路径> -b <分支>` + 在 worktree 内 `codex exec` 委托不是受支持路径(不应使用)**:守卫按 `.claude/worktrees/**` 前缀识别隔离区,手工建出的路径不在该前缀下、不被放行覆盖,写入仍会被协调者白名单拦截——详见下方「hook 会话 root 继承」段。worktree-notes 第 3 节的"委托 prompt 内联全部上游上下文"在 Codex 同样适用且是唯一可靠路径(串行委托时同样建议内联)。**注意**:worktree 同样不含 `flow-kit/` 与 `.agents/`(它们是目标仓库内容,不在 worktree 快照内)——委托 prompt 内联必须覆盖这些依赖。
42
+ **平台事实**:Codex 的常规用法是交互式 CLI(`codex` 无子命令)与会话内 agent,`codex exec` 只是 headless 子面;原生多代理 `multi_agent` 为 stable、默认启用(`codex features list` 可查),本机真实交互式会话日志中记录到 `spawn_agent` / `wait_agent` / `close_agent` 的实际调用。因此「Codex 不能委派 / 不使用并行委托」**不是平台事实**。
43
43
 
44
- **hook 会话 root 继承(实测 2026-08-15,与 CC 语义不同;2026-09-12 修订)**:Codex worktree 子代理的**会话 root 仍是主仓库**——写入守卫 hook 以主仓库 `.flow-comet/flow-comet-state.json` 的 `currentNode`/`executionMode` 判定白名单,`execute`/`subagent-execute` 阶段协调者白名单 `.specs/` 会**拦截子代理在 worktree 内写源码**(此前文档声称"worktree 内无 .codex/ → hook 不生效"与实测不符,已修正)。**处理方式(2026-09-12 修订——受支持路径)**:两平台判据不同,覆盖面也不同。CC 侧守卫按路径前缀识别隔离区(`.claude/worktrees/**` 内写入放行);Codex 无 `Agent` 工具的 `isolation: "worktree"` 能力,手工 `git worktree add <任意路径>` 建出的路径不在该前缀下、**不被放行覆盖**,写入仍会被协调者白名单拦截。故 **Codex 平台要求串行执行:不使用并行委托**——任务逐个走 `execute` 节点交付,直到守卫也能识别手工 worktree(属机制变更)。**已废弃的绕过手段(不应使用)**:用 Python `open()` 等 File API 直写曾被记为命令级检测缺口的规避通道——它**绕过写入守卫防线**,不是受支持做法,现明确废止,不得再作为委托方案使用。协调者层面的辅助做法(不改变上述结论):委托 prompt 内联全部上游上下文,验收产物时按 write_files 边界核对。CC 平台的 worktree 子代理在 v1.5.0-rc.2 之前无此问题:runRoot 取进程 cwd(即 worktree 内),区内无 state → 按设计放行;该版起的锚定链把 runRoot 锚到主仓库(`CLAUDE_PROJECT_DIR`),隔离子代理会被误判为协调者而遭白名单拦截——守卫已对 worktree 隔离区放行(区内写源码不受协调者白名单约束,见机制文档 1.4)。
44
+ **flow-comet 当前支持面(机制缺口)**:Codex 的原生子代理形态(`spawn_agent`)无自动 worktree 假定——现有守卫 / 白名单 / 隔离模型未覆盖该形态;在后续契约(须先由覆盖交互式会话与原生子代理的探针得出结论,再据此决定是否修改引擎)落地前,flow-comet 在 Codex 上**不派遣并行子代理**——任务逐个走 `execute` 节点交付(写边界天然互斥)。这是 flow-comet 现阶段的支持面限制,**不是平台能力边界**。**手工 `git worktree add <路径> -b <分支>` + 在 worktree 内 `codex exec` 委托不是受支持路径(不应使用),也不得作为绕过手段**。**委托 prompt 内联上游上下文(第 3 节)在 Codex 同样适用,且是串行交付时的唯一可靠路径**。**注意**:worktree 同样不含 `flow-kit/` 与 `.agents/`(它们是目标仓库内容,不在 worktree 快照内)——委托 prompt 内联必须覆盖这些依赖。
45
+
46
+ **headless 子面实测与 hook 会话 root 订正(依据 2026-09-30 真机重测;codex-cli 0.146.0 / Windows;仅 `codex exec --json --ephemeral` headless 子面;不得外推为平台结论)**:旧结论「手工 worktree 内的写入会被协调者白名单拦住、会话 root 仍是主仓库」被**推翻并收窄**——实测 hook 进程 cwd == 载荷 `cwd` == 会话工作根(cwd=项目 / `-C` / 手工 worktree 三形态一致);**Codex 原生子代理(`spawn_agent`)形态未覆盖,不得外推**。手工 worktree 形态下相对路径写入**不会**被拦:worktree 通常缺 gitignored 运行态 state → 守卫走「无活跃 workflow」放行;若 hook 命令仍指向主仓安装副本(runRoot 外),守卫因「workflow protocol file must stay inside the project root」报错退出,Codex 将 hook 失败降级为非阻塞 → 写入照常落地。**静态喂测(独立复现)**:守卫白名单只覆盖**解析后仍在 runRoot 内**的目标;`Write/Edit` 的 `file_path` 解析为 runRoot 外时跳过判定(**fail-open**,已知缺口、未闭合),而 Bash 写命令同目标仍 `decision:block`(两分支不对称)。**`apply_patch`**:会触发 PreToolUse,但 `tool_name="Bash"`、补丁正文在 `tool_input.command`(heredoc)、**无 `file_path`**;守卫不解析补丁体 → 目标不被提取、放行。独立复验复现了载荷与守卫盲区;**「文件确实落盘」子项在复验环境因 apply_patch shim 失败未复现(首次真机重测环境曾落盘)**——两环境存在差异,按此如实理解。**hook 触发条件**:隔离 `CODEX_HOME` 无持久信任时默认 headless **不执行**项目 hook;`hooks` 特性默认 enabled、可被项目配置/开关覆盖;`codex_hooks` 是 deprecated 别名;per-invocation 信任是必要因素之一,但独立复验显示 trust-only 触发**不稳定**(3/21;补 `--dangerously-bypass-approvals-and-sandbox` 后 5/5)——**不得写成稳定/确定性保证**。持久信任与交互式 TUI 形态未覆盖。
47
+
48
+ **已废弃的绕过手段(不应使用)**:用 Python `open()` 等 File API 直写曾被记为命令级检测缺口的规避通道——它**绕过写入守卫防线**,不是受支持做法,现明确废止,不得再作为委托方案使用。CC 平台的 worktree 子代理在 v1.5.0-rc.2 之前无此问题:runRoot 取进程 cwd(即 worktree 内),区内无 state → 按设计放行;该版起的锚定链把 runRoot 锚到主仓库(`CLAUDE_PROJECT_DIR`),隔离子代理会被误判为协调者而遭白名单拦截——守卫已对 worktree 隔离区放行(区内写源码不受协调者白名单约束,见机制文档 1.4)。
49
+
50
+ ## 4.6. dsh 平台的委托形态:进程内子代理,无需 worktree / 隔离区(实测核对)
51
+
52
+ dsh 的子代理是**平台进程内子代理**——不创建独立工作区,委托方与子代理在同一工作区运行。写入守卫按**会话身份分派**:子代理 `delegationDepth` 大于 0 时直接放行、**项目内任意路径可写(含 gitignored)**;协调者身份(`delegationDepth` 为 0 或缺失)才走白名单。因此 **dsh 委托不需要 worktree,也不存在隔离区**——直接委托即可。
53
+
54
+ 三平台对照:
55
+
56
+ | 平台 | 委托形态 | 隔离区 | 说明 |
57
+ |---|---|---|---|
58
+ | Claude Code | `Agent` 工具 `isolation: "worktree"` | 有(`.claude/worktrees/**`,守卫放行) | 并行委托需隔离;委托前 commit 上游工件(见第 3 节) |
59
+ | dsh | 平台进程内子代理 | **无**——无需创建 | 写入守卫按会话身份分派放行;同工作区并行靠 `write_files` 边界与提交时点作相互隔离纪律 |
60
+ | Codex | 原生多代理(`multi_agent` 默认启用;交互式真实使用 `spawn_agent`) | flow-comet 当前未覆盖该形态(机制缺口) | headless 子面实测见 4.5,不得外推 |
61
+
62
+ **同一工作区的通用边界**:进程内并行子代理会看到彼此未提交的中间态——任务的 `write_files` 边界互斥与提交时点(见第 3 节第 2/4 条)就是相互隔离纪律;dsh 上发起并行委托前同样必须先确认 `write_files` 互不重叠。
45
63
 
46
64
  ## 5. change 分支 + worktree 组合
47
65