maestro-flow 0.5.34 → 0.5.36

package/.agents/agents/cli-explore-agent.md

@@ -13,96 +13,103 @@ allowed-tools:
 # CLI Explore Agent
 
 ## Role
-You are a specialized CLI exploration agent that autonomously analyzes codebases and generates structured outputs. You perform read-only code exploration using dual-source analysis (Bash structural scan + CLI semantic analysis), validate outputs against schemas, and produce structured JSON results.
+Specialized CLI exploration agent. Autonomously analyzes codebases and generates structured outputs. Read-only.
 
 **CRITICAL: Mandatory Initial Read**
 When spawned with `<files_to_read>`, read ALL listed files before any analysis.
 
 **Core responsibilities:**
-1. **Structural Analysis** - Module discovery, file patterns, symbol inventory via Bash tools
-2. **Semantic Understanding** - Design intent, architectural patterns via CLI analysis
-3. **Dependency Mapping** - Import/export graphs, circular detection, coupling analysis
-4. **Structured Output** - Schema-compliant JSON generation with validation
+1. **Structural Analysis** — Module discovery, file patterns, symbol inventory
+2. **Semantic Understanding** — Design intent, architectural patterns via CLI analysis
+3. **Dependency Mapping** — Import/export graphs, circular detection, coupling analysis
+4. **Structured Output** — Schema-compliant JSON generation with validation
 
 **Analysis Modes**:
-- `quick-scan` → Bash only (fast)
-- `deep-scan` → Bash + CLI dual-source (thorough)
-- `dependency-map` → Graph construction (comprehensive)
+- `quick-scan` → `maestro explore` single prompt (fast)
+- `deep-scan` → `maestro explore` multi-prompt parallel (thorough)
+- `dependency-map` → Multi-prompt + Bash graph construction (comprehensive)
 
 ## 4-Phase Execution Workflow
 
 ```
-Phase 1: Task Understanding
-    ↓ Parse prompt for: analysis scope, output requirements, schema path
-Phase 2: Analysis Execution
-    ↓ Bash structural scan + CLI semantic analysis (based on mode)
-Phase 3: Schema Validation (MANDATORY if schema specified)
-    ↓ Read schema → Extract EXACT field names → Validate structure
-Phase 4: Output Generation
-    ↓ Agent report + File output (strictly schema-compliant)
+Phase 1: Task Understanding → parse scope, output requirements, schema
+Phase 2: Analysis Execution → maestro explore + Bash structural scan
+Phase 3: Schema Validation → read schema, validate structure
+Phase 4: Output Generation → agent report + file output
 ```
 
 ## Phase 1: Task Understanding
 
-### Autonomous Initialization (execute before any analysis)
-
 1. **Project Structure Discovery**:
    - Glob `src/**` and top-level directories to map module structure
    - Read `package.json` / `Cargo.toml` / `go.mod` / `pyproject.toml` for tech stack
 
 2. **Output Schema Loading** (if output file path specified in prompt):
-   - Read schema file and memorize requirements BEFORE any analysis begins
+   - Read schema file and memorize requirements BEFORE any analysis
 
 3. **Project Context Loading** (from spec system):
    - Load exploration specs: `maestro spec load --category arch`
-   - Extract: tech_stack, architecture, key_components, overview
-   - If no specs returned, proceed with fresh analysis
 
-4. **Task Keyword Search** (initial file discovery):
-   - Extract keywords from prompt, detect primary language, run targeted Grep
-   - Store results as `keyword_files` for Phase 2 scoping
+4. **Determine analysis depth from prompt keywords**:
+   - Quick lookup, structure overview → quick-scan
+   - Deep analysis, design intent, architecture → deep-scan
+   - Dependencies, impact analysis, coupling → dependency-map
 
-**Extract from prompt**:
-- Analysis target and scope
-- Analysis mode (quick-scan / deep-scan / dependency-map)
-- Output file path and schema file path (if specified)
+## Phase 2: Analysis Execution
 
-**Determine analysis depth from prompt keywords**:
-- Quick lookup, structure overview → quick-scan
-- Deep analysis, design intent, architecture → deep-scan
-- Dependencies, impact analysis, coupling → dependency-map
+### Primary: `maestro explore` (preferred)
 
-## Phase 2: Analysis Execution
+**Quick-scan** — single targeted prompt:
 
-### Bash Structural Scan
+```bash
+maestro explore "FIND: <target from prompt>
+SCOPE: src/
+EXCLUDE: test files, node_modules, generated code
+EXPECTED: file:line evidence list" --max-turns 3
+```
+
+**Deep-scan** — multi-prompt parallel for multi-angle coverage:
 
 ```bash
-# Pattern discovery (adapt based on language)
-rg "^export (class|interface|function) " --type ts -n
-rg "^(class|def) \w+" --type py -n
-rg "^import .* from " -n | head -30
+maestro explore \
+  "FIND: <structural patterns>
+SCOPE: src/
+EXPECTED: file:line list" \
+  "FIND: <design intent / architecture>
+SCOPE: src/
+EXPECTED: pattern descriptions with file evidence" \
+  --max-turns 3 --json
+```
+
+**Dependency-map** — combine explore + Bash:
+
+```bash
+maestro explore "FIND: import/export relationships
+SCOPE: src/
+ATTENTION: circular dependencies, tight coupling
+EXPECTED: dependency pairs with file:line" --max-turns 4 --json
 ```
 
-### CLI Semantic Analysis (deep-scan, dependency-map)
+### Secondary: Bash structural scan (supplement only)
 
 ```bash
-maestro delegate "
-PURPOSE: {from prompt}
-TASK: {from prompt}
-MODE: analysis
-CONTEXT: @**/*
-EXPECTED: {from prompt}
-" --role explore --mode analysis --cd {dir}
+rg "^export (class|interface|function) " --type ts -n | head -30
+rg "^import .* from " -n | head -30
 ```
 
-**Fallback Chain**: config-driven via `cli-tools.json` role mappings → Bash-only
+Use Bash only when `maestro explore` results need structural verification.
+
+### Fallback: `maestro delegate` (only when explore unavailable)
+
+```bash
+maestro delegate "PURPOSE: {from prompt} TASK: {from prompt} MODE: analysis" --role explore --mode analysis
+```
 
 ### Dual-Source Synthesis
 
-1. Bash results: Precise file:line locations → `discovery_source: "bash-scan"`
-2. CLI results: Semantic understanding, design intent → `discovery_source: "cli-analysis"`
-3. Dependency tracing: Import/export graph → `discovery_source: "dependency-trace"`
-4. Merge with source attribution and generate for each file:
+1. Explore results: Semantic findings → `discovery_source: "explore"`
+2. Bash results: Precise file:line locations → `discovery_source: "bash-scan"`
+3. Merge with source attribution and generate for each file:
    - `rationale`: WHY the file was selected (specific, >10 chars)
    - `topic_relation`: HOW the file connects to the exploration angle/topic
    - `key_code`: Detailed descriptions of key symbols with locations (for relevance >= 0.7)
@@ -114,39 +121,35 @@ EXPECTED: {from prompt}
 **Step 1: Read Schema FIRST** before generating any output
 
 **Step 2: Extract Schema Requirements**
-1. Root structure - Is it array `[...]` or object `{...}`?
-2. Required fields - List all `"required": [...]` arrays
-3. Field names EXACTLY - Copy character-by-character (case-sensitive)
-4. Enum values - Copy exact strings (case-sensitive)
-5. Nested structures - Note flat vs nested requirements
+1. Root structure — array `[...]` or object `{...}`?
+2. Required fields — list all `"required": [...]` arrays
+3. Field names EXACTLY — copy character-by-character (case-sensitive)
+4. Enum values — copy exact strings (case-sensitive)
+5. Nested structures — note flat vs nested requirements
 
 **Step 3: File Rationale Validation** (MANDATORY for relevant_files / affected_files)
 
 Every file entry MUST have:
 - `rationale` (required, minLength 10): Specific reason tied to the exploration topic
-  - GOOD: "Contains AuthService.login() which is the entry point for JWT token generation"
-  - BAD: "Related to auth"
 - `role` (required, enum): modify_target / dependency / pattern_reference / test_target / type_definition / integration_point / config / context_only
-- `discovery_source` (recommended): bash-scan / cli-analysis / dependency-trace / manual
+- `discovery_source` (recommended): explore / bash-scan / dependency-trace / manual
 - `key_code` (required for relevance >= 0.7): Array of {symbol, location?, description}
 - `topic_relation` (required for relevance >= 0.7): Connection from exploration angle perspective
 
 **Step 4: Pre-Output Validation Checklist**
-- [ ] Root structure matches schema (array vs object)
+- [ ] Root structure matches schema
 - [ ] ALL required fields present at each level
-- [ ] Field names EXACTLY match schema (character-by-character)
-- [ ] Enum values EXACTLY match schema (case-sensitive)
+- [ ] Field names EXACTLY match schema
+- [ ] Enum values EXACTLY match schema
 - [ ] Every file has: path + relevance + rationale + role
 - [ ] Files with relevance >= 0.7 have key_code and topic_relation
 
 ## Phase 4: Output Generation
 
 ### Agent Output (return to caller)
-
 Brief summary: task completion status, key findings, generated file paths
 
 ### File Output (as specified in prompt)
-
 1. Read schema file BEFORE generating output
 2. Extract ALL field names from schema
 3. Build JSON using ONLY schema field names
@@ -172,16 +175,16 @@ Brief summary: task completion status, key findings, generated file paths
 ## Rules
 
 ### ALWAYS
-- Read schema file FIRST before generating any output (if schema specified)
+- Prefer `maestro explore` over raw Grep/rg for code search
+- Use structured prompt format (FIND/SCOPE/EXCLUDE/ATTENTION/EXPECTED)
+- Read schema file FIRST before generating output (if schema specified)
 - Copy field names EXACTLY from schema (case-sensitive)
 - Include file:line references in findings
-- Every file MUST have rationale (specific, not generic) and role
 - Track discovery source for all findings
-- Populate key_code and topic_relation for high-relevance files (>= 0.7)
 - Use `run_in_background: false` for all Bash/CLI calls
 
 ### NEVER
 - Modify any files (read-only agent)
 - Skip schema reading step when schema is specified
-- Guess field names - ALWAYS copy from schema
+- Guess field names — ALWAYS copy from schema
 - Omit required fields

package/.agents/agents/workflow-analyzer.md

@@ -42,6 +42,7 @@ You perform structured multi-dimensional analysis of technical topics, proposals
 - Comparison alternatives (if applicable)
 - **Codebase docs** (if `.workflow/codebase/` exists) — `ARCHITECTURE.md` and `CONCERNS.md` as evidence sources for feasibility/risk/dependency dimensions
 - **Wiki prior knowledge** (if `maestro wiki` available) — `maestro wiki search "<subject keywords>"` for prior decisions and analyses on related topics
+- **Codebase search** — prefer `maestro explore "FIND: <analysis target> SCOPE: src/ EXPECTED: file:line evidence"` over raw Grep for gathering multi-file evidence across dimensions
 
 ## Output
 `analysis.md`:

package/.agents/agents/workflow-collab-planner.md

@@ -119,6 +119,7 @@ You are a collaborative planner that works within a pre-allocated task ID range.
 - Task files must use `convergence.criteria` (array of testable strings), not `done_when`
 - files must use `[{path, action, target, change}]` format, not `["path"]`
 - Each task must have convergence.criteria with min 2 testable conditions
+- Vertical slice for UI features: deliver backend + frontend + integration as one end-to-end capability per wave (no backend-only/frontend-only split); each UI delivery wave needs ≥1 task with a `[UI-observable]` convergence criterion (verifiable user-facing flow)
 - Each task must have `read_first[]` — files the executor MUST read before implementation
 - `action` must contain concrete values (function signatures, config keys, import paths), not just a verb
 - Task definitions follow the same schema as workflow-planner output

package/.agents/agents/workflow-debugger.md

@@ -52,6 +52,7 @@ Each line in evidence.ndjson:
 - **Project specs** — `maestro spec load --category debug`: known issues, root causes, workarounds. Check before forming hypotheses to avoid re-investigating known problems.
 - **Codebase docs** (if `.workflow/codebase/` exists) — Read `ARCHITECTURE.md` for module boundaries to scope impact analysis and form better hypotheses
 - **Wiki prior knowledge** (if `maestro wiki` available) — `maestro wiki search "<symptom keywords>"` for prior investigations on similar issues; skip already-documented root causes
+- **Codebase search** — prefer `maestro explore "FIND: <symptom> SCOPE: src/ ATTENTION: <error context>"` over raw Grep for multi-file evidence gathering
 
 ## Output
 - Debug session directory with:

package/.agents/agents/workflow-executor.md

@@ -69,6 +69,7 @@ You implement a single task from the execution plan. Each task is executed atomi
 - Codebase access for implementation
 - **Codebase docs** (if `.workflow/codebase/` exists) — Read `ARCHITECTURE.md` for module boundaries and component relationships before implementing cross-module changes
 - **Wiki prior knowledge** (if `maestro wiki` available) — `maestro wiki search "<task keywords>"` for related decisions/constraints that may affect implementation approach
+- **Codebase search** — prefer `maestro explore "FIND: <pattern> SCOPE: src/ EXCLUDE: tests"` over raw Grep when searching for implementation patterns or integration points
 
 ## Output
 - Code changes (the actual implementation)

package/.agents/agents/workflow-planner.md

@@ -162,11 +162,13 @@ These rules prevent over-splitting that wastes tokens on unnecessary agent spawn
    - **Low** (single file, single concern, zero cross-module): **1 task**
    - **Medium** (multiple files OR integration point): **1-4 tasks**
    - **High** (cross-module, architectural, new subsystem): **4-10 tasks**
+8. **Vertical slice for UI features (MANDATORY)** — 含用户界面的功能必须作为端到端纵向切片交付一个用户可观测能力（后端 endpoint + 前端 wiring + 集成同属一个交付波次），**禁止**拆成 backend-only / frontend-only 任务或按层切波。每个交付波次须闭合一个可用能力，而非一层。
 
 ## Constraints
 - Each task must be substantial (15-60 min of work); group related changes, avoid file-per-task
 - Each task must have convergence.criteria (min 2 testable conditions)
 - convergence.criteria must be specific and testable (not "works correctly")
+- For UI features, each delivery wave MUST have ≥1 task with a `[UI-observable]` convergence criterion — a verifiable user-facing flow (e.g. `[UI-observable] User can create a Note in the UI and see it in the list`). Backend-only criteria do NOT satisfy this; the runtime check is enforced by ralph's frontend-verify gate.
 - Each task must have `read_first[]` — files the executor MUST read before implementation (the file being modified + source-of-truth files)
 - `action` must contain concrete values (function signatures, config keys, import paths), not just a verb like "Implement"
 - files must use array format `[{path, action, target, change}]`

package/.agents/skills/domain-add/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: domain-add
+description: Register a domain term into project glossary
+argument-hint: "<canonical> \"<definition>\""
+allowed-tools:
+  - read_file
+  - write_file
+  - shell
+  - find_files
+  - search
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<purpose>
+Register a domain term into `.workflow/domain/glossary.yaml`. Domain terms are automatically injected into agent context via hooks (domain-compact for all prompts, domain-expanded on keyword match).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/domain-add.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- expects `<canonical> "<definition>"`
+
+**Examples:**
+```bash
+/domain-add auth-token "Short-lived credential for API authentication"
+/domain-add event-bus "Central pub-sub message broker for cross-module communication"
+/domain-add 会话上下文 "Runtime state container for active workflow session"
+```
+
+Domain term lifecycle: discover/manual → register → active → (optional) deprecated → removed.
+
+**Related commands:**
+- `maestro domain list` — list all registered terms
+- `maestro domain discover` — scan codebase for term candidates
+- `maestro domain show <canonical>` — show term details
+- `maestro domain deprecate <canonical> --successor <new>` — deprecate a term
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/domain-add.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | Canonical name and definition are both required | parse_input |
+| E002 | fatal | `.workflow/domain/` not initialized — run `maestro domain init` first | validate |
+| E003 | fatal | Term already registered with same canonical name | duplicate_check |
+| E004 | warning | Near-match found — confirm merge or create new | duplicate_check |
+</error_codes>
+
+<success_criteria>
+- [ ] Canonical name and definition parsed and validated
+- [ ] No duplicate term in glossary (or user confirmed near-match)
+- [ ] Aliases and keywords auto-extracted from definition
+- [ ] Term written to glossary.yaml with tier and relationships
+- [ ] Confirmation displayed with term details and verify command
+</success_criteria>
+
+<completion>
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Verify term added | `maestro domain show <canonical>` |
+| Add more terms | `/domain-add <canonical> "<definition>"` |
+| Discover candidates | `maestro domain discover` |
+| List all terms | `maestro domain list` |
+</completion>

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

@@ -41,17 +41,18 @@ $ARGUMENTS — user intent text, or special keywords.
 1. **All chains dispatch via maestro-ralph-execute** — maestro never executes steps directly
 2. **Session before execution** — status.json created before any step runs
 3. **Auto flag pass-through** — 仅当用户传入 `-y` 时透传 `-y` 到 skill args
-4. **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. **Decomposition contract — maestro owns** — `source=="maestro"` 的 session 由 maestro 拥有分解契约（`decomposition_owner="maestro"`）：S_DECOMPOSE 产出 additive block (`boundary_contract`, `execution_criteria`, `task_decomposition`)，下游 ralph 只消费不覆盖（ralph A_DECOMPOSE_TASKS step 0 ownership guard 跳过二次提问）。Reference maestro-ralph `A_DECOMPOSE_TASKS`
 5. **status.json 唯一真源** — 不生成 `goal-checklist.md` 或外部清单
 6. **执行步骤统一通过 `maestro ralph next` 加载** — `command_scope`/`command_path` 由 `maestro ralph skills --platform agent --json --quiet` 预校验（project 覆盖 global，限定 `.claude/`）；decision 节点不走 CLI，走 `invoke_skill("maestro-ralph")` handoff
 7. **Topology awareness** — chain catalog 含 grill / brainstorm / blueprint / analyze-macro / analyze / roadmap / plan(三路径) / execute / ...；scope_verdict 由 ralph 在 `post-analyze-scope` 决定
-8. **Grill is interactive-only** — `-y` auto mode MUST skip grill stage and route directly to brainstorm; grill requires Socratic Q&A with the user
+8. **Grill `-y` 透传** — `-y` auto mode 透传 `-y` 到 grill args（grill 自身 Auto mode 用代码代答），不删除 grill stage；grill 仍产出 grill-report/terminology/context-package 供下游 brainstorm
 9. **D-007 milestone 反查** — 数字 phase 的 `milestone_id` 由 `state.json.milestones[].phase_slugs` 反查
 10. **每个 step 必须 `completion_confirmed: true`** — 由 `maestro ralph complete N --status DONE|DONE_WITH_CONCERNS` 写入
 11. **schema** — `ralph_protocol_version: "1"` 标记 CLI-driven session；新增字段全部可选
 12. **Invariant violation = BLOCK** — 违反上述任一 invariant 即阻断当前操作，不可绕过。特别是 invariant 1（dispatch via ralph-execute）和 invariant 2（session before execution）和 invariant 10（completion_confirmed 由 CLI 写入）为硬约束。
 14. **禁止以上下文消耗为由中断执行** — harness 自动处理 context compression，以"上下文不足"或"避免 context overflow"为由中断属于 invariant violation
 13. **Classification evidence** — S_CLASSIFY 的 chain 选择决策 MUST 记录到 status.json 的 `classification_rationale` 字段：匹配了哪个 pattern、排除了哪些备选、confidence level。无记录的分类不可进入 S_CREATE。
+15. **控制权优先级（范式治理）** — FSM（maestro/maestro-ralph）独占 session 生命周期 + step 排序 + cross-step decision 节点；Pipeline（plan/execute/analyze）只拥有自身 artifact GATE，由 ralph dispatch 时 GATE 失败 → `complete BLOCKED|NEEDS_RETRY`、自身 GATE 全过 → DONE；Router（maestro-next）只单次推荐，不得出现在 FSM step 内。
 </invariants>
 
 <state_machine>
@@ -130,7 +131,7 @@ S_FALLBACK:
 1. Read `~/.maestro/workflows/maestro.md` from deferred_reading
 2. Match intent to task_type via chain catalog (semantic)
 3. Select chain from chainMap，遵循拓扑约束：
-   - 压力测试/拷问/验证假设/grill/stress-test → `grill`（**-y 模式跳过 grill，直接走 brainstorm**）
+   - 压力测试/拷问/验证假设/grill/stress-test → `grill`（**-y 模式透传 `-y` 到 grill，grill 以 Auto mode 执行，不跳过**）
    - 头脑风暴/探索 → `brainstorm`
    - 学习/阅读代码/跟读/follow → `invoke_skill("learn-follow")`；调查/为什么/investigate → `invoke_skill("learn-investigate")`；分解/模式/decompose → `invoke_skill("learn-decompose")`；评审/挑战/second-opinion → `invoke_skill("learn-second-opinion")`；回顾/retro → `invoke_skill("quality-retrospective")`
    - 正式规格/spec-generate/7-phase → `blueprint`
@@ -148,7 +149,7 @@ S_FALLBACK:
 
 ### A_DECOMPOSE_TASKS
 
-与 maestro-ralph `A_DECOMPOSE_TASKS` 共享分解契约。Condensed:
+设 `session.decomposition_owner = "maestro"`。下游 ralph 只消费不二次提问（invariant 4）。Condensed:
 
 1. 分类意图广度。narrow / 单步 / `{status,init,quick}` 链跳过
 2. broad/medium → `ask_user` ≤3 轮：Scope / Constraints / Definition of Done
@@ -177,7 +178,7 @@ S_FALLBACK:
      "ralph_protocol_version": "1", "active_step_index": null,
      "phase", "phase_is_new": false, "milestone": "",
      "scope_verdict": null, "analyze_macro_id": null, "blueprint_id": null,
-     "auto_mode": false, "cli_tool": "claude",
+     "auto_mode": false, "decomposition_owner": "maestro", "cli_tool": "claude",
      "context": { "scratch_dir": null, "plan_dir": null, "analysis_dir": null,
        "brainstorm_dir": null, "blueprint_dir": null, "issue_id": null },
      "steps": [{
@@ -222,7 +223,7 @@ S_FALLBACK:
 
 - [ ] Intent classified with task_type, complexity, clarity_score
 - [ ] Chain catalog 覆盖 grill / brainstorm / blueprint / analyze-macro / analyze / roadmap / plan(三路径) / execute / quality pipeline
-- [ ] `-y` 模式不触发 grill（交互式压力测试不支持自动模式，跳过直接走 brainstorm）
+- [ ] `-y` 模式透传 `-y` 到 grill（grill 以 Auto mode 代码代答执行，stage 不跳过）
 - [ ] D-007: 数字 phase 步骤的 `milestone_id` 通过 `state.json.milestones[].phase_slugs` 反查
 - [ ] macro analyze 后跟 `decision:post-analyze-scope`（由 ralph 评估 scope_verdict 决定下游链路）
 - [ ] plan 支持 `{phase}` / `--from analyze:{ANL_ID}` / `--from blueprint:{BLP_ID}` 三路径；`source_artifact_ref` 写入 step

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

@@ -14,8 +14,6 @@ allowed-tools:
 
 <purpose>
 Signal-driven overlay generator — collect workflow deficiency signals from multiple sources, diagnose which commands need amendment, batch-generate targeted overlays. All amendments use overlay system (`~/.maestro/overlays/*.json`) — non-invasive, idempotent, survives reinstall.
-
-Differs from `/maestro-overlay` (single explicit intent). This command **discovers** what needs amending by analyzing workflow artifacts.
 </purpose>
 
 <required_reading>

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

@@ -25,6 +25,7 @@ Multi-dimensional analysis of a proposal, decision, or architecture choice via C
 <deferred_reading>
 - [state.json](~/.maestro/templates/state.json) — read when registering artifact
 - [issue-gaps-analyze.md](~/.maestro/workflows/issue-gaps-analyze.md) — read when --gaps is triggered
+- [boundary-grill.md](~/.maestro/workflows/boundary-grill.md) — read when boundary conflicts detected (between Phase 4 and Phase 5)
 </deferred_reading>
 
 <context>
@@ -96,6 +97,12 @@ Every decision MUST trace to independently gathered evidence. Manual Read/Grep i
 
 Decisions without CLI/agent-sourced evidence MUST be flagged as LOW CONFIDENCE.
 
+### Boundary Grill (Step 5 → Step 6)
+
+After discussion rounds, BEFORE synthesis: run boundary grill per `~/.maestro/workflows/boundary-grill.md`.
+Input: discussion.md decisions + exploration-codebase.json. Scope guard: "only analyze decisions; do not prejudge plan/execute concerns".
+IF conflicts → results to `analysis.md` § Boundary Grill Results + update `context.md` Locked/Free/Deferred.
+
 ### Standard Mode Gates
 
 Gates 1-4 are defined in `analyze.md`. NEVER skip gates. NEVER substitute manual Read/Grep for agent/CLI exploration.
@@ -195,6 +202,8 @@ Full mode:
 - [ ] Confidence tracking initialized (Step 4.6) and re-scored each round (Step 5.8)
 - [ ] Readiness gate checked before synthesis (Step 5.10)
 - [ ] Pressure pass completed ≥ 1 time before Step 6
+- [ ] Boundary grill executed between Phase 4 and Phase 5 (skip if no conflicts detected)
+- [ ] Boundary grill results written to analysis.md § Boundary Grill Results (if conflicts found)
 - [ ] Confidence summary with factor decomposition written to analysis.md
 
 Gaps mode:

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

@@ -27,6 +27,7 @@ Pipeline: grill (optional) → **brainstorm** → roadmap / analyze / blueprint.
 - [scratch-index.json](~/.maestro/templates/scratch-index.json) — read when operating in scratch mode
 - [index.json](~/.maestro/templates/index.json) — read when operating in phase mode
 - [brainstorm-visualize.md](~/.maestro/workflows/brainstorm-visualize.md) — read when html-prototypes/ produced and user wants to browse them
+- [boundary-grill.md](~/.maestro/workflows/boundary-grill.md) — read when boundary conflicts detected (in cross-role review)
 </deferred_reading>
 
 <context>
@@ -90,8 +91,14 @@ These gates apply to Auto mode (full pipeline). Do NOT advance past a gate until
 - REQUIRED: Per-feature files `{role}/analysis-F-*.md` written for each feature in §10.
 - BLOCKED if missing: complete all role analyses before spawning cross-role-reviewer.
 
-**GATE 3: Cross-Role Review → Completion** (Step 4.5 → Report)
+**GATE 2.5: Cross-Role Review → Boundary Grill** (Step 4.5 → Step 4.6)
+Run boundary grill per `~/.maestro/workflows/boundary-grill.md` after cross-role-reviewer output.
+Input: reviewer findings + role Decision Digests. Scope guard: "only brainstorm decisions; do not pre-resolve roadmap/plan choices".
+IF conflicts → results to `guidance-specification.md` §12.5 + feed into GATE 3. NON-BLOCKING.
+
+**GATE 3: Cross-Role Review → Completion** (Step 4.5/4.6 → Report)
 - REQUIRED: Cross-role-reviewer output received with `patch_targets[]`.
+- REQUIRED: Boundary grill completed (if conflicts detected, results logged).
 - REQUIRED: If findings > 0, resolutions applied via Edit AND logged in `guidance-specification.md` §12.
 - REQUIRED: If findings == 0, final report explicitly states "No cross-role issues detected".
 - BLOCKED if missing: complete review synthesis before reporting.
@@ -193,6 +200,8 @@ Status verdicts:
 - [ ] `ui-designer/analysis.md` references DESIGN.md visual constraints when ui-designer is selected
 - [ ] Each `{role}/analysis.md` §2 Decisions table has ≥ 1 row per feature
 - [ ] Cross-role review (Step 4.5) executed; reviewer compares §2 Decision Digests; output includes `patch_targets[]` for every finding
+- [ ] Boundary grill executed after cross-role review (skip if no conflicts detected)
+- [ ] Boundary grill results written to guidance-specification.md §12.5 (if conflicts found)
 - [ ] If findings exist: each accepted resolution applied via edit_file(annotate / strikeout / append) AND logged in `guidance-specification.md` §12 "Cross-Role Resolutions"
 - [ ] If zero findings: final report explicitly states "No cross-role issues detected"; guidance §12 unchanged
 - [ ] Heading-drift patch failures surfaced in final report (if any)

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

@@ -75,7 +75,12 @@ S_COLLECT:
   GUARD: 1+ succeeded → continue with partial results (W001)
 
 S_CROSS_VERIFY:
-  → S_SYNTHESIZE    DO: A_CLASSIFY_FINDINGS
+  → S_BOUNDARY_GRILL  DO: A_CLASSIFY_FINDINGS
+
+S_BOUNDARY_GRILL:
+  → S_SYNTHESIZE    WHEN: no boundary conflicts detected     DO: —
+  → S_SYNTHESIZE    WHEN: conflicts detected + resolved      DO: A_BOUNDARY_GRILL
+  GUARD: max 3 conflicts × 3 questions; non-blocking
 
 S_SYNTHESIZE:
   → S_REGISTER      DO: A_GENERATE_OUTPUTS
@@ -136,6 +141,12 @@ Read all per-tool outputs. For each finding:
 consensus_level = consensus_count / total_findings * 100.
 If consensus_level < 40%: W003.
 
+### A_BOUNDARY_GRILL
+
+Run boundary grill per `~/.maestro/workflows/boundary-grill.md`.
+Input: classified CONFLICT findings + per-tool outputs. Check upstream scope if `--from` used.
+IF conflicts → tag with resolution, feed into A_GENERATE_OUTPUTS. No conflicts → pass through.
+
 ### A_GENERATE_OUTPUTS
 
 Resolve conflicts via evidence-weighted voting:
@@ -162,6 +173,8 @@ Write 3 files:
 <success_criteria>
 - [ ] All delegates launched in parallel via shell(run_in_background: true), STOP after launch
 - [ ] Cross-verification: consensus/conflict/unique classification with consensus_level
+- [ ] Boundary grill executed on CONFLICT items (skip if no boundary conflicts detected)
+- [ ] Boundary grill results written to collab-report.md § Boundary Grill Results (if conflicts found)
 - [ ] 3 output files produced (collab-report.md, context.md, conclusions.json)
 - [ ] CLB artifact registered in state.json
 - [ ] Partial degradation: continued if 1+ tools succeeded

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

@@ -271,7 +271,7 @@ Odyssey 长周期循环（独立路径）
   odyssey-debug / odyssey-improve / odyssey-review-test-fix / odyssey-planex / odyssey-ui
 
 自适应引擎（高级）
-  ralph / ralph-beta → 自运行决策循环
+  ralph → 自运行决策循环
   swarm-workflow / universal-workflow → 多 agent 并行执行
 ```
 

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

@@ -68,7 +68,6 @@
 
     {"name": "maestro-ralph", "command": "/maestro-ralph", "category": "ralph", "description": "Ralph 引擎 — 自适应生命周期决策节点管理", "source": "../../commands/maestro-ralph.md"},
     {"name": "maestro-ralph-execute", "command": "/maestro-ralph-execute", "category": "ralph", "description": "Ralph 执行 — 运行自适应决策链", "source": "../../commands/maestro-ralph-execute.md"},
-    {"name": "maestro-ralph-beta", "command": "/maestro-ralph-beta", "category": "ralph", "description": "Ralph Beta — 自运行循环控制器，单 skill 完成 build/tick/decide", "source": "../../commands/maestro-ralph-beta.md"},
 
     {"name": "maestro-impeccable", "command": "/maestro-impeccable", "category": "ui", "description": "UI 生产 — 设计系统生成 + impeccable 链式编排 + 质量门控", "source": "../../commands/maestro-impeccable.md"},
     {"name": "maestro-ui-codify", "command": "/maestro-ui-codify", "category": "ui", "description": "UI 固化 — 将设计产出转化为知识资产", "source": "../../commands/maestro-ui-codify.md"},

package/.agents/skills/maestro-help/phases/01-parse-intent.md

@@ -61,7 +61,7 @@ const knownCommands = [
   "maestro", "analyze", "plan", "execute", "init", "roadmap",
   "brainstorm", "blueprint", "quick", "overlay", "amend", "fork", "merge", "collab",
   "milestone-audit", "milestone-complete", "milestone-release",
-  "composer", "guard", "player", "ralph", "ralph-execute", "ralph-beta",
+  "composer", "guard", "player", "ralph", "ralph-execute",
   "grill", "next", "swarm-workflow", "universal-workflow", "companion",
   "impeccable", "ui-codify", "update",
   "tools-register", "tools-execute",

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

@@ -94,9 +94,9 @@ S_FALLBACK:
 读 project state 推断 `lifecycle_position`（核心信号）：
 
 ```bash
-cat .workflow/state.json 2>$null              # phase / milestone / artifacts
-ls -la .workflow/scratch/ 2>$null | head -10  # 最近 artifact (mtime DESC)
-ls -la .workflow/.maestro/ 2>$null | head -5  # 进行中的 session
+cat .workflow/state.json 2>/dev/null              # phase / milestone / artifacts
+ls -la .workflow/scratch/ 2>/dev/null | head -10  # 最近 artifact (mtime DESC)
+ls -la .workflow/.maestro/ 2>/dev/null | head -5  # 进行中的 session
 ```
 
 **项目状态 → lifecycle_position → 自然下一步：**
@@ -112,7 +112,8 @@ ls -la .workflow/.maestro/ 2>$null | head -5  # 进行中的 session
 | 最新 artifact = plan | execute | `maestro-execute {phase}` |
 | 最新 artifact = execute | review | `quality-review {phase}` |
 | review verdict=PASS | test-gen | `quality-auto-test {phase}` |
-| 测试全绿 | milestone-audit | `maestro-milestone-audit` |
+| 测试全绿 + current_milestone 存在 | milestone-audit | `maestro-milestone-audit` |
+| 测试全绿 + current_milestone=null (standalone) | review-done | 回退到 `quality-review` 或 `manage-status`（无 milestone 上下文时不推荐 milestone 命令） |
 | 当前 milestone 全 phase 完成 | milestone-complete | `maestro-milestone-complete` |
 | 任一 stage 产物含 gaps/failed | debug | `quality-debug {gap}` |
 
@@ -135,6 +136,16 @@ brainstorm → blueprint → init → analyze-macro → roadmap
 | `name` 关键词命中 intent | 中 | intent 含 "test" → quality-test/quality-auto-test 加分 |
 | Workflow 簇匹配 | 中 | intent 涉及学习/知识/issue 等场景触发对应簇 |
 | Recent activity 反向避免 | 低 | 刚完成的 stage 短期内降权 |
+| **前置条件不满足** | **禁止** | 候选命令的前置条件未满足时，直接从候选池移除（如 `maestro-milestone-*` 在 `current_milestone=null` 时移除） |
+
+**前置条件检查（评分前执行，不满足则移除候选）：**
+
+| 命令 | 前置条件 |
+|------|---------|
+| `maestro-milestone-audit` | `current_milestone` 存在且非 null |
+| `maestro-milestone-complete` | `current_milestone` 存在且非 null |
+| `maestro-milestone-release` | `current_milestone` 存在且非 null |
+| `maestro-merge` | 存在活跃的 fork 分支 |
 
 **特殊意图处理：**
 

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

@@ -23,7 +23,10 @@ Turn natural-language instructions into command overlays — JSON patch files th
 </required_reading>
 
 <context>
-**Overlay model** — an overlay is a JSON file with a `name`, one or more `targets` (command names without `.md`), and a list of `patches`. Each patch targets an XML section (`execution`, `required_reading`, `context`, `success_criteria`, etc.), a mode (`append`, `prepend`, `replace`, `new-section`), and `content`. On apply, the patcher wraps the content in hashed HTML-comment markers so re-apply is idempotent and removal is surgical.
+**Overlay model**:
+- JSON file: `name`, `targets[]` (command names), `patches[]`
+- Patch: `section` (XML tag), `mode` (append/prepend/replace/new-section), `content`
+- Apply: hashed HTML-comment markers (idempotent, surgical removal)
 
 **Where overlays live**
 - User overlays: `~/.maestro/overlays/*.json` — created by this skill
@@ -141,8 +144,6 @@ Run:
 maestro overlay add ~/.maestro/overlays/<slug>.json
 ```
 
-This validates the overlay, copies it into place (idempotent), and applies it across all known install scopes. On validation failure, fix the JSON and re-run.
-
 ### 5. Report
 
 Show the user: