maestro-flow 0.5.42 → 0.5.44

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

@@ -17,6 +17,7 @@ $ARGUMENTS — question text and optional flags.
 **Flags:**
 - `--scope <path>` — Restrict to files under this directory (default: entire project)
 - `--max-hypotheses N` — Max hypotheses before escalating (default: 3)
+- `--no-persist` — Skip writing to learnings.md (report.md still written locally)
 
 **Output**: `.workflow/knowhow/KNW-investigate-{slug}/` (evidence.ndjson, understanding.md, report.md)
 </context>
@@ -50,12 +51,15 @@ Generate ranked hypotheses from evidence. For each (in rank order):
 ### Stage 4: 3-Strike Escalation
 If all hypotheses fail: broaden scope, search wiki with alt keywords, or mark INCONCLUSIVE.
 
-### Stage 5: Synthesize + Persist
+### Stage 5: Synthesize + Persist (confirmation-gated)
 1. Write `report.md` with answer, evidence trail, hypothesis results
-2. Append to `.workflow/specs/learnings.md`:
-   - Confirmed → category: "technique" / "pattern"
-   - Disproved → category: "gotcha"
-3. Display summary with next-step routing
+2. If `--no-persist`: skip learnings append, display summary only
+3. Otherwise: **Confirmation gate** — prompt user via `request_user_input`: "Persist findings to learnings.md? (y/n)"
+   - `y` → append to `.workflow/specs/learnings.md`:
+     - Confirmed → category: "technique" / "pattern"
+     - Disproved → category: "gotcha"
+   - `n` → skip learnings append
+4. Display summary with next-step routing
 
 **Next steps:** `$spec-add debug <finding>`, `$learn-follow <path>`, `$learn-decompose <module>`
 </execution>
@@ -76,6 +80,7 @@ If all hypotheses fail: broaden scope, search wiki with alt keywords, or mark IN
 - [ ] At least 1 hypothesis formed and tested
 - [ ] understanding.md tracks evolving understanding
 - [ ] report.md written with answer and evidence trail
-- [ ] Findings appended to .workflow/specs/learnings.md with stable INS-ids
+- [ ] User confirmation obtained before learnings append (unless --no-persist)
+- [ ] Findings appended to .workflow/specs/learnings.md with stable INS-ids (if confirmed)
 - [ ] 3-strike escalation triggered if all hypotheses fail
 </success_criteria>

package/.codex/skills/learn-retro/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: learn-retro
 description: Retrospective of git activity and decision quality
-argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"[--lens git|decision|all] [--days N] [--author <name>] [--area <path>] [--phase N] [--compare]\""
+argument-hint: "[--lens git|decision|all] [--days N] [--author <name>] [--area <path>] [--phase N] [--compare]"
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
@@ -42,7 +42,9 @@ $ARGUMENTS — lens selection and scope flags.
 **3a: Collect decisions** from wiki, specs, git log, phase context, .workflow/specs/learnings.md.
 **3b: Build decision registry** per decision (id, title, source, rationale, alternatives, evidence).
 
-**3c: Multi-perspective evaluation** via spawn_agents_on_csv (3 parallel agents; filter `wave==1 AND status=="pending"`):
+**3c: Multi-perspective evaluation** — **Confirmation gate**: prompt user via `request_user_input` before spawning wave: "Spawn 3 perspective agents for decision evaluation? (y/n)". On `n`, skip to Phase 4 with decisions listed but unevaluated.
+
+Via spawn_agents_on_csv (3 parallel agents; filter `wave==1 AND status=="pending"`):
 
 | id | perspective | focus |
 |----|------------|-------|
@@ -85,8 +87,11 @@ Do NOT write to tasks.csv, wave-*.csv, results.csv. Do NOT call spawn_agents_on_
 ### Phase 4: Unified Report
 Write `KNW-retro-{date}.md` + `KNW-retro-{date}.json` with metrics, sessions, hotspots, decision health, combined insights, recommended actions.
 
-### Phase 5: Persist
-Append insights to `.workflow/specs/learnings.md` (source: "retro-git" or "retro-decision"). Display summary.
+### Phase 5: Persist (confirmation-gated)
+**Confirmation gate**: prompt user via `request_user_input` — "Append retro insights to learnings.md? (y/n)"
+- `y` → append insights to `.workflow/specs/learnings.md` (source: "retro-git" or "retro-decision")
+- `n` → skip append, display summary only
+Display summary.
 
 **Next steps:** `$learn-follow <path>`, `$quality-auto-test <area>`, `$learn-investigate <question>`
 </execution>
@@ -105,7 +110,8 @@ Append insights to `.workflow/specs/learnings.md` (source: "retro-git" or "retro
 <success_criteria>
 - [ ] Lens selection parsed correctly
 - [ ] Git lens: metrics computed, sessions detected, hotspots identified
-- [ ] Decision lens: decisions collected, 3 agents spawned in parallel, lifecycle classified
+- [ ] Decision lens: decisions collected, user confirmed before wave spawn, 3 agents spawned in parallel (if confirmed), lifecycle classified
 - [ ] Unified report written to KNW-retro-{date}.md + KNW-retro-{date}.json
-- [ ] .workflow/specs/learnings.md appended with insights (stable INS-ids)
+- [ ] User confirmation obtained before learnings append
+- [ ] .workflow/specs/learnings.md appended with insights (stable INS-ids, if confirmed)
 </success_criteria>

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

@@ -1,7 +1,7 @@
 ---
 name: learn-second-opinion
 description: Get alternative perspectives -- review, challenge, or consult
-argument-hint: "[-y|--yes] [-c|--concurrency 3] [--continue] \"<target> [--mode review|challenge|consult]\""
+argument-hint: "<target> [--mode review|challenge|consult]"
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
@@ -47,7 +47,14 @@ Resolve target to content. Load specs, `maestro search`, prior lessons for conte
 | 3 | strategist | Scalability, extensibility, architecture alignment | coupling, cohesion |
 | 4 | synthesis | Merge verdicts → agreements, disagreements, top 3 recommendations | combined verdict |
 
-Wave 1: 3 persona agents in parallel (filter `wave==1 AND status=="pending"`). Wave 2: synthesis agent with wave 1 findings as prev_context.
+Wave 1: 3 persona agents in parallel (filter `wave==1 AND status=="pending"`).
+
+**Failed persona handling** (between Wave 1 and Wave 2):
+- Exclude rows where `result_status == "failed"` from synthesis input
+- If any persona failed, inject `gap_note` into synthesis prev_context listing missing perspectives
+- If fewer than 2 personas completed, mark overall synthesis as `evidence_incomplete: true` in output
+
+Wave 2: synthesis agent with completed wave 1 findings as prev_context (failed rows excluded).
 
 **output_schema** (both waves):
 
@@ -103,13 +110,14 @@ Interactive loop via request_user_input. Agent studies target, answers questions
 |------|----------|-----------|----------|
 | E001 | error | Target not resolvable | Verify path/ID |
 | E002 | error | Unknown --mode value | Use: review, challenge, consult |
-| W001 | warning | Persona agent failed — partial perspectives | Proceed with available agents |
+| W001 | warning | Persona agent failed — partial perspectives | Exclude failed rows, inject gap_note, mark evidence_incomplete if <2 completed |
 | W003 | warning | Git diff empty for HEAD/staged | Use file path instead |
 </error_codes>
 
 <success_criteria>
 - [ ] Target resolved and context loaded
 - [ ] Mode executed: review (3 parallel agents), challenge (adversarial), or consult (interactive)
+- [ ] Failed persona rows excluded from synthesis input; gap_note injected if any failed; evidence_incomplete marked if <2 completed
 - [ ] Synthesis produced with agreements, disagreements, verdict
 - [ ] Report written to `KNW-opinion-{slug}-{date}.md`
 - [ ] Non-trivial findings appended to `.workflow/specs/learnings.md`

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

@@ -2,18 +2,24 @@
 name: maestro
 description: Auto-route intent to optimal command chain
 argument-hint: "\"intent text\" [-y] [-c|--continue] [--dry-run] [--super]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input, create_goal, update_plan, update_goal
 ---
 
 <purpose>
 Sequential pipeline coordinator. Classify intent → decompose (broad lifecycle intents) →
 resolve chain → **directly invoke each skill in-context, one at a time** → report.
 
+### Notation
+
+`Skill(name)` / `Skill(name, args)` = 加载 `~/.codex/skills/{name}/SKILL.md` 或 `.codex/skills/{name}/SKILL.md`（project 覆盖 global），args 填入目标 SKILL.md `<context>` 块的输入参数位。这是 skill 间的内部调用，**不是 CLI 命令**。严禁翻译为 `Bash("maestro {name} {args}")`。
+
+合法 CLI 子命令仅限结构化操作：`maestro ralph next`、`maestro ralph complete`、`maestro delegate`、`maestro explore` 等。
+
 Entry points:
-- **`$maestro "intent"`** — Classify → decompose → chain → execute
-- **`$maestro --continue`** — Resume from first pending step
-- **`$maestro --dry-run "intent"`** — Show chain, no execution
-- **`$maestro --super "intent"`** — Production-ready mode (read maestro-super.md)
+- **`Skill(maestro, "intent")`** — Classify → decompose → chain → execute
+- **`Skill(maestro, "--continue")`** — Resume from first pending step
+- **`Skill(maestro, "--dry-run intent")`** — Show chain, no execution
+- **`Skill(maestro, "--super intent")`** — Production-ready mode (read maestro-super.md)
 
 Codex specifics (parity with maestro-ralph):
 - **No agent spawning** — skills run directly in coordinator context, sequentially.
@@ -38,7 +44,7 @@ $ARGUMENTS — user intent text, or special flags.
 </context>
 
 <invariants>
-1. **Skills invoked DIRECTLY in-context** — coordinator runs `$skill {resolved_args}` itself, sequentially. NO spawn_agents_on_csv, NO wave/CSV/worker.
+1. **Skills invoked DIRECTLY in-context** — coordinator runs `Skill(skill_name, resolved_args)` itself, sequentially. NO spawn_agents_on_csv, NO wave/CSV/worker.
 2. **Coordinator owns the loop** — classify → decompose → resolve chain → for each step: resolve args → invoke skill → read result → persist → next.
 3. **Decomposition contract shared with maestro-ralph** — broad/lifecycle intents run S_DECOMPOSE producing the SAME additive block (`boundary_contract`, `execution_criteria`, `task_decomposition`). Reference maestro-ralph `A_DECOMPOSE_TASKS`
 4. **Goal is tool-created** — `A_DECOMPOSE_TASKS` calls `create_goal` with sub-goal success criteria. `update_goal` on convergence; held while aborted/paused
@@ -49,7 +55,7 @@ $ARGUMENTS — user intent text, or special flags.
 8. **schema 向后兼容** — decomposition 字段可选；`steps[]` 由 post-goal-audit 动态生长（goal_ref tagged）；既有字段不删不改；`waves` 保留空数组
 9. **Sequential execution** — one step at a time in index order; each step's result read before the next starts
 10. **Abort on failure** — failed step → mark remaining skipped → report (goal stays bound for `--continue`)
-11. **CLI ≠ Skill** — 本 skill 通过 `$maestro "intent"` 调用。`maestro` CLI 二进制不接受裸 intent（`Bash("maestro \"intent\"")` 会报错退出）。CLI 层只有结构化子命令：`ralph`、`delegate`、`explore`、`search` 等。
+11. **CLI ≠ Skill** — 本 skill 通过 `Skill(maestro, "intent")` 调用。`maestro` CLI 二进制不接受裸 intent（`Bash("maestro \"intent\"")` 会报错退出）。CLI 层只有结构化子命令：`ralph`、`delegate`、`explore`、`search` 等。
 </invariants>
 
 <state_machine>
@@ -279,7 +285,7 @@ Read `.workflow/state.json` and route by condition:
    ```
    create_goal({ objective: "Maestro {chain}: {intent} — converge {N} sub-goals within boundary",
      success_criteria: task_decomposition.map(g => `${g.id}: ${g.done_when}`),
-     constraints: [...execution_criteria, "stay within boundary_contract; resume via $maestro --continue"] })
+     constraints: [...execution_criteria, "stay within boundary_contract; resume via Skill(maestro, "--continue")"] })
    ```
 
 ### A_CREATE_SESSION
@@ -354,7 +360,7 @@ Direct in-context skill invocation — **replaces the old spawn/wave/CSV mechani
 
    **--from auto-injection**: 当 step 是 `maestro-plan`，args 含 `{phase}` 但无 `--from` 且无 `--dir`，且 `session.context.analysis_dir` 已填充 → 查 state.json 同 phase+milestone 最新 completed analyze artifact → 注入 `--from analyze:{id}`，写 `step.source_artifact_ref`
 2. Mark step `status="running"`, persist status.json + `update_plan` (this step → in_progress)
-3. **Invoke the skill directly**: execute `$skill {resolved_args}` in coordinator context (NO spawn). Read its produced artifacts directly
+3. **Invoke the skill directly**: execute `Skill(skill_name, resolved_args)` in coordinator context (NO spawn). Read its produced artifacts directly
 4. On success: mark step `status="done"`. **Structured completion**: `Bash("maestro ralph complete {idx} --status DONE --summary \"...\" [--decisions \"...\"] [--caveats \"...\"] [--deferred \"...\"]")`（`--summary` MUST，动词开头 ≤100 字）。**Barrier-context update** (when step is a context-producing skill):
    | Skill | Read | Context Updates |
    |-------|------|-----------------|
@@ -379,7 +385,7 @@ S_DECISION_EVAL 入口；镜像 maestro-ralph `A_GOAL_AUDIT_EVALUATE`。Condense
 
 ### A_APPLY_GOAL_FIX
 
-**Dynamic step-growth core** (mirrors maestro-ralph). For each unmet sub-goal (grouped by target_phase), insert before the post-goal-audit node a scoped mini-loop `$maestro-plan --gaps {phase} "G{n}: {gap}" → $maestro-execute {phase}`, each tagged `goal_ref: "G{n}"`, type `"skill"`. Re-append `decision:post-goal-audit {retry+1}`. Reindex, increment retry, persist + `update_plan`. `steps[]` grew.
+**Dynamic step-growth core** (mirrors maestro-ralph). For each unmet sub-goal (grouped by target_phase), insert before the post-goal-audit node a scoped mini-loop `Skill(maestro-plan, "--gaps {phase} G{n}: {gap}") → Skill(maestro-execute, "{phase}")`, each tagged `goal_ref: "G{n}"`, type `"skill"`. Re-append `decision:post-goal-audit {retry+1}`. Reindex, increment retry, persist + `update_plan`. `steps[]` grew.
 
 ### A_APPLY_GOAL_DONE
 
@@ -562,13 +568,13 @@ Chain:    {chain}
 Steps:    {completed}/{total}   Sub-goals: {done}/{total}
 
 STEP RESULTS:
-  [1] $maestro-analyze --gaps  →  ✓  found 3 gaps
-  [2] $maestro-plan --gaps     →  ✓  12 tasks
+  [1] maestro-analyze --gaps  →  ✓  found 3 gaps
+  [2] maestro-plan --gaps     →  ✓  12 tasks
   [◆] post-goal-audit          →  ✓  all sub-goals met
   ...
 
 State:    .workflow/.maestro/{sessionId}/status.json
-Resume:   $maestro --continue
+Resume:   Skill(maestro, "--continue")
 ```
 
 </appendix>

package/.codex/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, Write, Bash, Glob, Grep, request_user_input
 ---
 <purpose>
@@ -33,6 +33,13 @@ Multiple combinable. No flags + no description → interactive (scan + request_u
 
 **CLI targeting**: `"cli": "claude"` (default, patches .claude/commands/), `"codex"` (patches .codex/skills/), `"both"` (both paths)
 
+**Source path mapping by CLI**:
+| CLI | Pristine source path |
+|-----|---------------------|
+| `claude` | `$PKG_ROOT/.claude/commands/<name>.md` |
+| `codex` | `.codex/skills/<name>/SKILL.md` |
+| `both` | Both paths checked; overlay targets whichever exists |
+
 **Output**: `~/.maestro/overlays/amend-{slug}.json` + optional `~/.maestro/overlays/docs/amend-{slug}.md`
 </context>
 
@@ -62,6 +69,7 @@ S_GROUP:
   → S_PREVIEW     DO: A_GROUP_OVERLAYS
 
 S_PREVIEW:
+  → S_DRAFT       WHEN: `-y` flag set (skip confirmation, apply all)
   → S_DRAFT       WHEN: user confirms "Apply all" or selects patches
   → S_PREVIEW     WHEN: user selects "Edit"                DO: modify signal target/section
   → END           WHEN: user cancels
@@ -109,7 +117,7 @@ Per signal, determine:
 | Scope/context gap | context | append |
 | Entirely new concern | _(new section)_ | new-section |
 
-Read pristine source from `$PKG_ROOT/.claude/commands/<name>.md` to confirm section.
+Read pristine source using CLI path mapping: `claude` → `$PKG_ROOT/.claude/commands/<name>.md`, `codex` → `.codex/skills/<name>/SKILL.md`. Confirm section exists in target.
 Classify: command deficiency → proceed; code bug → skip (suggest $maestro-quick).
 
 ### A_GROUP_OVERLAYS

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

@@ -149,7 +149,11 @@ S_CSV_GEN:
 S_WAVE_1:
   -> S_WAVE_2     WHEN: full mode, 1+ completed    DO: A_SPAWN_WAVE_1
   -> S_WAVE_3     WHEN: gaps mode, 1+ completed    DO: merge results
-  -> ERROR        WHEN: all failed
+  -> S_WAVE_1 (retry)    WHEN: all failed, retry available   DO: retry once
+  -> S_WAVE_2_DEGRADED   WHEN: all failed, retry exhausted   DO: flag ALL downstream LOW CONFIDENCE, record degradation_event in discoveries.ndjson
+
+S_WAVE_2_DEGRADED:
+  -> S_WAVE_3     DO: A_SPAWN_WAVE_2 with degraded=true (scoring agents receive gap_note for all dimensions, outputs inherit LOW CONFIDENCE)
 
 S_WAVE_2:
   -> S_BOUNDARY_GRILL   WHEN: 1+ completed                 DO: A_SPAWN_WAVE_2
@@ -234,6 +238,8 @@ Merge results -> master tasks.csv (map `result_status` → master `status`).
 
 Filter `wave==3 AND status=="pending"` -> build prev_context from wave 2 scores (or project context for quick mode) -> spawn with `SYNTHESIS_INSTRUCTION + SHARED_TERMINATION_CONTRACT`.
 
+**Failed-score exclusion**: when building prev_context, skip `context_from` IDs whose status is `failed`/`blocked`. Append a `gap_note` to the synthesis instruction listing which scoring dimensions are missing so the agent knows its evidence base is incomplete. When gaps exist, synthesis outputs MUST include a `confidence_penalty` and flag affected decisions as LOW CONFIDENCE.
+
 **Synthesis agent**:
 - Full mode: analysis.md (executive summary, per-dimension scores, risk matrix, Go/No-Go), context.md (Locked/Free/Deferred decisions), context-package.json, conclusions.json (with `scope_verdict` + `implementation_scope[]`)
 - Quick mode: context.md + context-package.json + **minimal conclusions.json** (`scope_verdict` + `implementation_scope[]` only — seeds plan task generation per redesign §8.3)

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

@@ -50,7 +50,7 @@ maestro-analyze → maestro-roadmap → maestro-plan
 </context>
 
 <interview_protocol>
-Interview the user relentlessly about every aspect of the spec until shared understanding is reached. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one; if a question can be answered by exploring the codebase, explore the codebase instead. Active only in interactive mode; skip when `-y/--yes`, `-c/--continue`, or input is already specific (clear idea + scope).
+Interview the user relentlessly about every aspect of the spec until shared understanding is reached. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one; if a question can be answered by exploring the codebase, explore the codebase instead. Active only in interactive mode; skip ONLY when `-y/--yes` or `-c/--continue` is set.
 
 - Ask one question per turn via request_user_input and wait for the user's feedback before continuing; every question must carry a recommended answer marked `(Recommended)`, 2–4 options total. 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`, existing artifacts, `maestro load --type spec`, codebase exploration (`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.

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

@@ -173,9 +173,9 @@ INPUTS — read these files (do NOT modify):
 - <ABS_SESSION>/guidance-specification.md
 - <ABS_SESSION>/<role_1>/analysis.md
 - <ABS_SESSION>/<role_2>/analysis.md
-- ... (one per role from Wave 2)
+- ... (one per COMPLETED role from Wave 2 — failed/blocked roles are excluded)
 
-(Orchestrator MUST inject the actual absolute paths for all completed Wave 2 rows.)
+(Orchestrator MUST inject the actual absolute paths for completed Wave 2 rows ONLY. If any W2 roles failed, append a gap_note listing the missing roles so the reviewer can flag affected findings as LOW CONFIDENCE.)
 
 TASK: Compare §2 Decision Digests across role analysis.md index files. Identify:
 - Conflicts: contradictory stances between roles on the same feature/topic
@@ -306,8 +306,9 @@ S_CHECK_1 → S_WAVE_2   WHEN: (-y OR user "Proceed") AND ui-designer NOT in sel
 S_CHECK_1 → S_CHECK_1  WHEN: user "Revise"    DO: edit guidance-spec, re-display
 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: DESIGN.md already exists (skip explore — visual direction locked)
+S_DESIGN → S_WAVE_2    WHEN: user confirms explore AND explore completed    DO: A_DESIGN_EXPLORE
+S_DESIGN → S_WAVE_2    WHEN: user skips explore    DO: set session.design_degraded=true, W2 ui-designer receives gap_note="DESIGN.md unavailable"
 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   WHEN: 1+ completed     DO: spawn wave-2 (parallel), merge results — each agent writes {role}/analysis.md + sub-files
@@ -347,7 +348,7 @@ system-architect MUST include in §3: Data Model, State Machine, Error Handling,
 
 The agent MUST write files. The agent MUST NOT return analysis as text.
 
-**Cross-Role Review (W3, agent role `cross-role-reviewer`)**: Read ALL `{role}/analysis.md` files (§2 Decision Digests) + guidance-specification.md → emit structured report (NOT files):
+**Cross-Role Review (W3, agent role `cross-role-reviewer`)**: Read ONLY completed W2 role `{role}/analysis.md` files (§2 Decision Digests) + guidance-specification.md → emit structured report (NOT files). Failed/blocked W2 roles are excluded from W3 input; inject a `gap_note` listing which roles are missing so the reviewer knows its coverage is incomplete and flags affected cross-role findings as LOW CONFIDENCE:
 
 ```
 ## Conflicts (need user decision)
@@ -383,9 +384,11 @@ conflicts_count / gaps_count / synergies_count / review_confidence
 
 When ui-designer is among selected roles, establish visual direction before Wave 2:
 
-1. If `.workflow/impeccable/PRODUCT.md` missing → run `$maestro-impeccable teach`
-2. If `.workflow/impeccable/DESIGN.md` missing → run `$maestro-impeccable explore`
-3. If both already exist → skip (visual direction already locked)
+1. If both `.workflow/impeccable/PRODUCT.md` and `.workflow/impeccable/DESIGN.md` already exist → skip (visual direction already locked).
+2. Otherwise, **suggest** the missing steps to the user via `request_user_input` (skip gate when `-y/--yes`):
+   - If `PRODUCT.md` missing → suggest: "Run `maestro-impeccable teach` to establish product identity?" Options: `(Recommended) Yes` / `Skip`
+   - If `DESIGN.md` missing → suggest: "Run `maestro-impeccable explore` to establish visual direction?" Options: `(Recommended) Yes` / `Skip`
+3. Only execute the impeccable commands if the user confirms (or `-y` auto mode). If the user skips, set `session.design_degraded=true` and continue — W2 ui-designer agent receives `gap_note="DESIGN.md unavailable"`.
 
 explore generates multi-style HTML prototypes, visual comparison, user selection/mix, and produces DESIGN.md.
 ui-designer agents in Wave 2 then focus on UX/visual design referencing DESIGN.md.

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

@@ -2,7 +2,7 @@
 name: maestro-collab
 description: Use when a question needs cross-verification from multiple CLI tools or diverse analytical perspectives
 argument-hint: "\"<requirement>\" [--tools agy,qwen,claude] [--mode analysis|write] [--rule <template>] [-y]"
-allowed-tools: Read, Write, Edit, Glob, Grep, request_user_input
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
 <purpose>
@@ -68,7 +68,7 @@ $ARGUMENTS — requirement text and optional flags.
 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** — 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. **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)
 </invariants>
@@ -142,8 +142,8 @@ Launch ALL delegate commands simultaneously in parallel:
 
 ```
 // 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 })
+Bash(`maestro delegate "<shared_prompt>" --to agy --mode <mode> [--rule <rule>]`, { run_in_background: true })
+Bash(`maestro delegate "<shared_prompt>" --to claude --mode <mode> [--rule <rule>]`, { run_in_background: true })
 // ... one call per selected tool
 // Execution mapping: @~/.maestro/workflows/shell-exec-protocol.md
 ```
@@ -241,7 +241,7 @@ Generate 3 output files from cross-verify results:
 
 1. Copy outputs to scratchDir
 2. Register CLB artifact in state.json (type: collab, scope: adhoc)
-3. Spec enrichment: for each Locked decision → `maestro spec add arch "<title>" "<content>" --keywords <kw> --description "<summary>"`
+3. **Spec enrichment** (gated): for each Locked decision, display the proposed spec entry. Unless `-y/--yes`, `request_user_input` to confirm before writing. Only confirmed entries execute `maestro spec add arch "<title>" "<content>" --keywords <kw> --description "<summary>"`. Under `-y`, auto-write all Locked decisions.
 4. `update_plan` all steps completed
 5. Display summary:
    ```

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

@@ -34,7 +34,10 @@ $maestro-companion "route what should I do next"
 **Mode detection priority:**
 1. Explicit `before` / `note` / `after` / `route`
 2. Intent text that is not a mode keyword → `route`
-3. No arguments → auto-detect (`git status` has changes → `after`, else → `before`)
+3. No arguments → show `git status` summary and ask user to choose mode via `request_user_input`:
+   - Options: `before` (start new task), `after` (review & promote), `route` (get next command suggestion)
+   - Display working tree status (clean/dirty, changed file count) as context for the choice
+   - NEVER auto-enter `after` mode based on dirty tree — let the user decide
 
 **Flags:**
 - `--task <description>` — Current task description (for targeted knowledge loading and doc title)

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

@@ -44,9 +44,12 @@ $ARGUMENTS — natural language workflow description, or flags.
 
 | Detection | Condition | Handler |
 |-----------|-----------|---------|
-| Resume | `--resume` or existing WFD session | Phase 0: Resume |
+| Resume | `--resume` flag explicitly set | Phase 0: Resume |
 | Edit | `--edit <path>` | Phase 0: Load + Edit |
-| New | Default | Phase 1: Parse |
+| New | Description text provided (non-empty args without flags) | Phase 1: Parse |
+| Empty | No args, no flags | Phase 0: check for existing WFD drafts → if found, ask user via `request_user_input` whether to resume or start new; if none, Phase 1 |
+
+**IMPORTANT**: An existing WFD draft does NOT auto-resume when new description text is provided. New intent always starts Phase 1 fresh. Auto-resume only triggers with explicit `--resume` or empty args with user confirmation.
 
 **Node catalog**: Read `~/.maestro/templates/workflows/specs/node-catalog.md` at Phase 2 (deferred).
 **Template schema**: Read `~/.maestro/templates/workflows/specs/template-schema.md` at Phase 5 (deferred).
@@ -121,7 +124,7 @@ If spec not found, use built-in fallback:
 | `testing` | skill | `quality-test` |
 | `review` | skill | `quality-review` |
 | `brainstorm` | skill | `maestro-brainstorm` |
-| `analysis` | cli | `maestro delegate --role analyze --mode analysis` |
+| `analysis` | cli | `maestro delegate --to claude --mode analysis` |
 | `refactor` | skill | `quality-refactor` |
 | `debug` | skill | `quality-debug` |
 | `spec` | skill | `maestro-blueprint` |

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-execute
 description: Use when a confirmed plan is ready for implementation
-argument-hint: "[-y|--yes] [--concurrency N] [-c|--continue] \"<phase> [--auto-commit] [--method agent|cli] [--dir <path>]\""
+argument-hint: "[-y|--yes] [--concurrency N] [--continue] \"<phase> [--auto-commit] [--method agent|cli] [--dir <path>]\""
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
@@ -67,7 +67,7 @@ All mean: **run convergence criteria check NOW**.
 <context>
 ```bash
 $maestro-execute "3"
-$maestro-execute -c 4 "3 --auto-commit"
+$maestro-execute --concurrency 4 "3 --auto-commit"
 $maestro-execute -y "3 --method cli"
 $maestro-execute "3 --dir .workflow/scratch/quick-fix"
 $maestro-execute --continue "20260318-execute-P3-phase3"
@@ -75,8 +75,8 @@ $maestro-execute --continue "20260318-execute-P3-phase3"
 
 **Flags**:
 - `-y, --yes`: Skip all confirmations (auto mode)
-- `--concurrency N`: Max concurrent agents within each wave (default: 5)
-- `-c, --continue`: Resume existing session
+- `--concurrency N`: Max concurrent agents within each wave (default: 5, no short flag)
+- `--continue`: Resume existing session (no short flag)
 
 **Inner flags** (passed inside quotes):
 - `--auto-commit`: Atomic git commit after each task completion
@@ -178,7 +178,7 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column populated fr
 Parse from $ARGUMENTS:
   AUTO_YES        ← --yes | -y
   continueMode    ← --continue
-  maxConcurrency  ← --concurrency | -c N  (default: 5)
+  maxConcurrency  ← --concurrency N  (default: 5)
   autoCommit      ← --auto-commit
   executionMethod ← --method agent|cli  (default: from config.json)
   scratchDir      ← --dir <path>  (default: null)
@@ -352,7 +352,7 @@ Blocked/failed tasks cascade: mark all downstream dependents as `skipped` with e
 3. **Write verification.json** to plan directory with per-task pass/fail and gap list
 4. **Gate decision**:
    - `overall_pass == true` → proceed to Phase 3
-   - Critical gaps (task criteria all failed) → log warning, mark affected tasks as `needs_retry`
+   - Critical gaps (task criteria all failed) → log warning, mark affected tasks as `failed` with error referencing verification gaps
    - Non-critical gaps → record as `concerns` in verification.json, proceed
 5. **Register VRF artifact**: `{ id: "VRF-{next}", type: "verify", scope, path: verification.json, depends_on: "EXC-{id}" }`
 
@@ -384,7 +384,11 @@ Skip Phase 2.5 when `--skip-verify` flag present or task count == 0.
    - Root cause/workaround → `maestro spec add debug "<title>" "<content>" --keywords ... --description "<summary>"`
    Mark artifact `harvested: true`
 
-6. **Post-task Knowledge Inquiry**: After each task completes, evaluate inquiry triggers:
+6. **Post-task Knowledge Inquiry**: After each task completes, evaluate inquiry triggers.
+
+   **`-y` mode**: Skip all prompts. Instead, append triggered items to `context.md` under a "Suggested Knowledge Captures" section (suggest-only, no spec writes). This keeps `-y` fully non-interactive.
+
+   **Interactive mode**: Use `request_user_input` for each triggered item:
 
    - **Execution deviation**: If task summary mentions approach change, dependency swap, or plan deviation:
      → Prompt: "TASK-{NNN} deviated from the plan. Record as architecture constraint?"
@@ -398,7 +402,6 @@ Skip Phase 2.5 when `--skip-verify` flag present or task count == 0.
      → Prompt: "Design decision detected. Record as a learning?"
      → On confirm: `maestro spec add learning "<decision>" "<rationale>" --keywords ... --description "<summary>" --source execute:{PLAN_DIR}`
 
-   Use `request_user_input` for prompts:
    ```json
    { "questions": [{ "id": "knowledge-capture", "header": "Knowledge Capture", "question": "...", "options": [{ "label": "Yes", "description": "Record to specs" }, { "label": "Skip", "description": "Continue without recording" }] }] }
    ```

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

@@ -58,7 +58,7 @@ Follow '~/.maestro/workflows/fork.md' completely.
 **Fork flow:**
 1. Validate: initialized, roadmap exists, not inside worktree, milestone not forked
 2. Resolve milestone: `state.json.milestones[N-1]`
-3. Create worktree: `git worktree add -b milestone/{slug} .worktrees/m{N}-{slug} HEAD`
+3. Create worktree: `git worktree add -b milestone/{slug} .worktrees/m{N}-{slug} {base_branch}` (where `base_branch` = `--base` flag value or `HEAD` if not specified)
 4. Copy `.workflow/`: shared files + milestone scratch artifacts
 5. Write `worktree-scope.json` with milestone scope
 6. Write scoped `state.json` (this milestone's artifacts only)
@@ -66,8 +66,9 @@ Follow '~/.maestro/workflows/fork.md' completely.
 
 **Sync flow:**
 1. Find worktree from `worktrees.json`
-2. `cd worktree && git merge main`
-3. Re-copy shared files (project.md, roadmap.md, config.json, specs/)
+2. Resolve sync source: use `--base <branch>` if provided, else use `base_branch` from `fork_sessions[]` entry, else default to `main`
+3. `cd worktree && git merge {base_branch}`
+4. Re-copy shared files (project.md, roadmap.md, config.json, specs/)
 
 **Registry: `worktrees.json`** (`.workflow/worktrees.json` in main worktree):
 

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: `shell_exec("maestro delegate ... --role analyze --mode analysis")`.
+- **CLI delegation** for auto mode: `Bash("maestro delegate ... --to claude --mode analysis")`.
 </purpose>
 
 <required_reading>

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

@@ -9,7 +9,7 @@ Configure directory-level write boundaries enforced by the workflow-guard PreToo
 When enabled, Write and Edit tool calls targeting files outside allowed paths are blocked.
 
 Subcommands:
-- **on** -- Enable path guard (defaults to `src/` if no paths configured)
+- **on** -- Enable path guard (defaults to `["src/", "tests/", ".workflow/"]` if no paths configured)
 - **off** -- Disable path guard (preserves path list)
 - **status** -- Show current guard configuration
 - **allow `<path>`** -- Add a directory to the allowed paths list

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

@@ -154,7 +154,7 @@ Layer 1+2 both did not match, but intent is to build/create a specific thing:
 3. Interactive gates respected — teach, shape, craft retain user confirmation gates
 4. status.json before chain steps — session created before any chain step runs
 5. **Quality gate enforcement** — score MUST be parsed from critique/audit output (not assumed). P0 count MUST be extracted. Do NOT skip quality gate steps or mark as "passed" without parsing actual score.
-6. **Chain completion verification** — all non-skipped steps MUST be executed (TodoWrite all completed). status.json MUST be updated with status: "completed" and final scores.
+6. **Chain completion verification** — all non-skipped steps MUST be executed (all tracked as completed in status.json). status.json MUST be updated with status: "completed" and final scores.
 </invariants>
 
 ## Prerequisites
@@ -162,7 +162,7 @@ Layer 1+2 both did not match, but intent is to build/create a specific thing:
 Before reading any command workflow:
 
 1. **Context**: `maestro load --type spec --category ui` → if empty → `maestro impeccable load-context`
-2. **PRODUCT.md**: missing/placeholder (<200 chars / `[TODO]`) → execute teach first, then resume original task
+2. **PRODUCT.md**: missing/placeholder (<200 chars / `[TODO]`) → prompt user via `request_user_input` to confirm running teach first ("PRODUCT.md is missing or incomplete. Run teach to set it up before proceeding?"). On confirm → execute teach, then resume original task. On decline → abort with message. When `-y` → auto-confirm and run teach without prompting.
 3. **Register**: identify brand/product → Read `~/.maestro/workflows/impeccable/{brand|product}.md`
 
 ## Direct Execution
@@ -215,14 +215,14 @@ Before reading any command workflow:
    - Read `~/.maestro/workflows/impeccable/{command}.md` → execute
    - **Step start**: mark current step in_progress
    - **Step done**: mark completed + update status.json (`current_step`, step `status`)
-   - **Step failed**: mark completed (with note) + record reason
+   - **Step failed**: mark as `failed` in status.json + record reason (do NOT mark completed)
 6. **Quality gate** (critique/audit steps):
    - Parse score: critique `**Total** | | **N/40**`, audit `**Total** | | **N/20**`
    - Count `[P0]` / `[P1]` tags
    - Pass: score ≥ threshold AND P0 == 0 → advance
    - Fail: collect suggested commands from findings → execute → re-gate
-   - Max loops exceeded → force advance with warning
-   - Record gate result in current step notes (score, P0/P1 count, pass/fail)
+   - Max loops exceeded → mark step as `degraded` (not completed), record final score + unresolved P0s, log warning, advance to next step
+   - Record gate result in current step notes (score, P0/P1 count, pass/fail/degraded)
 7. Final report: scores + trend + commands executed
 
 ## Resume

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

@@ -123,8 +123,9 @@ Write collected configuration to `.workflow/config.json`.
 Run `Bash("maestro spec init")` to create empty seed files in `.workflow/specs/`.
 
 If project state is **code** (existing source files detected in Step 2):
-- Auto-trigger `$spec-setup` to scan codebase and populate specs with detected conventions
-- This runs unconditionally for `code` state — existing source means conventions can be extracted
+- Suggest `$spec-setup` to scan codebase and populate specs with detected conventions
+- Ask user via `request_user_input`: "Source files detected. Run spec-setup to scan codebase conventions?" with options: "Yes, scan now (Recommended)" / "No, skip for now"
+- Only run `$spec-setup` if user confirms
 
 If project state is **empty** (greenfield, no source files found in Step 2):
 - Skip spec-setup entirely — no code to scan