用途与实际影响
这项功能怎样使用
为什么需要它
目录名、旧文档和缓存路径都可能过期；多工作树仓库里，另一个临时目录的未提交修改或无上游状态，也可能被误算到当前目标。这个入口既核实真实仓库身份，也能只判断点名的工作树，同时把其他工作树作为证据保留下来。
举个实际例子
比如我问“E:\GitHub总索引这个目录最后会推到哪里？”系统会现场对照 Git 共享目录、origin 与 GitHub 上的仓库身份，告诉我目标是否确实是公开的 wlyaaaaa/github-local-index、默认分支是不是 main，以及当前工作区和远端是否同步。目录名即使相同，只要 origin 对不上，就只做定位排查，绝不继续写。
最后我会得到什么
得到这次要改的真实仓库和远端、正在使用的目录是否有别人修改、分支是否落后，以及能否安全开始。它只帮我认准目标，不自动给出提交或发布许可。
正常时
项目目录和远端身份都确认后，说明这次没有仓库层阻碍；实际修改仍按本轮授权。
发现问题时
有并发修改、分支落后或目标不对时指出应先处理的文件与分支。
入口不可用或证据不足时
远端暂时读不到时可继续安全的本地工作，推送和发布结论须等真实远端证据。
从哪里开始
在 AI 项目对话中点名一个仓库，要求“先检查能否在这里改或发布”；需要最新远端引用时再明确提出。
需要准备什么
- 目标仓库或工作树
- 要改动或发布的分支
- 是否需要刷新远端引用
从开始到拿到结果
- 1
核对正在使用的工作目录
AI 检查指定仓库这份目录的修改、关联分支和目标远端，避免把其他目录的状态混进来。
- 2
做入场检查
读取未提交改动、上游和已知远端；只有需要真实领先落后时才刷新引用。
- 3
说明可做范围
交回当前阻碍和下一步；只是只读元数据的结果不能证明远端已经同步。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
项目入场事实入口可用；实时元数据、远端引用和精确目标已有回归关键规则与设计选择
普通已知仓库的可逆小改可只用 git status（Git 状态命令）；Admission（仓库准入检查） 不是固定打卡。
准备创建但远端还不存在时，不拿要求远端已存在的普通 Admission（仓库准入检查） 伪造 identity；先走受保护的空 PRIVATE（私有） 创建，再回来做 live Admission（仓库准入检查）。
只需要 GitHub 可见性时用 LiveMetadata：它会联网读取 GitHub 现场元数据，但不会执行 git fetch，也不会刷新远端跟踪引用。
需要真实 ahead/behind（领先/落后提交数） 时用 RefreshRefs；准备发布判断时用 ForPublication 同时要求两类 live 证据。
TargetWorktree/TargetRef 只改变顶层 transport 判断，其他工作树仍保留在 evidence 中。
decision=block 关闭依赖不足证据的写入和直接 transport，但不关闭只读诊断。
Git命令失败、超时或无法完整读回时是证据未知，不是自动证明remote（远端仓库）或身份冲突。普通dirty只说明未提交内容，不能代替Execution Owner（施工责任）的活动施工登记。
本模块用到的名词
- evidence_source（证据来源）
- 分别标出 local Git、GitHub metadata（元数据） 和 remote（远端仓库） refs 是 live、cached 还是 unavailable。
- freshness（综合新鲜度）
- 三类来源全 live 才是 live；只现场读取一部分为 mixed；都未刷新为 cached。
- decision（入场结论）
- proceed、warn 或 block，描述事实充分程度和本地风险，不等于授权。
- push_decision（传输建议）
- 根据 dirty、behind、diverged（本地与远端双向分叉）、upstream（上游分支） 和 remote（远端仓库） mode 给出 transport readiness。
- target scope（目标范围）
- 精确到一个 worktree（Git 工作树）、branch（分支） ref 或 40 位 commit；目标冲突或多义时失败关闭。
专业定义
当路径、远端、公开属性或同步状态会改变做法时，先给这个项目做一次精确现场体检。
解决什么
单仓库判断同时依赖本地 `.git`、GitHub metadata（元数据） 和 remote-tracking refs。把它们混成一个 `fetch=true` 黑盒会让调用者不知道什么是现场、什么是缓存；只聚合所有工作树又会让无关临时目录阻断精确目标。
当前怎样实现
- 入口先规范化 owner/name；显式 RepoPath 或 TargetWorktree 可作为定位提示，但最终必须回读 remote.origin.url 与 git-common-dir。
- 无显式路径时可读取 ignored（已被版本控制忽略） 私有导航 cache；cache 候选 identity 不符时丢弃，并返回 remote_mismatch 或 bootstrap_required。
- visibility（公开或私有属性） 只接受 PUBLIC（公开）、PRIVATE（私有）、INTERNAL；非法值或 unknown（未验证） 都进入 blocking reasons。
- LiveMetadata 调用 GitHub metadata（元数据） 且 never fetch；RefreshRefs 才执行 `git fetch --prune origin`；ForPublication 同时要求两者成功。
- 顶层 evidence_source、freshness（证据新鲜度） 与 live_checked 明示 local_git、github_metadata、remote_refs 的来源，异常记录只保留类别和 exit code。
- New-ProjectAdmissionRecord 让正常和异常路径保持同一 schema（数据结构），不因 internal_error 丢字段。
- Get-ProjectPrivateCompanion.ps1按已确认repo与RepoPath读取现有私有配套登记，区分mapped、unregistered、registered_unmapped和conflict；只返回匹配路径/链接/恢复关系元数据，不扫描其他项目、不读正文、不创建文件或网络请求。进入项目或公开前按需读取已找到的最近规则，私有配套仍由原Owner管理。
执行流程
- 1
规范化预期 repo identity 和可选 target
- 2
解析候选路径并回读 `.git` origin/common-dir
- 3
枚举全部 worktree（Git 工作树） 并读取 branch（分支）、HEAD、upstream（上游分支）、dirty 和 sync
- 4
按调用模式读取 live GitHub metadata（元数据） 和/或刷新 refs
- 5
计算默认分支整合、branch（分支） inventory 与治理 registry（登记清单） 命中
- 6
限定 decision worktree（Git 工作树），生成 reasons、decision 和 push guidance
- 7
调用者结合项目规则、候选内容和授权决定下一步
边界
- V1 不输出 publication_decision，也不扫描实际候选内容
- push_decision=proceed 不授予 edit、commit、push 或公开发布权限
- 不靠项目名称硬编码治理例外；只读精确 artifact/retention registry（登记清单）
- 无 target 时保留全 worktree（Git 工作树） 聚合兼容语义
- 异常输出不回显外部命令 stderr 或秘密值，只保留稳定错误类别
失败与恢复
- repo、路径或 origin identity 无法唯一确定
- decision=block；读取 `.git`、remote（远端仓库） 和 Owner 证据继续定位。
- LiveMetadata 或 RefreshRefs 失败
- 加入 live_evidence_unavailable，ForPublication 保持 block，不把缓存冒充现场。
- target worktree（Git 工作树）/ref 不存在、冲突或不可用
- 返回精确 target reason，不退回任意工作树。
- PUBLIC（公开） 工作树命中敏感路径
- block 并给出 resolve_public_exposure；pure delete 和安全 rename 按实际目标判断。
- 任一可达 worktree（Git 工作树） 检查失败
- worktree_inspection_error 失败关闭；其他只读诊断仍可继续。
真实入口
E:\GitHub总索引\tools\Get-ProjectAdmission.ps1CLI（命令行工具）、模式参数、私有导航与稳定异常输出
E:\GitHub总索引\tools\GitHubIndex.Core.psm1Admission（仓库准入检查） record、worktree（Git 工作树）、branch（分支）、target 与 push guidance 核心
E:\GitHub总索引\docs\contracts\git.project-admission.mdv1 schema（数据结构）、新鲜度、target 与失败语义
E:\GitHub总索引\tests\Test-ProjectAdmission.ps1真实 Git fixture 和失败关闭回归
E:\GitHub总索引\docs\private-companion-discovery.md精确配套发现、读失败与实际身份冲突分层；Get-ProjectPrivateCompanion.ps1为现行入口
如何验证
- 2026-08-29 完整运行 Test-ProjectAdmission.ps1，exit 0，并以 `All project admission tests passed.` 收口；这是历史源码回归，不冒充本次现场。
- 2026-08-31 对 github-local-index 直接运行 ForPublication：schema（数据结构） v1、freshness（证据新鲜度）=live、live_checked=true、PUBLIC（公开）/main、HEAD=origin/main=806b668…、clean、0/0、decision=proceed。
- 测试覆盖正常/异常记录同 shape、visibility（公开或私有属性） 闭集、LiveMetadata never fetch、RefreshRefs、ForPublication 和兼容 Fetch。
- 真实 fixture 覆盖 primary、linked、detached（分离提交状态）、prunable、no-upstream、ahead、behind、diverged（本地与远端双向分叉） 和 inspection failure。
- target fixture 验证无关工作树不会污染顶层判断，但仍完整出现在 worktrees evidence。
与其他模块的关系
它是总账落到单个项目的现场入口；Worktree（Git 工作树） Sync 解释它怎样判断分支完成，Publication Gate 再解释为什么 transport 仍不等于公开。