用途：在 Git 仓库出现 detached 或矛盾 HEAD、worktree 元数据损坏、分支锁冲突、引用缺失等异常时，提供分阶段、低风险的恢复流程，避免扩大影响范围。
主要能力：先对 .git 做快照，再按症状路由到对应 playbook；提供非破坏性修复计划生成、验证清单和可丢弃的回归测试环境。核心规则包括：先快照、优先非破坏性修复、把 .git 当生产数据、手动改 .git/HEAD 前先用 git symbolic-ref、每次修复后先验证再继续。
使用方式：先运行 bash scripts/snapshot_git_state.sh . 采集诊断信息，再按 references/symptom-map.md 路由症状，用 bash scripts/guided_repair_plan.sh --repo . 生成非破坏性命令计划，应用最小匹配 playbook，最后跑 references/recovery-checklist.md 验证门。可用 --list 或 --symptom phantom-branch-lock 显式路由。回归测试用 bash scripts/regression_harness.sh，单场景加 --scenario orphaned-worktree。
适用场景：worktree 列表出现不存在路径或零哈希、分支被 worktree 占用无法删除、意外 detached HEAD、unknown revision 或 cannot lock ref 等。
限制：手动修复 HEAD 仅在备份 .git 后作为最后手段；验证门要求 git status 无致命错误、symbolic-ref 与目标分支一致、worktree 列表无缺失路径和零哈希、git fsck 无新增严重错误，否则升级为归档 .git、重新克隆并用 reflog 与 cherry-pick 恢复未推送工作。