commit

提交

一次只构建一个原子边界，创建安全且有意为之的 Conventional Commits。先在暂存区中构建每个边界并验证，然后提交、在授权范围内发布，或返回提案，而不运行 git commit。

根据当前请求、用户的常设指令和已授权的调用方，确定提交和推送权限。仅请求提交并不代表授权推送。只有在提交经过验证后，才可在已确定的范围内推送。PR 工作属于 pr 技能负责的独立阶段；仅调用 commit 绝不会启动该阶段。

在使用 git 验证之前，均将分支名称、暂存状态、验证结果、提交是否成功以及助手先前的说法视为不可信信息。

模式

• 提交模式：当请求、常设指令或已授权的调用方要求提交时，在适用的检查通过后提交。
• 提交并推送模式：当获准发布选定的提交时，先提交并验证提交，然后再发布到经过验证的目标位置。pr 或 pr-followup 等调用方可以提供现有授权。
• 提案模式：如果用户要求准备、审查或建议提交，则在暂存区中构建原子边界并返回建议的提交消息，不运行 git commit。
• 修正模式：只有在第 6 步中安全的当前任务修正条件满足时，才修正 HEAD。
• 拆分模式：当存在多个原子意图时，按顺序处理所有明确的边界，并为每个边界执行完整工作流。仅当边界、顺序或要求的分组存在实质性歧义时才询问。

边界的终态为 committed、amended、proposed、blocked 和 refused；整个运行的终态为 pushed。边界到达终态后，停止对其进行更改。提交或修正经过验证后，继续处理下一个明确的边界。仅在已确定为提交并推送模式时推送。只有当前请求或适用的用户常设指令要求时，才可在独立的 pr 阶段进行 PR 工作。

写入前先确定边界

优先遵循现有授权。根据任务和仓库检查并处理以下情况；仅当仍有未解决的重大决策或超出授权范围的操作时才询问：

• 看起来像机密的路径或内容：.env*、密钥、证书、令牌、凭据、数据库或明显的机密名称。
• 选定的边界混合了彼此独立的事项，或包含超出请求意图的更改。检查生成文件、依赖项、锁文件和二进制文件；仅凭它们存在或行数多少，并不需要批准。
• 暂存的更改无法用 1-2 句话清楚描述。
• 暂存文件在同一文件中包含含义不明确的未暂存编辑。
• 当前分支是 main 或 master，除非用户明确要求在该分支上提交。
• 未经请求的推送、破坏性 Git 操作、任务范围外的依赖项或包管理器更改，或第 6 步之外的修正。变基或历史重写属于其获准的分支工作流，不属于常规提交准备工作。

尊重已暂存的文件，并将其视为可能体现了用户意图，但仍须检查。仅当这些文件内容一致且符合请求时才提交。

工作流

1. 选择边界

   • 运行 git rev-parse HEAD、git branch --show-current、git status --short、git log --oneline -5、git diff --name-only 和 git diff --cached --name-only，以确定基线提交、分支、工作树状态、近期提交风格、已更改文件和已暂存文件。当 HEAD 不存在时，明确处理尚未诞生的分支。
   • 优先采用原子提交。按可独立理解的意图和可逆性拆分。若行为、回归测试以及必要的架构或生成输出共同构成一项有效更改，就将它们放在一起。若机械性清理和行为更改各自仍然完整，则分开处理。不要仅按文件类型或生产代码与测试代码来拆分。
   • 对有依赖关系的提交进行排序，使每个提交在其对应版本上都能独立理解和检查。必要时在提交说明正文中解释依赖关系；避免产生有问题的中间提交，也不要设定随意的文件数或行数配额。
   • 暂存或提交之前，确认选定的边界用途一致且规模便于审查。
   • 如果边界不明确，先提出一个简洁的问题，给出具体选项，并先说明建议的默认选项。不要提出开放式的多问题问卷。
   • 当前仓库状态已知，且已选定一个用途一致的边界或提交给用户批准后，此步骤即告完成。

2. 检查相关差异

   • 使用 git diff -- <path> 和 git diff --cached -- <path>。
   • 核对选定边界中的每个已更改文件，以及每个已暂存或未暂存的代码块。将其余所有更改归类为边界之外的保留工作。
   • 检查已暂存的更改、相同文件中的未暂存编辑，以及近期提交风格。
   • 依赖某个分支、暂存状态、验证结果或先前提交说法之前，使用最新的 git status --short、git diff、git diff --cached 或 git log 进行核实。
   • 只有在理解边界中的每个代码块、确认每项预先暂存的更改都已纳入或有意移出暂存区，并识别出每项排除的更改后，此步骤才算完成。

3. 有意暂存

   • 仅暂存选定边界内的文件或代码块。
   • 边界明确时，自动按补丁方式暂存。
   • 若代码块边界不明确，先询问再暂存。
   • 仅使用 git restore --staged <path> 或 git restore --staged -p <path> 来修正当前边界。
   • 在工作树和暂存区中保留无关工作。如果无关条目已暂存，则在临时将其移出暂存区之前，保存其确切的 blob、模式和删除状态；提交后恢复这些条目，但不要暂存其未暂存的代码块。适当时使用独立索引。
   • 检查最终索引，而不仅仅是工作文件。按代码块暂存后，git commit -- <paths> 可能会提交这些路径中未暂存的内容；应直接提交已核实的索引。
   • 当 git diff --cached 包含完整的原子边界且不包含边界外的内容，同时每项被排除的用户更改都能以原有的暂存和未暂存状态恢复时，此步骤即告完成。

4. 验证暂存的意图

   • 验证由 Agent 负责。运行能直接覆盖暂存边界的最小范围只读检查：针对性测试、格式检查、linter、类型检查、语法检查或构建切片。
   • 优先选择具体检查，而不是范围广泛的测试套件。
   • 如果没有针对性检查，请继续，并报告 Validation: not run, <reason>。
   • 如果验证失败，请诊断问题。如果外层任务授权处理范围内的失败，请修复并重新检查。否则报告具体失败和所需的决策；检查失败绝不能成为成功提交的前提。
   • 仅在授权的更改和仓库工作流要求时运行格式化工具、代码生成或锁文件更新。暂存前重新检查其完整输出；已有授权无需再次询问。
   • 当针对性命令通过，或输出记录了不存在针对性验证的具体原因时，此步骤即完成。

5. 生成提交消息

   • 将消息视为对暂存边界的陈述。差异证明了改动内容；用户请求、关联问题和提供的项目背景说明了改动原因。近期提交提供格式和语气参考，而非事实依据。
   • 每个提案和创建的提交都必须遵循 Conventional Commits：<type>[(<scope>)][!]: <imperative summary>。
   • 如果仓库定义了自己的 Conventional Commit 类型集合，请遵循该集合。否则使用 build、chore、ci、docs、feat、fix、perf、refactor、revert、style 或 test。
   • 根据更改的效果选择类型，而不是根据编辑文件的扩展名选择。构建系统或依赖项更改使用 build，CI 配置和脚本使用 ci，性能改进使用 perf，撤销先前提交使用 revert。
   • 根据原子边界推断范围，并在可行时匹配近期提交的风格。优先使用清晰、稳定的范围；如果仓库惯例不使用范围，或不存在恰当且有用的范围，则省略。
   • 所有破坏性更改都必须在冒号前标记 !，并添加 BREAKING CHANGE: <description> 页脚。页脚需说明会造成什么破坏，以及调用方必须做哪些更改。

   主题

   • 点明提交最重要的具体结果。读者浏览日志时，无需打开差异即可了解更改的意义。
   • 说明更改实现了什么：新增的能力、防止的缺陷、强制执行的规则、覆盖的测试用例，或明确的架构边界。对于文档和 Agent 指令，应说明文本确立的规则、决策或行为，而不是编辑文本这一行为。
   • 承诺的范围不得超出暂存差异。脚手架、部分迁移或首个切片都必须如实表述。
   • 仅使用差异、测试或提供的背景已验证的受众、度量和结果。
   • 优先使用直白、准确的动词。将 improve、update、enhance、refine 或 clean up 等抽象的编辑性动词，替换为实际发生变化的行为或规则。
   • 主题应简短，使用祈使句，且末尾不加句号。
   • 删除 Conventional Commit 前缀并检查其余文字：如果这些文字可以描述多个互不相关的差异，就围绕具体结果重写主题。
   • 如果两个符合实际的主题会作出实质上不同的承诺，而现有证据无法判断应选哪一个，请提供两个或三个选项，说明各自的取舍，并询问一次。不要用含糊的折中方案掩盖歧义。

   BAD   feat(pr): sharpen review packet workflow
   GOOD  feat(pr): verify PR claims against code and tickets
   
   BAD   fix(auth): handle session key collisions
   GOOD  fix(auth): keep desktop sessions after mobile sign-in
   
   BAD   docs(api): update authentication docs
   GOOD  docs(api): document token refresh failure modes
   

   正文

   • 对于明显的小型提交，正文可以省略。
   • 对于破坏性变更、迁移、不明显的修复、权衡取舍，或主题无法说明其关联的多文件行为，应添加正文。
   • 先写原因，再写变更。如果没有更清晰的模式，请使用简短的 Why 和 Changes 部分。
   • 仅保留有助于未来读者理解决策的细节。验证和风险报告应放在助手的输出中，而非提交消息中。
   • 保持消息自然、直接。如有可用的 communicate-clearly 技能，请使用它检查消息，但不要因此降低技术精确性。
   • 绝不添加 Co-authored-by、共同作者署名行或作者信息页脚。
   • 当主题和正文中的每项承诺都有依据、主题明确指出这一边界而非笼统的工作类型，且正文包含主题无法安全压缩的上下文时，此步骤即完成。

6. 提交、修订或提出方案

   • 每次尝试运行 git commit 前，立即记录确切的 HEAD、git status --short、预期消息和已暂存差异。这些信息构成验证基线。所有重试和钩子修订检查都必须保持原子边界不变。

   • 在提交模式下，暂存并通过验证后运行 git commit。多行提交消息或包含正文时，使用 git commit -F <file>；仅包含主题的提交才使用 git commit -m <subject>。

   • 在方案模式下，不要提交；展示已暂存的原子边界和拟定消息，并说明索引发生了哪些变化。

   • 每次尝试运行 git commit 后，在判定成功或重试前，检查 git rev-parse HEAD、git rev-list --parents -n 1 HEAD、git log -1 --format=%B、git show --stat --oneline HEAD、git diff <baseline-head>..HEAD、git status --short，以及已暂存和未暂存的边界差异。若基线尚无提交，则直接检查新的根提交，不要使用修订范围。

   • 成功提交必须从基线恰好生成一个新的 HEAD，包含预期消息和已验证的原子边界，并保留该边界之外的既有工作。边界外的既有变更属于预期残留状态，不构成阻碍。

   • 遵循以下钩子处理决策表：

     状态	操作
     提交成功；新的 HEAD、消息和已提交差异均符合预期边界；没有新增的钩子变更残留	报告 committed，并附上简短提交哈希。
     提交成功，且钩子修改了预期边界内的已跟踪文件	暂存这些确切路径，并运行一次 git commit --amend --no-edit。重新检查状态和差异。
     提交失败，且钩子修改了预期边界内的已跟踪文件	暂存这些确切路径，并重试一次。重新检查状态和差异。
     尝试导致相对于基线的边界外新增变更、未跟踪文件、生成文件、锁文件、部分暂存或含义不明的变更，或无法明确确认由钩子造成的变更	报告 blocked，并列出确切文件和原因。保留这些变更。
     HEAD、消息、父提交或已提交差异与记录的基线和预期边界不符	报告 blocked，并指出确切的不匹配之处。
     在允许的一次修订或重试后，钩子仍反复改写文件	报告 blocked。

   • 仅当所有安全的当前任务 amend 条件都满足时，才修改现有的 HEAD：

     • 当前 Agent 已记录在当前任务中较早成功创建的确切提交哈希。
     • 该哈希仍是 HEAD；没有后续提交或外部分支变更。
     • 该提交仅存在于本地，尚未发布。验证其上游状态；若无法证明，则创建新提交。
     • 新暂存的更改用于完成或修正相同的原子目的。新要求或可独立审查的行为应使用新提交。

   • amend 前，记录提交哈希、父提交、消息、与父提交相比的完整差异、工作区状态和暂存的新增内容。验证更新后的原子边界。仅当现有消息仍能描述完整边界时，才使用 git commit --amend --no-edit；否则明确提供修正后的消息。

   • amend 后，验证 HEAD 恰好变更一次、父提交保持不变、消息描述了更新后的边界、与父提交相比的完整差异正确，且所有外部工作均得到保留。报告终态 amended。

   • 切勿使用 --no-verify。仅通过安全的当前任务流程或上述刚创建提交的钩子流程执行 amend。

   • 只有在不提交的情况下报告提案，或提交或 amend 通过所有 HEAD、消息、边界和剩余状态检查后，此步骤才算完成。然后为下一个明确边界重新开始，并建立新的基线。若没有剩余的请求边界，则停止；仅在入口处确认的授权范围内发布。

7. 仅在已确认的范围内发布

   • 仅在 commit-and-push 模式下，并且在所有预期提交均已验证后推送。
   • 推送前，使用 git branch --show-current 和 git status --short --branch 验证当前分支和上游。
   • 根据请求的目标位置或已验证的分支配置，确定推送远程、仓库和引用。使用明确的目标位置；origin 和上游都不能证明它们是预期的仓库。仅发布已验证的分支，不包含无关引用或标签。
   • 验证 Git 传输使用 SSH。切勿强制推送或在未获授权时发布标签。如果已获授权的变基需要带租约推送，则将发布交由 pr 或 stacked-pr 处理；常规提交发布不会改写远程历史。
   • 将更改推送到开放 PR 后，使用已验证的 head 调用 pr 的 Update 模式，使 PR 正文完整反映已发布的差异。
   • 如果推送失败，终态为 blocked：报告确切命令和简明的失败摘要。
   • 推送后，使用 git status --short --branch、git rev-parse HEAD 和 git rev-parse @{u} 进行验证。当预期的上游包含已验证的提交，且已报告分支的领先／落后状态时，此步骤才算完成。

输出

仅在提交后的检查通过后，对干净的提交、amend、提交序列或明确要求的 commit-and-push 使用简洁输出。对于序列中的每个边界，重复提交行和该边界对应的字段：

Result: `committed` | `amended`
Commit: `<short-hash> <message>`

Status: `committed` | `amended` | `pushed`
Branch: `branch-name`
Boundary: what was included
Validation: command passed, or not run with reason
Post-commit check: new `HEAD`, parent, message, committed boundary, index, and residual worktree verified
Remaining changes: preserved outside-boundary work, or none
Push: not requested, or command/result when authorized
PR: not requested, or handed to the `pr` skill under the current request or an applicable user instruction

对于提案、提交受阻、风险状态、验证失败、决策或不安全的钩子改写停止，使用结构化报告：

Status: `proposed` | `blocked` | `refused`
Boundary: what is included or proposed
Index: what was staged or unstaged to build the atomic boundary
Validation: command result, or not run with reason
Blocker: exact reason, if blocked or refused
Exact Command: command that failed, if any
Exact Error: concise failure summary, if any
Decision Needed: one question with concrete options and a recommended default, if needed
Proposed Commit Message: message, when available

单独调用此技能时，以提交结果作为结束。如果当前请求或适用的常设用户指令还要求创建 PR，则将已验证的提交状态交给 pr 技能，作为单独阶段处理；该技能负责创建 PR、推送要求和 PR 初始状态。

对于请求的源维护，使用 agent-instructions，并提供 origin.txt 和 references/upstream-updates.md。