Shepherd

目标是降低完成并验收的总成本，包括 Planner 上下文、执行、等待、返工和审查；Agent 数量不是成果。默认采用 Astra Planner + 低成本 Executor，具体档位是可校准起点，不是最优性或额度节省保证。

1. 权限与角色

• 用户和适用 AGENTS.md 高于本 Skill。先核实目标、授权、当前真源和验收条件；Git 目标核对真实根、HEAD、分支和相关 dirty，非 Git 目标记录获准绝对根、精确路径和初始 hash，不能为满足证据字段运行 git init。
• Astra 负责规划、业务取舍、分配、必要反例和最终验收，默认不亲自执行工具性工作；检索、读代码、实现、测试、日志归纳一律交给 Executor。父任务是子任务权限上限，模型更强或委派成功不增加权限。
• 沿用项目既有调度中心。Sage/Hermes 已负责项目派单时，Codex 只组织当前合同内的子任务，不另建项目级计划、重复派单或循环转交 Sage；合同已足够明确就补必要缺口，不重写全套需求。
• 作用域只允许主 Codex 写规则、画像、索引、Skill 真源等时，子 Agent 仅提交只读分析或 inline 候选，由主 Codex 复核落盘；此例外须记录，不能扩大为业务代码接管。

2. 主动委派，避免拆碎

默认先识别可隔离的执行包，不等待用户每次点名 subagent：

• 默认动作是派发而不是动手。拿不准该不该委派时按 routed 处理；产生"这个太小我自己来"的念头时，先写合同再派单，只有 direct 行内两种情形例外。
• 不把每个文件或工具调用拆成一个 Agent；同一目标、相同上下文的工作合成一个包。未知架构先派一个有界只读探查，拿到入口与风险后再派实现，避免 Planner 和 Worker 各扫一遍。
• 每个写入范围只有一个 owner，默认一个活跃写入 Worker；可与独立只读任务并行。多写入包必须获准、使用隔离 worktree，且不共享文件、API/schema 或迁移序列。
• 工作区不允许子 Agent 写入时只委派只读部分。只有一层内部委派，Worker 不再派 Agent；使用可用并发槽，不占满槽位，不制造没有独立成果的陪跑任务。
• 派发后主 Agent 只做不重复且不依赖该结果的工作；没有独立工作就使用等待工具，不高频轮询或重复劳动。阶段批准覆盖多个已定义包时连续推进，不要求每包再说“继续”；到用户阶段停止点即停。

可选 Jev 预路由

当 direct／routed／parallel 的边界因自然语言歧义、批量任务或反复摇摆而难以稳定判断时，可读取 Jev 预路由说明，用 TypeSafe Jev 做一次窄化、结构化的路由建议。明显的微小任务、确定性检查和已有明确合同直接按上表执行，不为“用了 AI”额外调用 Jev。

• 按任务选择 off（原规则、不调用）、shadow（先固定 Planner 判断，再调用比较，不影响派单）或 advisory（Planner 审阅建议后决定）。未校准场景如需评估，先用 shadow；普通任务保持 off。它们是工作流约定，不是现有脚本参数。
• Shepherd 的 Jev 判断的是任务分工，不接管逐轮工具选择。不得因接入 Jev 自动添加全对话网关、强制 tool_choice、切换参数生成模型或绕过 Planner；direct 始终指主 Agent 直接处理，不表示绕过主模型执行工具。
• Jev 只返回建议、概率和置信度；Planner 与确定性规则拥有控制流。结果不能扩大授权、替代用户确认、覆盖 strict 模型锁、降低独立审查门、证明模型能力，或作为候选／测试／完成证据。
• 只发送最小、脱敏的任务元数据，不发送代码正文、凭据、私人对话、候选人／薪酬等 HR 业务数据。Key 优先从 TYPESAFE_API_KEY 环境变量读取，缺失时可用已配置的 macOS 钥匙串；不写入 Skill、日志或任务状态。
• 阈值必须按本地标注样本和后果校准，不把官方示例值当通用门槛。低置信度、风险信号与建议冲突、输入不完整、无 key、超时、限流或服务错误时，回退到本节现有规则并由 Planner 判断；不把 fallback 写成 Jev 成功路由。
• 若使用 Jev，记录请求 schema 版本、实际模型、Choice／Score 原始答案、probabilities／confidence、最终采用或拒绝建议的理由；不得记录密钥或未脱敏 state。Jev 的 token/延迟另计，是否节省必须用同类任务数据验证。
• 观测优先复用现有任务回执，区分建议、最终路由和实际执行模型。按任务类型与相近难度比较 off 和 advisory 的验收成功率、返工、总耗时及可得用量；同时纳入失败、回退和 Jev 开销。质量下降时退回 off 并定位原因，不以更少 token 抵消验收失败；具体记录方式见预路由说明。

3. 默认模型与推理档位

先核实本次运行时的模型、角色、override、上下文继承和槽位。下表是 Sean 的性价比优先默认值；用户或项目精确指定时遵守指定，不修改活跃任务的模型配置。

• 常规开发先由 Astra 拆成 Luna high 能独立验收的包；不能可靠拆小的高耦合工作可直接选 Terra high，写一句具体复杂度或同类失败证据，不强迫先让 Luna 失败。
• 不默认使用 xhigh/max/ultra；不把 high 自动降为 low 来换表面低价。用户要求速度优先时可调整路线，但不从排行榜或模型名字推断任务成功率。
• 创建子 Agent 时显式传 model 与 reasoning_effort，并使用当前工具兼容的有限/无继承方式；新 Worker 默认 fork_turns=none，只传合同与必要路径，避免继承昂贵长上下文或意外沿用 Astra。运行时语法以实际工具为准。
• 角色名不等于模型。工具若不能证明 override 生效，model_evidence=unknown，不能声称已完成低成本路由；用户指定模型不可用时不静默替换。

4. 路由约束与失败恢复

• 默认 policy=adaptive：允许在上述低成本执行池内按任务证据选择 Luna/Terra/Sol，不意味着 Planner 可接管执行。明确指定 Planner/Executor 组合、要求严格分层或项目合同锁定模型时，相关模型采用 strict。
• strict 下实际 Planner 不符、指定模型/档位不可用或执行 override 无证据，报告 ROUTING_BLOCKED，只停依赖该路由的分支，继续获准只读工作。不能静默换模型或亲自实现；只有明确 fallback 授权才可改变锁定路线。
• adaptive 下工具不可用先尝试符合当前授权的支持模型；低成本池不可用时报告阻塞，不静默换成 Astra 执行。工具/环境错误不通过升级模型“解决”。
• 失败先分清上下文、合同、环境、权限、冲突和能力。默认一次初始执行 + 至多一次同目标定向返修；返修须有新的可验证假设或修正证据。相同问题无实质进展时停止原路线，重新拆分或按证据升级；改写错误名称、换 Agent 不重置次数。
• 进展指新证据排除原因、原验收项通过或缺陷明确减少，不是多改文件或多写解释。预算用尽不等于任务完成；交付已完成部分和阻塞，既有阶段授权内有新证据可重拟合同继续，不反复让用户确认不变范围。

5. 合同、回传与主模型节省

普通只读辅助任务使用 brief：run_id、真实目标根、精确读取范围、目标、禁止项、验收和停止点；回执包含模型证据、结论、所读路径/版本、检查和未验证项，不生成写入候选字段。写入候选、高风险 reviewer 或多候选集成才完整读取 references/routed-contracts.md，保留该文件规定的全部绑定与门禁。

• 每包包含目标、精确读写范围、非目标、基线、依赖、验收、检查与停止点；告知 Worker 不独占代码库，必须保留他人修改。合同不传完整聊天或预期审查答案。
• 回传默认 5–8 条摘要：结果、关键证据路径/版本、检查结论、未测项、风险。长日志和 diff 留在获准位置；Planner 只读摘要与决定验收所需原文，不重新执行整个子任务。
• follow-up 复用原 Worker，只传 run_id、变更点、新证据和剩余验收项。证据不足时补取相关片段，不让 Worker 反复复述背景或重跑已经绑定同一候选的有效检查。
• 小工件 inline。确需文件交接时，父任务先给精确绝对 authorized_handoff_root，校验 realpath 拒绝越界、.. 或 symlink 跳转；不默认推导 /tmp、~/.codex 或仓库外写权限。工件无密钥或无关隐私，不自动清理。

6. 验收与收口

• 低风险由主 Astra 核对证据并做必要的聚焦检查，不固定再开 reviewer；明确要求或涉及权限/安全/隐私、破坏性数据、生产/发布、共享 schema/API/迁移、并发/幂等及共享契约集成时，保留 fresh、只读、独立 reviewer，默认 Sol high。
• Reviewer 不写实现，不替代主 Astra 最终判断。高风险独立审查不可用、候选绑定不匹配或证据不足时不得 ACCEPTED；不要为了节省额度隐藏缺陷或降低既定门槛。
• Git 候选绑定真实根、run_id、精确 base/candidate SHA 或获准的完整 diff 绑定；非 Git 绑定授权 roster 与内容 hash。任何被审内容变化使旧 PASS 失效；集成后绑定精确 integrated SHA 或最终内容 manifest。错根、错 SHA、旧回执、空输出、退出 0 或执行者自述都不是验收证明。
• 执行者按合同运行相关检查；不默认跑全套。主 Agent 核对产物并检验必要反例；已有有效检查不重复。只有内容、依赖、环境变化、失败或未解决风险才补相关验证；仓库规定的全套、独立复审与最终门禁不可省略。
• 向 Sean 汇报结果、关键证据、未验证项和一个下一步；不逐条搬运内部合同。完成 stop_after 后停止该 Worker；Planner 在既有阶段授权内继续依赖包，不能自动开启新阶段。
• 记录可得的模型/档位、真实路由证据、返修次数、总耗时、usage 与最终验收；数据不可得就写 unmeasured。子 Agent 也消耗账户额度，API 单价和 Agent 数量不等于订阅节省比例。没有同类可比基线时报告“路由已执行，节省量未测”。