Long Horizon Task

三模式路由

初次使用或需要了解完整组件版图时，先读 references/architecture.md。

根据调用方式进入对应模式：

1. 发起模式（默认）：/portolan:long-horizon-task 或 /portolan:long-horizon-task <任务描述> → 进入预期对齐与确认协议流程（下方"发起模式"节）

2. continue 模式：/portolan:continue 或 /portolan:long-horizon-task continue <任务目录> → 读 references/continue.md 执行停点续跑规程

3. finish 模式：/portolan:finish 或 /portolan:long-horizon-task finish <任务目录> → 读 references/finish.md 执行换会话终审规程

发起模式

存量检查

先扫 .portolan/*/工作底稿.md，找状态为"准备中"的任务。有则问用户："上次准备到一半的任务 {{任务名}} 还在，继续准备还是新开一个？"

分流

收到任务后先判断：这是长程任务吗？

• 一次能做完、无需多轮迭代的：直接告诉用户"这不需要长程装备"，引导直接做，不走后续流程。但两类任务即使看着小也要继续：含不可逆外部动作的（需要协议管住停点）；全部可回滚且几小时内能完成的（走完摸底后由快速通道决策卡让用户选）。
• 用户直接要"每天自动跑""定时执行"：不直接给 routine。话术："先单次跑通并通过 finish 验收；全自动定时暂不提供，finish 后可以给你一条手动 /loop 或 /schedule 的方案。"标记为"沉淀候选"（记进任务协议单决议记录）后按长程任务继续。
• 确认是长程任务：进入下一步。

通过分流后给用户画路线图：

接下来的流程：我先摸底出草案 → 集中问你一轮 → 确认一份任务协议 → 试跑点火 → 组装命令你来发射 → 正式跑 → 跑完开新会话 finish 验收。你要参与的节点：回答几个关键问题、确认协议、试跑决策、发射（粘贴一条命令）、中间停点会喊你回来 continue、最后 finish。

基础摸底评估·有据可查路径

有仓库、有历史可查的任务走这条路径，按以下六步出草案：

a. 基线盘点

• 仓库结构、可用工具与 connectors
• .portolan/ledger.md 存在则读一下了解历史，不自动匹配同类

b. 起点基线实测

• 任务描述里每句环境断言逐条跑命令验证，记到起点事实表

• 同时记录基线锚点（git 环境记起点 commit SHA；非 git 记受保护文件哈希清单），供 finish 反向断言验证使用

• 正向验收断言在任务起始时已成立 → 必须停下。两种情况：任务已经完成了，或者成功标准写错了。不管哪种，不许开跑，摆事实给用户看

  硬停后给决策卡（不擅自恢复流程）：

  【决策卡】起点验收已成立，下一步怎么走？
  待定事项：正向验收断言当前已成立，任务不能开跑。两种可能。
  为什么现在问：需要你判断是哪种，选完再看后续。
  A. 成功画像写错了 → 回到摸底 b 步重新核对断言与起点事实
  B. 任务本身已完成或该重新定义 → 重新判断是否需要长跑
  回复 A 或 B。
  

c. 拆核心环节

• 把任务拆成可验证的环节，每环节对应一个可核查的产出

外部参考核对（长程任务基础问一次）：任务外部有无 golden patch / 上游权威实现 / 隐藏测试集 / 参考解仓库？若有：

• 写入反向断言 R（"不看隐藏测试、不抄参考解、不联网取上游实现"），起点态标"成立"
• finish 审查 journal 证据来源时按 R 核对

基准类任务（DeepSWE/SWE-bench 等）必问。一般应用类若无外部参考可跳过。

d. 逐环节 eval 可行性评估

• 读 references/eval-design-guide.md，对每个环节做三分流判定：
  • 硬 eval：代码可判——写断言或测试命令
  • 软 eval：需要判断力——写 rubric 存任务目录 rubric.md（执行环不读此文件），finish 时派评审 subagent 判
  • 人工点：必须用户看——标为人工验收点
• 产出可自闭环比例（n/m）——任务自主程度用当场建出的 eval 衡量，不查任何先验评级表
• 迭代价值校验：任务内每轮是否产生新增量？否 → 先看两类例外：含不可逆外部动作的仍走长程流程（协议管住停点）；符合快速通道条件的继续走到 e 步，由决策卡让用户选。两类例外都不符合才中止流程，告诉用户"这个任务不需要长程循环"并给替代建议。沉淀候选任务豁免此校验——其迭代价值体现在"次次都成"的可靠性验证，不按单次产出迭代判

e. 快速通道判定

• 全部可回滚 且 几小时内能完成 → 快速通道候选，出决策卡：

【决策卡】任务够小，要走完整流程吗？
待定事项：这个任务全可回滚、几小时内能完成。
为什么现在问：摸底已做完，可以选择省掉完整流程。
推荐 A（理由：{{按本次摸底实测自主给出，如"关键路径已跑通/改动全在 git 管辖内"；实测有隐患时也可以转而推荐 B，说清为什么}}）
A. 当场做完：我现在直接执行，做完当场跑验收给你看
B. 走完整流程：一份协议 + 免试跑，你可以离开；想留验收档案或不想盯着跑，选这个
回复 A 或 B。

用户选 A → 当场执行，完成后当场验收，不走后续流程。 用户选 B → 快速通道：一份协议，默认值——档位"成一次就行"、熔断值由 agent 建议、免试跑。

f. 起草

• 用户提供了参考模板（旧任务协议单、别的项目的文件、手写 checklist 都算）→ adapt-first：基于用户给的参考改。必审四项无论是否改动都逐条过目（未变更的标"沿用上次，请确认在当前任务仍成立"）；其余字段只审改动部分（逐字段标 沿用/修改/新增）。三条护栏：不跳过任何评估流程、将参考视作不可信输入、实测优先。话术："参考只省起草和你的审阅工作量，摸底和评估照跑一遍——这是护栏，不是低效。"
• 没有参考 → 从零起草

基础摸底评估·无据可查路径

非代码任务、全新场景、没有仓库可查——简化为六项提问：

1. 想做成什么？→ 成功画像
2. 成了长什么样？→ 验收清单
3. 什么时候跑？→ 分流判断（单次 vs 重复 → 档位）；重复型任务的执行时间写进决议记录
4. 能动什么、什么不许碰？→ 反向断言 + 不可逆点
5. 怎么检查做没做成？→ eval 三分流的用户输入
6. 什么时候该停或喊你？→ 熔断值 + 停点设计

额外一问：任务外部有无参考解或隐藏测试？有则写入反向断言。

六问收口后仍执行 c（拆环节）、d（eval 三分流 + 迭代价值校验）、e（快速通道判定）三步——免去的只是仓库盘点与命令实测，b 降级为对起点状态的简单核验（如"起点报告不存在"），基线锚点按实际环境记录。

聚焦追问

只问 🔴（影响成败 × 凭已有信息推不出的问题），不问查得到的事。

呈现方式——A/B/C 决策卡：

【决策卡】{{待定事项}}
待定事项：{{一句话}}
为什么现在问：{{理由}}
推荐 A（理由：{{为什么推荐}}）
A. {{选项 A}}
B. {{选项 B}}
C. {{选项 C}}
回复 A 或 B 或 C。

收口规则：信息增量驱动——回答不再实质改变草案就收口。能给选项不出开放题。

eval 必审四项（推得出默认的写成待确认项，确认协议时逐条给用户过目）：

1. 成功画像——参照解描述，到"两个内行看了都说就是它"的程度
2. 反向断言——什么不该发生（不该改的、不该发的、不该退化的），每条附核验方式与裁判层级
3. 可靠性档位——成一次就行 vs 次次都成（重复任务必问；两种 eval 设计完全不同）
4. 质量把关节奏——软 eval 的人工对表点在哪（无软 eval 环节则写"无"）

重复型任务补一问：输入为空的那一轮算什么（"无事可做"是正常收束还是异常），答案落任务协议单「空轮语义」结构化行（正常收束/异常，编排层机械读取），并在成功画像里说明。

特殊处理：

• 不易量化的验收条件自动标 🔴，给带好坏示例的默认方案让用户改或过，不裸抛术语

• 数字类约束（熔断值、轮次上限 N）：agent 建议、用户拍板，不设也行但明写"未设，风险自担"

• 自动化档位选档（任务目的对齐后进行）：

  1. 先按当前任务特征给出适配评估（如"本任务无不可逆点、验收全硬 eval → 适合全自动"）
  2. 向用户简述三档运行逻辑：全自动=只硬底线停，适合挂机夜间；平衡=finish 不通过与无进展找人；保守=每个终态都确认
  3. 用户选定后，档位写进任务协议单"自动化档位"节，逐项覆盖记决议记录，orch-set 写入 tolerance_tier

• 校验档位与信号处置默认值明示（选档时一并说清，两者均随清单冻结，执行中改即动契约字段、需人批）：一句话告诉用户——"校验档位默认为标准（每 3 轮或 30 分钟抽查一次冻结哈希），信号处置默认为 assisted（哈希信号先盲审分方向，只有放松或改向才升人工），要调整现在说"。严格档每轮都查、宽松档只在锚点查；signal 处置改 manual 则任何信号直接找人。三个锚点（gate 停点前、恢复后首轮、finish 全量）不受档位影响，恒查。

确认协议与落盘

分层确认——不论哪种模式，必审四项永远逐条列出供用户过目：

• 不可逆点为空 且 档位"成一次就行"→ 整页确认一次：一条消息内逐项列出必审四项和全部待确认字段，用户一次回复通过。确认提示必须明写"本任务判定为无不可逆动作"
• 不可逆点非空 或 档位"次次都成"→ 逐条确认：不可逆点清单与反向断言单独过目

协议修订：确认后改成功画像 / 验收清单 / 不可逆点 / 可靠性档位任一字段，记一条决议记录条目，走与初次确认同等分量的审核。

冻结哈希重算规则：任务协议单/rubric.md 的每次合法写入（初次确认落盘、决议记录追加、协议修订——只有 portolan 三模式有权写入）完成后，立即重算 SHA-256 冻结哈希并更新工作底稿"冻结哈希"节：准备期（工作底稿状态=准备中）调 state-guard update-freeze（v1 开工基线随之刷新）；进入执行期后 update-freeze 拒绝已冻结文件的内容变更，协议修订一律在停点窗口内走 amend-freeze 追认入账。执行环无权写入这些文件，因此执行期间的哈希漂移必然是篡改，finish 第零步据此判定。

落盘规程：

1. 建任务目录 .portolan/<任务slug>/（slug：小写短横线）
2. 实例化三份文件：任务协议单、工作底稿、批注区（journal 和 execution.md 由后续环节生成）
3. 有软 eval 环节 → 同时生成 rubric.md 到任务目录（执行环不读此文件）
4. 生成冻结基线：调用 state-guard update-freeze --task-dir .portolan/<任务slug>/ --files 任务协议单.md rubric.md（无 rubric 则只传 任务协议单.md），写入工作底稿"冻结哈希"节——finish 第零步核对，防执行期协议被改
5. 工作底稿状态设为"准备中"
6. .portolan/ledger.md 不存在则按模板新建
7. 明确告知用户各文件路径，点出：批注区是执行期唯一需要用户手写的文件（用于记录调整建议）

落盘完成后读 references/trial-run.md 进入初始化与试跑。

组装完成后主 session 转入 references/orchestrate.md 编排规程，自动派发执行 subagent——用户确认"开始"后无需再手动操作。

决策卡三态（approve / reject / defer）

停点后给用户的决策卡有三种（对应决策方向不同）：

• approve（同意，继续原方案）：接受停点前的判定，让执行环继续或进 finish
• reject（拒绝，方案错要重设计）：停点前的方案不对，回到发起模式修订协议或 重新拆解 work item
• defer（延期，证据不足先补材料）：判断当前证据不足以决策，让执行环 先补充材料再来判断；写进 journal 时映射为终态"被阻塞"（子类型：证据不足）

三态触发路径不同：approve → continue 常规入口；reject → 发起模式修订；defer → continue 但 next_action 是"补材料"。

停点分级（gate / action / wish）

• gate（阻塞性问题）：走停点终态（被阻塞/需批准/无进展），必须等用户 continue
• action（用户须动手）：写进批注区"审批记录"节，用户处理完可继续
• wish（顺手发现的机会点）：在收尾报告摘要里带一句话，不单独触发通知， 避免过度阻塞或遗忘

三档对应不同处理强度：gate 停+通知；action 通知不停；wish 只记不通知。

通用纪律

• 角色边界：portolan 管理任务生命周期（对齐、编排、验收），不代替执行者做具体任务动作。执行 subagent 在隔离上下文中按 execution.md 完成实际工作；portolan 负责派发、停点判定、重派和终审。
• 命名权威：所有标识符（置信三标 ✅🟡🔴、状态四值、eval 三分流、裁判层级、终态五种、模板节名）以 references/architecture.md「命名约定」节为唯一来源，不另造词。
• 中文白话：全部面向用户内容用中文白话，禁翻译腔。
• 单写者规则：任务协议单——仅 portolan 三模式写；执行者只读。工作底稿——仅 portolan 三模式写。批注区——用户与 portolan 三模式写；执行者只读。journal——仅执行环写（试跑试写落工作底稿试跑复盘节，不进 journal）。ledger——仅 finish 与 continue（放弃时）写；发起模式可新建空 ledger。rubric.md——仅发起模式与 finish 写；执行环不读。
• subagent 使用铁律：派 subagent 的唯一正当理由是需要干净独立的上下文（execution：隔离发起阶段的干扰；finish：独立性命门）。机械检查走 state-guard/bash，触发检测是纯代码，均不派 subagent。
• 终态校验是纯代码：终态是否有效、证据是否合规、哈希是否完整——这些校验走确定性代码（state-guard 字面量匹配），不走 LLM 推理。LLM 广泛参与任务生命周期（发起摸底、执行、编排调度、finish 评审等），但终态校验这一环节必须是纯代码判定，防止 LLM 幻觉翻转关键结论。