maestro-flow 0.4.26 → 0.5.1

package/workflows/maestro.md

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

package/workflows/review.md

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

package/workflows/specs-add.md

@@ -97,7 +97,7 @@ Keyword quality rules:
 ```
 Entry format (closed-tag), date = YYYY-MM-DD, title = first meaningful phrase:
 
-<spec-entry category="{category}" keywords="{kw1},{kw2},{kw3}" date="{YYYY-MM-DD}">
+<spec-entry category="{category}" keywords="{kw1},{kw2},{kw3}" date="{YYYY-MM-DD}" title="{title}" description="{one-line summary}">
 ### {title}
 {content}
 </spec-entry>

package/workflows/specs-setup.md

@@ -228,9 +228,9 @@ Schema: matches `recipe` type defined in `~/.maestro/workflows/knowhow.md` Part
 
 **Skip rule:** If signals are missing, skip the recipe — do NOT generate placeholders.
 
-**Idempotency rule:** Before writing, glob `.workflow/knowhow/RCP-*-{slug}.md`. If a file matching the slug exists, do NOT overwrite — write `.workflow/knowhow/RCP-{YYYYMMDD-HHMM}-{slug}.proposed.md` instead and mention it in Step 7 summary so the user can diff and merge manually.
+**Idempotency rule:** Before writing, glob `.workflow/knowhow/RCP-*-{slug}.md`. If a file matching the slug exists, do NOT overwrite — write `.workflow/knowhow/RCP-{YYYYMMDD}-{slug}.proposed.md` instead and mention it in Step 7 summary so the user can diff and merge manually.
 
-**Filename:** `.workflow/knowhow/RCP-{YYYYMMDD-HHMM}-{slug}.md` (timestamp aligns with rest of knowhow store, slug disambiguates).
+**Filename:** `.workflow/knowhow/RCP-{YYYYMMDD}-{slug}.md` (date + semantic slug for readability).
 
 **Tags rule:** Match content language (English codebase → English tags). Always include `workflow`, the slug, and the detected framework (e.g. `vitest`, `pytest`). Add `auto-generated` so users can identify spec-setup output for later pruning.
 

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>