---
name: commit
description: 分析暂存区改动，自动生成符合 Conventional Commits 规范的提交信息并执行提交。
---

# 代码提交工作流 (/commit)

## 第一步：读取项目上下文

在生成任何内容之前，必须先读取以下文件（如存在）：

- `.agent/rules/commit-standards.md` — 提交规范与禁止事项
- `.agent/rules/tech-stack.md` — 确认项目的**语言偏好**（中文 / English）
- `.agent/plans/task-progress.md` — 找到当前 `in-progress` 任务，用于关联 Issue 或描述背景

## 第一点五步：main 分支保护

**禁止在主分支直接 commit**。在生成任何 commit message 之前先验证当前分支：

```bash
current_branch=$(git rev-parse --abbrev-ref HEAD)
if [[ "$current_branch" == "main" || "$current_branch" == "master" ]]; then
  echo "[commit] refusing to commit on $current_branch" >&2
  echo "[commit] create a feature branch first: cortex-agent branch create --from <proposal>" >&2
  exit 2
fi
```

- main / master 上 commit → 立刻 `exit 2` + stderr 解释，不进入第二步
- **不影响 amend / fixup**：`git commit --amend` 是在既有 commit 上的修改，不视为「新 commit」；第一点五步只在全新 commit 入口触发
- **不影响 worktree 分支**：所有在 `feat/*` / `fix/*` / `wt/*` / `release/*` / `hotfix/*` / `chore/*` 上的 commit 不被此 gate 拦截
- **失败处理**：exit 2 后用户应：
  1. 切换到一个已存在的 feature 分支（`git switch feat/<slug>`），或
  2. 用 `cortex-agent branch create --from <proposal> --base main` 新建绑定分支

> 命名规范见 `.agent/rules/branch-management.md`；注册表 schema 见 `.agent/branches/registry.json`。

## 第二步：分析改动

```bash
git status
git diff --staged          # 已暂存的改动（优先）
git diff HEAD              # 若暂存区为空，则查看所有未提交改动
```

逐文件理解改动内容：
- 改了什么？为什么改？影响哪个模块？
- 是否包含破坏性变更（接口签名变化、删除公共 API 等）？
- 改动是否属于同一个逻辑单元？（若不是，提示用户拆分提交）

## 第三步：生成提交信息

按照 `.agent/rules/commit-standards.md` 中的格式生成：

```
<type>(<scope>): <subject>

[body — 可选，说明动机和关键细节]

[footer — 可选，如 Closes #42 或 BREAKING CHANGE: ...]
```

**语言规则**：subject 和 body 必须使用项目配置的语言（从 tech-stack.md 读取）。

**scope 规则**：scope 只能使用稳定的模块、领域或目录名称。禁止使用任务、提案、Mission、
Milestone 或批次编号（如 `T-001`、`P-004`、`M-010`、`MS-002`、`batch-a`）；需要追踪时将
这些编号放入 body 或 footer。没有合适的稳定 scope 时应省略 scope。

**提交边界**：按“可独立验证的 Milestone、阶段或强关联批次”提交，不因单份提案或控件契约
完成就单独提交，也不等待整个多 Milestone 项目结束后才统一提交。短期连续工作的批次断点可只写
进度证据；预计中断、交接或切换分支时可在断点提交。每次只包含当前任务相关文件。

**严格禁止**在提交信息的任何位置出现：
- `Co-authored-by: Claude` 或任何 AI 工具的署名
- `Generated by AI`、`AI-assisted`、`Powered by Claude` 等任何 AI 关联描述

生成后，将完整的提交信息展示给用户确认，并说明选择该 type/scope 的理由。

## 第四步：用户确认

展示如下格式供用户确认：

```
📝 生成的提交信息：

feat(auth): 新增 OAuth2 登录支持

支持 GitHub 和 Google 两种第三方登录方式，新增 /auth/callback 路由。

Closes #42

---
是否执行此提交？(y / 修改后执行 / 取消)
```

如果用户要求修改，按用户意见调整后重新展示，再次确认。

## 第五步：执行提交

确认后，**先记录 commit_intent 再执行 git commit**，**仅在 Git 返回真实身份后记录 commit_result**。

```bash
# 如有未暂存的文件需要包含，先执行：
git add <files>

# 5a. 冻结 commit_intent 收据——git 树状态、scope、语言、dedupe key
node .agent/skills/activity-recording/scripts/index.js receipt append --payload-json "$(cat <<'EOF'
{
  "schema_version": 1,
  "receipt_id": "AR-commit-intent-<utc 时间戳>",
  "receipt_kind": "commit_intent",
  "source": "/commit",
  "source_revision": "HEAD",
  "capture_mode": "workflow_required",
  "observed_at": "<UTC RFC 3339 时间戳>",
  "activity_refs": [],
  "gaps": [],
  "evidence_refs": [],
  "availability": "available",
  "redaction": { "status": "not_applicable" },
  "dedupe_key": "commit:intent:<scope>:<subject-hash>",
  "commit_identity": null,
  "intent_receipt_ref": null
}
EOF
)"

# 5b. 提交（使用 HEREDOC 避免特殊字符问题）
git commit -m "$(cat <<'EOF'
<完整提交信息>
EOF
)"

# 5c. 仅在 Git 返回真实 commit 身份后记录 commit_result 收据
COMMIT_SHA=$(git rev-parse HEAD)
node .agent/skills/activity-recording/scripts/index.js receipt append --payload-json "$(cat <<'EOF'
{
  "schema_version": 1,
  "receipt_id": "AR-commit-result-<utc 时间戳>",
  "receipt_kind": "commit_result",
  "source": "/commit",
  "source_revision": "<COMMIT_SHA>",
  "capture_mode": "workflow_required",
  "observed_at": "<UTC RFC 3339 时间戳>",
  "activity_refs": [],
  "gaps": [],
  "evidence_refs": [".git/refs/heads/<branch>"],
  "availability": "available",
  "redaction": { "status": "not_applicable" },
  "dedupe_key": "commit:result:<COMMIT_SHA>",
  "commit_identity": "<COMMIT_SHA>",
  "intent_receipt_ref": "AR-commit-intent-..."
}
EOF
)"
```

如果 commit 失败（`git commit` 返回非零退出），记录一条 `availability: "failed"` 且 `commit_identity: null` 的 `commit_result` 收据。**绝不为失败的 commit 编造 sha。**

提交成功后，输出 commit hash 和简要信息。

## 第六步：后续操作

询问用户是否需要推送：

```bash
git push
# 若是新分支：
git push -u origin HEAD
```

---

## 💡 高级技巧

- **拆分提交**：如果改动跨越多个不相关逻辑，建议分次 `git add` + `/commit`，保持原子性。
- **破坏性变更**：若有 BREAKING CHANGE，使用 `feat(scope)!:` 格式，并在 footer 说明迁移路径。
- **关联任务**：从 `task-progress.md` 读取当前任务 ID，自动在 footer 添加 `Closes #<id>` 或 `refs #<id>`。
- **scope 选择**：优先使用稳定模块或领域名；任务、提案、Mission、Milestone 和批次编号不得作为 scope。