用途与实际影响
这项功能怎样使用
为什么需要它
同一仓库可能在多个文件夹里同时有人工作；只看眼前文件夹干净，会漏掉其他目录没保存的修改和只存在那里的提交。
举个实际例子
比如我问“这个功能分支已经推了，算完成吗？”它即使和自己的远端分支完全同步，目标提交也可能还没进入 origin/main。系统会直说“默认分支还缺这些提交”，而不会因为功能分支自己推成功了就冒充交付完成。
最后我会得到什么
得到每个工作目录仍有什么未提交修改、哪些分支已进入远端主分支、哪些目录有唯一内容要保留。清理只是候选，系统不会自动删。
正常时
所有相关目录和远端主分支都查清时，说明哪些工作已合并、哪些仍在使用。
发现问题时
某处还有未保存修改、独有提交或未进入主分支时保留它，不宣布整仓已交付。
入口不可用或证据不足时
目录或远端暂时读不到时不猜同步状态，更不删除可能是唯一副本的文件。
从哪里开始
在 AI 项目对话中说明哪个分支或工作树想收口，要求检查默认分支是否真正收到修改。
需要准备什么
- 仓库和目标提交或分支
- 保留中的其他工作树
从开始到拿到结果
- 1
找全同仓库的工作目录
AI 查看每份工作目录的未保存修改、关联远端分支和只存在本地的提交。
- 2
比较默认分支
判断目标提交是否进入真实远端默认分支，识别仍需整合或有唯一内容的分支。
- 3
决定后续动作
给出可保留、待整合或待复查项；删除候选仍需确认没有活动使用，不因当前目录干净就清理其他工作树。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
工作树与远端默认分支收敛检查可用关键规则与设计选择
behind 或 diverged（本地与远端双向分叉） 时先 update/reconcile 并复查，不能直接 push。
detached（分离提交状态） HEAD（游离提交）没有一个可以设置 upstream（上游）的当前分支；此时明确返回 choose_branch_or_refspec，先选择分支或显式 refspec（推送目标映射），不误导用户设置不存在的上游。
dirty 时只允许显式限定候选，不能 `git add .` 吞入其他任务。
分支对自身 upstream（上游分支） 同步但缺于远端默认分支时，仍需 integrate default branch（分支）。
已被默认分支吸收且无保护的 clean 残留只成为 retirement candidate，不自动删除。
unknown（未验证） 只作删除前瞬时保护；无法查清 owner、独有内容和依赖时 closeout 必须 BLOCK。
已登记的副机安全备份分支与制品按其恢复用途核对，不强迫当普通feature并回main；身份、分支用途和实际恢复完整性各自有来源。
本模块用到的名词
- sync_state（同步状态）
- in_sync、ahead、behind、diverged（本地与远端双向分叉）、no_upstream 或 unknown（未验证），只描述 HEAD 与 upstream（上游分支）。
- integration_state（整合状态）
- default、merged_ancestry、patch_equivalent、unmerged 或 unknown（未验证），描述 HEAD 相对远端默认分支。
- patch equivalent（补丁等价）
- 提交哈希不同，但同一补丁已经以另一提交进入默认分支。
- prunable（可修剪记录）
- Git 记录了一个已不存在或失效的 worktree（Git 工作树）；它仍是异常证据，不自动视为 clean。
- necessary retention（必要保留）
- 当前确有消费者的固定工作树例外；条件漂移后立即失效。
专业定义
提交真正进入远端默认分支才叫交付；没查清是否有独有内容，就绝不删工作树。
解决什么
Git 的“同步”至少包含工作文件、当前 upstream（上游分支） 和默认分支整合三层。任何一层被省略，都会把未提交、只推到 feature、patch-equivalent 或残留 worktree（Git 工作树） 混成一个模糊的“已同步”。
当前怎样实现
- `git worktree list --porcelain` 枚举全部工作树；每个存在路径单独回读 HEAD、branch（分支）、upstream（上游分支）、ahead/behind（领先/落后提交数） 和 NUL-delimited（以空字符分隔） status。
- dirty summary 分开计 staged、unstaged、untracked 和 conflicted，文件名含中文、空格或换行也不误解析。
- local_root 优先取 git rev-parse --show-toplevel 的真实根目录，精确 TargetWorktree 保持调用目标；从子目录进入不会把子目录误登记为根。失败 errors 保留 category/exit_code，并可附最多3行、512字符的诊断；含疑似凭据或控制字符的正文省略，但不吞掉原错误和阻断。
- fetch_attempts 明示0/1/2次；LiveMetadata（只读远端元数据）保持0次。只对已观察到的退出128与 TLS EOF 做一次同参数重试，不重试 push，不改代理、TLS、认证或凭据配置。
- 默认分支完成证据只接受 `refs/remotes/origin/<default>`；远端 ref 缺失就 unknown（未验证），不回退同名本地 branch（分支）。
- branch（分支） inventory 枚举无 worktree（Git 工作树） 的本地 refs 和 remote-tracking refs；用 ancestry 与 `git cherry` 区分 unmerged、merged_ancestry 和 patch_equivalent。
- artifact governance 只对 exact repo/ref 生效；必要 retention 必须同时匹配 repo、绝对 path 与 HEAD，并带 Owner、用途、exit condition。
- frozen_history 保留冻结仓库的非默认 refs 与独有提交，不回灌默认分支，也不把它们当普通清理候选。
执行流程
- 1
枚举 common-dir 下全部 worktree（Git 工作树） 与 refs
- 2
逐工作树读取文件状态、upstream（上游分支） 和 ahead/behind（领先/落后提交数）
- 3
刷新后读取远端默认分支 HEAD
- 4
比较每个 HEAD 与默认分支的 ancestry、距离和 patch equivalence
- 5
附加 exact governance、historical retention 与 necessary retention
- 6
生成整合、复查、保留或可退役结论
- 7
删除前由任务 Owner（任务责任方） 再确认没有活动依赖或唯一内容
边界
- retirement candidate 不等于删除授权，也不证明没有运行中消费者
- locked、prunable、dirty、ahead、普通 no-upstream 或证据矛盾不能被 snapshot 规则压掉
- 普通未来 branch（分支） 不因名称模式自动成为专门 Owner 或历史保留
- 未证明前不得 gc、prune 或删除内部 checkpoint（续作检查点） refs（检查点引用）与 unreachable objects（不可达对象）
- 项目业务决定 merge、rebase、PR 或 release 方式；总索引只提供 Git 事实
失败与恢复
- 任一可达 worktree（Git 工作树） status 或 refs 检查失败
- 该状态为 unknown（未验证），并阻止依赖它的收敛/删除结论。
- 远端默认分支 ref 不存在
- 不退回本地 main；标记 default_branch_integration_unknown 并刷新/补证。
- branch（分支） ahead+behind
- push_decision=block、strategy=reconcile_then_recheck。
- 已整合残留仍有 lock、dirty 或必要 retention
- 保持 evidence 和警告，不列为自动清理。
- retention path 或 HEAD 改变
- exact match 失效，恢复普通 dirty/sync/retirement 判断。
真实入口
E:\GitHub总索引\docs\contracts\git.worktree-sync.md全部 worktree（Git 工作树）、默认分支完成与必要保留合同
E:\GitHub总索引\tools\GitHubIndex.Core.psm1worktree（Git 工作树）/status/branch/default integration 实现
E:\GitHub总索引\config\git-artifact-governance.jsonexact governance、frozen history 与 retention schema（数据结构）
E:\GitHub总索引\tests\Test-ProjectAdmission.ps1多 worktree（Git 工作树）、branch（分支） inventory 与 retention fixture
如何验证
- 2026-08-29 完整 Admission（仓库准入检查） 回归 exit 0，覆盖本模块的 worktree（Git 工作树）、branch（分支）、default-ref、target 和 retention 路径。
- 测试 fixture 真实创建 primary、linked、detached（分离提交状态）、prunable、ahead 与 no-upstream 工作树。
- 回归覆盖 remote-only branch（分支）、已推送但未进默认分支、merged ancestry、patch equivalence 和 retirement candidate。
- registry（登记清单） 测试验证 missing/wrong schema（数据结构）、重复 ref、未知 override 和不完整 retention 全部失败关闭。
- 2026-08-29 两个 PUBLIC（公开） 仓库现场均确认 main/default integration=default、0/0，但 dirty 仍单独保留为 warning；这是历史现场。
- 2026-08-31 github-local-index 的 live Admission（仓库准入检查） 回读唯一 main worktree（Git 工作树） 为 clean、0/0、integration_state=default、missing_default_commits=0；本次未重跑多 worktree（Git 工作树） fixture。
与其他模块的关系
它把 Admission（仓库准入检查） 的 worktrees/branches 证据解释为真实收敛状态；Publication Gate 在此基础上继续审查候选内容和授权。