kld-sdd 2.6.7 → 2.6.9

package/templates/git-hooks/commit-msg-sdd-trailer.cjs

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * commit-msg hook，两种布局：
+ *
+ * - 多仓（代码仓有 .sdd.yaml，spec 是另一个 clone）：
+ *   写 Spec-Revision（spec 干净 HEAD 的完整 SHA）+ Spec-Change（活动 change，可多条）。
+ * - 单仓（openspec 与代码同仓）：
+ *   spec 与代码在同一次 commit 里，指针自指无意义 → 只写 Spec-Change，不写 Spec-Revision，
+ *   且不做「spec 工作区干净」检查（提交进行中必然是脏的）。
+ *
+ * Spec-Change 来源：KLD_SDD_CHANGE（显式覆盖）> sdd.config.yaml active_changes。
+ * Not from branch name, ever.
+ *
+ * Authority: 10-最小化多仓库关联与变更命名方案.md
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function resolveOntologyDir() {
+  const deployed = path.join(__dirname, '..', 'ontology');
+  if (fs.existsSync(path.join(deployed, 'change-key.cjs'))) return deployed;
+  const fromPackageTemplates = path.join(__dirname, '..', '..', 'skywalk-sdd', 'ontology');
+  if (fs.existsSync(path.join(fromPackageTemplates, 'change-key.cjs'))) return fromPackageTemplates;
+  throw new Error('无法定位 skywalk-sdd/ontology');
+}
+
+const ontologyDir = resolveOntologyDir();
+const changeKey = require(path.join(ontologyDir, 'change-key.cjs'));
+const sddConfig = require(path.join(ontologyDir, 'sdd-config.cjs'));
+const activeChanges = require(path.join(ontologyDir, 'active-changes.cjs'));
+const { parseFrontmatter } = require(path.join(ontologyDir, 'artifact-parser.cjs'));
+
+function projectRootFromHook() {
+  const explicit = process.argv.find((arg) => arg.startsWith('--project='));
+  if (explicit) return path.resolve(explicit.slice('--project='.length));
+  return path.resolve(__dirname, '..', '..');
+}
+
+function fail(message) {
+  console.error(`[kld-sdd commit-msg] ${message}`);
+  process.exit(1);
+}
+
+function isSddLinkedCodeRepo(codeRepoRoot) {
+  return fs.existsSync(path.join(codeRepoRoot, '.sdd.yaml'));
+}
+
+/**
+ * 决定本次提交按哪种布局处理。布局来自 .sdd.yaml 显式声明，不做启发式推断
+ * （否则单独诊断的 spec 仓 clone 会被误判成单仓）。
+ *
+ * 单仓优先于 specPath：即使用户把 sdd.specPath 指回本仓，也走单仓路径，
+ * 否则会因为「spec 工作区不干净」永久阻断提交。
+ */
+function resolveLayout(repoRoot, env = process.env) {
+  if (!isSddLinkedCodeRepo(repoRoot)) {
+    return { mode: 'unlinked' };
+  }
+  if (sddConfig.isMonoLayout(repoRoot)) {
+    return { mode: 'mono', specPath: repoRoot };
+  }
+
+  const context = sddConfig.resolveCodeRepoContext(repoRoot, env);
+  if (!context.specPath) {
+    fail(context.message || '无法解析 spec clone 路径。请执行 kld-sdd link-spec --path=<spec>');
+  }
+  if (context.code === sddConfig.CODES.SPEC_PATH_INVALID) {
+    fail(context.message);
+  }
+  // specPath 指回本仓：等同单仓，不能按外部 spec 校验干净度
+  if (path.resolve(context.specPath) === path.resolve(repoRoot)) {
+    return { mode: 'mono', specPath: repoRoot, context };
+  }
+  return { mode: 'multi', specPath: context.specPath, context };
+}
+
+/**
+ * Explicit override: KLD_SDD_CHANGE, comma/space separated for several changes.
+ * Not from branch name, not from repo-wide git config.
+ */
+function parseEnvChangeKeys(env = process.env) {
+  const raw = env.KLD_SDD_CHANGE && String(env.KLD_SDD_CHANGE).trim();
+  if (!raw) return null;
+  const keys = [];
+  for (const token of raw.split(/[,\s]+/).filter(Boolean)) {
+    const validated = changeKey.validate(token);
+    if (!validated.ok) {
+      fail(`KLD_SDD_CHANGE 无效: ${validated.message}`);
+    }
+    if (!keys.includes(validated.normalized)) keys.push(validated.normalized);
+  }
+  return keys.length ? keys : null;
+}
+
+/**
+ * Spec-Change values: explicit env wins, otherwise every active change
+ * registered in the spec repo's sdd.config.yaml.
+ */
+function resolveChangeKeys(specRoot, env = process.env) {
+  const fromEnv = parseEnvChangeKeys(env);
+  if (fromEnv) {
+    for (const key of fromEnv) {
+      requireChangeDir(specRoot, key, { strict: true });
+    }
+    return { keys: fromEnv, source: 'env' };
+  }
+  const registered = activeChanges.activeChangeKeys(specRoot);
+  const keys = registered.filter((key) => requireChangeDir(specRoot, key, { strict: false }));
+  return { keys, source: 'sdd.config.yaml' };
+}
+
+/**
+ * @param {{ strict: boolean }} options strict=true 阻断提交；false 仅警告并跳过该条
+ */
+function requireChangeDir(specRoot, key, options = { strict: true }) {
+  const proposalPath = path.join(specRoot, 'openspec', 'changes', key, 'proposal.md');
+  if (!fs.existsSync(proposalPath)) {
+    const message = `spec 中不存在 change: openspec/changes/${key}/proposal.md`;
+    if (options.strict) fail(message);
+    console.error(`[kld-sdd commit-msg] 警告: ${message}（已跳过该 Spec-Change）`);
+    return false;
+  }
+  const lines = fs.readFileSync(proposalPath, 'utf8').split(/\r?\n/);
+  const fm = parseFrontmatter(lines);
+  const declared = (fm['change-key'] || '').toLowerCase();
+  if (declared && declared !== key) {
+    const message = `proposal change-key (${declared}) 与目录 (${key}) 不一致`;
+    if (options.strict) fail(message);
+    console.error(`[kld-sdd commit-msg] 警告: ${message}（已跳过该 Spec-Change）`);
+    return false;
+  }
+  return true;
+}
+
+/**
+ * 重写 Trailer 区块：同名旧行先全部摘除，再作为连续区块追加到末尾。
+ *
+ * @param {Record<string, string|string[]>} trailers 数组值写成多条同名 Trailer
+ */
+function upsertTrailers(message, trailers) {
+  let body = String(message || '').replace(/\s+$/g, '');
+  const block = [];
+
+  for (const [name, value] of Object.entries(trailers)) {
+    const linePattern = new RegExp(`^${name}:[^\\n]*\\n?`, 'gim');
+    body = body.replace(linePattern, '');
+    const values = (Array.isArray(value) ? value : [value]).filter(
+      (item) => item != null && String(item).length > 0,
+    );
+    for (const item of values) {
+      block.push(`${name}: ${item}`);
+    }
+  }
+
+  body = body.replace(/\s+$/g, '');
+  if (block.length) {
+    body += `\n\n${block.join('\n')}`;
+  }
+  body = body.replace(/\n{3,}/g, '\n\n');
+  if (!body.endsWith('\n')) body += '\n';
+  return body;
+}
+
+function main(env = process.env) {
+  const msgFile = process.argv[2];
+  if (!msgFile) {
+    fail('缺少 commit message 文件参数');
+  }
+
+  const repoRoot = projectRootFromHook();
+  const layout = resolveLayout(repoRoot, env);
+
+  // 未接入 SDD 的普通代码仓：不写 Trailer
+  if (layout.mode === 'unlinked') {
+    process.exit(0);
+  }
+
+  const trailers = {
+    // 多个活动 change 时写多条 Spec-Change
+    'Spec-Change': resolveChangeKeys(layout.specPath, env).keys,
+  };
+
+  if (layout.mode === 'multi') {
+    const context = layout.context;
+    // remote mismatch：仍允许写本地 Revision（溯源本地快照）；仅警告
+    if (context.code === sddConfig.CODES.REMOTE_MISMATCH) {
+      console.error(`[kld-sdd commit-msg] 警告: ${context.message}`);
+    }
+
+    if (!sddConfig.gitWorkingTreeClean(layout.specPath)) {
+      fail('spec 工作区不干净。请先提交或暂存 spec 变更后再提交代码。');
+    }
+
+    const revision = sddConfig.gitHeadSha(layout.specPath);
+    if (!revision || revision.length < 40) {
+      fail(`无法读取完整 Spec-Revision（需要完整 SHA）: ${revision}`);
+    }
+    trailers['Spec-Revision'] = revision;
+  }
+
+  const original = fs.readFileSync(msgFile, 'utf8');
+  const updated = upsertTrailers(original, trailers);
+  fs.writeFileSync(msgFile, updated, 'utf8');
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (error) {
+    fail(error.message || String(error));
+  }
+}
+
+module.exports = {
+  upsertTrailers,
+  parseEnvChangeKeys,
+  resolveChangeKeys,
+  isSddLinkedCodeRepo,
+  resolveLayout,
+  main,
+};

package/templates/modules.yaml

@@ -0,0 +1,13 @@
+# 模块代号注册表（spec 仓库根目录）
+# 只登记模块代号与中文名，不包含代码仓库、路径或 CI 配置。
+version: 1
+
+modules:
+  fi:
+    name: 财务核算
+  mm:
+    name: 物料管理
+  sd:
+    name: 销售与分销
+  cross:
+    name: 跨模块

package/templates/openspec/proposal.md

@@ -1,6 +1,12 @@
 ---
 # 【用户选择配置 - 由 /opsx:propose 引导填写】
-change-id: "CHG-<CHANGE-SLUG>" # 创建时生成，后续不得修改
+change-id: "CHG-<MODULE>-<YYMMDD>-<SLUG>" # 创建时由 change-key 派生一次，后续不得修改
+change-key: "<module>-<yymmdd>-<slug>" # spec 仓目录名；可选写入代码 commit 的 Spec-Change（需 KLD_SDD_CHANGE）
+title: "<中文标题>" # 人读名称，opsx-explore / 知识平台展示
+module: "<module>" # modules.yaml 中的模块代号；跨模块用 cross
+# affected-modules: # 仅 module=cross 时必填，至少两个已注册模块
+#   - fi
+#   - mm
 entity-id: "<8位十六进制ID>" # Change 的全局逻辑实体 ID，added 时生成
 version-id: "<UUID>" # 本次 Change 版本 UUID
 delta-state: "added"

package/templates/sdd.config.yaml

@@ -0,0 +1,12 @@
+# 活动变更登记表（spec 仓库根目录）
+# 由 opsx-propose 隐式写入、opsx-archive 隐式移除，供代码仓 AI 与 commit-msg Hook 读取。
+# 不登记代码仓清单、路径 glob 或 CI 配置。
+version: 1
+
+active_changes:
+# 示例（propose 会自动写入，无需手填）：
+#   - change-key: fi-260727-account-doc-head-create
+#     change-id: CHG-FI-260727-ACCOUNT-DOC-HEAD-CREATE
+#     title: 会计凭证头创建
+#     module: fi
+#     summary: 支持凭证头创建与字段校验

package/templates/skills/kld-sdd/openspec-sync-specs/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: openspec-sync-specs
+description: Sync delta specs from a change to main specs. Use when the user wants to update main specs with changes from a delta spec, without archiving the change.
+allowed-tools: Bash(openspec:*)
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.6.0"
+---
+
+Sync delta specs from a change to main specs.
+
+This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).
+
+**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show changes that have delta specs (under `specs/` directory).
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Resolve change context**
+
+   Run:
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+
+3. **Find delta specs**
+
+   Use `artifactPaths.specs.existingOutputPaths` from the status JSON as the list of delta spec files.
+
+   Each delta spec file contains sections like:
+   - `## ADDED Requirements` - New requirements to add
+   - `## MODIFIED Requirements` - Changes to existing requirements
+   - `## REMOVED Requirements` - Requirements to remove
+   - `## RENAMED Requirements` - Requirements to rename (FROM:/TO: format)
+
+   If no delta specs found, inform user and stop.
+
+4. **For each delta spec, apply changes to main specs**
+
+   For each repo-local capability delta spec path returned by the CLI:
+
+   a. **Read the delta spec** to understand the intended changes
+
+   b. **Read the main spec** at `openspec/specs/<capability>/spec.md` (may not exist yet)
+
+   c. **Apply changes intelligently**:
+
+      **ADDED Requirements:**
+      - If requirement doesn't exist in main spec → add it
+      - If requirement already exists → update it to match (treat as implicit MODIFIED)
+
+      **MODIFIED Requirements:**
+      - Find the requirement in main spec
+      - Apply the changes - this can be:
+        - Adding new scenarios (don't need to copy existing ones)
+        - Modifying existing scenarios
+        - Changing the requirement description
+      - Preserve scenarios/content not mentioned in the delta
+
+      **REMOVED Requirements:**
+      - Remove the entire requirement block from main spec
+
+      **RENAMED Requirements:**
+      - Find the FROM requirement, rename to TO
+
+   d. **Create new main spec** if capability doesn't exist yet:
+      - Create `openspec/specs/<capability>/spec.md`
+      - Add Purpose section (can be brief, mark as TBD)
+      - Add Requirements section with the ADDED requirements
+
+5. **Show summary**
+
+   After applying all changes, summarize:
+   - Which capabilities were updated
+   - What changes were made (requirements added/modified/removed/renamed)
+
+**Delta Spec Format Reference**
+
+```markdown
+## ADDED Requirements
+
+### Requirement: New Feature
+The system SHALL do something new.
+
+#### Scenario: Basic case
+- **WHEN** user does X
+- **THEN** system does Y
+
+## MODIFIED Requirements
+
+### Requirement: Existing Feature
+#### Scenario: New scenario to add
+- **WHEN** user does A
+- **THEN** system does B
+
+## REMOVED Requirements
+
+### Requirement: Deprecated Feature
+
+## RENAMED Requirements
+
+- FROM: `### Requirement: Old Name`
+- TO: `### Requirement: New Name`
+```
+
+**Key Principle: Intelligent Merging**
+
+Unlike programmatic merging, you can apply **partial updates**:
+- To add a scenario, just include that scenario under MODIFIED - don't copy existing scenarios
+- The delta represents *intent*, not a wholesale replacement
+- Use your judgment to merge changes sensibly
+
+**Output On Success**
+
+```
+## Specs Synced: <change-name>
+
+Updated main specs:
+
+**<capability-1>**:
+- Added requirement: "New Feature"
+- Modified requirement: "Existing Feature" (added 1 scenario)
+
+**<capability-2>**:
+- Created new spec file
+- Added requirement: "Another Feature"
+
+Main specs are now updated. The change remains active - archive when implementation is complete.
+```
+
+**Guardrails**
+- Read both delta and main specs before making changes
+- Preserve existing content not mentioned in delta
+- If something is unclear, ask for clarification
+- Show what you're changing as you go
+- The operation should be idempotent - running twice should give same result

package/templates/skills/kld-sdd/openspec-update-change/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: openspec-update-change
+description: Update an OpenSpec change by revising its existing planning artifacts and keeping them coherent with one another. Use when the user wants to revise a change's plan, fold new decisions into it, or reconcile its artifacts after an edit. Never edits code.
+allowed-tools: Bash(openspec:*)
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.6.0"
+---
+
+Revise a change's existing planning artifacts and keep them coherent. Never edit code.
+
+**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to update.
+
+   Present the top 3-4 most recently modified changes as options, showing:
+   - Change name
+   - Schema (from `schema` field if present, otherwise "spec-driven")
+   - Status (e.g., "0/5 tasks", "complete", "no tasks")
+   - How recently it was modified (from `lastModified` field)
+
+   Mark the most recently modified change as "(Recommended)" since it's likely what the user wants to update.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Get the change's artifacts**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand current state. The response includes:
+   - `schemaName`: The workflow schema being used (e.g., "spec-driven")
+   - `artifacts`: Array of artifacts with their status ("done", "ready", "blocked")
+   - `isComplete`: Boolean indicating if all artifacts are complete
+   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths.
+
+   The artifact ids and paths come from the active schema - do NOT assume them, and do NOT branch on hardcoded artifact names. Custom schemas must work unchanged.
+
+   The files to edit are `artifactPaths.<id>.existingOutputPaths` - the concrete files that exist on disk, already glob-expanded for glob artifacts (e.g. `specs/**/*.md`). Do NOT write to `resolvedOutputPath`: for a glob artifact it is still the glob pattern, not a real file.
+
+3. **Understand the request**
+   - If the user asked for a specific revision ("the design now uses X"), that is the starting edit.
+   - If they only said "update" / "make this coherent", treat it as a coherence review: read the existing artifacts and check them against each other for contradictions, gaps, and duplication.
+
+4. **Read and reconcile**
+   - Read the artifact(s) the request touches and the change's other existing artifacts.
+   - Apply the requested edit. Then check every other existing artifact against it - in ANY direction: an edit to a later artifact may require revising an earlier one, not only the other way around. Build order is a useful reading order, not a constraint on which artifacts may be revised.
+   - Note everything that is now inconsistent, missing, or contradictory.
+   - Revise only files that already exist (`existingOutputPaths`). Do NOT create artifacts that don't exist yet, and do NOT invent new files under a glob artifact - note them and point the user to `/opsx:continue` to create them.
+   - If the change is already coherent, say so and make no edits.
+
+5. **Confirm and apply, one artifact at a time**
+   - Show each proposed revision and why. Write only after the user confirms.
+   - If the user rejects a revision, do not write it - leave that artifact unchanged.
+   - When a substantial rewrite is needed, get that artifact's rules and template first:
+     ```bash
+     openspec instructions <artifact-id> --change "<name>" --json
+     ```
+
+6. **Point to the next step (guidance only - NEVER act on it)**
+   - Artifacts still missing -> suggest `/opsx:continue` to create them.
+   - Change already implemented (tasks checked off / already applied) -> the code may no longer match the revised plan; suggest `/opsx:apply` to carry the delta into code.
+   - Everything done and implemented -> suggest `/opsx:archive`.
+
+**Output**
+
+After each invocation, show:
+- Which artifacts were revised (and which proposed revisions were rejected)
+- Anything deferred to `/opsx:continue` (not-yet-created artifacts or files)
+- Where the change stands and the recommended next command
+
+**Guardrails**
+- Planning artifacts only - NEVER edit implementation code. If the revised plan implies code changes, stop and point to `/opsx:apply`.
+- Use the artifact ids and paths reported by `openspec status`; never branch on hardcoded artifact names.
+- Edit only the concrete files in `existingOutputPaths`; never write to a glob `resolvedOutputPath`.
+- Do not advance the build frontier: no new artifacts, no new files under glob artifacts - that is `/opsx:continue`'s job.
+- Confirm every edit with the user before writing.
+- If the request changes the change's *intent* rather than refining it, recommend starting fresh with `/opsx:new` (the "Update vs. Start Fresh" heuristic).

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

@@ -183,8 +183,8 @@ openspec list --json
 
 **执行每个任务**（a-g 步骤）：
 
-a. **DAG 依赖检查 & 层级收集** — 收集依赖已满足的待执行任务；同层多个独立任务可并行派发子代理。
-b. **显示当前层级任务** — `📍 层级 [X]：准备派发 [K] 个子代理并行处理 [M] 个任务`。
+a. **DAG 依赖检查 & 层级收集** — 收集依赖已满足的待执行任务；同层多个独立任务可并行派发子代理。**⛔ TDD 模式豁免**：当 `test-strategy=tdd` 时，同层的 RED→GREEN 对**不可并行**，必须逐对串行执行（见下方 S2）。仅同层的非 TDD 模块任务（UI/配置/SQL DDL）可并行。
+b. **显示当前层级任务** — `📍 层级 [X]：准备派发 [K] 个子代理并行处理 [M] 个任务`。**TDD 模式下**：若本层含 RED→GREEN 对，显示 `📍 层级 [X]：[M] 个 RED→GREEN 对须逐对串行执行（TDD 串行约束），[K] 个非 TDD 任务可并行`。
 c. **🤖 派发子代理实现代码** — 使用 Agent 工具并行派发同层任务，⛔ 子代理阶段不创建 worktree/分支。**派发模板与状态处理见 `./reference.md`「§5c 子代理派发模板」+ `./implementer-prompt.md`**。
 d. **⛔ 编译检查门禁** — 每完成一个任务后必须编译通过；**详细见 `./checklist.md`「§5d 编译检查门禁」**。
 e. **⛔ 测试执行门禁** — 按 `proposal.md` 的 `test-strategy` 决定（tdd=强制, impl-first=警告, none=跳过）；**详细见 `./checklist.md`「§5e 测试执行门禁」**。
@@ -285,7 +285,7 @@ g. **继续下一个层级** — 重新检查 DAG，找出依赖已满足的下
 - **⛔ 必须实时更新任务状态**：每完成一个任务立即改 tasks.md，两种格式同步。
 - **⛔ apply 结束前 checkbox 全量同步校验**：`stage_end` 前对比 telemetry `task_update` 记录数与 tasks.md `[x]` 数量，不一致则补齐（见 `./checklist.md` §5f.1）。
 - **⛔ task_update 后必须验证 checkbox 已更新**：执行 `check-task` 确认 tasks.md 对应行已变更；未更新则手动修改。
-- **⛔ TDD RED→GREEN 严格串行**：不适用同层并行派发；RED-N 确认失败后必须执行中断声明再进入 GREEN-N；GREEN 完成后必须通过 Scope 门禁再进入下一个 RED。
+- **⛔ TDD RED→GREEN 严格串行**：不适用同层并行派发；RED-N 确认失败后必须执行中断声明再进入 GREEN-N；GREEN 完成后必须通过 Scope 门禁再进入下一个 RED。同层存在多个 RED→GREEN 对时，必须逐对串行完成，禁止并行派发子代理处理多个 RED→GREEN 对。同层非 TDD 模块任务（UI/配置/SQL DDL）仍可并行。
 - **Git 只读策略**：禁止为了度量自动初始化 Git、创建分支或提交 commit；非 Git 项目用 `vcs_mode=no-git` 继续执行。
 - **⛔ Step 0.1 隔离校验必做**：建 worktree / 建议分支名前必须完成 proposal + 跨 cap spec 依赖校验并输出报告。
 - **Worktree 为加速手段，非必选项**：校验通过且解耦方可多 worktree；有依赖或共享修改面则串行。

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

@@ -130,7 +130,7 @@ description: opsx-apply 的阶段强制检查点与自检清单。仅在执行 a
 - [ ] ⛔ **必须实时更新任务状态**：每完成一个任务立即改 tasks.md，两种格式（`- [ ]`→`- [x]` 与 `**状态**: [ ]`→`[x]`）同步
 - [ ] ⛔ **apply 结束前 checkbox 全量同步校验**：见 §5f.1，`stage_end` 前对比 telemetry `task_update` 记录数与 tasks.md `[x]` 数量
 - [ ] ⛔ **task_update 后必须验证 checkbox 已更新**：执行 `check-task` 确认 tasks.md 对应行已变更；未更新则手动修改
-- [ ] ⛔ **TDD RED→GREEN 严格串行**：不适用同层并行派发；RED-N 确认失败后必须执行中断声明再进入 GREEN-N；GREEN 完成后必须通过 Scope 门禁再进入下一个 RED
+- [ ] ⛔ **TDD RED→GREEN 严格串行**：不适用同层并行派发；RED-N 确认失败后必须执行中断声明再进入 GREEN-N；GREEN 完成后必须通过 Scope 门禁再进入下一个 RED。同层多个 RED→GREEN 对须逐对串行，禁止并行派发；同层非 TDD 模块任务仍可并行
 - [ ] ⛔ **TDD 节奏校验**：见 §5e.1，连续 RED-N/GREEN-N 的 `task_update` 时间戳须有可验证间距
 - [ ] **Git 只读策略**：禁止为了度量自动初始化 Git、创建分支或提交 commit；非 Git 项目用 `vcs_mode=no-git` 继续执行
 - [ ] ⛔ **Step 0.1 隔离校验必做**：建 worktree / 建议分支名前必须完成 proposal + 跨 cap spec 依赖校验并输出报告；未通过不得按 full 并行策略拆 `kld-sdd/<change>/<cap>`

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

@@ -17,7 +17,7 @@ allowed-tools:
 
 你是一个 SDD（Specification-Driven Development）变更归档专家。激活本技能后，你要安全地结束变更生命周期：真实归档文档、同步正式 specs、记录 archive telemetry，并生成最终中文度量报告。
 
-> **硬依赖（收尾入库）**：zip 生成后的上传依赖同级已部署的 **`opsx-kb-ingest`**。进入 §5.5 前必须先 `Read` 该技能的 `SKILL.md` 并完成其 Session 启动。缺失则提示用户重新 `kld-sdd-init`，**不要**自造另一套入库协议。
+> **硬依赖（收尾入库）**：zip 生成后的上传依赖同级已部署的 **`opsx-kb-ingest`**。进入 §5.5 前必须先 `Read` 该技能的 `SKILL.md` 并完成其 Session 启动。入库成功后，`Read` `opsx-ontology-query/phase-3-postchange.md` 验证版本生效、AC 保留、关系完整性。缺失则提示用户重新 `kld-sdd-init`，**不要**自造另一套入库协议。
 
 > **跨平台执行规则**
 > - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
@@ -118,6 +118,16 @@ node skywalk-sdd/log.cjs archive-docs --project=. --change=<变更名称> --reas
 - 最终中文报告生成到 `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.4 隐式注销活动变更
+
+归档成功后立即执行（不询问用户）：
+
+```bash
+node skywalk-sdd/ontology/cli.cjs active-change --remove --change=<变更名称> --project=.
+```
+
+把该 change 从 spec 仓 `sdd.config.yaml` 的 `active_changes` 移除，避免已归档 change 继续被代码 commit 写成 `Spec-Change`。该操作幂等；条目本就不存在时不报错。
+
 ### 5.5 收尾入库（opsx-kb-ingest）
 
 1. 确认 `${AGENT_SKILL_DIR}/opsx-kb-ingest/SKILL.md` 存在并 Read；按该技能完成 API Key / targets。

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

@@ -1,9 +1,10 @@
----
+---
 name: opsx-check
 description: "质量检查技能 - 验证文档完整性、一致性、算法正确性及可执行性"
 argument-hint: "[change-name] [上下文文件...]"
 license: MIT
-compatibility: Requires openspec CLI.
+compatibility: Requires openspec CLI; depends on opsx-ontology-query for external-key validation and baseline checks.
+  depends-on: opsx-ontology-query
 metadata:
   author: sdd-team
   version: "3.0"
@@ -25,6 +26,10 @@ allowed-tools:
 > 即使检查发现代码相关问题，也只记录在检查报告中，**不自动修复代码**。
 > 代码修复将在 `/opsx-apply` 阶段进行。
 
+> **KB 上下文**：check 阶段需验证外部键格式（REQ/FEAT/SCN 文法）、SCN REQ 前缀一致性和历史覆盖率基线。进入相关步骤前先 `Read` `opsx-ontology-query/phase-2-during.md` §3-5，并按 `SKILL.md` → Session 启动准备 API Key + targets。
+>
+> **📡 KB 就绪检查**：§2.6 在进入 KB 相关检查前会检测 KB 配置状态。若未配置，会**主动询问**用户选择「配置」或「跳过」，KB 相关检查项降级为仅本地验证。
+
 
 > **🖥️ 跨平台执行规则**
 > - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
@@ -69,6 +74,71 @@ openspec list
 - `specs/<capability>/design.md`（实现方案）
 - `specs/<capability>/tasks.md`（或 task.md，兼容旧格式）（任务拆解）
 
+### 2.5 【多仓库关联配置诊断】（在五维检查之前）
+
+先执行轻量配置诊断，**不执行代码 diff**，只检查命名与引用配置：
+
+```bash
+# 在 spec 仓库：
+node skywalk-sdd/ontology/cli.cjs diagnose-naming --project=. --change=<change-key>
+
+# 在代码仓库：
+node skywalk-sdd/ontology/cli.cjs diagnose-naming --project=. --mode=code-repo
+```
+
+诊断结果三类：
+
+| 状态 | 含义 |
+|------|------|
+| PASS | 配置完整 |
+| FIXABLE | 修复方式唯一，用户确认后可自动修复（如安装 commit-msg Hook、设置 sdd.specPath） |
+| NEEDS_INPUT | 多候选或团队级配置，必须询问用户 |
+
+规则：
+- 只问缺失项，不重复询问已合法配置
+- 本地 Git config / Hook 可在确认后修复
+- `.sdd.yaml`、`modules.yaml`、proposal frontmatter 修改前必须展示变更摘要
+- 已被代码 commit 引用的 change-id/change-key **禁止静默重命名**
+- 用户拒绝修复时按严重程度记 warning/failure，然后继续后续文档检查
+- spec 仓诊断跳过代码仓 Hook；代码仓诊断跳过 modules/change 命名（入口分离）
+- 单仓（`.sdd.yaml` 声明 `layout: mono`，openspec 与代码同仓）：`mode=mono-repo`，命名与 Hook 一并就地检查；该布局 commit 只写 `Spec-Change`，不写 `Spec-Revision`
+- 若在个人工作目录发现未接入的新代码仓（缺 `.sdd.yaml` 或 commit-msg Hook）：
+  1. 向用户展示仓名列表；
+  2. 用户确认后执行 `kld-sdd sync-repos`（只装 Hook/关联，不装 skills）；
+  3. 用户拒绝则记 warning，不阻断五维文档检查
+- Trailer 协议：已接入仓 commit 必写 `Spec-Revision`；`Spec-Change` 来自 spec 仓 `sdd.config.yaml` 的 `active_changes`（多个则写多条），`KLD_SDD_CHANGE` 可显式覆盖，**不从分支名推断**
+- 活动变更登记表诊断：`sdd.config.yaml` 是否存在且格式合法；当前 change 是否已登记（未登记则提示执行 `active-change --register`）；登记项对应目录是否仍存在（已归档应执行 `active-change --remove`）
+
+最终检查报告必须包含「多仓库关联配置」章节（命令输出已按此格式打印）。
+
+### 2.6 【KB 就绪检查】检测并配置知识库连接
+
+在进入 KB 相关检查（外部键验证、coverage 基线）之前，检测 Engineering KB 的连接状态。
+
+1. 检查 proposal.md frontmatter 中 `kb-status` 字段：
+   - 若 `kb-status: degraded(by-user-choice)` → KB 已被用户明确跳过，本阶段 KB 相关检查降级为仅本地验证（external-key 格式校验 + 本地 semantic-check），跳过 KB API 调用。
+   - 若未标记 → 继续检查。
+2. 运行 KB 就绪检查（程序化检测，自动搜索多 IDE 目录，消除路径歧义）：
+   ```bash
+   node skywalk-sdd/context-client.cjs --check-only
+   ```
+   - 输出 `"available": true` → KB 已配置
+   - 输出 `"available": false` → KB 未配置
+3. **若已配置** → 直接进入 §3，正常使用 KB 做 coverage 基线、predecessor 预检。
+4. **若未配置** → 使用 **AskUserQuestion** 询问：
+
+   > "📡 **Engineering KB 未配置**
+   >
+   > KB 可以提供覆盖率基线检查、predecessor 版本预检（防止入库冲突）。是否现在配置？
+   >
+   > - A. **配置 KB**
+   > - B. **跳过 KB**，仅执行本地检查（semantic-check + external-key 格式校验），入库前无 predecessor 预检
+   > - C. **取消操作**"
+
+   - **选 A** → 配置 → 进入 §3。
+   - **选 B** → KB 相关检查项降级：coverage 基线跳过、`current-version` 预检跳过。检查报告中标注 `kb: degraded(by-user-choice)`。
+   - **选 C** → 终止 check。
+
 ### 3. 【上下文加载】识别并读取用户提供的文件
 
 **自动识别上下文文件**：
@@ -117,7 +187,7 @@ openspec list
 
 #### 4.4a TDD 合规性检查（仅 test-strategy=tdd 时执行）
 
-⛔ 执行 `opsx-tdd-core/checklist.md` §B（11 项）逐项检查。
+⛔ 执行 `opsx-tdd-core/checklist.md` §B（15 项）逐项检查。
 
 > 不在此内联复制，以 opsx-tdd-core/checklist.md §B 为唯一真相源。
 > 额外补充：还需检查 `opsx-tdd-rules/rules/exception-path-coverage.md`（异常路径覆盖门禁）。