kld-sdd 2.7.3 → 2.7.8-2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. package/README.md +12 -5
  2. package/USABILITY.md +104 -0
  3. package/bin/kld-sdd-init.js +1 -1
  4. package/kld-sdd-guide.html +16 -4
  5. package/lib/hook-gate-core.js +327 -0
  6. package/lib/init.js +228 -37
  7. package/lib/scale-thresholds.json +19 -0
  8. package/lib/skills-bundle.js +2 -1
  9. package/package.json +5 -3
  10. package/skywalk-sdd/context-client.cjs +50 -30
  11. package/skywalk-sdd/index.cjs +159 -40
  12. package/skywalk-sdd/kb-sync-identity.cjs +99 -451
  13. package/skywalk-sdd/kb-upload.cjs +67 -44
  14. package/skywalk-sdd/lib/check-review.cjs +41 -0
  15. package/skywalk-sdd/lib/test-execution.cjs +110 -0
  16. package/skywalk-sdd/lib/usage-contract.cjs +3 -2
  17. package/skywalk-sdd/lib/usage-reporter.cjs +27 -2
  18. package/skywalk-sdd/metrics-v3.cjs +2 -2
  19. package/skywalk-sdd/ontology/active-changes.cjs +2 -1
  20. package/skywalk-sdd/ontology/archive-package.cjs +1 -1
  21. package/skywalk-sdd/ontology/artifact-parser.cjs +7 -4
  22. package/skywalk-sdd/ontology/id.cjs +5 -4
  23. package/skywalk-sdd/ontology/identity-index.cjs +9 -4
  24. package/skywalk-sdd/ontology/list-changes.cjs +1 -1
  25. package/skywalk-sdd/ontology/runtime.cjs +7 -3
  26. package/skywalk-sdd/ontology/schema.cjs +2 -0
  27. package/skywalk-sdd/ontology/traceability-validator.cjs +74 -4
  28. package/skywalk-sdd/ontology/workspace-layout.cjs +25 -5
  29. package/skywalk-sdd/reporting/change-report-model.cjs +4 -3
  30. package/templates/git-hooks/commit-msg +39 -24
  31. package/templates/git-hooks/consistency-check-core.cjs +1097 -0
  32. package/templates/git-hooks/hooks.config +20 -1
  33. package/templates/git-hooks/pre-commit +39 -24
  34. package/templates/git-hooks/pre-commit-consistency-check.cjs +29 -332
  35. package/templates/git-hooks/pre-commit-sdd-check.cjs +98 -0
  36. package/templates/git-hooks/pre-push +39 -24
  37. package/templates/git-hooks/pre-push-consistency-check.cjs +58 -406
  38. package/templates/hooks/claude/hooks/sdd-post-tool.cjs +2 -2
  39. package/templates/hooks/codebuddy/hooks/sdd-post-tool.cjs +2 -2
  40. package/templates/hooks/codebuddy/hooks/sdd-tdd-rhythm-gate.cjs +1 -1
  41. package/templates/openspec/tasks.md +3 -3
  42. package/templates/skills/kld-sdd/opsx-apply/SKILL.md +44 -6
  43. package/templates/skills/kld-sdd/opsx-apply/checklist.md +1 -1
  44. package/templates/skills/kld-sdd/opsx-apply/reference.md +20 -2
  45. package/templates/skills/kld-sdd/opsx-archive/SKILL.md +19 -21
  46. package/templates/skills/kld-sdd/opsx-check/SKILL.md +55 -327
  47. package/templates/skills/kld-sdd/opsx-check/checklist.md +7 -4
  48. package/templates/skills/kld-sdd/opsx-check/reference.md +60 -0
  49. package/templates/skills/kld-sdd/opsx-check/result-template.json +52 -0
  50. package/templates/skills/kld-sdd/opsx-check/review-template.json +22 -0
  51. package/templates/skills/kld-sdd/opsx-check/reviewer.md +100 -0
  52. package/templates/skills/kld-sdd/opsx-consistency-check/SKILL.md +82 -451
  53. package/templates/skills/kld-sdd/opsx-consistency-check/{reference.md → references/reference.md} +0 -1
  54. package/templates/skills/kld-sdd/opsx-consistency-check/scripts/scripts.cjs +517 -0
  55. package/templates/skills/kld-sdd/opsx-design/SKILL.md +10 -30
  56. package/templates/skills/kld-sdd/opsx-design/checklist.md +3 -4
  57. package/templates/skills/kld-sdd/opsx-design/reference.md +1 -1
  58. package/templates/skills/kld-sdd/opsx-kb-config/SKILL.md +29 -154
  59. package/templates/skills/kld-sdd/opsx-kb-config/reference.md +8 -11
  60. package/templates/skills/kld-sdd/opsx-kb-ingest/SKILL.md +12 -74
  61. package/templates/skills/kld-sdd/opsx-kb-ingest/reference.md +2 -2
  62. package/templates/skills/kld-sdd/opsx-ontology-query/SKILL.md +7 -5
  63. package/templates/skills/kld-sdd/opsx-ontology-query/phase-1-prechange.md +2 -2
  64. package/templates/skills/kld-sdd/opsx-ontology-query/reference.md +1 -1
  65. package/templates/skills/kld-sdd/opsx-propose/SKILL.md +29 -74
  66. package/templates/skills/kld-sdd/opsx-propose/checklist.md +8 -8
  67. package/templates/skills/kld-sdd/opsx-propose/interaction-policy.md +35 -0
  68. package/templates/skills/kld-sdd/opsx-propose/reference.md +12 -46
  69. package/templates/skills/kld-sdd/opsx-spec/SKILL.md +14 -61
  70. package/templates/skills/kld-sdd/opsx-spec/checklist.md +3 -3
  71. package/templates/skills/kld-sdd/opsx-task/SKILL.md +40 -34
  72. package/templates/skills/kld-sdd/opsx-task/checklist.md +5 -6
  73. package/templates/skills/kld-sdd/opsx-test/SKILL.md +2 -0
  74. package/templates/skills/kld-sdd/tdd-rules/rules/tdd-strategy-selection.md +1 -1
@@ -15,22 +15,23 @@ allowed-tools:
15
15
  - Edit
16
16
  ---
17
17
 
18
+ > **执行方式**:先读 [交互与执行契约](./interaction-policy.md);同一会话已读则复用。用户已授权连续处理时按范围推进,不重复索要阶段口令;只请求单阶段时完成即停。
19
+
18
20
  你是一个 SDD(Specification-Driven Development)业务意图文档专家。激活本技能后,你将引导用户创建符合质量红线标准的 **proposal.md** 文档。
19
21
 
20
- > **硬依赖**:本技能 Continuity 步骤依赖同级已部署的 **`opsx-ontology-query`**。启动 Continuity 前必须先 `Read` 该技能的 `SKILL.md`,并按其中流程准备 `kb-state.json`(spec 仓根目录,API Key + targets,与 `opsx-kb-ingest` 共用)。若项目 skills 目录中不存在 `opsx-ontology-query/`,停止 Continuity,提示用户重新执行 `kld-sdd-init`;**禁止**用本地 `archive/` 冒充查询。
22
+ > **KB 查询依赖**:需要查询时加载 `opsx-ontology-query`;缺失或不可用只跳过远程查询,记录待核对基线后继续本地工作。
21
23
  >
22
- > **📡 KB 就绪检查**:§6.5 在进入编号入场前会检测 KB 配置状态。若未配置,会**主动询问**用户选择「配置」或「跳过」,不再静默降级。
24
+ > **KB 使用**:有复用需要时查询一次;未配置或断连按交互契约继续,不在每个阶段询问配置。
23
25
 
24
26
  > **⚠️ 阶段边界约束**
25
27
  >
26
28
  > 当前处于 **Propose(规划)阶段**:
27
29
  > - ✅ **允许**:创建/编辑 proposal.md 文档、读取代码/文档作为上下文分析
28
30
  > - ❌ **禁止**:创建/修改任何代码文件、执行代码生成、运行测试
29
- > - ⛔ **单阶段原则**:完成 proposal.md 后**必须立即停止**,等待用户主动触发下一阶段
31
+ > - **执行范围**:单阶段请求完成即停;已授权连续处理则按交互契约加载下一阶段,check 通过后方可进入 apply,不能超出授权范围。
30
32
  >
31
33
  > 即使用户提供了代码作为上下文,也只用于理解需求背景,**不执行任何代码操作**。
32
34
  > 代码实现请引导用户使用 `/opsx-apply` 命令。
33
- > **完成本阶段后,绝对禁止自动继续执行 spec/design/task 等后续阶段。**
34
35
  > 阶段边界自检见 `./checklist.md`「阶段边界⛔」。
35
36
 
36
37
  > **🖥️ 跨平台执行规则**
@@ -208,17 +209,8 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" external-key --validat
208
209
  - 编号格式:大写字母 + 数字 + 连字符(-) + 下划线(_),1~50 字符;例 KLERP-001、REQ-FI-2024-001、1010000。
209
210
  - 不合规 → **拒绝进入 resolve**,告知「编号格式不合规(仅允许大写字母、数字、连字符、下划线)」;Agent 不得猜测、补位、改写。
210
211
  - 用户明确说「没有外部需求号」→ 走 `numbering-waiver.reason`(必填理由);`requirement-refs` 必须为空;提示本轮不种桥。
211
- 3. **先加载依赖技能**:确认 `${AGENT_SKILL_DIR}/opsx-kb-config/SKILL.md` 存在并 Read。KB 配置(API Key + Space/KB 选择 + project-identity.json)由 `opsx-kb-config` 统一负责,`kb-state.json`(spec 仓根目录)与 `opsx-ontology-query`、`opsx-kb-ingest` 共用。未安装则停止本步。
212
- - **KB 就绪检查**:运行 `node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" --check-only`,若 `"available": false`,使用 **AskUserQuestion** 询问用户:
213
- > "📡 **知识库未配置**
214
- >
215
- > 知识库可以帮你追踪能力版本,避免重复定义。现在要配置吗?
216
- > - A. **现在配置** — 运行 /opsx-kb-config,配置后可复用已有能力
217
- > - B. **暂不配置,先继续** — 用本地归档数据代替(精度有限,后续入库可能需修正)
218
- > - C. **取消** — 终止本次操作"
219
- - **选 A** → 引导运行 `/opsx-kb-config`,配置完成后继续步骤 4。
220
- - **选 B** → 在 proposal.md frontmatter 标注 `kb-status: degraded(by-user-choice)`,走降级路径(扫描归档 `ontology-identities.json` 匹配已有能力;归档为空则全部按新增处理)。
221
- - **选 C** → 终止 propose。
212
+ 3. 若本轮需要 KB 复用且尚未降级,加载查询技能并使用已有 `kb-state.json`。无需先做独立 readiness 请求;查询本身即可发现连接问题。未配置、缺少查询技能、断连或无权限时,记录 `kb-status: degraded` 和原因,跳过步骤 4—6 的远程操作,继续本地编写,不开启配置问答。用户主动要求配置时再加载 `opsx-kb-config`。
213
+
222
214
  4. 验号通过后才 resolve:
223
215
  ```bash
224
216
  node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" --mode=resolve \
@@ -233,43 +225,23 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" --mode=resolve \
233
225
  6. 按 KB 结果确认 Continuity:`iteration` / `similar-reference` / `new`;勾选本次涉及的 CAP。
234
226
  7. 写入 proposal frontmatter:`requirement-refs`(含 `feature-id`)/ `numbering-waiver` + `continuity`。**禁止**写本地 archive 文件夹名作为 `base-archive`。
235
227
  8. CAP 级「同 key + 同锚点、不同 entity_id」当场问 A/B/C;决议写入 `ontology/continuity-resolution.json` 的 `capabilities[]`。
236
- 9. KB 不可用 → `degraded` 继续,**禁止**扫本地 `archive/` 抄 UUID。用户选择跳过 KB 时走降级路径:
237
- - 扫描 `openspec/changes/archive/*/ontology/ontology-identities.json` 匹配 canonicalKey
238
- - 降级路径的所有 entity-id 来源在 sdd-output.md 知识库使用表中标注 `source: archive(degraded)`,与 `source: KB current` 明确区分。
239
- - ⚠️ **降级风险**:归档中的版本号可能已过时(归档后该能力可能在 KB 中有更新版本)。降级路径取到的 predecessor-version 不保证是 KB 最新版本,入库时可能触发 `VERSION_CONFLICT`,需手动修正。
228
+ 9. KB 不可用时,保留当前草稿已有身份和真实前驱,记录 `kb-status: degraded`。本地归档可作背景参考,不能仅凭相似标题复制身份并宣称已验证 KB current。已知迭代而身份未确认时先完成正文,登记待确认项,发布前在线解析;不把“查询失败”当作“确认新增”。
240
229
  10. **不得**在本阶段生成 STMT/AC/场景或裁决场景身份;**不得**铸/改 REQ/FEAT 号。
241
230
 
242
- **完整流程示例(路径 A — KB 驱动)**:
243
- ```
244
- # 对每个能力域按 canonicalKey 查 KB
245
- resolve(canonicalKey=CAP-ACCOUNT-LOCKOUT) → RELATED_ONLY (reviewRequired)
246
- → candidates[0]: entity-id=90c49a72, version=d6787d6e (来自 KB current)
247
- → 用户确认复用 → modified, predecessor=d6787d6e
248
- resolve(canonicalKey=CAP-PHONE-LOGIN) → RELATED_ONLY (reviewRequired)
249
- → candidates[0]: entity-id=xxx, version=yyy (来自 KB current)
250
- → 用户确认复用 → modified, predecessor=yyy
251
- resolve(canonicalKey=CAP-USER-REGISTRATION) → CREATE_NEW
252
- → KB 中无此 canonicalKey
253
- → added, 新 CAP-USER-REGISTRATION
254
- ```
231
+ **示例**:已有明确实体身份 → 在线核对当前版本 → 保留真实继承关系;仅相似候选 → 参考内容,不自动继承;断连 → 继续本地草稿,远程身份待确认。
255
232
 
256
- **完整流程示例(路径 B — archive 降级)**:
257
- ```
258
- # 扫描归档(仅 KB degraded 时)
259
- Read openspec/changes/archive/*/proposal.md 的能力分解章节
260
- Read openspec/changes/archive/*/ontology/ontology-identities.json
261
-
262
- # 匹配结果示例:
263
- # "账号锁定从内存迁到DB" → 匹配归档 CAP-ACCOUNT-LOCKOUT (entity-id: 3d18c60e, version: 29e7f242)
264
- # → modified, 复用 entity-id=3d18c60e, predecessor=29e7f242
265
- # → ⚠️ source: archive(degraded)
266
- # "新增用户注册 API" → 无匹配
267
- # → added, 新 CAP-USER-REGISTRATION
268
- ```
233
+ ### 6.8 【自动规模判定】选择最小适用的文档形态
269
234
 
270
- ### 7. 【交互引导】文档拆分模式选择
235
+ 先读取用户需求、已知依赖和已有文档。当前 git diff 仅作辅助,需求尚未实现时不能把空 diff 当作“小需求”的证明。
271
236
 
272
- **❗ 必须主动询问用户,不得默认选择**。Full / Simple / Auto 三种模式的目录结构、适用场景与 AskUserQuestion 文案见 `./reference.md`「§7 文档拆分模式选择」。根据用户选择设置 `mode: full | simple`(Auto 按能力域数量判断),记录到 proposal.md 的 YAML frontmatter。
237
+ - 已有变更沿用原 `mode` 和目录,不自动迁移。
238
+ - 新变更只有一个清晰能力域,优先 `simple`;多个独立能力域或需要分别维护的协作契约,采用 `full`。
239
+ - 新接口、新表、文件数和行数是风险线索,不单独决定文档拆分。风险通过相关设计和验证处理。
240
+ - 写入 `mode: simple | full`,在摘要中说明一句理由;不单独询问内部模式。
241
+
242
+ ### 7. 文档形态记录
243
+
244
+ 记录上述自动选择,尊重用户明确指定。详细目录说明见 `./reference.md`「§7 文档拆分模式选择」。历史文档未设置 mode 时仍按原 Full 兼容规则读取。
273
245
 
274
246
  ### 7.5 自动判断变更类型
275
247
 
@@ -286,42 +258,25 @@ Read openspec/changes/archive/*/ontology/ontology-identities.json
286
258
 
287
259
  类型原话、判断顺序和边界见 `./reference.md`「§7.5 变更类型自动分类」。
288
260
 
289
- ### 8. 【交互引导】测试策略选择
261
+ ### 8. 【自动选择】测试策略
262
+
263
+ 沿用团队或当前变更已有策略。新变更中的复杂业务规则、状态转换、缺陷复现优先 `tdd`;一般实现采用 `impl-first` 并完成相关测试;仅正文说明或无运行行为变化时才用 `none`,仍验证格式或构建等实际受影响内容。写入 `test-strategy: tdd | impl-first | none` 并说明理由,不发起独立选择题。用户明确要求时调整;自动选择不能记录为 `user_decision`。
290
264
 
291
- **❗ 必须主动询问用户,不得默认选择**。TDD / Impl-First / None 三种策略的 DAG 结构、适用场景与 AskUserQuestion 文案见 `./reference.md`「§8 测试策略选择」。根据用户选择设置 `test-strategy: tdd | impl-first | none`,记录到 proposal.md 的 YAML frontmatter。
265
+ 详细语义见 `./reference.md`「§8 测试策略选择」。
292
266
 
293
267
  ### 9. 创建 proposal.md
294
268
 
295
269
  **以 `openspec-templates/proposal.md` 的结构为骨架**,填充内容到 `outputPath`。
296
270
 
297
- **【质量红线】生成文档必须严格遵循模板结构。**
271
+ **【质量红线】保留模板中解析必需的字段、身份、锚点和关系,按实际变更保留相关章节,不机械复制无关空表和说明。**
298
272
 
299
273
  ### 10. 质量红线自检
300
274
 
301
275
  > 写入文档前逐项确认,完整 8 项自检清单见 `./reference.md`「§10 质量红线自检清单」。如有任意一项未满足,重新生成对应章节,直至全部通过。
302
276
 
303
- ### 11. 确认文档并输出结果
304
-
305
- 生成文档后,向用户展示概要:
306
- > "已生成 proposal.md 草案,概要如下:
307
- > - 变更名称:[name]
308
- > - 核心目标:[一句话总结]
309
- > - 影响模块:[模块列表]
310
- > - 能力域:[capability 列表]
311
- >
312
- > 请确认:
313
- > - A. 确认无误,继续创建 specs
314
- > - B. 需要修改 [具体章节]
315
- > - C. 补充更多信息"
316
-
317
- 根据用户反馈:
318
- - 选择 A:保存文档,提示下一步
319
- - 选择 B/C:根据反馈修改文档
277
+ ### 11. 展示业务摘要并按授权继续
320
278
 
321
- 最终输出:
322
- - 文档路径
323
- - 内容摘要
324
- - 下一步提示:"运行 `/opsx-spec` 创建技术契约文档 (specs/<capability>/spec.md)"
279
+ 展示目标、范围、验收要点、自动选择及文档路径。只有业务口径未定、实际范围变化时集中询问;已有连续处理授权则加载 spec 技能继续。只请求 proposal 时在此结束,不额外问一次“是否批量推进”。
325
280
 
326
281
  ---
327
282
 
@@ -348,9 +303,9 @@ Read openspec/changes/archive/*/ontology/ontology-identities.json
348
303
  - `context` 和 `rules` 是约束条件,**不得出现在生成的文档中**。
349
304
  - proposal.md 聚焦【Why】,不写技术实现细节(留给 design.md),不写 API 细节(留给 specs)。
350
305
  - **Capabilities 章节是关键**:决定后续 specs 文件夹结构。
351
- - 文档写入后验证文件确实存在;每次生成都提供文档摘要,等待用户确认后再继续。
352
- - **⛔ 阶段边界**:本阶段禁止执行任何代码创建/修改操作。若用户要求处理代码,回复:「当前处于 Propose 阶段,代码操作请在完成文档后使用 `/opsx-apply` 执行。」
353
- - **⛔ 单阶段原则**:完成 proposal.md 后必须立即停止。仅提示用户下一步可运行 `/opsx-spec`,绝对禁止自动执行 spec/design/task 等后续阶段。每个阶段必须由用户主动触发。
306
+ - 文档写入后验证文件确实存在;提供业务差异摘要;已有授权则继续,只有新增业务歧义或范围变化才询问。
307
+ - **⛔ 阶段边界**:本阶段禁止执行任何代码创建/修改操作。已授权实现时,在前置文档和 check 完成后加载 apply 继续。
308
+ - **执行范围**:单阶段请求完成即停;已授权连续处理则按交互契约加载下一阶段,check 通过后方可进入 apply,不能超出授权范围。
354
309
  - **⛔ Frontmatter 规范(L7)**:YAML frontmatter 中禁止写 `#` 注释(YAML 注释在 frontmatter 中可能导致解析问题)。如需说明,在 frontmatter 之前或之后用正文描述。
355
310
  - **⛔ change-type 必采**:frontmatter 必须含 `change-type`、`change-type-source`、`change-type-confidence`、`change-type-reason`;Agent 自动判断,不为内部分类单独打断用户。
356
311
 
@@ -13,10 +13,10 @@ description: opsx-propose 的阶段强制检查点与自检清单。仅在执行
13
13
 
14
14
  - [ ] ✅ 允许:创建/编辑 proposal.md 文档、读取代码/文档作为上下文分析
15
15
  - [ ] ❌ 禁止:创建/修改任何代码文件、执行代码生成、运行测试
16
- - [ ] ⛔ 单阶段原则:完成 proposal.md 后必须立即停止,等待用户主动触发下一阶段
16
+ - [ ] **执行范围**:单阶段请求完成即停;已授权连续处理则按交互契约加载下一阶段,check 通过后方可进入 apply,不能超出授权范围。
17
17
  - [ ] 即使用户提供代码作为上下文,只用于理解需求背景,不执行任何代码操作
18
18
  - [ ] 代码实现引导用户使用 `/opsx-apply`
19
- - [ ] ⛔ 完成本阶段后绝对禁止自动继续执行 spec/design/task 等后续阶段
19
+ - [ ] **执行范围**:单阶段请求完成即停;已授权连续处理则按交互契约加载下一阶段,check 通过后方可进入 apply,不能超出授权范围。
20
20
 
21
21
  ---
22
22
 
@@ -25,8 +25,8 @@ description: opsx-propose 的阶段强制检查点与自检清单。仅在执行
25
25
  - [ ] 是否有明确的问题描述?
26
26
  - [ ] 是否有可衡量的目标?
27
27
  - [ ] 是否涉及具体模块?
28
- - [ ] 是否有时间/资源约束?
29
- - [ ] 发现缺失时主动询问用户补充("我发现以下信息还不够清晰,请补充...")
28
+ - [ ] 若用户提出时间/资源约束,是否已准确记录?没有约束无需专门追问。
29
+ - [ ] 先读取已有上下文,只对影响业务范围或验收的缺失事实集中询问;可推断的内部参数由 Agent 处理。
30
30
 
31
31
  ---
32
32
 
@@ -43,7 +43,7 @@ description: opsx-propose 的阶段强制检查点与自检清单。仅在执行
43
43
  - [ ] 文档写入后验证文件确实存在
44
44
  - [ ] proposal.md 写入后已运行 `semantic-reconcile`,`openspec/changes/<变更名称>/artifacts/proposal.ontology.json` 已存在
45
45
  - [ ] 工作态 JSON 为 `canonical=false`、`review_status=draft`,实体能够通过 `source.file/source.anchor_id/source.content_hash` 展开到 proposal.md 原文
46
- - [ ] 每次生成都提供文档摘要,等待用户确认后再继续
47
- - [ ] ⛔ **阶段边界**:本阶段禁止执行任何代码创建/修改操作;用户要求处理代码时回复「当前处于 Propose 阶段,代码操作请在完成文档后使用 `/opsx-apply` 执行。」
48
- - [ ] ⛔ **单阶段原则**:完成 proposal.md 后必须立即停止;仅提示用户下一步可运行 `/opsx-spec`,绝对禁止自动执行 spec/design/task 等后续阶段。每个阶段必须由用户主动触发。
49
- - [ ] ⛔ **CAP 身份复用**:KB 可用时按 canonicalKey 逐个 resolve 获取 entity-id(路径 A),KB degraded 时扫描归档 `ontology-identities.json`(路径 B,标注 `source: archive(degraded)`);修改既有能力已复用历史 entity-id 并设置 predecessor-version,新增能力已调用 `semantic-identity --delta-state=added`;禁止不经判定直接对所有能力调 `--delta-state=added`。
46
+ - [ ] 提供业务差异摘要;已有授权则继续,只有新增业务歧义或范围变化才询问
47
+ - [ ] 本阶段只产出文档;已授权实现时,文档和 check 完成后加载 apply 技能继续,不能跳过前置检查。
48
+ - [ ] **执行范围**:单阶段请求完成即停;已授权连续处理则按交互契约加载下一阶段,check 通过后方可进入 apply,不能超出授权范围。
49
+ - [ ] CAP 身份:在线继承有明确解析依据;离线保留已有草稿身份和真实基线,归档仅作背景参考。已知迭代但身份待核对时记录待确认项,不因连接失败重建旧对象。
@@ -0,0 +1,35 @@
1
+ # SDD 交互与执行契约
2
+
3
+ 本文件统一各阶段的交互方式;各阶段仍执行自己的解析、检查和证据记录。用户的明确范围与团队显式配置优先。
4
+
5
+ ## 用户决定结果,Agent 管理过程
6
+
7
+ - 用户只要求一个阶段(例如“只写 Spec”或单独调用 `/opsx-spec`)时,完成该阶段即停。
8
+ - 用户已要求“完成这个需求”“实现并验证”或连续处理时,在授权范围内加载下一阶段技能并继续,Simple / Full 均适用,不反复索要阶段口令。要求“完善文档”不授权实现代码。
9
+ - 连续推进仍按依赖完成文档、check、apply 和测试;check 未通过不得冒充通过。归档、入库、合并、推送、部署按用户授权分别判断,不能从“实现”推导为已授权发布。
10
+ - 只在业务目标或验收口径存在实质歧义、多个身份无法判定、真实冲突或新增外部副作用需要授权时询问。先读取用户提供的材料与现有代码,集中提出缺失事实,不把 mode、UUID、内部枚举当作业务问题。
11
+ - 自动选择文档形态和测试策略并简短说明理由;沿用已有变更的设置,不因这次默认规则重排存量目录。
12
+ - 只展示业务差异、必要决策、验证结果和剩余问题。遥测、身份分配、结构化 JSON 由工具和 Agent 维护,不让用户手填,不把自动推断伪记为用户确认。
13
+
14
+ ## 本地工作可以独立进行
15
+
16
+ - KB 是历史参考和发布基线服务。编写、设计、任务、实现、测试、本地归档可在离线状态继续;本地格式、语义和质量检查照常执行。
17
+ - 有实际查询需要时直接查询,不在每个阶段先发一次 `--check-only`。同一连续任务复用已取得的上下文;发生失败后,本轮后续可选查询默认跳过,只简短提示一次。用户重试、配置/目标变化或准备发布时重新检查。
18
+ - 未配置、断连、无权限、未安装查询技能时,记录真实原因与 `kb-status: degraded`,进入本地工作,不反复问“配置还是继续”。读取旧的 `degraded(by-user-choice)` 时继续尊重用户跳过意愿。
19
+ - 显式离线可调用 `context-client.cjs --offline`。这只跳过远程查询,不代表验证过远程基线;`--strict` 用于明确要求在线检查的调用。
20
+ - 本地原文和归档可以作为背景参考。已有草稿身份和前驱保持不变;只有标题/内容相似时,不从归档复制 ID 来宣称已获 KB 当前身份。已知迭代但远程身份未确认时,先写业务内容,登记待确认事项,发布前再解析,不能为绕过断网而重建旧对象身份。
21
+ - 发布前调用在线身份同步和服务端入库校验。旧基线先比较并合并正文;不得只改 predecessor。离线、权限不足、目标不明确或版本冲突只影响相应远程操作,不作“已发布”报告。
22
+
23
+ ## 身份与任务的呈现
24
+
25
+ - 对人用业务标题、`CAP-* / STMT-* / AC-*` 锚点和来源链接;完整 entity/version/predecessor ID 留在机器需要的元数据中。短前缀仅作显示,不能用于身份判定或截断写回。
26
+ - 当前 Markdown 身份块和归档格式继续兼容;本规则不声称已经把业务身份迁移到 sidecar。新 ID 由工具生成,旧 ID 不批量改写。
27
+ - 任务按可验证的行为或交付单元组织,保留依赖和验收,避免按每五分钟、每个字段或每次命令机械拆分。规模以实际风险和依赖判断,不能用估计的工时冒充质量证明。
28
+ - 默认聚焦当前 Capability;确有跨能力依赖时允许读取相关契约,注明依赖来源,避免全量加载或混写其他能力。多仓各自保留 Git 提交事实,共享 Spec 的关联由工具处理。
29
+
30
+ ## 文档只保留真实决策与契约
31
+
32
+ - 模板用于提示需要考虑的内容,必须保留解析字段、身份、锚点和引用关系;不为填满模板复制教程、空表、重复背景或不适用章节。简单变更直接表达目的、行为、验收、设计决定和可验证任务。
33
+ - 已有全局契约用引用复用;Spec 写行为,Design 只补实现决策,Task 只写交付单元、依赖和验收,不在四份文档重复同一解释。
34
+ - 参数边界可用表驱动验收和测试;只有行为、依赖或交付确实不同才拆任务。若项目明确采用 TDD,保留真实 RED→GREEN 证据与顺序,不机械按每个字段或输入值生成一整套任务。
35
+ - Check 的结构合法性由程序负责,模型聚焦业务覆盖与矛盾;结果按实际检查项输出,由 check-record 计算记账字段。
@@ -18,35 +18,14 @@ description: opsx-propose 的详细模板:telemetry 命令、文档拆分模
18
18
 
19
19
  ## §7 文档拆分模式选择
20
20
 
21
- **❗ 必须主动询问用户,不得默认选择**
22
-
23
- 分析需求中的能力域数量后,使用 **AskUserQuestion** 工具向用户询问:
24
-
25
- > "📋 **检测到需求包含以下能力域:**
26
- > - [能力域列表]
27
- >
28
- > 🤔 **请选择文档拆分模式:**
29
- >
30
- > **A) 完整模式 (Full)** - 每个能力域独立文档
31
- > - 目录结构:`specs/<capability>/spec.md`, `specs/<capability>/design.md`, `specs/<capability>/tasks.md`
32
- > - 适合:大需求、多人协作、需要精细管控
33
- >
34
- > **B) 简化模式 (Simple)** - 单一文档
35
- > - 目录结构:`spec.md`, `design.md`, `tasks.md`(合并所有能力域)
36
- > - 适合:小需求、单人快速迭代
37
- >
38
- > **C) 自动判断** - 根据能力域数量自动选择
39
- > - 单个能力域 → Simple 模式
40
- > - 多个能力域 → Full 模式"
41
-
42
- 根据用户选择:
43
- - 选择 A:设置 `mode: full`
44
- - 选择 B:设置 `mode: simple`
45
- - 选择 C:根据能力域数量自动判断并设置
46
-
47
- **将用户选择记录到 proposal.md 的 YAML frontmatter 中。**
21
+ Agent 根据能力边界自动判断,无需单独询问。已有 mode 和用户明确选择优先。
48
22
 
49
- ---
23
+ | 形态 | 目录 | 默认用途 |
24
+ |---|---|---|
25
+ | Simple | 根目录 spec.md / design.md / tasks.md | 单一能力域 |
26
+ | Full | specs/<capability>/ 下分别维护三份文档 | 多能力域或需要独立协作的契约 |
27
+
28
+ 新接口、新表和代码行数不自动增加人工确认。未设置 mode 的存量文档仍按 Full 读取,不自动迁移。
50
29
 
51
30
  ## §7.5 变更类型自动分类
52
31
 
@@ -79,26 +58,13 @@ Agent 应在 proposal 正文或完成摘要中展示中文分类及理由,但
79
58
 
80
59
  ## §8 测试策略选择
81
60
 
82
- **❗ 必须主动询问用户,不得默认选择**
83
-
84
- 三种策略:
85
- - A) TDD(红绿重构循环):每个行为点先写失败测试再写最少代码,任务量 3-5 倍
86
- - B) Impl-First(代码先行):先实现再补测试验证
87
- - C) None(仅实现):不生成测试任务
88
-
89
- 使用 **AskUserQuestion** 工具向用户询问(A/B/C 三选一)。
61
+ 沿用团队/当前变更配置;新变更自动选择并说明理由,不单独询问内部枚举。
90
62
 
91
- 根据用户选择:
92
- - 选择 A:设置 `test-strategy: tdd`
93
- - 选择 B:设置 `test-strategy: impl-first`
94
- - 选择 C:设置 `test-strategy: none`
63
+ - `tdd`:复杂业务行为、状态转换或需要稳定复现的缺陷。保留真实 RED→GREEN 证据。
64
+ - `impl-first`:一般实现,配套相关测试与构建验证。
65
+ - `none`:仅文档等不改变运行行为的变更;保留实际适用的验证,不能借此跳过业务测试。
95
66
 
96
- **将用户选择记录到 proposal.md 的 YAML frontmatter 中。**
97
-
98
- > 完整策略定义见 tdd-core/SKILL.md §5
99
- > 交互引导文案见 tdd-rules/rules/tdd-strategy-selection.md
100
-
101
- ---
67
+ 用户可纠正;自动判断不是用户决策,不能伪记为 `user_decision`。
102
68
 
103
69
  ## §10 质量红线自检清单
104
70
 
@@ -15,22 +15,23 @@ allowed-tools:
15
15
  - Edit
16
16
  ---
17
17
 
18
+ > **执行方式**:先读 [交互与执行契约](../opsx-propose/interaction-policy.md);同一会话已读则复用。用户已授权连续处理时按范围推进,不重复索要阶段口令;只请求单阶段时完成即停。
19
+
18
20
  你是一个 SDD(Specification-Driven Development)技术契约专家。激活本技能后,你将引导用户为每个 Capability 创建 **spec.md** 文档。
19
21
 
20
- > **硬依赖**:场景身份 / Spec 复用依赖同级已部署的 **`opsx-ontology-query`**。进入知识库上下文步骤前必须先 `Read` 该技能的 `SKILL.md` 并完成其 Session 启动(API Key + targets → `kb-state.json`,spec 仓根目录)。缺失则停止复用查询,提示重新 `kld-sdd-init`;**KB 可用时禁止**从本地 `archive/` 抄 UUID,entity-id 必须来自 KB resolve by canonicalKey。
22
+ > **KB 查询依赖**:需要复用时加载 `opsx-ontology-query`;缺失只跳过查询,不阻断正文编写。远程继承以在线解析结果为准。
21
23
  >
22
- > **📡 KB 就绪检查**:§2.5 在进入上下文加载前会检测 KB 配置状态。若未配置,会**主动询问**用户选择「配置」或「跳过」,不再静默降级。
24
+ > **KB 使用**:按共享交互契约复用本轮上下文,不重复询问配置。
23
25
 
24
26
  > **⚠️ 阶段边界约束**
25
27
  >
26
28
  > 当前处于 **Spec(契约)阶段**:
27
29
  > - ✅ **允许**:创建/编辑 spec.md 文档、读取代码/文档作为上下文分析
28
30
  > - ❌ **禁止**:创建/修改任何代码文件、执行代码生成、运行测试
29
- > - ⛔ **单阶段原则**:完成 spec.md 后**必须立即停止**,等待用户主动触发下一阶段
31
+ > - **执行范围**:单阶段请求完成即停;已授权连续处理则按交互契约加载下一阶段,check 通过后方可进入 apply,不能超出授权范围。
30
32
  >
31
33
  > 即使用户提供了代码作为上下文,也只用于分析现有实现,**不执行任何代码操作**。
32
34
  > 代码实现将在 `/opsx-apply` 阶段进行。
33
- > **完成本阶段后,绝对禁止自动继续执行 design/task 等后续阶段。**
34
35
  > 阶段边界自检见 `./checklist.md`「阶段边界⛔」。
35
36
 
36
37
  > **🖥️ 跨平台执行规则**
@@ -97,48 +98,13 @@ openspec list
97
98
  ```
98
99
  若变更不存在,引导用户先运行 `/opsx-propose <name>`。
99
100
 
100
- ### 2. 【交互引导】确认 Capability
101
-
102
- 读取 `proposal.md` 中定义的 Capabilities 列表:
103
-
104
- 使用 **AskUserQuestion** 让用户选择要编写规格的 Capability:
105
- > "📋 **proposal.md 中定义的能力域:**
106
- > - A. `user-auth` - 用户认证
107
- > - B. `data-export` - 数据导出
108
- > - C. 全部(按顺序逐个创建)
109
- >
110
- > 请选择要为哪个 Capability 创建 spec.md:"
111
-
112
- ### 2.5 【KB 就绪检查】检测并配置知识库连接
101
+ ### 2. 确定本次 Capability 范围
113
102
 
114
- 在进入上下文加载之前,检测 Engineering KB 的连接状态。**不得静默降级**。
103
+ 从用户请求和 proposal 读取范围。只有一个 Capability 或用户已要求全部处理时自动选中;多个能力域且本次范围不明确时才询问。
115
104
 
116
- 1. 检查 proposal.md frontmatter 中 `kb-status` 字段:
117
- - 若 `kb-status: degraded(by-user-choice)` → KB 已在 propose 阶段由用户明确跳过,本阶段同样跳过 KB 查询,直接进入 §3(仅加载本地上下文)。
118
- - 若未标记 → 继续检查。
119
- 2. 运行 KB 就绪检查(程序化检测,自动搜索多 IDE 目录,消除路径歧义):
120
- ```bash
121
- node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" --check-only
122
- ```
123
- - 输出 `"available": true` → KB 已配置
124
- - 输出 `"available": false` → KB 未配置
105
+ ### 2.5 KB 上下文状态
125
106
 
126
- > **注意**:KB 就绪检查(`--check-only`)与 KB 上下文查询(`match-requirement`)是两个独立步骤。即使 Continuity=new 无需上下文查询,**仍需执行 `--check-only`** 确认 KB 可用性,以便在 sdd-output.md 中记录 KB 状态。
127
-
128
- 3. **若已配置** → 直接进入 §3。
129
- 4. **若未配置** → 使用 **AskUserQuestion** 询问:
130
-
131
- > "📡 **知识库未配置**
132
- >
133
- > 知识库可以帮你验证场景身份、复用已有 Spec 和检索历史验收标准。现在要配置吗?
134
- >
135
- > - A. **现在配置** — 运行 /opsx-kb-config
136
- > - B. **暂不配置,先继续** — 仅用本地数据(精度有限)
137
- > - C. **取消** — 终止本次操作"
138
-
139
- - **选 A** → 引导运行 `/opsx-kb-config`,配置完成后进入 §3。
140
- - **选 B** → 在 spec.md frontmatter 标注 `kb-status: degraded(by-user-choice)`,进入 §3(仅本地上下文)。
141
- - **选 C** → 终止 spec。
107
+ 复用本轮已取得的 KB 上下文。有新的复用问题时直接执行 §3 查询,不在各阶段重复 `--check-only`。本轮已降级或用户明确离线时,记录 `kb-status: degraded` 和原因,仅加载本地上下文。未配置、断连和无权限不能被当作“确认没有历史身份”,也不触发配置问答。
142
108
 
143
109
  ### 3. 【上下文加载】识别并读取用户提供的文件
144
110
 
@@ -148,7 +114,7 @@ openspec list
148
114
 
149
115
  **【默认尝试】工程 Spec 知识库上下文(场景身份主战场)**:
150
116
 
151
- 1. **先加载依赖技能**:确认 `${AGENT_SKILL_DIR}/opsx-ontology-query/SKILL.md` 存在并 Read;按该技能完成 API Key / targets(`kb-state.json`,spec 仓根目录,与 `opsx-kb-ingest` 共用)。未安装则停止本步。
117
+ 1. **先加载依赖技能**:确认 `${AGENT_SKILL_DIR}/opsx-ontology-query/SKILL.md` 存在并 Read;使用已有 API Key / target(`kb-state.json`);未配置或未安装仅跳过远程查询,继续正文编写。
152
118
  2. 读取 proposal Continuity。对**当前 Capability** 各调一次(「全部」= 循环 N 次,不是一次大查询)——优先走 **`opsx-ontology-query`** 的 `match-requirement`;薄封装仅作参数拼装:
153
119
 
154
120
  ```bash
@@ -234,22 +200,9 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" \
234
200
 
235
201
  > 写入文档前逐项确认,完整 7 项自检清单见 `./checklist.md`「§7 质量红线自检」。自检完成后**必须**输出结构化自检报告(模板见 `./reference.md`「§7 质量自检报告模板」),未通过项自动修复后重新输出,直至全部 ✅。
236
202
 
237
- ### 8. 确认文档并输出结果
238
-
239
- 生成文档后,向用户展示概要:
240
- > "已生成 spec.md,概要如下:
241
- > - Capability:[name]
242
- > - 需求项数量:[N]
243
- > - 场景数量:[M]
244
- >
245
- > 请确认:
246
- > - A. 确认无误,继续下一个 Capability 的 spec / 进入 design
247
- > - B. 需要修改
248
- > - C. 补充更多信息"
203
+ ### 8. 展示可审阅的业务差异
249
204
 
250
- 最终输出:
251
- - 文档路径
252
- - 下一步提示:"运行 `/opsx-design <name> <capability>` 创建技术设计文档"
205
+ 展示新增/修改的规则、验收条件、来源和未决问题,完整 UUID 不放在面向用户的摘要中。已授权连续处理时完成范围内 Capability 后加载 design;单阶段请求在此结束。只在业务歧义或真实身份冲突时询问,不再追加“批量推进”选择题。
253
206
 
254
207
  ---
255
208
 
@@ -259,7 +212,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" \
259
212
  - 新需求、场景和约束分别使用 `STMT-*`、`AC-*`、`CON-*`;分配规则是同前缀同 Capability 当前最大序号 + 1。
260
213
  - 修改已有实体必须复用原 ID;删除实体只写 removal 语义,不得把编号分配给新实体。
261
214
  - `added` 必须调用 `semantic-identity --delta-state=added` 生成新的实体 UUID 和版本 UUID;禁止通过复制另一需求的 UUID 创建新实体。
262
- - `modified/removed` 必须从 **KB**(resolve by canonicalKey / match-requirement)取得历史 `entity-id` 和直接前序 `version-id`,调用 `semantic-identity --delta-state=<modified|removed> --entity-id=<UUID> --predecessor-version=<UUID>`;实体 UUID 复用,版本 UUID 新建。KB degraded 时可从 archive `ontology-identities.json` 只读(标注 `source: archive(degraded)`),但 **KB 可用时禁止**把本地 archive 当跨迭代继承权威。
215
+ - `modified/removed` 保留已明确的 `entity-id` 和真实 `predecessor-version`;在线解析当前版本后由工具分配版本。离线可以继续正文,未确认的远程身份登记为待核对,发布前解决;不能从相似归档复制 UUID 或把最新版本编号直接当作实际编辑基线。
263
216
  - AC 必须嵌套在所属 STMT 下;CON 必须通过 `**constrains**` 显式引用 STMT。
264
217
  - 对 `reuseMode=REFERENCE` 的历史候选必须创建新的实体身份;禁止因为内容相似而复用历史 `entity-id`。
265
218
  - 对 `reuseMode=INHERIT` 的历史事实,必须使用返回的实体与版本来源完成 unchanged/modified 身份参数校验。
@@ -277,7 +230,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" \
277
230
  - **需求项格式必须正确**:`####` 需求项、`#####` 场景;每个需求项必须有清晰的验收标准。
278
231
  - 技术契约必须可执行、无歧义。
279
232
  - **⛔ 阶段边界**:禁止执行任何代码创建/修改操作。
280
- - **⛔ 单阶段原则**:完成 spec.md 后必须立即停止。仅提示用户下一步可运行 `/opsx-design`,绝对禁止自动执行 design/task 等后续阶段。每个阶段必须由用户主动触发。
233
+ - **执行范围**:单阶段请求完成即停;已授权连续处理则按交互契约加载下一阶段,check 通过后方可进入 apply,不能超出授权范围。
281
234
 
282
235
  ---
283
236
 
@@ -13,10 +13,10 @@ description: opsx-spec 的阶段强制检查点与自检清单。仅在执行 sp
13
13
 
14
14
  - [ ] ✅ 允许:创建/编辑 spec.md 文档、读取代码/文档作为上下文分析
15
15
  - [ ] ❌ 禁止:创建/修改任何代码文件、执行代码生成、运行测试
16
- - [ ] ⛔ 单阶段原则:完成 spec.md 后必须立即停止,等待用户主动触发下一阶段
16
+ - [ ] **执行范围**:单阶段请求完成即停;已授权连续处理则按交互契约加载下一阶段,check 通过后方可进入 apply,不能超出授权范围。
17
17
  - [ ] 即使用户提供代码作为上下文,只用于分析现有实现,不执行任何代码操作
18
18
  - [ ] 代码实现将在 `/opsx-apply` 阶段进行
19
- - [ ] ⛔ 完成本阶段后绝对禁止自动继续执行 design/task 等后续阶段
19
+ - [ ] **执行范围**:单阶段请求完成即停;已授权连续处理则按交互契约加载下一阶段,check 通过后方可进入 apply,不能超出授权范围。
20
20
  - [ ] 工程知识库未配置、超时或降级时继续 Spec 主流程,不阻塞本地创作
21
21
 
22
22
  ---
@@ -51,4 +51,4 @@ description: opsx-spec 的阶段强制检查点与自检清单。仅在执行 sp
51
51
  - [ ] 技术契约必须可执行、无歧义
52
52
  - [ ] 工程知识库结果只作为 advisory 上下文,不覆盖用户输入或 proposal.md
53
53
  - [ ] ⛔ **阶段边界**:禁止执行任何代码创建/修改操作
54
- - [ ] ⛔ **单阶段原则**:完成 spec.md 后必须立即停止;仅提示用户下一步可运行 `/opsx-design`,绝对禁止自动执行 design/task 等后续阶段。每个阶段必须由用户主动触发。
54
+ - [ ] **执行范围**:单阶段请求完成即停;已授权连续处理则按交互契约加载下一阶段,check 通过后方可进入 apply,不能超出授权范围。
@@ -14,6 +14,8 @@ allowed-tools:
14
14
  - Edit
15
15
  ---
16
16
 
17
+ > **执行方式**:先读 [交互与执行契约](../opsx-propose/interaction-policy.md);同一会话已读则复用。用户已授权连续处理时按范围推进,不重复索要阶段口令;只请求单阶段时完成即停。
18
+
17
19
  你是一个 SDD(Specification-Driven Development)任务拆解专家。激活本技能后,你将引导用户为**单一 Capability** 创建 DAG 任务清单。
18
20
 
19
21
  > **⚠️ 阶段边界约束**
@@ -21,21 +23,13 @@ allowed-tools:
21
23
  > 当前处于 **Task(任务拆解)阶段**:
22
24
  > - ✅ **允许**:创建/编辑 tasks.md 文档、读取代码作为任务分析参考
23
25
  > - ❌ **禁止**:创建/修改任何代码文件、执行代码生成、运行测试
24
- > - ⛔ **单阶段原则**:完成 tasks.md 后**必须立即停止**,等待用户主动触发下一阶段
26
+ > - **执行范围**:单阶段请求完成即停;已授权连续处理则按交互契约加载下一阶段,check 通过后方可进入 apply,不能超出授权范围。
25
27
  >
26
28
  > tasks.md 定义的是「待执行的任务清单」,**不是立即执行代码**。
27
29
  > 请引导用户使用 `/opsx-apply` 进入实施阶段。
28
- > **完成本阶段后,绝对禁止自动继续执行 apply/check 等后续阶段。**
29
30
  > 阶段边界自检见 `./checklist.md`「阶段边界⛔」。
30
31
 
31
- > **KB 上下文**:任务拆解时可参考历史任务分解策略。
32
- > 1. 检查 proposal.md frontmatter `kb-status`:若 `degraded(by-user-choice)` → 跳过 KB,仅用本地上下文。
33
- > 2. 否则运行 KB 就绪检查:
34
- > ```bash
35
- > node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" --check-only
36
- > ```
37
- > - `"available": true` → 若需查历史任务参考,先 `Read` `opsx-ontology-query/phase-2-during.md` §2
38
- > - `"available": false` → **KB 不可用不阻塞 task 流程**,仅跳过历史任务追溯参考
32
+ > **KB 上下文**:仅在需要历史任务参考时查询,优先复用本轮已有结果;不逐阶段执行 `--check-only`。未配置、断连或无权限时记录原因,继续本地流程,不重复询问配置。
39
33
 
40
34
  > **⚠️ 渐进式上下文加载原则**
41
35
  >
@@ -44,7 +38,7 @@ allowed-tools:
44
38
  > - **输出路径**(Full 模式):`changes/<name>/specs/<capability>/tasks.md`
45
39
  > - **输入路径**(Simple 模式):`changes/<name>/design.md`
46
40
  > - **输出路径**(Simple 模式):`changes/<name>/tasks.md`
47
- > - ⛔ **隔离红线**:绝对禁止跨目录读取同级其他 Capability 的文档(Full 模式)
41
+ > - ⛔ **隔离红线**:默认聚焦当前 Capability;为核对已声明依赖可读取相关 Capability 契约并注明来源,不全量加载或混写其他能力。
48
42
 
49
43
  > **🖥️ 跨平台执行规则**
50
44
  > - **SDD 文档根** = `*-sdd-specs` 包裹包(含 `openspec/`、`modules.yaml`),不是 Git 根或工作区根。
@@ -64,7 +58,7 @@ allowed-tools:
64
58
  | 核心问题 | Do - 单一 Capability 具体做什么任务 |
65
59
  | 关键输出 | 局部 tasks.md(DAG 拓扑图 + 原子任务清单) |
66
60
  | 上游依赖 | overview.md → proposal.md → 当前 capability 的 spec.md → design.md |
67
- | 质量要求 | 每个任务 5 分钟可完成,100% 覆盖 design,DAG 无循环依赖 |
61
+ | 质量要求 | 每个任务可独立验证,100% 覆盖 design,DAG 无循环依赖 |
68
62
 
69
63
  ---
70
64
 
@@ -111,7 +105,7 @@ Simple 模式或单文件能力域下,**不要拆成多个同文件任务**。
111
105
  → changes/<name>/specs/<capability>/spec.md
112
106
  → changes/<name>/specs/<capability>/design.md
113
107
 
114
- ⛔ 隔离红线:禁止读取其他 Capability 的文档!
108
+ ⛔ 隔离红线:默认聚焦当前 Capability;为核对已声明依赖可读取相关 Capability 契约并注明来源,不全量加载或混写其他能力。
115
109
  ```
116
110
 
117
111
  ### 3. 【关键步骤】读取本地模板文件
@@ -153,7 +147,7 @@ Simple 模式或单文件能力域下,**不要拆成多个同文件任务**。
153
147
 
154
148
  ### 6. 【交互引导】确认任务拆解策略
155
149
 
156
- 向用户确认拆解维度、任务粒度、预计 DAG 层级。**根据 test-strategy 调整 DAG 生成规则**,规则表(tdd / impl-first / none 对应的 DAG 生成规则)见 `./reference.md`「§6 DAG 生成规则表」。
150
+ 依据已授权需求和真实依赖选择拆解维度、任务粒度与 DAG;只就业务歧义询问。**根据 test-strategy 调整 DAG 生成规则**,规则表(tdd / impl-first / none 对应的 DAG 生成规则)见 `./reference.md`「§6 DAG 生成规则表」。
157
151
 
158
152
  **当 test-strategy=tdd 时,必须向用户说明:**
159
153
  > "🧪 TDD 模式将采用红绿重构循环:
@@ -177,7 +171,7 @@ Simple 模式或单文件能力域下,**不要拆成多个同文件任务**。
177
171
  **当 test-strategy=tdd 时,任务生成规则:**
178
172
 
179
173
  ⛔ 核心规则(inline):
180
- 1. 每个场景拆为一个行为点,每个行为点生成一对 RED+GREEN 任务
174
+ 1. 同一行为的输入边界合并为表驱动场景;按独立行为生成 RED+GREEN 任务,保留所有验收变体
181
175
  2. RED 验收标准必须包含"测试运行失败且失败原因正确"
182
176
  3. GREEN 验收标准必须包含"写最少代码让对应 RED 测试通过",禁止捆绑
183
177
  4. GREEN 不得包含未测试的 Controller/Filter/Config
@@ -197,9 +191,34 @@ Simple 模式或单文件能力域下,**不要拆成多个同文件任务**。
197
191
  > 非 TDD 模块定义见 tdd-rules/rules/non-tdd-modules.md
198
192
  > 任务类型定义见 tdd-rules/rules/task-type-definitions.md
199
193
 
194
+ **【新增】任务自动分层标注**
195
+
196
+ 每个任务在生成时应自动标注 `layer` 字段(从 TASK-ID 后缀或描述推断):
197
+
198
+ | Layer | 后缀模式 | 任务类型 | 隐式依赖 |
199
+ |-------|---------|---------|---------|
200
+ | 0 | `-DEPS` / `-CONFIG` / `-CONST` | 依赖配置、常量定义、工具类 | 无 |
201
+ | 1 | `-ENTITY` / `-DTO` / `-ENUM` / `-VO` | 实体类、DTO、枚举、值对象 | Layer 0 |
202
+ | 2 | `-MAPPER` / `-REPO` / `-DAO` | Mapper、Repository、DAO | Layer 1 |
203
+ | 3 | `-SERVICE-IF` / `-IF` | Service 接口 | Layer 1-2 |
204
+ | 4 | `-IMPL` / `-SERVICE` / `-HANDLER` | Service 实现、处理器 | Layer 3 |
205
+ | 5 | `-CONTROLLER` / `-API` / `-RESOURCE` | Controller、API、使用方 | Layer 4 |
206
+ | 6 | `-TEST` / `-VERIFY` / `-VALIDATE` | 测试、验证 | Layer 5 |
207
+
208
+ **分层标注规则**:
209
+ 1. 在 tasks.md 每个任务的 YAML frontmatter 或属性区写入 `layer: N`
210
+ 2. 若 TASK-ID 已明确包含类型后缀(如 `-ENTITY`),优先按后缀推断
211
+ 3. 若 TASK-ID 无明确后缀,从任务描述中提取关键词推断
212
+
213
+ **警告提示(非阻断)**:
214
+ - 任务生成完成后,扫描所有任务的 layer 和 dependsOn
215
+ - 若 Layer N 任务未显式声明对同 Capability 中任意 Layer < N 任务的 `dependsOn`,在概要中提示:
216
+ > "⚠️ 检测到 [N] 个任务可能存在隐式依赖缺失(高 Layer 任务未依赖低 Layer 定义方任务),建议检查 DAG 拓扑。"
217
+ - 不阻断任务生成,用户仍可选择 A(确认)/B(调整)/C(忽略警告继续)
218
+
200
219
  ### 8. 质量红线自检
201
220
 
202
- > 逐项确认,完整 7 项自检清单 + TDD 合规性自检(结构符合模板 / 拓扑图已绘制 / 依赖字段已填写 / 无循环依赖 / 颗粒度 ≤5 分钟 / 100% 覆盖 design / 每任务有验收标准)见 `./checklist.md`「§8 质量红线自检 + §8.1 TDD 合规性自检」。
221
+ > 逐项确认,完整 7 项自检清单 + TDD 合规性自检(结构符合模板 / 拓扑图已绘制 / 依赖字段已填写 / 无循环依赖 / 按可验证交付单元拆分 / 100% 覆盖 design / 每任务有验收标准)见 `./checklist.md`「§8 质量红线自检 + §8.1 TDD 合规性自检」。
203
222
  >
204
223
  > 额外强制项(见 `./checklist.md` §8):
205
224
  > - ⛔ **CON 覆盖**:spec.md 中每个 CON 必须有对应验证任务或显式声明间接覆盖
@@ -208,22 +227,9 @@ Simple 模式或单文件能力域下,**不要拆成多个同文件任务**。
208
227
  >
209
228
  > 如有任意一项未满足,重新生成对应章节,直至全部通过。
210
229
 
211
- ### 9. 确认任务并输出
212
-
213
- 展示任务概要:
214
- > "已生成 tasks.md,概要如下:
215
- > - 任务总数:[N]
216
- > - DAG 层级数:[M]
217
- > - 测试策略:[strategy]
218
- >
219
- > 请确认:
220
- > - A. 确认无误
221
- > - B. 需要调整拆解粒度
222
- > - C. 需要修改依赖关系"
230
+ ### 9. 展示任务差异并继续
223
231
 
224
- 最终输出:
225
- - 文档路径
226
- - 下一步提示:"下一步:运行 `/opsx-check <name>` 完成质量检查,通过后再 `/opsx-apply <name> <capability>` 开始实施"
232
+ 展示关键任务决定、依赖、验收和未决问题。Agent 能确定的缺失字段或依赖先自行修复;实质业务歧义再集中询问。已授权连续处理时加载下一阶段 `/opsx-check`,检查通过后才进入已授权的 `/opsx-apply`。单阶段请求完成即停,不重复询问模式或后续阶段口令。
227
233
 
228
234
  ---
229
235
 
@@ -244,11 +250,11 @@ Simple 模式或单文件能力域下,**不要拆成多个同文件任务**。
244
250
 
245
251
  - **必须以 `openspec-templates/tasks.md` 为模板基准**。
246
252
  - **⛔ 渐进式加载**:严格按 overview.md → proposal.md → spec.md → design.md 顺序。
247
- - **⛔ 隔离红线**:绝对禁止读取同级其他 Capability 的文档。
253
+ - **⛔ 隔离红线**:默认聚焦当前 Capability;为核对已声明依赖可读取相关 Capability 契约并注明来源,不全量加载或混写其他能力。
248
254
  - **⛔ DAG 必须完整**:每个任务必须有依赖字段;**⛔ 无循环依赖**:DAG 中不允许存在环。
249
- - 任务颗粒度宁可过细也不要过粗。
255
+ - 任务粒度以可验证结果和真实依赖为准,避免按字段或命令机械拆分。
250
256
  - **⛔ 阶段边界**:禁止执行任何代码创建/修改操作。
251
- - **⛔ 单阶段原则**:完成 tasks.md 后必须立即停止。仅提示用户下一步 **check 优先**:先运行 `/opsx-check` 通过质量检查,再 `/opsx-apply`(apply 须在 check 通过后);绝对禁止自动执行 apply/check 等后续阶段。每个阶段必须由用户主动触发。
257
+ - **执行范围**:单阶段请求完成即停;已授权连续处理则按交互契约加载下一阶段,check 通过后方可进入 apply,不能超出授权范围。
252
258
 
253
259
  ---
254
260