Prepare project handoff

Prepare Project Handoff

核心合同

把 handoff 当作“针对当前 requested decision，从持久化事实恢复足够且可证明的判断能力”。证据闭合就停止，不把聊天摘要或平台记录当作当前事实源。

始终遵守：

1. 默认只读。不得因调用本 Skill 修改项目、创建 .handoff/、写平台记录，或执行 commit、push、stash、checkout、reset、清理工作区。
2. 用户指令、适用的 AGENTS.md / CLAUDE.md 和当前任务合同高于本 Skill；在宣布 sufficient、给建议或生成 prompt 前，完整读取所有适用的项目指令。
3. 按事实类别确定 authority；文件名、mtime、篇幅、Git tracked 状态、摘要和记录 metadata 都不能单独证明权威性。
4. 冲突影响当前任务、allowlist、写权限或 verdict 时，停止受影响结论并请求裁决；其他已验证结论可继续。
5. 不读取或回显 secret。默认机械 Git/audit 采集只包含 branch、HEAD、upstream、ahead/behind 和路径级 staged/unstaged/untracked/conflicted；navigation 不读取 diff 正文。只有当前决定的 required evidence 明确依赖改动内容时，才按第四步的只读 bounded diff 例外工作；不得借 handoff 扩大读取或写入范围。
6. 对话中的 handoff 默认直接发给用户。只有用户明确要求落盘时才按项目授权写文件，并在写前后复核边界。
7. 最终答复必须自包含；不要要求用户回看 commentary 才能理解结论。

第一步：定位根目录与 requested decision

确定实际项目根目录；多个候选无法唯一确定时，只做安全定位并询问一个必要问题。根目录确定后，在读取任何 bundled reference、运行 audit 或调用 provider 前，先用有界的 AGENTS.md / CLAUDE.md 定位并完整读取当前 scope 适用的项目 instructions。不要先审计、后读 instructions、再重复审计。

把用户当前需要的判断路由为：

• navigation：接手、看看、现在在哪、状态说明、普通 Host handoff；
• focused_discussion：讨论一个明确问题，不进入实现边界；
• investigation：保留现象、假设/排除项和下一条判别探针；
• execution_boundary：继续实现，或生成包含任务语义的执行 prompt；
• current_verdict：用户明确要求验收、接受/拒绝 candidate、pass/fail 或是否完成。只问当前 changed path、diff 或工作区状态不是 verdict：状态说明走 navigation，诊断原因走 investigation。

裸“继续”只有在明确、有效、已授权的 active objective 存在时才继续该目标；否则先走 navigation。安全歧义只问一个必要问题。

普通 navigation / locator_only 内联 pack

普通 navigation / locator_only 只用本页内联 pack 闭合，并依次取得：applicable instructions 全文；root 与当前角色；authority/current-state/decision owner；live root/Git/workspace；影响 navigation 的 conflict。task 仅作为 locator，不自动全文读取。该 pack 闭合后停止，不完整读取 references/progressive-recovery.md，也不得只为填模板完整读取 reference。

升级 decision 与 progressive reference

以下 trigger 要求对 reference 作全文完整阅读，并完整读取 references/progressive-recovery.md：升级为 focused_discussion、investigation、execution_boundary 或 current_verdict；生成 task_boundary；生成 12 段 full rendering；使用平台记录；处理 freshness/invalidation；执行行为评测；或处理 migration/rollback。decision 无法按本页规则安全路由时也须完整读取。若本轮只是校验/初始化 authority map，同时完整读取 references/authority-map.md。

第二步：运行只读审计

运行：

python3 <本 Skill 目录>/scripts/audit_project.py --root <项目根目录>

审计 JSON 是 mechanical index：它报告 authority map 状态、结构化 Git/workspace 和有界候选发现，不决定用户 intent、current task、handoff readiness 或产品语义。

同一稳定 root/HEAD/workspace/authority snapshot 下只运行一次审计并复用结果。首次结果 exit 0 且 snapshot 未变时，禁止第二次运行相同 audit；工具输出截断也不能靠重跑补救，只能定向读取尚缺的 required source 或 live atom。读取 reference、authority/current-state 文件、平台 metadata/summary/raw index 都不使该 audit snapshot 失效；需要在 lookup 后确认 current Git 时，复用 audit 的 structured Git evidence，或只跑缺失的定向 Git probe，不重跑整个 audit。只有 root 或相关 live/authority 状态真实变化、前次结果 partial/error 影响 required claim 时才允许重跑，并说明触发项；不要用相同命令重复“确认”。审计完成后只读它路由到的声明来源；除非 applicable instructions 或 required source 仍未定位，不再用全仓 find / rg --files 重建同一清单。

退出码：0 表示审计完成，2 表示 authority map 无效，3 表示根目录或参数错误；map 缺失本身不是错误。

把 task/goal/spec/任务书的存在只当 locator，不自动全文读取。只有当前 requested decision 依赖任务语义，或将输出任务目标、allowlist、禁项、stopline、gate、执行/验收动作时，才升级并闭合完整 task dependency pack。

第三步：解析 authority 与当前控制面

按以下顺序处理：

1. .handoff/authority.json 有效：按 map 的 category、sources 和 resolution 工作。
2. map 缺失：检查项目说明中的明确声明；只有 scope 清楚、来源存在且无相反声明，才标记为本轮“项目已声明但未持久化”的临时关系。
3. map 缺失且声明不清：列出候选和理由，询问最小必要问题；不得替用户决定产品或治理语义。
4. map 无效：报告具体错误；修复或用户裁决前，不基于该 map 宣布当前状态。

优先读取适用 instructions、入口、governance、current-state/decision owner 和 live Git/workspace。审计候选只是定位索引，不是阅读队列。

若 current-state 明示阶段未冻结、当前无 active task 或同义状态：不按编号、mtime 或候选排序猜任务；只读关闭当前 decision 所必需的文件，并把下一步收束为裁决、欠账或工作区协调。

需要创建或修订 authority map 时，先在对话中给出候选；只有用户明确授权才写 .handoff/authority.json，随后重新审计。完整 schema、隐私和冲突规则见 references/authority-map.md。

第四步：闭合当前 evidence pack

普通 navigation 使用内联 pack，闭合后停止，不为该路径完整读取 reference。升级 decision 时，先按上面的 trigger 完整读取 references/progressive-recovery.md，再按该 reference 收集 required evidence，并记录每个 claim 的 authority | index | live role 与 fully_read | section_read | indexed_only | not_read 状态。

硬门：

• navigation 闭合后停止；active task 保持 locator。
• 一旦讨论开始输出任务边界，升级到 execution_boundary。
• 调查转修复或裁决时，重新计算相应 pack；调查证据不自动授权实现。
• TASK 未闭合前：task-specific advice=0、task-boundary prompt=0、mutation=0。必须全文读唯一 task、直接 Mandatory Sources、allowlist/禁项/stopline/gates，并通过 Fresh Gate。
• VERDICT 未闭合前不下 current verdict。必须读裁决合同和 required sources，并取得与当前 root/HEAD/workspace/environment 相称的 live diff/test/build/runtime proof。

当 investigation、execution_boundary 或 current_verdict 的 required evidence 明确依赖改动内容时，先完整读取 applicable instructions；其中 execution/verdict 还须先闭合相应 TASK 或 VERDICT scope，才允许对明确相关或 allowlisted path 执行只读 bounded diff，审阅当前 unstaged/staged diff，并为 candidate/base/Oracle 取得必要的 current content proof。不扩大到无关路径，不把 diff 正文无必要地复制到 final；遇到 secret/credential 时停止回显并只报告结构化风险。读取 diff 不授予 mutation，current verdict 不能因默认路径级采集而无法闭合。

Required evidence 不因时间、context 或工具预算下降；不足时缩窄 decision 或输出 insufficient/missing/trigger。Optional 读取必须先说明未回答问题、expected decision change 和 required/optional 分类；说不清就不读。

第五步：按需使用平台记录

调用任何 provider helper 或读取任何 Session/memory/summary/file-history locator 前，必须先全文读取 references/progressive-recovery.md；只读本节摘要不能执行 lookup。读取 reference 不使既有 audit snapshot 失效，lookup 前后都不得为此重跑相同 audit。

只有 current_state_owner_missing、用户点名精确 Session、需要定位旧 claim 来源、或 report 缺 evidence locator 时，才进入 platform lookup。控制面已足够时平台记录读取为零。

• 精确 ID先调用 exact_session_metadata，不先扫 memory 或全局 history；metadata 后按具体 unanswered question 选择最窄 provider capability：

exact_session_metadata
  -> 按具体 unanswered question 选择最窄 provider capability
     -> touched file/path requested
        -> file_history_locator
        -> current Git status
        -> bounded diff for located relevant path
     -> formal source / old claim origin requested
        -> optional_short_summary
        -> minimal_raw_window only when concrete gap + expected decision change remain

• touched-path branch中，optional_short_summary 不能替代 touched-path provenance；file_history_locator 始终是 role: index，不是所有 exact-ID request 的无条件读取。找到 path locator 后立即停止 provider 扩读，返回 current Git status，并只读 located relevant path 的 bounded diff；不能把历史 Session 归属冒充当前 ownership；
• 无精确 ID：先用 project memory index 缩小 candidate，再查 candidate metadata；
• summary 可选且始终 index-only；raw window 只有具体 gap 和 expected decision change 时才最小化打开；
• metadata 不得返回 message/display/prompt/tool output/content 正文；restricted/secret surface 立即停止；
• 任何 Session、memory、report、file-history 都不能关闭 current claim；找到 repo owner、正式文件或 live probe 后立即返回；
• provider 或 touched-path capability not_found / unavailable / restricted 是局部不可用：不以 summary 补造 Session provenance；可以独立报告 live Git 当前观察，但不能反向宣称其证明该 Session touched path。缺失的 requested evidence 进入 limitation 与 missing / trigger，且不阻断其他 repo/live 证据。收到 provider-level missing 结果就结束 lookup：不再查 summary/raw/file-history，不重跑已经完成的 audit，立即复用已保存的 repo/live evidence 生成结果。

详细双路由、result、stop 和 privacy 合同见 references/progressive-recovery.md。不得把 provider-specific 私有字段固化为公共 schema，也不得建立 cache、persistent read ledger 或 production parser。

第六步：生成结果或 handoff

每一个 final 都必须输出短而自包含的 recovery capsule，四字段原子呈现；无论答案多短，都不得用 prose、handoff 字段或项目 reliability 代替：

recovery:
  requested_decision: navigation | focused_discussion | investigation | execution_boundary | current_verdict
  evidence_sufficiency: sufficient | insufficient
  reason: "证据为什么足够或仍不足"
  missing:
    - requirement: "缺少的 evidence atom"
      trigger: "何时补读、重验或请求裁决"

missing: [] 只在 required pack 闭合时允许。项目自己的 ready / conditional / blocked 与 recovery 分栏；execution_boundary=sufficient 不代表 implemented/tested/accepted，current_verdict=sufficient 不授予 mutation。

handoff payload 独立选择：

• none：用户没有要求交接提示词；
• locator_only：普通 Host handoff；只含 root、role、authority/task locator、live Git 重验提醒、known unknown 和第一安全动作；
• task_boundary：只有 TASK pack 闭合后，才可包含任务目标、allowlist、禁项、stopline、gates 或下一执行动作。

默认直接在对话中给短提示词。固定 12 段 full handoff 仅在用户明确要求“完整 handoff”或已知 consumer 依赖时渲染；模板不授权额外读取，每个 claim 仍受当前 decision pack 约束。

关闭前自检

确认：

• 没有把候选、摘要、report、memory 或 raw Session 当 authority/current proof；
• 没有混淆 discussed、specified、implemented、tested、host_verified、integrated、committed、pushed、user_accepted、closed；
• 没有遗漏 relevant dirty/conflict、未跟踪文件、ahead/behind、detached/non-Git 或 live proof 缺口；
• task payload、执行建议和 verdict 都已通过各自硬门；
• 没有未经授权写入、网络访问、secret 读取或 scope escape；
• final 自包含，新 Session 能从正式文件和 live evidence 独立复核。