commit

提交

验证各项门禁，然后提交。提交不是拉取请求，拉取请求也不是合并。 此技能在提交后停止。只有在使用 --pr 或用户提出要求时，才会推送并创建拉取请求， 并且绝不会合并——只有用户明确表示要合并该拉取请求时才会进行合并（见下文“合并”）。 拉取请求创建后，Codex 和 Copilot 等审查者会发表评论；在他们给出审查意见前就合并，会跳过他们的审查。

步骤

步骤 0：质量门禁（提交前）

在创建分支前运行。 对每个有质量评分标准的已更改 .qmd、.tex 或 .R 文件，运行：

python3 scripts/quality_score.py <changed-file-paths>

• 如果任何文件的评分低于 80，请停止并报告发现的问题。用户必须修复问题，或明确使用类似 “仍要提交” 或 “跳过质量门禁” 的措辞覆盖此要求。运行 ./scripts/install-hooks.sh 后，.githooks/pre-commit 会对已暂存的 .qmd/.tex/.R 文件重新运行相同的 ≥80 门禁，因此请将已批准的覆盖带入步骤 4，使用 SKIP_QUALITY_GATE=1 git commit ...，并在提交说明中记录覆盖原因。该变量只会跳过质量评分；回测仍会运行。绝不要改用 git commit --no-verify。
• 如果所有文件的评分均为 80 或以上，则继续。

通过 Agent 工具并设置 subagent_type=verifier，启动 verifier Agent，对已更改的文件运行编译/渲染检查。提交前报告通过或失败。

步骤 0b：一致性门禁（提交前）

无条件运行。 完整回测套件——全部十项门禁（表面同步计数声明，如 "18 agents, 61 skills, 37 rules, 11 hooks" 和带标记的表格、技能完整性、模型时效性、链接、规范符合性、过时检查、仓库卫生、派生计数、账本覆盖、钩子测试套件）：

./scripts/backtest.sh

• 退出码为 0： 所有门禁均通过——继续。
• 非零： 至少有一项门禁未通过——打印其输出并停止。修复后重新运行。即使用户说“仍要提交”，也不得在此门禁未通过时继续：未通过意味着存在漂移，下一位读者会继承这个问题，而且计数的细微漂移已多次导致后续拉取请求。

步骤 0c：Passport 检查（提交前）

如果差异涉及某篇在 quality_reports/passports/ 中有 passport 的手稿（.tex/.qmd）、passport 列出的任何 source_file，或某项声明指定为展示内容的任何文件（其 location: 或 appears_in 中的 path:），请阅读该 passport：状态为 FAIL 或 STALE 的关键声明属于必须修复的问题——停止，指出该声明，并在提交前提示使用 /audit-reproducibility（或过时的脚本）。修改展示文件也会触发检查，原因与修改脚本相同：编辑某个制品中的数字副本，会使其与该数字在其他位置的展示不一致——补充材料或演示文稿中的相同数值未必在同一次提交中更新。若不存在 passport，则静默跳过。

步骤 1：检查当前状态

git status
git diff --stat
git log --oneline -5

步骤 2：创建分支（当前处于 main 时）

绝不要直接提交到 main。如果当前分支是 main，请创建一个新分支；如果已经处于 功能分支，则在该分支上提交。

git checkout -b <short-descriptive-branch-name>

步骤 3：暂存文件

添加指定文件（绝不要使用 git add -A）：

git add <file1> <file2> ...

不要暂存 .claude/settings.local.json 或任何包含机密信息的文件。

步骤 4：使用描述性消息提交

如果提供了 $ARGUMENTS，请将其用作提交消息。否则，分析已暂存的更改并撰写一条说明原因而不只是内容的消息。

主题行要陈述提交后成立的事实——用一句平实的话描述行为，读者可以亲自测试。“修复审查反馈”和“更新检查器”只是在叙述你的工作过程，没有告诉读者任何有用信息；“奇偶校验门禁会拒绝哈希未注册的测试样例”则是读者可以对照代码验证的说法。过程叙述——来自哪一轮审查、是谁提出的、尝试了多少次——如果确有必要，应放在正文中。正文仍需说明原因；主题则陈述事实。

git commit -m "$(cat <<'EOF'
<commit message here>
EOF
)"

步骤 5：推送并创建拉取请求——仅限使用 --pr 或用户提出要求时

如果没有使用 --pr，且用户没有要求创建拉取请求，则跳过此步骤：提交保留在本地，并在报告中说明。

git push -u origin <branch-name>
gh pr create --title "<short title>" --body "$(cat <<'EOF'
## Summary
<1-3 bullet points>

## Changed defaults
<"None", or each default a forker will notice changing: a setting, a threshold, a hook that now fires, a path that moved>

## Test plan
<checklist>

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

步骤 6：报告

报告提交（哈希和主题）、分支，以及——如果已创建拉取请求——其 URL。明确说明没有合并任何内容。

合并——仅限用户提出要求时

合并从来都不是此技能的步骤。只有用户明确要求合并某个拉取请求（“merge #155”）时才进行合并；“ship it”、“done”或“commit”都不属于合并指令。合并前，检查该拉取请求的 CI 是否通过，并确认已阅读和回复相关评审意见（来自人工、Codex、Copilot）。

gh pr merge <pr-number> --merge --delete-branch
git checkout main
git status --porcelain          # must print nothing before the next line runs
git pull

此处的工作树预计处于脏状态——这正是步骤 3 的目的。暂存指定文件意味着，会话中修改但未暂存的所有内容，以及所有未跟踪的文件，在进入此步骤时仍会留在工作树中。此模板附带的 git-guardrails hook 会在 git status --porcelain 输出非空时拒绝git pull（以及 merge 和 rebase），因为在未提交的工作之上解决冲突的拉取操作事后无法审查——你将无法再判断哪些代码块来自远程。把 stash 和拉取串在同一命令行中并无帮助：hook 会读取工作树，而不是预测命令行会如何修改它。

有意清理工作树，然后拉取：

git stash push -u -m "post-merge: unstaged leftovers"   # -u, or untracked files stay behind
git pull
git stash pop

git pull --autostash 是另一种单命令方案，但仅适用于脏内容全部已跟踪的工作树。git stash 不会暂存未跟踪文件，因此，如果有 ?? 条目，autostash 会在仍处于脏状态的工作树上开始拉取，而检查机制正是为了拒绝这种情况——因此，只要存在任何 ?? 条目，hook 就会读取 porcelain 并拒绝--autostash。此步骤通常正是这种状态，因此上面的显式 -u stash 是默认做法；只有当 git status --porcelain 完全没有 ?? 行时，才使用 --autostash 这个快捷方式。Git 也会独立处理这种情况：如果传入的提交在你保留为未跟踪文件的路径上新增了文件，它会在 autostash 已经执行后中止合并（"untracked working tree files would be overwritten"）。无论采用哪种方式，都必须作为单独命令执行——把 stash 和 pull 串在同一行会被直接拒绝，因为只有作为独立的简单命令执行时，已识别的历史操作才会读取工作树。

ALLOW_DIRTY_MERGE=1 是为你已检查过且能明确说明理由的脏状态准备的应急开关。它不是常规解决方案；检查机制正是为了防止你因操作受阻而随手启用它。

重要事项

• **绝不跳过步骤 0。**质量门禁会在问题进入 main 前发现编译错误、引用错误和硬编码路径。如果用户坚持跳过，请在提交消息中记录其覆盖检查的理由。
• 绝不直接提交到 main；先从该分支切出新分支。
• 除非用户提出要求，否则绝不推送、创建拉取请求或合并——参见步骤 5 和“合并”。
• 不要暂存 settings.local.json 和敏感文件。
• 用户要求合并时，使用 --merge（而非 --squash 或 --rebase），除非用户另有说明。
• 如果 $ARGUMENTS 提供了提交消息，请原样使用。

标志

标志	效果
--pr	提交后推送分支并创建拉取请求（步骤 5）。绝不合并。