karryviber/orb/commit-lineage

Commit Lineage

每次 commit 把代码改动反向锚定到 spec / lesson / 决策原文，长期可审计「为什么这行长这样」。

借鉴 Yansu traceable lineage 原则：每行代码都该能追溯到引发它的需求或决策。

When to Use

• 准备执行 git commit 时
• 起草 commit message 时
• 用户说「提交」「commit」「先 commit 一下」

规则

commit message 末尾按需追加 lineage 行，使用以下锚点：

没有源头的改动（探索性 / 临时调试 / 重构）不强制带 lineage，但 message 主体要写清「为什么」。

模板

conventional commits + lineage 行：

{type}({scope}): {简述}
 
{可选 body}
 
Spec: specs/xxx.md[#section]
Lesson: lessons/yyy.md

例子

好：

feat(execplan): 加 ## 验收场景 段
 
借鉴 Yansu scenario-simulation，spec 草稿后增加 Karry 拍板 gate。
 
Spec: specs/yansu-borrow.md
Decision: CLAUDE.md#Surgical-Changes

好（无源头但 why 清晰）：

fix(worker): typo 导致 inject 失败
 
变量名 `injectId` 写成 `injetId`。

坏（有 spec 来源但没引用）：

feat: 新增场景段

Gotchas

• 不要为了凑 lineage 编造来源——没源头的改动主体写清 why 即可
• 不要把 lineage 行写在 message 第一行（影响 oneline 可读性），只放末尾
• 引用 lessons 时用相对路径 lessons/xxx.md，不要绝对路径（commit history 跨机器看也能 grep）
• spec 引用最好带 #anchor 锚到具体段，否则 spec 长了找不到
• 多源头时一个锚点一行，不要堆在同一行

反模式

• :x: 每个 commit 都硬塞 lineage（没源头就别加）
• :x: Spec: see above / Lesson: 见之前讨论（不可追溯）
• :x: lineage 写在 message 主标题里