maestro-flow 0.5.39 → 0.5.40

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

@@ -40,7 +40,10 @@ $ARGUMENTS -- phase number, topic text, and optional flags.
 </context>
 
 <interview_protocol>
-Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `--continue`, or input is already specific (explicit phase number or unambiguous topic).
+Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip ONLY when `-y/--yes` or `--continue` is set.
+
+**Numeric phase argument**: interview still runs but scope is pre-resolved to "phase" — skip the scope decision, start from depth.
+**Text topic**: always interview from scope onward — text topics are never auto-classified as "unambiguous".
 
 - One decision per turn via request_user_input with 2–4 options + a (Recommended) default. The user controls termination — keep interviewing until convergence; they can interrupt naturally at any time.
 - Search-first when uncertain: before asking, resolve via `state.json`, `roadmap.md`, `issues.jsonl`, `maestro load --type spec`, `maestro search`, Grep, Read, or — for open-ended multi-file scans — `maestro delegate ... --role explore`. Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
@@ -94,7 +97,7 @@ Available exploration dimensions: architecture, implementation, performance, sec
 9. **D-007 milestone resolution**: numeric scope MUST reverse-lookup `state.json.milestones[].phase_slugs`. NEVER read `current_milestone` directly for phase-scoped artifact registration.
 10. **scope_verdict mandatory** (D-003): macro/adhoc/standalone scopes MUST produce `scope_verdict ∈ {small, medium, large}` in conclusions.json. Drives downstream chain (roadmap vs plan).
 11. **Invariant violation = BLOCK** — violating any invariant above blocks the current operation. Do NOT bypass for "efficiency" or "clear intent" reasons.
-12. **Evidence required on decisions** — every decision in context.md MUST cite evidence from Wave 1 exploration findings or Wave 2 scores. Decisions citing only orchestrator's manual file reading are flagged LOW CONFIDENCE.
+12. **Evidence required on decisions** — every decision in context.md MUST cite evidence from Wave 1 exploration findings or Wave 2 scores. Decisions citing only orchestrator's manual file reading are flagged LOW CONFIDENCE. **Degradation exception**: when invariant 7 activates and evidence is incomplete, decisions MAY proceed but MUST inherit LOW CONFIDENCE flag per invariant 13 — this is not a violation of the MUST, it is the defined degraded behavior.
 13. **Degradation must be marked** — when graceful degradation (invariant 7) activates, ALL downstream outputs inherit a LOW CONFIDENCE flag. Record in discoveries.ndjson: `{ type: "degradation_event", data: { wave, failed_tasks, impact } }`.
 </invariants>
 
@@ -149,13 +152,18 @@ S_WAVE_1:
   -> ERROR        WHEN: all failed
 
 S_WAVE_2:
-  -> S_BOUNDARY_GRILL   DO: A_SPAWN_WAVE_2
+  -> S_BOUNDARY_GRILL   WHEN: 1+ completed                 DO: A_SPAWN_WAVE_2
+  -> S_WAVE_3_DEGRADED   WHEN: all failed, retry exhausted  DO: flag LOW CONFIDENCE on all downstream, record degradation_event
+  -> S_WAVE_2 (retry)    WHEN: all failed, retry available   DO: retry once
 
 S_BOUNDARY_GRILL:
   -> S_WAVE_3     WHEN: no boundary conflicts detected     DO: —
   -> S_WAVE_3     WHEN: conflicts detected + resolved      DO: A_BOUNDARY_GRILL
   GUARD: max 3 conflicts × 3 questions; non-blocking (see boundary-grill.md)
 
+S_WAVE_3_DEGRADED:
+  -> S_AGGREGATE  DO: A_SPAWN_WAVE_3 with degraded=true (decision-only context.md, ALL decisions flagged LOW CONFIDENCE)
+
 S_WAVE_3:
   -> S_AGGREGATE  DO: A_SPAWN_WAVE_3
 
@@ -215,8 +223,10 @@ Share via discovery board. Merge results -> master tasks.csv (map `result_status
 
 Filter `wave==2 AND status=="pending"` -> build prev_context from wave 1 findings -> write wave-2.csv -> spawn with `SCORING_INSTRUCTION + SHARED_TERMINATION_CONTRACT`.
 
+**Failed-dependency handling**: when building prev_context, skip `context_from` IDs whose status is `failed`/`blocked`. If ALL `context_from` IDs failed, mark the scoring task as `blocked` (do not spawn). Append a `gap_note` to the scoring instruction listing which exploration dimensions are missing so the agent knows its evidence base is incomplete.
+
 **Scoring agent** (6 dimensions: feasibility, impact, risk, complexity, alignment, maintainability):
-Score 0-100 with specific evidence (code refs from exploration). Each score MUST reference exploration findings.
+Score 0-100 with specific evidence (code refs from exploration). Each score MUST reference exploration findings. When exploration gaps exist (gap_note present), score MUST include a `confidence_penalty` and flag `evidence_incomplete=true`.
 
 Merge results -> master tasks.csv (map `result_status` → master `status`).
 
@@ -252,14 +262,23 @@ Non-blocking: conflicts produce warnings, pipeline continues.
 
 1. Export results.csv
 2. **Confidence scoring** (full mode): factors -- findings_depth(.30), evidence_strength(.25), coverage_breadth(.20), user_validation(.15), consistency(.10). Thresholds: <60% deeper, 60-80% optional, 80-95% converging, >95% converge.
-3. Auto-create issues from Deferred items -> issues.jsonl
-4. Spec enrichment: Locked decisions -> `maestro spec add arch "<title>" "<content>" --keywords <kw> --description "<summary>"`; code patterns -> `maestro spec add coding "<title>" "<content>" --keywords <kw> --description "<summary>"`
-5. Register artifact in state.json (type: analyze, includes context_package field pointing to context-package.json)
-6. Copy outputs to scratchDir, display summary
-7. **Next-step routing** (D-003 §5.3 — macro scope uses `scope_verdict` for downstream chain selection):
-
-   | Scope | Condition | Next |
-   |-------|-----------|------|
+3. Register artifact in state.json (type: analyze, includes context_package field pointing to context-package.json)
+4. Copy outputs to scratchDir, display summary
+
+5. **Side-effect confirmation gate** (skip when `-y/--yes`):
+   Before writing to external stores, present a summary to the user via `request_user_input` listing:
+   - Deferred items to create as issues (count + titles)
+   - Locked decisions to register as specs (count + titles)
+   The user can approve all, selectively exclude, or skip entirely.
+
+   5a. **Issue creation** (approved items only): Deferred items -> issues.jsonl
+   5b. **Spec enrichment** (approved items only): Locked decisions -> `maestro spec add arch "<title>" "<content>" --keywords <kw> --description "<summary>"`; code patterns -> `maestro spec add coding "<title>" "<content>" --keywords <kw> --description "<summary>"`
+
+6. **Next-step suggestion** (D-003 §5.3 — suggest only, NEVER auto-execute):
+   Display the recommended next command based on scope_verdict. The user decides whether to proceed.
+
+   | Scope | Condition | Suggested |
+   |-------|-----------|-----------|
    | Phase/Milestone | Go + UI work needed | `$maestro-impeccable build {target}` |
    | Phase/Milestone | Go + ready to plan | `$maestro-plan` or `$maestro-plan {phase}` |
    | Phase/Milestone | No-Go | `$maestro-brainstorm {topic}` |
@@ -324,12 +343,12 @@ Protocol: read before analysis, append-only, dedup by type+key.
 - [ ] Boundary grill executed between Wave 2 and Wave 3 (skip if no conflicts detected)
 - [ ] Boundary grill results written to analysis.md § Boundary Grill Results (if conflicts found)
 - [ ] Pressure pass completed ≥ 1 time on highest-risk dimension before synthesis
-- [ ] Deferred items auto-created as issues
+- [ ] Deferred items created as issues (after user confirmation in interactive mode; auto in -y mode)
 - [ ] Scope creep redirected to Deferred section
 - [ ] Artifact registered in state.json (includes context_package field)
 - [ ] Upstream context loaded via `--from` when specified
 - [ ] discoveries.ndjson append-only throughout
-- [ ] Next step routed (plan for Go, brainstorm for No-Go, plan --gaps for Gaps)
+- [ ] Next step suggested to user (plan for Go, brainstorm for No-Go, plan --gaps for Gaps) — never auto-executed
 - [ ] Session sealed via finish-work (archive.json written, optional spec/knowhow extraction)
 - [ ] Ralph-invoked: `maestro ralph complete <idx> --status {STATUS}` called with correct verdict
 </success_criteria>
@@ -345,4 +364,3 @@ Status verdicts: **DONE** (normal), **DONE_WITH_CONCERNS** (caveats; pass `--con
 <on_complete>
 @~/.maestro/workflows/finish-work.md — SESSION_DIR=OUTPUT_DIR, SESSION_TYPE=analyze, SESSION_ID={artifact_id}, LINKED_MILESTONE={target_milestone or null}
 </on_complete>
-</output>

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

@@ -54,7 +54,7 @@ When `--from` is absent, auto-discover from state.json: latest `type=grill` arti
 </context>
 
 <interview_protocol>
-Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `--skip-questions`, `--continue` (existing session), or input is already specific.
+Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip ONLY when `-y/--yes`, `--skip-questions`, or `--continue` (existing session) is set. Text topics always require at least mode + role confirmation — never auto-classify input as "specific enough" to skip.
 
 - One decision per turn via request_user_input with 2–4 options + a (Recommended) default. The user controls termination — keep interviewing until convergence; they can interrupt naturally at any time.
 - Search-first when uncertain: before asking, resolve via `state.json`, the session directory, `maestro load --type spec`, `maestro search`, `maestro explore` (preferred, fallback Glob/Grep/Read). Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
@@ -223,12 +223,12 @@ CONSTRAINTS:
 1. **Wave order sacred**: Guidance (W1) MUST complete before role design (W2); review (W3) MUST run only after all W2 rows complete.
 2. **CSV source of truth**: Master tasks.csv holds all state.
 3. **Discovery board append-only**: Never modify/delete discoveries.ndjson.
-4. **Skip on failure**: Guidance fails → abort. All W2 roles fail → skip review.
+4. **Skip on failure**: Guidance fails → abort. All W2 roles fail → skip review, flag all downstream LOW CONFIDENCE.
 5. **9 valid roles only**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
 6. **Wave 3 is read-only at the agent boundary**: the reviewer emits structured findings (conflicts / gaps / synergies with `patch_targets[]`). The orchestrator (not the agent) applies the patches via Edit.
-7. **DO NOT STOP**: Continuous until all waves complete; only pause at [CHECKPOINT] (skipped with -y).
-8. **Invariant violation = BLOCK** — violating any invariant above blocks the current operation. Do NOT bypass for "efficiency" or "clear intent" reasons.
-9. **Evidence required** — role analysis findings in {role}/analysis.md §2 Decision Digest MUST cite concrete evidence: code references (file:line), API endpoints, data models from codebase exploration. Decisions without evidence are flagged LOW CONFIDENCE.
+7. **Pipeline continuity**: Continuous until all waves complete; only pause at [CHECKPOINT] (skipped with -y). When invariant 4 (skip on failure) activates, the pipeline continues in degraded mode — this is NOT a violation of invariant 8 but a defined degradation path.
+8. **Invariant violation = BLOCK** — violating any invariant above blocks the current operation. Do NOT bypass for "efficiency" or "clear intent" reasons. Defined degradation paths (invariant 4) are not violations.
+9. **Evidence required** — role analysis findings in {role}/analysis.md §2 Decision Digest MUST cite concrete evidence: code references (file:line), API endpoints, data models from codebase exploration. Decisions without evidence are flagged LOW CONFIDENCE. **Degradation exception**: when invariant 4 activates and evidence is unavailable due to upstream failure, decisions MAY proceed but MUST inherit LOW CONFIDENCE flag.
 10. **Artifact verification before completion** — before reporting completion, verify ALL expected artifacts exist: guidance-specification.md, {role}/analysis.md (per selected role), {role}/analysis-F-*.md (per feature). If any missing: DO NOT report completion.
 </invariants>
 
@@ -308,16 +308,19 @@ S_CHECK_1 → END        WHEN: user "Abort"
 
 S_DESIGN → S_WAVE_2    WHEN: DESIGN.md exists OR explore completed    DO: A_DESIGN_EXPLORE
 S_DESIGN → S_WAVE_2    WHEN: DESIGN.md already exists (skip explore)
-S_DESIGN → S_WAVE_2    WHEN: explore failed → W004 → retry once. If still fails: flag downstream outputs as LOW CONFIDENCE, continue without
+S_DESIGN → S_WAVE_2    WHEN: explore failed → W004 → retry once. If still fails: set session.design_degraded=true, record degradation_event in discoveries.ndjson, continue without. W2 ui-designer agent receives gap_note="DESIGN.md unavailable, design evidence incomplete" and outputs inherit LOW CONFIDENCE flag.
 
-S_WAVE_2 → S_CHECK_2   DO: spawn wave-2 (parallel), merge results — each agent writes {role}/analysis.md + sub-files
-S_WAVE_2 → S_AGGREGATE WHEN: all failed       DO: skip review
+S_WAVE_2 → S_CHECK_2   WHEN: 1+ completed     DO: spawn wave-2 (parallel), merge results — each agent writes {role}/analysis.md + sub-files
+S_WAVE_2 → S_WAVE_2    WHEN: all failed, retry available   DO: retry once
+S_WAVE_2 → S_AGGREGATE WHEN: all failed, retry exhausted   DO: skip review, flag LOW CONFIDENCE on all downstream
 
 S_CHECK_2 → S_WAVE_3   WHEN: -y OR user "Proceed"
 S_CHECK_2 → S_WAVE_2   WHEN: user "Add Roles"  DO: add new role rows, spawn only new
 
-S_WAVE_3 → S_BOUNDARY_GRILL  DO: spawn wave-3, capture review_findings (conflicts/gaps/synergies with patch_targets)
+S_WAVE_3 → S_BOUNDARY_GRILL  WHEN: completed    DO: spawn wave-3, capture review_findings (conflicts/gaps/synergies with patch_targets)
 S_WAVE_3 → S_AGGREGATE      WHEN: zero findings    DO: log "No cross-role issues detected", skip resolve
+S_WAVE_3 → S_WAVE_3         WHEN: failed, retry available   DO: retry once
+S_WAVE_3 → S_AGGREGATE      WHEN: failed, retry exhausted   DO: use analysis files directly, no resolution writeback, flag LOW CONFIDENCE
 
 S_BOUNDARY_GRILL:
   → S_RESOLVE     WHEN: no boundary conflicts detected     DO: —
@@ -415,7 +418,7 @@ If zero findings, S_RESOLVE is bypassed and `guidance §12` is unchanged.
 2. Generate context.md (summary, guidance, per-role analyses, review_findings_count, resolutions_applied, patches_skipped, next steps)
 3. Confidence scoring: 5 dimensions (role_coverage, cross_role_consistency, feature_completeness, spec_quality, design_feasibility). Quality gate: cross_role_consistency < 0.4 → warn.
 4. Copy artifacts to target session directory (preserve `{role}/` subdirs).
-5. Next-step routing: DESIGN.md established → `maestro-impeccable build <feature>`; else UI features detected → `maestro-impeccable build <feature>`; else → maestro-analyze / maestro-plan / maestro-roadmap
+5. **Next-step suggestion** (suggest only, NEVER auto-execute): Display the recommended next command. DESIGN.md established → `maestro-impeccable build <feature>`; else UI features detected → `maestro-impeccable build <feature>`; else → maestro-analyze / maestro-plan / maestro-roadmap. The user decides whether to proceed.
 
 </actions>
 </state_machine>

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

@@ -6,14 +6,14 @@ allowed-tools: Read, Write, Edit, Glob, Grep, request_user_input
 ---
 
 <purpose>
-Direct CLI fan-out collaboration via `exec_command`. Diamond topology:
-Fan-out (parallel `exec_command` → `maestro delegate --to <tool>`) → Cross-verify (coordinator) → Synthesize (coordinator).
+Direct CLI fan-out collaboration via `shell_exec`. Diamond topology:
+Fan-out (parallel `shell_exec` → `maestro delegate --to <tool>`) → Cross-verify (coordinator) → Synthesize (coordinator).
 
 Each CLI tool independently analyzes the requirement via `maestro delegate` shell call.
-Coordinator polls ALL CLI results to completion via delegate-protocol.codex.md,
+Coordinator waits for ALL CLI results to completion via shell-exec-protocol.md,
 then cross-verifies for consensus/conflicts and synthesizes into unified report.
 
-NO spawn_agents_on_csv. NO spawn_agent. ALL CLI calls directly by coordinator via exec_command.
+NO spawn_agents_on_csv. NO spawn_agent. ALL CLI calls directly by coordinator via shell_exec.
 </purpose>
 
 
@@ -62,12 +62,12 @@ $ARGUMENTS — requirement text and optional flags.
 </context>
 
 <invariants>
-1. **ALL analysis via exec_command → maestro delegate** — coordinator NEVER performs analysis internally, NEVER spawns agents for analysis
-2. **exec_command is the execution mechanism** — every delegate call: `exec_command({ cmd: "maestro delegate ..." })`
-3. **delegate-protocol.codex.md governs lifecycle** — MUST follow exec_command → poll write_stdin → parse for every delegate
-4. **NEVER fire-and-forget** — every exec_command MUST be polled to completion via write_stdin, result consumed before proceeding
+1. **ALL analysis via shell_exec → maestro delegate** — coordinator NEVER performs analysis internally, NEVER spawns agents for analysis
+2. **shell_exec is the execution mechanism** — every delegate call: `shell_exec("maestro delegate ...", { timeout: N })`
+3. **shell-exec-protocol.md governs lifecycle** — MUST follow shell_exec → wait for completion → parse for every delegate
+4. **NEVER fire-and-forget** — every shell_exec MUST complete before proceeding, result consumed before next step
 5. **NEVER substitute internal reasoning** — if CLI fails, report failure; do NOT generate analysis yourself as replacement
-6. **Indefinite wait** — polling has NO max timeout; continue polling until CLI returns regardless of elapsed time; NEVER abandon a running session
+6. **Indefinite wait** — shell_exec has NO max timeout; continue waiting until CLI returns regardless of elapsed time; NEVER abandon a running session
 6. **Same prompt, different --to** — fan-out delegates all use identical base prompt, only `--to <tool>` differs
 7. **Minimum 2 tools** — abort if fewer eligible
 8. **Partial degradation** — 1 tool fails → continue with remaining (minimum 2 results for cross-verify)
@@ -78,7 +78,7 @@ $ARGUMENTS — requirement text and optional flags.
 <states>
 S_PARSE          — 解析参数、发现工具                       PERSIST: —
 S_CONFIRM        — 展示计划、用户确认（-y 跳过）            PERSIST: —
-S_FAN_OUT        — 并行 exec_command fan-out + 轮询等待      PERSIST: per-tool outputs
+S_FAN_OUT        — 并行 shell_exec fan-out + 等待完成          PERSIST: per-tool outputs
 S_CROSS_VERIFY   — 交叉验证：共识/冲突/独特分类              PERSIST: cross-verify.md
 S_SYNTHESIZE     — 生成最终报告                              PERSIST: reports
 S_AGGREGATE      — 注册 artifact、输出摘要                   PERSIST: state.json
@@ -138,72 +138,27 @@ S_AGGREGATE:
 
 #### Phase 1: Parallel Launch
 
-Launch ALL delegate commands simultaneously via `multi_tool_use.parallel`:
+Launch ALL delegate commands simultaneously in parallel:
 
 ```
-multi_tool_use.parallel({
-  tool_uses: [
-    {
-      recipient_name: "functions.exec_command",
-      parameters: {
-        cmd: "maestro delegate \"<shared_prompt>\" --to agy --mode <mode> [--rule <rule>]",
-        yield_time_ms: 30000,
-        max_output_tokens: 6000
-      }
-    },
-    {
-      recipient_name: "functions.exec_command",
-      parameters: {
-        cmd: "maestro delegate \"<shared_prompt>\" --to claude --mode <mode> [--rule <rule>]",
-        yield_time_ms: 30000,
-        max_output_tokens: 6000
-      }
-    }
-    // ... one entry per selected tool
-  ]
-})
+// Parallel fan-out — one shell_exec per selected tool:
+shell_exec(`maestro delegate "<shared_prompt>" --to agy --mode <mode> [--rule <rule>]`, { timeout: 30000 })
+shell_exec(`maestro delegate "<shared_prompt>" --to claude --mode <mode> [--rule <rule>]`, { timeout: 30000 })
+// ... one call per selected tool
+// Execution mapping: @~/.maestro/workflows/shell-exec-protocol.md
 ```
 
 #### Phase 2: Block Until ALL Complete
 
-For each result from Phase 1, check completion status:
+Each `shell_exec` call blocks until its delegate completes. Save each result:
 
-- **Completed** (no session_id) → save output directly to `{scratchDir}/per-tool/{tool}-output.md`
-- **Running** (session_id returned) → add to `pending_sessions[]`
+- **Completed** → save output to `{scratchDir}/per-tool/{tool}-output.md`
+- **Failed** → log error for that tool
 
-**Blocking poll loop — runs until pending_sessions is empty:**
-
-```
-pending_sessions = [{ tool, session_id }, ...]
-
-WHILE pending_sessions.length > 0:
-  FOR EACH session IN pending_sessions:
-    result = write_stdin({
-      session_id: session.session_id,
-      chars: "",
-      yield_time_ms: 60000,          // 60s per poll — no rush, wait for real output
-      max_output_tokens: 6000
-    })
-
-    IF result indicates completed:
-      save output → {scratchDir}/per-tool/{session.tool}-output.md
-      REMOVE session FROM pending_sessions
-      completed_count += 1
-
-    IF result indicates failed/error:
-      log error for session.tool
-      REMOVE session FROM pending_sessions
-      failed_count += 1
-
-    // still running → stays in pending_sessions, poll again next round
-```
-
-**Blocking guarantees:**
-- `yield_time_ms: 60000` — each poll waits up to 60s for output, no short-circuit
-- NO max retry count — loop continues indefinitely until CLI returns
-- NO timeout escalation — delegate can run as long as needed (30s to 10min+)
-- NO early exit — even if tool 1 and 2 are done, keep polling tool 3 until it completes
-- Round-robin ensures fair polling across all pending sessions
+**Blocking guarantees (per shell-exec-protocol.md):**
+- Each `shell_exec` waits until CLI returns — no short-circuit
+- NO max timeout — delegate can run as long as needed
+- NO early exit — all tools must complete before proceeding
 
 #### Phase 3: Validate
 
@@ -212,9 +167,9 @@ WHILE pending_sessions.length > 0:
 - 1 tool failed but 2+ succeeded → W001, log failure, continue
 
 **Iron rules**:
-- NEVER skip polling — every session_id MUST be polled to completion
-- NEVER proceed to S_CROSS_VERIFY while pending_sessions is non-empty
-- NEVER set a max timeout or max retry count on the poll loop
+- NEVER skip waiting — every shell_exec MUST complete before proceeding
+- NEVER proceed to S_CROSS_VERIFY while any delegate is still running
+- NEVER set a max timeout on shell_exec calls
 - NEVER generate analysis internally as substitute for CLI output
 - NEVER summarize or paraphrase — save raw CLI output verbatim
 
@@ -318,10 +273,10 @@ Generate 3 output files from cross-verify results:
 </error_codes>
 
 <success_criteria>
-- [ ] ALL analysis performed via exec_command → maestro delegate — zero internal analysis
-- [ ] multi_tool_use.parallel used for fan-out launch
-- [ ] Every exec_command polled to completion via write_stdin — no timeout cap, no max retries
-- [ ] Blocking poll loop ran until pending_sessions empty — no early exit
+- [ ] ALL analysis performed via shell_exec → maestro delegate — zero internal analysis
+- [ ] Parallel shell_exec calls used for fan-out launch
+- [ ] Every shell_exec waited to completion — no timeout cap, no early exit
+- [ ] All shell_exec calls waited to completion — no early exit
 - [ ] Per-tool raw outputs saved to {scratchDir}/per-tool/
 - [ ] Cross-verify: CONSENSUS/CONFLICT/UNIQUE classified, consensus_level computed
 - [ ] Boundary grill executed on CONFLICT items (skip if no boundary conflicts detected)

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

@@ -82,6 +82,7 @@ $maestro-execute --continue "20260318-execute-P3-phase3"
 - `--auto-commit`: Atomic git commit after each task completion
 - `--method agent|cli`: Override execution method (default: from config.json)
 - `--dir <path>`: Use arbitrary directory instead of phase resolution (scratch mode)
+- `--skip-verify`: Skip Phase 2.5 verification gate
 
 When `--yes` or `-y`: Auto-confirm task breakdown, skip blocked-task prompts, auto-continue through all waves.
 
@@ -159,14 +160,14 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column populated fr
 3. **CSV is Source of Truth**: Master tasks.csv holds all execution state
 4. **Context Propagation**: prev_context built from master CSV findings, not from memory
 5. **Discovery Board is Append-Only**: Never clear, modify, or recreate discoveries.ndjson
-6. **Cascading Skip on Failure**: If a task fails/blocks, all dependent tasks are skipped
+6. **Cascading Skip on Failure**: If a task fails/blocks, all dependent tasks are marked `skipped` with error referencing the failed dependency. Skipped tasks have no summaries — this is expected, not a violation of invariant 12/13.
 7. **Cleanup Temp Files**: Remove `wave-{N}.csv` AND `wave-{N}-results.csv` after results are merged
 8. **Max 3 Fix Attempts**: Per task, auto-fix convergence failures up to 3 times, then mark blocked
 9. **Breakpoint Resume**: Always detect completed tasks and skip them on re-run
-10. **DO NOT STOP**: Continuous execution until all waves complete or user explicitly stops
-11. **Invariant violation = BLOCK** — violating any invariant above blocks the current operation.
-12. **Evidence required in task summaries** — task summaries MUST include: files actually modified (not just planned targets), convergence criteria verification results (pass/fail with evidence), any deviations from plan with rationale. "Task completed successfully" without evidence is INVALID.
-13. **Artifact verification before completion** — for each completed task, .summaries/TASK-{NNN}-summary.md MUST exist with concrete evidence. EXC artifact MUST be registered in state.json. If any missing: DO NOT report completion.
+10. **Pipeline continuity**: Continuous execution until all waves complete or user explicitly stops. When all tasks in a wave are blocked/failed, stop execution and report the blocked wave — this is a defined termination, not an invariant violation.
+11. **Invariant violation = BLOCK** — violating any invariant above blocks the current operation. Defined termination (invariant 10) and cascading skips (invariant 6) are not violations.
+12. **Evidence required in task summaries** — task summaries MUST include: files actually modified (not just planned targets), convergence criteria verification results (pass/fail with evidence), any deviations from plan with rationale. "Task completed successfully" without evidence is INVALID. Does NOT apply to `skipped` tasks (invariant 6).
+13. **Artifact verification before completion** — for each completed task, .summaries/TASK-{NNN}-summary.md MUST exist with concrete evidence. EXC artifact MUST be registered in state.json. If any missing: DO NOT report completion. Skipped tasks are exempt (no summary expected).
 </invariants>
 
 <execution>
@@ -255,7 +256,7 @@ If exit code is 1, present warnings and ask whether to proceed.
 For each wave N in ascending order:
 
 1. Extract wave N pending rows from master `tasks.csv` (skip wave if none)
-2. Build `prev_context` per task from completed predecessor findings
+2. Build `prev_context` per task from completed predecessor findings. For `context_from` IDs whose status is `failed`/`blocked`/`skipped`: exclude from prev_context and append gap_note listing missing task IDs so the executor knows its context is incomplete.
 3. Write `wave-{N}.csv` with `prev_context` column, then execute:
 
 ```javascript
@@ -365,13 +366,19 @@ Skip Phase 2.5 when `--skip-verify` flag present or task count == 0.
 
 2. **Update task files**: Write each task's status from CSV back to `.task/{id}.json`
 
-3. **Issue status sync**: For tasks with `issue_id`, update `.workflow/issues/issues.jsonl`:
+3. **Register EXC artifact in state.json**: Find matching plan artifact, create `{ id: "EXC-{next_id}", type: "execute", milestone, phase, scope, path, status: "completed", depends_on: plan_artifact.id, harvested: false, created_at, completed_at }`. `milestone` MUST come from D-007 `phase_slugs` reverse lookup (numeric phase) — inherit from matching plan artifact if available, otherwise reverse-lookup directly.
+
+4. **Side-effect confirmation gate** (skip when `-y/--yes`):
+   Before writing to external stores, present a summary to the user via `request_user_input`:
+   - Issue status changes (count + IDs to resolve/update)
+   - Specs to extract (count + titles)
+   The user can approve all, selectively exclude, or skip entirely.
+
+   4a. **Issue status sync** (approved items only): For tasks with `issue_id`, update `.workflow/issues/issues.jsonl`:
    - All task_refs completed -> `issue.status = "resolved"`; any failed -> `"in_progress"`
    - Append history entry: `{ action: "executed", at: <ISO>, by: "maestro-execute", summary: "TASK-{NNN} {status}" }`
 
-4. **Register EXC artifact in state.json**: Find matching plan artifact, create `{ id: "EXC-{next_id}", type: "execute", milestone, phase, scope, path, status: "completed", depends_on: plan_artifact.id, harvested: false, created_at, completed_at }`. `milestone` MUST come from D-007 `phase_slugs` reverse lookup (numeric phase) — inherit from matching plan artifact if available, otherwise reverse-lookup directly.
-
-5. **Extract incremental specs**: Read `.summaries/`, use `maestro spec add` CLI:
+   4b. **Extract incremental specs** (approved items only): Read `.summaries/`, use `maestro spec add` CLI:
    - Learnings/pitfalls → `maestro spec add learning "<title>" "<content>" --keywords ... --description "<summary>" --source execute:{PLAN_DIR}`
    - Design rationale → `maestro spec add coding "<title>" "<content>" --keywords ... --description "<summary>"`
    - Root cause/workaround → `maestro spec add debug "<title>" "<content>" --keywords ... --description "<summary>"`
@@ -400,7 +407,7 @@ Skip Phase 2.5 when `--skip-verify` flag present or task count == 0.
 
 8. **Auto-sync** (if config.json.codebase.auto_sync_after_execute == true): detect changed files, trigger codebase doc update.
 
-9. **Display completion report**: Phase, completed/blocked counts, wave progress, paths to `.summaries/` and `.task/`, next step suggestions (`quality-review`, `manage-status`).
+9. **Display completion report**: Phase, completed/blocked counts, wave progress, paths to `.summaries/` and `.task/`. **Next-step suggestion** (suggest only, NEVER auto-execute): display recommended next command (e.g., `quality-review`, `manage-status`). The user decides whether to proceed.
 
 ### Shared Discovery Board Protocol
 
@@ -435,7 +442,7 @@ echo '{"ts":"<ISO>","worker":"TASK-001","type":"code_pattern","data":{"name":"Re
 | Agent spawn fails | Retry once, then mark task as blocked with checkpoint |
 | Convergence criteria not met after 3 attempts | Mark task as blocked, write checkpoint |
 | Git commit fails (--auto-commit) | Log warning, continue (task still marked completed) |
-| All tasks in wave blocked | Stop execution, report blocked wave |
+| All tasks in wave blocked | Stop execution, report blocked wave. Cascade-skip all tasks in subsequent waves. Proceed to Phase 3 aggregation with partial results. |
 | CSV parse error | Validate format, show line number |
 | discoveries.ndjson corrupt | Ignore malformed lines, continue |
 | Continue mode: no session found | List available sessions |

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

@@ -11,7 +11,7 @@ Socratic stress-testing of a plan, idea, or requirement against codebase reality
 Codex specifics:
 - **No agent spawning** — codebase exploration via `maestro explore` (preferred, fallback Glob/Grep/Read).
 - **request_user_input** replaces request_user_input for Socratic Q&A.
-- **CLI delegation** for auto mode: `exec_command("maestro delegate ... --role analyze --mode analysis")`.
+- **CLI delegation** for auto mode: `shell_exec("maestro delegate ... --role analyze --mode analysis")`.
 </purpose>
 
 <required_reading>
@@ -70,22 +70,23 @@ Exit: When all depth-selected branches are fully walked (every question answered
 <execution>
 Follow '~/.maestro/workflows/grill.md' completely.
 
-**Next-step routing on completion:**
+**Next-step suggestion** (suggest only, NEVER auto-execute):
+Display the recommended next command based on grill outcomes. The user decides whether to proceed.
 
-Standard routing:
-- Need multi-role elaboration → `$maestro-brainstorm "{topic}" --from grill:{artifact_id}`
-- Need deep technical analysis → `$maestro-analyze "{topic}" --from grill:{artifact_id}`
-- Scope is clear, ready for roadmap → `$maestro-roadmap --from grill:{artifact_id}`
-- Need formal spec package → `$maestro-blueprint --from grill:{artifact_id}`
-
-Resume routing:
-- More branches to walk → `$maestro-grill "{topic}" -c`
+| Condition | Suggested |
+|-----------|-----------|
+| Need multi-role elaboration | `$maestro-brainstorm "{topic}" --from grill:{artifact_id}` |
+| Need deep technical analysis | `$maestro-analyze "{topic}" --from grill:{artifact_id}` |
+| Scope is clear, ready for roadmap | `$maestro-roadmap --from grill:{artifact_id}` |
+| Need formal spec package | `$maestro-blueprint --from grill:{artifact_id}` |
+| More branches to walk | `$maestro-grill "{topic}" -c` |
 </execution>
 
 <invariants>
 1. **Invariant violation = BLOCK** — violating any invariant above blocks the current operation.
 2. **Code-grounded questions required** — 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, flag ALL locked decisions as LOW CONFIDENCE.
-3. **Artifact verification before completion** — verify grill-report.md (with Branch Log + Q&A + synthesis), terminology.md (≥5 terms), and context-package.json all exist before reporting completion. If any missing: DO NOT report completion.
+3. **Auto mode decisions are advisory** — in auto mode (`-y`), delegate-generated answers are recorded as decisions but MUST be tagged `source: "auto/delegate"` (not `source: "user"`). Downstream consumers SHOULD treat auto-sourced locked decisions with lower confidence than user-confirmed ones. The `context-package.json` MUST include `auto_mode: true` flag so downstream skills can distinguish.
+4. **Artifact verification before completion** — verify grill-report.md (with Branch Log + Q&A + synthesis), terminology.md (≥5 terms), and context-package.json all exist before reporting completion. If any missing: DO NOT report completion.
 </invariants>
 
 <error_codes>

package/.codex/skills/maestro-next/SKILL.md

@@ -44,7 +44,7 @@ $ARGUMENTS — 意图文本 + 可选 flags。
 3. **Skill 发现限定 codex 平台** — 通过 `maestro ralph skills --platform codex --json --quiet` 解析 `command_scope` + `command_path`（project 覆盖 global，限定 `.codex/skills/`）；未命中即 E003
 4. **空 intent 或 "continue/next/go/继续/下一步/接下来"** → 直接采用 lifecycle_position 推断的自然下一步
 5. **字面命中路由表优先** — lifecycle 仅作加分；命中失败时 lifecycle 上升为决定性信号
-6. **In-context invocation** — top pick 以 `$skill-name {args}` 形式在协调器上下文直接调用，**禁止** spawn_agent / spawn_agents_on_csv / exec_command 包装
+6. **In-context invocation** — top pick 以 `$skill-name {args}` 形式在协调器上下文直接调用，**禁止** spawn_agent / spawn_agents_on_csv / shell_exec 包装
 7. **参数传递** — 默认 intent 原文作为第一个 arg；用户可在 S_CONFIRM 修改；`-y` 仅当用户传入时透传到 skill args
 8. **`--list` 模式跳过 lifecycle 推断与评分**，仅按 workflow 簇分组列出全部候选
 </invariants>
@@ -234,7 +234,7 @@ brainstorm → blueprint → init → analyze-macro → roadmap
 
 ### A_INVOKE_SKILL
 
-在协调器上下文以 `$skill-name {args}` 直接调用（**NO spawn_agent, NO exec_command 包装**）：
+在协调器上下文以 `$skill-name {args}` 直接调用（**NO spawn_agent, NO shell_exec 包装**）：
 
 1. 解析最终 args：
    - 默认：`{intent}`（原文，去除已识别的关键词如 "continue"）
@@ -296,7 +296,7 @@ brainstorm → blueprint → init → analyze-macro → roadmap
 - [ ] `--dry-run` 仅展示，不执行
 - [ ] `-y` 自动执行 top pick；用户传入时透传到 skill args
 - [ ] 非自动模式通过 `request_user_input` 确认或选备选
-- [ ] 选定 skill 在协调器上下文以 `$skill {args}` 直调（NO spawn_agent / NO exec_command 包装）
+- [ ] 选定 skill 在协调器上下文以 `$skill {args}` 直调（NO spawn_agent / NO shell_exec 包装）
 - [ ] 不创建 session / 不生成 status.json / 不调用 create_goal/update_plan / 不触发后续 chain
 - [ ] `--list` 模式按 workflow 簇分组展示，每项标 `[project|global]` scope
 

package/.codex/skills/maestro-overlay/SKILL.md

@@ -10,7 +10,7 @@ allowed-tools: Read, Write, Bash, Glob, Grep
 
 ```
 Parse Intent  →  Identify Targets  →  Draft JSON  →  Install + Report
-(or --list /      (read command        (apply_patch    (exec_command +
+(or --list /      (read command        (apply_patch    (shell_exec +
   --remove)         XML sections)       to overlays/)    banner)
 ```
 

package/.codex/skills/maestro-plan/SKILL.md

@@ -90,7 +90,9 @@ Write resolved milestone into PLN artifact registration and `plan.json.milestone
 
 **Pre-load** (optional): context-package.json (via `--from`, takes precedence), context.md (prior analyze), conclusions.json, codebase ARCHITECTURE.md, `maestro search`, `maestro load --type spec --category arch`, team preflight `maestro collab preflight`.
 
-**D-008 Ad-hoc Milestone Auto-Creation**: When scope resolves to `standalone` via standard resolution (routes 6 or 7, NOT via `--from`), and `state.json.current_milestone == null`, auto-create an adhoc milestone:
+**D-008 Ad-hoc Milestone Auto-Creation**: When scope resolves to `standalone` via standard resolution (routes 6 or 7, NOT via `--from`), and `state.json.current_milestone == null`:
+- **Interactive mode**: prompt user via `request_user_input` — "No active milestone. Create ad-hoc milestone `ADH-{YYYYMMDD}-{slug}`?" with options: Create (Recommended) / Abort / Specify milestone name. Only write to state.json after user confirms.
+- **Auto mode (`-y`)**: auto-create with log notification.
 ```
 milestone_id = "ADH-{YYYYMMDD}-{slug}"
 state.json.milestones.push({ id: milestone_id, name: "{intent slug}", type: "adhoc", status: "active", phase_slugs: [] })
@@ -114,10 +116,10 @@ Wave 1: N exploration rows (parallel). Wave 2: 1 planning row (sequential).
 1. **Wave order sacred**: Explorations (W1) before planning (W2)
 2. **CSV source of truth**: Master tasks.csv holds all state
 3. **Discovery board append-only**: Never modify/delete
-4. **Skip on failure**: If all explorations fail, planner proceeds with available context
-5. **DO NOT STOP**: Continuous until all waves complete
-6. **Invariant violation = BLOCK** — violating any invariant above blocks the current operation.
-7. **Verifiable convergence criteria required** — every task MUST have convergence.criteria[] with grep-verifiable conditions (no subjective language like "well-structured" or "properly implemented"). If any task lacks verifiable criteria: DO NOT report completion — fix the criteria first.
+4. **Skip on failure**: If all explorations fail, planner proceeds with available context but ALL generated tasks inherit LOW CONFIDENCE flag. Record `degradation_event` in discoveries.ndjson. This is a defined degradation path, not an invariant violation.
+5. **Pipeline continuity**: Continuous until all waves complete. When invariant 4 (skip on failure) activates, the pipeline continues in degraded mode — this is NOT a violation of invariant 6.
+6. **Invariant violation = BLOCK** — violating any invariant above blocks the current operation. Defined degradation paths (invariant 4) are not violations.
+7. **Verifiable convergence criteria required** — every task MUST have convergence.criteria[] with grep-verifiable conditions (no subjective language like "well-structured" or "properly implemented"). If any task lacks verifiable criteria: DO NOT report completion — fix the criteria first. **Degradation exception**: when invariant 4 is active (exploration failed), criteria that would normally reference exploration findings MAY use available context instead, but MUST be flagged LOW CONFIDENCE.
 8. **Artifact verification before completion** — plan.json and .task/TASK-*.json files MUST exist. PLN artifact MUST be registered in state.json. If any missing: DO NOT report completion.
 </invariants>
 
@@ -138,18 +140,21 @@ S_REGISTER    — 注册 PLN artifact、更新 index.json           PERSIST: sta
 <transitions>
 S_PARSE → S_RESUME     WHEN: --continue
 S_PARSE → S_CONTEXT    WHEN: phase/dir/--from resolved (D-007 reverse lookup for numeric)
-S_PARSE → S_CONTEXT    WHEN: no args + no roadmap AND latest analyze artifact found in state.json (scope=standalone)
+S_PARSE → S_CONTEXT    WHEN: no args + no roadmap AND latest analyze artifact found in state.json (scope=standalone). Interactive mode: confirm the auto-discovered artifact with user ("Using analyze artifact ANL-xxx from {date}. Proceed?"). -y mode: auto-proceed with log.
 S_PARSE → ERROR        WHEN: no args + no roadmap + no analyze artifact
 
 S_RESUME → S_WAVE_1    WHEN: W1 incomplete    DO: load session, resume
 S_RESUME → S_WAVE_2    WHEN: W1 done, W2 pending
 S_RESUME → S_CHECK     WHEN: W2 done, check pending
+S_RESUME → ERROR       WHEN: session file corrupted/missing or CSV parse failure
 
 S_CONTEXT → S_CSV_GEN  DO: if --from: resolve context-package.json (precedence over context.md); load context.md, conclusions.json, specs, wiki, codebase docs
 
 S_CSV_GEN → S_WAVE_1   DO: pre-flight (`maestro collab preflight --phase N`; exit 1 → warn + ask), determine exploration angles, generate tasks.csv, user validates (skip -y)
 
-S_WAVE_1 → S_WAVE_2    DO: spawn parallel explorations, merge results, build prev_context
+S_WAVE_1 → S_WAVE_2    WHEN: 1+ completed    DO: spawn parallel explorations, merge results, build prev_context. For failed exploration tasks: exclude from prev_context and append gap_note to W2 planning instruction listing missing angles.
+S_WAVE_1 → S_WAVE_1    WHEN: all failed, retry available   DO: retry once
+S_WAVE_1 → S_WAVE_2    WHEN: all failed, retry exhausted   DO: proceed with available context only, flag LOW CONFIDENCE (invariant 4 degradation)
 
 S_WAVE_2 → S_CHECK     DO: spawn planning agent, merge results
 
@@ -242,10 +247,14 @@ Confidence: 5-dimension factor model + readiness gate.
 Collision detection against same-milestone plans.
 
 ### A_REGISTER
+
+**Note**: S_CONFIRM already gates user confirmation (or -y skip). The writes below execute only after S_CONFIRM passes.
+
 1. Register PLN artifact in state.json (scope, milestone, phase, depends_on)
 2. Update index.json with plan metadata
 3. If --gaps: link TASK files back to issues bidirectionally (task_refs[], task_plan_dir in issues.jsonl)
-4. Display: phase, task count, wave count, check status, confidence, next steps
+4. Display: phase, task count, wave count, check status, confidence
+5. **Next-step suggestion** (suggest only, NEVER auto-execute): display recommended next command (e.g., `maestro-execute {phase}`). The user decides whether to proceed.
 
 </actions>
 </state_machine>

package/.codex/skills/maestro-ralph/SKILL.md

@@ -20,6 +20,8 @@ Reads project state → infers position → builds adaptive chain → delegates
 
 > 推进规则：**step 推进由 `$maestro-ralph-execute` 负责**；ralph 仅在 build / decision 评估时介入。decision 节点由 ralph-execute 自动 `$maestro-ralph` 直调 handoff，无需用户手动切换。
 
+> **CLI vs Skill 边界**：`maestro` 作为 CLI 二进制只有结构化子命令（`ralph`、`delegate`、`explore` 等），不接受裸 intent。`Bash("maestro \"some intent\"")` 会报错退出。创建 session 和路由 intent 必须通过 `$maestro-ralph` 或 `$maestro` skill 调用。CLI 层仅用于 step 加载（`ralph next`）和完成标记（`ralph complete`）。
+
 Initial decomposition (S_DECOMPOSE): boundary-clarified via ≤3 questions for broad intents (重构/全面/迁移/重写). 写入 status.json 的 `boundary_contract` / `execution_criteria` / `task_decomposition`，附 `/goal` prompt。
 
 Step kinds:
@@ -85,6 +87,7 @@ Remaining                        → intent (amend_mode 时为 change_request)
 12. **Platform** — `session.platform = "codex"`；CLI 调用一律带 `--platform codex`
 13. **Invariant violation = BLOCK** — violating any invariant above blocks the current operation. Do NOT bypass for "efficiency" or "clear intent" reasons. Especially invariants about ralph never executing steps and completion_confirmed by CLI.
 14. **Delegate fallback must be marked** — when A_DELEGATE_EVALUATE verdict parse fails and falls back to "fix", MUST record `parse_failed: true, confidence_score: 0` in decisions.ndjson. Subsequent steps inherit LOW CONFIDENCE flag.
+15. **CLI ≠ Skill** — `maestro` CLI binary 只提供结构化子命令（`ralph next|complete|skills|check|session`、`delegate`、`explore`、`search` 等），**不接受裸 intent**。Session 创建、intent 路由、decision 评估均为 skill 层操作：`$maestro-ralph "intent"` 或 `$maestro "intent"`。**严禁** `Bash("maestro \"intent text\"")` — CLI 会报错退出。
 </invariants>
 
 <state_machine>

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

@@ -48,6 +48,7 @@ HARD RULES:
 7. **status.json 每步骤后由 CLI 原子写盘** — resume-safe
 8. **STATUS 枚举受限** — 仅 `DONE | DONE_WITH_CONCERNS | NEEDS_RETRY | BLOCKED`
 9. **Platform binding** — 仅处理 `session.platform == "codex"` 的会话；platform 缺失视为 codex（向前兼容）
+10. **CLI ≠ Skill** — `maestro ralph next|complete|retry` 是 CLI 子命令（Bash 调用）；`$maestro-ralph` / `$maestro-ralph-execute` 是 skill 直调。**严禁** `Bash("maestro \"intent\"")` 裸 intent 调用，CLI 不接受。
 </invariants>
 
 <state_machine>