maestro-flow 0.5.41 → 0.5.43

package/.agents/skills/domain-add/SKILL.md

@@ -8,6 +8,7 @@ allowed-tools:
   - shell
   - find_files
   - search
+  - ask_user
 ---
 <!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
 
@@ -40,6 +41,8 @@ Domain term lifecycle: discover/manual → register → active → (optional) de
 
 <execution>
 Follow '~/.maestro/workflows/domain-add.md' completely.
+
+**Confirmation gate**: Before writing to glossary.yaml, ask_user showing the term canonical name, definition, extracted aliases/keywords, tier, and target file path. Proceed only on user confirm.
 </execution>
 
 <error_codes>

package/.agents/skills/learn-decompose/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: learn-decompose
 description: Extract design patterns from code into specs and wiki
-argument-hint: "<path|module> [--patterns <list>] [--save-spec] [--save-wiki]"
+argument-hint: "<path|module> [--patterns <list>] [--save-spec] [--save-wiki] [-y]"
 allowed-tools:
   - read_file
   - write_file
@@ -26,6 +26,7 @@ $ARGUMENTS — target path/module and optional flags.
 - `--patterns <list>`: Comma-separated pattern names to look for (default: detect all)
 - `--save-spec`: `invoke_skill("spec-add")` for each new pattern
 - `--save-wiki`: create wiki note per dimension group
+- `-y`: Skip confirmation prompts for knowhow/spec writes
 
 **Storage read**: target files + `coding-conventions.md` + `.workflow/specs/learnings.md` (dedup)
 **Storage write**: `.workflow/knowhow/KNW-decompose-{slug}-{date}.md` + append `.workflow/specs/learnings.md`
@@ -61,7 +62,8 @@ S_CATALOG:
   → S_PERSIST     DO: write KNW-decompose report (grouped by dimension: pattern table + details)
 
 S_PERSIST:
-  → END           DO: append .workflow/specs/learnings.md [+ spec-add if --save-spec] [+ wiki note if --save-wiki]
+  → END           GATE: unless -y, ask_user showing files to write and patterns to persist — proceed only on confirm
+                  DO: append .workflow/specs/learnings.md [+ spec-add if --save-spec] [+ wiki note if --save-wiki]
 
 </transitions>
 
@@ -88,8 +90,8 @@ For each finding, match against known pattern set:
 | Status | Condition |
 |--------|-----------|
 | documented | Already in coding-conventions.md |
-| known | In .workflow/specs/learnings.md |
-| new | Not seen before |
+| known | In .workflow/specs/learnings.md (if file exists) |
+| new | Not seen before (or learnings.md absent — treat all as new) |
 
 Flag contradictions (finding conflicts with documented convention). Merge duplicates across agents (same pattern found by multiple dimensions).
 
@@ -102,6 +104,7 @@ Flag contradictions (finding conflicts with documented convention). Merge duplic
 |------|-----------|----------|
 | E002 | No source files in target | Check target has .ts/.js files |
 | W001 | One+ dimension agent failed | Proceed with available dimensions |
+| W002 | .workflow/specs/learnings.md missing or malformed | Treat all patterns as new; create file on persist |
 | W003 | Large target (>50 files) | Consider --patterns filter |
 </error_codes>
 

package/.agents/skills/learn-follow/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: learn-follow
 description: Guided reading of code or wiki to extract patterns
-argument-hint: "<path|wiki-id|topic> [--depth shallow|deep] [--save-wiki]"
+argument-hint: "<path|wiki-id|topic> [--depth shallow|deep] [--save-wiki] [-y]"
 allowed-tools:
   - read_file
   - write_file
@@ -31,6 +31,7 @@ $ARGUMENTS — target and optional flags.
 - `--depth shallow` (default): key patterns and structure only
 - `--depth deep`: every function, every branch, every assumption
 - `--save-wiki`: create wiki note entry with reading notes
+- `-y`: Skip confirmation prompts for knowhow/spec writes
 
 **Storage read**: target file + wiki forward/backlinks + `coding-conventions.md` + `.workflow/specs/learnings.md` (dedup)
 **Storage write**: `.workflow/knowhow/KNW-follow-{slug}-{date}.md` + append `.workflow/specs/learnings.md`
@@ -66,7 +67,8 @@ S_EXTRACT:
   → S_PERSIST     DO: A_EXTRACT_PATTERNS
 
 S_PERSIST:
-  → END           DO: write KNW-follow + append .workflow/specs/learnings.md [+ wiki note if --save-wiki]
+  → END           GATE: unless -y, ask_user showing files to write and spec-entries to append — proceed only on confirm
+                  DO: write KNW-follow + append .workflow/specs/learnings.md [+ wiki note if --save-wiki]
 
 </transitions>
 

package/.agents/skills/learn-investigate/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: learn-investigate
 description: Investigate questions with hypothesis testing and evidence logging
-argument-hint: "<question> [--scope <path>] [--max-hypotheses N]"
+argument-hint: "<question> [--scope <path>] [--max-hypotheses N] [-y]"
 allowed-tools:
   - read_file
   - write_file
@@ -24,6 +24,7 @@ $ARGUMENTS — question text and optional flags.
 **Flags**:
 - `--scope <path>`: Restrict to files under this dir (default: entire project)
 - `--max-hypotheses N`: Max hypotheses before escalation (default: 3)
+- `-y`: Skip confirmation prompts for report/spec writes
 
 **Storage write**:
 - `.workflow/knowhow/KNW-investigate-{slug}/evidence.ndjson` — structured evidence (one JSON line per item)
@@ -59,11 +60,11 @@ S_PATTERN:
   → S_HYPOTHESIZE DO: match evidence against debug-notes.md + .workflow/specs/learnings.md patterns
 
 S_HYPOTHESIZE:
-  → S_CLI_EXPLORE WHEN: CLI tools enabled AND hypotheses non-trivial    DO: A_FORM_HYPOTHESES
-  → S_TEST        WHEN: no CLI tools OR trivial hypotheses              DO: A_FORM_HYPOTHESES
+  → S_CLI_EXPLORE WHEN: CLI tools enabled (at least one tool in cli-tools.json enabled) AND hypotheses non-trivial (require cross-file tracing or data-flow analysis)    DO: A_FORM_HYPOTHESES
+  → S_TEST        WHEN: no CLI tools OR trivial hypotheses (answerable by local Grep/Read)    DO: A_FORM_HYPOTHESES
 
 S_CLI_EXPLORE:
-  → S_TEST        DO: A_CLI_SUPPLEMENT (maestro delegate --role explore --mode analysis, run_in_background, STOP)
+  → S_TEST        DO: A_CLI_SUPPLEMENT (maestro delegate --to <first-enabled-tool> --mode analysis, run_in_background, STOP)
 
 S_TEST:
   → S_REPORT      WHEN: hypothesis confirmed                  DO: A_TEST_HYPOTHESIS
@@ -75,7 +76,8 @@ S_ESCALATE:
   → S_REPORT      WHEN: user selects "Escalate" or still stuck          DO: mark INCONCLUSIVE
 
 S_REPORT:
-  → END           DO: A_SYNTHESIZE_REPORT
+  → END           GATE: unless -y, ask_user showing report.md path and spec-entries to append — proceed only on confirm
+                  DO: A_SYNTHESIZE_REPORT
 
 </transitions>
 
@@ -110,7 +112,7 @@ Rank by plausibility (evidence strength). Write to understanding.md:
 maestro delegate "PURPOSE: Gather evidence for hypotheses
 TASK: Trace call chains and data flows per hypothesis | Find corroborating/contradicting patterns
 EXPECTED: JSON [{hypothesis_rank, evidence: [{file, line, supports: bool, explanation}]}]
-" --role explore --mode analysis
+" --to <first-enabled-tool> --mode analysis
 ```
 Run_in_background, STOP, wait. On callback: append to evidence.ndjson.
 

package/.agents/skills/learn-second-opinion/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: learn-second-opinion
 description: Get alternative perspectives — review, challenge, or consult
-argument-hint: "<target> [--mode review|challenge|consult]"
+argument-hint: "<target> [--mode review|challenge|consult] [-y]"
 allowed-tools:
   - read_file
   - write_file
@@ -29,7 +29,9 @@ $ARGUMENTS — target and optional mode flag.
 | `HEAD` / `staged` | `git diff HEAD` / `git diff --staged` |
 | Phase number | Resolve via state.json.artifacts[] → plan.json |
 
-**Flags**: `--mode review|challenge|consult` (default: review)
+**Flags**:
+- `--mode review|challenge|consult` (default: review)
+- `-y`: Skip confirmation prompts for knowhow/spec writes
 
 **Pre-load** (optional): `invoke_skill("spec-load")` for conventions + `maestro search "<target topic>"` for related entries.
 
@@ -64,7 +66,8 @@ S_SYNTHESIZE:
   → S_PERSIST     DO: merge perspectives → agreements, disagreements, verdict, top 3 recommendations
 
 S_PERSIST:
-  → END           DO: write KNW-opinion + append <spec-entry> blocks to .workflow/specs/learnings.md
+  → END           GATE: unless -y, ask_user showing files to write and spec-entries to append — proceed only on confirm
+                  DO: write KNW-opinion + append <spec-entry> blocks to .workflow/specs/learnings.md
 
 </transitions>
 

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

@@ -32,7 +32,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/.agents/skills/maestro-amend/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-amend
 description: Generate overlays to fix workflow command deficiencies
-argument-hint: "[description] [--from-verify <dir>] [--from-review <dir>] [--from-session <id>] [--from-issues ISS-xxx,...] [--scan] [--dry-run]"
+argument-hint: "[description] [--from-verify <dir>] [--from-review <dir>] [--from-session <id>] [--from-issues ISS-xxx,...] [--scan] [--dry-run] [-y]"
 allowed-tools:
   - read_file
   - write_file

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

@@ -47,7 +47,7 @@ $ARGUMENTS -- phase number for micro mode, topic text for macro/adhoc mode, no a
 |------|--------|---------|
 | `-y` / `--yes` | Auto mode — skip interactive scoping, use recommended defaults, auto-deepen | false |
 | `-c` / `--continue` | Resume from existing session (auto-detect session folder + discussion.md) | false |
-| `-q` / `--quick` | Quick mode — skip exploration + scoring, go straight to decision extraction (context.md only) | false |
+| `-q` / `--quick` | Quick mode — skip exploration + scoring, go straight to decision extraction (context.md only). **Precedence**: when combined with `-c`, the resumed session preserves its original mode (full or quick); `-q` does NOT override a resumed full session to quick mode. | false |
 | `--from <source>` | Load upstream context package (grill:ID, brainstorm:ID, blueprint:BLP-xxx, @file, or path) | — |
 | `--gaps [ISS-ID]` | Issue root cause analysis mode. If ISS-ID provided, analyze single issue. If omitted, analyze all open/registered issues from issues.jsonl | — |
 
@@ -88,51 +88,9 @@ Follows @~/.maestro/workflows/interview-mechanics.md standard.
 <execution>
 Follow '~/.maestro/workflows/analyze.md' completely.
 
-### Evidence-Backed Decisions
-
-Every decision MUST trace to independently gathered evidence. Manual Read/Grep is preparation — NOT evidence. Valid evidence sources:
-- cli-explore-agent output (code anchors, call chains, data flows)
-- maestro delegate CLI analysis output (multi-perspective findings)
-- User-provided input (domain knowledge, constraints, corrections)
-
-Decisions without CLI/agent-sourced evidence MUST be flagged as LOW CONFIDENCE.
-
-### Boundary Grill (Step 5 → Step 6)
-
-After discussion rounds, BEFORE synthesis: run boundary grill per `~/.maestro/workflows/boundary-grill.md`.
-Input: discussion.md decisions + exploration-codebase.json. Scope guard: "only analyze decisions; do not prejudge plan/execute concerns".
-IF conflicts → results to `analysis.md` § Boundary Grill Results + update `context.md` Locked/Free/Deferred.
-
-### Standard Mode Gates
-
-Gates 1-4 are defined in `analyze.md`. NEVER skip gates. NEVER substitute manual Read/Grep for agent/CLI exploration.
-
-### Artifact Verification
-
-Before writing the completion report (Step 9), verify ALL expected artifacts exist in OUTPUT_DIR:
-```
-FULL_MODE_REQUIRED = [
-  "discussion.md",             // Step 3+5
-  "exploration-codebase.json", // Step 4.1
-  "explorations.json" OR "perspectives.json", // Step 4.3
-  "analysis.md",               // Step 6
-  "conclusions.json",          // Step 7
-  "context.md",                // Step 8
-  "context-package.json"       // Step 8.6
-]
-```
-If any artifact is missing: DO NOT report completion. Produce the missing artifact first.
-
 ### --gaps Mode
 
 When `--gaps` is present, follow `~/.maestro/workflows/issue-gaps-analyze.md` instead of the standard pipeline.
-
-**Handoff:** context.md is consumed by maestro-plan. In --gaps mode, context.md contains issue root causes for `plan --gaps`.
-
-**scope_verdict** (added to context.md in Step 6 Synthesis for macro/adhoc/standalone scopes):
-- `large` (3+ independent subsystems or hard serial dependencies) → suggest `/maestro-roadmap --from analyze:ANL-xxx`
-- `medium` (1-2 subsystems, parallelizable) → suggest `/maestro-plan --from analyze:ANL-xxx`
-- `small` (single-file or few-file change) → suggest `/maestro-plan --from analyze:ANL-xxx`
 </execution>
 
 <completion>

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

@@ -90,28 +90,6 @@ Each phase produces artifacts that are prerequisites for the next. Do NOT advanc
 **GATE P5 → P6**: `epics/` directory with `_index.md` + individual `EPIC-*.md` files. Cross-Epic dependency map present.
 **GATE P6**: Readiness score computed. Pass (≥80%) or Review (≥60%) required for handoff.
 
-### Artifact Verification (before completion)
-
-```
-REQUIRED_ARTIFACTS = [
-  "blueprint-config.json",        // P0
-  "product-brief.md",             // P2
-  "glossary.json",                // P2 (≥5 terms)
-  "requirements/_index.md",       // P3
-  "architecture/_index.md",       // P4
-  "epics/_index.md",              // P5
-  "readiness-report.md",          // P6
-  "blueprint-summary.md",         // P6
-  "context-package.json"          // P6
-]
-```
-If any artifact is missing: DO NOT report completion. Go back and produce it.
-
-### Evidence Requirement
-
-Architecture Decision Records (ADR-*.md) MUST cite evidence for each decision:
-- Valid: code analysis, requirement traceability (REQ-xxx), upstream context, CLI analysis output
-- INVALID: generic rationale without reference to project-specific constraints
 </execution>
 
 <completion>
@@ -183,7 +161,7 @@ Status verdicts:
 - [ ] Readiness gate: Pass (>=80%) or Review (>=60%) with documented caveats
 - [ ] Artifact registered in state.json (type=blueprint)
 - [ ] context-package.json generated for downstream consumption
-- [ ] On gate Pass/Review: session sealed via finish-work (archive.json + optional spec/knowhow extraction). On Fail: skip — session stays active, excluded from wiki search.
+- [ ] On gate Pass/Review: session sealed via finish-work (finish-work.md includes ask_user confirmation before state.json artifact registration and optional spec/knowhow extraction). On Fail: skip — session stays active, excluded from wiki search.
 </success_criteria>
 
 <on_complete>

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

@@ -1,10 +1,11 @@
 ---
 name: maestro-brainstorm
 description: Use when exploring ideas, evaluating approaches, or needing multi-perspective analysis before implementation
-argument-hint: "[topic|role-name] [--yes] [--count N] [--session ID] [--update] [--skip-questions] [--include-questions] [--style-skill PKG]"
+argument-hint: "[topic|role-name] [--yes] [--count N] [--session ID] [--update] [--skip-questions] [--include-questions] [--style-skill PKG] [--review-only] [--from <source>]"
 allowed-tools:
   - read_file
   - write_file
+  - edit_file
   - shell
   - find_files
   - search
@@ -53,6 +54,8 @@ $ARGUMENTS -- topic text for auto mode, or role name for single role mode.
 | `--skip-questions` | Skip context gathering questions | false |
 | `--include-questions` | Force context gathering even if analysis exists | false |
 | `--style-skill PKG` | Style package for ui-designer role | — |
+| `--review-only` | Run cross-role review on existing analyses without re-running role analysis | false |
+| `--from <source>` | Load upstream context package (grill:ID, blueprint:ID, @file, or path) | — |
 
 ### Pre-load specs
 1. **Architecture specs**: Run `maestro load --type spec --category arch` to load architecture constraints. Use as context for multi-role analysis — ensures roles respect documented decisions.
@@ -92,35 +95,15 @@ These gates apply to Auto mode (full pipeline). Do NOT advance past a gate until
 - BLOCKED if missing: complete all role analyses before spawning cross-role-reviewer.
 
 **GATE 2.5: Cross-Role Review → Boundary Grill** (Step 4.5 → Step 4.6)
-Run boundary grill per `~/.maestro/workflows/boundary-grill.md` after cross-role-reviewer output.
-Input: reviewer findings + role Decision Digests. Scope guard: "only brainstorm decisions; do not pre-resolve roadmap/plan choices".
-IF conflicts → results to `guidance-specification.md` §12.5 + feed into GATE 3. NON-BLOCKING.
+- REQUIRED: Boundary grill executed per workflow boundary-grill.md after cross-role review.
+- NON-BLOCKING: conflicts logged as warnings.
 
 **GATE 3: Cross-Role Review → Completion** (Step 4.5/4.6 → Report)
 - REQUIRED: Cross-role-reviewer output received with `patch_targets[]`.
-- REQUIRED: Boundary grill completed (if conflicts detected, results logged).
-- REQUIRED: If findings > 0, resolutions applied via Edit AND logged in `guidance-specification.md` §12.
-- REQUIRED: If findings == 0, final report explicitly states "No cross-role issues detected".
+- REQUIRED: Boundary grill completed.
+- REQUIRED: Resolutions applied and logged (details in workflow).
 - BLOCKED if missing: complete review synthesis before reporting.
 
-### Artifact Verification (before completion report)
-
-```
-AUTO_MODE_REQUIRED = [
-  "guidance-specification.md",            // Step 1
-  "{role}/analysis.md" (per selected role), // Step 3
-  "{role}/analysis-F-*.md" (per feature),   // Step 3
-]
-```
-If any artifact is missing: DO NOT report completion. Go back and produce the missing artifact.
-
-### Evidence Requirement
-
-Role analysis findings in `{role}/analysis.md` §2 Decision Digest MUST cite concrete evidence:
-- Code references (file:line), API endpoints, data models from the codebase
-- User-provided constraints from interview
-- Cross-role references to other role analyses
-Decisions without evidence are flagged LOW CONFIDENCE.
 </execution>
 
 <completion>

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

@@ -45,6 +45,7 @@ S_CONFIRM         — 展示计划、用户确认（-y 跳过）              PE
 S_FANOUT          — 构建 prompt、并行启动 delegate、STOP       PERSIST: —
 S_COLLECT         — 回调到达、收集结果                          PERSIST: per-tool outputs
 S_CROSS_VERIFY    — 分类发现（共识/冲突/独有）                  PERSIST: —
+S_BOUNDARY_GRILL  — 边界冲突检测与解决                          PERSIST: —
 S_SYNTHESIZE      — 解决冲突、生成 3 个输出文件                 PERSIST: outputs
 S_REGISTER        — 注册 CLB artifact                          PERSIST: state.json
 S_REPORT          — 显示摘要 + next-step routing               PERSIST: —
@@ -86,7 +87,9 @@ S_SYNTHESIZE:
   → S_REGISTER      DO: A_GENERATE_OUTPUTS
 
 S_REGISTER:
-  → S_REPORT        DO: append CLB artifact to state.json (type: collab, scope: adhoc)
+  → S_REPORT        WHEN: user confirms or -y    DO: append CLB artifact to state.json (type: collab, scope: adhoc)
+  → S_REPORT        WHEN: user declines           DO: skip artifact registration, proceed to report
+  GUARD: ask_user "Register collab artifact to state.json?" (skipped if -y)
 
 S_REPORT:
   → END             DO: display summary (requirement, tools, consensus_level, per-tool status, artifact id, output dir)
@@ -98,8 +101,9 @@ S_REPORT:
 ### A_DISCOVER_TOOLS
 
 ```
-shell("maestro tools list --json 2>/dev/null || cat ~/.maestro/cli-tools.json")
+shell("maestro tools list --json 2>$null || cat ~/.maestro/cli-tools.json")
 ```
+**Note:** Shell commands MUST use the Bash tool (not PowerShell). Use POSIX syntax within Bash calls.
 Filter: enabled == true. If --mode write: exclude type == "api-endpoint".
 Auto-select (no --tools): first 3 eligible in config order.
 

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

@@ -415,7 +415,10 @@ Collect task outcome data:
 
 ```bash
 # Detect files changed since companion doc creation
-git diff --name-only --since="{companion_created_timestamp}"
+# Use git log --since for time-based filtering, then git diff for the range
+git log --since="{companion_created_timestamp}" --format="%H" -1  # get oldest commit in range
+git diff --name-only {oldest_commit}..HEAD                         # diff from that commit to HEAD
+# Fallback if no commits since timestamp: git diff --name-only HEAD
 ```
 
 Update frontmatter:

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

@@ -126,7 +126,7 @@ Read deferred `node-catalog.md` (fallback to built-in mapping):
 | testing | `quality-test` |
 | review | `quality-review` |
 | brainstorm | `maestro-brainstorm` |
-| analysis | `maestro delegate --role analyze` |
+| analysis | `maestro delegate --to <tool> --mode analysis` |
 | verify | `maestro-execute` |
 | refactor | `quality-refactor` |
 | debug | `quality-debug` |
@@ -156,7 +156,9 @@ Write `nodes.json`. Display resolved node list.
 
 Read deferred `template-schema.md` (fallback to built-in structure).
 Assemble template JSON: template_id, name, nodes, edges, checkpoints, context_schema, execution_mode.
-Write to `~/.maestro/templates/workflows/<slug>.json`. Update index.json.
+**Confirmation gate**: ask_user showing template summary (ID, node count, variables) before writing.
+- User confirms → write to `~/.maestro/templates/workflows/<slug>.json` and update index.json.
+- User cancels → save draft, do not write template or index.
 Display: path, ID, node count, variables, execute/edit commands. Clean up draft dir.
 
 </actions>

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

@@ -39,7 +39,7 @@ $ARGUMENTS — phase number, or no args for milestone-wide execution, with optio
 | `--method agent\|cli\|auto` | Execution method: Agent tool, CLI delegate, or auto-select | `auto` |
 | `--executor <tool>` | Explicit executor tool for CLI delegate mode | First enabled in config |
 | `--dir <path>` | Execute a specific plan directory instead of auto-discovery | — |
-| `-y` / `--yes` | Auto mode — skip interactive questions | false |
+| `-y` / `--yes` | Auto mode — skip ALL interactive questions (executor selection, wave progression, blocked prompts) | false |
 
 ### Scope routing
 
@@ -88,8 +88,14 @@ Follow '~/.maestro/workflows/execute.md' completely.
 - BLOCKED if missing: summary file absent or task status not updated — halt wave progression until evidence is recorded.
 - Do NOT silently skip failed tasks — mark as blocked with reason.
 
+**GATE 2.5: Wave Failure Handling**
+- IF all tasks in a wave failed: halt wave progression, report E005 with per-task failure reasons. Do NOT proceed to next wave — downstream waves depend on current wave outputs.
+- IF cascading failure (wave N fails → wave N+1 has unmet dependencies): mark all dependent tasks in subsequent waves as `blocked` with reason `"upstream_wave_failed"`. Skip blocked waves and proceed to completion with partial results.
+- `-y` mode: auto-skip blocked waves without prompting, log warning W002.
+- Non `-y` mode: `ask_user` with options [retry wave / skip and continue / abort execution].
+
 **GATE 3: All Tasks → Completion**
-- REQUIRED: All waves executed in dependency order.
+- REQUIRED: All waves executed in dependency order (or explicitly skipped via Gate 2.5).
 - REQUIRED: EXC artifact registered in state.json.
 - BLOCKED if missing: waves incomplete or EXC artifact not registered — do not report execution complete.
 
@@ -102,27 +108,37 @@ Task summaries MUST include:
 
 ### Post-task Knowledge Inquiry
 
-After each task completion, check triggers:
+After each task completion, extract structured fields from the task summary, then check triggers:
+
+**Structured extraction** (from `.summaries/TASK-{NNN}-summary.md`):
+- `deviations[]` — explicit plan deviations (look for "deviated", "changed approach", "instead of", "unlike plan")
+- `design_rationale[]` — explicit design decisions (look for "chose X because", "decided to", "trade-off")
+- `retry_count` — from `.task/TASK-{NNN}.json` status history
 
 | Condition | Ask | Route |
 |-----------|-----|-------|
-| Summary mentions approach change / plan deviation | "Record as arch constraint?" | spec-add arch |
-| retry_count >= 2 | "Document fix pattern?" | spec-add debug |
-| Summary contains design rationale ("chose X because") | "Record as knowhow?" | spec-add learning |
+| `deviations[]` is non-empty | "Record as arch constraint?" | spec-add arch |
+| `retry_count >= 2` | "Document fix pattern?" | spec-add debug |
+| `design_rationale[]` is non-empty | "Record as knowhow?" | spec-add learning |
 
 On confirm → `invoke_skill("spec-add", "<category> <content> --description \"<summary>\"")`.
 Include `--description` with a one-line summary for search result display.
 
 ### Issue Status Sync
 
-On each task completion, if `task.issue_id` exists, sync status back to the issue in `.workflow/issues/issues.jsonl`:
+On each task completion, if `task.issue_id` exists, sync status back to the issue in `.workflow/issues/issues.jsonl`.
+
+**Confirmation gate**: Before writing to issues.jsonl, show the proposed status change and ask for confirmation — unless `-y` is active, in which case auto-approve.
 
 ```
 For each completed/failed TASK with issue_id:
   Read issue from issues.jsonl by issue_id
   Collect all task_refs[] statuses for that issue:
-    all task_refs completed → issue.status = "resolved"
-    any task_ref failed    → issue.status = "in_progress"
+    all task_refs completed → proposed issue.status = "resolved"
+    any task_ref failed    → proposed issue.status = "in_progress"
+  IF NOT auto_mode (-y):
+    ask_user: "Update issue {issue_id} status to {proposed_status}?" [Yes / Skip]
+    IF Skip → continue to next task without writing
   Append history entry: { action: "executed", at: <ISO>, by: "maestro-execute", summary: "TASK-{NNN} {status}" }
   Write updated issue back to issues.jsonl
 ```
@@ -171,7 +187,9 @@ Status verdicts:
 | E002 | error | Plan directory not found | Check --dir path |
 | E003 | error | plan.json not found in directory | Verify plan.json exists, run maestro-plan first |
 | E004 | error | No pending tasks, all tasks already completed | Check task statuses, reset if needed |
+| E005 | error | All tasks in wave failed — wave progression halted | Review per-task failure reasons; retry wave or abort |
 | W001 | warning | Executor completed with partial failures | Check task dependencies, retry failed wave |
+| W002 | warning | Cascading wave failure — downstream waves auto-blocked | Review blocked tasks; re-run after fixing upstream failures |
 </error_codes>
 
 <success_criteria>

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

@@ -55,9 +55,10 @@ Fork and sync algorithm steps are defined in workflow `fork.md`.
 - BLOCKED if missing: worktree creation failed or shared files not copied — do not proceed to artifact scoping.
 
 **GATE 3: Artifact Copy → Completion**
-- REQUIRED: `worktree-scope.json` written with milestone scope.
-- REQUIRED: Scoped `state.json` written (only this milestone's artifacts).
-- REQUIRED: `worktrees.json` registry updated in main worktree.
+- REQUIRED: ask_user confirmation before registry writes — show milestone scope, worktree path, and state entries to be written. User must confirm or abort.
+- REQUIRED: `worktree-scope.json` written with milestone scope (after confirmation).
+- REQUIRED: Scoped `state.json` written (only this milestone's artifacts) (after confirmation).
+- REQUIRED: `worktrees.json` registry updated in main worktree (after confirmation).
 - BLOCKED if missing: scope marker, scoped state, or registry update absent — worktree is unusable without these.
 
 **Sync mode:**

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

@@ -93,22 +93,6 @@ Follow '~/.maestro/workflows/grill.md' completely.
 - REQUIRED: `context-package.json` generated.
 - BLOCKED if any artifact missing: produce it before reporting completion.
 
-### Evidence Requirement
-
-Grill questions MUST reference specific code (`file:line`) when challenging the user's proposal. Generic questions without code grounding are INVALID.
-
-If codebase scan failed (W001): flag ALL subsequent locked decisions as LOW CONFIDENCE.
-
-### Artifact Verification (before completion)
-
-```
-REQUIRED_ARTIFACTS = [
-  "grill-report.md",        // Branch Log + Q&A + synthesis
-  "terminology.md",         // ≥5 terms with code refs
-  "context-package.json"    // Schema "context-package/1.0"
-]
-```
-If any missing: DO NOT report completion. Go back and produce the missing artifact.
 </execution>
 
 <completion>
@@ -169,7 +153,7 @@ Status verdicts:
 - [ ] Risk register captures all unresolved tensions
 - [ ] `context-package.json` generated with schema "context-package/1.0"
 - [ ] Artifact registered in state.json (type=grill, id=GRL-xxx)
-- [ ] Session sealed via finish-work
+- [ ] Session sealed via finish-work (finish-work.md includes ask_user confirmation before state.json artifact registration and optional spec/knowhow extraction)
 </success_criteria>
 
 <on_complete>

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

@@ -66,14 +66,14 @@ Read `.workflow/config.json`. If file missing, initialize with empty guard secti
 
 **`allow <path>`:**
 - Normalize path to forward slashes, ensure trailing slash for directories
-- If `guard.mode` is `deny`, switch to `allow` and clear paths with warning
+- If `guard.mode` is `deny`, ask_user: "Switching from deny to allow mode will clear existing paths ({N} paths). Continue?" — abort if user declines.
 - Add path to `guard.paths` (deduplicate)
 - Set `guard.enabled = true` if not already
 - Write config
 
 **`deny <path>`:**
 - Normalize path to forward slashes, ensure trailing slash for directories
-- If `guard.mode` is `allow`, switch to `deny` and clear paths with warning
+- If `guard.mode` is `allow`, ask_user: "Switching from allow to deny mode will clear existing paths ({N} paths). Continue?" — abort if user declines.
 - Set `guard.mode = "deny"`
 - Add path to `guard.paths` (deduplicate)
 - Set `guard.enabled = true` if not already (symmetric with `allow`: adding a deny path auto-enables the guard)

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

@@ -204,7 +204,8 @@ Before reading any command workflow:
    - `↺` marks refine loop with max iteration count
    - Conditional steps show trigger condition
    - Skipped conditional steps marked `(skipped)`
-3. Create session: `.workflow/.maestro/ui-craft-{YYYYMMDD-HHmmss}/status.json`
+3. **Confirm chain session**: ask_user "Create chain session for '{chain_type}' targeting '{target}'?" — proceed only if user confirms. On decline, abort chain.
+   Create session: `.workflow/.maestro/ui-craft-{YYYYMMDD-HHmmss}/status.json`
    ```json
    { "chain_type": "...", "target": "...", "steps": [...], "current_step": 0,
      "gate_history": [], "loop_count": 0, "status": "running" }

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-init
 description: Initialize project with auto state detection
-argument-hint: "[-y] [--from <source>]"
+argument-hint: "[-y] [--from <source>] [--from-brainstorm SESSION-ID]"
 allowed-tools:
   - read_file
   - write_file

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

@@ -54,7 +54,18 @@ Follow '~/.maestro/workflows/merge.md' completely.
 <completion>
 ### Knowledge inquiry
 
-After successful merge, ask user once: "Record milestone learnings?" If yes, persist via `invoke_skill("spec-add", "learning \"<title>\" \"<insight>\" --keywords <kw1>,<kw2> --description \"<summary>\"")`.
+After successful merge, use `ask_user` to confirm knowledge persistence:
+
+```
+question: "Merge 完成。是否记录里程碑经验教训？"
+options:
+  - label: "记录经验"
+    description: "通过 spec-add 持久化此次里程碑的关键洞察"
+  - label: "跳过"
+    description: "不记录，直接完成"
+```
+
+User selects "记录经验" → prompt for title/insight, then persist via `invoke_skill("spec-add", "learning \"<title>\" \"<insight>\" --keywords <kw1>,<kw2> --description \"<summary>\"")`. User selects "跳过" → proceed to next-step routing.
 
 ### Next-step routing
 

package/.agents/skills/maestro-milestone-audit/SKILL.md

@@ -25,6 +25,7 @@ Produces audit-report.md with PASS/FAIL verdict.
 
 <context>
 Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json).
+If $ARGUMENTS is empty AND current_milestone is null → raise E001 with message "No milestone specified and no current_milestone set in state.json. Provide a milestone identifier as argument."
 
 **Requires:** All phases in the milestone should have completed execute artifacts.
 
@@ -71,21 +72,6 @@ Audit checklist steps (phase coverage, ad-hoc completeness, execution completene
 - REQUIRED: Clear PASS/FAIL verdict determined with evidence for each check.
 - BLOCKED if missing: integration check not completed — do not write report without cross-artifact verification.
 
-### Artifact Verification (before completion)
-
-```
-REQUIRED_ARTIFACTS = [
-  ".workflow/milestones/{milestone}/audit-report.md"  // Clear PASS/FAIL verdict
-]
-```
-If missing: DO NOT report completion. Write the audit report first.
-
-### Evidence Requirement
-
-Every audit check result MUST cite what was examined and what was found:
-- PASS: "Phase 1 chain complete: ANL-001 → PLN-001 → EXC-001, all tasks completed"
-- FAIL: "Phase 2 missing EXC artifact — PLN-002 exists but no execution found"
-- Do NOT mark checks as PASS without verifying the actual artifact exists and contains expected content.
 </execution>
 
 <completion>