kld-sdd 2.6.7 → 2.6.8

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/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

@@ -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,4 +1,4 @@
----
+---
 name: opsx-check
 description: "质量检查技能 - 验证文档完整性、一致性、算法正确性及可执行性"
 argument-hint: "[change-name] [上下文文件...]"
@@ -69,6 +69,43 @@ 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`）
+
+最终检查报告必须包含「多仓库关联配置」章节（命令输出已按此格式打印）。
+
 ### 3. 【上下文加载】识别并读取用户提供的文件
 
 **自动识别上下文文件**：
@@ -117,7 +154,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`（异常路径覆盖门禁）。

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

@@ -1,4 +1,4 @@
----
+---
 name: opsx-explore
 description: "浏览变更技能 - 查看所有变更状态和 SDD 文档完整性概览"
 argument-hint: "[change-name]"
@@ -10,8 +10,6 @@ metadata:
 allowed-tools:
   - Bash
   - Read
-  - Write
-  - Edit
 ---
 
 你是一个 SDD（Specification-Driven Development）变更浏览专家。激活本技能后，你将展示项目中所有变更的状态概览，并引导用户执行下一步操作。
@@ -40,8 +38,15 @@ allowed-tools:
 
 ## 启动流程
 
-### 1. 获取所有变更列表
+### 1. 获取所有变更列表（按模块中文分组）
 
+优先使用命名协议分组：
+```bash
+node skywalk-sdd/ontology/cli.cjs list-changes --project=.
+# 需要结构化数据时加 --json
+```
+
+也可辅助：
 ```bash
 openspec list
 ```
@@ -52,25 +57,40 @@ openspec list
 ### 2. 检查每个变更的 SDD 文档完整性
 
 对每个变更，检查以下文件是否存在：
-- `openspec/changes/<name>/proposal.md`（P）
-- `openspec/changes/<name>/specs/<capability>/spec.md`（S）
-- `openspec/changes/<name>/specs/<capability>/design.md`（D）
-- `openspec/changes/<name>/specs/<capability>/tasks.md`（T）
+- `openspec/changes/<change-key>/proposal.md`（P）
+- `openspec/changes/<change-key>/specs/<capability>/spec.md`（S）
+- `openspec/changes/<change-key>/specs/<capability>/design.md`（D）
+- `openspec/changes/<change-key>/specs/<capability>/tasks.md`（T）
 
 同时获取每个变更状态：
 ```bash
-openspec status --change "<name>" --json
+openspec status --change "<change-key>" --json
 ```
 
-### 3. 展示变更概览表
+### 3. 展示按模块分组的变更概览
+
+展示格式（title 来自 proposal frontmatter，目录定位使用 change-key）：
+
+```text
+📦 财务核算 (fi)
+  ● 会计凭证头创建
+    fi-260727-account-doc-head-create
+    P✅ S✅ D✅ T❌ | 建议: /opsx-task fi-260727-account-doc-head-create
+
+📦 跨模块 (cross)
+  ● 凭证与库存联动
+    cross-260727-fi-mm-voucher-stock-link
+    affected: fi, mm
+
+📦 未分类
+  ● legacy-add-user-auth
+    legacy-add-user-auth
+```
 
-> "📋 **项目变更概览**（P=提案 S=规格 D=设计 T=任务）：
->
-> | 变更名称 | P | S | D | T | openspec状态 | 建议下一步 |
-> |---------|---|---|---|---|------------|---------|
-> | add-user-auth | ✅ | ✅ | ✅ | ❌ | PENDING | `/opsx-task add-user-auth` |
-> | payment-refund | ✅ | ❌ | ❌ | ❌ | PENDING | `/opsx-spec payment-refund` |
-> | points-exchange | ✅ | ✅ | ✅ | ✅ | IMPLEMENTING | `/opsx-check points-exchange` |"
+规则：
+- 分组依据 `module`；中文组名来自 `modules.yaml`
+- 缺少 change-key/title/module 的存量 change 归入「未分类」
+- `module=cross` 时额外展示 `affected-modules`
 
 ### 4. 【交互引导】选择操作
 

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

@@ -54,13 +54,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 +81,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 +112,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/<name>/` 创建变更目录和 `.openspec.yaml`。
+此命令在 `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=.
+```
+
+写入 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 全局契约空模板引导
 
@@ -238,7 +264,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-task/SKILL.md

@@ -175,6 +175,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` 时执行：