maestro-flow 0.4.26 → 0.5.0

package/workflows/claude-instructions.md

@@ -19,21 +19,33 @@ Available CLI endpoints are dynamically defined by the config file
 
 ## Knowledge System
 
-### Search — Query Before Acting
+### Design Principles
 
-**Before planning or implementing any task, search wiki and spec first** — the knowledge base contains reusable methods, tools, and hard-won experience. Load the right knowledge at the right time: search before you plan, load relevant entries before you implement, and revisit when you hit unfamiliar territory mid-task.
+- **Single search entry** — `maestro search` is the only user-facing search command
+- **Silent-skip-is-bug** — if knowledge exists but search misses it, that is a defect
+- **Layer 2 auto-injection** — agents receive specs via hooks, rarely need manual `spec load`
 
-When tackling unfamiliar domains or cross-cutting concerns, search existing knowledge first:
-- `maestro spec load --category <cat>` — load rules by category (coding/arch/debug/test/review/learning)
-- `maestro spec load --keyword <kw>` — cross-category keyword match
-- `maestro wiki search "<query>"` — full-text search across all knowhow
-- `maestro wiki list --category <cat>` → `maestro wiki load <id>` — browse then load full detail
+### Search — Three-Layer Architecture
+
+**Before planning or implementing, search first.** Load the right knowledge at the right time.
+
+| Layer | Command | When to Use |
+|-------|---------|-------------|
+| **1. Unified** | `maestro search "<query>" [--type spec\|knowhow\|issue] [--category <cat>]` | Daily search — BM25 full-text across all knowledge types |
+| **2. Agent injection** | `maestro spec load --category <cat> [--keyword <kw>]` | Domain rules for implementation (auto-injected by hooks) |
+| **3. Code structure** | `maestro kg search <symbol>` / `maestro kg context <node>` | Tracing dependencies, call chains, module boundaries |
+
+**Deprecated** (do not use): `spec search`, `knowhow search`, `wiki search` — all replaced by Layer 1.
+
+KG stays fresh via hooks (`kg-sync` on UserPromptSubmit, `kg-context-injector` on Agent spawn). Manual `maestro kg index --sqlite` only needed on initial setup.
 
 ### Record — Capture Knowledge
 
-When execution surfaces non-obvious knowledge (decisions, root causes, pitfalls, patterns), persist it:
+When execution surfaces non-obvious knowledge, persist it:
 
-- **Spec entry** (short rule/constraint) → `/spec-add <category> "title" "content" --keywords kw1,kw2`
-- **Knowhow document** (detailed recipe/template/decision/reference) → `/manage-knowhow-capture`
+- **Spec entry** (short rule/constraint) → `/spec-add <category> "title" "content" --keywords kw1,kw2 --description "summary"`
+- **Knowhow document** (detailed recipe/template/decision) → `/manage-knowhow-capture`
+  - Use `--spec-category <cat>` to bridge knowhow into agent injection
+  - Files use `{PREFIX}-{YYYYMMDD}-{slug}.md` naming for readable filenames
 
-Category routing: decisions→`arch`, patterns→`coding`, pitfalls→`debug`/`learning`, rules→`review`, test strategy→`test`.
+Category routing: decisions→`arch`, patterns→`coding`, pitfalls→`debug`/`learning`, rules→`review`, test strategy→`test`.

package/workflows/codex-instructions.md

@@ -68,14 +68,13 @@ Available CLI endpoints are dynamically defined by the config file
 
 **Before planning or implementing any task, search wiki and spec first** — the knowledge base contains reusable methods, tools, and hard-won experience. Load the right knowledge at the right time: search before you plan, load relevant entries before you implement, and revisit when you hit unfamiliar territory mid-task.
 
+- `maestro search "<query>" [--type spec|knowhow|issue] [--category <cat>]` — BM25 full-text across all knowledge types
 - `maestro spec load --category <cat>` — load rules by category (coding/arch/debug/test/review/learning)
 - `maestro spec load --keyword <kw>` — cross-category keyword match
-- `maestro wiki search "<query>"` — full-text search across all knowhow
-- `maestro wiki list --category <cat>` → `maestro wiki load <id>` — browse then load full detail
 
 ### Knowledge Capture
 
-- **Spec writes** → always `<spec-entry>` closed-tag format with `category`, `keywords`, `date`, `source`. Never raw Markdown. Route through `spec-add` when possible.
+- **Spec writes** → always `<spec-entry>` closed-tag format with `title`, `description`, `category`, `keywords`, `date`, `source`. Never raw Markdown. Route through `spec-add` when possible.
 - **Capture signal** → when execution surfaces non-obvious knowledge (plan deviation, retry pattern, root cause, constraint violation), ask user once whether to persist it. Match category to content: decisions→`arch`, pitfalls→`debug`/`learning`, patterns→`coding`, rules→`quality`.
 - **Promotion** → at milestone close, scan learnings for repeated keywords (≥2 entries) and offer to graduate them into formal conventions.
 - **Traceability** → every entry needs a source anchor: `file:line`, `INS-{id}`, commit, or phase path.

package/workflows/execute.md

@@ -1,8 +1,8 @@
 # Execute Workflow
 
-Wave-based parallel execution with atomic commits, breakpoint resume, and optional sync/reflection.
+Wave-based parallel execution with atomic commits, breakpoint resume, built-in verification gate, and optional sync/reflection.
 
-Core principle: **Execute per-plan, not per-phase.** Each plan's wave DAG runs independently. Multiple plans execute sequentially.
+Core principle: **Execute per-plan, not per-phase.** Each plan's wave DAG runs independently. Multiple plans execute sequentially. Verification is an integral post-gate — not a separate command.
 
 ---
 
@@ -69,6 +69,7 @@ For each PLAN_DIR in PLAN_DIRS (sequential):
 | `--method agent\|codex\|gemini\|cli\|auto` | Override execution method (default: config.json.execution.method) |
 | `--executor <tool>` | Default CLI tool: gemini\|codex\|qwen\|opencode\|claude (default: first enabled in cli-tools.json) |
 | `--dir <path>` | Use arbitrary directory instead of phase resolution (skip roadmap validation) |
+| `--skip-verify` | Skip E2.7 verification gate (trust execution output) |
 | `-y` | Auto-approve execution options (skip confirmation prompt) |
 
 ---
@@ -117,10 +118,19 @@ AskUserQuestion({
       header: "Review",
       multiSelect: false,
       options: [
-        { label: "Skip (Recommended)", description: "No code review, proceed to verification" },
-        // One option per enabled CLI tool with review capability:
+        { label: "Skip", description: "No code review" },
         ...availableTools.map(t => ({ label: `${t} Review`, description: `${t} CLI: git diff quality review` }))
       ]
+    },
+    {
+      question: "Verification gate? (external model checks convergence + structure + anti-patterns)",
+      header: "Verify",
+      multiSelect: false,
+      options: [
+        { label: "Auto (Recommended)", description: `Delegate to ${availableTools[0] || 'first enabled tool'} for convergence + 3-layer structure + anti-pattern check` },
+        ...availableTools.map(t => ({ label: t, description: `${t}: verification gate` })),
+        { label: "Skip", description: "No verification gate" }
+      ]
     }
   ]
 })
@@ -146,7 +156,17 @@ Other text parsing — match tool names dynamically from enabled tools:
 
 **Question 2 (Review):** store as `codeReviewTool`
 
-Store: `executionMethod`, `domainRouting`, `codeReviewTool`
+**Question 3 (Verify):**
+
+| Answer | verificationTool |
+|--------|-----------------|
+| "Auto" | First enabled tool from config |
+| Tool name | That tool |
+| "Skip" | `"Skip"` |
+
+`--skip-verify` flag overrides to `"Skip"`.
+
+Store: `executionMethod`, `domainRouting`, `codeReviewTool`, `verificationTool`
 
 ---
 
@@ -166,6 +186,7 @@ If executionContext is available in memory:
   executorAssignments = executionContext.executorAssignments || {}
   domainRouting = E0.5 domainRouting || executionContext.domainRouting || {}
   codeReviewTool = E0.5 selection || executionContext.codeReviewTool || "Skip"
+  verificationTool = E0.5 selection || executionContext.verificationTool || "Auto"
   Skip disk reload
 ```
 
@@ -179,6 +200,7 @@ defaultExecutor = --executor flag || config.json.execution.default_executor || f
 executorAssignments = plan.json.executor_assignments || {}
 domainRouting = E0.5 domainRouting || built from delegate-config domain tags (frontend→tag match, backend→tag match, default→"agent")
 codeReviewTool = E0.5 selection || "Skip"
+verificationTool = E0.5 selection || "Auto"
 ```
 
 ### Detect completed tasks (breakpoint resume)
@@ -415,6 +437,128 @@ Wait for completion, log findings summary
 
 ---
 
+## E2.7: Verification Gate
+
+**Purpose:** External model verifies execution output actually achieves convergence criteria and structural integrity. Replaces the standalone `maestro-verify` — verification is now an integral post-gate within execution. The executing agent does NOT verify itself; a separate model performs the cross-check.
+
+**Skip if** `verificationTool == "Skip"` OR `--skip-verify` flag OR no completed tasks.
+
+### Step 1: Collect Verification Inputs
+
+```
+modified_files = collect all files changed by completed tasks (from .summaries/ + git diff)
+convergence_criteria = collect convergence.criteria from all completed .task/*.json
+success_criteria = index.json.success_criteria (if exists)
+must_haves = success_criteria || convergence_criteria aggregated
+summaries_content = concatenate all .summaries/TASK-*-summary.md
+```
+
+### Step 2: Resolve Verification Tool
+
+```
+IF verificationTool == "Auto": resolve to first enabled tool from delegate-config
+ELSE: use specified tool name
+```
+
+### Step 3: Dispatch Verification (external model)
+
+Single delegate call covers convergence review + structure verify + anti-pattern scan:
+
+```
+Bash({
+  command: 'maestro delegate "PURPOSE: Verify execution output meets all convergence criteria and structural integrity; success = all criteria verified with file:line evidence
+TASK:
+1. CONVERGENCE: For each criterion below, check if the actual code satisfies it — read the files, verify the behavior exists, report status with evidence
+2. STRUCTURE Layer 1 (Existence): Verify all expected output files exist on disk
+3. STRUCTURE Layer 2 (Substance): Verify files have real implementation — flag stubs, placeholders, TODO-only, empty returns
+4. STRUCTURE Layer 3 (Wiring): Verify files are imported and used by the system — flag orphaned files
+5. ANTI-PATTERNS: Scan modified files for TODO/FIXME/HACK, placeholder content, console.log/print debug statements, disabled tests
+MODE: analysis
+CONTEXT: @${modified_files as glob patterns}
+EXPECTED: JSON {
+  convergence: [{ criterion: string, status: \"verified\"|\"failed\"|\"uncertain\", evidence: string }],
+  structure: {
+    existence: [{ path: string, status: \"exists\"|\"missing\" }],
+    substance: [{ path: string, status: \"real\"|\"stub\", evidence: string }],
+    wiring: [{ path: string, status: \"wired\"|\"orphaned\", importers: string[] }]
+  },
+  anti_patterns: [{ type: string, file: string, line: number, severity: \"blocker\"|\"warning\"|\"info\" }],
+  gaps: [{ id: string, type: string, severity: \"critical\"|\"high\"|\"medium\"|\"low\", description: string, fix_direction: string }],
+  overall: \"passed\"|\"gaps_found\"
+}
+CONSTRAINTS: Read-only | Check ALL criteria exhaustively | Evidence must be file:line references | Do NOT assume — verify by reading code
+
+## Convergence Criteria (verify each one)
+${must_haves.map((c, i) => (i+1) + \". \" + c).join(\"\\n\")}
+
+## Modified Files
+${modified_files.join(\"\\n\")}
+
+## Task Summaries (executor self-reports — verify independently)
+${summaries_content}
+" --to ${verificationTool} --mode analysis',
+  run_in_background: true
+})
+```
+
+### Step 4: Process Results
+
+```
+On callback:
+  Parse JSON result from delegate output
+
+  // Write verification.json (downstream compatibility for quality-review, quality-test, etc.)
+  Write ${PLAN_DIR}/verification.json:
+  {
+    "phase": PHASE_NUM,
+    "status": result.overall,
+    "verified_at": ISO_timestamp,
+    "verifier": verificationTool,
+    "must_haves": {
+      "truths": result.convergence,
+      "artifacts": [...result.structure.existence, ...result.structure.substance],
+      "key_links": result.structure.wiring
+    },
+    "gaps": result.gaps,
+    "antipatterns": result.anti_patterns,
+    "coverage_score": verified_count / total_count
+  }
+
+  IF result.overall == "passed":
+    Log "✓ Verification Gate: PASSED — all criteria verified by ${verificationTool}"
+    Continue to E3
+
+  IF result.overall == "gaps_found":
+    Log verification report with per-criterion status
+
+    // Auto-create issues from critical/high gaps
+    For each gap with severity critical|high:
+      Create issue in .workflow/issues/issues.jsonl:
+        id: "ISS-{YYYYMMDD}-{NNN}", status: "registered",
+        priority: severity_to_priority(gap.severity), source: "verification-gate",
+        phase_ref: PHASE_NUM, gap_ref: gap.id
+
+    // Gate decision
+    IF any critical gaps:
+      Set index.json.status = "verification_failed"
+      Log: "✗ Verification Gate: FAILED — {N} critical gaps. Run /maestro-plan --gaps to fix."
+      STOP pipeline (do not proceed to E3)
+    ELSE (medium/low only):
+      Log warnings, continue to E3
+```
+
+### Step 5: Register VRF Artifact
+
+```
+IF verification ran (not skipped):
+  Create VRF artifact in state.json:
+    { id: "VRF-{next_id}", type: "verify", milestone, phase,
+      path: "${PLAN_DIR}/verification.json", status: result.overall == "passed" ? "completed" : "gaps_found",
+      depends_on: EXC_artifact.id, created_at, completed_at }
+```
+
+---
+
 ## E3: Auto Sync
 
 **Purpose:** Update codebase documentation after execution.
@@ -460,8 +604,10 @@ If config.json.workflow.reflection == true:
 ## Final State Update
 
 ```
-If all tasks completed:
-  index.json.status = "verifying", set completed_at → "Run /workflow:verify"
+If all tasks completed AND verification passed (or skipped):
+  index.json.status = "verified", set completed_at
+Elif all tasks completed AND verification failed:
+  index.json.status = "verification_failed", set completed_at
 Else:
   index.json.status = "executing" (partial) → "Re-run /workflow:execute to resume"
 

package/workflows/fork.md

@@ -152,7 +152,7 @@ Display:
     /maestro-analyze {firstPending.phase}
     /maestro-plan {firstPending.phase}
     /maestro-execute {firstPending.phase}
-    /maestro-verify {firstPending.phase}
+    /quality-review {firstPending.phase}
     # ... repeat for next phases in milestone
 
   Or delegate (automated):

package/workflows/integration-test.md

@@ -179,7 +179,7 @@ List output files: state.json, reflection-log.md, summary.json.
 
 | Result | Suggestion |
 |--------|------------|
-| Converged (>=95%) | Skill({ skill: "maestro-verify", args: "{phase}" }) to update validation |
+| Converged (>=95%) | Skill({ skill: "quality-review", args: "{phase}" }) to update validation |
 | Max iter, >80% | Skill({ skill: "quality-test", args: "{phase}" }) for manual UAT on remaining gaps |
 | Max iter, <80% | Skill({ skill: "quality-debug" }) for deep investigation |
 | Bugs discovered | Skill({ skill: "maestro-plan", args: "{phase} --gaps" }) to plan fixes |

package/workflows/maestro-super.md

@@ -34,7 +34,7 @@ Each milestone must pass a readiness score before advancing. Prevents premature
 | Documentation (API docs, README, setup guide) | 10% | 60% |
 | **Weighted total** | | **≥ 80%** |
 
-Score is computed via `maestro-verify` + Gemini analysis. If score < 80%, generate fix plan and re-execute until threshold is met (max 3 retries per milestone, then report blockers).
+Score is computed via `maestro-execute` verification gate + Gemini analysis. If score < 80%, generate fix plan and re-execute until threshold is met (max 3 retries per milestone, then report blockers).
 
 ## 6. Completion Criteria
 

package/workflows/maestro.codex.md

@@ -40,7 +40,7 @@ Instead of regex, extract a structured intent tuple using LLM semantic understan
 
 ```json
 {
-  "action":    "<create|fix|analyze|plan|execute|verify|review|test|debug|refactor|explore|manage|transition|continue|sync|learn|retrospect>",
+  "action":    "<create|fix|analyze|plan|execute|review|test|debug|refactor|explore|manage|transition|continue|sync|learn|retrospect>",
   "object":    "<feature|bug|issue|code|test|spec|phase|milestone|doc|performance|security|ui|memory|codebase|config>",
   "scope":     "<module/file/area or null>",
   "issue_id":  "<ISS-XXXXXXXX-NNN if mentioned, else null>",
@@ -65,7 +65,7 @@ Route via `action × object` matrix. If `issue_id` present → issue pipeline di
 | execute | issue→issue_execute | execute |
 | manage | issue→issue, milestone→milestone_audit, phase→phase_transition, memory/doc/codebase→memory/sync/codebase_refresh | status |
 | transition | phase→phase_transition, milestone→milestone_complete | phase_transition |
-| verify, review, test, debug, refactor, continue, sync, learn, retrospect, release, amend, compose | — | self-named |
+| review, test, debug, refactor, continue, sync, learn, retrospect, release, amend, compose | — | self-named |
 
 **Clarity scoring**: 3 = action+object+scope, 2 = action+object, 1 = action only, 0 = empty.
 If `clarity < 2` and not `AUTO_YES`: request user input (max 2 rounds).
@@ -81,16 +81,15 @@ Returns `{ chain, argsOverride? }`. Steps resolved from `chainMap[chain]`.
 | No phases | `brainstorm-driven` |
 | pending + has context | `plan` |
 | pending, no context | `analyze` |
-| exploring/planning + has plan | `execute-verify` |
+| exploring/planning + has plan | `execute` |
 | exploring/planning, no plan | `plan` |
-| executing, all tasks done | `verify` |
+| executing, all tasks done | `review` |
 | executing, tasks remain | `execute` |
-| verifying, passed + no review | `review` |
-| verifying, passed + BLOCK | `review-fix` |
-| verifying, passed + UAT pending | `test` |
-| verifying, passed + UAT passed | `milestone-close` |
-| verifying, passed + UAT failed | `debug` |
-| verifying, not passed | `quality-loop-partial` |
+| exec completed + no review | `review` |
+| exec completed + review BLOCK | `review-fix` |
+| exec completed + UAT pending | `test` |
+| exec completed + UAT passed | `milestone-close` |
+| exec completed + UAT failed | `debug` |
 | testing, UAT passed | `milestone-close` |
 | testing, UAT not passed | `debug` |
 | completed | `milestone-close` |
@@ -108,7 +107,6 @@ const chainMap = {
   'ui_design':          [{ cmd: 'maestro-impeccable',         args: '"{phase}" --chain build' }],
   'plan':               [{ cmd: 'maestro-plan',            args: '{phase}' }],
   'execute':            [{ cmd: 'maestro-execute',         args: '{phase}' }],
-  'verify':             [{ cmd: 'maestro-verify',          args: '{phase}' }],
   'test_gen':           [{ cmd: 'quality-auto-test',        args: '{phase}' }],
   'auto_test':          [{ cmd: 'quality-auto-test',        args: '{phase}' }],
   'test':               [{ cmd: 'quality-test',            args: '{phase}' }],
@@ -141,36 +139,27 @@ const chainMap = {
     { cmd: 'maestro-init' },
     { cmd: 'maestro-roadmap', args: '--mode full "{description}"' },
     { cmd: 'maestro-plan',          args: '{phase}' },
-    { cmd: 'maestro-execute',       args: '{phase}' },
-    { cmd: 'maestro-verify',        args: '{phase}' }
+    { cmd: 'maestro-execute',       args: '{phase}' }
   ],
   'brainstorm-driven': [
     { cmd: 'maestro-brainstorm', args: '"{description}"' },
     { cmd: 'maestro-plan',       args: '{phase}' },
-    { cmd: 'maestro-execute',    args: '{phase}' },
-    { cmd: 'maestro-verify',     args: '{phase}' }
+    { cmd: 'maestro-execute',    args: '{phase}' }
   ],
   'impeccable-build': [
     { cmd: 'maestro-impeccable', args: '"{phase}" --chain build' },
     { cmd: 'maestro-plan',      args: '{phase}' },
-    { cmd: 'maestro-execute',   args: '{phase}' },
-    { cmd: 'maestro-verify',    args: '{phase}' }
+    { cmd: 'maestro-execute',   args: '{phase}' }
   ],
   'full-lifecycle': [
     { cmd: 'maestro-plan',          args: '{phase}' },
     { cmd: 'maestro-execute',       args: '{phase}' },
-    { cmd: 'maestro-verify',        args: '{phase}' },
     { cmd: 'quality-review',        args: '{phase}' },
     { cmd: 'quality-test',          args: '{phase}' },
     { cmd: 'maestro-milestone-audit' },
     { cmd: 'maestro-milestone-complete' }
   ],
-  'execute-verify': [
-    { cmd: 'maestro-execute', args: '{phase}' },
-    { cmd: 'maestro-verify',  args: '{phase}' }
-  ],
   'quality-loop': [
-    { cmd: 'maestro-verify',   args: '{phase}' },
     { cmd: 'quality-review',   args: '{phase}' },
     { cmd: 'quality-test',     args: '{phase}' },
     { cmd: 'quality-debug',    args: '--from-uat {phase}' },
@@ -185,14 +174,12 @@ const chainMap = {
     { cmd: 'maestro-init' },
     { cmd: 'maestro-roadmap',  args: '"{description}"' },
     { cmd: 'maestro-plan',     args: '{phase}' },
-    { cmd: 'maestro-execute',  args: '{phase}' },
-    { cmd: 'maestro-verify',   args: '{phase}' }
+    { cmd: 'maestro-execute',  args: '{phase}' }
   ],
   'next-milestone': [
     { cmd: 'maestro-roadmap',  args: '"{description}"' },
     { cmd: 'maestro-plan',     args: '{phase}' },
-    { cmd: 'maestro-execute',  args: '{phase}' },
-    { cmd: 'maestro-verify',   args: '{phase}' }
+    { cmd: 'maestro-execute',  args: '{phase}' }
   ],
   'analyze-plan-execute': [
     { cmd: 'maestro-analyze', args: '"{description}" -q' },
@@ -203,17 +190,15 @@ const chainMap = {
   // ── SKILL.md simplified aliases (--chain <name> shortcuts) ───────────────
   'feature': [
     { cmd: 'maestro-plan',    args: '{phase}' },
-    { cmd: 'maestro-execute', args: '{phase}' },
-    { cmd: 'maestro-verify',  args: '{phase}' }
+    { cmd: 'maestro-execute', args: '{phase}' }
   ],
   'quality-fix': [
     { cmd: 'maestro-analyze',      args: '--gaps "{description}"' },
     { cmd: 'maestro-plan',         args: '--gaps' },
-    { cmd: 'maestro-execute',      args: '' },
-    { cmd: 'maestro-verify',       args: '{phase}' }
+    { cmd: 'maestro-execute',      args: '' }
   ],
   'deploy': [
-    { cmd: 'maestro-verify',           args: '{phase}' },
+    { cmd: 'maestro-execute',         args: '{phase}' },
     { cmd: 'maestro-milestone-release' }
   ],
 
@@ -238,8 +223,7 @@ const chainMap = {
   ],
   'quality-loop-partial': [
     { cmd: 'maestro-plan',    args: '{phase} --gaps' },
-    { cmd: 'maestro-execute', args: '{phase}' },
-    { cmd: 'maestro-verify',  args: '{phase}' }
+    { cmd: 'maestro-execute', args: '{phase}' }
   ],
   'milestone-release': [
     { cmd: 'maestro-milestone-audit' },

package/workflows/maestro.md

@@ -24,7 +24,7 @@ Parse $ARGUMENTS → extract flags, remainder is intent text.
 
 Check `.workflow/state.json` existence.
 
-**If exists:** Read state.json + roadmap.md. Derive progress by grouping artifacts by phase, determining furthest artifact type per phase (analyze→plan→execute→verify), and identifying pending plans. Build `$PROJECT_STATE`:
+**If exists:** Read state.json + roadmap.md. Derive progress by grouping artifacts by phase, determining furthest artifact type per phase (analyze→plan→execute), and identifying pending plans. Build `$PROJECT_STATE`:
 ```json
 {
   "initialized": true,
@@ -91,9 +91,8 @@ Directly match user intent to the best `task_type` (maps to chain in chainMap).
 |-----------|---------------------------|
 | `quick` | Simple/small task, add a feature, quick change |
 | `plan` | Plan, design, architect a phase |
-| `execute` | Implement, develop, code a phase |
+| `execute` | Implement, develop, code a phase (includes built-in verification gate) |
 | `analyze` | Understand, investigate, evaluate code |
-| `verify` | Check goals met, validate results |
 | `review` | Code quality review |
 | `test` | Run or create tests, UAT |
 | `test_gen` | Generate tests for coverage gaps |
@@ -127,12 +126,11 @@ Directly match user intent to the best `task_type` (maps to chain in chainMap).
 | `team_qa` | Team QA, debugging |
 | `team_tech_debt` | Team tech debt remediation |
 | `team_lifecycle` | Team full lifecycle (plan+dev+test+review) |
-| `full-lifecycle` | Complete phase: plan→execute→verify→review→test→audit |
+| `full-lifecycle` | Complete phase: plan→execute→review→test→audit |
 | `brainstorm-driven` | Start from exploration/brainstorm |
 | `spec-driven` | From spec/requirements (heavy, with init) |
 | `roadmap-driven` | From requirements (light, with init) |
 | `analyze-plan-execute` | Fast track: analyze→plan→execute |
-| `execute-verify` | Resume after planning |
 | `review-fix` | Fix review-blocked issues |
 | `quality-loop` | Full quality improvement cycle |
 | `quality-loop-partial` | Partial quality fix |
@@ -181,8 +179,7 @@ Full `chainMap` and `detectNextAction` are in the [Reference Data](#reference-da
 
 Cross-validate intent against project state:
 - `execute` but no plan → warn, prepend `maestro-plan`
-- `verify` but not executed → warn, prepend `maestro-execute`
-- `test` but not verified → warn, prepend `maestro-verify`
+- `test` but not executed → warn, prepend `maestro-execute`
 - `milestone_close` but not all phases executed → warn, suggest completing first
 
 Display warning but let user override.
@@ -221,7 +218,7 @@ Step type is selected **per step**, not per chain. Pre-compute and write to each
 If execMode is 'cli' or 'internal' → force that type for all steps ("cli" or "skill").
 In 'auto' mode, select per step:
   CLI steps (heavy, context-isolated): maestro-plan, maestro-execute, maestro-analyze, maestro-brainstorm, maestro-roadmap, maestro-impeccable, quality-refactor → type: "cli"
-  Skill steps (everything else): current-session Skill() call — verify, review, test, debug, milestone-*, manage-*, spec-*, quick, etc. → type: "skill"
+  Skill steps (everything else): current-session Skill() call — review, test, debug, milestone-*, manage-*, spec-*, quick, etc. → type: "skill"
 ```
 
 **Trade-off:** CLI = context isolation + template prompts. Skill = current-session Skill() call, direct visibility + synchronous + user can intervene.
@@ -311,7 +308,6 @@ const chainMap = {
   'impeccable_improve':   [{ cmd: 'maestro-impeccable', args: '"{description}" --chain improve' }],
   'plan':               [{ cmd: 'maestro-plan', args: '{phase}' }],
   'execute':            [{ cmd: 'maestro-execute', args: '{phase}' }],
-  'verify':             [{ cmd: 'maestro-verify', args: '{phase}' }],
   'test_gen':           [{ cmd: 'quality-auto-test', args: '{phase}' }],
   'auto_test':          [{ cmd: 'quality-auto-test', args: '{phase}' }],
   'test':               [{ cmd: 'quality-test', args: '{phase}' }],
@@ -353,20 +349,19 @@ const chainMap = {
   'team_tech_debt':     [{ cmd: 'team-tech-debt', args: '"{description}"' }],
 
   // ── Multi-step chains ──
-  'full-lifecycle':       [{ cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }, { cmd: 'quality-review', args: '{phase}' }, { cmd: 'quality-test', args: '{phase}' }, { cmd: 'maestro-milestone-audit' }],
-  'spec-driven':          [{ cmd: 'maestro-init' }, { cmd: 'maestro-roadmap', args: '--mode full "{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
-  'roadmap-driven':       [{ cmd: 'maestro-init' }, { cmd: 'maestro-roadmap', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
-  'brainstorm-driven':    [{ cmd: 'maestro-brainstorm', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
+  'full-lifecycle':       [{ cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'quality-review', args: '{phase}' }, { cmd: 'quality-test', args: '{phase}' }, { cmd: 'maestro-milestone-audit' }],
+  'spec-driven':          [{ cmd: 'maestro-init' }, { cmd: 'maestro-roadmap', args: '--mode full "{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }],
+  'roadmap-driven':       [{ cmd: 'maestro-init' }, { cmd: 'maestro-roadmap', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }],
+  'brainstorm-driven':    [{ cmd: 'maestro-brainstorm', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }],
   'brainstorm_visualize': [{ cmd: 'brainstorm-visualize', args: '"{description}"' }],
-  'impeccable-build':       [{ cmd: 'maestro-impeccable', args: '"{description}" --chain build' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
-  'impeccable-driven':      [{ cmd: 'maestro-impeccable', args: '"{description}" --chain build' }, { cmd: 'maestro-verify', args: '{phase}' }],
+  'impeccable-build':       [{ cmd: 'maestro-impeccable', args: '"{description}" --chain build' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }],
+  'impeccable-driven':      [{ cmd: 'maestro-impeccable', args: '"{description}" --chain build' }, { cmd: 'maestro-execute', args: '{phase}' }],
   'analyze-plan-execute': [{ cmd: 'maestro-analyze', args: '"{description}" -q' }, { cmd: 'maestro-plan', args: '--dir {scratch_dir}' }, { cmd: 'maestro-execute', args: '--dir {scratch_dir}' }],
-  'execute-verify':       [{ cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
-  'quality-loop':         [{ cmd: 'maestro-verify', args: '{phase}' }, { cmd: 'quality-review', args: '{phase}' }, { cmd: 'quality-auto-test', args: '{phase}' }, { cmd: 'quality-test', args: '{phase}' }, { cmd: 'quality-debug', args: '--from-uat {phase}' }, { cmd: 'maestro-plan', args: '{phase} --gaps' }, { cmd: 'maestro-execute', args: '{phase}' }],
+  'quality-loop':         [{ cmd: 'quality-review', args: '{phase}' }, { cmd: 'quality-auto-test', args: '{phase}' }, { cmd: 'quality-test', args: '{phase}' }, { cmd: 'quality-debug', args: '--from-uat {phase}' }, { cmd: 'maestro-plan', args: '{phase} --gaps' }, { cmd: 'maestro-execute', args: '{phase}' }],
   'milestone-close':      [{ cmd: 'maestro-milestone-audit' }, { cmd: 'maestro-milestone-complete' }],
-  'next-milestone':       [{ cmd: 'maestro-roadmap', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
+  'next-milestone':       [{ cmd: 'maestro-roadmap', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }],
   'review-fix':           [{ cmd: 'maestro-plan', args: '{phase} --gaps' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'quality-review', args: '{phase}' }],
-  'quality-loop-partial': [{ cmd: 'maestro-plan', args: '{phase} --gaps' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
+  'quality-loop-partial': [{ cmd: 'maestro-plan', args: '{phase} --gaps' }, { cmd: 'maestro-execute', args: '{phase}' }],
   'issue-full':           [{ cmd: 'maestro-analyze', args: '--gaps {issue_id}' }, { cmd: 'maestro-plan', args: '--gaps' }, { cmd: 'maestro-execute', args: '' }, { cmd: 'quality-review', args: '{phase}' }, { cmd: 'manage-issue', args: 'close {issue_id} --resolution fixed' }],
   'issue-quick':          [{ cmd: 'maestro-plan', args: '--gaps' }, { cmd: 'maestro-execute', args: '' }, { cmd: 'manage-issue', args: 'close {issue_id} --resolution fixed' }],
   'milestone-release':    [{ cmd: 'maestro-milestone-audit' }, { cmd: 'maestro-milestone-release' }],
@@ -404,15 +399,13 @@ detectNextAction(state):
 
   Route by phase_status (ps):
     pending:    has context artifact → 'plan'; has analysis → 'analyze-quick'; else → 'analyze'
-    exploring/planning: has plan → 'execute-verify'; else → 'plan'
-    executing:  all tasks done → 'verify'; has blockers → 'debug'; else → 'execute'
-    verifying:
-      verification passed:
-        no review → 'review'
-        review BLOCK → 'review-fix'
-        uat pending → 'test'; uat passed → 'milestone-close'; uat failed → 'debug'
-        default → 'test'
-      verification not passed → 'quality-loop-partial'
+    exploring/planning: has plan → 'execute'; else → 'plan'
+    executing:  all tasks done → 'review'; has blockers → 'debug'; else → 'execute'
+    exec completed (verification is built-in):
+      no review → 'review'
+      review BLOCK → 'review-fix'
+      uat pending → 'test'; uat passed → 'milestone-close'; uat failed → 'debug'
+      default → 'test'
     testing:    uat passed → 'milestone-close'; else → 'debug'
     completed:  → 'milestone-close'
     forked:     worktrees.json exists → 'merge'; else → 'status'
@@ -424,19 +417,18 @@ detectNextAction(state):
 
 | Chain | Steps | Use Case |
 |-------|-------|----------|
-| `full-lifecycle` | plan → execute → verify → review → test → audit | Full milestone completion |
-| `blueprint-driven` | init → blueprint → plan → execute → verify | From idea/requirements (heavy) |
-| `roadmap-driven` | init → roadmap → plan → execute → verify | From requirements (light) |
-| `brainstorm-driven` | brainstorm → plan → execute → verify | From exploration |
-| `impeccable-build` | impeccable --chain build → plan → execute → verify | From design system generation |
+| `full-lifecycle` | plan → execute → review → test → audit | Full milestone completion |
+| `blueprint-driven` | init → blueprint → plan → execute | From idea/requirements (heavy) |
+| `roadmap-driven` | init → roadmap → plan → execute | From requirements (light) |
+| `brainstorm-driven` | brainstorm → plan → execute | From exploration |
+| `impeccable-build` | impeccable --chain build → plan → execute | From design system generation |
 | `analyze-plan-execute` | analyze -q → plan --dir → execute --dir | Fast track (scratch mode) |
-| `execute-verify` | execute → verify | Resume after planning |
 | `review-fix` | plan --gaps → execute → review | Fix review-blocked issues |
-| `quality-loop` | verify → review → test-gen → test → debug → plan --gaps → execute | Fix quality issues |
-| `quality-loop-partial` | plan --gaps → execute → verify | Partial quality fix cycle |
+| `quality-loop` | review → test-gen → test → debug → plan --gaps → execute | Fix quality issues |
+| `quality-loop-partial` | plan --gaps → execute | Partial quality fix cycle |
 | `milestone-close` | audit → complete | Close a milestone |
 | `milestone-release` | audit → release | Release with version tag |
-| `next-milestone` | roadmap → plan → execute → verify | Next milestone (auto-loads deferred) |
+| `next-milestone` | roadmap → plan → execute | Next milestone (auto-loads deferred) |
 | `issue-full` | analyze → plan → execute → review → close | Issue with quality gate |
 | `issue-quick` | plan → execute → close | Issue fast path |
 
@@ -456,8 +448,8 @@ detectNextAction(state):
 | `"这个问题需要看看"` | analyze | maestro-analyze |
 | `"创建一个 issue 跟踪"` | issue | manage-issue |
 | `"discover issues"` | issue_discover | manage-issue-discover |
-| `"brainstorm notifications"` | brainstorm-driven | brainstorm→plan→execute→verify |
-| `"spec generate auth"` | spec-driven | init→spec→plan→execute→verify |
+| `"brainstorm notifications"` | brainstorm-driven | brainstorm→plan→execute |
+| `"spec generate auth"` | spec-driven | init→spec→plan→execute |
 | `"ui design landing"` | impeccable_build | maestro-impeccable --chain build |
 | `"优化界面交互"` | impeccable_improve | maestro-impeccable --chain improve |
 | `"refactor auth module"` | refactor | quality-refactor "auth module" |
@@ -466,10 +458,10 @@ detectNextAction(state):
 | `"next phase"` | milestone-close | audit→complete |
 | `-y "implement X"` | execute | maestro-execute (auto) |
 | `"release v1.2"` | release | maestro-milestone-release |
-| `"从需求开始做完整个项目"` | spec-driven | init→spec→plan→execute→verify |
+| `"从需求开始做完整个项目"` | spec-driven | init→spec→plan→execute |
 | `"分析完直接改"` | analyze-plan-execute | analyze→plan→execute |
 | `"review 有问题需要修"` | review-fix | plan --gaps→execute→review |
-| `"全面质量检查"` | quality-loop | verify→review→test→debug→plan→execute |
+| `"全面质量检查"` | quality-loop | review→test→debug→plan→execute |
 
 ### Error Codes
 
@@ -488,7 +480,7 @@ detectNextAction(state):
 1. **Semantic Routing** — LLM-native `action × object` extraction; disambiguates "问题" by context
 2. **State-Aware** — Reads `.workflow/state.json` before routing
 3. **Quality Gates** — Issue chains auto-include review; `issue-full` is default for issue execution
-4. **Per-Step Type** — Each step independently typed as `"skill"` or `"cli"`. Heavy steps (plan, execute, analyze, brainstorm) → CLI for context isolation. Observable steps (verify, review, test, debug, manage-*) → Skill (current-session) for direct visibility. `--exec cli|internal` forces all steps.
+4. **Per-Step Type** — Each step independently typed as `"skill"` or `"cli"`. Heavy steps (plan, execute, analyze, brainstorm) → CLI for context isolation. Observable steps (review, test, debug, manage-*) → Skill (current-session) for direct visibility. `--exec cli|internal` forces all steps.
 5. **Unified Executor** — All execution dispatched to `maestro-ralph-execute`, which handles both maestro (static chain) and ralph (adaptive chain with decision nodes) sessions.
 6. **Phase Propagation** — Auto-detects and passes phase numbers to downstream commands
 7. **Auto Mode** — `-y` propagates through chain, skipping all confirmations

package/workflows/review.md

@@ -38,7 +38,7 @@ When external review feedback is received (from human reviewers, PR comments, or
 ## Prerequisites
 
 - Phase execution completed (task summaries exist)
-- Recommended: maestro-verify already run (review uses verification gaps as context)
+- Recommended: maestro-execute verification gate already run (review uses verification gaps as context)
 
 ---