maestro-flow 0.4.26 → 0.5.0

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

@@ -35,7 +35,7 @@ If not provided, prompt user for scope.
 1. **Coding specs**: Run `maestro spec load --category coding` to load coding conventions. Apply conventions to all refactored code.
 2. **Review specs**: Run `maestro spec load --category review` to load review standards. Use as quality gate for refactored code.
 3. **Role Knowledge**:
-   - Browse: `maestro wiki list --category coding`
+   - Browse: `maestro search --category coding`
    - Identify task-relevant entries, then load: `maestro wiki load <id1> [id2...]`
 4. All are optional — proceed without if unavailable.
 </context>
@@ -44,7 +44,7 @@ If not provided, prompt user for scope.
 Follow '~/.maestro/workflows/refactor.md' completely.
 
 **Knowledge inquiry on completion:**
-After successful refactoring, ask user once: "Record refactoring pattern as coding convention?" If yes, persist via `Skill("spec-add", "coding \"<title>\" \"<pattern>\" --keywords <kw1>,<kw2>")`.
+After successful refactoring, ask user once: "Record refactoring pattern as coding convention?" If yes, persist via `Skill("spec-add", "coding \"<title>\" \"<pattern>\" --keywords <kw1>,<kw2> --description \"<summary>\"")`.
 
 **Next-step routing on completion:**
 - All tests pass → `/quality-sync` (update codebase docs)

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

@@ -24,7 +24,7 @@ Post-execution multi-perspective retrospective (复盘) for completed phases. Co
 
 <deferred_reading>
 - @~/.maestro/workflows/issue.md (issues.jsonl schema for auto-creation)
-- @~/.maestro/workflows/learn.md (tip routing via manage-learn tip)
+- @~/.maestro/workflows/learn.md (tip routing via manage-knowhow-capture tip)
 - @~/.maestro/workflows/verify.md (verification.json schema for quality lens parsing)
 - @~/.maestro/workflows/review.md (review.json schema for quality lens parsing)
 </deferred_reading>
@@ -41,7 +41,7 @@ Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order. Key invari
 1. **Read-only until Stage 6** — Stages 1–5 must not write anything except the in-memory retrospective record.
 2. **Parallel lens dispatch** — Stage 4 spawns one Agent per active lens in a single message (multiple Agent tool calls). All agents use `subagent_type: "general-purpose"` and `run_in_background: false`.
 3. **Match canonical issues schema** — Stage 6 issue routing must produce rows that pass `jq` parsing and match the schema in `workflows/issue.md` Step 4 exactly (status `"open"`, full `issue_history` entry, all required fields).
-4. **Reuse `manage-learn tip` for note routing** — do not duplicate the learning pipeline; invoke via `view_file(AbsolutePath="<agy-skills-dir>/manage-learn/SKILL.md") + execute inline (args: "tip ...")`.
+4. **Reuse `manage-knowhow-capture tip` for note routing** — do not duplicate the learning pipeline; invoke via `view_file(AbsolutePath="<agy-skills-dir>/manage-knowhow-capture/SKILL.md") + execute inline (args: "tip ...")`.
 5. **Backward-compat with phase-transition** — append a one-line summary per insight to `.workflow/specs/learnings.md` if and only if that file already exists. Never create it.
 6. **Stable insight IDs** — `INS-{8 hex}` from `hash(phase_num + lens + title)` so re-runs do not duplicate.
 7. **Archive before overwrite** — if existing `retrospective.{md,json}` are being replaced, move them to `{artifact_dir}/.history/` with a timestamp suffix first.
@@ -57,7 +57,7 @@ Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order. Key invari
 | E005 | error | Phase argument out of range / phase directory not found | scan_unreviewed |
 | W001 | warning | One or more lens agents failed — proceeding with partial coverage | multi_lens_analysis |
 | W002 | warning | Existing retrospective.json found and not `--all` — prompted user to overwrite | scan_unreviewed |
-| W003 | warning | `manage-learn tip` did not return parseable INS id; fell back to direct write | route_outputs |
+| W003 | warning | `manage-knowhow-capture tip` did not return parseable INS id; fell back to direct write | route_outputs |
 | W004 | warning | `--compare` target phase has no retrospective.json; delta omitted | load_artifacts |
 </error_codes>
 
@@ -71,9 +71,9 @@ Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order. Key invari
 - [ ] If routing enabled (default): every recommendation either created an artifact or was explicitly skipped by user
 - [ ] Spec entries (if any) appended as `<spec-entry>` to matching `.workflow/specs/{category-file}.md`
 - [ ] Issue rows (if any) match canonical issues.jsonl schema (status "open", full issue_history, all required fields)
-- [ ] Note tips (if any) created via `view_file(AbsolutePath="<agy-skills-dir>/manage-learn/SKILL.md") + execute inline (args: "tip ...")`
+- [ ] Note tips (if any) created via `view_file(AbsolutePath="<agy-skills-dir>/manage-knowhow-capture/SKILL.md") + execute inline (args: "tip ...")`
 - [ ] `.workflow/specs/learnings.md` appended with one `<spec-entry>` per insight regardless of routing target
 - [ ] No existing phase artifacts modified (verification.json, review.json, plan.json untouched)
 - [ ] Confirmation banner displays routing counts and next-step suggestions
-- [ ] Next step: `/manage-status` to review state, or `/manage-issue list --source retrospective` to triage created issues, or `/manage-learn list` to browse the knowhow library
+- [ ] Next step: `/manage-status` to review state, or `/manage-issue list --source retrospective` to triage created issues, or `/manage-knowhow list` to browse the knowhow library
 </success_criteria>

package/.agy/skills/quality-review/SKILL.md

@@ -15,7 +15,7 @@ allowed-tools:
   - write_to_file
 ---
 <purpose>
-Run multi-dimensional code review on a completed phase's changed files. Answers the question "is this code good?" -- complementing maestro-verify ("is the goal met?") and quality-test ("does it work for users?"). Three review levels (quick/standard/deep) scale with task depth, auto-detected from file count. Level definitions, dimension lists, deep-dive rules, and issue creation thresholds defined in workflow review.md.
+Run multi-dimensional code review on a completed phase's changed files. Answers the question "is this code good?" -- complementing maestro-execute's built-in verification ("is the goal met?") and quality-test ("does it work for users?"). Three review levels (quick/standard/deep) scale with task depth, auto-detected from file count. Level definitions, dimension lists, deep-dive rules, and issue creation thresholds defined in workflow review.md.
 </purpose>
 
 <required_reading>
@@ -52,9 +52,9 @@ Extract conclusions from related artifacts that may affect this review. Pass as
 
 ### Pre-load (optional, proceed without)
 - Codebase docs: `.workflow/codebase/ARCHITECTURE.md` → component boundaries, layer rules
-- Wiki constraints: `maestro wiki search "architecture constraint" --json` → documented decisions
+- Wiki constraints: `maestro search "architecture constraint" --json` → documented decisions
 - Specs: `maestro spec load --category review` → review standards, checklists, knowhow tools
-- Role knowledge: `maestro wiki list --category review` → select relevant → `maestro wiki load`
+- Role knowledge: `maestro search --category review` → select relevant → `maestro wiki load`
 
 **Output**: `REVIEW_DIR = .workflow/scratch/{YYYYMMDD}-review-P{N}-{slug}/` (P{N} = phase number, enables directory-level identification as state.json fallback)
 </context>
@@ -101,7 +101,7 @@ NEXT: /quality-refactor
 
 Status mapping:
 - **DONE** — PASS verdict, no critical findings → NEXT: /quality-refactor
-- **DONE_WITH_CONCERNS** — WARN verdict, issues found but non-blocking → NEXT: /maestro-verify
+- **DONE_WITH_CONCERNS** — WARN verdict, issues found but non-blocking → NEXT: /quality-test
 - **NEEDS_RETRY** — BLOCK verdict, critical findings require fix first
 </execution>
 

package/.agy/skills/quality-sync/SKILL.md

@@ -35,6 +35,7 @@ Follow '~/.maestro/workflows/sync.md' completely.
 **Next-step routing on completion:**
 - Docs refreshed → `/manage-status`
 - Major structural changes detected → `/manage-codebase-rebuild` (full rebuild recommended)
+- Incremental refresh (replaces former `/manage-codebase-refresh`) → use `--since` flag
 </execution>
 
 <error_codes>

package/.agy/skills/quality-test/SKILL.md

@@ -43,8 +43,8 @@ Follow '~/.maestro/workflows/test.md' completely.
 **Command-specific extensions (not in workflow):**
 
 **Knowledge context loading** (before test design):
-- Wiki search: `maestro wiki search "<phase/feature keywords>" --json` → prior test strategies, recipes, decisions
-- Role knowledge: `maestro wiki list --category test` → select relevant → `maestro wiki load <id>`
+- Wiki search: `maestro search "<phase/feature keywords>" --json` → prior test strategies, recipes, decisions
+- Role knowledge: `maestro search --category test` → select relevant → `maestro wiki load <id>`
 - Specs + tools: `maestro spec load --category test` → test conventions + discoverable knowhow tools
 
 **Test tool discovery** (knowhow tools as scenario source):
@@ -79,7 +79,7 @@ Append to state.json.artifacts[]:
 
 **Next-step routing on completion:**
 - All tests pass → `/maestro-milestone-audit`
-- Issues found, --auto-fix ran and succeeded → `/maestro-verify {phase}`
+- Issues found, --auto-fix ran and succeeded → `/maestro-execute {phase}`
 - Issues found, --auto-fix ran but gaps remain → `/quality-debug --from-uat {phase}`
 - Issues found, manual fix needed → `/quality-debug --from-uat {phase}`
 - Coverage below threshold → `/quality-auto-test {phase}`
@@ -90,7 +90,7 @@ Append to state.json.artifacts[]:
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
 | E001 | error | Phase or task target required (no active sessions) | Prompt user for phase number |
-| E002 | error | Phase not verified yet (no verification.json) | Suggest `/maestro-verify` first |
+| E002 | error | Phase not verified yet (no verification.json) | Suggest `/maestro-execute` first (verification is built-in) |
 | E003 | error | Smoke test failed (app won't start) | Suggest `/quality-debug` |
 | W001 | warning | One or more test scenarios failed | Auto-diagnose, suggest fix options |
 | W002 | warning | Coverage below threshold | Suggest `/quality-auto-test` |

package/.agy/skills/spec-add/SKILL.md

@@ -23,6 +23,7 @@ Entries use `category` attribute to declare which category they belong to.
 $ARGUMENTS -- expects `[--scope <scope>] [--uid <uid>] <category> <content>`
 
 **Options:**
+- `--description <desc>` — One-line description for search results (falls back to content[:240])
 - `--ref <path>` — Create as index entry referencing a knowhow document. If the path exists, only creates the spec index entry. If path doesn't exist, also creates the knowhow file.
 - `--knowhow-type <type>` — Knowhow document type when creating with --ref (asset, blueprint, document, template, recipe, reference, decision)
 
@@ -33,12 +34,13 @@ Scope-to-directory mapping, category-to-file mapping, and entry format defined i
 # English content → English keywords
 /spec-add coding "Named exports" "Always use named exports" --keywords "exports,naming"
 
-# Chinese content → Chinese keywords (匹配中文 prompt)
-/spec-add coding "命名导出规范" "始终使用命名导出" --keywords "导出,命名,模块"
+# With description for search results
+/spec-add coding "OAuth PKCE Flow" "完整 PKCE 集成流程" --keywords "oauth,pkce" --description "OAuth 2.0 PKCE 认证流程规范"
 
-# Mixed → bilingual keywords
-/spec-add coding "OAuth PKCE Flow" "完整 PKCE 集成流程" --ref knowhow/RCP-oauth-pkce.md --keywords "oauth,pkce,认证,授权"
+# Chinese content → Chinese keywords
+/spec-add coding "命名导出规范" "始终使用命名导出" --keywords "导出,命名,模块"
 
+# Ref mode
 /spec-add arch "OAuth PKCE 集成" "完整流程设计" --ref knowhow/AST-oauth-flow.md
 ```
 </context>

package/.agy/skills/spec-setup/SKILL.md

@@ -11,7 +11,7 @@ allowed-tools:
 <purpose>
 Initialize the project-level specs directory by scanning the codebase for conventions, patterns, and tech stack.
 Core files (coding, arch, learnings) are always created. Optional spec files (quality, test, ui) are created only when relevant signals are detected.
-Additionally, generates recipe-type knowhow docs in `.workflow/knowhow/` for detected operational workflows (test / debug / build / dev / lint) — capturing "how to do X in this project" so future agents can find them via `maestro wiki search`.
+Additionally, generates recipe-type knowhow docs in `.workflow/knowhow/` for detected operational workflows (test / debug / build / dev / lint) — capturing "how to do X in this project" so future agents can find them via `maestro search`.
 Spec output lands in `.workflow/specs/`; recipe output lands in `.workflow/knowhow/`.
 </purpose>
 

package/.claude/commands/learn-follow.md

@@ -23,7 +23,7 @@ $ARGUMENTS — target and optional flags.
 |-------|-----------|
 | File path (contains `/` or `\`) | Read source file |
 | Wiki ID (`<type>-<slug>`) | `maestro wiki get <id>` |
-| Topic string | `maestro wiki search "<topic>"` → top result; fallback: Grep src/ |
+| Topic string | `maestro search "<topic>"` → top result; fallback: Grep src/ |
 
 **Flags**:
 - `--depth shallow` (default): key patterns and structure only

package/.claude/commands/learn-investigate.md

@@ -30,7 +30,7 @@ $ARGUMENTS — question text and optional flags.
 - `.workflow/knowhow/KNW-investigate-{slug}/report.md` — final report
 - `.workflow/specs/learnings.md` — appended `<spec-entry>` blocks
 
-**Storage read**: source files in scope + `maestro wiki search` + `.workflow/specs/learnings.md` + `debug-notes.md` + `codebase/architecture.md`
+**Storage read**: source files in scope + `maestro search` + `.workflow/specs/learnings.md` + `debug-notes.md` + `codebase/architecture.md`
 </context>
 
 <state_machine>
@@ -83,7 +83,7 @@ S_REPORT:
 ### A_FRAME_QUESTION
 
 1. Parse question, generate slug, create KNW-investigate-{slug}/
-2. Search prior knowledge: `maestro wiki search "<question>"` + search .workflow/specs/learnings.md + read debug-notes.md
+2. Search prior knowledge: `maestro search "<question>"` + search .workflow/specs/learnings.md + read debug-notes.md
 3. Write initial understanding.md (question, prior knowledge summary, scope, timestamp)
 
 ### A_COLLECT_EVIDENCE

package/.claude/commands/learn-second-opinion.md

@@ -33,7 +33,7 @@ $ARGUMENTS — target and optional mode flag.
 
 **Flags**: `--mode review|challenge|consult` (default: review)
 
-**Pre-load** (optional): `Skill("spec-load")` for conventions + `maestro wiki search "<target topic>"` for related entries.
+**Pre-load** (optional): `Skill("spec-load")` for conventions + `maestro search "<target topic>"` for related entries.
 
 **Output**: `.workflow/knowhow/KNW-opinion-{slug}-{YYYY-MM-DD}.md`
 </context>

package/.claude/commands/maestro-analyze.md

@@ -71,11 +71,11 @@ Output directory format, artifact registration schema, and output artifact listi
 
 1. **Codebase docs**: IF `.workflow/codebase/doc-index.json` exists → Read ARCHITECTURE.md for module boundaries
 2. **Specs**: `maestro spec load --category arch` — load architecture constraints
-3. **Wiki search**: `maestro wiki search "{topic keywords}" --json` → top 5-10 entries as prior knowledge
+3. **Wiki search**: `maestro search "{topic keywords}" --json` → top 5-10 entries as prior knowledge
 4. All optional — proceed without if unavailable (log warning)
 
 ### Role Knowledge
-`maestro wiki list --category debug` → select relevant → `maestro wiki load`
+`maestro search --category debug` → select relevant → `maestro wiki load`
 </context>
 
 <interview_protocol>
@@ -93,6 +93,57 @@ Follows @~/.maestro/workflows/interview-mechanics.md standard.
 <execution>
 Follow '~/.maestro/workflows/analyze.md' completely.
 
+### Core Principle: Evidence-Backed Decisions
+
+Every decision produced by this command MUST be traceable to independently gathered evidence. Manual file reading (Read/Grep by the orchestrator) is preparation, NOT evidence. Evidence comes from:
+- cli-explore-agent output (code anchors, call chains, data flows)
+- maestro delegate CLI analysis output (multi-perspective findings)
+- User-provided input (domain knowledge, constraints, corrections)
+
+A decision without at least one CLI/agent-sourced evidence item is LOW CONFIDENCE and MUST be flagged as such.
+
+### Standard Mode Phase Gates (when `-q` and `--gaps` are BOTH absent)
+
+These gates are MANDATORY and BLOCKING. Do NOT advance past a gate until ALL conditions are met. Do NOT substitute manual Read/Grep for agent/CLI exploration.
+
+**GATE 1: Step 4 → Step 5** (Exploration → Discussion)
+- REQUIRED: cli-explore-agent spawned and completed (Step 4.1). Output written to `exploration-codebase.json` with ≥1 code anchor.
+- REQUIRED: At least one maestro delegate CLI call completed (Step 4.2). Output aggregated into `explorations.json` or `perspectives.json`.
+- REQUIRED: Baseline confidence scoring recorded in discussion.md (Step 4.6).
+- BLOCKED if any missing: complete Step 4 before proceeding.
+
+**GATE 2: Step 5 → Step 6** (Discussion → Scoring)
+- REQUIRED: discussion.md contains ≥1 interactive round with user feedback (Step 5.3).
+- REQUIRED: Confidence re-scored ≥1 time with delta shown (Step 5.8).
+- REQUIRED: Pressure pass completed ≥1 time (Step 5.9).
+- BLOCKED if any missing: continue discussion rounds.
+
+**GATE 3: Step 6 → Step 7** (Scoring → Synthesis)
+- REQUIRED: analysis.md written with all 6 dimensions scored.
+- REQUIRED: Each dimension score cites evidence from exploration-codebase.json or explorations.json — NOT from orchestrator's manual file reading.
+- BLOCKED if any missing: complete scoring first.
+
+**GATE 4: Step 7 → Step 8** (Synthesis → Decision Extraction)
+- REQUIRED: conclusions.json written with recommendations and decision trail.
+- REQUIRED: Intent Coverage Matrix shows no unresolved ❌ items (or user-confirmed deferrals).
+- BLOCKED if any missing: complete synthesis first.
+
+### Artifact Verification
+
+Before writing the completion report (Step 9), verify ALL expected artifacts exist in OUTPUT_DIR:
+```
+FULL_MODE_REQUIRED = [
+  "discussion.md",           // Step 3+5
+  "exploration-codebase.json", // Step 4.1
+  "explorations.json" OR "perspectives.json", // Step 4.3
+  "analysis.md",             // Step 6
+  "conclusions.json",        // Step 7
+  "context.md",              // Step 8
+  "context-package.json"     // Step 8.6
+]
+```
+If any artifact is missing: DO NOT report completion. Go back and produce the missing artifact.
+
 ### --gaps Mode (Issue Root Cause Analysis)
 
 When `--gaps` flag is present, follow `~/.maestro/workflows/issue-gaps-analyze.md` instead of the standard analyze pipeline:

package/.claude/commands/maestro-blueprint.md

@@ -64,7 +64,7 @@ maestro-analyze → maestro-roadmap → maestro-plan
 ### Pre-load
 
 1. **Specs**: `maestro spec load --category arch` — load architecture constraints for Phase 4 decisions
-2. **Wiki search**: `maestro wiki search "{topic keywords}" --json` → prior knowledge context
+2. **Wiki search**: `maestro search "{topic keywords}" --json` → prior knowledge context
 3. All optional — proceed without if unavailable
 </context>
 
@@ -90,6 +90,41 @@ P0: Spec Study → P1: Discovery → P1.5: Req Expansion → P2: Product Brief
 
 P6 gate: Pass (>=80%) → Handoff | Review (60-79%) → Handoff w/caveats | Fail (<60%) → P6.5 Auto-Fix (max 2 iter) → re-check
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+Each phase produces artifacts that are prerequisites for the next. Do NOT advance past a gate without verifying the prior phase's output exists.
+
+**GATE P0 → P1**: `blueprint-config.json` created with session metadata.
+**GATE P1 → P1.5**: Discovery context gathered (codebase patterns, upstream context loaded).
+**GATE P1.5 → P2**: Requirements expanded from discovery findings.
+**GATE P2 → P3**: `product-brief.md` written with vision, goals, scope, multi-perspective synthesis.
+**GATE P3 → P4**: `requirements/` directory with `_index.md` + individual `REQ-*.md` + `NFR-*.md` files. All requirements have RFC 2119 keywords and acceptance criteria.
+**GATE P4 → P5**: `architecture/` directory with `_index.md` + individual `ADR-*.md` files.
+**GATE P5 → P6**: `epics/` directory with `_index.md` + individual `EPIC-*.md` files. Cross-Epic dependency map present.
+**GATE P6**: Readiness score computed. Pass (≥80%) or Review (≥60%) required for handoff.
+
+### Artifact Verification (before completion)
+
+```
+REQUIRED_ARTIFACTS = [
+  "blueprint-config.json",        // P0
+  "product-brief.md",             // P2
+  "glossary.json",                // P2 (≥5 terms)
+  "requirements/_index.md",       // P3
+  "architecture/_index.md",       // P4
+  "epics/_index.md",              // P5
+  "readiness-report.md",          // P6
+  "blueprint-summary.md",         // P6
+  "context-package.json"          // P6
+]
+```
+If any artifact is missing: DO NOT report completion. Go back and produce it.
+
+### Evidence Requirement
+
+Architecture Decision Records (ADR-*.md) MUST cite evidence for each decision:
+- Valid: code analysis, requirement traceability (REQ-xxx), upstream context, CLI analysis output
+- INVALID: generic rationale without reference to project-specific constraints
 </execution>
 
 <completion>

package/.claude/commands/maestro-brainstorm.md

@@ -57,7 +57,7 @@ $ARGUMENTS -- topic text for auto mode, or role name for single role mode.
 
 ### Role Knowledge
 1. Browse accumulated knowledge for this role:
-   `maestro wiki list --category arch`
+   `maestro search --category arch`
 2. Analyze the index, identify entries relevant to the current task
 3. Load selected documents:
    `maestro wiki load <id1> [id2] [id3...]`
@@ -77,6 +77,45 @@ Follows @~/.maestro/workflows/interview-mechanics.md standard.
 
 <execution>
 Follow '~/.maestro/workflows/brainstorm.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+These gates apply to Auto mode (full pipeline). Do NOT advance past a gate until ALL conditions are met.
+
+**GATE 1: Framework → Role Analysis** (Step 1 → Step 3)
+- REQUIRED: `guidance-specification.md` written with §10 feature decomposition and RFC 2119 keywords.
+- REQUIRED: Role selection completed (interactive or auto-default).
+- BLOCKED if missing: complete framework generation before spawning role agents.
+
+**GATE 2: Role Analysis → Cross-Role Review** (Step 3 → Step 4.5)
+- REQUIRED: Every selected role has `{role}/analysis.md` with §2 Decision Digest (4 tables).
+- REQUIRED: Per-feature files `{role}/analysis-F-*.md` written for each feature in §10.
+- BLOCKED if missing: complete all role analyses before spawning cross-role-reviewer.
+
+**GATE 3: Cross-Role Review → Completion** (Step 4.5 → Report)
+- REQUIRED: Cross-role-reviewer output received with `patch_targets[]`.
+- REQUIRED: If findings > 0, resolutions applied via Edit AND logged in `guidance-specification.md` §12.
+- REQUIRED: If findings == 0, final report explicitly states "No cross-role issues detected".
+- BLOCKED if missing: complete review synthesis before reporting.
+
+### Artifact Verification (before completion report)
+
+```
+AUTO_MODE_REQUIRED = [
+  "guidance-specification.md",            // Step 1
+  "{role}/analysis.md" (per selected role), // Step 3
+  "{role}/analysis-F-*.md" (per feature),   // Step 3
+]
+```
+If any artifact is missing: DO NOT report completion. Go back and produce the missing artifact.
+
+### Evidence Requirement
+
+Role analysis findings in `{role}/analysis.md` §2 Decision Digest MUST cite concrete evidence:
+- Code references (file:line), API endpoints, data models from the codebase
+- User-provided constraints from interview
+- Cross-role references to other role analyses
+Decisions without evidence are flagged LOW CONFIDENCE.
 </execution>
 
 <completion>

package/.claude/commands/maestro-collab.md

@@ -25,7 +25,7 @@ $ARGUMENTS — requirement text and optional flags.
 - `--rule <template>`: Shared rule template for all delegates
 - `-y`: Skip plan confirmation
 
-**Pre-load** (optional): `maestro spec load --category arch` + `maestro wiki list --category arch` → include in delegate prompts.
+**Pre-load** (optional): `maestro spec load --category arch` + `maestro search --category arch` → include in delegate prompts.
 
 **Output**: `.workflow/scratch/{YYYYMMDD}-collab-{slug}/`
 - `collab-report.md` — merged findings with consensus/conflict/unique tags

package/.claude/commands/maestro-companion.md

@@ -114,7 +114,7 @@ Display loaded rules summary (entry count + key rule names).
 maestro knowhow list --store workflow
 
 # With --task: search relevant entries
-maestro knowhow search "<task_keyword>"
+maestro search --type knowhow "<task_keyword>"
 ```
 
 Display available knowhow entries (ID + title). Hint: `maestro wiki load <id>` for details.
@@ -127,7 +127,7 @@ ls .workflow/codebase/doc-index.json
 
 - Exists → display "Codebase docs ready, last updated: {timestamp}"
 - Missing → suggest `/manage-codebase-rebuild`
-- Stale (>7 days) → suggest `/manage-codebase-refresh`
+- Stale (>7 days) → suggest `/quality-sync`
 
 ### 4. Create companion document
 
@@ -341,7 +341,7 @@ Mid-task commands:
   /maestro-companion note "finding or decision"
   /maestro-companion note --file src/auth.ts "changed token validation"
   /spec-load --keyword <keyword>
-  maestro wiki search "<query>"
+  maestro search "<query>"
 ```
 
 ---
@@ -470,7 +470,7 @@ Clear `.workflow/.scratchpad/.companion-active`.
 
 ```
 Knowledge accumulation reminders:
-  Reusable pattern found?        /spec-add <category> "title" "content"
+  Reusable pattern found?        /spec-add <category> "title" "content" --description "summary"
   Solved a complex problem?      /manage-knowhow-capture recipe "description"
   Made an architecture decision? /manage-knowhow-capture decision "description"
   Discovered a useful trick?     /manage-knowhow-capture tip "content"

package/.claude/commands/maestro-composer.md

@@ -126,7 +126,7 @@ Read deferred `node-catalog.md` (fallback to built-in mapping):
 | review | `quality-review` |
 | brainstorm | `maestro-brainstorm` |
 | analysis | `maestro delegate --role analyze` |
-| verify | `maestro-verify` |
+| verify | `maestro-execute` |
 | refactor | `quality-refactor` |
 | debug | `quality-debug` |
 

package/.claude/commands/maestro-execute.md

@@ -17,7 +17,7 @@ Execute all tasks in a plan using wave-based parallel execution with dependency-
 
 Invoked after /maestro-plan produces a confirmed plan. When called without args on a milestone, finds all pending plans and executes them sequentially.
 
-Pipeline position: upstream from maestro-plan (consumes confirmed plan), downstream to maestro-verify.
+Pipeline position: upstream from maestro-plan (consumes confirmed plan). Verification is built-in (E2.7).
 </purpose>
 
 <required_reading>
@@ -56,13 +56,13 @@ Full resolution logic, output directory format, artifact registration schema, an
 ### Pre-load context (before task execution)
 
 1. **Codebase docs**: If `.workflow/codebase/doc-index.json` exists, read `ARCHITECTURE.md` for module boundaries. Pass as shared context to executor agents.
-2. **Wiki knowledge**: Run `maestro wiki search "<phase keywords>" --json 2>/dev/null`. If results found, extract top 5 entries as prior knowledge context for agents.
+2. **Wiki knowledge**: Run `maestro search "<phase keywords>" --json 2>/dev/null`. If results found, extract top 5 entries as prior knowledge context for agents.
 3. **Coding specs + tools**: Run `maestro spec load --category coding` to load coding conventions AND discoverable knowhow tools (tool: true entries). Pass as specs context to all executor agents.
 4. **UI specs (conditional)**: If any task involves frontend/UI work (task scope/description contains keywords like component, page, style, layout, CSS, HTML, frontend; or focus_paths in `src/components/`, `src/pages/`, `src/styles/`, `src/ui/`), also run `maestro spec load --category ui` and include in agent context.
 5. All are optional — proceed without if unavailable (log warning).
 
 ### Role Knowledge
-`maestro wiki list --category coding` → select relevant → `maestro wiki load`
+`maestro search --category coding` → select relevant → `maestro wiki load`
 </context>
 
 <execution>
@@ -76,6 +76,29 @@ If exit code is 1, present warnings and ask whether to proceed.
 
 Follow '~/.maestro/workflows/execute.md' completely.
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Plan Load → Task Execution**
+- REQUIRED: plan.json found and parsed with valid task definitions.
+- REQUIRED: `.task/TASK-*.json` files exist for all tasks in plan.
+- BLOCKED if no pending tasks: error E004.
+
+**GATE 2: Per-Task Execution → Summary**
+- REQUIRED: Each completed task has `.summaries/TASK-{NNN}-summary.md` written with concrete evidence (files changed, tests run, verification results).
+- REQUIRED: `.task/TASK-{NNN}.json` status updated to completed|blocked.
+- Do NOT silently skip failed tasks — mark as blocked with reason.
+
+**GATE 3: All Tasks → Completion**
+- REQUIRED: All waves executed in dependency order.
+- REQUIRED: EXC artifact registered in state.json.
+
+### Evidence Requirement
+
+Task summaries MUST include:
+- Files actually modified (not just planned targets)
+- Convergence criteria verification results (pass/fail with evidence)
+- Any deviations from the plan with rationale
+
 ### Post-task Knowledge Inquiry
 
 After each task completion, check triggers:
@@ -86,7 +109,8 @@ After each task completion, check triggers:
 | retry_count >= 2 | "Document fix pattern?" | spec-add debug |
 | Summary contains design rationale ("chose X because") | "Record as knowhow?" | spec-add learning |
 
-On confirm → `Skill("spec-add", "<category> <content>")`.
+On confirm → `Skill("spec-add", "<category> <content> --description \"<summary>\"")`.
+Include `--description` with a one-line summary for search result display.
 
 ### Issue Status Sync
 
@@ -134,8 +158,7 @@ Status verdicts:
 
 | Condition | Suggestion |
 |-----------|-----------|
-| All tasks completed successfully | `/maestro-verify` |
-| Specific plan needs verification | `/maestro-verify --dir {dir}` |
+| All tasks completed successfully | `/quality-review` |
 | Failed tasks exist | `/quality-debug` |
 | View project dashboard | `/manage-status` |
 </completion>

package/.claude/commands/maestro-fork.md

@@ -42,6 +42,30 @@ Follow '~/.maestro/workflows/fork.md' completely.
 
 Fork and sync algorithm steps are defined in workflow `fork.md`.
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**Fork mode:**
+
+**GATE 1: Validation → Worktree Creation**
+- REQUIRED: Milestone resolved from state.json.milestones[].
+- REQUIRED: No existing active worktree for this milestone (E008).
+- REQUIRED: Not running inside a worktree (E003).
+
+**GATE 2: Worktree Creation → Artifact Copy**
+- REQUIRED: Git worktree created with branch (`milestone/{slug}`).
+- REQUIRED: Shared `.workflow/` files copied (project.md, roadmap.md, config.json, specs/).
+
+**GATE 3: Artifact Copy → Completion**
+- REQUIRED: `worktree-scope.json` written with milestone scope.
+- REQUIRED: Scoped `state.json` written (only this milestone's artifacts).
+- REQUIRED: `worktrees.json` registry updated in main worktree.
+
+**Sync mode:**
+
+**GATE: Sync → Completion**
+- REQUIRED: Git merge main into worktree branch completed.
+- REQUIRED: Shared artifacts re-copied.
+
 **Next-step routing on completion:**
 
 Fork mode:

package/.claude/commands/maestro-grill.md

@@ -50,7 +50,7 @@ $ARGUMENTS -- topic/plan text for interactive mode, or --from source for upstrea
 ### Pre-load
 
 1. **Specs**: `maestro spec load --category arch` — load architecture constraints
-2. **Wiki search**: `maestro wiki search "{topic keywords}"` → load relevant entries before grilling
+2. **Wiki search**: `maestro search "{topic keywords}"` → load relevant entries before grilling
 3. All optional — proceed without if unavailable
 </context>
 
@@ -71,6 +71,43 @@ Follows @~/.maestro/workflows/interview-mechanics.md standard.
 
 <execution>
 Follow '~/.maestro/workflows/grill.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Setup → Branch Walking** (Step 1 → Step 2)
+- REQUIRED: Topic parsed and output directory created.
+- REQUIRED: Initial codebase scan completed — at least one code reference identified for grounding.
+- BLOCKED if missing: cannot grill without code reality baseline.
+
+**GATE 2: Branch Walking → Synthesis** (Step 2 → Step 3)
+- REQUIRED: All depth-selected branches walked (shallow=3, standard=5, deep=8).
+- REQUIRED: Each branch has ≥2 Q&A pairs with evidence (code reference or explicit user input).
+- REQUIRED: Every locked decision has evidence — NOT just orchestrator inference.
+- BLOCKED if branches incomplete: continue walking before synthesizing.
+
+**GATE 3: Synthesis → Completion** (Step 3 → Report)
+- REQUIRED: `grill-report.md` written with Branch Log table + all Q&A entries + synthesis section.
+- REQUIRED: `terminology.md` written with ≥5 terms.
+- REQUIRED: `context-package.json` generated.
+- BLOCKED if any artifact missing: produce it before reporting completion.
+
+### Evidence Requirement
+
+Grill questions MUST reference specific code when challenging the user's proposal:
+- Valid: "The codebase uses `{symbol}` at `{file:line}` — your proposal calls it `{term}`. Which wins?"
+- INVALID: Generic questions without code grounding (e.g., "How would you handle errors?")
+- If codebase scan failed (W001): flag ALL subsequent locked decisions as LOW CONFIDENCE.
+
+### Artifact Verification (before completion)
+
+```
+REQUIRED_ARTIFACTS = [
+  "grill-report.md",        // Branch Log + Q&A + synthesis
+  "terminology.md",         // ≥5 terms with code refs
+  "context-package.json"    // Schema "context-package/1.0"
+]
+```
+If any missing: DO NOT report completion. Go back and produce the missing artifact.
 </execution>
 
 <completion>

package/.claude/commands/maestro-impeccable.md

@@ -253,3 +253,16 @@ When findings lack explicit suggested command:
 | Personality, memorability | delight |
 
 Never auto-select: teach, shape, craft, live, document, extract, overdrive, critique, audit.
+
+## Chain Phase Gates (MANDATORY for chain mode)
+
+**GATE: Quality Gate Step → Next Step**
+- REQUIRED: Score parsed from critique/audit output (not assumed or estimated).
+- REQUIRED: P0 count extracted from findings — P0 == 0 required for pass.
+- REQUIRED: If gate fails, refine commands executed and re-gate attempted.
+- Do NOT skip quality gate steps or mark as "passed" without parsing actual score.
+
+**GATE: Chain → Completion**
+- REQUIRED: All non-skipped steps executed (TodoWrite all completed).
+- REQUIRED: status.json updated with `status: "completed"` and final scores.
+- REQUIRED: If any step failed: documented in status.json with reason.

package/.claude/commands/maestro-init.md

@@ -59,6 +59,17 @@ Follows @~/.maestro/workflows/interview-mechanics.md standard.
 2. Validate `--from` source is accessible if provided
 
 Follow '~/.maestro/workflows/init.md' completely.
+
+### Artifact Verification (before completion)
+
+```
+REQUIRED_ARTIFACTS = [
+  ".workflow/project.md",    // Core Value, Requirements, Key Decisions
+  ".workflow/state.json",    // artifacts[], initialized to idle state
+  ".workflow/config.json"    // Workflow configuration
+]
+```
+If any artifact is missing: DO NOT report completion. Write the missing file first.
 </execution>
 
 <completion>