kld-sdd 2.6.21 → 2.7.8

package/templates/git-hooks/hooks.config

@@ -0,0 +1,38 @@
+# KLD SDD Hook 插件配置文件
+# 每行一个脚本名，空行和 # 开头的行会被忽略
+# 注释某行 = 禁用该插件，取消注释 = 启用该插件
+
+[commit-msg]
+# 自动写入 Spec-Change / Spec-Revision Trailer 到 commit message
+commit-msg-sdd-trailer.cjs
+
+[pre-commit]
+# 检查 tasks.md 中是否有未完成的归档任务
+pre-commit-sdd-check.cjs
+# 检查 Spec 一致性校验报告（置信度、过期、人工确认等）
+pre-commit-consistency-check.cjs
+
+[pre-push]
+# 运行 doctor 完整诊断（配置、Trailer 协议、活动变更等）
+pre-push-sdd-check.cjs
+# 检查待推送范围的一致性报告（存在性、过期；置信度由 pre-commit 负责）
+pre-push-consistency-check.cjs
+
+[consistency]
+# 一致性校验的业务代码扩展名
+# 语义：整行替换式配置，以本清单为准
+# Go / Kotlin 等项目按需修改：
+# 注意：新增语言的语言特定构建文件（如 Rust 的 build.rs）不在内置排除规则内，需自行确认
+# 本配置同时被 git hook（isBusinessCode）与 opsx-consistency-check skill 读取，单一来源
+# ⚠️ 清空本行 = 不拦截任何业务代码文件（一致性门禁对提交/推送失效，仅剩报告存在性/过期检查）
+business_code_exts = .java,.ts,.tsx,.js,.jsx,.vue,.py
+
+# 一致性校验模式（项目级默认值，环境变量优先覆盖；三个互斥，只能启用一个）
+# 环境变量：SDD_SKIP_CONSISTENCY_CHECK=1 / SDD_STRICT_CONSISTENCY=1 / SDD_WARN_ONLY=1
+# - skip = 1：跳过一致性校验（紧急绕过，如 hotfix 仓不需要 spec 校验）
+# - strict = 1：严格模式，medium 置信度也阻止提交（仅 pre-commit 生效，pre-push 忽略）
+# - warn_only = 1：仅告警不拦截（CI 调试期，问题全列但不阻断提交/推送）
+# 三项均不设或均设为 0 = 默认模式（low 阻止，medium 放行，high 放行）
+skip = 0
+strict = 0
+warn_only = 0

package/templates/git-hooks/pre-commit

@@ -1,28 +1,27 @@
 #!/bin/sh
 # KLD SDD Pre-Commit Hook
-# 远程引用 spec 仓 skywalk-sdd/git-hooks/ 下的 .cjs 脚本
-# 兼容单仓库/多仓库/单仓mono布局
+# 在下方 SCRIPTS 列表中声明要加载的 .cjs 脚本
+# 删除某行 = 禁用该插件
 # marker: KLD SDD quality gate
 
-# 从 hook 所在目录推算 git 根目录
-hook_dir="$(cd "$(dirname "$0")" && pwd)"
-git_dir="$(dirname "$hook_dir")"
-git_root="$(dirname "$git_dir")"
-
+# Git supplies the working tree context; this also supports worktrees and core.hooksPath.
+git_root=$(git rev-parse --show-toplevel 2>/dev/null) || {
+  echo "[SDD] 无法定位当前 Git 工作区"
+  exit 1
+}
 hooks_dir=""
-
-# 方法1: git config sdd.specPath（多仓布局：spec 是独立 clone）
-spec_path=$(git config --local sdd.specPath 2>/dev/null)
-if [ -n "$spec_path" ] && [ -d "$spec_path/skywalk-sdd/git-hooks" ]; then
+spec_path=$(git -C "$git_root" config --local sdd.specPath 2>/dev/null)
+if [ -n "$spec_path" ]; then
+  case "$spec_path" in /*) ;; *) spec_path="$git_root/$spec_path" ;; esac
   hooks_dir="$spec_path/skywalk-sdd/git-hooks"
+elif [ -f "$git_root/.sdd-spec-root" ]; then
+  spec_rel=$(head -1 "$git_root/.sdd-spec-root" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+  case "$spec_rel" in /*) hooks_dir="$spec_rel/skywalk-sdd/git-hooks" ;; *) hooks_dir="$git_root/$spec_rel/skywalk-sdd/git-hooks" ;; esac
 fi
-
-# 方法2: .sdd-spec-root（单仓 mono 布局：skywalk-sdd 在 spec 包裹包子目录内）
-if [ -z "$hooks_dir" ] && [ -f "$git_root/.sdd-spec-root" ]; then
-  spec_rel=$(cat "$git_root/.sdd-spec-root" | head -1 | tr -d '[:space:]')
-  if [ -n "$spec_rel" ] && [ -d "$git_root/$spec_rel/skywalk-sdd/git-hooks" ]; then
-    hooks_dir="$git_root/$spec_rel/skywalk-sdd/git-hooks"
-  fi
+if [ -n "$hooks_dir" ] && [ ! -d "$hooks_dir" ]; then
+  echo "[SDD] 已配置的 Spec 路径失效：$hooks_dir"
+  echo "[SDD] 请恢复 Spec 仓，或修正 sdd.specPath / .sdd-spec-root 后重试"
+  exit 1
 fi
 
 # 方法3: 从 git 根向上搜索 skywalk-sdd/git-hooks（spec 仓本身或父级）
@@ -38,20 +37,56 @@ if [ -z "$hooks_dir" ]; then
 fi
 
 if [ -z "$hooks_dir" ]; then
-  echo "[SDD] 未找到 spec 仓的 skywalk-sdd/git-hooks 目录，跳过 pre-commit 检查"
+  echo "[SDD] 未找到 spec 仓的 skywalk-sdd/git-hooks 目录，跳过 pre-commit"
   exit 0
 fi
 
 echo "[SDD] 执行提交前检查..."
 
-# 1. tasks.md 完成度检查
-if [ -f "$hooks_dir/pre-commit-sdd-check.cjs" ]; then
-  node "$hooks_dir/pre-commit-sdd-check.cjs" --project="$git_root" "$@" || exit 1
+# 从配置文件读取插件列表
+config_file="$hooks_dir/hooks.config"
+if [ ! -f "$config_file" ]; then
+  echo "[SDD] ️  配置文件不存在：hooks.config，使用默认插件"
+  SCRIPTS="pre-commit-sdd-check.cjs pre-commit-consistency-check.cjs"
+else
+  # 读取 [pre-commit] 段落的配置
+  in_section=0
+  SCRIPTS=""
+  CR=$(printf '\r')
+  while IFS= read -r line; do
+    line=${line%"$CR"}
+    case "$line" in
+      "[pre-commit]") in_section=1 ;;
+      "["*) in_section=0 ;;
+      "#"*|"") ;;
+      *)
+        if [ "$in_section" -eq 1 ]; then
+          SCRIPTS="$SCRIPTS $line"
+        fi
+        ;;
+    esac
+  done < "$config_file"
 fi
 
-# 2. 代码-spec 一致性检查
-if [ -f "$hooks_dir/pre-commit-consistency-check.cjs" ]; then
-  node "$hooks_dir/pre-commit-consistency-check.cjs" --project="$git_root" "$@" || exit 1
-fi
+executed=0
+failed=0
+for script_name in $SCRIPTS; do
+  script="$hooks_dir/$script_name"
+  if [ ! -f "$script" ]; then
+    echo "[SDD] ❌ 已配置的插件不存在：$script_name"
+    failed=$((failed + 1))
+    continue
+  fi
+  executed=$((executed + 1))
+  echo "[SDD] 执行 pre-commit 插件：$script_name"
+  node "$script" --project="$git_root" "$@" || failed=$((failed + 1))
+done
 
-echo "[SDD] ✅ 所有 pre-commit 检查通过"
+if [ "$failed" -gt 0 ]; then
+  echo "[SDD] ❌ 共执行 $executed 个 pre-commit 插件，$failed 个失败"
+  exit 1
+elif [ "$executed" -eq 0 ]; then
+  echo "[SDD] 配置已禁用 pre-commit 插件"
+else
+  echo "[SDD] ✅ 共执行 $executed 个 pre-commit 插件，全部通过"
+fi

package/templates/git-hooks/pre-commit-consistency-check.cjs

@@ -2,347 +2,44 @@
 /**
  * pre-commit-consistency-check.cjs
  *
- * Pre-commit 门禁：检查活跃变更的 Spec 一致性校验报告。
- * - 默认：缺少报告 / confidence=low → 阻止提交；strict 模式下 medium 也阻止
+ * Pre-commit 门禁：检查本次提交 diff 涉及的 Spec 一致性校验报告。
+ * - diff 驱动：仅检查 diff 文件与报告 coveredFiles 有交集的 change，无关 change 跳过
+ * - 报告存在性：活跃 change 无报告 → 阻止提交
+ * - 报告过期：代码在报告生成后被修改 → 阻止提交
+ * - 置信度门禁：confidence=low → 阻止提交；strict 模式下 medium 也阻止
  *
  * 通过环境变量控制：
  * - SDD_SKIP_CONSISTENCY_CHECK=1 → 跳过校验
  * - SDD_STRICT_CONSISTENCY=1 → 严格模式（medium 也阻止）
  * - SDD_WARN_ONLY=1 → 仅告警不拦截
  * - 注意：三个环境变量互斥，只能启用一个
+ *
+ * 共享逻辑见同目录 consistency-check-core.cjs。
  */
 'use strict';
 
-const fs = require('fs');
-const path = require('path');
-const { execFileSync } = require('child_process');
-
-const readArg = (name) => {
-  const prefix = `--${name}=`;
-  const found = process.argv.find(a => a.startsWith(prefix));
-  return found ? found.slice(prefix.length) : '';
-};
-
-// --- Spec 根路径解析 ---
-
-function resolveSpecRoot() {
-  // .cjs 位于 <spec-root>/skywalk-sdd/git-hooks/，直接用 __dirname 推算
-  return path.resolve(__dirname, '..', '..');
-}
-
-function discoverActiveChanges(specRoot) {
-  const changesDir = path.join(specRoot, 'openspec', 'changes');
-  if (!fs.existsSync(changesDir)) return [];
-
-  return fs.readdirSync(changesDir).filter(name => {
-    const p = path.join(changesDir, name);
-    return fs.statSync(p).isDirectory() && !name.startsWith('.') && name !== 'archive';
-  });
-}
-
-// --- 报告查找与解析 ---
-
-function findReport(specRoot, changeName, type) {
-  const names = type === 'json'
-    ? ['consistency-report-result.json', 'consistency-report-self-review-result.json']
-    : ['consistency-report.md', 'consistency-report-self-review.md'];
-
-  const found = [];
-  for (const n of names) {
-    const p = path.join(specRoot, 'openspec', 'changes', changeName, n);
-    if (fs.existsSync(p)) found.push(p);
-  }
-
-  // 如果两种模式的报告都存在，返回错误标记
-  if (found.length > 1) {
-    return { error: 'duplicate', paths: found };
-  }
-
-  return found.length === 1 ? found[0] : null;
-}
-
-function parseReport(reportPath) {
-  try {
-    const data = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
-    return {
-      confidence: (data.confidence || '').toLowerCase(),
-      reviewMode: data.reviewMode || 'independent-review',
-      humanConfirmed: data.humanConfirmed === true,
-      reportPath,
-    };
-  } catch (err) {
-    return { confidence: '', reviewMode: '', humanConfirmed: false, reportPath, parseError: err.message };
-  }
-}
-
-// --- 变更文件采集（基于配置文件精准定位） ---
-
-/**
- * 简易 YAML 解析器：仅提取 code_repos 列表
- */
-function parseCodeRepos(yamlPath) {
-  try {
-    const content = fs.readFileSync(yamlPath, 'utf8');
-    const match = content.match(/code_repos:\s*\n((?:\s+-\s+\S+\n?)+)/);
-    if (!match) return null;
-    return match[1]
-      .split('\n')
-      .map(line => line.replace(/^\s+-\s+/, '').trim())
-      .filter(Boolean);
-  } catch {
-    return null;
-  }
-}
-
-function gitDiff(repoRoot) {
-  try {
-    return execFileSync('git', ['diff', 'HEAD', '--name-only'], {
-      cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
-    }).split(/\r?\n/).filter(Boolean);
-  } catch {
-    return [];
-  }
-}
-
-function getModifiedFiles(projectRoot) {
-  // 工作区模式：读 .sdd-workspace.yaml 的 code_repos
-  const wsYaml = path.join(projectRoot, '.sdd-workspace.yaml');
-  if (fs.existsSync(wsYaml)) {
-    const repos = parseCodeRepos(wsYaml);
-    if (repos && repos.length > 0) {
-      const files = [];
-      for (const repo of repos) {
-        const repoRoot = path.join(projectRoot, repo);
-        for (const f of gitDiff(repoRoot)) {
-          files.push(path.join(repo, f).replace(/\\/g, '/'));
-        }
-      }
-      return [...new Set(files)];
-    }
-  }
-
-  // 单仓模式 / 兜底：直接对 projectRoot 做 diff
-  return gitDiff(projectRoot);
-}
+const core = require('./consistency-check-core.cjs');
+const { gitDiffNameStatus } = core;
 
 /**
- * 获取报告生成时间：优先用 JSON 中的 generatedAt，降级用文件 mtime
+ * 单仓 diff 采集：工作区相对 HEAD 的变更（含 staged 与未 staged）。
+ * files=修改/新增（排除删除）；deleted=删除文件。
+ * 空仓（无任何 commit）时 HEAD 不存在：降级用 staged 文件列表。
+ * @returns {{files: string[], deleted: string[], ok: boolean}} ok=false 表示无法确定变更范围
  */
-function getReportTime(jsonPath) {
-  try {
-    const data = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
-    if (data.generatedAt) {
-      const t = new Date(data.generatedAt).getTime();
-      if (!isNaN(t)) return t;
-    }
-  } catch {}
-  // 降级：用文件 mtime
-  return fs.statSync(jsonPath).mtimeMs;
-}
-
-function isReportStale(specRoot, changeName, modifiedFiles, projectRoot) {
-  const jsonPath = findReport(specRoot, changeName, 'json');
-  if (!jsonPath) return false;
-
-  const reportTime = getReportTime(jsonPath);
-
-  // 排除报告文件本身
-  const reportFiles = [
-    'consistency-report.md',
-    'consistency-report-self-review.md',
-    'consistency-report-result.json',
-    'consistency-report-self-review-result.json',
-  ];
-
-  return modifiedFiles.some(file => {
-    if (reportFiles.includes(path.basename(file))) return false;
-    const fp = path.join(projectRoot, file);
-    return fs.existsSync(fp) && fs.statSync(fp).mtimeMs > reportTime;
-  });
-}
-
-// --- 提示信息 ---
-
-function generateInstructions(missing, parseError, lowConfidence, stale, needsConfirmation, warnOnly) {
-  const lines = ['', '=========================================='];
-  const needsRegenerate = [...new Set([...missing, ...parseError, ...lowConfidence, ...stale])];
-
-  if (warnOnly) {
-    lines.push('[SDD commit-consistency-check] ⚠️  仅告警模式（SDD_WARN_ONLY=1），以下问题不会阻止提交：');
-  } else {
-    lines.push('[SDD commit-consistency-check] 以下变更存在问题，拒绝提交：');
-  }
-
-  lines.push('');
-
-  if (missing.length) {
-    lines.push('  缺少一致性报告：');
-    missing.forEach(c => lines.push(`    - ${c}`));
-  }
-
-  if (parseError.length) {
-    lines.push('  报告解析失败（JSON 格式损坏）：');
-    parseError.forEach(c => lines.push(`    - ${c}`));
-  }
-
-  if (lowConfidence.length) {
-    lines.push('  报告置信度不达标：');
-    lowConfidence.forEach(c => lines.push(`    - ${c}`));
-  }
-
-  if (stale.length) {
-    lines.push('  报告已过期（代码在报告生成后被修改）：');
-    stale.forEach(c => lines.push(`    - ${c}`));
-  }
-
-  if (needsConfirmation.length) {
-    lines.push('  自审模式需人工确认：');
-    needsConfirmation.forEach(c => lines.push(`    - ${c}`));
-  }
-
-  // 只有需要重新生成报告时才显示 skill 执行建议
-  if (needsRegenerate.length > 0) {
-    lines.push('');
-    lines.push(warnOnly
-      ? '建议执行 opsx-consistency-check skill 更新报告：'
-      : '请执行 opsx-consistency-check skill 更新报告后再提交：');
-    lines.push('');
-
-    if (needsRegenerate.length === 1) {
-      lines.push(`  skill: opsx-consistency-check ${needsRegenerate[0]}`);
-    } else {
-      lines.push('  skill（逐个执行）：');
-      needsRegenerate.forEach(c => lines.push(`    opsx-consistency-check ${c}`));
-    }
-
-    lines.push(
-      '',
-      '  💡 建议：新开对话窗口执行校验，以获得独立、客观的审核结果',
-    );
-  }
-
-  // 自审模式人工确认指引
-  if (needsConfirmation.length > 0) {
-    lines.push('');
-    lines.push('  人工确认步骤：');
-    lines.push('  1. 打开 consistency-report-self-review.md，找到「人工确认（自审模式）」章节');
-    lines.push('  2. 逐条核对断言，在「人工确认」列填写 ✅ 已确认 或 ❌ 有误');
-    lines.push('  3. 确认无误后，编辑 consistency-report-self-review-result.json，将 humanConfirmed 从 false 改为 true');
-    lines.push('');
-    lines.push('  报告路径: openspec/changes/<change-name>/consistency-report-self-review.md');
-    lines.push('  JSON 路径: openspec/changes/<change-name>/consistency-report-self-review-result.json');
-  }
-
-  // 如果没有需要重新生成的报告，但有其他问题，显示默认报告路径
-  if (needsRegenerate.length > 0 && needsConfirmation.length === 0) {
-    lines.push(
-      '',
-      '  报告路径: openspec/changes/<change-name>/consistency-report.md',
-      '  JSON 路径: openspec/changes/<change-name>/consistency-report-result.json',
-    );
-  }
-
-  lines.push('==========================================', '');
-
-  return lines.join('\n');
-}
-
-// --- 主流程 ---
-
-function main() {
-  const projectRoot = path.resolve(readArg('project') || process.env.SDD_PROJECT || process.cwd());
-
-  const skip = process.env.SDD_SKIP_CONSISTENCY_CHECK === '1';
-  const strict = process.env.SDD_STRICT_CONSISTENCY === '1';
-  const warnOnly = process.env.SDD_WARN_ONLY === '1';
-
-  // 互斥检查
-  const activeModes = [skip, strict, warnOnly].filter(Boolean).length;
-  if (activeModes > 1) {
-    console.error('[SDD commit-consistency-check] 错误：SDD_SKIP_CONSISTENCY_CHECK、SDD_STRICT_CONSISTENCY、SDD_WARN_ONLY 三个环境变量互斥，只能启用一个');
-    process.exit(1);
-  }
-
-  if (skip) {
-    console.log('[SDD commit-consistency-check] 跳过校验');
-    process.exit(0);
-  }
-
-  if (warnOnly) console.log('[SDD commit-consistency-check] 仅告警模式');
-
-  const specRoot = resolveSpecRoot();
-
-  const changes = discoverActiveChanges(specRoot);
-  if (!changes.length) {
-    console.log('[SDD commit-consistency-check] 无活跃变更，跳过');
-    process.exit(0);
-  }
-
-  const modifiedFiles = getModifiedFiles(projectRoot);
-  const missing = [];
-  const parseError = [];
-  const lowConfidence = [];
-  const stale = [];
-  const needsConfirmation = [];
-
-  for (const cn of changes) {
-    const rp = findReport(specRoot, cn, 'json');
-    if (!rp) {
-      missing.push(cn);
-      continue;
-    }
-
-    // 检查是否存在两种模式的报告
-    if (rp.error === 'duplicate') {
-      console.warn(`[SDD commit-consistency-check] ⚠️  ${cn} 存在两种模式的报告，请删除其中一个：`);
-      rp.paths.forEach(p => console.warn(`    - ${p}`));
-      parseError.push(cn);
-      continue;
-    }
-
-    const report = parseReport(rp);
-    if (report.parseError) {
-      console.warn(`[SDD commit-consistency-check] ⚠️  ${cn} 报告解析失败`);
-      parseError.push(cn);
-      continue;
-    }
-
-    if (isReportStale(specRoot, cn, modifiedFiles, projectRoot)) {
-      console.log(`[SDD commit-consistency-check] ⚠️  ${cn}: 报告已过期`);
-      stale.push(cn);
-      continue;
-    }
-
-    // 自审模式需要人工确认
-    if (report.reviewMode === 'self-review' && !report.humanConfirmed) {
-      console.log(`[SDD commit-consistency-check] ⚠️  ${cn}: 自审模式需人工确认`);
-      needsConfirmation.push(cn);
-      continue;
-    }
-
-    const c = report.confidence;
-    if (c === 'low' || (c === 'medium' && strict)) {
-      console.log(`[SDD commit-consistency-check] ❌ ${cn}: 置信度 ${c}`);
-      lowConfidence.push(cn);
-      continue;
-    }
-
-    console.log(`[SDD commit-consistency-check] ✅ ${cn}: 置信度 ${c}`);
-  }
-
-  if (missing.length || parseError.length || lowConfidence.length || stale.length || needsConfirmation.length) {
-    console.log(generateInstructions(missing, parseError, lowConfidence, stale, needsConfirmation, warnOnly));
-
-    if (warnOnly) {
-      console.log('[SDD commit-consistency-check] 仅告警模式，放行提交');
-      process.exit(0);
-    }
-
-    process.exit(1);
-  }
-
-  console.log('\n[SDD commit-consistency-check] ✅ 所有变更均已通过一致性校验，放行提交');
-  process.exit(0);
-}
-
-main();
+function gitDiffHead(repoRoot) {
+  const bases = [['diff', 'HEAD'], ['diff', '--cached']];
+  for (const base of bases) {
+    const r = gitDiffNameStatus(repoRoot, base);
+    if (r.ok) return r;
+  }
+  return { files: [], deleted: [], ok: false };
+}
+
+core.runConsistencyCheck({
+  label: '[SDD commit-consistency-check]',
+  actionNoun: '提交',
+  diffFn: gitDiffHead,
+  checkConfidence: true, // 置信度校验由 pre-commit 完成
+  includeUntracked: true, // 新文件将随本次提交入库，需检查
+});

package/templates/git-hooks/pre-commit-sdd-check.cjs

@@ -30,6 +30,95 @@ function normalizePath(filePath) {
   return filePath.replace(/\\/g, '/');
 }
 
+function isCodeFile(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  return ['.js', '.ts', '.java', '.py', '.go', '.rs', '.c', '.cpp', '.h', '.cs', '.rb', '.php', '.swift', '.kt'].includes(ext);
+}
+
+function isSddDocument(filePath) {
+  const normalized = normalizePath(filePath);
+  return normalized.includes('openspec/changes/') &&
+    (normalized.endsWith('proposal.md') ||
+     normalized.endsWith('spec.md') ||
+     normalized.endsWith('design.md') ||
+     normalized.endsWith('tasks.md'));
+}
+
+function getCurrentBranch(projectRoot) {
+  try {
+    return execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return 'unknown';
+  }
+}
+
+function getStagedLineCount(projectRoot) {
+  try {
+    const output = execFileSync('git', ['diff', '--cached', '--numstat'], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    let total = 0;
+    for (const line of output.split(/\r?\n/).filter(Boolean)) {
+      const parts = line.split(/\t/);
+      if (parts.length >= 2) {
+        total += (parseInt(parts[0], 10) || 0) + (parseInt(parts[1], 10) || 0);
+      }
+    }
+    return total;
+  } catch {
+    return 0;
+  }
+}
+
+function recordBypassTelemetry(projectRoot, branch, files, lines) {
+  try {
+    const logCli = path.join(projectRoot, 'skywalk-sdd', 'log.cjs');
+    if (!fs.existsSync(logCli)) {
+      console.warn('SDD pre-commit: log.cjs not found, bypass telemetry skipped.');
+      return false;
+    }
+
+    const safeBranch = branch.replace(/[^a-z0-9\-]/gi, '-').toLowerCase();
+    const details = JSON.stringify({
+      bypass_detected: {
+        branch: branch,
+        files_changed: files.length,
+        lines_changed: lines,
+        staged_files: files.slice(0, 20),
+        reason: 'code_commit_without_sdd_documents',
+      },
+    });
+
+    execFileSync('node', [
+      logCli,
+      'record',
+      '--strict',
+      '--type=bypass_detected',
+      '--command=pre-commit',
+      '--project=.',
+      `--change=${safeBranch}`,
+      '--agent=git-hook',
+      '--source=pre-commit-hook',
+      `--details-json=${details}`,
+    ], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    console.log(`SDD pre-commit: bypass-detected event recorded for ${safeBranch} (${files.length} files, ${lines} lines).`);
+    return true;
+  } catch (err) {
+    console.warn('SDD pre-commit: bypass telemetry recording failed:', err.message);
+    return false;
+  }
+}
+
 function getChangeNameFromPath(filePath) {
   const normalized = normalizePath(filePath);
   const match = normalized.match(/^openspec\/changes\/([^/]+)\//);
@@ -119,6 +208,15 @@ function main() {
   const changes = discoverChanges(projectRoot, explicitChange, archiveMode);
 
   if (changes.length === 0) {
+    // Bypass detection: if code files are staged without SDD documents, record telemetry
+    const stagedFiles = getStagedFiles(projectRoot);
+    const hasCodeFiles = stagedFiles.some(isCodeFile);
+    const hasSddDocs = stagedFiles.some(isSddDocument);
+    if (hasCodeFiles && !hasSddDocs) {
+      const branch = getCurrentBranch(projectRoot);
+      const lines = getStagedLineCount(projectRoot);
+      recordBypassTelemetry(projectRoot, branch, stagedFiles, lines);
+    }
     console.log('SDD pre-commit: no archive intent detected; tasks gate skipped.');
     return;
   }