maestro-flow 0.5.41 → 0.5.43

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

@@ -61,7 +61,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"
@@ -76,18 +78,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: Bash("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
@@ -173,6 +185,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
@@ -200,22 +233,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 组装的参数调用：
    - `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`
+6. **Propagate context signals** — 按 4c checklist 将关键信号写入 `status.json.context`
 
 完成后 S_LOCATE 触发 `Skill({ skill: "maestro-ralph-execute" })` 自调用。
 
+### 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. `Bash("maestro ralph retry N")` — CLI 设 `step.retried = true`, `step.status = "pending"`, `step.completion_confirmed = false`, 清 `active_step_index`

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

@@ -42,7 +42,7 @@ Remaining     → intent (amend_mode 时为 change_request)
 <invariants>
 1. **Ralph never executes steps** — only creates sessions and evaluates decisions
 2. **Handoff via Skill("maestro-ralph-execute")** — 创建 session 后始终自动 handoff；decision 评估后始终 handoff
-3. **Decision delegates read-only** — `maestro delegate --role analyze --mode analysis`
+3. **Decision delegates read-only** — `maestro delegate --to <tool> --mode analysis`
 4. **执行 step 通过 `maestro ralph next` CLI 加载并内联执行**（详见 invariant 8）
 5. **status.json 是唯一真源** — 不生成 markdown 清单或侧文件
 6. **每个 step 必须 `completion_confirmed: true`** — 由 `maestro ralph complete N --status DONE`（或 DONE_WITH_CONCERNS）写入；CLI 是唯一合法写入路径
@@ -472,11 +472,11 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`（`sess
    ```
    maestro delegate "PURPOSE: 评估 {decision} 质量门结果
    TASK: 读取结果 | 分析状态 | 评估严重性 | 给出建议
-   EXPECTED: ---VERDICT--- STATUS/REASON/GAP_SUMMARY/CONFIDENCE(high|medium|low)/CONFIDENCE_SCORE(0-100)/WEAKEST_DIMENSION ---END---
+   EXPECTED: ---VERDICT--- STATUS(PASS|FAIL|PARTIAL|BLOCKED)/REASON/GAP_SUMMARY/CONFIDENCE(high|medium|low)/CONFIDENCE_SCORE(0-100)/WEAKEST_DIMENSION ---END---
    CONSTRAINTS: 只评估 | 置信度<60% 倾向 fix | retry {n}/{max} 达上限必须 escalate"
-   --role analyze --mode analysis
+   --to {session.cli_tool} --mode analysis
    ```
-6. On callback: parse verdict; if parse fails → fallback STATUS="fix", BUT MUST set `parse_failed: true` and `confidence_score: 0` in decision log (invariant 13). Subsequent steps inherit LOW CONFIDENCE flag.
+6. On callback: parse verdict block — STATUS must match strict enum `PASS|FAIL|PARTIAL|BLOCKED`; any other value → parse failure. If parse fails → fallback STATUS="fix", BUT MUST set `parse_failed: true` and `confidence_score: 0` in decision log (invariant 13). Subsequent steps inherit LOW CONFIDENCE flag.
 7. Confidence adjustment: <60 + proceed → fix; >95 + fix + retry>0 → suggest proceed
 8. **Decision log**: Append to `{session_dir}/decisions.ndjson`:
    ```json
@@ -545,7 +545,7 @@ Runs only when `task_decomposition` present.
      - 严格按 done_when 判定；evidence 缺失 → unmet
      - 不得建议超出 boundary_contract 的修改
    "
-   --role analyze --mode analysis
+   --to {session.cli_tool} --mode analysis
    ```
 4. On callback: 对每个 met 子目标，set `task_decomposition[i].status="done"` + `completion_confirmed=true` + `completed_at=now`
 5. Append `{session_dir}/decisions.ndjson` with `"type": "goal-gate"`, `unmet_count`, `unmet_ids`
@@ -592,7 +592,7 @@ GUARD: `task_decomposition` 存在（周期触发，见 build rule 5.5）
      - aligned 阈值：≥80% 已完成产出直接服务 intent
      - 单个 step 触碰 out_of_scope → 直接判 drifted
      - goal_changelog 存在 → 以最新 after.goals 为基准"
-   --role analyze --mode analysis
+   --to {session.cli_tool} --mode analysis
    ```
 3. On callback: parse verdict
 4. Append `{session_dir}/decisions.ndjson`：`{ "id": "DEC-{ts}", "type": "reground-gate", "source": "ralph", "node_id": "post-reground", "verdict": "{aligned|drifted}", "confidence_score": {N}, "drift_description": "...", "corrective_action": "..." }`
@@ -677,7 +677,7 @@ GUARD: `task_decomposition` 存在（周期触发，见 build rule 5.5）
 |-------|------|------|
 | 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 |
+| 3. Mini Grill | `maestro delegate --to {session.cli_tool} --mode analysis`：评估影响 | RISK_LEVEL + AFFECTED_GOALS + INVALIDATED_STEPS + NEW_GAPS |
 | 4. 确认 | AskUserQuestion：应用并继续 / 仅改目标 / 取消 | 用户选择 |
 | 5. 应用 | 归档旧目标（`superseded`）→ 写入新目标（`origin: CHG-xxx`）→ 重建链路 → write status.json | handoff ralph-execute |
 
@@ -890,7 +890,7 @@ decision:post-goal-audit {retry+1}
 - [ ] planning_mode 显式决定；unified=无 `{phase}`, independent=带 `{phase}`
 - [ ] specs 预检：lifecycle_position 在 init 之后 + `.workflow/specs/` 不存在 → 链路最前面插入 `spec-setup`
 - [ ] Chain 必须以 `milestone-complete` 结尾
-- [ ] Decision nodes 由 maestro delegate --role analyze 评估
+- [ ] Decision nodes 由 maestro delegate --to {session.cli_tool} --mode analysis 评估
 - [ ] Ralph 不执行 step，只 evaluate；Skill("maestro-ralph-execute") handoff
 - [ ] 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 查找注入）

package/.claude/commands/maestro-roadmap.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:
   - Read
   - Write
@@ -96,14 +96,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/.claude/commands/maestro-swarm-workflow.md

@@ -92,20 +92,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` |
-
-多命中 → AskUserQuestion 让用户选择。
+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**: 多命中（同一优先级内多个关键词匹配不同脚本）→ AskUserQuestion 让用户选择。跨优先级命中取高优先级。
 
 ### A_ASSEMBLE_CONTEXT
 

package/.claude/commands/maestro-tools-register.md

@@ -100,6 +100,21 @@ Use when {timing/trigger condition}.
 1. Step one ...
 ```
 
+**Confirm before writing** — Use `AskUserQuestion` 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
 ---
@@ -115,7 +130,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/.claude/commands/maestro-ui-codify.md

@@ -11,6 +11,7 @@ allowed-tools:
   - Grep
   - Agent
   - Skill
+  - AskUserQuestion
 ---
 <purpose>
 Extract design system from source code into tokens, reference package, and knowledge assets.
@@ -63,10 +64,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: AskUserQuestion 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/.claude/commands/maestro-universal-workflow.md

@@ -43,6 +43,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>
@@ -58,7 +59,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: —
 
@@ -66,10 +67,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
@@ -284,6 +290,23 @@ Bash({ command: 'node --check "path/to/uwf-{slug}.js"' })
 
 验证通过后进入 S_EXECUTE（若非 `--dry-run`）。
 
+### A_CONFIRM_EXECUTE
+
+Use `AskUserQuestion` 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/.claude/commands/maestro-update.md

@@ -21,7 +21,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
@@ -69,24 +69,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):
    AskUserQuestion: "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

package/.claude/commands/maestro.md

@@ -30,7 +30,7 @@ $ARGUMENTS — user intent text, or special keywords.
 
 **Flags:**
 - `-y` / `--yes` — Auto mode: skip clarification, skip confirmation, auto-skip on errors
-- `-c` / `--continue` — Resume previous session
+- `-c` / `--continue` — Resume previous session. **`-c` is reserved for `--continue` across all maestro commands** — downstream skills MUST NOT redefine `-c` for other purposes to prevent collision via transparent forwarding.
 - `--dry-run` — Show chain without executing
 - `--super` — Read and follow `maestro-super.md`
 </context>

package/.claude/commands/manage-codebase-rebuild.md

@@ -29,6 +29,8 @@ $ARGUMENTS -- optional flags.
 - `--force` -- Skip confirmation prompt and proceed directly
 - `--skip-commit` -- Do not auto-commit after rebuild
 
+**Confirmation gate:** Unless `--force` is set, prompt the user (AskUserQuestion) before executing git commit. Show the list of changed files and proposed commit message. If `--skip-commit` is set, skip the commit entirely.
+
 **Mapper agent assignments (when `--focus` omitted):**
 | Agent | Focus | Output file |
 |-------|-------|-------------|
@@ -66,6 +68,7 @@ Follow '~/.maestro/workflows/codebase-rebuild.md' completely.
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
 | E001 | error | .workflow/ not initialized | Run maestro-init first to create .workflow/ |
+| E002 | error | All 4 mapper agents failed | Abort rebuild; check agent configuration and retry |
 | W001 | warning | A mapper agent failed (partial results) | Retry failed mapper or accept partial results |
 | W002 | warning | `.workflow/codebase/` already exists -- user prompted for rebuild/skip | check_existing |
 | W003 | warning | KG validation failed (graph written with valid=false) | Review .kg-tmp/ artifacts, re-run KG pipeline |
@@ -75,7 +78,8 @@ Follow '~/.maestro/workflows/codebase-rebuild.md' completely.
 <success_criteria>
 - [ ] User confirmed rebuild (or --force used)
 - [ ] .workflow/codebase/ cleared and rebuilt from scratch (or scoped subset when --focus set)
-- [ ] All 4 mapper agents spawned (failures logged as W001)
+- [ ] All 4 mapper agents spawned (all-fail → E002; partial fail → W001)
+- [ ] If not --skip-commit: user confirmed git commit (or --force used) before committing
 - [ ] doc-index.json generated and valid
 - [ ] All documentation files regenerated
 - [ ] state.json updated with rebuild timestamp

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

@@ -1,7 +1,7 @@
 ---
 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]"
+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
@@ -43,7 +43,10 @@ Arguments: $ARGUMENTS
 
 **`--interactive`：** 逐项交互分诊（默认）。
 
-**互斥规则：** `--report` 覆盖 `--interactive`；`--auto-archive` 覆盖 `--interactive`。
+**互斥规则：**
+- `--report` 覆盖 `--interactive`
+- `--auto-archive` 覆盖 `--interactive`
+- `--report` 与 `--auto-archive` 互斥（同时传入 → E006）
 
 **状态文件读取：**
 - `.workflow/state.json`
@@ -127,6 +130,7 @@ Follow `~/.maestro/workflows/drift-realign.md` Stages 1-9 in order.
 | E003 | error | git 不可用（非 git 仓库） | 初始化 git |
 | E004 | error | `--since` 无法解析 | 检查日期格式或 commit ref |
 | E005 | error | 备份失败 | 检查磁盘空间 |
+| E006 | error | `--report` 与 `--auto-archive` 同时传入 | 二选一：`--report` 仅生成报告，`--auto-archive` 执行归档 |
 | W001 | warning | session 历史不可用（wiki 未索引） | 运行 `maestro wiki rebuild` |
 | W002 | warning | `drift_window` > 180 天 | 建议使用 `--depth deep` |
 | W003 | warning | 部分 scanner agent 失败 | 以部分覆盖继续 |

package/.claude/commands/manage-harvest.md

@@ -33,7 +33,10 @@ Arguments: $ARGUMENTS
 - `<session-id>` (e.g., `ANL-auth-20260410`, `WFS-xxx`) → `session` mode: harvest specific session
 - `<path>` (e.g., `.workflow/.analysis/ANL-auth-20260410/`) → `path` mode: harvest from explicit directory
 
-Flags, source registry (scan paths), and storage locations defined in workflow harvest.md.
+**Flags:**
+- `-y` / `--yes` — Skip confirmation prompts for all write operations (artifact selection, routing decisions, store writes). Useful for CI or batch harvesting.
+
+Additional flags, source registry (scan paths), and storage locations defined in workflow harvest.md.
 </context>
 
 <execution>

package/.claude/commands/manage-issue-discover.md

@@ -5,6 +5,7 @@ argument-hint: "[multi-perspective | by-prompt <prompt>] [-y] [--scope <glob>] [
 allowed-tools:
   - Read
   - Write
+  - Edit
   - Bash
   - Glob
   - Grep

package/.claude/commands/manage-kg-extractors.md

@@ -1,7 +1,7 @@
 ---
 name: manage-kg-extractors
 description: Analyze codebase patterns and generate .workflow/kg/extractors.yaml for custom symbol extraction
-argument-hint: "[--scan-only] [--append] [--language <lang>]"
+argument-hint: "[--scan-only] [--append] [--language <lang>] [--min-count <n>]"
 allowed-tools:
   - Read
   - Write
@@ -24,6 +24,7 @@ $ARGUMENTS -- optional flags.
 - `--scan-only` — Only report detected patterns, don't write extractors.yaml
 - `--append` — Append new rules to existing extractors.yaml (default: overwrite)
 - `--language <lang>` — Limit analysis to specific language (python, typescript, java, etc.)
+- `--min-count <n>` — Minimum occurrences to include a pattern (default: 3). Use `--min-count 1` to include rare patterns.
 
 **Analysis targets (per language):**
 
@@ -77,6 +78,8 @@ Spawn **3 parallel agents** to scan the codebase:
 
 Each agent returns: `[{pattern_type, regex_evidence, file_count, sample_matches: [{file, line, code}]}]`
 
+**Gate:** If all 3 agents return empty results → E002 (abort). If at least 1 agent succeeds, proceed with partial results (log W001 for failed agents).
+
 ### Phase 2: Generate rules
 
 For each discovered pattern with ≥3 occurrences:
@@ -112,6 +115,7 @@ If `--scan-only`: stop after Phase 2 summary.
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
 | E001 | error | .workflow/ not initialized | Run maestro-init first |
+| E002 | error | All 3 Phase 1 agents failed — zero patterns discovered | Check codebase language detection; retry with `--language` |
 | W001 | warning | No patterns detected for language | Try broader scan or different language |
 | W002 | warning | Pattern has < 3 occurrences | Skipped by default, include with --min-count 1 |
 | W003 | warning | Existing extractors.yaml will be overwritten | Use --append to preserve |

package/.claude/commands/manage-knowhow-capture.md

@@ -9,6 +9,7 @@ allowed-tools:
   - Bash
   - Glob
   - Grep
+  - WebFetch
   - AskUserQuestion
 ---
 <purpose>

package/.claude/commands/manage-knowledge-audit.md

@@ -32,6 +32,8 @@ Arguments: $ARGUMENTS
 
 **删除策略**默认 `--interactive`（三态面板逐项决策）；非交互模式 `--mark`（仅打标）/ `--delete`（软删到 `.trash/`）/ `--purge`（物理擦除，仅 artifact 且需双重确认）。
 
+**互斥规则：** `--interactive`、`--mark`、`--delete`、`--purge` 四选一，同时传入多个 → E006。
+
 Flag 全集、scope 对应的扫描路径、Stage 步骤、检测算法定义在 workflow knowledge-audit.md。
 </context>
 
@@ -111,6 +113,7 @@ Follow `~/.maestro/workflows/knowledge-audit.md` Stages 1-8 in order.
 | E003 | error | `--purge` 与 `--dry-run` 同用 | 二选一 |
 | E004 | error | `--purge` 作用于非 artifact 范围 | purge 仅支持 artifact scope |
 | E005 | error | 备份失败（`.trash/` 写入异常） | 检查磁盘空间与权限，重试 |
+| E006 | error | `--interactive`/`--mark`/`--delete`/`--purge` 同时传入多个 | 四选一，默认 `--interactive` |
 | W001 | warning | 检出冲突但用户选择 keep | 记入 report，不阻断 |
 | W002 | warning | 待删 artifact 无 harvest-log 记录 | 提示先跑 manage-harvest |
 | W003 | warning | 循环 supersedes 链 | 自动断环或交互选保留节点 |

package/.claude/commands/manage-wiki.md

@@ -36,6 +36,7 @@ $ARGUMENTS — subcommand and optional flags.
 **Flags:**
 - `--type <type>` — Filter by wiki type: spec, knowhow, note, issue
 - `--fix` — Auto-fix issues found during cleanup/connect (remove broken links, apply connections)
+- `--dry-run` — Preview mode, no writes. **Overrides `--fix`**: when both are passed, `--dry-run` takes precedence (preview only, no fixes applied).
 - `--json` — Output in JSON format
 - `--min-similarity N` — (connect) Minimum similarity threshold for link candidates
 - `--max N` — (connect) Maximum number of suggestions