项目收口
“收口”不是整理得更漂亮，而是证明未来的人能找到真实入口、理解边界、验证结果并从失败处恢复。
不可越过的边界
- 默认只读检查源码和状态，并在对话中交付报告。项目已有验证命令可能生成缓存或忽略产物；运行前先说明，运行后核对其归属。用户要求严格零写入时不要运行会落盘的验证。
- 只有用户明确要求保存时，才更新目标项目已有的说明文件。
- 不自动提交、推送、打标签、删除产物或清理用户工作区。
- 不把 Agent 实现的代码描述成用户能独立解释或复现的能力。
- 先读取目标项目的
AGENTS.md或等价规则；它高于本 Skill 的一般建议。
收口步骤
1. 定位真实边界
确认目标路径、软链接最终位置、真实 Git 根、当前分支和外层仓库。可先运行：
python3 scripts/inspect_project.py /path/to/project --json
完成标准：能区分“目录路径”“真实路径”“Git 根”和“工作区容器”，且没有把外层脏文件归到错误项目。
2. 建立项目地图
读取 README、AGENTS、状态/交接文档、入口脚本、配置、关键实现和最近 Git 历史。用白话回答：
- 解决什么真实问题；
- 数据或操作从哪里进入；
- 关键文件分别负责什么；
- 真实产物在哪里；
- 哪些是用户判断，哪些由 Agent 主要实现。
完成标准：不是技术栈清单，且每个重要结论都有可定位文件或命令证据。
3. 核对入口与产物
找到实际可运行入口、前置条件、配置来源、输出目录和不应提交的运行产物。入口说明与代码不一致时，以真实代码和运行结果为准，并记录文档漂移。
完成标准：至少有一个入口命令和一项真实产物被核对；没有产物时明确标记“尚未成形”。
4. 分层验证
先判断项目已有验证是否会生成缓存、日志或运行产物，再运行低风险自动化；根据风险选择真实 HTTP、浏览器、数据库、设备或文件重开验证。不要把单元测试、端口监听、模拟器或 Mock 数据扩大解释成完整验收。
完成标准：报告逐项写明“已运行、通过/失败、覆盖边界、未覆盖边界、生成了哪些可忽略产物”。
5. 记录失败恢复
列出已知失败、可观察症状、真实原因、恢复命令/入口、需要外部条件的部分和不可自动恢复的部分。
完成标准：未来使用者能区分“可以重试”“要先修复条件”“必须询问用户”。
6. 核对 Git 与交付范围
检查未提交、已暂存、忽略文件、最近提交和远程；不触碰无关改动。若用户要求提交，先按目标项目规则总结并再次核对暂存内容。
完成标准：所有未提交文件都被解释为本轮、用户既有或未知，不混入运行产物。
7. 交付收口报告
按 报告模板 在对话中输出。只有用户要求保存时才写入既有 README、STATUS 或 handoff 文件；不要擅自新建重复说明。
完成标准：报告能回答入口、产物、验证、失败恢复、Git 状态、未完成项和下一次最小动作。
停止条件
目标路径不明确、仓库根存在争议、验证会改变外部状态、需要登录/付款/真实设备或工作区包含无法归属的改动时，先完成其余只读检查，然后明确请求缺失条件。不要用“看起来完成”结束。
平台差异见 platform-notes.md，依赖状态见：
python3 scripts/doctor.py --json --branch git-project
