Git 纪律

本规则在任何项目的任何阶段生效，是修改文件的前提条件，不是可选项。

0. 核心公式

能回退  =  干净起点  +  每步提交

⚠️ git 撤不掉"未跟踪的新文件"。 若新建了若干文件却未提交，git checkout 对它们完全无效，只能手动删除。所以"改完就提交"不是形式主义——它是安全网的唯一实现方式。

1. 授权边界

本地 commit 的持续授权不包含表中任何标 ⚠️ 或 ❌ 的动作。 授权范围不清时，停在计划或 diff，不要扩大解释。 一次授权只覆盖一个动作、一个仓库：用户说"上传/推送"不等于同意合并 PR、 删除远端分支，也不等于同意推送另一个仓库——跨仓库必须重新确认。 push 前先把 git diff --staged 与本轮编号给用户看。

完整流程（何时才该开 PR、分支判据、标题与描述规范、PR 阶段回退）见仓库 docs/05-提交与PR流程.md——本技能被拷贝安装后 docs/ 不在包内，故此处只作文本引用。

1.1 推送核验与失败处置（push 的输出不可信）

• ⚠️ git push 的输出不可信：实测出现过"报错的同时打印 Everything up-to-date"， 而远端实际没收到。以远端为准——推送后必须用 git ls-remote origin <branch> （或 git fetch + 比对 SHA）核对；核对不一致就当作失败，不得回报"已推送"。
• ⚠️ ls-remote 自己也会挂（实测 2026-10-20：push 打印成功，紧接着 ls-remote 报 gnutls_handshake() failed: The TLS connection was non-properly terminated，HTTP/1.1 重试同样失败）。 此时既不能判失败也不能判成功：用 gh api repos/<owner>/<repo>/commits/<branch> --jq .sha 做第二通道（走独立 HTTP 栈），拿到 SHA 且与本地 HEAD 一致即可确认推送； 两路都拿不到才报 GIT_BLOCKED，并说明是核验通道不可用，不是推送失败。
• 链路抖动导致的中断（GnuTLS recv error (-110) / send-pack: unexpected disconnect / Empty reply from server）属可重试错误：先 git -c http.version=HTTP/1.1 -c pack.threads=1 push 重试（关掉 HTTP/2 多路复用 + 单流 pack）， 连续失败再换出口/稍后重试。
• 禁止用 --no-verify 绕过门禁来"解决"推送问题——那等于把"门禁没过"伪装成"推上去了"。
• ⚠️ @{u}..HEAD 这类领先/落后计数，在 fetch 之前不可信：本地 origin/* 只是上次 fetch 的快照， 远端在别处被推进后它仍显示旧值。实测（2026-10-13）：据此报"有 7 个提交未推送"，git push 却被拒 （non-fast-forward）；fetch 后真相是 本地落后 74 个提交、本地零独有提交 —— 根本没有东西要推。 ⇒ 报告"领先/落后几个提交"之前先 git fetch（或改以 git ls-remote 为准）。 同一轮里另一处同类问题：git branch -f 看似成功、实则本地引用过期，SHA 根本没动。
• 完整实战记录与处置步骤见仓库 docs/05-提交与PR流程.md（步骤 3）与 docs/02-实践经验.md。

2. 改动前：核对仓库边界

1. 用 git rev-parse --show-toplevel 定位真实 Git 根，不凭目录名假设。
2. 核对现场：branch、HEAD、index、工作树、目标文件归属。
3. 工作区起点若为脏：
   • 用户自己的改动 → 先报告，不擅自提交或丢弃。
   • 上一轮 agent 的改动 → 先提交或 stash 存档，建立干净起点。
   • 与本轮无关的改动 → 绝不回退。
4. 不得在不知道仓库边界时直接写代码。
5. 执行前先确认工作树（v6）：多 worktree 并存时，同一相对路径在不同工作树里可能是不同版本 的脚本/配置 —— 实测两份同名脚本对同一个事实给出相反判据，据此得出的结论是错的。 执行脚本或读取配置前先确认工作树；输出与本仓库既有决定相反时，先怀疑跑错了副本，再怀疑结论。 推论：同一仓库别长期留落后的 worktree（它是"旧副本"的温床）。

3. 提交时：原子、窄范围、可复核

1. 首段写入前建本次原子基线（若仓库无首个提交或缺少可信基线）。
2. 每个通过验证的原子改动：只 git add 本轮明确文件 → 复核 git diff --staged → 立即 commit。
3. 禁止 git add . / git add -A；不得顺手带入无关未跟踪文件、构建产物、凭据、机器配置。
4. 改动里混有"该提交的"与"不该提交的"时，用 git add -p 逐块挑选。
5. 发现范围外文件被暂存 → git restore --staged <该文件>，但不得丢弃用户内容。
6. 不允许积攒多轮改动后一次混合提交。
7. commit message 说明做了什么、为什么；同一项目保持前缀风格一致。
8. 生成物是否入库服从项目 .gitignore 与既有政策。.gitignore 本身应入库。
9. 不回退与自己无关的工作区改动 —— 发现别人的未提交改动，报告，不动手。

原子性检验（提交前自查）

一个 commit 是原子的，当且仅当全部成立：

[ ] 只做了一件事（一个逻辑变更）
[ ] 代码库仍处于可工作状态
[ ] message 标题里不需要出现 "and"
[ ] 能独立 revert 而不破坏其他功能
[ ] 审查者无需外部上下文就能理解全部改动

「and 检验」：描述这个 commit 时必须说"和"，那它就是两个 commit。

检测启发式：

反例（必须拆）：feat: 加登录 和 顺手修了日志格式 正例（本就原子）：一个特性 + 它的测试 + 它的类型定义，同属一个关注点。

4. 编号与回报

每次 commit 后计算该仓库的连续编号：

git rev-list --first-parent --count HEAD

最终回复的最后一条普通文本必须是以下之一：

• 有提交：已git：<仓库> 第 N 次 git（commit <短SHA>）
• 无提交：本轮未git：原因

⚠️ <仓库> 必填，只改一个仓库也不省略——编号是每仓库的， 多仓库并行时"第 N 次"无法分辨指哪个仓库（实测踩过：同一轮回报里出现过 两个仓库都叫"第 7 次"）。涉及多个仓库时逐个仓库各写一行。

提交失败时：报告 GIT_BLOCKED 并说明真实原因， 不得把未提交的代码声称为完成，不得伪造编号。 编号是给人用的回退别名，精确回退仍以完整 SHA 为准。

5. 回退动作

用 reset --hard 或 git clean 前，先预览（git clean -nd）或 git stash -u 存档。

详细命令与应急流程见 references/rollback-manual.md。

6. 无 Git 时的兜底

1. 项目没有 Git、或仓库无首个提交时，先建立范围明确、可恢复的项目级基线。
2. 若安全基线会卷入大量历史文件、秘密、缓存或归属不明改动： 停止写入并请求用户确认基线范围，不能用"先改完再说"绕过 Git。
3. 确实无法纳入 git 的用户级文件，改前备份到本平台备份根， 写入前核对目标盘可用与空间，写入后逐文件校验（SHA256）。 各平台备份根取值见 references/platform-notes.md。

7. 安全与隐私

• 永不把密码、.env 内容、凭据、token、cookie、私钥、真实个人数据、联系方式、 数据库内容或敏感配置写入项目文件、日志或聊天。
• 秘密一旦提交进历史极难清除（需要 git-filter-repo/BFG 重写历史， 而重写历史本身也需单独授权），防线必须前移到"根本不提交"。

8. 反模式清单（禁止）

• ❌ git add . / git add -A 顺手带入无关文件
• ❌ 把构建产物、虚拟环境、缓存、凭据提交入库
• ❌ 积攒多轮改动一次混合提交
• ❌ 未提交就声称任务完成
• ❌ 提交失败后沉默或伪造编号
• ❌ 把 git push 的成功输出当成"已推送"（必须以 git ls-remote 核对远端）
• ❌ 对已推送历史做 rebase / reset / --force
• ❌ 未经授权新建分支、切换分支、打 tag、push
• ❌ 在不确定仓库边界时直接改代码
• ❌ 丢弃用户已有的未提交改动

9. 与规则入口体系的关系

本技能是完整规则载体，与下列入口构成一套体系：

冲突裁定顺序（与 agents.md 规范 一致）：

用户当前会话中的明确指令
      ↓ 覆盖
项目级规则
      ↓ 覆盖
用户级规则
      ↓ 覆盖
随包默认

托管块的同步与校验见 references/block-sync.md。