Merge remote-tracking branch 'origin/master' into docs/pj2026-02-terminal-spec

.agents/skills/unidesk-subagent/SKILL.md

@@ -15,6 +15,7 @@ description: UniDesk 主代理调度子代理的必读技能。用户提到子
   - 发现衍生问题时，只能创建独立 issue 或记录待办，不得扩大当前 prompt、PR、合并范围或验收前置；
   - 现有机制阻碍原始目标时，先寻找既有架构内的最小实现路径；确需架构扩展时，必须向用户说明与原始目标的关系并取得明确授权。
 - 执行型和调研型委派默认优先使用 AgentRun `Artificer`：
+  - Artificer 的 `create task`、`apply` 和 `dispatch` 必须以下文“子 issue + MDTODO”登记为 fail-closed 前置；禁止先创建 task 或派单再补登记；
   - 未显式选模时，不由主代理注入客户端模型默认值；使用 owning AipodSpec 的默认模型，当前为 `gpt-5.6-sol`，默认 reasoning effort 为 `medium`；
   - Artificer 的 API credential：
     - 只允许由 UniDesk owning YAML 将 `/root/.codex/auth.json.pika` 与 `/root/.codex/config.toml.pika` 投影为 `gpt-pika` SecretRef；
@@ -37,9 +38,10 @@ description: UniDesk 主代理调度子代理的必读技能。用户提到子
 - 纯文档交付可以按 `$git-spec` 的稳定分支快路径由主代理直接 commit/push，不要求临时 branch、`.worktree` 或 PR；发现本地分叉、并行改动、分支保护或运行面影响时必须保留状态并回到隔离交付。
 - 正式 GitHub issue/PR/comment/merge 仍走 `$unidesk-gh`；子代理可以提交 PR 和写调查结论，主代理负责 review/preflight/merge，除非用户明确授权某个子代理自上线自验证。
 - 主代理和子代理必须通过 issue/PR/comment 链接传递可复用上下文、调查结论、证据链接和下一步边界；派发前先读既有评论，prompt 中只引用链接和增量任务，不复述长结论，避免不同子代理重复调查同一事实。
-- 主代理派发执行型子代理前必须完成两项登记：
+- 主代理派发任何执行型子代理前必须完成以下登记；对 Artificer，全部步骤必须早于 AgentRun `create task`、`apply` 和 `dispatch`：
   - 创建子 issue，把主要任务、接续上下文、目标分支/worktree、范围、禁止项和验收入口写入正文；
-  - 使用 `$mdtodo-edit` 将子 issue 链接登记到对应泛化问题域的 MDTODO ITEM 或 SUBITEM；不得为单个 issue 创建窄范围 MDTODO FILE。
+  - 使用 `$mdtodo-edit` 在对应泛化问题域的 MDTODO ITEM 或 SUBITEM 中登记子 issue 链接，并把任务标记为进行中；不得为单个 issue 创建窄范围 MDTODO FILE；
+  - 任一登记缺失或写入失败时不得创建 AgentRun task；派单后补写 MDTODO 不计为合规登记。
 - 子代理 prompt 只给子 issue 链接和极短边界，不塞大段任务正文。每个执行型子代理维护自己的子 issue 和评论作为接续上下文；主 issue 评论区只由主代理写入主线 anchor、阶段汇总、调度决策和最终 closeout。
 - 子代理不得把过程日志、单步证据、长调查和 post-task 反馈直接堆到主 issue 评论区，只能在主 issue 需要可见时由主代理引用子 issue/PR/comment 链接。
 - 主代理跟踪子代理进度时优先读取子 issue 评论区、关联 PR 更新和 bounded issue/PR 状态；不要为了普通进度查询主动 `send_input interrupt` 打断子代理主线。只有子 issue/PR 长时间无更新且只读 worktree 也无推进时，才进入问询、关闭和重开流程。
@@ -70,7 +72,7 @@ description: UniDesk 主代理调度子代理的必读技能。用户提到子
 - CI/CD、rollout、PipelineRun、Argo closeout：`$unidesk-cicd`。
 - WebProbe、Workbench、浏览器复测：`$unidesk-webdev`。
 - 子代理完成后的反馈收口和反馈 issue 判定：`$post-task`。
-- 需要 MDTODO 记录和执行-审查循环时再用 `$mdtodo-loop`；不要把普通 GitHub PR 并行工作强行塞进 MDTODO。
+- Artificer 和其他执行型子代理派单前的任务登记必须使用 `$mdtodo-edit`；只有用户明确要求多轮审查或循环修复时才使用 `$mdtodo-loop`。
 
 ## 何时读取 reference
 

.agents/skills/unidesk-subagent/references/gh-workflow.md

@@ -1,4 +1,4 @@
-# GitHub Subagent Workflow
+# GitHub 子代理工作流
 
 本 reference 记录 UniDesk 主代理调度子代理、并结合 GitHub issue/PR 的稳定工作流。它约束的是协作方式，不替代 `$unidesk-gh` 的具体命令参数，也不替代各业务 skill 的验收标准。
 
@@ -35,6 +35,11 @@
 ## GitHub Issue 协作
 
 - 大任务先有 GitHub issue 或在既有 issue 中补并行计划：列出子任务、负责人/子代理、目标分支、预期 PR、验证入口、依赖关系和哪些任务可并行。
+- Artificer 派单采用 fail-closed 登记顺序：
+  - 先创建子 issue，冻结目标分支、工作区、范围、禁止项和验收入口；
+  - 再使用 `$mdtodo-edit` 在泛化问题域 MDTODO 中创建或更新 ITEM/SUBITEM、登记子 issue 链接并标记进行中；
+  - 只有上述写入成功后，才允许 AgentRun `create task`、`apply` 或 `dispatch`；
+  - 缺少 MDTODO FILE、任务项、进行中状态或子 issue 链接时不得派单，派单后补写不算合规。
 - 主 issue 评论区由主代理独占维护：只写主线 anchor、阶段汇总、调度决策、已采纳结论、下一批边界和最终 closeout。子代理不得直接在主 issue 评论区堆过程、日志、单步证据或 post-task 反馈；需要让主线可见时，由主代理在主 issue 引用子 issue/PR/comment 链接。
 - 主代理派发执行型子代理前必须先创建子 issue，不能把主要任务正文直接塞进 subagent prompt。子 issue 标题应能反映父 issue、运行面/模块和子任务；正文必须引用父 issue、目标分支/worktree、允许范围、禁止范围、验收入口、模型/思考等级选择理由和当前接续链接。子代理的调查、单步证据、阻塞、post-task 和后续接力评论都写在自己的子 issue 或关联 PR 中。
 - 子代理 prompt 只传子 issue 链接、模型要求和“不写父 issue 评论区”等极短边界；不要在 prompt 里复述长任务、历史结论、日志或完整证据。主代理通过观察子 issue 评论区跟踪进度。
@@ -75,14 +80,15 @@ Prompt 至少包含以下字段，按任务裁剪：
 
 1. 建立计划：列出可并行任务、串行依赖和每个子代理交付物。
 2. 为每个执行型子代理先创建子 issue，把任务正文写进子 issue。
-3. 同时派发低耦合子任务；prompt 只引用子 issue 链接和极短边界；共享契约先派一个基线任务。
-4. 轮询子代理结果：子 issue comment、PR、验证摘要、阻塞。
-5. 对每个 PR 做架构 review、bounded diff、preflight 和必要本地验证。
-6. 按依赖顺序合并；合并后同步目标 worktree。
-7. 触发受控 CI/CD 或让明确授权的子代理上线；主代理核对 closeout。
-8. 用原入口复测；把剩余问题拆到新 issue 或追加既有 issue。
-9. 对每个已完成或已纠偏完成的子代理发送 post-task 收口要求，读取其已判断 feedback；主代理只挑选适合工程化的项转正式 FEATURE/BUG issue，并优先派回原子代理执行。
-10. 主代理 post-task：长期参考、清理已吸收 worktree；不代替子代理做 feedback 池去重。
+3. 使用 `$mdtodo-edit` 把子 issue 登记到泛化问题域 ITEM/SUBITEM 并标记进行中；登记失败时停止派单。
+4. 同时派发低耦合子任务；Artificer 的 `create task`、`apply` 和 `dispatch` 均只能发生在 MDTODO 登记之后；共享契约先派一个基线任务。
+5. 轮询子代理结果：子 issue comment、PR、验证摘要、阻塞。
+6. 对每个 PR 做架构 review、bounded diff、preflight 和必要本地验证。
+7. 按依赖顺序合并；合并后同步目标 worktree。
+8. 触发受控 CI/CD 或让明确授权的子代理上线；主代理核对 closeout。
+9. 用原入口复测；把剩余问题拆到新 issue 或追加既有 issue。
+10. 对每个已完成或已纠偏完成的子代理发送 post-task 收口要求，读取其已判断 feedback；主代理只挑选适合工程化的项转正式 FEATURE/BUG issue，并优先派回原子代理执行。
+11. 主代理 post-task：长期参考、清理已吸收 worktree；不代替子代理做 feedback 池去重。
 
 ## 无响应接续