maestro-flow 0.5.34 → 0.5.36

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

@@ -39,18 +39,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/.claude/skills/team-tech-debt/roles/scanner/role.md

@@ -56,7 +56,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/.claude/skills/team-ultra-analyze/roles/explorer/role.md

@@ -41,24 +41,31 @@ Explore codebase structure through cli-explore-agent, collecting structured cont
 
 ## Phase 3: Codebase Exploration
 
-Use CLI tool for codebase exploration:
-
-```javascript
-Bash({
-  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/.codex/skills/domain-add/SKILL.md

@@ -0,0 +1,79 @@
+---
+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).
+
+```bash
+$domain-add "auth-token" "Short-lived credential for API authentication"
+$domain-add "event-bus" "Central pub-sub message broker for cross-module communication"
+```
+
+**CLI alternative**: `maestro domain add "<canonical>" "<definition>" --tier core|extended|peripheral`. Used by finish-work for programmatic domain term extraction from session outputs.
+</purpose>
+
+<context>
+$ARGUMENTS — `<canonical> <definition>` where canonical is a kebab-case term name.
+
+**Prerequisites**: `.workflow/domain/` must exist (run `maestro domain init` if missing).
+
+**Domain term lifecycle**: discover/manual → register → active → (optional) deprecated → removed
+</context>
+
+<execution>
+
+### Step 1: Parse Input
+
+Extract canonical (first token, kebab-case) and definition (remainder) from arguments.
+- Validate canonical is non-empty, kebab-case (lowercase, hyphens only)
+- Validate definition is non-empty, ≤200 chars (E001 if missing)
+
+### Step 2: Validate Domain Directory
+
+Verify `.workflow/domain/glossary.yaml` exists (E002). If not, run `maestro domain init`.
+
+### Step 3: Check Duplicates
+
+Read existing glossary and check for:
+- Exact duplicate (same canonical name) → report existing entry, exit
+- Near match (Levenshtein ≤ 2 or alias overlap) → warn, ask to confirm or merge
+
+### Step 4: Extract Metadata
+
+Auto-derive from the definition and codebase context:
+- **aliases** (1-3): common abbreviations, Chinese translations, alternate forms
+- **keywords** (3-5): search terms for discovery
+- **tier**: `core` | `extended` | `peripheral`
+- **relationships**: scan existing glossary for related terms
+
+### Step 5: Register Term
+
+```bash
+maestro domain add "<canonical>" "<definition>" --tier <tier>
+maestro domain update "<canonical>" --aliases "alias1,alias2" --keywords "kw1,kw2" --relationships "rel1,rel2"
+```
+
+### Step 6: Confirm
+
+Display: canonical name, definition, aliases, tier, relationships, and verify command `maestro domain list`.
+</execution>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | Canonical name and definition are both required |
+| E002 | fatal | `.workflow/domain/` not initialized — run `maestro domain init` first |
+| E003 | fatal | Term already registered with same canonical name |
+</error_codes>
+
+<success_criteria>
+- [ ] Canonical name and definition parsed and validated
+- [ ] No duplicate term in glossary
+- [ ] Aliases and keywords auto-extracted
+- [ ] Term written to glossary.yaml with tier and relationships
+- [ ] Confirmation displayed with verify command
+</success_criteria>

package/.codex/skills/domain-discover/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: domain-discover
+description: Discover domain term candidates from codebase
+argument-hint: "[--auto]"
+allowed-tools: Read, Bash, Glob, Grep
+---
+
+<purpose>
+Scan codebase for potential domain terms not yet in `.workflow/domain/glossary.yaml`. Presents candidates with confidence scores for interactive registration.
+
+`--auto`: auto-register candidates with confidence ≥ 0.8 without prompting.
+</purpose>
+
+<execution>
+
+### Step 1: Scan Codebase
+
+Run `maestro domain discover` to scan TypeScript interfaces, types, enums, const patterns, API routes, and README headings.
+
+### Step 2: Filter Existing
+
+Remove candidates already registered in glossary.yaml (by canonical name or alias match).
+
+### Step 3: Present Candidates
+
+Display ranked candidates with confidence scores:
+
+```
+=== DOMAIN TERM CANDIDATES ({N} found) ===
+
+  0.92  session-context — Runtime state container for active workflow session
+  0.85  skill-resolver — Module that maps skill names to SKILL.md file paths
+  0.71  chain-graph — DAG definition for multi-step command sequences
+  ...
+
+Register? (all | select by number | skip)
+```
+
+### Step 4: Register Selected
+
+For each confirmed candidate, run `maestro domain add "<canonical>" "<definition>"`.
+
+</execution>

package/.codex/skills/domain-list/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: domain-list
+description: List registered domain terms from glossary
+argument-hint: "[--tier core|extended|peripheral]"
+allowed-tools: Read, Bash, Glob, Grep
+---
+
+<purpose>
+List all registered domain terms from `.workflow/domain/glossary.yaml`. Shows canonical name, definition, tier, aliases, and status.
+</purpose>
+
+<execution>
+
+### Step 1: Load Glossary
+
+Read `.workflow/domain/glossary.yaml`. If not exists, report "No domain glossary — run `maestro domain init`".
+
+### Step 2: Filter and Display
+
+Apply optional `--tier` filter. Display terms grouped by tier (core → extended → peripheral):
+
+```
+=== DOMAIN TERMS ({N} total) ===
+
+[core]
+  auth-token — Short-lived credential for API authentication
+    aliases: 令牌, access-token | keywords: auth, credential, jwt
+  event-bus — Central pub-sub message broker
+    aliases: 事件总线 | keywords: pubsub, messaging
+
+[extended]
+  ...
+
+[deprecated]
+  wikiindexer → search-engine (successor)
+```
+
+</execution>

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

@@ -9,9 +9,6 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
 Guided reading experience for code files, wiki entries, or topics. Walks through content
 section by section using 4 forcing questions to extract patterns, identify assumptions,
 and build a structured understanding map. Insights persist to `.workflow/specs/learnings.md`.
-
-Unlike `learn-decompose` which is parallel pattern extraction, this is sequential
-deep reading that builds understanding incrementally.
 </purpose>
 
 <context>

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

@@ -9,9 +9,6 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
 Systematic investigation for understanding questions (not bug-fixing). 4-phase approach
 with scope lock and 3-strike escalation. Produces structured evidence trails and
 understanding documents that persist to the learning system.
-
-Unlike `quality-debug` (fixing bugs during execution), this answers "how does X work?",
-"why does Y happen?", "what would happen if Z?" questions.
 </purpose>
 
 <context>

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

@@ -10,8 +10,6 @@ Unified retrospective combining git activity analysis and decision quality evalu
 Two lenses, usable independently or together:
 - **git**: Commit metrics, session detection, per-author breakdown, file hotspots, trends
 - **decision**: Decision tracing across wiki/specs/git, multi-perspective evaluation via 3 parallel agents
-
-Works on raw git history and wiki/spec data — does not require completed phase artifacts.
 </purpose>
 
 <context>

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

@@ -180,6 +180,9 @@ Extract:
 | `overlay` | Create/edit command overlays |
 | `update` | Update maestro itself |
 | `harvest` | Extract knowledge from artifacts |
+| `domain_add` | Register a domain term into glossary |
+| `domain_list` | List registered domain terms |
+| `domain_discover` | Discover domain term candidates from codebase |
 | `wiki` | Manage wiki graph |
 | `knowhow` | Manage knowhow entries |
 | `ui_design` | UI design, build new UI |
@@ -293,7 +296,7 @@ Read `.workflow/state.json` and route by condition:
      "scope_verdict": null, "analyze_macro_id": null, "blueprint_id": null,
      "auto_mode": false,
      "context": { "issue_id": null, "scratch_dir": null, "plan_dir": null,
-       "analysis_dir": null, "brainstorm_dir": null, "blueprint_dir": null },
+       "analysis_dir": null, "brainstorm_dir": null, "blueprint_dir": null, "grill_id": null },
      "steps": [{
        "index": 0, "type": "skill|decision",
        "skill": "", "args": "",
@@ -328,12 +331,27 @@ Read `.workflow/state.json` and route by condition:
 
 Direct in-context skill invocation — **replaces the old spawn/wave/CSV mechanism**.
 
-1. **buildSkillCall**: replace placeholders `{phase}`/`{plan_dir}`/`{analysis_dir}`/`{brainstorm_dir}`/`{spec_session_id}`; append auto-yes flag if `auto_mode` (see Appendix: Auto-Yes Flag Map)
+1. **buildSkillCall**: replace placeholders + append auto-yes flag if `auto_mode` (see Appendix: Auto-Yes Flag Map):
+
+   | Placeholder | Source |
+   |-------------|--------|
+   | `{phase}` | session.phase |
+   | `{plan_dir}` | session.context.plan_dir |
+   | `{analysis_dir}` | session.context.analysis_dir |
+   | `{brainstorm_dir}` | session.context.brainstorm_dir |
+   | `{spec_session_id}` | session.context.spec_session_id |
+   | `{GRL}` | session.context.grill_id |
+   | `{ANL}` | session.analyze_macro_id |
+   | `{BLP}` | session.blueprint_id |
+   | `{intent}` | session.intent |
+
+   **--from auto-injection**: 当 step 是 `maestro-plan`，args 含 `{phase}` 但无 `--from` 且无 `--dir`，且 `session.context.analysis_dir` 已填充 → 查 state.json 同 phase+milestone 最新 completed analyze artifact → 注入 `--from analyze:{id}`，写 `step.source_artifact_ref`
 2. Mark step `status="running"`, persist status.json + `update_plan` (this step → in_progress)
 3. **Invoke the skill directly**: execute `$skill {resolved_args}` in coordinator context (NO spawn). Read its produced artifacts directly
 4. On success: capture summary; mark step `status="done"`. **Barrier-context update** (when step is a context-producing skill):
    | Skill | Read | Context Updates |
    |-------|------|-----------------|
+   | maestro-grill | grill-report.md, state.json | grill_id |
    | maestro-analyze | context.md, state.json | analysis_dir, gaps, phase |
    | maestro-plan | plan.json, .task/TASK-*.json | plan_dir, task_count |
    | maestro-brainstorm | .brainstorming/ | brainstorm_dir, features |
@@ -419,6 +437,9 @@ S_DECISION_EVAL 入口；镜像 maestro-ralph `A_GOAL_AUDIT_EVALUATE`。Condense
 | `spec_load` | `spec-load` |
 | `spec_map` | `manage-codebase-rebuild` |
 | `spec_remove` | `spec-remove "{description}"` |
+| `domain_add` | `domain-add "{description}"` |
+| `domain_list` | `domain-list` |
+| `domain_discover` | `domain-discover` |
 | `knowhow_capture` | `manage-knowhow-capture "{description}"` |
 | `knowhow` | `manage-knowhow "{description}"` |
 | `issue` | `manage-issue "{description}"` |
@@ -444,26 +465,26 @@ S_DECISION_EVAL 入口；镜像 maestro-ralph `A_GOAL_AUDIT_EVALUATE`。Condense
 
 | Chain | Steps (→ = sequential, [B] = context-producing barrier) |
 |-------|---------------------------------------|
-| `feature` | [B] maestro-plan → [B] maestro-execute → quality-review |
+| `feature` | [B] maestro-plan → [B] maestro-execute → quality-review → manage-harvest --auto |
 | `quality-fix` | [B] maestro-analyze --gaps → [B] maestro-plan --gaps → [B] maestro-execute → quality-review |
 | `deploy` | quality-review → maestro-milestone-release |
-| `blueprint-driven` | maestro-init → [B] maestro-blueprint → [B] maestro-plan --from blueprint:{BLP} → [B] maestro-execute → quality-review |
-| `analyze-macro-driven` | [B] maestro-analyze "{intent}" → ◆ post-analyze-scope → (large: [B] maestro-roadmap --from analyze:{ANL} → [B] maestro-analyze {phase} → [B] maestro-plan {phase}) / (medium\|small: [B] maestro-plan --from analyze:{ANL}) → [B] maestro-execute → quality-review |
-| `grill-brainstorm` | [B] maestro-grill → [B] maestro-brainstorm --from grill:{GRL} → [B] maestro-plan → [B] maestro-execute → quality-review (**auto_mode: skip grill step, fall back to brainstorm-driven**) |
-| `brainstorm-driven` | [B] maestro-brainstorm → [B] maestro-plan → [B] maestro-execute → quality-review |
-| `ui-craft-build` | maestro-impeccable build → [B] maestro-plan → [B] maestro-execute → quality-review |
-| `roadmap-driven` | maestro-init → [B] maestro-roadmap → [B] maestro-plan → [B] maestro-execute → quality-review |
-| `next-milestone` | [B] maestro-roadmap → [B] maestro-plan → [B] maestro-execute → quality-review |
-| `full-lifecycle` | [B] maestro-plan → [B] maestro-execute → quality-review → quality-test → maestro-milestone-audit → maestro-milestone-complete |
+| `blueprint-driven` | maestro-init → [B] maestro-blueprint → [B] maestro-plan --from blueprint:{BLP} → [B] maestro-execute → quality-review → manage-harvest --auto |
+| `analyze-macro-driven` | [B] maestro-analyze "{intent}" → ◆ post-analyze-scope → (large: [B] maestro-roadmap --from analyze:{ANL} → [B] maestro-analyze {phase} → [B] maestro-plan {phase}) / (medium\|small: [B] maestro-plan --from analyze:{ANL}) → [B] maestro-execute → quality-review → manage-harvest --auto |
+| `grill-brainstorm` | [B] maestro-grill → [B] maestro-brainstorm --from grill:{GRL} → [B] maestro-plan → [B] maestro-execute → quality-review → manage-harvest --auto (**auto_mode: skip grill step, fall back to brainstorm-driven**) |
+| `brainstorm-driven` | [B] maestro-brainstorm → [B] maestro-plan → [B] maestro-execute → quality-review → manage-harvest --auto |
+| `ui-craft-build` | maestro-impeccable build → [B] maestro-plan → [B] maestro-execute → quality-review → manage-harvest --auto |
+| `roadmap-driven` | maestro-init → [B] maestro-roadmap → [B] maestro-plan → [B] maestro-execute → quality-review → manage-harvest --auto |
+| `next-milestone` | [B] maestro-roadmap → [B] maestro-plan → [B] maestro-execute → quality-review → manage-harvest --auto |
+| `full-lifecycle` | [B] maestro-plan → [B] maestro-execute → quality-review → quality-test → maestro-milestone-audit → maestro-milestone-complete → manage-harvest --auto |
 | `execute-review` | [B] maestro-execute → quality-review |
-| `analyze-plan-execute` | [B] maestro-analyze -q → [B] maestro-plan --dir {scratch_dir} → [B] maestro-execute --dir {scratch_dir} |
+| `analyze-plan-execute` | [B] maestro-analyze -q → [B] maestro-plan --dir {scratch_dir} → [B] maestro-execute --dir {scratch_dir} → manage-harvest --auto |
 | `quality-loop` | quality-review → quality-test → quality-debug --from-uat → [B] maestro-plan --gaps → [B] maestro-execute |
 | `quality-loop-partial` | [B] maestro-plan --gaps → [B] maestro-execute → quality-review |
 | `review-fix` | [B] maestro-plan --gaps → [B] maestro-execute → quality-review |
 | `milestone-close` | maestro-milestone-audit → maestro-milestone-complete |
 | `milestone-release` | maestro-milestone-audit → maestro-milestone-release |
 | `phase_transition` | maestro-milestone-audit → maestro-milestone-complete |
-| `issue-full` | [B] maestro-analyze --gaps → [B] maestro-plan --gaps → [B] maestro-execute → quality-review → manage-issue close |
+| `issue-full` | [B] maestro-analyze --gaps → [B] maestro-plan --gaps → [B] maestro-execute → quality-review → manage-issue close → manage-harvest --auto |
 | `issue-quick` | [B] maestro-plan --gaps → [B] maestro-execute → quality-review → manage-issue close |
 
 > When S_DECOMPOSE ran, a `decision:post-goal-audit` node is appended as the final node (after the last evidence-producing step; before milestone-complete/close-out if the chain ends with one). `[B]` now denotes a context-producing skill (artifacts read into `session.context`) — execution is still sequential (no parallelism; spawning removed).

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

@@ -6,8 +6,6 @@ allowed-tools: Read, Write, Bash, Glob, Grep, request_user_input
 ---
 <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/.codex/skills/maestro-analyze/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-analyze
 description: Use when a topic needs structured multi-dimensional investigation before planning or decision-making
-argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] [--from <source>] \"<phase|topic> [-q|--quick] [--gaps [ISS-ID]]\""
+argument-hint: "[-y|--yes] [--concurrency N] [-c|--continue] [--from <source>] \"<phase|topic> [-q|--quick] [--gaps [ISS-ID]]\""
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
@@ -14,8 +14,6 @@ Wave 1 (CLI exploration, parallel) -> Wave 2 (6-dimension scoring, parallel) ->
 **Dual-layer scope (D-003)**:
 - **Macro layer** (text argument, e.g. `analyze "auth refactor"`): broad impact exploration. Produces `scope_verdict ∈ {small, medium, large}` to drive downstream routing (roadmap vs plan).
 - **Phase layer** (numeric argument, e.g. `analyze 1`): phase-scoped deep analysis under `current_milestone`. Milestone resolved via D-007 `phase_slugs` reverse lookup, NEVER direct `current_milestone` read.
-
-Produces context-package.json (standardized cross-command context contract) in all modes.
 </purpose>
 
 <context>
@@ -23,14 +21,22 @@ $ARGUMENTS -- phase number, topic text, and optional flags.
 
 **Flags**:
 - `-y, --yes`: Skip all confirmations (auto mode)
-- `-c, --concurrency N`: Max concurrent agents per wave (default: 6)
+- `--concurrency N`: Max concurrent agents per wave (default: 6)
+- `-c, --continue`: Resume existing session
 - `--continue`: Resume existing session
 - `-q, --quick`: Skip exploration + scoring, Wave 3 only
 - `--gaps [ISS-ID]`: Issue root cause analysis. If ISS-ID: single issue. If omitted: all open/registered from issues.jsonl.
-- `--from <source>`: Load upstream context package (brainstorm:ID, analyze:ID, @file, or path). Resolves to context-package.json for upstream context inheritance.
+- `--from <source>`: Load upstream context package (grill:ID, brainstorm:ID, analyze:ID, blueprint:BLP-xxx, @file, or path). Resolves to context-package.json via state.json artifact lookup for typed references, or direct path for @file/path.
 
 **Session**: `.workflow/.csv-wave/{YYYYMMDD}-analyze-{slug}/`
 **Output**: tasks.csv, results.csv, discoveries.ndjson, context.md, context-package.json (all modes), analysis.md + conclusions.json (full mode AND quick mode; quick writes minimal conclusions.json with `scope_verdict` + `implementation_scope[]` only)
+
+### Pre-load (runs unconditionally, including -y auto mode)
+1. **Codebase docs**: IF `.workflow/codebase/doc-index.json` exists → Read ARCHITECTURE.md for module boundaries
+2. **Specs**: `maestro spec load --category arch` — load architecture constraints
+3. **Wiki search**: `maestro search "{topic keywords}" --json` → top 5-10 entries as prior knowledge
+4. **Role Knowledge**: `maestro search --category debug` → select relevant → `maestro wiki load`
+5. All optional — proceed without if unavailable (log warning)
 </context>
 
 <interview_protocol>
@@ -143,7 +149,12 @@ S_WAVE_1:
   -> ERROR        WHEN: all failed
 
 S_WAVE_2:
-  -> S_WAVE_3     DO: A_SPAWN_WAVE_2
+  -> S_BOUNDARY_GRILL   DO: A_SPAWN_WAVE_2
+
+S_BOUNDARY_GRILL:
+  -> S_WAVE_3     WHEN: no boundary conflicts detected     DO: —
+  -> S_WAVE_3     WHEN: conflicts detected + resolved      DO: A_BOUNDARY_GRILL
+  GUARD: max 3 conflicts × 3 questions; non-blocking (see boundary-grill.md)
 
 S_WAVE_3:
   -> S_AGGREGATE  DO: A_SPAWN_WAVE_3
@@ -229,6 +240,14 @@ Write to `conclusions.json.scope_verdict` (all modes that produce conclusions);
 
 Gray area detection: domain-aware (things users SEE/CALL/RUN/READ), phase-specific (skip prior decided areas).
 
+### A_BOUNDARY_GRILL
+
+Run boundary grill per `~/.maestro/workflows/boundary-grill.md` after Wave 2 scoring, before Wave 3 synthesis.
+Input: Wave 1 exploration findings + Wave 2 dimension scores. Scope guard: "only analyze decisions; do not prejudge plan/execute concerns".
+Detect RSC (scope violations), MOD (module boundary crossings), DEC (upstream locked vs code reality).
+IF conflicts → results to `analysis.md` § Boundary Grill Results + update `context.md` Locked/Free/Deferred.
+Non-blocking: conflicts produce warnings, pipeline continues.
+
 ### A_AGGREGATE_RESULTS
 
 1. Export results.csv
@@ -302,6 +321,8 @@ Protocol: read before analysis, append-only, dedup by type+key.
 - [ ] Decision Recording Protocol applied to all decisions
 - [ ] Confidence scored per dimension with factor-based model (full mode)
 - [ ] Readiness gate checked before synthesis (wave 3)
+- [ ] Boundary grill executed between Wave 2 and Wave 3 (skip if no conflicts detected)
+- [ ] Boundary grill results written to analysis.md § Boundary Grill Results (if conflicts found)
 - [ ] Pressure pass completed ≥ 1 time on highest-risk dimension before synthesis
 - [ ] Deferred items auto-created as issues
 - [ ] Scope creep redirected to Deferred section
@@ -310,8 +331,17 @@ Protocol: read before analysis, append-only, dedup by type+key.
 - [ ] discoveries.ndjson append-only throughout
 - [ ] Next step routed (plan for Go, brainstorm for No-Go, plan --gaps for Gaps)
 - [ ] Session sealed via finish-work (archive.json written, optional spec/knowhow extraction)
+- [ ] Ralph-invoked: `maestro ralph complete <idx> --status {STATUS}` called with correct verdict
 </success_criteria>
 
+<ralph_completion>
+When invoked as a ralph session step, end by calling the CLI (no standalone report):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+Status verdicts: **DONE** (normal), **DONE_WITH_CONCERNS** (caveats; pass `--concerns`), **NEEDS_RETRY** (transient error), **BLOCKED** (hard blocker; pass `--reason`).
+</ralph_completion>
+
 <on_complete>
 @~/.maestro/workflows/finish-work.md — SESSION_DIR=OUTPUT_DIR, SESSION_TYPE=analyze, SESSION_ID={artifact_id}, LINKED_MILESTONE={target_milestone or null}
 </on_complete>

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

@@ -7,10 +7,6 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, spawn_agents_on_csv, request
 <purpose>
 Formal specification document chain producing a complete specification package through 7 sequential phases (P0–P6, plus P1.5 requirement expansion) with multi-CLI analysis and interactive refinement. Pure documentation — no code generation, no roadmap generation.
 
-Parallel to `brainstorm` as an upstream origin command:
-- **brainstorm** = divergent exploration (lightweight, multi-role creative)
-- **blueprint** = convergent documentation (heavyweight, 7-phase formal spec chain)
-
 Output: `.workflow/blueprint/BLP-{slug}-{date}/` containing Product Brief, PRD, Architecture, and Epics.
 </purpose>
 

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-brainstorm
 description: Use when exploring ideas, evaluating approaches, or needing multi-perspective analysis before implementation
-argument-hint: "[topic] [-y|--yes] [-c|--concurrency N] [--continue] [--count N] [--skip-questions] [--review-only]"
+argument-hint: "[topic] [-y|--yes] [--concurrency N] [-c|--continue] [--count N] [--skip-questions] [--review-only]"
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
@@ -15,14 +15,31 @@ Wave 3 compares Decision Digests from each role's `analysis.md` §2 and patches
 <context>
 $ARGUMENTS — topic text and optional flags.
 
-**Flags**: `-y` (auto), `-c N` (concurrency, default 6), `--continue` (resume), `--count N` (roles, default 3 max 9), `--skip-questions`, `--review-only` (skip Wave 1/2; run Wave 3 only against existing */analysis.md)
+**Flags**: `-y` (auto), `--concurrency N` (default 6), `-c`/`--continue` (resume), `--count N` (roles, default 3 max 9), `--skip-questions`, `--review-only` (skip Wave 1/2; run Wave 3 only against existing */analysis.md), `--from <source>` (load upstream context package)
+
+**--from resolution** (upstream context loading):
+```
+--from grill:ID     → state.json.artifacts[type=grill, id=ID].context_package → load context-package.json
+--from blueprint:ID → state.json.artifacts[type=blueprint, id=ID].context_package → load
+--from @file        → load file directly as context-package.json
+--from path/        → load path/context-package.json
+```
+When loaded, pre-seed guidance-specification.md with:
+- `constraints[status=locked]` → §4 locked decisions (skip in interview)
+- `domain.terminology[]` → §2 Concepts & Terminology (seed)
+- `non_goals[]` → §3 Non-Goals (seed)
+- `open_questions[]` → interview priority topics
+- `insights[]` → W2 role analysis context
+
+When `--from` is absent, auto-discover from state.json: latest `type=grill` artifact in same milestone → load its `context_package` if available. No match → proceed without upstream context.
 
 **9 valid roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
 
-### Pre-load specs
+### Pre-load
 1. **Architecture specs**: `maestro spec load --category arch` — load architecture constraints as context for multi-role design (roles respect documented decisions).
 2. **Role Knowledge**: `maestro search --category arch` → identify relevant entries → `maestro wiki load <id1> [id2...]`
-3. Both optional — proceed without if unavailable.
+3. **Project context**: Read `.workflow/project.md` (if exists) → Validated requirements (already shipped) as constraints, Active requirements as current scope. Read `state.json.accumulated_context` → deferred items as brainstorming seeds, key_decisions as locked constraints.
+4. All optional — proceed without if unavailable.
 
 **Session**: `.workflow/.csv-wave/{YYYYMMDD}-brainstorm-{slug}/`
 
@@ -299,8 +316,13 @@ S_WAVE_2 → S_AGGREGATE WHEN: all failed       DO: skip review
 S_CHECK_2 → S_WAVE_3   WHEN: -y OR user "Proceed"
 S_CHECK_2 → S_WAVE_2   WHEN: user "Add Roles"  DO: add new role rows, spawn only new
 
-S_WAVE_3 → S_RESOLVE   DO: spawn wave-3, capture review_findings (conflicts/gaps/synergies with patch_targets)
-S_WAVE_3 → S_AGGREGATE WHEN: zero findings    DO: log "No cross-role issues detected", skip resolve
+S_WAVE_3 → S_BOUNDARY_GRILL  DO: spawn wave-3, capture review_findings (conflicts/gaps/synergies with patch_targets)
+S_WAVE_3 → S_AGGREGATE      WHEN: zero findings    DO: log "No cross-role issues detected", skip resolve
+
+S_BOUNDARY_GRILL:
+  → S_RESOLVE     WHEN: no boundary conflicts detected     DO: —
+  → S_RESOLVE     WHEN: conflicts detected + resolved      DO: A_BOUNDARY_GRILL
+  GUARD: max 3 conflicts × 3 questions; non-blocking (see boundary-grill.md)
 
 S_RESOLVE → S_AGGREGATE  DO: A_APPLY_RESOLUTIONS (orchestrator iterates patch_targets and applies Edits)
 
@@ -365,6 +387,13 @@ When ui-designer is among selected roles, establish visual direction before Wave
 explore generates multi-style HTML prototypes, visual comparison, user selection/mix, and produces DESIGN.md.
 ui-designer agents in Wave 2 then focus on UX/visual design referencing DESIGN.md.
 
+### A_BOUNDARY_GRILL
+
+Run boundary grill per `~/.maestro/workflows/boundary-grill.md` after cross-role review, before resolution application.
+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 Boundary Grill Results + feed into S_RESOLVE.
+Non-blocking: conflicts produce warnings, pipeline continues.
+
 ### A_APPLY_RESOLUTIONS
 
 For each finding in `review_findings`:
@@ -425,6 +454,8 @@ Protocol: read before analysis, append-only, dedup by type+key.
 - [ ] system-architect/analysis.md §3 includes Data Model + State Machine when system-architect selected
 - [ ] Each {role}/analysis.md §2 Decisions table has ≥ 1 row per feature
 - [ ] Cross-role review (W3) executed; reviewer 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: resolutions applied via Edit AND logged in guidance §12 "Cross-Role Resolutions"
 - [ ] If zero findings: final report explicitly notes "No cross-role issues detected"; guidance §12 unchanged
 - [ ] Heading-drift patch failures surfaced (not silently dropped)
@@ -432,8 +463,17 @@ Protocol: read before analysis, append-only, dedup by type+key.
 - [ ] discoveries.ndjson append-only throughout
 - [ ] context.md aggregates session results with next-step routing
 - [ ] Session sealed via finish-work (auto mode only)
+- [ ] Ralph-invoked: `maestro ralph complete <idx> --status {STATUS}` called with correct verdict
 </success_criteria>
 
+<ralph_completion>
+When invoked as a ralph session step, end by calling the CLI (no standalone report):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+Status verdicts: **DONE** (normal), **DONE_WITH_CONCERNS** (caveats; pass `--concerns`), **NEEDS_RETRY** (transient error), **BLOCKED** (hard blocker; pass `--reason`).
+</ralph_completion>
+
 <on_complete>
 @~/.maestro/workflows/finish-work.md — SESSION_DIR={output_dir}, SESSION_TYPE=brainstorm, SESSION_ID={artifact_id}, LINKED_MILESTONE=null
 </on_complete>

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

@@ -100,7 +100,12 @@ S_FAN_OUT:
   → ERROR(E004)     WHEN: all failed OR fewer than 2 completed
 
 S_CROSS_VERIFY:
-  → S_SYNTHESIZE    DO: A_CROSS_VERIFY
+  → S_BOUNDARY_GRILL  DO: A_CROSS_VERIFY
+
+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 (see boundary-grill.md)
 
 S_SYNTHESIZE:
   → S_AGGREGATE     DO: A_SYNTHESIZE
@@ -229,6 +234,12 @@ Compute: `consensus_level = consensus_count / total_findings * 100`
 
 Write results to `{scratchDir}/cross-verify.md`.
 
+### A_BOUNDARY_GRILL
+
+Run boundary grill per `~/.maestro/workflows/boundary-grill.md` after cross-verification.
+Input: classified CONFLICT findings + per-tool outputs. Check upstream scope if `--from` used.
+IF conflicts → tag with resolution, feed into A_SYNTHESIZE. No conflicts → pass through.
+
 ### A_SYNTHESIZE
 
 Generate 3 output files from cross-verify results:
@@ -313,6 +324,8 @@ Generate 3 output files from cross-verify results:
 - [ ] Blocking poll loop ran until pending_sessions empty — no early exit
 - [ ] Per-tool raw outputs saved to {scratchDir}/per-tool/
 - [ ] Cross-verify: CONSENSUS/CONFLICT/UNIQUE classified, consensus_level computed
+- [ ] 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)
 - [ ] collab-report.md + context.md + conclusions.json produced
 - [ ] CLB artifact registered in state.json
 - [ ] Partial degradation: continued if 2+ tools succeeded