kld-sdd 2.4.19 → 2.5.1

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

@@ -0,0 +1,395 @@
+#!/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');
+const core = require('./hook-gate-core.cjs');
+
+const {
+  readStdin,
+  parseHookInput,
+  normalizeHookInput,
+  getProjectRoot,
+  safeChangeName,
+  findActiveApplyStage,
+  blockWithReason,
+} = core;
+
+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) {
+  blockWithReason(reason, { decision, ...extra });
+}
+
+function recordWarning(projectRoot, applyEvent, code, message, taskIds) {
+  const logPath = path.join(projectRoot, 'skywalk-sdd', 'log.cjs');
+  if (!fs.existsSync(logPath)) {
+    // Y8 修复：log.cjs 缺失时 stderr 提示（本 repo 无 log.cjs 属预期——脚手架部署时 deployTelemetryDataDir 复制 index.cjs→log.cjs）
+    try { console.error(`[sdd-apply-test-gate] log.cjs 不存在（${logPath}），telemetry_warning 未记录；确认 deployTelemetryDataDir 已执行`); } catch {}
+    return;
+  }
+  try {
+    // T1.5b(v3): task_update_reuse 写入复用 task_ids，供 E4(A3) 扣分识别
+    const details = { warning: code, test_strategy: applyEvent.test_strategy };
+    if (Array.isArray(taskIds) && taskIds.length > 0) details.task_ids = taskIds;
+    const args = [
+      logPath,
+      'record',
+      '--type=telemetry_warning',
+      '--command=apply',
+      `--project=${projectRoot}`,
+      `--change=${applyEvent.change || 'general'}`,
+      '--agent=codebuddy',
+      '--source=codebuddy-hook',
+      '--result=partial',
+      `--summary=${message}`,
+      `--details-json=${JSON.stringify(details)}`,
+    ];
+    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 };
+}
+
+// ── T1.1: task_update 复用检测（不阻断，仅记 warning） ──
+/**
+ * 检测同一 change 的 implementation task_update 是否复用同一次测试结果。
+ * 判定：同 session_id + 同 test_results 三元组(passed+failed+duration_ms) 的 group 内 >1 条（不再要求时间戳相邻）。
+ * 测试确实跑过，只是 task_update 记录不实 → 记 telemetry_warning(task_update_reuse)，不阻断。
+ * 返回 { reused, groups: [{ duration_ms, fingerprint, session_id, task_ids }] }
+ */
+function detectReusedTestResults(events) {
+  const taskUpdates = (events || []).filter((e) =>
+    e && e.type === 'task_update' &&
+    e.details && e.details.test_results &&
+    isRealTestDetails(e.details.test_results)
+  );
+  const bySession = new Map();
+  for (const e of taskUpdates) {
+    const sid = e.session_id || '_no_session_';
+    if (!bySession.has(sid)) bySession.set(sid, []);
+    bySession.get(sid).push(e);
+  }
+  const groups = [];
+  let reused = false;
+  for (const [, group] of bySession) {
+    const byFingerprint = new Map();
+    for (const e of group) {
+      const tr = e.details.test_results;
+      const passed = Number(tr.passed);
+      const failed = Number(tr.failed);
+      const dur = Number(tr.duration_ms);
+      if (!Number.isFinite(dur)) continue;
+      const fp = `${passed}|${failed}|${dur}`;
+      if (!byFingerprint.has(fp)) byFingerprint.set(fp, []);
+      byFingerprint.get(fp).push(e);
+    }
+    for (const [fp, evs] of byFingerprint) {
+      if (evs.length < 2) continue;
+      const sorted = evs.slice().sort((a, b) => new Date(a.timestamp || 0) - new Date(b.timestamp || 0));
+      // T1.5(v3): 去掉 <5s 相邻限制 — 同 session + 同三元组即复用，无论时间间隔
+      // todo-cli 真实场景：实现任务与验证任务间隔 15-17s，<5s 阈值漏检 3/4 组
+      reused = true;
+      const first = sorted[0];
+      groups.push({
+        duration_ms: Number(first.details.test_results.duration_ms),
+        fingerprint: fp,
+        session_id: first.session_id || null,
+        task_ids: sorted.map((e) => e.task_id || e.event_id).filter(Boolean),
+      });
+    }
+  }
+  return { reused, groups };
+}
+
+/** T1.6: 检测本阶段是否有失败/门禁拦截但无 process_note 过程记录。
+ *  Y4 修复：when 参数过滤时间窗口（仅检测 sinceTimestamp 后的事件），避免 change 级误报。
+ *  返回 { gap, hasFailure, hasGateBlock, hasProcessNote } */
+function detectProcessNoteGap(events, sinceTimestamp) {
+  const evs = events || [];
+  const filtered = sinceTimestamp ? evs.filter(e => new Date(e.timestamp || 0).getTime() >= new Date(sinceTimestamp).getTime()) : evs;
+  const stageEnds = filtered.filter((e) => e.type === 'stage_end');
+  const hasFailure = stageEnds.some((e) => e.result === 'failure' || e.result === 'partial');
+  const hasGateBlock = filtered.some((e) =>
+    e.type === 'telemetry_warning' && e.details && e.details.warning === 'apply_test_missing'
+  );
+  const hasProcessNote = filtered.some((e) => e.type === 'process_note');
+  const gap = (hasFailure || hasGateBlock) && !hasProcessNote;
+  return { gap, hasFailure, hasGateBlock, hasProcessNote };
+}
+
+/** B2(v3): 检测 tdd 策略下 apply 阶段是否缺失"红灯"（失败的测试结果）。
+ *  TDD 节奏要求测试骨架先 RED（failed>0）再实现转 GREEN；若 apply 阶段有真实测试信号
+ *  但全部 failed===0，说明骨架可能未经 RED 验证即标记完成 → 记 telemetry_warning(tdd_red_missing)，不阻断。
+ *  不复用 isRealTestDetails（其要求 command 非空，会漏掉无 command 的骨架 test_results）。
+ *  返回 { missing, hasRed, signalCount } */
+function detectMissingTddRed(events, sinceTimestamp) {
+  const evs = events || [];
+  const filtered = sinceTimestamp ? evs.filter(e => new Date(e.timestamp || 0).getTime() >= new Date(sinceTimestamp).getTime()) : evs;
+  let signalCount = 0;
+  let hasRed = false;
+  for (const e of filtered) {
+    const tr = e && e.details && (e.details.test_results || e.details.test);
+    if (!tr || typeof tr !== 'object') continue;
+    const passed = Number(tr.passed);
+    const failed = Number(tr.failed);
+    const dur = Number(tr.duration_ms);
+    const isReal = (Number.isFinite(passed) && passed > 0)
+      || (Number.isFinite(failed) && failed > 0)
+      || (Number.isFinite(dur) && dur > 0);
+    if (!isReal) continue;
+    signalCount++;
+    if (Number.isFinite(failed) && failed > 0) hasRed = true;
+  }
+  if (signalCount === 0) return { missing: false, hasRed: false, signalCount: 0, reason: 'no-real-test-signals' };
+  return { missing: !hasRed, hasRed, signalCount };
+}
+
+/** 是否已存在某 code 的 telemetry_warning（去重，避免每次 hook 触发都重复记录） */
+function hasExistingWarning(events, code) {
+  return (events || []).some((e) =>
+    e.type === 'telemetry_warning' && e.details && e.details.warning === code
+  );
+}
+
+// ── 主逻辑（仅直接执行时运行；被 require 时跳过，便于单元测试） ──
+if (require.main === module) {
+  const parsed = parseHookInput(readStdin(), { strict: true });
+  if (!parsed.ok) {
+    blockWithReason(parsed.error);
+  }
+  const input = normalizeHookInput(parsed.input);
+  const projectRoot = getProjectRoot(input, 'codebuddy');
+  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);
+  }
+
+  // 非阻断警告检测（T1.1 task_update 复用 / T1.6 process_note 缺失）：放行但记录 warning
+  try {
+    const warningEvents = loadChangeEvents(projectRoot, activeApply.change);
+    const warningCtx = { ...activeApply, test_strategy: readTestStrategy(projectRoot, activeApply.change) };
+    const reuse = detectReusedTestResults(warningEvents);
+    if (reuse.reused && !hasExistingWarning(warningEvents, 'task_update_reuse')) {
+      const taskCount = reuse.groups.reduce((s, g) => s + g.task_ids.length, 0);
+      const reusedTaskIds = reuse.groups.flatMap((g) => g.task_ids).filter(Boolean);
+      recordWarning(projectRoot, warningCtx, 'task_update_reuse',
+        `检测到 ${reuse.groups.length} 组 task_update 复用同一次测试结果（共 ${taskCount} 条），测试确实跑过但记录不实`,
+        reusedTaskIds);
+    }
+    const noteGap = detectProcessNoteGap(warningEvents, activeApply.timestamp);
+    if (noteGap.gap && !hasExistingWarning(warningEvents, 'process_note_missing')) {
+      recordWarning(projectRoot, warningCtx, 'process_note_missing',
+        '本阶段存在失败/门禁拦截但无 process_note 过程记录，建议补记');
+    }
+    // B2(v3): tdd 策略下 apply 阶段无红灯（失败 test_result）→ 软警告，不阻断
+    if (warningCtx.test_strategy === 'tdd') {
+      const redGap = detectMissingTddRed(warningEvents, activeApply.timestamp);
+      if (redGap.missing && !hasExistingWarning(warningEvents, 'tdd_red_missing')) {
+        recordWarning(projectRoot, warningCtx, 'tdd_red_missing',
+          'tdd 策略下 apply 阶段未检测到失败的测试结果（红灯），测试骨架可能未经 RED 验证即标记完成');
+      }
+    }
+  } catch {
+    // 警告检测失败不阻断主流程
+  }
+
+  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,
+  });
+}
+
+module.exports = {
+  detectReusedTestResults,
+  detectProcessNoteGap,
+  detectMissingTddRed,
+  hasExistingWarning,
+  isRealTestDetails,
+  requiresUnitTests,
+};

package/templates/hooks/codebuddy/hooks/sdd-post-tool.cjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const core = require('./hook-gate-core.cjs');
+
+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 { result: response.exit_code === 0 ? 'success' : 'failure', exit_code_known: true };
+  }
+  if (typeof response.exitCode === 'number') {
+    return { result: response.exitCode === 0 ? 'success' : 'failure', exit_code_known: true };
+  }
+  if (typeof response.success === 'boolean') {
+    return { result: response.success ? 'success' : 'failure', exit_code_known: true };
+  }
+  const out = String(response.stdout || response.stderr || '');
+  if (/BUILD FAILED|error TS\d+|ERR_/i.test(out)) {
+    return { result: 'failure', exit_code_known: false };
+  }
+  return { result: 'partial', exit_code_known: false };
+}
+
+function inferRecord(command) {
+  if (/\b(log\.cjs|log\.js)\s+record\b/.test(command)) return null;
+  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, exitCodeKnown, input, runner) {
+  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 toolInput = (input && (input.tool_input || input.toolInput)) || {};
+  const toolResponse = (input && (input.tool_response || input.toolResponse)) || {};
+  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;
+    details.build_results.exit_code_known = Boolean(exitCodeKnown);
+    const durationMs = typeof toolResponse.duration_ms === 'number' ? toolResponse.duration_ms : null;
+    details.build_results.duration_ms = durationMs;
+    details.build_results.duration_known = durationMs !== null;
+  }
+
+  const args = [
+    logCli,
+    'record',
+    `--type=${record.type}`,
+    `--command=${toolInput.command || activeStage.command || activeStage.stage || 'unknown'}`,
+    `--project=${projectRoot}`,
+    `--change=${activeStage.change || 'general'}`,
+    `--agent=${activeStage.agent_type || 'codebuddy'}`,
+    '--source=codebuddy-hook',
+    `--result=${result}`,
+    `--summary=CodeBuddy 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}`);
+  const run = runner || ((a) => execFileSync('node', a, { cwd: projectRoot, stdio: 'ignore' }));
+  run(args);
+}
+
+if (require.main === module) {
+  const parsed = core.parseHookInput(core.readStdin(), { strict: false });
+  const input = core.normalizeHookInput(parsed.input || {});
+  const toolInput = input.tool_input || {};
+  const command = String(toolInput.command || input.command || '');
+  const record = inferRecord(command);
+  if (!record) process.exit(0);
+
+  const projectRoot = core.getProjectRoot(input, 'codebuddy');
+  const activeStage = latestActiveStage(projectRoot);
+  if (!activeStage || !activeStage.change || activeStage.change === 'general') {
+    process.exit(0);
+  }
+
+  try {
+    const inferred = inferResult(input);
+    recordTelemetry(projectRoot, activeStage, record, inferred.result, inferred.exit_code_known, input);
+  } catch {
+    process.exit(0);
+  }
+}
+
+module.exports = { inferResult, inferRecord, recordTelemetry, latestActiveStage };

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

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+'use strict';
+
+const core = require('./hook-gate-core.cjs');
+
+const parsed = core.parseHookInput(core.readStdin(), { strict: true });
+if (!parsed.ok) {
+  core.blockWithReason(parsed.error);
+}
+
+const input = core.normalizeHookInput(parsed.input);
+const result = core.evaluatePreToolDangerGate(input);
+if (result.action === 'block') {
+  core.blockWithReason(result.reason);
+}
+core.allowExit();

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

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const core = require('./hook-gate-core.cjs');
+
+const parsed = core.parseHookInput(core.readStdin(), { strict: false });
+const input = core.normalizeHookInput(parsed.input || {});
+
+const prompt = input.prompt || input.message || input.user_prompt || '';
+if (!/\/opsx[:|-]/.test(prompt)) {
+  process.exit(0);
+}
+
+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 projectRoot = core.getProjectRoot(input, 'codebuddy');
+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'));
+process.exit(0);

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

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+'use strict';
+
+const core = require('./hook-gate-core.cjs');
+
+const parsed = core.parseHookInput(core.readStdin(), { strict: true });
+if (!parsed.ok) {
+  core.blockWithReason(parsed.error);
+}
+
+const input = core.normalizeHookInput(parsed.input);
+const result = core.evaluateSkillApplyGate(input, 'codebuddy');
+if (result.action === 'block') {
+  core.blockWithReason(result.reason);
+}
+core.allowExit(result.reason ? { reason: result.reason } : undefined);

package/templates/hooks/codebuddy/hooks/sdd-stop.cjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const core = require('./hook-gate-core.cjs');
+
+const parsed = core.parseHookInput(core.readStdin(), { strict: false });
+const input = core.normalizeHookInput(parsed.input || {});
+
+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);
+}
+
+function writeWarning(projectRoot, event) {
+  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 args = [
+    logCli,
+    'record',
+    '--type=telemetry_warning',
+    `--command=${event.command || event.stage || 'unknown'}`,
+    `--project=${projectRoot}`,
+    `--change=${event.change || 'general'}`,
+    `--agent=${event.agent_type || 'codebuddy'}`,
+    '--source=codebuddy-hook',
+    '--result=partial',
+    '--summary=CodeBuddy hook detected an open SDD stage at stop',
+    `--details-json=${JSON.stringify({ warning: 'open_stage_at_stop', event_id: event.event_id })}`,
+  ];
+  if (event.capability) args.push(`--capability=${event.capability}`);
+  if (event.session_id) args.push(`--session-id=${event.session_id}`);
+  execFileSync('node', args, { cwd: projectRoot, stdio: 'ignore' });
+}
+
+const projectRoot = core.getProjectRoot(input, 'codebuddy');
+const activeStages = readActiveStages(projectRoot);
+if (activeStages.length === 0) {
+  process.exit(0);
+}
+
+for (const event of activeStages) {
+  try {
+    writeWarning(projectRoot, event);
+  } catch {
+    // ignore
+  }
+}
+
+console.log([
+  'SDD Telemetry warning: open stage(s) detected.',
+  ...activeStages.map((event) => `- ${event.change || 'general'}:${event.command || event.stage || 'unknown'} event_id=${event.event_id}`),
+  'Run skywalk-sdd/log.cjs end before closing the OPSX stage, or explicitly mark it partial/failure.',
+].join('\n'));
+process.exit(0);