ssf-git

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 内容

核心硬规则

1. commit 标题的类型与范围使用英文标识符，摘要与正文必须是中文。
   • 标题格式：<英文类型>(<英文范围>): <中文摘要>。
   • 类型必须从下方“允许的英文类型”表中选取，范围必须采用 <根模块> 或 <根模块>:<业务子模块> 形式。
   • 正文（项目符号、变更编号、关联规格、变更内容、验证方式、风险与回滚等字段及其说明）必须使用中文。
   • 允许出现不可避免的代码标识符、路径、命令、Spec ID、change-id，例如 AUTH-001、src/api/user.ts、pnpm test。
   • 禁止 WIP、update、fix bug、changes、misc 这类模糊提交信息。
2. 没有 change-id，不提交行为变更。
3. 没有 Spec ID，不提交行为变更。
4. 没有验证证据，不提交完成态 commit。
5. 不得提交无关改动。
6. 不得把多个无关目标混在一个 commit。
7. 提交前必须检查 staged diff。
8. 不得提交本地 workflow 运行时、安装副本或缓存产物。
9. 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 monitoring
• ssf-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、生产配置、隐私数据
• 当前分支和目标变更不匹配