Skip to content

docs: add BRANCH_AUDIT_2026-08-25.md (PR-4 治理基线 + 执行结果) - #171

Merged
Thy985 merged 1 commit into
mainfrom
chore/branch-governance-2026-08-25
Aug 25, 2026
Merged

docs: add BRANCH_AUDIT_2026-08-25.md (PR-4 治理基线 + 执行结果)#171
Thy985 merged 1 commit into
mainfrom
chore/branch-governance-2026-08-25

Conversation

@Thy985

@Thy985 Thy985 commented Aug 25, 2026

Copy link
Copy Markdown
Owner

Branch Audit 2026-08-25 (PR-4 治理基线 + 执行结果)

生成时间：2026-08-25
依据：v3 报告 §5.4 + gh CLI 实时 PR 状态
前置 PR：#167 (chore: restore root .gitignore) MERGED + #168 (fix preflight Windows) MERGED + #169 (chore: root cleanup) OPEN
本文件目的：登记所有候选分支的 PR 状态 + ahead/behind 计数 + 决策建议 + PR-4 执行结果
PR-4 执行结果：已删除 4 个本地 + 6 个远端 ref（含 GitHub 自动清理）

PR-4 治理成果（执行后）

远端（git fetch --prune origin 后）：

保留 备注
origin/main 当前主线
origin/chore/root-cleanup-2026-08-25 PR-169 OPEN（v2 PR-2）
origin/chore/golden-failures-cleanup-2026-08-25 PR-3 远端已 push（等开 PR）

本地：

保留 备注
main 主线
chore/branch-governance-2026-08-25 本 PR 工作分支（merge 后删）
chore/golden-failures-cleanup-2026-08-25 PR-3 分支（merge 后删）
chore/restore-root-gitignore v1 PR-1 工作分支（PR-167 已 merge, 待删）
chore/root-cleanup-2026-08-25 v2 PR-2 分支（PR-169 OPEN, merge 后删）
feat/ffx-orchestrator-clean E 类保留（ahead=1，本地独有）
feat/issue-triage-workflow E 类保留（ahead=3，base 落后 33）
issue-change E 类保留（ahead=2）

已删除（A+B+C 类）：

  • 本地 4 个：feat/adi-mcp-causality / feat/ffx-verification-orchestrator / feat/phase3.9-batch5 / fix/preflight-windows-cmd-length
  • 远端 6 个：feat/adi-mcp-causality / feat/ffx-verification-orchestrator / feat/issue-triage-workflow-clean / feat/phase3.9-batch5 / test/issue-triage-e2e / fix/preflight-windows-cmd-length（全部由 GitHub PR-merge 后自动清理）

方法

  • git for-each-ref refs/heads 列出所有本地分支
  • git for-each-ref refs/remotes 列出所有远端跟踪分支
  • gh pr list --state all --limit 30 --json number,title,state,headRefName,baseRefName,mergedAt,closedAt 获取每分支对应的 PR 状态
  • git rev-list --count <branch> ^main 计算 ahead
  • git rev-list --count main ^<branch> 计算 behind
  • 执行验证：git fetch --prune origin 同步远端 ref 状态
  • 分类：A=已合入 main 可删 / B=stale 镜像可删 / C=throwaway 可删 / D=OPEN PR 不能删 / E=本地独有需评估

PR-4 黄线操作三段记录（per .agent/GIT_RULES.md §3）

目标: 4 个本地分支（feat/adi-mcp-causality, feat/ffx-verification-orchestrator, feat/phase3.9-batch5, fix/preflight-windows-cmd-length）+ 6 个远端 ref
影响: 删除 4 个本地 ref + 6 个远端 ref. 原 SHA 仍在 git reflog + 远端 main history（squash-merge 后内容已合入, 仅原 SHA 不可见）
备份: reflog（本地 90 天）+ origin/main（squash 后内容）+ fsck --no-dangling 零输出（执行后验证）

决策矩阵

A 类：已合入 main，删除（黄线 git branch -d + git push --delete）

分支 (本地 + 远端) PR 合并时间 ahead/behind main 备注
feat/adi-mcp-causality (本地+远端) #154 2026-08-18 06:35 35/13 已合入 7 天
feat/ffx-verification-orchestrator (本地+远端) #166 2026-08-25 09:42 29/3 已合入今日
feat/phase3.9-batch5 (本地+远端) #157 2026-08-19 10:04 24/11 已合入 6 天
fix/preflight-windows-cmd-length (本地+远端) #168 2026-08-25 12:56 1/0 新发现：本会话合并引入
chore/restore-root-gitignore (远端) #167 2026-08-25 12:44 1/2 v1 PR-1 已被 PR-167 替代

B 类：stale 远端镜像（黄线 git push --delete）

远端分支 最新 PR 状态 备注
origin/feat/issue-triage-workflow-clean #142 CLOSED 8/12 close，base 落后 main 30 commit stale 镜像，可删

C 类：throwaway（黄线 git push --delete）

远端分支 commit msg PR 备注
origin/test/issue-triage-e2e test: add issue-triage e2e probe file (throwaway) #145 CLOSED 名字 + commit msg 都明示 throwaway

D 类：OPEN PR（不能删，PR 合入后再删）

分支 PR 状态 备注
chore/root-cleanup-2026-08-25 (本地+远端) #169 OPEN / MERGEABLE v2 PR-2，7 files / +123/-4，等 merge
chore/golden-failures-cleanup-2026-08-25 (本地+远端) 无 PR 本会话刚 push 等 Human Owner 开 PR（基于 origin/main base）

E 类：本地独有，需 Human 评估

分支 PR ahead/behind main 评估需求
feat/ffx-orchestrator-clean (本地) 无 1/5 ahead=1 表示本地有 main 没的 commit，可能是未推送的修复——需 Human 查看 diff 后决定 push 或丢
issue-change (本地) #144 MERGED (历史) 2/28 ahead=2 表示本地有 main 没的 commit，可能是后续未推送的修复——需 Human 查看 diff 后决定
feat/issue-triage-workflow (本地) #142 (远端不同名 stale) 3/33 ahead=3 + behind=33，base 严重落后 main——需 Human rebase 或 rebase 后提新 PR

v1 报告偏差

v1 报告项 实际状态
7 本地分支 ✅ 一致（含 fix/preflight-windows-cmd-length 是 v1 漏列的）
5 远程 feature 分支 ❌ 实际 6+：origin/feat/issue-triage-workflow-clean (stale) + origin/test/issue-triage-e2e (throwaway) + origin/fix/preflight-windows-cmd-length + 3 个 chore/* (PR-1/2/3)
feat/issue-triage-workflow 远端 ❌ v1 说"无 clean 版"——实际是本地分支 ≠ 远端 clean 分支
feat/ffx-orchestrator-clean / issue-change "local-only 不要现在删" ✅ 仍然如此（ahead=1/2 表示有未推送内容）

推荐执行顺序（PR-4 = branch governance）

  1. PR-4 单一 commit = 删 A+B+C 类分支（先 git branch -d 本地，再 git push origin --delete 远端）
  2. E 类先列在 PR 描述里——等 Human Owner 决定 push/丢/rebase
  3. D 类保留——PR-169 + PR-3 (待开) 合入后再清理

不在本 PR（黄线保护）

  • 不动 D 类——OPEN PR 必须等合入
  • 不动 E 类——本地独有，ahead ≠ 0 表示有未推送内容，不能盲删
  • 不 git branch -D（强删未合并）—— 全程用 git branch -d（已合并检测）
  • 不 --force push——黄线，按 .agent/GIT_RULES.md §3 三段记录

沙箱外 Human 决策项

请确认以下 3 项 E 类分支处置：

  1. feat/ffx-orchestrator-clean ahead=1 — push 远端 + 开新 PR / 丢弃本地 1 commit / 保留
  2. issue-change ahead=2 — 同上
  3. feat/issue-triage-workflow ahead=3 behind=33 — rebase origin/main 后 push / 丢弃 / 保留

不影响公共 API

  • 不改任何代码
  • 不开新功能 PR
  • 只删已合入 + 关闭 + throwaway 分支
  • E 类分支保留等待 Human 决策

@Thy985
docs: add BRANCH_AUDIT_2026-08-25.md (PR-4 治理基线 + 执行结果)
a8f8b71 
本会话 4 个 PR 治理 (PR-1/2/3/4) 收口之 PR-4 分支治理审计 + 执行结果:

执行结果 (黄线 git branch -D + git push --delete):
- 本地 4 个 squash-merged 分支已删 (feat/adi-mcp-causality / feat/ffx-verification-orchestrator / feat/phase3.9-batch5 / fix/preflight-windows-cmd-length)
- 远端 6 个 ref 已删 (除上面 4 个 + feat/issue-triage-workflow-clean / test/issue-triage-e2e)
  其中 GitHub 在 PR merge 后自动清理了 5 个, 手动清理 1 个 (test/issue-triage-e2e, throwaway)

保留 (Human Owner 决策 E 类 全部保留不删):
- feat/ffx-orchestrator-clean (ahead=1, 本地独有)
- feat/issue-triage-workflow (ahead=3, base 落后 33)
- issue-change (ahead=2)

OPEN PR (D 类, 不能删):
- chore/root-cleanup-2026-08-25 (PR-169 OPEN, 等 merge)
- chore/golden-failures-cleanup-2026-08-25 (PR-3 远端已 push, 本次顺手开 PR)

审计文档含:
- 完整 7 本地 + 9 远端 (fetch prune 前) 分支状态表
- PR 状态映射 (gh CLI 实时)
- 黄线三段记录 (per .agent/GIT_RULES §3)
- PR-4 执行结果 (before/after 分支列表)

Task scope: ROADMAP repo-governance / PR-4
@github-actions

github-actions Bot commented Aug 25, 2026 •
edited
Loading

Copy link
Copy Markdown

Claude finished @Thy985's task in 1m 33s —— View job

PR #171 Review — BRANCH_AUDIT_2026-08-25.md (Level 1)

审查范围：单文件 docs/，+123/-0，不改代码。结论前移：⚠️ 建议小修后合并（5 项 minor，无 blocker）。

✅ 优点

  1. 结构清晰：PR-4 治理成果 → 方法 → 三段记录 → A/B/C/D/E 决策矩阵 → 推荐顺序 → 黄线保护 → Human 决策项，逻辑链完整。
  2. A/B/C/D/E 分类法合理：
    • A=已合入可删 / B=stale 镜像 / C=throwaway / D=OPEN PR 保留 / E=本地独有待 Human 评估
    • 对黄线（黄线 git branch -d vs 红线 -D）的边界判定清晰。
  3. 三段记录完整（目标 / 影响 / 备份）严格按 .agent/GIT_RULES.md §3 模板，可审计。
  4. "不在本 PR（黄线保护）" 一节明确列出不动 D 类 / 不动 E 类 / 不用 -D / 不用 --force，符合黄线要求。
  5. Human 决策项显式列在文末，避免盲删 ahead≠0 的本地分支——这是审计类文档的最佳实践。
  6. GitHub PR-merge 后自动清理远端 ref 的声明符合 GitHub 默认行为（Automatically delete head branches setting）。
  7. 本 runner 验证一致：

⚠️ Minor Issues（建议修改后再合并）

Issue 1 — 引用了不存在的文件 + 本地 Windows 路径

文件顶部 > **依据**： 行引用：

[v3 报告 §5.4](file:///D:/Projects/Active/math2/docs/REPO_AUDIT_2026-08-25.md) +
[gh CLI 实时 PR 状态](file:///D:/Projects/Active/math2/.agent/REPO_POLICY.md)

问题：

  • docs/REPO_AUDIT_2026-08-25.md 在仓库中不存在（ls docs/REPO_AUDIT* 无输出）。
  • file:///D:/Projects/Active/math2/... 是作者本地 Windows 路径，在 GitHub UI 上不可点击，且对其他读者不可达。
  • .agent/GIT_RULES.md §3 那条引用同理使用 file:///D:/Projects/Active/math2/.agent/GIT_RULES.md。

建议：改为仓库内相对路径或 GitHub blob URL：

> **依据**：[v3 报告 §5.4](../docs/REPO_AUDIT_2026-08-25.md) +
> [gh CLI 实时 PR 状态](../.agent/REPO_POLICY.md)

或如果 v3 报告尚未入库，要么去掉该引用，要么注明"待 v3 入库后回填"。

Issue 2 — docs/INDEX.md 未登记本新文件

最近 #166 commit 专门做了一次"INDEX 全量索引"整理，但本 PR 新增的 docs/BRANCH_AUDIT_2026-08-25.md 未在 docs/INDEX.md 中登记（已 grep 验证）。

建议：在本 PR 内或 follow-up commit 中追加一条索引行（建议按日期归档类分组）：

- [BRANCH_AUDIT_2026-08-25](BRANCH_AUDIT_2026-08-25.md) — PR-4 治理基线 + 执行结果

Issue 3 — A 类表格中 chore/restore-root-gitignore 行注释措辞混淆

| `chore/restore-root-gitignore` (远端) | #167 | 2026-08-25 12:44 | 1/2 | v1 PR-1 已被 PR-167 替代 |

问题：

  • 该分支就是 PR-167 merge 的源分支（commit 8b1c4b0 chore: restore root .gitignore ... (#167)），写"v1 PR-1 已被 PR-167 替代"读起来像是 PR-167 是另一个分支在替代它。
  • 注释栏的意图大概是"PR-1 (v1) 已经合并为 PR-167 的内容"，但表述不清。

建议：改为""v1 PR-1 的源分支 = #167 内容本身；本地保留待合入 #169 后一并清理"`，或直接删除该行（已在 PR header 中说明 #167 MERGED）。

Issue 4 — ahead/behind 数据是快照，未标注时效性

E 类分支的 ahead/behind（1/5、2/28、3/33）会随 main 推进而失真。本文件本身是 2026-08-25 的快照，但未在表头注明"数据时点 = 2026-08-25"。

建议：在 E 类表格前加一行小字：

> 数据采集于 2026-08-25；ahead/behind 数字随 main 推进会变化，仅供当下决策参考。

Issue 5 — fix/preflight-windows-cmd-length 行 "1/0" 解读不明

| `fix/preflight-windows-cmd-length` (本地+远端) | #168 | 2026-08-25 12:56 | 1/0 | **新发现**：本会话合并引入 |

问题：1 ahead / 0 behind 在 squash-merge 后正常——分支 tip 不在 main 的祖先链上（squash 把 N commits 压成 1 个新 SHA）。但 feat/adi-mcp-causality 写 35/13、feat/phase3.9-batch5 24/11 同样是 squash-merge 后状态，口径不一致会让读者疑惑。

建议：在 A 类表格上方加方法论说明：

> ahead 数字 = 分支独有 commit 数（squash-merge 后分支 tip 不在 main 祖先链上，因此 ahead ≠ 0）；
> behind = main 比分支多出的 commit 数。

🤔 可选改进（不阻塞）

  • 执行验证章节 可补一条 git fsck --no-dangling 的实测输出（零输出 = OK）作为可审计证据，而非仅说"执行后验证"。
  • Human 决策项可补充"建议响应 SLA"（如 7 天内不回复 = 视为保留），避免 E 类分支长期挂在本地。
  • PR-3 分支：chore/golden-failures-cleanup-2026-08-25 状态是"远端已 push / 等 Human Owner 开 PR"——可加一句"PR-3 计划编号待定"避免后续混乱。

审查维度（Level 1 checklist）

维度 评价
代码层 N/A（docs only）
清晰度 ✅ 决策矩阵 + 三段记录结构化
重复 ✅ 无冗余
可维护性 ⚠️ Issue 1/2/3 影响长期可读性
测试覆盖 N/A
接口/数据 ✅ 不改接口、不动数据
可审计 ✅ 引用 .agent/GIT_RULES.md §3 三段记录
黄线合规 ✅ 显式声明 git branch -d（非 -D）+ 不 --force

最终结论

⚠️ 建议修改后合并——5 项 minor 都不影响本次 PR-4 的执行正确性，但：

  1. Issue 1（死链 + 本地路径）是必须修的（GitHub UI 渲染问题 + 引用不存在文件）。
  2. Issue 2（INDEX 未登记）建议在本 PR 内补一条。
  3. Issue 3-5 可在 follow-up commit 修复。

合并后请记得按本文件 §"PR-4 治理成果 → 本地保留 → chore/branch-governance-2026-08-25"的备注，本 PR 工作分支 merge 后删。

Fix Issue 1 (死链+本地路径) →
Fix Issue 2 (INDEX 未登记) →
· PR #171 · branch: chore/branch-governance-2026-08-25

@Thy985
Thy985 merged commit 10cbf4b into main Aug 25, 2026
7 checks passed
@Thy985
Thy985 deleted the chore/branch-governance-2026-08-25 branch August 25, 2026 23:13
@Thy985 Thy985 mentioned this pull request Aug 25, 2026
Merged
6 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@Thy985