maestro-flow 0.4.26 → 0.5.0

package/workflows/status.md

@@ -77,7 +77,7 @@ CONTEXT: key_decisions, blockers, deferred
 If issue_state exists: display ISSUES panel (open count, critical count, by-status breakdown, critical issues list).
 - Omit critical sub-section if none. Note blockers→issues migration if applicable. Note deferred items.
 
-If issue_state is null: "No issues tracked. Use /manage-issue create or /maestro-verify to discover issues."
+If issue_state is null: "No issues tracked. Use /manage-issue create to discover issues."
 
 Status icons:
 - `[x]` completed
@@ -116,7 +116,7 @@ Based on current project state, suggest the next command:
 | Phase pending, needs decisions | /maestro-analyze \<N\> -q |
 | Phase planned, not executed | /maestro-execute \<N\> |
 | Phase executing, tasks blocked | /quality-debug \<N\> |
-| Phase executed, not verified | /maestro-verify \<N\> |
+| Phase executed, not verified | /quality-review \<N\> |
 | Phase verified with gaps | /maestro-plan \<N\> --gaps |
 | Phase verified, not reviewed | /quality-review \<N\> |
 | Phase reviewed, BLOCK verdict | /maestro-plan \<N\> --gaps |

package/workflows/swarm/wf-verify.js

@@ -1,7 +1,7 @@
 export const meta = {
   name: 'wf-verify',
   description: 'Three-layer verification with prosecutor/defender/judge adversarial aggregation',
-  whenToUse: 'Accelerate maestro-verify with parallel layer checks + adversarial pass/fail determination',
+  whenToUse: 'Accelerate maestro-execute verification gate with parallel layer checks + adversarial pass/fail determination',
   phases: [
     { title: 'Check', detail: 'Parallel 3-layer verification + anti-pattern scan via workflow-verifier' },
     { title: 'Argue', detail: 'Prosecutor argues FAIL, Defender argues PASS — adversarial positions' },

package/workflows/test-gen.md

@@ -1,6 +1,6 @@
 # Test Generation Workflow
 
-Generate missing automated tests for a phase based on gap analysis from maestro-verify (Nyquist audit) and quality-test (UAT coverage gaps). Classifies changed files into unit/E2E/skip, discovers test infrastructure, generates a test plan for user approval, then writes tests using RED-GREEN methodology.
+Generate missing automated tests for a phase based on gap analysis from maestro-execute verification gate (Nyquist audit) and quality-test (UAT coverage gaps). Classifies changed files into unit/E2E/skip, discovers test infrastructure, generates a test plan for user approval, then writes tests using RED-GREEN methodology.
 
 Tests expose bugs -- fixing is for quality-debug or maestro-execute.
 
@@ -220,7 +220,7 @@ Display: phase, framework, files/cases generated, passing/failing counts,
 
 | Result | Suggestion |
 |--------|------------|
-| All tests passing | Skill({ skill: "maestro-verify", args: "{phase}" }) to update Nyquist coverage |
+| All tests passing | Skill({ skill: "quality-review", args: "{phase}" }) to update Nyquist coverage |
 | Bugs discovered (failing tests) | Skill({ skill: "quality-debug", args: "--from-uat {phase}" }) to investigate |
 | Regressions found | Skill({ skill: "quality-debug" }) immediately |
 | Coverage still low | Run again with `--layer` for uncovered layers |

package/workflows/test.md

@@ -402,7 +402,7 @@ Execute the loop: plan --gaps -> execute -> re-verify.
 
 1. Run Skill({ skill: "maestro-plan", args: "{phase} --gaps" }) -- generates fix tasks from gaps
 2. Run Skill({ skill: "maestro-execute", args: "{phase}" }) -- executes fix tasks
-3. Run Skill({ skill: "maestro-verify", args: "{phase}" }) -- re-verify
+3. Run Skill({ skill: "maestro-execute", args: "{phase}" }) -- re-verify via verification gate
 
 If re-verify passes: update uat.md gaps as resolved, report success.
 If re-verify still has gaps: report remaining gaps, suggest manual intervention.

package/workflows/updates/README.md

@@ -0,0 +1,41 @@
+# Update Scripts
+
+Version-specific smart upgrade workflows for `maestro-update`.
+
+## Architecture
+
+```
+Schema migration (automatic)     Smart upgrade (workflow doc)
+─────────────────────────        ──────────────────────────
+src/migrations/v1-to-v2.ts  ──→  workflows/updates/update-v2-setup.md
+src/migrations/v2-to-v3.ts  ──→  workflows/updates/update-v3-setup.md
+```
+
+- **Schema**: `src/migrations/` — code-level state.json transforms. Registry auto-chains all intermediate versions (v1→v2→v3 runs automatically, no manual steps).
+- **Workflow**: `workflows/updates/update-v{VERSION}-setup.md` — what the user needs to know, configure, or verify after upgrading to that version.
+
+## How It Works
+
+1. `maestro-update` reads `.workflow/state.json` → `version`
+2. Runs `npx tsx src/migrations/run.ts` which auto-chains all pending schema migrations
+3. Loads `update-v{target}-setup.md` for the final target version
+4. Setup doc guides user through environment changes (hooks, deps, knowledge system)
+
+## Naming Convention
+
+```
+update-v{VERSION}-setup.md     — post-migration setup for version {VERSION}
+```
+
+## Adding a New Version
+
+1. Create `src/migrations/v{FROM}-to-v{TO}.ts` (schema migration code)
+2. Register in `src/migrations/index.ts`
+3. Create `workflows/updates/update-v{TO}-setup.md` (smart upgrade guide)
+
+## Current Versions
+
+| Version | Schema | Setup |
+|---------|--------|-------|
+| v2.0 | `src/migrations/v1-to-v2.ts` | — |
+| v3.0 | `src/migrations/v2-to-v3.ts` | `update-v3-setup.md` |

package/workflows/updates/update-v3-setup.md

@@ -0,0 +1,79 @@
+# Setup: v3.0 — Knowledge System Configuration
+
+v2→v3 迁移后的环境配置。验证并引导用户完成知识系统、CodeGraph、Hook 的安装和配置。
+
+## Step 1: 统一搜索验证
+
+```
+1. 运行：maestro search --help 2>&1 | head -1
+2. IF 可用 → 显示 "统一搜索：就绪（maestro search）"
+3. IF 不可用 → 警告 "运行 maestro install --force 更新 CLI"
+```
+
+**迁移提示**：
+```
+以下命令已废弃，请使用 maestro search 替代：
+  - spec search    → maestro search --type spec
+  - knowhow search → maestro search --type knowhow
+  - wiki search    → maestro search
+```
+
+## Step 2: CodeGraph 安装
+
+```
+1. 检测：node -e "require('@colbymchenry/codegraph')" 2>&1
+2. IF 已安装 → 显示 "CodeGraph：已安装"
+3. IF 未安装 → 显示：
+     "可选：@colbymchenry/codegraph（tree-sitter 代码分析）"
+     "启用函数级 KG，提供 callers/callees 查询。"
+     "安装：npm install -g @colbymchenry/codegraph"
+   
+   AskUserQuestion: "是否安装 CodeGraph？"
+   Options: [安装 / 跳过]
+   IF 安装：
+     Bash: npm install -g @colbymchenry/codegraph
+
+4. IF 已安装 AND 无索引：
+     Bash: maestro kg index --sqlite
+     显示 "KG 索引已初始化"
+```
+
+## Step 3: Hook 升级
+
+```
+1. 运行：maestro hooks status 2>&1
+2. IF standard 级别已安装 BUT 缺少 kg-sync 或 kg-context-injector：
+     AskUserQuestion: "Hooks 需升级以包含 KG hooks，是否重新安装？"
+     Options: [重新安装 / 跳过]
+     IF 重新安装：
+       Bash: maestro hooks install --level standard
+       显示 "Hooks 已升级，包含 kg-sync + kg-context-injector"
+
+3. IF 未安装任何 hooks：
+     AskUserQuestion: "是否安装 standard 级别 Hooks？（推荐）"
+     Options: [安装 / 跳过]
+     IF 安装：
+       Bash: maestro hooks install --level standard
+```
+
+### Hook 变更说明
+
+| Hook | 事件 | 作用 |
+|------|------|------|
+| `kg-sync` | UserPromptSubmit | 用户输入时静默同步知识图谱（30 秒冷却） |
+| `kg-context-injector` | PreToolUse:Agent | Agent 启动时注入代码结构上下文 |
+
+`keyword-spec-injector` 也已升级——现在包含 KG 符号查找，从 prompt 中提取 camelCase/snake_case 符号名，查询 CodeGraph 获取调用关系。
+
+## Step 4: 验证
+
+```
+1. 验证统一搜索：maestro search "test" --limit 1
+2. 验证 KG（如已安装）：maestro kg stats
+3. 验证 Hooks：maestro hooks status
+4. 显示最终状态：
+     Knowledge System:
+       Search:    maestro search（统一，BM25）
+       CodeGraph: {已安装 | 未安装（可选）}
+       KG Hooks:  {活跃 | 需重新安装}
+```

package/workflows/verify.md

@@ -1,3 +1,9 @@
+# ⚠️ DEPRECATED — Merged into execute.md (E2.7)
+
+Verification is now a built-in gate in `execute.md` step E2.7. This file is kept for reference only.
+
+---
+
 # Verify Workflow
 
 Dual verification: Goal-Backward structural verification + Nyquist test coverage validation.
@@ -520,7 +526,7 @@ Next steps:
 |--------|------------|
 | All passed, no gaps | Skill({ skill: "quality-review", args: "{phase}" }) for code review, then Skill({ skill: "quality-test" }) for UAT |
 | Critical gaps found | Skill({ skill: "quality-debug" }) for investigation |
-| Minor gaps only | Skill({ skill: "maestro-plan", args: "--gaps" }) -> Skill({ skill: "maestro-execute" }) -> re-run Skill({ skill: "maestro-verify" }) |
+| Minor gaps only | Skill({ skill: "maestro-plan", args: "--gaps" }) -> Skill({ skill: "maestro-execute" }) |
 | Low test coverage | Skill({ skill: "quality-auto-test", args: "{phase}" }) to generate missing tests |
 | Human verification needed | Skill({ skill: "quality-test", args: "{phase}" }) for interactive UAT |
 

package/.agents/skills/learn-retro/SKILL.md

@@ -1,159 +0,0 @@
----
-name: learn-retro
-description: Retrospective of git activity and decision quality
-argument-hint: "[--lens git|decision|all] [--days N] [--author <name>] [--area <path>] [--phase N] [--tag <tag>] [--id <id>] [--compare]"
-allowed-tools:
-  - read_file
-  - write_file
-  - shell
-  - find_files
-  - search
-  - delegate_subagent
-  - ask_user
----
-<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
-
-<purpose>
-Unified retrospective combining git activity analysis and decision quality evaluation. Works on raw git history and wiki/spec data. Two lenses (git, decision), usable independently or together.
-
-All insights persist to `.workflow/specs/learnings.md` as `<spec-entry>` blocks.
-</purpose>
-
-<context>
-$ARGUMENTS — lens selection and scope flags.
-
-**Lens**: `--lens git` | `--lens decision` | `--lens all` (default: all)
-
-**Git lens flags**: `--days N` (default: 7), `--author <name>`, `--area <path>`, `--compare` (vs prior retro)
-**Decision lens flags**: `--phase N`, `--tag <tag>`, `--id <id>` (single decision by wiki/INS id)
-
-**Storage write**:
-- `.workflow/knowhow/KNW-retro-{date}.md` — unified report
-- `.workflow/knowhow/KNW-retro-{date}.json` — structured metrics
-- `.workflow/specs/learnings.md` — appended `<spec-entry>` blocks (source: retro-git / retro-decision)
-
-**Storage read**: git history, `.workflow/state.json`, prior `KNW-retro-*.json`, `.workflow/specs/learnings.md`, wiki specs, `architecture-constraints.md`, phase context files
-</context>
-
-<state_machine>
-
-<states>
-S_PARSE       — 解析 lens + flags                           PERSIST: —
-S_GIT         — git 活动分析（lens=git/all 时）              PERSIST: metrics
-S_DECISION    — 决策质量评估（lens=decision/all 时）         PERSIST: evaluations
-S_REPORT      — 生成统一报告                                 PERSIST: .md + .json
-S_PERSIST     — 写 spec-entry 块                             PERSIST: .workflow/specs/learnings.md
-</states>
-
-<transitions>
-
-S_PARSE:
-  → S_GIT         WHEN: lens == git OR all               DO: ensure .workflow/knowhow/ exists (mkdir -p)
-  → S_DECISION    WHEN: lens == decision                  DO: ensure .workflow/knowhow/ exists (mkdir -p)
-
-S_GIT:
-  → S_DECISION    WHEN: lens == all                          DO: A_GIT_ANALYSIS
-  → S_REPORT      WHEN: lens == git                          DO: A_GIT_ANALYSIS
-
-S_DECISION:
-  → S_REPORT      DO: A_DECISION_ANALYSIS
-
-S_REPORT:
-  → S_PERSIST     DO: write KNW-retro-{date}.md + .json
-
-S_PERSIST:
-  → END           DO: append insights to .workflow/specs/learnings.md via `maestro spec add learning`
-  RULE: INS-id = hash(lens + metric_or_decision_id + date) for cross-session stability
-
-</transitions>
-
-<actions>
-
-### A_GIT_ANALYSIS
-
-**Parallel git commands**:
-```bash
-git log --since="{start}" --format="%H|%aN|%ae|%ai|%s" --shortstat
-git log --since="{start}" --format="COMMIT:%H|%aN" --numstat
-git log --since="{start}" --format="%at|%aN|%ai|%s" | sort -n
-git log --since="{start}" --format="" --name-only | grep -v '^$' | sort | uniq -c | sort -rn | head -20
-git shortlog --since="{start}" -sn --no-merges
-```
-Apply --author and --area filters.
-
-**Compute metrics**:
-
-| Metric | Formula |
-|--------|---------|
-| Test ratio | test_insertions / total_insertions * 100% |
-| Churn rate | files changed >2x / total unique files |
-| Sessions | Cluster commits by >2hr gaps in timestamps |
-| LOC/session-hour | net_loc / total_session_hours |
-
-**Per-author breakdown**: commits, LOC, top 3 areas, test ratio, session count.
-
-**Trend** (if --compare or prior KNW-retro-*.json exists): compute deltas, flag >20% changes.
-
-**Distill insights**: high churn files (instability), low test ratio areas (<20%), session patterns, area drift vs roadmap.
-
-### A_DECISION_ANALYSIS
-
-**Collect** (parallel):
-```bash
-maestro wiki search "decision" --json
-maestro wiki list --type spec --json
-git log --oneline --all --grep="decision\|chose\|decided" -20
-```
-Plus: architecture-constraints.md, phase context Locked/Deferred sections, .workflow/specs/learnings.md.
-Apply --phase/--tag/--id filters.
-
-**Build registry** per decision: id, title, source, date, rationale, alternatives, phase, implementation_evidence [file paths].
-
-**Evaluate** — spawn 3 Agents in single message:
-
-| Agent | Dimension | Grades |
-|-------|-----------|--------|
-| Technical Soundness | Implementation matches intent? Context changed? | sound / degraded / violated |
-| Cost Assessment | Complexity added? Coupling/debt? | low-cost / acceptable / expensive / debt-creating |
-| Alternative Hindsight | Right call with current knowledge? Reversible? | confirmed / questionable / should-revisit |
-
-**Classify lifecycle**:
-
-| Status | Criteria |
-|--------|---------|
-| Validated | sound + low/acceptable + confirmed |
-| Aging | sound + expensive + confirmed |
-| Questionable | degraded/violated + questionable |
-| Stale | any + should-revisit |
-| Reversed | code contradicts decision |
-
-**Recommend**: Aging → tech debt review, Questionable → create issue, Stale → refresh, Reversed → document reversal.
-
-</actions>
-
-</state_machine>
-
-<error_codes>
-| Code | Condition | Recovery |
-|------|-----------|----------|
-| E001 | Not in git repo (git lens) | Navigate to git repo |
-| E002 | No commits in window (git lens) | Increase --days |
-| E003 | No decisions found (decision lens) | Check wiki/specs or provide --id |
-| E004 | --id not found in wiki or knowhow | Verify the decision ID exists |
-| W002 | No prior retro for comparison | Skip trend; first retro = baseline |
-| W003 | One perspective agent failed | Proceed with available perspectives |
-</error_codes>
-
-<success_criteria>
-- [ ] Git lens: metrics computed (commits, LOC, test ratio, churn, sessions), insights distilled
-- [ ] Decision lens: decisions collected, 3 agents evaluated in parallel, lifecycle classified
-- [ ] Unified report + structured JSON written
-- [ ] .workflow/specs/learnings.md appended with stable INS-ids
-</success_criteria>
-
-<next_step_routing>
-- Browse insights → `/manage-learn list --tag retro`
-- Deep dive churn → `/learn-follow <path>`
-- Fix test gaps → `/quality-auto-test <area>`
-- Investigate stale decision → `/learn-investigate <question>`
-</next_step_routing>

package/.agents/skills/maestro-learn/SKILL.md

@@ -1,142 +0,0 @@
----
-name: maestro-learn
-description: Route learning intent to learn-* commands
-argument-hint: "<intent> [-y] [--dry-run] [--chain <name>]"
-allowed-tools:
-  - read_file
-  - write_file
-  - shell
-  - find_files
-  - search
-  - delegate_subagent
-  - ask_user
----
-<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
-
-<purpose>
-Route learning requests to the optimal learn command or multi-step chain. Supports direct chain selection via `--chain` or intent-based routing via keyword matching.
-
-Executes commands sequentially via invoke_skill() with session tracking.
-</purpose>
-
-<context>
-$ARGUMENTS — user learning intent text, or flags.
-
-**Flags:**
-- `-y` / `--yes` — Auto mode: skip confirmation
-- `--dry-run` — Show planned chain without executing
-- `--chain <name>` — Force a specific chain (bypass intent detection)
-
-**Available learn commands:**
-| Command | Purpose |
-|---------|---------|
-| `learn-follow` | Guided reading with forcing questions, pattern extraction |
-| `learn-investigate` | Hypothesis-driven question investigation |
-| `learn-decompose` | 4-dimension parallel pattern extraction |
-| `learn-second-opinion` | Multi-perspective review/challenge/consult |
-| `learn-retro` | Unified retrospective (git metrics + decision evaluation) |
-
-**Available chains:**
-| Chain | Steps | Use when |
-|-------|-------|----------|
-| `follow` | learn-follow | Read/understand code or docs |
-| `investigate` | learn-investigate | Answer a "how/why" question |
-| `decompose` | learn-decompose | Catalog patterns in a module |
-| `second-opinion` | learn-second-opinion | Get review/challenge on code |
-| `retro` | learn-retro --lens all | Full retrospective (git + decisions) |
-| `deep-understand` | follow → decompose → second-opinion | Thorough module analysis |
-| `pattern-catalog` | decompose --save-spec --save-wiki → second-opinion --mode review | Full pattern extraction + review |
-
-**Storage:**
-- `.workflow/knowhow/.maestro-learn/{session_id}/status.json` — Session tracking
-- All learn command outputs go to `.workflow/knowhow/`
-</context>
-
-<execution>
-
-### Step 1: Parse & Route
-
-Parse flags (`-y`, `--dry-run`, `--chain`). Extract intent text.
-
-**If `--chain` specified:** validate against known chains, jump to Step 2.
-
-**Intent routing table** (match first token or keywords):
-
-| Keywords | Route |
-|----------|-------|
-| File path (contains `/` or `\`) | `follow` |
-| Wiki ID (`type-slug` pattern) | `follow` |
-| read, follow, walk through, understand, 阅读, 跟读 | `follow` |
-| why, how, what if, investigate, 为什么, 怎么 | `investigate` |
-| pattern, decompose, catalog, 分解, 模式 | `decompose` |
-| opinion, review, challenge, consult, 评审, 挑战 | `second-opinion` |
-| retro, git, commit, decision, 回顾 | `retro` |
-| thorough, deep, 全面, 深入 | `deep-understand` |
-
-**If no match:** present menu via ask_user:
-```
-What would you like to do?
-1. Read through code/docs → follow
-2. Investigate a question → investigate
-3. Find patterns in code → decompose
-4. Get a second opinion → second-opinion
-5. Retrospective → retro
-```
-
-Max 1 clarification round. If still unclear: error.
-
-### Step 2: Resolve Target & Build Args
-
-- File path → pass directly
-- Wiki ID → pass directly
-- Topic string → pass as quoted argument
-- Extract any flags (--depth, --days, --lens, --mode, --scope, etc.)
-
-**Chain → command mapping:**
-```
-follow          → invoke_skill("learn-follow", "{target} {flags}")
-investigate     → invoke_skill("learn-investigate", "\"{target}\" {flags}")
-decompose       → invoke_skill("learn-decompose", "{target} {flags}")
-second-opinion  → invoke_skill("learn-second-opinion", "{target} {flags}")
-retro           → invoke_skill("learn-retro", "{flags}")
-deep-understand → [learn-follow --depth deep, learn-decompose --save-spec, learn-second-opinion --mode challenge]
-pattern-catalog → [learn-decompose --save-spec --save-wiki, learn-second-opinion --mode review]
-```
-
-### Step 3: Confirm & Execute
-
-**If `--dry-run`:** display chain plan and exit.
-
-**If not `-y`:** show plan, ask for confirmation.
-
-**Execute:**
-1. Create session dir: `.workflow/knowhow/.maestro-learn/learn-{timestamp}/`
-2. Write `status.json` with chain steps
-3. Execute each step via `invoke_skill()`:
-   - On success: mark completed, continue
-   - On failure (interactive): ask retry/skip/abort
-   - On failure (auto): skip and continue
-4. Display session summary with artifact list and next-step suggestion
-
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Recovery |
-|------|----------|-------------|----------|
-| E001 | error | No intent provided | Provide a learning goal or use --chain |
-| E002 | error | Cannot determine intent after clarification | Rephrase or use --chain directly |
-| E003 | error | Chain step failed + user chose abort | Partial progress saved in status.json |
-| E005 | error | Invalid --chain name | Show valid chains |
-| W001 | warning | Intent ambiguous between commands | Present options |
-| W002 | warning | Chain step completed with warnings | Log and continue |
-</error_codes>
-
-<success_criteria>
-- [ ] Intent routed to correct chain (or --chain validated)
-- [ ] Target resolved and arguments assembled
-- [ ] Session directory created with status.json
-- [ ] All chain steps executed via invoke_skill()
-- [ ] Error handling: retry/skip/abort per step
-- [ ] Session summary displayed with next-step routing
-- [ ] No files modified outside `.workflow/knowhow/`
-</success_criteria>

package/.agents/skills/maestro-verify/SKILL.md

@@ -1,146 +0,0 @@
----
-name: maestro-verify
-description: Use after execution to verify goals are actually achieved with evidence-based structural checks
-argument-hint: "[phase] [--skip-tests] [--skip-antipattern] [--dir <path>]"
-allowed-tools:
-  - read_file
-  - write_file
-  - edit_file
-  - shell
-  - find_files
-  - search
-  - delegate_subagent
-  - ask_user
----
-<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
-
-<purpose>
-Verify execution results through three complementary methods:
-1. **Goal-Backward verification** — 3-layer check (Truths → Artifacts → Wiring) that validates goals are actually achieved
-2. **Anti-pattern scan** — detect stubs, placeholders, TODO/FIXME, empty returns in modified files
-3. **Nyquist test coverage validation** — requirement-to-test mapping with gap classification
-
-Supports dual-level verification:
-- **Single plan**: `verify --dir scratch/{YYYYMMDD}-plan-xxx` — verifies one plan, writes `verification.json` into plan dir
-- **Milestone**: `verify` (no args) — aggregates all execute artifacts for current milestone into `scratch/{YYYYMMDD}-verify-M{N}-{slug}/milestone-verification.json`
-
-Registers VRF artifact in state.json on completion.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/verify.md
-</required_reading>
-
-<deferred_reading>
-- [verification.json](~/.maestro/templates/verification.json) — read when generating output
-- [validation.json](~/.maestro/templates/validation.json) — read when generating test output
-</deferred_reading>
-
-<context>
-$ARGUMENTS — phase number or no args for milestone-wide, with optional flags.
-
-### Flags
-
-| Flag | Effect | Default |
-|------|--------|---------|
-| `--skip-tests` | Skip Nyquist test coverage validation (V2), only run Goal-Backward verification | false |
-| `--skip-antipattern` | Skip anti-pattern scan step | false |
-| `--dir <path>` | Verify a single plan directory instead of milestone-wide | — (milestone mode) |
-
-**Scope routing:**
-| Input | Scope | Resolution |
-|-------|-------|------------|
-| `--dir scratch/{dir}` | single plan | Verify one plan, write verification.json into plan dir |
-| numeric arg | phase | Verify all execute artifacts for that phase |
-| no args | milestone | Aggregate all execute artifacts for current milestone |
-
-Output paths and VRF artifact registration schema are defined in workflow `verify.md`.
-
-### Pre-load context (before verification)
-
-1. **Codebase docs**: If `.workflow/codebase/` exists, read `ARCHITECTURE.md` for expected module wiring and `FEATURES.md` for component mapping. Use in Layer 3 (Connection) checks.
-2. **Review specs**: Run `maestro spec load --category review` to load review standards. Use as quality baseline for anti-pattern scan and constraint checks.
-3. **Wiki constraints**: Run `maestro wiki search "architecture constraint" --json 2>/dev/null`. If results found, include documented invariants as additional truth checks in Layer 1.
-4. **Role Knowledge**:
-   - Browse: `maestro wiki list --category review`
-   - Load task-relevant entries: `maestro wiki load <id1> [id2...]`
-5. All are optional — proceed without if unavailable.
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/verify.md' completely.
-
-### Post-verify Knowledge Inquiry
-
-| Condition | Ask | Route |
-|-----------|-----|-------|
-| Anti-pattern blockers found (TODO/FIXME/stubs) | "Update quality-rules.md?" | spec-add quality |
-| Architecture constraint violations | "Update architecture-constraints.md?" | spec-add arch |
-| Recurring test coverage gap (same module across tasks) | "Add to test-conventions.md?" | spec-add test |
-
-On confirm → `invoke_skill("spec-add", "<category> <content>")`.
-
-</execution>
-
-<completion>
-### Standalone report
-
-```
-=== VERIFY COMPLETE ===
-STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_RETRY
-CONCERNS: {description if applicable}
-NEXT: /quality-review
-=== END VERIFY ===
-```
-
-Status mapping:
-- **DONE** — All checks pass, no gaps → NEXT: /quality-review
-- **DONE_WITH_CONCERNS** — Gaps found (must-have failures or anti-pattern blockers) → NEXT: /maestro-execute (after /maestro-plan --gaps)
-- **NEEDS_RETRY** — Verification could not complete (missing artifacts, corrupt data)
-
-### Ralph-invoked completion
-
-End the step by calling the CLI (no text block output):
-```
-maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
-```
-
-Status verdicts:
-- **DONE** — Normal completion
-- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
-- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
-- **BLOCKED** — External hard blocker; pass `--reason`
-
-### Next-step routing
-
-| Condition | Suggestion |
-|-----------|-----------|
-| All checks pass, no gaps | `/quality-review` |
-| Gaps found (must-have failures or anti-pattern blockers) | `/maestro-plan --gaps` |
-| Low test coverage (Nyquist gaps) | `/quality-auto-test` |
-
-**Gap-fix closure loop:**
-Gaps found → maestro-plan --gaps → maestro-execute → maestro-verify (re-run)
-</completion>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | No executed plans found for verification | Run maestro-execute first |
-| E002 | error | Plan directory not found | Check --dir path |
-| E003 | error | No execution results found (missing summaries) | Run maestro-execute first |
-| W001 | warning | Test coverage below configured threshold | Review coverage gaps |
-| W002 | warning | Anti-pattern blockers found in modified files | Fix blockers before proceeding |
-</error_codes>
-
-<success_criteria>
-- [ ] Must-haves established (from convergence.criteria in tasks)
-- [ ] All truths verified with status and evidence (Layer 1)
-- [ ] All artifacts checked at L1 (exists), L2 (substantive), L3 (wired) (Layer 2)
-- [ ] All key links verified with evidence (Layer 3)
-- [ ] Anti-patterns scanned and categorized (unless skipped)
-- [ ] Nyquist test coverage assessed (unless skipped)
-- [ ] Fix plans generated for identified gaps
-- [ ] verification.json written to plan dir (single plan) or milestone verify dir
-- [ ] VRF artifact registered in state.json
-</success_criteria>