kld-sdd 2.6.8 → 2.6.10

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

@@ -17,7 +17,9 @@ allowed-tools:
 
 你是一个 SDD（Specification-Driven Development）业务意图文档专家。激活本技能后，你将引导用户创建符合质量红线标准的 **proposal.md** 文档。
 
-> **硬依赖**：本技能 Continuity 步骤依赖同级已部署的 **`opsx-ontology-query`**。启动 Continuity 前必须先 `Read` 该技能的 `SKILL.md`，并按其中流程准备 `.local/state.json`（API Key + targets）。若项目 skills 目录中不存在 `opsx-ontology-query/`，停止 Continuity，提示用户重新执行 `kld-sdd-init`；**禁止**用本地 `archive/` 冒充查询。
+> **硬依赖**：本技能 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/` 冒充查询。
+>
+> **📡 KB 就绪检查**：§6.5 在进入编号入场前会检测 KB 配置状态。若未配置，会**主动询问**用户选择「配置」或「跳过」，不再静默降级。
 
 > **⚠️ 阶段边界约束**
 >
@@ -32,7 +34,9 @@ allowed-tools:
 > 阶段边界自检见 `./checklist.md`「阶段边界⛔」。
 
 > **🖥️ 跨平台执行规则**
-> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
+> - `openspec` 命令：优先 `node skywalk-sdd/openspec-shim.cjs list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
+> - `skywalk-sdd/log.cjs` / `ontology/cli.cjs`：`--project=.` 在 Git 根/工作区根会自动解析；也可 `node skywalk-sdd/ontology/cli.cjs spec-root` 查看路径。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
@@ -201,7 +205,16 @@ node skywalk-sdd/ontology/cli.cjs external-key --validate "<FEAT-...>" --type fe
 ```
    - REQ/FEAT 不合规 → **拒绝进入 resolve**，告知「编号不合规，请回需求管理系统核实/换发」；Agent 不得猜测、补位、改写。
    - 用户明确说「没有外部需求号」→ 走 `numbering-waiver.reason`（必填理由）；`requirement-refs` 必须为空；提示本轮不种桥。
-3. **先加载依赖技能**：确认 `${AGENT_SKILL_DIR}/opsx-ontology-query/SKILL.md` 存在并 Read；按该技能完成 API Key / 空间与 KB 选择。未安装则停止本步。
+3. **先加载依赖技能**：确认 `${AGENT_SKILL_DIR}/opsx-ontology-query/SKILL.md` 存在并 Read；按该技能完成 API Key / 空间与 KB 选择（`../.shared/kb-state.json`，与 `opsx-kb-ingest` 共用）。未安装则停止本步。
+   - **KB 就绪检查**：运行 `node 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)`）。
+     - **选 C** → 终止 propose。
 4. 验号通过后才 resolve：
 ```bash
 node skywalk-sdd/context-client.cjs --mode=resolve \
@@ -216,9 +229,40 @@ node 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；决议写入 `continuity-resolution.json` 的 `capabilities[]`。
-9. KB 不可用 → `degraded` 继续，**禁止**扫本地 `archive/` 抄 UUID。
+9. KB 不可用 → `degraded` 继续，**禁止**扫本地 `archive/` 抄 UUID。KB degraded（用户选择跳过）时走路径 B（archive 降级）：
+   - 扫描 `openspec/changes/archive/*/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`。
 10. **不得**在本阶段生成 STMT/AC/场景或裁决场景身份；**不得**铸/改 REQ/FEAT 号。
 
+**完整流程示例（路径 A — KB 驱动）**：
+```
+# 对每个能力域按 canonicalKey 查 KB
+resolve(canonicalKey=CAP-ACCOUNT-LOCKOUT) → RELATED_ONLY (reviewRequired)
+  → candidates[0]: entity-id=90c49a72, version=d6787d6e (来自 KB current)
+  → 用户确认复用 → modified, predecessor=d6787d6e
+resolve(canonicalKey=CAP-PHONE-LOGIN) → RELATED_ONLY (reviewRequired)
+  → candidates[0]: entity-id=xxx, version=yyy (来自 KB current)
+  → 用户确认复用 → modified, predecessor=yyy
+resolve(canonicalKey=CAP-USER-REGISTRATION) → CREATE_NEW
+  → KB 中无此 canonicalKey
+  → added, 新 CAP-USER-REGISTRATION
+```
+
+**完整流程示例（路径 B — archive 降级）**：
+```
+# 扫描归档（仅 KB degraded 时）
+Read openspec/changes/archive/*/proposal.md 的能力分解章节
+Read openspec/changes/archive/*/ontology-identities.json
+
+# 匹配结果示例：
+# "账号锁定从内存迁到DB" → 匹配归档 CAP-ACCOUNT-LOCKOUT (entity-id: 3d18c60e, version: 29e7f242)
+#   → modified, 复用 entity-id=3d18c60e, predecessor=29e7f242
+#   → ⚠️ source: archive(degraded)
+# "新增用户注册 API" → 无匹配
+#   → added, 新 CAP-USER-REGISTRATION
+```
+
 ### 7. 【交互引导】文档拆分模式选择
 
 **❗ 必须主动询问用户，不得默认选择**。Full / Simple / Auto 三种模式的目录结构、适用场景与 AskUserQuestion 文案见 `./reference.md`「§7 文档拆分模式选择」。根据用户选择设置 `mode: full | simple`（Auto 按能力域数量判断），记录到 proposal.md 的 YAML frontmatter。

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

@@ -44,3 +44,4 @@ description: opsx-propose 的阶段强制检查点与自检清单。仅在执行
 - [ ] 每次生成都提供文档摘要，等待用户确认后再继续
 - [ ] ⛔ **阶段边界**：本阶段禁止执行任何代码创建/修改操作；用户要求处理代码时回复「当前处于 Propose 阶段，代码操作请在完成文档后使用 `/opsx-apply` 执行。」
 - [ ] ⛔ **单阶段原则**：完成 proposal.md 后必须立即停止；仅提示用户下一步可运行 `/opsx-spec`，绝对禁止自动执行 spec/design/task 等后续阶段。每个阶段必须由用户主动触发。
+- [ ] ⛔ **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`。

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

@@ -19,7 +19,9 @@ allowed-tools:
 你是一个 SDD 项目规则生成与维护专家。激活本技能后，你将扫描项目事实，为已部署的 Agent 生成或审查规则文件。
 
 > **🖥️ 跨平台执行规则**
-> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
+> - `openspec` 命令：优先 `node skywalk-sdd/openspec-shim.cjs list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
+> - `skywalk-sdd/log.cjs` / `ontology/cli.cjs`：`--project=.` 在 Git 根/工作区根会自动解析；也可 `node skywalk-sdd/ontology/cli.cjs spec-root` 查看路径。
 > - ${SHELL_GUIDANCE}
 > - **本技能不写入 SkyWalk Telemetry**（与 `opsx-knowledge` 同属辅助技能，不走 `log.cjs start/end`）。
 

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

@@ -17,7 +17,9 @@ allowed-tools:
 
 你是一个 SDD（Specification-Driven Development）技术契约专家。激活本技能后，你将引导用户为每个 Capability 创建 **spec.md** 文档。
 
-> **硬依赖**：场景身份 / Spec 复用依赖同级已部署的 **`opsx-ontology-query`**。进入知识库上下文步骤前必须先 `Read` 该技能的 `SKILL.md` 并完成其 Session 启动（API Key + targets）。缺失则停止复用查询，提示重新 `kld-sdd-init`；**禁止**从本地 `archive/` 抄 UUID。
+> **硬依赖**：场景身份 / 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。
+>
+> **📡 KB 就绪检查**：§2.5 在进入上下文加载前会检测 KB 配置状态。若未配置，会**主动询问**用户选择「配置」或「跳过」，不再静默降级。
 
 > **⚠️ 阶段边界约束**
 >
@@ -32,7 +34,9 @@ allowed-tools:
 > 阶段边界自检见 `./checklist.md`「阶段边界⛔」。
 
 > **🖥️ 跨平台执行规则**
-> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
+> - `openspec` 命令：优先 `node skywalk-sdd/openspec-shim.cjs list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
+> - `skywalk-sdd/log.cjs` / `ontology/cli.cjs`：`--project=.` 在 Git 根/工作区根会自动解析；也可 `node skywalk-sdd/ontology/cli.cjs spec-root` 查看路径。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
@@ -104,6 +108,34 @@ openspec list
 >
 > 请选择要为哪个 Capability 创建 spec.md："
 
+### 2.5 【KB 就绪检查】检测并配置知识库连接
+
+在进入上下文加载之前，检测 Engineering KB 的连接状态。**不得静默降级**。
+
+1. 检查 proposal.md frontmatter 中 `kb-status` 字段：
+   - 若 `kb-status: degraded(by-user-choice)` → KB 已在 propose 阶段由用户明确跳过，本阶段同样跳过 KB 查询，直接进入 §3（仅加载本地上下文）。
+   - 若未标记 → 继续检查。
+2. 运行 KB 就绪检查（程序化检测，自动搜索多 IDE 目录，消除路径歧义）：
+   ```bash
+   node skywalk-sdd/context-client.cjs --check-only
+   ```
+   - 输出 `"available": true` → KB 已配置
+   - 输出 `"available": false` → KB 未配置
+3. **若已配置** → 直接进入 §3。
+4. **若未配置** → 使用 **AskUserQuestion** 询问：
+
+   > "📡 **Engineering KB 未配置**
+   >
+   > KB 可以提供场景身份验证、Spec 复用和历史 AC 检索。是否现在配置？
+   >
+   > - A. **配置 KB**
+   > - B. **跳过 KB**，仅使用本地上下文（archive 降级，标注 `source: archive(degraded)`）
+   > - C. **取消操作**"
+
+   - **选 A** → 配置 → 进入 §3。
+   - **选 B** → 在 spec.md frontmatter 标注 `kb-status: degraded(by-user-choice)`，进入 §3（仅本地上下文）。
+   - **选 C** → 终止 spec。
+
 ### 3. 【上下文加载】识别并读取用户提供的文件
 
 **自动识别上下文文件**：若用户在命令中指定了文件路径，或在对话中附加/引用了文件，**必须自动读取这些文件**。
@@ -112,7 +144,7 @@ openspec list
 
 **【默认尝试】工程 Spec 知识库上下文（场景身份主战场）**：
 
-1. **先加载依赖技能**：确认 `${AGENT_SKILL_DIR}/opsx-ontology-query/SKILL.md` 存在并 Read；按该技能完成 API Key / targets（`.local/state.json`）。未安装则停止本步。
+1. **先加载依赖技能**：确认 `${AGENT_SKILL_DIR}/opsx-ontology-query/SKILL.md` 存在并 Read；按该技能完成 API Key / targets（`../.shared/kb-state.json`，与 `opsx-kb-ingest` 共用）。未安装则停止本步。
 2. 读取 proposal Continuity。对**当前 Capability** 各调一次（「全部」= 循环 N 次，不是一次大查询）——优先走 **`opsx-ontology-query`** 的 `match-requirement`；薄封装仅作参数拼装：
 
 ```bash
@@ -223,7 +255,7 @@ node skywalk-sdd/context-client.cjs \
 - 新需求、场景和约束分别使用 `STMT-*`、`AC-*`、`CON-*`；分配规则是同前缀同 Capability 当前最大序号 + 1。
 - 修改已有实体必须复用原 ID；删除实体只写 removal 语义，不得把编号分配给新实体。
 - `added` 必须调用 `semantic-identity --delta-state=added` 生成新的实体 UUID 和版本 UUID；禁止通过复制另一需求的 UUID 创建新实体。
-- `modified/removed` 必须从 **KB**（match-requirement / resolve）取得历史 `entity-id` 和直接前序 `version-id`，调用 `semantic-identity --delta-state=<modified|removed> --entity-id=<UUID> --predecessor-version=<UUID>`；实体 UUID 复用，版本 UUID 新建。禁止把本地 archive 目录当跨迭代继承权威。
+- `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 当跨迭代继承权威。
 - AC 必须嵌套在所属 STMT 下；CON 必须通过 `**constrains**` 显式引用 STMT。
 - 对 `reuseMode=REFERENCE` 的历史候选必须创建新的实体身份；禁止因为内容相似而复用历史 `entity-id`。
 - 对 `reuseMode=INHERIT` 的历史事实，必须使用返回的实体与版本来源完成 unchanged/modified 身份参数校验。

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

@@ -28,6 +28,15 @@ allowed-tools:
 > **完成本阶段后，绝对禁止自动继续执行 apply/check 等后续阶段。**
 > 阶段边界自检见 `./checklist.md`「阶段边界⛔」。
 
+> **KB 上下文**：任务拆解时可参考历史任务分解策略。
+> 1. 检查 proposal.md frontmatter `kb-status`：若 `degraded(by-user-choice)` → 跳过 KB，仅用本地上下文。
+> 2. 否则运行 KB 就绪检查：
+> ```bash
+> node skywalk-sdd/context-client.cjs --check-only
+> ```
+> - `"available": true` → 若需查历史任务参考，先 `Read` `opsx-ontology-query/phase-2-during.md` §2
+> - `"available": false` → **KB 不可用不阻塞 task 流程**，仅跳过历史任务追溯参考
+
 > **⚠️ 渐进式上下文加载原则**
 >
 > - 本技能针对**单一 Capability** 执行任务拆解（Simple 模式例外，见下方 S1 说明）
@@ -38,7 +47,9 @@ allowed-tools:
 > - ⛔ **隔离红线**：绝对禁止跨目录读取同级其他 Capability 的文档（Full 模式）
 
 > **🖥️ 跨平台执行规则**
-> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
+> - `openspec` 命令：优先 `node skywalk-sdd/openspec-shim.cjs list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
+> - `skywalk-sdd/log.cjs` / `ontology/cli.cjs`：`--project=.` 在 Git 根/工作区根会自动解析；也可 `node skywalk-sdd/ontology/cli.cjs spec-root` 查看路径。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。

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

@@ -24,7 +24,9 @@ allowed-tools:
 > - 输出标准化测试报告，便于质量追踪
 
 > **🖥️ 跨平台执行规则**
-> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
+> - `openspec` 命令：优先 `node skywalk-sdd/openspec-shim.cjs list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
+> - `skywalk-sdd/log.cjs` / `ontology/cli.cjs`：`--project=.` 在 Git 根/工作区根会自动解析；也可 `node skywalk-sdd/ontology/cli.cjs spec-root` 查看路径。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。