用途
Synthesis Git Hooks 是一个基于 YAML 配置的 pre-commit 策略引擎，属于 synthesis-engineering 操作层。它目标是在提交边界、即差异被持久化之前，确定性地拦截凭据泄露和暴露敏感内容。引擎主体是一个 Bash 边界脚本加 Python 标准库侧车；策略本身是数据，位于 ~/.synthesis/git-hook-config.yaml，采用者需填入个人远端模式、客户名称、内部 URL，可选配置协同板路径。
主要能力
强制内容分两层：Tier 0 凭据（AWS、OpenAI、Anthropic、Google、GitHub、GitLab、Slack 的 API 密钥，以及 RSA、OpenSSH、EC、PGP 私钥标记）在所有仓库执行；Tier 1 暴露敏感项（财务、人事/雇佣、保密标记、保密客户/公司名、私有技能名、内部 URL）在 strict 和 public-surface 仓库执行，personal 仓库跳过。分类由每次提交时的 git remote -v 推导：任一推送远端匹配 strict_repo_patterns、远端列表为空或其它都不匹配则为 strict；所有推送远端匹配 public_surface_patterns 为 public-surface；全部匹配 personal_remote_patterns 为 personal。披露账本可允许 public-surface 仓库豁免特定名称模式。
配套的 commit-msg 钩子扫描提交信息本身，补上 pre-commit 无法覆盖的通道；personal 类仓库按配置跳过提交信息扫描。
使用方式
安装步骤：先用 codex plugin marketplace add synthesisengineering/synthesis-skills 和 codex plugin add synthesis-skills@synthesis-engineering 安装原生插件（Claude Code 对应 claude plugin marketplace add 与 claude plugin install），再运行 <synthesis-git-hooks-root>/scripts/install.sh，将引擎复制到 ~/.synthesis/git-hooks/ 并设置 git 的 core.hooksPath，从模板生成初始配置，随后编辑配置文件填入自己的模式。安装后工作站上每次 git commit 都会执行策略，无需逐仓库配置。可用 ~/.synthesis/git-hooks/_load_config.py --classify 查看某仓库分类。自检命令 python3 ~/.synthesis/git-hooks/_load_config.py --doctor 会校验配置解析、模式在 Python re 与 grep -E 下均可编译、hooksPath 接线、安装副本与技能源是否漂移、当前仓库分类与链式本地钩子。
适用场景
适用于作为 synthesis-engineering 安装的一部分配置新工作站、审计因误报导致频繁 --no-verify 绕过的系统、团队采纳 synthesis engineering。不适用于一次性脚本或丢弃型仓库、确实需要提交凭据的环境（通常意味着缺少密钥存储），以及已运行自带凭据泄露扫描的 CI/CD 流水线（开发者侧与 CI 侧是互补控制）。
限制与机制
引擎失败即拦截：配置缺失或不可解析、侧车崩溃、无效模式、解释器缺失都会阻止提交并给出醒目诊断，侧车最后一行需输出 SYNTHESIS_SIDECAR_OK=1 哨兵。零第三方依赖，自带严格 YAML 子集解析器，只支持注释、缩进嵌套映射、引号/裸字符串列表与标量值，其余语法（制表符、流式风格、锚点、块标量）为硬解析错误。可选协同边界：配置 coordination_board 后，pre-commit 在内容扫描前调用 check-staged，除非选中的活动会话拥有确切工作树和分支且每条暂存路径被声明覆盖，否则拒绝；故意越界需 SYNTHESIS_COORDINATION_OVERRIDE_REASON 并被原子记录。绕过手段包括单次使用不同配置（SYNTHESIS_GIT_HOOK_CONFIG）、git commit --no-verify、向 allowlist_lines 添加正则以加入允许列表、扩展 personal_remote_patterns。仓库自有的 .githooks/pre-commit 不会被取代，引擎先执行自身扫描再链式调用它；声明 .githooks/required 后，缺失或不可执行的本地委托会阻止提交。
版本要点
v2.6.0 增加缓存模式校验，按配置摘要与 grep 身份复用结果；v2.5.0 引入必需的仓库本地委托并失败即拦截；v2.4.0 在提交边界加入协同声明；v2.3.0 使漂移源解析可移植；v2.1.2 识别已提交文件的精确副本以校准迁移；v2.1.1 支持 Codex 与 Claude Code 双运行时；v2.0.0 确立失败即拦截、零依赖、自诊断三项保证。安装器还会从 synthesis-project-management 依赖复制 coordination.py、claim_scope.py、coordination_schema.py、pointer_lock.py、peer_addressing.py 及版本化会话词资产到共享运行时，doctor 会比较安装副本与源路径并报告漂移。