ship-workflow

交付工作流

通过授权端点交付，并遵循仓库当前的检查、必需的评审、分支保护和合并策略。常规交付是默认方式。可执行程序负责 Git/提供方变更、日志记录、协调和清理；助手负责范围、逻辑变更分组、仓库惯例，以及诊断不熟悉的故障。

参考文件

文件	内容	加载时机
references/commit-planning.md	清单、逻辑提交计划和本地门禁数据包	创建提交或请求本地/逐提交验证时
references/lifecycle-contract.md	显式策略、保障、发布、堆栈数据包、日志和恢复	提供 --policy 或 --stack-plan、恢复操作或解读阻塞项时
references/project-detection.md	仓库门禁源检测	查找本地测试命令时；版本/变更日志表格不授权发布工作

工作流

1. 确定范围

恰好选择一个目标：--pr N、--branch NAME、显式堆栈、已保存的运行，或能够唯一确定目标的当前分支。根据提供方/Git 信息确定有歧义的目标或基准；只有在这些信息无法判定时才询问。--repo [HOST/]OWNER/REPO 指定 PR 基础仓库，--head-repo OWNER/REPO 指定分叉仓库的头部命名空间。

请求	端点
“交付它”、“/ship”、“完成 PR 12 并清理”	clean（默认）
“合并它”、“合并 PR 12，但保留分支”	--until merged
“创建 PR”、“推送并创建 PR”	--until pr
“检查 CI”、“PR 12 有什么阻塞项”	--until pr --dry-run（仅检查）
版本、变更日志、标签、发布、软件包发布或部署	使用独立的发布权限，不属于此技能

执行变更前说明目标、端点和清理范围。恢复操作会保留已保存的权限。pr 仅确认已发布；merged 还会确认已合并，并执行适用的合并后验收；clean 还会添加基于证据的清理。保留活跃、脏、受保护/默认/发布、未合并、依赖未关闭 PR 以及状态未知的工作。绝不隐式扩大堆栈选择范围或恢复操作的端点。

2. 通过可执行程序检查

从已加载技能中客户端报告的绝对目录解析 <skill-dir>。在目标仓库的检出目录中运行：

uv run --no-project --python 3.12 python "<skill-dir>/scripts/ship.py" --pr 12 --dry-run
uv run --no-project --python 3.12 python "<skill-dir>/scripts/ship.py" --inventory

需要 Python 3.12+、Git 和已通过身份验证的 gh。缺少前置条件时状态为 BLOCKED；不得手动运行生命周期流程作为替代方案。检查不会写入对象、引用、钩子、锁或日志，也不会获取或修剪数据。使用字面的 argv 列表，为路径和由仓库控制的值加引号，并将数据包和 PR 正文放在仓库外的私有临时目录中。

3. 执行常规推送

对于合并策略明确的现有 PR：

uv run --no-project --python 3.12 python "<skill-dir>/scripts/ship.py" --pr 12 --until merged

使用所有适用的当前检查，包括非必需任务，以及服务提供方要求的检查发布者、当前头部审查和保护规则。检查待处理或失败时，不得合并。缺失或无法访问的证据不算通过。服务提供方严格要求的当前基线检查仍具有权威性。显示名称重复很常见：工作流、事件、发布者、任务和当前尝试共同确定证据；推送结果仅针对头部，不能替代 PR 合并上下文结果。较新的尝试仅在针对同一逻辑任务时取代较旧的证据。服务提供方当前的任务 ID 决定成员关系：部分重新运行可能会沿用较早尝试中的不同同名任务。不要为满足此控制器而重命名任务或更改工作流。

明确指定 --policy 可消除实际歧义：仓库的合并方法惯例、预期任务清单、合理说明的跳过项／仅针对头部的检查、记录在案的合并后命令、受保护引用，或有意不配置 CI 的仓库。按照生命周期参考中的说明，将其绑定到当前头部／基线（schema 1）或发布（schema 2）。空 CI 需要有来源依据的 ci_free 决策；绝不能根据任务缺失推断。

常规保障不要求签出日志证明或不可变的操作固定版本。仅在有要求时，才在明确策略中使用 assurance: "high"，或使用所选技术栈节点的决策。此选项要求提供生命周期参考中所述的更强签出／提交父级证据。绝不要默默降低已保存运行的保障级别；旧版运行或不兼容的源代码更新必须因等待明确的迁移／策略决策而停止。

4. 推送前验证本地工作

对于存在未提交更改的工作，请遵循提交规划参考：列出每项处置方式，拟定逻辑分组草案，使用 --draft 和 --gates 编译，保存打印出的计划，然后执行 --plan。保留合理的现有提交和保留的工作；绝不要为了满足前置条件而暂存、重置、盲目添加或丢弃工作。

对于发布，如果可能创建 PR，请同时提供 --title 和 --body-file。通过计划或 schema 2 绑定解析其指定的基线。重用完全匹配的 PR，而不是创建重复项。发布准备交接在 pr 阶段结束。

请求的本地门禁会在推送前于隔离的干净签出中运行，并有各自的截止时间。发布和堆栈重放使用 --gates；如果每个待推送／重放的提交都必须通过门禁，请在门禁数据包中设置 per_commit: true。现有仓库钩子仍会正常运行。不要安装或覆盖 pre-push 钩子，不要在推送期间运行耗时验证，也不要引入停止／验证／恢复协议。

控制器会在发布前冻结并验证重放提案。明确遭拒后，如果输入未变，则会重用完全相同的拟议提交对象，并在再次执行受保护的推送前重新验证。调用方不得预先设置 GIT_COMMITTER_DATE。结果未知时，操作保持待处理状态，并在进行任何后续变更前根据当前事实重新协调。

5. 按父节点优先发布现有堆栈

加载已注册的 stacked-prs 配套技能，并检查拓扑、切片边界、来源信息和原生成员关系。缺少配套技能时，结果为 BLOCKED。编写一个明确的 --stack-plan 计划包：只选择获得授权的 PR；将所有祖先和相关依赖项作为上下文纳入；注明未更改的来源信息以及每个所选节点的合并策略。除非要求高保证，否则采用常规节点保证。

uv run --no-project --python 3.12 python "<skill-dir>/scripts/ship.py" --stack-plan /tmp/ship.X/stack.json --dry-run
uv run --no-project --python 3.12 python "<skill-dir>/scripts/ship.py" --stack-plan /tmp/ship.X/stack.json --gates /tmp/ship.X/gates.json --until merged

控制器会验证每个独立切片，保留作者、消息和尾注的字节内容；使用精确的预期旧值 force-with-lease 发布重整后的堆栈；仅在确认父节点已落地后才更改目标分支，并要求针对新上下文重新检查。未选择的开放祖先节点会触发范围决策。只有确认落地后才进行清理，绝不因合并请求已提交就清理。

GitHub 原生选择会在最高的已选成员上发起一个受保护的异步请求，绝不手动合并，也不使用备用晋级方式。提供方可以对保留的上层成员执行变基；必须披露这一影响，并要求控制器验证树和切片。加入队列不等于落地；该请求只保护最高已选成员的头部，不会以原子方式保护所有较低层成员。

错误处理与恢复

结果	操作
PLANNED	报告检查结果；未进行任何更改
COMPLETE	仅报告已达到的端点
WAITING	报告待处理事实；恢复返回的已保存运行，否则重复只读检查
NEEDS_JUDGMENT	解决所指出的策略、范围、来源信息或失败归属决策
BLOCKED	报告实际的前置条件、保护措施或失败；保留已确认的事实

仅使用返回的 run_id 和 --resume RUN_ID 恢复；绝不自行编造。重试前，先核对状态不确定的推送、PR 创建、目标分支更改、合并和删除操作。合并后命令失败或必要清理未完成，意味着已合并但未完成，并非成功。对于由更改本身导致的 CI 失败，在范围内修复；继承而来的失败、权限问题和保护措施问题仍是阻塞项。绝不绕过保护、使用管理员合并、放宽检查要求或请求审查机器人介入。

当传输层阻塞信息仅包含操作标识符时，使用 last_gate.reason 或经过净化的 diagnostic 说明等待原因。注明有限的监控截止时间以及任何最低派发时段。若发布预览中的命名基础分支尚未解决，应将其作为需要 NEEDS_JUDGMENT 阻塞项的 resolve-base 操作，而不是可执行的推送/PR 计划。

CI 问题保持只读。对于明确要求等待的情况，在有限的外部截止时间内运行 gh pr checks N --repo owner/repo --watch --interval 10 --fail-fast，然后再次运行控制器检查。仅靠监视器无法证明检查适用、当前基础分支、审查策略或状态为 GREEN。

输出

传达实际回执字段：端点、PR URL、已确认的提交/合并、实际执行的检查和本地门禁、已删除/保留/清理失败的目标及原因、可用的检出内容、阻塞项和确切的后续操作。PLANNED/COMPLETE 的退出代码为 0，WAITING 为 3，NEEDS_JUDGMENT 为 4，阻塞/输入错误为 2 或 5。解析错误或预写入日志错误可能不会包含运行及其他回执字段。堆栈未完全处理、队列中仍有待处理项或清理未完成，都不算成功。常规发布不会更改版本、变更日志、标签或发布信息。