kld-sdd 2.6.2 → 2.6.4

package/skywalk-sdd/ontology/traceability-validator.cjs

@@ -340,6 +340,161 @@ function validateInheritedReferences(facts, diagnostics, identityHistory) {
   }
 }
 
+function validateContinuityAndExternalRefs(facts, diagnostics, options = {}) {
+  const allowed = {
+    requirement: new Set(['Capability']),
+    scenario: new Set(['SpecificationStatement', 'AcceptanceCriterion']),
+    feature: new Set(['Capability']),
+  };
+  const continuity = facts.continuity || {};
+  const kind = String(continuity.kind || '').toLowerCase();
+  const resolutionPath = options.continuityResolutionPath
+    || (facts.change
+      ? require('path').join(
+        options.projectRoot || process.cwd(),
+        'openspec',
+        'changes',
+        facts.change,
+        'continuity-resolution.json',
+      )
+      : '');
+  let resolution = null;
+  if (resolutionPath) {
+    try {
+      const fs = require('fs');
+      if (fs.existsSync(resolutionPath)) {
+        resolution = JSON.parse(fs.readFileSync(resolutionPath, 'utf8'));
+      }
+    } catch {
+      resolution = null;
+    }
+  }
+
+  if (kind === 'iteration') {
+    const caps = (facts.entities || []).filter((entity) => entity.type === 'Capability');
+    for (const capability of caps) {
+      if (!capability.entity_id || !capability.version_id) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.CONTINUITY_IDENTITY_MISMATCH,
+          'error',
+          `Continuity=iteration 时 Capability 缺少 KB 回传身份: ${capability.id}`,
+          {
+            ...sourceContext(capability),
+            entity_id: capability.id,
+            suggestion: '在 propose 用 entities/resolve 回填 entity-id / version-id',
+          },
+        ));
+      }
+    }
+    if (!resolution || resolution.status === 'pending') {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.CONTINUITY_DECISION_REQUIRED,
+        'error',
+        'Continuity=iteration 但 continuity-resolution.json 缺失或仍为 pending',
+        {
+          file: resolutionPath || 'continuity-resolution.json',
+          suggestion: '在 propose/spec 完成 A/B/C 决议后再 check',
+        },
+      ));
+    }
+  }
+
+  if (resolution && resolution.status && resolution.status !== 'pending') {
+    const decisions = [
+      ...(Array.isArray(resolution.capabilities) ? resolution.capabilities : []),
+      ...(Array.isArray(resolution.scenarios) ? resolution.scenarios : []),
+    ];
+    const entitiesByAnchor = new Map(
+      (facts.entities || []).map((entity) => [String(entity.anchor_id || entity.id || '').toUpperCase(), entity]),
+    );
+    for (const decision of decisions) {
+      const anchor = String(decision.anchor || '').toUpperCase();
+      if (!anchor) continue;
+      const entity = entitiesByAnchor.get(anchor);
+      if (!entity) continue;
+      const decisionCode = String(decision.decision || '').toLowerCase();
+      const decidedEntityId = String(decision.entityId || decision.entity_id || '').toLowerCase();
+      const actualEntityId = String(entity.entity_id || '').toLowerCase();
+      if (
+        (decisionCode === 'reuse-existing-identity' || decisionCode === 'reuse_existing' || decisionCode === 'a')
+        && decidedEntityId
+        && actualEntityId
+        && decidedEntityId !== actualEntityId
+      ) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.CONTINUITY_IDENTITY_MISMATCH,
+          'error',
+          `决议复用历史身份但产物仍使用新 entity_id: ${anchor}`,
+          {
+            ...sourceContext(entity),
+            entity_id: entity.id,
+            suggestion: '按 continuity-resolution 回填历史 entity-id / version-id',
+          },
+        ));
+      }
+      if (
+        (decisionCode === 'assign-new-anchor' || decisionCode === 'assign_new' || decisionCode === 'b')
+        && decidedEntityId
+        && actualEntityId
+        && decidedEntityId === actualEntityId
+        && String(decision.notes || '').toLowerCase().includes('new-anchor-required')
+      ) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.CONTINUITY_IDENTITY_MISMATCH,
+          'error',
+          `决议为新对象但仍共用旧锚点/身份: ${anchor}`,
+          {
+            ...sourceContext(entity),
+            entity_id: entity.id,
+            suggestion: '更换新锚点并分配新 entity_id 后重跑 check',
+          },
+        ));
+      }
+    }
+  }
+
+  const bindingKeys = new Map();
+  for (const entity of facts.entities || []) {
+    for (const ref of entity.external_refs || []) {
+      const objectType = String(ref.object_type || '').toLowerCase();
+      const allowedTypes = allowed[objectType];
+      if (!allowedTypes) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.EXTERNAL_REF_INVALID,
+          'error',
+          `未知 external object_type: ${objectType} (${entity.id})`,
+          { ...sourceContext(entity), entity_id: entity.id },
+        ));
+        continue;
+      }
+      if (!allowedTypes.has(entity.type)) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.EXTERNAL_REF_TYPE_MISMATCH,
+          'error',
+          `external object_type=${objectType} 与实体类型 ${entity.type} 不匹配: ${entity.id}`,
+          { ...sourceContext(entity), entity_id: entity.id },
+        ));
+      }
+      const key = `${ref.system}|${objectType}|${ref.external_id}|${entity.anchor_id || entity.id}`;
+      const prior = bindingKeys.get(key);
+      if (prior && prior !== entity.entity_id) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.EXTERNAL_REF_CONFLICT,
+          'error',
+          `同外部键+同锚点绑定了不同 entity_id: ${entity.id}`,
+          {
+            ...sourceContext(entity),
+            entity_id: entity.id,
+            suggestion: '复用历史身份或更换新锚点后重开 entity_id',
+          },
+        ));
+      } else if (entity.entity_id) {
+        bindingKeys.set(key, entity.entity_id);
+      }
+    }
+  }
+}
+
 function validateTraceability(facts, options = {}) {
   const profile = normalizeProfile(options.profile || 'auto', facts.profile || 'simple');
   const graphEntities = options.effectiveGraph && options.effectiveGraph.effective_entities
@@ -356,6 +511,7 @@ function validateTraceability(facts, options = {}) {
   const entitiesById = new Map();
 
   validateArtifactPresence(facts, profile, diagnostics);
+  validateContinuityAndExternalRefs(facts, diagnostics, options);
 
   if (profile === 'strict') {
     for (const artifact of facts.artifacts || []) {

package/templates/openspec/continuity-resolution.example.json

@@ -0,0 +1,32 @@
+{
+  "status": "resolved",
+  "updatedAt": "2026-07-23T00:00:00.000Z",
+  "capabilities": [
+    {
+      "anchor": "CAP-ORDER-CANCEL",
+      "externalKey": {
+        "system": "requirement-mgmt",
+        "objectType": "requirement",
+        "externalId": "REQ-FI-2024-001"
+      },
+      "decision": "reuse-existing-identity",
+      "entityId": "00000000-0000-4000-8000-000000000001",
+      "currentVersionId": "00000000-0000-4000-8000-000000000011",
+      "notes": "propose 阶段 A/B/C：复用历史能力"
+    }
+  ],
+  "scenarios": [
+    {
+      "anchor": "AC-ORDER-CANCEL-001",
+      "externalKey": {
+        "system": "requirement-mgmt",
+        "objectType": "scenario",
+        "externalId": "REQ-FI-2024-001:SCN-req-date-empty-002"
+      },
+      "decision": "reuse-existing-identity",
+      "entityId": "00000000-0000-4000-8000-000000000021",
+      "currentVersionId": "00000000-0000-4000-8000-000000000031",
+      "notes": "spec 阶段场景冲突决议"
+    }
+  ]
+}

package/templates/openspec/proposal.md

@@ -7,6 +7,24 @@ delta-state: "added"
 predecessor-version: "" # added 留空；modified/removed 指向直接前序版本
 mode: "" # full=分 Capability 产物，simple=根目录精简产物
 test-strategy: "" # tdd=测试先行, impl-first=实现优先, none=无测试
+# 外部需求键（首轮冷启动也建议写入，便于 ingest 种桥）
+requirement-refs:
+  - system: requirement-mgmt
+    object-type: requirement
+    external-id: REQ-<DOMAIN>-<NNN>
+# Continuity：字段一律来自知识库 resolve，禁止本地 archive 文件夹名
+continuity:
+  kind: new # iteration | similar-reference | new
+  kb-space-id: "" # KB space UUID（iteration 时必填）
+  kb-id: "" # KB UUID（iteration 时必填）
+  base-change-id: "" # 可选，来自 KB source/change_id
+  base-archive-id: "" # 可选溯源（KB archive_id），不是本地目录名
+  base-capabilities: []
+  # iteration 示例：
+  # base-capabilities:
+  #   - anchor: CAP-<CAPABILITY>
+  #     entity-id: <uuid>
+  #     current-version-id: <uuid>
 ---
 
 # proposal.md - 业务意图与上下文总览

package/templates/openspec/spec.md

@@ -34,6 +34,7 @@ capability-id: "CAP-<CAPABILITY>" # 必须与 proposal.md 中的 Capability ID
 - **version-id**: <UUID>
 - **delta-state**: added
 - **predecessor-version**: 无
+- **external-ref**: requirement-mgmt:scenario:REQ-<DOMAIN>-<NNN>:SCN-<slug>
 - **当** <!-- 触发条件 -->
 - **预期** <!-- 预期结果 -->
 
@@ -42,6 +43,7 @@ capability-id: "CAP-<CAPABILITY>" # 必须与 proposal.md 中的 Capability ID
 - **version-id**: <UUID>
 - **delta-state**: added
 - **predecessor-version**: 无
+- **external-ref**: requirement-mgmt:scenario:REQ-<DOMAIN>-<NNN>:SCN-<slug>
 - **当** <!-- 触发条件 -->
 - **预期** <!-- 预期结果 -->
 
@@ -61,6 +63,7 @@ capability-id: "CAP-<CAPABILITY>" # 必须与 proposal.md 中的 Capability ID
 - **version-id**: <新 UUID>
 - **delta-state**: <modified|added>
 - **predecessor-version**: <modified 时填写；added 为无>
+- **external-ref**: requirement-mgmt:scenario:REQ-<DOMAIN>-<NNN>:SCN-<slug>
 - **当** <!-- 触发条件 -->
 - **预期** <!-- 预期结果 -->
 

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

@@ -204,7 +204,8 @@ g. **继续下一个层级** — 重新检查 DAG，找出依赖已满足的下
 3. **GREEN**：读取 RED 失败原因 → 执行 GREEN Scope 声明 → 逐条确认 YAGNI 围栏 → 写最少代码让测试通过 → 禁止捆绑未测试代码
 4. **GREEN Scope 门禁**：Verify GREEN 之后，检查生产代码无越界逻辑分支（属于后续 RED 的行为 → 删除）
 5. **REFACTOR**：在测试全绿状态下重构 → 运行全部测试确认仍绿
-6. 再进入下一个任务
+6. **可选：TDD 审查子代理**：GREEN 任务完成后，可派发独立审查子代理执行 `opsx-tdd-review/SKILL.md` §7（子代理审查提示模板），检测"测试通过但没测到关键点"。implementer 自审查 ≠ 独立审查。
+7. 再进入下一个任务
 
 > 完整执行步骤见 opsx-tdd-core/reference.md §1-§3
 > 合理化预防表见 opsx-tdd-core/SKILL.md §7

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

@@ -42,7 +42,7 @@ description: opsx-apply 的阶段强制检查点与自检清单。仅在执行 a
 
 ### §5e.1 TDD 执行合规自检（仅 test-strategy=tdd 时）
 
-⛔ 每完成一个 RED/GREEN/REFACTOR 任务后，必须执行 `opsx-tdd-core/checklist.md` §A（7 项）逐项勾选。
+⛔ 每完成一个 RED/GREEN/REFACTOR 任务后，必须执行 `opsx-tdd-core/checklist.md` §A（11 项）逐项勾选。
 
 > 不在此内联复制，以 opsx-tdd-core/checklist.md §A 为唯一真相源。
 > 额外补充：REFACTOR 任务还需执行 `opsx-tdd-rules/rules/refactor-checklist.md`（7 项重构检查点）。
@@ -55,7 +55,7 @@ description: opsx-apply 的阶段强制检查点与自检清单。仅在执行 a
 - [ ] RED 测试 Given 是真实输入
 
 ⛔ 测试命名与结构（引用 opsx-tdd-quality/SKILL.md §3-§4）：
-- [ ] 测试方法名符合 `{method}_{given}_{expected}` 格式
+- [ ] 测试方法名符合 `{method}_{state}_{outcome}` 格式
 - [ ] 测试包含 `// Given` / `// When` / `// Then` 注释结构
 - [ ] 一测一场景（测试方法名不含 "and"）
 

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

@@ -108,13 +108,17 @@ node skywalk-sdd/log.cjs archive-docs --project=. --change=<变更名称> --reas
 该命令成功后必须已经完成：
 - 活动目录 `openspec/changes/<name>/` 被移入 `openspec/changes/archive/<日期>-<name>/`。
 - 归档目录写入 `archive-ontology.json`、`canonical-facts.json`、`conversion-report.json` 和新版 `archive-manifest.json`。
-- 生成知识库可直接消费的 `openspec/changes/archive/<日期>-<name>.zip`，包内文件必须由 manifest 完整列举并通过 SHA-256 校验。
+- 生成知识库可直接消费的 `openspec/changes/archive/<日期>-<name>.zip`（canonical-facts **v2**，含 `external_refs`），包内文件必须由 manifest 完整列举并通过 SHA-256 校验。
 - Full Spec 的 `specs/<capability>/spec.md` 同步到 `openspec/specs/<capability>/spec.md`。
 - archive 阶段写入 `stage_end`。
 - 未勾选 tasks 被写入 `archive_result.task_completion`。
 - 最终中文报告生成到 `openspec/changes/archive/<日期>-<name>/reports/<name>-report.md` 及同名 `<name>-report.html`（默认同时生成 .md 与 .html 双产物，默认归档后 archive 目录，可用 --report-output 自定义）。
 - 执行日志 `openspec/changes/archive/<日期>-<name>/logs/execution-log.md` 随归档整目录迁移（人读审计层）。
 
+### 5.5 收尾入库（opsx-kb-ingest）
+
+归档 zip 生成后，提示用户用知识库技能 **`opsx-kb-ingest`** 上传；成功则写 `ingest-receipt.json`。若返回 `EXTERNAL_REF_CONFLICT`，引导回 spec/check 修正后重入，**禁止**在 KB 内现场改绑。
+
 > 注意：`archive-docs` 成功执行后已经在内部写入 `stage_end`，因此**不要在成功的归档后再单独运行 `node skywalk-sdd/log.cjs end --command=archive ...`**。仅在第 5 步归档命令失败时，才需要运行下方的失败分支 `end`。
 
 如果该命令失败，以失败状态结束 telemetry：

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

@@ -113,11 +113,15 @@ openspec list
 
 #### 4.4a TDD 合规性检查（仅 test-strategy=tdd 时执行）
 
-⛔ 执行 `opsx-tdd-core/checklist.md` §B（10 项）逐项检查。
+⛔ 执行 `opsx-tdd-core/checklist.md` §B（11 项）逐项检查。
 
 > 不在此内联复制，以 opsx-tdd-core/checklist.md §B 为唯一真相源。
 > 额外补充：还需检查 `opsx-tdd-rules/rules/exception-path-coverage.md`（异常路径覆盖门禁）。
 
+**检查项适用阶段**：§B 中部分检查项在 apply 前后均可验证（文档级），部分仅在 apply 后可验证（代码级）：
+- **apply 前可验证**（文档级）：RED 验收标准包含"测试运行失败"、无"断言为空"、GREEN 为行为级粒度、DAG 存在 RED→GREEN 循环对、非 TDD 模块未拆红绿、GREEN 验收标准为"让对应 RED 通过"、已声明 Controller 策略、Controller 两种策略都生成测试任务、每个 RED 含测试方法名、每个 GREEN 含 YAGNI 围栏、每个 REFACTOR 列出重构点
+- **apply 后可验证**（代码级）：GREEN 任务输出不含未测试的 Controller/Filter/Config
+
 ⛔ BEFORE 完成 TDD 合规性检查，如需深度审查测试质量，必须读取：
 - opsx-tdd-review/SKILL.md（测试质量审查清单 8 项 + 缺失测试检测）
 读取后确认："已读取测试质量审查清单"。
@@ -212,6 +216,16 @@ node skywalk-sdd/log.cjs record --type=conformance_review --command=check --proj
 
 ---
 
+## Continuity / external_ref 确定性门禁
+
+`opsx-check` **不联网提问**。Agent 应在 propose/spec 已问完；本阶段只验证并入既有 apply 前门禁：
+
+- Continuity=`iteration` 时每个 CAP 具备 KB 回传 `entity-id` / `version-id`
+- 已写 spec 的 Capability：场景 `external-ref` 与 `continuity-resolution.json` 决议一致；同 key+同锚点未偷偷换 entity_id
+- 用户选「原对象」却仍用新 id、或选「新对象」却仍共用旧锚点 → 失败（`CONTINUITY_IDENTITY_MISMATCH` / `EXTERNAL_REF_CONFLICT`）
+- 决议缺失 / pending / 与产物不一致 → `CONTINUITY_DECISION_REQUIRED`
+- CI/非交互：失败即非零退出并打印修复说明，不挂起等待输入
+
 ## 本体语义关系门禁
 
 在其他质量检查前必须运行：

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

@@ -38,11 +38,15 @@ description: "opsx-check 阶段日志自检清单 — 仅在 check 自检时读
 
 ## E. TDD 合规性检查（仅 test-strategy=tdd 时）
 
-⛔ 执行 `opsx-tdd-core/checklist.md` §B（10 项）逐项检查。
+⛔ 执行 `opsx-tdd-core/checklist.md` §B（11 项）逐项检查。
 
 > 不在此内联复制，以 opsx-tdd-core/checklist.md §B 为唯一真相源。
 > 额外补充：还需检查 `opsx-tdd-rules/rules/exception-path-coverage.md`（异常路径覆盖门禁）。
 
+**检查项适用阶段**：
+- **apply 前可验证**（文档级）：§B 中除"GREEN 任务输出不含未测试的 Controller/Filter/Config"外的所有检查项（含 Controller 策略声明和测试任务生成）
+- **apply 后可验证**（代码级）："GREEN 任务输出不含未测试的 Controller/Filter/Config"
+
 ## F. 语义门禁与工作态
 
 - [ ] `openspec/changes/<变更名称>/artifact-index.json` 已覆盖当前全部 proposal/spec/design/tasks，且每份 `artifacts/*.ontology.json` 与 `working-ontology.json` revision 一致

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

@@ -159,6 +159,27 @@ openspec instructions proposal --change "<name>" --json
 
 > 完整性检查（问题描述/目标/模块/约束 4 项）与缺失补充机制见 `./checklist.md`「§6 需求完整性检查」。发现缺失时主动询问用户补充。
 
+### 6.5 【Continuity】需求 / Capability 身份（只到 CAP，不做场景）
+
+在创建变更目录之后、写 proposal 能力列表之前（或紧接 CAP 编号分配前）：
+
+1. 提取 / 询问外部需求号 `REQ-*`（没有则问一次）。
+2. 调用知识库 **`opsx-ontology-query`**（或薄封装）：
+```bash
+node skywalk-sdd/context-client.cjs --mode=resolve \
+  --external-system=requirement-mgmt \
+  --external-object-type=requirement \
+  --external-id="<REQ-...>" \
+  --entity-type=Capability \
+  --space-id="$ENGINEERING_KB_SPACE_ID" \
+  --kb-id="$ENGINEERING_KB_KB_ID"
+```
+3. 按 KB 结果确认 Continuity：`iteration` / `similar-reference` / `new`；勾选本次涉及的 CAP。
+4. 写入 proposal frontmatter：`requirement-refs` + `continuity`（字段来自 KB：`kb-space-id` / `kb-id` / `base-capabilities[].entity-id` / `current-version-id`）。**禁止**写本地 archive 文件夹名作为 `base-archive`。
+5. CAP 级「同 key + 同锚点、不同 entity_id」当场问 A/B/C；决议写入 `openspec/changes/<name>/continuity-resolution.json` 的 `capabilities[]`。
+6. KB 不可用 → `degraded` 继续，**禁止**扫本地 `archive/` 抄 UUID。预期：恢复后同锚点入库可能触发 `EXTERNAL_REF_CONFLICT`。
+7. **不得**在本阶段生成 STMT/AC/场景或裁决场景身份。
+
 ### 7. 【交互引导】文档拆分模式选择
 
 **❗ 必须主动询问用户，不得默认选择**。Full / Simple / Auto 三种模式的目录结构、适用场景与 AskUserQuestion 文案见 `./reference.md`「§7 文档拆分模式选择」。根据用户选择设置 `mode: full | simple`（Auto 按能力域数量判断），记录到 proposal.md 的 YAML frontmatter。

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

@@ -107,21 +107,31 @@ openspec list
 
 > 上下文类型（需求文档 / 代码文件 / API 文档）与用途见 `./reference.md`「§3 上下文类型与用途」。
 
-**【默认尝试】工程 Spec 知识库上下文**：
+**【默认尝试】工程 Spec 知识库上下文（场景身份主战场）**：
 
-从用户输入、proposal.md 中当前 Capability 的名称、业务目标、边界和约束组成一段自然语言查询。不要要求用户提供 `entity_id`。执行：
+读取 proposal Continuity。对**当前 Capability** 各调一次（「全部」= 循环 N 次，不是一次大查询）：
 
 ```bash
-node skywalk-sdd/context-client.cjs --query="<当前 Capability 的自然语言需求>" --target-stage=spec
+node skywalk-sdd/context-client.cjs \
+  --query="<当前 Capability 的自然语言需求>" \
+  --target-stage=spec \
+  --entity-id="<该 CAP 的 entity_id>" \
+  --external-system=requirement-mgmt \
+  --external-object-type=requirement \
+  --external-id="<REQ-...>" \
+  --space-id="$ENGINEERING_KB_SPACE_ID" \
+  --kb-id="$ENGINEERING_KB_KB_ID"
 ```
 
-- 配置项：`ENGINEERING_KB_API`、`ENGINEERING_KB_SPACE_ID`、可选 `ENGINEERING_KB_TOKEN`。
-- 若返回 `available=false` 或 `degraded=true`，记录降级原因并继续 Spec 流程，不得阻塞。
-- 优先消费 `reuseBundles[].statements` 中的历史 STMT、AC、Constraint；`designElements` 只能作为理解上下文，不能写成 Spec 的 How。
-- `answeredQuestions` 表示历史事实已经覆盖的内容，不要对用户重复提问。
-- 只向用户询问 `clarificationQuestions` 中仍与当前 Capability 有关的问题。
-- `reuseMode=REFERENCE` 只能参考复用，不得复制历史 UUID；只有 `reuseMode=INHERIT` 才允许按本体语义生成契约复用历史身份。
-- 所有知识库内容均为 advisory；若与用户输入、proposal.md 或用户确认冲突，以当前用户确认和 proposal.md 为准。
+- 配置项：`ENGINEERING_KB_API`、`ENGINEERING_KB_SPACE_ID`、`ENGINEERING_KB_KB_ID`、可选 `ENGINEERING_KB_TOKEN`。查询权威技能是知识库 **`opsx-ontology-query`**；本脚本只是薄封装。
+- Continuity=`iteration` 时**必须**带 `--entity-id` + external。
+- **禁止**从本地 `archive/` 抄 UUID 当跨迭代继承源；跨迭代只认 KB current。
+- 若返回 `available=false` / `degraded=true`，记录降级并继续，不得扫本地 archive 兜底。
+- `INHERIT`：unchanged 写继承引用；modified 复用 entity-id + predecessor。`REFERENCE`：只参考，新开身份。
+- reuseBundle / 实体上的 `externalRefs` 写入场景 `external-ref`（`requirement-mgmt:scenario:REQ-…:SCN-…`）。
+- 场景级「同 SCN key + 同锚点、不同 entity_id」在写完该 CAP identity 后、确认文档前**当场问** A/B/C；未决不得进入下一 CAP / design。决议追加到 `continuity-resolution.json` 的 `scenarios[]`。
+- 优先消费 `reuseBundles[].statements`；`designElements` 只作理解上下文，不能写成 Spec 的 How。
+- 所有知识库内容均为 advisory；与用户确认 / proposal 冲突时以当前确认与 proposal 为准。
 
 **【可选】业务知识库检索**：
 术语含义不清且可能影响 spec 准确性时，可调用 **opsx-knowledge** skill。
@@ -203,7 +213,7 @@ node skywalk-sdd/context-client.cjs --query="<当前 Capability 的自然语言
 - 新需求、场景和约束分别使用 `STMT-*`、`AC-*`、`CON-*`；分配规则是同前缀同 Capability 当前最大序号 + 1。
 - 修改已有实体必须复用原 ID；删除实体只写 removal 语义，不得把编号分配给新实体。
 - `added` 必须调用 `semantic-identity --delta-state=added` 生成新的实体 UUID 和版本 UUID；禁止通过复制另一需求的 UUID 创建新实体。
-- `modified/removed` 必须从 Archive 读取历史 `entity-id` 和直接前序 `version-id`，调用 `semantic-identity --delta-state=<modified|removed> --entity-id=<UUID> --predecessor-version=<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 目录当跨迭代继承权威。
 - AC 必须嵌套在所属 STMT 下；CON 必须通过 `**constrains**` 显式引用 STMT。
 - 对 `reuseMode=REFERENCE` 的历史候选必须创建新的实体身份；禁止因为内容相似而复用历史 `entity-id`。
 - 对 `reuseMode=INHERIT` 的历史事实，必须使用返回的实体与版本来源完成 unchanged/modified 身份参数校验。

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

@@ -34,6 +34,7 @@ description: opsx-spec 的阶段强制检查点与自检清单。仅在执行 sp
 - [ ] 已消费工程知识库 `answeredQuestions`，没有重复询问历史事实已经回答的问题
 - [ ] 仅将 `reuseMode=INHERIT` 的事实作为身份继承；`REFERENCE` 候选使用新实体身份
 - [ ] 已处理与当前 Capability 有关的 `clarificationQuestions`
+- [ ] ⛔ **多校验拆分（TDD 模式）**：当 test-strategy=tdd 时，单个 STMT 包含多个"必须校验"条件时，每个校验条件有对应的独立 AC 场景（规则见 `opsx-tdd-rules/rules/multi-validation-split.md`）
 
 **如有任意一项未满足，重新生成对应章节，直至全部通过。** 自检完成后必须输出结构化自检报告（模板见 `./reference.md`「§7 质量自检报告模板」），未通过项自动修复后重新输出。
 

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

@@ -153,6 +153,7 @@ Simple 模式或单文件能力域下，**不要拆成多个同文件任务**。
 > - RED 任务验收标准：测试运行失败，且失败原因正确（功能未实现）
 > - GREEN 任务验收标准：写最少代码让对应 RED 测试通过
 > - 非 TDD 模块（前端 UI、配置、SQL DDL）不拆红绿，按常规任务处理
+> - Controller 层必须选择策略 A（红绿循环）或策略 B（impl-first 接线测试），两种策略都生成测试
 >
 > 是否继续使用 TDD 策略？"
 
@@ -172,7 +173,7 @@ Simple 模式或单文件能力域下，**不要拆成多个同文件任务**。
 3. GREEN 验收标准必须包含"写最少代码让对应 RED 测试通过"，禁止捆绑
 4. GREEN 不得包含未测试的 Controller/Filter/Config
 5. 非 TDD 模块（前端 UI/配置/SQL DDL）不拆红绿
-6. Controller 层策略必须在 tasks.md §2.0 中声明（策略 A 或 B）
+6. Controller 层策略必须在 tasks.md §2.0 中声明（策略 A 或 B），两种策略都必须生成测试任务
 7. ⛔ **GREEN 任务 YAGNI 围栏**：每个 GREEN-N 任务描述末尾必须包含"不提前实现 [后续 RED 行为]"围栏声明。规则详见 `opsx-tdd-rules/rules/green-yagni-fence.md`
 
 ⛔ BEFORE 生成 TDD 任务，必须读取：

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

@@ -36,7 +36,7 @@ description: opsx-task 的阶段强制检查点与自检清单。仅在执行 ta
 
 ## §8.1 TDD 合规性自检（仅 test-strategy=tdd 时）
 
-⛔ 执行 `opsx-tdd-core/checklist.md` §B（10 项）逐项检查。
+⛔ 执行 `opsx-tdd-core/checklist.md` §B（11 项）逐项检查。
 
 > 不在此内联复制，以 opsx-tdd-core/checklist.md §B 为唯一真相源。
 > 额外补充：还需检查 `opsx-tdd-rules/rules/exception-path-coverage.md`（异常路径覆盖门禁）——每个 orElseThrow/边界检查须有对应 RED 任务。

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

@@ -62,7 +62,7 @@ spec.md user-auth 定义了 7 个场景，拆为 7 对 RED+GREEN + 1 个 REFACTO
 
 ### Controller 层处理示例
 
-**策略 A：Controller 也拆 RED→GREEN（推荐，适合接口数量少时）**
+**策略 A：Controller 也拆 RED→GREEN（适合 Controller 含业务逻辑时）**
 
 | 任务 ID | 行为点 | 类型 | 依赖 | 验收标准 |
 |---------|--------|------|------|---------|
@@ -73,13 +73,14 @@ spec.md user-auth 定义了 7 个场景，拆为 7 对 RED+GREEN + 1 个 REFACTO
 | TASK-05-RED-10 | POST /auth/logout 返回成功 | 测试-RED | TASK-05-GREEN-6 | 测试失败 |
 | TASK-05-GREEN-10 | AuthController.logout() 实现 | 实现-GREEN | TASK-05-RED-10 | 只实现 logout 接口 |
 
-**策略 B：Controller 作为非 TDD 任务（适合接口数量多时）**
+**策略 B：Controller 先接线，再写 @WebMvcTest 验证（适合 Controller 为纯接线时）**
 
 | 任务 ID | 行为点 | 类型 | 依赖 | 验收标准 |
 |---------|--------|------|------|---------|
-| TASK-05-CTRL | AuthController 3 个接口接线 | 接口层 | TASK-05-GREEN-6 | Controller 编译通过，调用对应 Service 方法，返回 Result 统一响应体 |
+| TASK-05-CTRL-IMPL | AuthController 3 个接口接线 | 接口层 | TASK-05-GREEN-6 | Controller 编译通过，调用对应 Service 方法，返回 Result 统一响应体 |
+| TASK-05-CTRL-TEST | AuthController HTTP 契约验证 | 接口测试 | TASK-05-CTRL-IMPL | @WebMvcTest 通过：URL 映射正确、请求体绑定正确、响应 JSON 结构正确、错误响应正确 |
 
-注意：策略 B 中 Controller 任务不是 GREEN，不对应任何 RED 测试，仅做编译检查。
+注意：策略 B 中 Controller 任务不是 GREEN，不对应 RED 测试。但**必须生成 CTRL-TEST 任务**，使用 @WebMvcTest 验证 HTTP 契约（URL 映射、请求绑定、响应结构、错误处理）。策略 B 本质是对 Controller 层单独应用 impl-first 模式。
 
 ---
 
@@ -92,7 +93,8 @@ spec.md user-auth 定义了 7 个场景，拆为 7 对 RED+GREEN + 1 个 REFACTO
 - 项目脚手架/配置（pom.xml, application.yml）→ 配置任务
 - 数据库迁移脚本（SQL DDL）→ 数据层任务
 - 前端路由/状态管理/API 封装 → UI层任务
-- Controller 层（可选）→ 接口层任务（当选择策略 B 时，Controller 作为接线层不拆红绿）
+
+> Controller 层不属于非 TDD 模块，必须通过策略 A（TDD 红绿循环）或策略 B（impl-first 接线测试）生成测试。
 
 ⚠️ Controller 层处理策略需在 tasks.md §2.0 中明确声明，不能默认选择。
 

package/templates/skills/kld-sdd/opsx-tdd-anti-patterns/SKILL.md

@@ -58,6 +58,11 @@ BEFORE 编写测试代码：
   1. "我在测试真实组件行为还是仅测试 mock 存在？" → 如果仅测试 mock 存在，停止
   2. "我的 Given 是真实数据还是 mock 出的预定结论？" → 如果是预定结论，重写
   3. "我是否完全理解被 mock 依赖的副作用？" → 如果不理解，先理解再 mock
+
+AFTER GREEN（GREEN 完成后、标记通过前）：
+  4. "测试是否有真实断言（assertEquals/assertThrows），而非仅 assertNotNull？" → 如果只有弱断言，补充具体值断言
+  5. "单个测试 mock 了几个依赖？" → 如果 >5 个，拆分测试或减少依赖
+  6. "正常路径有测试，异常路径呢？" → 每个 orElseThrow/边界检查须有对应测试
 ```
 
 ## §6 红旗列表

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

@@ -37,6 +37,38 @@ RED → Verify RED → 🔴中断声明 → GREEN → Verify GREEN → GREEN Sco
 - **RED**：写一个最小的失败测试，展示期望行为
   - 一个行为、清晰名称、真实代码（除非不可避免否则不用 mock）
   - ⛔ **只写当前 RED 对应的测试方法**，不提前写后续 RED 的测试
+
+  <Good>
+  ```java
+  // ✅ 一个行为、清晰名称、真实断言
+  @Test
+  void login_validCredentials_returnsToken() {
+      // Given
+      UserMapper mapper = mock(UserMapper.class);
+      when(mapper.findByUsername("admin")).thenReturn(testUser);
+      AuthService service = new AuthService(mapper);
+
+      // When
+      Token result = service.login("admin", "password123");
+
+      // Then
+      assertNotNull(result);
+      assertNotNull(result.getAccessToken());
+  }
+  ```
+  </Good>
+
+  <Bad>
+  ```java
+  // ❌ 模糊名称、测试 mock 而非真实行为
+  @Test
+  void testLogin() {
+      when(mapper.findByUsername(any())).thenReturn(testUser);
+      service.login("admin", "password123");
+      verify(mapper).findByUsername("admin"); // 只验证 mock 被调用
+  }
+  ```
+  </Bad>
 - **Verify RED**（强制执行，绝不跳过）：
   - 确认测试失败（不是报错）
   - 失败信息符合预期
@@ -55,6 +87,32 @@ RED → Verify RED → 🔴中断声明 → GREEN → Verify GREEN → GREEN Sco
     3. 标记步骤归属（✅ 属于当前 RED / ⛔ 属于后续 RED）
     4. 仅实现标记为 ✅ 的步骤
   - ⛔ **逐条确认 YAGNI 围栏**：读取 tasks.md 中本 GREEN 任务的 YAGNI 围栏声明，逐条确认"未实现 [后续 RED 的行为]：✅"
+
+  <Good>
+  ```java
+  // ✅ RED 只断言了 login 返回 Token，GREEN 只实现到返回 Token
+  public Token login(String username, String password) {
+      User user = userMapper.findByUsername(username);
+      return new Token(jwtUtil.generate(user.getId()));
+  }
+  ```
+  </Good>
+
+  <Bad>
+  ```java
+  // ❌ RED 只断言了 login 返回 Token，GREEN 却同时实现了密码校验（后续 RED 的行为）
+  public Token login(String username, String password) {
+      User user = userMapper.findByUsername(username);
+      if (!passwordEncoder.matches(password, user.getPassword())) {
+          throw new BusinessException(2001, "密码错误"); // 越界！后续 RED 才需要
+      }
+      if (user.getStatus() == UserStatus.DISABLED) {
+          throw new BusinessException(2002, "账号禁用"); // 越界！后续 RED 才需要
+      }
+      return new Token(jwtUtil.generate(user.getId()));
+  }
+  ```
+  </Bad>
 - **Verify GREEN**（强制执行）：
   - 确认测试通过
   - 其他测试仍通过
@@ -95,10 +153,12 @@ RED → Verify RED → 🔴中断声明 → GREEN → Verify GREEN → GREEN Sco
 
 > 完整规则见 `opsx-tdd-rules/rules/controller-strategy.md`，此处仅保留快速参考。
 
-| 策略 | 说明 | 适用 |
-|------|------|------|
-| 策略 A | 为每个 Controller 接口生成 RED 测试（@WebMvcTest），拆为 RED→GREEN 对 | Controller 含业务逻辑 |
-| 策略 B | Controller 作为非 TDD 模块，独立接口层任务，仅做编译检查 | Controller 为纯接线（调用 Service + 返回 Result） |
+⛔ Controller 层**必须**有测试。两种策略的区别在于测试方式，而非"有无测试"。
+
+| 策略 | 说明 | 适用 | 测试方式 |
+|------|------|------|----------|
+| 策略 A | Controller 拆 RED→GREEN（@WebMvcTest） | Controller 含业务逻辑 | TDD 红绿循环 |
+| 策略 B | Controller 先接线，再写 @WebMvcTest 验证 | Controller 为纯接线（调用 Service + 返回 Result） | impl-first：CTRL-IMPL → CTRL-TEST |
 
 必须在 tasks.md §2.0 中声明使用哪种策略。
 

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

@@ -24,7 +24,7 @@ description: "opsx-tdd-core 自检清单 — TDD 执行合规自检、合规性
 - [ ] REFACTOR 后全部测试仍绿
 - [ ] 未出现"先写生产代码再补测试"的情况
 
-## §B TDD 合规性检查（10 项）
+## §B TDD 合规性检查（11 项）
 
 仅 `test-strategy=tdd` 时执行：
 
@@ -36,7 +36,9 @@ description: "opsx-tdd-core 自检清单 — TDD 执行合规自检、合规性
 - [ ] GREEN 任务验收标准为"让对应 RED 通过"（而非"实现完整功能"）
 - [ ] GREEN 任务输出不含未测试的 Controller/Filter/Config
 - [ ] 已声明 Controller 层处理策略（策略 A 或 B）
+- [ ] Controller 层两种策略都生成了测试任务（策略 A: RED→GREEN 对；策略 B: CTRL-IMPL → CTRL-TEST）
 - [ ] 每个 RED 任务包含测试方法名（`{method}_{state}_{outcome}` 格式）
+- [ ] 每个 GREEN 任务包含 YAGNI 围栏声明（"不提前实现 [后续 RED 行为]"）
 - [ ] 每个 REFACTOR 任务列出至少 2 个具体重构点
 
 ## §C 完成验证清单（8 项）