maestro-flow 0.5.37 → 0.5.38

package/.agy/skills/maestro-ralph/SKILL.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:
   - ask_question
   - grep_search
@@ -15,6 +15,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.
 
@@ -22,8 +26,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:**
@@ -69,6 +74,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>
 
@@ -77,6 +83,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
@@ -163,6 +171,11 @@ S_APPLY_VERDICT:
   GUARD: not auto_confirm → ask_question 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 无效，必须 ask_question
+
 S_FALLBACK:
   → S_PARSE_ROUTE   WHEN: user provides input               DO: ask_question
   → END             WHEN: user cancels
@@ -402,7 +415,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}`
@@ -413,7 +430,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}`
@@ -538,9 +555,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 验证累积执行是否漂移
@@ -554,8 +574,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
@@ -566,7 +588,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
@@ -644,6 +667,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` 非空 → 直接用；为空 → ask_question（修改/新增/移除/调整边界） | `change_type` + `change_request` |
+| 3. Mini Grill | `maestro delegate --role analyze --mode analysis`：评估影响 | RISK_LEVEL + AFFECTED_GOALS + INVALIDATED_STEPS + NEW_GAPS |
+| 4. 确认 | ask_question：应用并继续 / 仅改目标 / 取消 | 用户选择 |
+| 5. 应用 | 归档旧目标（`superseded`）→ 写入新目标（`origin: CHG-xxx`）→ 重建链路 → write status.json | handoff ralph-execute |
+
+GUARD: `RISK_LEVEL == high` → ask_question 不跳过（auto_confirm 无效）
+GUARD: 已完成（`status: "done"`）的目标不可 supersede（skip + warn）
+
 </actions>
 
 </state_machine>
@@ -656,7 +694,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,
@@ -691,6 +729,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 写入
@@ -704,10 +746,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":"..."}] } }
+  ]
 }
 ```
 
@@ -839,5 +893,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/.agy/skills/maestro-ralph-execute/SKILL.md

@@ -185,7 +185,9 @@ Write enriched args + source_artifact_ref back to status.json.
    - 退出码 2 → 交给 S_LOCATE
    - 退出码 3 → active_step_index 已被占用
    - 退出码 1 → pause session
-2. **Goal context pre-injection** — 若 A_RESOLVE_ARGS 产出了 `goal_snippet`（step.goal_ref 非空），在 ralph next stdout prompt **顶部前置**以下 block，使执行命令感知当前子目标和执行约束：
+2. **Goal context pre-injection**:
+   - GUARD: `ralph_protocol_version >= "2"` → skip（session_anchor 已含 goal context）
+   - WHEN `ralph_protocol_version < "2"` 或缺失 AND `step.goal_ref` 非空 → 在 stdout 顶部前置：
    ```
    <goal_context>
    Sub-goal: {goal.id} — {goal.goal}
@@ -195,13 +197,19 @@ Write enriched args + source_artifact_ref back to status.json.
    Execution criteria: {session.execution_criteria joined by '; '}
    </goal_context>
    ```
-   无 goal_snippet 时跳过此步。goal_context block 不替换 ralph next 的 stdout 内容，仅在其前方拼接。
-3. **Inline execution** — 按 stdout（含 goal_context 前置）执行；deferred_reading 按需 Read
+3. **Inline execution** — 按 stdout 执行；deferred_reading 按需 Read
 4. **Complete**:
-   - `run_command("maestro ralph complete N --status DONE [--evidence <path>]")`
-   - `run_command("maestro ralph complete N --status DONE_WITH_CONCERNS --concerns \"...\"")`
+   - `run_command("maestro ralph complete N --status DONE --summary \"...\" [--evidence <path>] [--decisions \"...\"] [--caveats \"...\"] [--deferred \"...\"]")`
+   - `run_command("maestro ralph complete N --status DONE_WITH_CONCERNS --summary \"...\" --concerns \"...\"")`
    - `run_command("maestro ralph retry N")`
    - `run_command("maestro ralph complete N --status BLOCKED --reason \"...\"")`
+
+   | Param | 必填 | 格式 | 示例 |
+   |-------|------|------|------|
+   | `--summary` | MUST | 动词开头，≤100 字 | `"实现搜索 API 分页逻辑，新增 3 端点"` |
+   | `--decisions` | SHOULD（可多次） | 每条一个决策 | `"选择 ELK 布局而非 dagre"` |
+   | `--caveats` | SHOULD | 后续注意事项 | `"X 模块 e2e 暂未覆盖新端点"` |
+   | `--deferred` | SHOULD（可多次） | 推迟工作 | `"性能优化留到 review 后"` |
 5. **Propagate context signals** — 关键信号 (`PHASE: N` / `scratch_dir: path` / `BLP-xxx`) 写入 `status.json.context`
 
 完成后 S_LOCATE 触发 `view_file(AbsolutePath="<agy-skills-dir>/maestro-ralph-execute/SKILL.md") + execute inline` 自调用。
@@ -280,8 +288,11 @@ Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。/maestro
 - [ ] 自调用持续到全部 completion_confirmed 或 paused
 - [ ] --from auto-injection：phase-level plan step 运行时从 state.json 查找同 phase+milestone 最新 completed analyze artifact → 注入 `--from analyze:{id}`，写 `source_artifact_ref`
 - [ ] --from auto-injection：phase-level execute step 运行时查找同 phase+milestone 最新 completed plan artifact → 注入 `--dir`，写 `source_artifact_ref`
-- [ ] Goal context injection：step.goal_ref 非空时从 task_decomposition 提取 goal_snippet，A_EXEC_STEP 在 ralph next stdout 顶部前置 `<goal_context>` block
+- [ ] Goal context injection：`ralph_protocol_version < "2"` → 前置 `<goal_context>` block；`>= "2"` → skip（session_anchor 覆盖）
 - [ ] Goal context 包含 sub-goal description、done_when、boundary、evidence、execution_criteria
 - [ ] 已有 `--from` 或 `--dir` 的 step 不被 auto-injection 覆盖
+- [ ] `--summary` 在 DONE/DONE_WITH_CONCERNS 时为 MUST（动词开头，≤100 字）
+- [ ] `--decisions`/`--caveats`/`--deferred` 为 SHOULD；存在关键决策/注意事项/推迟工作时填写
+- [ ] 结构化总结由 CLI 写入 status.json，session_anchor 自动聚合注入下游 step
 
 </appendix>

package/.agy/skills/manage-drift-realign/SKILL.md

@@ -0,0 +1,153 @@
+---
+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:
+  - ask_question
+  - define_subagent
+  - grep_search
+  - invoke_subagent
+  - manage_subagents
+  - replace_file_content
+  - run_command
+  - send_message
+  - view_file
+  - write_to_file
+---
+<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 时，使用 ask_question 询问用户修改主要在哪个平台进行。用户选择后以 `--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/.claude/commands/maestro-ralph-execute.md

@@ -187,7 +187,9 @@ Write enriched args + source_artifact_ref back to status.json.
    - 退出码 2 → 交给 S_LOCATE
    - 退出码 3 → active_step_index 已被占用
    - 退出码 1 → pause session
-2. **Goal context pre-injection** — 若 A_RESOLVE_ARGS 产出了 `goal_snippet`（step.goal_ref 非空），在 ralph next stdout prompt **顶部前置**以下 block，使执行命令感知当前子目标和执行约束：
+2. **Goal context pre-injection**:
+   - GUARD: `ralph_protocol_version >= "2"` → skip（session_anchor 已含 goal context）
+   - WHEN `ralph_protocol_version < "2"` 或缺失 AND `step.goal_ref` 非空 → 在 stdout 顶部前置：
    ```
    <goal_context>
    Sub-goal: {goal.id} — {goal.goal}
@@ -197,13 +199,19 @@ Write enriched args + source_artifact_ref back to status.json.
    Execution criteria: {session.execution_criteria joined by '; '}
    </goal_context>
    ```
-   无 goal_snippet 时跳过此步。goal_context block 不替换 ralph next 的 stdout 内容，仅在其前方拼接。
-3. **Inline execution** — 按 stdout（含 goal_context 前置）执行；deferred_reading 按需 Read
+3. **Inline execution** — 按 stdout 执行；deferred_reading 按需 Read
 4. **Complete**:
-   - `Bash("maestro ralph complete N --status DONE [--evidence <path>]")`
-   - `Bash("maestro ralph complete N --status DONE_WITH_CONCERNS --concerns \"...\"")`
+   - `Bash("maestro ralph complete N --status DONE --summary \"...\" [--evidence <path>] [--decisions \"...\"] [--caveats \"...\"] [--deferred \"...\"]")`
+   - `Bash("maestro ralph complete N --status DONE_WITH_CONCERNS --summary \"...\" --concerns \"...\"")`
    - `Bash("maestro ralph retry N")`
    - `Bash("maestro ralph complete N --status BLOCKED --reason \"...\"")`
+
+   | Param | 必填 | 格式 | 示例 |
+   |-------|------|------|------|
+   | `--summary` | MUST | 动词开头，≤100 字 | `"实现搜索 API 分页逻辑，新增 3 端点"` |
+   | `--decisions` | SHOULD（可多次） | 每条一个决策 | `"选择 ELK 布局而非 dagre"` |
+   | `--caveats` | SHOULD | 后续注意事项 | `"X 模块 e2e 暂未覆盖新端点"` |
+   | `--deferred` | SHOULD（可多次） | 推迟工作 | `"性能优化留到 review 后"` |
 5. **Propagate context signals** — 关键信号 (`PHASE: N` / `scratch_dir: path` / `BLP-xxx`) 写入 `status.json.context`
 
 完成后 S_LOCATE 触发 `Skill({ skill: "maestro-ralph-execute" })` 自调用。
@@ -282,8 +290,11 @@ Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。/maestro
 - [ ] 自调用持续到全部 completion_confirmed 或 paused
 - [ ] --from auto-injection：phase-level plan step 运行时从 state.json 查找同 phase+milestone 最新 completed analyze artifact → 注入 `--from analyze:{id}`，写 `source_artifact_ref`
 - [ ] --from auto-injection：phase-level execute step 运行时查找同 phase+milestone 最新 completed plan artifact → 注入 `--dir`，写 `source_artifact_ref`
-- [ ] Goal context injection：step.goal_ref 非空时从 task_decomposition 提取 goal_snippet，A_EXEC_STEP 在 ralph next stdout 顶部前置 `<goal_context>` block
+- [ ] Goal context injection：`ralph_protocol_version < "2"` → 前置 `<goal_context>` block；`>= "2"` → skip（session_anchor 覆盖）
 - [ ] Goal context 包含 sub-goal description、done_when、boundary、evidence、execution_criteria
 - [ ] 已有 `--from` 或 `--dir` 的 step 不被 auto-injection 覆盖
+- [ ] `--summary` 在 DONE/DONE_WITH_CONCERNS 时为 MUST（动词开头，≤100 字）
+- [ ] `--decisions`/`--caveats`/`--deferred` 为 SHOULD；存在关键决策/注意事项/推迟工作时填写
+- [ ] 结构化总结由 CLI 写入 status.json，session_anchor 自动聚合注入下游 step
 
 </appendix>