kld-sdd 2.6.21 → 2.7.8

package/templates/skills/kld-sdd/opsx-consistency-check/scripts/scripts.cjs

@@ -0,0 +1,517 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * opsx-consistency-check 辅助脚本
+ *
+ * 封装 SKILL.md 中需要跨平台执行的命令（非 git 命令），
+ * 避免 node -e 单行命令的可读性和引号转义问题。
+ *
+ * 用法：
+ *   node scripts.cjs <command> [args...]
+ *
+ * 命令列表：
+ *   list-changes   [--spec-root=<路径>]   列出活跃变更（注册表优先：sdd.config.yaml 的 active_changes；
+ *                                         无注册表时降级扫描目录，排除 archive 和隐藏目录——与 hook 同源）
+ *   find-specs <change-name> [--spec-root=<路径>]
+ *                                         递归查找变更级 + 全局 spec.md 文件
+ *                                         （支持嵌套 specs/ 子目录与平铺 spec.md 两种结构）
+ *   clean-reports <change-dir>            清理指定 change 下所有旧报告文件（删除结果可见，失败退出 1）
+ *   file-hash <file>                      计算单个文件的 size + sha256
+ *   batch-hash [--files-from=<列表文件>] [--files=<逗号分隔列表>]
+ *                                         批量计算 size + sha256。输入优先级：
+ *                                         --files-from=（UTF-8 列表文件，每行一个路径，适合上百文件的大变更）
+ *                                         > --files=（逗号分隔，适合少量文件）> stdin（注意 PowerShell 管道编码问题）
+ *   grep-code <pattern> [dir] [--glob=<通配>] [-i]
+ *                                         跨平台内容搜索（Node 实现，IDE 搜索工具故障时的兜底）。
+ *                                         输出 相对路径:行号: 内容，最多 200 条后截断
+ *   prepare-report <change-dir> [--files-from=<列表文件>|--files=<csv>]
+ *                                         一体化命令：清理旧报告 + 批量哈希（可选）+ 输出本地时间，
+ *                                         单个 JSON 输出（cleaned/hashes/unreadable/timestamp），减少报告阶段往返。
+ *                                         不带 --files-from=/--files= 时跳过哈希（hashes 为空），
+ *                                         适用于哈希已由 --collect --hash 提供的场景；绝不读 stdin（防挂起）
+ *   now                                   输出当前本机本地时间（YYYY-MM-DD HH:mm:ss）
+ *
+ * spec 仓根解析（list-changes / find-specs 共用）：
+ *   --spec-root= 参数 > .sdd-spec-root 标记文件 > .sdd.yaml mono 的 spec_path
+ *   > cwd 有 openspec/ > .sdd-workspace.yaml 的 spec_path > 向上找父目录
+ *   单仓（.sdd.yaml layout: mono + .sdd-spec-root）与多仓（.sdd-workspace.yaml + .sdd-spec-root）
+ *   均自动解析，无需手动传 --spec-root。与权威实现 resolve-spec-root.cjs 策略对齐。
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+/**
+ * 解析 spec 仓根目录（含 openspec/ 的目录）。
+ * 解析顺序（与权威实现 resolve-spec-root.cjs 的 resolveSpecProjectRoot 对齐）：
+ * 1. --spec-root= 命令行参数（显式指定，验证 openspec/ 存在）
+ * 2. .sdd-spec-root 标记文件（cwd 及祖先目录向上遍历，读内容 resolve）
+ * 3. .sdd.yaml 且 layout: mono（cwd 及祖先目录，读 spec_path resolve）
+ * 4. cwd 下存在 openspec/ → cwd 即 spec 根（单仓场景，兼容现状）
+ * 5. cwd 或祖先目录存在 .sdd-workspace.yaml → 读 spec_path 解析（多仓场景）
+ * 6. 向上逐级父目录找 openspec/（兜底）
+ * 找不到返回 null（调用方报错退出，不静默）。
+ */
+function resolveSpecRoot() {
+  // 1. 显式参数
+  const argPrefix = '--spec-root=';
+  const arg = process.argv.find(a => a.startsWith(argPrefix));
+  if (arg) {
+    const p = path.resolve(arg.slice(argPrefix.length));
+    if (fs.existsSync(path.join(p, 'openspec'))) return p;
+    console.error(`ERROR: --spec-root=${arg.slice(argPrefix.length)} 下不存在 openspec/`);
+    process.exit(1);
+  }
+
+  // 2. .sdd-spec-root 标记文件（cwd 及祖先目录）— 与权威 resolveHint 对齐
+  const hinted = resolveSpecRootHint(process.cwd());
+  if (hinted) return hinted;
+
+  // 3. .sdd.yaml mono 布局（cwd 及祖先目录）— 与权威 isMonoLayout + resolveMonoSpecRoot 对齐
+  const monoRoot = resolveMonoSpecRootFrom(process.cwd());
+  if (monoRoot) return monoRoot;
+
+  // 4. cwd 即 spec 根
+  if (fs.existsSync(path.join(process.cwd(), 'openspec'))) return process.cwd();
+
+  // 5. .sdd-workspace.yaml 的 spec_path（cwd 及祖先目录）
+  let dir = process.cwd();
+  for (let i = 0; i < 10; i++) {
+    const wsYaml = path.join(dir, '.sdd-workspace.yaml');
+    if (fs.existsSync(wsYaml)) {
+      try {
+        const content = fs.readFileSync(wsYaml, 'utf8');
+        const m = /^spec_path:\s*(\S+)/m.exec(content);
+        if (m) {
+          const p = path.resolve(dir, m[1].replace(/["']/g, ''));
+          if (fs.existsSync(path.join(p, 'openspec'))) return p;
+        }
+      } catch { /* 继续兜底 */ }
+      break;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  // 6. 向上找 openspec/（兜底）
+  dir = process.cwd();
+  for (let i = 0; i < 10; i++) {
+    if (fs.existsSync(path.join(dir, 'openspec'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return null;
+}
+
+/**
+ * 从 dir 向上遍历找 .sdd-spec-root 标记文件。
+ * 读其内容作为相对路径，path.resolve 得到 spec 根；验证路径存在即返回。
+ * 与 resolve-spec-root.cjs 的 resolveHint 同策略。
+ */
+function resolveSpecRootHint(dir) {
+  let current = path.resolve(dir);
+  const root = path.parse(current).root;
+  for (;;) {
+    const hintPath = path.join(current, '.sdd-spec-root');
+    if (fs.existsSync(hintPath)) {
+      try {
+        const hint = fs.readFileSync(hintPath, 'utf8').trim();
+        if (hint) {
+          const resolved = path.resolve(current, hint);
+          if (fs.existsSync(resolved)) return resolved;
+        }
+      } catch { /* 忽略读取异常，继续兜底 */ }
+    }
+    if (current === root) break;
+    current = path.dirname(current);
+  }
+  return null;
+}
+
+/**
+ * 从 dir 向上遍历找 .sdd.yaml 且 layout: mono，读 spec_path resolve。
+ * 与 sdd-config.cjs 的 isMonoLayout + resolveMonoSpecRoot 同策略。
+ * 逐行去注释再匹配（与现有 parseActiveChangesRegistry / sdd-config.cjs 风格一致），
+ * 避免 `layout: mono# comment` 等边缘情况误匹配。
+ */
+function resolveMonoSpecRootFrom(dir) {
+  let current = path.resolve(dir);
+  const root = path.parse(current).root;
+  for (;;) {
+    const yamlPath = path.join(current, '.sdd.yaml');
+    if (fs.existsSync(yamlPath)) {
+      try {
+        const lines = fs.readFileSync(yamlPath, 'utf8').split(/\r?\n/);
+        let layout = null;
+        let specPathRel = null;
+        for (const raw of lines) {
+          const line = raw.replace(/#.*$/, '').trim();
+          if (!line) continue;
+          const layoutM = /^layout:\s*(.+?)\s*$/.exec(line);
+          if (layoutM) { layout = layoutM[1].replace(/["']/g, '').toLowerCase(); continue; }
+          const pathM = /^spec_path:\s*(.+?)\s*$/.exec(line);
+          if (pathM) { specPathRel = pathM[1].replace(/["']/g, ''); continue; }
+        }
+        if (layout === 'mono' && specPathRel) {
+          const p = path.resolve(current, specPathRel);
+          if (fs.existsSync(p)) return p;
+        }
+      } catch { /* 忽略，继续兜底 */ }
+      // 找到 .sdd.yaml 但非 mono 或解析失败，不再向上找（.sdd.yaml 是仓库级标记）
+      break;
+    }
+    if (current === root) break;
+    current = path.dirname(current);
+  }
+  return null;
+}
+
+// --- 活跃变更注册表解析（与 consistency-check-core.cjs parseActiveChangesFromYaml 同规则） ---
+function parseActiveChangesRegistry(specRoot) {
+  const configPath = path.join(specRoot, 'sdd.config.yaml');
+  if (!fs.existsSync(configPath)) return { keys: [], sawSection: false };
+  try {
+    const keys = [];
+    let inActive = false;
+    for (const raw of fs.readFileSync(configPath, 'utf8').split(/\r?\n/)) {
+      const line = raw.replace(/#.*$/, '').replace(/\s+$/, '');
+      if (!line.trim()) continue;
+      if (/^active_changes:\s*(\[\s*\])?\s*$/.test(line)) { inActive = true; continue; }
+      if (inActive) {
+        const m = /^\s+-\s+change-key:\s*(\S+)/.exec(line);
+        if (m) keys.push(m[1]);
+      }
+    }
+    return { keys, sawSection: inActive };
+  } catch {
+    return { keys: [], sawSection: false };
+  }
+}
+
+// --- list-changes ---
+function listChanges() {
+  const specRoot = resolveSpecRoot();
+  if (!specRoot) {
+    console.error('ERROR: 未找到 spec 仓根目录（含 openspec/）。可用 --spec-root=<路径> 显式指定');
+    process.exit(1);
+  }
+  // 1. 注册表优先（与 hook discoverActiveChanges 同源，避免两边发现结果不一致）
+  const { keys, sawSection } = parseActiveChangesRegistry(specRoot);
+  if (sawSection) {
+    if (keys.length) console.log(keys.join('\n'));
+    return;
+  }
+  // 2. 降级：目录扫描
+  const dir = path.join(specRoot, 'openspec', 'changes');
+  if (!fs.existsSync(dir)) {
+    process.exit(0);
+  }
+  const names = fs.readdirSync(dir)
+    .filter(n => !n.startsWith('.') && n !== 'archive')
+    .filter(n => fs.statSync(path.join(dir, n)).isDirectory());
+  if (names.length) console.log(names.join('\n'));
+}
+
+// --- find-specs ---
+function findSpecs(changeName) {
+  const specRoot = resolveSpecRoot();
+  if (!specRoot) {
+    console.error('ERROR: 未找到 spec 仓根目录（含 openspec/）。可用 --spec-root=<路径> 显式指定');
+    process.exit(1);
+  }
+  const results = [];
+  // 平铺结构：changes/<name>/spec.md（部分项目变更目录下无 specs/ 子目录，spec.md 直接平铺）
+  const flat = path.join(specRoot, 'openspec', 'changes', changeName, 'spec.md');
+  if (fs.existsSync(flat)) results.push(flat);
+  const targets = [
+    path.join(specRoot, 'openspec', 'changes', changeName, 'specs'),
+    path.join(specRoot, 'openspec', 'specs'),
+  ];
+  for (const target of targets) {
+    if (!fs.existsSync(target)) continue;
+    walkDir(target).forEach(f => {
+      if (f.endsWith('spec.md') && !results.includes(f)) results.push(f);
+    });
+  }
+  if (results.length) console.log(results.join('\n'));
+}
+
+function walkDir(dir) {
+  const results = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkDir(full));
+    } else {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+// --- clean-reports ---
+function cleanReports(changeDir) {
+  const files = [
+    'consistency-report.md',
+    'consistency-report-result.json',
+  ];
+  let deleted = 0;
+  for (const f of files) {
+    const fp = path.join(changeDir, f);
+    try {
+      if (fs.existsSync(fp)) {
+        fs.unlinkSync(fp);
+        console.log('deleted: ' + fp);
+        deleted++;
+      }
+    } catch (e) {
+      // 失败不静默：删除失败会导致后续 Write 要求先 Read（多一轮工具调用），必须可见
+      console.error('ERROR: failed to delete ' + fp + ': ' + e.message);
+      process.exit(1);
+    }
+  }
+  if (!deleted) console.log('no stale reports to clean');
+}
+
+// --- 行尾归一化（与 consistency-check-core.cjs normalizeEolLf 保持一致） ---
+// 报告生成与 hook 校验均对内容做 LF 归一化后再算 size/sha256，
+// 消除 autocrlf=true 下 CRLF→LF→CRLF 往返不完美、混合行尾等导致的哈希不一致。
+function normalizeEolLf(buf) {
+  return Buffer.from(buf.toString('binary').replace(/\r\n/g, '\n'), 'binary');
+}
+
+// --- file-hash ---
+function fileHash(file) {
+  const buf = normalizeEolLf(fs.readFileSync(file));
+  console.log(JSON.stringify({
+    size: buf.length,
+    sha256: crypto.createHash('sha256').update(buf).digest('hex'),
+  }));
+}
+
+// --- 哈希输入解析（batch-hash / prepare-report 共用） ---
+// 输入优先级：--files-from= > --files= > stdin。
+// - --files-from=：UTF-8 列表文件（每行一个路径），适合上百文件的大变更——同时绕开
+//   stdin 管道编码问题（PowerShell 默认 UTF-16）与命令行长度上限（cmd.exe 8191 字符 / CreateProcess 32KB）
+// - --files=：逗号分隔，适合少量文件（命令行长度上限约 8K 字符，约 60~80 个典型路径）
+// - stdin 兜底：交互式终端（TTY）下无重定向输入会永久阻塞（等待 EOF），直接报错退出而非挂起
+function readHashInput() {
+  const filesFromPrefix = '--files-from=';
+  const filesFromArg = process.argv.find(a => a.startsWith(filesFromPrefix));
+  const filesPrefix = '--files=';
+  const filesArg = process.argv.find(a => a.startsWith(filesPrefix));
+  if (filesFromArg) {
+    return fs.readFileSync(filesFromArg.slice(filesFromPrefix.length), 'utf8')
+      .split(/\r?\n/).map(s => s.trim()).filter(Boolean);
+  }
+  if (filesArg) {
+    return filesArg.slice(filesPrefix.length).split(',').map(s => s.trim()).filter(Boolean);
+  }
+  if (process.stdin.isTTY) {
+    console.error('ERROR: 未提供 --files-from= 或 --files=，且 stdin 为交互式终端（等待管道输入会永久挂起）。');
+    console.error('用法: node scripts.cjs batch-hash --files-from=<列表文件>  或  --files=<逗号分隔路径>');
+    process.exit(1);
+  }
+  return fs.readFileSync(0, 'utf8').split(/\r?\n/).map(s => s.trim()).filter(Boolean);
+}
+
+// --- batch-hash ---
+function batchHash() {
+  const input = readHashInput();
+  for (const f of input) {
+    const buf = normalizeEolLf(fs.readFileSync(f));
+    console.log(JSON.stringify({
+      path: f,
+      size: buf.length,
+      sha256: crypto.createHash('sha256').update(buf).digest('hex'),
+    }));
+  }
+}
+
+// --- 本地时间（now / prepare-report 共用） ---
+function nowString() {
+  const d = new Date();
+  const p = n => String(n).padStart(2, '0');
+  return d.getFullYear() + '-' + p(d.getMonth() + 1) + '-' + p(d.getDate()) +
+    ' ' + p(d.getHours()) + ':' + p(d.getMinutes()) + ':' + p(d.getSeconds());
+}
+
+// --- now ---
+function now() {
+  console.log(nowString());
+}
+
+// --- grep-code（跨平台内容搜索，IDE 搜索工具故障时的兜底） ---
+const GREP_SKIP_DIRS = new Set([
+  'node_modules', 'dist', 'build', 'target', 'out', 'vendor',
+  '.git', '.svn', '.hg', '.idea', '.vscode',
+]);
+const GREP_BINARY_EXT_RE = /\.(png|jpe?g|gif|bmp|ico|webp|pdf|zip|gz|tgz|tar|jar|class|woff2?|ttf|eot|mp4|mp3|avi|mov|xlsx?|docx?|pptx?|bin|so|dll|exe)$/i;
+const GREP_MAX_MATCHES = 200;
+const GREP_MAX_FILE_BYTES = 2 * 1024 * 1024;
+
+function globToRegExp(glob) {
+  const escaped = glob
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*/g, '\u0000')
+    .replace(/\*/g, '[^/]*')
+    .replace(/\u0000/g, '.*')
+    .replace(/\?/g, '.');
+  return new RegExp('^' + escaped + '$', 'i');
+}
+
+function grepCode() {
+  const pattern = process.argv[3];
+  if (!pattern) {
+    console.error('ERROR: 缺少搜索模式。用法: node scripts.cjs grep-code <pattern> [dir] [--glob=<通配>] [-i]');
+    process.exit(1);
+  }
+  let dir = process.argv[4] ? path.resolve(process.argv[4]) : process.cwd();
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+    console.error('ERROR: 搜索目录不存在: ' + dir);
+    process.exit(1);
+  }
+  const globPrefix = '--glob=';
+  const globArg = process.argv.find(a => a.startsWith(globPrefix));
+  const globRe = globArg ? globToRegExp(globArg.slice(globPrefix.length)) : null;
+  const globHasSlash = globArg ? globArg.slice(globPrefix.length).includes('/') : false;
+  const caseInsensitive = process.argv.includes('-i') || process.argv.includes('--ignore-case');
+  let re;
+  try {
+    re = new RegExp(pattern, caseInsensitive ? 'i' : '');
+  } catch (e) {
+    console.error('ERROR: 非法正则: ' + e.message);
+    process.exit(1);
+  }
+
+  const out = [];
+  let truncated = false;
+  const walk = (d, relBase) => {
+    if (truncated) return;
+    for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+      if (truncated) return;
+      const full = path.join(d, entry.name);
+      const rel = relBase ? relBase + '/' + entry.name : entry.name;
+      if (entry.isDirectory()) {
+        if (!GREP_SKIP_DIRS.has(entry.name) && !entry.name.startsWith('.')) walk(full, rel);
+        continue;
+      }
+      if (GREP_BINARY_EXT_RE.test(entry.name)) continue;
+      if (globRe && !globRe.test(globHasSlash ? rel : entry.name)) continue;
+      let stat;
+      try { stat = fs.statSync(full); } catch { continue; }
+      if (stat.size > GREP_MAX_FILE_BYTES) continue;
+      let content;
+      try { content = fs.readFileSync(full, 'utf8'); } catch { continue; }
+      if (content.includes('\u0000')) continue; // 二进制内容跳过
+      const lines = content.split(/\r?\n/);
+      for (let i = 0; i < lines.length; i++) {
+        if (re.test(lines[i])) {
+          out.push(rel + ':' + (i + 1) + ': ' + lines[i].trim());
+          if (out.length >= GREP_MAX_MATCHES) { truncated = true; break; }
+        }
+      }
+    }
+  };
+  walk(dir, '');
+  if (out.length) console.log(out.join('\n'));
+  else console.log('no matches');
+  if (truncated) console.error('NOTE: 结果超过 ' + GREP_MAX_MATCHES + ' 条已截断，请缩小搜索范围（加 --glob= 或指定更精确目录）');
+}
+
+// --- prepare-report（一体化：清理旧报告 + 批量哈希 + 本地时间，单 JSON 输出减少往返） ---
+function prepareReport(changeDir) {
+  if (!changeDir) {
+    console.error('ERROR: 缺少 change 目录。用法: node scripts.cjs prepare-report <change-dir> [--files-from=<列表文件>|--files=<csv>]');
+    process.exit(1);
+  }
+  // 相对路径解析：报告固定落在 spec 根下（hook findReportJson 只认 specRoot/openspec/changes/<name>/），
+  // 相对路径优先按 spec 根解析——cwd 可能是项目根/代码仓根而非 spec 根（多仓/子目录布局），
+  // 按 cwd 解析会清错目录（曾实际发生：清理未作用于真实 change 目录，AI 被迫读源码自查浪费多轮）。
+  // 绝对路径原样使用；spec 根解析失败时回退 cwd（向后兼容）。
+  let dir = path.resolve(changeDir);
+  if (!path.isAbsolute(changeDir)) {
+    const specRoot = resolveSpecRoot();
+    if (specRoot) dir = path.resolve(specRoot, changeDir);
+  }
+  // 1. 清理旧报告（失败不静默：残留旧报告会导致后续 Write 要求先 Read）
+  const reportFiles = ['consistency-report.md', 'consistency-report-result.json'];
+  const cleaned = [];
+  for (const f of reportFiles) {
+    const fp = path.join(dir, f);
+    try {
+      if (fs.existsSync(fp)) {
+        fs.unlinkSync(fp);
+        cleaned.push(fp.replace(/\\/g, '/'));
+      }
+    } catch (e) {
+      console.error('ERROR: failed to delete ' + fp + ': ' + e.message);
+      process.exit(1);
+    }
+  }
+  // 2. 批量哈希（可选）：仅当显式提供 --files-from=/--files= 时执行，绝不读 stdin（防交互式终端挂起）。
+  //    无输入源 = "只清理 + 取时间戳"合法模式（哈希已由 --collect --hash 提供时无需重复传入），hashes 输出空数组
+  const hashes = [];
+  const unreadable = [];
+  const hasHashInput = process.argv.some(a => a.startsWith('--files-from=') || a.startsWith('--files='));
+  if (hasHashInput) {
+    for (const f of readHashInput()) {
+      try {
+        const buf = normalizeEolLf(fs.readFileSync(f));
+        hashes.push({
+          path: f,
+          size: buf.length,
+          sha256: crypto.createHash('sha256').update(buf).digest('hex'),
+        });
+      } catch {
+        unreadable.push(f);
+      }
+    }
+  }
+  // 3. 单 JSON 输出：cleaned + hashes + timestamp + 实际目录一次拿全
+  //    changeDir 带回解析后的绝对路径，调用方无需再自行推导报告落点（写报告直接用它）
+  console.log(JSON.stringify({
+    changeDir: dir.replace(/\\/g, '/'),
+    cleaned,
+    hashes,
+    unreadable,
+    timestamp: nowString(),
+  }, null, 2));
+}
+
+// --- main ---
+const command = process.argv[2];
+switch (command) {
+  case 'list-changes':
+    listChanges();
+    break;
+  case 'find-specs':
+    findSpecs(process.argv[3]);
+    break;
+  case 'clean-reports':
+    cleanReports(process.argv[3]);
+    break;
+  case 'file-hash':
+    fileHash(process.argv[3]);
+    break;
+  case 'batch-hash':
+    batchHash();
+    break;
+  case 'now':
+    now();
+    break;
+  case 'grep-code':
+    grepCode();
+    break;
+  case 'prepare-report':
+    prepareReport(process.argv[3]);
+    break;
+  default:
+    console.error('Usage: node scripts.cjs <list-changes|find-specs|clean-reports|file-hash|batch-hash|now|grep-code|prepare-report> [args...]');
+    process.exit(1);
+}

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

@@ -14,6 +14,8 @@ allowed-tools:
   - Edit
 ---
 
+> **执行方式**：先读 [交互与执行契约](../opsx-propose/interaction-policy.md)；同一会话已读则复用。用户已授权连续处理时按范围推进，不重复索要阶段口令；只请求单阶段时完成即停。
+
 你是一个 SDD（Specification-Driven Development）技术设计专家。激活本技能后，你将引导用户为**单一 Capability** 创建 **design.md** 文档。
 
 > **⚠️ 阶段边界约束**
@@ -21,20 +23,12 @@ allowed-tools:
 > 当前处于 **Design（设计）阶段**：
 > - ✅ **允许**：创建/编辑 design.md 文档、读取代码/文档作为上下文分析
 > - ❌ **禁止**：创建/修改任何代码文件、执行代码生成、运行测试
-> - ⛔ **单阶段原则**：完成 design.md 后**必须立即停止**，等待用户主动触发下一阶段
+> - **执行范围**：单阶段请求完成即停；已授权连续处理则按交互契约加载下一阶段，check 通过后方可进入 apply，不能超出授权范围。
 >
 > 代码实现将在 `/opsx-apply` 阶段进行。
-> **完成本阶段后，绝对禁止自动继续执行 task 等后续阶段。**
 > 阶段边界自检见 `./checklist.md`「阶段边界⛔」。
 
-> **KB 上下文**：设计时可参考历史设计决策。
-> 1. 检查 proposal.md frontmatter `kb-status`：若 `degraded(by-user-choice)` → 跳过 KB，仅用本地上下文。
-> 2. 否则运行 KB 就绪检查：
-> ```bash
-> node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" --check-only
-> ```
-> - `"available": true` → 若需查历史设计参考，先 `Read` `opsx-ontology-query/phase-2-during.md` §1
-> - `"available": false` → **KB 不可用不阻塞 design 流程**，仅跳过历史设计参考查询
+> **KB 上下文**：仅在需要历史设计参考时查询，优先复用本轮已有结果；不逐阶段执行 `--check-only`。未配置、断连或无权限时记录原因，继续本地流程，不重复询问配置。
 
 > **⚠️ 渐进式上下文加载原则**
 >
@@ -43,7 +37,7 @@ allowed-tools:
 > - **输出路径**（Full 模式）：`changes/<name>/specs/<capability>/design.md`
 > - **输入路径**（Simple 模式）：`changes/<name>/spec.md`
 > - **输出路径**（Simple 模式）：`changes/<name>/design.md`
-> - ⛔ **隔离红线**：绝对禁止跨目录读取同级其他 Capability 的 spec 或 design（Full 模式）
+> - ⛔ **隔离红线**：默认聚焦当前 Capability；为核对已声明依赖可读取相关 Capability 契约并注明来源，不全量加载或混写其他能力。
 
 > **🖥️ 跨平台执行规则**
 > - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
@@ -111,7 +105,7 @@ openspec list
 
 ### 3. 渐进式上下文加载
 
-> ⛔ 必须严格按 overview.md → proposal.md → 当前 capability spec.md 顺序加载；隔离红线：禁止读取其他 Capability 的文档。**完整层级图见 `./reference.md`「§3 渐进式上下文加载层级图」**。
+> ⛔ 必须严格按 overview.md → proposal.md → 当前 capability spec.md 顺序加载；隔离红线：默认聚焦当前 Capability；为核对已声明依赖可读取相关 Capability 契约并注明来源，不全量加载或混写其他能力。**完整层级图见 `./reference.md`「§3 渐进式上下文加载层级图」**。
 
 ### 4. 【关键步骤】读取本地模板文件
 
@@ -157,23 +151,9 @@ design.md 中若使用 version 正则约束（如格式校验 `^\d+\.\d+\.\d+$`
 
 > 写入文档前逐项确认，完整 7 项自检清单见 `./checklist.md`「§7 质量红线自检」。如有任意一项未满足，重新生成对应章节，直至全部通过。
 
-### 8. 【交互引导】确认文档并输出结果
-
-生成文档后，向用户展示概要：
-> "已生成 design.md，概要如下：
-> - Capability：[name]
-> - 核心模块：[模块列表]
-> - 设计模式：[使用的设计模式]
-> - 预估复杂度：[高/中/低]
->
-> 请确认：
-> - A. 确认无误，继续创建 tasks.md
-> - B. 需要修改设计方案
-> - C. 补充更多代码上下文"
+### 7. 展示设计差异并继续
 
-最终输出：
-- 文档路径
-- 下一步提示："运行 `/opsx-task <name> <capability>` 创建任务拆解文档"
+展示关键设计决定、依赖、验收和未决问题。Agent 能确定的缺失字段或依赖先自行修复；实质业务歧义再集中询问。已授权连续处理时加载下一阶段 task。单阶段请求完成即停，不重复询问模式或后续阶段口令。
 
 ---
 
@@ -194,11 +174,11 @@ design.md 中若使用 version 正则约束（如格式校验 `^\d+\.\d+\.\d+$`
 
 - **必须以 `openspec-templates/design.md` 为模板基准**。
 - **⛔ 渐进式加载**：严格按 overview.md → proposal.md → spec.md 顺序加载。
-- **⛔ 隔离红线**：绝对禁止跨目录读取同级其他 Capability 的 spec 或 design。
+- **⛔ 隔离红线**：默认聚焦当前 Capability；为核对已声明依赖可读取相关 Capability 契约并注明来源，不全量加载或混写其他能力。
 - design.md 聚焦【How】，是 spec.md → tasks.md 的桥梁；必须 100% 覆盖 spec.md 定义的需求项。
 - 代码锚点必须具体到类/方法级别。
 - **⛔ 阶段边界**：禁止执行任何代码创建/修改操作。
-- **⛔ 单阶段原则**：完成 design.md 后必须立即停止。仅提示用户下一步可运行 `/opsx-task`，绝对禁止自动执行 task 等后续阶段。每个阶段必须由用户主动触发。
+- **执行范围**：单阶段请求完成即停；已授权连续处理则按交互契约加载下一阶段，check 通过后方可进入 apply，不能超出授权范围。
 
 ---
 

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

@@ -13,9 +13,8 @@ description: opsx-design 的阶段强制检查点与自检清单。仅在执行
 
 - [ ] ✅ 允许：创建/编辑 design.md 文档、读取代码/文档作为上下文分析
 - [ ] ❌ 禁止：创建/修改任何代码文件、执行代码生成、运行测试
-- [ ] ⛔ 单阶段原则：完成 design.md 后必须立即停止，等待用户主动触发下一阶段
+- [ ] **执行范围**：单阶段请求完成即停；已授权连续处理则按交互契约加载下一阶段，check 通过后方可进入 apply，不能超出授权范围。
 - [ ] 代码实现将在 `/opsx-apply` 阶段进行
-- [ ] ⛔ 完成本阶段后绝对禁止自动继续执行 task 等后续阶段
 
 ---
 
@@ -39,9 +38,9 @@ description: opsx-design 的阶段强制检查点与自检清单。仅在执行
 
 - [ ] 必须以 `openspec-templates/design.md` 为模板基准
 - [ ] ⛔ **渐进式加载**：严格按 overview.md → proposal.md → spec.md 顺序加载（层级图见 `./reference.md`「§3」）
-- [ ] ⛔ **隔离红线**：绝对禁止跨目录读取同级其他 Capability 的 spec 或 design
+- [ ] ⛔ **隔离红线**：默认聚焦当前 Capability；为核对已声明依赖可读取相关 Capability 契约并注明来源，不全量加载或混写其他能力。
 - [ ] design.md 聚焦【How】，是 spec.md → tasks.md 的桥梁
 - [ ] 必须 100% 覆盖 spec.md 定义的需求项
 - [ ] 代码锚点必须具体到类/方法级别
 - [ ] ⛔ **阶段边界**：禁止执行任何代码创建/修改操作
-- [ ] ⛔ **单阶段原则**：完成 design.md 后必须立即停止；仅提示用户下一步可运行 `/opsx-task`，绝对禁止自动执行 task 等后续阶段。每个阶段必须由用户主动触发。
+- [ ] **执行范围**：单阶段请求完成即停；已授权连续处理则按交互契约加载下一阶段，check 通过后方可进入 apply，不能超出授权范围。

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

@@ -40,5 +40,5 @@ description: opsx-design 的详细模板：telemetry 命令、上下文类型表
 第 3 层：精准打击（仅当前 Capability）
   → changes/<name>/specs/<capability>/spec.md
 
-⛔ 隔离红线：禁止读取其他 Capability 的文档！
+⛔ 隔离红线：默认聚焦当前 Capability；为核对已声明依赖可读取相关 Capability 契约并注明来源，不全量加载或混写其他能力。
 ```