oma-scm

软件配置管理

调度

目标

在明确范围内执行 Git 操作，确保提交可追溯且历史可恢复。

意图签名

• 提交、暂存、推送、创建分支、合并、变基、解决冲突、管理工作树，或检查 SCM 治理。

适用场景

• 提交和推送请求，包括 Conventional Commit 消息和逻辑拆分。
• 分支与历史操作、发布、基线、CODEOWNERS 和配置管理审查。

不适用场景

• 实现功能或修复应用代码 → 使用负责该领域的专家。
• 通用需求规划 → 使用 oma-pm；安全/测试审查 → 使用 oma-qa。

预期输入

请求的 Git 操作、仓库状态，以及项目配置中生效的 scm 设置。

预期输出

请求的 Git 更改或建议计划、提交/分支标识、已执行的检查，以及未解决的工作。

依赖项

Git CLI；项目配置和钩子。仅针对所选操作阅读下方参考资料。

结构化流程

入口

检查分支、上游、已暂存/未暂存更改，以及现有授权。根据下方内容选择提交路径，或在涉及更广泛操作时选择配置管理资源。

转换

• 仅提交的请求：提交后结束。只有在用户请求或适用工作流要求时，才推送或创建 PR。
• 独立更改：按功能拆分。一个逻辑更改即使涉及代码、测试和文档，也应保持为一个提交；明确的分组指示优先。文件数仅作为平局时的判断依据（最多五个文件时倾向于合为一个提交）。
• 治理、工作树、发布或历史操作：加载 resources/cm-operations.md。
• 大型合并：在选择合并顺序或恢复步骤之前，加载 resources/merge-risk.md。
• 推送到默认分支：遵循下方的“推送与 PR 安全”部分。

失败与恢复

失败	恢复
存在无关的未提交或已暂存文件	将其排除在请求的提交之外；绝不要未经说明就将其并入 amend
提交钩子拒绝消息	根据钩子要求修正消息或实际缺陷；不要绕过钩子
推送出现非快进错误	获取更新、检查分歧，并在本地整合；不要重试强制推送
存在冲突更改	保留双方意图，解决冲突，并在完成前运行受影响的检查
拟议差异中可能包含密钥	暂停暂存，并指出受影响的路径，不要暴露密钥值

退出

报告创建的提交/引用和验证结果。提交失败、推送被拒或冲突未解决，都不算完成。

逻辑操作

标准命令路径

1. 检查工作树和近期惯例：

   git status -sb
   git diff --staged
   git diff
   git log --oneline -5
   

2. 根据“转换”选择逻辑提交组。阅读 resources/conventional-commits.md，了解消息语法、类型、页脚和分支命名；遵循仓库钩子/配置限制。
3. 展示所选消息。暂存明确指定的路径，检查已暂存差异，并使用准备好的消息文件进行提交：

   git add -- <specific-files>
   git diff --cached --check
   git diff --cached
   git commit -F <message-file>
   

4. 检查生成的提交和剩余工作树。如果请求了推送，则遵循“推送与 PR 安全”部分，然后报告远程结果。

防护措施

1. 明确且无歧义的用户指令优先于 SCM 默认设置，包括提交分组和直接推送到默认分支。现有授权持续有效；不要再次请求授权。疑似机密的内容仍需在暂存前停止操作。
2. 暂存明确指定的路径。未经明确授权，不要使用 git add -A 或 git add .，也绝不能包含凭据或机密文件。
3. 未经明确授权，不要改写共享历史。获准改写时，使用 --force-with-lease，绝不要使用普通的 --force。
4. 执行 amend 前，先阅读暂存的差异。未推送的提交可在请求范围内修改或重新整理；已推送的提交属于共享历史。
5. 面向用户的回复遵循已配置的语言；提交消息、分支名称和 PR 标题／正文保持英文。

推送和 PR 安全（仅在收到请求时）

• 推送前，确认分支、上游以及领先／落后状态。
• 如果 scm.require_pr_for_default_branch 为 true，则对默认分支的变更使用主题分支和 PR，除非用户明确要求直接推送。
• 保留仓库要求的钩子／检查。若失败，必须修复问题或准确说明部分结果，不得宣称成功。
• 验证请求的提交已到达预期的远程分支。

Amend、fixup、autosquash

如果存在上游，使用 git log --oneline @{u}..HEAD 判断目标提交是否已共享。如果没有上游，在假定提交未共享之前，先检查远程引用。操作时不要包含无关的暂存变更。

资源范围和影响

Git 操作会更改索引、本地提交／引用、工作树，并可能更改远程引用。只读取相关项目配置；绝不要在消息或报告中复制凭据值。对授权和验证应用 ../_shared/core/execution-policy.md。

参考资料

• 提交语法、类型、共同作者政策和分支命名：resources/conventional-commits.md（提交请求）
• 配置管理操作：resources/cm-operations.md（治理／历史／工作树任务）
• 合并风险和回滚：resources/merge-risk.md（大型合并）
• 所有权详情：resources/codeowners-playbook.md（CODEOWNERS 工作）
• 入门风险指标：resources/onboarding-risk-signals.md（仓库风险评估）
• 发布可观测性：../oma-observability/SKILL.md §Integrations（发布标记和基线对比）