| name | delivering-delegated-linear-issues |
| description | 当用户要求从 Linear 领取、处理、批量清空或定时扫描带 `Delegated to Agent` 标签的 issue，讨论默认交付方式、ready PR、本地 master、Agent 状态标签或定时扫描会话归属时使用。 |
Linear 委派交付
核心合同
把 Linear 标签分成用户意图与 Agent 运行状态两类，禁止混用：
| 标签 | Owner | 含义 | Agent 权限 |
|---|
Delegated to Agent | 用户 | 该 issue 允许由 Agent 自动开发 | 只读；Agent 永不自动添加或删除 |
Delivery: Local Master | 用户 | 显式确认默认的本地 master 交付，兼容既有筛选与审计 | 只读；不是本地合入的必需条件，单独存在也不构成开发授权 |
Agent: Queued | Agent | 等待领取或已显式要求重试 | 可替换为下一状态 |
Agent: Claimed | Agent | 某个 Run 已领取并正在处理 | 可替换为下一状态 |
Agent: Blocked | Agent | 本次处理停止，等待输入或环境恢复 | 保持到显式重试 |
Agent: Delivered | Agent | 已完成本轮交付 | 持久保留 |
Linear 原生状态与 Agent: * 标签是有意冗余：原生状态服务团队流程，Agent 标签提供稳定、可过滤、可审计的自动化状态。一个 issue 最多只能有一个 Agent: * 标签；Agent 第一次写入后不得把状态清空，只能在一次完整标签更新中替换为下一状态，并保留全部其它标签。
下文把用户明确要求 ready PR、禁止本地合并或不得修改本地 master 统称为“PR 例外说明”。
- 有
Delegated to Agent 且没有相反交付说明：默认在满足全部硬门后 fast-forward 到干净的本地 master；不 push、不建 PR。
- 只有存在 PR 例外说明时，才改走 ready PR 路径；PR 不自动 merge。
- 更具体的用户交付说明始终覆盖默认值；若用户既禁止本地合入，也禁止或没有授权 push / PR，且指定方式无法形成受支持的独立交付，必须退回澄清，不得擅自扩权创建 PR。
Delivery: Local Master 只显式强化默认交付意图，缺少该标签不得成为降级到 PR 或拒绝本地合入的理由。- 所有交付模式都不授权 release、deploy、migration、远程配置/密钥/生产数据修改或其它不可逆外部动作。
- 用户直接点名 issue 并要求处理时，本轮指令可替代
Delegated to Agent；除非同时存在 PR 例外说明，否则仍默认交付本地 master。Agent 不得替用户补加或删除两个用户标签。
- Linear 保存任务意图、状态和交付记录；仓库与 PR/commit 保存实现结果。本 skill 只编排两者，不复制项目开发规范。
- 实现与验证必须使用
nextclaw-delivery-workflow；提交前的 release notes 与迭代记录判断继续遵守项目现有 owner。
状态合同
| Linear 状态 | Agent 状态标签 | 含义 | 自动扫描动作 |
|---|
Todo | 无 Agent: * 或 Agent: Queued | 新委派或显式重试，等待领取 | 有 Delegated 时可进入预检 |
In Progress | Agent: Claimed | 某个 Run 正在处理 | 跳过 |
Todo | Agent: Blocked | 已退回，等待用户补充或显式重试 | 跳过 |
In Review | Agent: Delivered | 已交付，等待人工审核 | 跳过 |
| 任意 | 任一非 Queued 的 Agent: * | 已有 Agent 状态 | 跳过并按恢复规则核对异常组合 |
Todo | 任意，且无 Delegated | 未进入自动委派队列 | 跳过 |
Done / Canceled / Duplicate | 任意 | 已终止 | 永不自动领取 |
Delivery: Local Master 不改变领取资格，也不再负责选择交付路径；它是对默认本地交付的可选显式确认。新委派可以暂时没有 Agent 状态；一旦被 Agent 处理，就必须持续保留一个 Agent: * 状态。
第一版只允许一个活跃队列执行者，所有 issue 串行处理。批量处理表示清空一次扫描得到的队列快照，不表示并行开发。
入口与队列选择
人工触发
- 指定 issue：只处理用户点名的 ID。用户要求实现或处理时，该指令构成本轮授权并默认交付本地
master；存在 PR 例外说明时改走 PR 路径。两种情况都不改用户标签。
- 用户要求只调查或只给方案时，不扩大到代码交付，也不进入 claim、不改状态或标签，除非用户另有明确要求。
- 批量触发：读取
Todo + Delegated to Agent +（无 Agent 状态或 Agent: Queued）；按优先级从高到低、同级从旧到新排序。
- 用户明确说“只处理 Urgent”时再增加 Urgent 过滤；Urgent 表示顺序，不表示授权。
- 用户明确要求重试
Agent: Blocked 或重新处理 Agent: Delivered issue 时，先核对上一 Run 已停止，再把 Agent 状态替换为 Agent: Queued，按新 Run 重新领取。
定时触发与会话归属
- 用户只说“定时扫描”“每隔 N 小时扫描”或等价话术时，默认创建绑定当前会话的 thread heartbeat automation，让后续唤醒继续进入当前会话并继承同一任务上下文；不得默认创建每次运行都产生独立会话的 standalone cron automation，也不为这个默认值额外追问。
- 只有用户明确要求“每次新会话”“独立任务运行”或等价语义时，才创建 standalone cron automation。
- 创建或更新自动化后，必须回读确认 automation kind、target thread、周期和启用状态；同一扫描目标已有自动化时优先更新，禁止 heartbeat 与 cron 重复并存。
- 默认团队为
NextClaw，只扫描 Todo + Delegated to Agent +（无 Agent 状态或 Agent: Queued）。
- 自动化 prompt 可以追加 priority、project、team 或单次最大数量，但不能放宽标签授权门。
- 自动化 prompt 必须保持本 skill 的默认交付合同：除非存在 PR 例外说明，成功后 fast-forward 到干净的本地
master。
- 一次唤醒先冻结 issue ID 快照；处理期间新加入的 issue 留给下一次唤醒。
- 不配置多个重叠定时任务。Linear 普通读写没有可靠的原子租约，第一版不声称支持多执行者竞争。
领取前预检
先只读调查，不因描述短就直接退回：
- 读取 issue 的标题、描述、评论、附件/截图、关系、项目、标签、状态和已有 PR/分支线索。
- 检查仓库指令、相关代码、历史实现和可复现环境；从证据中补全根因假设与可观察验收条件。
- 检查 Git 工作区、目标文件是否有用户 WIP、远端/PR 权限以及必需工具是否可用；不得输出 secret。
- 判断任务能否形成单一、内聚、可验证的交付。
- 默认按本地
master 路径预检：定位实际持有 master 的 worktree，确认其 staged、unstaged、untracked 都为空，并冻结当前本地 master SHA。只有存在 PR 例外说明时才跳过这项本地集成预检。不得自动 fetch、pull、stash、reset 或用远端覆盖本地分支。
满足以下条件时直接推进：
- 通过 issue 与仓库调查能够形成单一、可验证的交付目标；
- 剩余不确定性只需要低风险、可逆且符合现有规范的判断；
- 不需要标签授权之外的外部副作用；
- 用户 WIP 可以通过隔离 worktree 完整避开；
- 默认本地
master 路径还要求集成 worktree 当前完全干净。
issue 提到越界动作时，不要因此放弃可独立交付的代码部分。用户明确选择 PR 时可跳过本地 merge、release、deploy 并继续交付 ready PR；默认本地路径只能执行本 skill 明确授权的本地 fast-forward，仍跳过远程合并、push、release、deploy 和 migration。
出现以下情况时退回，不猜测实现：
- 存在两个会实质改变产品结果的方向，证据无法裁决；
- 任务依赖用户未提交且语义重叠的 WIP；
- 缺少仓库、权限、账号、密钥、真实环境或可验证成功的路径；
- 当前交付本身无法形成独立价值，成功只能由未授权动作证明；
- 多个独立目标无法作为一次交付统一验收；
- 默认交付所需的本地
master worktree 不干净、无法定位，或其真实状态无法安全确认；不得擅自降级成 PR 来绕过阻塞。
预检阻塞也要通过领取竞争确定唯一 winner，再由 winner 把 Agent: Claimed 替换为 Agent: Blocked 并写退回评论，避免每次定时扫描重复报告。
领取与幂等
真正开始前生成稳定 Run ID，并重新读取 issue：
- 确认仍满足
Todo + Delegated to Agent +（无 Agent 状态或 Agent: Queued），或仍属于用户本轮明确点名的 issue。
- 搜索该 issue ID 对应的活动 claim、分支、commit 和 PR；已有交付时复用或归一化状态，禁止重复创建。活动 claim 是只有领取评论、尚无同 Run ID 的交付/退回评论。
- 写一条带 Run ID 的领取评论，短暂等待 5 秒后重新读取评论。
- 若竞争窗口出现多个活动 claim，以 Linear 服务端
createdAt 最早者为 winner；时间相同时以 comment ID 字典序最小者为 winner。
- loser 只追加一条同 Run ID 的领取取消说明并立即退出，不改状态、标签或仓库；无法判定唯一 winner 时所有执行者都停止。
- winner 把 Agent 状态替换为
Agent: Claimed，把 Linear 状态改为 In Progress，再回读完整状态、标签集与 claim；无法确认时立即停止，不开始修改仓库。
领取时按“显式例外优先”冻结交付模式：issue 正文、评论或本轮指令存在 PR 例外说明时选择 PR；否则选择本地 master。更具体的其它交付说明优先，无法落入受支持路径时退回。Delivery: Local Master 的有无不改变这个判断，清晰的当前文字说明优先于该标签；若多个用户说明互相冲突且无法确认当前意图，必须退回而不是猜测。运行中标签变化不得自动改变本 Run 的交付模式；新的用户明确说明必须重新读取并按其权限收窄或重新确认。
领取评论只写可审查事实：
### Agent 已领取
- Run：<稳定 ID>
- 目标：<一句话>
- 验收：<可观察条件>
- 交付：<ready PR；不自动合并 | 本地 master fast-forward；不 push、不建 PR>
- 未授权：release / deploy / migration / 生产操作
领取取消评论只写：Run <ID> 领取取消；此任务已由 Run <winner ID> 领取。 不删除或改写其它执行者的评论。
领取时禁止擅自：
- 创建子 issue、修改父子关系或合并 issue；
- 标记
Duplicate / Canceled；
- 修改 priority、assignee、issue 正文或用户标签；
- 批量把尚未真正开始的 issue 改成
In Progress。
更新标签前先读取并保留完整标签集。Agent 只在 Agent: Queued / Claimed / Blocked / Delivered 之间做互斥替换，不得覆盖 Delegated to Agent、Delivery: Local Master、Bug、Feature 等用户标签。发现多个 Agent: * 标签时先停止并按异常状态处理，不擅自猜测真实状态。
隔离开发与验证
- 保留原工作区全部用户改动，不 stash、reset、checkout、格式化或 stage 无关文件。
- 每个 issue 使用独立 worktree/分支，分支名包含 Linear issue ID；不复制用户 WIP。
- PR 路径使用仓库约定基线；本地路径必须从预检冻结的本地
master SHA 建分支，不能擅自改用 origin/master。
- 使用
nextclaw-delivery-workflow 完成调查、方案门、实现、验证、可维护性复核、changeset 与迭代记录适用性判断。
- 只提交当前 issue 的文件；提交信息使用英文。委派授权 commit；只有 PR 路径授权推送交付分支和创建 PR。
- 完成项目规则要求的最小充分验证和用户可见行为验收。仅有 tsc/lint/单测时，不得把功能写成“已验证”。
- 发现邻近问题时只记录，不顺手扩 scope。若它阻塞当前交付，按阻塞流程退回；否则在最终评论列为后续项。
PR 交付路径（显式例外）
- 只有存在 PR 例外说明并且验证闭环后，才创建 ready PR；不把本地合入阻塞擅自降级为 PR，也不为无法验收的半成品自动创建 draft PR。
- 创建 PR 前再次确认 issue 仍为
In Progress + Agent: Claimed，本轮委派授权仍有效，且不存在同 issue 的现有 PR。
- 创建 ready PR 后按“成功收尾”回写 Linear。禁止自动 merge、release 或 deploy。
本地 master 交付路径
本地合入是委派实现成功后的默认受控交付路径，不依赖 Delivery: Local Master 标签，但绝不是绕过验证的“随手 merge”。必须全部满足：
- 交付分支已精确提交，完整必跑验证和功能验收通过。
- 合并前重读 Linear，确认 issue 仍为
In Progress + Delegated to Agent + Agent: Claimed，且没有 PR 例外说明；人工直接授权的等价条件必须仍有效。
- 再次确认实际
master worktree staged、unstaged、untracked 全为空，不覆盖任何用户 WIP。
- 比较当前本地
master SHA 与冻结 SHA：
- 未变化：继续；
- 已前进且交付分支可无冲突更新：在隔离 worktree 将未推送的交付分支更新到最新本地
master，并重新运行全部必跑验证；
- 出现冲突、回退、分叉或来源不明：停止，不猜测解决。
- 在
master worktree 只执行 git merge --ff-only <delivery-branch>；禁止自动 merge commit、squash、rebase master、push 或修改远程 master。
- 确认本地
master 精确指向交付 commit、worktree 仍干净，并从本地 master 运行最贴近真实行为的合并后 smoke。
合并后 smoke 失败属于高风险异常：禁止 reset、强推或隐瞒状态。先在原交付分支做向前修复、重新完整验证，再次 fast-forward 本地 master。若无法安全修复，把 Agent 状态替换为 Agent: Blocked 并保留 In Progress，写明本地 master 已包含的 commit 与人工恢复要求，然后停止整个批次。
成功收尾
成功必须同时满足：
- PR 路径：ready PR 已创建且只包含当前 issue；
- 本地路径：本地
master 已 fast-forward 到交付 commit，合并后 smoke 通过，未 push、未建 PR；
- 必跑验证通过，功能证据与剩余风险已经明确；
- Linear 最终评论、状态和标签都已回读确认。
按以下顺序收尾：
- 写交付评论；
- 将状态改为
In Review；
- 把
Agent: Claimed 替换为 Agent: Delivered，保留 Delegated to Agent、Delivery: Local Master 及其它全部用户标签；
- 重新读取 issue，确认三项都成功。任一失败时不得宣称完整交付。
### Agent 交付完成
- Run：<稳定 ID>
- 结果：<用户可观察结果>
- 交付：<PR URL | 本地 master>
- Commit：<SHA>
- 修改：<主要范围>
- 验证：<命令与结果>
- 功能验收：<真实场景与结果>
- 剩余风险：<无或明确列表>
- 未执行：<merge / push / PR / release / deploy / migration 中的适用项>
永不自动标记 Done。Done 表示人工审核、远程合并或团队约定的后续闭环已经完成。
阻塞与失败
任务特定阻塞不终止整个批次；先安全退回当前 issue，再继续下一个。Linear/GitHub 授权失效、仓库不可用、本地 master 合入后异常或同类系统性故障应停止整个批次，避免重复污染。
合入本地 master 之前退回时：
- 不创建 ready PR，不修改本地
master；若已有验证通过的分支/commit则保留并写入评论；
- 写清已确认事实、阻塞原因和最小所需输入；
- 将状态恢复为
Todo；
- 把
Agent: Claimed 替换为 Agent: Blocked，且不修改任何用户标签；
- 回读确认。用户补充后可把 Agent 状态改为
Agent: Queued，或直接指令新 Run 重试。
### Agent 已退回
- Run：<稳定 ID>
- 已确认：<事实与证据>
- 阻塞：<无法安全继续的原因>
- 需要：<一个最小决策、信息或权限>
- 已保留：<分支/commit 或无>
- 重试：改为 `Agent: Queued`，或直接要求 Agent 重试
- 未执行：<代码、PR、本地合入、发布等>
不要只写“信息不足”。先主动调查并说明证据；只有调查后仍存在实质分歧才退回。
若用户在运行中移除 Delegated to Agent，视为撤销自动执行授权：停止新增仓库副作用，写取消事实，将 Linear 状态恢复为 Todo，并把 Agent: Claimed 替换为 Agent: Blocked；不得重新添加用户标签，也不得留下空白 Agent 状态。
恢复与异常状态
- 正常扫描只领取无 Agent 状态或
Agent: Queued 的 issue；Blocked / Delivered / Claimed 都必须跳过。
In Progress + Agent: Claimed 表示可能仍有 Run 活跃；不根据时间自行宣布 lease 过期，也不让第二个 Agent 抢占。- 发现遗留项时，先检查同 Run ID 的评论、分支、commit、PR 和本地
master：已有完整交付则归一化为 In Review + Agent: Delivered；明确已退回则归一化为 Todo + Agent: Blocked；状态不明则只报告，不重跑或重置。
- 若提交、push、PR、合入或评论只完成一部分，先从 Git/PR/Linear 的真实状态恢复，不重复创建任何交付物。
- Agent 状态只由 winner 迁移；loser 和普通扫描不得删除、替换或叠加状态标签。
红旗
- “
Delegated to Agent 是队列锁，完成或失败后应该删掉。”——错误，它是用户标签，Agent 永不自动修改。
- “claim 结束后直接清掉 Agent 标签最干净。”——错误，Agent 状态必须持久化为
Blocked 或 Delivered，不能回到无状态。
- “没有
Delivery: Local Master 就只能建 PR。”——错误；有效委派默认交付本地 master，该标签只是可选的显式确认。
- “默认本地合入意味着可以忽略用户要求 PR。”——错误；ready PR、禁止合并或不得修改本地
master 等明确说明优先，冲突不明时必须退回。
- “用户只说不要合并，所以一定可以 push 并建 PR。”——错误；更具体的禁止项和交付范围优先，未授权的外部副作用不得自行补全。
- “本地合入等同于授权 push 或远程 merge。”——错误，本地路径默认不触碰远程。
- “master 有一点 WIP，可以先 stash 或强行 fast-forward。”——错误，必须退回并保留用户现场。
- “测试通过就可以 Done。”——错误，交付状态是
In Review。
- “批量最快的方式是并行多个 Agent。”——错误，第一版固定串行。
- “描述只有一句，直接退回最安全。”——错误，必须先调查和尝试形成验收条件。
- “更新标签时直接写目标标签数组。”——错误，必须保留完整标签集，且只互斥替换 Agent 状态标签。
- “用户说每小时扫描，所以默认建独立 cron。”——错误；除非用户明确要求每次新会话，否则必须绑定当前会话。
第一版非目标
- 多执行者租约、并发 worktree 或自动抢占恢复；
- 自动拆分/合并 issue、修改优先级、负责人或用户标签；
- 自动 push/merge 远程
master、release、deploy、migration 或生产操作；
- 在 dirty、冲突、分叉或无法验证的本地
master 上自动集成；
- 用 Linear 替代仓库已有开发、验证、提交和发布 owner。
