maestro-flow 0.5.37 → 0.5.39

package/.agents/skills/maestro/SKILL.md

@@ -48,7 +48,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。
@@ -175,7 +175,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",
@@ -188,12 +188,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
@@ -234,7 +240,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 agent --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/.agents/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:
   - read_file
   - write_file
@@ -19,6 +19,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.
 
@@ -26,8 +30,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:**
@@ -73,6 +78,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>
 
@@ -81,6 +87,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
@@ -167,6 +175,11 @@ S_APPLY_VERDICT:
   GUARD: not auto_confirm → ask_user 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_user
+
 S_FALLBACK:
   → S_PARSE_ROUTE   WHEN: user provides input               DO: ask_user
   → END             WHEN: user cancels
@@ -406,7 +419,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}`
@@ -417,7 +434,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}`
@@ -542,9 +559,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 验证累积执行是否漂移
@@ -558,8 +578,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
@@ -570,7 +592,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
@@ -648,6 +671,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_user（修改/新增/移除/调整边界） | `change_type` + `change_request` |
+| 3. Mini Grill | `maestro delegate --role analyze --mode analysis`：评估影响 | RISK_LEVEL + AFFECTED_GOALS + INVALIDATED_STEPS + NEW_GAPS |
+| 4. 确认 | ask_user：应用并继续 / 仅改目标 / 取消 | 用户选择 |
+| 5. 应用 | 归档旧目标（`superseded`）→ 写入新目标（`origin: CHG-xxx`）→ 重建链路 → write status.json | handoff ralph-execute |
+
+GUARD: `RISK_LEVEL == high` → ask_user 不跳过（auto_confirm 无效）
+GUARD: 已完成（`status: "done"`）的目标不可 supersede（skip + warn）
+
 </actions>
 
 </state_machine>
@@ -660,7 +698,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,
@@ -695,6 +733,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 写入
@@ -708,10 +750,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":"..."}] } }
+  ]
 }
 ```
 
@@ -843,5 +897,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/.agents/skills/maestro-ralph-execute/SKILL.md

@@ -189,7 +189,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}
@@ -199,13 +201,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**:
-   - `shell("maestro ralph complete N --status DONE [--evidence <path>]")`
-   - `shell("maestro ralph complete N --status DONE_WITH_CONCERNS --concerns \"...\"")`
+   - `shell("maestro ralph complete N --status DONE --summary \"...\" [--evidence <path>] [--decisions \"...\"] [--caveats \"...\"] [--deferred \"...\"]")`
+   - `shell("maestro ralph complete N --status DONE_WITH_CONCERNS --summary \"...\" --concerns \"...\"")`
    - `shell("maestro ralph retry N")`
    - `shell("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 触发 `invoke_skill({ skill: "maestro-ralph-execute" })` 自调用。
@@ -284,8 +292,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/.agents/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:
+  - read_file
+  - write_file
+  - edit_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<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_user 询问用户修改主要在哪个平台进行。用户选择后以 `--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>