maestro-flow 0.5.41 → 0.5.43

package/.agy/skills/maestro-ralph-cli-execute/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: maestro-ralph-cli-execute
+description: Skill execution wrapper for delegate — execute skill, return structured result
+argument-hint: --session <id> | <skill-name> [args...]
+allowed-tools:
+  - ask_question
+  - grep_search
+  - replace_file_content
+  - run_command
+  - view_file
+  - write_to_file
+---
+<purpose>
+Thin execution wrapper for CLI delegation.
+
+Job: receive session ID (or skill name + args) → load via `maestro ralph next` → execute the skill → scan artifacts → output structured `---RESULT---` block.
+
+This command does NOT manage sessions, compose prompts, make decisions, or call `maestro ralph complete`. Completion 由 orchestrator (`/maestro-ralph-cli`) 负责：orchestrator 解析 `---RESULT---` 块后调用 `maestro ralph complete N --status <STATUS> --summary <SUMMARY> [--evidence ...] [--decisions ...] [--caveats ...] [--deferred ...]`，清 `active_step_index`。
+</purpose>
+
+<context>
+$ARGUMENTS — `--session <id>` (session mode) 或 `<skill-name> [args...]` (direct mode)
+
+**Parse:**
+```
+--session <id>  → session_id (session mode: skill 由 ralph next 从 status.json 解析，无需传 skill name)
+First token     → skill_name (direct mode only, e.g., maestro-plan, maestro-execute)
+Remaining       → skill_args (direct mode only)
+```
+
+`<execution_context>` 块由 ralph-cli delegation prompt 注入于 `$ARGUMENTS` 之前，含 intent、boundary、goals 等，透传给 skill。
+</context>
+
+<invariants>
+1. **Execute exactly one skill** — session mode 由 `ralph next` 解析，direct mode 由 skill_name 确定；执行一次即返回
+2. **Structured output** — always end with `---RESULT---` / `---END---` block
+3. **No session management** — never create/modify sessions, make decisions, or call `maestro ralph complete`（completion 由 orchestrator 负责）
+4. **No self-invocation** — execute once and return
+5. **Artifact scanning** — after skill execution, scan for produced artifacts
+6. **Required reading 由 CLI 负责** — session mode 下 `ralph next` 自动展开 + 加载 `<required_reading>`，缺失 → exit 1（E007），cli-execute 不手动处理
+7. **Deferred reading 只记录** — `<deferred_reading>` 路径由 CLI 记录到 `step.load.deferred_files`，执行阶段按需 Read，不提前批量读取
+8. **并发保护** — 同一 session 最多一个 step 持 `active_step_index`；`ralph next` exit 3 表示冲突，不静默推进
+9. **STATUS 枚举受限** — 仅 `DONE | DONE_WITH_CONCERNS | NEEDS_RETRY | BLOCKED`；`NEEDS_CONTEXT` 已废除
+10. **CLI 输出禁止截断** — `maestro ralph next` 的 stdout 必须全量捕获，严禁 `| head`/`| tail` 等截断管道
+</invariants>
+
+<state_machine>
+
+<states>
+S_PARSE     — 解析 skill name + args              PERSIST: —
+S_EXECUTE   — 执行 skill                          PERSIST: —
+S_SCAN      — 扫描产物 + 提取信号                   PERSIST: —
+S_OUTPUT    — 输出结构化结果                        PERSIST: —
+</states>
+
+<transitions>
+S_PARSE → S_EXECUTE    DO: A_PARSE_ARGS
+S_EXECUTE → S_SCAN     DO: A_EXECUTE_SKILL
+S_SCAN → S_OUTPUT      DO: A_SCAN_ARTIFACTS
+S_OUTPUT → END         DO: A_OUTPUT_RESULT
+</transitions>
+
+<actions>
+
+### A_PARSE_ARGS
+
+1. Parse `--session <id>` → `session_id`（session mode）
+2. 无 `--session` → extract `skill_name`（first token）and `skill_args`（remaining）为 direct mode
+3. Parse `<execution_context>` block from delegation prompt if present:
+   ```
+   intent, phase, boundary_contract, active_goals, execution_criteria
+   ```
+
+### A_EXECUTE_SKILL
+
+1. If `session_id` present → `run_command("maestro ralph next --session {session_id}")` — CLI loads skill + required_reading, returns prompt
+   - **必须全量捕获 stdout，严禁 `| head`/`| tail` 等任何截断管道**（stdout 含完整 skill prompt，截断会导致执行内容不完整）
+   - Exit 0 → 按 stdout 内联执行（stdout 含 CLI 拼接好的完整 prompt + session_anchor）
+   - Exit 1 → required_reading 缺失或 schema 错误 → set `status = "BLOCKED"`, skip to S_OUTPUT, SUMMARY 引用 CLI stderr
+   - Exit 2 → 无 pending step（已全部完成）→ set `status = "DONE"`, SUMMARY = "所有 step 已完成", skip to S_OUTPUT
+   - Exit 3 → active_step_index 冲突（另一进程占用）→ set `status = "BLOCKED"`, SUMMARY = "并发冲突", skip to S_OUTPUT
+2. If no session → `Skill({ skill: skill_name, args: skill_args })` — direct skill call
+3. **Goal context**: `ralph next` CLI 输出的 session_anchor 已含 goal context（`ralph_protocol_version >= "2"`），无需额外注入
+4. **Deferred reading**: `ralph next` 将 `<deferred_reading>` 路径记录到 `step.load.deferred_files`，执行阶段按需 Read
+5. **Inline execution** — 按 stdout 内容执行 skill 逻辑；执行完成后进入 S_SCAN
+6. Track execution: note start time, watch for errors
+
+### A_SCAN_ARTIFACTS
+
+After skill execution, scan for produced artifacts:
+
+| Pattern | Stage signal |
+|---------|-------------|
+| `conclusions.json` | `analysis_dir` |
+| `TASK-*.json` | `plan_dir` |
+| `verification.json` | `scratch_dir` |
+| `review.json` | review stage |
+| `test-results.json`, `uat.md` | test stage |
+| `grill-report.md` | `grill_id` |
+| `.brainstorming/*` | `brainstorm_dir` |
+
+Use `Glob` to find files created/modified during execution.
+
+Extract signals from output:
+- Artifact IDs: `ANL-xxx`, `PLN-xxx`, `BLP-xxx`
+- Path signals: `scratch_dir:`, `plan_dir:`
+- Phase signals: `PHASE: N`
+
+### A_OUTPUT_RESULT
+
+Output structured result block.
+
+```
+---RESULT---
+STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_RETRY|BLOCKED
+SUMMARY: <动词开头，≤100 字的执行总结>
+ARTIFACTS: <逗号分隔的产物路径>
+EVIDENCE: <验证产物路径，如 verification.json、uat.md、e2e-results.json>
+DECISIONS: <本步做出的关键决策，分号分隔>
+CAVEATS: <后续步骤需注意的事项；DONE_WITH_CONCERNS 时同时作为 concerns>
+DEFERRED: <推迟到后续的工作项，分号分隔>
+SIGNALS: <key=value 对，分号分隔，如 plan_dir=.workflow/scratch/PLN-xxx;phase=2>
+---END---
+```
+
+**Rules:**
+- STATUS 必填，从执行结果推断（仅 4 个合法值，NEEDS_CONTEXT 已废除）
+- SUMMARY 必填（DONE/DONE_WITH_CONCERNS 时为 MUST），动词开头
+- ARTIFACTS 列出所有新增/修改的产物文件路径
+- EVIDENCE 为 SHOULD，列出验证产物路径
+- DECISIONS/CAVEATS/DEFERRED 为 SHOULD，有则填
+- SIGNALS 提取 A_SCAN_ARTIFACTS 发现的 key=value 对
+
+**SIGNALS→context 映射：**
+
+| Signal key | 写入 status.json 字段 |
+|------------|----------------------|
+| `analysis_dir` | `context.analysis_dir` |
+| `plan_dir` | `context.plan_dir` |
+| `scratch_dir` | `context.scratch_dir` |
+| `grill_id` | `context.grill_id` |
+| `brainstorm_dir` | `context.brainstorm_dir` |
+| `blueprint_dir` | `context.blueprint_dir` |
+| `ANL-xxx` | `session.analyze_macro_id` |
+| `BLP-xxx` | `session.blueprint_id` |
+| `phase` | `session.context.phase` |
+
+**Stage-specific SUMMARY 提取指引：**
+
+| Stage | SUMMARY 应包含 | EVIDENCE 来源 |
+|-------|---------------|---------------|
+| analyze | scope_verdict + key_findings 数量 + 依赖图摘要 | `conclusions.json` |
+| plan | TASK-*.json 数量 + 主要模块 + 波次划分 | — |
+| execute | 修改文件数 + verification passed/failed | `verification.json` |
+| review | verdict + findings 数量 + severity 分布 | `review.json` |
+| test | pass/fail 统计 | `uat.md`, `test-results.json` |
+| debug | root cause + 修复内容 | — |
+| grill | 核心质疑点数量 + 术语表 | `grill-report.md` |
+| brainstorm | 候选方案数量 + 推荐方案 | — |
+
+**STATUS determination:**
+- Skill 正常完成 + 有产物 → `DONE`
+- 完成但有 warnings/concerns → `DONE_WITH_CONCERNS`
+- 执行出错但可重试 → `NEEDS_RETRY`
+- 执行出错且无法重试 → `BLOCKED`
+
+</actions>
+
+</state_machine>
+
+<appendix>
+
+### Output Example
+
+```
+---RESULT---
+STATUS: DONE
+SUMMARY: 生成 8 个 task 覆盖认证模块 3 个子系统，wave 1 含 5 个独立 task
+ARTIFACTS: .workflow/scratch/PLN-20260628/TASK-001.json,.workflow/scratch/PLN-20260628/TASK-002.json,.workflow/scratch/PLN-20260628/plan.json
+EVIDENCE:
+DECISIONS: 选择 wave 模式分 2 波执行；JWT 和 session 分离为独立 task
+CAVEATS: 模块 X 的外部 API 尚未确认，TASK-003 可能需调整
+DEFERRED: 性能基准测试留到 review 后
+SIGNALS: plan_dir=.workflow/scratch/PLN-20260628;PLN-xxx=PLN-20260628
+---END---
+```
+
+### Error Output
+
+```
+---RESULT---
+STATUS: BLOCKED
+SUMMARY: maestro-plan 执行失败：required_reading 文件 analyze-guide.md 缺失
+ARTIFACTS:
+EVIDENCE:
+DECISIONS:
+CAVEATS:
+DEFERRED:
+SIGNALS:
+---END---
+```
+
+### Error Codes
+
+| Code | Exit | Severity | Description | STATUS |
+|------|------|----------|-------------|--------|
+| E006 | 1 | error | command_path 缺失/不可达 | BLOCKED |
+| E007 | 1 | error | required_reading 引用文件缺失 | BLOCKED |
+| E008 | 1 | error | active_step_index 与 complete idx 不匹配 | BLOCKED |
+| E009 | 1 | error | step.status ≠ running（重复 complete 或非法跳跃）| BLOCKED |
+| E010 | 1 | error | status.json schema 损坏 | BLOCKED |
+| — | 2 | info | 无 pending step（全部已完成）| DONE |
+| — | 3 | error | active_step_index 并发冲突 | BLOCKED |
+| W001 | 0 | warning | Step completed with concerns | DONE_WITH_CONCERNS |
+
+### Success Criteria
+
+- [ ] Session mode 只需 `--session <id>`，skill 由 `ralph next` 从 status.json 解析
+- [ ] Direct mode 解析 `skill_name` + `skill_args`
+- [ ] Session mode 通过 `maestro ralph next --session {id}` 加载；stdout 全量捕获，禁止截断管道
+- [ ] Exit codes 完整处理：0→执行，1→BLOCKED，2→DONE，3→BLOCKED
+- [ ] Execute via `maestro ralph next` (session mode) or `Skill()` (direct mode)
+- [ ] Scan artifacts after execution using Glob
+- [ ] Extract artifact IDs and path signals from output
+- [ ] Always output `---RESULT---` / `---END---` block
+- [ ] STATUS 仅 4 个合法值：DONE / DONE_WITH_CONCERNS / NEEDS_RETRY / BLOCKED
+- [ ] SUMMARY 在 DONE/DONE_WITH_CONCERNS 时为 MUST（动词开头，≤100 字）
+- [ ] EVIDENCE 字段列出验证产物路径
+- [ ] SIGNALS 含 stage-specific key=value 对（参照 SIGNALS→context 映射表）
+- [ ] Stage-specific SUMMARY 提取指引（analyze→scope_verdict，plan→TASK 数量 等）
+- [ ] No session management, no self-invocation, no decisions, no `ralph complete`
+- [ ] Deferred reading 按需 Read，不提前批量读取
+
+</appendix>
+</output>

package/.agy/skills/maestro-ralph-execute/SKILL.md

@@ -59,7 +59,9 @@ HARD RULES:
 <states>
 S_LOCATE        — 定位 session + 找下一个 pending step   PERSIST: —
 S_RESOLVE_ARGS  — 解析占位符 + 丰富参数                  PERSIST: step.args (enriched)
+S_LOAD_CONTEXT  — 加载前序产出 + 发现                    PERSIST: —
 S_EXECUTE       — 执行当前 step                          PERSIST: step.status = "running", session.current_step
+S_POST_ANALYZE  — 产物 vs 目标偏离分析                    PERSIST: step.drift_score, step.drift_correction
 S_POST_EXEC     — 标记完成 + 传播上下文                   PERSIST: step.completion_*, step.status, session.context
 S_HANDLE_FAIL   — 处理失败                               PERSIST: step.status, session.status
 S_COMPLETE      — 所有 step 完成                         PERSIST: session.status = "completed"
@@ -74,18 +76,28 @@ S_LOCATE:
   → S_FALLBACK      WHEN: no running session
 
 S_RESOLVE_ARGS:
-  → S_EXECUTE       DO: A_RESOLVE_ARGS
+  → S_LOAD_CONTEXT  DO: A_RESOLVE_ARGS
+
+S_LOAD_CONTEXT:
+  → S_EXECUTE       DO: A_LOAD_STEP_CONTEXT
 
 S_EXECUTE:
   → END             WHEN: step.decision != null              DO: A_EXEC_DECISION
-  → S_POST_EXEC     WHEN: step.decision == null + ralph complete invoked with DONE|DONE_WITH_CONCERNS  DO: A_EXEC_STEP
-  → S_HANDLE_FAIL   WHEN: step.decision == null + ralph next exit≠0 OR ralph complete with NEEDS_RETRY|BLOCKED  DO: A_EXEC_STEP
+  → S_POST_ANALYZE  WHEN: step.decision == null + execution succeeded (DONE|DONE_WITH_CONCERNS)  DO: A_EXEC_STEP
+  → S_HANDLE_FAIL   WHEN: step.decision == null + ralph next exit=1 OR ralph complete with NEEDS_RETRY|BLOCKED  DO: A_EXEC_STEP
+  → S_HANDLE_FAIL   WHEN: step.decision == null + ralph next exit=3 (concurrency conflict)  DO: A_HANDLE_CONCURRENCY
+
+S_POST_ANALYZE:
+  → S_POST_EXEC     WHEN: drift_score == ALIGNED|MINOR_DRIFT   DO: A_POST_ANALYZE_DRIFT
+  → S_EXECUTE       WHEN: drift_score == MAJOR_DRIFT + not retried  DO: A_POST_ANALYZE_DRIFT (re-execute with correction)
+  → S_POST_EXEC     WHEN: drift_score == MAJOR_DRIFT + retried     DO: A_POST_ANALYZE_DRIFT (proceed with caveats)
 
 S_POST_EXEC:
   → S_LOCATE        DO: run_command("maestro ralph complete ...") + Skill("maestro-ralph-execute")
                      NOTE: CLI 已写完 completion_*, status, active_step_index；无需额外写盘
 
 S_HANDLE_FAIL:
+  → S_LOCATE        WHEN: exit code 3 (concurrency conflict)  DO: A_HANDLE_CONCURRENCY (wait 3s + retry)
   → S_LOCATE        WHEN: auto + not retried               DO: A_RETRY
   → END             WHEN: auto + retried                    DO: A_PAUSE_SESSION
   → S_LOCATE        WHEN: interactive + user selects retry  DO: A_RETRY
@@ -171,6 +183,27 @@ if goal:
 
 Write enriched args + source_artifact_ref back to status.json.
 
+### A_LOAD_STEP_CONTEXT
+
+加载前序产出和发现，为 inline execution 注入上下文。
+
+1. **Previous step output** — 读前一 completed step 的 `completion_summary` + `completion_caveats` + `completion_decisions` + `completion_deferred`
+2. **Artifacts** — 按 `session.context` 中的路径逐个 Read，提取与当前 step 相关的内容：
+
+   | 当前 stage | 加载什么 | Source |
+   |-----------|---------|--------|
+   | plan | analysis conclusions + scope_verdict | `{context.analysis_dir}/conclusions.json` |
+   | execute | task list + wave assignments | `{context.plan_dir}/TASK-*.json` |
+   | review | changed files + verification results | `{context.scratch_dir}/verification.json` |
+   | test | review findings | `review.json` |
+   | debug | error traces + failing test details | 前一 step 的 `completion_evidence` |
+   | brainstorm | grill report | `{context.grill_id}` report |
+
+3. **Explore if needed** — 产物指向代码位置但缺少上下文 → `maestro explore` 补充（仅 execute/debug/test 且有文件路径引用时）
+4. **Accumulated signals** — 遍历 ALL completed steps → 聚合 caveats + deferred
+
+加载的内容进入会话上下文，后续 inline execution 自动受益。
+
 ### A_EXEC_DECISION
 
 1. Mark step running, write status.json
@@ -198,22 +231,105 @@ Write enriched args + source_artifact_ref back to status.json.
    </goal_context>
    ```
 3. **Inline execution** — 按 stdout 执行；deferred_reading 按需 Read
-4. **Complete**:
+4. **Extract step signals** (A_EXTRACT_STEP_SIGNALS) — 执行完成后、调 ralph complete 前，提取结构化信号用于组装 completion 参数和下一步上下文：
+
+   **4a. Stage-specific signal extraction:**
+
+   | Stage | 提取什么 | 写入字段 |
+   |-------|---------|---------|
+   | analyze | `conclusions.json` 的 scope_verdict + key_findings; 依赖图摘要 | `--summary`, `--decisions`, context.analysis_dir |
+   | plan | 生成的 TASK-*.json 数量 + 主要模块; 波次划分 | `--summary`, context.plan_dir |
+   | execute | 修改的文件列表; verification.json passed/failed; 新 artifact ID | `--summary`, `--evidence`, context.scratch_dir |
+   | review | review.json verdict + findings 数量 + severity 分布 | `--summary`, `--decisions` |
+   | test | test-results.json pass/fail 统计; uat.md 结果 | `--summary`, `--evidence` |
+   | debug | root cause 描述; 修复了什么 | `--summary`, `--decisions` |
+   | grill | grill-report.md 核心质疑点; 术语表 | `--summary`, `--caveats`, context.grill_id |
+   | brainstorm | 候选方案数量 + 推荐方案 | `--summary`, `--decisions`, context.brainstorm_dir |
+
+   **4b. Compose completion params:**
+
+   | Param | 规则 | 组装方法 |
+   |-------|------|---------|
+   | `--summary` | MUST。动词开头，≤100 字。从 4a 提取的关键产出组合 | `"<动词><做了什么>，<量化结果>"` e.g. `"分析认证模块依赖图，发现 5 处 JWT 内联验证，scope=medium"` |
+   | `--decisions` | SHOULD。每条一个架构/技术决策（可多次 `--decisions`） | 从执行过程中做出的非显而易见的选择提取。e.g. `"选择中间件模式而非装饰器"` `"跳过 session 层重构，留给 G2"` |
+   | `--caveats` | SHOULD。后续 step 必须知道的约束/风险 | 从执行中发现但不属于本步解决的问题。e.g. `"session 存储层与 JWT 有隐式耦合，execute 阶段需处理"` |
+   | `--deferred` | SHOULD。明确推迟到后续的工作（可多次 `--deferred`） | 被主动推迟的项。e.g. `"性能基准测试留到 review 后"` `"错误码国际化不在 scope 内"` |
+
+   **4c. Context-to-next-step propagation checklist:**
+
+   | 信号 | 检查 | 传播到 |
+   |------|------|--------|
+   | PHASE 变更 | 输出含 `PHASE: N` | `session.context.phase` |
+   | Artifact ID | 输出含 `ANL-xxx`/`PLN-xxx`/`BLP-xxx` | `session.analyze_macro_id`/`context.plan_dir` 等 |
+   | Scratch dir | 输出含 `scratch_dir:` 或 `.workflow/scratch/` 路径 | `session.context.scratch_dir` |
+   | Plan dir | plan step 产出目录 | `session.context.plan_dir` |
+   | Grill ID | grill step 产出 ID | `session.context.grill_id` |
+   | Blueprint ID | blueprint step 产出 `BLP-xxx` | `session.blueprint_id` |
+
+   这些信号直接写入 `status.json.context`，下一步的 session_anchor 自动携带。
+
+5. **Complete** — 使用 4b 组装的参数调用：
    - `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`
+6. **Propagate context signals** — 按 4c checklist 将关键信号写入 `status.json.context`
 
 完成后 S_LOCATE 触发 `view_file(AbsolutePath="<agy-skills-dir>/maestro-ralph-execute/SKILL.md") + execute inline` 自调用。
 
+### A_POST_ANALYZE_DRIFT
+
+执行完成后、调 ralph complete 前，分析产物与目标的偏离程度并自动修正。
+
+**1. 收集对照基准:**
+
+| 基准来源 | 取值 |
+|---------|------|
+| `step.goal_ref` → goal.done_when | 子目标的完成条件 |
+| `session.boundary_contract.definition_of_done` | 全局验收标准 |
+| `session.execution_criteria` | 执行准则 |
+| `session.intent` | 原始意图 |
+
+**2. 读产物摘要:**
+
+从 A_EXTRACT_STEP_SIGNALS (step 4a) 已提取的 summary + decisions + artifacts 构建产物画像。
+
+**3. 对比评分:**
+
+| 维度 | 检查 |
+|------|------|
+| 覆盖度 | 产物是否覆盖了 goal.done_when 的每个条件 |
+| 方向性 | decisions 是否与 intent 和 boundary 一致 |
+| 完整性 | 预期产物类型是否齐全（如 plan 阶段应有 TASK-*.json） |
+
+**drift_score:**
+- `ALIGNED` — 全部维度通过
+- `MINOR_DRIFT` — 覆盖度/完整性有小缺口，不影响后续
+- `MAJOR_DRIFT` — 方向性偏离或关键产物缺失
+
+**4. 修正动作:**
+
+| drift_score | 动作 |
+|-------------|------|
+| ALIGNED | 正常进入 S_POST_EXEC |
+| MINOR_DRIFT | 将偏离项追加到 completion_caveats，正常 complete |
+| MAJOR_DRIFT + 未重试 | 将偏离分析写入 `step.drift_correction`，回到 S_EXECUTE 重跑（A_LOAD_STEP_CONTEXT 自动加载 drift_correction 作为修正上下文） |
+| MAJOR_DRIFT + 已重试 | 将偏离项写入 caveats + concerns，以 DONE_WITH_CONCERNS complete，由后续 decision node 裁决 |
+
+**5. 写入:**
+- `step.drift_score` — ALIGNED / MINOR_DRIFT / MAJOR_DRIFT
+- `step.drift_correction` — MAJOR_DRIFT 时的偏离描述 + 修正指引（供重跑时注入）
+
+### A_HANDLE_CONCURRENCY
+
+Exit code 3 — `active_step_index` occupied by another process (concurrency conflict).
+
+1. Display: `[{index}] ⚠ Concurrency conflict — active_step_index already held`
+2. Wait 3 seconds, then re-read `status.json` to check if `active_step_index` has been cleared
+3. If cleared → return to S_LOCATE (retry the step)
+4. If still held after 2 attempts → A_PAUSE_SESSION with reason "concurrency conflict unresolved — another process may be holding the lock"
+
 ### A_RETRY
 
 1. `run_command("maestro ralph retry N")` — CLI 设 `step.retried = true`, `step.status = "pending"`, `step.completion_confirmed = false`, 清 `active_step_index`

package/.agy/skills/maestro-roadmap/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-roadmap
 description: Generate roadmap with milestone/phase structure from requirements or upstream context
-argument-hint: <requirement> [-y] [-c] [-m progressive|direct|auto] [--from <source>] [--revise [instructions]] [--review]
+argument-hint: <requirement> [-y] [-c] [-m progressive|direct|auto] [--from <source>] [--from-brainstorm SESSION-ID] [--revise [instructions]] [--review]
 allowed-tools:
   - ask_question
   - define_subagent
@@ -98,14 +98,6 @@ Sub-modes:
 - REQUIRED: Artifact registered in state.json with milestone entries.
 - BLOCKED if missing: do not report completion without written roadmap.
 
-### Artifact Verification (before completion)
-
-```
-REQUIRED_ARTIFACTS = [
-  ".workflow/roadmap.md"    // Milestone > Phase hierarchy with progress table
-]
-```
-If missing: DO NOT report completion.
 
 </execution>
 

package/.agy/skills/maestro-swarm-workflow/SKILL.md

@@ -91,20 +91,22 @@ S_FALLBACK:
 
 ### A_ROUTE_SCRIPT
 
-Intent-to-script routing（按关键词匹配，--script 优先级最高）：
-
-| Keywords | Script |
-|----------|--------|
-| 分析 / analyze / 探索 / explore / 架构 / architecture / 复杂度 / 风险 | `wf-analyze` |
-| 头脑风暴 / brainstorm / 方案 / 设计 / 评估 / evaluate / 多角度 | `wf-brainstorm` |
-| 审查 / review / 代码审查 / code review / 质量 / quality | `wf-review` |
-| 验证 / verify / 检查 / check / 反模式 / antipattern | `wf-verify` |
-| 拷问 / grill / 压力测试 / stress-test / 挑战 / challenge | `wf-grill` |
-| 规划 / plan / 任务分解 / decompose / 分波 / wave | `wf-plan` |
-| 执行 / execute / 实现 / implement / 开发 / develop | `wf-execute` |
-| 里程碑审计 / milestone-audit / 集成检查 / integration | `wf-milestone-audit` |
-
-多命中 → ask_question 让用户选择。
+Intent-to-script routing（按关键词匹配，--script 优先级最高）。
+
+**Priority ordering** — 按下表自上而下匹配，先命中先用。高优先级的具体关键词优先于低优先级的宽泛关键词（如 "grill" > "analyze"，"verify" > "check"）：
+
+| Priority | Keywords | Script |
+|----------|----------|--------|
+| 1 | 里程碑审计 / milestone-audit / 集成检查 / integration | `wf-milestone-audit` |
+| 2 | 拷问 / grill / 压力测试 / stress-test / 挑战 / challenge | `wf-grill` |
+| 3 | 验证 / verify / 反模式 / antipattern | `wf-verify` |
+| 4 | 审查 / review / 代码审查 / code review / 质量 / quality | `wf-review` |
+| 5 | 执行 / execute / 实现 / implement / 开发 / develop | `wf-execute` |
+| 6 | 规划 / plan / 任务分解 / decompose / 分波 / wave | `wf-plan` |
+| 7 | 头脑风暴 / brainstorm / 方案 / 评估 / evaluate / 多角度 | `wf-brainstorm` |
+| 8 | 分析 / analyze / 探索 / explore / 架构 / architecture / 复杂度 / 风险 | `wf-analyze` |
+
+**Disambiguation**: 多命中（同一优先级内多个关键词匹配不同脚本）→ ask_question 让用户选择。跨优先级命中取高优先级。
 
 ### A_ASSEMBLE_CONTEXT
 

package/.agy/skills/maestro-tools-register/SKILL.md

@@ -102,6 +102,21 @@ Use when {timing/trigger condition}.
 1. Step one ...
 ```
 
+**Confirm before writing** — Use `ask_question` to show the user the planned knowhow document (title, category, keywords, summary, step count) and spec ref entry before persisting:
+
+```
+question: "确认写入以下 knowhow 工具文档？"
+options:
+  - label: "确认写入"
+    description: "knowhow: {title} (category: {category}, keywords: {keywords}), spec ref entry"
+  - label: "修改后写入"
+    description: "调整 title/category/keywords 后重新确认"
+  - label: "取消"
+    description: "不写入任何文件"
+```
+
+User confirms → proceed; user edits → re-gather; user cancels → END.
+
 **Create knowhow tool document** in `.workflow/knowhow/` with `tool: true` in YAML frontmatter:
 ```yaml
 ---
@@ -117,7 +132,7 @@ summary: "Use when <timing>. <scope description>"
 1. Step one ...
 ```
 
-**Optionally register spec ref entry** for index discoverability:
+**Optionally register spec ref entry** (after user confirmation above) for index discoverability:
 ```bash
 maestro spec add <category> "<title>" "Use when <timing>. <scope summary>" --keywords "<csv>" \
   --description "<one-line summary>" --ref "knowhow/RCP-<slug>.md" --knowhow-type recipe

package/.agy/skills/maestro-ui-codify/SKILL.md

@@ -3,6 +3,7 @@ name: maestro-ui-codify
 description: Extract design system from code, generate reference package, persist as knowledge assets
 argument-hint: <source-path> [--package-name <name>] [--output-dir <path>] [--overwrite]
 allowed-tools:
+  - ask_question
   - define_subagent
   - grep_search
   - invoke_subagent
@@ -64,10 +65,19 @@ The workflow orchestrates 4 phases with deferred loading of phase-specific workf
 **GATE Phase 3 → Phase 4: Package → Knowhow**
 - REQUIRED: preview.html + preview.css generated as interactive showcase.
 - BLOCKED if missing: preview artifacts not generated — knowhow phase needs rendered reference for validation.
+- REQUIRED: ask_question confirmation before proceeding to knowhow generation:
+  ```
+  question: "Preview 生成完成。是否继续将设计系统持久化为 knowhow 知识资产？"
+  options:
+    - label: "继续生成 knowhow"
+      description: "调用 codify-to-knowhow 写入 AST/DCS assets 和 spec entries"
+    - label: "仅保留 preview，跳过 knowhow"
+      description: "保留 preview.html + preview.css，不写入知识库"
+  ```
 
 **GATE Phase 4 → Completion: Knowhow → Done**
 - REQUIRED: knowhow-manifest.json created with AST/DCS assets and spec entries.
-- REQUIRED: codify-to-knowhow called and completed.
+- REQUIRED: codify-to-knowhow called and completed (only after user confirmation at Phase 3→4 gate).
 - BLOCKED if missing: knowhow-manifest.json absent or codify-to-knowhow not invoked — knowledge assets not persisted.
 
 ### Artifact Verification (before completion)

package/.agy/skills/maestro-universal-workflow/SKILL.md

@@ -42,6 +42,7 @@ S_SCAN        — 扫描现有 workflow 库匹配            PERSIST: —
 S_DECIDE      — 用户选择：复用现有 / 生成新脚本       PERSIST: —
 S_DESIGN      — 分析任务、设计工作流结构              PERSIST: —
 S_GENERATE    — 生成脚本 → 写入文件 → node --check 验证  PERSIST: uwf-{slug}.js
+S_CONFIRM_EXEC — 确认执行前门控                       PERSIST: —
 S_EXECUTE     — 调用 Workflow 工具执行               PERSIST: —
 S_PERSIST     — 保存脚本到 dynamic/ 目录              PERSIST: —
 </states>
@@ -57,7 +58,7 @@ S_SCAN:
   → S_DESIGN    WHEN: no matches                    DO: A_SCAN_LIBRARY
 
 S_DECIDE:
-  → S_EXECUTE   WHEN: user picks existing script    DO: —
+  → S_EXECUTE   WHEN: user picks existing script    DO: A_CONFIRM_EXECUTE
   → S_DESIGN    WHEN: user wants new script         DO: —
   → S_DESIGN    WHEN: --from specified              DO: —
 
@@ -65,10 +66,15 @@ S_DESIGN:
   → S_GENERATE  DO: A_DESIGN_WORKFLOW
 
 S_GENERATE:
-  → S_EXECUTE   WHEN: Write + node --check pass AND NOT --dry-run  DO: A_GENERATE_SCRIPT
-  → S_PERSIST   WHEN: --dry-run (file already written)             DO: A_GENERATE_SCRIPT
-  → S_GENERATE  WHEN: node --check fails (retry ≤2)               DO: A_GENERATE_SCRIPT (fix & retry)
-  → END         WHEN: node --check fails after 2 retries          DO: report E003
+  → S_CONFIRM_EXEC  WHEN: Write + node --check pass AND NOT --dry-run  DO: A_GENERATE_SCRIPT
+  → S_PERSIST       WHEN: --dry-run (file already written)             DO: A_GENERATE_SCRIPT
+  → S_GENERATE      WHEN: node --check fails (retry ≤2)               DO: A_GENERATE_SCRIPT (fix & retry)
+  → END             WHEN: node --check fails after 2 retries          DO: report E003
+
+S_CONFIRM_EXEC:
+  → S_EXECUTE   WHEN: user confirms execution      DO: A_CONFIRM_EXECUTE
+  → S_PERSIST   WHEN: user declines execution       DO: —
+  → END         WHEN: user cancels                  DO: —
 
 S_EXECUTE:
   → S_PERSIST   WHEN: workflow completed             DO: A_EXECUTE_WORKFLOW
@@ -283,6 +289,23 @@ run_command({ command: 'node --check "path/to/uwf-{slug}.js"' })
 
 验证通过后进入 S_EXECUTE（若非 `--dry-run`）。
 
+### A_CONFIRM_EXECUTE
+
+Use `ask_question` to confirm before executing the generated or selected script:
+
+```
+question: "脚本已就绪，是否执行？"
+options:
+  - label: "执行"
+    description: "调用 Workflow 工具运行 {script_name}（预估 {agent_count} 个 agent）"
+  - label: "仅保存，不执行"
+    description: "保存脚本到 dynamic/ 目录，稍后手动执行"
+  - label: "取消"
+    description: "不执行也不保存"
+```
+
+User confirms → S_EXECUTE; user declines → S_PERSIST (save only); user cancels → END.
+
 ### A_EXECUTE_WORKFLOW
 
 **必须用 scriptPath 调用**（不用 script 内联字符串）：

package/.agy/skills/maestro-update/SKILL.md

@@ -20,7 +20,7 @@ $ARGUMENTS — optional flags.
 
 **Flags:**
 - `--dry-run` -- Preview migration plan without executing
-- `--force` -- Skip confirmation prompts
+- `--force` -- Skip confirmation prompts (intended for CI/automated contexts). Migration diff is still displayed even with `--force` to maintain audit visibility.
 - `--setup-only` -- Skip schema migration, run only the setup for current version
 
 **Version source:** `.workflow/state.json` → `version` field
@@ -68,24 +68,27 @@ IF `--dry-run` → display info and EXIT.
 ### Step 3: Execute
 
 ```
-1. Confirm (unless --force):
+1. Display migration diff (always — even with --force):
+   Show schema changes that will be applied.
+
+2. Confirm (unless --force):
    ask_question: "Upgrade v{current} → v{target}?"
    Options: [执行 / 取消]
 
-2. Create backup:
+3. Create backup:
    Bash: cp .workflow/state.json .workflow/state.json.backup-v{current}-{timestamp}
 
-3. Run schema migration (handles all intermediate steps automatically):
+4. Run schema migration (handles all intermediate steps automatically):
    Bash: npx tsx src/migrations/run.ts "$(pwd)" --json
    Parse result, display changes.
 
-4. IF failed → display backup restore command → EXIT
+5. IF failed → display backup restore command → EXIT
 
-5. Load version-specific setup:
+6. Load version-specific setup:
    Read: ~/.maestro/workflows/updates/update-v{target}-setup.md
    IF exists → follow completely (hooks, deps, knowledge system config)
 
-6. Display: "v{current} → v{target}: done"
+7. Display: "v{current} → v{target}: done"
 ```
 
 ### Step 4: Summary