@hunterzheng/kld-sdd 2.4.19

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-post-tool.cjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+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 findTelemetryRoot(startDir) {
+  if (!startDir) return '';
+
+  let current = path.resolve(startDir);
+  while (true) {
+    if (hasTelemetryCli(current)) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return '';
+    current = parent;
+  }
+}
+
+function findProjectRoot(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 = findTelemetryRoot(dir);
+    if (root) return root;
+  }
+  return process.cwd();
+}
+
+function latestActiveStage(projectRoot) {
+  const stateDir = path.join(projectRoot, 'skywalk-sdd', 'state');
+  if (!fs.existsSync(stateDir)) return null;
+  return fs.readdirSync(stateDir)
+    .filter(file => file.endsWith('.json'))
+    .map(file => {
+      try {
+        const data = JSON.parse(fs.readFileSync(path.join(stateDir, file), 'utf8'));
+        return data.event || null;
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime())[0] || null;
+}
+
+function inferResult(input) {
+  const response = input.tool_response || input.toolResponse || {};
+  if (typeof response.exit_code === 'number') return response.exit_code === 0 ? 'success' : 'failure';
+  if (typeof response.exitCode === 'number') return response.exitCode === 0 ? 'success' : 'failure';
+  if (typeof response.success === 'boolean') return response.success ? 'success' : 'failure';
+  return 'partial';
+}
+
+function inferRecord(command) {
+  if (/\b(npm|pnpm|yarn)\s+(test|run\s+test)\b|\bpytest\b|\bmvn\b.*\btest\b|\bgo\s+test\b|\bcargo\s+test\b/i.test(command)) {
+    return {
+      type: 'test_result',
+      detailsKey: 'test_results',
+      details: { command, passed: 0, failed: 0, skipped: 0, coverage: null, duration_ms: null },
+    };
+  }
+  if (/\b(npm|pnpm|yarn)\s+(run\s+build|build)\b|\btsc\b|\bmvn\b.*\bcompile\b|\bgradle\b.*\bcompile|\bgo\s+build\b|\bcargo\s+check\b/i.test(command)) {
+    return {
+      type: 'build_result',
+      detailsKey: 'build_results',
+      details: { command, success: null, duration_ms: null, error_count: null },
+    };
+  }
+  return null;
+}
+
+function recordTelemetry(projectRoot, activeStage, record, result) {
+  const logPath = path.join(projectRoot, 'skywalk-sdd', 'log.cjs');
+  const legacyLogPath = path.join(projectRoot, 'skywalk-sdd', 'log.js');
+  const logCli = fs.existsSync(logPath) ? logPath : legacyLogPath;
+  if (!fs.existsSync(logCli)) return;
+
+  const details = { [record.detailsKey]: { ...record.details } };
+  if (record.type === 'build_result') {
+    details.build_results.success = result === 'success';
+    details.build_results.error_count = result === 'success' ? 0 : null;
+  }
+
+  const args = [
+    logCli,
+    'record',
+    `--type=${record.type}`,
+    `--command=${activeStage.command || activeStage.stage || 'unknown'}`,
+    `--project=${projectRoot}`,
+    `--change=${activeStage.change || 'general'}`,
+    `--agent=${activeStage.agent_type || 'claude-code'}`,
+    '--source=claude-hook',
+    `--result=${result}`,
+    `--summary=Claude hook captured ${record.type}`,
+    `--details-json=${JSON.stringify(details)}`,
+  ];
+  if (activeStage.capability) args.push(`--capability=${activeStage.capability}`);
+  if (activeStage.task_id) args.push(`--task-id=${activeStage.task_id}`);
+  if (activeStage.session_id) args.push(`--session-id=${activeStage.session_id}`);
+  execFileSync('node', args, { cwd: projectRoot, stdio: 'ignore' });
+}
+
+const input = parseInput(readStdin());
+const toolInput = input.tool_input || input.toolInput || {};
+const command = String(toolInput.command || input.command || '');
+const record = inferRecord(command);
+if (!record) process.exit(0);
+
+const projectRoot = findProjectRoot(input);
+const activeStage = latestActiveStage(projectRoot);
+if (!activeStage || !activeStage.change || activeStage.change === 'general') {
+  process.exit(0);
+}
+
+try {
+  recordTelemetry(projectRoot, activeStage, record, inferResult(input));
+} catch {
+  process.exit(0);
+}

package/templates/hooks/claude/hooks/sdd-pre-tool.cjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+const fs = require('fs');
+
+function readStdin() {
+  try {
+    return fs.readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function parseInput(raw) {
+  try {
+    return JSON.parse(raw || '{}');
+  } catch {
+    return {};
+  }
+}
+
+const input = parseInput(readStdin());
+const toolInput = input.tool_input || input.toolInput || {};
+const command = String(toolInput.command || input.command || '');
+
+const dangerousPatterns = [
+  /\brm\s+-rf\b/i,
+  /\brmdir\s+\/s\b/i,
+  /\bdel\s+\/[fsq]/i,
+  /\bgit\s+reset\s+--hard\b/i,
+  /\bgit\s+clean\s+-fdx\b/i,
+  /\bRemove-Item\b.*\b-Recurse\b.*\b-Force\b/i,
+];
+
+if (dangerousPatterns.some(pattern => pattern.test(command))) {
+  console.log(JSON.stringify({
+    decision: 'block',
+    reason: 'Blocked by SDD hook: destructive command requires explicit user approval.',
+  }));
+  process.exit(2);
+}
+
+process.exit(0);

package/templates/hooks/claude/hooks/sdd-prompt.cjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+
+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 findTelemetryRoot(startDir) {
+  if (!startDir) return '';
+
+  let current = path.resolve(startDir);
+  while (true) {
+    if (hasTelemetryCli(current)) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return '';
+    current = parent;
+  }
+}
+
+function findProjectRoot(input) {
+  const candidates = [
+    input.cwd,
+    input.project_root,
+    process.env.CLAUDE_PROJECT_DIR,
+    process.env.PWD,
+    process.cwd(),
+  ].filter(Boolean);
+  for (const dir of candidates) {
+    const root = findTelemetryRoot(dir);
+    if (root) return root;
+  }
+  return process.cwd();
+}
+
+function readActiveStages(projectRoot) {
+  const stateDir = path.join(projectRoot, 'skywalk-sdd', 'state');
+  if (!fs.existsSync(stateDir)) return [];
+  return fs.readdirSync(stateDir)
+    .filter(file => file.endsWith('.json'))
+    .map(file => {
+      try {
+        return JSON.parse(fs.readFileSync(path.join(stateDir, file), 'utf8')).event;
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+const input = parseInput(readStdin());
+const prompt = input.prompt || input.message || input.user_prompt || '';
+if (!/\/opsx[:|-]/.test(prompt)) process.exit(0);
+
+const projectRoot = findProjectRoot(input);
+const activeStages = readActiveStages(projectRoot)
+  .map(event => `${event.change || 'general'}:${event.command || event.stage || 'unknown'}`)
+  .join(', ');
+
+const lines = [
+  'SDD Telemetry reminder:',
+  '- Run skywalk-sdd/log.cjs start before the OPSX stage work begins.',
+  '- Run skywalk-sdd/log.cjs end before stopping the stage.',
+  '- Hooks are only an enhancement; OPSX skill instructions remain authoritative.',
+];
+
+if (activeStages) {
+  lines.push(`- Active stage state: ${activeStages}`);
+}
+
+console.log(lines.join('\n'));