maestro-flow 0.4.26 → 0.5.1

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

@@ -41,8 +41,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):
@@ -77,7 +77,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}`
@@ -88,7 +88,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/.claude/commands/spec-add.md

@@ -24,6 +24,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)
 
@@ -34,12 +35,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/.claude/commands/spec-setup.md

@@ -12,7 +12,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/skills/codify-to-knowhow/phases/03-generate-specs.md

@@ -68,7 +68,8 @@ ${spec.body}
 
   // 追加到目标文件
   // 优先使用 maestro spec add CLI
-  const cliResult = Bash(`maestro spec add ${spec.category} "${spec.title}" "${spec.body}" --keywords "${spec.keywords}" 2>/dev/null`);
+  const descFlag = spec.description ? ` --description "${spec.description}"` : '';
+  const cliResult = Bash(`maestro spec add ${spec.category} "${spec.title}" "${spec.body}" --keywords "${spec.keywords}"${descFlag} 2>/dev/null`);
 
   if (cliResult.exitCode !== 0) {
     // 回退：直接追加到文件

package/.claude/skills/maestro-help/SKILL.md

@@ -195,7 +195,6 @@ $ARGUMENTS → Parse:
 | `/maestro-analyze` | 双层分析 — 宏观(文本参数)探索影响面 / 微观(数字参数)Phase 级深入 |
 | `/maestro-plan` | 任务规划 — 支持 `--from analyze:ANL-xxx` 直达 |
 | `/maestro-execute` | 任务执行 |
-| `/maestro-verify` | 验证确认 |
 
 ### 质量管线 (quality)
 
@@ -245,17 +244,17 @@ Roadmap > Milestone > Phase > Task
   roadmap — 消费上游 context，纯 Milestone > Phase 分解
 
 执行层
-  plan → execute → verify
+  plan → execute
 ```
 
 ### 合法路径
 
 | 路径 | 场景 | 命令序列 |
 |------|------|---------|
-| Path A | 完整新项目 | `brainstorm` → `blueprint`(可选) → `analyze "topic"` → `roadmap` → `analyze 1` → `plan 1` → `execute` → `verify` |
-| Path B | 旧项目大功能 | `analyze "feature X"` → `roadmap` → `analyze 1` → `plan 1` → `execute` → `verify` |
-| Path C | 中等功能 | `analyze "feature X"` → `plan --from analyze:ANL-xxx` → `execute` → `verify` |
-| Path D | 小改动 | `plan "fix auth bug"` → `execute` → `verify` |
+| Path A | 完整新项目 | `brainstorm` → `blueprint`(可选) → `analyze "topic"` → `roadmap` → `analyze 1` → `plan 1` → `execute` |
+| Path B | 旧项目大功能 | `analyze "feature X"` → `roadmap` → `analyze 1` → `plan 1` → `execute` |
+| Path C | 中等功能 | `analyze "feature X"` → `plan --from analyze:ANL-xxx` → `execute` |
+| Path D | 小改动 | `plan "fix auth bug"` → `execute` |
 | Path E | 纯规格文档 | `blueprint "project idea"` → (供人阅读) |
 | Path F | 纯探索 | `brainstorm "idea"` → (供人决策) |
 | 快速修复 | 已知简单问题 | `/maestro-quick "修复描述"` |

package/.claude/skills/maestro-help/index/catalog.json

@@ -13,7 +13,6 @@
     {"name": "maestro-analyze", "command": "/maestro-analyze", "category": "pipeline", "description": "双层分析 — 宏观(文本参数)探索影响面+scope_verdict / 微观(数字参数)Phase 级深入", "source": "../../commands/maestro-analyze.md"},
     {"name": "maestro-plan", "command": "/maestro-plan", "category": "pipeline", "description": "任务规划 — 支持 --from analyze:ANL-xxx 直达、碰撞检测、gap 修复计划", "source": "../../commands/maestro-plan.md"},
     {"name": "maestro-execute", "command": "/maestro-execute", "category": "pipeline", "description": "任务执行 — wave 并行执行、delegate 编排、自动提交", "source": "../../commands/maestro-execute.md"},
-    {"name": "maestro-verify", "command": "/maestro-verify", "category": "pipeline", "description": "验证确认 — 成果检查、gap 发现、下一阶段建议", "source": "../../commands/maestro-verify.md"},
     {"name": "maestro-quick", "command": "/maestro-quick", "category": "core", "description": "快速任务 — 跳过 Phase 管线直接完成，支持 --full/--discuss 模式", "source": "../../commands/maestro-quick.md"},
     {"name": "maestro-overlay", "command": "/maestro-overlay", "category": "core", "description": "Overlay 管理 — 创建、查看、删除命令补丁", "source": "../../commands/maestro-overlay.md"},
     {"name": "maestro-amend", "command": "/maestro-amend", "category": "core", "description": "修正补丁 — 从工作流信号自动生成 overlay", "source": "../../commands/maestro-amend.md"},
@@ -156,7 +155,6 @@
     "/maestro-roadmap",
     "/maestro-plan",
     "/maestro-execute",
-    "/maestro-verify",
     "/maestro-quick"
   ],
   "workflows": {
@@ -166,27 +164,27 @@
         "upstream_origin": ["brainstorm (发散/轻量)", "blueprint (收敛/重型)"],
         "understanding": "analyze 双层: 宏观(文本参数) + 微观(数字参数)",
         "orchestration": "roadmap (可选，消费上游 context)",
-        "execution": ["plan", "execute", "verify"]
+        "execution": ["plan", "execute"]
       }
     },
     "paths": {
-      "A_full_project": "brainstorm → blueprint(可选) → analyze 宏观 → roadmap → analyze 微观 → plan → execute → verify",
-      "B_large_feature": "analyze 宏观 → roadmap → analyze 微观 → plan → execute → verify",
-      "C_medium_feature": "analyze 宏观 → plan --from analyze:ANL-xxx → execute → verify",
-      "D_small_fix": "plan → execute → verify",
+      "A_full_project": "brainstorm → blueprint(可选) → analyze 宏观 → roadmap → analyze 微观 → plan → execute",
+      "B_large_feature": "analyze 宏观 → roadmap → analyze 微观 → plan → execute",
+      "C_medium_feature": "analyze 宏观 → plan --from analyze:ANL-xxx → execute",
+      "D_small_fix": "plan → execute",
       "E_spec_only": "blueprint → (供人阅读)",
       "F_explore_only": "brainstorm → (供人决策)"
     },
     "main_pipeline": {
       "name": "主干管线",
-      "phases": ["analyze", "plan", "execute", "verify"],
+      "phases": ["analyze", "plan", "execute"],
       "quality": ["quality-auto-test", "quality-review", "quality-test"],
       "close": ["maestro-milestone-audit", "maestro-milestone-complete"]
     },
     "quick": {
       "name": "快速渠道",
       "entry": "/maestro-quick",
-      "modes": ["default (analyze+execute)", "--full (analyze+plan+execute+verify)", "--discuss (multi-cli讨论)"]
+      "modes": ["default (analyze+execute)", "--full (analyze+plan+execute)", "--discuss (multi-cli讨论)"]
     },
     "issue_loop": {
       "name": "Issue 闭环",

package/.claude/skills/maestro-help/phases/02-search-present.md

@@ -69,7 +69,7 @@
 
 | 命令 | Guide 文档 |
 |------|-----------|
-| maestro-analyze/plan/execute/verify | `guide/command-usage-guide.md` (主干管线) |
+| maestro-analyze/plan/execute | `guide/command-usage-guide.md` (主干管线) |
 | maestro-init/roadmap/blueprint | `guide/quick-start-guide.md` |
 | maestro-ralph | `guide/maestro-ralph-guide.md` |
 | maestro (协调器) | `guide/maestro-coordinator-guide.md` |
@@ -97,9 +97,7 @@
 | roadmap 完成，phase=pending | `/maestro-analyze 1` | 微观分析：Phase 级深入探索 |
 | analyze (微观) 完成 | `/maestro-plan 1` | Phase 级规划 |
 | plan 完成 | `/maestro-execute` | 规划完成，开始执行 |
-| execute 完成 | `/maestro-verify` | 执行完成，验证成果 |
-| verify 有 gaps | `/maestro-analyze --gaps` | 发现差距，重新分析 |
-| verify 通过 | `/quality-review` | 进入质量管线 |
+| execute 完成 | `/quality-review` | 执行完成，进入质量管线 |
 | quality 全通过 | `/maestro-milestone-audit` | 准备里程碑审计 |
 | 所有 Phase 完成 | `/maestro-milestone-complete` | 里程碑可以关闭 |
 

package/.claude/skills/maestro-help/phases/03-workflow-guide.md

@@ -45,7 +45,7 @@ const taskPatterns = [
 4. `/maestro-analyze "topic"` — 宏观分析，探索影响面 → scope_verdict
 5. `/maestro-roadmap --from analyze:ANL-xxx` — 纯编排，Milestone > Phase 分解
 6. `/maestro-analyze 1` — 微观分析，Phase 级深入
-7. `/maestro-plan 1` → `/maestro-execute` → `/maestro-verify`
+7. `/maestro-plan 1` → `/maestro-execute`
 
 ### 路径 E: 纯规格文档（不进执行链）
 1. `/maestro-blueprint "project idea"` — 供人阅读和决策
@@ -62,7 +62,7 @@ const taskPatterns = [
 1. `/maestro-analyze "feature X"` — 宏观分析 → scope_verdict=large
 2. `/maestro-roadmap --from analyze:ANL-xxx` — Milestone > Phase 分解
 3. `/maestro-analyze 1` — 微观分析
-4. `/maestro-plan 1` → `/maestro-execute` → `/maestro-verify`
+4. `/maestro-plan 1` → `/maestro-execute`
 ```
 
 **中等功能 — Path C** (复杂度: 中，跳过 roadmap):
@@ -72,7 +72,7 @@ const taskPatterns = [
 
 1. `/maestro-analyze "feature X"` — 宏观分析 → scope_verdict=medium
 2. `/maestro-plan --from analyze:ANL-xxx` — 直达规划，跳过 roadmap
-3. `/maestro-execute` → `/maestro-verify`
+3. `/maestro-execute`
 
 ### 快速渠道（简单功能）
 1. `/maestro-quick "功能描述"` — 一键完成
@@ -87,7 +87,7 @@ const taskPatterns = [
 ## 小改动工作流
 
 1. `/maestro-plan "fix auth bug"` — 直接规划
-2. `/maestro-execute` → `/maestro-verify`
+2. `/maestro-execute`
 
 ### 快速修复（已知问题）
 1. `/maestro-quick "修复 Bug 描述"`
@@ -131,7 +131,7 @@ const taskPatterns = [
 上游起源: brainstorm(发散) | blueprint(收敛) → 可选
 理解层:   analyze "topic"(宏观) → scope_verdict 路由
 编排层:   roadmap(可选，仅 scope_verdict=large 时建议)
-执行层:   plan → execute → verify → quality → milestone-audit → milestone-complete
+执行层:   plan → execute → quality → milestone-audit → milestone-complete
 快速渠道: maestro-quick → (直接完成)
 Issue 闭环: discover → create → analyze --gaps → plan --gaps → execute → close
 全自动: /maestro -y → (自动路由)
@@ -146,7 +146,7 @@ Issue 闭环: discover → create → analyze --gaps → plan --gaps → execute
 
 - **Roadmap**: 项目级常驻规划文档，包含多个 Milestone
 - **Milestone**: 可独立交付的版本节点（v0.1.0-rc1），包含多个 Phase
-- **Phase**: Milestone 内的同步屏障执行阶段，走 analyze → plan → execute → verify 生命周期
+- **Phase**: Milestone 内的同步屏障执行阶段，走 analyze → plan → execute 生命周期
 - **Task**: Phase 内的具体代码修改单元（wave DAG 管理并行）
 - **Blueprint**: 正式规格文档化命令（7-phase 收敛），与 brainstorm 并列作为上游起源
 - **Analyze 双层**: 宏观(文本参数)探索影响面产出 scope_verdict；微观(数字参数)Phase 级深入分析
@@ -179,8 +179,7 @@ Issue 闭环: discover → create → analyze --gaps → plan --gaps → execute
 | 6 | `/maestro-roadmap` | 路线图编排 | scope_verdict=large 时，Milestone > Phase 分解 |
 | 7 | `/maestro-plan` | 规划 | 分析完成后生成执行计划，支持 `--from analyze:ANL-xxx` 直达 |
 | 8 | `/maestro-execute` | 执行 | 计划完成后，执行实现 |
-| 9 | `/maestro-verify` | 验证 | 执行完成后，检查成果 |
-| 10 | `/maestro-quick` | 快速任务 | 简单任务跳过管线 |
+| 9 | `/maestro-quick` | 快速任务 | 简单任务跳过管线 |
 ```
 
 #### Step 5.2: 快速入门路径

package/.codex/skills/codify-to-knowhow/SKILL.md

@@ -56,7 +56,7 @@ $codify-to-knowhow ".workflow/reference_style/my-style-v1"
 - `<package-path>` (positional, required): Directory containing `knowhow-manifest.json`
 
 **Upstream**: `maestro-ui-codify`, `learn-decompose`, or any skill that generates a manifest
-**Downstream**: `maestro wiki list --category coding`, `maestro spec load --keyword <slug>`
+**Downstream**: `maestro search --category coding`, `maestro spec load --keyword <slug>`
 </context>
 
 <manifest_schema>
@@ -246,7 +246,7 @@ type: ${asset.category}`;
     for (let i = 0; i < asset.entries.length; i++) {
       const entry = asset.entries[i];
       const entryId = `${asset.prefix}-${manifest.slug}-${String(i + 1).padStart(3, '0')}`;
-      body += `\n\n<knowhow-entry keywords="${entry.category},${entry.keywords}" date="${today}" id="${entryId}" roles="${manifest.roles.join(',')}" source="codify-to-knowhow">
+      body += `\n\n<knowhow-entry keywords="${entry.category},${entry.keywords}" date="${today}" title="${entry.title}" description="${entry.description || ''}" id="${entryId}" roles="${manifest.roles.join(',')}" source="codify-to-knowhow">
 
 ### ${entry.title}
 
@@ -303,7 +303,7 @@ for (const spec of manifest.specs) {
 
   const entryBlock = `
 
-<spec-entry roles="${manifest.roles.join(',')}" keywords="${spec.keywords}" date="${today}"${refAttr}>
+<spec-entry roles="${manifest.roles.join(',')}" keywords="${spec.keywords}" date="${today}" title="${spec.title}" description="${spec.description || ''}"${refAttr}>
 
 ### ${spec.title}
 
@@ -312,7 +312,8 @@ ${spec.body}
 </spec-entry>`;
 
   // Prefer CLI, fallback to direct append
-  const cliResult = Bash(`maestro spec add ${spec.category} "${spec.title}" "${spec.body}" --keywords "${spec.keywords}" 2>/dev/null`);
+  const descFlag = spec.description ? ` --description "${spec.description}"` : '';
+  const cliResult = Bash(`maestro spec add ${spec.category} "${spec.title}" "${spec.body}" --keywords "${spec.keywords}"${descFlag} 2>/dev/null`);
 
   if (cliResult.exitCode !== 0) {
     // Fallback: direct file append
@@ -396,7 +397,7 @@ Ref Links: spec -> knowhow bridge established
 Wiki Index: refreshed
 
 Next steps:
-  maestro wiki list --category coding    # Browse by role
+  maestro search --category coding    # Browse by role
   maestro spec load --keyword {slug}    # Load related specs
   maestro wiki load <id>                # Load full entry
 ```

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

@@ -50,7 +50,7 @@ $ARGUMENTS — target path/module and optional flags.
 Parse flags from `$ARGUMENTS`: `-y`/`--yes`, `--patterns <list>`, `--save-spec`, `--save-wiki`, `--continue`, `-c N`.
 Extract remaining text as target path/module.
 
-Resolve target to file list. Load coding specs: `maestro spec load --category coding` for documented patterns and conventions. Load existing patterns from `coding-conventions.md` + `.workflow/specs/learnings.md` for dedup set. Browse wiki: `maestro wiki list --category coding`, load relevant entries.
+Resolve target to file list. Load coding specs: `maestro spec load --category coding` for documented patterns and conventions. Load existing patterns from `coding-conventions.md` + `.workflow/specs/learnings.md` for dedup set. Browse wiki: `maestro search --category coding`, load relevant entries.
 
 ### Phase 2: Wave 1 — Parallel Dimension Scans
 

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

@@ -20,7 +20,7 @@ $ARGUMENTS — target and optional flags.
 **Target resolution (auto-detected):**
 - File path → Read source file
 - Wiki ID (`type-slug`) → Fetch via `maestro wiki get`
-- Topic string → Search via `maestro wiki search`, use top result
+- Topic string → Search via `maestro search`, use top result
 
 **Flags:**
 - `--depth shallow` — Key patterns and structure only (default)

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

@@ -29,7 +29,7 @@ $ARGUMENTS — question text and optional flags.
 ### Stage 1: Frame the Question
 - Parse question, generate slug, create investigation directory
 - Load debug specs: `maestro spec load --category debug` for known issues and patterns
-- Search prior knowledge: `maestro wiki list --category debug`, wiki search, grep .workflow/specs/learnings.md
+- Search prior knowledge: `maestro search --category debug`, wiki search, grep .workflow/specs/learnings.md
 - Write initial `understanding.md`
 
 ### Stage 2: Evidence Collection

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

@@ -34,7 +34,7 @@ $ARGUMENTS — target and optional flags.
 <execution>
 
 ### Phase 1: Resolve Target + Load Context
-Resolve target to content. Load specs, wiki search, prior lessons for context brief.
+Resolve target to content. Load specs, `maestro search`, prior lessons for context brief.
 
 ### Phase 2: Execute Mode
 

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

@@ -43,7 +43,7 @@ $ARGUMENTS — user intent text, or special flags.
 3. **Decomposition contract shared with maestro-ralph** — broad/lifecycle intents run S_DECOMPOSE producing the SAME additive block (`boundary_contract`, `execution_criteria`, `task_decomposition`). Reference maestro-ralph `A_DECOMPOSE_TASKS`
 4. **Goal is tool-created** — `A_DECOMPOSE_TASKS` calls `create_goal` with sub-goal success criteria. `update_goal` on convergence; held while aborted/paused
 5. **status.json 唯一真源** — 不生成 `goal-checklist.md`；step 含 `command_scope` + `command_path` + `completion_confirmed`
-6. **Topology awareness** — chain catalog 含 grill / brainstorm / blueprint / analyze-macro(text) / analyze(numeric) / roadmap / plan(三路径) / execute / verify / ...
+6. **Topology awareness** — chain catalog 含 grill / brainstorm / blueprint / analyze-macro(text) / analyze(numeric) / roadmap / plan(三路径) / execute / ...
 6.5. **Grill is interactive-only** — auto_mode MUST skip grill stage and route directly to brainstorm; grill requires Socratic Q&A with the user
 7. **D-007 milestone 反查** — 数字 phase 步骤的 `milestone_id` 由 `state.json.milestones[].phase_slugs` 反查
 8. **schema 向后兼容** — decomposition 字段可选；`steps[]` 由 post-goal-audit 动态生长（goal_ref tagged）；既有字段不删不改；`waves` 保留空数组
@@ -164,7 +164,7 @@ Extract:
 | `plan` | Plan, design, architect a phase |
 | `execute` | Implement, develop, code a phase |
 | `analyze` | Understand, investigate, evaluate code (numeric phase) |
-| `verify` | Check goals met, validate results |
+| `verify` | Check goals met, validate results (routes to quality-review) |
 | `review` | Code quality review |
 | `test` | Run or create tests, UAT |
 | `test_gen` | Generate tests for coverage gaps |
@@ -188,17 +188,17 @@ Extract:
 | `issue_analyze` | Analyze a specific issue |
 | `issue_plan` | Plan fix for an issue |
 | `issue_execute` | Fix issue end-to-end (auto-upgrades to issue-full) |
-| `feature` | Standard feature: plan→execute→verify |
-| `full-lifecycle` | Complete phase: plan→execute→verify→review→test→audit→complete |
+| `feature` | Standard feature: plan→execute→review |
+| `full-lifecycle` | Complete phase: plan→execute→review→test→audit→complete |
 | `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 |
+| `execute-review` | Resume after planning |
 | `review-fix` | Fix review-blocked issues |
 | `quality-loop` | Full quality improvement cycle |
 | `quality-loop-partial` | Partial quality fix |
-| `quality-fix` | Analyze gaps→plan→execute→verify |
+| `quality-fix` | Analyze gaps→plan→execute→review |
 | `deploy` | Verify then release |
 | `milestone-close` | Close/transition milestone |
 | `milestone-release` | Release milestone with version tag |
@@ -235,16 +235,14 @@ Read `.workflow/state.json` and route by condition:
 | No phases | `brainstorm-driven` |
 | pending + has context | `plan` |
 | pending, no context | `analyze` |
-| exploring/planning + has plan | `execute-verify` |
+| exploring/planning + has plan | `execute-review` |
 | 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` |
+| reviewing, verdict == BLOCK | `review-fix` |
+| reviewing, verdict != BLOCK + UAT pending | `test` |
+| reviewing, verdict != BLOCK + UAT passed | `milestone-close` |
+| reviewing, verdict != BLOCK + UAT failed | `debug` |
 | testing, UAT passed | `milestone-close` |
 | testing, UAT not passed | `debug` |
 | completed | `milestone-close` |
@@ -353,7 +351,7 @@ S_DECISION_EVAL 入口；镜像 maestro-ralph `A_GOAL_AUDIT_EVALUATE`。Condense
 
 ### A_APPLY_GOAL_FIX
 
-**Dynamic step-growth core** (mirrors maestro-ralph). For each unmet sub-goal (grouped by target_phase), insert before the post-goal-audit node a scoped mini-loop `$maestro-plan --gaps {phase} "G{n}: {gap}" → $maestro-execute {phase} → $maestro-verify {phase}`, each tagged `goal_ref: "G{n}"`, type `"skill"`. Re-append `decision:post-goal-audit {retry+1}`. Reindex, increment retry, persist + `update_plan`. `steps[]` grew.
+**Dynamic step-growth core** (mirrors maestro-ralph). For each unmet sub-goal (grouped by target_phase), insert before the post-goal-audit node a scoped mini-loop `$maestro-plan --gaps {phase} "G{n}: {gap}" → $maestro-execute {phase}`, each tagged `goal_ref: "G{n}"`, type `"skill"`. Re-append `decision:post-goal-audit {retry+1}`. Reindex, increment retry, persist + `update_plan`. `steps[]` grew.
 
 ### A_APPLY_GOAL_DONE
 
@@ -398,7 +396,7 @@ S_DECISION_EVAL 入口；镜像 maestro-ralph `A_GOAL_AUDIT_EVALUATE`。Condense
 | `plan_from_analyze` | `maestro-plan --from analyze:{analyze_macro_id}` |
 | `plan_from_blueprint` | `maestro-plan --from blueprint:{blueprint_id}` |
 | `execute` | `maestro-execute {phase}` |
-| `verify` | `maestro-verify {phase}` |
+| `verify` | `quality-review {phase}` |
 | `test_gen` | `quality-auto-test {phase}` |
 | `auto_test` | `quality-auto-test {phase}` |
 | `test` | `quality-test {phase}` |
@@ -443,27 +441,27 @@ S_DECISION_EVAL 入口；镜像 maestro-ralph `A_GOAL_AUDIT_EVALUATE`。Condense
 
 | Chain | Steps (→ = sequential, [B] = context-producing barrier) |
 |-------|---------------------------------------|
-| `feature` | [B] maestro-plan → [B] maestro-execute → maestro-verify |
-| `quality-fix` | [B] maestro-analyze --gaps → [B] maestro-plan --gaps → [B] maestro-execute → maestro-verify |
-| `deploy` | maestro-verify → maestro-milestone-release |
-| `blueprint-driven` | maestro-init → [B] maestro-blueprint → [B] maestro-plan --from blueprint:{BLP} → [B] maestro-execute → maestro-verify |
-| `analyze-macro-driven` | [B] maestro-analyze "{intent}" → ◆ post-analyze-scope → (large: [B] maestro-roadmap --from analyze:{ANL} → [B] maestro-analyze {phase} → [B] maestro-plan {phase}) / (medium\|small: [B] maestro-plan --from analyze:{ANL}) → [B] maestro-execute → maestro-verify |
-| `grill-brainstorm` | [B] maestro-grill → [B] maestro-brainstorm --from grill:{GRL} → [B] maestro-plan → [B] maestro-execute → maestro-verify (**auto_mode: skip grill step, fall back to brainstorm-driven**) |
-| `brainstorm-driven` | [B] maestro-brainstorm → [B] maestro-plan → [B] maestro-execute → maestro-verify |
-| `ui-craft-build` | maestro-impeccable build → [B] maestro-plan → [B] maestro-execute → maestro-verify |
-| `roadmap-driven` | maestro-init → [B] maestro-roadmap → [B] maestro-plan → [B] maestro-execute → maestro-verify |
-| `next-milestone` | [B] maestro-roadmap → [B] maestro-plan → [B] maestro-execute → maestro-verify |
-| `full-lifecycle` | [B] maestro-plan → [B] maestro-execute → maestro-verify → quality-review → quality-test → maestro-milestone-audit → maestro-milestone-complete |
-| `execute-verify` | [B] maestro-execute → maestro-verify |
+| `feature` | [B] maestro-plan → [B] maestro-execute → quality-review |
+| `quality-fix` | [B] maestro-analyze --gaps → [B] maestro-plan --gaps → [B] maestro-execute → quality-review |
+| `deploy` | quality-review → maestro-milestone-release |
+| `blueprint-driven` | maestro-init → [B] maestro-blueprint → [B] maestro-plan --from blueprint:{BLP} → [B] maestro-execute → quality-review |
+| `analyze-macro-driven` | [B] maestro-analyze "{intent}" → ◆ post-analyze-scope → (large: [B] maestro-roadmap --from analyze:{ANL} → [B] maestro-analyze {phase} → [B] maestro-plan {phase}) / (medium\|small: [B] maestro-plan --from analyze:{ANL}) → [B] maestro-execute → quality-review |
+| `grill-brainstorm` | [B] maestro-grill → [B] maestro-brainstorm --from grill:{GRL} → [B] maestro-plan → [B] maestro-execute → quality-review (**auto_mode: skip grill step, fall back to brainstorm-driven**) |
+| `brainstorm-driven` | [B] maestro-brainstorm → [B] maestro-plan → [B] maestro-execute → quality-review |
+| `ui-craft-build` | maestro-impeccable build → [B] maestro-plan → [B] maestro-execute → quality-review |
+| `roadmap-driven` | maestro-init → [B] maestro-roadmap → [B] maestro-plan → [B] maestro-execute → quality-review |
+| `next-milestone` | [B] maestro-roadmap → [B] maestro-plan → [B] maestro-execute → quality-review |
+| `full-lifecycle` | [B] maestro-plan → [B] maestro-execute → quality-review → quality-test → maestro-milestone-audit → maestro-milestone-complete |
+| `execute-review` | [B] maestro-execute → quality-review |
 | `analyze-plan-execute` | [B] maestro-analyze -q → [B] maestro-plan --dir {scratch_dir} → [B] maestro-execute --dir {scratch_dir} |
-| `quality-loop` | maestro-verify → quality-review → quality-test → quality-debug --from-uat → [B] maestro-plan --gaps → [B] maestro-execute |
-| `quality-loop-partial` | [B] maestro-plan --gaps → [B] maestro-execute → maestro-verify |
+| `quality-loop` | quality-review → quality-test → quality-debug --from-uat → [B] maestro-plan --gaps → [B] maestro-execute |
+| `quality-loop-partial` | [B] maestro-plan --gaps → [B] maestro-execute → quality-review |
 | `review-fix` | [B] maestro-plan --gaps → [B] maestro-execute → quality-review |
 | `milestone-close` | maestro-milestone-audit → maestro-milestone-complete |
 | `milestone-release` | maestro-milestone-audit → maestro-milestone-release |
 | `phase_transition` | maestro-milestone-audit → maestro-milestone-complete |
 | `issue-full` | [B] maestro-analyze --gaps → [B] maestro-plan --gaps → [B] maestro-execute → quality-review → manage-issue close |
-| `issue-quick` | [B] maestro-plan --gaps → [B] maestro-execute → manage-issue close |
+| `issue-quick` | [B] maestro-plan --gaps → [B] maestro-execute → quality-review → manage-issue close |
 
 > When S_DECOMPOSE ran, a `decision:post-goal-audit` node is appended as the final node (after the last evidence-producing step; before milestone-complete/close-out if the chain ends with one). `[B]` now denotes a context-producing skill (artifacts read into `session.context`) — execution is still sequential (no parallelism; spawning removed).
 

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

@@ -37,7 +37,7 @@ $ARGUMENTS -- phase number, topic text, and optional flags.
 Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `--continue`, or input is already specific (explicit phase number or unambiguous topic).
 
 - One decision per turn via AskUserQuestion 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`, `roadmap.md`, `issues.jsonl`, `maestro spec load`, `maestro wiki search`, 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`, `roadmap.md`, `issues.jsonl`, `maestro spec load`, `maestro search`, 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 `context.md` "Interview Decisions" (and mirrored into `analysis.md` in full mode). Do NOT batch writeback to the end — partial decisions must already be on disk before the next question.
 - Walk the decision dependency tree strictly: scope → depth → dimensions → Go/No-Go threshold. Do not open the next branch until the current one is settled.
 - Scope guard: only ask about decisions owned by `analyze`. Do not prejudge plan/execute concerns.
@@ -87,6 +87,9 @@ Available exploration dimensions: architecture, implementation, performance, sec
 8. **Tri-output**: context.md + context-package.json always. analysis.md (full only) + conclusions.json (full + quick — quick writes minimal with `scope_verdict` + `implementation_scope[]`). Gaps mode writes to issues.jsonl + context.md + context-package.json
 9. **D-007 milestone resolution**: numeric scope MUST reverse-lookup `state.json.milestones[].phase_slugs`. NEVER read `current_milestone` directly for phase-scoped artifact registration.
 10. **scope_verdict mandatory** (D-003): macro/adhoc/standalone scopes MUST produce `scope_verdict ∈ {small, medium, large}` in conclusions.json. Drives downstream chain (roadmap vs plan).
+11. **Invariant violation = BLOCK** — violating any invariant above blocks the current operation. Do NOT bypass for "efficiency" or "clear intent" reasons.
+12. **Evidence required on decisions** — every decision in context.md MUST cite evidence from Wave 1 exploration findings or Wave 2 scores. Decisions citing only orchestrator's manual file reading are flagged LOW CONFIDENCE.
+13. **Degradation must be marked** — when graceful degradation (invariant 7) activates, ALL downstream outputs inherit a LOW CONFIDENCE flag. Record in discoveries.ndjson: `{ type: "degradation_event", data: { wave, failed_tasks, impact } }`.
 </invariants>
 
 <state_machine>
@@ -231,7 +234,7 @@ Gray area detection: domain-aware (things users SEE/CALL/RUN/READ), phase-specif
 1. Export results.csv
 2. **Confidence scoring** (full mode): factors -- findings_depth(.30), evidence_strength(.25), coverage_breadth(.20), user_validation(.15), consistency(.10). Thresholds: <60% deeper, 60-80% optional, 80-95% converging, >95% converge.
 3. Auto-create issues from Deferred items -> issues.jsonl
-4. Spec enrichment: Locked decisions -> `maestro spec add arch`; code patterns -> `maestro spec add coding`
+4. Spec enrichment: Locked decisions -> `maestro spec add arch "<title>" "<content>" --keywords <kw> --description "<summary>"`; code patterns -> `maestro spec add coding "<title>" "<content>" --keywords <kw> --description "<summary>"`
 5. Register artifact in state.json (type: analyze, includes context_package field pointing to context-package.json)
 6. Copy outputs to scratchDir, display summary
 7. **Next-step routing** (D-003 §5.3 — macro scope uses `scope_verdict` for downstream chain selection):
@@ -250,6 +253,16 @@ Gray area detection: domain-aware (things users SEE/CALL/RUN/READ), phase-specif
 
 </actions>
 
+### Artifact Verification (before S_AGGREGATE)
+
+Before transitioning to S_AGGREGATE, verify ALL expected outputs exist:
+```
+FULL_MODE_REQUIRED = ["tasks.csv", "context.md", "context-package.json", "analysis.md", "conclusions.json"]
+QUICK_MODE_REQUIRED = ["tasks.csv", "context.md", "context-package.json", "conclusions.json"]
+GAPS_MODE_REQUIRED = ["tasks.csv", "context.md", "context-package.json"]
+```
+If any artifact is missing for the active mode: DO NOT proceed to S_AGGREGATE. Go back and produce the missing artifact.
+
 </state_machine>
 
 <discovery_board>
@@ -272,8 +285,8 @@ Protocol: read before analysis, append-only, dedup by type+key.
 | --gaps but no issues found | Abort: "No open/registered issues" |
 | --gaps ISS-ID not found | Abort: "Issue not found" |
 | Phase directory not found | List available phases, abort |
-| All exploration agents failed | Proceed to scoring with limited context |
-| All scoring agents failed | Skip analysis.md, decision extraction only |
+| All exploration agents failed | Retry once. If still fails: proceed to scoring but flag ALL downstream decisions as LOW CONFIDENCE in discoveries.ndjson |
+| All scoring agents failed | Retry once. If still fails: produce decision-only context.md but flag ALL decisions as LOW CONFIDENCE |
 | Synthesis agent failed | Minimal context.md from raw scores/exploration |
 | Continue mode: no session found | List available sessions |
 </error_codes>

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

@@ -88,6 +88,13 @@ P6 gate: Pass (>=80%) → Handoff | Review (60-79%) → Handoff w/caveats | Fail
 | Need project setup | /maestro-init |
 </execution>
 
+<invariants>
+1. **Invariant violation = BLOCK** — violating any invariant above blocks the current operation.
+2. **Phase gate enforcement** — each phase produces artifacts that are prerequisites for the next. Do NOT advance to phase N+1 without verifying phase N's output exists: P2→product-brief.md, P3→requirements/_index.md, P4→architecture/_index.md, P5→epics/_index.md, P6→readiness-report.md.
+3. **Evidence required on ADRs** — Architecture Decision Records (ADR-*.md) MUST cite evidence (code analysis, requirement traceability REQ-xxx, upstream context). Generic rationale without project-specific references is INVALID.
+4. **Artifact verification before completion** — verify blueprint-config.json, product-brief.md, glossary.json (≥5 terms), requirements/_index.md, architecture/_index.md, epics/_index.md, readiness-report.md, blueprint-summary.md, context-package.json all exist. If any missing: DO NOT report completion.
+</invariants>
+
 <error_codes>
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
@@ -95,7 +102,7 @@ P6 gate: Pass (>=80%) → Handoff | Review (60-79%) → Handoff w/caveats | Fail
 | E002 | error | Context source not found (--from) | Show available sessions/sources |
 | E006 | error | `.workflow/` not initialized | Run maestro-init first |
 | E007 | error | Phase 6 readiness Fail after 2 auto-fix iterations | Present manual fix options |
-| W001 | warning | CLI analysis failed, using fallback | Continue with available data |
+| W001 | warning | CLI analysis failed | Retry once. If still fails: continue but flag affected phase outputs as LOW CONFIDENCE |
 | W002 | warning | Codebase exploration failed | Continue without codebase context |
 | W003 | warning | Glossary has < 5 terms | Note in readiness check |
 | W004 | warning | Review-level readiness score (60-79%) | Proceed with caveats |

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

@@ -21,7 +21,7 @@ $ARGUMENTS — topic text and optional flags.
 
 ### Pre-load specs
 1. **Architecture specs**: `maestro spec load --category arch` — load architecture constraints as context for multi-role design (roles respect documented decisions).
-2. **Role Knowledge**: `maestro wiki list --category arch` → identify relevant entries → `maestro wiki load <id1> [id2...]`
+2. **Role Knowledge**: `maestro search --category arch` → identify relevant entries → `maestro wiki load <id1> [id2...]`
 3. Both optional — proceed without if unavailable.
 
 **Session**: `.workflow/.csv-wave/{YYYYMMDD}-brainstorm-{slug}/`
@@ -40,7 +40,7 @@ $ARGUMENTS — topic text and optional flags.
 Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `--skip-questions`, `--continue` (existing session), or input is already specific.
 
 - 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`, the session directory, `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`, the session directory, `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 time a decision settles, immediately append/update its row in `guidance-specification.md` §11 (create the section if absent). Do NOT batch writeback to the end — partial decisions must already be on disk before the next question.
 - Branch jumps allowed: the user may switch freely between mode / role / upstream / sub-pipeline branches; sequence is not enforced, but every decision point must end with a definite answer.
 - Scope guard: only ask about decisions owned by `brainstorm`. Do not pre-resolve roadmap/plan choices.
@@ -210,6 +210,9 @@ CONSTRAINTS:
 5. **9 valid roles only**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
 6. **Wave 3 is read-only at the agent boundary**: the reviewer emits structured findings (conflicts / gaps / synergies with `patch_targets[]`). The orchestrator (not the agent) applies the patches via Edit.
 7. **DO NOT STOP**: Continuous until all waves complete; only pause at [CHECKPOINT] (skipped with -y).
+8. **Invariant violation = BLOCK** — violating any invariant above blocks the current operation. Do NOT bypass for "efficiency" or "clear intent" reasons.
+9. **Evidence required** — role analysis findings in {role}/analysis.md §2 Decision Digest MUST cite concrete evidence: code references (file:line), API endpoints, data models from codebase exploration. Decisions without evidence are flagged LOW CONFIDENCE.
+10. **Artifact verification before completion** — before reporting completion, verify ALL expected artifacts exist: guidance-specification.md, {role}/analysis.md (per selected role), {role}/analysis-F-*.md (per feature). If any missing: DO NOT report completion.
 </invariants>
 
 <spawn_contract>
@@ -288,7 +291,7 @@ S_CHECK_1 → END        WHEN: user "Abort"
 
 S_DESIGN → S_WAVE_2    WHEN: DESIGN.md exists OR explore completed    DO: A_DESIGN_EXPLORE
 S_DESIGN → S_WAVE_2    WHEN: DESIGN.md already exists (skip explore)
-S_DESIGN → S_WAVE_2    WHEN: explore failed → W004 → continue without
+S_DESIGN → S_WAVE_2    WHEN: explore failed → W004 → retry once. If still fails: flag downstream outputs as LOW CONFIDENCE, continue without
 
 S_WAVE_2 → S_CHECK_2   DO: spawn wave-2 (parallel), merge results — each agent writes {role}/analysis.md + sub-files
 S_WAVE_2 → S_AGGREGATE WHEN: all failed       DO: skip review
@@ -405,8 +408,8 @@ Protocol: read before analysis, append-only, dedup by type+key.
 | Condition | Recovery |
 |-----------|----------|
 | Guidance agent failed | Abort pipeline (W2 depends on guidance) |
-| All role agents failed | Skip review, report partial |
-| Review agent failed | Use analysis files directly, no resolution writeback |
+| All role agents failed | Skip review, report partial. Retry once. If still fails: flag downstream outputs as LOW CONFIDENCE |
+| Review agent failed | Use analysis files directly, no resolution writeback. Retry once. If still fails: flag downstream outputs as LOW CONFIDENCE |
 | Role count > 9 | Cap at 9 with warning |
 | E006 --review-only but no */analysis.md | Run auto mode or single roles first |
 | E007 --review-only but missing guidance-specification.md | Run auto mode first |

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

@@ -275,7 +275,7 @@ Generate 3 output files from cross-verify results:
 
 1. Copy outputs to scratchDir
 2. Register CLB artifact in state.json (type: collab, scope: adhoc)
-3. Spec enrichment: for each Locked decision → `maestro spec add arch`
+3. Spec enrichment: for each Locked decision → `maestro spec add arch "<title>" "<content>" --keywords <kw> --description "<summary>"`
 4. `update_plan` all steps completed
 5. Display summary:
    ```