kld-sdd 2.4.16 → 2.4.18

package/templates/hooks/claude/hooks/sdd-apply-test-gate.cjs

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+/**
+ * SDD Apply Test Gate Hook
+ *
+ * 当 proposal 选择单元测试策略（test-strategy: tdd | impl-first）时，
+ * 在 apply 收尾前校验是否已有真实测试执行证据；缺失则阻断并提示模型执行测试。
+ *
+ * 触发点：
+ *   - PreToolUse(Bash): apply-worktree-finish（非 --record-base）、log.cjs end（apply 阶段）
+ *   - Stop: 存在活跃 apply 阶段且即将结束会话
+ *
+ * 退出码：0 放行 | 2 阻断（stdout JSON decision:block）
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+function readStdin() {
+  try {
+    return fs.readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function parseInput(raw) {
+  try {
+    return JSON.parse(raw || '{}');
+  } catch {
+    return {};
+  }
+}
+
+function hasTelemetryCli(dir) {
+  return fs.existsSync(path.join(dir, 'skywalk-sdd', 'log.cjs')) ||
+    fs.existsSync(path.join(dir, 'skywalk-sdd', 'log.js'));
+}
+
+function findProjectRoot(startDir) {
+  if (!startDir) return '';
+  let current = path.resolve(startDir);
+  for (let i = 0; i < 25; i++) {
+    if (hasTelemetryCli(current)) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return '';
+    current = parent;
+  }
+  return '';
+}
+
+function getProjectRoot(input) {
+  const toolInput = input.tool_input || input.toolInput || {};
+  const candidates = [
+    toolInput.cwd,
+    input.cwd,
+    input.project_root,
+    process.env.CLAUDE_PROJECT_DIR,
+    process.env.PWD,
+    process.cwd(),
+  ].filter(Boolean);
+  for (const dir of candidates) {
+    const root = findProjectRoot(dir);
+    if (root) return root;
+  }
+  return process.cwd();
+}
+
+function safeChangeName(name) {
+  if (!name) return '';
+  return String(name)
+    .toLowerCase()
+    .replace(/[\s_]+/g, '-')
+    .replace(/[^a-z0-9一-鿿\-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+function findActiveApplyStage(projectRoot) {
+  const stateDir = path.join(projectRoot, 'skywalk-sdd', 'state');
+  if (!fs.existsSync(stateDir)) return null;
+
+  let latest = null;
+  for (const file of fs.readdirSync(stateDir).filter((f) => f.endsWith('.json'))) {
+    try {
+      const data = JSON.parse(fs.readFileSync(path.join(stateDir, file), 'utf8'));
+      const event = data.event || null;
+      if (event && event.command === 'apply') {
+        if (!latest || new Date(event.timestamp) > new Date(latest.timestamp)) {
+          latest = event;
+        }
+      }
+    } catch {
+      // skip
+    }
+  }
+  return latest;
+}
+
+function findProposalPath(projectRoot, changeName) {
+  const candidates = [
+    path.join(projectRoot, 'openspec', 'changes', changeName, 'proposal.md'),
+    path.join(projectRoot, 'changes', changeName, 'proposal.md'),
+  ];
+  for (const p of candidates) {
+    if (fs.existsSync(p)) return p;
+  }
+  const safe = safeChangeName(changeName);
+  if (safe && safe !== changeName) {
+    return findProposalPath(projectRoot, safe);
+  }
+  return null;
+}
+
+function readTestStrategy(projectRoot, changeName) {
+  const proposalPath = findProposalPath(projectRoot, changeName);
+  if (!proposalPath) return null;
+  try {
+    const content = fs.readFileSync(proposalPath, 'utf8');
+    const fm = content.match(/^---\s*[\r\n]+([\s\S]*?)[\r\n]+---/);
+    if (!fm) return null;
+    const m = fm[1].match(/^\s*test-strategy:\s*["']?([a-z-]+)["']?\s*$/im);
+    return m ? m[1].trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+function requiresUnitTests(strategy) {
+  return strategy === 'tdd' || strategy === 'impl-first';
+}
+
+function isRealTestDetails(testResults) {
+  if (!testResults || typeof testResults !== 'object') return false;
+  const command = String(testResults.command || '').trim();
+  if (!command) return false;
+  const passed = Number(testResults.passed);
+  const failed = Number(testResults.failed);
+  const duration = Number(testResults.duration_ms);
+  if (Number.isFinite(passed) && passed > 0) return true;
+  if (Number.isFinite(failed) && failed > 0) return true;
+  if (Number.isFinite(duration) && duration > 0) return true;
+  return false;
+}
+
+function loadChangeEvents(projectRoot, changeName) {
+  const safe = safeChangeName(changeName);
+  const dir = path.join(projectRoot, 'skywalk-sdd', 'events', safe);
+  if (!fs.existsSync(dir)) return [];
+
+  const events = [];
+  for (const file of fs.readdirSync(dir).filter((f) => f.endsWith('.jsonl'))) {
+    try {
+      const lines = fs.readFileSync(path.join(dir, file), 'utf8').split('\n').filter(Boolean);
+      for (const line of lines) {
+        try {
+          events.push(JSON.parse(line));
+        } catch {
+          // skip
+        }
+      }
+    } catch {
+      // skip
+    }
+  }
+  return events;
+}
+
+function hasRealTestExecution(projectRoot, changeName, capability, sinceTimestamp) {
+  const since = sinceTimestamp ? new Date(sinceTimestamp).getTime() : 0;
+  const events = loadChangeEvents(projectRoot, changeName);
+
+  for (const event of events) {
+    const ts = new Date(event.timestamp || 0).getTime();
+    if (since && ts < since) continue;
+
+    if (event.type === 'stage_end' && event.command === 'test' &&
+        (event.result === 'success' || event.result === 'failure')) {
+      return { kind: 'opsx-test', event };
+    }
+
+    if (event.type === 'test_result') {
+      const tr = event.details && event.details.test_results;
+      if (isRealTestDetails(tr)) {
+        return { kind: 'test_result', event };
+      }
+    }
+
+    if (event.type === 'task_update' && (event.command === 'apply' || !event.command)) {
+      const tr = event.details && event.details.test_results;
+      if (isRealTestDetails(tr)) {
+        if (!capability || !event.capability || event.capability === capability) {
+          return { kind: 'task_update', event };
+        }
+      }
+    }
+  }
+  return null;
+}
+
+function isApplyCompletionBash(command) {
+  const cmd = String(command || '');
+  if (/apply-worktree-finish\.cjs/.test(cmd) && !/--record-base/.test(cmd)) {
+    return true;
+  }
+  if (/(?:skywalk-sdd\/)?log\.cjs\s+end\b/.test(cmd)) {
+    return true;
+  }
+  return false;
+}
+
+function block(decision, reason, extra) {
+  console.log(JSON.stringify({ decision, reason, ...extra }));
+  process.exit(2);
+}
+
+function recordWarning(projectRoot, applyEvent, code, message) {
+  const logPath = path.join(projectRoot, 'skywalk-sdd', 'log.cjs');
+  if (!fs.existsSync(logPath)) return;
+  try {
+    const args = [
+      logPath,
+      'record',
+      '--type=telemetry_warning',
+      '--command=apply',
+      `--project=${projectRoot}`,
+      `--change=${applyEvent.change || 'general'}`,
+      '--agent=claude-code',
+      '--source=claude-hook',
+      '--result=partial',
+      `--summary=${message}`,
+      `--details-json=${JSON.stringify({ warning: code, test_strategy: applyEvent.test_strategy })}`,
+    ];
+    if (applyEvent.capability) args.push(`--capability=${applyEvent.capability}`);
+    if (applyEvent.session_id) args.push(`--session-id=${applyEvent.session_id}`);
+    execFileSync('node', args, { cwd: projectRoot, stdio: 'ignore' });
+  } catch {
+    // ignore
+  }
+}
+
+function buildReason(strategy, changeName, capability) {
+  const cap = capability ? ` / ${capability}` : '';
+  const strict = strategy === 'tdd';
+  const lines = [
+    `[SDD Apply Test Gate] 变更 ${changeName}${cap} 的 test-strategy=${strategy}，但尚未检测到真实单元测试执行记录。`,
+    '',
+    '请先在本项目根目录（或 apply worktree）执行单元测试，例如：',
+    '  npm test / pnpm test / pytest / go test ./... / cargo test',
+    '',
+    '执行后应产生以下任一 telemetry 证据：',
+    '  - skywalk-sdd 事件 test_result（含实际 command 与 passed/failed/duration）',
+    '  - task_update 中 test_results 非空占位',
+    '  - 或运行 /opsx-test 完成 test 阶段',
+    '',
+    strict
+      ? 'tdd 策略：测试未执行前不得结束 apply 或执行 apply-worktree-finish。'
+      : 'impl-first 策略：实现后须补跑测试并确认通过，再结束 apply。',
+    '',
+    '完成后可重试当前操作。',
+  ];
+  return lines.join('\n');
+}
+
+function shouldGate(projectRoot, applyEvent) {
+  const strategy = readTestStrategy(projectRoot, applyEvent.change);
+  if (!requiresUnitTests(strategy)) {
+    return null;
+  }
+  const evidence = hasRealTestExecution(
+    projectRoot,
+    applyEvent.change,
+    applyEvent.capability,
+    applyEvent.timestamp
+  );
+  if (evidence) {
+    return null;
+  }
+  return { strategy, changeName: applyEvent.change, capability: applyEvent.capability };
+}
+
+// ── 主逻辑 ─────────────────────────────────────────────
+
+const input = parseInput(readStdin());
+const projectRoot = getProjectRoot(input);
+const toolName = String(input.tool_name || input.toolName || '');
+const toolInput = input.tool_input || input.toolInput || {};
+const command = String(toolInput.command || '');
+
+const activeApply = findActiveApplyStage(projectRoot);
+if (!activeApply) {
+  process.exit(0);
+}
+
+const bashGate = toolName === 'Bash' && isApplyCompletionBash(command);
+const stopGate = !toolName || toolName === 'Stop';
+
+if (!bashGate && !stopGate) {
+  process.exit(0);
+}
+
+const gate = shouldGate(projectRoot, activeApply);
+if (!gate) {
+  process.exit(0);
+}
+
+const reason = buildReason(gate.strategy, gate.changeName, gate.capability);
+recordWarning(projectRoot, { ...activeApply, test_strategy: gate.strategy }, 'apply_test_missing', 'Apply test gate blocked: no unit test evidence');
+
+block('block', reason, {
+  test_strategy: gate.strategy,
+  change: gate.changeName,
+  capability: gate.capability,
+});

package/templates/hooks/claude/hooks/sdd-skill-apply-gate.cjs

@@ -0,0 +1,268 @@
+/**
+ * sdd-skill-apply-gate.cjs
+ *
+ * PreToolUse(Skill) 门禁 —— 在 opsx-apply Skill 被调用的瞬间阻断，不再等到 Write/Edit 阶段。
+ *
+ * 门禁体系：
+ *   L1: sdd-skill-apply-gate  (PreToolUse/Skill) ← 本文件 — check 前置
+ *   L2: sdd-apply-gate        (PreToolUse/Write|Edit)
+ *   L3: SKILL.md Step 1.2     (Skill 自检)
+ *   L4: sdd-apply-test-gate   (PreToolUse/Bash + Stop) — apply 后单元测试真实执行
+ *
+ * 判定逻辑：
+ *   - 非 opsx-apply 调用 → 放行
+ *   - 提供了 change-name → 检查该变更是否已完成 check，未完成则阻断
+ *   - 未提供 change-name → 扫描所有变更，只要有一个已完成 check 则放行，否则阻断
+ *
+ * 退出码约定（遵循 Claude Code hook 规范）：
+ *   0  → 放行（stdout 可为空，或输出允许决策 JSON）
+ *   2  → 阻断（stdout 需包含 { decision: "block", reason: "..." }）
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// 工具函数
+// ---------------------------------------------------------------------------
+
+/** 读取 stdin（与 sdd-prompt.cjs 保持一致的简洁实现） */
+function readStdin() {
+  try {
+    return fs.readFileSync(0, 'utf8');
+  } catch (_) {
+    return '';
+  }
+}
+
+/** 安全解析 hook 输入 JSON */
+function parseInput(raw) {
+  if (!raw || !raw.trim()) return null;
+  try {
+    return JSON.parse(raw);
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * 向上查找项目根目录 —— 以 skywalk-sdd/log.cjs 文件存在为标志
+ */
+function findProjectRoot(startDir) {
+  let dir = startDir;
+  for (let i = 0; i < 20; i++) {
+    if (fs.existsSync(path.join(dir, 'skywalk-sdd', 'log.cjs'))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/** 从 hook 输入中提取项目根目录 */
+function getProjectRoot(input) {
+  if (!input) return null;
+  const cwd = input.cwd || process.cwd();
+  return findProjectRoot(cwd);
+}
+
+/**
+ * 规范化变更名称 —— 与 openspec/changes/ 下的目录名保持一致
+ * 规则：
+ *   - 转小写
+ *   - 特殊字符 → 连字符
+ *   - 中文保留原样
+ */
+function safeChangeName(name) {
+  if (!name) return '';
+  return name
+    .toLowerCase()
+    .replace(/[\s_]+/g, '-')
+    .replace(/[^a-z0-9一-鿿\-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+/**
+ * 判断指定变更是否已完成 check 阶段。
+ *
+ * 检测方式：读取 skywalk-sdd/events/<changeName>/ 下的 JSONL 事件文件，
+ * 查找 stage_end + command=check + result=success 事件。
+ */
+function hasCompletedCheck(projectRoot, changeName) {
+  if (!projectRoot || !changeName) return false;
+  const eventsDir = path.join(projectRoot, 'skywalk-sdd', 'events', changeName);
+  if (!fs.existsSync(eventsDir)) return false;
+
+  try {
+    const files = fs.readdirSync(eventsDir).filter(f => f.endsWith('.jsonl'));
+    for (const file of files) {
+      const filePath = path.join(eventsDir, file);
+      const content = fs.readFileSync(filePath, 'utf8');
+      const lines = content.split('\n').filter(l => l.trim());
+      for (const line of lines) {
+        try {
+          const evt = JSON.parse(line);
+          if (
+            evt.type === 'stage_end' &&
+            evt.command === 'check' &&
+            (evt.result === 'success' || evt.result === 'partial')
+          ) {
+            return true;
+          }
+        } catch (_) { /* skip malformed lines */ }
+      }
+    }
+  } catch (_) {
+    return false;
+  }
+  return false;
+}
+
+/**
+ * 扫描 openspec/changes/ 下所有已通过 check 的变更。
+ * 返回已通过 check 的变更名称列表。
+ */
+function getPassedChanges(projectRoot) {
+  if (!projectRoot) return [];
+  const changesDir = path.join(projectRoot, 'openspec', 'changes');
+  if (!fs.existsSync(changesDir)) return [];
+
+  const passed = [];
+  try {
+    const entries = fs.readdirSync(changesDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith('.')) continue;
+      if (entry.name === 'archive') continue;
+      if (hasCompletedCheck(projectRoot, entry.name)) {
+        passed.push(entry.name);
+      }
+    }
+  } catch (_) { /* ignore */ }
+  return passed;
+}
+
+/**
+ * 判断给定的 tool_input 字符串是否为 opsx-apply Skill 调用。
+ *
+ * Skill 的 tool_input 格式为 JSON 字符串: {"skill": "opsx-apply", "args": "..."}
+ */
+function isOpsxApplySkill(toolInput) {
+  if (!toolInput) return false;
+  let input;
+  if (typeof toolInput === 'string') {
+    try { input = JSON.parse(toolInput); } catch (_) { return false; }
+  } else {
+    input = toolInput;
+  }
+  if (!input || typeof input !== 'object') return false;
+  const skill = input.skill || '';
+  return skill === 'opsx-apply';
+}
+
+/**
+ * 从 tool_input 中提取 change-name。
+ * opsx-apply 的 args 格式为: "change-name" 或 "--change change-name"
+ */
+function extractChangeName(toolInput) {
+  if (!toolInput) return null;
+  let input;
+  if (typeof toolInput === 'string') {
+    try { input = JSON.parse(toolInput); } catch (_) { return null; }
+  } else {
+    input = toolInput;
+  }
+  if (!input || typeof input !== 'object') return null;
+
+  const args = input.args || '';
+  if (!args.trim()) return null;
+
+  // args 可能是 "change-name" 或 "--change change-name ..." 格式
+  const trimmed = args.trim();
+
+  // 尝试 --change <name> 格式
+  const changeFlagMatch = trimmed.match(/^--change\s+(.+)$/);
+  if (changeFlagMatch) {
+    return safeChangeName(changeFlagMatch[1].trim().split(/\s+/)[0]);
+  }
+
+  // 否则整个 args 的第一个 token 就是 change-name
+  const firstToken = trimmed.split(/\s+/)[0];
+  return safeChangeName(firstToken);
+}
+
+// ---------------------------------------------------------------------------
+// 主逻辑
+// ---------------------------------------------------------------------------
+
+function main() {
+  const raw = readStdin();
+  const input = parseInput(raw);
+
+  if (!input) {
+    // 无法解析输入，保守放行（避免阻断非 opsx-apply 操作）
+    process.exit(0);
+  }
+
+  // --- 仅处理 Skill 工具调用 ---
+  const toolName = input.tool_name || '';
+  if (toolName !== 'Skill') {
+    // 非 Skill 调用，放行
+    process.exit(0);
+  }
+
+  // --- 确认是否为 opsx-apply ---
+  const toolInput = input.tool_input;
+  if (!isOpsxApplySkill(toolInput)) {
+    // 不是 opsx-apply skill，放行
+    process.exit(0);
+  }
+
+  // --- 确定项目根目录 ---
+  const projectRoot = getProjectRoot(input);
+  if (!projectRoot) {
+    // 找不到项目根目录，说明不在 kld-sdd 项目中，放行
+    process.exit(0);
+  }
+
+  // --- 提取 change-name ---
+  const changeName = extractChangeName(toolInput);
+
+  if (changeName) {
+    // 场景 A：指定了 change-name → 精确检查
+    if (hasCompletedCheck(projectRoot, changeName)) {
+      process.exit(0); // 已通过 check，放行
+    }
+    // 未通过 check，阻断
+    const reason = `变更 "${changeName}" 尚未完成 check 阶段。请先执行 /opsx-check ${changeName} 完成检查后再 apply。`;
+    console.log(JSON.stringify({ decision: 'block', reason }));
+    process.exit(2);
+  } else {
+    // 场景 B：未指定 change-name → 扫描所有变更
+    const passedChanges = getPassedChanges(projectRoot);
+
+    if (passedChanges.length === 0) {
+      const reason = '当前项目没有任何变更已完成 check 阶段。请先执行 /opsx-check <change-name> 完成检查后再 apply。';
+      console.log(JSON.stringify({ decision: 'block', reason }));
+      process.exit(2);
+    }
+
+    // 有已通过 check 的变更，放行（后续由 Skill 自身引导用户选择）
+    if (passedChanges.length === 1) {
+      const msg = `检测到已通过 check 的变更: "${passedChanges[0]}"，允许进入 apply。`;
+      console.log(JSON.stringify({ decision: 'allow', reason: msg }));
+    } else {
+      const msg = `检测到 ${passedChanges.length} 个已通过 check 的变更: ${passedChanges.join(', ')}，允许进入 apply。`;
+      console.log(JSON.stringify({ decision: 'allow', reason: msg }));
+    }
+    process.exit(0);
+  }
+}
+
+// --- 入口 ---
+main();

package/templates/hooks/claude/settings.json

@@ -11,12 +11,25 @@
       }
     ],
     "PreToolUse": [
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/sdd-skill-apply-gate.cjs\""
+          }
+        ]
+      },
       {
         "matcher": "Bash",
         "hooks": [
           {
             "type": "command",
             "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/sdd-pre-tool.cjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/sdd-apply-test-gate.cjs\""
           }
         ]
       },
@@ -44,6 +57,10 @@
     "Stop": [
       {
         "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/sdd-apply-test-gate.cjs\""
+          },
           {
             "type": "command",
             "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/sdd-stop.cjs\""