---
name: git-workflow
description: 管理 Git 分支、工作树、提交、拉取请求和历史整理的完整生命周期。当需要确认仓库状态、创建或切换分支与工作树、组织提交、创建或更新拉取请求、进入 Ready、处理评审与持续集成反馈、合并，或执行 rebase、squash、amend、force-push 等历史改写时使用。
---

# Git 生命周期

`git-workflow` 保存团队特有的交付契约和远端操作边界。常规 Git 命令由模型自行选择；Hook 负责可确定执行的门禁，本技能负责仍需结合上下文判断的部分。

## 核心约束

1. **先确认现场。** 改变 Git 或 GitHub 状态前，确认目标仓库、工作树、当前分支、远端、基准分支、现有拉取请求和未提交改动。
2. **保护已有改动。** 无法确认归属的改动默认属于用户；不覆盖、不移动、不提交，也不通过暂存、清理或切换命令隐藏它们。
3. **分支先行。** 不直接提交默认分支。新工作从仓库约定的最新基准分支开始；已有正确任务分支时继续使用，不机械重建。
4. **提交表达一个逻辑变化。** 按语义边界提交，验证强度与风险匹配；不要把无关关注点塞进同一提交。
5. **拉取请求正文保持当前事实。** 评论记录过程，正文记录最终范围、决定、风险、验收、验证与后续事项。
6. **远端变更需要任务授权。** 推送、创建或更新拉取请求、进入 Ready、评论、改写共享历史和合并，都必须在用户授权的任务范围内。

## 1. 操作前检查

- 读取仓库根、当前分支、工作树状态、远端关系和 worktree 列表；不要根据当前目录名猜测仓库。
- 确认仓库实际采用的默认分支和本次基准分支，不写死为 `main`。
- 如果已有未提交或未跟踪内容，先判断能否与本任务隔离；不能安全隔离时停止并说明冲突。
- 未经明确授权，不执行 `git stash`、`git reset --hard`、`git checkout --`、`git clean` 或对共享分支强制推送。
- 多个写入任务并行时使用独立 worktree，并显式指定基准引用；单写入任务不为形式额外创建 worktree。

## 2. 提交与历史

- 在一个能用一句话描述的逻辑变化完成后提交；高风险删除、批量替换或依赖升级前，可先建立安全检查点。
- 提交信息使用 Conventional Commits：

```text
<type>(<scope>): <摘要>
```

允许的 `type`：`feat`、`fix`、`docs`、`refactor`、`chore`、`test`、`perf`、`style`、`build`、`ci`、`revert`。

- 正文只在动机、关键决定或限制不明显时补充，解释为什么，不复述差异。
- 临时检查点可以使用 `fixup` 或可识别的临时前缀，但在需要保留逐提交历史的仓库中，进入 Ready 前应整理。
- 是否整理历史取决于仓库合并策略和分支是否已共享。采用压缩合并时不为表面整洁重写本地历史；改写共享历史前必须获得团队确认。

## 3. 创建 Draft 拉取请求

首个有意义的提交验证并推送后，尽早创建 Draft 拉取请求。正文必须使用二级标题，并覆盖范围、验收标准、设计决定、风险、验证计划和后续事项。

验收标准表示当前拉取请求必须成立的可验证结果，可以来自正式规格或用户的口头要求，不限定为产品需求。只有存在真实设计决定时才记录取舍；没有时明确写“无”，不编造候选。

```markdown
## Summary / 摘要

本次变更解决了什么问题，以及为什么现在需要处理。

## Acceptance Criteria / 验收标准

- [ ] 用户或调用方能够观察到的结果成立。
- [ ] 既有行为与兼容性约束得到保留。

## Design Decisions / 设计决策

- 选择当前方案的原因和需要评审者理解的代价；没有真实决定时写“无”。

## Risks / 风险

- 可能受影响的边界、已知限制和恢复条件。

## Test Plan / 验证计划

- [ ] 运行与改动匹配的自动化验证。
- [ ] 完成必要的手工、界面或运行时检查。

## Remaining TODOs / 后续事项

- 无。
```

创建后读取远端拉取请求的标题与正文，确认标题符合 Conventional Commits，正文与当前提交一致；发现漂移就直接更新。

## 4. 进入 Ready

进入 Ready 前确认：

- 所有当前提交已推送，基准分支与目标分支正确。
- 最后一次相关修改之后的自动化、构建和必要手工验证已经完成。
- 正文反映最终范围、验收、决定、风险、验证证据和真实后续事项。
- 当前拉取请求的临时规格与计划已按用户选择晋升、归档或删除；该动作用 `documentation-management` 执行，不直接移动文件。跨拉取请求的长期规范保持原位。

Hook 会检查可确定的结构问题和未推送提交，但不能替代以上判断。

## 5. 处理评审与持续集成反馈

- 逐项判断为修复、延期或不处理，并保留理由；不要因为评审出现就自动扩大范围。
- 一批处理完成后，在拉取请求会话中汇总问题、状态和对应提交。某条讨论需要澄清、拒绝或人工决定时，可以单独回复。
- 不擅自关闭仍需评审者确认的讨论。
- 新发现改变了范围、设计决定、风险或后续事项时，同步更新正文；批次评论不代替提交信息中的理由。

## 6. 合并

- 确认用户已授权合并，拉取请求仍指向预期提交，必需检查与批准均满足。
- 验收标准和验证计划中的合并前事项必须完成；无法在合并前完成的真实后续工作移到“后续事项”，写成普通条目并说明原因。
- 读取仓库允许且惯用的合并策略，不默认选择压缩、变基或合并提交。
- 合并后确认远端状态和合并提交，再清理已经不需要的本地与远端任务分支。

## 机制边界

| 机制 | 保证什么 |
|---|---|
| `commit-reminder` | 未提交变化增长时提醒在下一个语义边界提交 |
| `pr-create-guard` | 创建后展示标题与正文结构，提醒修正漂移 |
| `pr-ready-guard` | 阻止未清理的临时规范和未推送提交进入 Ready |
| `pr-merge-guard` | 阻止验收标准或验证计划仍有未完成事项的拉取请求合并 |