maestro-flow 0.5.41 → 0.5.43

package/.claude/commands/odyssey-debug.md

@@ -1,7 +1,7 @@
 ---
 name: odyssey-debug
 description: Long-running debug cycle — archaeology, diagnosis, fix, confirmation, generalization, discovery, and knowledge persistence
-argument-hint: "<issue> [--skip-fix] [--skip-generalize] [--auto] [-y] [-c] [--heartbeat]"
+argument-hint: "<issue> [--template <name>] [--skip-fix] [--skip-generalize] [--auto] [-y] [-c] [--heartbeat]"
 allowed-tools:
   - Read
   - Write
@@ -237,6 +237,7 @@ All sibling bugs fixed or issued — no leftovers.
 | E001 | error | No issue, no session | Provide issue or -c |
 | W001 | warning | No relevant git history | Proceed |
 | W002 | warning | 3 retries exhausted | INCONCLUSIVE |
+| W003 | warning | Partial archaeology agent failure (Timeline or Blame) | Proceed with available results, log failed agent |
 | W005 | warning | Pending decisions | Filter evidence phase=decision |
 | W006 | warning | No CLI tools | Skip explore |
 </error_codes>

package/.claude/commands/odyssey-improve.md

@@ -1,7 +1,7 @@
 ---
 name: odyssey-improve
 description: Long-running codebase improvement cycle — multi-dimensional audit, deep diagnosis, targeted fix, verify, generalize, and engineering knowledge persistence
-argument-hint: "<target> [--dimensions <list>] [--skip-fix] [--skip-generalize] [--auto] [-y] [-c] [--heartbeat]"
+argument-hint: "<target> [--dimensions <list>] [--fix-threshold <severity>] [--skip-fix] [--skip-generalize] [--auto] [-y] [-c] [--heartbeat]"
 allowed-tools:
   - Read
   - Write
@@ -189,7 +189,7 @@ Commit: `"odyssey-improve({slug}): DIAGNOSE — root cause analysis"`
 `retries++`. < 3: `maestro delegate --role analyze`, new hypotheses, → S_DIAGNOSE. >= 3: Normal → AskUserQuestion | `-y` → INCONCLUSIVE → S_RECORD.
 
 ### A_FIX
-1. Exhaustive fix: ALL diagnosed issues by severity tier (critical → high → medium → low within fix_threshold), one dimension at a time. After each tier, re-verify — new findings append to current tier.
+1. Exhaustive fix: ALL diagnosed issues by severity tier (critical → high → medium → low within fix_threshold), one dimension at a time. After each tier, re-verify **current tier's dimension only** (not all dimensions) — new findings at same or higher severity append to current tier. Cross-dimension regression checks run once at S_VERIFY after all tiers complete.
 2. For each fix: implement → evidence phase=fix
 3. Normal: AskUserQuestion per-fix confirmation | `-y`: auto-proceed, record `deferred`
 

package/.claude/commands/odyssey-planex.md

@@ -1,7 +1,7 @@
 ---
 name: odyssey-planex
 description: Requirement-driven iterative cycle — plan, execute, strict verify, fix loop until acceptance criteria met
-argument-hint: "<requirement> [--max-iterations N] [--skip-generalize] [--auto] [--method agent|cli|auto] [--executor <tool>] [--skip-verify] [--heartbeat] [-y] [-c]"
+argument-hint: "<requirement> [--template <name>] [--max-iterations N] [--skip-generalize] [--auto] [--method agent|cli|auto] [--executor <tool>] [--skip-verify] [--heartbeat] [-y] [-c]"
 allowed-tools:
   - Read
   - Write
@@ -108,7 +108,7 @@ Applies to: **S_PLAN, S_VERIFY, S_GENERALIZE**. Logic in base.
 <state_machine>
 
 <states>
-S_INTAKE → S_PLAN → S_EXECUTE → S_VERIFY → S_GENERALIZE → S_DISCOVER → S_RECORD → END
+S_INTAKE → S_PLAN → S_EXECUTE → S_VERIFY → S_FIX → S_GENERALIZE → S_DISCOVER → S_RECORD → END
 </states>
 
 <transitions>
@@ -122,7 +122,7 @@ S_EXECUTE → S_VERIFY
 S_VERIFY → S_GENERALIZE   : all passed AND NOT skip_generalize
 S_VERIFY → S_RECORD       : all passed AND skip_generalize
 S_VERIFY → S_FIX          : some failed AND iteration < max
-S_VERIFY → S_PLAN         : fundamental plan flaw → cross_phase_loops++ (replan)
+S_VERIFY → S_PLAN         : fundamental plan flaw → cross_phase_loops++ (replan). **Criteria preservation:** acceptance_criteria[] statuses are preserved; only plan.tasks[] are regenerated. Previously passed criteria retain `passed` status; failed criteria reset to `pending` for re-verification after new plan execution.
 S_VERIFY → S_RECORD       : some failed AND iteration >= max (escalate)
 
 S_FIX → S_VERIFY (loop)
@@ -295,7 +295,7 @@ Iron gate — every acceptance criterion checked objectively.
 |--------|--------|
 | `test` | Run relevant tests, check pass/fail |
 | `grep` | Grep for expected pattern |
-| `cli-review` | `maestro delegate --role review --mode analysis` with criterion as focus |
+| `cli-review` | `maestro delegate "PURPOSE: Verify criterion {criterion_id}: {criterion}\nTASK: Read implementation code \| Check behavior matches criterion \| Report pass/fail with file:line evidence\nMODE: analysis\nCONTEXT: @{relevant_files}\nEXPECTED: JSON {criterion_id, status: passed\|failed, evidence: [{file, line, detail}]}" --role review --mode analysis` |
 | `manual` | Normal: AskUserQuestion / `-y`: record `deferred` |
 
 Record per criterion: `{"phase":"verification","type":"criterion-check","criterion_id":"AC1","method":"","result":"passed|failed","evidence":"","iteration":N}`. Update acceptance_criteria[].status. Append to iterations[].
@@ -312,11 +312,12 @@ Commit: `"odyssey-planex({slug}): VERIFY — acceptance check"`
 2. For each failed criterion: diagnose gap → targeted code fix
 3. CLI fix review (optional):
    ```bash
-   maestro delegate "PURPOSE: Review fixes for failing criteria
-   TASK: Check fix correctness | Verify no regressions on passing criteria
+   maestro delegate "PURPOSE: Review fixes for failing criteria; success = no regressions and fixes correct
+   TASK: Check fix correctness | Verify no regressions on passing criteria | Report verdict with file:line evidence
    MODE: analysis
    CONTEXT: @{modified_files} | Passing: {passing} | Fixed: {fixed}
-   EXPECTED: JSON {verdict, regression_risk, concerns}
+   EXPECTED: JSON {verdict: passed|concerns_found, regression_risk: low|medium|high, concerns: [{criterion_id, file, line, description}]}
+   CONSTRAINTS: Read-only | Check ALL passing criteria for regressions
    " --role review --mode analysis
    ```
 4. Append evidence (fix), update understanding.md section 5 → S_VERIFY

package/.claude/commands/odyssey-review-test-fix.md

@@ -133,6 +133,8 @@ Glob latest session → read `session.json` → jump to `current_state`.
 ### A_ARCHAEOLOGY
 2 parallel Agents: Timeline (`git log --oneline -20 -- {files}`) + Blame (top 3 files `git blame -L {region}`). Evidence phase=archaeology.
 
+**Error handling:** If any archaeology agent fails (Timeline or Blame), log W003 and proceed with available results. If delegate fails, log W003 and proceed with local agent results only.
+
 `maestro delegate --role analyze --mode analysis` (`run_in_background: true`):
 - PURPOSE: Review recent modifications related to {target}
 - EXPECTED: JSON [{commit_sha, risk_level, analysis, could_cause_issue, explanation}]
@@ -170,7 +172,7 @@ for tier in [critical, high, medium, low].filter(>= threshold):
 ```
 
 Normal: AskUserQuestion per tier. `-y`: auto-fix all.
-Remaining > 0 → retry (no max_loops limit). Unchanged 2 rounds → classify each individually.
+Remaining > 0 → retry (max_fix_rounds = 5). Unchanged 2 rounds → classify each individually. After 5 rounds with remaining > 0 → escalate: Normal: AskUserQuestion (continue/accept/reclassify) | `-y`: classify remaining as `deferred`, proceed.
 Blanket "pre-existing" forbidden.
 
 Commit per tier: `"odyssey-review({slug}): FIX-{tier} — {N} items fixed"`
@@ -235,6 +237,7 @@ Every finding must have action (fix/issue/decision). Decision pending must AskUs
 | E002 | error | Target path not found | Check path |
 | W001 | warning | No git history | Proceed |
 | W002 | warning | Some dimension agents failed | Partial coverage |
+| W003 | warning | Archaeology agent or delegate failure | Proceed with available results |
 </error_codes>
 
 <success_criteria>

package/.claude/commands/odyssey-ui.md

@@ -1,7 +1,7 @@
 ---
 name: odyssey-ui
 description: Long-running UI optimization cycle — visual survey, multi-dimensional audit, divergent exploration, fix, verify, generalize, and design knowledge persistence
-argument-hint: "<target> [--dimensions <list>] [--skip-fix] [--skip-generalize] [--auto] [-y] [-c] [--heartbeat]"
+argument-hint: "<target> [--dimensions <list>] [--fix-threshold <severity>] [--skip-fix] [--skip-generalize] [--auto] [-y] [-c] [--heartbeat]"
 allowed-tools:
   - Read
   - Write
@@ -136,7 +136,7 @@ Glob latest session → read `session.json` → jump to `current_state`.
 ### A_SURVEY
 1. **Design system inventory**: Scan for design tokens, CSS variables, theme imports
 2. **Current state analysis**: Styling patterns, layout strategy, component hierarchy
-3. **CLI-assisted**: `maestro delegate --role analyze` — survey tokens, spacing, typography, hierarchy, consistency
+3. **CLI-assisted**: `maestro delegate --role analyze --mode analysis` — survey tokens, spacing, typography, hierarchy, consistency
 4. Append evidence phase=survey. Update section 2. Mark G1.
 
 Commit: `"odyssey-ui({slug}): SURVEY — design token inventory"`
@@ -167,7 +167,7 @@ Goes beyond defect fixing — "what would make this delightful?"
 
 Each returns `[{idea, category (polish|delight), impact, effort, description, inspiration}]`
 
-**Step 2 — CLI-assisted**: `maestro delegate --role analyze` — polish opportunities, micro-interactions, visual rhythm, delight moments
+**Step 2 — CLI-assisted**: `maestro delegate --role analyze --mode analysis` — polish opportunities, micro-interactions, visual rhythm, delight moments
 
 **Step 3 — Consolidate**: Merge audit findings + divergent ideas → prioritized list (severity x impact x effort).
 Append evidence phase=diverge. Update section 4. Mark G3.
@@ -184,7 +184,7 @@ Commit: `"odyssey-ui({slug}): FIX — implement improvements"`
 
 ### A_VERIFY
 1. Run tests (lint, unit, visual regression)
-2. `maestro delegate --role review` — visual correctness, interaction states, accessibility, responsive
+2. `maestro delegate --role review --mode analysis` — visual correctness, interaction states, accessibility, responsive
 3. `needs_rework` → S_FIX. `verified` → mark G4. Update section 5, write `confirmation`.
 
 Commit: `"odyssey-ui({slug}): VERIFY — visual verification"`

package/.claude/commands/quality-auto-test.md

@@ -25,6 +25,8 @@ Layers L0→L3 sequential (fail-fast), scenarios within layer parallel. `--max-i
 Phase or task: $ARGUMENTS (required — phase number)
 
 **Flags:**
+- `-c N` — Resume from iteration N of an existing session (skips setup, resumes from last checkpoint)
+- `-y` — Skip confirmation prompts for artifact registration and issue creation
 - `--max-iter N` — Maximum outer iterations (default: 5). Set to 1 for single-pass generation only.
 - `--layer L` — Start from or restrict to specific layer (L0|L1|L2|L3)
 - `--dry-run` — Generate test plan only, do not execute
@@ -90,6 +92,14 @@ Follow '~/.maestro/workflows/auto-test.md' completely.
 - Generate regression test scenarios from confirmed root causes, marked `source: "debug_root_cause"`
 
 **Register artifact on completion:**
+
+Unless `-y` flag is set, confirm before writing:
+```
+AskUserQuestion("Register auto-test artifact TST-{NNN} in state.json? (yes/no)")
+→ yes: proceed with write
+→ no: skip registration, continue to next-step routing
+```
+
 ```
 Append to state.json.artifacts[]:
 {
@@ -147,7 +157,7 @@ Append to state.json.artifacts[]:
 - [ ] report.json includes confidence section
 - [ ] index.json updated with auto_test section
 - [ ] If spec source: traceability matrix built, traceability.md written
-- [ ] If failures: issues auto-created in issues.jsonl
+- [ ] If failures: issues created in issues.jsonl (confirmed by user unless `-y`)
 - [ ] If gap source: validation.json gaps updated (MISSING→COVERED)
 - [ ] Next step routed based on convergence status
 </success_criteria>

package/.claude/commands/quality-debug.md

@@ -1,7 +1,7 @@
 ---
 name: quality-debug
 description: Use when bugs, test failures, or unexpected behavior need systematic root cause investigation
-argument-hint: "[issue description] [--from-uat <phase>] [--parallel]"
+argument-hint: "[issue description] [-c] [--from-uat <phase>] [--parallel]"
 allowed-tools:
   - Read
   - Write
@@ -73,6 +73,14 @@ Follow '~/.maestro/workflows/debug.md' completely.
 - BLOCKED if inconclusive: resume session or escalate.
 
 **Register artifact on completion (phase-scoped only):**
+
+Confirm before writing:
+```
+AskUserQuestion("Register debug artifact DBG-{NNN} in state.json? (yes/no)")
+→ yes: proceed with write
+→ no: skip registration, continue to knowledge inquiry
+```
+
 ```
 Append to state.json.artifacts[]:
 {
@@ -92,13 +100,19 @@ Append to state.json.artifacts[]:
 
 ### Post-debug Knowledge Inquiry
 
+For each matching condition, ask the user explicitly:
+
 | Condition | Ask | Route |
 |-----------|-----|-------|
 | Recurring root cause pattern (seen in prior debug) | "Document in debug-notes.md?" | spec-add debug |
 | Non-obvious fix / workaround | "Record as learning?" | spec-add learning |
 | Root cause = architectural boundary violation | "Update architecture-constraints.md?" | spec-add arch |
 
-On confirm → `Skill("spec-add", "<category> <content> --description \"<summary>\"")`.
+```
+AskUserQuestion("<ask text> (yes/no)")
+→ yes: Skill("spec-add", "<category> <content> --description \"<summary>\"")
+→ no: skip this entry, proceed to next condition or completion
+```
 
 </execution>
 

package/.claude/commands/quality-retrospective.md

@@ -30,7 +30,14 @@ Post-execution retrospective (复盘): four parallel lenses (technical/process/q
 <context>
 Arguments: $ARGUMENTS
 
-Modes (scan/single/range/all), flags (--lens, --no-route, --compare, -y), and storage paths defined in workflow retrospective.md Argument Shape and Stages 1-7.
+**Flags:**
+- `-y` — Skip confirmation prompts for external writes (issues.jsonl, spec entries, knowhow capture)
+- `--no-route` — Skip routing stage (produce retrospective files only, no spec/issue/knowhow writes)
+- `--compare N` — Compare current phase retrospective against phase N (requires single phase argument)
+- `--all` — Run retrospective on all completed phases that lack retrospective.json
+- `--lens <name>` — Restrict to specific lens (technical|process|quality|decision); default: all four
+
+Modes (scan/single/range/all) and storage paths defined in workflow retrospective.md Argument Shape and Stages 1-7.
 </context>
 
 <execution>
@@ -55,6 +62,7 @@ Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order.
 - REQUIRED: `retrospective.md` written (human-readable).
 - REQUIRED: Issue rows match canonical `issues.jsonl` schema (status "open", full fields).
 - REQUIRED: Note tips routed via `Skill({ skill: "manage-knowhow-capture", args: "tip ..." })`.
+- REQUIRED: Unless `-y` flag is set, confirm before each external write (issues.jsonl append, spec-entry append, knowhow-capture). With `-y`, skip all confirmation prompts.
 - BLOCKED if routing incomplete: finish all write operations before reporting.
 
 ### Execution Constraints

package/.claude/commands/quality-review.md

@@ -80,6 +80,14 @@ Follow '~/.maestro/workflows/review.md' completely.
 - `REVIEW_DIR/review.json` — findings, severity distribution, verdict
 
 **Register artifact on completion:**
+
+Confirm before writing state.json and issues.jsonl:
+```
+AskUserQuestion("Register review artifact REV-{NNN} in state.json and create {N} issues in issues.jsonl? (yes/no)")
+→ yes: proceed with both writes
+→ no: skip registration and issue creation, continue to completion
+```
+
 ```
 Append to state.json.artifacts[]:
 {

package/.claude/commands/quality-sync.md

@@ -42,7 +42,7 @@ Follow '~/.maestro/workflows/sync.md' completely.
 
 **GATE 3: Refresh → Completion**
 - REQUIRED: `.workflow/codebase/` docs refreshed for affected components.
-- REQUIRED: state.json updated with sync timestamp.
+- REQUIRED: If `--dry-run` is set, skip state.json write and report what would change. Otherwise, update state.json with sync timestamp.
 - BLOCKED if missing: do not report completion without updated docs.
 </execution>
 
@@ -80,7 +80,7 @@ maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
 </error_codes>
 
 <success_criteria>
-- [ ] state.json updated with current sync timestamp
+- [ ] state.json updated with current sync timestamp (skipped if `--dry-run`)
 - [ ] Codebase docs refreshed for all affected components
 - [ ] doc-index.json reflects current file state
 - [ ] Changes tracked and logged

package/.claude/commands/quality-test.md

@@ -90,6 +90,14 @@ Follow '~/.maestro/workflows/test.md' completely.
 - Generate regression test scenarios from confirmed root causes, marked `source: "debug_root_cause"`
 
 **Register artifact on completion:**
+
+Confirm before writing:
+```
+AskUserQuestion("Register test artifact TST-{NNN} in state.json? (yes/no)")
+→ yes: proceed with write
+→ no: skip registration, continue to completion
+```
+
 ```
 Append to state.json.artifacts[]:
 {
@@ -163,7 +171,7 @@ maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
 - [ ] Pressure pass completed if > 80% pass rate
 - [ ] Confidence summary appended to uat.md
 - [ ] index.json uat fields updated
-- [ ] If issues: parallel debug agents spawned per gap cluster
+- [ ] If issues: confirm with user before spawning parallel debug agents per gap cluster
 - [ ] Gaps updated with root_cause, fix_direction, affected_files
 - [ ] Gap-fix loop triggered if --auto-fix (max 2 iterations)
 - [ ] Next step routed (phase-transition if pass, verify if auto-fix success, debug --from-uat if issues, test-gen if low coverage)

package/.claude/commands/security-audit.md

@@ -98,10 +98,12 @@ Check for:
 
 **Phase 4: Secrets Detection** (standard + deep)
 
-```bash
-# Current codebase
-grep -rn --include="*.ts" --include="*.js" --include="*.json" --include="*.env*" \
-  -E "(password|secret|api.?key|token|credential).*=.*['\"][^'\"]{8,}" . || true
+```
+Grep({
+  pattern: "(password|secret|api.?key|token|credential).*=.*['\"][^'\"]{8,}",
+  glob: "*.{ts,js,json,env*}",
+  output_mode: "content"
+})
 ```
 
 Check `.env.example` for leaked values. Check `.gitignore` for missing `.env` patterns.
@@ -159,6 +161,14 @@ Summary: {total} findings ({critical} critical, {high} high, {medium} medium, {l
 ```
 
 **Register artifact on completion:**
+
+Confirm before writing:
+```
+AskUserQuestion("Register security-audit artifact RVW-{NNN} in state.json? (yes/no)")
+→ yes: proceed with write
+→ no: skip registration, continue to completion
+```
+
 ```
 Append to state.json.artifacts[]:
 {

package/.claude/commands/spec-add.md

@@ -1,13 +1,14 @@
 ---
 name: spec-add
 description: Add spec entry by category with role tagging
-argument-hint: "[--scope project|global|team|personal] <category> <content>"
+argument-hint: "[--scope project|global|team|personal] [-y] <category> <content>"
 allowed-tools:
   - Read
   - Write
   - Bash
   - Glob
   - Grep
+  - AskUserQuestion
 ---
 <purpose>
 Add `<spec-entry>` to specs by category. 4 scopes: project (default), global, team, personal.
@@ -45,6 +46,8 @@ Scope-to-directory mapping, category-to-file mapping, and entry format defined i
 
 <execution>
 Follow '~/.maestro/workflows/specs-add.md' completely.
+
+**Confirmation gate**: Unless -y flag is passed, after formatting the `<spec-entry>` block but before appending to the target file, AskUserQuestion showing the formatted entry, target file path, and scope. Proceed only on user confirm.
 </execution>
 
 <error_codes>
@@ -52,7 +55,7 @@ Follow '~/.maestro/workflows/specs-add.md' completely.
 |------|----------|-------------|-------|
 | E001 | fatal | Category and content are both required | parse_input |
 | E002 | fatal | Specs directory not initialized -- run `maestro spec init --scope <scope>` | validate_entry |
-| E003 | fatal | Invalid category -- must be one of: coding, arch, quality, debug, test, review, learning, tools, ui | parse_input |
+| E003 | fatal | Invalid category -- must be one of: coding, arch, quality, debug, test, review, learning, ui | parse_input |
 | E004 | fatal | Invalid scope -- must be one of: project, global, team, personal | parse_input |
 | E005 | fatal | Personal scope requires uid -- use `--uid` or run `maestro collab join` first | parse_input |
 </error_codes>

package/.claude/commands/spec-load.md

@@ -27,7 +27,7 @@ $ARGUMENTS -- optional flags and keyword
   - `global`: global + project merged (~/.maestro/specs/ + .workflow/specs/)
   - `team`: project + team shared (.workflow/collab/specs/)
   - `personal`: project + team + personal (requires uid)
-- `--category <category>` — Load by category: primary category doc (full) + cross-file entries with matching category attr. Categories: coding, arch, test, review, debug, learning, ui.
+- `--category <category>` — Load by category: primary category doc (full) + cross-file entries with matching category attr. Categories: coding, arch, quality, test, review, debug, learning, ui.
 - `--keyword <word>` — Filter by keyword within entries
 
 **File → Primary Category mapping:**

package/.claude/commands/spec-remove.md

@@ -1,7 +1,7 @@
 ---
 name: spec-remove
 description: Remove spec entry by ID
-argument-hint: "<entry-id> [--cascade]"
+argument-hint: "<entry-id> [--cascade] [-y]"
 allowed-tools:
   - Read
   - Write

package/.claude/commands/spec-setup.md

@@ -8,6 +8,7 @@ allowed-tools:
   - Bash
   - Glob
   - Grep
+  - AskUserQuestion
 ---
 <purpose>
 Initialize `.workflow/specs/` by scanning codebase for conventions. Core files always created; optional files created when signals detected. Also generates recipe knowhow for detected workflows.
@@ -27,6 +28,8 @@ $ARGUMENTS (no arguments expected)
 
 <execution>
 Follow '~/.maestro/workflows/specs-setup.md' completely.
+
+**Confirmation gate**: After scanning codebase and determining which files/directories will be created (core specs, optional specs, recipe knowhow), AskUserQuestion showing the full list of files to create with their categories and detected signals. Proceed only on user confirm.
 </execution>
 
 <error_codes>