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
@@ -1 +1 @@
1
- 1.6.2
1
+ 1.6.3
@@ -3,7 +3,7 @@ name: flow-comet
3
3
  description: "Use when the user wants the flow-comet managed workflow for flow-kit 9 阶段工作流的 workflow-kernel 实现。工件直接读写 .specs/, explicitly invokes /flow-comet, or persisted workflow state identifies one unambiguous active run. Route through this entry Skill; do not invoke its internal Node Skills directly."
4
4
  ---
5
5
 
6
- <!-- 手写区详细协议见 GUIDANCE.md(可选阅读) -->
6
+ <!-- 手写区详细协议见 reference/entry-detail.md(可选阅读) -->
7
7
 
8
8
  # flow-comet
9
9
 
@@ -54,10 +54,9 @@ description: "Use when the user wants the flow-comet managed workflow for flow-k
54
54
  | 停止条件 | guard 失败 / 缺依赖 / 状态损坏 | 报告阻塞与恢复条件,无合法动作时才升级为用户决策 |
55
55
  | 手动交接 | `NEXT: manual`(若有) | 不是用户决策,直接继续 |
56
56
 
57
- **决策点清单(挂到四分类下)**:
58
- - **用户决策**:首次调用且主题/范围有多个合法解释;技术栈选型(5~6 卡,design 节点内暂停);破坏性变更检测(R4.6,execute 节点内暂停展示引用图);Schema 迁移(R4.5,execute 节点内暂停);REVIEW Critical 项(review 节点暂停等人工确认);UAT 失败超限(第 4 次,机器计数 verifyFailures,verify 节点暂停);归档操作(不可逆,archive 节点暂停等最终确认);切换 executionMode 到 direct(execute 节点内暂停,需用户确认,记录 directOverride);合并 change 分支到 main(归档收尾,merge 前暂停等用户确认);PR approve(enablePrReview 开启时,archive 前置,等用户/GitHub approve)
59
- - **自动处理**:唯一安全下一步直接执行;flow-kit 反问协议要求确认(CHANGE/REQUIREMENT/DESIGN)按 flow-kit 规则暂停等待
60
- - **停止条件**:Node guard 失败时先自动诊断并执行唯一安全修复;缺依赖或状态损坏导致无法继续时报告停止条件与恢复条件;只有恢复方式存在多个会改变范围或风险的合法选项时,才升级为用户决策
57
+ **决策点分布(挂到四分类下 · 逐节点作者化的完整清单见 `reference/decision-points.md`)**:**用户决策**集中在六个相位——open(主题 / 范围澄清)· design(技术栈选型)· execute(破坏性变更 R4.6 / Schema 迁移 R4.5 / 切 direct 模式并记录 `directOverride`)· review(Critical 项处置)· verify(UAT 第 4 次失败,机器计数 `verifyFailures`)· archive(归档 / 合并 main / PR approve);**自动处理**=唯一安全下一步直接执行(flow-kit 反问协议要求确认时按 flow-kit 规则暂停等待);**停止条件**=guard 失败先自动诊断并执行唯一安全修复,缺依赖或状态损坏时报阻塞与恢复条件,只有恢复方式存在多个合法选项时才升级为用户决策。
58
+
59
+ > **当你遇到四分类里的「用户决策」、不确定该不该停下来问时读 `reference/decision-points.md`**(按节点作者化的确认点清单 + 机制性决策点,逐条给出触发条件与处置)。
61
60
 
62
61
  ### Red Flags
63
62
 
@@ -72,7 +71,7 @@ description: "Use when the user wants the flow-comet managed workflow for flow-k
72
71
  | "guard 失败了,让用户决定" | 先自动诊断并执行唯一安全修复;无合法动作时才报告停止条件 |
73
72
  | "跳过 entry 直接 exit,反正没检查" | 新 change 未 entry 直接 exit → BLOCKED(进入检查不可跳过);旧 change WARN 渐进 |
74
73
  | "SUMMARY 不写,任务先标 done" | 新 change done 任务缺 SUMMARY → BLOCKED(产物完整性强制);旧 change WARN 渐进 |
75
- | "subagent-execute 阶段,我直接改源码更快" | 协调者禁令:subagent-execute 阶段主会话禁止写源码(hook 白名单只允许 .specs/,Write/Edit 与 Bash 写命令均物理拦截),必须 worktree 委托子代理 |
74
+ | "subagent-execute 阶段,我直接改源码更快" | 协调者禁令:subagent-execute 阶段主会话禁止写源码(hook 白名单只允许 .specs/,Write/Edit 与 Bash 写命令均物理拦截),必须委托子代理——委托走**身份通道**(三平台同一判据),worktree 只是「① 写权限」的实现之一,不是委托前提 |
76
75
  | "用户要健康检查 / 同步架构,我给他 init 一个新 change" | 三条侧命令(evolve / health / context-scan)**不进 8 节点流程**——它们不路由、不 entry/exit、不写节点证据;按下方「侧命令」小节的命令面直接执行即可 |
77
76
 
78
77
  ## 侧命令(横向命令 · 不进 8 节点流程)
@@ -115,7 +114,43 @@ node .claude/skills/flow-comet/scripts/context-scan.mjs [--root <项目根>] [--
115
114
  | verify | control | 集成验证 + UAT | flowkit.verify.v1 |
116
115
  | archive | control | 归档 + LESSONS | flowkit.archive.v1 |
117
116
 
118
- > **并行任务路由(节点顺序是动态的 · 多趟语义)**:TASK 含依赖已满足的 `parallel="true" status="pending"` 任务时路由到 subagent-execute——每趟委托全部依赖已满足的并行任务;子代理返回后重新判定:仍有可并行 pending 就再次进入 subagent-execute(委托节点可多次往返),存在串行 pending 时回 execute 消化一趟再循环。委托节点的完成 = 不存在依赖已满足的可并行 pending 且无串行残留;并行/串行交错的混排序列合法,唯一前置拦截是依赖环(plan 出口校验并附恢复指引)。全部为串行任务时走 execute,行为不变。`next` 的输出始终是权威——以 `NODE:` 输出为准,不按静态顺序推断。
117
+ > **并行任务路由(节点顺序是动态的 · 多趟语义)**:TASK 含依赖已满足的 `parallel="true" status="pending"` 任务时路由到 subagent-execute——每趟委托全部依赖已满足的并行任务;子代理返回后重新判定:仍有可并行 pending 就再次进入 subagent-execute(委托节点可多次往返),存在串行 pending 时回 execute 消化一趟再循环。委托节点的完成 = 不存在依赖已满足的可并行 pending 且无串行残留;并行/串行交错的混排序列合法——plan 出口的硬性拦截**不止**依赖环;完整拦截集与恢复指引以 plan 节点册的「硬性拦截」段为单一来源(本文不复述,避免同一口径两处表达分叉)。全部为串行任务时走 execute,行为不变。`next` 的输出始终是权威——以 `NODE:` 输出为准,不按静态顺序推断。
118
+
119
+ ### 并行委派契约(四属性)· 三平台通道
120
+
121
+ 并行委派的契约对象是**并行安全四属性**——worktree(隔离工作区)只是「① 写权限」的一种打包实现,**不是契约本身**,也不是并行委托的前提:
122
+
123
+ | 属性 | 含义(本节为口径单一来源) |
124
+ |------|---------------------------|
125
+ | ① 写权限 | 子代理写入目标的**放行依据**(含 gitignored 面):身份在场 ⇒ 子代理语义放行;**最小保护集**(`.flow-comet/flow-comet-state.json`、`reference/workflow-protocol.json`)在身份在场时**仍拦** |
126
+ | ② 提交隔离 | 各写者只提交**自己的字面路径**(`git add -- <路径>` / `git commit -- <同一路径>`;多个写者共享同一工作区时禁裸 `add` / `commit -a` / `stash` / `clean` / `reset`) |
127
+ | ③ 验证隔离 | **同一时刻只有一个写者**(有 request 无对应 result 的在飞委托 ⇒ 不跑全量判据,待写入者收工后重跑;已作废的委托经 `workflow-handoff.mjs withdraw <task-id> --by <来源>` 撤回,留痕 `withdrawnAt` + `withdrawnBy`,已撤回 = 终态、历史不删) |
128
+ | ④ 集成纪律 | 协调者按确定性规则**显式、可审计**地集成(`merge --no-ff` 优先、冲突难解时降级 cherry-pick 并记因;机械冲突与语义冲突分别处置) |
129
+
130
+ **结论(三条,足以支撑任何委派决策)**:① **三平台统一走身份判据**——平台差异只体现在通道形态,判据同义;② **契约对象是四属性**,worktree 只是「① 写权限」的一种打包实现(谁建 tree 不是契约);③ **唯一平台差异是「谁建 tree」**——CC 可选 harness 自动建树或共享工作区直写 · Codex 协调者显式 `git worktree add` 或共享工作区直写 · dsh 进程内子代理不建树;判定序**身份先于路径**。②③④ 三属性三平台同形,各自落点见本节末「四属性的机制落点」。
131
+
132
+ **三平台通道(身份判据与谁建树)**——判级只取三态(**证实 / 推翻 / 未覆盖**);**未覆盖 ≠ 已验证**,不得写成已支持:
133
+
134
+ | 属性 | Claude Code | Codex | dsh |
135
+ |------|-------------|-------|-----|
136
+ | ① 写权限 | 载荷 `agent_id` / `agent_type`——**证实**(真机实测:子代理载荷含二者、主会话载荷不含;与 Codex 同一判据) | 载荷 `agent_id` + `agent_type`——**证实**(实测:子代理载荷 12 键含二者、主线程 10 键不含);守卫读 `agent_id`,与 CC 同一判据 | 桥接透传 `delegationDepth` **+ 通道标记**(`FLOW_COMET_AGENT_DEPTH_SOURCE`,守卫要求两者同时在场才接受 env 面身份——继承来的深度变量不作数)——**证实**(0.1.7-rc.2 全接缝重认证;本批收窄为「最小保护集除外」) |
137
+ | **谁建树**(三平台唯一差异) | 可选:harness `isolation: "worktree"` 建独立树,或共享工作区直写 | 协调者**显式** `git worktree add` 并在委派 prompt 指定 `workdir`(原生子代理无自动建树;**证实**:子代理可被指向独立目录并落盘),或共享工作区直写;**建树选择的适用面**:协调者显式 `git worktree add <路径>`(手工建树)**是受支持的建树选择**——在委派 prompt 里指定 `workdir`,写入由身份通道放行(原生子代理无自动建树);**以建树绕过边界**不受支持——用独立树规避协调者禁令 / 最小保护集 / `write_files` 互斥与提交时点纪律 / handoff 与 Return Contract 证据,或把 worktree 当作四属性的替代品。 | **不建树**:进程内子代理、同一工作区运行——**无需隔离区 ≠ 无需边界**(`write_files` 互斥 + 提交时点 + 最小保护集仍构成边界) |
138
+
139
+ **已知边界(不得写成机械保证 · 摘要)**:① Codex 载荷 `cwd` = 会话根,**与实际工作目录无关**(实测证实)⇒ 路径判定在 Codex 上必错,故判定序为**身份先于路径**(精确对照见下);② 身份判据是**声明式信任边界**——守卫读到的 `agent_id` 来自宿主载荷,本机制**不声称能证明**其真实来源;③ 实测结论只覆盖限定形态,`agent_type` 取值域、嵌套委派载荷、非 Windows 环境、非 `bypassPermissions` 权限模式**均未覆盖**(未覆盖 ≠ 已验证,不得写成已支持)。
140
+
141
+ > **当你要判定某平台的通道形态、或要引用平台结论与判级口径时读 `reference/platform-facts.md`**(交互式 Codex 实测口径 · 已知边界全文与限定形态 · 判级三态清单 · Codex 平台事实与当前支持面 · 旧结论留档 · headless 子面实测与 hook 会话 root 订正)。
142
+
143
+ **三平台 `cwd` 语义对照(真机实测新增的精确事实 · 「身份先于路径」的精确理由)**——同为载荷 `cwd`,三平台语义各不相同;下表**三行各自独立**,缺一行即口径残缺:
144
+
145
+ | 平台 | 载荷 `cwd` 的实际语义 | 对路径判定的影响 |
146
+ |------|----------------------|------------------|
147
+ | **Claude Code** | **子代理的工作目录**(`…\.claude\worktrees\<agent-id>`) | **路径判定是正确的** |
148
+ | **Codex** | **恒等于会话根**(子代理在 worktree 写入而 `cwd` 仍是主工程) | **路径判定必错** |
149
+ | **dsh** | 载荷**无** `cwd`(桥接另读会话 header cwd) | 路径判定**不适用** |
150
+
151
+ > ⇒ **不是「路径判定普遍不可靠」,而是三平台 `cwd` 语义各不相同(正确 / 恒错 / 无)——只有身份判据是三平台同义的**。该对照只解释**为什么必须身份优先**,**不构成**「可以改走路径判定」的依据:契约仍走**身份判据**(三条通道同义)。
152
+
153
+ **四属性的机制落点**:① 由守卫的身份短路 + 最小保护集承载(`comet-hook-guard.mjs`)· ② / ④ 见 `flow-comet-subagent-execute` 与 `flow-comet-execute` 两册的提交 / 集成纪律 · ③ 由 `subagent-execute` 出口校验承载。
119
154
 
120
155
  ## Skill Bindings
121
156
 
@@ -132,7 +167,7 @@ node .claude/skills/flow-comet/scripts/context-scan.mjs [--root <项目根>] [--
132
167
 
133
168
  **新 change 严格模式**:`init` 创建的 change 标记为"新"(`newChange: true`)——新 change 下全部内容级检查强制 BLOCKED(处置标记/缓存证据/波次散文/越权委托/SUMMARY 完整性/进入证据等);旧 change(历史遗留,无标记)保持渐进 WARN。执行者可通过 `status` 确认当前 change 的新旧。
134
169
 
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` 的「视觉调性」段在场,且段内的「不适用」标记成**结构形态**——该标记**独立行**、居**行首**(可带列表符号 / 引用 / 加粗),或写在适用性类标签(`适用性` / `适用范围` / `是否前端` / `视觉调性` / `前端` / `界面` / `适用`)的**字段值位**;标记之后须成**词形边界**(紧跟空白、标点或行尾),命中即回显**命中片段**自证。段内其它位置顺带提到「不适用」(如「不适用于暗色主题」)不算标注,仍判前端。
170
+ > **design 行绑定的前端适用性**:`flow-comet-ui-design` 与协议一致为 `guarded`,但只对**前端 change** 适用——**触发与跳过判据的唯一权威是 `flow-comet-ui-design` 册**;结构形态按其口径压缩为:`CHANGE.md` 的「视觉调性」段在场,段内「不适用」标记须成**独立行**、居**行首**,或写在适用性类标签的**字段值位**,标记之后须成**词形边界**(命中即回显**命中片段**自证)。前端须先用 Skill 工具加载该技能 + `skill-load design flow-comet-ui-design --prompt flow-kit/prompts/2a-ui-design.md` 建标记,并在 record 载荷带 `required-skill:design.flow-comet-ui-design`;非前端不加载、不声明,出口打印可见的 `UI-DESIGN: skipped(非前端)` 后放行;旧 change 缺件仅 WARN。
136
171
 
137
172
  **节点技能两层加载模型(入口层 · 双步硬规则)**:路由到节点后,以下两步**都不可跳过**:
138
173
 
@@ -174,6 +209,8 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load <node> <ski
174
209
  - **Trust files over state**: if the script says a Node is DONE but its expected artifacts are missing, treat the Node as incomplete and re-enter it.
175
210
  - **Drift handling**: if the user's request belongs to a different Node than the one returned by `next`, pause and confirm which Node to enter.
176
211
 
212
+ > **当上下文恢复、或 guard 报错需要排查时读 `reference/recovery.md`**(workflow-run 状态模型 · 恢复指引:未 entry 直接 exit 被拦时的唯一安全修复路径)。
213
+
177
214
  ### Node Boundary Rules
178
215
 
179
216
  - **节点顺序**:每个节点按 `entry <node>` → 产出工件 → `record <node>` → `exit <node> --apply` 执行(record 必须先于 exit——exit 校验 evidence 前置,缺证据会 BLOCKED)。
@@ -183,33 +220,26 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load <node> <ski
183
220
 
184
221
  ### 受控重入(archive 源)
185
222
 
186
- 归档后发现缺陷、且归档移动尚未发生时,用受控重入把工作归属退回 `execute` / `subagent-execute` / `review` / `verify` 之一:
187
-
188
- ```bash
189
- node .claude/skills/flow-comet/scripts/workflow-state.mjs reenter <target> --authorized-by <source> --reason <text> [--continue-round <n>]
190
- ```
223
+ 归档后发现缺陷、且归档移动尚未发生时,用受控重入把工作归属退回 `execute` / `subagent-execute` / `review` / `verify` 之一——命令面 `workflow-state.mjs reenter <target> --authorized-by <source> --reason <text> [--continue-round <n>]`:
191
224
 
192
225
  - **何时用**:`currentNode` 停在 `archive`、`.specs/<change-id>/` 仍在原位(归档移动尚未发生)、`status !== 'completed'`,且存在必须回到既有生命周期才能完成的修复。
193
- - **授权**:每次调用都需要用户显式授权——命令面 `--authorized-by` 记录授权来源、`--reason` 说明原因(原因随审计记录一并落盘);引擎把授权留痕写入目标节点的嵌套证据(`state.evidence.<target>.reentryAuthorization`),缺授权或形态不合法一律 BLOCKED 且 state 字节零改写,授权不可由执行者自决(授权是声明式信任边界:`state` 只走脚本通道留痕,hook 拦工具不拦脚本,引擎按声明处理)。
194
- - **上限与显式续轮**:每 change 最多 3 轮;第 4 次 BLOCKED 并给出「继续 / 停止」人工裁决指引。人工裁决「继续」须追加 `--continue-round <n>`(正整数,且 n ≥ 已用轮次 + 1)作显式续轮授权:满足则放行并计入下一轮、审计行打印 `第 n 轮(显式授权续轮,上限 3)`;未到上限即传该参数、或轮次不足一律 BLOCKED 且零改写。轮次与审计事件记入 `state.history`(事件类型 `reentry-applied`,含 `reason`;续轮时附 `continuationAuthorized: true`),成功输出 `REENTRY: archive → <target>(授权源 <source>;第 n/3 轮;备份 <file>)` 与 `REASON: <text>` 两行。
195
- - **备份**:转移前自动落 state 快照 `.specs/<change-id>/.reentry-backups/<UTC ISO>-pre-<target>.json`(时间戳中的 `:` 替换为 `-`),并记录 sha256 指纹,供审查核验与手工回滚。
196
- - **顺序**:命令成功后再写修复内容——archive 阶段写入白名单只放行 `.specs/<change-id>/KNOWN-ISSUES.md` 等少数路径;重入后写入权限跟随目标节点,此时才追加 Fix 任务 / 修改工件。
197
- - **边界**:归档移动已发生或 change 已 `completed` → BLOCKED,走人工处置或新 change / hotfix;重复调用同一目标 → 空操作(输出 `REENTRY: 空操作——…`,不备份、不计数、不改写 state),不会静默跳过。
226
+ - **授权**:每次调用需用户显式授权(`--authorized-by` + `--reason`,留痕写入 `state.evidence.<target>.reentryAuthorization`);缺授权或形态不合法一律 BLOCKED 且 state 字节零改写——授权不可由执行者自决。
227
+ - **上限**:每 change 最多 3 轮,第 4 次 BLOCKED 并给出「继续 / 停止」人工裁决指引;人工裁决「继续」须追加 `--continue-round <n>`(n ≥ 已用轮次 + 1)作显式续轮。
228
+ - **备份**:转移前自动落 `.specs/<change-id>/.reentry-backups/<UTC ISO>-pre-<target>.json` 并记 sha256 指纹(供审查核验与手工回滚)。
229
+ - **顺序与边界**:命令成功后再写修复内容(archive 阶段白名单只放行 `.specs/<change-id>/KNOWN-ISSUES.md` 等少数路径);归档移动已发生或 change 已 `completed` → BLOCKED,重复调用同一目标 = 空操作、不会静默跳过。
198
230
 
199
- ### 受控重校(`replan` · execute 源)
231
+ > **当你要开修复回路、要把工作归属受控归位 / 受控重入,或要核对归档侧重入边界时读 `reference/fix-loop.md`**(受控重入完整规格 · 修复回路状态机路径六步 · 归档侧边界与写权限顺序 · Fix / RETURN / REENTRY 三类审计行语义)。
200
232
 
201
- 计划在执行中被证明有缺陷、任务集因此需要修订时,用受控重校重新校验并重签任务集——不跳节点、不重置任何完成态:
233
+ ### 受控重校(`replan` · execute 源)
202
234
 
203
- ```bash
204
- node .claude/skills/flow-comet/scripts/workflow-state.mjs replan "<reason>" --authorized-by <source> [--continue-round <n>]
205
- ```
235
+ 计划在执行中被证明有缺陷、任务集因此需要修订时,用受控重校重新校验并重签任务集——不跳节点、不重置任何完成态。命令面 `workflow-state.mjs replan "<reason>" --authorized-by <source> [--continue-round <n>]`:
206
236
 
207
237
  - **何时用**:`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。它不是绕过签名门禁,而是把「签名不匹配」重新收敛为「匹配」。
238
+ - **授权与上限**:每次调用需用户显式授权(留痕写入 `state.evidence.<node>.replanAuthorization`);每 change 最多 3 轮,第 4 次 BLOCKED 并需显式续轮 `--continue-round <n>`(n ≥ 已用轮次 + 1)——缺授权、值为空 / 纯空白或轮次不足一律 BLOCKED 且 state 字节零改写。
239
+ - **备份与幂等**:改写前落 `.specs/<change-id>/replan-backups/<UTC ISO>-pre-replan.json` + sha256 指纹;目标形态已成立时的重复同形态调用 = 空操作(不备份、不计数、不写事件、不改写 state)。
240
+ - **绝不豁免校验**:只做「重新校验 + 重新签名」——判据与 plan 出口同源(任务块 / 每任务 `<verify>` / 任务图依赖环与缺失依赖 / 并行写写冲突任一不成立即 BLOCKED;读写仅 WARN),不是绕过签名门禁,而是把「签名不匹配」重新收敛为「匹配」。
241
+
242
+ > **当你要判定该不该走 `replan` 重校任务集、或出口报「任务集签名不匹配」时读 `reference/replan.md`**(规格全文 · 判据与 plan 出口的同源对照 · 审计行 / 续轮 / 备份语义)。
213
243
 
214
244
  ### Evidence Recording
215
245
 
@@ -231,33 +261,21 @@ All artifacts in `.specs/<change-id>/`. Cross-change files in `.specs/` (CONTEXT
231
261
 
232
262
  | 脚本 | 用途 |
233
263
  |------|------|
234
- | `workflow-state.mjs` | 状态管理:init/status/next/select/record/advance/skill-load/execution-mode/config/verify-fail(verify 失败计数,第 4 次 BLOCKED)/reenter(archive 源受控重入)/replan(execute 源计划重校重签) |
264
+ | `workflow-state.mjs` | 状态管理:init/status/next/select/record/advance/skill-load/execution-mode/config/verify-fail(verify 失败计数,第 4 次 BLOCKED)/reenter(archive 源受控重入)/replan(execute 源计划重校重签)/explain(节点现问) |
235
265
  | `workflow-state.mjs reenter` | 归档后受控重入:`reenter <target> --authorized-by <source> --reason <text> [--continue-round <n>]` 把工作归属退回 execute / subagent-execute / review / verify 之一(仅 archive 源、归档移动前、每次显式用户授权、每 change 上限 3 轮,超限继续需显式续轮授权) |
236
266
  | `workflow-state.mjs replan` | 计划重校重签:`replan <reason> --authorized-by <source> [--continue-round <n>]` 在 execute / subagent-execute 相位重跑任务图与字段校验并重录任务集签名(仅这两个相位、每次显式授权、每 change 上限 3 轮、超限继续需显式续轮、缺授权或形态非法一律 BLOCKED 且零改写;写盘前落备份;重复同形态为空操作;只重校重签、绝不豁免校验) |
267
+ | `workflow-state.mjs explain` | 节点现问(只读):`explain <node>` 从协议 JSON 现算出该节点的产物路径与证据 id、门禁(guardrails)、必需技能声明,以及 entry / exit / record 三条命令(脚本路径按平台形态生成;不写状态、不改路由,节点名非法一律拒绝并列出合法取值)。需要可照抄的完整命令时跑它——命令形态以它的输出为准 |
237
268
  | `workflow-guard.mjs` | 节点门禁:entry/exit/verify 检查 |
238
269
  | `workflow-handoff.mjs` | 子代理交接:request/result/status |
239
270
  | `comet-plan.mjs` | 兼容别名入口(内容为 workflow-state 的别名壳) |
240
271
  | `comet-check.mjs` | workflow contract 检查 |
241
- | `comet-hook-guard.mjs` | 文件写入边界守卫(phase 白名单:subagent-execute 阶段只允许 .specs/;隔离委托的工作区 `.claude/worktrees/**` 放行——`Write`/`Edit` 与 `Bash` 写命令两条判定路径同语义) |
272
+ | `comet-hook-guard.mjs` | 文件写入边界守卫(**身份判据先于路径判据**:载荷 `agent_id` / 桥接透传的 `delegationDepth` 在场 ⇒ 子代理语义放行;最小保护集 `.flow-comet/flow-comet-state.json` 与 `reference/workflow-protocol.json` 在身份在场时**仍拦**;无身份走 phase 白名单——subagent-execute 阶段只允许 .specs/,`.claude/worktrees/**` 前缀保留为兼容路径;`Write`/`Edit` 与 `Bash` 写命令两条判定路径同语义,runRoot 外一致拦截) |
242
273
 
243
274
  ### 机器拥有字段
244
275
 
245
- 以下字段只能由 `workflow-state.mjs` 和 `workflow-guard.mjs` 脚本管理,不应被手动编辑:
246
-
247
- | 字段 | 说明 | 管理者 |
248
- |------|------|--------|
249
- | `currentNode` | 当前活动节点 | workflow-state.mjs next/advance/reenter |
250
- | `completedNodes` | 已完成节点列表 | workflow-guard.mjs exit --apply / workflow-state.mjs reenter |
251
- | `evidence` | 节点证据记录 | workflow-state.mjs record |
252
- | `verifyFailures` | verify 失败计数 | workflow-guard.mjs (auto-increment) |
253
- | `verifyFailuresByChange` | 按 change 隔离的失败计数(keyed by change-id) | workflow-state.mjs / state-schema.mjs helper |
254
- | `status` | 运行状态 | workflow-guard.mjs exit --apply |
255
- | `executionMode` | subagent/direct,execute 执行模式 | workflow-state.mjs execution-mode |
256
- | `directOverride` | direct 是否用户显式确认 | workflow-state.mjs execution-mode direct |
257
-
258
- 手动修改这些字段可能导致 guard 校验不一致。若需修正状态,使用 `workflow-state.mjs advance` 或 `workflow-state.mjs select`。
276
+ `currentNode` · `completedNodes` · `evidence` · `verifyFailures` · `verifyFailuresByChange` · `status` · `executionMode` · `directOverride` 这八个字段**只能由 `workflow-state.mjs` / `workflow-guard.mjs` 脚本管理,绝不手改**(手改会导致 guard 校验不一致)。修正状态一律走脚本通道——`workflow-state.mjs advance` 或 `select`;`workflow-state.mjs reenter` 是 `currentNode` / `completedNodes` / `status` 的受控写入点(先落备份、写授权留痕与审计事件,再转移工作归属),除该命令与上述脚本外不得用其他方式改这些字段。
259
277
 
260
- `workflow-state.mjs reenter` 是 `currentNode` / `completedNodes` / `status` 的受控脚本写入点:它先落备份、写授权留痕与审计事件,再转移工作归属;除该命令与上述脚本外,不要用其他方式改这些字段。
278
+ > **当你要核对某个字段由谁管理、或要判定某次 state 变更该走哪条命令时读 `reference/entry-detail.md`**(逐字段管理者对照表 · 只读 / 受控写入边界 · 手写区详细协议全文)。
261
279
 
262
280
  The route, Output Schemas, required Skill calls, and recovery state are defined by `reference/workflow-protocol.json`.
263
- - Resolved source Skill evidence and composition provenance: `reference/resolved-skills.json`.
281
+ - 组合与已解析技能的来源证据已随分发面移出技能树:`docs/internal/resolved-skills.json`(仓库内维护者面,随包不分发)。
@@ -10,7 +10,7 @@
10
10
  - **初始化检测相关文档既有过程用语**:`reference/init-detection.md` 等含历史过程用语(历史遗留,由人工清单跟进;清理后删除本条目)
11
11
  - **待复查观察项**:验证过程中记录,未达修复优先级——后续迭代按需复查
12
12
  - **本地文档健康检查工具版本映射**:本地检查工具的版本/场景数一致性子检查用发布时快照,开发窗口期(版本未发布、场景数已增)会误报——由系统测试集的结构检查放行逻辑覆盖,权威判定在引擎自测
13
- - **design 节点 required 自指核验结论**:设计如此,无需修复——详见 `reference/TEST-MATRIX.md` 附节(三模式对照与理由)
13
+ - **design 节点 required 自指核验结论**:设计如此,无需修复(三模式对照与理由见维护者面的系统测试集设计文档;该文档不随包分发,缺失不影响本清单可用)
14
14
 
15
15
  ## 使用说明
16
16
 
@@ -0,0 +1,32 @@
1
+ # 提交面与集成纪律(多写者共享同一工作区)
2
+
3
+ > **读者对象**:共享工作区形态下并行 / 串行委托的子代理,以及做集成的协调者。
4
+ > **何时读**:本趟存在多个写者共享同一工作区(或要在集成前先定规则)时读。
5
+ >
6
+ > 本文件内容**逐字搬运**自 `flow-comet-subagent-execute` 的「提交面 pathspec 纪律」与「集成纪律」两节**正文**(搬运,不重写);两节原标题里已被 ADR-016 作废的旧「两册同锁 · 逐字一致」限定词**不随搬运带出**,其余一字未改。两册只留要点句与条件句。
7
+
8
+ ## 提交面 pathspec 纪律(五要素 · 带适用条件)
9
+
10
+ **适用条件(先读)**:本条纪律适用于「**多个写者共享同一工作区**」形态——并发写者同处一个工作树(CC 非 worktree 委托 / Codex 共享工作区 / dsh 进程内子代理)。**各自独立工作区(worktree 等)内的局部 `reset` / `clean` 不在禁令内**(那是写者对自有工作区的正常整理);但只要本趟存在**任一**共享工作区的写者,本条即对整个并行趟生效。
11
+
12
+ 五要素(缺一不可):
13
+
14
+ 1. **`git add -- <自己字面路径>`**:逐条字面路径(取自本任务 `write_files`),禁用 `.` / `-A` / `-u` 等宽泛形态。
15
+ 2. **`git commit -- <同一路径>`**:提交以 pathspec 限定范围,保证提交只含自己的文件;路径集与上一步**逐字一致**。
16
+ 3. **锁失败重试**:并发提交会撞 `index.lock` / `cannot lock ref`——**失败即重试**(临时仓真并发实测:20 提交 / 25 次锁失败全部重试成功);不得因锁失败改用宽泛命令。
17
+ 4. **禁裸 `add` / `commit -a` / `stash` / `clean` / `reset`**:无 pathspec 的 `git add`、`git commit -a`、`git stash`、`git clean`、`git reset` 一律禁止——它们作用于整个共享工作区。
18
+ 5. **为什么**:并发写者共享**同一个索引与工作树**——宽泛命令存在**并发索引竞态**:一方 `add -A` 会把另一方的半成品纳入自己的提交(串味 / 多文件提交);`stash` / `clean` / `reset` 更会直接破坏同伴的未提交工作。
19
+
20
+ **并行波次附加两条(与上列五要素并列适用 · 不改其语义与适用条件)**:
21
+
22
+ - **并行波次禁用 `git commit --amend`**:共享工作区下 HEAD 会被并行写者推进——`--amend` 改的是 **HEAD 指向的提交**、不一定是「你的提交」,会把同伴的提交连同提交信息一并改写(本仓实测撞过:amend 误改了另一并行任务的提交,经 `reset --soft` 复原,内容零损失)。确需修正时必须**先断言 `git rev-parse HEAD` 等于自己刚提交的哈希**,否则一律改用**新提交追加**。
23
+ - **误改后的自救通道(与上列第 4 条的定向例外)**:合法修复路径 = **先断言** `git rev-parse HEAD` 即被误改的那次提交,再 `git reset --soft <自己的父提交>` 回退(**只用 `--soft`**:只移动 HEAD、不动索引与工作树,同伴的未提交工作零影响),最后以 **pathspec** 重建自己的提交。纪律必须留出这条明路——让执行者**不必违规**(force-push / 手改历史)即可收拾;**无合法修复通道时人会暗改**(见 ADR-013 记录的同型教训)。诚实边界:这条断言与随后的 `reset --soft` **之间不是原子操作**(共享工作区没有跨写者锁,做不到原子),故断言是**尽力而为**、**不构成并发保证**;断言不符时**一律回落到「新提交追加」**这条安全路径。
24
+
25
+ ## 集成纪律(四要素)
26
+
27
+ 1. **机制选择**:优先 **`git merge --no-ff`**(保留父子关系、可审计;comet 先例:集成用 `--no-ff`、交付用 `--ff-only`);冲突难解时**降级 `git cherry-pick` 并强制记因**(审计行写明降级原因)——cherry-pick 丢失父子关系、审计弱,故只作降级路径。
28
+ 2. **顺序(确定性规则)**:先按 `depends_on` 的**拓扑序**集成(被依赖者先入);同一拓扑层内按 **task id 升序**(计划期固定的稳定键,与完成先后无关)。**不得依赖书写顺序** / 提交到达顺序 / 完成先后等运行期不确定量。
29
+ 3. **审计留痕**:每次集成输出一行审计行 `INTEGRATE: <task-id> <commitHash> → <集成提交>`;降级路径为 `INTEGRATE: <task-id> <commitHash> via cherry-pick -- 降级原因:<原因>`。映射(task-id → commitHash → 集成提交)记入该趟流程记录(`<task-id>-SUMMARY.md` / handoff evidence 文本字段)。**判级**:审计行是**执行纪律**(review 把关),本节点不声称存在机械门禁校验它。
30
+ 4. **冲突处置(两类分别动作)**:
31
+ - **机械冲突**(不改用户可见行为:同一文件不同区域 / 相邻行 / 纯格式):执行者**可自行解决**——解决后必须跑**合并后验证**(该任务 `verify` + 受影响任务的判据),并在审计行记录冲突与解决方式。
32
+ - **语义冲突**(两侧对同一行为 / 契约 / 接口给出不同语义:同一函数语义分叉、同一 AC 的两种实现、公共 API 形状不一致):**必须中止集成并上抛**(记 BLOCKED + 恢复指引),**不得**由执行者自行拍板;由协调者 / 用户裁决(补 `depends_on`、拆任务或开新 change)。
@@ -4,7 +4,7 @@
4
4
 
5
5
  进入 execute / subagent-execute / verify 节点前,运行:
6
6
 
7
- > **强制上下文**(实测):委托 worktree 子代理前**必须**先执行本协议——未 commit 的工件不会被 worktree 子代理看到(harness 从已提交 HEAD 创建 worktree),曾有 8 个排查任务因工件未 commit 全部空上下文运行。本协议是委托前的前置步骤,不是可选项。
7
+ > **强制上下文**(实测):委托子代理前**必须**先执行本协议。**隔离工作区(worktree)形态**下这一步还决定子代理能否看到工件——未 commit 的工件不会被该子代理看到(harness 从已提交 HEAD 创建 worktree),曾有 8 个排查任务因工件未 commit 全部空上下文运行;**共享工作区形态**(身份通道下的直接委托)看得到未提交改动,但仍须执行本协议澄清脏工作树的归属(归属不清即不得推进阶段)。本协议是委托前的前置步骤,不是可选项。
8
8
 
9
9
  ```bash
10
10
  git status --short
@@ -1,11 +1,9 @@
1
- ---
2
- name: flow-comet
3
- description: "Use when the user wants the flow-comet managed workflow for flow-kit 9 阶段工作流的 workflow-kernel 实现。工件直接读写 .specs/, explicitly invokes /flow-comet, or persisted workflow state identifies one unambiguous active run. Route through this entry Skill; do not invoke its internal Node Skills directly."
4
- ---
1
+ # 入口册展开版(手写区详细协议)
5
2
 
6
- # flow-comet
7
-
8
- > 手写区详细协议——主 SKILL.md 的展开版(可选阅读;主 SKILL.md 与本文冲突时以本文为准,本文以外的部分以 SKILL.md 为准,协议定义以 `reference/workflow-protocol.json` 为准)。
3
+ > **读者对象**:需要手写区协议细节(而非只要路由判据)的执行者与协调者——典型是核对机器拥有字段的管理者、查入口册各小节的展开表述。
4
+ > **何时读**:当你要核对某个字段由谁管理、要判定某次 state 变更该走哪条命令,或要查入口册某小节的展开表述时读。
5
+ >
6
+ > 本文是主 `SKILL.md` 的**展开版**(由 `GUIDANCE.md` 改名而来);路由判据、锚点句与各段要点以 `SKILL.md` 为准,本文承载**未被 SKILL.md 保留的细节**,协议定义以 `reference/workflow-protocol.json` 为准。
9
7
 
10
8
  flow-kit 9 阶段工作流的 workflow-kernel 实现。保留 flow-kit 的全部产物模板、规则体系和 LESSONS 知识库,用脚本自动管理状态和阶段路由。
11
9
 
@@ -76,7 +74,7 @@ flow-kit 9 阶段工作流的 workflow-kernel 实现。保留 flow-kit 的全部
76
74
  | "guard 失败了,让用户决定" | 先自动诊断并执行唯一安全修复;无合法动作时才报告停止条件 |
77
75
  | "跳过 entry 直接 exit,反正没检查" | 新 change 未 entry 直接 exit → BLOCKED(进入检查不可跳过);旧 change WARN 渐进 |
78
76
  | "SUMMARY 不写,任务先标 done" | 新 change done 任务缺 SUMMARY → BLOCKED(产物完整性强制);旧 change WARN 渐进 |
79
- | "subagent-execute 阶段,我直接改源码更快" | 协调者禁令:subagent-execute 阶段主会话禁止写源码(hook 白名单只允许 .specs/,Write/Edit 与 Bash 写命令均物理拦截),必须 worktree 委托子代理 |
77
+ | "subagent-execute 阶段,我直接改源码更快" | 协调者禁令:subagent-execute 阶段主会话禁止写源码(hook 白名单只允许 .specs/,Write/Edit 与 Bash 写命令均物理拦截),必须委托子代理——委托走**身份通道**(三平台同一判据),worktree 只是「① 写权限」的实现之一,不是委托前提 |
80
78
 
81
79
  ## Workflow Nodes
82
80
 
@@ -91,7 +89,7 @@ flow-kit 9 阶段工作流的 workflow-kernel 实现。保留 flow-kit 的全部
91
89
  | verify | control | 集成验证 + UAT | flowkit.verify.v1 |
92
90
  | archive | control | 归档 + LESSONS | flowkit.archive.v1 |
93
91
 
94
- > **并行任务路由(节点顺序是动态的 · 多趟语义)**:TASK 含依赖已满足的 `parallel="true" status="pending"` 任务时路由到 subagent-execute——每趟委托全部依赖已满足的并行任务;子代理返回后重新判定:仍有可并行 pending 就再次进入 subagent-execute(委托节点可多次往返),存在串行 pending 时回 execute 消化一趟再循环。委托节点的完成 = 不存在依赖已满足的可并行 pending 且无串行残留;并行/串行交错的混排序列合法,唯一前置拦截是依赖环(plan 出口校验并附恢复指引)。全部为串行任务时走 execute,行为不变。`next` 的输出始终是权威——以 `NODE:` 输出为准,不按静态顺序推断。direct 模式下 `parallel="true"` 任务仍必须由 subagent-execute 委托消化;direct 仅覆盖串行任务的主代理直写。
92
+ > **并行任务路由(节点顺序是动态的 · 多趟语义)**:TASK 含依赖已满足的 `parallel="true" status="pending"` 任务时路由到 subagent-execute——每趟委托全部依赖已满足的并行任务;子代理返回后重新判定:仍有可并行 pending 就再次进入 subagent-execute(委托节点可多次往返),存在串行 pending 时回 execute 消化一趟再循环。委托节点的完成 = 不存在依赖已满足的可并行 pending 且无串行残留;并行/串行交错的混排序列合法——plan 出口的硬性拦截**不止**依赖环;完整拦截集与恢复指引以 plan 节点册的「硬性拦截」段为单一来源(本文不复述,避免同一口径两处表达分叉)。全部为串行任务时走 execute,行为不变。`next` 的输出始终是权威——以 `NODE:` 输出为准,不按静态顺序推断。direct 模式下 `parallel="true"` 任务仍必须由 subagent-execute 委托消化;direct 仅覆盖串行任务的主代理直写。**并行委派契约(四属性)与三平台通道**的单一来源 = 主 `SKILL.md` 的「并行委派契约(四属性)· 三平台通道」小节——本文只留指针,不复述平台事实(同一口径两处表达必分叉)。
95
93
 
96
94
  ## Skill Bindings
97
95
 
@@ -150,24 +148,14 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load <node> <ski
150
148
 
151
149
  ### Node Boundary Rules
152
150
 
153
- - Before leaving a Node, run `node .claude/skills/flow-comet/scripts/workflow-guard.mjs exit <node> --apply` to advance state.
154
- - If the guard fails, do not proceed — present the guard output and ask the user how to fix it.
151
+ - **节点顺序**:每个节点按 `entry <node>` → 产出工件 → `record <node>` → `exit <node> --apply` 执行(record 必须先于 exit——exit 校验 evidence 前置,缺证据会 BLOCKED)。
152
+ - Before leaving a Node, run `node .claude/skills/flow-comet/scripts/workflow-guard.mjs entry <node>` then `exit <node> --apply` to advance state. **新 change 未 entry 直接 exit → BLOCKED**(旧 change WARN 渐进)——entry 的进入检查(协调者禁令/委托前检查/签名记录)不可跳过。
153
+ - If the guard fails, do not proceed past it — 先自动诊断并执行唯一安全修复(与 Decision Core 停止条件一致);存在多个会改变范围/风险的合法恢复动作时,展示 guard 输出并询问用户。
155
154
  - If the user wants to redo a completed Node, reset its completion state and re-enter rather than creating a parallel path.
156
155
 
157
156
  ### 受控重校(`replan` · execute 源)
158
157
 
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。它不是绕过签名门禁,而是把「签名不匹配」重新收敛为「匹配」。
158
+ **规格已单一化**:`replan` 的完整规格(何时用 / 授权留痕 / 上限与显式续轮 / 备份 / 幂等 / 「绝不豁免校验」的判据同源对照)归 `reference/replan.md` 一处;本文不复述,入口册只留 4 行要点与条件句。命令面:`node .claude/skills/flow-comet/scripts/workflow-state.mjs replan "<reason>" --authorized-by <source> [--continue-round <n>]`。
171
159
 
172
160
  ### Evidence Recording
173
161
 
@@ -181,7 +169,7 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs record <node-id> '{"su
181
169
  All artifacts in `.specs/<change-id>/`. Cross-change files in `.specs/` (CONTEXT.md, LESSONS.md, CHANGELOG.md).
182
170
 
183
171
  > **模板权威**:工件段形以 `flow-kit/templates/**` 为唯一权威。
184
- > **archive 定位与读法**:`.specs/archive/**` 是历史证据。**何时可读**:工作区文档明确要求(如断点续传 / 决策追溯),或某 guard 硬校验的约定在模板与 LESSONS 中查不到时;**读什么**:只取结构与证据;**不读什么**:不作为格式规范或决策依据,不得以归档工件对齐段形。
172
+ > **archive 定位与读法**:见主 `SKILL.md` 的「Artifact Paths」小节(单一来源——「何时可读 / 读什么 / 不读什么」的三段判据只在那一处表达,本文不复述)。
185
173
 
186
174
  ### Scripts
187
175
 
@@ -195,16 +183,16 @@ All artifacts in `.specs/<change-id>/`. Cross-change files in `.specs/` (CONTEXT
195
183
  | `workflow-handoff.mjs` | 子代理交接:request/result/status |
196
184
  | `comet-plan.mjs` | 兼容别名入口(内容为 workflow-state 的别名壳) |
197
185
  | `comet-check.mjs` | workflow contract 检查 |
198
- | `comet-hook-guard.mjs` | 文件写入边界守卫(phase 白名单:subagent-execute 阶段只允许 .specs/;隔离委托的工作区 `.claude/worktrees/**` 放行——`Write`/`Edit` 与 `Bash` 写命令两条判定路径同语义) |
186
+ | `comet-hook-guard.mjs` | 文件写入边界守卫(**身份判据先于路径判据**:载荷 `agent_id` / 桥接透传的 `delegationDepth` 在场 ⇒ 子代理语义放行;最小保护集 `.flow-comet/flow-comet-state.json` 与 `reference/workflow-protocol.json` 在身份在场时**仍拦**;无身份走 phase 白名单——subagent-execute 阶段只允许 .specs/,`.claude/worktrees/**` 前缀保留为兼容路径;`Write`/`Edit` 与 `Bash` 写命令两条判定路径同语义,runRoot 外一致拦截) |
199
187
 
200
188
  ### 机器拥有字段
201
189
 
202
- 以下字段只能由 `workflow-state.mjs` 和 `workflow-guard.mjs` 脚本管理,不应被手动编辑:
190
+ 以下字段只能由 `workflow-state.mjs` 和 `workflow-guard.mjs` 脚本管理,**绝不手改**:
203
191
 
204
192
  | 字段 | 说明 | 管理者 |
205
193
  |------|------|--------|
206
- | `currentNode` | 当前活动节点 | workflow-state.mjs next/advance |
207
- | `completedNodes` | 已完成节点列表 | workflow-guard.mjs exit --apply |
194
+ | `currentNode` | 当前活动节点 | workflow-state.mjs next/advance/reenter |
195
+ | `completedNodes` | 已完成节点列表 | workflow-guard.mjs exit --apply / workflow-state.mjs reenter |
208
196
  | `evidence` | 节点证据记录 | workflow-state.mjs record |
209
197
  | `verifyFailures` | verify 失败计数 | workflow-guard.mjs (auto-increment) |
210
198
  | `verifyFailuresByChange` | 按 change 隔离的失败计数(keyed by change-id) | workflow-state.mjs / state-schema.mjs helper |
@@ -214,4 +202,6 @@ All artifacts in `.specs/<change-id>/`. Cross-change files in `.specs/` (CONTEXT
214
202
 
215
203
  手动修改这些字段可能导致 guard 校验不一致。若需修正状态,使用 `workflow-state.mjs advance` 或 `workflow-state.mjs select`。
216
204
 
205
+ `workflow-state.mjs reenter` 是 `currentNode` / `completedNodes` / `status` 的受控脚本写入点:它先落备份、写授权留痕与审计事件,再转移工作归属;除该命令与上述脚本外,不要用其他方式改这些字段。
206
+
217
207
  The route, Output Schemas, required Skill calls, and recovery state are defined by `reference/workflow-protocol.json`. 恢复语义见 `reference/recovery.md`。
@@ -0,0 +1,57 @@
1
+ # 修复回路(缺陷 → execute 生命周期 · 受控重入)
2
+
3
+ > **读者对象**:review / verify 发现缺陷后要开修复回路的人,以及归档后要把工作归属退回既有生命周期的协调者。
4
+ > **何时读**:要判定需开修复回路、要把工作归属受控归位 / 受控重入,或要核对归档侧重入边界时读。
5
+ >
6
+ > 本文件内容**逐字搬运**自 `flow-comet-verify`(「修复回路状态机路径」段全文)· `flow-comet`(受控重入完整规格)· `flow-comet-archive`(归档后发现缺陷)· `flow-comet-subagent-execute`(受控重入打开的修复场景)四册的原有段落(搬运,不重写);各节点册只留要点句与条件句。
7
+
8
+ ## 修复回路状态机路径
9
+
10
+ review / verify 发现缺陷后的修复必须回到 `execute` 节点生命周期内完成,禁止驻留源节点「顺手修完」;引擎按以下路径强制闭环(`<源节点>` 为 review 或 verify):
11
+
12
+ 1. **追加 Fix 任务**:在 `.specs/<change-id>/TASK.md` 的 `## Fix 任务` 段内追加编号修复任务(完整任务字段),**禁止文件尾追加**;任务集修订必须在 `entry` 之前完成。
13
+ 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` 的输出核对任务状态与路由,不要未经归位硬开工。
14
+ 3. **执行修复**:按 execute 节点生命周期完成全部 Fix 任务(委托/直写规则不变);`entry execute` 刷新任务集签名,锁定追加后的任务集——归位后不得再增删任务或修改任务内容。
15
+ 4. **跑 execute 四类出口**:`record execute` → `exit execute --apply`。四类出口门禁真实执行——**全任务 done / 逐任务 SUMMARY 完备 / 6 维自查 + 自检方法声明 / 任务集签名一致**;任一缺失即 BLOCKED 并给出恢复指引。通过后,引擎在 Fix 二次完成时把当前节点推回源节点(review 或 verify)。
16
+ - **guard exit 回源审计行语义(Fix vs RETURN)**:真实修复回路二次完成保留 `FIX-BATCH: 回源节点 <源节点>`(真实 Fix 回炉的机器锚);正常多趟收尾(任务集签名全等且无 Fix 标记)输出中性 `RETURN: 回源节点 <源节点>`(非 Fix 回修);旧 state 缺闭合/修复证据(无签名事件且无 Fix 标记)输出 `RETURN: 回源节点 <源节点>(旧 state 缺闭合/修复证据,未分类)`,不冒充 Fix、不 BLOCK;上述分类只改审计行文本,路由与 state 写入零变化。此处 `RETURN:` 仅指审计行前缀,与子代理 handoff 的 Return Contract 无关。
17
+ 5. **回源节点跑出口**:回到源节点后运行 `next`,Fix 回程豁免生效时应输出 `NODE: review` 或 `NODE: verify`(不会因源节点产物已存在而跳过);若仍输出后续节点,说明回程条件未满足,先核对状态机归属与任务状态,不要继续推进。随后执行 `entry <源节点>` → `exit <源节点> --apply` 跑源节点出口门禁(即 entry/exit 源节点);通过后继续正常路由(review → verify;verify → archive),必要时进入下一轮 Fix 闭环。
18
+ - **`next` 回程审计行语义**:回程豁免行始终输出中性 `RETURN: 回程源节点 <源节点>`(源节点产物在场且未出口;保留源节点跑出口),不再输出 FIX-BATCH;受控归位行的 `FIX-BATCH: 归位 <execute 家族>` 保留(真实 Fix 回退行),两者不得混同。
19
+ 6. **禁止绕过**:驻留源节点不归位、顺手改完后直接跑源节点 exit 收场会被 BLOCKED(存在未归位/未跑出口的修复回路),必须按上述路径恢复;不得用跳过归位或出口门禁的手段(含手动改写 `.flow-comet/flow-comet-state.json`)替代本路径。
20
+
21
+ **由受控重入打开的场景(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)。
22
+
23
+ ## 受控重入与归档侧边界
24
+
25
+ ### 受控重入(archive 源)
26
+
27
+ 归档后发现缺陷、且归档移动尚未发生时,用受控重入把工作归属退回 `execute` / `subagent-execute` / `review` / `verify` 之一:
28
+
29
+ ```bash
30
+ node .claude/skills/flow-comet/scripts/workflow-state.mjs reenter <target> --authorized-by <source> --reason <text> [--continue-round <n>]
31
+ ```
32
+
33
+ - **何时用**:`currentNode` 停在 `archive`、`.specs/<change-id>/` 仍在原位(归档移动尚未发生)、`status !== 'completed'`,且存在必须回到既有生命周期才能完成的修复。
34
+ - **授权**:每次调用都需要用户显式授权——命令面 `--authorized-by` 记录授权来源、`--reason` 说明原因(原因随审计记录一并落盘);引擎把授权留痕写入目标节点的嵌套证据(`state.evidence.<target>.reentryAuthorization`),缺授权或形态不合法一律 BLOCKED 且 state 字节零改写,授权不可由执行者自决(授权是声明式信任边界:`state` 只走脚本通道留痕,hook 拦工具不拦脚本,引擎按声明处理)。
35
+ - **上限与显式续轮**:每 change 最多 3 轮;第 4 次 BLOCKED 并给出「继续 / 停止」人工裁决指引。人工裁决「继续」须追加 `--continue-round <n>`(正整数,且 n ≥ 已用轮次 + 1)作显式续轮授权:满足则放行并计入下一轮、审计行打印 `第 n 轮(显式授权续轮,上限 3)`;未到上限即传该参数、或轮次不足一律 BLOCKED 且零改写。轮次与审计事件记入 `state.history`(事件类型 `reentry-applied`,含 `reason`;续轮时附 `continuationAuthorized: true`),成功输出 `REENTRY: archive → <target>(授权源 <source>;第 n/3 轮;备份 <file>)` 与 `REASON: <text>` 两行。
36
+ - **备份**:转移前自动落 state 快照 `.specs/<change-id>/.reentry-backups/<UTC ISO>-pre-<target>.json`(时间戳中的 `:` 替换为 `-`),并记录 sha256 指纹,供审查核验与手工回滚。
37
+ - **顺序**:命令成功后再写修复内容——archive 阶段写入白名单只放行 `.specs/<change-id>/KNOWN-ISSUES.md` 等少数路径;重入后写入权限跟随目标节点,此时才追加 Fix 任务 / 修改工件。
38
+ - **边界**:归档移动已发生或 change 已 `completed` → BLOCKED,走人工处置或新 change / hotfix;重复调用同一目标 → 空操作(输出 `REENTRY: 空操作——…`,不备份、不计数、不改写 state),不会静默跳过。
39
+
40
+ ### 归档后发现缺陷(受控重入)
41
+
42
+ 归档已 entry 但归档移动尚未发生(`.specs/<change-id>/` 仍在原位、`status !== 'completed'`)时,review / verify / 执行阶段发现的新缺陷按下列边界处置:
43
+
44
+ - **未移动** → 受控重入:由用户显式授权后运行
45
+
46
+ ```bash
47
+ node .claude/skills/flow-comet/scripts/workflow-state.mjs reenter <target> --authorized-by <source> --reason <text> [--continue-round <n>]
48
+ ```
49
+
50
+ 目标限 `execute` / `subagent-execute` / `review` / `verify` 之一;每次调用都需要用户显式授权,每 change 上限 3 轮(达上限后凭显式续轮授权 `--continue-round <n>`(n ≥ 已用轮次 + 1)可继续并计入下一轮);命令先自动落 state 备份快照(`.specs/<change-id>/.reentry-backups/`),再转移工作归属,并打印 `REENTRY: archive → <target>(授权源 <source>;第 n/3 轮;备份 <file>)` 与 `REASON: <text>` 行(续轮审计行为 `第 n 轮(显式授权续轮,上限 3)`)。缺授权、目标越界、超上限或归档移动已发生一律 BLOCKED(state 字节零改写),不会静默跳过。
51
+ - **已移动 / 已合并** → 人工处置或新 change:归档移动已发生(`.specs/archive/<日期>-<change-id>/`)或 change 已 `completed` / 已合并时,受控重入不适用(不承诺把文件搬回原位);走人工处置,或把修复放进新 change / hotfix,并在遗留清单里登记指针。
52
+
53
+ **写权限顺序(先转移后写 TASK)**:archive 阶段 hook 对 change 目录只放行 `KNOWN-ISSUES.md` 这一个精确文件(另有 `.specs/archive/`、`.specs/CHANGELOG.md`、`.specs/LESSONS.md`、`STATE.md`),TASK.md 的修复任务写入不在放行面内。顺序固定为:先跑 `reenter` 完成转移(写入权限随即跟随目标节点),再在目标节点权限内追加 Fix 任务 / 修改工件——不要试图在 archive 阶段先写 TASK.md。若重入成功后追加任务失败,用 `next` / `status` 核对归属;重复调用同一目标为空操作(不备份、不计数、不改写 state)。
54
+
55
+ ### 受控重入打开的修复场景(archive 源)
56
+
57
+ 缺陷在归档后才暴露、且归档移动尚未发生时,可先由用户显式授权把工作归属退回本节点或 `execute` / `review` / `verify`,再按常规委托与出口流程完成修复。重入命令:`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,不得静默跳过。重入只改工作归属,不写任何闭合标记,也不跳过本节点入口 / 出口门禁;重入后并行任务的委托证据、write_files 边界与 Return Contract 校验与常规流程完全一致;重复调用同一目标为空操作(输出 `REENTRY: 空操作——…`,不备份、不计数、不改写 state)。
@@ -0,0 +1,58 @@
1
+ # 平台事实(三平台通道 · 判级口径 · 实测与边界)
2
+
3
+ > **读者对象**:在任一节点上引用平台结论、构造委派 prompt、或要写「某平台支持 / 不支持」措辞的执行者与协调者。
4
+ > **何时读**:要判定平台能力(能否并行委派 / 谁建树 / 写通道是什么)或引用平台判级口径时读。
5
+ >
6
+ > 本文件内容**逐字搬运**自 `flow-comet-subagent-execute` 与 `flow-comet` 两册的原有段落(搬运,不重写);各节点册只留要点句与条件句。
7
+
8
+ ## Codex 平台事实与当前支持面
9
+
10
+ > **Codex 平台事实与 flow-comet 当前支持面(2026-09-30 记录)**:**平台事实**——Codex 的常规用法是交互式 CLI(`codex` 无子命令)与会话内 agent,`codex exec` 只是 headless 子面;原生多代理 `multi_agent` 为 stable、默认启用(`codex features list` 可查),本机真实交互式会话日志中记录到 `spawn_agent` / `wait_agent` / `close_agent` 的实际调用——因此「Codex 不能委派 / 不使用并行委托」**不是平台事实**。**已关闭的机制缺口**——本节点此前记录「原生子代理形态未被守卫 / 白名单 / 隔离模型覆盖」的**机制缺口**,已由身份分派(载荷 `agent_id`)关闭:**三平台均可并行委派,差异只在谁建树**(Codex 无自动建树、默认共享工作区);headless 子面实测见下(仅 `codex exec`,不得外推)。
11
+
12
+ ## 通道对照表(subagent-execute 侧:四属性 × 三平台)
13
+
14
+ > **三平台通道对照表(四属性 × 三平台;差异只在「谁建树」)**:
15
+ >
16
+ > | 平台 | ① 写权限通道 | 谁建树 | ②③④ |
17
+ > |------|--------------|--------|-------|
18
+ > | **Claude Code** | 身份分派(载荷含 `agent_id` / `agent_type`——**证实**:真机实测子代理载荷含二者、主会话载荷不含,与 Codex 同一判据);`.claude/worktrees/**` 路径前缀为**兼容通道**,不是唯一通道 | harness 可自动建树(`Agent` 工具的 `isolation: "worktree"`——①的一种实现,非强制) | 三平台同形 |
19
+ > | **Codex** | 身份分派(载荷含 `agent_id` / `agent_type`;真机实测:子代理载荷 12 键含 `agent_id`,主线程 10 键不含) | 无自动建树——默认**共享工作区** | 三平台同形 |
20
+ > | **dsh** | 身份分派(桥接以环境变量 `FLOW_COMET_AGENT_DEPTH` 透传正整数身份深度 **+ 通道标记 `FLOW_COMET_AGENT_DEPTH_SOURCE`**;0 / 缺失 / 无标记 = 协调者) | 平台**进程内子代理**,不建树 | 三平台同形 |
21
+
22
+ ## 判级口径(三态)
23
+
24
+ > **判级口径(三态;未覆盖项显式标注、不得写成已支持)**:**证实**——Codex 交互式会话的原生子代理载荷含 `agent_id`(2026-10-04/05 真机会话实测)· CC 子代理载荷含 `agent_id` / `agent_type`(真机实测:子代理载荷含二者、主会话载荷不含,与 Codex 同一判据)· dsh 身份分派通道 · CC 的 `.claude/worktrees/**` 兼容通道(历史实证)。**推翻**——「Codex 载荷无身份字段」只对 `codex exec` headless 主线程成立,**不得外推**为平台结论。**未覆盖(显式标注,不得写成已支持)**——非 Windows 环境的 Codex 形态 · `agent_type` 取值域 · 嵌套委派载荷 · Codex hook 触发稳定性(实测 3/21;补 `--dangerously-bypass-approvals-and-sandbox` 后 5/5,**不得写成稳定保证**)· 非 `bypassPermissions` 权限模式下的载荷形态 · dsh 子代理能否带独立 cwd 的探针待补。
25
+
26
+ ## 旧结论留档
27
+
28
+ > **旧结论(实测 2026-08-13;证据已不可复核,未纳入 2026-09-30 重测矩阵——不得作为现行结论)**:worktree 的 `.git` 是主仓共享——`workspace-write`/`git-write-access` 沙箱均被 Codex 硬拦截(index.lock / objects / COMMIT_EDITMSG Permission denied);子代理必须用 `sandbox_mode="danger-full-access"` 才能完成 git 提交(worktree 隔离已限定写范围,full-access 仅用于让 git 提交可行)。**信任边界**:`danger-full-access` 是宿主级信任边界(不隔离凭据/网络访问)——仅委托可信子代理,并移除委托环境中的不必要凭据。以上仅作历史留档;现行结论以探针结论与后续契约为准。
29
+
30
+ ## headless 子面实测与 hook 会话 root 订正
31
+
32
+ > **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**,记录时点**未闭合**)——**该缺口现已被守卫关闭**:runRoot 外写入与 Bash 写命令分支**同判** `BLOCKED`(修复前的两分支不对称是历史形态),身份在场者由身份判据先行放行;记录时点的缺口表述作为边界留档保留,现行判据见守卫的 runRoot 外关断段。**`apply_patch`**:会触发 PreToolUse,但 `tool_name="Bash"`、补丁正文在 `tool_input.command`(heredoc)、**无 `file_path`**;记录时点守卫不解析补丁体 → 目标不被提取、放行(独立复验复现了载荷与守卫盲区)——**该缺口现已被守卫关闭**:补丁体按行语义解析出 `*** Update File:` / `*** Add File:` / `*** Delete File:` / `*** Move to:` 摘要行的目标后与其余写入形态**同流**(白名单与最小保护集共用同一判定入口),身份在场者仍受最小保护集拦截;「文件确实落盘」子项在复验环境因 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 形态未覆盖。**CC 的判据不同**:CC 的守卫以**身份判据优先于路径判据**(载荷含 `agent_id` ⇒ 子代理语义);`.claude/worktrees/**` 路径前缀通道仍然在场,属**兼容通道**(写入落在该区内即放行,`file_path` 与 Bash 命令两条判定路径同语义),不再是唯一通道。
33
+
34
+ ## 入口册侧:三平台通道表与实测口径(原文搬运)
35
+
36
+ **三平台通道(属性 × 平台)**——判级只取三态(**证实 / 推翻 / 未覆盖**);**未覆盖 ≠ 已验证**,不得写成已支持:
37
+
38
+ | 属性 | Claude Code | Codex | dsh |
39
+ |------|-------------|-------|-----|
40
+ | ① 写权限 | 载荷 `agent_id` / `agent_type`——**证实**(真机实测:子代理载荷含二者、主会话载荷不含;与 Codex 同一判据) | 载荷 `agent_id` + `agent_type`——**证实**(实测:子代理载荷 12 键含二者、主线程 10 键不含);守卫读 `agent_id`,与 CC 同一判据 | 桥接透传 `delegationDepth` **+ 通道标记**(`FLOW_COMET_AGENT_DEPTH_SOURCE`,守卫要求两者同时在场才接受 env 面身份——继承来的深度变量不作数)——**证实**(0.1.7-rc.2 全接缝重认证;本批收窄为「最小保护集除外」) |
41
+ | ② 提交隔离 | pathspec 纪律(多写者共享同一工作区形态) | 同左 | 同左 |
42
+ | ③ 验证隔离 | `subagent-execute` 出口锚:有 request 无 result(新 change BLOCKED / 旧 change WARN 渐进) | 同左 | 同左 |
43
+ | ④ 集成纪律 | `merge --no-ff` 优先;降级 cherry-pick 必记因 | 同左 | 同左 |
44
+ | **谁建树**(三平台唯一差异) | 可选:harness `isolation: "worktree"` 建独立树,或共享工作区直写 | 协调者**显式** `git worktree add` 并在委派 prompt 指定 `workdir`(原生子代理无自动建树;**证实**:子代理可被指向独立目录并落盘),或共享工作区直写;**建树选择的适用面**:协调者显式 `git worktree add <路径>`(手工建树)**是受支持的建树选择**——在委派 prompt 里指定 `workdir`,写入由身份通道放行(原生子代理无自动建树);**以建树绕过边界**不受支持——用独立树规避协调者禁令 / 最小保护集 / `write_files` 互斥与提交时点纪律 / handoff 与 Return Contract 证据,或把 worktree 当作四属性的替代品。 | **不建树**:进程内子代理、同一工作区运行——**无需隔离区 ≠ 无需边界**(`write_files` 互斥 + 提交时点 + 最小保护集仍构成边界) |
45
+
46
+ **交互式 Codex 实测口径(口径以下文陈述为准;该次取证为**一次性工件**、已按仓库纪律清理——**分发产物不得把结论挂靠一次性路径**)**:交互式 Codex 会话触发 `PreToolUse`(启动有 hook 信任提示)· 原生子代理工具调用触发 · `spawn_agent` / `wait_agent` / `close_agent` 类调用各自触发 · 子代理可被指向独立 worktree · 全局 `~/.codex/hooks.json` 与项目级 hook **并存生效**(合并规则未覆盖)。
47
+
48
+ **已知边界(不得写成机械保证)**:① Codex 载荷 `cwd` = 会话根,**与实际工作目录无关**(实测证实)⇒ 路径判定在 Codex 上必错,故判定序为**身份先于路径**;② 身份判据是**声明式信任边界**——守卫读到的 `agent_id` 来自宿主载荷,本机制**不声称能证明**其真实来源;③ 该次实测结论只覆盖「Windows + 交互式 Codex TUI + 该版本」形态;CC 侧身份判据的真机实测条件同样是**限定形态**——**Windows + CC v2.1.177 + `permission_mode = bypassPermissions` + 一次性仓库载体**。`agent_type` 取值域、嵌套委派载荷、非 Windows 环境、非 `bypassPermissions` 权限模式**均未覆盖**(未覆盖 ≠ 已验证,不得写成已支持)。
49
+
50
+ **三平台 `cwd` 语义对照(真机实测新增的精确事实 · 「身份先于路径」的精确理由)**——同为载荷 `cwd`,三平台语义各不相同;下表**三行各自独立**,缺一行即口径残缺:
51
+
52
+ | 平台 | 载荷 `cwd` 的实际语义 | 对路径判定的影响 |
53
+ |------|----------------------|------------------|
54
+ | **Claude Code** | **子代理的工作目录**(`…\.claude\worktrees\<agent-id>`) | **路径判定是正确的** |
55
+ | **Codex** | **恒等于会话根**(子代理在 worktree 写入而 `cwd` 仍是主工程) | **路径判定必错** |
56
+ | **dsh** | 载荷**无** `cwd`(桥接另读会话 header cwd) | 路径判定**不适用** |
57
+
58
+ > ⇒ **不是「路径判定普遍不可靠」,而是三平台 `cwd` 语义各不相同(正确 / 恒错 / 无)——只有身份判据是三平台同义的**。该对照只解释**为什么必须身份优先**,**不构成**「可以改走路径判定」的依据:契约仍走**身份判据**(三条通道同义)。
@@ -0,0 +1,23 @@
1
+ # 受控重校(`replan` · execute 源)
2
+
3
+ > **读者对象**:`execute` / `subagent-execute` 相位上发现计划有缺陷、需要重新校验并重签任务集的协调者与执行者。
4
+ > **何时读**:要判定该不该走 `replan` 重校任务集、或出口报「任务集签名不匹配」时读。
5
+ >
6
+ > 本文件内容**逐字搬运**自入口册 `flow-comet` 的「受控重校」段原文(搬运,不重写);入口册与 `flow-comet-execute` 册只留要点句与条件句。
7
+
8
+ ## 规格全文(入口册原文搬运)
9
+
10
+ ### 受控重校(`replan` · execute 源)
11
+
12
+ 计划在执行中被证明有缺陷、任务集因此需要修订时,用受控重校重新校验并重签任务集——不跳节点、不重置任何完成态:
13
+
14
+ ```bash
15
+ node .claude/skills/flow-comet/scripts/workflow-state.mjs replan "<reason>" --authorized-by <source> [--continue-round <n>]
16
+ ```
17
+
18
+ - **何时用**:`currentNode` 停在 `execute` / `subagent-execute`,且任务集在进入该节点后被修订、出口因此报「签名不匹配」时;修订后的任务集必须自身合法。
19
+ - **授权**:每次调用都需要用户显式授权——`--authorized-by` 记录授权来源,位置参数记录原因;引擎把授权留痕写入当前节点的嵌套证据(`state.evidence.<node>.replanAuthorization`)。缺授权、值为空/纯空白或形态非法一律 BLOCKED,且 state 字节零改写。
20
+ - **上限与显式续轮**:每 change 最多 3 轮;第 4 次 BLOCKED 并给出「继续 / 停止」人工裁决指引。人工裁决「继续」须追加 `--continue-round <n>`(正整数,且 n ≥ 已用轮次 + 1)作显式续轮授权:满足则放行并计入下一轮,审计行打印续轮标记;未到上限即传该参数、或轮次不足一律 BLOCKED 且零改写。轮次与审计事件记入 `state.history`(事件类型 `replan-applied`),成功输出 `REPLAN: <node> 重新校验通过(授权源 <source>;第 n/3 轮;备份 <file>)` 与 `REASON: <text>` 两行。
21
+ - **备份**:改写前自动落 state 快照 `.specs/<change-id>/replan-backups/<UTC ISO>-pre-replan.json`(时间戳中的 `:` 替换为 `-`),并记录 sha256 指纹,供审查核验与手工回滚。
22
+ - **幂等与零改写**:目标形态已成立时的重复同形态调用 = 空操作(输出 `REPLAN: 空操作——…`,不备份、不计数、不写事件、不改写 state),不会静默跳过。
23
+ - **绝不豁免校验**:`replan` 只做「重新校验 + 重新签名」——判据与 plan 出口同源,处置按路径分列:**replan 重校**——任务块 / 每任务 `<verify>` / 任务图(依赖环 / 缺失依赖)任一不成立,或并行写冲突的写写(write∩write)成立,一律 BLOCKED(状态零改写);读写(read∩write)仅 WARN 不阻断;7 字段完整性只在「新模板形态(含 `<name>`)+ 新 change」缺字段时 BLOCKED,其余情形 WARN 渐进。**plan 出口**——任务块 / 每任务 `<verify>` 缺失一律 BLOCKED;任务图的依赖环 / 缺失依赖与并行写冲突的写写,对新 change BLOCKED、旧 change WARN 渐进;读写对新旧 change 均仅 WARN。它不是绕过签名门禁,而是把「签名不匹配」重新收敛为「匹配」。
@@ -16,14 +16,15 @@ const required = [
16
16
  "../flow-comet-review/SKILL.md",
17
17
  "../flow-comet-verify/SKILL.md",
18
18
  "../flow-comet-archive/SKILL.md",
19
- "reference/resolved-skills.json",
20
19
  "reference/workflow-protocol.json",
21
20
  "reference/decision-points.md",
22
21
  "reference/recovery.md",
23
22
  "reference/authoring-lanes.json",
24
- "reference/skill-review.md",
25
- "reference/composition-report.md",
26
- "reference/subagents/script-author.md",
23
+ "reference/platform-facts.md",
24
+ "reference/fix-loop.md",
25
+ "reference/replan.md",
26
+ "reference/commit-discipline.md",
27
+ "reference/entry-detail.md",
27
28
  "scripts/comet-plan.mjs",
28
29
  "scripts/comet-check.mjs",
29
30
  "scripts/comet-hook-guard.mjs",