kld-sdd 2.6.16 → 2.6.17

package/templates/skills/kld-sdd/opsx-kb-ingest/reference.md

@@ -8,7 +8,7 @@
 
 ```json
 {
-  "api": "http://localhost:8090/api",
+  "api": "http://10.29.213.80:8080/api",
   "tenantKey": "default",
   "apiKey": "sk_sdd_…",
   "updatedAt": "2026-07-19T12:00:00Z",
@@ -117,7 +117,7 @@ POST {base}/ingestions/{jobId}/retry
 | `stage` | String | `validating` / `canonical-store` / `committed` / `failed` |
 | `idempotentHit` | boolean | 是否命中幂等（同 archive_id + content_hash） |
 | `relationStatus` | String | `pending` / `committed` / `rolled_back` / `not_required` |
-| `projectionStatus` | String | `pending` / `not_started` / … |
+| `projectionStatus` | String | `pending` / `not_started` / `complete` / `degraded` / `disabled` |
 | `errorCode` | String | 失败错误码（见下表） |
 | `errorMessage` | String | 失败错误描述 |
 | `report` | JsonNode | 入库报告（成功含 `externalRefsWritten`；冲突失败含 `details`） |
@@ -134,6 +134,8 @@ POST {base}/ingestions/{jobId}/retry
 | `INGEST_FAILED` | 通用入库失败 |
 | `PROJECT_SPACE_MISMATCH` | manifest 中 project_id 与目标 Space spaceKey 不一致 |
 | `ARCHIVE_IMMUTABILITY_VIOLATION` | 同一 archive_id 已存在不同 content_hash |
+| `VERSION_IDENTITY_CONFLICT` | version-id 已存在但 content_hash 或 entity_id 不同；错误消息含 anchorId / name / versionId 帮助定位。该 Change 之前已入库，需对被修改的实体按「重新入库前：KB 身份同步」步骤更新 delta-state=modified + predecessor-version 后重新上传 |
+| `SEM_VERSION_LINEAGE_MISSING` | 语义校验阶段：modified/removed 实体的 predecessor-version 在本地 archive 中找不到对应版本。检查 predecessor-version 是否来自 KB resolve 返回的 entityVersionId |
 | `MANIFEST_MISSING` | 缺少必需的 manifest 文件 |
 | `INVALID_FILE_TYPE` | 包含不允许的文件类型 |
 | `SIZE_LIMIT_EXCEEDED` | 超过包/文件/条目大小限制 |
@@ -141,26 +143,26 @@ POST {base}/ingestions/{jobId}/retry
 | `EXTERNAL_REF_CONFLICT` | 同外部键+同锚点已绑不同 entity_id；整包回滚；见 `report.details` |
 | `EXTERNAL_REFERENCE_TYPE_MISMATCH` | 包内 object_type 与实体类型不匹配 |
 | `EXTERNAL_REFERENCE_DUPLICATE_IN_PACKAGE` | 包内重复 `(external key, entity_id)` |
-| `EXTERNAL_REFERENCE_FORMAT_INVALID` | 编号归一化后不合规（含 requirement.`feature_id`）；回需求系统换发 |
-| `EXTERNAL_REFERENCE_SCOPE_MISMATCH` | 场景键 REQ 前缀不在同包 requirement 集合；回 kld-sdd spec 修正 |
+| `EXTERNAL_REFERENCE_FORMAT_INVALID` | 编号归一化后不合规（含非白名单字符 A-Z 0-9 - _ 或超长）；请检查外部编号来源 |
+| `EXTERNAL_REFERENCE_SCOPE_MISMATCH` | 场景键需求编号前缀不在同包 requirement 集合；回 kld-sdd spec 修正 |
 | `EXTERNAL_REFERENCE_FEATURE_UNBOUND` | feature 绑定与 requirement.`feature_id` 无法配对；回 propose/archive |
 | `FACTS_SCHEMA_UNSUPPORTED` | canonical-facts schema 非 v1/v2 |
 
 ### 编号正则（与 KB 设计 §2 / ExternalKeyFormat 一致）
 
 ```text
-requirement: ^REQ-[A-Z][A-Z0-9]{1,7}-[0-9]{4}-[0-9]{3,6}$
-feature:     ^FEAT-[A-Z][A-Z0-9]{1,7}-[0-9]{3,6}$
-scenario:    ^REQ-[A-Z][A-Z0-9]{1,7}-[0-9]{4}-[0-9]{3,6}:SCN-[a-z0-9]+(-[a-z0-9]+)*-[0-9]{3}$
+requirement: ^[A-Z0-9_-]+$
+feature:     ^[A-Z0-9_-]+$
+scenario:    ^[A-Z0-9_-]+:SCN-[a-z0-9]+(-[a-z0-9]+)*-[0-9]{3}$
 ```
 
-requirement 条目可选 `feature_id`（FEAT 文法）；配对关系随线缆走，KB 不反查 frontmatter。
+requirement 条目可选 `feature_id`（同 feature 文法）；配对关系随线缆走，KB 不反查 frontmatter。
 
 ### `EXTERNAL_REF_CONFLICT` 的 report.details
 
 ```json
 {
-  "externalRef": { "system": "requirement-mgmt", "objectType": "requirement", "externalId": "REQ-…" },
+  "externalRef": { "system": "requirement-mgmt", "objectType": "requirement", "externalId": "KLERP-001" },
   "anchor": "CAP-ORDER-CANCEL",
   "existingEntityId": "<uuid>",
   "existingCurrentVersionId": "<uuid>",
@@ -207,3 +209,43 @@ requirement 条目可选 `feature_id`（FEAT 文法）；配对关系随线缆
   ]
 }
 ```
+
+## 文件夹上传（kb-upload.cjs）
+
+### 用法
+
+```bash
+# 仅校验
+node skywalk-sdd/kb-upload.cjs --validate-only --folder=<path> [--minimum-level=propose-spec]
+
+# 文件夹上传（自动语义管线 + 元数据生成 + 打包 + 上传）
+node skywalk-sdd/kb-upload.cjs --folder=<path> [--minimum-level=propose-spec] [--space-id=<id>] [--kb-id=<id>]
+
+# zip 包上传
+node skywalk-sdd/kb-upload.cjs --package=<zip-path> [--space-id=<id>] [--kb-id=<id>]
+```
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--folder=<path>` | 与 `--package` 二选一 | SDD 变更目录路径 |
+| `--package=<zip>` | 与 `--folder` 二选一 | 已打包的 zip 路径 |
+| `--minimum-level` | 否 | 上传最低等级：`propose-spec`（默认）/ `design` / `task` / `full` |
+| `--validate-only` | 否 | 仅校验不上传 |
+| `--space-id=<id>` | 否 | 目标 Space ID（从 kb-state.json targets[0] 读取） |
+| `--kb-id=<id>` | 否 | 目标 KB ID（从 kb-state.json targets[0] 读取） |
+
+### project_id 解析优先级
+
+1. `$SPEC_ROOT/skywalk-sdd/project-identity.json` 的 `project_id` 字段
+2. 都没有 → 报错：`请运行 /opsx-kb-config 配置知识库`
+
+### 上传等级校验
+
+| 等级 | 必需文件 |
+|------|---------|
+| `propose-spec` | proposal.md + spec.md |
+| `design` | + design.md |
+| `task` | + tasks.md |
+| `full` | 全部 4 个 + ontology 状态完整 |

package/templates/skills/kld-sdd/opsx-ontology-query/SKILL.md

@@ -41,53 +41,17 @@ SDD 流程：Propose → Spec → Design → Task → Check → Apply → Archiv
 
 ## Session 启动（每次用本 Skill 必做）
 
-> **📡 共享状态**：本技能与 `opsx-kb-ingest` **共用同一份 KB 配置**（`../.shared/kb-state.json`）。任一 skill 配置后，另一个自动可用，无需重复输入 API Key。
+> **📡 共享状态**：本技能与 `opsx-kb-ingest`、`kb-upload` **共用同一份 KB 配置**（`kb-state.json`，位于 spec 仓根目录）。KB 配置（API Key + Space/KB 选择 + project-identity.json）由 `opsx-kb-config` 统一负责。
 
 ```
 Task Progress:
-- [ ] 1. 读 ../.shared/kb-state.json（没有则当空）
-- [ ] 2. 无 apiKey → 向用户索取并写入共享 state（勿把完整 key 打进聊天摘要）
-- [ ] 3. 无 targets 或用户要重置 → 拉空间/KB 列表，让用户多选后写入
-- [ ] 4. 按意图查询（可对多个 KB 逐个查询）
-- [ ] 5. 按模板输出；无命中不编造
+- [ ] 1. 读 kb-state.json（spec 仓根目录）
+- [ ] 2. 无 apiKey 或无 targets → 提示用户运行 /opsx-kb-config 配置知识库
+- [ ] 3. 有配置 → 按意图查询（可对多个 KB 逐个查询）
+- [ ] 4. 按模板输出；无命中不编造
 ```
 
-**API Key**：控制台「API 密钥」创建，scope ≥ `context:read`。401/403 → 清掉 apiKey 请用户重贴，勿循环重试。
-
-**选择空间/KB**：`GET $API/v1/spaces?tenantKey=…` → 对每个 space `GET …/knowledge-bases` → 展示清单**允许多选** → 写入共享 `../.shared/kb-state.json` 的 `targets`。
-
-### 3.5 写入项目身份文件（首次配置 Space 后）
-
-> `project-identity.json` 是 spec 仓 Git 中的**团队共享**文件，记录 `project_id`（= KB Space 的 `spaceKey`）。Archive 阶段 `archive-docs` 读取此文件生成 `archive-manifest.json`，kb-ingest 上传时 KB 校验 `project_id === spaceKey`。
-
-选择 Space 完成后（Step 3 写入 `targets` 后），执行以下逻辑：
-
-1. 读取 spec 包裹包路径：
-   ```bash
-   SPEC_ROOT=$(node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" spec-root)
-   ```
-2. 检查 `$SPEC_ROOT/skywalk-sdd/project-identity.json` 是否已存在
-3. **不存在** → 创建（取 `targets[0].spaceKey` 作为 `project_id`）：
-   ```json
-   {
-     "schema_version": "kld-sdd-project-identity/v1",
-     "project_id": "<targets[0].spaceKey>",
-     "created_at": "<ISO timestamp>",
-     "kb_space_id": "<targets[0].spaceId>",
-     "kb_space_name": "<targets[0].spaceName>"
-   }
-   ```
-   输出：`✓ 已创建 skywalk-sdd/project-identity.json（project_id: <spaceKey>），请提交到 spec 仓 Git 以便团队共享`
-4. **已存在但 `project_id` 与 `targets[0].spaceKey` 不一致** → 用 AskUserQuestion 询问：
-   > "project-identity.json 中的 project_id 与当前选择的 KB Space spaceKey 不一致：
-   > - 文件中：`<existing project_id>`
-   > - 当前 Space：`<spaceKey>`
-   > 是否更新？"
-   - 用户确认 → 更新 `project_id` + `kb_space_id` + `kb_space_name`
-   - 用户拒绝 → 保留原值（可能入库时报 `PROJECT_SPACE_MISMATCH`）
-5. **已存在且一致** → 跳过，不输出
-
-> state.json 字段 schema、鉴权细节、列表接口 → [reference.md](reference.md)。
+> **KB 配置**（API Key、Space/KB 选择、project-identity.json）由 `opsx-kb-config` 统一负责。如用户需要配置或更换 KB，请引导运行 `/opsx-kb-config`。
 
 ## 查询
 
@@ -118,12 +82,12 @@ Task Progress:
 ### 编号文法速查（权威在 KB 仓设计 §2）
 
 ```text
-requirement: ^REQ-[A-Z][A-Z0-9]{1,7}-[0-9]{4}-[0-9]{3,6}$
-feature:     ^FEAT-[A-Z][A-Z0-9]{1,7}-[0-9]{3,6}$
-scenario:    ^REQ-…:SCN-[a-z0-9]+(-[a-z0-9]+)*-[0-9]{3}$
+requirement: ^[A-Z0-9_-]+$
+feature:     ^[A-Z0-9_-]+$
+scenario:    ^[A-Z0-9_-]+:SCN-[a-z0-9]+(-[a-z0-9]+)*-[0-9]{3}$
 ```
 
-归一化：trim；REQ/FEAT 段大写；SCN slug 小写。编号五律摘要：REQ/FEAT 仅需求系统铸号；SCN 由 kld-sdd/opsx-spec 铸号；编号≠身份；归属权威在需求系统；历史绑定 append-only。
+归一化：trim；requirement/feature 段大写；SCN slug 小写。编号五律摘要：requirement/feature 由外部需求系统铸号（格式不限 REQ-/FEAT- 前缀，白名单 A-Z 0-9 - _）；SCN 由 kld-sdd/opsx-spec 铸号；编号≠身份；归属权威在需求系统；历史绑定 append-only。
 
 > 按功能号圈能力（FEAT query）、match-requirement / resolve 完整 curl 示例与响应字段解读 → [reference.md](reference.md)。
 
@@ -148,16 +112,14 @@ scenario:    ^REQ-…:SCN-[a-z0-9]+(-[a-z0-9]+)*-[0-9]{3}$
 - 无 `apiKey` 不得猜密钥、不得改走 login。
 - 无 `targets` 不得臆造 spaceId/kbId。
 - 无命中 → 写明「无当前依据」，禁止编造条款。
-- 完整 apiKey 只写共享 state 文件（`../.shared/kb-state.json`）；聊天里最多显示前缀（如 `sk_sdd_****`）。
+- 完整 apiKey 只写共享 state 文件（`kb-state.json`，spec 仓根目录）；聊天里最多显示前缀（如 `sk_sdd_****`）。
 - **共享状态**：state 文件与 `opsx-kb-ingest` 共用。配置一次，两个 skill 都生效。
 
 ## 用户口令
 
 | 用户说 | Agent 做 |
 |--------|----------|
-| （首次使用） | 要 key → 选 KB（多选）→ 写共享 state → 再查。此后 `opsx-kb-ingest` 也自动可用 |
-| 换密钥 / 重置 API Key | 清 apiKey，重走 Session 第 2 步 |
-| 重新选择 / 重置空间或知识库 | 清 targets，重走 Session 第 3 步 |
+| 配置 / 换密钥 / 换 KB | 引导运行 `/opsx-kb-config`（本技能不处理配置） |
 | 查 / Spec 复用 / 影响… | 用当前共享 targets 查询 |
 
 ## 心智模型

package/templates/skills/kld-sdd/opsx-ontology-query/phase-3-postchange.md

@@ -216,8 +216,8 @@ curl -sS -H "Authorization: Bearer $API_KEY" \
 |----------|------|----------|
 | `VERSION_CONFLICT` | predecessor 不匹配当前 version | 回 spec 获取正确 predecessor，重新 archive |
 | `EXTERNAL_REF_CONFLICT` | 同 external key 绑定不同 entity_id | 回 propose/spec 确认身份决议 |
-| `EXTERNAL_REFERENCE_FORMAT_INVALID` | 编号归一化后不合文法（含 requirement.`feature_id`） | 回需求管理系统换发合规编号，禁止手改硬闯 |
-| `EXTERNAL_REFERENCE_SCOPE_MISMATCH` | 场景键 REQ 前缀不在同包 requirement 集合 | 回 spec 修正 external-ref 中 SCN 的 REQ 前缀 |
+| `EXTERNAL_REFERENCE_FORMAT_INVALID` | 编号含非白名单字符（A-Z 0-9 - _ 之外的字符）或超长 | 检查外部编号来源，修正后重新入库 |
+| `EXTERNAL_REFERENCE_SCOPE_MISMATCH` | 场景键需求编号前缀不在同包 requirement 集合 | 回 spec 修正 external-ref 中场景键的需求编号前缀 |
 | `EXTERNAL_REFERENCE_FEATURE_UNBOUND` | feature 绑定与 requirement.`feature_id` 无法配对 | 回 propose/archive 修正线缆字段，确认 FEAT 号存在 |
 
 > **禁止**在 KB 内现场改绑或解绑。必须回 SDD 流程修正后重新入库。

package/templates/skills/kld-sdd/opsx-ontology-query/reference.md

@@ -8,7 +8,7 @@
 
 ```json
 {
-  "api": "http://localhost:8090/api",
+  "api": "http://10.29.213.80:8080/api",
   "tenantKey": "default",
   "apiKey": "sk_sdd_…",
   "updatedAt": "2026-07-19T12:00:00Z",

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": []
-}