maestro-flow 0.4.11 → 0.4.12

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] \"<phase|topic> [-q|--quick] [--gaps [ISS-ID]]\""
+argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] [--from <source>] \"<phase|topic> [-q|--quick] [--gaps [ISS-ID]]\""
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---
 
@@ -10,6 +10,12 @@ Wave-based multi-dimensional analysis using `spawn_agents_on_csv`. Diamond topol
 Wave 1 (CLI exploration, parallel) -> Wave 2 (6-dimension scoring, parallel) -> Wave 3 (decision synthesis).
 
 **Tri-depth**: Full mode (all 3 waves), Quick mode (`-q`, Wave 3 only), Gaps mode (`--gaps`, issue root cause pipeline).
+
+**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>
@@ -21,11 +27,26 @@ $ARGUMENTS -- phase number, topic text, and optional flags.
 - `--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.
 
 **Session**: `.workflow/.csv-wave/{YYYYMMDD}-analyze-{slug}/`
-**Output**: tasks.csv, results.csv, discoveries.ndjson, context.md (all modes), analysis.md + conclusions.json (full mode only)
+**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)
 </context>
 
+<interview_protocol>
+Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `--continue`, or input is already specific (explicit phase number or unambiguous topic).
+
+- One decision per turn via AskUserQuestion with 2–4 options + a (Recommended) default; every question must include a `Proceed now` option so the user can end the interview at any time.
+- Never ask what code can verify — resolve via `state.json`, `roadmap.md`, `issues.jsonl`, `maestro spec load`, `maestro wiki search`, Grep, or Read.
+- Walk the decision dependency tree strictly: scope → depth → dimensions → Go/No-Go threshold. Do not open the next branch until the current one is settled.
+- Scope guard: only ask about decisions owned by `analyze`. Do not prejudge plan/execute concerns.
+
+Decision points: scope (phase / topic / milestone-wide / adhoc / --gaps) → depth (quick / standard / deep) → dimensions (which of the 6 to keep) → Go/No-Go threshold.
+
+Exit: on `Proceed now` or when all decision points are settled, write the table below into `context.md` under an `Interview Decisions` section (and mirror into `analysis.md` in full mode):
+`| # | Decision | Choice | Source (user / code / default) |`
+</interview_protocol>
+
 <csv_schema>
 
 ### tasks.csv
@@ -62,7 +83,9 @@ Available exploration dimensions: architecture, implementation, performance, sec
 5. **Quick mode shortcut**: -q generates only wave 3 task
 6. **Gaps mode pipeline**: --gaps follows: Load issues from issues.jsonl -> Classify & group by location/component -> CSV gen (W1: 1 explore row per issue, W2: 1 synthesis per group) -> Execute waves -> Write issue.analysis record per issue -> Append history `{ action: "analyzed", at: <ISO>, by: "maestro-analyze --gaps" }` -> Output context.md for plan --gaps
 7. **Graceful degradation**: Missing exploration reduces scoring quality; missing scoring reduces synthesis quality
-8. **Tri-output**: context.md always. analysis.md + conclusions.json full-mode only. Gaps mode writes to issues.jsonl + context.md
+8. **Tri-output**: context.md + context-package.json always. analysis.md (full only) + conclusions.json (full + quick — quick writes minimal with `scope_verdict` + `implementation_scope[]`). Gaps mode writes to issues.jsonl + context.md + context-package.json
+9. **D-007 milestone resolution**: numeric scope MUST reverse-lookup `state.json.milestones[].phase_slugs`. NEVER read `current_milestone` directly for phase-scoped artifact registration.
+10. **scope_verdict mandatory** (D-003): macro/adhoc/standalone scopes MUST produce `scope_verdict ∈ {small, medium, large}` in conclusions.json. Drives downstream chain (roadmap vs plan).
 </invariants>
 
 <state_machine>
@@ -80,21 +103,30 @@ S_AGGREGATE  -- 注册 artifact、输出摘要                    PERSIST: state
 <transitions>
 
 S_PARSE:
-  -> S_CONTEXT    WHEN: scope resolved (milestone/phase/adhoc/standalone/gaps)
+  -> S_CONTEXT    WHEN: scope resolved (milestone/phase/macro/adhoc/standalone/gaps)
   -> ERROR(E001)  WHEN: no args and no roadmap
 
-  **Scope routing**:
-  | Condition | Scope | Slug |
-  |-----------|-------|------|
-  | --gaps flag | gaps | ISS-ID slugified or "issue-gaps" |
-  | Empty subject + milestone + roadmap | milestone | milestone name slugified |
-  | Empty subject, no roadmap | ERROR E001 | -- |
-  | Numeric + milestone + roadmap | phase | phase slug from roadmap |
-  | Text subject + milestone | adhoc | subject slugified (max 40) |
-  | Text subject, no milestone | standalone | subject slugified (max 40) |
+  **Scope routing** (text → macro layer, numeric → phase layer per D-003):
+  | Condition | Scope | Layer | Slug |
+  |-----------|-------|-------|------|
+  | --gaps flag | gaps | — | ISS-ID slugified or "issue-gaps" |
+  | Empty subject + milestone + roadmap | milestone | phase | milestone name slugified |
+  | Empty subject, no roadmap | ERROR E001 | — | -- |
+  | Numeric + milestone + roadmap | phase | phase | phase slug from roadmap |
+  | Text subject + milestone | macro | macro | subject slugified (max 40) |
+  | Text subject, no milestone | macro | macro | subject slugified (max 40) |
+
+  **D-007 milestone reverse lookup** (numeric scope only):
+  ```
+  resolve_milestone(phase_number):
+    for ms in state.json.milestones[]:
+      if str(phase_number) in ms.phase_slugs: return ms.id
+    return state.json.current_milestone   # fallback (standalone)
+  ```
+  Write resolved milestone into `session.milestone` and artifact registration; NEVER use `current_milestone` directly for phase-scoped runs.
 
 S_CONTEXT:
-  -> S_CSV_GEN    DO: load project.md, roadmap.md, state.json, prior artifacts, specs
+  -> S_CSV_GEN    DO: load project.md, roadmap.md, state.json, prior artifacts, specs, upstream context-package (if --from)
 
 S_CSV_GEN:
   -> S_WAVE_1     WHEN: full mode         DO: generate N explore + 6 score + 1 synthesis rows
@@ -144,9 +176,18 @@ Merge results -> master tasks.csv.
 Filter wave==3 -> build prev_context from wave 2 scores (or project context for quick mode) -> spawn.
 
 **Synthesis agent**:
-- Full mode: analysis.md (executive summary, per-dimension scores, risk matrix, Go/No-Go), context.md (Locked/Free/Deferred decisions), conclusions.json
-- Quick mode: context.md only from available project context
-- Gaps mode: per-issue analysis records -> issues.jsonl + context.md for plan --gaps
+- Full mode: analysis.md (executive summary, per-dimension scores, risk matrix, Go/No-Go), context.md (Locked/Free/Deferred decisions), context-package.json, conclusions.json (with `scope_verdict` + `implementation_scope[]`)
+- Quick mode: context.md + context-package.json + **minimal conclusions.json** (`scope_verdict` + `implementation_scope[]` only — seeds plan task generation per redesign §8.3)
+- Gaps mode: per-issue analysis records -> issues.jsonl + context.md + context-package.json for plan --gaps
+
+**`scope_verdict` evaluation** (D-003 §5.3, macro/standalone/adhoc scopes only):
+| Verdict | Criteria |
+|---------|----------|
+| `large` | 3+ independent subsystems, OR hard dependencies requiring serialized verification points |
+| `medium` | 1-2 subsystems, parallel-safe |
+| `small` | Single file or few files, directly executable |
+
+Write to `conclusions.json.scope_verdict` (all modes that produce conclusions); mirror into `context.md` and `context-package.json.source.scope_verdict`. Phase-scoped runs may omit (default null).
 
 Gray area detection: domain-aware (things users SEE/CALL/RUN/READ), phase-specific (skip prior decided areas).
 
@@ -156,17 +197,19 @@ Gray area detection: domain-aware (things users SEE/CALL/RUN/READ), phase-specif
 2. **Confidence scoring** (full mode): factors -- findings_depth(.30), evidence_strength(.25), coverage_breadth(.20), user_validation(.15), consistency(.10). Thresholds: <60% deeper, 60-80% optional, 80-95% converging, >95% converge.
 3. Auto-create issues from Deferred items -> issues.jsonl
 4. Spec enrichment: Locked decisions -> `maestro spec add arch`; code patterns -> `maestro spec add coding`
-5. Register artifact in state.json (type: analyze)
+5. Register artifact in state.json (type: analyze, includes context_package field pointing to context-package.json)
 6. Copy outputs to scratchDir, display summary
-7. **Next-step routing**:
+7. **Next-step routing** (D-003 §5.3 — macro scope uses `scope_verdict` for downstream chain selection):
 
    | Scope | Condition | Next |
    |-------|-----------|------|
    | Phase/Milestone | Go + UI work needed | `$maestro-impeccable build {target}` |
    | Phase/Milestone | Go + ready to plan | `$maestro-plan` or `$maestro-plan {phase}` |
    | Phase/Milestone | No-Go | `$maestro-brainstorm {topic}` |
-   | Adhoc/Standalone | Ready to plan | `$maestro-plan --dir {scratch_dir}` |
-   | Adhoc/Standalone | Need more exploration | `$maestro-analyze {topic} --continue` |
+   | Macro/Adhoc/Standalone | `scope_verdict == "large"` | `$maestro-roadmap --from analyze:{ANL_ID}` |
+   | Macro/Adhoc/Standalone | `scope_verdict == "medium"` | `$maestro-plan --from analyze:{ANL_ID}` |
+   | Macro/Adhoc/Standalone | `scope_verdict == "small"` | `$maestro-plan --from analyze:{ANL_ID}` |
+   | Macro/Adhoc/Standalone | Need more exploration | `$maestro-analyze {topic} --continue` |
    | Gaps | Issues analyzed | `$maestro-plan --gaps` |
    | Gaps | Need more context | `$maestro-analyze --gaps {ISS-ID}` |
 
@@ -201,8 +244,12 @@ Protocol: read before analysis, append-only, dedup by type+key.
 </error_codes>
 
 <success_criteria>
+- [ ] Interactive mode: interview decision table written to `context.md` "Interview Decisions" (mirrored into `analysis.md` in full mode)
 - [ ] All waves executed in order (or skipped per mode)
-- [ ] context.md produced (all modes); analysis.md + conclusions.json (full mode)
+- [ ] context.md produced (all modes); analysis.md (full mode); conclusions.json (full mode AND quick mode with at minimum `scope_verdict` + `implementation_scope[]`)
+- [ ] context-package.json produced (all modes) with constraints, requirements, insights, open_questions
+- [ ] `scope_verdict ∈ {small, medium, large}` written into conclusions.json + context.md (macro/adhoc/standalone scopes)
+- [ ] D-007 milestone reverse lookup applied for numeric scope; `session.milestone` populated via `phase_slugs`, never via direct `current_milestone` read
 - [ ] context.md contains all decisions classified as Locked/Free/Deferred
 - [ ] Decision Recording Protocol applied to all decisions
 - [ ] Confidence scored per dimension with factor-based model (full mode)
@@ -210,7 +257,8 @@ Protocol: read before analysis, append-only, dedup by type+key.
 - [ ] Pressure pass completed ≥ 1 time on highest-risk dimension before synthesis
 - [ ] Deferred items auto-created as issues
 - [ ] Scope creep redirected to Deferred section
-- [ ] Artifact registered in state.json
+- [ ] Artifact registered in state.json (includes context_package field)
+- [ ] Upstream context loaded via `--from` when specified
 - [ ] discoveries.ndjson append-only throughout
 - [ ] Next step routed (plan for Go, brainstorm for No-Go, plan --gaps for Gaps)
 </success_criteria>

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

@@ -0,0 +1,122 @@
+---
+name: maestro-blueprint
+description: Generate formal specification package (Product Brief, PRD, Architecture, Epics) through 7-phase document chain (P0 Spec Study → P1 Discovery → P1.5 Req Expansion → P2 Product Brief → P3 PRD → P4 Architecture → P5 Epics → P6 Readiness Check)
+argument-hint: "<idea or @file> [-y] [-c] [--from <source>]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, spawn_agents_on_csv, request_user_input
+---
+<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>
+
+<required_reading>
+@~/.maestro/workflows/blueprint.md
+</required_reading>
+
+<deferred_reading>
+- [blueprint-config.json](~/.maestro/templates/blueprint-config.json) — read when initializing blueprint configuration
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- idea text, @file reference, or upstream context source.
+
+**Flags:**
+- `-y` / `--yes`: Auto mode — skip interactive questions, use recommended defaults
+- `-c` / `--continue`: Resume from last checkpoint (reads blueprint-config.json)
+- `--from <source>`: Load upstream context package (brainstorm:ID, @file, or path). Consumes context-package.json
+- `--from-brainstorm SESSION-ID`: (backward compat alias for `--from brainstorm:ID`)
+
+**Input types:**
+- Direct text: `"Build a real-time collaboration platform with WebSocket"`
+- File reference: `@requirements.md`
+- Context import: `--from brainstorm:BRN-001` or `--from @requirements.md` or `--from path/`
+- Resume: `-c` (resumes from first incomplete phase)
+
+**Pipeline position:**
+```
+maestro-brainstorm (optional upstream)
+        ↓ guidance-specification.md / context-package.json
+maestro-blueprint
+        ↓ .workflow/blueprint/BLP-{slug}-{date}/
+maestro-analyze → maestro-roadmap → maestro-plan
+```
+
+**Output boundary**: ALL file writes MUST target `.workflow/blueprint/BLP-{slug}-{date}/` or `.workflow/state.json` only. NEVER modify source code or files outside these paths.
+
+### Pre-load specs
+1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for architecture decisions (Phase 4).
+2. Optional — proceed without if unavailable.
+</context>
+
+<interview_protocol>
+Interview the user relentlessly about every aspect of the spec until shared understanding is reached. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one; if a question can be answered by exploring the codebase, explore the codebase instead. Active only in interactive mode; skip when `-y/--yes`, `-c/--continue`, or input is already specific (clear idea + scope).
+
+- Ask one question per turn via request_user_input and wait for the user's feedback before continuing; every question must carry a recommended answer marked `(Recommended)`, 2–4 options total, and a `Proceed now` option.
+- Never ask what code can verify — resolve via `state.json`, existing artifacts, `maestro spec load`, or direct codebase exploration (Glob/Grep/Read) instead of prompting.
+- Walk the decision dependency tree depth-first: scope → spec type → focus areas → requirement priorities. Do not open the next branch until the current one is settled.
+- Scope guard: only decide the shape of the specification. Do not pre-resolve roadmap phases or plan tasks — those belong to downstream commands.
+
+Decision points: scope (full product / feature set / single feature) → spec type (service / api / library / platform) → focus areas → whether to run codebase exploration.
+
+Exit: on consensus or `Proceed now`, persist decisions in blueprint-config.json and proceed to Phase 1.
+</interview_protocol>
+
+<execution>
+Follow `~/.maestro/workflows/blueprint.md` completely.
+
+### Phase chain
+
+```
+P0: Spec Study → P1: Discovery → P1.5: Req Expansion → P2: Product Brief → P3: PRD → P4: Architecture → P5: Epics → P6: Readiness Check
+```
+
+P6 gate: Pass (>=80%) → Handoff | Review (60-79%) → Handoff w/caveats | Fail (<60%) → P6.5 Auto-Fix (max 2 iter) → re-check
+
+### Next-step routing on completion
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Need codebase analysis | /maestro-analyze {topic} --from blueprint:BLP-xxx |
+| Ready for roadmap | /maestro-roadmap --from blueprint:BLP-xxx |
+| Small scope, direct plan | /maestro-plan --from blueprint:BLP-xxx |
+| Need project setup | /maestro-init |
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Idea text or @file required | Prompt user for input |
+| E002 | error | Context source not found (--from) | Show available sessions/sources |
+| E006 | error | `.workflow/` not initialized | Run maestro-init first |
+| E007 | error | Phase 6 readiness Fail after 2 auto-fix iterations | Present manual fix options |
+| W001 | warning | CLI analysis failed, using fallback | Continue with available data |
+| W002 | warning | Codebase exploration failed | Continue without codebase context |
+| W003 | warning | Glossary has < 5 terms | Note in readiness check |
+| W004 | warning | Review-level readiness score (60-79%) | Proceed with caveats |
+| W005 | warning | External research agent failed | Continue without apiResearchContext |
+</error_codes>
+
+<success_criteria>
+- [ ] Interactive mode: interview decisions persisted in blueprint-config.json
+- [ ] `blueprint-config.json` created with session metadata and phase tracking
+- [ ] `product-brief.md` with vision, goals, scope, multi-perspective synthesis
+- [ ] `glossary.json` with 5+ core terms for cross-document consistency
+- [ ] `requirements/` directory with `_index.md` + individual `REQ-*.md` + `NFR-*.md` files
+- [ ] All requirements have RFC 2119 keywords and acceptance criteria
+- [ ] `architecture/` directory with `_index.md` + individual `ADR-*.md` files
+- [ ] Architecture includes state machine, config model, error handling, observability (service type)
+- [ ] `epics/` directory with `_index.md` + individual `EPIC-*.md` files
+- [ ] Cross-Epic dependency map (Mermaid) and MVP subset tagged
+- [ ] `readiness-report.md` with 4-dimension quality scores and traceability matrix
+- [ ] `blueprint-summary.md` with one-page executive summary
+- [ ] All documents have valid YAML frontmatter with session_id
+- [ ] Glossary terms used consistently across all documents
+- [ ] Readiness gate: Pass (>=80%) or Review (>=60%) with documented caveats
+- [ ] Artifact registered in state.json (type=blueprint)
+- [ ] context-package.json generated for downstream consumption
+</success_criteria>

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

@@ -1,49 +1,74 @@
 ---
 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]"
+argument-hint: "[topic] [-y|--yes] [-c|--concurrency N] [--continue] [--count N] [--skip-questions] [--review-only]"
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
 <purpose>
 Wave-based multi-role brainstorming via `spawn_agents_on_csv`. Diamond topology:
-Wave 1 (guidance spec) → Wave 2 (parallel role analysis, 3-9 agents) → Wave 3 (synthesis + feature index).
+Wave 1 (guidance spec) → Wave 2 (parallel role analysis, 3-9 agents) → Wave 3 (cross-role review + resolution writeback).
+Wave 2 agents produce multi-file analysis per role under `{role}/` (analysis.md index + per-feature files + findings).
+Wave 3 compares Decision Digests from each role's `analysis.md` §2 and patches the role files. Audit trail appended to `guidance-specification.md` §12.
 </purpose>
 
 <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`
+**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)
 
 **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
-1. **Architecture specs**: `maestro spec load --category arch` — load architecture constraints as context for multi-role analysis (roles respect documented decisions).
+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 wiki list --category arch` → identify relevant entries → `maestro wiki load <id1> [id2...]`
 3. Both optional — proceed without if unavailable.
 
 **Session**: `.workflow/.csv-wave/{YYYYMMDD}-brainstorm-{slug}/`
-**Output**: tasks.csv, results.csv, discoveries.ndjson, context.md, `.brainstorming/` (guidance-specification.md, feature-index.json, synthesis-changelog.md, feature-specs/, {role}/analysis*.md)
+
+**Output** (per session):
+- `guidance-specification.md` — machine contract (Wave 1; consumed by downstream roadmap/analyze/blueprint). §11 Decision Tracking, §12 Cross-Role Resolutions.
+- `design-research.md` — optional, external research from Wave 1
+- `{role}/analysis.md` — index + Decision Digest + cross-cutting foundations per selected role (Wave 2)
+- `{role}/analysis-F-{id}-{slug}.md` — per-feature analysis files (Wave 2)
+- `{role}/findings-{slug}.md` — additional discoveries (Wave 2, optional)
+- `context-package.json` — standardized context contract (context-package/1.0 schema) for downstream commands
+- `tasks.csv`, `results.csv`, `discoveries.ndjson`, `context.md` — wave-engine bookkeeping
 </context>
 
+<interview_protocol>
+Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `--skip-questions`, `--continue` (existing session), or input is already specific.
+
+- One decision per turn via request_user_input with 2–4 options + a (Recommended) default; every question must include a `Proceed now` option.
+- Never ask what code can verify — resolve via `state.json`, the session directory, `maestro spec load`, or `maestro wiki search`.
+- Branch jumps allowed: the user may switch freely between mode / role / upstream / sub-pipeline branches; sequence is not enforced, but every decision point must end with a definite answer.
+- Scope guard: only ask about decisions owned by `brainstorm`. Do not pre-resolve roadmap/plan choices.
+
+Decision points: mode (auto / single-role / review-only) / role selection and `--count` / `--from` upstream source / whether to enable design-research and the DESIGN.md sub-pipeline.
+
+Exit: on consensus or `Proceed now`, write the table below into `guidance-specification.md` §11 and session metadata:
+`| # | Decision | Choice | Source (user / code / default) |`
+</interview_protocol>
+
 <csv_schema>
 ```csv
-id,title,description,role,topic,guidance_spec,deps,context_from,wave,status,findings,analysis_file,error
+id,title,description,role,topic,guidance_spec,deps,context_from,wave,status,findings,output_file,error
 "1","Guidance Spec","...","guidance-generator","<topic>","","","","1","","","",""
-"2","System Architect","...","system-architect","<topic>","","1","1","2","","","",""
-"3","UI Designer","...","ui-designer","<topic>","","1","1","2","","","",""
-"4","Synthesis","...","synthesis","<topic>","","2;3","2;3","3","","","",""
+"2","System Architect","...","system-architect","<topic>","","1","1","2","","","system-architect/analysis.md",""
+"3","UI Designer","...","ui-designer","<topic>","","1","1","2","","","ui-designer/analysis.md",""
+"4","Cross-Role Review","...","cross-role-reviewer","<topic>","","2;3","2;3","3","","","",""
 ```
-Wave 1: 1 guidance row. Wave 2: N role rows (parallel). Wave 3: 1 synthesis row.
+Wave 1: 1 guidance row. Wave 2: N role rows (parallel) — each writes `{role}/analysis.md` + `{role}/analysis-F-*.md` + `{role}/findings-*.md`. Wave 3: 1 reviewer row (reads analysis.md §2 Decision Digests; emits structured findings consumed by orchestrator).
 </csv_schema>
 
 <invariants>
-1. **Wave order sacred**: Guidance (W1) MUST complete before roles (W2)
-2. **CSV source of truth**: Master tasks.csv holds all state
-3. **Discovery board append-only**: Never modify/delete discoveries.ndjson
-4. **Skip on failure**: Guidance fails → abort. All roles fail → skip synthesis.
+1. **Wave order sacred**: Guidance (W1) MUST complete before role design (W2); review (W3) MUST run only after all W2 rows complete.
+2. **CSV source of truth**: Master tasks.csv holds all state.
+3. **Discovery board append-only**: Never modify/delete discoveries.ndjson.
+4. **Skip on failure**: Guidance fails → abort. All W2 roles fail → skip review.
 5. **9 valid roles only**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
-6. **DO NOT STOP**: Continuous until all waves complete; only pause at [CHECKPOINT] (skipped with -y)
+6. **Wave 3 is read-only at the agent boundary**: the reviewer emits structured findings (conflicts / gaps / synergies with `patch_targets[]`). The orchestrator (not the agent) applies the patches via Edit.
+7. **DO NOT STOP**: Continuous until all waves complete; only pause at [CHECKPOINT] (skipped with -y).
 </invariants>
 
 <state_machine>
@@ -55,16 +80,21 @@ S_CSV_GEN    — 生成 tasks.csv                              PERSIST: tasks.cs
 S_WAVE_1     — Guidance Spec (single agent)                PERSIST: guidance-specification.md
 S_CHECK_1    — Checkpoint: 用户审阅 guidance（-y 跳过）    PERSIST: —
 S_DESIGN     — 视觉风格确定 (impeccable teach + explore)   PERSIST: DESIGN.md
-S_WAVE_2     — Role Analysis (parallel spawn)              PERSIST: role analyses
-S_CHECK_2    — Checkpoint: 用户审阅 roles（-y 跳过）       PERSIST: —
-S_WAVE_3     — Synthesis + Feature Index (single agent)    PERSIST: synthesis artifacts
+S_WAVE_2     — Role Analysis (parallel spawn)               PERSIST: {role}/ multi-file × N
+S_CHECK_2    — Checkpoint: 用户审阅分析结果（-y 跳过）     PERSIST: —
+S_WAVE_3     — Cross-Role Review (single agent, read-only) PERSIST: review_findings (in-memory)
+S_RESOLVE    — Apply Resolutions (orchestrator-side)       PERSIST: */analysis.md edits + guidance §12
 S_AGGREGATE  — 生成报告、注册 artifact                     PERSIST: context.md + results.csv
 </states>
 
 <transitions>
-S_PARSE → S_ROLES      DO: parse args, detect mode (phase/scratch), load specs
+S_PARSE → S_ROLES      DO: parse args, detect mode (phase/scratch/review-only), load specs
 S_ROLES → S_CSV_GEN    DO: select roles (-y: auto top N; interactive: request_user_input)
-S_CSV_GEN → S_WAVE_1   DO: generate tasks.csv (1 guidance + N roles + 1 synthesis)
+S_CSV_GEN → S_WAVE_1   DO: generate tasks.csv (1 guidance + N roles + 1 reviewer)
+
+# --review-only path: skip W1/W2, jump straight to W3
+S_PARSE → S_WAVE_3     WHEN: --review-only AND existing session has guidance-specification.md AND */analysis.md
+S_PARSE → END          WHEN: --review-only AND missing prerequisites (E006/E007)
 
 S_WAVE_1 → S_CHECK_1   WHEN: completed    DO: spawn wave-1, merge results, read guidance-spec
 S_WAVE_1 → END         WHEN: failed       DO: abort pipeline
@@ -78,13 +108,16 @@ S_DESIGN → S_WAVE_2    WHEN: DESIGN.md exists OR explore completed    DO: A_DE
 S_DESIGN → S_WAVE_2    WHEN: DESIGN.md already exists (skip explore)
 S_DESIGN → S_WAVE_2    WHEN: explore failed → W004 → continue without
 
-S_WAVE_2 → S_CHECK_2   DO: spawn wave-2 (parallel), merge results
-S_WAVE_2 → S_WAVE_3    WHEN: all failed       DO: skip synthesis
+S_WAVE_2 → S_CHECK_2   DO: spawn wave-2 (parallel), merge results — each agent writes {role}/analysis.md + sub-files
+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_AGGREGATE DO: spawn wave-3, merge results
+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_RESOLVE → S_AGGREGATE  DO: A_APPLY_RESOLUTIONS (orchestrator iterates patch_targets and applies Edits)
 
 S_AGGREGATE → END      DO: A_AGGREGATE
 </transitions>
@@ -93,11 +126,48 @@ S_AGGREGATE → END      DO: A_AGGREGATE
 
 ### Wave agent responsibilities
 
-**Guidance (W1)**: Analyze topic → extract 5-10 terms → define non-goals → decompose features (max 8, F-{3digit}) → RFC 2119 keywords → write guidance-specification.md
+**Guidance (W1, agent role `guidance-generator`)**: Analyze topic → extract 5-10 terms → define non-goals → decompose features (max 8, F-{3digit}) → RFC 2119 keywords → write `guidance-specification.md` with §1-§12 (§11 Decision Tracking, §12 Cross-Role Resolutions initially empty — populated later by S_RESOLVE).
+
+**Role Analysis (W2, agent role = the role name itself)**: Read guidance-spec → produce multi-file analysis under `{role}/`:
+- `analysis.md` — INDEX with §1 Role Mandate (≤ 200 words), §2 Decision Digest (4 tables: Decisions, Interfaces, Cross-Cutting Positions, Findings Summary), §3 Cross-Cutting Foundations, §4 File Index, §5 Outstanding TODOs
+- `analysis-F-{id}-{slug}.md` — one per feature (< 2000 words each)
+- `findings-{slug}.md` — additional discoveries (0 or more, < 1000 words)
+
+system-architect MUST include in §3: Data Model, State Machine, Error Handling, Observability, Configuration, Boundary Scenarios.
 
-**Role (W2)**: Read guidance-spec → analyze through role lens → feature-point organization (analysis.md index + analysis-cross-cutting.md + per-feature analysis-F-{id}.md) or fallback single analysis.md. system-architect MUST include: Data Model, State Machine, Error Handling, Observability, Config Model.
+The agent MUST write files. The agent MUST NOT return analysis as text.
 
-**Synthesis (W3)**: Cross-role consensus/conflicts/unique → conflict tags [RESOLVED]/[SUGGESTED]/[UNRESOLVED] → feature-specs or synthesis-specification.md → feature-index.json + synthesis-changelog.md. Four-layer: Direct Reference → Structured Extraction → Conflict Distillation → Cross-Feature Annotation.
+**Cross-Role Review (W3, agent role `cross-role-reviewer`)**: Read ALL `{role}/analysis.md` files (§2 Decision Digests) + guidance-specification.md → emit structured report (NOT files):
+
+```
+## Conflicts (need user decision)
+### C-001: ...
+  patch_targets:
+    - target_file: {role-A}/analysis-F-{id}-{slug}.md   # or {role-A}/analysis.md for cross-cutting
+      target_heading: ## {exact heading text}
+      edit_type: annotate_and_strikeout
+      edit_content: > **Cross-Role Resolution (C-001)**: {1-line resolution}
+    - target_file: {role-B}/analysis-F-{id}-{slug}.md
+      target_heading: ## {exact heading text}
+      edit_type: annotate_and_strikeout
+
+## Gaps
+### G-001: ...
+  patch_targets:
+    - target_file: {ref-role}/analysis.md   edit_type: annotate_after_heading   # §2 Interfaces table
+    - target_file: {owner-role}/analysis.md edit_type: append_to_section        # §2 Decisions table
+
+## Synergy Opportunities
+### S-001: ...
+  patch_targets:
+    - target_file: {role-A}/analysis-F-{id}-{slug}.md edit_type: annotate_after_heading
+    - target_file: {role-B}/analysis-F-{id}-{slug}.md edit_type: annotate_after_heading
+
+## Summary
+conflicts_count / gaps_count / synergies_count / review_confidence
+```
+
+`edit_type` vocabulary is closed: `annotate_after_heading` / `annotate_and_strikeout` / `append_to_section`. The orchestrator MUST refuse any patch outside this set.
 
 ### A_DESIGN_EXPLORE
 
@@ -108,14 +178,29 @@ When ui-designer is among selected roles, establish visual direction before Wave
 3. If both already exist → skip (visual direction already locked)
 
 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 analysis only (interaction flows, state design), not visual styling.
+ui-designer agents in Wave 2 then focus on UX/visual design referencing DESIGN.md.
+
+### A_APPLY_RESOLUTIONS
+
+For each finding in `review_findings`:
+
+1. **Confirm with user** (skip if -y): present finding + suggested resolution; user picks `Accept` / `Pick A` / `Pick B` (conflict only) / `Skip` / `Defer to TODO`.
+2. **Iterate `patch_targets[]`**: for each target, locate `target_heading` verbatim in `target_file`; apply the edit per `edit_type`.
+3. **Heading drift fallback**: if `target_heading` not found verbatim, log W006 and skip that target. Never invent or fuzzy-match headings.
+4. **Append audit row** to `guidance-specification.md` §12 "Cross-Role Resolutions":
+   ```
+   | C-001 | conflict | system-architect/analysis-F-*.md "<heading>" / subject-matter-expert/analysis-F-*.md "<heading>" | {resolution} | both annotated+superseded |
+   ```
+
+If zero findings, S_RESOLVE is bypassed and `guidance §12` is unchanged.
 
 ### A_AGGREGATE
 
 1. Export results.csv
-2. Generate context.md (summary, guidance, per-role findings, synthesis, feature index, next steps)
-3. Confidence scoring: 5 dimensions (role_coverage, cross_role_consistency, feature_completeness, spec_quality, design_feasibility). Quality gate: >3 UNRESOLVED → warn.
-4. Copy artifacts to target .brainstorming/
+1.5. Generate context-package.json (extract from guidance-specification.md + {role}/analysis.md §2 Digests → standardized schema per context-package/1.0)
+2. Generate context.md (summary, guidance, per-role analyses, review_findings_count, resolutions_applied, patches_skipped, next steps)
+3. Confidence scoring: 5 dimensions (role_coverage, cross_role_consistency, feature_completeness, spec_quality, design_feasibility). Quality gate: cross_role_consistency < 0.4 → warn.
+4. Copy artifacts to target session directory (preserve `{role}/` subdirs).
 5. Next-step routing: DESIGN.md established → `maestro-impeccable build <feature>`; else UI features detected → `maestro-impeccable build <feature>`; else → maestro-analyze / maestro-plan / maestro-roadmap
 
 </actions>
@@ -128,7 +213,8 @@ ui-designer agents in Wave 2 then focus on UX analysis only (interaction flows,
 | non_goal | title | {title, rationale} |
 | feature_candidate | id | {id, slug, description, roles[], priority} |
 | role_insight | role+topic | {role, topic, insight, confidence} |
-| cross_role_conflict | area | {area, roles[], positions[], resolution} |
+| cross_role_finding | finding_id | {kind: conflict\|gap\|synergy, finding_id: C-/G-/S-XXX, patch_targets[]} |
+| resolution_applied | finding_id | {finding_id, decision, patched_files[], skipped_targets[]} |
 
 Protocol: read before analysis, append-only, dedup by type+key.
 </discovery_board>
@@ -137,23 +223,27 @@ Protocol: read before analysis, append-only, dedup by type+key.
 | Condition | Recovery |
 |-----------|----------|
 | Guidance agent failed | Abort pipeline (W2 depends on guidance) |
-| All role agents failed | Skip synthesis, report partial |
-| Synthesis failed | Use W2 results directly |
+| All role agents failed | Skip review, report partial |
+| Review agent failed | Use analysis files directly, no resolution writeback |
 | Role count > 9 | Cap at 9 with warning |
+| E006 --review-only but no */analysis.md | Run auto mode or single roles first |
+| E007 --review-only but missing guidance-specification.md | Run auto mode first |
+| W006 patch heading drift (no verbatim match) | Skip that patch, surface in final report |
 </error_codes>
 
 <success_criteria>
-- [ ] 3 waves executed: guidance → parallel roles → synthesis
-- [ ] guidance-specification.md with RFC 2119 keywords, terminology, non-goals, feature decomposition
-- [ ] Role analysis files for each selected NON-UI role
-- [ ] If ui-designer selected: DESIGN.md established via impeccable explore; analysis.md with UX analysis
-- [ ] Feature specs in `.brainstorming/feature-specs/` or synthesis-specification.md
-- [ ] UI-bearing feature specs reference DESIGN.md for visual constraints
-- [ ] feature-index.json + synthesis-changelog.md + context.md generated
-- [ ] All user decisions captured with Decision Recording Protocol
-- [ ] Confidence scored per role and after cross-role analysis
-- [ ] Readiness gate checked before spec generation (wave 3)
-- [ ] Pressure pass completed on at least 1 feature spec
+- [ ] Interactive mode: interview decision table written to `guidance-specification.md` §11 and session metadata
+- [ ] guidance-specification.md with RFC 2119 keywords, terminology, non-goals, feature decomposition (§10), decision tracking (§11)
+- [ ] If ui-designer selected: DESIGN.md established via impeccable explore
+- [ ] {role}/analysis.md written for each selected role with §1 Role Mandate / §2 Decision Digest (4 tables) / §3 Cross-Cutting Foundations / §4 File Index / §5 Outstanding TODOs
+- [ ] {role}/analysis-F-{id}-{slug}.md written per feature (< 2000 words)
+- [ ] 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
+- [ ] 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)
+- [ ] context-package.json generated with per-item `ref` traceability
 - [ ] discoveries.ndjson append-only throughout
-- [ ] Conflict quality gate: >3 UNRESOLVED → warn
+- [ ] context.md aggregates session results with next-step routing
 </success_criteria>

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

@@ -125,7 +125,7 @@ If spec not found, use built-in fallback:
 | `verify` | skill | `maestro-verify` |
 | `refactor` | skill | `quality-refactor` |
 | `debug` | skill | `quality-debug` |
-| `spec` | skill | `maestro-roadmap --mode full` |
+| `spec` | skill | `maestro-blueprint` |
 | `checkpoint` | checkpoint | — |
 
 **Step 2.1** — Load `intent.json`, map each step to executor.

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

@@ -206,12 +206,21 @@ If exit code is 1, present warnings and ask whether to proceed.
 
 | Input | Resolution |
 |-------|------------|
-| `--dir <path>` | Use path directly (scratch plan dir) |
+| `--dir <path>` | Use path directly (scratch plan dir); scope=standalone |
 | No args | Find all pending plans for current milestone from state.json.artifacts[] |
-| Number (e.g., `3`) | Find pending plans for phase N from state.json.artifacts[] |
+| Number (e.g., `3`) | Find pending plans for phase N from state.json.artifacts[]; **resolve milestone via D-007 reverse lookup** |
 
    For multi-plan: execute sequentially. Each plan is a full CSV session.
 
+   **D-007 milestone reverse lookup** (numeric arg only):
+   ```
+   resolve_milestone(phase_number):
+     for ms in state.json.milestones[]:
+       if str(phase_number) in ms.phase_slugs: return ms.id
+     return state.json.current_milestone   # fallback
+   ```
+   Use the resolved milestone for EXC artifact registration (`milestone` field) and artifact filtering. NEVER read `current_milestone` directly for phase-scoped runs — phase N may belong to a milestone different from current.
+
 2. **Load plan**: Read `{PLAN_DIR}/plan.json` for wave structure and task assignments
 
 3. **Detect completed tasks (breakpoint resume)**: Read `.task/TASK-{NNN}.json` for each task; exclude completed ones from CSV. Log resume count.
@@ -279,7 +288,7 @@ Blocked/failed tasks cascade: mark all downstream dependents as `skipped` with e
    - All task_refs completed -> `issue.status = "resolved"`; any failed -> `"in_progress"`
    - Append history entry: `{ action: "executed", at: <ISO>, by: "maestro-execute", summary: "TASK-{NNN} {status}" }`
 
-4. **Register EXC artifact in state.json**: Find matching plan artifact, create `{ id: "EXC-{next_id}", type: "execute", milestone, phase, scope, path, status: "completed", depends_on: plan_artifact.id, harvested: false, created_at, completed_at }`
+4. **Register EXC artifact in state.json**: Find matching plan artifact, create `{ id: "EXC-{next_id}", type: "execute", milestone, phase, scope, path, status: "completed", depends_on: plan_artifact.id, harvested: false, created_at, completed_at }`. `milestone` MUST come from D-007 `phase_slugs` reverse lookup (numeric phase) — inherit from matching plan artifact if available, otherwise reverse-lookup directly.
 
 5. **Extract incremental specs**: Read `.summaries/`, use `maestro spec add` CLI:
    - Learnings/pitfalls → `maestro spec add learning "<title>" "<content>" --keywords ... --source execute:{PLAN_DIR}`
@@ -356,7 +365,7 @@ echo '{"ts":"<ISO>","worker":"TASK-001","type":"code_pattern","data":{"name":"Re
 - [ ] All waves executed in order with cross-wave context propagation
 - [ ] Completed tasks have .summaries/TASK-{NNN}-summary.md
 - [ ] .task/TASK-*.json statuses updated to match execution results
-- [ ] state.json updated with EXC artifact
+- [ ] state.json updated with EXC artifact (numeric scope: milestone resolved via D-007 `phase_slugs` reverse lookup, NOT direct `current_milestone` read)
 - [ ] Issue status synced for tasks with issue_id (all completed → resolved, any failed → in_progress)
 - [ ] Incremental specs extracted from summaries (learnings, design rationale, root causes)
 - [ ] Post-task knowledge inquiry triggered when applicable (deviation, retry>=2, design rationale)