kld-sdd 2.6.16 → 2.6.21

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

@@ -17,7 +17,7 @@ allowed-tools:
 
 你是一个 SDD（Specification-Driven Development）业务意图文档专家。激活本技能后，你将引导用户创建符合质量红线标准的 **proposal.md** 文档。
 
-> **硬依赖**：本技能 Continuity 步骤依赖同级已部署的 **`opsx-ontology-query`**。启动 Continuity 前必须先 `Read` 该技能的 `SKILL.md`，并按其中流程准备 `../.shared/kb-state.json`（API Key + targets，与 `opsx-kb-ingest` 共用）。若项目 skills 目录中不存在 `opsx-ontology-query/`，停止 Continuity，提示用户重新执行 `kld-sdd-init`；**禁止**用本地 `archive/` 冒充查询。
+> **硬依赖**：本技能 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/` 冒充查询。
 >
 > **📡 KB 就绪检查**：§6.5 在进入编号入场前会检测 KB 配置状态。若未配置，会**主动询问**用户选择「配置」或「跳过」，不再静默降级。
 
@@ -35,10 +35,11 @@ allowed-tools:
 
 > **🖥️ 跨平台执行规则**
 > - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
-> - `openspec` 命令：优先 `node "$(cat .sdd-spec-root)/skywalk-sdd/openspec-shim.cjs" list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
-> - Telemetry / ontology：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" …`（Git 根无 skywalk-sdd/）；`spec-root` 可用 `node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" spec-root`。
+> - `openspec` 命令：`cd <spec-package> && openspec …`（先 cd 到包裹包即可）。路径不确定时用 `node <spec-package>/skywalk-sdd/spec-root.cjs` 验证。
+> - Telemetry / ontology：`node <spec-package>/skywalk-sdd/log.cjs …`（直接在包裹包内执行）；`--project=.` 指当前 spec 包裹包。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
+> - **⚠️ PowerShell CLIXML**：在 PowerShell 中直接执行 `node xxx.cjs --arg=val` 时，stdout 可能被包装为 CLIXML `<Objs>` 格式，导致 JSON 解析失败。建议用 `write_to_file` 创建临时 `.cjs` 脚本通过 `execFileSync` 调用，或使用 `stripCliXml()`（`lib/shared.cjs` 已内置）剥离。
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）** — 阶段开始 / 阶段结束**命令模板**见 `./reference.md`「📊 Telemetry 命令模板」。
 > - 用户确认变更范围、`mode`、`test-strategy` 或方案 A/B/C 时，记录严格 `process_note`：`kind=user_decision`，并分别填写 `decision_type=scope|mode|test_strategy|other`。同一决定只记录一次，后续改变范围时改用 `kind=scope_change`。
@@ -200,28 +201,30 @@ openspec instructions proposal --change "<name>" --json
 1. 收集 REQ 号（含可选 `feature-id`）；没有则问一次。
 2. 逐个验号（确定性入口，禁止肉眼判正则）：
 ```bash
-node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" external-key --validate "<REQ-...>" --type requirement
+node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" external-key --validate "<外部需求编号>" --type requirement
 # 若有 feature-id：
-node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" external-key --validate "<FEAT-...>" --type feature
+node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" external-key --validate "<外部功能编号>" --type feature
 ```
-   - REQ/FEAT 不合规 → **拒绝进入 resolve**，告知「编号不合规，请回需求管理系统核实/换发」；Agent 不得猜测、补位、改写。
+   - 编号格式：大写字母 + 数字 + 连字符(-) + 下划线(_)，1~50 字符；例 KLERP-001、REQ-FI-2024-001、1010000。
+   - 不合规 → **拒绝进入 resolve**，告知「编号格式不合规（仅允许大写字母、数字、连字符、下划线）」；Agent 不得猜测、补位、改写。
    - 用户明确说「没有外部需求号」→ 走 `numbering-waiver.reason`（必填理由）；`requirement-refs` 必须为空；提示本轮不种桥。
-3. **先加载依赖技能**：确认 `${AGENT_SKILL_DIR}/opsx-ontology-query/SKILL.md` 存在并 Read；按该技能完成 API Key / 空间与 KB 选择（`../.shared/kb-state.json`，与 `opsx-kb-ingest` 共用）。未安装则停止本步。
+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` 共用。未安装则停止本步。
    - **KB 就绪检查**：运行 `node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" --check-only`，若 `"available": false`，使用 **AskUserQuestion** 询问用户：
-     > "📡 **Engineering KB 未配置**
-     > KB 可以提供 Continuity 身份验证和 Capability 复用。是否现在配置？
-     > - A. **配置 KB**（加载 opsx-ontology-query 走 Session 启动）
-     > - B. **跳过 KB**，走 archive 降级路径（标注 `source: archive(degraded)`）
-     > - C. **取消操作**"
-     - **选 A** → 配置 → 继续步骤 4。
-     - **选 B** → 在 proposal.md frontmatter 标注 `kb-status: degraded(by-user-choice)`，走路径 B（扫描归档 `ontology-identities.json`，标注 `source: archive(degraded)`）。
+     > "📡 **知识库未配置**
+     >
+     > 知识库可以帮你追踪能力版本，避免重复定义。现在要配置吗？
+     > - A. **现在配置** — 运行 /opsx-kb-config，配置后可复用已有能力
+     > - B. **暂不配置，先继续** — 用本地归档数据代替（精度有限，后续入库可能需修正）
+     > - C. **取消** — 终止本次操作"
+     - **选 A** → 引导运行 `/opsx-kb-config`，配置完成后继续步骤 4。
+     - **选 B** → 在 proposal.md frontmatter 标注 `kb-status: degraded(by-user-choice)`，走降级路径（扫描归档 `ontology-identities.json` 匹配已有能力；归档为空则全部按新增处理）。
      - **选 C** → 终止 propose。
 4. 验号通过后才 resolve：
 ```bash
 node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" --mode=resolve \
   --external-system=requirement-mgmt \
   --external-object-type=requirement \
-  --external-id="<REQ-...>" \
+  --external-id="<外部需求编号>" \
   --entity-type=Capability \
   --space-id="$ENGINEERING_KB_SPACE_ID" \
   --kb-id="$ENGINEERING_KB_KB_ID"
@@ -230,10 +233,10 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" --mode=resolve \
 6. 按 KB 结果确认 Continuity：`iteration` / `similar-reference` / `new`；勾选本次涉及的 CAP。
 7. 写入 proposal frontmatter：`requirement-refs`（含 `feature-id`）/ `numbering-waiver` + `continuity`。**禁止**写本地 archive 文件夹名作为 `base-archive`。
 8. CAP 级「同 key + 同锚点、不同 entity_id」当场问 A/B/C；决议写入 `ontology/continuity-resolution.json` 的 `capabilities[]`。
-9. KB 不可用 → `degraded` 继续，**禁止**扫本地 `archive/` 抄 UUID。KB degraded（用户选择跳过）时走路径 B（archive 降级）：
+9. KB 不可用 → `degraded` 继续，**禁止**扫本地 `archive/` 抄 UUID。用户选择跳过 KB 时走降级路径：
    - 扫描 `openspec/changes/archive/*/ontology/ontology-identities.json` 匹配 canonicalKey
-   - path B 的所有 entity-id 来源在 sdd-output.md 知识库使用表中必须标注 `source: archive(degraded)`，与 `source: KB current` 明确区分。
-   - ⚠️ **降级风险**：archive 中的 version-id 可能已过时（如果该 capability 在 archive 之后又有新版本入库到 KB）。path B 的 predecessor-version 不保证是 KB current。入库时可能触发 `VERSION_CONFLICT`。
+   - 降级路径的所有 entity-id 来源在 sdd-output.md 知识库使用表中标注 `source: archive(degraded)`，与 `source: KB current` 明确区分。
+   - ⚠️ **降级风险**：归档中的版本号可能已过时（归档后该能力可能在 KB 中有更新版本）。降级路径取到的 predecessor-version 不保证是 KB 最新版本，入库时可能触发 `VERSION_CONFLICT`，需手动修正。
 10. **不得**在本阶段生成 STMT/AC/场景或裁决场景身份；**不得**铸/改 REQ/FEAT 号。
 
 **完整流程示例（路径 A — KB 驱动）**：
@@ -268,11 +271,20 @@ Read openspec/changes/archive/*/ontology/ontology-identities.json
 
 **❗ 必须主动询问用户，不得默认选择**。Full / Simple / Auto 三种模式的目录结构、适用场景与 AskUserQuestion 文案见 `./reference.md`「§7 文档拆分模式选择」。根据用户选择设置 `mode: full | simple`（Auto 按能力域数量判断），记录到 proposal.md 的 YAML frontmatter。
 
-### 7.5 【交互引导】变更类型确认
+### 7.5 自动判断变更类型
 
-**❗ 必须主动询问用户，不得默认选择**。在模式与测试策略选择附近，基于需求给出 `change-type` **推荐**并让用户确认；Auto 只能推荐，**禁止无提示静默写入**。
+变更类型只用于最终指标的分层统计，不再作为一个单独的用户交互问题，也不单独询问用户选择内部枚举。Agent 根据需求、影响范围和能力域自动分类，并把中文判断理由展示给用户；只有现有描述不足以判断业务范围时，才在正常需求澄清中补问事实。
 
-允许值固定为：`config | transaction | report | composite`（写入 proposal.md YAML frontmatter 的 `change-type` 字段）。AskUserQuestion 文案与类型说明见 `./reference.md`「§7.5 变更类型选择」。
+按以下优先级判断，命中即停止：`composite` → `report` → `transaction` → `config`。纯 SDD/遥测/报告生成器等非业务工具变更使用受限值 `unknown`，并排除在四种业务类型的均值比较之外。
+
+写入 proposal.md YAML frontmatter：
+
+- `change-type`: `config | transaction | report | composite | unknown`
+- `change-type-source`: Agent 初次判断写 `agent-inferred`；用户在整份 proposal 确认时纠正后写 `user-corrected`
+- `change-type-confidence`: `high | medium | low`
+- `change-type-reason`: 一句中文理由
+
+类型原话、判断顺序和边界见 `./reference.md`「§7.5 变更类型自动分类」。
 
 ### 8. 【交互引导】测试策略选择
 
@@ -340,11 +352,11 @@ Read openspec/changes/archive/*/ontology/ontology-identities.json
 - **⛔ 阶段边界**：本阶段禁止执行任何代码创建/修改操作。若用户要求处理代码，回复：「当前处于 Propose 阶段，代码操作请在完成文档后使用 `/opsx-apply` 执行。」
 - **⛔ 单阶段原则**：完成 proposal.md 后必须立即停止。仅提示用户下一步可运行 `/opsx-spec`，绝对禁止自动执行 spec/design/task 等后续阶段。每个阶段必须由用户主动触发。
 - **⛔ Frontmatter 规范（L7）**：YAML frontmatter 中禁止写 `#` 注释（YAML 注释在 frontmatter 中可能导致解析问题）。如需说明，在 frontmatter 之前或之后用正文描述。
-- **⛔ change-type 必采**：frontmatter 必须含 `change-type`，取值仅限 `config | transaction | report | composite`；Agent 可推荐但须经用户确认后写入，禁止静默默认。
+- **⛔ change-type 必采**：frontmatter 必须含 `change-type`、`change-type-source`、`change-type-confidence`、`change-type-reason`；Agent 自动判断，不为内部分类单独打断用户。
 
 ---
 
 ## 渐进披露
 
 - Read `checklist.md` 仅在执行 propose 需要校验时 — 含阶段边界⛔（Propose 阶段约束）、§6 需求完整性检查、Guardrails ⛔ 强制项勾选表。
-- Read `reference.md` 仅在需要参考详细模板时 — 含 📊 Telemetry 命令模板（start/end）、§7 文档拆分模式（Full/Simple/Auto）、§7.5 变更类型（config/transaction/report/composite）、§8 测试策略（TDD/Impl-First/None）、§10 质量红线自检清单（8 项）。
+- Read `reference.md` 仅在需要参考详细模板时 — 含 📊 Telemetry 命令模板（start/end）、§7 文档拆分模式（Full/Simple/Auto）、§7.5 变更类型自动分类（config/transaction/report/composite/unknown）、§8 测试策略（TDD/Impl-First/None）、§10 质量红线自检清单（8 项）。

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

@@ -32,6 +32,8 @@ description: opsx-propose 的阶段强制检查点与自检清单。仅在执行
 
 ## Guardrails ⛔ 强制项
 
+- [ ] ⛔ **Telemetry**：阶段开始前已执行 `log.cjs start --command=propose ...`，event_id 已保存
+- [ ] ⛔ **Telemetry**：阶段结束后已执行 `log.cjs end --event-id=<event_id> --command=propose ...`
 - [ ] 必须以 `openspec-templates/proposal.md` 为模板基准，不得使用 `openspec instructions` 返回的简化 template
 - [ ] `context` 和 `rules` 是约束条件，不得出现在生成的文档中
 - [ ] proposal.md 聚焦【Why】，不写技术实现细节（留给 design.md）

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

@@ -48,27 +48,32 @@ description: opsx-propose 的详细模板：telemetry 命令、文档拆分模
 
 ---
 
-## §7.5 变更类型选择
+## §7.5 变更类型自动分类
 
-**❗ 必须主动询问用户，不得默认选择；Auto 仅给推荐，禁止无提示写入**
+变更类型用于按类型分组呈现核心指标，避免把不同类型变更混在一个平均数里导致结论失真。它只影响统计分层，不需要作为一个单独问题打断用户。
 
-分析需求后，Agent 先给出推荐类型，再使用 **AskUserQuestion** 让用户确认：
+按以下顺序自动判断，命中后停止：
 
-> "📊 **变更类型（用于 V3 指标分层统计）**
->
-> 根据本次需求，推荐类型：**[config | transaction | report | composite]** — [一句话理由]
->
-> 请选择或确认：
-> - **config** — 配置/开关/环境/依赖调整，几乎不改业务逻辑
-> - **transaction** — 单据类：业务流程、状态流转、CRUD/交易路径变更
-> - **report** — 报表类：报表查询、度量展示、采集契约（不是“度量报告工具”本身的专属类型）
-> - **composite** — 跨多类能力的组合变更
->
-> A) 采用推荐  B) 手动选择其他类型"
+1. **composite（复合变更）**：多能力域耦合、依赖关系复杂，或同时明显具备两种以上业务类型特征。预期 E1 较长、返工次数较高，重点关注 P-R、E1。
+2. **report（报表类）**：业务目标是报表查询、统计展示或复杂数据口径，通常数据逻辑复杂、查询优化要求高。重点关注 Q3、Q4、E2。
+3. **transaction（单据类）**：业务流程、状态流转、CRUD、交易路径或接口协作变更，通常复杂度中等、接口较多。重点关注 P4、P-R。
+4. **config（配置类）**：配置、开关、环境、依赖或固定模式调整，范围小、单能力域、几乎不改变业务流程。重点关注 E1、Q3。
+5. **unknown（非业务工具）**：纯 SDD 流程、遥测、报告生成器、开发工具或无法可靠归入上述四种业务类型的变更。`unknown` 必须单列数量，不参与四种业务类型的均值和趋势比较。
+
+写入示例：
+
+```yaml
+change-type: report
+change-type-source: agent-inferred
+change-type-confidence: high
+change-type-reason: "主要目标是展示和解释度量报告中的计算口径，属于报表类变更"
+```
+
+Agent 应在 proposal 正文或完成摘要中展示中文分类及理由，但不单独询问用户选择内部枚举。只有需求事实不足时，才通过正常需求澄清补问业务目标或影响范围。
 
-根据用户确认，在 proposal.md YAML frontmatter 写入 `change-type: <值>`。允许值固定：`config | transaction | report | composite`。
+若用户在整份 proposal 确认时纠正分类，更新 `change-type` 和理由，并将 `change-type-source` 改为 `user-corrected`；不要再次发起独立的变更类型交互。
 
-> 历史 proposal 的 `document`/`other` 读取侧迁移为 `unknown` 并告警，不写入新 proposal；本阶段不得替用户猜测补写。
+> 历史 proposal 的 `document`/`other` 读取侧迁移为 `unknown` 并告警；新 proposal 不再写入这两个历史值。
 
 ---
 
@@ -106,6 +111,6 @@ description: opsx-propose 的详细模板：telemetry 命令、文档拆分模
 - [ ] 前置依赖使用 checkbox 格式
 - [ ] 文档末尾包含质量红线检查清单
 - [ ] 能力分解章节已明确（决定后续 specs 文件夹结构）
-- [ ] frontmatter 含 `change-type`，取值为 `config | transaction | report | composite` 之一且经用户确认
+- [ ] frontmatter 含 `change-type`、`change-type-source`、`change-type-confidence`、`change-type-reason`，分类理由与需求事实一致
 
 **如有任意一项未满足，重新生成对应章节，直至全部通过。**

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

@@ -20,8 +20,8 @@ allowed-tools:
 
 > **🖥️ 跨平台执行规则**
 > - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`、`skywalk-sdd/`），不是 Git 根。
-> - **CLI 前缀**：Git/工作区根执行时用 `node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" …`；**不要**在 Git 根另建 `skywalk-sdd/`。
-> - `openspec`：优先 `node "$(cat .sdd-spec-root)/skywalk-sdd/openspec-shim.cjs" list`，或先 `cd` 到包裹包再执行。
+> - **CLI 前缀**：`node <spec-package>/skywalk-sdd/log.cjs …`（直接在包裹包内执行）。路径不确定时用 `node <spec-package>/skywalk-sdd/spec-root.cjs` 验证。
+> - `openspec`：`cd <spec-package> && openspec …`（先 cd 到包裹包即可）。
 > - ${SHELL_GUIDANCE}
 > - **本技能不写入 SkyWalk Telemetry**（与 `opsx-knowledge` 同属辅助技能，不走 `log.cjs start/end`）。
 

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

@@ -17,7 +17,7 @@ allowed-tools:
 
 你是一个 SDD（Specification-Driven Development）技术契约专家。激活本技能后，你将引导用户为每个 Capability 创建 **spec.md** 文档。
 
-> **硬依赖**：场景身份 / Spec 复用依赖同级已部署的 **`opsx-ontology-query`**。进入知识库上下文步骤前必须先 `Read` 该技能的 `SKILL.md` 并完成其 Session 启动（API Key + targets → `../.shared/kb-state.json`）。缺失则停止复用查询，提示重新 `kld-sdd-init`；**KB 可用时禁止**从本地 `archive/` 抄 UUID，entity-id 必须来自 KB resolve by canonicalKey。
+> **硬依赖**：场景身份 / 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。
 >
 > **📡 KB 就绪检查**：§2.5 在进入上下文加载前会检测 KB 配置状态。若未配置，会**主动询问**用户选择「配置」或「跳过」，不再静默降级。
 
@@ -35,10 +35,11 @@ allowed-tools:
 
 > **🖥️ 跨平台执行规则**
 > - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
-> - `openspec` 命令：优先 `node "$(cat .sdd-spec-root)/skywalk-sdd/openspec-shim.cjs" list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
-> - Telemetry / ontology：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" …`（Git 根无 skywalk-sdd/）；`spec-root` 可用 `node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" spec-root`。
+> - `openspec` 命令：`cd <spec-package> && openspec …`（先 cd 到包裹包即可）。路径不确定时用 `node <spec-package>/skywalk-sdd/spec-root.cjs` 验证。
+> - Telemetry / ontology：`node <spec-package>/skywalk-sdd/log.cjs …`（直接在包裹包内执行）；`--project=.` 指当前 spec 包裹包。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
+> - **⚠️ PowerShell CLIXML**：在 PowerShell 中直接执行 `node xxx.cjs --arg=val` 时，stdout 可能被包装为 CLIXML `<Objs>` 格式，导致 JSON 解析失败。建议用 `write_to_file` 创建临时 `.cjs` 脚本通过 `execFileSync` 调用，或使用 `stripCliXml()`（`lib/shared.cjs` 已内置）剥离。
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）** — 阶段开始 / 阶段结束**命令模板**见 `./reference.md`「📊 Telemetry 命令模板」。
 
@@ -121,18 +122,21 @@ openspec list
    ```
    - 输出 `"available": true` → KB 已配置
    - 输出 `"available": false` → KB 未配置
+
+> **注意**：KB 就绪检查（`--check-only`）与 KB 上下文查询（`match-requirement`）是两个独立步骤。即使 Continuity=new 无需上下文查询，**仍需执行 `--check-only`** 确认 KB 可用性，以便在 sdd-output.md 中记录 KB 状态。
+
 3. **若已配置** → 直接进入 §3。
 4. **若未配置** → 使用 **AskUserQuestion** 询问：
 
-   > "📡 **Engineering KB 未配置**
+   > "📡 **知识库未配置**
    >
-   > KB 可以提供场景身份验证、Spec 复用和历史 AC 检索。是否现在配置？
+   > 知识库可以帮你验证场景身份、复用已有 Spec 和检索历史验收标准。现在要配置吗？
    >
-   > - A. **配置 KB**
-   > - B. **跳过 KB**，仅使用本地上下文（archive 降级，标注 `source: archive(degraded)`）
-   > - C. **取消操作**"
+   > - A. **现在配置** — 运行 /opsx-kb-config
+   > - B. **暂不配置，先继续** — 仅用本地数据（精度有限）
+   > - C. **取消** — 终止本次操作"
 
-   - **选 A** → 配置 → 进入 §3。
+   - **选 A** → 引导运行 `/opsx-kb-config`，配置完成后进入 §3。
    - **选 B** → 在 spec.md frontmatter 标注 `kb-status: degraded(by-user-choice)`，进入 §3（仅本地上下文）。
    - **选 C** → 终止 spec。
 
@@ -144,7 +148,7 @@ openspec list
 
 **【默认尝试】工程 Spec 知识库上下文（场景身份主战场）**：
 
-1. **先加载依赖技能**：确认 `${AGENT_SKILL_DIR}/opsx-ontology-query/SKILL.md` 存在并 Read；按该技能完成 API Key / targets（`../.shared/kb-state.json`，与 `opsx-kb-ingest` 共用）。未安装则停止本步。
+1. **先加载依赖技能**：确认 `${AGENT_SKILL_DIR}/opsx-ontology-query/SKILL.md` 存在并 Read；按该技能完成 API Key / targets（`kb-state.json`，spec 仓根目录，与 `opsx-kb-ingest` 共用）。未安装则停止本步。
 2. 读取 proposal Continuity。对**当前 Capability** 各调一次（「全部」= 循环 N 次，不是一次大查询）——优先走 **`opsx-ontology-query`** 的 `match-requirement`；薄封装仅作参数拼装：
 
 ```bash
@@ -154,7 +158,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" \
   --entity-id="<该 CAP 的 entity_id>" \
   --external-system=requirement-mgmt \
   --external-object-type=requirement \
-  --external-id="<REQ-...>" \
+  --external-id="<外部需求编号>" \
   --space-id="$ENGINEERING_KB_SPACE_ID" \
   --kb-id="$ENGINEERING_KB_KB_ID"
 ```
@@ -164,16 +168,16 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" \
 - **禁止**从本地 `archive/` 抄 UUID 当跨迭代继承源；跨迭代只认 KB current。
 - 若返回 `available=false` / `degraded=true`，记录降级并继续，不得扫本地 archive 兜底。
 - `INHERIT`：unchanged 写继承引用；modified 复用 entity-id + predecessor。`REFERENCE`：只参考，新开身份。
-- reuseBundle / 实体上的 `externalRefs` 写入场景 `external-ref`（完整键 `REQ-…:SCN-<slug>-<NNN>`）。
+- reuseBundle / 实体上的 `externalRefs` 写入场景 `external-ref`（完整键 `<外部需求编号>:SCN-<slug>-<NNN>`）。
 - **SCN 铸号（本仓唯一铸号点）**：
   1. 继承优先：`reuseBundle.externalRefs` 已有场景键的 unchanged/modified 场景一律沿用原 SCN 号，禁止另铸。
-  2. 新场景：`SCN-<slug>-<NNN>`；slug=kebab-case 小写 ≤40；NNN=该 REQ 命名空间内 max+1（已用集合=KB 回传 ∪ 本 Change 已写键，含 removed 墓碑）。
+  2. 新场景：`SCN-<slug>-<NNN>`；slug=kebab-case 小写 ≤40；NNN=该需求编号命名空间内 max+1（已用集合=KB 回传 ∪ 本 Change 已写键，含 removed 墓碑）。
   3. removed 号是墓碑：永不复用、永不重排；序号达 999 → 硬错误，回需求系统拆分需求，不扩位。
-  4. 写完立即用 `cli.cjs external-key --validate … --type scenario` 校验；REQ 前缀必须 ∈ proposal `requirement-refs`。
+  4. 写完立即用 `cli.cjs external-key --validate … --type scenario` 校验；需求编号前缀必须 ∈ proposal `requirement-refs`。
 - 场景级「同 SCN key + 同锚点、不同 entity_id」当场问 A/B/C；未决不得进入下一 CAP / design。决议追加到 `ontology/continuity-resolution.json` 的 `scenarios[]`；决议中的 `externalKey` 必须是归一化形态。
 - 优先消费 `reuseBundles[].statements`；`designElements` 只作理解上下文，不能写成 Spec 的 How。
 - 所有知识库内容均为 advisory；与用户确认 / proposal 冲突时以当前确认与 proposal 为准。
-- **禁止**铸/改 REQ/FEAT；**禁止**自动重排/回收 SCN。
+- **禁止**铸/改外部需求/功能编号；**禁止**自动重排/回收 SCN。
 
 **【可选】业务知识库检索**：
 术语含义不清且可能影响 spec 准确性时，可调用 **opsx-knowledge** skill。

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

@@ -42,6 +42,8 @@ description: opsx-spec 的阶段强制检查点与自检清单。仅在执行 sp
 
 ## Guardrails ⛔ 强制项
 
+- [ ] ⛔ **Telemetry**：阶段开始前已执行 `log.cjs start --command=spec ...`，event_id 已保存
+- [ ] ⛔ **Telemetry**：阶段结束后已执行 `log.cjs end --event-id=<event_id> --command=spec ...`
 - [ ] 必须以 `openspec-templates/spec.md` 为模板基准
 - [ ] spec.md 聚焦【What】，不写 How（留给 design.md）
 - [ ] **需求项格式必须正确**：`####` 需求项、`#####` 场景

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

@@ -48,8 +48,8 @@ allowed-tools:
 
 > **🖥️ 跨平台执行规则**
 > - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
-> - `openspec` 命令：优先 `node "$(cat .sdd-spec-root)/skywalk-sdd/openspec-shim.cjs" list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
-> - Telemetry / ontology：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" …`（Git 根无 skywalk-sdd/）；`spec-root` 可用 `node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" spec-root`。
+> - `openspec` 命令：`cd <spec-package> && openspec …`（先 cd 到包裹包即可）。路径不确定时用 `node <spec-package>/skywalk-sdd/spec-root.cjs` 验证。
+> - Telemetry / ontology：`node <spec-package>/skywalk-sdd/log.cjs …`（直接在包裹包内执行）；`--project=.` 指当前 spec 包裹包。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
@@ -80,8 +80,6 @@ allowed-tools:
 
 Simple 模式或单文件能力域下，**不要拆成多个同文件任务**。按可独立测试的函数/单元拆分任务，每个任务对应一个可独立验证的代码单元。同文件多处改动有顺序依赖时合并为一个任务。
 
-## 启动流程
-
 ### 1. 【交互引导】确认变更名称和 Capability
 
 若未提供参数，列出已有 design.md 的 Capability 供用户选择。

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

@@ -25,8 +25,8 @@ allowed-tools:
 
 > **🖥️ 跨平台执行规则**
 > - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
-> - `openspec` 命令：优先 `node "$(cat .sdd-spec-root)/skywalk-sdd/openspec-shim.cjs" list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
-> - Telemetry / ontology：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" …`（Git 根无 skywalk-sdd/）；`spec-root` 可用 `node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" spec-root`。
+> - `openspec` 命令：`cd <spec-package> && openspec …`（先 cd 到包裹包即可）。路径不确定时用 `node <spec-package>/skywalk-sdd/spec-root.cjs` 验证。
+> - Telemetry / ontology：`node <spec-package>/skywalk-sdd/log.cjs …`（直接在包裹包内执行）；`--project=.` 指当前 spec 包裹包。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。

package/templates/skills/kld-sdd/tdd-core/reference.md

@@ -129,7 +129,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=test_res
 **实现任务**（不带 `task_kind`）：
 
 ```bash
-node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --run-id=<任务更新稳定ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-json='{"files_changed":[],"task_update":{"test_event_id":"<成功的green/refactor测试event_id>","tdd_required":true,"tdd_pair_id":"<pair-N>","tdd_role":"green"}}'
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --run-id=<任务更新稳定ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-json='{"task_update":{"files":["<本任务实际修改的项目相对路径>"],"test_event_id":"<成功的green/refactor测试event_id>","tdd_required":true,"tdd_pair_id":"<pair-N>","tdd_role":"green"}}'
 
 > RED/GREEN 同对必须写相同 `tdd_pair_id`；也可用互斥的 `test_run_id`（唯一严格完成候选）代替 `test_event_id`。
 ```

package/templates/skills/kld-sdd/tdd-rules/rules/test-skeleton-telemetry.md

@@ -15,5 +15,5 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=test_res
 实现任务不带 `task_kind`（默认 implementation），按真实测试结果记录。
 
 ```bash
-node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --run-id=<任务更新稳定ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-json='{"files_changed":[],"task_update":{"test_event_id":"<成功的green/refactor测试event_id>","tdd_required":true,"tdd_pair_id":"<pair-N>","tdd_role":"green"}}'
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --run-id=<任务更新稳定ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-json='{"task_update":{"files":["<本任务实际修改的项目相对路径>"],"test_event_id":"<成功的green/refactor测试event_id>","tdd_required":true,"tdd_pair_id":"<pair-N>","tdd_role":"green"}}'
 ```

package/templates/skills/kld-sdd/opsx-kb-ingest/state.example.json

@@ -1,7 +0,0 @@
-{
-  "api": "http://localhost:8090/api",
-  "tenantKey": "default",
-  "apiKey": "",
-  "updatedAt": "",
-  "targets": []
-}

package/templates/skills/kld-sdd/opsx-ontology-query/state.example.json

@@ -1,7 +0,0 @@
-{
-  "api": "http://localhost:8090/api",
-  "tenantKey": "default",
-  "apiKey": "",
-  "updatedAt": "",
-  "targets": []
-}