using-upaseo

name	using-upaseo
description	核心开发工作流编排技能。运行重度开发任务的生命周期管理，内置自主复杂度判定、 微改快速通道、增量式迭代推进、独立迭代设计文档、自主推进/用户验证网关、 风险分级 upaseo-loop、UI 走 preferences、精简阶梯前置门、优先日志验证、 PR 提交前强制自审简化（删除清单+延迟债务）与大代码审查(ocr)、会话复盘与避障学习落盘。Use for /using-upaseo development tasks, including optional quick/full, autopilot/gate, worktree, and PR-per-iteration modes.

Using Upaseo (核心开发工作流技能)

本技能为唯一的完整开发工作流入口。它将一项任务或一个已落盘的 goal 在完全本地化的 upaseo 基座上驱动，严格通过：可选 goal 读取 → 避障前置 → 自主复杂度与风险判定 → 微改快速通道或 quick/full 模式 → 脑暴前置（完整模式） → 增量迭代拆分 → 单迭代设计草案 → 迭代计划评审会 → 自主推进/用户网关 → 风险分级 Loop 实现（含精简阶梯前置门） → UI 走 preferences → 优先日志验证 → 提交PR前强制自审与简化（删除清单+延迟债务）与大代码审查(ocr) → 会话复盘学习落盘的闭环推进。

User's request: $ARGUMENTS

---

预备知识与依赖

1. 深入阅读全局 upaseo 基座参考以了解 Worktree、Agent、CLI 与 Provider 偏好等底层控制逻辑。upaseo 只提供低层能力，不承载完整开发流程。
2. 角色职责规范定义在 references/roles.md。
3. 快速模式完整流程参见 references/quick-mode.md。
4. 参数速查与自主判定规则参见 references/params.md。

---

执行流程图

Step 0: 可选 goal 读取 + .paseo/ 目录初始化
Step 0.1: 前置读取 .paseo/learnings.jsonl (避障)
Step 0.2: 自主判定执行模式 (micro / quick / full)
  │
  ├── [micro 微改] ──> Micro-Change Decision → 直接手术刀式修改 → 最小确定性验证 → 简短交付
  │
  ├── [quick 模式] ──> 最小主计划 → 单迭代计划评审会 → 轻量 Loop 实现 → 验证 → Gate/Auto → 提交
  │
  └── [full 模式]
        │
        ▼
      [Worktree] ──> upaseo-handoff 到新 worktree 会话 ──> Research ──> upaseo-brainstorm ──> 迭代分解规划
                                                                │
       ┌──────────────────── 下一个迭代 ────────────────────────┘
       │
       ▼
      创建迭代设计草案 (iter_N_design_tasks.md)
       │
       ▼
      迭代计划评审会 (架构/功能/测试 1-2 轮博弈修正)
       │
       ▼
      派生子 Agent (内联摘要 + 绝对路径) ──> upaseo-loop 实现
       │
       ▼
      子 Agent 完工 ──> 主 Agent 同步更新主计划状态
       │
       ▼
      日志验证 ──> 自主判定是否需要用户确认
       │
       ├── [auto-advance] ──> 记录证据 ──> 下一迭代
       └── [wait-gate] ──> 等待用户确认 ──> 下一迭代
                                                │
       ┌────────────────────────────────────────┘
       ▼
      阶梯前置门 ──> 自审与简化(删除清单+debt+ocr审查) ──> 提交 PR ──> 会话复盘 ──> 归档

---

详细阶段规程

0. 偏好设置检查与目录初始化 (Pre-start)

1. 读取 ~/.paseo/orchestration-preferences.json 以获取底层 Agent 的 Provider 分发。
2. UI 设计 Provider 约束：涉及 ui 或 ui-impl 阶段时，Provider 从 ~/.paseo/orchestration-preferences.json 的 ui 分类解析。本项目 ui 已 pin 到 codex/gpt-5.5，以用户 preferences 为准；若某项目 ui 分类未配置，默认回退 codex/gpt-5.5 并告知用户可在 preferences 中覆盖。
3. 自动初始化 .paseo/ 运行态目录、.agents/story/ 历史资产库与 AGENTS.md 引用自愈：
   • 运行 mkdir -p <项目根目录>/.paseo/goals、mkdir -p <项目根目录>/.paseo/plans 与 mkdir -p <项目根目录>/.agents/story 确保目录结构存在。
   • 若 <项目根目录>/.paseo/todos.md 缺失，创建最小 todo 模板；后续用户提到 todo/待办/backlog 时交由 /upaseo-todo 写入，不只保留在对话里。
   • 历史资产库自愈：检查 .agents/story/ 目录下是否存在 stories.md、data_models.md、apis.md、modules.md、architecture_constraints.md 和 coding_standards.md。若有任何文件缺失，自动将 upaseo-init/references/templates/ 下对应的模板文件（例如 stories.md 等）拷贝/写入生成至该目录下，确保架构基础资产库健全。如果当前项目是遗留或老项目，推荐手动触发运行 /upaseo-init 技能来进行代码的深度扫描和资产的逆向初始化整理。
   • AGENTS.md 引用自愈：若项目根目录缺失 AGENTS.md，创建一个简洁根指引；若已存在但没有 .agents/story/ 引用，幂等追加一个 upaseo 资产引用段落。该段落必须说明 .paseo/ 只保存运行态上下文，.agents/story/ 保存长期项目资产，并列出六个资产文件。
4. Paseo 命令行自动检测与初始化安装：
   • 检查当前系统 PATH 中是否能成功执行 paseo（通过 which paseo 或运行 paseo --version）。
   • 若未在 PATH 中找到：
     • 主动在默认桌面端安装路径下搜寻内置 CLI 可执行文件：
       • macOS: /Applications/Paseo.app/Contents/Resources/bin/paseo
       • Linux: /opt/Paseo/resources/bin/paseo
       • Windows: C:\Program Files\Paseo\resources\bin\paseo.cmd
     • 若成功搜寻到内置 CLI：
       • 检测本地用户执行目录 ~/.local/bin 是否存在；若不存在，可提示用户运行 mkdir -p ~/.local/bin。
       • 不得静默创建软链接。必须向用户展示建议命令，由用户确认后再在 ~/.local/bin/paseo 创建软链接指向内置 CLI 物理路径（Windows 下为对应的 .cmd 启动脚本/Trampoline）。
       • 检查 ~/.local/bin 是否已在当前 PATH 环境变量中。若不在，可在本次会话运行时临时 export PATH="$HOME/.local/bin:$PATH"，并提示用户将该 export 追加到 shell 配置（如 ~/.zshrc 或 ~/.bashrc）。
     • 若最终无法找到任何内置或全局 CLI，打印醒目警告提示用户先去下载并安装 Paseo 桌面端客户端。

0.1 全局会话避障前置读取 (Hard Mitigation Precheck) ⚠️ 硬性规定

本步骤为整个工作流的第零优先级动作，在任何其他步骤之前必须无条件执行。

执行标准避障前置读取，见 upaseo/references/learnings-precheck.md。本技能相关 category 为全量(command_error|wrong_assumption|tool_misuse|design_flaw)，读取顺序为先 global(~/.paseo/global-learnings.jsonl)后项目(.paseo/learnings.jsonl)，提炼出的规则作为本会话全局硬约束，在后续所有阶段的决策和指令中绝对遵守。

0.15 可选 Goal 输入读取 (Optional Goal Intake)

upaseo-goal 是可选流程，不是必经前置。using-upaseo 可以直接从用户任务启动，也可以在用户已经确认并落盘 goal 之后，从 goal 文件开始规划。

• 若用户提供了 .paseo/goals/<slug>.md 的路径、slug，或明确说“按这个 goal 继续”，必须先读取该 goal 文件。
• 若没有 goal 文件，直接从当前用户请求提炼工作目标并继续，不要求用户先运行 /upaseo-goal。
• 目录边界：goal 只存放在 .paseo/goals/；plan 只存放在 .paseo/plans/。严禁把迭代设计、执行状态或实现细节写回 goal 文件。
• 若从 goal 文件进入，必须把 goal 中的 目标、边界、验证 视为规划输入约束；plan 负责拆解实现路径，不得改写或稀释这些约束。若发现 goal 本身有歧义，先和用户确认，再继续产出 plan。
• 若从 goal 文件进入，主计划 slug 默认与 goal 文件 slug 对齐；随后在 .paseo/plans/<slug>.md 产出独立 plan。

0.2 自主复杂度与风险判定 (Complexity and Risk Auto-Assessment)

Agent 必须在此步骤自主评估任务复杂度与风险等级，自动选择执行模式。用户可通过 --quick / --full 参数强制覆盖 quick/full 判定；若用户明确要求 TDD、loop 或完整仪式，则不得走微改快速通道。

自动判定规则：

当任务满足以下全部条件时，自动进入微改快速通道：

• 预估改动范围 ≤ 2 个文件，且改动可以通过人工 diff 审查完整理解
• 只涉及文案、注释、文档、格式、无行为影响的样式微调，或机械性重命名/拼写修正
• 不改变运行时逻辑、控制流、数据结构、公共 API、权限、安全、计费、并发、持久化、构建/部署流程或测试语义
• Agent 对预期结果有确定性，且无需新增测试才能证明行为正确

微改快速通道允许跳过新增失败测试、跳过 upaseo-loop、跳过最小主计划和迭代设计文档，但必须在执行前给出一句 Micro-Change Decision，说明为什么风险足够低；执行后必须做最小确定性验证（如 diff 审查、格式/文档校验、现有窄域检查）。一旦发现实际改动超出上述边界，必须立即升级到快速模式或完整仪式模式。

当任务不满足微改快速通道，但满足以下全部条件时，自动进入快速模式：

• 预估改动范围 ≤ 3 个文件
• 不涉及架构调整或新增模块
• 任务意图明确、无需与用户收敛设计方向（如 Bug 修复、样式微调、配置变更、文案修改）

其余情况进入完整仪式模式。

模式	触发方式	流程
微改快速通道	Agent 风险判定 / 非 --full / 用户未要求 TDD	Micro-Change Decision → 直接手术刀式修改 → 最小确定性验证 → 简短交付
完整仪式	自动判定 / --full 强制	脑暴 → 迭代拆分 → 每迭代计划评审会 → Loop 实现 → Gate/Auto → 自审 → PR
快速模式	自动判定 / --quick 强制	跳过脑暴，最小主计划 → 单迭代计划评审会 → 轻量 Loop 实现 → 日志验证 → Gate/Auto 判定 → 提交

Agent 选择模式后，必须在执行前向用户简要说明判定理由（一句话），用户可随时纠正。无法确定风险等级时，必须保守升级，不得走微改快速通道。

快速模式详细流程参见 references/quick-mode.md。参数与判定规则完整定义参见 references/params.md。

---

1. 自身调研与 Research

• 在开工前，先理解代码环境。对大改动或涉及多个 package 时，可启动 researcher 角色对特定范围进行只读分析，绝不写代码。
• 给出你对当前代码状况的 2-3 句话极简总结。

2. 准备工作区 (Worktree)

• 若带有 --worktree 选项，优先通过 upaseo 接口创建一个独立的 git worktree 工作区，避免弄脏主分支。
• 高追溯性命名规约：创建的分支必须统一使用极简且具高辨识度的拼音/英文 slug 命名（如 upaseo-feat-<task_slug> 格式），物理 worktree 目录物理隔离在主仓库平级目录下（如 ../paseo-improved_upaseo-feat-<task_slug>），绝不在临时路径堆积磁盘垃圾。
• 会话隔离硬规则：带有 --worktree 时，创建 worktree 后必须立即使用 /upaseo-handoff --worktree 在该 worktree 的 cwd 下启动全新的接收 Agent。原 Orchestrator 只负责创建隔离工作区、生成/指向 handoff 移交文档，并把任务计划的 Source of Truth 交给新会话；不得继续在原工作区直接 Research、Brainstorm、Loop 实现、验证或提交。
• 计划落点规则：--worktree 模式下，主计划 .paseo/plans/<slug>.md、迭代设计文档和 .paseo/handoffs/<handoff>.md 的权威副本必须位于新 worktree 内，并在 handoff prompt 中使用新 worktree 的绝对路径。接收 Agent 启动后的第一步必须读取 handoff 移交文档，再读取主计划/迭代设计文档。
• 防混淆规则：原仓库路径只能作为创建 worktree 与发起 handoff 的启动上下文；一旦 handoff 创建成功，后续 git diff、checkpoint commit、验证日志、PR/提交都必须发生在新 worktree 路径中。若无法确认当前 cwd 是新 worktree，必须暂停并向用户说明，严禁猜测执行。

3. 头脑风暴前置 (upaseo-brainstorm) — 仅完整仪式模式

• 在制定整体技术计划前，强制加载并运行本地的 upaseo-brainstorm 技能。
• 明确提炼出最简架构设想（Simplicity First / Surgical Changes），提出 2 种带 Trade-offs 的方案，并在 3 个多选题以内打包发给用户收敛意图，取得方案的明确批复。
• 快速模式下跳过此步骤。

4. 增量迭代计划制定 (Incremental Iteration Planning)

方案确定后，Orchestrator 必须将整个技术方案切分为数个紧凑的增量迭代（Incremental Iterations）。若本次是从 .paseo/goals/<slug>.md 启动，先把 goal 翻译成可执行路线图；若不是，则直接从用户任务提炼路线图。此时只允许形成路线图级别的迭代假设，具体功能设计和验收标准必须在每个迭代开始前通过“迭代计划评审会”定稿。 在 .paseo/plans/<slug>.md 写入整体路线图（Source of Truth），标记 Iterations：

schema_version: 1
State: Designing

## 迭代路线图
- [ ] 迭代 1：[简短目标]
- [ ] 迭代 2：[简短目标]

## Progress Notes
(由 Orchestrator 在每个迭代完工后追加)

schema_version 字段：计划文件首行必须写 schema_version: 1，决定迭代设计文件命名约定（见上文 §异常恢复 的 schema_version 迁移规则）。无该字段的旧文件视为 schema_version: 0，恢复时先迁移再继续。State: 字段持久化当前迭代阶段状态机，用于断电恢复。

Priority: 元数据：计划文件头部还应声明 Priority: plan（见 upaseo/SKILL.md "Source-of-Truth Priority Chain"），让恢复 Agent 知晓本文件在 SoT 链中的位置。

快速模式下只有 1 个迭代，但仍必须创建最小主计划文件 .paseo/plans/<slug>.md，用于恢复、状态审计和 /upaseo-ship 发布前校验。

5. 迭代执行大循环 (The Iteration Loop)

针对路线图中未完成的每一个迭代（N），必须依次严密执行以下子流程：

A. 创建单迭代“设计与任务”草案

在 .paseo/plans/<slug>/iter_<N>_design_tasks.md 创建独立的设计与任务文档草案（在极简工作流中，技术设计与具体任务融为一体）。该文档必须包含以下段落：

1. 迭代目标 (Iteration Goal)：清晰描述本轮增量迭代要达到的具体效果。
2. 极简技术方案 (Surgical Design)：遵循极简主义设计，不留任何冗余接口。
3. 验证计划 (Verification Plan)：
   • 必须写清楚具体验证方式，三选一或组合：
     • logs（通过观察应用日志、调试日志、特定 key event 输出来验证）。
     • browser（通过浏览器页面及元素状态进行验证）。
     • manual 或 agent-run（通过操作电脑，运行特定脚本或查看终端输出验证）。
   • 用户手动验证具体步骤：为用户编写一行明晰、无门槛的手动验证命令或操作步骤。

B. 迭代计划评审会（架构/功能/测试自适应评审，硬性规定）

在任何实现类子 Agent 启动前，Orchestrator 必须围绕本轮 iter_<N>_design_tasks.md 草案组织评审会：

• 自适应评审会分级（轻重自适应以降低流程阻力）：
  • 低风险任务（仅涉及局部文件修改、简单样式微调或文案配置变动）：跳过三个角色扮演与多轮辩论，由 Orchestrator 直接进行一份**自检清单（Mini Checklist）**核对并记录在设计文档的 Mini Checklist Log 中，瞬间定稿。
  • 高风险任务（涉及数据库表 Schema 变更、新增公共 API 路由或核心公共依赖重塑）：强制组织 architecture-designer、feature-designer 与 test-strategist 开展 1-2 轮评审会，定稿时在计划文件中追加 Design Council Log 记录每个角色的关键意见、采纳/拒绝理由、最终验收标准。
• 没有定稿日志或存在未解决阻塞项时，严禁进入实现。

C. 风险分级使用 upaseo-loop 驱动实现（含精简上下文传递）

若当前任务已在 Step 0.2 被判定为微改快速通道，本节整体跳过：不派生实现子 Agent，不新增失败测试，不启动 upaseo-loop。Orchestrator 直接执行手术刀式修改，并在最终报告中记录 Micro-Change Decision、变更范围和最小确定性验证结果。若修改过程中发现任一风险边界被突破，必须立即停止微改路径并升级到 quick/full 流程。

派生子 Agent 的上下文传递规则（硬性规定）：

Orchestrator 在 initialPrompt 中必须：

1. 内联关键摘要（迭代目标 + 验证标准，不超过 5 行）。
2. 附带文件绝对路径供子 Agent 按需深入查阅：

上下文摘要

• 迭代目标：<一句话目标>
• 验证方式：<logs|browser|manual>
• 验证标准：<具体通过条件>

必读文件（启动后第一步必须用当前宿主的文件读取原语读取以下文件，见 upaseo/SKILL.md 宿主工具兼容小节）

• 迭代设计与任务文档：<iter_N_design_tasks.md 绝对路径>
• 架构约束资产：<项目根目录>/.agents/story/architecture_constraints.md
• 编码规范资产：<项目根目录>/.agents/story/coding_standards.md
• 主计划文件（按需）：<主计划文件绝对路径>
• 避障学习记录（按需）：<项目根目录>/.paseo/learnings.jsonl

关联历史开发资产（根据改动范围追加读取并绝对遵守）

• 用户故事资产：<项目根目录>/.agents/story/stories.md
• 数据模型资产：<项目根目录>/.agents/story/data_models.md
• 核心接口资产：<项目根目录>/.agents/story/apis.md
• 包与模块资产：<项目根目录>/.agents/story/modules.md

硬性读取顺序：先读取迭代设计文档，再读取 architecture_constraints.md 和 coding_standards.md，然后按本轮改动范围读取 stories.md、data_models.md、apis.md 或 modules.md。严禁跳过这些启动读取动作。严禁违反已有的核心历史开发资产、架构约束和编码规范进行重复造轮子、破坏性重构或风格漂移。

• 精简阶梯前置门 (Simplification Ladder Gate)：启动 loop 写代码之前，对照 upaseo/references/simplify-ladder.md 做 6 级阶梯自检（按项目类型条件启用：diff 含代码扩展名走完整 6 级；纯文档/配置降级为一句话 YAGNI 自检），把"本可停在更高 rung 却写多了"的实现挡在写代码之前。阶梯判定结论一句话写入迭代设计草案（如"用了 stdlib 的 X，跳过 5/6"）。微改快速通道跳过本前置门。
• 除微改快速通道外，启动 upaseo-loop 技能，以实现-测试-纠错的闭环状态去驱动 refactorer 和 impl 角色开始写代码；快速模式也必须使用轻量 loop（建议 max-iterations <= 3），不得由 Agent 直接绕过 loop 自行修改。
• 如果这是 UI 或 Styling 改动，upaseo-loop 的 worker provider 从 orchestration-preferences.json 的 ui 分类解析；本项目 ui 已 pin 到 codex/gpt-5.5，以用户 preferences 为准（未配置时回退 codex/gpt-5.5）（详见 upaseo/SKILL.md）。
• TDD 模式只用于有行为风险、验收不确定或需要锁定回归的改动：先写失败测试/日志埋点，再让它跑通。微改快速通道不得为了“走流程”新增低价值测试。

D. 子 Agent 完工通知与主计划状态同步（文件即上下文，实时记录）

当子 Agent 完成阶段性任务并发出完工通知时，主 Agent (Orchestrator) 必须执行以下同步规程，在完成之前不得执行任何后续动作：

1. 读取子 Agent 交付产出：查看子 Agent 的最终报告或直接读取受影响的关键文件（用当前宿主的文件读取原语，见 upaseo/SKILL.md 宿主工具兼容小节）。
2. 立即持久化记录状态（文件即上下文）：主 Agent 不依赖自身 memory，必须立即、实时地将当前执行状态与中间证据持久化写入主计划文件 .paseo/plans/<slug>.md。在 Progress Notes 段落中追加“实现完成，等待验证”的精确说明。同时在主计划或迭代设计文档中显式声明当前的业务 State（例如 State: Verifying），便于断电恢复。此时不得把路线图勾选为 [x]。
3. 受阻状态同步：若子 Agent 报告 blocked 或实现结果不可验证，必须在 .paseo/plans/<slug>.md 中将当前迭代标记为 [!] 并将 State 更新为 State: Blocked，留在本迭代修复。
4. 保存计划文件后，方可进入后续流程。
5. 记录待刷新资产范围：主 Agent 分析本轮变更可能影响的资产文件（如 stories.md , data_models.md 等），但验证通过前，严禁将其写入 .agents/story/ 资产。

严禁：子 Agent 完工后直接跳到下一阶段而不记录主计划执行状态；验证通过前严禁提前将路线图标记为 [x]。

E. 优先日志验证 (Log-Based Verification)

• 无论是 upaseo-loop 的自动验证，还是后续的 Auditor verify 阶段，都必须遵循"优先日志验证"原则。
• Agent 需要优先捕获并详细分析应用程序在运行时的事件日志 (Event Logs)、Debug 日志以及状态流输出，以此直接自证功能完整性，其后辅以自动化测试用例通过。

F. 用户验证网关 / 自主推进判定 (Gate or Auto-Advance)

Agent 根据验证结果的确定性自主决定是否需要等待用户确认。用户可通过 --autopilot / --gate 参数强制覆盖。

自动推进条件（全部满足时可自动推进）：

• 验证方式为 logs 或 agent-run（Agent 可自行完成的客观验证）
• 日志证据完整，关键事件 Trace 全部匹配预期
• 自动化测试全部通过（若有）
• 本迭代无架构性决策变更

必须等待用户条件（任一满足时必须等待）：

• 验证方式包含 browser 或 manual（需人眼判断）
• 涉及 UI/UX 视觉变更
• 迭代中做出了设计文档之外的架构性决策
• Agent 对验证结果存在不确定性

自动推进时：

• 在主计划文件中记录 [auto-advanced] 标记及验证证据摘要。
• 资产防事实漂移校验 (Diff-Asset Validation)：执行标准校验清单，见 upaseo/references/diff-asset-validation.md（六步三方对照：diff 全集 × 设计承诺 × 验证证据，逐条 [write]/[drop]/[hold] 登记）。校验通过前严禁更新 .agents/story/，严防空头承诺和设计漂移。
• 校验通过后，执行增量历史资产刷新：若本轮新增或修改了前后台用户功能点用例、数据库表结构、类与核心数据结构体、公共 API 路由与服务规范、新的包目录、前端展示页面路由、架构约束或编码规范，必须由主 Agent 或 story-updater 更新 .agents/story/ 对应文件，并以 * [Updated in Iter <N>] 作为前缀。
• 将当前迭代路线图状态更新为 [x]，更新计划文件中的 State: Completed（或在多迭代下标记 State: Next_Iteration_Start），并创建本迭代高追溯性命名（如 checkpoint-iter-<N>）的 checkpoint commit，记录 commit hash 后方可进入下一迭代。
• checkpoint commit 只允许包含本迭代计划和本迭代实际修改的文件。提交前必须复查 git status --short，发现无关改动时保留不动并在计划中说明；不得为了整洁提交而回退、stash 或 stage 用户/他人已有改动。
• 用户可随时要求回溯查看。

等待用户时，向用户展示：

1. 本迭代完成的成果。
2. 捕获到的关键日志输出片段/验证结果。
3. 指导用户自行操作的手动验证步骤。
4. 等待用户回复"验证通过"后，将当前迭代路线图状态更新为 [x]。先执行资产防事实漂移校验（标准清单见 upaseo/references/diff-asset-validation.md），校验通过后执行必要的增量历史资产刷新，标记计划文件 State，创建高追溯性命名的 checkpoint commit，记录 commit hash 后方可继续。若不通过，留在本迭代修复。

G. 回滚机制 (Rollback)

当迭代 N 的改动破坏了迭代 N-1 已验证通过的功能时：

1. 优先在当前迭代内修复回归问题。
2. 若修复失败（超过 loop 最大迭代次数），执行 git revert 回退到上一已验证迭代的 checkpoint commit；若 checkpoint 缺失，必须暂停并向用户说明不能安全自动回滚。
3. 将回退事件记录到主计划文件（标记 [!] 迭代 N: reverted），并重新设计当前迭代方案。

---

6. 提 PR 门槛、自审与交付

在所有增量迭代全部勾选 [x] 完成后，Orchestrator 进入 PR 交付阶段。

PR 策略：默认统一 PR。若带 --pr-per-iteration 参数，则在每个迭代验证通过后单独提 PR（自审同样在每个 PR 前执行）。

1. 极致精简自理 (upaseo-simplify)：

   • 强制加载并执行本地 upaseo-simplify 技能。
   • 对照 upaseo/references/simplify-ladder.md 产出删除清单 (Delete-List)：对 diff 逐 hunk 重跑阶梯，逐条决定 [cut] / [shrink] / [keep]，应用后重跑验证确认未破坏行为。
   • 为求简而取的捷径（主动落到更低 rung）必须登记为延迟债务：写入 .paseo/todos.md 的 ## Active 桶，带 type: debt 字段（格式见 upaseo-todo/SKILL.md）。
   • 删除清单摘要（[cut] N / [shrink] M / [keep] K）与新增 debt 条目数写入交付报告。

2. 严苛自审质检 (upaseo-reviewer)：

   • 强制加载并执行本地 upaseo-reviewer 技能。
   • 完整模式默认 Tier 1 (ocr)：自检 command -v ocr && ocr llm test，通过则调 ocr review --audience agent --format text --from <base> --to HEAD --background "<迭代目标>"；ocr 不可用（未装/未配 LLM/超时）降级 Tier 2 (Agent 模拟审计) 并在报告标注。快速模式可选 ocr；微改跳过。
   • findings 按严重度分级：blocker（安全/正确性/资源泄漏）必须本地 100% 闭环修复，未修复不得提 PR；minor（风格/可读性）记录进报告不阻断，可登记 type: debt。
   • 生成含 ocr findings 摘要或 Agent 清单结论的自审确认表。

3. 创建 PR 并交付 (PR Fallback 智能兜底)：

   • 在 worktree 中进行整洁提交（Git commit），然后尝试运行 gh pr create 提交 PR，将 PR 链接和自审报告呈给用户。
   • 自审报告必须包含三段摘要：删除清单（[cut]/[shrink]/[keep] 计数）、审查引擎结论（ocr findings blocker/minor 或 Agent 清单）、新增 type: debt 条目数。
   • 提交前必须只 stage 本任务相关文件；若工作区包含无关改动，保持原样并在交付报告中列出“未纳入提交的无关改动”。
   • PR 智能兜底 (PR Fallback)：如果本地环境未安装 gh CLI 命令行、网络阻断或未授权登录导致 PR 创建失败，系统必须智能且温和地降级为本地提交模式。在已确认 staged 内容仅包含本任务相关文件后，创建一个语义整洁的 Commit，并清晰打印引导：“本地 gh CLI 未授权或缺失，已为您在本地完成整洁 Commit，请您手动执行 git push / 提交 PR。”若无法隔离 unrelated changes，停止并请用户确认，不得把无关改动混入提交。
   • 最终 PR 阶段必须等待用户审批，不可自动合并。
   • using-upaseo 到 PR 创建与用户审批为止；用户确认并合并 PR 后，必须手动运行 /upaseo-ship 完成发布校验、资产固化、CHANGELOG 和 worktree/分支清理。

7. 会话复盘与学习落盘 (Session Learnings Dump) ⚠️ 硬性规定

在 PR 交付完毕或任务因故挂起归档前，本步骤必须无条件执行。

1. 深度复盘本次会话/迭代：回顾整个执行过程，识别出所有：

   • 曾执行但失败的命令或指令（如工具参数错误、路径假设错误）。
   • 被推翻的错误技术假设（如对 API 行为的错误理解、对框架能力的错误预期）。
   • 导致浪费时间的弯路或无效决策。

2. 精炼提取避障规则：将上述发现提炼为 1-3 条 极简、高密度的避障规则。

3. 容量控制与去重：读取现有 .paseo/learnings.jsonl，若条目数 ≥ 30，先精炼合并最旧的相似条目，保持总量 ≤ 30。写入前去重——检查 mitigation 字段是否与已有条目语义重复，重复则跳过。

4. 追加写入 .paseo/learnings.jsonl：以 JSON Lines 格式追加。格式规范：

   {"timestamp":"<ISO8601>","session_id":"<conversation-id>","category":"<command_error|wrong_assumption|tool_misuse|design_flaw>","failed_attempt":"<简述失败操作>","mitigation":"<应该怎么做>"}
   

5. 若本次会话无任何错误或教训，可写入一条 {"category":"clean_session","mitigation":"无新增避障规则"} 占位。

---

异常恢复 (Resumability & Self-healing)

如果执行过程中意外中断（如服务器重启、Token 耗尽），重新调用 /using-upaseo <slug> 时，系统必须遵循“文件即上下文”理念进行秒级无感现场自愈恢复：

恢复读取顺序遵循 SoT 优先级链（权威定义见 upaseo/SKILL.md "Source-of-Truth Priority Chain" 小节）：compact(最新现场) > handoff > plan > goal。若存在 compact 或 handoff 文档，先读它们恢复现场状态与任务语义；plan 用于路线图与状态机；goal 的边界/验证约束不可被覆盖。本节下方"启动首步必读"聚焦 plan 层（最常见恢复路径），但若 compact/handoff 存在，它们在"现场状态/下一步"上优先于 plan。

1. 启动首步必读（自愈凭证）：Orchestrator 唤醒后，第一步且必须按 SoT 优先级链读取：若存在最新 compact 文档（.paseo/compacts/）或 handoff 文档（.paseo/handoffs/）先读；然后读取主计划 .paseo/plans/<slug>.md 以及当前未完成迭代的 iter_<N>_design_tasks.md（用当前宿主的文件读取原语，见 upaseo/SKILL.md 宿主工具兼容小节）。plan 文件含 schema_version 字段时按其版本决定迭代设计文件命名（见下文 §迁移规则）；若遇到无 schema_version 的旧文件（视为 schema_version: 0）且存在旧版历史文件 iter_<N>_design.md，兼容读取并在继续开发前自动迁移为 iter_<N>_design_tasks.md 同时把 plan 升级为 schema_version: 1。以此作为重建现场的权威上下文。
2. plan schema_version 迁移规则：
   • schema_version: 0（无字段）：兼容读取 iter_<N>_design.md，迁移为 iter_<N>_design_tasks.md，升级 plan 字段为 schema_version: 1。
   • schema_version: 1（当前）：只读 iter_N_design_tasks.md，不再兼容旧名。
   • schema_version: 2（未来触发点）：预留，届时可移除 iter_N_design.md 兼容分支。本次不强制迁移到 2，只埋点。
3. 自愈状态机现场复原：根据文件中持久化登记的 State 字段与路线图状态，自动引导进入对应的操作阶段：
   • State: Designing $\rightarrow$ 自动读取并恢复迭代设计草案编写与评审会阶段。
   • State: Implementing $\rightarrow$ 自动派生子 Agent，直接唤醒并调度 upaseo-loop 继续驱动实现，还原 Worker 现场。
   • State: Verifying $\rightarrow$ 自动进入日志与测试优先验证阶段。
   • State: Waiting_Gate $\rightarrow$ 重新为用户渲染手动验证步骤，恢复等待用户验证网关。
   • State: Completed / State: Next_Iteration_Start $\rightarrow$ 自动推进至下一迭代或自理自审交付阶段。
4. 流程恢复宣告：Orchestrator 成功恢复现场后，需向用户发送一句话极简说明（如：“检测到 Iteration 1 在断电前处于 Implementing 状态，现场已完美还原，正继续驱动子 Agent 实现...”），全程对用户零心智负担。