ticket-autopilot

Ticket Autopilot

负责：文件夹调度、运行状态、工作树／分支／PR 编排、提供方规范化和受保护的最终处理。不实现工单、评审、QA 计划或声明。

规范的 Ticket Envelope 为 版本 1。验证产物和声明规则属于 verification-audit。

可移植组合

invoke = 内联执行一项技能；compose = 按串行顺序运行多项技能，同时保留各自的责任归属。 delegate = 使用独立的主机工作进程；independent = 已观察到使用独立上下文；parallel = 并发委派。 默认工单执行以内联方式串行组合，且不需要调用 AgentTool。 对于独立工作进程，请应用操作默认设置；记录请求的范围和观察到的隔离情况。

AFK 合约

• 当工单范围内的关卡仍未通过时，继续处理已就绪且无关的 AFK 工作。
• 每次文件夹运行都创建一个隔离的工作树，以串行方式变更一个工单，并为其创建一个分支／PR。
• 仅堆叠单父级链；多父级合并需等待所有父级完成集成。
• 将提供方的 MERGED 视为必要但不充分的条件：推导递归根交付基线，重新获取该基线，并在标记为 integrated 前持久化精确提交头或显式合并对象的祖先关系。
• 绝不虚构凭据、提供方能力、实时证据、审批或合并授权。
• 手动合并需要明确的精确提交头决策；自主合并需要绑定执行者／证据的运行授权。AFK、访问权限和沉默均不构成授权。
• CandidateRef v2 绑定语义树／摘要／版本；单独的版本化记录绑定提供方／PR／基线／提交头／分支沿袭。
• 语义漂移会使所有证据失效；仅沿袭发生漂移时，证据仍有效，但会清除一次性合并授权。
• 工单达到配置的质量重试上限后即停止；继续处理其他已就绪工单。

公共 CLI

新运行使用账本架构 4，并设有质量、交互／工具／时间限制。交互次数默认为 10，其中为 qa-execute 和 verify 各预留一次；未设置的限制会报告为 unavailable。总数无效时，会在创建前失败。

导入目录或引导私有 GitHub 时，请在盘点或发布前加载引导流程；引导权限不授予运行或合并权限。

采用、中止、清理或收集工作树时，请加载工作树流程；符合条件不代表获准删除。

持久化集成后刷新已安装的技能时，请加载本地 Pi 同步；要求单独配置执行者／证据，并报告仍需执行 /reload。

合并 PR、授予／撤销合并权限、迁移仓库权限，或协调已变更的 PR 基线／提交头时，请在操作前加载合并和协调流程。

收到肯定的、针对整个仓库的“merge all”、“merge everything”或“mergia tutto”时：检查 repository-autonomous-merge-status。如果不存在，则使用人工执行者和持久化的肯定消息授予 --scope current-and-future-runs；保留精确的有效授权，并在授权已撤销、属于旧版、格式错误或存在矛盾时拒绝继续。然后调用 merge-all --repo <repository>；绝不要求调用方提供 PR 提交头，也不缩小到单个 PR。疑问、引语、否定表达和身份不明确均不构成授权。合并权限不会解除其他关卡，也不会授权处理冲突内容、发布、清理、wiki 或 Pi。

投影最终跟踪树或恢复精确的源模式关卡时，请在产生任何影响前加载最终树流程。新运行默认使用 --final-tree-mode enabled；投影不等于集成，也不构成授权。 resume <run-id> --events <file.json> 读取 {"schema": 1, "events": [...]}；leaf-result-template <run-id> 会为当前评审、QA 计划/执行或验证阶段预填并输出 leaf-result 事件。每个 schema-3 结果都会绑定确切的 CandidateRef、阶段、资源和规范化的 execution；QA/验证还会添加 schema-1 quality 范围、内容寻址的证据和限制。部分交接只能在同一 CandidateRef 上恢复。语义偏移会启动新的有界周期，同时仅追加历史会保留生命周期总计；同一候选的重试仍处于当前周期。leaf-result 是 leaf 上下文的唯一通道。handoff 技能用于衔接人工会话，不是 leaf 上下文通道。带有 result: "gated" 的 stage 事件以及 Kernel.record_stage(..., reason=...) 必须在变更前提供非空字符串 reason。首尾空白会被去除；剩余原因会按原文持久化，不会生成备用文本。非 gated 结果无需提供原因。切勿在 gate 原因或详情中包含凭据或私密负载。

对于环境阶段阻塞，或对新的人工决策存在不确定性的情况，请加载gate 就绪状态与现有授权。只有在原因已解决后，才能复用有效的现有范围；就绪标签本身不授予任何权限。 对于尚未启动的后续任务上的 post-merge-verification gate，请加载合并后源代码验证：获取新鲜的源代码质量信息，不要重新打开前序任务，也不要绕过实时 gate。

迁移/退役旧版运行、压缩其账本或修复旧版的错误预算耗尽问题时，请加载旧版恢复流程；切勿手动编辑历史记录或绕过实际耗尽。

交付遵循版本化的 PR 正文交接；将 render-required 路由到 explain-pr，并要求在 pr-open 时验证提供方正文/头部的回读结果。

verification-checkpoint 接受预期树、规范化输入和绝对路径的 verification-audit 根目录，随后使用其验证器/归约器。检查点模块负责序列化、哈希、阶段索引和恢复，而不负责证据类别、gate、授权或声明。inspect_verification_checkpoints 无需适配器即可读取可信前缀。缓存键绑定 CandidateRef、leaf 合约、范围、制品、命令和环境；精确命中无需交互，缺失/损坏的条目会重新运行，部分链会继续恢复。

只有 docs-only-adopt 可以绕过 execute-ticket。v1 请求会绑定 Ticket Envelope、摘要、CandidateRef、路径和范围。只有暂存的常规 docs/**/*.md 文件符合条件；工单/Agent/生成的/配置/代码/脚本/混合路径、符号链接、子模块、歧义或偏移都需要 standard-path-required。内容寻址的补丁/类型/Markdown/图检查和链接检查不消耗 leaf 交互，最多推进至 implementation-complete，并会在受保护的交付/精确头部合并前重新检查。

当工单已持久集成，或 wiki 交付需要重试时，请加载 wiki 交付流程。针对确切的头部单独运行 wiki-sync-v1；分别记录失败，绝不继承工单验证或合并授权。

发布或协调 runner 缺陷 issue 时，请加载 issue 发布流程；必须要求其单独授权，而非运行或合并许可。

TICKET_AUTOPILOT_ROOT 是绝对技能根目录，绝不能是仓库工作目录。TICKET_AUTOPILOT_PYTHON 是可在此处运行的 Python 3.10+：Linux/macOS 上使用 python3；Windows 上使用 python 或 py -3，因为 python3 通常是 Store 占位程序。命令界面如下：

"$TICKET_AUTOPILOT_PYTHON" -B "$TICKET_AUTOPILOT_ROOT/scripts/ticket-autopilot.py" --help

命令包括 prepare-zero-to-autopilot、zero-to-autopilot、zero-to-autopilot-status、bootstrap-private-github、sync-local-pi、grant-repository-autonomous-merge、revoke-repository-autonomous-merge、repository-autonomous-merge-status、grant-repository-autonomous-reconciliation、revoke-repository-autonomous-reconciliation、repository-autonomous-reconciliation-status、migrate-repository-authority、merge-all、plan、run、worktree-owner-adopt、worktree-gc-plan、worktree-gc-apply、worktree-sweep、resume、status、post-merge-verify、wiki-delivery-retry-status、retry-wiki-delivery、pause、unpause、grant-autonomous-merge、grant-completion-projection、runner-defect-issue-grant、runner-defect-issue-revoke、runner-defect-issue-status、runner-defect-issue-escalate、approve、abort、cleanup、ticket-hold、ticket-cancel、ticket-reopen-request、ticket-reopen、migrate-run-lifecycle、compact-run-ledger、ticket-parse、ticket-emit、ticket-list、artifact-audit 和 migrate；使用 <command> --help。ticket-list 无需提供方且为只读的 schema 2 命令，会报告处置状态、生命周期、就绪情况/原因、格式错误或重复的工单、依赖缺失和循环依赖。artifact-audit 无需提供方且为只读的 schema 1 命令；它会区分错误、旧版警告、未引用的候选项和迁移工作，且绝不会改写构件。

pause 作用于单次运行。Hold/cancel 操作要求提供身份、原因和持久授权。重新开放流程为请求→人工 approve→应用：它只会使用匹配的已通过门禁，并使从候选阶段到合并阶段的状态失效。审批是持久的人工授权，而非调用方身份验证。提供方/Git/交付边界会重新检查暂停状态、处置状态、源路径和摘要；仍可能发生人工在边界外操作导致的 TOCTOU 问题。

调度器流程

1. 仅接受基线干净的已跟踪工单，或在仓库内被完全忽略的工单。创建快照／工作树之前，遵循 pre-QA coherence：获取 --base <branch>（默认为 main），持久化其身份，并保持本地分支不变。在 Git 公共状态下，从该获取的提交中快照规范内容，并绑定模式／摘要；恢复时绝不重新解析调用方文件。被忽略的完成内容留在 PR 之外，只有另行授权、摘要精确匹配且仅限候选项的规范 done/ 投影例外；源所有权和最终定稿仍由外部负责。
2. 通过规范 CLI 解析；拒绝不支持的架构、重复 ID、依赖缺失和循环。迁移必须显式指定，绝不回退。
3. 确定性地计算就绪前沿。暂停／取消的工单不可调度，且会阻塞后代，但不会级联；HITL 门控不会冻结无须人工介入（AFK）的其他工单。
4. 选择一个就绪工单，并调用 execute-ticket，传入规范化信封、源工件引用、正文、CandidateRef、重试限制和范围，除非明确适用且已验证的 docs-only-adopt。绝不推断仅限文档的资格。首先完成其序列化变更和状态转换。
5. 收到实现和简化结果后，要么保留既定的完整周期，要么在精确满足已启用且已跟踪的资格条件时，持久化并应用 I → D，然后进行最终质量检查。每次 review → qa-plan → qa-execute → verify 变更，都必须针对有效交付目标和当前最终 CandidateRef 进行新的 pre-QA coherence 检查，其中包括已提交 HEAD 的精确记录沿袭。然后按常规完成定稿。拒绝不完整、导入的、过期或不一致的交接；不要重新解释其声明上限。
6. 质量检查通过后，冻结、提交并仅推送工单拥有的文件，然后遵循 PR 正文交接流程。门控失败时予以记录；只有在验证提供方正文／HEAD 后，才记录 pr-open。
7. 将 pr-open 与 integrated 分开记录。常规审批遵循即时且可恢复的 merge critical path v1。在明确获准的自主运行中，每次变更尝试前都要重新确认资格，并沿用同一精确 HEAD 路径，无需逐个 PR 提示。每个集成入口还必须将提供方读回结果和交付沿袭绑定到新的终端 SHA／树，证明精确 HEAD 的祖先关系，或明确提供方合并提交的祖先关系；外部读回保留独立溯源，且不能授权合并变更。如果提供方已合并了不同的单提交 HEAD，只有在记录的、观察到的以及提供方集成的原始转换均非空且逐字节一致时，integrate 才可采纳该结果。仅接受双父合并，且第二个父提交必须是观察到的 HEAD，或是与其基线相同、树相同的独立单父集成副本。终端证明之前，必须持久化并读回带版本的拓扑回执；历史架构 1 的双父回执按原样重放，不得改写。仅凭 Patch ID、仅路径相等、提供方标签、最终树相似度、多提交、常规 squash、队列重写，或路径／blob／模式／父提交偏移，均不合格。
8. 在一次幂等的 delivery 中，执行受保护推送，读回至 pr-open／门控状态，并且仅在集成完成后标记完成。
9. 父工单完成终端集成，或已记录的 PR 基线前进后，reconcile 会根据 Git 树／HEAD 推导状态，仅在树相等时保留证据，归档已被取代的尝试，并在推送前刷新任何前进的目标。无父工单时的基线前进使用交付沿袭；绝不虚构依赖祖先关系。 语义偏移需在新的有界周期中重新验证；提供方变更后拒绝刷新。
10. 只有在 agent-skills 工单已持久完成集成，且存在绑定到独立行为者／证据的本地配置后，才可针对该精确 HEAD 运行 sync-local-pi。本地同步失败应保持可见，不得改写集成状态；绝不推断授权，也不得声称当前 Pi 会话已重新加载。

组件边界

• execute-ticket：负责实现和工单本地质量闭环；不执行提交、推送、创建 PR 或运行状态变更。
• code-simplification、code-review、qa-test-plan 和 verification-audit：作为叶子工作器组合在 execute-ticket 中，而非由文件夹调度器直接调用。
• explain-pr：用于验证通过的交接后，由最终处理阶段调用的确定性 PR 正文渲染工具。

保持调度器变更串行：任何时候，最多只能有一个活动变更影响工单的 CandidateRef，并且只能通过幂等保护调用一次文件夹最终处理器。

对于工作流系列版本发布，运行 scripts/forward_test.py --output <artifact.json>。使用 --list 查看原始场景提示词，但不执行它们。仅将报告视为本地单元／集成证据；对于未通过实时观测验证的提供商或环境行为，报告中记录的限制仍是声明门槛。

最终报告

status schema 2 会公开权威生命周期、结果、就绪状态、门槛、进度、预算／总计、CandidateRef 失效情况、目标身份、QA 前一致性、来源／交付状态、授权和精确头指针。 重复读取只是纯投影：不会追加心跳或消耗预算。open_gates 保留其有序 ID；open_gate_records 按相同顺序添加 {"schema": 1, "records": [...]}。深拷贝的记录包含 gate_id、ticket_id（运行所有者对应 null）、category、scope、kind、state、reason 和现有的 details。已关闭的门槛会被省略。历史 schema-4 通用原因保持原样：不会推断回填、历史重写或批准。

将每张工单报告为就绪、活动中、受阻、审核次数耗尽、PR 已开启、已集成或失败。 包括 PR 链接和观测到的头部 SHA、证据上限、未关闭的人为／提供商门槛，以及下一个未受阻的前沿。不要夸大完成情况。