maestro-flow 0.5.35 → 0.5.36

package/.agy/skills/manage-kg-extractors/SKILL.md

@@ -17,8 +17,6 @@ allowed-tools:
 
 <purpose>
 Analyze current repository's code patterns to auto-generate `.workflow/kg/extractors.yaml` — a declarative config that teaches MaestroGraph's codegraph extractor to recognize project-specific symbols beyond standard function/class/method declarations.
-
-Detects: builder/factory API registrations, domain constant patterns, custom decorator conventions, framework-specific patterns, module-level constants.
 </purpose>
 
 <context>

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

@@ -33,8 +33,6 @@ Flags, artifact context resolution, and output directory format defined in workf
 
 ### Frontend Verify Mode (`--frontend-verify`)
 
-补 ralph 链路缺失的运行时可用性门：确定性验证每个用户可观测能力真正经 UI 可触发，避免"后端绿灯=完成"。
-
 1. **Resolve targets**: 读 phase 的 `plan.json` / `.task/TASK-*.json`，提取所有 `[UI-observable]` convergence.criteria（plan 阶段产出）；缺失则枚举后端写端点（POST/PUT/PATCH/DELETE）作为待验证清单。
 2. **Start app**: `next start`（或从 dashboard/package.json 解析的既有启动脚本）；启动失败 → E003。
 3. **Drive browser**: 用 chrome-devtools MCP（`mcp__claude_dms3-chrome-devtools__*`：navigate / click / fill / take_snapshot / list_network_requests）逐条执行每个 `[UI-observable]` 流程，断言：UI 入口存在且可触发 → 对应写请求返回 2xx → DOM 出现预期结果。

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

@@ -74,4 +74,3 @@ Follow '~/.maestro/workflows/specs-load.md' completely.
 - [ ] Legacy entries filtered by text grep fallback
 - [ ] Results displayed with file:category references
 </success_criteria>
-</output>

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

@@ -45,4 +45,3 @@ Follow '~/.maestro/workflows/specs-setup.md' completely.
 - [ ] Workflow recipe knowhow created in `.workflow/knowhow/` for each detected operational workflow (test / debug / build / dev / lint). Each recipe matches the `recipe` schema in `~/.maestro/workflows/knowhow.md` Part B and contains at least one runnable command.
 - [ ] Report displayed grouped by destination (specs / recipes / skipped / deferred), with `.proposed.md` files surfaced when an existing recipe slug was preserved.
 </success_criteria>
-</output>

package/.agy/skills/team-lifecycle-v4/roles/analyst/role.md

@@ -48,15 +48,21 @@ Research and codebase exploration for context gathering.
 | package.json / Cargo.toml / pyproject.toml / go.mod exists | Explore |
 | No project files | Skip (codebase_context = null) |
 
-When project detected:
-```
-run_command({ command: `maestro delegate "PURPOSE: Explore codebase for context
-TASK: • Identify tech stack • Map architecture patterns • Document conventions • List integration points
-MODE: analysis
-CONTEXT: @**/*
-EXPECTED: JSON with: tech_stack[], architecture_patterns[], conventions[], integration_points[]" --tool gemini --mode analysis`, run_in_background: false })
+When project detected — prefer `maestro explore` multi-prompt:
+```bash
+maestro explore \
+  "FIND: tech stack and framework detection
+SCOPE: package.json, Cargo.toml, pyproject.toml, go.mod, src/
+EXPECTED: tech_stack list with versions" \
+  "FIND: architecture patterns and conventions
+SCOPE: src/
+EXCLUDE: tests, node_modules
+EXPECTED: patterns list with file:line evidence" \
+  --max-turns 3 --json
 ```
 
+**Fallback**: `maestro delegate "PURPOSE: Explore codebase for context ..." --tool gemini --mode analysis`
+
 ### Tech Profile Scan
 
 After codebase exploration, scan results for context-aware trigger signals (based on detected codebase characteristics):

package/.agy/skills/team-quality-assurance/roles/scout/role.md

@@ -36,18 +36,22 @@ Scan codebase from multiple perspectives (bug, security, test-coverage, code-qua
 
 **Low complexity**: Use `` for quick pattern-based scan.
 
-**Medium/High complexity**: CLI fan-out -- one `maestro delegate --mode analysis` per perspective:
-
-For each active perspective, build prompt:
-```
-PURPOSE: Scan code from <perspective> perspective to discover potential issues
-TASK: Analyze code patterns for <perspective> problems, identify anti-patterns, check for common issues
-MODE: analysis
-CONTEXT: @<scan-scope>
-EXPECTED: List of findings with severity (critical/high/medium/low), file:line references, description
-CONSTRAINTS: Focus on actionable findings only
+**Medium/High complexity**: Multi-prompt `maestro explore` (preferred for read-only scan):
+
+Build one prompt per active perspective:
+```bash
+maestro explore \
+  "FIND: <perspective1> issues and anti-patterns
+SCOPE: <scan-scope>
+ATTENTION: common <perspective1> problems
+EXPECTED: severity + file:line + description" \
+  "FIND: <perspective2> issues and anti-patterns
+SCOPE: <scan-scope>
+EXPECTED: severity + file:line + description" \
+  --max-turns 3 --json
 ```
-Execute via: `maestro delegate "<prompt>" --role analyze --mode analysis`
+
+**Fallback** (when deeper analysis needed per perspective): `maestro delegate "<prompt>" --role analyze --mode analysis`
 
 After all perspectives complete:
 - Parse CLI outputs into structured findings

package/.agy/skills/team-tech-debt/roles/scanner/role.md

@@ -55,7 +55,7 @@ Multi-dimension tech debt scanner. Scan codebase across 5 dimensions (code, arch
 - Classify findings into dimensions
 
 **Medium/High Complexity** (Fan-out):
-- Fan-out A: CLI exploration (structure, patterns, dependencies angles) via `maestro delegate --role explore --mode analysis`
+- Fan-out A: `maestro explore` multi-prompt parallel (structure, patterns, dependencies angles) — preferred over delegate for exploration
 - Fan-out B: CLI dimension analysis (parallel per dimension -- code, architecture, testing, dependency, documentation) via `--role analyze`
 - Fan-out C (High only): Multi-perspective analysis (security, performance, code-quality, architecture) via `--role analyze`
 - Fan-in: Merge results, cross-deduplicate by file:line, boost severity for multi-source findings

package/.agy/skills/team-ultra-analyze/roles/explorer/role.md

@@ -39,24 +39,31 @@ Explore codebase structure through cli-explore-agent, collecting structured cont
 
 ## Phase 3: Codebase Exploration
 
-Use CLI tool for codebase exploration:
-
-```javascript
-run_command({
-  command: `maestro delegate "PURPOSE: Explore codebase for <topic> from <perspective> perspective; success = structured findings with relevant files and patterns
-TASK: • Run module depth analysis • Search for topic-related patterns • Identify key files and their relationships • Extract architectural insights
-MODE: analysis
-CONTEXT: @**/* | Memory: Session <session-folder>, perspective <perspective>
-EXPECTED: JSON output with: relevant_files (path, relevance, summary), patterns, key_findings, module_map, questions_for_analysis, _metadata (perspective, search_queries, timestamp)
-CONSTRAINTS: Focus on <perspective> angle - <strategy.focus> | Write to <session>/explorations/exploration-<num>.json
-" --tool gemini --mode analysis --rule analysis-analyze-code-patterns`,
-  run_in_background: false
-})
+**Primary: `maestro explore`** (structured multi-prompt):
+
+```bash
+maestro explore \
+  "FIND: <topic> patterns and implementations
+SCOPE: src/
+ATTENTION: <perspective>-specific concerns
+EXPECTED: file:line evidence with relevance" \
+  "FIND: module boundaries and relationships for <topic>
+SCOPE: src/
+EXCLUDE: tests, generated code
+EXPECTED: dependency pairs and architectural insights" \
+  --max-turns 3 --json
 ```
 
-**ACE fallback** (when CLI produces no output):
-```javascript
-({ project_root_path: ".", query: "<topic> <perspective>" })
+Parse JSON results → extract relevant_files, patterns, key_findings.
+
+**Fallback: `maestro delegate`** (when explore results insufficient):
+
+```bash
+maestro delegate "PURPOSE: Explore codebase for <topic> from <perspective> perspective
+TASK: Search for topic-related patterns | Identify key files and relationships | Extract architectural insights
+EXPECTED: JSON with relevant_files, patterns, key_findings
+CONSTRAINTS: Focus on <perspective> angle
+" --tool gemini --mode analysis --rule analysis-analyze-code-patterns
 ```
 
 ## Phase 4: Result Validation

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

@@ -11,96 +11,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)
@@ -112,39 +119,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
@@ -170,16 +173,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/.claude/agents/workflow-analyzer.md

@@ -40,6 +40,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/.claude/agents/workflow-debugger.md

@@ -50,6 +50,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/.claude/agents/workflow-executor.md

@@ -67,6 +67,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/.claude/commands/domain-add.md

@@ -0,0 +1,69 @@
+---
+name: domain-add
+description: Register a domain term into project glossary
+argument-hint: "<canonical> \"<definition>\""
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+<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/.claude/commands/maestro-amend.md

@@ -12,8 +12,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/.claude/commands/maestro-analyze.md

@@ -23,6 +23,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>
@@ -94,6 +95,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.
@@ -193,6 +200,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/.claude/commands/maestro-brainstorm.md

@@ -25,6 +25,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>
@@ -88,8 +89,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.
@@ -191,6 +198,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 (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/.claude/commands/maestro-collab.md

@@ -73,7 +73,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
@@ -134,6 +139,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:
@@ -160,6 +171,8 @@ Write 3 files:
 <success_criteria>
 - [ ] All delegates launched in parallel via Bash(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/.claude/commands/maestro-next.md

@@ -92,9 +92,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 → 自然下一步：**
@@ -110,7 +110,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}` |
 
@@ -133,6 +134,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 分支 |
 
 **特殊意图处理：**