maestro-flow 0.4.25 → 0.5.0

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

@@ -177,7 +177,7 @@ S_TICK_EXEC: Entry: A_EXEC_STEP
   → S_HANDLE_FAIL   WHEN: ralph complete with NEEDS_RETRY|BLOCKED
 
 S_TICK_DECISION: (gate 名取自 `step.decision`)
-  → S_TICK_APPLY    WHEN: quality-gate (post-verify, post-business-test, post-review, post-test)
+  → S_TICK_APPLY    WHEN: quality-gate (post-execute, post-business-test, post-review, post-test)
                      DO: A_DELEGATE_EVALUATE
   → S_TICK_APPLY    WHEN: goal-gate (post-goal-audit)
                      DO: A_GOAL_AUDIT_EVALUATE
@@ -299,15 +299,12 @@ resolve_milestone(phase_number):
 | phase 已存在 + 无任何 artifact | `analyze` |
 | phase 已存在 + 最新 artifact = analyze | `plan` |
 | phase 已存在 + 最新 artifact = plan | `execute` |
-| phase 已存在 + 最新 artifact = execute | `verify` |
-| phase 已存在 + 最新 artifact = verify | → refine from result files |
+| phase 已存在 + 最新 artifact = execute | `review` |
 
-**Refine from verify results:**
+**Refine from review results:**
 
 | Condition | Position |
 |-----------|----------|
-| verification.json: passed==false or gaps[] | `verify-failed` |
-| passed==true, no review.json | `business-test` |
 | review.json: verdict=="BLOCK" | `review-failed` |
 | review.json: verdict!="BLOCK" | `test` |
 | uat.md: all passed | `milestone-audit` |
@@ -332,7 +329,7 @@ resolve_milestone(phase_number):
 
 读 `session.quality_mode_override`（CLI `--quality`），无则按规则推断：
 
-| Condition | Mode | Pipeline (verify 之后) |
+| Condition | Mode | Pipeline (execute 之后) |
 |-----------|------|-------------------------|
 | Has `specs/REQ-*.md` + 当前 phase 业务范围明确 | `full` | business-test → review → test-gen → test |
 | Default | `standard` | review → test-gen (当 coverage<80%) → test |
@@ -414,8 +411,7 @@ narrow → derive defaults from intent + codebase, skip questions.
 | roadmap | `maestro-roadmap --from analyze:{analyze_macro_id}` | *(same)* | — | all |
 | analyze | `maestro-analyze {phase}` | `maestro-analyze` | — | all |
 | plan | `maestro-plan {phase}` *(scope=phase)* / `maestro-plan --from analyze:{analyze_macro_id}` *(scope=standalone)* / `maestro-plan --from blueprint:{blueprint_id}` *(scope=standalone)* | `maestro-plan` | — | all |
-| execute | `maestro-execute {phase}` | `maestro-execute` | — | all |
-| verify | `maestro-verify {phase}` | `maestro-verify` | `post-verify` | all |
+| execute | `maestro-execute {phase}` | `maestro-execute` | `post-execute` | all |
 | business-test | `quality-auto-test {phase}` | `quality-auto-test` | `post-business-test` | full only |
 | review | `quality-review {phase}` | `quality-review` | `post-review` | all (quick: append `--tier quick`) |
 | test-gen | `quality-auto-test {phase}` | `quality-auto-test` | — | full / standard if coverage<80% |
@@ -544,7 +540,7 @@ Write enriched args back to status.json.
 3. Map result files:
    | Decision | Files |
    |----------|-------|
-   | post-verify | verification.json |
+   | post-execute | verification.json |
    | post-business-test | .tests/auto-test/report.json |
    | post-review | review.json |
    | post-test | uat.md, .tests/test-results.json |
@@ -717,8 +713,8 @@ Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。/maestro
 
      [✓] 0.   maestro-plan 1            [global]
      [✓] 1.   maestro-execute 1         [project]
-     [✓] 2.   maestro-verify 1          [global]
-     [✓] 3. ◆ post-verify               [decision]
+     [✓] 2.   quality-review 1           [global]
+     [✓] 3. ◆ post-review               [decision]
      ...
    ============================================================
    ```
@@ -756,7 +752,7 @@ Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。/maestro
     "index": 0,
     "skill": "",                   // 执行 step 有值；decision 节点为空字符串/null
     "args": "",
-    "stage": "",                   // brainstorm|blueprint|init|analyze-macro|roadmap|analyze|plan|execute|verify|...
+    "stage": "",                   // brainstorm|blueprint|init|analyze-macro|roadmap|analyze|plan|execute|...
     "scope": null,                 // "phase"|"standalone"|"milestone"|null（plan 等需要）
     "decision": null,              // null = 执行 step；非 null = decision step (值为 gate 名)
     "retry_count": 0,              // decision step
@@ -793,13 +789,12 @@ Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。/maestro
 
 插入的执行 step 按 A_BUILD_STEPS 规则 9 解析 `command_path` + `command_scope`；`decision:*` 条目为 decision 节点。
 
-**post-verify:**
+**post-execute:**
 ```
 quality-debug "{gap_summary}"
 maestro-plan --gaps {phase}
 maestro-execute {phase}
-maestro-verify {phase}
-decision:post-verify {retry+1}
+decision:post-execute {retry+1}
 ```
 
 **post-business-test:**
@@ -807,8 +802,7 @@ decision:post-verify {retry+1}
 quality-debug --from-business-test "{gap_summary}"
 maestro-plan --gaps {phase}
 maestro-execute {phase}
-maestro-verify {phase}
-decision:post-verify {retry: 0}
+decision:post-execute {retry: 0}
 quality-auto-test {phase}
 decision:post-business-test {retry+1}
 ```
@@ -827,8 +821,7 @@ decision:post-review {retry+1}
 quality-debug --from-uat "{gap_summary}"
 maestro-plan --gaps {phase}
 maestro-execute {phase}
-maestro-verify {phase}
-decision:post-verify {retry: 0}
+decision:post-execute {retry: 0}
 quality-auto-test {phase}
 decision:post-business-test {retry: 0}
 quality-review {phase}
@@ -843,7 +836,6 @@ decision:post-test {retry+1}
 # for each unmet sub-goal G{n}, scoped to target_phase:
 maestro-plan --gaps {target_phase} "G{n}: {gap}"     [goal_ref: G{n}]
 maestro-execute {target_phase}                       [goal_ref: G{n}]
-maestro-verify {target_phase}                        [goal_ref: G{n}]
 # after all unmet groups inserted:
 decision:post-goal-audit {retry+1}
 ```

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

@@ -196,8 +196,8 @@ Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。/maestro
 
      [✓] 0.   maestro-plan 1            [global]
      [✓] 1.   maestro-execute 1         [project]
-     [✓] 2.   maestro-verify 1          [global]
-     [✓] 3. ◆ post-verify               [decision]
+     [✓] 2.   quality-review 1           [global]
+     [✓] 3. ◆ post-review               [decision]
      ...
    ============================================================
    ```

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

@@ -35,7 +35,7 @@ $ARGUMENTS -- requirement/idea text or @file reference, plus optional flags.
 Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `--revise`, `--review`, `-c`, or input is already specific (clear requirement + mode).
 
 - 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`, existing `roadmap.md`, `project.md`, `maestro spec load`, `maestro wiki search`, Glob/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.
+- Search-first when uncertain: before asking, resolve via `state.json`, existing `roadmap.md`, `project.md`, `maestro spec load`, `maestro search`, Glob/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.
 - Writeback cadence: each settled decision is immediately appended/updated in the `Roadmap Decisions` section at the top of `.workflow/roadmap.md` (create the section if absent). Do NOT batch writeback to the end — partial decisions must already be on disk before the next question.
 - Walk the decision dependency tree strictly: mode → requirement scope → decomposition strategy → phase dependencies/order. Do not open the next branch until the current one is settled.
 - Scope guard: only decide the shape of the roadmap. Do not pre-resolve intra-phase task breakdown — that belongs to `plan`.
@@ -70,7 +70,10 @@ Wave 1: 3 analysis rows (parallel). Wave 2: 1 assembly row.
 2. **CSV is source of truth**: Master tasks.csv holds all state
 3. **Context propagation**: prev_context from master CSV, not memory
 4. **Discovery board append-only**: Never modify/delete discoveries.ndjson
-5. **Graceful degradation**: Wave 1 fails -> Wave 2 proceeds with seed input only
+5. **Graceful degradation**: Wave 1 fails -> Wave 2 proceeds with seed input only. When degradation activates, flag downstream outputs as LOW CONFIDENCE.
+6. **Invariant violation = BLOCK** — violating any invariant above blocks the current operation.
+7. **Requirement mapping completeness** — every Active requirement from project.md MUST be mapped to exactly one phase. No circular dependencies in phase ordering.
+8. **Artifact verification before completion** — .workflow/roadmap.md MUST exist with Milestone > Phase hierarchy and progress table. Artifact MUST be registered in state.json. If missing: DO NOT report completion.
 </invariants>
 
 <state_machine>

package/.codex/skills/maestro-tools-register/SKILL.md

@@ -72,7 +72,7 @@ Parse $ARGUMENTS to determine mode:
 - Analyze improvement points (step splitting, prerequisites, error handling)
 
 **Promote mode** (existing knowhow → tool):
-- Locate document: `maestro wiki list --keyword <name>` or by path in `.workflow/knowhow/`
+- Locate document: `maestro search "<name>" --type knowhow` or by path in `.workflow/knowhow/`
 - Read document, verify it contains actionable steps (numbered list or ## Steps section)
 - If no actionable steps, suggest extract mode instead
 - Determine category (Step 3) and summary ("Use when ...")

package/.codex/skills/maestro-ui-codify/SKILL.md

@@ -90,9 +90,9 @@ id,wave,title,description,agent_type,deps
 | `agent_type` | Input | Agent type: discover/extract-style/extract-animation/extract-layout/package/knowhow |
 | `deps` | Input | Semicolon-separated dependency task IDs |
 | `result_status` | Output | `completed` / `failed` (returned via output_schema) |
-| `findings` | Output | Key findings summary (max 500 chars) |
-| `output_path` | Output | Path to generated artifact |
-| `error` | Output | Error message if failed |
+| `findings` | Output | Key findings summary (max 500 chars, via output_schema) |
+| `output_path` | Output | Path to generated artifact (via output_schema) |
+| `error` | Output | Error message if failed (via output_schema) |
 
 ### Session Structure
 
@@ -115,6 +115,9 @@ id,wave,title,description,agent_type,deps
 6. **Idempotent Package**: --overwrite required to replace existing package directory
 7. **Cleanup Temp Files**: Remove wave-{N}.csv after results merged, remove temp workspace after Wave 4
 8. **DO NOT STOP**: Continuous execution until all waves complete
+
+### Artifact Verification
+Before reporting completion, verify: design-tokens.json, layout-templates.json, preview.html, preview.css, knowhow-manifest.json all exist. If any missing: DO NOT report completion.
 </invariants>
 
 <execution>
@@ -392,7 +395,7 @@ Open preview:
   file://{absolute_path}/preview.html
 
 Next steps:
-  maestro wiki list --category coding    # Browse by role
+  maestro search --category coding    # Browse by role
   maestro spec load --keyword {package_name}    # Load related specs
 ```
 

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

@@ -1,169 +1,74 @@
 ---
 name: maestro-update
 description: Detect version, preview changes, apply workflow upgrades
-argument-hint: "[--dry-run] [--force]"
+argument-hint: "[--dry-run] [--force] [--setup-only]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 <purpose>
-Detect the current `.workflow/` schema version, show available migrations, and interactively apply them step-by-step. Uses a migration registry that supports incremental version upgrades (e.g., 1.0 → 2.0 → 3.0).
+Version router — detect current version, run schema migration to latest, then follow the version-specific smart upgrade workflow.
 
-Each migration step is previewed before execution. The user confirms each step in a loop.
+Migration scripts live in two layers:
+- **Schema** (`src/migrations/`): code-level state.json transforms, auto-chained by registry
+- **Workflow** (`~/.maestro/workflows/updates/`): version-specific upgrade guides with environment setup
+
+Schema migrations handle the mechanical version bump. Workflow docs handle the smart part — what the user needs to know, configure, or verify for that version. The router runs schema first, then loads the matching workflow doc.
 </purpose>
 
+<required_reading>
+@~/.maestro/workflows/updates/README.md
+</required_reading>
+
 <context>
 $ARGUMENTS — optional flags.
 
 **Flags:**
 - `--dry-run` -- Preview migration plan without executing
-- `--force` -- Skip confirmation prompts (apply all pending migrations)
-
-**Migration registry:** `src/migrations/`
-- Each migration is a standalone file (e.g., `v1-to-v2.ts`) exporting a `MigrationDef`
-- All migrations are registered via `src/migrations/index.ts`
-- Registry auto-chains: detects current version → walks chain → applies in order
-- To add a new migration: create `src/migrations/v{N}-to-v{N+1}.ts`, register in `index.ts`
-
-**CLI runner:** `src/migrations/run.ts`
-- Executable entrypoint: `npx tsx src/migrations/run.ts [root] [--dry-run] [--force] [--json]`
-- Outputs JSON (with `--json`) or human-readable text
+- `--force` -- Skip confirmation prompts
+- `--setup-only` -- Skip schema migration, run only the setup for current version
 
-**State version source:** `.workflow/state.json` → `version` field
+**Version source:** `.workflow/state.json` → `version` field
 </context>
 
 <execution>
 
-### Step 1: Detect Current State
+### Step 1: Detect Version
 
 ```
-1. Read .workflow/state.json
-2. Extract version field (default "1.0" if missing)
-3. Display:
-
-   === Maestro Workflow Update ===
-   Project:  {project_name}
-   Version:  {version}
-   Location: {.workflow/ path}
+1. Read .workflow/state.json → extract version (default "1.0" if missing)
+2. Display current version
 ```
 
-### Step 2: Dry-Run Preview
+IF `--setup-only`:
+  → Load `~/.maestro/workflows/updates/update-v{version}-setup.md`
+  → IF exists: follow completely, then EXIT
+  → IF not exists: display "No setup script for v{version}" → EXIT
 
-Run the migration CLI in dry-run + JSON mode to get the full plan:
+### Step 2: Check for Updates
 
-```bash
-npx tsx src/migrations/run.ts "$(pwd)" --dry-run --json
 ```
-
-Parse the JSON output. If status is `up-to-date`:
-```
-Already up to date (v{version})
+1. Run: npx tsx src/migrations/run.ts "$(pwd)" --dry-run --json
+2. IF up-to-date → offer setup if available → EXIT
+3. Display target version
 ```
-→ EXIT
 
-Otherwise display the migration plan:
-```
-Pending Migrations ({N} step(s)):
+IF `--dry-run` → EXIT.
 
-  1. [v{from} → v{to}] {name}
-     {description}
+### Step 3: Execute
 
-  2. [v{from} → v{to}] {name}
-     {description}
 ```
-
-If `--dry-run` flag was passed by user → display plan and EXIT.
-
-### Step 3: Interactive Confirmation Loop
-
-For each migration step (unless `--force`):
-
+1. Confirm (unless --force)
+2. Backup state.json
+3. Run schema migration (auto-chains all intermediate steps)
+4. Load update-v{target}-setup.md → follow completely
 ```
-LOOP for step_index = 1 to N:
-
-  Display:
-    --- Step {step_index}/{N}: {name} ---
-    Version: v{from} → v{to}
-
-    Changes:
-      {description, indented}
 
-  IF NOT --force:
-    AskUserQuestion: "Apply this migration?"
-    Options: [yes / skip / abort]
+### Step 4: Summary
 
-    - "yes"   → proceed to Step 4 (execute)
-    - "skip"  → WARN "Skipping may break the migration chain"
-                 continue to next step
-    - "abort" → display summary of what was applied so far → EXIT
-
-  IF --force:
-    → proceed to Step 4 (execute)
-```
-
-### Step 4: Execute Single Migration
-
-```
-1. Create backup:
-   Bash: cp .workflow/state.json .workflow/state.json.backup-v{from}-{timestamp}
-
-2. Run migration:
-   Bash: npx tsx src/migrations/run.ts "$(pwd)" --json
-   
-   NOTE: The runner executes ALL pending migrations. For step-by-step control,
-   read state.json, call the migration function directly, or use the runner
-   which stops on first failure.
-
-3. Parse result JSON and display:
-
-   {status_icon} Step {N} completed: {name}
-   Summary: {summary}
-   Changes:
-     - {change_1}
-     - {change_2}
-     - ...
-
-4. If failed:
-   Display: "Migration failed: {summary}"
-   Display: "Backup available at: {backup_path}"
-   Display: "Restore with: cp {backup_path} .workflow/state.json"
-   → EXIT
-
-5. Continue loop to next step
-```
-
-### Step 5: Summary
-
-After all steps completed (or user aborted):
-
-```
-=== Migration Complete ===
-Applied: {applied_count} / {total_count} migration(s)
-Skipped: {skipped_count}
-Version: v{original} → v{final}
-Backup:  .workflow/state.json.backup-v{original}-{timestamp}
-
-Next steps:
-  /manage-status  -- Verify project state
-  /maestro        -- Continue workflow
-```
+Display version change, backup path, next steps.
 
 </execution>
 
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | .workflow/state.json not found | Run /maestro-init first |
-| E002 | error | state.json parse error | Check file for corruption |
-| E003 | error | Migration function failed | Restore from backup |
-| W001 | warning | Skipped migration may break version chain | Re-run /maestro-update later |
-| W002 | warning | tsx not available | Install tsx: npm i -D tsx |
-</error_codes>
-
 <success_criteria>
-- [ ] Current version detected from state.json
-- [ ] Dry-run preview shows full migration plan without execution
-- [ ] Each step confirmed interactively (unless --force)
-- [ ] Backup created before each migration
-- [ ] Migration executed and result displayed with change list
-- [ ] Abort stops cleanly with partial summary
-- [ ] Summary shows applied/skipped counts and version change
+- [ ] Version detected, schema migration run, setup doc followed
+- [ ] --setup-only, --dry-run, --force flags handled
 </success_criteria>

package/.codex/skills/manage-codebase-rebuild/SKILL.md

@@ -155,7 +155,7 @@ Single wave generates `wave-1.csv`. No `prev_context` needed (all tasks independ
 | `feature-maps/{slug}.md` | Per-feature documentation |
 | `knowledge-graph.json` | Knowledge Graph: nodes, edges, layers, tour (generated by `maestro kg index`) |
 
-**Wiki Integration**: After rebuild, KG nodes are automatically indexed as virtual wiki entries (type: knowhow, virtualKind: kg-node/kg-layer/kg-tour-step) on next `maestro wiki` access. Verify with `maestro wiki list --keyword kg`. Use `maestro kg diff-wiki` for future change impact analysis.
+**Wiki Integration**: After rebuild, KG nodes are automatically indexed as virtual wiki entries (type: knowhow, virtualKind: kg-node/kg-layer/kg-tour-step) on next `maestro wiki` access. Verify with `maestro search "kg" --type knowhow`. Use `maestro kg diff-wiki` for future change impact analysis.
 
 ### Session Structure
 
@@ -354,7 +354,7 @@ Next steps:
   Skill({ skill: "manage-status" })
   Skill({ skill: "manage-codebase-refresh" })
   maestro kg stats           # verify KG
-  maestro wiki list --keyword kg  # verify wiki integration
+  maestro search "kg" --type knowhow  # verify wiki integration
   maestro kg diff-wiki       # future change impact
 ```
 

package/.codex/skills/manage-harvest/SKILL.md

@@ -56,7 +56,7 @@ Follow '~/.maestro/workflows/harvest.md' Stages 1–8 (standard mode) or Stage 9
 3. **Stable fragment IDs** — `HRV-{8 hex}` from `hash(source_id + content_hash)`
 4. **Never modify source artifacts** — purely extractive
 5. **Confidence filtering** — below threshold logged but not routed
-6. **Spec format enforcement** — all spec routing must use `<spec-entry>` closed-tag format with `roles`, `keywords`, `date`, `source="harvest"` attributes
+6. **Spec format enforcement** — all spec routing must use `<spec-entry>` closed-tag format with `title`, `description`, `keywords`, `date`, `source="harvest"` attributes
 
 **Routing rules:**
 - Universal design patterns → `coding` or `arch` category
@@ -66,7 +66,7 @@ Follow '~/.maestro/workflows/harvest.md' Stages 1–8 (standard mode) or Stage 9
 - Spec: `maestro wiki append spec-<file> --body "<content>" --keywords "<kws>"` (unified write path) or `Skill({ skill: "spec-add", args: "<category> <content>" })`
 - Issue: append to `issues.jsonl` matching canonical schema, with `source: "harvest"` field (distinguishes from `manage-issue-discover`, which uses `source: "discover"` — required for cross-skill dedup when both write concurrently)
 
-**Next steps:** `/manage-wiki health`, `maestro wiki list --type note`, `/wiki-connect --fix`, `/wiki-digest`, `/manage-issue list --source harvest`
+**Next steps:** `/manage-wiki health`, `maestro search --type note`, `/wiki-connect --fix`, `/wiki-digest`, `/manage-issue list --source harvest`
 
 **Prune mode** (`--prune`): Classifies artifacts (active/graduated/stale/protected), graduates harvested artifacts to wiki knowhow, archives from `artifacts[]` → `artifact_archive[]`, prunes resolved entries from accumulated_context. Files on disk are never deleted. Always backs up state.json before writing.
 </execution>

package/.codex/skills/manage-knowhow/SKILL.md

@@ -49,7 +49,7 @@ Default to `list` if no arguments. Parse first token as subcommand.
 ### Step 3: Execute Subcommand
 
 **list**: Show entries from both stores (or filtered by `--store`, `--tag`, `--type`).
-- Workflow: use `maestro wiki list --type knowhow --json` or read `.workflow/wiki-index.json`, display ID, type, category, date, tags, title
+- Workflow: use `maestro search --type knowhow --json` or read `.workflow/wiki-index.json`, display ID, type, category, date, tags, title
 - System: list `.md` files in system memory directory
 
 **search `<query>`**: Full-text grep across both stores. Rank by match count.

package/.codex/skills/manage-status/SKILL.md

@@ -53,8 +53,7 @@ Use this decision table to suggest the next action:
 |---------------|------------|
 | No phases planned | `Skill({ skill: "maestro-brainstorm" })` or `Skill({ skill: "maestro-plan" })` |
 | Phase planned, not executed | `Skill({ skill: "maestro-execute", args: "<N>" })` |
-| Phase executed, not verified | `Skill({ skill: "maestro-verify", args: "<N>" })` |
-| Phase verified with gaps | `Skill({ skill: "maestro-plan", args: "<N> --gaps" })` |
+| Phase executed, not reviewed | `Skill({ skill: "quality-review", args: "<N>" })` |
 | Phase reviewed PASS/WARN | `Skill({ skill: "quality-test", args: "<N>" })` |
 | UAT passed | `Skill({ skill: "maestro-milestone-audit" })` |
 | All milestone phases done | `Skill({ skill: "maestro-milestone-audit" })` |

package/.codex/skills/quality-auto-test/SKILL.md

@@ -270,7 +270,7 @@ You MUST call report_agent_job_result EXACTLY ONCE before exiting.
 3. Conditional: traceability.md (spec route), issue creation (code_defect -> issues.jsonl)
 4. Register artifact in state.json (type: test)
 5. Display summary: route, iterations, convergence status, per-layer pass rates, bugs discovered
-6. Route: converged -> maestro-verify; bugs -> quality-debug; >80% -> quality-test; <80% -> quality-debug; single pass all pass -> quality-test
+6. Route: converged -> quality-review; bugs -> quality-debug; >80% -> quality-test; <80% -> quality-debug; single pass all pass -> quality-test
 
 </actions>
 
@@ -314,6 +314,6 @@ Protocol: read before writing tests, append-only, dedup by type+key.
 - [ ] TST artifact registered in state.json
 - [ ] If spec: traceability.md written; if failures: issues auto-created in issues.jsonl
 - [ ] If gap source: validation.json gaps updated (MISSING→COVERED)
-- [ ] Next step routed (converged → verify, bugs → debug, >80% → quality-test, <80% → debug)
+- [ ] Next step routed (converged → quality-review, bugs → debug, >80% → quality-test, <80% → debug)
 </success_criteria>
 </output>

package/.codex/skills/quality-debug/SKILL.md

@@ -110,7 +110,9 @@ id,title,description,hypothesis,deps,context_from,wave,status,findings,evidence_
 | `deps` | Input | Semicolon-separated dependency task IDs (wave 2 depends on wave 1) |
 | `context_from` | Input | Semicolon-separated task IDs whose findings this task needs |
 | `wave` | Input | Wave number (1 = investigation, 2 = fix attempt) |
-| `status` | Lifecycle | `pending` (initial) → `confirmed`/`refuted`/`inconclusive`/`fixed`/`fix_failed`/`failed`/`skipped` (set by merge step from worker's `result_status`) |
+| `status` | Lifecycle | `pending` (initial) → `completed`/`failed`/`skipped` (set by merge step from worker's `result_status`) |
+| `hypothesis_verdict` | Lifecycle | Wave 1 only: `confirmed`/`refuted`/`inconclusive` (merged from worker output) |
+| `fix_result` | Lifecycle | Wave 2 only: `fixed`/`fix_failed` (merged from worker output) |
 | `findings` | Lifecycle | Key findings summary (max 500 chars; merged from worker output) |
 | `evidence_for` | Lifecycle | Evidence supporting the hypothesis (wave 1; merged) |
 | `evidence_against` | Lifecycle | Evidence refuting the hypothesis (wave 1; merged) |
@@ -205,7 +207,7 @@ mkdir -p {sessionFolder}
 
 2b. **Load codebase + wiki context** (optional, informs hypothesis generation):
    - If `.workflow/codebase/ARCHITECTURE.md` exists: read module boundaries to scope impact analysis
-   - Run `maestro wiki search "<symptom keywords>" --json 2>/dev/null`; if results: check for prior investigations on similar issues
+   - Run `maestro search "<symptom keywords>" --json 2>/dev/null`; if results: check for prior investigations on similar issues
    - Run `maestro spec load --category debug --keyword "<symptom keywords>"`; if tools found: extract known issues, workarounds, and root-cause notes to inform hypotheses
    - All are optional — proceed without if unavailable
 
@@ -250,21 +252,22 @@ spawn_agents_on_csv({
   output_schema: {
     type: "object",
     properties: {
-      id:               { type: "string" },
-      result_status:    { type: "string", enum: ["confirmed", "refuted", "inconclusive", "failed"] },
-      findings:         { type: "string", maxLength: 500 },
-      evidence_for:     { type: "string" },
-      evidence_against: { type: "string" },
-      error:            { type: "string" }
+      id:                  { type: "string" },
+      result_status:       { type: "string", enum: ["completed", "failed"] },
+      hypothesis_verdict:  { type: "string", enum: ["confirmed", "refuted", "inconclusive"], description: "Investigation outcome" },
+      findings:            { type: "string", maxLength: 500 },
+      evidence_for:        { type: "string" },
+      evidence_against:    { type: "string" },
+      error:               { type: "string" }
     },
-    required: ["id", "result_status", "findings"]
+    required: ["id", "result_status", "hypothesis_verdict", "findings"]
   }
 })
 ```
 
-3. **Merge**: for each row in `wave-1-results.csv`, look up master row by `id` and write `master.status = result_status`, then copy `findings`, `evidence_for`, `evidence_against`, `error`. Delete `wave-1.csv` and `wave-1-results.csv`.
+3. **Merge**: for each row in `wave-1-results.csv`, look up master row by `id` and write `master.status = result_status`, then copy `hypothesis_verdict`, `findings`, `evidence_for`, `evidence_against`, `error`. Delete `wave-1.csv` and `wave-1-results.csv`.
 4. **Wave 2 gating** (read from MASTER `tasks.csv` after merge, NOT from wave-1-results.csv):
-   - For each `FIX-H{N}` row: read its `context_from` hypothesis ID (e.g., `H{N}`) from master; if master `H{N}.status != "confirmed"`, set `FIX-H{N}.status = "skipped"` (with findings = "upstream {H{N}.status}").
+   - For each `FIX-H{N}` row: read its `context_from` hypothesis ID (e.g., `H{N}`) from master; if master `H{N}.hypothesis_verdict != "confirmed"`, set `FIX-H{N}.status = "skipped"` (with findings = "upstream hypothesis_verdict={H{N}.hypothesis_verdict}").
    - Only rows where `status == "pending"` proceed to wave 2.
 
 #### Wave 1 Worker Contract (WAVE1_INVESTIGATION_INSTRUCTION)
@@ -281,23 +284,24 @@ REQUIRED STEPS:
   1. Read shared discoveries: {sessionFolder}/discoveries.ndjson (may be empty)
   2. Scan codebase for evidence using Read/Grep/Glob (read-only investigation)
   3. Classify the hypothesis based on evidence collected:
-     - confirmed   → strong evidence supports the hypothesis (file:line proof)
-     - refuted     → strong evidence contradicts the hypothesis
-     - inconclusive → insufficient evidence within time budget; do NOT guess
-     - failed      → tool error / cannot read files / blocked by environment
+     - confirmed   → strong evidence supports the hypothesis (file:line proof) → result_status=completed, hypothesis_verdict=confirmed
+     - refuted     → strong evidence contradicts the hypothesis → result_status=completed, hypothesis_verdict=refuted
+     - inconclusive → insufficient evidence within time budget; do NOT guess → result_status=completed, hypothesis_verdict=inconclusive
+     - failed      → tool error / cannot read files / blocked by environment → result_status=failed
   4. Append discoveries to {sessionFolder}/discoveries.ndjson if reusable (root_cause / hypothesis_evidence types)
   5. Call report_agent_job_result EXACTLY ONCE with the verdict
 
 TERMINATION CONTRACT (mandatory — NO worker may end without calling report_agent_job_result):
-  - Success path  → result_status = confirmed | refuted, with evidence
-  - Timeout path  → if approaching {max_runtime_seconds}, STOP investigation and report inconclusive
-  - Failure path  → on any unrecoverable error, report failed with error message
+  - Success path  → result_status=completed, hypothesis_verdict = confirmed | refuted, with evidence
+  - Timeout path  → if approaching {max_runtime_seconds}, STOP investigation and report result_status=completed, hypothesis_verdict=inconclusive
+  - Failure path  → on any unrecoverable error, result_status=failed with error message
   - NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
 
 OUTPUT (return via report_agent_job_result; must match output_schema):
   {
     "id": "<your row id>",
-    "result_status": "confirmed" | "refuted" | "inconclusive" | "failed",
+    "result_status": "completed" | "failed",
+    "hypothesis_verdict": "confirmed" | "refuted" | "inconclusive",
     "findings": "<one-sentence summary, max 500 chars>",
     "evidence_for": "<bullet list of file:line refs supporting, or empty>",
     "evidence_against": "<bullet list of file:line refs refuting, or empty>",
@@ -328,18 +332,19 @@ spawn_agents_on_csv({
     type: "object",
     properties: {
       id:            { type: "string" },
-      result_status: { type: "string", enum: ["fixed", "fix_failed", "failed"] },
+      result_status: { type: "string", enum: ["completed", "failed"] },
+      fix_result:    { type: "string", enum: ["fixed", "fix_failed"], description: "Fix attempt outcome" },
       findings:      { type: "string", maxLength: 500 },
       fix_applied:   { type: "string" },
       verified:      { type: "string", enum: ["true", "false"] },
       error:         { type: "string" }
     },
-    required: ["id", "result_status", "findings", "verified"]
+    required: ["id", "result_status", "fix_result", "findings", "verified"]
   }
 })
 ```
 
-4. **Merge**: write `master.status = result_status`, copy `findings`, `fix_applied`, `verified`, `error`. Delete `wave-2.csv` and `wave-2-results.csv`.
+4. **Merge**: write `master.status = result_status`, copy `fix_result`, `findings`, `fix_applied`, `verified`, `error`. Delete `wave-2.csv` and `wave-2-results.csv`.
 
 #### Wave 2 Worker Contract (WAVE2_FIX_INSTRUCTION)
 
@@ -359,16 +364,17 @@ REQUIRED STEPS:
   5. Call report_agent_job_result EXACTLY ONCE
 
 TERMINATION CONTRACT (mandatory):
-  - Success path → fix applied AND verified → result_status=fixed, verified="true"
-  - Partial path → fix applied but verification failed → result_status=fix_failed, verified="false"
-  - Timeout path → approaching {max_runtime_seconds} with no fix applied → result_status=fix_failed with error="timeout"
+  - Success path → fix applied AND verified → result_status=completed, fix_result=fixed, verified="true"
+  - Partial path → fix applied but verification failed → result_status=completed, fix_result=fix_failed, verified="false"
+  - Timeout path → approaching {max_runtime_seconds} with no fix applied → result_status=completed, fix_result=fix_failed with error="timeout"
   - Failure path → cannot apply fix (file missing, parse error, etc.) → result_status=failed
   - NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
 
 OUTPUT (return via report_agent_job_result; must match output_schema):
   {
     "id": "<your row id>",
-    "result_status": "fixed" | "fix_failed" | "failed",
+    "result_status": "completed" | "failed",
+    "fix_result": "fixed" | "fix_failed",
     "findings": "<one-sentence summary of what was changed, max 500 chars>",
     "fix_applied": "<file:line description of the change>",
     "verified": "true" | "false",
@@ -409,7 +415,7 @@ CONSTRAINTS:
 | Result | Suggestion |
 |--------|------------|
 | All fixes verified | Run tests: `Skill({ skill: "quality-test", args: "{phase}" })` |
-| Fixes applied, not verified | Re-verify: `Skill({ skill: "maestro-verify", args: "{phase}" })` |
+| Fixes applied, not verified | Re-execute: `Skill({ skill: "maestro-execute", args: "{phase}" })` |
 | Confirmed but no fix | Plan fixes: `Skill({ skill: "maestro-plan", args: "{phase} --gaps" })` |
 | All inconclusive | Resume with more context or manual investigation |
 | From UAT, all diagnosed | `Skill({ skill: "quality-test", args: "{phase} --auto-fix" })` |

package/.codex/skills/quality-refactor/SKILL.md

@@ -123,7 +123,7 @@ Create `.workflow/scratch/refactor-{slug}-{date}/` with `.task/` and `.summaries
 
 ### Step 3: Scope Analysis
 
-Load project specs if available (`maestro spec load --category coding` for conventions, `maestro spec load --category review` for quality standards). Browse wiki: `maestro wiki list --category coding`, load relevant entries.
+Load project specs if available (`maestro spec load --category coding` for conventions, `maestro spec load --category review` for quality standards). Browse wiki: `maestro search --category coding`, load relevant entries.
 
 Analyze scope for tech debt categories:
 

package/.codex/skills/quality-retrospective/SKILL.md

@@ -241,7 +241,7 @@ If `--no-route`: skip this stage.
 For each insight in `synthResult.insights`, route based on `routing` field:
 
 **Spec routing** (`routing: "spec"`):
-Map category (pattern/convention → `coding`, architecture → `arch`, quality → `quality`). Append `<spec-entry>` with category, auto-extracted keywords, date, source="retrospective", title, summary, evidence, phase/lens/INS-id.
+Map category (pattern/convention → `coding`, architecture → `arch`, quality → `quality`). Append `<spec-entry>` with category, auto-extracted keywords, date, title, description, source="retrospective", evidence, phase/lens/INS-id.
 
 **Issue routing** (`routing: "issue"`, severity critical/high):
 Append to `.workflow/issues/issues.jsonl` with `ISS-<date>-<seq>` id, source="retrospective", phase/INS-id context, and history entry.