kld-sdd 2.7.3 → 2.7.8-2

package/templates/skills/kld-sdd/opsx-apply/SKILL.md

@@ -17,6 +17,8 @@ allowed-tools:
   - Agent
 ---
 
+> **执行方式**：先读 [交互与执行契约](../opsx-propose/interaction-policy.md)；同一会话已读则复用。用户已授权连续处理时按范围推进，不重复索要阶段口令；只请求单阶段时完成即停。
+
 你是一个 SDD（Specification-Driven Development）变更实施专家。激活本技能后，你将引导用户按 DAG 依赖顺序逐任务实施代码。
 
 
@@ -24,7 +26,7 @@ allowed-tools:
 >
 > - 本技能针对**单一 Capability** 执行实施
 > - **上下文**：overview.md → proposal.md → 当前 capability 的 spec/design/tasks
-> - ⛔ **隔离红线**：绝对禁止加载同级其他 Capability 的文档
+> - ⛔ **隔离红线**：默认聚焦当前 Capability；为核对已声明依赖可读取相关 Capability 契约并注明来源，不全量加载或混写其他能力。
 
 > **🖥️ 跨平台执行规则**
 > - **写代码**：cwd 保持在 Git 根（含 `src/`）；**文档 / telemetry**：`--project` 指向 SDD 包裹包（`node <spec-package>/skywalk-sdd/spec-root.cjs` 可获取）。
@@ -38,6 +40,7 @@ allowed-tools:
 > - 较大的 `--details-json` 负载可先写入文件，再通过 `--details-file="$(cat .sdd-spec-root)/skywalk-sdd/state/<变更名称>-<type>.json"` 传递（例如 `task_update` 对应 `<变更名称>-task-update.json`）。
 > - `task_update` 记录成功后会自动调用 `check-task` 更新 `tasks.md` 中的 checkbox；录入成功后，agent 可以通过 `check-task` 命令验证该 checkbox 已更新。
 > - **⚠️ P1-2 ai_adoption_review 必填 ai_diff**：记录 AI 产出快照时，`--details-json` 必须含 `ai_diff.files_changed`（即使=0）与 `ai_diff.files`（产出文件路径数组，非空），**不得只发 `assertions`**。`vcs_mode=readonly` 时 `ai_diff.added_lines` 不得为 null——用只读 `git diff --numstat HEAD` 取值（apply Git 只读策略允许）；`vcs_mode=no-git` 时可填 null。工具侧已加记录时硬校验：`files` 空数组或 `readonly` 下 `added_lines=null` 将 **拒绝记录**（与 conformance_review 校验对称）。缺失 `ai_diff` 会导致 report 变更文件数为 null（工具侧已加 `assertions[].files` 兜底，但 `ai_diff` 是主数据源）。完整模板见 `./reference.md`「§5.1」。
+> - **默认测试入口**：使用 reference.md 中的 test-run 执行、采集和关联真实证据；可用 completion-file 同步已验证任务。不手填退出码、测试计数和耗时。
 > - **严格证据链**：一次真实测试执行只写一条严格 `test_result`；任务完成事件只通过 `test_event_id` 引用成功的 green/refactor/regression 测试，并明确 `tdd_required=true/false`，不复制测试计数。测试不适用时必须写明原因。完整 schema 见 `./reference.md`。
 > - **任务涉及文件必记**：每条严格 `task_update` 必须在 `task_update.files` 写本任务实际修改的仓库相对路径；本任务确实没有改文件时，改填具体的 `no_file_change_reason`。两者至少有一个。
 > - **最终交付文件必记**：apply 所有文件就绪后记录严格 `final_output_snapshot`，其中 `final_output_snapshot.files` 是最终交付文件的仓库相对路径清单。报告把它与逐任务文件分开说明；旧 `ai_adoption_review.ai_diff.files` 只作兼容来源。
@@ -116,12 +119,40 @@ openspec list --json
 > - **Capability**：`<capability-name>`
 > - **任务文件**：`changes/<name>/specs/<capability>/tasks.md`"
 
-### 1.2 【Check 门禁检查】验证质量门禁状态
+### 1.5 【非阻断】编译依赖预检
+
+读取当前 Capability 的 tasks.md 中所有 IMPL/CONTROLLER 任务的描述，提取：
+1. 使用的注解（@PreAuthorize, @Transactional, @Valid, @Mapper 等）
+2. 导入的框架类（spring-security, mybatis, validation 等）
+3. 与当前 pom.xml（或 build.gradle）已声明依赖做对比
+
+**预检输出格式**（仅警告，不拦截 apply）：
+> "📋 **编译依赖预检**（非阻断）
+>
+> | 检查项 | 状态 | 详情 |
+> |--------|------|------|
+> | @PreAuthorize 依赖 | ⚠️ | spring-boot-starter-security 未在 pom.xml 中声明 |
+> | @Transactional 依赖 | ✅ | spring-tx 已声明 |
+> | @Mapper 依赖 | ✅ | mybatis 已声明 |
+>
+> 建议：若上述缺失依赖确需使用，可在 Layer 0 补充依赖配置任务，或确认现有构建文件已包含。
+>
+> 请选择：
+> - **A. 忽略警告，继续 apply**（默认）
+> - **B. 暂停，先补充依赖任务**
+> - **C. 确认 pom.xml 已包含（预检误报）**"
+
+**预检规则**：
+- 只扫描 tasks.md 中任务描述文本，不扫描实际代码（apply 前代码可能尚未生成）
+- 依赖映射表维护常用注解→Maven/Gradle 依赖的对应关系（见 `./reference.md`「§1.5a 注解依赖映射表」）
+- 误报时用户选择 C，记录 `process_note(kind=user_decision, decision_type=ignore_dependency_warning)`
+
+### 1.6 【Check 门禁检查】验证质量门禁状态
 
 > **⛔ 强制门禁**：apply 阶段开始前，必须确认 check 阶段已完成。这是 SDD 流程的关键质量保障。
 > 详细检查步骤、判定与门禁体系说明见 `./checklist.md`「§1.2 Check 门禁」。未完成强制拒绝。${HOOK_GATE_DESCRIPTION}
 
-### 1.5 【本地并行】Worktree 与工作区（建议性策略）
+### 1.7 【本地并行】Worktree 与工作区（建议性策略）
 
 > **目标（本质）**：在**本地仓库**加快 SDD Apply——让**解耦**的 spec/capability 可以各自实现、互不踩目录，做完再按依赖顺序合并回你**当时所在的分支**（集成分支，如 `hotfix-1`）。
 >
@@ -153,7 +184,7 @@ openspec list --json
 第 3 层：当前 Capability 四文档
   → spec.md → design.md → tasks.md
 
-⛔ 隔离红线：禁止加载其他 Capability 的文档！
+⛔ 隔离红线：默认聚焦当前 Capability；为核对已声明依赖可读取相关 Capability 契约并注明来源，不全量加载或混写其他能力。
 ```
 
 **【可选】业务知识库检索**：
@@ -267,7 +298,14 @@ g. **继续下一个层级** — 重新检查 DAG，找出依赖已满足的下
 > - 已完成：[N/M] 任务
 > - 当前层级：Layer [X]
 > - 下一步建议：[继续实施 / 运行测试 / 归档]"
->
+
+**【已授权连续处理完成】**
+若本次为用户已授权的连续处理，完成时展示一次整体交付结果：
+> "✅ **本轮连续处理完成**
+> - propose → spec → design → task → check → apply 已全部执行完毕
+> - 各阶段文档已生成，质量门禁已执行
+> - 建议下一步：运行测试 / 归档变更"
+
 > **💡 代码评审提示**：
 > 建议执行 `/kld-review --local` 对本次变更的代码进行评审。
 > 该技能可在公司内部 SkillHub 下载安装。
@@ -295,7 +333,7 @@ g. **继续下一个层级** — 重新检查 DAG，找出依赖已满足的下
 > 完整 ⛔ 强制项勾选清单见 `./checklist.md`「Guardrails ⛔ 强制项」。核心红线：
 
 - **⛔ Check 门禁检查**：apply 前必须确认 check 已完成；未完成强制拒绝。${HOOK_GATE_DESCRIPTION}
-- **⛔ 渐进式加载 + 隔离红线**：只加载当前 Capability 的四文档链，禁止加载同级其他 Capability 的文档。
+- **⛔ 渐进式加载 + 隔离红线**：只加载当前 Capability 的四文档链，默认聚焦当前 Capability；为核对已声明依赖可读取相关 Capability 契约并注明来源，不全量加载或混写其他能力。
 - **⛔ DAG 依赖拦截**：执行任务前必须检查依赖，前置未完成必须拦截。
 - **⛔ 编译检查门禁**：每完成一个任务后必须运行编译检查，编译失败禁止标记已完成。
 - **⛔ 测试执行门禁**：根据 `test-strategy` 决定（tdd=强制, impl-first=强制补跑, none=跳过）；须真实执行并留 telemetry。${HOOK_GATE_DESCRIPTION}

package/templates/skills/kld-sdd/opsx-apply/checklist.md

@@ -139,7 +139,7 @@ description: opsx-apply 的阶段强制检查点与自检清单。仅在执行 a
 
 - [ ] ⛔ **Check 门禁检查**：apply 前必须确认 check 已完成；未完成强制拒绝，与 `sdd-apply-gate.cjs` Hook 形成双重保障
 - [ ] ⛔ **渐进式加载**：只加载当前 Capability 的四文档链
-- [ ] ⛔ **隔离红线**：绝对禁止加载同级其他 Capability 的文档
+- [ ] ⛔ **隔离红线**：默认聚焦当前 Capability；为核对已声明依赖可读取相关 Capability 契约并注明来源，不全量加载或混写其他能力。
 - [ ] ⛔ **DAG 依赖拦截**：执行任务前必须检查依赖，前置未完成必须拦截
 - [ ] ⛔ **编译检查门禁**：每完成一个任务后必须运行编译检查，编译失败禁止标记已完成
 - [ ] ⛔ **测试执行门禁**：根据 `test-strategy` 决定（tdd=强制, impl-first=强制补跑, none=跳过）；须真实执行并留 telemetry，`sdd-apply-test-gate` 校验非占位数据

package/templates/skills/kld-sdd/opsx-apply/reference.md

@@ -2,6 +2,24 @@
 description: opsx-apply 的详细模板：telemetry 命令、worktree 全套策略、子代理派发、收尾脚本。仅在需要参考详细模板时读取。
 ---
 
+## 自动执行并取证（默认入口）
+
+使用 test-run 运行真实测试并记录同一条严格事件。工具采集命令参数、实际 cwd、退出码、耗时、测试计数和原始输出哈希；不让模型抄写这些字段。测试命令用 JSON 参数数组，无 shell 展开。
+
+```bash
+node "<spec-package>/skywalk-sdd/log.cjs" test-run --project="<spec-package>" --change=<变更名称> --session-id=<会话ID> --task-ids=<TASK-ID列表> --cwd="<代码仓>" --tdd-phase=regression --command-json='["node","--test","--test-reporter=tap","test/order-total.test.js"]'
+```
+
+RED 使用 --tdd-phase=red --expected-failure；真正的断言失败才能形成有效 RED。找不到测试入口/模块、编译/环境错误、超时均不能冒充业务红灯。命令返回实际测试退出码，失败仍保留事件与回执；不要因为 RED 非零就重复执行同一个 run-id。
+
+默认支持 Node TAP/Node 测试汇总。其他运行器输出无法可靠解析时 counts_known=false，不猜计数，不自动完成任务；已有适配器可继续用下方兼容入口提交实际报告。调用方明确声明 task-ids，工具不会把测试通过自动等同于覆盖了任意业务任务。
+
+需要测试成功后同步任务时，增加 --completion-file=<完成信息JSON文件>。内容为数组，每项包含 task_id、实际修改的仓库相对 files、tdd_required；TDD 任务同时写 tdd_pair_id/tdd_role。无文件修改填写 no_file_change_reason。工具将完成事件自动关联本轮 test_event_id 并同步任务勾选；RED、失败或未知计数不会自动完成任务。
+
+回执路径在输出 receipt 字段；原始 stdout/stderr 和执行清单保留在 skywalk-sdd/state/test-runs。记录失败后用原 details.json 重试 record --strict，禁止重写退出码或补造测试数。输出哈希不一致会被拒绝。自动 Hook 仅作补充，不对同一次 test-run 再手写一条 test_result。
+
+以下手写 test_result 模板仅保留给旧集成和已有测试报告适配器，新流程优先用 test-run。
+
 # opsx-apply — 详细参考（reference）
 
 > 本文件承载 opsx-apply 的重细节模板：telemetry 命令、§1.5 worktree 全套策略、§5c 子代理派发、§5.1 AI 产出快照、§6.0 单元测试真实执行、§6.1 worktree 收尾脚本。
@@ -95,7 +113,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=test_res
 - `expected_failure=true` 仅允许 `tdd_phase=red`
 - 有效 RED：`expected_failure=true` + `exit_code≠0` + `failure_type` 为 `assertion` 或 `contract`
 
-> **自动记录**：`sdd-post-tool.cjs` hook 会在 agent 运行 `mvn test`/`npm test` 等命令时自动记录 `test_result`，使用正确的 `test_results` key。但自动记录依赖 `activeStage.task_id`，若未设置则 `tdd_phase` 默认为 `regression`。需要精确标注 RED/GREEN 时建议手动记录。
+> **自动记录**：`sdd-post-tool.cjs` hook 会在 agent 运行 `mvn test`/`npm test` 等命令时自动记录 `test_result`，使用正确的 `test_results` key。但自动记录依赖 `activeStage.task_id`，若未设置则 `tdd_phase` 默认为 `regression`。需要精确标注 RED/GREEN 时使用上方 test-run 自动取证。
 
 ### process_note（阶段内过程事件：决策/范围变化/故障与恢复）
 
@@ -237,7 +255,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=worktree_finish \
 - **§4 依赖**（是否依赖 `<当前 capability>` 或其它 cap）
 - **涉及模块 / 数据表 / 公共配置**（若有）
 
-⛔ 禁止为校验而加载其它 cap 的 `design.md`、`tasks.md`（完整实施上下文仍遵守 §2 隔离红线）。
+默认聚焦当前 cap；核对真实跨能力依赖时可读取相关契约并注明来源，避免全量加载或混写。
 
 **Step D — 判定矩阵（输出给用户）**
 

package/templates/skills/kld-sdd/opsx-archive/SKILL.md

@@ -15,9 +15,11 @@ allowed-tools:
   - Edit
 ---
 
+> **执行方式**：先读 [交互与执行契约](../opsx-propose/interaction-policy.md)；同一会话已读则复用。用户已授权连续处理时按范围推进，不重复索要阶段口令；只请求单阶段时完成即停。
+
 你是一个 SDD（Specification-Driven Development）变更归档专家。激活本技能后，你要安全地结束变更生命周期：真实归档文档、同步正式 specs、记录 archive telemetry，并生成最终中文度量报告。
 
-> **硬依赖（收尾入库）**：zip 生成后的上传依赖同级已部署的 **`opsx-kb-ingest`**。进入 §5.5 前必须先 `Read` 该技能的 `SKILL.md` 并确认 KB 已配置（配置由 `opsx-kb-config` 负责）。入库成功后，`Read` `opsx-ontology-query/phase-3-postchange.md` 验证版本生效、AC 保留、关系完整性。缺失则提示用户重新 `kld-sdd-init`，**不要**自造另一套入库协议。
+> **硬依赖（收尾入库）**：zip 生成后的上传依赖同级已部署的 **`opsx-kb-ingest`**。用户已授权入库时，进入 §5.5 前读取该技能并检查目标配置；未授权或 KB 不可用时保留本地归档和待入库状态。入库成功后，`Read` `opsx-ontology-query/phase-3-postchange.md` 验证版本生效、AC 保留、关系完整性。缺失则提示用户重新 `kld-sdd-init`，**不要**自造另一套入库协议。
 
 > **跨平台执行规则**
 > - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
@@ -43,7 +45,7 @@ allowed-tools:
 
 ## 启动流程
 
-### 1. 确认变更名称并记录阶段开始
+### 1. 确认变更名称
 
 如果未提供变更名，运行：
 
@@ -51,25 +53,13 @@ allowed-tools:
 openspec list
 ```
 
-让用户选择现有变更。确认后记录阶段开始：
-
-```bash
-node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" start --command=archive --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>
-```
-
-保存 `event_id`。
-
-### 2. 询问归档原因
+按参数、会话或唯一活动变更定位；只有多个候选且无法判断时请用户选择。此时尚未开始 archive 阶段。
 
-使用交互问题让用户选择：
+### 2. 记录归档原因
 
-> 请选择归档原因：
-> - A. 变更已完成实施
-> - B. 变更已取消
-> - C. 变更已搁置
-> - D. 其他原因
+优先使用用户已经说明的原因。实际主任务全部完成且用户要求归档时，记录“变更已完成实施”；取消/搁置按用户明确意图记录。只有原因与当前任务状态矛盾或无法确定时才询问，不重复展示内部原因枚举。
 
-记录为 `<归档原因>`，它会进入 `archive-manifest.json`、archive telemetry 和最终报告。
+原因写入 `archive-manifest.json`、archive telemetry 和最终报告；不能把未完成任务自动写成完成。
 
 ### 2.5 确认无残留 Apply Worktree（Git 项目）
 
@@ -89,6 +79,14 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" doctor --project=. --change=<
 
 如果存在 `severe_issues`，暂停归档并说明必须先修复。`superseded_open_stages` 和 `rework_summary` 只作为返工/重复执行展示，不要求用户人工区分测试回滚或真实研发返工。
 
+诊断通过后才记录本轮 archive 开始，保存返回的 `event_id`：
+
+```bash
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" start --command=archive --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>
+```
+
+不要在本轮阶段已开始但未结束时再次运行前置 doctor；历史未闭环阶段仍须按真实结果补齐，不得跳过诊断或删除事件。
+
 ### 4. 扫描 tasks 完成状态
 
 ```bash
@@ -170,8 +168,8 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" active-change --remove
 
 ### 5.5 收尾入库（opsx-kb-ingest）
 
-1. 确认 `${AGENT_SKILL_DIR}/opsx-kb-ingest/SKILL.md` 存在并 Read；KB 配置（API Key / targets / project-identity.json）由 `opsx-kb-config` 统一负责，如未配置则提示运行 `/opsx-kb-config`。
-2. 归档 zip 生成后，**加载并执行** **`opsx-kb-ingest`** 上传（勿只口头提示而不走技能流程）；也可直接使用 `kb-upload.cjs --package=<zip路径>` 上传；成功则写 `ingest-receipt.json`。
+1. 确认 `${AGENT_SKILL_DIR}/opsx-kb-ingest/SKILL.md` 存在并 Read；KB 配置（API Key / targets / project-identity.json）由 `opsx-kb-config` 统一负责，如未配置则记录待入库原因；用户要求配置时再运行 `/opsx-kb-config`，不阻断已完成的本地归档。
+2. 归档 zip 生成后，若用户已授权入库且目标明确，加载并执行 `opsx-kb-ingest` 上传，也可使用 `kb-upload.cjs --package=<zip路径>`。未授权或断连时保留包并报告待入库，不把本地归档成功写成发布成功。只有真实入库回执成功后才写 `ingest-receipt.json`。
 3. 若返回 `EXTERNAL_REF_CONFLICT`，引导回 spec/check 修正后重入，**禁止**在 KB 内现场改绑。
 
 > 注意：`archive-docs` 成功执行后已经在内部写入 `stage_end`，因此**不要在成功的归档后再单独运行 `node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" end --command=archive ...`**。仅在第 5 步归档命令失败时，才需要运行下方的失败分支 `end`。
@@ -234,7 +232,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=baseline_record -
 
 ## Guardrails
 
-- 归档操作执行前必须让用户确认归档原因。
+- 归档原因根据用户意图与真实任务状态记录，已有明确原因不重复询问。
 - 不要调用 OpenSpec 自带归档命令；统一由 `archive-docs` 负责真实归档、阶段结束和报告生成。
 - “完成实施”归档允许 tasks 未全部勾选；未勾选项必须进入 archive details 和最终报告。
 - 最终报告由 `archive-docs` 自动生成（Markdown + HTML + JSON 三产物，默认落归档后 archive 目录的 reports/ 子目录，可用 --report-output 自定义路径）。