kld-sdd 2.6.8 → 2.6.9

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

@@ -5,126 +5,85 @@ description: >-
   entity/impact/ontology-view). Prompts for API key and multi-selects spaces/KBs into
   local skill state. Use when looking up Spec/design facts, Spec reuse, impact, or
   citation-backed answers from the ontology KB.
+argument-hint: "[query or continuity intent]"
+license: MIT
+compatibility: Requires Engineering KB API (API Key with context:read).
+metadata:
+  author: sdd-team
+  version: "2.0"
+  source: "kb-sdd/skills/opsx-ontology-query"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
 ---
 
 # 本体知识库 · 查询
 
 只负责**查**。鉴权只用 **API Key**（`Authorization: Bearer sk_sdd_…`），**禁止**走手机号登录。
 
-> 控制台知识库页另有浮动 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**，除非以后要跨会话个人偏好记忆。
-
-本地状态文件（含密钥，勿提交）：
+> **部署说明**：随 `kld-sdd-init` 安装。`opsx-propose` / `opsx-spec` 等流程技能**硬依赖**本技能，缺失时不得用本地 archive 兜底。
+> 控制台 Agent 架构 / Skills 激活机制 / 记忆策略等实现细节 → [reference.md](reference.md)「实现备注」。
+
+## ⚠️ 数据边界（必读）
 
-```text
-skills/opsx-ontology-query/.local/state.json
+```
+SDD 流程：Propose → Spec → Design → Task → Check → Apply → Archive → kb-ingest
+                                                          ↑
+                                                   此刻之前，当前变更不在 KB 中
 ```
 
-字段说明 → [reference.md](reference.md)。
+- Propose → Check 阶段查 KB = 查**历史上下文**（上一次入库的状态）
+- 当前变更的 added/modified 实体在 KB 中**不存在**或**只有旧版本**
+- 当前变更内部一致性 → **本地文件 + semantic-check**，不查 KB
+- 只有 Archive → kb-ingest 后，当前变更才进入 KB（Phase 3 验证）
 
 ## Session 启动（每次用本 Skill 必做）
 
+> **📡 共享状态**：本技能与 `opsx-kb-ingest` **共用同一份 KB 配置**（`../.shared/kb-state.json`）。任一 skill 配置后，另一个自动可用，无需重复输入 API Key。
+
 ```
 Task Progress:
-- [ ] 1. 读 .local/state.json（没有则当空）
-- [ ] 2. 无 apiKey → 向用户索取并写入 state（勿把完整 key 打进聊天摘要）
+- [ ] 1. 读 ../.shared/kb-state.json（没有则当空）
+- [ ] 2. 无 apiKey → 向用户索取并写入共享 state（勿把完整 key 打进聊天摘要）
 - [ ] 3. 无 targets 或用户要重置 → 拉空间/KB 列表，让用户多选后写入
 - [ ] 4. 按意图查询（可对多个 KB 逐个查询）
 - [ ] 5. 按模板输出；无命中不编造
 ```
 
-### 1–2. API Key
-
-若 `state.apiKey` 为空或无效（401/403）：
-
-1. 请用户提供 API Key（控制台「API 密钥」创建，至少含 `context:read`）。
-2. 可选：请用户确认 `api`（默认 `http://localhost:8090/api`）与 `tenantKey`（默认 `default`）。
-3. 写入 `.local/state.json`（创建目录若不存在）。
-4. 用 `GET $API/health` 探活；再用 `GET $API/v1/spaces?tenantKey=…` + Bearer 校验 key。
-
-用户说「换密钥 / 重置 API Key」→ 清空 `apiKey`（可保留 targets），回到本步。
+**API Key**：控制台「API 密钥」创建，scope ≥ `context:read`。401/403 → 清掉 apiKey 请用户重贴，勿循环重试。
 
-### 3. 选择空间与知识库（支持多选）
+**选择空间/KB**：`GET $API/v1/spaces?tenantKey=…` → 对每个 space `GET …/knowledge-bases` → 展示清单**允许多选** → 写入共享 `../.shared/kb-state.json` 的 `targets`。
 
-若 `state.targets` 为空，或用户说「重新选择 / 重置空间 / 重置知识库」：
+> state.json 字段 schema、鉴权细节、列表接口 → [reference.md](reference.md)。
 
-1. `GET $API/v1/spaces?tenantKey=$TENANT_KEY`
-2. 对每个相关 space：`GET $API/v1/spaces/{spaceId}/knowledge-bases`
-3. 向用户展示「空间名 / spaceId → KB 名 / kbId」清单，**允许多选**。
-4. 写入 `targets: [{ spaceId, spaceName, spaceKey, kbId, kbName }, …]`。
-5. 仅清空 targets、保留 apiKey 即完成「重置空间和知识库」。
+## 查询
 
-查询时：对 `targets` **逐个**调用同一查询，结果按 KB 分组展示。用户若指定「只用某某 KB」，则仅查对应子集。
-
-### 4. 查询
-
-路径前缀：`/api/v1/spaces/{spaceId}/knowledge-bases/{kbId}`  
+路径前缀：`/api/v1/spaces/{spaceId}/knowledge-bases/{kbId}`
 所有请求：`-H "Authorization: Bearer $API_KEY"`
 
 | 意图 | 调用 |
 |------|------|
 | 开放问题 / 相似事实 | `POST …/context/search` |
-| Continuity / 按外部需求号定位身份 | `POST …/entities/resolve`（带 `externalSystem` / `externalObjectType` / `externalId`；可选 `entityType`） |
-| Spec 复用 / 转换 | `POST …/context/match-requirement`（可带外部三元组与/或 `entityId`） |
+| Continuity / 按外部需求号定位身份 | `POST …/entities/resolve` |
+| Spec 复用 / 转换 | `POST …/context/match-requirement` |
 | 对象详情 | `GET …/entities/{id}/current-version` |
 | 一跳结构 | `GET …/entities/{id}/ontology-view` |
 | 多跳影响 | `GET …/entities/{id}/impact` |
-| 原文 | `POST …/context/disclosures`（见 reference） |
-
-**机器意图（SDD 流程 Agent）**
+| 版本谱系 | `GET …/entities/{id}/lineage` |
+| 原文 | `POST …/context/disclosures` |
 
-- Continuity（只要身份、不要 reuseBundles）→ 优先 `POST …/entities/resolve`
-- Spec 复用 → `POST …/context/match-requirement`，带 external 与/或 `entityId`
-- **禁止**扫描消费方本地 `archive/` 目录当跨迭代继承源；历史有效规格以 KB current 为准
+> 各 API 的完整 curl 示例、请求/响应字段、matchType 含义、降级处理 → [reference.md](reference.md)。
 
-**search**
+**机器意图（SDD 流程 Agent）**：
 
-```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}'
-```
-
-**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"
-  }'
-```
+- Continuity（只要身份）→ 优先 `entities/resolve`
+- Spec 复用 → `context/match-requirement`，带 external 与/或 `entityId`
+- **KB 可用时禁止**扫描消费方本地 `archive/` 目录当跨迭代继承源；entity-id 必须来自 KB resolve by canonicalKey。KB degraded 时 archive 可作为降级手段（标注 `source: archive(degraded)`），历史有效规格以 KB current 为准
 
 命中时关注：`resolution=LINK_EXISTING` 且 `inheritanceAllowed=true`（可继承 n）；`removedBindingCount`（已失效绑定 m）；`matchType=HISTORICAL_ONLY` 表示仅有失效绑定，不可继承。
 
-**按功能号圈能力（propose 前）**
-
-```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"
-  }'
-```
-
-展示该功能下存活 / 失效能力清单，辅助勾选本次 CAP 范围；此查询只作范围参考，不改变 Continuity 判定优先级。
-
 ### 编号文法速查（权威在 KB 仓设计 §2）
 
 ```text
@@ -135,24 +94,9 @@ scenario:    ^REQ-…:SCN-[a-z0-9]+(-[a-z0-9]+)*-[0-9]{3}$
 
 归一化：trim；REQ/FEAT 段大写；SCN slug 小写。编号五律摘要：REQ/FEAT 仅需求系统铸号；SCN 由 kld-sdd/opsx-spec 铸号；编号≠身份；归属权威在需求系统；历史绑定 append-only。
 
-**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`。
+> 按功能号圈能力（FEAT query）、match-requirement / resolve 完整 curl 示例与响应字段解读 → [reference.md](reference.md)。
 
-### 5. 输出模板
+## 输出模板
 
 ```markdown
 ### 本体查询结论
@@ -160,6 +104,7 @@ curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/context/match-
 - 意图：{复用 | 事实检索 | 影响}
 - 可信度：{高 | 中（降级） | 无命中}
 - 降级：{reasons 或 无}
+- 建议性：{是（advisory=true） | 否}
 
 ### 命中
 1. **{displayName}**（{entityType}）@ {kbName}
@@ -167,25 +112,54 @@ curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/context/match-
    - 若外部键命中：可继承 n / 已失效绑定 m
 ```
 
-**硬规则**
+## 硬规则
 
 - 无 `apiKey` 不得猜密钥、不得改走 login。
 - 无 `targets` 不得臆造 spaceId/kbId。
 - 无命中 → 写明「无当前依据」，禁止编造条款。
-- 完整 apiKey 只写 state 文件；聊天里最多显示前缀（如 `sk_sdd_****`）。
+- 完整 apiKey 只写共享 state 文件（`../.shared/kb-state.json`）；聊天里最多显示前缀（如 `sk_sdd_****`）。
+- **共享状态**：state 文件与 `opsx-kb-ingest` 共用。配置一次，两个 skill 都生效。
 
 ## 用户口令
 
 | 用户说 | Agent 做 |
 |--------|----------|
-| （首次使用） | 要 key → 选 KB（多选）→ 再查 |
-| 换密钥 / 重置 API Key | 清 apiKey，重走第 2 步 |
-| 重新选择 / 重置空间或知识库 | 清 targets，重走第 3 步 |
-| 查 / Spec 复用 / 影响… | 用当前 targets 查询 |
+| （首次使用） | 要 key → 选 KB（多选）→ 写共享 state → 再查。此后 `opsx-kb-ingest` 也自动可用 |
+| 换密钥 / 重置 API Key | 清 apiKey，重走 Session 第 2 步 |
+| 重新选择 / 重置空间或知识库 | 清 targets，重走 Session 第 3 步 |
+| 查 / Spec 复用 / 影响… | 用当前共享 targets 查询 |
 
-## 心智模型（简述）
+## 心智模型
 
 - 本体真相在 PG（entity + relation）；控制台地图/对象用 SQL 遍历。
 - **外部需求号是确定性身份**；自然语言只产生 REFERENCE 候选，不能自动 sameAs。
-- `context/search` 才是语义检索主通道（+ 可选 AGE 扩邻）；跨迭代 Continuity 走 `entities/resolve`。
-- 细节与 state schema → [reference.md](reference.md)。
+- `context/search` 是语义检索主通道（+ 可选 AGE 扩邻）；跨迭代 Continuity 走 `entities/resolve`。
+
+## 渐进披露（阶段 Playbook）
+
+> **何时读哪个文件**——SDD 各阶段 skill 在对应步骤 `Read` 以下文件，获取场景化的 API 调用示例和决策逻辑。
+
+| 文件 | 何时 Read | 场景 |
+|------|----------|------|
+| [reference.md](reference.md) | 需要 API 字段细节 / state schema / 鉴权细节 | 完整 API 参考 |
+| [phase-1-prechange.md](phase-1-prechange.md) | opsx-propose §6.5 / opsx-spec §3 | 连续性检查、影响预评、历史 AC、Spec 复用、约束冲突 |
+| [phase-2-during.md](phase-2-during.md) | opsx-design / opsx-task / opsx-check | 历史设计参考、历史任务参考、历史覆盖率基线、入库前预检 |
+| [phase-3-postchange.md](phase-3-postchange.md) | opsx-archive 入库后 | 版本生效验证、AC 保留、关系完整性、谱系验证、冲突检测 |
+| [phase-4-explore.md](phase-4-explore.md) | 跨迭代探索 / 开发者手动 | 谱系追踪、语义检索、原文溯源、图谱导航、多跳影响 |
+| [phase-5-governance.md](phase-5-governance.md) | 治理流程 / 定期巡检 | 覆盖率仪表盘、一致性检查、漂移检测、候选审批、变更统计 |
+
+**快速定位**：
+
+```
+propose 前查影响范围？           → phase-1-prechange.md §2
+看某 STMT 有哪些历史 AC？        → phase-1-prechange.md §3
+复用历史 Spec？                  → phase-1-prechange.md §4
+查历史设计作参考？               → phase-2-during.md §1
+查历史覆盖率基线？               → phase-2-during.md §3
+入库前预检 predecessor？         → phase-2-during.md §5
+入库后验证版本生效？              → phase-3-postchange.md §1
+查实体完整变更历史？              → phase-4-explore.md §1
+用自然语言搜工程事实？            → phase-4-explore.md §2
+看全局覆盖率仪表盘？             → phase-5-governance.md §1
+当前变更内部一致性验证？          → 不查 KB，走本地文件 + semantic-check
+```

package/templates/skills/kld-sdd/opsx-ontology-query/phase-1-prechange.md

@@ -0,0 +1,276 @@
+# Phase 1 · 变更前评估（Pre-change Assessment）
+
+> **触发时机**：opsx-propose 创建变更前 / opsx-spec 生成规格前
+> **加载方式**：SDD skill 在对应阶段 `Read` 本文件
+> **前置条件**：`.local/state.json` 已完成 Session 启动（apiKey + targets 就绪）
+>
+> ⚠️ **数据边界**：当前变更尚未入库，KB 中只有历史变更数据。
+> 本阶段 KB 查询的目的：**用历史上下文辅助当前变更的决策**（身份决议、影响预评、历史 AC 查询、Spec 复用）。
+> KB 返回的是上一次入库的状态，不是当前变更的状态。
+
+---
+
+## §1 需求连续性检查（Continuity）
+
+> **已有集成**：opsx-propose §6.5 已调用。此处为完整参考。
+
+### 场景
+
+判断新需求是全新需求还是历史需求的延续，确定是否可继承历史 UUID。
+
+### API
+
+```
+POST {base}/entities/resolve
+```
+
+### 请求
+
+```json
+{
+  "externalSystem": "requirement-mgmt",
+  "externalObjectType": "requirement",
+  "externalId": "REQ-FI-2024-001",
+  "entityType": "Capability"
+}
+```
+
+> **编号文法**：`externalId` 必须符合 `REQ-{DOMAIN}-{YEAR}-{SEQ}` 格式（如 `REQ-FI-2024-001`）。
+> 查询前先归一化：trim → REQ/FEAT 段大写。完整文法见 `SKILL.md` → 编号文法速查。
+
+### 决策逻辑
+
+| 响应字段 | 值 | 含义 | SDD 动作 |
+|----------|-----|------|----------|
+| `resolution` | `LINK_EXISTING` | 命中可继承绑定 | `inheritanceAllowed=true` → 复用 entity-id，写 `delta-state=modified` |
+| `removedBindingCount` | > 0 | 存在历史失效绑定 | 仅提示，不影响 inheritance 判定 |
+| `matchType` | `HISTORICAL_ONLY` | 仅有失效绑定，`inheritanceAllowed=false` | 不可继承，新开身份 |
+| `resolution` | `CREATE_NEW` | 无匹配 | 全新需求，`delta-state=added` |
+| — | `SIMILAR_REQUIREMENT` | 名称/结构相似 | 仅候选，需人确认 |
+| — | `NEEDS_CONFIRM` | 需人确认 | ask_user A/B/C |
+
+### 按功能号圈能力（FEAT scoping）
+
+同一 `/entities/resolve` 接口，`externalObjectType:"feature"` 可查询某 FEAT 下已有能力清单，辅助 propose 阶段勾选本次 CAP 范围：
+
+```json
+{
+  "externalSystem": "requirement-mgmt",
+  "externalObjectType": "feature",
+  "externalId": "FEAT-FI-012",
+  "entityType": "Capability"
+}
+```
+
+响应 `candidates` 列出存活/失效能力，`removedBindingCount` 为已失效绑定数。
+> 此查询只作范围参考，不改变 Continuity 判定优先级。
+
+### 集成点
+
+- opsx-propose §6.5：写入 proposal frontmatter `continuity` 字段
+- 禁止扫本地 `archive/` 抄 UUID（KB 可用时）；KB degraded 时 archive 作为降级手段，标注 `source: archive(degraded)`
+
+> **Agent 行为指导**：响应中的 `clarificationQuestions` 是 AI 生成的澄清问题，Agent 应直接用 `ask_user` 呈现给用户，不要自行回答。
+> `supportEvidence` / `oppositionEvidence` 可作为决策依据向用户展示。
+
+---
+
+## §2 影响范围分析（Impact Analysis）
+
+> **新增场景**：opsx-propose 在能力分解前评估修改影响。
+
+### 场景
+
+用户要修改某个 Capability 或 STMT，需知道波及哪些下游实体（AC/DES/TASK）。
+
+### API（一跳结构）
+
+```
+GET {base}/entities/{entityId}/ontology-view
+```
+
+### API（多跳影响）
+
+```
+GET {base}/entities/{entityId}/impact
+```
+
+### 示例
+
+查询 CAP-USER-LOGIN（e89287e8）的影响：
+
+```bash
+curl -sS -H "Authorization: Bearer $API_KEY" \
+  "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/entities/e89287e8-0000-0000-0000-000000000000/impact"
+```
+
+### 响应解读
+
+- `anchorEntityId`：锚点实体 ID
+- `maxDepth`：最大影响深度（≤4 跳）
+- `nodes`：受影响实体列表（含 entityId / entityType / displayName / depth）
+- `edges`：影响路径（fromEntityId → toEntityId / relationType）
+
+### 决策逻辑
+
+| 影响范围 | 风险等级 | 建议 |
+|----------|----------|------|
+| 仅 1 跳（直接子节点） | 低 | 正常进行 |
+| 2 跳（STMT → AC/DES） | 中 | 确认受影响 AC 是否需要修改 |
+| 3-4 跳（到 TASK） | 高 | 先与用户确认影响范围再继续 |
+
+### 集成点
+
+- opsx-propose §3（能力分解）：在列出 modified Capability 前，查询影响范围写入 proposal §4 影响范围
+- opsx-propose §6.5：Continuity 结果结合影响范围，判断 iteration vs new
+
+---
+
+## §3 历史覆盖场景查询（Historical AC Coverage）
+
+> **新增场景**：opsx-spec 生成规格前，查询当前 STMT 已有哪些 AC。
+
+### 场景
+
+为已有 STMT 追加新场景时，需知道历史 AC 列表，避免遗漏或重复。
+
+### API
+
+```
+GET {base}/entities/{stmtEntityId}/ontology-view
+```
+
+### 示例
+
+查询 STMT-USER-LOGIN-001（89bbf6a6）的 AC 列表：
+
+```bash
+curl -sS -H "Authorization: Bearer $API_KEY" \
+  "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/entities/89bbf6a6-0000-0000-0000-000000000000/ontology-view"
+```
+
+### 响应解读
+
+从 `relations` 数组提取 `relationType=verifiedBy && direction=outbound` 的邻居：
+
+```json
+{
+  "relationType": "verifiedBy",
+  "direction": "outbound",
+  "neighbor": {
+    "entityId": "c9f6a0e8-0000-0000-0000-000000000000",
+    "canonicalKey": "AC-USER-LOGIN-001",
+    "displayName": "正确凭证登录成功",
+    "changeId": "CHG-ADD-USER-LOGIN"
+  }
+}
+```
+
+### 决策逻辑
+
+> ⚠️ **数据边界**：KB 中只有已入库的历史变更数据。当前变更的 AC 尚未入库，不会出现在查询结果中。以下决策基于"KB 返回的全部是历史 AC"这一前提。
+
+| 发现 | 含义 | SDD 动作 |
+|------|------|----------|
+| AC 来自旧变更（changeId ≠ 当前） | 历史保留场景 | 新场景编号从 `max+1` 开始，不重复；SCN 格式 `:SCN-{slug}-{NNN}`（见 `SKILL.md` → 编号文法速查） |
+| 无 AC | 全新 STMT 或历史无场景 | 正常创建首个 AC |
+| AC 的 statement_id 指向当前 STMT | 关系正确 | 确认新 AC 也写 statement_id |
+| STMT 在 KB 中不存在 | 全新 STMT（added） | 无历史 AC 可查，直接创建 |
+
+### 关键机制
+
+- `verifiedBy` 是 inferred 关系（rule_id=nested-acceptance-scenario），由 AC 的 `statement_id` 属性推导
+- 历史 AC 未被修改时，其 v1 仍是 current，关系自动保留
+- ontology-view 只显示每个实体的 current version
+
+### 集成点
+
+- opsx-spec §3：在 match-requirement 之后，对 modified STMT 查询历史 AC
+- opsx-spec §6：生成新 AC 时确认编号不与历史冲突
+
+---
+
+## §4 Spec 复用评估（Spec Reuse）
+
+> **已有集成**：opsx-spec §3 已调用。此处为完整参考。
+
+### 场景
+
+查找是否有可复用的历史规格（statements / ACs / constraints / designElements / tasks）。
+
+### API
+
+```
+POST {base}/context/match-requirement
+```
+
+### 请求
+
+```json
+{
+  "query": "用户登录认证",
+  "targetStage": "spec",
+  "entityId": "e89287e8-0000-0000-0000-000000000000",
+  "externalSystem": "requirement-mgmt",
+  "externalObjectType": "requirement",
+  "externalId": "REQ-FI-2024-001"
+}
+```
+
+### 决策逻辑
+
+| `reuseMode` | 含义 | SDD 动作 |
+|-------------|------|----------|
+| `INHERIT` | 确定性命中，可继承 UUID | unchanged 写继承引用；modified 复用 entity-id + predecessor |
+| `REFERENCE` | 仅候选，不能自动复用 | 只参考内容，新开身份 |
+| — | 无命中 | 全新建 |
+
+### 响应消费
+
+- `reuseBundles[].statements` → 优先消费，写入 spec 的 STMT
+- `reuseBundles[].acceptanceCriteria` → 参考场景定义
+- `reuseBundles[].designElements` → 仅理解上下文，不能写成 Spec 的 How
+- 实体上的 `externalRefs` → 写入场景 `external-ref`
+
+### 集成点
+
+- opsx-spec §3：Continuity=iteration 时必须带 `entityId` + external
+- 禁止从本地 `archive/` 抄 UUID 当跨迭代继承源（KB 可用时）；KB degraded 时 archive 作为降级手段，标注 `source: archive(degraded)`
+
+> **Agent 行为指导**：消费 `specGenerationContext` 判断复用率——`reusableStatements` > 50% 走迭代修改，< 20% 走全新建。
+> `warnings` 和 `clarificationQuestions` 应呈现给用户，不要忽略。
+
+---
+
+## §5 约束冲突检测（Constraint Conflict）
+
+> **新增场景**：opsx-spec 新增 Constraint 时检查冲突。
+
+### 场景
+
+新增约束时，检查 KB 中是否已有语义矛盾的约束。
+
+### API
+
+```
+POST {base}/context/search
+```
+
+### 请求
+
+```json
+{
+  "query": "密码最小长度限制",
+  "entityTypes": ["Constraint"],
+  "limit": 10
+}
+```
+
+### 决策逻辑
+
+- 返回结果中若存在与新增约束语义矛盾的 Constraint → 标记 warning，提示用户确认
+- 无冲突或无命中 → 正常创建
+
+### 集成点
+
+- opsx-spec §6：创建 CON-* 前可选调用