跳转至

Git 生命周期指南

本文是 Skill Family 各工作区 Git 生命周期规则的唯一权威文档。新建项目骨架 （npx skill-family-engineering-kit scaffold）中的 AGENTS.md「Minimal Git lifecycle」区块与 docs/git-lifecycle.md 页面都是对本指南同口径的投影与指针—— 任何工作区都不得再维护第二套 Git 规则。所有工具链（projen、engineering kit、 CI 脚本）都不执行 Git 写操作；下述每一类写操作都只来自人的显式决定。

分支命名与寿命

  • 分支模型：一条长期分支 main，加短寿命任务分支 task/<任务号>-<短横线摘要> （例如 task/0050-git-lifecycle）。
  • 任务分支只承载一个任务的一组相关变更；任务验收通过后合并；确认没有未合并 提交后可删除本地分支。远端分支删除属于 push 类外部写入，必须另行取得显式 授权（见下文逐项授权节），合并本身不自动授权远端删除。不存在长期存活的 特性分支，也不允许在任务分支上堆积与任务无关的变更。
  • main 永远只接收已通过门禁的合并；任何情况下都不得对 main 直接提交或 force-push。

修改前状态检查

  • 提交、远端等实时 Git 状态不写进任何版本化文档（包括产品状态页）；执行任何 Git 动作前，先现场运行下列只读命令发现当前状态：

bash git status --short --branch git rev-parse --verify HEAD git remote -v

这三条命令只是只读探测：输出只反映本机工作区当下的状态，不授予任何写权限； 执行 stage/commit/push/tag/release 仍必须按下文逐项授权节单独取得授权。 - 开始任何修改之前，先运行 git status --short --branch，确认当前分支、未提交 变更与远端跟踪状态；工作区里出现不认识的分支、未暂存变更或陌生文件时，先 调查来源再动手，那是别人正在进行的工作，不是可以随手清理的噪声。 - 禁止用 git checkout .、git restore .、git clean -f、git reset --hard 之类的破坏性命令“顺手”清空工作区来绕过障碍；确需丢弃未提交变更时，必须 逐条列出将被丢弃的内容并获得显式确认。

原子 commit 条件

一个 commit 必须同时满足：

  1. 只包含一个逻辑变更（一个任务的推进，或一次明确拆分的修正）；
  2. 受管生成物与其源（.projenrc.js、投影脚本）在同一次提交内成对出现；
  3. 提交前 pnpm check（或任务指定的最小验证入口）退出码为 0——不得把红的 状态提交进任何分支后再“回头修”；
  4. 提交信息说明“为什么”，引用任务号；不得包含凭据、私有数据或不可公开的 内部标识。

不满足以上任一条件的变更不得提交；宁可拆成多个 commit，也不合并成一个混合 变更。

stage、commit、push、tag、release 的逐项授权

  • 修改授权不包含 stage 与 commit：获得某任务的修改授权，只表示可以在工作区 里改动文件；stage（git add）与 commit 仍是两个独立的写操作，必须分别 按风险逐项取得明确授权，不存在“授权修改即默认授权提交”。
  • stage 与 commit：默认只在本地、按原子条件执行；一次 commit 授权只覆盖被 明确声明的那一次本地提交，不覆盖任务之外的清理、改写（含 amend/rebase 改写已提交内容）或后续提交。
  • push：把任务分支推送到远端、开 PR，以及删除远端分支 （git push --delete / git push origin :<branch>）同属 push 类外部 写入，都需要在当前任务里单独授权；禁止直接 push main。合并后的清理说明 不构成对远端删除的自动授权。
  • tag 与 release：每一次打 tag、发布 release（包括 npm publish、Pages 部署、 建远端仓库）都是独立的高风险动作，必须逐项单独授权；一次 push 授权不构成 任何 tag/release 授权。
  • 自动化工具（含 AI 助手与 CI）在未获得针对当前任务的显式人工授权前，不得 执行 git add（stage）、git commit、git push、git tag 或任何建 远端/发布/删除远端引用的命令。
  • 授权只对声明者的那一次操作有效，不构成对同类后续操作的长期放行。

受管投影与源同提交

  • projen 受管文件只能通过修改 .projenrc.js 后运行 pnpm synth 产生；生成物 必须与其源变更在同一个 commit 内提交，不得先提交源、后补生成物，更不得只 提交其中一侧。
  • 文档受管投影（如 setup.md 的稳定门禁阶段区块）同理：投影脚本重跑 的输出与触发它的真源变更同提交；CI 的漂移检查（synth-drift / synth-idempotency） 会机械拦截只提交一侧的变更。

.gitignore 分类

  • 每个被忽略的路径都必须归入 .foundation/file-registry.json 的一个类别： 工具生成物（artifacts，如 node_modules/、site/、.cache/、日志）走 .gitignore；依赖锁文件（trackedToolLocks，如 pnpm-lock.yaml）被显式跟踪、 不得忽略；手写源事实与受管文件一律跟踪。
  • .gitignore 的忽略模式集合与 file-registry 的 artifacts 模式集合必须逐字 一致（scripts/check-structure.mjs 机械核对）；新增忽略项必须先登记类别， 不允许出现“跟踪但被忽略”或“忽略但未登记”的中间态。

删除前核对与可恢复处置

  • 删除任何文件、分支或历史内容之前，先核对其是否仍被引用（门禁、文档链接、 冻结证据引用）；被冻结验收输入引用的证据一律不得删除。
  • 优先可恢复处置：能改就不删，能停用（如 if: false 硬门禁）就不移除；确需 删除时保留可追溯的替代物（续接记录、决定记录、归档页）。
  • 分支退出：任务分支合并后，先确认没有未合并的提交，再删除本地分支；远端 分支删除属于 push 类外部写入，合并后的清理说明不得自动授权远端删除，须按 逐项授权节另行取得显式授权。
  • 任何“删除后重放”都必须有先红后绿的机器证据，证明删除不是静默丢失。

生成物禁止手改

  • 带 projen 生成标记的文件、投影脚本写入的受管区块、.foundation/ 下的机器 真源一律禁止手改；手改会被 synth 漂移检查检出并拦截。
  • 需要变更受管内容时，唯一合法路径是修改对应的源（.projenrc.js 或投影脚本 的真源输入）再重新生成；“手改后再重新生成把差异洗白”属于被门禁明确拒绝 的篡改模式。