kld-sdd 2.6.7 → 2.6.9

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

@@ -1,6 +1,6 @@
 # 本体查询 · 参考
 
-需要鉴权细节、state 字段或响应字段时再读。
+需要鉴权细节、state 字段、API curl 示例或响应字段时再读。
 
 ## `.local/state.json`
 
@@ -68,6 +68,12 @@ API Key 一般为租户范围；`apiKeySpaceId` 为空时可列出租户下多
 
 `POST {base}/context/search`
 
+```bash
+curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/context/search" \
+  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
+  -d '{"query":"用户登录与会话","entityTypes":[],"limit":15}'
+```
+
 ```json
 { "query": "string", "entityTypes": [], "limit": 15 }
 ```
@@ -75,14 +81,30 @@ API Key 一般为租户范围；`apiKeySpaceId` 为空时可列出租户下多
 | 字段 | 含义 |
 |------|------|
 | `degraded` / `degradationReasons` | 向量/AGE/rerank 等降级 |
+| `advisory` | true=结果为建议性，非权威；Agent 应在输出中标注 |
 | `results[].matchType` | exact / structural / fulltext / vector / graph … |
 | `results[].entityId` / `entityVersionId` | 溯源 |
+| `results[].snippet` | 命中片段预览 |
+| `results[].source` | 溯源信息（file/line/anchor_id/change_id/archive_id） |
+| `results[].reviewStatus` | 审核状态 |
+| `results[].score` | 归一化分数 |
 | `results[].scoreExplanation` | RRF channel ranks 等 |
 
 ## entities/resolve（Continuity / 外部需求号）
 
 `POST {base}/entities/resolve`
 
+```bash
+curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/entities/resolve" \
+  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
+  -d '{
+    "externalSystem":"requirement-mgmt",
+    "externalObjectType":"requirement",
+    "externalId":"REQ-FI-2024-001",
+    "entityType":"Capability"
+  }'
+```
+
 ```json
 {
   "externalSystem": "requirement-mgmt",
@@ -97,16 +119,60 @@ API Key 一般为租户范围；`apiKeySpaceId` 为空时可列出租户下多
 | 结果 | 含义 |
 |------|------|
 | `resolution=LINK_EXISTING` + `inheritanceAllowed=true` | ≥1 可继承绑定；`candidates` 仅存活实体；`removedBindingCount` 为失效绑定数 |
+| `resolution=SAME_ITERATION` | entityId/previousVersionId 精确命中，已对齐同一实体 |
+| `resolution=CREATE_NEW` | 无匹配，全新需求 |
+| `resolution=RELATED_ONLY` | canonicalKey/名称匹配但无确定性身份，仅候选 |
 | `matchType=HISTORICAL_ONLY` | 有绑定但全部无 current / removed；`inheritanceAllowed=false`，不得当迭代继承 |
 | `NEEDS_CONFIRM` / `SIMILAR_REQUIREMENT` | 名称/结构相似，仅候选 |
 | `NEW_REQUIREMENT` | 无命中 |
 
-**禁止**用本地 `archive/` 目录当跨迭代继承源。
+> **补充响应字段**：
+> - `reviewRequired`：true=需人工确认
+> - `supportEvidence` / `oppositionEvidence`：支持/反对决议的证据列表，Agent 可向用户展示
+> - `clarificationQuestions`：AI 生成的澄清问题，Agent 可用 `ask_user` 呈现给用户
+
+**KB 可用时禁止**用本地 `archive/` 目录当跨迭代继承源，entity-id 必须来自 KB resolve by canonicalKey。KB degraded 时 archive 可作为降级手段（标注 `source: archive(degraded)`）。
+
+## 按功能号圈能力（FEAT query）
+
+在 propose 前，用 feature 编号查询该功能下已有能力清单，辅助勾选本次 CAP 范围。
+
+`POST {base}/entities/resolve`（与 Continuity 同一接口，`externalObjectType:"feature"`）
+
+```bash
+curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/entities/resolve" \
+  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
+  -d '{
+    "externalSystem":"requirement-mgmt",
+    "externalObjectType":"feature",
+    "externalId":"FEAT-FI-012",
+    "entityType":"Capability"
+  }'
+```
+
+响应中 `candidates` 列出该 FEAT 下存活 / 失效能力清单；`removedBindingCount` 为已失效绑定数。
+
+> 此查询只作范围参考，不改变 Continuity 判定优先级。
 
 ## context/match-requirement
 
 `POST {base}/context/match-requirement`
 
+```bash
+curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/context/match-requirement" \
+  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
+  -d '{
+    "query":"用户登录与会话",
+    "targetStage":"spec",
+    "entityId":"<capability-entity-uuid>",
+    "externalSystem":"requirement-mgmt",
+    "externalObjectType":"requirement",
+    "externalId":"REQ-FI-2024-001"
+  }'
+```
+
+检索通道：精确/结构 + 全文 + 向量（就绪时）→ RRF →（可选）图谱扩展。看 `degraded` / `degradationReasons`。
+
 ```json
 {
   "query": "string",
@@ -129,6 +195,13 @@ API Key 一般为租户范围；`apiKeySpaceId` 为空时可列出租户下多
 | `NEEDS_CONFIRM` | 需人确认 |
 | `NEW_REQUIREMENT` | 无可信复用 |
 
+> **补充响应字段**：
+> - `advisory`：true=结果为建议性
+> - `reviewRequired`：true=需人工确认
+> - `specGenerationContext`：复用统计（`reusableStatements`/`reusableAcceptanceCriteria`/`reusableConstraints`/`reusableDesignElements`/`unresolvedQuestions`），Agent 可据此判断复用率
+> - `warnings`：注意事项（如"相似度只能产生候选，不能自动 sameAs"）
+> - `clarificationQuestions`：AI 生成的澄清问题，Agent 可用 `ask_user` 呈现给用户
+
 ## 对象读
 
 | 方法 | 路径 |
@@ -141,6 +214,8 @@ API Key 一般为租户范围；`apiKeySpaceId` 为空时可列出租户下多
 
 `impact` / `ontology-view` 走 PG 关系；与 `context/search` 不同链路。
 
+`impact` 响应字段：`anchorEntityId`（锚点实体 ID）、`maxDepth`（最大影响深度≤4）、`nodes`（含 entityId/entityVersionId/entityType/displayName/depth）、`edges`（含 relationType/fromEntityId/toEntityId/assertionType）。
+
 ## disclosures
 
 `POST {base}/context/disclosures`
@@ -150,8 +225,21 @@ API Key 一般为租户范围；`apiKeySpaceId` 为空时可列出租户下多
   "anchorId": "STMT-…",
   "entityId": null,
   "entityVersionId": null,
-  "level": "preview"
+  "sourceLevel": "preview"
 }
 ```
 
-`level`：`preview` | `section` | `document`。
+`sourceLevel`：`preview` | `section` | `document`。
+
+> 注：请求字段名为 `sourceLevel`（不是 `level`）。响应中对应字段为 `disclosureLevel`。
+> 请求还支持可选的 `relationDepth`、`direction`、`relationTypes`、`entityTypes`、`relatedLimit`。
+
+## 实现备注
+
+> 控制台 Agent 架构 / Skills 激活机制 / 记忆策略。对查询操作无直接影响，仅供维护者参考。
+
+- 控制台知识库页另有浮动 Ontology Agent（会话登录 + SSE）；本 Skill 走 API Key，二者分开。
+- **Agent 角色（V1）**：控制台 Agent 是**单一 ReActAgent + 角色人格切换**（架构师 / 业务分析师 / 数据分析师），不是三个独立 JVM agent。共享工具集，仅 sysPrompt 与工具偏好不同——Studio 仍单 run、延迟更低，后续需要再拆。
+- 交互硬规则：自然语言优先，不向用户索要 UUID；多实体时用 `ask_user` Generative UI 卡片（`type=choice`，options.label=名称）。
+- **Skills 激活**：控制台 Agent 通过 AgentScope `FileSystemSkillRepository`（`skillsRoot`，见 `classpath:agent/agent.yml`）挂载本目录；运行时用内置工具 `load_skill_through_path`（skillId=`opsx-ontology-query`，path=`SKILL.md` / `reference.md`）按需加载，不把全文塞进 system prompt。
+- **记忆**：会话短期用 AgentScope `InMemoryAgentStateStore`；本体事实仍走 KB（pgvector/SQL）。不需要 mem0，除非以后要跨会话个人偏好记忆。

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 配置状态。若未配置，会**主动询问**用户选择「配置」或「跳过」，不再静默降级。
 
 > **⚠️ 阶段边界约束**
 >
@@ -54,13 +56,25 @@ allowed-tools:
 
 ## 启动流程
 
-### 1. 输入处理
+### 1. 输入处理与 Change Key 生成
 
 当用户激活此 skill 时：
 
-**若提供了变更名称/描述**：
-- 解析为 kebab-case 名称（如 "add user authentication" → `add-user-auth`）
-- 跳转到第 2 步
+**若提供了变更描述（中文优先）**：
+1. 保留中文描述作为 `title`（人读名称）
+2. 读取项目根 `modules.yaml`；不存在则先引导创建（可参考模板 `templates/modules.yaml`）
+3. 从描述推断模块代号；无法唯一判断时用 **AskUserQuestion** 让用户选择
+4. 涉及多个模块时使用保留代号 `cross`，并准备 `affected-modules`（≥2）
+5. 生成英文短 slug（小写、连字符、建议 ≤48 字符）
+6. 用本地日历日 `YYMMDD` 生成 change-key，并做冲突消解：
+   ```bash
+   node skywalk-sdd/ontology/cli.cjs change-key --generate --module=<code> --slug=<slug> --project=.
+   ```
+7. 得到：
+   - `change-key`：spec 仓目录名 `openspec/changes/<change-key>/`（权威名称；不等于代码分支名）
+   - `change-id`：`CHG-` + change-key 大写（仅创建时生成一次，之后永不改）
+   - 若在个人工作目录执行：可顺带提醒未接入的代码子仓执行 `kld-sdd sync-repos`（不装 skills）
+8. 跳转到第 2 步
 
 **若未提供任何输入**，使用 **AskUserQuestion** 询问：
 > "请描述本次变更的业务需求：
@@ -69,14 +83,15 @@ allowed-tools:
 > 3. 涉及哪些模块/系统？
 > 4. 有什么约束条件？（时间/技术/资源）"
 
-从描述中推导 kebab-case 名称。
-
 **【澄清机制】若用户描述模糊，主动追问**：
 - 若目标不明确："请用一句话明确本次变更要达成的具体目标"
 - 若影响范围不清："请列出本次变更涉及的所有模块/服务"
 - 若约束未提及："是否有时间限制、技术约束或依赖前提？"
 
-**重要**：未明确需求前不得继续。
+**重要**：未明确需求前不得继续。change-key 必须通过校验，禁止手写不合规目录名：
+```bash
+node skywalk-sdd/ontology/cli.cjs change-key --validate <change-key> --project=.
+```
 
 ### 2. 【上下文加载】识别并读取用户提供的文件
 
@@ -99,23 +114,36 @@ allowed-tools:
 ```bash
 openspec list --json 2>/dev/null || true
 ```
-或直接探测 `openspec/changes/<name>/` 是否存在（含 `.openspec.yaml` 或 `proposal.md`）。排除 `logs/` 目录——`logs/` 是 telemetry 自动创建的，不代表变更已初始化。
+或直接探测 `openspec/changes/<change-key>/` 是否存在（含 `.openspec.yaml` 或 `proposal.md`）。排除 `logs/` 目录——`logs/` 是 telemetry 自动创建的，不代表变更已初始化。
 
 **第 2 步：根据检测结果决定**：
 - **不存在** → 直接执行第 3 步创建。
-- **已存在** → 先询问用户，**不要直接 new**："变更 `<name>` 已存在，请选择：
+- **已存在** → 先询问用户，**不要直接 new**："变更 `<change-key>` 已存在，请选择：
   - A. 覆盖原有变更（删除重建）
   - B. 继续编辑现有变更
   - C. 取消操作"
   - **若目录仅含 `logs/`（无 `.openspec.yaml` 且无 `proposal.md`）**：提示用户"检测到残留空变更目录（仅含 telemetry 自动创建的 logs/），建议选 A 覆盖重建，避免复用空目录导致后续流程混淆"
-  - 用户选 A → 先删除 `openspec/changes/<name>/` 再执行第 3 步；选 B → 跳过创建直接进入 §4；选 C → 终止。
+  - 用户选 A → 先删除 `openspec/changes/<change-key>/` 再执行第 3 步；选 B → 跳过创建直接进入 §4；选 C → 终止。
 
 **第 3 步：创建变更目录**（仅在不存在或用户确认覆盖后执行）：
 ```bash
-openspec new change "<name>"
+openspec new change "<change-key>"
+```
+
+此命令在 `openspec/changes/<change-key>/` 创建变更目录和 `.openspec.yaml`。目录名必须等于 change-key。
+
+**第 4 步：隐式登记活动变更**（创建目录后立即执行，不询问用户）：
+```bash
+node skywalk-sdd/ontology/cli.cjs active-change --register --change=<change-key> \
+  --title="<中文标题>" --module=<code> --summary="<一句话摘要>" --project=.
 ```
 
-此命令在 `openspec/changes/<name>/` 创建变更目录和 `.openspec.yaml`。
+写入 spec 仓根目录 `sdd.config.yaml` 的 `active_changes`。作用：
+
+- 所有已接入代码仓的 AI 经 `sdd.specPath` 读到同一份，知道「当前在做哪个 change、中文叫什么」；
+- 代码仓 `git commit` 时由 commit-msg Hook 自动写成 `Spec-Change` Trailer（多个活动 change 就写多条）。
+
+登记按 change-key 幂等；同一 change 重复 propose 只更新标题/摘要。**不需要用户手工编辑该文件**。
 
 ### 3.5 【首次检测】overview.md 全局契约空模板引导
 
@@ -175,7 +203,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 \
@@ -190,9 +227,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。
@@ -238,7 +306,10 @@ node skywalk-sdd/context-client.cjs --mode=resolve \
 
 ## 本体语义生成契约
 
-- 创建 Change 时必须写入 `change-id: CHG-<CHANGE-SLUG>`；重新编辑时不得修改已有 Change ID。
+- 创建 Change 时必须写入 `change-key`、中文 `title`、`module`，以及 `change-id: CHG-<MODULE>-<YYMMDD>-<SLUG>`（由初始 change-key 派生一次）；重新编辑时不得修改已有 Change ID。
+- 创建 Change 目录后必须隐式执行 `active-change --register`（见 §3 第 4 步），把 change-key/标题/摘要登记进 spec 仓 `sdd.config.yaml`；漏登记会导致代码 commit 缺少 `Spec-Change`。
+- 跨模块 Change 使用 `module: cross`，并写入至少两个 `affected-modules`。
+- 存量 Change 迁移目录时必须保留原 `change-id`，不得按新目录重新派生。
 - 每个新增 Capability 必须写成 `[CAP-<CAPABILITY>] <slug>: <说明>`。
 - 修改既有 Capability 时必须复用已有 CAP ID，不得修改或重新分配已有实体 ID。
 - 分配新 CAP ID 前必须扫描当前 proposal 和归档中的显式编号；不得只凭标题认定跨 Change 同一性。

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-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 配置状态。若未配置，会**主动询问**用户选择「配置」或「跳过」，不再静默降级。
 
 > **⚠️ 阶段边界约束**
 >
@@ -104,6 +106,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 +142,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 +253,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 说明）
@@ -175,6 +184,7 @@ Simple 模式或单文件能力域下，**不要拆成多个同文件任务**。
 5. 非 TDD 模块（前端 UI/配置/SQL DDL）不拆红绿
 6. Controller 层策略必须在 tasks.md §2.0 中声明（策略 A 或 B），两种策略都必须生成测试任务
 7. ⛔ **GREEN 任务 YAGNI 围栏**：每个 GREEN-N 任务描述末尾必须包含"不提前实现 [后续 RED 行为]"围栏声明。规则详见 `opsx-tdd-rules/rules/green-yagni-fence.md`
+8. ⛔ **TDD 模式 DAG 并行标注**：当 `test-strategy=tdd` 时，DAG 拓扑图中每个 RED→GREEN 对必须标注 `⛔ 串行：不可同层并行`。同层存在多个 RED→GREEN 对时，必须在拓扑图中显式注明"本层 RED→GREEN 对须逐对串行执行，禁止并行派发"。非 TDD 模块的同层任务（如 UI/配置/SQL DDL）仍可并行。
 
 ⛔ BEFORE 生成 TDD 任务，必须读取：
 1. opsx-tdd-core/reference.md §6（DAG 生成规则表）

package/templates/skills/kld-sdd/opsx-tdd-core/checklist.md

@@ -24,7 +24,7 @@ description: "opsx-tdd-core 自检清单 — TDD 执行合规自检、合规性
 - [ ] REFACTOR 后全部测试仍绿
 - [ ] 未出现"先写生产代码再补测试"的情况
 
-## §B TDD 合规性检查（11 项）
+## §B TDD 合规性检查（15 项）
 
 仅 `test-strategy=tdd` 时执行：