kld-sdd 2.6.12 → 2.6.13
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/README.md +20 -0
- package/kld-sdd-guide.html +429 -159
- package/lib/init.js +40 -7
- package/package.json +5 -2
- package/skywalk-sdd/index.cjs +2668 -415
- package/skywalk-sdd/metrics-v3.cjs +1153 -0
- package/skywalk-sdd/ontology/archive-package.cjs +114 -3
- package/skywalk-sdd/ontology/resolve-spec-root.cjs +20 -80
- package/skywalk-sdd/ontology/working-artifacts.cjs +2 -1
- package/templates/hooks/claude/hooks/sdd-apply-test-gate.cjs +39 -9
- package/templates/hooks/claude/hooks/sdd-post-tool.cjs +87 -8
- package/templates/hooks/claude/hooks/sdd-prompt.cjs +3 -1
- package/templates/hooks/codebuddy/hooks/sdd-apply-test-gate.cjs +39 -9
- package/templates/hooks/codebuddy/hooks/sdd-post-tool.cjs +87 -9
- package/templates/hooks/codebuddy/hooks/sdd-prompt.cjs +3 -1
- package/templates/skills/kld-sdd/opsx-apply/SKILL.md +14 -13
- package/templates/skills/kld-sdd/opsx-apply/checklist.md +20 -20
- package/templates/skills/kld-sdd/opsx-apply/implementer-prompt.md +12 -12
- package/templates/skills/kld-sdd/opsx-apply/reference.md +32 -31
- package/templates/skills/kld-sdd/opsx-archive/SKILL.md +44 -6
- package/templates/skills/kld-sdd/opsx-archive/checklist.md +4 -1
- package/templates/skills/kld-sdd/opsx-check/SKILL.md +19 -11
- package/templates/skills/kld-sdd/opsx-check/checklist.md +7 -6
- package/templates/skills/kld-sdd/opsx-design/SKILL.md +1 -1
- package/templates/skills/kld-sdd/opsx-design/checklist.md +1 -1
- package/templates/skills/kld-sdd/opsx-propose/SKILL.md +9 -1
- package/templates/skills/kld-sdd/opsx-propose/reference.md +29 -3
- package/templates/skills/kld-sdd/opsx-rules/reference.md +3 -1
- package/templates/skills/kld-sdd/opsx-spec/SKILL.md +1 -1
- package/templates/skills/kld-sdd/opsx-spec/checklist.md +1 -1
- package/templates/skills/kld-sdd/opsx-task/SKILL.md +10 -10
- package/templates/skills/kld-sdd/opsx-task/checklist.md +3 -3
- package/templates/skills/kld-sdd/opsx-task/reference.md +3 -3
- package/templates/skills/kld-sdd/opsx-test/SKILL.md +7 -5
- package/templates/skills/kld-sdd/{opsx-tdd-anti-patterns → tdd-anti-patterns}/SKILL.md +4 -4
- package/templates/skills/kld-sdd/{opsx-tdd-anti-patterns → tdd-anti-patterns}/reference.md +4 -4
- package/templates/skills/kld-sdd/{opsx-tdd-core → tdd-core}/SKILL.md +13 -13
- package/templates/skills/kld-sdd/{opsx-tdd-core → tdd-core}/checklist.md +5 -5
- package/templates/skills/kld-sdd/{opsx-tdd-core → tdd-core}/reference.md +12 -12
- package/templates/skills/kld-sdd/{opsx-tdd-metrics → tdd-metrics}/SKILL.md +3 -3
- package/templates/skills/kld-sdd/{opsx-tdd-metrics → tdd-metrics}/checklist.md +2 -2
- package/templates/skills/kld-sdd/{opsx-tdd-quality → tdd-quality}/SKILL.md +2 -2
- package/templates/skills/kld-sdd/{opsx-tdd-quality → tdd-quality}/rules/general/parameterized-testing.md +1 -1
- package/templates/skills/kld-sdd/{opsx-tdd-review → tdd-review}/SKILL.md +5 -5
- package/templates/skills/kld-sdd/{opsx-tdd-review → tdd-review}/checklist.md +5 -5
- package/templates/skills/kld-sdd/{opsx-tdd-rules → tdd-rules}/SKILL.md +3 -3
- package/templates/skills/kld-sdd/{opsx-tdd-rules → tdd-rules}/rules/non-tdd-modules.md +1 -1
- package/templates/skills/kld-sdd/{opsx-tdd-rules → tdd-rules}/rules/refactor-checklist.md +1 -1
- package/templates/skills/kld-sdd/tdd-rules/rules/test-skeleton-telemetry.md +19 -0
- package/templates/skills/kld-sdd/opsx-tdd-rules/rules/test-skeleton-telemetry.md +0 -19
- /package/templates/skills/kld-sdd/{opsx-tdd-quality → tdd-quality}/rules/general/cause-effect-clarity.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-quality → tdd-quality}/rules/general/clean-test-data.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-quality → tdd-quality}/rules/general/existing-test-awareness.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-quality → tdd-quality}/rules/general/given-when-then.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-quality → tdd-quality}/rules/general/good-test-qualities.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-quality → tdd-quality}/rules/general/mock-boundary.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-quality → tdd-quality}/rules/general/naming-conventions.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-quality → tdd-quality}/rules/general/no-logic-in-tests.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-quality → tdd-quality}/rules/general/one-test-one-scenario.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-quality → tdd-quality}/rules/general/prefer-public-apis.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-quality → tdd-quality}/rules/general/test-behaviors-not-methods.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-quality → tdd-quality}/rules/java/argument-matching.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-quality → tdd-quality}/rules/java/controller-test-rules.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-quality → tdd-quality}/rules/java/domain-service-rules.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-quality → tdd-quality}/rules/java/java-test-template.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-quality → tdd-quality}/rules/java/json-serialization.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-quality → tdd-quality}/rules/java/logging-rules.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-quality → tdd-quality}/rules/post-generation/compilation-verification.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-quality → tdd-quality}/rules/post-generation/execution-verification.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-quality → tdd-quality}/rules/python/py-test-template.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-quality → tdd-quality}/rules/typescript/ts-test-template.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-rules → tdd-rules}/rules/controller-strategy.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-rules → tdd-rules}/rules/dag-generation-rules.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-rules → tdd-rules}/rules/des-step-annotation.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-rules → tdd-rules}/rules/exception-path-coverage.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-rules → tdd-rules}/rules/green-scope-declaration.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-rules → tdd-rules}/rules/green-yagni-fence.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-rules → tdd-rules}/rules/multi-validation-split.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-rules → tdd-rules}/rules/task-type-definitions.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-rules → tdd-rules}/rules/tdd-strategy-selection.md +0 -0
- /package/templates/skills/kld-sdd/{opsx-tdd-rules → tdd-rules}/rules/test-execution-gate.md +0 -0
|
@@ -40,7 +40,7 @@ allowed-tools:
|
|
|
40
40
|
> - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
|
|
41
41
|
> **📊 Telemetry(必做,不得跳过)**
|
|
42
42
|
> - 阶段开始:`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" start --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`(保存 event_id)
|
|
43
|
-
> - 检查报告生成后,必须先记录结构化检查结果:`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=check_result --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/partial/failure --summary="检查结果摘要" --details-json="{\"check_results\":{\"total\":0,\"errors\":0,\"warnings\":0,\"warning_items\":[],\"suggestions\":0,\"fixed_before_apply\":0,\"consistency_score\":null,\"categories\":{\"completeness\":{\"passed\":0,\"total\":0},\"consistency\":{\"passed\":0,\"total\":0},\"executability\":{\"passed\":0,\"total\":0},\"tdd_compliance\":{\"passed\":0,\"total\":0}},\"task_completion\":{\"completed\":0,\"incomplete\":0,\"total\":0,\"has_incomplete\":false,\"checked_for_archive_readiness\":false}}}"`
|
|
43
|
+
> - 检查报告生成后,必须先记录结构化检查结果:`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=check_result --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/partial/failure --summary="检查结果摘要" --details-json="{\"check_results\":{\"total\":0,\"errors\":0,\"warnings\":0,\"warning_items\":[],\"warning_dispositions\":[{\"warning\":\"<稳定编号>\",\"disposition\":\"fixed|accepted|waived|needs_input|open\",\"reason\":\"<处置依据>\"}],\"suggestions\":0,\"fixed_before_apply\":0,\"consistency_score\":null,\"reviewer\":\"<reviewer-identifier>\",\"review_session_id\":\"<当前check会话ID>\",\"author_session_id\":\"<文档作者/apply会话ID或unknown>\",\"reviewer_independence\":\"independent-review|self-review|unknown\",\"categories\":{\"completeness\":{\"passed\":0,\"total\":0},\"consistency\":{\"passed\":0,\"total\":0},\"executability\":{\"passed\":0,\"total\":0},\"tdd_compliance\":{\"passed\":0,\"total\":0}},\"task_completion\":{\"completed\":0,\"incomplete\":0,\"total\":0,\"has_incomplete\":false,\"checked_for_archive_readiness\":false}}}"`
|
|
44
44
|
> - `check_result` 记录成功后,才允许阶段结束:`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" end --event-id=<event_id> --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/partial/failure --summary="摘要"`
|
|
45
45
|
> - **【B1 摘要数字校验】** `stage_end --summary` 中的数字(如「N 个场景」「N 层 DAG」「N 个任务」)必须与 `spec.md`/`tasks.md`/`test-scenarios.md` 的实统计交叉校验一致后再填写,不得凭记忆自填。典型失真:summary 写「11 个场景」实际 spec 含 13 条断言、「5 层 DAG」实际 tasks 修复后为 6 层。check 阶段发现不一致时,修正 summary 或补齐文档,使三者数字自洽。
|
|
46
46
|
|
|
@@ -171,7 +171,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" diagnose-naming --proj
|
|
|
171
171
|
- [ ] 跨文档引用路径正确
|
|
172
172
|
- [ ] ⛔ **CON 覆盖一致性**:spec.md 中每个 CON 在 tasks.md 中有对应验证任务或显式声明间接覆盖;tasks.md 声明"100% 覆盖 CON"时必须可追溯
|
|
173
173
|
- [ ] ⛔ **安全/审计要求覆盖一致性**:spec.md §5.x 中的安全与审计要求在 tasks.md 中有对应任务或显式声明推迟
|
|
174
|
-
- [ ] ⛔ **AC 变体覆盖一致性**:spec.md 中含"或"条件的 AC 场景,其 RED 任务验收标准须列出所有变体的测试方法(规则见 `
|
|
174
|
+
- [ ] ⛔ **AC 变体覆盖一致性**:spec.md 中含"或"条件的 AC 场景,其 RED 任务验收标准须列出所有变体的测试方法(规则见 `tdd-rules/rules/multi-validation-split.md` §AC 内"或"条件变体覆盖)
|
|
175
175
|
- [ ] ⛔ **tasks.md §4.x 验证方式表内部一致性**:§4.x 验证方式表中的测试注解/配置与任务实现步骤中的声明一致
|
|
176
176
|
|
|
177
177
|
#### 4.3 算法正确性检查
|
|
@@ -189,17 +189,17 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" diagnose-naming --proj
|
|
|
189
189
|
|
|
190
190
|
#### 4.4a TDD 合规性检查(仅 test-strategy=tdd 时执行)
|
|
191
191
|
|
|
192
|
-
⛔ 执行 `
|
|
192
|
+
⛔ 执行 `tdd-core/checklist.md` §B(15 项)逐项检查。
|
|
193
193
|
|
|
194
|
-
> 不在此内联复制,以
|
|
195
|
-
> 额外补充:还需检查 `
|
|
194
|
+
> 不在此内联复制,以 tdd-core/checklist.md §B 为唯一真相源。
|
|
195
|
+
> 额外补充:还需检查 `tdd-rules/rules/exception-path-coverage.md`(异常路径覆盖门禁)。
|
|
196
196
|
|
|
197
197
|
**检查项适用阶段**:§B 中部分检查项在 apply 前后均可验证(文档级),部分仅在 apply 后可验证(代码级):
|
|
198
198
|
- **apply 前可验证**(文档级):RED 验收标准包含"测试运行失败"、无"断言为空"、GREEN 为行为级粒度、DAG 存在 RED→GREEN 循环对、非 TDD 模块未拆红绿、GREEN 验收标准为"让对应 RED 通过"、已声明 Controller 策略、Controller 两种策略都生成测试任务、每个 RED 含测试方法名、每个 GREEN 含 YAGNI 围栏、每个 REFACTOR 列出重构点
|
|
199
199
|
- **apply 后可验证**(代码级):GREEN 任务输出不含未测试的 Controller/Filter/Config
|
|
200
200
|
|
|
201
201
|
⛔ BEFORE 完成 TDD 合规性检查,如需深度审查测试质量,必须读取:
|
|
202
|
-
-
|
|
202
|
+
- tdd-review/SKILL.md(测试质量审查清单 8 项 + 缺失测试检测)
|
|
203
203
|
读取后确认:"已读取测试质量审查清单"。
|
|
204
204
|
|
|
205
205
|
#### 4.5 任务完成状态检查(实现后 / 归档前)
|
|
@@ -244,16 +244,20 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" tasks-status --project=. --chan
|
|
|
244
244
|
- `warning_items`: 警告明细数组,每项 `{category, description, target}`(如 `{"category":"task_completion","description":"4.3 手动验证清单未勾选","target":"tasks.md:595"}`),用于报告已知风险区渲染具体待确认项;无明细时省略(向后兼容,旧事件仅 `warnings` 数量,报告降级显示数量)。
|
|
245
245
|
- `suggestions`: 可选优化建议数。
|
|
246
246
|
- `fixed_before_apply`: 进入 apply 前已通过或已确认满足质量门禁的检查项数。**【Q2 口径】**:apply 前第一次 check 全过则 = total(全部通过);apply 前有 check 但 fixed_before_apply=0 不触发 P4 警示(P4 主指标已改为"apply 前是否 check",与 fixed_before_apply 解耦)。
|
|
247
|
-
- `consistency_score`:
|
|
247
|
+
- `consistency_score`: **legacy 兼容字段**(保留一个发布版本);跨文档一致性评分 0-1,无法评分时填 `null`。
|
|
248
|
+
- `reviewer`: 执行本次 check 的代理或会话标识。
|
|
249
|
+
- `review_session_id`: 当前 check 会话 ID(与 `--session-id` 一致)。
|
|
250
|
+
- `author_session_id`: 文档作者或 apply 阶段会话 ID;无法确定时填 `unknown`。
|
|
251
|
+
- `reviewer_independence`: `independent-review`(独立 evaluator 且会话与作者不同)| `self-review` | `unknown`。优先使用独立 evaluator;不可用时继续检查但标 `self-review` 或 `unknown`,报告中 Q3 为 `provisional`。
|
|
248
252
|
- `categories`: 至少包含 `completeness`、`consistency`、`executability`。
|
|
249
253
|
- `task_completion`: 从 `tasks-status` 输出整理而来;未进入 apply 时 `checked_for_archive_readiness=false`。
|
|
250
254
|
|
|
251
255
|
在终端执行(必须成功):
|
|
252
256
|
```bash
|
|
253
|
-
node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=check_result --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/partial/failure --summary="检查结果摘要" --details-json="{\"check_results\":{\"total\":0,\"errors\":0,\"warnings\":0,\"warning_items\":[],\"suggestions\":0,\"fixed_before_apply\":0,\"consistency_score\":null,\"categories\":{\"completeness\":{\"passed\":0,\"total\":0},\"consistency\":{\"passed\":0,\"total\":0},\"executability\":{\"passed\":0,\"total\":0},\"tdd_compliance\":{\"passed\":0,\"total\":0}},\"task_completion\":{\"completed\":0,\"incomplete\":0,\"total\":0,\"has_incomplete\":false,\"checked_for_archive_readiness\":false}}}"
|
|
257
|
+
node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=check_result --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/partial/failure --summary="检查结果摘要" --details-json="{\"check_results\":{\"total\":0,\"errors\":0,\"warnings\":0,\"warning_items\":[],\"suggestions\":0,\"fixed_before_apply\":0,\"consistency_score\":null,\"reviewer\":\"<reviewer-identifier>\",\"review_session_id\":\"<当前check会话ID>\",\"author_session_id\":\"<文档作者/apply会话ID或unknown>\",\"reviewer_independence\":\"independent-review|self-review|unknown\",\"categories\":{\"completeness\":{\"passed\":0,\"total\":0},\"consistency\":{\"passed\":0,\"total\":0},\"executability\":{\"passed\":0,\"total\":0},\"tdd_compliance\":{\"passed\":0,\"total\":0}},\"task_completion\":{\"completed\":0,\"incomplete\":0,\"total\":0,\"has_incomplete\":false,\"checked_for_archive_readiness\":false}}}"
|
|
254
258
|
```
|
|
255
259
|
|
|
256
|
-
> **⚠️ P1-1 check_result details 不得为空**:`--details-json` 必须含 `
|
|
260
|
+
> **⚠️ P1-1 check_result details 不得为空**:`--details-json` 必须含 `categories` / `task_completion` / reviewer 独立性字段等,**禁止传空对象 `{}`**。空 details 导致 Q3 不可计算(工具侧虽有 state fallback 兜底,但事件 details 是主数据源)。
|
|
257
261
|
|
|
258
262
|
> **⚠️ P2-3 check 纳入 task_completion 判定**:执行 `tasks-status` 后,若 `has_incomplete=true`,`check_result` 的 `--result` 应标 `partial` 并在 `warning_items` 记录未勾选项(`{category:"task_completion", description:"N 项验收未勾选", target:"tasks.md:行号"}`)。不阻断 apply(P4 已与 fixRate 解耦),但反映真实完成度。
|
|
259
263
|
|
|
@@ -270,7 +274,11 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=conformance_revie
|
|
|
270
274
|
> - `assertions[].judge_status` 枚举:`matched` / `partial` / `missed`
|
|
271
275
|
> - `assertions[].human_status` 枚举:`matched` / `partial` / `missed` / 省略(默认跟随 judge_status)
|
|
272
276
|
|
|
273
|
-
> **reviewer 与 reviewer_independence
|
|
277
|
+
> **reviewer 与 reviewer_independence 说明(check_result)**:执行 check 前先读取文档作者/阶段会话信息;**能使用独立 evaluator 时必须使用**。`reviewer_independence=independent-review` 且 `review_session_id` 与 `author_session_id` 不同时,Q3 为 `verified`;自评或无法确认时为 `self-review` 或 `unknown`,Q3 标 `provisional` 但仍可计算分数。
|
|
278
|
+
|
|
279
|
+
> **报告用语**:`verified` 展示为“已验证”,表示有独立复核;`provisional` 展示为“临时”,表示已有数值但仍需独立复核。不得仅用颜色区分,也不得把临时结果写成最终可信结论。
|
|
280
|
+
|
|
281
|
+
> **reviewer 与 reviewer_independence 说明(conformance_review)**:`reviewer` 用于标识实际执行本次符合度评审的代理或会话(例如 agent 名称、会话 ID)。渲染报告时会比较 `reviewer` 与 apply 阶段记录的 `apply_agent`:若两者相同,则 `reviewer_independence` 显示为 `self-review`;否则显示为 `independent-review`。建议尽可能由独立评审方执行 check,以提升结果可信度。
|
|
274
282
|
|
|
275
283
|
### 6. 【交互引导】根据结果引导下一步
|
|
276
284
|
|
|
@@ -288,7 +296,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=conformance_revie
|
|
|
288
296
|
> - A. 逐个修复(引导到对应命令)
|
|
289
297
|
> - B. 忽略警告继续"
|
|
290
298
|
|
|
291
|
-
> **📊 过程记录(U3)**:若用户选择 A 逐个修复,或在 check 后、归档前补充修复(补 README/CHANGELOG、勾 checkbox 等),每个修复动作**必须**记 `process_note` 事件(`kind=
|
|
299
|
+
> **📊 过程记录(U3)**:若用户选择 A 逐个修复,或在 check 后、归档前补充修复(补 README/CHANGELOG、勾 checkbox 等),每个修复动作**必须**记 `process_note` 事件(`kind=recovery`,`command=check`),归档前修补不再黑箱。**若本阶段存在失败/门禁拦截但无对应 `process_note`,`sdd-apply-test-gate` 会记 `telemetry_warning(process_note_missing)`(不阻断,但报告过程质量信号会标红)。** 必记节点清单见 `opsx-apply/reference.md`「process_note」。
|
|
292
300
|
|
|
293
301
|
---
|
|
294
302
|
|
|
@@ -20,10 +20,11 @@ description: "opsx-check 阶段日志自检清单 — 仅在 check 自检时读
|
|
|
20
20
|
- [ ] `warnings`: 建议修复的问题数
|
|
21
21
|
- [ ] `suggestions`: 可选优化建议数
|
|
22
22
|
- [ ] `fixed_before_apply`: 进入 apply 前已通过/已确认满足门禁的检查项数
|
|
23
|
-
- [ ] `consistency_score`:
|
|
23
|
+
- [ ] `consistency_score`: legacy 兼容字段;跨文档一致性评分 0-1,无法评分填 `null`
|
|
24
|
+
- [ ] `reviewer` / `review_session_id` / `author_session_id` / `reviewer_independence`: Q3 独立性元数据已填写;优先独立 evaluator,不可用时标 `self-review` 或 `unknown`(Q3 provisional)
|
|
24
25
|
- [ ] `categories`: 至少含 `completeness` / `consistency` / `executability`
|
|
25
26
|
- [ ] `task_completion`: 从 `tasks-status` 整理;未进入 apply 时 `checked_for_archive_readiness=false`
|
|
26
|
-
- [ ] **P1-1**:`check_result` 事件 `details` 非空且含 `
|
|
27
|
+
- [ ] **P1-1**:`check_result` 事件 `details` 非空且含 `categories` 等必填键(禁止空 `{}`,否则 Q3 不可计算)
|
|
27
28
|
- [ ] **P2-3**:`has_incomplete=true` 时 `check_result.result=partial` 且 `warning_items` 含 task_completion 项
|
|
28
29
|
|
|
29
30
|
## C. execution-log 状态标记
|
|
@@ -40,15 +41,15 @@ description: "opsx-check 阶段日志自检清单 — 仅在 check 自检时读
|
|
|
40
41
|
|
|
41
42
|
- [ ] **CON 覆盖**:spec.md 中每个 CON 在 tasks.md 中有对应验证任务或显式声明间接覆盖
|
|
42
43
|
- [ ] **安全/审计要求覆盖**:spec.md §5.x 中的安全与审计要求在 tasks.md 中有对应任务或显式声明推迟
|
|
43
|
-
- [ ] **AC 变体覆盖**:spec.md 中含"或"条件的 AC 场景,其 RED 任务验收标准列出所有变体的测试方法(引用 `
|
|
44
|
+
- [ ] **AC 变体覆盖**:spec.md 中含"或"条件的 AC 场景,其 RED 任务验收标准列出所有变体的测试方法(引用 `tdd-rules/rules/multi-validation-split.md`)
|
|
44
45
|
- [ ] **§4.x 验证方式表内部一致性**:tasks.md §4.x 验证方式表中的测试注解/配置与任务实现步骤中的声明一致
|
|
45
46
|
|
|
46
47
|
## E. TDD 合规性检查(仅 test-strategy=tdd 时)
|
|
47
48
|
|
|
48
|
-
⛔ 执行 `
|
|
49
|
+
⛔ 执行 `tdd-core/checklist.md` §B(11 项)逐项检查。
|
|
49
50
|
|
|
50
|
-
> 不在此内联复制,以
|
|
51
|
-
> 额外补充:还需检查 `
|
|
51
|
+
> 不在此内联复制,以 tdd-core/checklist.md §B 为唯一真相源。
|
|
52
|
+
> 额外补充:还需检查 `tdd-rules/rules/exception-path-coverage.md`(异常路径覆盖门禁)。
|
|
52
53
|
|
|
53
54
|
**检查项适用阶段**:
|
|
54
55
|
- **apply 前可验证**(文档级):§B 中除"GREEN 任务输出不含未测试的 Controller/Filter/Config"外的所有检查项(含 Controller 策略声明和测试任务生成)
|
|
@@ -141,7 +141,7 @@ openspec list
|
|
|
141
141
|
|
|
142
142
|
**输出路径**:`changes/<name>/specs/<capability>/design.md`
|
|
143
143
|
|
|
144
|
-
**⛔ DES 步骤级标注(TDD 模式强制)**:当 `test-strategy=tdd` 时,被多个 RED/GREEN 对映射的 DES 元素必须标注步骤级任务归属。规则详见 `
|
|
144
|
+
**⛔ DES 步骤级标注(TDD 模式强制)**:当 `test-strategy=tdd` 时,被多个 RED/GREEN 对映射的 DES 元素必须标注步骤级任务归属。规则详见 `tdd-rules/rules/des-step-annotation.md`
|
|
145
145
|
|
|
146
146
|
### 6.5 【version 正则注释】允许前导零
|
|
147
147
|
|
|
@@ -29,7 +29,7 @@ description: opsx-design 的阶段强制检查点与自检清单。仅在执行
|
|
|
29
29
|
- [ ] 外部依赖已列出
|
|
30
30
|
- [ ] 异常处理策略已定义
|
|
31
31
|
- [ ] 文档末尾包含质量红线检查清单
|
|
32
|
-
- [ ] ⛔ **DES 步骤级标注(TDD 模式)**:当 test-strategy=tdd 时,被多个 RED/GREEN 对映射的 DES 元素已标注步骤级 `[GREEN-N]` 归属(规则见 `
|
|
32
|
+
- [ ] ⛔ **DES 步骤级标注(TDD 模式)**:当 test-strategy=tdd 时,被多个 RED/GREEN 对映射的 DES 元素已标注步骤级 `[GREEN-N]` 归属(规则见 `tdd-rules/rules/des-step-annotation.md`)
|
|
33
33
|
|
|
34
34
|
**如有任意一项未满足,重新生成对应章节,直至全部通过。**
|
|
35
35
|
|
|
@@ -41,6 +41,7 @@ allowed-tools:
|
|
|
41
41
|
> - ${SHELL_GUIDANCE}
|
|
42
42
|
> - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
|
|
43
43
|
> **📊 Telemetry(必做,不得跳过)** — 阶段开始 / 阶段结束**命令模板**见 `./reference.md`「📊 Telemetry 命令模板」。
|
|
44
|
+
> - 用户确认变更范围、`mode`、`test-strategy` 或方案 A/B/C 时,记录严格 `process_note`:`kind=user_decision`,并分别填写 `decision_type=scope|mode|test_strategy|other`。同一决定只记录一次,后续改变范围时改用 `kind=scope_change`。
|
|
44
45
|
|
|
45
46
|
---
|
|
46
47
|
|
|
@@ -267,6 +268,12 @@ Read openspec/changes/archive/*/ontology-identities.json
|
|
|
267
268
|
|
|
268
269
|
**❗ 必须主动询问用户,不得默认选择**。Full / Simple / Auto 三种模式的目录结构、适用场景与 AskUserQuestion 文案见 `./reference.md`「§7 文档拆分模式选择」。根据用户选择设置 `mode: full | simple`(Auto 按能力域数量判断),记录到 proposal.md 的 YAML frontmatter。
|
|
269
270
|
|
|
271
|
+
### 7.5 【交互引导】变更类型确认
|
|
272
|
+
|
|
273
|
+
**❗ 必须主动询问用户,不得默认选择**。在模式与测试策略选择附近,基于需求给出 `change-type` **推荐**并让用户确认;Auto 只能推荐,**禁止无提示静默写入**。
|
|
274
|
+
|
|
275
|
+
允许值固定为:`config | document | report | composite | other`(写入 proposal.md YAML frontmatter 的 `change-type` 字段)。AskUserQuestion 文案与类型说明见 `./reference.md`「§7.5 变更类型选择」。
|
|
276
|
+
|
|
270
277
|
### 8. 【交互引导】测试策略选择
|
|
271
278
|
|
|
272
279
|
**❗ 必须主动询问用户,不得默认选择**。TDD / Impl-First / None 三种策略的 DAG 结构、适用场景与 AskUserQuestion 文案见 `./reference.md`「§8 测试策略选择」。根据用户选择设置 `test-strategy: tdd | impl-first | none`,记录到 proposal.md 的 YAML frontmatter。
|
|
@@ -333,10 +340,11 @@ Read openspec/changes/archive/*/ontology-identities.json
|
|
|
333
340
|
- **⛔ 阶段边界**:本阶段禁止执行任何代码创建/修改操作。若用户要求处理代码,回复:「当前处于 Propose 阶段,代码操作请在完成文档后使用 `/opsx-apply` 执行。」
|
|
334
341
|
- **⛔ 单阶段原则**:完成 proposal.md 后必须立即停止。仅提示用户下一步可运行 `/opsx-spec`,绝对禁止自动执行 spec/design/task 等后续阶段。每个阶段必须由用户主动触发。
|
|
335
342
|
- **⛔ Frontmatter 规范(L7)**:YAML frontmatter 中禁止写 `#` 注释(YAML 注释在 frontmatter 中可能导致解析问题)。如需说明,在 frontmatter 之前或之后用正文描述。
|
|
343
|
+
- **⛔ change-type 必采**:frontmatter 必须含 `change-type`,取值仅限 `config | document | report | composite | other`;Agent 可推荐但须经用户确认后写入,禁止静默默认。
|
|
336
344
|
|
|
337
345
|
---
|
|
338
346
|
|
|
339
347
|
## 渐进披露
|
|
340
348
|
|
|
341
349
|
- Read `checklist.md` 仅在执行 propose 需要校验时 — 含阶段边界⛔(Propose 阶段约束)、§6 需求完整性检查、Guardrails ⛔ 强制项勾选表。
|
|
342
|
-
- Read `reference.md` 仅在需要参考详细模板时 — 含 📊 Telemetry 命令模板(start/end)、§7 文档拆分模式(Full/Simple/Auto)、§8 测试策略(TDD/Impl-First/None)、§10 质量红线自检清单(8 项)。
|
|
350
|
+
- Read `reference.md` 仅在需要参考详细模板时 — 含 📊 Telemetry 命令模板(start/end)、§7 文档拆分模式(Full/Simple/Auto)、§7.5 变更类型(config/document/report/composite/other)、§8 测试策略(TDD/Impl-First/None)、§10 质量红线自检清单(8 项)。
|
|
@@ -4,7 +4,7 @@ description: opsx-propose 的详细模板:telemetry 命令、文档拆分模
|
|
|
4
4
|
|
|
5
5
|
# opsx-propose — 详细参考(reference)
|
|
6
6
|
|
|
7
|
-
> 本文件承载 opsx-propose 的重细节模板:telemetry 命令、§7 文档拆分模式说明、§8 测试策略说明、§10 质量红线自检清单。
|
|
7
|
+
> 本文件承载 opsx-propose 的重细节模板:telemetry 命令、§7 文档拆分模式说明、§7.5 变更类型说明、§8 测试策略说明、§10 质量红线自检清单。
|
|
8
8
|
> SKILL.md 保留入口骨架与指针;本文件为详细模板来源。
|
|
9
9
|
|
|
10
10
|
---
|
|
@@ -48,6 +48,31 @@ description: opsx-propose 的详细模板:telemetry 命令、文档拆分模
|
|
|
48
48
|
|
|
49
49
|
---
|
|
50
50
|
|
|
51
|
+
## §7.5 变更类型选择
|
|
52
|
+
|
|
53
|
+
**❗ 必须主动询问用户,不得默认选择;Auto 仅给推荐,禁止无提示写入**
|
|
54
|
+
|
|
55
|
+
分析需求后,Agent 先给出推荐类型,再使用 **AskUserQuestion** 让用户确认:
|
|
56
|
+
|
|
57
|
+
> "📊 **变更类型(用于 V3 指标分层统计)**
|
|
58
|
+
>
|
|
59
|
+
> 根据本次需求,推荐类型:**[config | document | report | composite | other]** — [一句话理由]
|
|
60
|
+
>
|
|
61
|
+
> 请选择或确认:
|
|
62
|
+
> - **config** — 配置/开关/环境/依赖调整,几乎不改业务逻辑
|
|
63
|
+
> - **document** — 文档、规范、模板、注释类变更
|
|
64
|
+
> - **report** — 报告、度量、仪表盘、采集契约类变更
|
|
65
|
+
> - **composite** — 跨多类能力的组合变更
|
|
66
|
+
> - **other** — 以上均不合适时使用
|
|
67
|
+
>
|
|
68
|
+
> A) 采用推荐 B) 手动选择其他类型"
|
|
69
|
+
|
|
70
|
+
根据用户确认,在 proposal.md YAML frontmatter 写入 `change-type: <值>`。允许值固定:`config | document | report | composite | other`。
|
|
71
|
+
|
|
72
|
+
> 历史 proposal 缺该字段时,报告侧归为 `unknown`;本阶段不得替用户猜测补写。
|
|
73
|
+
|
|
74
|
+
---
|
|
75
|
+
|
|
51
76
|
## §8 测试策略选择
|
|
52
77
|
|
|
53
78
|
**❗ 必须主动询问用户,不得默认选择**
|
|
@@ -66,8 +91,8 @@ description: opsx-propose 的详细模板:telemetry 命令、文档拆分模
|
|
|
66
91
|
|
|
67
92
|
**将用户选择记录到 proposal.md 的 YAML frontmatter 中。**
|
|
68
93
|
|
|
69
|
-
> 完整策略定义见
|
|
70
|
-
> 交互引导文案见
|
|
94
|
+
> 完整策略定义见 tdd-core/SKILL.md §5
|
|
95
|
+
> 交互引导文案见 tdd-rules/rules/tdd-strategy-selection.md
|
|
71
96
|
|
|
72
97
|
---
|
|
73
98
|
|
|
@@ -82,5 +107,6 @@ description: opsx-propose 的详细模板:telemetry 命令、文档拆分模
|
|
|
82
107
|
- [ ] 前置依赖使用 checkbox 格式
|
|
83
108
|
- [ ] 文档末尾包含质量红线检查清单
|
|
84
109
|
- [ ] 能力分解章节已明确(决定后续 specs 文件夹结构)
|
|
110
|
+
- [ ] frontmatter 含 `change-type`,取值为 `config | document | report | composite | other` 之一且经用户确认
|
|
85
111
|
|
|
86
112
|
**如有任意一项未满足,重新生成对应章节,直至全部通过。**
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
# opsx-rules 参考 — 落位矩阵与格式模板
|
|
2
2
|
|
|
3
3
|
> **权威源说明**:本文件是 skill **运行时**的落位矩阵真相源(部署到目标项目后无法 `require` kld-sdd 的 `lib/`)。`lib/tool-profiles.js` 中的 `rulesDir` / `rulesFormat` / `rulesWiring` 为 **init 契约与测试断言**;变更时须与本表同步,以本表为准写入规则文件。
|
|
4
|
+
>
|
|
5
|
+
> **边界**:SkyWalk Telemetry 的事件 schema、`run_id`、`test_event_id` 等属于 SDD 工具协议,不属于业务项目规则。生成或 review 五类项目规则时,不把 telemetry 命令或事件字段写入规则正文。
|
|
4
6
|
|
|
5
7
|
## 落位矩阵
|
|
6
8
|
|
|
@@ -80,7 +82,7 @@ trigger: always_on
|
|
|
80
82
|
|------|--------|----------|----------|
|
|
81
83
|
| 架构规范 | `architecture` | 目录分层、模块边界、入口 | 分层约定、禁止循环依赖、新代码落位 |
|
|
82
84
|
| 编码规范 | `coding-style` | 语言、lint、缩进 | 命名、缩进、注释语言、CommonJS/ESM |
|
|
83
|
-
| 测试约定 | `testing` | test 目录、框架 | 测试命令、命名、TDD 期望(见
|
|
85
|
+
| 测试约定 | `testing` | test 目录、框架 | 测试命令、命名、TDD 期望(见 tdd-core/SKILL.md §5) |
|
|
84
86
|
| 数据安全 | `database-safety` | ORM/迁移目录 | 无 DB 时降级为「禁止危险文件操作/敏感数据提交」 |
|
|
85
87
|
| Git 提交 | `git-commit` | git log 风格、CI | 提交前确认、message 风格、禁止 force push |
|
|
86
88
|
|
|
@@ -214,7 +214,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" \
|
|
|
214
214
|
- 需求项使用 `####`(4个#)
|
|
215
215
|
- 场景使用 `#####`(5个#)
|
|
216
216
|
|
|
217
|
-
**⛔ 多校验拆分规则(TDD 关键)**:当单个 STMT 包含多个"必须校验"条件时,每个校验条件必须有对应的独立 AC 场景。规则详见 `
|
|
217
|
+
**⛔ 多校验拆分规则(TDD 关键)**:当单个 STMT 包含多个"必须校验"条件时,每个校验条件必须有对应的独立 AC 场景。规则详见 `tdd-rules/rules/multi-validation-split.md`
|
|
218
218
|
|
|
219
219
|
### 6.5 【Node 版本约束来源校验】
|
|
220
220
|
|
|
@@ -34,7 +34,7 @@ description: opsx-spec 的阶段强制检查点与自检清单。仅在执行 sp
|
|
|
34
34
|
- [ ] 已消费工程知识库 `answeredQuestions`,没有重复询问历史事实已经回答的问题
|
|
35
35
|
- [ ] 仅将 `reuseMode=INHERIT` 的事实作为身份继承;`REFERENCE` 候选使用新实体身份
|
|
36
36
|
- [ ] 已处理与当前 Capability 有关的 `clarificationQuestions`
|
|
37
|
-
- [ ] ⛔ **多校验拆分(TDD 模式)**:当 test-strategy=tdd 时,单个 STMT 包含多个"必须校验"条件时,每个校验条件有对应的独立 AC 场景(规则见 `
|
|
37
|
+
- [ ] ⛔ **多校验拆分(TDD 模式)**:当 test-strategy=tdd 时,单个 STMT 包含多个"必须校验"条件时,每个校验条件有对应的独立 AC 场景(规则见 `tdd-rules/rules/multi-validation-split.md`)
|
|
38
38
|
|
|
39
39
|
**如有任意一项未满足,重新生成对应章节,直至全部通过。** 自检完成后必须输出结构化自检报告(模板见 `./reference.md`「§7 质量自检报告模板」),未通过项自动修复后重新输出。
|
|
40
40
|
|
|
@@ -150,8 +150,8 @@ Simple 模式或单文件能力域下,**不要拆成多个同文件任务**。
|
|
|
150
150
|
|
|
151
151
|
**若未设置**:使用 **AskUserQuestion** 工具询问(A/B/C 三选一)
|
|
152
152
|
|
|
153
|
-
> 完整策略定义见
|
|
154
|
-
> 交互引导文案见
|
|
153
|
+
> 完整策略定义见 tdd-core/SKILL.md §5
|
|
154
|
+
> 交互引导文案见 tdd-rules/rules/tdd-strategy-selection.md
|
|
155
155
|
|
|
156
156
|
### 6. 【交互引导】确认任务拆解策略
|
|
157
157
|
|
|
@@ -185,19 +185,19 @@ Simple 模式或单文件能力域下,**不要拆成多个同文件任务**。
|
|
|
185
185
|
4. GREEN 不得包含未测试的 Controller/Filter/Config
|
|
186
186
|
5. 非 TDD 模块(前端 UI/配置/SQL DDL)不拆红绿
|
|
187
187
|
6. Controller 层策略必须在 tasks.md §2.0 中声明(策略 A 或 B),两种策略都必须生成测试任务
|
|
188
|
-
7. ⛔ **GREEN 任务 YAGNI 围栏**:每个 GREEN-N 任务描述末尾必须包含"不提前实现 [后续 RED 行为]"围栏声明。规则详见 `
|
|
188
|
+
7. ⛔ **GREEN 任务 YAGNI 围栏**:每个 GREEN-N 任务描述末尾必须包含"不提前实现 [后续 RED 行为]"围栏声明。规则详见 `tdd-rules/rules/green-yagni-fence.md`
|
|
189
189
|
8. ⛔ **TDD 模式 DAG 并行标注**:当 `test-strategy=tdd` 时,DAG 拓扑图中每个 RED→GREEN 对必须标注 `⛔ 串行:不可同层并行`。同层存在多个 RED→GREEN 对时,必须在拓扑图中显式注明"本层 RED→GREEN 对须逐对串行执行,禁止并行派发"。非 TDD 模块的同层任务(如 UI/配置/SQL DDL)仍可并行。
|
|
190
190
|
|
|
191
191
|
⛔ BEFORE 生成 TDD 任务,必须读取:
|
|
192
|
-
1.
|
|
193
|
-
2.
|
|
194
|
-
3.
|
|
195
|
-
4.
|
|
192
|
+
1. tdd-core/reference.md §6(DAG 生成规则表)
|
|
193
|
+
2. tdd-rules/rules/dag-generation-rules.md(DAG 规则文件)
|
|
194
|
+
3. tdd-rules/rules/controller-strategy.md(Controller 策略 A/B)
|
|
195
|
+
4. tdd-rules/rules/exception-path-coverage.md(异常路径测试覆盖门禁)
|
|
196
196
|
读取后确认:"已读取 N 个规则文件"。
|
|
197
197
|
|
|
198
|
-
> 完整 TDD 拆分示例见
|
|
199
|
-
> 非 TDD 模块定义见
|
|
200
|
-
> 任务类型定义见
|
|
198
|
+
> 完整 TDD 拆分示例见 tdd-core/reference.md §4
|
|
199
|
+
> 非 TDD 模块定义见 tdd-rules/rules/non-tdd-modules.md
|
|
200
|
+
> 任务类型定义见 tdd-rules/rules/task-type-definitions.md
|
|
201
201
|
|
|
202
202
|
### 8. 质量红线自检
|
|
203
203
|
|
|
@@ -39,10 +39,10 @@ description: opsx-task 的阶段强制检查点与自检清单。仅在执行 ta
|
|
|
39
39
|
|
|
40
40
|
## §8.1 TDD 合规性自检(仅 test-strategy=tdd 时)
|
|
41
41
|
|
|
42
|
-
⛔ 执行 `
|
|
42
|
+
⛔ 执行 `tdd-core/checklist.md` §B(11 项)逐项检查。
|
|
43
43
|
|
|
44
|
-
> 不在此内联复制,以
|
|
45
|
-
> 额外补充:还需检查 `
|
|
44
|
+
> 不在此内联复制,以 tdd-core/checklist.md §B 为唯一真相源。
|
|
45
|
+
> 额外补充:还需检查 `tdd-rules/rules/exception-path-coverage.md`(异常路径覆盖门禁)——每个 orElseThrow/边界检查须有对应 RED 任务。
|
|
46
46
|
|
|
47
47
|
---
|
|
48
48
|
|
|
@@ -18,7 +18,7 @@ description: opsx-task 的详细模板:telemetry 命令、DAG 生成规则表
|
|
|
18
18
|
|
|
19
19
|
## §6 DAG 生成规则表
|
|
20
20
|
|
|
21
|
-
> 完整规则见 `
|
|
21
|
+
> 完整规则见 `tdd-rules/rules/dag-generation-rules.md`,此处仅保留快速参考。
|
|
22
22
|
|
|
23
23
|
**根据 test-strategy 调整 DAG 生成规则:**
|
|
24
24
|
|
|
@@ -52,7 +52,7 @@ spec.md user-auth 定义了 7 个场景,拆为 7 对 RED+GREEN + 1 个 REFACTO
|
|
|
52
52
|
| TASK-05-GREEN-6 | 登出实现 | 实现-GREEN | TASK-05-RED-6 | 让 RED-6 通过。仅实现当前 RED 测试覆盖的行为路径,不提前实现后续 capability 的功能。 |
|
|
53
53
|
| TASK-05-REFACTOR | 重构优化 | 重构-REFACTOR | TASK-05-GREEN-6 | 所有测试仍绿,代码清理 |
|
|
54
54
|
|
|
55
|
-
> GREEN 任务的 YAGNI 围栏生成规则详见 `
|
|
55
|
+
> GREEN 任务的 YAGNI 围栏生成规则详见 `tdd-rules/rules/green-yagni-fence.md`
|
|
56
56
|
|
|
57
57
|
**关键区别**:
|
|
58
58
|
- 每个 RED 任务都带**真实断言**,跑起来确实失败
|
|
@@ -86,7 +86,7 @@ spec.md user-auth 定义了 7 个场景,拆为 7 对 RED+GREEN + 1 个 REFACTO
|
|
|
86
86
|
|
|
87
87
|
## §6.2 非 TDD 模块处理规则
|
|
88
88
|
|
|
89
|
-
> 完整规则见 `
|
|
89
|
+
> 完整规则见 `tdd-rules/rules/non-tdd-modules.md`,此处仅保留快速参考。
|
|
90
90
|
|
|
91
91
|
以下模块不需要红绿循环,按常规任务处理:
|
|
92
92
|
- 前端 UI 页面(Vue 组件)→ UI层任务
|
|
@@ -105,13 +105,15 @@ allowed-tools:
|
|
|
105
105
|
|
|
106
106
|
### 4a. 【M3 Telemetry】记录测试结果
|
|
107
107
|
|
|
108
|
-
|
|
108
|
+
每一次真实测试执行只记录一条 `test_result`,不得把同一次命令的结果复制到多个任务,也不得用估算值补齐用例数。测试执行完成后,在 stage_end 之前记录:
|
|
109
109
|
|
|
110
110
|
```bash
|
|
111
|
-
node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=test_result --command=test --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/failure --summary="
|
|
111
|
+
node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=test_result --command=test --project=. --change=<变更名称> --capability=<可选capability-name> --task-id=<首个TASK-ID> --run-id=<本次真实执行的稳定ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/failure --summary="<人能看懂的测试结论>" --details-json="{\"test_results\":{\"snapshot_kind\":\"final\",\"verified_task_ids\":[\"<TASK-ID-1>\",\"<TASK-ID-2>\"],\"tdd_phase\":\"<red|green|refactor|regression|not-applicable>\",\"command\":\"<实际测试命令>\",\"exit_code\":<退出码>,\"counts_known\":<true|false>,\"passed\":<counts_known=true时填写>,\"failed\":<counts_known=true时填写>,\"skipped\":<counts_known=true时填写>,\"duration_ms\":<实测毫秒>,\"failure_type\":\"<assertion|contract|compile|infrastructure|timeout|none>\",\"expected_failure\":<仅RED预期失败时true>}}"
|
|
112
112
|
```
|
|
113
113
|
|
|
114
|
-
|
|
114
|
+
`run_id` 在同一次执行重试写入时必须保持不变:相同内容会幂等跳过,不同内容会被判为冲突。`counts_known=false` 时省略 `passed/failed/skipped`,绝不写虚构的 `0`。RED 只有在 `expected_failure=true`、退出码非 0 且失败类型为 `assertion` 或 `contract` 时才是有效 RED;基础设施或编译错误不算。
|
|
115
|
+
|
|
116
|
+
此事件供任务完成证据和最终报告采集。最终回归必须写 `snapshot_kind:"final"`;一次执行覆盖多个任务时用去重的 `verified_task_ids`,仍只写一条事件。后续 `task_update` 只引用本事件返回的 `event_id`,不再内嵌或复制测试计数。
|
|
115
117
|
|
|
116
118
|
> **⚠️ P1-4 coverage 不得为 null**:`test_results.coverage` 必须填实测覆盖率数值(跑了 `--coverage` 就填数值,如 `86.5`);未跑 `--coverage` 时填字符串 `"not-run"` 并在 summary 说明原因。**禁止填 `null`**。若 `proposal.md` 含"覆盖率 ≥ X%"验收标准,强制使用 `--coverage` 运行测试。
|
|
117
119
|
|
|
@@ -148,8 +150,8 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=test_result --com
|
|
|
148
150
|
- [ ] 无"生产类中加测试专用方法"
|
|
149
151
|
- [ ] 无"不理解依赖就 mock"
|
|
150
152
|
|
|
151
|
-
> 完整 12 项反模式检测见
|
|
152
|
-
> TDD 报告模式见
|
|
153
|
+
> 完整 12 项反模式检测见 tdd-anti-patterns/SKILL.md §4
|
|
154
|
+
> TDD 报告模式见 tdd-review/SKILL.md §3
|
|
153
155
|
|
|
154
156
|
### 6. 【交互引导】根据结果引导下一步
|
|
155
157
|
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
---
|
|
2
|
-
name:
|
|
2
|
+
name: tdd-anti-patterns
|
|
3
3
|
description: "测试反模式防护层 — 16 种反模式检测(RED 阶段 3 种 + GREEN 后 13 种),每种带门禁函数和修复方案。当编写或审查测试代码时引用本技能。"
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
#
|
|
6
|
+
# tdd-anti-patterns — 反模式防护层
|
|
7
7
|
|
|
8
8
|
> **定位**:测试反模式的系统化检测,RED 阶段 + GREEN 后双重检查。
|
|
9
9
|
> **参考来源**:Superpowers `testing-anti-patterns.md`
|
|
@@ -47,8 +47,8 @@ description: "测试反模式防护层 — 16 种反模式检测(RED 阶段 3
|
|
|
47
47
|
| 12 | **测试代码重复** | 大量 copy-paste 的测试代码,缺少 helper 提取 | 提取 test fixture builder 或 helper 方法 |
|
|
48
48
|
| 13 | **魔法值** | 测试中使用未解释的字面值(如 `assertEquals(42, result)` 无注释说明 42 的含义) | 使用命名常量或注释解释字面值含义 |
|
|
49
49
|
| 14 | **断言不足** | 只断言了部分结果,遗漏了关键属性(如只 assertNotNull 但不 assertEquals 具体值) | 每个测试至少有一个具体值断言(assertEquals),而非仅 assertNotNull |
|
|
50
|
-
| 15 | **缺少负面测试** | 只测试正常路径,不测试错误条件 | 每个方法至少有一个异常路径测试(见 `
|
|
51
|
-
| 16 | **AC 变体覆盖不足** | AC 场景描述含"或"条件(如"缺少 A 或 B 或为空"),但测试只覆盖部分变体 | AC 中每个"或"条件变体必须有对应测试方法(规则见 `
|
|
50
|
+
| 15 | **缺少负面测试** | 只测试正常路径,不测试错误条件 | 每个方法至少有一个异常路径测试(见 `tdd-rules/rules/exception-path-coverage.md`) |
|
|
51
|
+
| 16 | **AC 变体覆盖不足** | AC 场景描述含"或"条件(如"缺少 A 或 B 或为空"),但测试只覆盖部分变体 | AC 中每个"或"条件变体必须有对应测试方法(规则见 `tdd-rules/rules/multi-validation-split.md` §AC 内"或"条件变体覆盖) |
|
|
52
52
|
|
|
53
53
|
## §5 门禁函数
|
|
54
54
|
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: "
|
|
2
|
+
description: "tdd-anti-patterns 详细参考 — 9 种反模式完整详表 + 修复方案代码示例。仅在需要详细反模式检查时读取。"
|
|
3
3
|
---
|
|
4
4
|
|
|
5
|
-
#
|
|
5
|
+
# tdd-anti-patterns — 详细参考
|
|
6
6
|
|
|
7
7
|
> 仅在需要详细反模式检查时读取。日常检查见 `SKILL.md`。
|
|
8
8
|
|
|
@@ -193,7 +193,7 @@ assertEquals("user-001", result.getUserId());
|
|
|
193
193
|
|
|
194
194
|
**问题**:只测试正常路径,不测试错误条件。
|
|
195
195
|
|
|
196
|
-
**修复**:每个方法至少有一个异常路径测试。规则见 `
|
|
196
|
+
**修复**:每个方法至少有一个异常路径测试。规则见 `tdd-rules/rules/exception-path-coverage.md`。
|
|
197
197
|
|
|
198
198
|
## 反模式 16:AC 变体覆盖不足
|
|
199
199
|
|
|
@@ -222,7 +222,7 @@ void login_withMissingParams_returns1001() {
|
|
|
222
222
|
@Test void login_withBothMissing_returns1001() { ... }
|
|
223
223
|
```
|
|
224
224
|
|
|
225
|
-
**修复**:AC 中每个"或"条件变体必须有对应测试方法。规则见 `
|
|
225
|
+
**修复**:AC 中每个"或"条件变体必须有对应测试方法。规则见 `tdd-rules/rules/multi-validation-split.md` §AC 内"或"条件变体覆盖。
|
|
226
226
|
|
|
227
227
|
## TDD 如何防止这些反模式
|
|
228
228
|
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
---
|
|
2
|
-
name:
|
|
2
|
+
name: tdd-core
|
|
3
3
|
description: "TDD 流程纪律层 — 铁律、红绿重构循环、执行门禁、合规自检。当 test-strategy=tdd 时,所有 SDD 阶段引用本技能获取 TDD 流程规则。"
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
#
|
|
6
|
+
# tdd-core — TDD 流程纪律层
|
|
7
7
|
|
|
8
8
|
> **定位**:TDD 铁律、红绿重构循环定义、执行门禁的唯一真相源。
|
|
9
9
|
> **参考来源**:Superpowers `test-driven-development`
|
|
@@ -81,7 +81,7 @@ RED → Verify RED → 🔴中断声明 → GREEN → Verify GREEN → GREEN Sco
|
|
|
81
81
|
- 此声明强制 agent 在 RED 和 GREEN 之间产生节奏断点,防止从 RED 滑入 GREEN 再滑入下一个行为点
|
|
82
82
|
- **GREEN**:写最简单的代码通过测试
|
|
83
83
|
- 不添加功能、不重构其他代码、不"改进"超出测试范围的内容
|
|
84
|
-
- ⛔ **执行 GREEN Scope 声明**(见 `
|
|
84
|
+
- ⛔ **执行 GREEN Scope 声明**(见 `tdd-rules/rules/green-scope-declaration.md`):
|
|
85
85
|
1. 列出当前 RED 测试的断言清单
|
|
86
86
|
2. 列出 design.md 中本 DES 元素的完整流程步骤
|
|
87
87
|
3. 标记步骤归属(✅ 属于当前 RED / ⛔ 属于后续 RED)
|
|
@@ -126,12 +126,12 @@ RED → Verify RED → 🔴中断声明 → GREEN → Verify GREEN → GREEN Sco
|
|
|
126
126
|
- **REFACTOR**:仅在绿色之后
|
|
127
127
|
- 移除重复、改善命名、提取辅助函数
|
|
128
128
|
- 保持测试绿色,不添加行为
|
|
129
|
-
- ⛔ 执行 `
|
|
129
|
+
- ⛔ 执行 `tdd-rules/rules/refactor-checklist.md`(7 项重构检查点)
|
|
130
130
|
- **Repeat**:下一个失败测试,下一个功能
|
|
131
131
|
|
|
132
132
|
## §4 执行门禁
|
|
133
133
|
|
|
134
|
-
> 完整规则见 `
|
|
134
|
+
> 完整规则见 `tdd-rules/rules/test-execution-gate.md`,此处仅保留快速参考。
|
|
135
135
|
|
|
136
136
|
| test-strategy | 行为 |
|
|
137
137
|
|---------------|------|
|
|
@@ -141,7 +141,7 @@ RED → Verify RED → 🔴中断声明 → GREEN → Verify GREEN → GREEN Sco
|
|
|
141
141
|
|
|
142
142
|
## §5 TDD 策略定义
|
|
143
143
|
|
|
144
|
-
> 完整规则见 `
|
|
144
|
+
> 完整规则见 `tdd-rules/rules/tdd-strategy-selection.md`,此处仅保留快速参考。
|
|
145
145
|
|
|
146
146
|
三种策略(tdd/impl-first/none)的定义与适用场景:
|
|
147
147
|
|
|
@@ -151,7 +151,7 @@ RED → Verify RED → 🔴中断声明 → GREEN → Verify GREEN → GREEN Sco
|
|
|
151
151
|
|
|
152
152
|
## §6 Controller 层策略
|
|
153
153
|
|
|
154
|
-
> 完整规则见 `
|
|
154
|
+
> 完整规则见 `tdd-rules/rules/controller-strategy.md`,此处仅保留快速参考。
|
|
155
155
|
|
|
156
156
|
⛔ Controller 层**必须**有测试。两种策略的区别在于测试方式,而非"有无测试"。
|
|
157
157
|
|
|
@@ -214,14 +214,14 @@ RED → Verify RED → 🔴中断声明 → GREEN → Verify GREEN → GREEN Sco
|
|
|
214
214
|
|
|
215
215
|
## §10 跨技能引用
|
|
216
216
|
|
|
217
|
-
- → `
|
|
218
|
-
- → `
|
|
219
|
-
- → `
|
|
220
|
-
- → `
|
|
221
|
-
- → `
|
|
217
|
+
- → `tdd-quality`:单测代码质量标准(Mock 边界矩阵、命名规范、Java 规则等)
|
|
218
|
+
- → `tdd-anti-patterns`:测试反模式检测(15 种反模式 + 门禁函数)
|
|
219
|
+
- → `tdd-review`:测试审查(8 项质量检查 + 缺失测试检测)
|
|
220
|
+
- → `tdd-metrics`:度量分析(隔离评分、命名评分、覆盖率缺口)
|
|
221
|
+
- → `tdd-rules`:规则库(DAG 规则、Controller 策略、telemetry 模板等)
|
|
222
222
|
- `rules/green-yagni-fence.md`:GREEN 任务 YAGNI 围栏(引用方:opsx-task)
|
|
223
223
|
- `rules/green-scope-declaration.md`:GREEN Scope 声明(引用方:opsx-apply)
|
|
224
224
|
- `rules/des-step-annotation.md`:DES 步骤级标注(引用方:opsx-design)
|
|
225
225
|
- `rules/multi-validation-split.md`:多校验拆分(引用方:opsx-spec)
|
|
226
226
|
- `rules/exception-path-coverage.md`:异常路径测试覆盖门禁(引用方:opsx-task, opsx-apply, opsx-check)
|
|
227
|
-
- `rules/refactor-checklist.md`:REFACTOR 阶段检查点(引用方:opsx-apply,
|
|
227
|
+
- `rules/refactor-checklist.md`:REFACTOR 阶段检查点(引用方:opsx-apply, tdd-core)
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: "
|
|
2
|
+
description: "tdd-core 自检清单 — TDD 执行合规自检、合规性检查、完成验证。仅在执行 TDD 任务自检时读取。"
|
|
3
3
|
---
|
|
4
4
|
|
|
5
|
-
#
|
|
5
|
+
# tdd-core — 自检清单
|
|
6
6
|
|
|
7
7
|
> 仅在执行 TDD 任务自检时读取。日常流程见 `SKILL.md`。
|
|
8
8
|
|
|
@@ -18,7 +18,7 @@ description: "opsx-tdd-core 自检清单 — TDD 执行合规自检、合规性
|
|
|
18
18
|
- [ ] ⛔ **RED→GREEN 中断声明已执行**:RED 确认失败后,显式声明了"🔴 RED-N 确认失败,现在进入 GREEN-N"
|
|
19
19
|
- [ ] GREEN 任务已运行测试确认通过
|
|
20
20
|
- [ ] GREEN 未提前实现没有测试要求的功能
|
|
21
|
-
- [ ] ⛔ **GREEN Scope 越界检测**:GREEN 实现后检查生产代码是否包含未被当前 RED 断言覆盖的逻辑分支(规则见 `
|
|
21
|
+
- [ ] ⛔ **GREEN Scope 越界检测**:GREEN 实现后检查生产代码是否包含未被当前 RED 断言覆盖的逻辑分支(规则见 `tdd-rules/rules/green-scope-declaration.md` §Scope 自检)
|
|
22
22
|
- [ ] ⛔ **GREEN YAGNI 围栏逐条确认**:读取 tasks.md 中本 GREEN 任务的 YAGNI 围栏声明,逐条确认"未实现 [后续 RED 的行为]:✅"
|
|
23
23
|
- [ ] ⛔ **GREEN Scope 门禁已执行**:Verify GREEN 之后,检查生产代码无越界逻辑分支
|
|
24
24
|
- [ ] REFACTOR 后全部测试仍绿
|
|
@@ -42,7 +42,7 @@ description: "opsx-tdd-core 自检清单 — TDD 执行合规自检、合规性
|
|
|
42
42
|
- [ ] 每个 REFACTOR 任务列出至少 2 个具体重构点
|
|
43
43
|
- [ ] ⛔ **CON 覆盖**:spec.md 中每个 CON 在 tasks.md 中有对应验证任务或显式声明间接覆盖
|
|
44
44
|
- [ ] ⛔ **安全/审计要求覆盖**:spec.md §5.x 中的安全与审计要求在 tasks.md 中有对应任务或显式声明推迟
|
|
45
|
-
- [ ] ⛔ **AC 变体覆盖**:spec.md 中含"或"条件的 AC 场景,其 RED 任务验收标准列出所有变体的测试方法(引用 `
|
|
45
|
+
- [ ] ⛔ **AC 变体覆盖**:spec.md 中含"或"条件的 AC 场景,其 RED 任务验收标准列出所有变体的测试方法(引用 `tdd-rules/rules/multi-validation-split.md`)
|
|
46
46
|
|
|
47
47
|
## §C 完成验证清单(8 项)
|
|
48
48
|
|
|
@@ -56,6 +56,6 @@ description: "opsx-tdd-core 自检清单 — TDD 执行合规自检、合规性
|
|
|
56
56
|
- [ ] 输出纯净(无错误/警告)
|
|
57
57
|
- [ ] 测试使用真实代码(仅在不可避免时使用 mock)
|
|
58
58
|
- [ ] 边界情况和错误已覆盖
|
|
59
|
-
- [ ] ⛔ **AC "或"条件变体全覆盖**:AC 场景描述含"或"条件时,每个变体都有对应测试方法(引用 `
|
|
59
|
+
- [ ] ⛔ **AC "或"条件变体全覆盖**:AC 场景描述含"或"条件时,每个变体都有对应测试方法(引用 `tdd-rules/rules/multi-validation-split.md`)
|
|
60
60
|
|
|
61
61
|
> Can't check all boxes? You skipped TDD. Start over.
|