maestro-flow 0.5.37 → 0.5.38

package/.claude/commands/maestro-ralph.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-ralph
 description: Use when the optimal command sequence is unclear and needs automated state-based determination
-argument-hint: "<intent> [-y] | status | continue"
+argument-hint: "<intent> [-y] | status | continue | --amend [change]"
 allowed-tools:
   - Read
   - Write
@@ -17,6 +17,10 @@ Closed-loop decision engine: read project state → infer position → build ada
 Ralph builds/evaluates; ralph-execute runs steps. Session: `.workflow/.maestro/ralph-{YYYYMMDD-HHmmss}/status.json`.
 </purpose>
 
+<deferred_reading>
+- [ralph-amend-goal.md](~/.maestro/workflows/ralph-amend-goal.md) — read when `--amend` flag active for goal amendment flow
+</deferred_reading>
+
 <context>
 $ARGUMENTS — intent text, flags, or keywords.
 
@@ -24,8 +28,9 @@ $ARGUMENTS — intent text, flags, or keywords.
 ```
 -y flag       → auto_confirm = true   # 唯一来源：用户显式传入；ralph 不内部推断（invariant 14）
 --roadmap     → wants_roadmap = true (强制多发布 roadmap 路径；roadmap 默认 opt-in)
+--amend / -a  → amend_mode = true (running session 存在时触发目标修改流程)
 .md/.txt path → input_doc (supplementary context only, NEVER substitutes lifecycle stages)
-Remaining     → intent
+Remaining     → intent (amend_mode 时为 change_request)
 ```
 
 **State files:**
@@ -71,6 +76,7 @@ S_CONFIRM         — 用户确认                             PERSIST: —
 S_DISPATCH        — 移交 maestro-ralph-execute           PERSIST: —
 S_DECISION_EVAL   — 委托评估质量门                       PERSIST: —
 S_APPLY_VERDICT   — 应用裁决 + 插入命令                  PERSIST: session.steps[], session.passed_gates[]
+S_AMEND_GOAL      — 修改 running session 目标               PERSIST: session.task_decomposition, .boundary_contract, .goal_changelog, .steps[]
 S_FALLBACK        — 请求用户输入                         PERSIST: —
 </states>
 
@@ -79,6 +85,8 @@ S_FALLBACK        — 请求用户输入                         PERSIST: —
 S_PARSE_ROUTE:
   → S_STATUS        WHEN: intent == "status"
   → S_CONTINUE      WHEN: intent == "continue"
+  → S_AMEND_GOAL    WHEN: amend_mode == true AND running session exists
+  → S_FALLBACK      WHEN: amend_mode == true AND no running session  DO: Display: "无运行中的 ralph 会话，--amend 需要活跃 session"
   → S_DECISION_EVAL WHEN: running session with decision step in "running" status
   → S_RESOLVE_PHASE WHEN: intent is non-empty                  ← phase 必须先于 position
   → S_FALLBACK      WHEN: no intent AND no running session
@@ -165,6 +173,11 @@ S_APPLY_VERDICT:
   GUARD: not auto_confirm → AskUserQuestion with override options
   GUARD: post-reground + drifted + confidence_score >= 60 → A_REGROUND_HALT（漂移熔断为安全门，auto_confirm 不跳过）
 
+S_AMEND_GOAL:
+  → S_DISPATCH      WHEN: change applied + user confirmed    DO: A_AMEND_GOAL
+  → END             WHEN: user cancels
+  GUARD: RISK_LEVEL=high → auto_confirm 无效，必须 AskUserQuestion
+
 S_FALLBACK:
   → S_PARSE_ROUTE   WHEN: user provides input               DO: AskUserQuestion
   → END             WHEN: user cancels
@@ -404,7 +417,11 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`（`sess
 3.6. **frontend-verify UI 门控**：仅当当前 phase 交付前端（检出 `dashboard/` 目录，或 phase 目标/计划含 UI 关键词 `landing|page|dashboard|frontend|UI|component|界面`）时保留 `frontend-verify` stage + `post-frontend-verify` decision；纯后端 phase 删除该 stage
 4. **决策节点**：每个 Decision after 非空的 stage 之后插入 `{ decision: "<gate>", retry_count: 0, max_retries: 2, command_scope: null, command_path: null }`
 5. **goal-audit 插入**：`task_decomposition` 存在时，在最后一个 evidence-producing stage（execute/review/test）之后、`milestone-complete` 之前插入 `decision:post-goal-audit`
-5.5. **re-grounding 插入**：当 `task_decomposition` 存在 **且** 链路含 ≥3 个执行 step（不含 decision 节点）时，从第 3 个执行 step 起每隔 3 个执行 step 后插入 `{ decision: "post-reground", retry_count: 0, max_retries: 0, command_scope: null, command_path: null }`。不在最后一个执行 step 之后插入（由 goal-audit 覆盖）；不与已有 quality-gate decision 节点相邻（顺延到下一个 3-step 边界）；fix-loop 动态插入的 step（index > 原始 chain 长度）不纳入计数
+5.5. **re-grounding 插入**：WHEN `task_decomposition` 存在 AND 执行 step（不含 decision）≥3
+   - 从第 3 个执行 step 起每隔 3 个插入 `{ decision: "post-reground", retry_count: 0, max_retries: 0, command_scope: null, command_path: null }`
+   - 不在最后一个执行 step 后插入（由 goal-audit 覆盖）
+   - 不与已有 quality-gate decision 节点相邻（顺延到下一个 3-step 边界）
+   - fix-loop 动态插入的 step **纳入**计数（从插入点起重新计算 3-step 间隔）
 6. **终点硬约束**：`session.milestone` 存在时 chain 以 `milestone-complete` 结尾；`session.milestone=null`（standalone）时跳过 `milestone-audit` + `milestone-complete` stage，chain 以最后一个质量门 stage 结尾
 7. **goal_ref 传播**：`task_decomposition` 存在时，每个 step 按 `step.stage ∈ g.lifecycle` 匹配 `step.goal_ref = g.id`（多匹配取字典序最小）；decision 节点不打 goal_ref
 8. **占位符**：independent 保留 `{phase}` `{intent}`；unified 不带 `{phase}`
@@ -415,7 +432,7 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`（`sess
      - 命中 skills → 同上（type=skill）
      - 未命中 → `command_scope = "missing"`, `command_path = null`，A_CREATE_SESSION 报错 E006
    - **不在 build 阶段读取 .md 内容**；`<required_reading>` / `<deferred_reading>` 解析与加载由 `maestro ralph next` CLI 在执行期完成
-10. **每个 step 初始化** `completion_confirmed: false`, `completion_status: null`, `completion_evidence: null`, `deferred_reads: []`, `load: null`（由 `ralph next` 写入）
+10. **每个 step 初始化** `completion_confirmed: false`, `completion_status: null`, `completion_evidence: null`, `completion_summary: null`, `completion_decisions: null`, `completion_caveats: null`, `completion_deferred: null`, `deferred_reads: []`, `load: null`（由 `ralph next` 写入）
 11. **scope_verdict gating**（仅当 chain 起点 = `analyze-macro`）：
     - `scope_verdict == large` **且** `wants_roadmap` → 保留 `roadmap` + `analyze`；`plan` 选 phase 列（`{phase}`）
     - 其余（`medium` / `small`，或 `large` 但非 `wants_roadmap`）→ 跳过 `roadmap` + `analyze` 两 stage；`plan` 选 standalone 列（`--from analyze:{analyze_macro_id}`），不带 `{phase}`
@@ -540,9 +557,12 @@ Runs only when `task_decomposition` present.
 
 ### A_REGROUND_EVALUATE
 
-仅当 `task_decomposition` 存在。周期触发（build rule 5.5）。
+GUARD: `task_decomposition` 存在（周期触发，见 build rule 5.5）
 
-1. 从 status.json 读取：`session.intent`、`session.boundary_contract`、`steps[]` 中 `status=="completed"` 的 step + `completion_evidence`、`task_decomposition` 中已 done 子目标的 `goal` + `done_when`
+1. Read status.json：
+   - `session.intent`, `session.boundary_contract`
+   - `steps[]` WHERE `status=="completed"` → 取 `completion_evidence`, `completion_summary`, `completion_decisions`, `completion_caveats`
+   - `task_decomposition[]` WHERE `status=="done"` → 取 `goal`, `done_when`
 2. Delegate read-only audit (run_in_background, STOP, wait):
    ```
    maestro delegate "PURPOSE: 意图保真检查 — 对照 intent 验证累积执行是否漂移
@@ -556,8 +576,10 @@ Runs only when `task_decomposition` present.
      definition_of_done = {boundary_contract.definition_of_done}
      in_scope           = {boundary_contract.in_scope}
      out_of_scope       = {boundary_contract.out_of_scope}
-     completed_steps    = [{index, skill, stage, completion_evidence}, ...]
+     completed_steps    = [{index, skill, stage, completion_evidence, completion_summary, completion_decisions, completion_caveats}, ...]
      done_goals         = [{id, goal, done_when}, ...]
+     accumulated_deferred = [{from_step, item}, ...]
+     goal_changelog     = {session.goal_changelog ?? []}
    EXPECTED:
      ---VERDICT---
      STATUS=aligned|drifted
@@ -568,7 +590,8 @@ Runs only when `task_decomposition` present.
    CONSTRAINTS:
      - 只评估，不修改文件
      - aligned 阈值：≥80% 已完成产出直接服务 intent
-     - 单个 step 触碰 out_of_scope → 直接判 drifted"
+     - 单个 step 触碰 out_of_scope → 直接判 drifted
+     - goal_changelog 存在 → 以最新 after.goals 为基准"
    --role analyze --mode analysis
    ```
 3. On callback: parse verdict
@@ -646,6 +669,21 @@ Runs only when `task_decomposition` present.
 2. Display: ◆ 已达最大重试次数，debug 已执行。请人工介入。
 3. Display: /maestro-ralph continue 恢复
 
+### A_AMEND_GOAL
+
+运行中 session 的目标热修改。详细流程由 `<deferred_reading>` 加载 `ralph-amend-goal.md`。
+
+| Phase | 行为 | 产出 |
+|-------|------|------|
+| 1. 快照 | 读 `task_decomposition` + `boundary_contract` + 已完成 steps 的 `completion_summary` | Display: 目标列表 + 进度 |
+| 2. 解析 | `change_request` 非空 → 直接用；为空 → AskUserQuestion（修改/新增/移除/调整边界） | `change_type` + `change_request` |
+| 3. Mini Grill | `maestro delegate --role analyze --mode analysis`：评估影响 | RISK_LEVEL + AFFECTED_GOALS + INVALIDATED_STEPS + NEW_GAPS |
+| 4. 确认 | AskUserQuestion：应用并继续 / 仅改目标 / 取消 | 用户选择 |
+| 5. 应用 | 归档旧目标（`superseded`）→ 写入新目标（`origin: CHG-xxx`）→ 重建链路 → write status.json | handoff ralph-execute |
+
+GUARD: `RISK_LEVEL == high` → AskUserQuestion 不跳过（auto_confirm 无效）
+GUARD: 已完成（`status: "done"`）的目标不可 supersede（skip + warn）
+
 </actions>
 
 </state_machine>
@@ -658,7 +696,7 @@ Runs only when `task_decomposition` present.
 {
   "session_id": "ralph-{YYYYMMDD-HHmmss}",
   "source": "ralph", "status": "running",
-  "ralph_protocol_version": "1",   // CLI-driven; absent/0 → legacy inline ralph-execute
+  "ralph_protocol_version": "2",   // CLI-driven; absent/0 → legacy; "1" → basic CLI; "2" → structured completion + enhanced anchor
   "active_step_index": null,       // CLI-managed; only one step held at a time
   "intent": "", "lifecycle_position": "",
   "phase": null, "phase_is_new": false,
@@ -693,6 +731,10 @@ Runs only when `task_decomposition` present.
     "completion_confirmed": false,
     "completion_status": null,
     "completion_evidence": null,
+    "completion_summary": null,      // 一句话总结：做了什么（MUST on DONE）
+    "completion_decisions": null,    // 本 step 做出的关键决策列表
+    "completion_caveats": null,      // 后续 step 需注意的事项
+    "completion_deferred": null,     // 被推迟到后续的工作列表
     "completed_at": null,
     "deferred_reads": [],         // 由 ralph next CLI 解析 .md 时填充
     "load": null                  // { loaded_at, required_files[], deferred_files[], resolve_version } —— 由 ralph next 写入
@@ -706,10 +748,22 @@ Runs only when `task_decomposition` present.
   "execution_criteria": [],
   "task_decomposition": [
     { "id": "G1", "goal": "", "boundary": "", "done_when": "",
-      "evidence": "", "lifecycle": [], "status": "pending|done",
-      "completion_confirmed": false, "completed_at": null }
+      "evidence": "", "lifecycle": [], "status": "pending|done|superseded",
+      "completion_confirmed": false, "completed_at": null,
+      "superseded_by": null, "superseded_at": null, "origin": null }
   ],
-  "task_decomposition_all_done": false
+  "task_decomposition_all_done": false,
+
+  // goal_changelog: additive; absent → no amendments
+  "goal_changelog": [
+    { "id": "CHG-001", "timestamp": "{ISO}",
+      "change_type": "modify|add|remove|boundary",
+      "reason": "变更描述",
+      "impact_assessment": { "risk_level": "low|medium|high",
+        "invalidated_steps": [], "new_steps_inserted": 0 },
+      "before": { "goals": [{"id":"G1","goal":"...","done_when":"..."}] },
+      "after":  { "goals": [{"id":"G1v2","goal":"...","done_when":"..."}] } }
+  ]
 }
 ```
 
@@ -841,5 +895,19 @@ decision:post-goal-audit {retry+1}
 - [ ] Phase-level deferred chaining：plan/execute step 的 `--from`/`--dir` 注入由 A_RESOLVE_ARGS（ralph-execute）运行时完成；build 阶段标记意图，不预知 artifact ID
 - [ ] Phase-level plan step 运行时获得 `--from analyze:{phase_analyze_id}`（由 ralph-execute 从 state.json 查找注入）
 - [ ] Phase-level execute step 运行时获得 `source_artifact_ref = "plan:{id}"`
+- [ ] 每个 step 含 `completion_summary` + `completion_decisions` + `completion_caveats` + `completion_deferred`（初始 null）
+- [ ] `completion_summary` 在 DONE/DONE_WITH_CONCERNS 时为 MUST（由 CLI `--summary` 参数传入）
+- [ ] session_anchor 包含最近 5 个已完成 step 的 `completion_summary` + `completion_caveats`（滑动窗口）
+- [ ] session_anchor 包含 task_decomposition 全局视图（仅 `status != "superseded"` 的目标）
+- [ ] session_anchor boundary_contract 不截断（`capAnchorList` n=8）
+- [ ] session_anchor 包含 Accumulated Signals（聚合所有 caveats + deferred）
+- [ ] re-grounding 完成 steps 信息含 completion_summary/decisions/caveats
+- [ ] fix-loop 动态插入的 step 纳入 re-grounding 3-step 计数
+- [ ] `--amend` 路由到 S_AMEND_GOAL（需 running session）
+- [ ] A_AMEND_GOAL：5 步流程（快照→解析→mini grill→确认→应用）
+- [ ] 旧目标标 `superseded`（`superseded_by` + `superseded_at`），新目标标 `origin: "CHG-xxx"`
+- [ ] `goal_changelog` 记录完整 before/after 快照 + impact_assessment
+- [ ] `RISK_LEVEL=high` 时 amend 不跳过 auto_confirm
+- [ ] session_anchor 中 superseded 目标仅占一行标注，不展开细节
 
 </appendix>

package/.claude/commands/maestro.md

@@ -46,7 +46,7 @@ $ARGUMENTS — user intent text, or special keywords.
 8. **Grill `-y` 透传** — `-y` auto mode 透传 `-y` 到 grill args（grill 自身 Auto mode 用代码代答），不删除 grill stage；grill 仍产出 grill-report/terminology/context-package 供下游 brainstorm
 9. **D-007 milestone 反查** — 数字 phase 的 `milestone_id` 由 `state.json.milestones[].phase_slugs` 反查
 10. **每个 step 必须 `completion_confirmed: true`** — 由 `maestro ralph complete N --status DONE|DONE_WITH_CONCERNS` 写入
-11. **schema** — `ralph_protocol_version: "1"` 标记 CLI-driven session；新增字段全部可选
+11. **schema** — `ralph_protocol_version: "2"` 标记 CLI-driven session；新增字段全部可选
 12. **Invariant violation = BLOCK** — 违反上述任一 invariant 即阻断当前操作，不可绕过。特别是 invariant 1（dispatch via ralph-execute）和 invariant 2（session before execution）和 invariant 10（completion_confirmed 由 CLI 写入）为硬约束。
 14. **禁止以上下文消耗为由中断执行** — harness 自动处理 context compression，以"上下文不足"或"避免 context overflow"为由中断属于 invariant violation
 13. **Classification evidence** — S_CLASSIFY 的 chain 选择决策 MUST 记录到 status.json 的 `classification_rationale` 字段：匹配了哪个 pattern、排除了哪些备选、confidence level。无记录的分类不可进入 S_CREATE。
@@ -173,7 +173,7 @@ S_FALLBACK:
    ```json
    {
      "session_id", "source": "maestro", "intent", "task_type", "chain_name",
-     "ralph_protocol_version": "1", "active_step_index": null,
+     "ralph_protocol_version": "2", "active_step_index": null,
      "phase", "phase_is_new": false, "milestone": "",
      "scope_verdict": null, "analyze_macro_id": null, "blueprint_id": null,
      "auto_mode": false, "decomposition_owner": "maestro", "cli_tool": "claude",
@@ -186,12 +186,18 @@ S_FALLBACK:
        "milestone_id": null, "source_artifact_ref": null,
        "status": "pending", "goal_ref": null,
        "completion_confirmed": false, "completion_status": null,
-       "completion_evidence": null, "completed_at": null,
+       "completion_evidence": null,
+       "completion_summary": null, "completion_decisions": null,
+       "completion_caveats": null, "completion_deferred": null,
+       "completed_at": null,
        "deferred_reads": [], "load": null
      }],
      "waves": [], "current_step": 0, "status": "running",
      "boundary_contract": {}, "execution_criteria": [],
-     "task_decomposition": [], "task_decomposition_all_done": false
+     "task_decomposition": [{ "status": "pending|done|superseded",
+       "superseded_by": null, "superseded_at": null, "origin": null }],
+     "task_decomposition_all_done": false,
+     "goal_changelog": []
    }
    ```
 3. Validate: 所有 step 的 `command_scope != "missing"`，否则 raise E005 列出缺失 skill
@@ -232,7 +238,7 @@ S_FALLBACK:
 - [ ] Session dir created with status.json before execution; decomposition fields additive-only
 - [ ] 执行 step 含 `command_scope` + `command_path` + `completion_confirmed`；decision step 由 `step.decision` 标识
 - [ ] `command_scope`/`command_path` 由 `maestro ralph skills --platform claude --json --quiet` 预校验（project 覆盖 global）
-- [ ] Session schema 含 `ralph_protocol_version: "1"` + `active_step_index: null` + step.load 占位
+- [ ] Session schema 含 `ralph_protocol_version: "2"` + `active_step_index: null` + step.load 占位
 - [ ] 用户传入 `-y` 时透传到 skill args
 - [ ] All chains dispatched via maestro-ralph-execute
 - [ ] Low-complexity intents routed to maestro-quick

package/.claude/commands/manage-drift-realign.md

@@ -0,0 +1,151 @@
+---
+name: manage-drift-realign
+description: Detect and realign .workflow/ artifact drift against code reality after refactoring
+argument-hint: "--scope <roadmap|spec|codebase|state|issue|knowhow|project|all> [--since YYYY-MM-DD|commit|HEAD~N] [--depth shallow|deep] [--dry-run] [--report] [--auto-archive] [--interactive]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+检测代码重构/增量变更后，代码现实与 .workflow/ 文档之间的漂移。互补于 `manage-knowledge-audit`（检测知识存储内部矛盾）。本命令通过 git 时间线 + session 历史检测 code↔document 漂移。
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/drift-realign.md
+</required_reading>
+
+<deferred_reading>
+- ~/.maestro/workflows/knowledge-audit.md (交叉引用已有审计发现)
+- ~/.maestro/workflows/sync.md (codebase 文档严重漂移时自动触发)
+- ~/.maestro/workflows/codebase-rebuild.md (sync 不足时的回退方案)
+</deferred_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Scope：** `roadmap` | `spec` | `codebase` | `state` | `issue` | `knowhow` | `project` | `all`（默认 `all`）
+
+**`--since`：** 分析起始点。支持日期（`YYYY-MM-DD`）、commit ref（`abc1234`）、相对引用（`HEAD~N`）。默认自动检测：优先读 `state.json` 的 `last_drift_realign` 或 `last_pruned` 时间戳，回退 90 天。
+
+**`--depth`：** `shallow`（mtime + 引用检查）vs `deep`（LLM 语义分析）。默认 `shallow`。
+
+**`--dry-run`：** 预览模式，不执行任何写入。
+
+**`--report`：** 仅生成报告，不进入交互分诊。
+
+**`--auto-archive`：** 自动归档陈旧项，跳过逐项确认。
+
+**`--interactive`：** 逐项交互分诊（默认）。
+
+**互斥规则：** `--report` 覆盖 `--interactive`；`--auto-archive` 覆盖 `--interactive`。
+
+**状态文件读取：**
+- `.workflow/state.json`
+- `.workflow/roadmap.md`
+- `.workflow/specs/*.md`
+- `.workflow/codebase/*.md`
+- `.workflow/issues/issues.jsonl`
+- `.workflow/knowhow/*.md`
+- `.workflow/project.md`
+
+使用 `maestro timeline` CLI 构建统一的 git+session 时间线。
+</context>
+
+<execution>
+Follow `~/.maestro/workflows/drift-realign.md` Stages 1-9 in order.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Timeline** (Stages 1-2)
+- REQUIRED: `.workflow/` 存在，scope 解析通过，`--since` 已解析。
+- REQUIRED: `maestro timeline --since <date> --json` 产出有效时间线。
+- BLOCKED if `.workflow/` 缺失 (E001)、scope 非法 (E002)、git 不可用 (E003)。
+
+**GATE 2: Timeline → Scan** (Stages 2-3 → Stage 4)
+- REQUIRED: `timeline.json` 已生成且包含事件。
+- REQUIRED: `drift_score` 已计算（LOW/MODERATE/SEVERE）。
+- REQUIRED: 若 SEVERE 且 `--depth shallow`，发出 W002 建议 `--depth deep`。
+- BLOCKED if 时间线为空（`--since` 之后无变更）。
+
+**GATE 3: Scan → Triage** (Stage 4 → Stages 5-6)
+- REQUIRED: 4 个并行漂移扫描 agent 全部返回结果（或 W003 部分覆盖）。
+- REQUIRED: `DriftFinding[]` 已合并、去重、按严重度排序。
+- BLOCKED if 所有 agent 均失败。
+
+**GATE 4: Triage → Apply** (Stages 6-7 → Stage 8)
+- REQUIRED: 备份 tarball 生成于 `.workflow/.trash/drift-realign-{timestamp}/`。
+- REQUIRED: 所有用户决策已记录（或 `--auto-archive`/`--report` 已生效）。
+- REQUIRED: codebase scope 的 rebuild 动作自动触发 `/quality-sync --full`。
+- BLOCKED if 备份失败 (E005)。
+
+### Execution Constraints
+
+- **Code-as-Truth**: 代码是唯一真理源。当文档说 X 但代码做 Y 时，文档漂移。
+- **Parallel scan**: Stage 4 在单条消息中派发 4 个 agent（roadmap-scanner、spec-scanner、codebase-scanner、artifact-scanner）。
+- **Auto-rebuild**: 当 codebase-scanner 检测到严重漂移（3+ P0 finding）时，分诊后自动触发 `/quality-sync --full`。若 sync 报告重大结构变更，建议 `/manage-codebase-rebuild`。
+- **Long gap handling**: 当 `drift_window` > 180 天时，自动升级为 `--depth deep` 并警告用户 (W002)。
+
+### Platform Inquiry（Stage 2a，交互式）
+
+当 `session_summary.by_platform` 包含多个平台且 session 总量 > 20 时，使用 AskUserQuestion 询问用户修改主要在哪个平台进行。用户选择后以 `--platform` 参数重新获取 timeline，缩小后续分析范围。
+
+### Session 详情加载策略（Stage 2b）
+
+`maestro timeline` 每条 session 事件已包含：`summary`（用户提问摘要）、`edited_files`、`code_paths`、`platform`。这些信息在 `--depth shallow` 模式下足以支撑漂移检测。
+
+当 `--depth deep` 时，对与 cold_workflow_files 有 edited_files 交集的 session，通过 `maestro load --type session --id <id> --json` 按需加载完整 body 和 related 字段：
+- 仅加载 edited_files 与 cold_workflow_files 有交集的 session
+- 最多加载 10 个（按交集文件数降序排序）
+- 结果写入 `.workflow/.drift-realign/session-details-{date}.json`
+- scanner agent 在 deep 模式下同时接收 timeline.json + session-details.json
+</execution>
+
+<completion>
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| codebase 文档已重建 | `/manage-status` |
+| spec 标记待更新 | 手动编辑标记的 spec 文件 |
+| roadmap 已过时 | `/maestro-roadmap` 重新生成 |
+| state.json 需清理 | `/manage-knowledge-audit --scope artifact` |
+| 需要完整同步 | `/quality-sync --full` |
+| project.md 已过时 | 编辑 `.workflow/project.md` |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | `.workflow/` 未初始化 | 先跑 `/maestro-init` |
+| E002 | error | `--scope` 非法 | 提供有效 scope: roadmap/spec/codebase/state/issue/knowhow/project/all |
+| E003 | error | git 不可用（非 git 仓库） | 初始化 git |
+| E004 | error | `--since` 无法解析 | 检查日期格式或 commit ref |
+| E005 | error | 备份失败 | 检查磁盘空间 |
+| W001 | warning | session 历史不可用（wiki 未索引） | 运行 `maestro wiki rebuild` |
+| W002 | warning | `drift_window` > 180 天 | 建议使用 `--depth deep` |
+| W003 | warning | 部分 scanner agent 失败 | 以部分覆盖继续 |
+| W004 | warning | git log > 1000 commits | 自动截断至最近 1000 条 |
+</error_codes>
+
+<success_criteria>
+- [ ] Scope 正确解析，互斥标志校验通过
+- [ ] `maestro timeline` 已调用，`timeline.json` 已生成
+- [ ] `drift_score` 已计算（LOW/MODERATE/SEVERE 已展示）
+- [ ] 4 个并行 scanner agent 已派发
+- [ ] `DriftFinding[]` 已合并并按 P0 > P1 > P2 排序
+- [ ] 如 `--interactive`：用户已分诊所有 finding
+- [ ] 变更前备份 tarball 已生成
+- [ ] archive 动作已将文件移入 `.trash/`
+- [ ] update 动作已注入 TODO 标记及提示
+- [ ] rebuild 动作已自动触发 `/quality-sync --full`
+- [ ] `state.json` 已更新 `last_drift_realign` 时间戳
+- [ ] `drift-report-{date}.md` 已生成
+- [ ] `drift-log.jsonl` 已追加
+- [ ] 摘要展示及下一步路由已输出
+</success_criteria>

package/.codex/skills/maestro/SKILL.md

@@ -44,7 +44,7 @@ $ARGUMENTS — user intent text, or special flags.
 4. **Goal is tool-created** — `A_DECOMPOSE_TASKS` calls `create_goal` with sub-goal success criteria. `update_goal` on convergence; held while aborted/paused
 5. **status.json 唯一真源** — 不生成 `goal-checklist.md`；step 含 `command_scope` + `command_path` + `completion_confirmed`
 6. **Topology awareness** — chain catalog 含 grill / brainstorm / blueprint / analyze-macro(text) / analyze(numeric) / roadmap / plan(三路径) / execute / ...
-6.5. **Grill is interactive-only** — auto_mode MUST skip grill stage and route directly to brainstorm; grill requires Socratic Q&A with the user
+6.5. **Grill auto_mode 透传** — auto_mode 时为 grill step args 追加 `-y`（grill Auto mode 代码代答），stage 不跳过，产出 grill-report/terminology/context-package
 7. **D-007 milestone 反查** — 数字 phase 步骤的 `milestone_id` 由 `state.json.milestones[].phase_slugs` 反查
 8. **schema 向后兼容** — decomposition 字段可选；`steps[]` 由 post-goal-audit 动态生长（goal_ref tagged）；既有字段不删不改；`waves` 保留空数组
 9. **Sequential execution** — one step at a time in index order; each step's result read before the next starts
@@ -155,7 +155,7 @@ Extract:
 
 | task_type | When user intent is about... |
 |-----------|---------------------------|
-| `grill` | Stress-test, challenge assumptions, Socratic questioning on a plan/idea (**skip when auto_mode — grill is interactive-only**) |
+| `grill` | Stress-test, challenge assumptions, Socratic questioning on a plan/idea (**auto_mode: 透传 `-y`，grill Auto mode 代码代答，不跳过**) |
 | `quick` | Simple/small task, add a feature, quick change |
 | `blueprint` | Formal spec generation (Product Brief / PRD / Architecture / Epics) |
 | `analyze_macro` | Broad/medium intent w/o numeric phase — explore impact, produce scope_verdict |
@@ -213,7 +213,7 @@ Extract:
 1. `issue_id` present → prefer issue chains
 2. UI/design/界面/页面/原型 → prefer `ui_design`
 3. 正式规格/spec-generate/7-phase → `blueprint` (single-step) 或 `blueprint-driven`
-4. 压力测试/拷问/grill/stress-test → `grill` (single-step); **auto_mode → skip grill, route to `brainstorm-driven` instead**
+4. 压力测试/拷问/grill/stress-test → `grill` (single-step); **auto_mode → 透传 `-y`，不跳过**
 5. 头脑风暴/探索 → `brainstorm-driven`
 5. Broad/medium intent + 无数字 phase → `analyze_macro`（产 scope_verdict）；后续 large→roadmap链；medium/small→`plan_from_analyze`
 6. 已有 analyze artifact 直达 plan → `plan_from_analyze`
@@ -292,6 +292,7 @@ Read `.workflow/state.json` and route by condition:
    ```json
    {
      "session_id", "source": "maestro", "intent", "task_type", "chain_name",
+     "ralph_protocol_version": "2", "active_step_index": null,
      "phase", "phase_is_new": false, "milestone": "",
      "scope_verdict": null, "analyze_macro_id": null, "blueprint_id": null,
      "auto_mode": false,
@@ -306,13 +307,18 @@ Read `.workflow/state.json` and route by condition:
        "milestone_id": null, "source_artifact_ref": null,
        "status": "pending", "goal_ref": null,
        "completion_confirmed": false, "completion_status": null,
-       "completion_evidence": null, "completed_at": null
+       "completion_evidence": null,
+       "completion_summary": null, "completion_decisions": null,
+       "completion_caveats": null, "completion_deferred": null,
+       "completed_at": null
      }],
      "waves": [], "current_step": 0, "status": "running",
      "boundary_contract": {}, "execution_criteria": [],
      "task_decomposition": [{ "id": "G1", "goal": "", "done_when": "", "evidence": "",
-       "status": "pending|done", "completion_confirmed": false, "completed_at": null }],
-     "task_decomposition_all_done": false
+       "status": "pending|done|superseded", "completion_confirmed": false, "completed_at": null,
+       "superseded_by": null, "superseded_at": null, "origin": null }],
+     "task_decomposition_all_done": false,
+     "goal_changelog": []
    }
    ```
    Decomposition fields written ONLY if A_DECOMPOSE_TASKS produced them (additive)
@@ -348,7 +354,7 @@ Direct in-context skill invocation — **replaces the old spawn/wave/CSV mechani
    **--from auto-injection**: 当 step 是 `maestro-plan`，args 含 `{phase}` 但无 `--from` 且无 `--dir`，且 `session.context.analysis_dir` 已填充 → 查 state.json 同 phase+milestone 最新 completed analyze artifact → 注入 `--from analyze:{id}`，写 `step.source_artifact_ref`
 2. Mark step `status="running"`, persist status.json + `update_plan` (this step → in_progress)
 3. **Invoke the skill directly**: execute `$skill {resolved_args}` in coordinator context (NO spawn). Read its produced artifacts directly
-4. On success: capture summary; mark step `status="done"`. **Barrier-context update** (when step is a context-producing skill):
+4. On success: mark step `status="done"`. **Structured completion**: `Bash("maestro ralph complete {idx} --status DONE --summary \"...\" [--decisions \"...\"] [--caveats \"...\"] [--deferred \"...\"]")`（`--summary` MUST，动词开头 ≤100 字）。**Barrier-context update** (when step is a context-producing skill):
    | Skill | Read | Context Updates |
    |-------|------|-----------------|
    | maestro-grill | grill-report.md, state.json | grill_id |
@@ -470,7 +476,7 @@ S_DECISION_EVAL 入口；镜像 maestro-ralph `A_GOAL_AUDIT_EVALUATE`。Condense
 | `deploy` | quality-review → maestro-milestone-release |
 | `blueprint-driven` | maestro-init → [B] maestro-blueprint → [B] maestro-plan --from blueprint:{BLP} → [B] maestro-execute → quality-review → manage-harvest --auto |
 | `analyze-macro-driven` | [B] maestro-analyze "{intent}" → ◆ post-analyze-scope → (large: [B] maestro-roadmap --from analyze:{ANL} → [B] maestro-analyze {phase} → [B] maestro-plan {phase}) / (medium\|small: [B] maestro-plan --from analyze:{ANL}) → [B] maestro-execute → quality-review → manage-harvest --auto |
-| `grill-brainstorm` | [B] maestro-grill → [B] maestro-brainstorm --from grill:{GRL} → [B] maestro-plan → [B] maestro-execute → quality-review → manage-harvest --auto (**auto_mode: skip grill step, fall back to brainstorm-driven**) |
+| `grill-brainstorm` | [B] maestro-grill → [B] maestro-brainstorm --from grill:{GRL} → [B] maestro-plan → [B] maestro-execute → quality-review → manage-harvest --auto (**auto_mode: grill 透传 `-y`，Auto mode 代码代答**) |
 | `brainstorm-driven` | [B] maestro-brainstorm → [B] maestro-plan → [B] maestro-execute → quality-review → manage-harvest --auto |
 | `ui-craft-build` | maestro-impeccable build → [B] maestro-plan → [B] maestro-execute → quality-review → manage-harvest --auto |
 | `roadmap-driven` | maestro-init → [B] maestro-roadmap → [B] maestro-plan → [B] maestro-execute → quality-review → manage-harvest --auto |
@@ -543,6 +549,8 @@ S_DECISION_EVAL 入口；镜像 maestro-ralph `A_GOAL_AUDIT_EVALUATE`。Condense
 - [ ] --dry-run shows chain + sub-goal summary, no execution
 - [ ] --continue resumes from first pending step
 - [ ] update_goal released on convergence (A_APPLY_GOAL_DONE / A_FINALIZE); held while aborted
+- [ ] 每个 step completion 含 `--summary`（MUST）+ `--decisions/--caveats/--deferred`（SHOULD）
+- [ ] task_decomposition 支持 `superseded` 状态 + `goal_changelog` 审计轨迹
 
 ### Report Format