| name | ssf-git |
| description | Git 工作流与中文 commit 正文门禁。用户输入 /ssf-git、/ssf-branch、/ssf-commit、/ssf-pr，或要求建分支、提交、生成 PR、合并、rebase 时触发。强制分支、暂存、提交、PR 与 OpenSpec change-id/Spec ID 对齐；commit 标题的类型与范围使用英文标识符（conventional commits），摘要、正文、字段名必须使用中文。 |
ssf-git — Git 工作流与中文 commit 正文门禁
目标
把“代码改完了”变成可审计、可回滚、可追踪的 Git 记录。
本阶段把 OpenSpec 的 change-id / Spec ID、Superpowers 的小步验证、Karpathy 的 surgical changes，以及发布检查结果连接到 Git：
Spec ID → 任务 → 测试 → 最小实现 → 规范 commit（英文类型 + 中文正文） → PR → Release Gate
触发
- 显式：
/ssf-git、/ssf-branch <change-id>、/ssf-commit <change-id>、/ssf-pr <change-id>
- 隐式：用户说提交、commit、建分支、branch、PR、merge、rebase、cherry-pick、回滚、revert
- 自动：
ssf-build 完成一个可验证任务后建议提交；ssf-ship 前必须检查 Git 状态和 PR 内容
核心硬规则
- commit 标题的类型与范围使用英文标识符，摘要与正文必须是中文。
- 标题格式：
<英文类型>(<英文范围>): <中文摘要>。
- 类型必须从下方“允许的英文类型”表中选取，范围必须采用
<根模块> 或 <根模块>:<业务子模块> 形式。
- 正文（项目符号、变更编号、关联规格、变更内容、验证方式、风险与回滚等字段及其说明）必须使用中文。
- 允许出现不可避免的代码标识符、路径、命令、Spec ID、change-id，例如
AUTH-001、src/api/user.ts、pnpm test。
- 禁止
WIP、update、fix bug、changes、misc 这类模糊提交信息。
- 没有 change-id，不提交行为变更。
- 没有 Spec ID，不提交行为变更。
- 没有验证证据，不提交完成态 commit。
- 不得提交无关改动。
- 不得把多个无关目标混在一个 commit。
- 提交前必须检查 staged diff。
- 不得提交本地 workflow 运行时、安装副本或缓存产物。
- merge / ship 前必须保证工作区干净，或明确列出未提交内容。
分支命名规范
优先使用：
ssf/<change-id>-<中文或拼音短描述>
示例：
ssf/add-membership-renewal-reminder-xufei-tixing
ssf/fix-payment-retry-state-zhifu-chongshi
高风险紧急修复：
hotfix/<change-id>-<短描述>
规格或流程类变更：
spec/<change-id>-<短描述>
process/<change-id>-<短描述>
Spec cluster 分支命名：
ssf/<parent-change>-<cluster-id>-<short-slug>
为 cluster 推荐或创建 worktree 前必须检查未提交改动。worktree 只是执行隔离机制，不是发布边界；清理 worktree 前必须获得用户明确批准。
Step 1 — Git 状态审计
提交或 PR 前先运行并总结：
git branch --show-current
git status --short
git diff --stat
git diff --check
如果已经暂存，还要运行：
git diff --staged --stat
git diff --staged --check
输出：
# Git 状态审计
## 当前分支
## 工作区状态
## 改动统计
## 可能无关改动
## 建议下一步
Step 2 — 分支创建
git checkout -b ssf/<change-id>-<short-slug>
创建分支前检查：
- 当前是否已有未提交改动
- 是否在正确 base 分支
- 是否需要先 pull/rebase
- 当前工作是否属于同一个 change-id
Step 3 — 暂存策略
默认使用选择性暂存：
git add <path1> <path2>
git diff --staged --stat
git diff --staged
禁止盲目使用：
git add .
除非已经明确确认所有改动都属于同一 change-id，并且没有生成物、缓存、日志、临时文件。
Step 4 — commit 标题与中文正文格式
提交标题格式：
<英文类型>(<英文范围>): <中文摘要>
字段约束：
英文类型：从下方“允许的英文类型”表中选取，conventional commits 标准 + 项目定制 spec。英文范围：必须采用 <根模块> 或 <根模块>:<业务子模块> 形式。
- 根模块取自仓库根目录划分：
skills、commands、agents、routing、templates、scripts、docs、openspec、examples、meta（用于 CLAUDE.md、README.md 等根级文档）。
- 业务子模块按本次改动实际涉及的业务模块填写，使用小写英文 kebab-case。
- 示例：
skills、skills:members、routing:payment、meta。
中文摘要：必须是中文，长度建议不超过 50 字符。
允许的英文类型：
| 类型 | 用途 |
|---|
| feat | 新功能或新增行为 |
| fix | 缺陷修复 |
| docs | README、说明、runbook、用户文档 |
| style | 不影响语义的格式调整 |
| refactor | 不改变行为的结构调整 |
| perf | 性能优化 |
| test | 单测、集成测试、E2E、负向测试 |
| build | 构建脚本、依赖、工具链 |
| ci | CI 配置 |
| chore | 杂项维护 |
| revert | 回滚提交 |
| spec | OpenSpec、需求、验收标准、任务（项目定制） |
提交正文格式：
<英文类型>(<英文范围>): <中文摘要>
变更编号：<change-id>
关联规格：<SPEC-ID-1>, <SPEC-ID-2>
变更内容：
- <中文说明 1>
- <中文说明 2>
验证方式：
- <命令或人工验证步骤>
- <测试结果>
风险与回滚：
- <主要风险>
- <回滚方式>
示例：
feat(skills:members): 增加续费提醒入口
变更编号：add-membership-renewal-reminder
关联规格：MEMBERSHIP-001, MEMBERSHIP-002
变更内容：
- 在会员中心增加续费提醒入口。
- 增加到期前提醒状态的展示逻辑。
验证方式：
- 已运行 pnpm test membership。
- 已通过续费提醒入口的 E2E 验证。
风险与回滚：
- 主要风险是提醒状态展示不一致。
- 可通过移除入口组件并回滚该提交恢复。
Step 5 — 提交前检查清单
# Commit Gate: [change-id]
- [ ] 当前分支符合命名规范
- [ ] staged diff 只包含本次任务相关文件
- [ ] 每个行为变更都有 Spec ID
- [ ] 每个 Spec ID 有测试或明确人工验证
- [ ] 已运行相关测试或说明无法运行原因
- [ ] commit 标题符合 `<英文类型>(<英文范围>): <中文摘要>` 规范
- [ ] commit 标题的类型在允许列表中，范围符合 `<根模块>` 或 `<根模块>:<业务子模块>` 形式
- [ ] commit 摘要为中文
- [ ] commit 正文为中文
- [ ] commit 正文包含 change-id、Spec ID、验证方式、风险与回滚
- [ ] 没有 `superpowers/`、`docs/superpowers/`、`.superspecflow/`、`.claude/`、`.codex/`、`.DS_Store` 等运行时、安装或缓存产物
- [ ] 没有 secret、日志、缓存、临时文件、无关格式化
Step 6 — 提交命令
优先使用文件方式，避免多行消息转义错误：
cat > /tmp/ssf-commit-msg.txt <<'COMMIT'
feat(skills:members): 增加续费提醒入口
变更编号：add-membership-renewal-reminder
关联规格：MEMBERSHIP-001
变更内容：
- 在会员中心增加续费提醒入口。
验证方式：
- 已运行 pnpm test membership。
风险与回滚：
- 可回滚该提交移除入口。
COMMIT
git commit -F /tmp/ssf-commit-msg.txt
Step 7 — PR 工作流
PR 标题必须遵循 commit 标题规范（英文类型与范围 + 中文摘要）：
feat(skills:members): 增加续费提醒入口
PR 正文：
# PR：<中文标题>
## 变更编号
## 关联规格
## 变更摘要
## 用户影响
## 主要改动
## 验证方式
## 风险
## 回滚方案
## QA 结果
## 截图 / 录屏
## 发布备注
PR 前必须检查：
git status --short
git log --oneline --decorate -n 5
git diff --stat origin/develop...HEAD
如果目标分支不是 develop，将 origin/develop 替换为实际 base。
Step 8 — 合并 / 回滚
合并前：
ssf-review 无 🔴ssf-qa 推荐 Ship 或 Ship with monitoringssf-ship 无阻塞- PR commits 均符合
<英文类型>(<英文范围>): <中文摘要> 规范，且正文为中文
回滚提交也必须遵循同样的标题规范，正文使用中文：
revert(skills:members): 回滚续费提醒入口
变更编号：add-membership-renewal-reminder
关联规格：MEMBERSHIP-001
回滚原因：
- 上线后发现提醒状态在部分用户下展示不一致。
回滚方式：
- 回滚提交 <commit-sha>。
验证方式：
- 已确认会员中心入口恢复到发布前状态。
暂停条件
以下情况暂停并报告，不要提交：
- staged diff 包含无关文件
- staged diff 包含本地 workflow 运行时、安装副本或缓存产物
- commit message 无法满足标题规范（英文类型 + 英文范围 + 中文摘要）或正文中文规范
- 找不到 change-id 或 Spec ID
- 测试失败且用户没有明确要求保存失败状态
- 发现 secret、生产配置、隐私数据
- 当前分支和目标变更不匹配
