flow-comet 1.5.0-rc.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.
- package/.flow-comet/rules/flow-comet-orchestration.md +13 -0
- package/.flow-comet/skills/flow-comet/GUIDANCE.md +196 -0
- package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -0
- package/.flow-comet/skills/flow-comet/SKILL.md +196 -0
- package/.flow-comet/skills/flow-comet/reference/KNOWN-ISSUES-template.md +19 -0
- package/.flow-comet/skills/flow-comet/reference/TEST-MATRIX.md +115 -0
- package/.flow-comet/skills/flow-comet/reference/authoring-lanes.json +33 -0
- package/.flow-comet/skills/flow-comet/reference/composition-report.md +65 -0
- package/.flow-comet/skills/flow-comet/reference/decision-points.md +64 -0
- package/.flow-comet/skills/flow-comet/reference/dirty-worktree.md +30 -0
- package/.flow-comet/skills/flow-comet/reference/dsh-platform.md +169 -0
- package/.flow-comet/skills/flow-comet/reference/init-detection.md +58 -0
- package/.flow-comet/skills/flow-comet/reference/recovery.md +20 -0
- package/.flow-comet/skills/flow-comet/reference/resolved-skills.json +661 -0
- package/.flow-comet/skills/flow-comet/reference/skill-review.md +13 -0
- package/.flow-comet/skills/flow-comet/reference/subagents/script-author.md +7 -0
- package/.flow-comet/skills/flow-comet/reference/workflow-protocol.json +681 -0
- package/.flow-comet/skills/flow-comet/reference/worktree-notes.md +52 -0
- package/.flow-comet/skills/flow-comet/scripts/comet-check.mjs +61 -0
- package/.flow-comet/skills/flow-comet/scripts/comet-hook-guard.mjs +909 -0
- package/.flow-comet/skills/flow-comet/scripts/comet-plan.mjs +2 -0
- package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +312 -0
- package/.flow-comet/skills/flow-comet/scripts/contract-check.mjs +136 -0
- package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +7331 -0
- package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +376 -0
- package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +230 -0
- package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +99 -0
- package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +4017 -0
- package/.flow-comet/skills/flow-comet/scripts/task-parsing.mjs +28 -0
- package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +2396 -0
- package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +378 -0
- package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +1263 -0
- package/.flow-comet/skills/flow-comet-archive/SKILL.md +195 -0
- package/.flow-comet/skills/flow-comet-change/SKILL.md +29 -0
- package/.flow-comet/skills/flow-comet-compose/SKILL.md +249 -0
- package/.flow-comet/skills/flow-comet-design/GUIDANCE.md +23 -0
- package/.flow-comet/skills/flow-comet-design/SKILL.md +161 -0
- package/.flow-comet/skills/flow-comet-dev/SKILL.md +51 -0
- package/.flow-comet/skills/flow-comet-evolve/SKILL.md +26 -0
- package/.flow-comet/skills/flow-comet-execute/SKILL.md +182 -0
- package/.flow-comet/skills/flow-comet-health/SKILL.md +31 -0
- package/.flow-comet/skills/flow-comet-integration/SKILL.md +45 -0
- package/.flow-comet/skills/flow-comet-open/GUIDANCE.md +36 -0
- package/.flow-comet/skills/flow-comet-open/SKILL.md +161 -0
- package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +33 -0
- package/.flow-comet/skills/flow-comet-plan/SKILL.md +169 -0
- package/.flow-comet/skills/flow-comet-requirement/SKILL.md +27 -0
- package/.flow-comet/skills/flow-comet-review/SKILL.md +204 -0
- package/.flow-comet/skills/flow-comet-subagent-execute/GUIDANCE.md +29 -0
- package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +214 -0
- package/.flow-comet/skills/flow-comet-task/SKILL.md +33 -0
- package/.flow-comet/skills/flow-comet-test/SKILL.md +41 -0
- package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +26 -0
- package/.flow-comet/skills/flow-comet-verify/SKILL.md +164 -0
- package/LICENSE +21 -0
- package/README.md +255 -0
- package/package.json +27 -0
- package/scripts/dsh-bridge.mjs +461 -0
- package/scripts/prepare-env.mjs +1526 -0
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# flow-comet Orchestration
|
|
2
|
+
|
|
3
|
+
This Bundle is generated by flow-comet and uses a portable control plane.
|
|
4
|
+
|
|
5
|
+
- Entry Skill: `skills/flow-comet/SKILL.md`
|
|
6
|
+
- Plan script: `skills/flow-comet/scripts/comet-plan.mjs`
|
|
7
|
+
- Check script: `skills/flow-comet/scripts/comet-check.mjs`
|
|
8
|
+
- Hook guard script: `skills/flow-comet/scripts/comet-hook-guard.mjs`
|
|
9
|
+
- Workflow state script: `skills/flow-comet/scripts/workflow-state.mjs`
|
|
10
|
+
- Workflow guard script: `skills/flow-comet/scripts/workflow-guard.mjs`
|
|
11
|
+
- Workflow handoff script: `skills/flow-comet/scripts/workflow-handoff.mjs`
|
|
12
|
+
|
|
13
|
+
Run the generated Skill through its workflow protocol and keep resolved Skill evidence in `skills/flow-comet/reference/`.
|
|
@@ -0,0 +1,196 @@
|
|
|
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
|
+
---
|
|
5
|
+
|
|
6
|
+
# flow-comet
|
|
7
|
+
|
|
8
|
+
> 手写区详细协议——主 SKILL.md 的展开版(可选阅读;主 SKILL.md 与本文冲突时以本文为准,本文以外的部分以 SKILL.md 为准,协议定义以 `reference/workflow-protocol.json` 为准)。
|
|
9
|
+
|
|
10
|
+
flow-kit 9 阶段工作流的 workflow-kernel 实现。保留 flow-kit 的全部产物模板、规则体系和 LESSONS 知识库,用脚本自动管理状态和阶段路由。
|
|
11
|
+
|
|
12
|
+
**工件根目录:`.specs/<change-id>/`**
|
|
13
|
+
|
|
14
|
+
## Decision Core
|
|
15
|
+
|
|
16
|
+
### 自动节点检测
|
|
17
|
+
|
|
18
|
+
**Step 0:确定当前节点与意图**
|
|
19
|
+
|
|
20
|
+
1. 检查 workflow protocol 的有序 Node 列表(open→design→plan→execute→subagent-execute→review→verify→archive)。
|
|
21
|
+
2. 运行 `node .claude/skills/flow-comet/scripts/workflow-state.mjs status` 确认检测到的节点。
|
|
22
|
+
3. 若脚本输出与文件产物冲突(如脚本说 execute 但 TASK.md 不存在),以文件为准,先纠正状态再继续。
|
|
23
|
+
4. 若用户描述的工作明显属于更后面的 Node(如"验证结果"但 design 尚未完成),暂停并说明前序 Node 必须先完成。
|
|
24
|
+
5. 若用户描述的工作属于已标记完成的更早 Node,视为纠正——重置该 Node 的完成状态并重新进入。
|
|
25
|
+
|
|
26
|
+
**Step 1:flow-kit 产物门禁**
|
|
27
|
+
|
|
28
|
+
| 目标节点 | 必须已有的上游工件 | 缺失时动作 |
|
|
29
|
+
|---------|-----------------|-----------|
|
|
30
|
+
| open | 无 | 直接进入 |
|
|
31
|
+
| design | CHANGE.md + REQUIREMENT.md | 回 open 补齐 |
|
|
32
|
+
| plan | DESIGN.md(或 DESIGN-lite.md) | 回 design 补齐 |
|
|
33
|
+
| execute | TASK.md | 回 plan 补齐 |
|
|
34
|
+
| subagent-execute | TASK.md(含 parallel=true pending 任务) | 回 execute 串行执行 |
|
|
35
|
+
| review | 所有 task status="done" | 回 execute 补齐 |
|
|
36
|
+
| verify | REVIEW.md | 回 review 补齐 |
|
|
37
|
+
| archive | UAT.md | 回 verify 补齐 |
|
|
38
|
+
|
|
39
|
+
**Step 2:读取下一个节点**
|
|
40
|
+
|
|
41
|
+
运行 `node .claude/skills/flow-comet/scripts/workflow-state.mjs next`。若返回的 NODE 与 Step 0 产物检测不一致,以产物为准。
|
|
42
|
+
|
|
43
|
+
### Resume 规则
|
|
44
|
+
|
|
45
|
+
- 每次上下文恢复,重新执行 Step 0 和 Step 2。不信任对话历史。
|
|
46
|
+
- 产物文件(`.specs/<id>/`)是唯一真相源。脚本状态只是加速器。
|
|
47
|
+
- 若状态显示某 Node 已完成但预期 artifact 缺失,视为未完成并重新进入。
|
|
48
|
+
- 若用户在某个 Node 中途恢复但话题变了,确认是继续当前 Node 还是开始新的。
|
|
49
|
+
|
|
50
|
+
### 决策分类与决策点
|
|
51
|
+
|
|
52
|
+
先分类再行动:
|
|
53
|
+
|
|
54
|
+
| 分类 | 定义 | 处理 |
|
|
55
|
+
|------|------|------|
|
|
56
|
+
| 用户决策 | ≥2 个会改变范围/行为/风险/不可逆结果的合法选项 | 用交互确认问(Claude Code 用 AskUserQuestion 优先;Codex 用文本提问+内联确认)或文本回退;相邻选择合并为一个问题,不重问已持久化选择 |
|
|
57
|
+
| 自动处理 | 唯一安全下一步 | 直接执行并汇报,不许制造确认 |
|
|
58
|
+
| 停止条件 | guard 失败 / 缺依赖 / 状态损坏 | 报告阻塞与恢复条件,无合法动作时才升级为用户决策 |
|
|
59
|
+
| 手动交接 | `NEXT: manual`(若有) | 不是用户决策,直接继续 |
|
|
60
|
+
|
|
61
|
+
**决策点清单(挂到四分类下,详细作者化见 `reference/decision-points.md`)**:
|
|
62
|
+
- **用户决策**:首次调用且主题/范围有多个合法解释;技术栈选型(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)
|
|
63
|
+
- **自动处理**:唯一安全下一步直接执行;flow-kit 反问协议要求确认(CHANGE/REQUIREMENT/DESIGN)按 flow-kit 规则暂停等待
|
|
64
|
+
- **停止条件**:Node guard 失败时先自动诊断并执行唯一安全修复;缺依赖或状态损坏导致无法继续时报告停止条件与恢复条件;只有恢复方式存在多个会改变范围或风险的合法选项时,才升级为用户决策
|
|
65
|
+
|
|
66
|
+
### Red Flags
|
|
67
|
+
|
|
68
|
+
| Agent 想法 | 实际风险 |
|
|
69
|
+
|-----------|---------|
|
|
70
|
+
| "这是小改动,不用走完整流程" | 可走最短路径但不能跳过阶段门禁 |
|
|
71
|
+
| "REQUIREMENT 可以跳过,直接写代码" | R2.2:没有 REQUIREMENT 不能进 DESIGN |
|
|
72
|
+
| "verify 通过了所以可以归档" | 还要检查 REVIEW.md 的 Critical 项是否全部处理 |
|
|
73
|
+
| "上下文恢复后从上次对话继续" | 始终重新读取状态和产物文件,对话记忆不可靠 |
|
|
74
|
+
| "LESSONS.md 不用扫" | R1.8:每个 DEV 任务必须扫描 |
|
|
75
|
+
| "测试从实现派生就行" | R5.1:测试必须从 AC 派生 |
|
|
76
|
+
| "guard 失败了,让用户决定" | 先自动诊断并执行唯一安全修复;无合法动作时才报告停止条件 |
|
|
77
|
+
| "跳过 entry 直接 exit,反正没检查" | 新 change 未 entry 直接 exit → BLOCKED(进入检查不可跳过);旧 change WARN 渐进 |
|
|
78
|
+
| "SUMMARY 不写,任务先标 done" | 新 change done 任务缺 SUMMARY → BLOCKED(产物完整性强制);旧 change WARN 渐进 |
|
|
79
|
+
| "subagent-execute 阶段,我直接改源码更快" | 协调者禁令:subagent-execute 阶段主会话禁止写源码(hook 白名单只允许 .specs/,Write/Edit 与 Bash 写命令均物理拦截),必须 worktree 委托子代理 |
|
|
80
|
+
|
|
81
|
+
## Workflow Nodes
|
|
82
|
+
|
|
83
|
+
| 节点 | Kind | 职责 | Output Schema |
|
|
84
|
+
|------|------|------|---------------|
|
|
85
|
+
| open | control | CHANGE 反问 + REQUIREMENT 需求 | flowkit.intake.v1 |
|
|
86
|
+
| design | control | 技术决策 + ADR | flowkit.design.v1 |
|
|
87
|
+
| plan | control | 拆原子任务 | flowkit.plan.v1 |
|
|
88
|
+
| execute | control | TDD 开发 + 自查(串行) | flowkit.execution.v1 |
|
|
89
|
+
| subagent-execute | handoff | [P] 并行任务委托 | flowkit.handoff.v1 |
|
|
90
|
+
| review | control | 4 轮审查 | flowkit.review.v1 |
|
|
91
|
+
| verify | control | 集成验证 + UAT | flowkit.verify.v1 |
|
|
92
|
+
| archive | control | 归档 + LESSONS | flowkit.archive.v1 |
|
|
93
|
+
|
|
94
|
+
> **并行任务路由(节点顺序是动态的 · 多趟语义)**:TASK 含依赖已满足的 `parallel="true" status="pending"` 任务时路由到 subagent-execute——每趟委托全部依赖已满足的并行任务;子代理返回后重新判定:仍有可并行 pending 就再次进入 subagent-execute(委托节点可多次往返),存在串行 pending 时回 execute 消化一趟再循环。委托节点的完成 = 不存在依赖已满足的可并行 pending 且无串行残留;并行/串行交错的混排序列合法,唯一前置拦截是依赖环(plan 出口校验并附恢复指引)。全部为串行任务时走 execute,行为不变。`next` 的输出始终是权威——以 `NODE:` 输出为准,不按静态顺序推断。
|
|
95
|
+
|
|
96
|
+
## Skill Bindings
|
|
97
|
+
|
|
98
|
+
| 节点 | Implementation | Required Calls | Enforcement |
|
|
99
|
+
|------|---------------|----------------|-------------|
|
|
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 |
|
|
102
|
+
| plan | flow-comet-plan | flow-comet-task | guarded |
|
|
103
|
+
| execute | flow-comet-execute | flow-comet-dev | guarded |
|
|
104
|
+
| subagent-execute | flow-comet-subagent-execute | flow-comet-dev (handoff) | handoff-guarded |
|
|
105
|
+
| review | flow-comet-review | flow-comet-review, flow-comet-test | guarded |
|
|
106
|
+
| verify | flow-comet-verify | flow-comet-integration | guarded |
|
|
107
|
+
| archive | flow-comet-archive | flow-comet-integration | guarded |
|
|
108
|
+
|
|
109
|
+
**节点技能两层加载模型(入口层 · 双步硬规则)**:路由到节点后,以下两步**都不可跳过**:
|
|
110
|
+
|
|
111
|
+
1. **用 Skill 工具加载该节点的 Implementation 技能**(见下方 Skill Bindings 表 Implementation 列,如 execute → flow-comet-execute)。**不得跳过**——只读取 SKILL.md 文件不叫加载;真正让该 skill 的指令生效的是 Skill 工具把它注入本次会话。
|
|
112
|
+
2. 随后按该节点 SKILL 的 Required Skill Calls,用 Skill 工具加载协议技能(与 Implementation 同名的条目已随路由加载,无需重复加载),加载完成后**立即**逐条运行声明命令(open/review 等涉及多个协议文件的节点,每个协议文件对应一条声明命令):
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load <node> <skill> --prompt flow-kit/prompts/<阶段>.md
|
|
116
|
+
```
|
|
117
|
+
|
|
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
|
+
|
|
120
|
+
节点退出(exit)与证据记录(record)会核对声明标记。声明如实记录执行者动作——加载了哪个 skill、按哪份协议工作——**不等于产出证明**;产出是否正确由产物结构校验与门禁把关。**技能加载前置门**:新 change 的 required 条目不再自动补写——handoff request / record 前必须已有本节点声明标记(先加载、再声明、后干活);声明标记自动补写仅对旧 change 兜底(按协议 requiredSkillCalls 代记,标记带 `auto: true`),手动声明仍推荐(如实记录加载动作与协议文件)。advisory 条目(如 flow-comet-ui-design,仅前端触发)不要求 skill-load 声明——record 只校验执行者实际声明的条目。
|
|
121
|
+
|
|
122
|
+
## Guardrails And Evidence
|
|
123
|
+
|
|
124
|
+
| 节点 | Guardrail | Validation | Description |
|
|
125
|
+
|------|-----------|-----------|-------------|
|
|
126
|
+
| open | intake-artifacts | artifact-exists | CHANGE.md + REQUIREMENT.md exist |
|
|
127
|
+
| design | design-artifacts | artifact-exists | DESIGN.md exists |
|
|
128
|
+
| plan | plan-artifacts | artifact-exists | TASK.md exists |
|
|
129
|
+
| execute | build-evidence | artifact-exists | At least one SUMMARY.md |
|
|
130
|
+
| subagent-execute | handoff-evidence | evidence-only | Handoff evidence recorded |
|
|
131
|
+
| review | review-evidence | artifact-exists | REVIEW.md exists |
|
|
132
|
+
| verify | verify-evidence | artifact-exists | TEST.md + UAT.md exist |
|
|
133
|
+
| archive | archive-evidence | state-transition | Archive completed |
|
|
134
|
+
|
|
135
|
+
## Runtime And Recovery
|
|
136
|
+
|
|
137
|
+
### Startup Protocol
|
|
138
|
+
|
|
139
|
+
1. Run `node .claude/skills/flow-comet/scripts/workflow-state.mjs status` to detect active change and current node.
|
|
140
|
+
2. If no active change and user wants to start new work: `node .claude/skills/flow-comet/scripts/workflow-state.mjs init <change-name>`. **init 自动检测项目上下文**:需要初始化时输出提示(同意重跑 `init <id> --init-context` 全量生成 CONTEXT.md / 拒绝 `--init-skip`);CONTEXT.md 已存在且新鲜时完全静默——详见 `reference/init-detection.md`。
|
|
141
|
+
3. **首次路由**: `init` 输出即首次路由(NODE: 内置 open 或协议首节点)——直接加载该节点 Skill 并执行(产出工件),一次只加载一个 Skill。`next` 在节点完成(`guard exit <node> --apply` 推进)后用于获取下一节点;init 后立即 `next` 会命中节点顺序门禁(open 未 exit → BLOCKED,符合节点顺序门禁语义)。
|
|
142
|
+
|
|
143
|
+
### Resume Rules (every context resume)
|
|
144
|
+
|
|
145
|
+
- **Re-detect from scratch**: on every context resume, re-run Startup Protocol. Do not trust conversation history.
|
|
146
|
+
- **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.
|
|
147
|
+
- **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.
|
|
148
|
+
|
|
149
|
+
### Node Boundary Rules
|
|
150
|
+
|
|
151
|
+
- Before leaving a Node, run `node .claude/skills/flow-comet/scripts/workflow-guard.mjs exit <node> --apply` to advance state.
|
|
152
|
+
- If the guard fails, do not proceed — present the guard output and ask the user how to fix it.
|
|
153
|
+
- If the user wants to redo a completed Node, reset its completion state and re-enter rather than creating a parallel path.
|
|
154
|
+
|
|
155
|
+
### Evidence Recording
|
|
156
|
+
|
|
157
|
+
After completing a Node:
|
|
158
|
+
```bash
|
|
159
|
+
node .claude/skills/flow-comet/scripts/workflow-state.mjs record <node-id> '{"summary":"完成摘要"}'
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
### Artifact Paths
|
|
163
|
+
|
|
164
|
+
All artifacts in `.specs/<change-id>/`. Cross-change files in `.specs/` (CONTEXT.md, LESSONS.md, CHANGELOG.md).
|
|
165
|
+
|
|
166
|
+
### Scripts
|
|
167
|
+
|
|
168
|
+
> **命令路径的平台化**:本文件命令统一为**权威源设计形态** `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
|
+
|
|
170
|
+
| 脚本 | 用途 |
|
|
171
|
+
|------|------|
|
|
172
|
+
| `workflow-state.mjs` | 状态管理:init/status/next/select/record/advance/skill-load/execution-mode/config/verify-fail(verify 失败计数,第 4 次 BLOCKED) |
|
|
173
|
+
| `workflow-guard.mjs` | 节点门禁:entry/exit/verify 检查 |
|
|
174
|
+
| `workflow-handoff.mjs` | 子代理交接:request/result/status |
|
|
175
|
+
| `comet-plan.mjs` | 兼容别名入口(内容为 workflow-state 的别名壳) |
|
|
176
|
+
| `comet-check.mjs` | workflow contract 检查 |
|
|
177
|
+
| `comet-hook-guard.mjs` | 文件写入边界守卫(phase 白名单:subagent-execute 阶段只允许 .specs/;隔离委托的工作区 `.claude/worktrees/**` 放行——`Write`/`Edit` 与 `Bash` 写命令两条判定路径同语义) |
|
|
178
|
+
|
|
179
|
+
### 机器拥有字段
|
|
180
|
+
|
|
181
|
+
以下字段只能由 `workflow-state.mjs` 和 `workflow-guard.mjs` 脚本管理,不应被手动编辑:
|
|
182
|
+
|
|
183
|
+
| 字段 | 说明 | 管理者 |
|
|
184
|
+
|------|------|--------|
|
|
185
|
+
| `currentNode` | 当前活动节点 | workflow-state.mjs next/advance |
|
|
186
|
+
| `completedNodes` | 已完成节点列表 | workflow-guard.mjs exit --apply |
|
|
187
|
+
| `evidence` | 节点证据记录 | workflow-state.mjs record |
|
|
188
|
+
| `verifyFailures` | verify 失败计数 | workflow-guard.mjs (auto-increment) |
|
|
189
|
+
| `verifyFailuresByChange` | 按 change 隔离的失败计数(keyed by change-id) | workflow-state.mjs / state-schema.mjs helper |
|
|
190
|
+
| `status` | 运行状态 | workflow-guard.mjs exit --apply |
|
|
191
|
+
| `executionMode` | subagent/direct,execute 执行模式 | workflow-state.mjs execution-mode |
|
|
192
|
+
| `directOverride` | direct 是否用户显式确认 | workflow-state.mjs execution-mode direct |
|
|
193
|
+
|
|
194
|
+
手动修改这些字段可能导致 guard 校验不一致。若需修正状态,使用 `workflow-state.mjs advance` 或 `workflow-state.mjs select`。
|
|
195
|
+
|
|
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 为平台模型)。
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
1.5.0-rc.3
|
|
@@ -0,0 +1,196 @@
|
|
|
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
|
+
---
|
|
5
|
+
|
|
6
|
+
<!-- 手写区详细协议见 GUIDANCE.md(可选阅读) -->
|
|
7
|
+
|
|
8
|
+
# flow-comet
|
|
9
|
+
|
|
10
|
+
## Decision Core
|
|
11
|
+
|
|
12
|
+
### 自动节点检测
|
|
13
|
+
|
|
14
|
+
**Step 0:确定当前节点与意图**
|
|
15
|
+
|
|
16
|
+
1. 检查 workflow protocol 的有序 Node 列表(open→design→plan→execute→subagent-execute→review→verify→archive)。
|
|
17
|
+
2. 运行 `node .claude/skills/flow-comet/scripts/workflow-state.mjs status` 确认检测到的节点。
|
|
18
|
+
3. 若脚本输出与文件产物冲突(如脚本说 execute 但 TASK.md 不存在),以文件为准,先纠正状态再继续。
|
|
19
|
+
4. 若用户描述的工作明显属于更后面的 Node(如"验证结果"但 design 尚未完成),暂停并说明前序 Node 必须先完成。
|
|
20
|
+
5. 若用户描述的工作属于已标记完成的更早 Node,视为纠正——重置该 Node 的完成状态并重新进入。
|
|
21
|
+
|
|
22
|
+
**Step 1:flow-kit 产物门禁**
|
|
23
|
+
|
|
24
|
+
| 目标节点 | 必须已有的上游工件 | 缺失时动作 |
|
|
25
|
+
|---------|-----------------|-----------|
|
|
26
|
+
| open | 无 | 直接进入 |
|
|
27
|
+
| design | CHANGE.md + REQUIREMENT.md | 回 open 补齐 |
|
|
28
|
+
| plan | DESIGN.md(或 DESIGN-lite.md) | 回 design 补齐 |
|
|
29
|
+
| execute | TASK.md | 回 plan 补齐 |
|
|
30
|
+
| subagent-execute | TASK.md(含 parallel=true pending 任务) | 回 execute 串行执行 |
|
|
31
|
+
| review | 所有 task status="done" | 回 execute 补齐 |
|
|
32
|
+
| verify | REVIEW.md | 回 review 补齐 |
|
|
33
|
+
| archive | UAT.md | 回 verify 补齐 |
|
|
34
|
+
|
|
35
|
+
**Step 2:读取下一个节点**
|
|
36
|
+
|
|
37
|
+
运行 `node .claude/skills/flow-comet/scripts/workflow-state.mjs next`。若返回的 NODE 与 Step 0 产物检测不一致,以产物为准。
|
|
38
|
+
|
|
39
|
+
### Resume 规则
|
|
40
|
+
|
|
41
|
+
- 每次上下文恢复,重新执行 Step 0 和 Step 2。不信任对话历史。
|
|
42
|
+
- 产物文件(`.specs/<id>/`)是唯一真相源。脚本状态只是加速器。
|
|
43
|
+
- 若状态显示某 Node 已完成但预期 artifact 缺失,视为未完成并重新进入。
|
|
44
|
+
- 若用户在某个 Node 中途恢复但话题变了,确认是继续当前 Node 还是开始新的。
|
|
45
|
+
|
|
46
|
+
### 决策分类与决策点
|
|
47
|
+
|
|
48
|
+
先分类再行动:
|
|
49
|
+
|
|
50
|
+
| 分类 | 定义 | 处理 |
|
|
51
|
+
|------|------|------|
|
|
52
|
+
| 用户决策 | ≥2 个会改变范围/行为/风险/不可逆结果的合法选项 | 用交互确认问(Claude Code 用 AskUserQuestion 优先;Codex 用文本提问+内联确认)或文本回退;相邻选择合并为一个问题,不重问已持久化选择 |
|
|
53
|
+
| 自动处理 | 唯一安全下一步 | 直接执行并汇报,不许制造确认 |
|
|
54
|
+
| 停止条件 | guard 失败 / 缺依赖 / 状态损坏 | 报告阻塞与恢复条件,无合法动作时才升级为用户决策 |
|
|
55
|
+
| 手动交接 | `NEXT: manual`(若有) | 不是用户决策,直接继续 |
|
|
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 失败时先自动诊断并执行唯一安全修复;缺依赖或状态损坏导致无法继续时报告停止条件与恢复条件;只有恢复方式存在多个会改变范围或风险的合法选项时,才升级为用户决策
|
|
61
|
+
|
|
62
|
+
### Red Flags
|
|
63
|
+
|
|
64
|
+
| Agent 想法 | 实际风险 |
|
|
65
|
+
|-----------|---------|
|
|
66
|
+
| "这是小改动,不用走完整流程" | 可走最短路径但不能跳过阶段门禁 |
|
|
67
|
+
| "REQUIREMENT 可以跳过,直接写代码" | R2.2:没有 REQUIREMENT 不能进 DESIGN |
|
|
68
|
+
| "verify 通过了所以可以归档" | 还要检查 REVIEW.md 的 Critical 项是否全部处理 |
|
|
69
|
+
| "上下文恢复后从上次对话继续" | 始终重新读取状态和产物文件,对话记忆不可靠 |
|
|
70
|
+
| "LESSONS.md 不用扫" | R1.8:每个 DEV 任务必须扫描 |
|
|
71
|
+
| "测试从实现派生就行" | R5.1:测试必须从 AC 派生 |
|
|
72
|
+
| "guard 失败了,让用户决定" | 先自动诊断并执行唯一安全修复;无合法动作时才报告停止条件 |
|
|
73
|
+
| "跳过 entry 直接 exit,反正没检查" | 新 change 未 entry 直接 exit → BLOCKED(进入检查不可跳过);旧 change WARN 渐进 |
|
|
74
|
+
| "SUMMARY 不写,任务先标 done" | 新 change done 任务缺 SUMMARY → BLOCKED(产物完整性强制);旧 change WARN 渐进 |
|
|
75
|
+
| "subagent-execute 阶段,我直接改源码更快" | 协调者禁令:subagent-execute 阶段主会话禁止写源码(hook 白名单只允许 .specs/,Write/Edit 与 Bash 写命令均物理拦截),必须 worktree 委托子代理 |
|
|
76
|
+
|
|
77
|
+
## Workflow Nodes
|
|
78
|
+
|
|
79
|
+
| 节点 | Kind | 职责 | Output Schema |
|
|
80
|
+
|------|------|------|---------------|
|
|
81
|
+
| open | control | CHANGE 反问 + REQUIREMENT 需求 | flowkit.intake.v1 |
|
|
82
|
+
| design | control | 技术决策 + ADR | flowkit.design.v1 |
|
|
83
|
+
| plan | control | 拆原子任务 | flowkit.plan.v1 |
|
|
84
|
+
| execute | control | TDD 开发 + 自查(串行) | flowkit.execution.v1 |
|
|
85
|
+
| subagent-execute | handoff | [P] 并行任务委托 | flowkit.handoff.v1 |
|
|
86
|
+
| review | control | 4 轮审查 | flowkit.review.v1 |
|
|
87
|
+
| verify | control | 集成验证 + UAT | flowkit.verify.v1 |
|
|
88
|
+
| archive | control | 归档 + LESSONS | flowkit.archive.v1 |
|
|
89
|
+
|
|
90
|
+
> **并行任务路由(节点顺序是动态的 · 多趟语义)**:TASK 含依赖已满足的 `parallel="true" status="pending"` 任务时路由到 subagent-execute——每趟委托全部依赖已满足的并行任务;子代理返回后重新判定:仍有可并行 pending 就再次进入 subagent-execute(委托节点可多次往返),存在串行 pending 时回 execute 消化一趟再循环。委托节点的完成 = 不存在依赖已满足的可并行 pending 且无串行残留;并行/串行交错的混排序列合法,唯一前置拦截是依赖环(plan 出口校验并附恢复指引)。全部为串行任务时走 execute,行为不变。`next` 的输出始终是权威——以 `NODE:` 输出为准,不按静态顺序推断。
|
|
91
|
+
|
|
92
|
+
## Skill Bindings
|
|
93
|
+
|
|
94
|
+
| 节点 | Implementation | Required Calls | Enforcement |
|
|
95
|
+
|------|---------------|----------------|-------------|
|
|
96
|
+
| 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 |
|
|
98
|
+
| plan | flow-comet-plan | flow-comet-task | guarded |
|
|
99
|
+
| execute | flow-comet-execute | flow-comet-dev | guarded |
|
|
100
|
+
| subagent-execute | flow-comet-subagent-execute | flow-comet-dev (handoff) | handoff-guarded |
|
|
101
|
+
| review | flow-comet-review | flow-comet-review, flow-comet-test | guarded |
|
|
102
|
+
| verify | flow-comet-verify | flow-comet-integration | guarded |
|
|
103
|
+
| archive | flow-comet-archive | flow-comet-integration | guarded |
|
|
104
|
+
|
|
105
|
+
**新 change 严格模式**:`init` 创建的 change 标记为"新"(`newChange: true`)——新 change 下全部内容级检查强制 BLOCKED(处置标记/缓存证据/波次散文/越权委托/SUMMARY 完整性/进入证据等);旧 change(历史遗留,无标记)保持渐进 WARN。执行者可通过 `status` 确认当前 change 的新旧。
|
|
106
|
+
|
|
107
|
+
**节点技能两层加载模型(入口层 · 双步硬规则)**:路由到节点后,以下两步**都不可跳过**:
|
|
108
|
+
|
|
109
|
+
1. **用 Skill 工具加载该节点的 Implementation 技能**(见下方 Skill Bindings 表 Implementation 列,如 execute → flow-comet-execute)。**不得跳过**——只读取 SKILL.md 文件不叫加载;真正让该 skill 的指令生效的是 Skill 工具把它注入本次会话。
|
|
110
|
+
2. 随后按该节点 SKILL 的 Required Skill Calls,用 Skill 工具加载协议技能(与 Implementation 同名的条目已随路由加载,无需重复加载),加载完成后**立即**逐条运行声明命令(open/review 等涉及多个协议文件的节点,每个协议文件对应一条声明命令):
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load <node> <skill> --prompt flow-kit/prompts/<阶段>.md
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
> **跑声明命令 ≠ 加载**:声明只把“哪次会话加载了哪个 skill、按哪份协议工作”写进状态供 exit/record 核对;真正加载只有第 1 步的 Skill 工具能做到。协议的引用示例:execute / subagent-execute 节点加载 flow-comet-dev 时用 `--prompt flow-kit/prompts/4-dev.md`(DEV 阶段协议),交付物按 `flow-kit/templates/SUMMARY.md` 模板填写并补写 `## 自检方法` 段。
|
|
117
|
+
|
|
118
|
+
节点退出(exit)与证据记录(record)会核对声明标记。声明如实记录执行者动作——加载了哪个 skill、按哪份协议工作——**不等于产出证明**;产出是否正确由产物结构校验与门禁把关。**技能加载前置门**:新 change 的 required 条目不再自动补写——handoff request / record 前必须已有本节点声明标记(先加载、再声明、后干活);声明标记自动补写仅对旧 change 兜底(按协议 requiredSkillCalls 代记,标记带 `auto: true`),手动声明仍推荐(如实记录加载动作与协议文件)。
|
|
119
|
+
|
|
120
|
+
## Guardrails And Evidence
|
|
121
|
+
|
|
122
|
+
| 节点 | Guardrail | Validation | Description |
|
|
123
|
+
|------|-----------|-----------|-------------|
|
|
124
|
+
| open | intake-artifacts | artifact-exists | CHANGE.md + REQUIREMENT.md exist |
|
|
125
|
+
| design | design-artifacts | artifact-exists | DESIGN.md exists |
|
|
126
|
+
| plan | plan-artifacts | artifact-exists | TASK.md exists |
|
|
127
|
+
| execute | build-evidence | artifact-exists | At least one SUMMARY.md |
|
|
128
|
+
| subagent-execute | handoff-evidence | evidence-only | Handoff evidence recorded |
|
|
129
|
+
| review | review-evidence | artifact-exists | REVIEW.md exists |
|
|
130
|
+
| verify | verify-evidence | artifact-exists | TEST.md + UAT.md exist |
|
|
131
|
+
| archive | archive-evidence | state-transition | Archive completed |
|
|
132
|
+
|
|
133
|
+
## Runtime And Recovery
|
|
134
|
+
|
|
135
|
+
### Startup Protocol
|
|
136
|
+
|
|
137
|
+
1. Run `node .claude/skills/flow-comet/scripts/workflow-state.mjs status` to detect active change and current node.
|
|
138
|
+
2. If no active change and user wants to start new work: `node .claude/skills/flow-comet/scripts/workflow-state.mjs init <change-name>`. **init 自动检测项目上下文**:需要初始化时输出提示(同意重跑 `init <id> --init-context` 全量生成 CONTEXT.md / 拒绝 `--init-skip`);CONTEXT.md 已存在且新鲜时完全静默——详见 `reference/init-detection.md`。项目本地分支规范非默认前缀时可用 `init <id> --branch-prefix <prefix>` 对齐(详见安装文档分支命名小节)。
|
|
139
|
+
3. **首次路由**: `init` 输出即首次路由(NODE: 内置 open 或协议首节点)——直接加载该节点 Skill 并执行(产出工件),一次只加载一个 Skill。`next` 在节点完成(`guard exit <node> --apply` 推进)后用于获取下一节点;init 后立即 `next` 会命中节点顺序门禁(open 未 exit → BLOCKED,符合节点顺序门禁语义)。
|
|
140
|
+
|
|
141
|
+
### Resume Rules (every context resume)
|
|
142
|
+
|
|
143
|
+
- **Re-detect from scratch**: on every context resume, re-run Startup Protocol. Do not trust conversation history.
|
|
144
|
+
- **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.
|
|
145
|
+
- **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.
|
|
146
|
+
|
|
147
|
+
### Node Boundary Rules
|
|
148
|
+
|
|
149
|
+
- **节点顺序**:每个节点按 `entry <node>` → 产出工件 → `record <node>` → `exit <node> --apply` 执行(record 必须先于 exit——exit 校验 evidence 前置,缺证据会 BLOCKED)。
|
|
150
|
+
- 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 的进入检查(协调者禁令/委托前检查/签名记录)不可跳过。
|
|
151
|
+
- If the guard fails, do not proceed past it — 先自动诊断并执行唯一安全修复(与 Decision Core 停止条件一致);存在多个会改变范围/风险的合法恢复动作时,展示 guard 输出并询问用户。
|
|
152
|
+
- If the user wants to redo a completed Node, reset its completion state and re-enter rather than creating a parallel path.
|
|
153
|
+
|
|
154
|
+
### Evidence Recording
|
|
155
|
+
|
|
156
|
+
After completing a Node:
|
|
157
|
+
```bash
|
|
158
|
+
node .claude/skills/flow-comet/scripts/workflow-state.mjs record <node-id> '{"summary":"完成摘要"}'
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
### Artifact Paths
|
|
162
|
+
|
|
163
|
+
All artifacts in `.specs/<change-id>/`. Cross-change files in `.specs/` (CONTEXT.md, LESSONS.md, CHANGELOG.md).
|
|
164
|
+
|
|
165
|
+
### Scripts
|
|
166
|
+
|
|
167
|
+
> **命令路径的平台化**:本文件命令统一为**权威源设计形态** `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 请用安装器。
|
|
168
|
+
|
|
169
|
+
| 脚本 | 用途 |
|
|
170
|
+
|------|------|
|
|
171
|
+
| `workflow-state.mjs` | 状态管理:init/status/next/select/record/advance/skill-load/execution-mode/config/verify-fail(verify 失败计数,第 4 次 BLOCKED) |
|
|
172
|
+
| `workflow-guard.mjs` | 节点门禁:entry/exit/verify 检查 |
|
|
173
|
+
| `workflow-handoff.mjs` | 子代理交接:request/result/status |
|
|
174
|
+
| `comet-plan.mjs` | 兼容别名入口(内容为 workflow-state 的别名壳) |
|
|
175
|
+
| `comet-check.mjs` | workflow contract 检查 |
|
|
176
|
+
| `comet-hook-guard.mjs` | 文件写入边界守卫(phase 白名单:subagent-execute 阶段只允许 .specs/;隔离委托的工作区 `.claude/worktrees/**` 放行——`Write`/`Edit` 与 `Bash` 写命令两条判定路径同语义) |
|
|
177
|
+
|
|
178
|
+
### 机器拥有字段
|
|
179
|
+
|
|
180
|
+
以下字段只能由 `workflow-state.mjs` 和 `workflow-guard.mjs` 脚本管理,不应被手动编辑:
|
|
181
|
+
|
|
182
|
+
| 字段 | 说明 | 管理者 |
|
|
183
|
+
|------|------|--------|
|
|
184
|
+
| `currentNode` | 当前活动节点 | workflow-state.mjs next/advance |
|
|
185
|
+
| `completedNodes` | 已完成节点列表 | workflow-guard.mjs exit --apply |
|
|
186
|
+
| `evidence` | 节点证据记录 | workflow-state.mjs record |
|
|
187
|
+
| `verifyFailures` | verify 失败计数 | workflow-guard.mjs (auto-increment) |
|
|
188
|
+
| `verifyFailuresByChange` | 按 change 隔离的失败计数(keyed by change-id) | workflow-state.mjs / state-schema.mjs helper |
|
|
189
|
+
| `status` | 运行状态 | workflow-guard.mjs exit --apply |
|
|
190
|
+
| `executionMode` | subagent/direct,execute 执行模式 | workflow-state.mjs execution-mode |
|
|
191
|
+
| `directOverride` | direct 是否用户显式确认 | workflow-state.mjs execution-mode direct |
|
|
192
|
+
|
|
193
|
+
手动修改这些字段可能导致 guard 校验不一致。若需修正状态,使用 `workflow-state.mjs advance` 或 `workflow-state.mjs select`。
|
|
194
|
+
|
|
195
|
+
The route, Output Schemas, required Skill calls, and recovery state are defined by `reference/workflow-protocol.json`.
|
|
196
|
+
- Resolved source Skill evidence and composition provenance: `reference/resolved-skills.json`.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# KNOWN-ISSUES(归档遗留清单模板)
|
|
2
|
+
|
|
3
|
+
> 用途:归档节点使用——REVIEW.md 发现区标记为 `[转待办]` 的 Minor 发现 + 已知限制 → 归档时生成 KNOWN-ISSUES.md 置于 `.specs/archive/<日期>-<change-id>/` 下(归档输出 Schema 的必选产物;无遗留也显式写「无遗留问题」)。
|
|
4
|
+
> 用法:按实际 change 修订本模板;「遗留清单」节记录本 change 结束后仍需跟进的事项,每项标注跟进动作与责任批次。
|
|
5
|
+
> 纪律:本模板为分发产物——零过程代号;归档实例(.specs/archive/ 下)不受此限。
|
|
6
|
+
|
|
7
|
+
## 遗留清单
|
|
8
|
+
|
|
9
|
+
- **版本基线**:版本 1.4.2 + 144 场景数 + 系统测试 60 项(发布已对齐;后续发布按版本纪律同步全库变体)
|
|
10
|
+
- **初始化检测相关文档既有过程用语**:`reference/init-detection.md` 等含历史过程用语(历史遗留,由人工清单跟进;清理后删除本条目)
|
|
11
|
+
- **待复查观察项**:验证过程中记录,未达修复优先级——后续迭代按需复查
|
|
12
|
+
- **本地文档健康检查工具版本映射**:本地检查工具的版本/场景数一致性子检查用发布时快照,开发窗口期(版本未发布、场景数已增)会误报——由系统测试集的结构检查放行逻辑覆盖,权威判定在引擎自测
|
|
13
|
+
- **design 节点 required 自指核验结论**:设计如此,无需修复——详见 `reference/TEST-MATRIX.md` 附节(三模式对照与理由)
|
|
14
|
+
|
|
15
|
+
## 使用说明
|
|
16
|
+
|
|
17
|
+
- **归档时**:把 REVIEW.md 发现区 `[转待办]` 的 Minor 条目与已知限制汇总为本清单;无遗留则写「无遗留问题」(KNOWN-ISSUES.md 为归档输出 Schema 必选产物,guard 校验存在性)
|
|
18
|
+
- **跟进**:下一 change 或维护批次按清单逐项处置,处置后移除条目并注明处置结果
|
|
19
|
+
- **验证**:归档流程的完整链路(遗留清单 + 目录移动 + 完成态)由系统测试集 H 面覆盖
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# flow-comet 系统测试矩阵(TEST-MATRIX)
|
|
2
|
+
|
|
3
|
+
> 定位:系统测试集(`system-test.mjs`)的设计文档——说明测试覆盖的机制面、测试载体与判定规则。
|
|
4
|
+
> 运行:`node .flow-comet/skills/flow-comet/scripts/system-test.mjs`(权威源直接跑;安装副本路径同理)。
|
|
5
|
+
|
|
6
|
+
## 一、测试载体说明
|
|
7
|
+
|
|
8
|
+
- **载体**:每个测试项 = 一个独立临时目录(`fs.mkdtemp`)+ 内置协议副本复制到 `<tmp>/reference/`(受保护路径要求协议文件位于 runRoot 内)+ **真实命令序列**(`init → record → guard entry/exit → handoff → hook` 的 `spawnSync` 调用)+ 断言退出码与输出关键词;测试项跑完 `rmSync` 清理。
|
|
9
|
+
- **与引擎回归的关系**:`guard-self-test.mjs` 是引擎脚本的单元/场景级回归(fixture 构造为主,**场景数以套件自身输出为准**);本系统测试集是**系统级**(**A~L 共十二组,项数以套件自身输出为准**)——每个测试项走真实命令链路,验证机制在真实调用序列下生效(行为锚定归场景回归,集成正确性归系统测试)。
|
|
10
|
+
|
|
11
|
+
> **本文件刻意不记录具体计数**:计数随场景/测试项增减而变化,而本文件不在计数一致性自检的覆盖范围内——写死数字会静默过期(本项目已因此复发多次)。以两套件的实际输出为准(`ALL n SCENARIOS PASSED` 与系统测试的汇总行)。
|
|
12
|
+
- **运行环境**:仅 node 内置模块(child_process/fs/os/path),无网络、无第三方依赖。
|
|
13
|
+
- **输出纪律**:逐项 PASS/FAIL + 汇总(`SYSTEM TEST: N/M passed`);全过 exit 0,有 FAIL exit 1。测试项命名为公开面——零过程代号。
|
|
14
|
+
|
|
15
|
+
## 二、判定规则
|
|
16
|
+
|
|
17
|
+
- **全部 PASS = 级 2(系统测试集)完整通过**:与级 1 引擎回归(guard-self-test 全绿)构成统一测试集两级基线,方可进入下一级验证(CLI 冒烟)。
|
|
18
|
+
- **任一 FAIL**:修复后重跑(修复只改权威源一处,重跑至全绿)。
|
|
19
|
+
- **误通过 = 测试无效,必须修**:该拦截未拦截 / 该放行未放行,说明测试自身没守住机制边界——测试先于功能守边界,不许自欺("当时能过"不等于"现在正确")。
|
|
20
|
+
|
|
21
|
+
## 三、机制面覆盖矩阵(A~L 十二类)
|
|
22
|
+
|
|
23
|
+
### A. 状态机与路由
|
|
24
|
+
|
|
25
|
+
覆盖:init 全分支(状态写入/工件目录/同 id 重跑防护/分支模式)、status 节点推导与无活跃兜底、next 推进与状态漂移校正、next 未出口节点严格拦截、select 切换、advance 推进、record 基础证据、execution-mode 切换与记录、config 设置与非法值拒绝、多趟路由真实链路(并→串→交替与多波依赖)、plan 出口依赖环负例与恢复、多趟路由时序收敛、plan 出口文件依赖检出。
|
|
26
|
+
|
|
27
|
+
测试项(20):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 / 协调者授权通过)。
|
|
28
|
+
|
|
29
|
+
### B. 声明机制
|
|
30
|
+
|
|
31
|
+
覆盖:skill-load 声明标记写入(协议归属)、非法参数拒绝不落标记、record 缺声明标记拦截、声明后记录通过、声明时间序自洽、损坏声明标记 fail-closed、委托范围条目豁免(有委托通过/无委托拦截)、exit 协议声明标记校验(真实链路通过/无标记·空协议·损坏拦截)、旧项目兼容(未激活声明机制照常通过)。
|
|
32
|
+
|
|
33
|
+
测试项(9):B1 声明标记写入 / B2 非法参数拒绝 / B3 缺声明标记拦截 / B4 声明后记录通过 / B5 声明时间序自洽 / B6 损坏标记 fail-closed / B7 委托范围条目豁免 / B8 exit 协议声明标记校验 / B9 旧项目兼容。
|
|
34
|
+
|
|
35
|
+
### C. 委托链路
|
|
36
|
+
|
|
37
|
+
覆盖:handoff 请求/结果/状态全链路(含提交校验)、红绿证据时间序(先红后绿通过/补录拦截)、委托后 exit 证据键名契约与契约校验(通过/空交接拦截)。
|
|
38
|
+
|
|
39
|
+
测试项(3):C1 handoff 全链路 / C2 红绿证据时间序 / C3 委托后 exit 契约校验。
|
|
40
|
+
|
|
41
|
+
### D. hook 写白名单
|
|
42
|
+
|
|
43
|
+
覆盖:open 阶段工件放行与源码拦截、execute 按执行模式收窄(subagent 只写 .specs/,direct 放宽)、归档阶段白名单与完成态放行。
|
|
44
|
+
|
|
45
|
+
测试项(3):D1 open 阶段白名单 / D2 execute 执行模式收窄 / D3 归档阶段白名单与完成态放行。
|
|
46
|
+
|
|
47
|
+
### E. 自定义协议
|
|
48
|
+
|
|
49
|
+
覆盖:自定义协议加载路由与节点推导(`--protocol`/env 加载)、自定义节点声明机制与出口全链路(含技能绑定)、内置特化校验对自定义协议不误触发。
|
|
50
|
+
|
|
51
|
+
测试项(2):E1 加载路由与节点推导 / E2 声明机制与出口全链路。
|
|
52
|
+
|
|
53
|
+
### F. 自动初始化
|
|
54
|
+
|
|
55
|
+
覆盖:上下文缺失提示且不自动生成、跳过记忆、新鲜上下文静默、生成协作全链路(7 段校验 + 扫描时间记录)。
|
|
56
|
+
|
|
57
|
+
测试项(4):F1 上下文缺失提示 / F2 跳过记忆 / F3 新鲜上下文静默 / F4 生成协作全链路。
|
|
58
|
+
|
|
59
|
+
### G. 分支模式
|
|
60
|
+
|
|
61
|
+
覆盖:init 建分支与一致性、归档入口分支校验、分支一致性失配警告。
|
|
62
|
+
|
|
63
|
+
测试项(3):G1 init 建分支与一致性 / G2 归档入口分支校验 / G3 一致性失配警告。
|
|
64
|
+
|
|
65
|
+
### H. verify 与归档
|
|
66
|
+
|
|
67
|
+
覆盖:验证命令真实执行与超时配置、归档完整流程(遗留清单 + 目录移动 + 完成态)、归档路径声明标记查找(先移目录后 exit 顺序下标记只存归档路径)。
|
|
68
|
+
|
|
69
|
+
测试项(4):H1 验证命令真实执行与超时 / H2 归档完整流程 / H3 归档路径声明标记查找 / H4 归档后自动补声明标记写归档路径(不重建活动目录)。
|
|
70
|
+
|
|
71
|
+
### I. 异常路径
|
|
72
|
+
|
|
73
|
+
覆盖:损坏状态文件 fail-closed、缺工件出口拦截、非法参数拒绝、状态字段类型非法拦截。
|
|
74
|
+
|
|
75
|
+
测试项(4):I1 损坏状态文件 fail-closed / I2 缺工件出口拦截 / I3 非法参数拒绝 / I4 状态字段类型非法拦截。
|
|
76
|
+
|
|
77
|
+
### J. 文档一致性
|
|
78
|
+
|
|
79
|
+
覆盖:双语健康检查(英文文档零中文/中文文档零英文长句/双语镜像对称/版本场景数)、公开产物零代号检查(调用仓库本地工具;安装副本无仓库文档跳过)。注:本地工具为发布快照——开发窗口期场景数一致性子检查按结构检查放行,权威判定在引擎自测。
|
|
80
|
+
|
|
81
|
+
测试项(2):J1 双语健康检查 / J2 公开产物零代号检查。
|
|
82
|
+
|
|
83
|
+
### K. 安装器(版本标识 + 多平台)
|
|
84
|
+
|
|
85
|
+
覆盖: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 纯函数与流程态门/版本戳重装断言)。
|
|
86
|
+
|
|
87
|
+
测试项(16):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 版本戳重装断言(升级/降级方向与覆盖后新戳)/ K15 桥接 loader 同源重装断言(首次安装后版本一致)/ K16 桥接 loader purge 后重建路径回归(loader 恢复与再装收敛)。
|
|
88
|
+
|
|
89
|
+
### L. 执行遗漏防护(真实链路)
|
|
90
|
+
|
|
91
|
+
覆盖:进入证据(entry 记录 enteredNodes、正常流程 exit 无误报——真实链路中节点顺序检查先于进入警告,未 entry 场景由引擎回归覆盖)、空退出豁免(显式 emptyExitApproved 通过 / 无豁免仍拦截)、空仓库提示(init 在无提交仓库输出 EMPTY-REPO)。
|
|
92
|
+
|
|
93
|
+
测试项(3):L1 进入证据 / L2 空退出豁免 / L3 空仓库。
|
|
94
|
+
|
|
95
|
+
## 四、附:design 节点 required 自指核验结论
|
|
96
|
+
|
|
97
|
+
**核验对象**:`workflow-protocol.json` 的 design 节点——`requiredSkillCalls` 含与 `implementation` 相同的技能(自指),对照 open / review 两模式核验(遗留核验项)。
|
|
98
|
+
|
|
99
|
+
**三模式对照**:
|
|
100
|
+
|
|
101
|
+
| 节点 | implementation | requiredSkillCalls | 含自身? |
|
|
102
|
+
|---|---|---|---|
|
|
103
|
+
| open | flow-comet-open | flow-comet-change, flow-comet-requirement | 否 |
|
|
104
|
+
| design | flow-comet-design | flow-comet-design, flow-comet-ui-design | 是 |
|
|
105
|
+
| review | flow-comet-review | flow-comet-review, flow-comet-test | 是 |
|
|
106
|
+
|
|
107
|
+
**结论:设计如此,非缺陷。** 理由:
|
|
108
|
+
|
|
109
|
+
1. **协议承载型入口 vs 纯壳编排**:design 与 review 的入口技能即协议本体(flow-comet-design 承载 DESIGN 阶段协议,flow-comet-review 承载 REVIEW 阶段协议),其 `required` 列表 = 执行者必须加载并声明的协议技能集合,含自身是「入口即协议承载」的自然形态。open 是纯壳编排者(flow-comet-open 自身无协议文件,协议由 flow-comet-change / flow-comet-requirement 两个独立技能承载),故 required 不含自身——open 若含自身反而无法声明(没有对应协议文件可声明)。
|
|
110
|
+
2. **required 自条目是加载声明的载体**:执行者加载 flow-comet-design 后运行 `skill-load design flow-comet-design --prompt flow-kit/prompts/2-design.md` 写入声明标记——该标记同时满足记录校验(required-skill 条目须有对应标记)与节点 exit 的协议声明校验(design 节点要求 2-design.md 标记),两处复用同一文件,机械上自洽。
|
|
111
|
+
3. **review 同构佐证**:review 的 required(flow-comet-review + flow-comet-test)与其节点协议文件集(6-review.md + 5-test.md)一一对应——两个节点同构,是设计而非偶发。
|
|
112
|
+
4. **与 plan 节点修正不同类**:plan 节点那次修正的缺陷在 `implementation` 字段指向错误(指向协议技能而非节点入口技能),修正后确立「implementation = 节点入口、required = 需加载声明的协议技能」语义——design 的 implementation 指向正确,required 含自身不违反该语义。
|
|
113
|
+
5. **机械上无害**:required 条目在节点 exit 时自动补全,不产生额外拦截;删除反而破坏上述声明载体对应关系。
|
|
114
|
+
|
|
115
|
+
**边界**:若未来把 design 重构为「壳 + 独立协议技能」双层结构(同 open),required 自条目随结构自然去除;当前形态保持,无需修复。
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schemaVersion": 1,
|
|
3
|
+
"protocolHash": "438bc3acfe5ae51b4a2ddacc3426649b124b4bfa3141ba1b1cee9087e2f6b893",
|
|
4
|
+
"lanes": [
|
|
5
|
+
{
|
|
6
|
+
"lane": "script"
|
|
7
|
+
},
|
|
8
|
+
{
|
|
9
|
+
"lane": "reference"
|
|
10
|
+
},
|
|
11
|
+
{
|
|
12
|
+
"lane": "pause-points"
|
|
13
|
+
},
|
|
14
|
+
{
|
|
15
|
+
"lane": "workflow-entry"
|
|
16
|
+
},
|
|
17
|
+
{
|
|
18
|
+
"lane": "skill-core"
|
|
19
|
+
},
|
|
20
|
+
{
|
|
21
|
+
"lane": "skill-review"
|
|
22
|
+
}
|
|
23
|
+
],
|
|
24
|
+
"review": {
|
|
25
|
+
"passed": true,
|
|
26
|
+
"evidenceSource": "llm-single",
|
|
27
|
+
"voters": null,
|
|
28
|
+
"lenses": [],
|
|
29
|
+
"rounds": null,
|
|
30
|
+
"blockingFindings": [],
|
|
31
|
+
"warnings": []
|
|
32
|
+
}
|
|
33
|
+
}
|