maestro-flow-one 0.2.17 → 0.2.19

package/maestro-flow/commands/lifecycle/amend.md

@@ -148,6 +148,7 @@ On validation failure: fix JSON, retry (max 2).
 | Code | Condition | Recovery |
 |------|-----------|----------|
 | E001 | No signals from any source | Verify artifact paths or provide description |
+| E002 | Signal source path invalid or unreadable | Check `--from-*` path; ensure artifact exists |
 | E003 | All signals are code bugs, not command gaps | Use /maestro-quick or /maestro-plan --gaps |
 | E004 | Overlay validation failed after 2 retries | Review JSON manually |
 | W001 | Some signals skipped (code bugs) | Route to appropriate fix command |

package/maestro-flow/commands/lifecycle/analyze.md

@@ -32,12 +32,23 @@ Use `--gaps` for issue-focused root cause analysis (replaces manage-issue-analyz
 </deferred_reading>
 
 <context>
-$ARGUMENTS -- phase number for milestone-scoped, topic text for adhoc/standalone mode, no args for milestone-wide.
+$ARGUMENTS -- phase number for micro mode, topic text for macro/adhoc mode, no args for milestone-wide.
+
+**Dual-layer mode:**
+- **Macro mode** (text argument): Explore impact surface of a topic/requirement. Produces coarse-grained context with `scope_verdict` to route next step. Use before roadmap or for standalone analysis.
+- **Micro mode** (numeric argument): Phase-level deep analysis within an existing roadmap. Produces fine-grained context for plan consumption. `analyze 1` = Phase 1 of current milestone.
+
+**Disambiguation rule (mode selection):**
+- First positional arg matches `^\d+$` (pure digits, e.g. `1`, `42`) → **micro mode** (treat as phase number)
+- First positional arg is non-numeric text (e.g. `auth-refactor`, `improve search`) → **macro mode** (treat as topic)
+- No positional arg → milestone-wide micro mode (when roadmap present) else macro fallback
+- Mixed input like `"1 phase"` is treated as text → macro mode (only bare numerics trigger micro)
 
 **Flags:**
 - `-y` / `--yes`: Auto mode — skip interactive scoping, use recommended defaults, auto-deepen
 - `-c` / `--continue`: Resume from existing session (auto-detect session folder + discussion.md)
 - `-q` / `--quick`: Quick mode — skip exploration + scoring, go straight to decision extraction (context.md only)
+- `--from <source>`: Load upstream context package (brainstorm:ID, blueprint:BLP-xxx, @file, or path)
 - `--gaps [ISS-ID]`: Issue root cause analysis mode. If ISS-ID provided, analyze single issue. If omitted, analyze all open/registered issues from issues.jsonl.
 
 Scope routing, output directory format, artifact registration schema, and output artifact listing are defined in workflow analyze.md (Scope Routing and Output Structure sections).
@@ -46,6 +57,21 @@ Scope routing, output directory format, artifact registration schema, and output
 `maestro wiki list --category debug` → select relevant → `maestro wiki load`
 </context>
 
+<interview_protocol>
+Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `-c/--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. The user controls termination — keep interviewing until convergence; they can interrupt naturally or via `Other` at any time.
+- Search-first when uncertain: before asking, resolve via `state.json`, `roadmap.md`, `issues.jsonl`, `maestro spec load`, `maestro wiki search`, Grep, Read, or — for open-ended multi-file scans — spawn `Agent(subagent_type: Explore)` / `maestro delegate ... --role explore`. Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
+- Writeback cadence: each settled decision is immediately appended/updated in `discussion.md` (top table) and mirrored into `context.md` "Interview Decisions". Do NOT batch writeback to the end — partial decisions must already be on disk before the next question.
+- 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: when all decision points are settled (or user explicitly signals to proceed), finalize session metadata. The decision table (populated incrementally during interview) uses this schema:
+`| # | Decision | Choice | Source (user / code / default) |`
+</interview_protocol>
+
 <execution>
 Follow '~/.maestro/workflows/analyze.md' completely.
 
@@ -76,15 +102,21 @@ Phase 4: Output context.md for downstream plan --gaps
 
 **Handoff:** context.md is consumed by maestro-plan (loads Locked/Free/Deferred decisions). In --gaps mode, context.md contains issue root causes for `plan --gaps` consumption.
 
+**scope_verdict** (added to context.md in Step 6 Synthesis for macro/adhoc/standalone scopes):
+- `large` (3+ independent subsystems or hard serial dependencies) → suggest `/maestro-roadmap --from analyze:ANL-xxx`
+- `medium` (1-2 subsystems, parallelizable) → suggest `/maestro-plan --from analyze:ANL-xxx`
+- `small` (single-file or few-file change) → suggest `/maestro-plan --from analyze:ANL-xxx`
+
 **Next-step routing on completion:**
 
-Phase/Milestone scope:
+Phase/Milestone scope (micro mode):
 - Go recommendation, UI work needed → `/maestro-impeccable build {target}`
 - Go recommendation, ready to plan → `/maestro-plan` or `/maestro-plan {phase}`
 - No-Go recommendation → revisit requirements or `/maestro-brainstorm {topic}`
 
-Adhoc/Standalone scope:
-- Ready to plan → `/maestro-plan --dir {scratch_dir}`
+Macro/Adhoc/Standalone scope:
+- scope_verdict = large → `/maestro-roadmap --from analyze:ANL-xxx`
+- scope_verdict = medium/small → `/maestro-plan --from analyze:ANL-xxx`
 - Need more exploration → `/maestro-analyze {topic} -c`
 
 Gaps scope:
@@ -123,6 +155,7 @@ Gaps mode:
 - [ ] context.md written with aggregated root causes for plan --gaps
 
 Both modes (full + quick):
+- [ ] Interactive mode: interview decision table written to `discussion.md` and mirrored into `context.md` "Interview Decisions"
 - [ ] context.md written with all decisions classified as Locked/Free/Deferred
 - [ ] Gray areas identified through phase-specific analysis
 - [ ] Decision Recording Protocol applied to all decisions

package/maestro-flow/commands/lifecycle/blueprint.md

@@ -0,0 +1,131 @@
+---
+name: maestro-blueprint
+description: Generate formal specification package (Product Brief, PRD, Architecture, Epics) through 6-phase document chain
+argument-hint: "<idea or @file> [-y] [-c] [--from <source>]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Formal specification document chain producing a complete specification package through 6 sequential phases 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, 6-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 AskUserQuestion and wait for the user's feedback before continuing; every question must carry a recommended answer marked `(Recommended)`, 2–4 options total. The user controls termination — keep interviewing until convergence; they can interrupt naturally or via `Other` at any time.
+- Search-first when uncertain: before asking, resolve via `state.json`, existing artifacts, `maestro spec load`, direct codebase exploration (Glob/Grep/Read), or — for open-ended multi-file scans — spawn `Agent(subagent_type: Explore)` / `maestro delegate ... --role explore`. Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
+- Writeback cadence: each settled decision is immediately persisted into `blueprint-config.json` before the next question. Do NOT batch writeback to the end — partial decisions must already be on disk.
+- 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 explicit user signal to proceed, finalize blueprint-config.json (decisions already written incrementally) 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/maestro-flow/commands/lifecycle/brainstorm.md

@@ -1,116 +1,133 @@
----
-name: maestro-brainstorm
-description: Use when exploring ideas, evaluating approaches, or needing multi-perspective analysis before implementation
-argument-hint: "[topic|role-name] [--yes] [--count N] [--session ID] [--update] [--skip-questions] [--include-questions] [--style-skill PKG]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Unified brainstorming combining interactive framework generation, multi-role parallel analysis, and cross-role synthesis. Two modes: Auto (full pipeline with guidance-specification → parallel role analysis → synthesis) and Single Role (individual role analysis for an existing session). Outputs structured artifacts in .brainstorming/ directory ready for downstream planning.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/brainstorm.md
-</required_reading>
-
-<deferred_reading>
-- [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
-</deferred_reading>
-
-<context>
-$ARGUMENTS -- topic text for auto mode, or role name for single role mode.
-
-**Auto mode**: topic text (e.g., "Build real-time collaboration platform") triggers full pipeline.
-**Single role mode**: valid role name (e.g., "system-architect") runs one role analysis.
-**All output** goes to `.workflow/scratch/{YYYYMMDD}-brainstorm-{slug}/`.
-**Artifact registration**: On completion, registers artifact (type=brainstorm) in state.json.
-**Output boundary**: ALL file writes MUST target `{output_dir}/` or `.workflow/state.json` only. NEVER modify source code or files outside these paths.
-
-**Valid roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
-
-**Flags**:
-- `--yes` / `-y`: Auto mode, skip interactive questions, use defaults
-- `--count N`: Number of roles to select (default 3, max 9)
-- `--session ID`: Use existing session
-- `--update`: Update existing analysis (single role)
-- `--skip-questions`: Skip context gathering questions
-- `--include-questions`: Force context gathering even if analysis exists
-- `--style-skill PKG`: Style package for ui-designer role
-
-### Pre-load specs
-1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for multi-role analysis — ensures roles respect documented decisions.
-2. Optional — proceed without if unavailable.
-
-### Role Knowledge
-1. Browse accumulated knowledge for this role:
-   `maestro wiki list --category arch`
-2. Analyze the index, identify entries relevant to the current task
-3. Load selected documents:
-   `maestro wiki load <id1> [id2] [id3...]`
-4. Review loaded knowledge before proceeding
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/brainstorm.md' completely.
-
-**Next-step routing on completion:**
-
-Auto mode:
-- Project not initialized → Skill({ skill: "maestro-init" })
-- Project initialized, need spec package → Skill({ skill: "maestro-roadmap", args: "--mode full --from-brainstorm {session_id}" })
-- Project initialized, quick roadmap → Skill({ skill: "maestro-roadmap", args: "--from-brainstorm {session_id}" })
-- Need deeper analysis first → Skill({ skill: "maestro-analyze", args: "{topic}" })
-- `html-prototypes/` produced with 2+ files and user wants to browse → load `~/.maestro/workflows/brainstorm-visualize.md` and launch visualizer server (optional, user-triggered)
-- DESIGN.md established during Step 3.5 → suggest: "Run `/maestro-impeccable build <feature-description>` to build with the established design system"
-
-Single role mode:
-- More roles needed → Skill({ skill: "maestro-brainstorm", args: "{next_role} --session {session_id}" })
-- All roles done, run synthesis → Skill({ skill: "maestro-brainstorm", args: "{topic} --session {session_id}" })
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Topic or role argument required | Prompt user for topic text or role name |
-| E002 | error | No active session for single role mode | Guide user to run auto mode first |
-| E003 | error | Invalid role name | Show valid roles list |
-| W001 | warning | Fewer than 10 ideas in divergent phase | Proceed with available ideas |
-| W002 | warning | Project context (.workflow/) not found | Continue without project context |
-| W003 | warning | Role template not found | Use generic analysis structure |
-| W004 | warning | Validation score < 60 | Log warning, suggest manual review |
-| W005 | warning | External research agent failed | Continue without designResearchContext |
-</error_codes>
-
-<success_criteria>
-**Auto mode**:
-- [ ] guidance-specification.md with RFC 2119 keywords, terminology, non-goals, feature decomposition
-- [ ] design-research.md persisted when Step 1.7 external research ran (fail-soft: absence not a failure)
-- [ ] Spec Review Gate passed (Step 3.5) or `--yes` bypassed
-- [ ] Role analysis files for each selected NON-UI role in `.brainstorming/{role}/`
-- [ ] If `ui-designer` in selected_roles AND Step 3.5 ran: `.workflow/impeccable/DESIGN.md` exists (visual style established via impeccable explore)
-- [ ] If `ui-designer` in selected_roles: `ui-designer/analysis.md` exists with UX analysis (interaction flows, state design, information architecture)
-- [ ] Feature specs in `.brainstorming/feature-specs/` (or synthesis-specification.md)
-- [ ] UI-bearing feature specs reference DESIGN.md for visual constraints in Section 3 (Interface Contract)
-- [ ] feature-index.json and synthesis-changelog.md
-- [ ] Final Output Gate passed (Step 5.5) or `--yes` bypassed
-- [ ] All user decisions captured with Decision Recording Protocol
-- [ ] Session metadata updated with completion status
-- [ ] Confidence scored per role completion and after cross-role analysis
-- [ ] Readiness gate checked before spec generation
-- [ ] Pressure pass completed on at least 1 feature spec
-- [ ] Confidence summary appended to synthesis-changelog.md
-
-**Single role mode**:
-- [ ] analysis.md written to `{output_dir}/{role}/`
-- [ ] Feature-point organization used when feature list available
-- [ ] Framework reference included when guidance-specification.md exists
-- [ ] Session metadata updated
-</success_criteria>
+---
+name: maestro-brainstorm
+description: Use when exploring ideas, evaluating approaches, or needing multi-perspective analysis before implementation
+argument-hint: "[topic|role-name] [--yes] [--count N] [--session ID] [--update] [--skip-questions] [--include-questions] [--style-skill PKG]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Unified brainstorming combining interactive framework generation, multi-role parallel analysis, cross-role review, and resolution writeback. Two modes: Auto (full pipeline: guidance-specification → parallel {role}/ multi-file analysis → cross-role-reviewer compares Decision Digests for conflicts/gaps/synergies → user-confirmed resolutions patched into role files + logged in guidance §12) and Single Role (individual role analysis for an existing session). Outputs structured artifacts in `.workflow/scratch/brainstorm-{slug}-{date}/` ready for downstream planning (roadmap / analyze / blueprint consume `guidance-specification.md`).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/brainstorm.md
+</required_reading>
+
+<deferred_reading>
+- [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
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- topic text for auto mode, or role name for single role mode.
+
+**Auto mode**: topic text (e.g., "Build real-time collaboration platform") triggers full pipeline.
+**Single role mode**: valid role name (e.g., "system-architect") runs one role analysis.
+**All output** goes to `.workflow/scratch/brainstorm-{slug}-{YYYYMMDD}/` (orchestrator MUST resolve this to an absolute path before passing to sub-agents).
+**Artifact registration**: On completion, registers artifact (type=brainstorm) in state.json.
+**Output boundary**: ALL file writes MUST target `{output_dir}/` or `.workflow/state.json` only. NEVER modify source code or files outside these paths.
+**Produced files**: `guidance-specification.md`, `design-research.md` (optional), `{role}/analysis.md` + `{role}/analysis-F-*.md` + `{role}/findings-*.md` (per selected role).
+
+**Valid roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
+
+**Flags**:
+- `--yes` / `-y`: Auto mode, skip interactive questions, use defaults
+- `--count N`: Number of roles to select (default 3, max 9)
+- `--session ID`: Use existing session
+- `--update`: Update existing analysis (single role)
+- `--skip-questions`: Skip context gathering questions
+- `--include-questions`: Force context gathering even if analysis exists
+- `--style-skill PKG`: Style package for ui-designer role
+
+### Pre-load specs
+1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for multi-role analysis — ensures roles respect documented decisions.
+2. Optional — proceed without if unavailable.
+
+### Role Knowledge
+1. Browse accumulated knowledge for this role:
+   `maestro wiki list --category arch`
+2. Analyze the index, identify entries relevant to the current task
+3. Load selected documents:
+   `maestro wiki load <id1> [id2] [id3...]`
+4. Review loaded knowledge before proceeding
+</context>
+
+<interview_protocol>
+Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `--yes/-y`, `--skip-questions`, `--session` (existing session), or input is already specific.
+
+- One decision per turn via AskUserQuestion with 2–4 options + a (Recommended) default. The user controls termination — keep interviewing until convergence; they can interrupt naturally or via `Other` at any time.
+- Search-first when uncertain: before asking, resolve via `state.json`, the session directory, `maestro spec load`, `maestro wiki search`, Glob/Grep/Read, or — for open-ended multi-file scans — spawn `Agent(subagent_type: Explore)` / `maestro delegate ... --role explore`. Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
+- Writeback cadence: each time a decision settles, immediately append/update its row in `guidance-specification.md` §11 (create the section if absent). Do NOT batch writeback to the end — partial decisions must already be on disk before the next question.
+- 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 explicit user signal to proceed, finalize session metadata. The §11 table (already populated incrementally) uses this schema:
+`| # | Decision | Choice | Source (user / code / default) |`
+</interview_protocol>
+
+<execution>
+Follow '~/.maestro/workflows/brainstorm.md' completely.
+
+**Next-step routing on completion:**
+
+Auto mode:
+- Project not initialized → Skill({ skill: "maestro-init" })
+- Project initialized, need formal spec package → Skill({ skill: "maestro-blueprint", args: "--from brainstorm:{artifact_id}" })
+- Project initialized, quick roadmap → Skill({ skill: "maestro-roadmap", args: "--from brainstorm:{artifact_id}" })
+- Need deeper analysis first → Skill({ skill: "maestro-analyze", args: "{topic} --from brainstorm:{artifact_id}" })
+- `html-prototypes/` produced with 2+ files and user wants to browse → load `~/.maestro/workflows/brainstorm-visualize.md` and launch visualizer server (optional, user-triggered)
+- DESIGN.md established during Step 3.5 → suggest: "Run `/maestro-impeccable build <feature-description>` to build with the established design system"
+
+Single role mode:
+- More roles needed → Skill({ skill: "maestro-brainstorm", args: "{next_role} --session {session_id}" })
+- All roles done, run synthesis → Skill({ skill: "maestro-brainstorm", args: "{topic} --session {session_id}" })
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Topic or role argument required | Prompt user for topic text or role name |
+| E002 | error | No active session for single role mode | Guide user to run auto mode first |
+| E003 | error | Invalid role name | Show valid roles list |
+| E006 | error | `--review-only` but no `{role}/analysis.md` found | Run auto or single-role mode first |
+| E007 | error | `--review-only` but `guidance-specification.md` missing | Run auto mode to generate guidance first |
+| W001 | warning | Fewer than 10 ideas in divergent phase | Proceed with available ideas |
+| W002 | warning | Project context (.workflow/) not found | Continue without project context |
+| W003 | warning | Role template not found | Use generic analysis structure |
+| W004 | warning | Validation score < 60 | Log warning, suggest manual review |
+| W005 | warning | External research agent failed | Continue without designResearchContext |
+| W006 | warning | Reviewer patch_targets heading drift (no match) | Skip that patch; report in final summary |
+</error_codes>
+
+<success_criteria>
+**Auto mode**:
+- [ ] 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), cross-role resolutions placeholder (§12)
+- [ ] `design-research.md` persisted when Step 1.7 external research ran (fail-soft: absence not a failure)
+- [ ] If `ui-designer` in selected_roles AND Step 3.5 ran: `.workflow/impeccable/DESIGN.md` exists (visual style established via impeccable explore)
+- [ ] `{role}/analysis.md` written for each selected role, containing §2 Decision Digest (4 tables) + §3 Cross-Cutting Foundations + §4 File Index
+- [ ] `{role}/analysis-F-{id}-{slug}.md` written per feature (one file per feature, < 2000 words)
+- [ ] `system-architect/analysis.md` §3 includes Data Model + State Machine when system-architect is selected
+- [ ] `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
+- [ ] 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)
+- [ ] Session metadata updated with completion status (review_findings_count, resolutions_applied, patches_skipped)
+
+**Single role mode**:
+- [ ] `{role}/analysis.md` written with §2 Decision Digest + §4 File Index
+- [ ] `{role}/analysis-F-*.md` written when guidance §10 feature list available
+- [ ] §2 Decisions table references guidance decision IDs
+- [ ] Session metadata updated
+</success_criteria>

package/maestro-flow/commands/lifecycle/fork.md

@@ -19,7 +19,7 @@ Since `.workflow/` is gitignored, this command explicitly copies project context
 
 Also supports `--sync` mode to pull latest main branch changes and shared artifacts into an active worktree (prevents source and artifact drift for long-lived worktrees).
 
-Produces `.workflow/worktrees.json` registry in the main worktree and `.workflow/worktree-scope.json` marker in the worktree.
+Produces `.workflow/worktrees.json` registry in the main worktree and `.workflow/worktree-scope.json` marker in the worktree, and writes a scoped `state.json` inside the worktree containing only the forked milestone's artifacts.
 </purpose>
 
 <required_reading>

package/maestro-flow/commands/lifecycle/guard.md

@@ -77,10 +77,11 @@ Read `.workflow/config.json`. If file missing, initialize with empty guard secti
 - Write config
 
 **`deny <path>`:**
-- Normalize path to forward slashes
+- Normalize path to forward slashes, ensure trailing slash for directories
+- If `guard.mode` is `allow`, switch to `deny` and clear paths with warning
 - Set `guard.mode = "deny"`
 - Add path to `guard.paths` (deduplicate)
-- Set `guard.enabled = true` if not already
+- Set `guard.enabled = true` if not already (symmetric with `allow`: adding a deny path auto-enables the guard)
 - Write config
 
 **Step 4: Confirm**

package/maestro-flow/commands/lifecycle/impeccable.md

@@ -74,6 +74,8 @@ responsive-design.md, spatial-design.md, typography.md, ux-writing.md
 
 ## Chains
 
+Chain step names below reuse Command Routing names but resolve through the chain runner. To avoid ambiguity with Direct command invocation, internal display, todo items, and session status records always tag chain steps with the `impeccable:` prefix (e.g. `impeccable:craft`, `impeccable:critique`). The bare names in this table refer to the workflow file at `~/.maestro/workflows/impeccable/{name}.md` that the chain step reads.
+
 | Chain | Steps | Scenario |
 |-------|-------|----------|
 | build | teach? → explore? → shape → craft → critique → [refine] → audit → polish | New from scratch |
@@ -181,17 +183,17 @@ Before reading any command workflow:
 ## Chain Execution
 
 1. Prerequisites ✓
-2. **Display chain preview**: parse chain definition, output full step preview:
+2. **Display chain preview**: parse chain definition, output full step preview (chain steps prefixed `impeccable:` to disambiguate from Direct commands):
    ```
    ── Chain: build ──────────────────────────
-    1. teach        (conditional: PRODUCT.md missing)
-    2. explore      (conditional: DESIGN.md missing)
-    3. shape
-    4. craft
-    5. critique     ◆ quality gate (threshold: 26/40)
-    6. [refine]     ↺ auto-fix loop (max: 3)
-    7. audit        ◆ quality gate (threshold: 14/20)
-    8. polish
+    1. impeccable:teach        (conditional: PRODUCT.md missing)
+    2. impeccable:explore      (conditional: DESIGN.md missing)
+    3. impeccable:shape
+    4. impeccable:craft
+    5. impeccable:critique     ◆ quality gate (threshold: 26/40)
+    6. impeccable:[refine]     ↺ auto-fix loop (max: 3)
+    7. impeccable:audit        ◆ quality gate (threshold: 14/20)
+    8. impeccable:polish
    ─────────────────────────────────────────
    Target: {target}
    ```
@@ -205,9 +207,9 @@ Before reading any command workflow:
      "gate_history": [], "loop_count": 0, "status": "running" }
    ```
 4. **TodoWrite init**: create todo items for all chain steps
-   - One item per step, format: `[chain] step N: {command} — {description}`
+   - One item per step, format: `[chain] step N: impeccable:{command} — {description}` (use `impeccable:` prefix to disambiguate from Direct command items)
    - If conditional step is skipped, immediately mark completed
-   - Quality gate steps include threshold: `[chain] step 5: critique ◆ gate ≥26/40`
+   - Quality gate steps include threshold: `[chain] step 5: impeccable:critique ◆ gate ≥26/40`
 5. For each step:
    - Read `~/.maestro/workflows/impeccable/{command}.md` → execute
    - **Step start**: TodoWrite marks current step in_progress

package/maestro-flow/commands/lifecycle/init.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-init
 description: Initialize project with auto state detection
-argument-hint: "[-y] [--from-brainstorm SESSION-ID]"
+argument-hint: "[-y] [--from <source>]"
 allowed-tools:
   - Read
   - Write
@@ -25,7 +25,7 @@ Initialize a new project through auto state detection and unified flow. Invoked
 <context>
 **Flags:**
 - `-y` -- Automatic mode. After config questions, runs research without further interaction. Expects idea document via @ reference.
-- `--from-brainstorm SESSION-ID` -- Import from a brainstorm session. Reads guidance-specification.md to pre-fill project vision, goals, constraints, and terminology. Skips interactive questioning.
+- `--from <source>` -- Load upstream context package (brainstorm:ID, @file, or path). Consumes context-package.json to pre-fill project vision, goals, constraints, and terminology. Skips interactive questioning. Alias: `--from-brainstorm`
 
 **Load project state if exists:**
 Check for `.workflow/state.json` -- loads context if project already initialized.
@@ -63,7 +63,7 @@ Other commands:
 |------|----------|-----------|----------|
 | E001 | error | No arguments provided when -y requires @ reference | Check arguments format, re-run with correct input |
 | E002 | error | .workflow/ already exists for greenfield init | Check .workflow/ directory state, resolve conflicts |
-| E003 | error | Brainstorm session not found (--from-brainstorm) | Check arguments format, re-run with correct input |
+| E003 | error | Context source not found (--from / --from-brainstorm) | Check arguments format, re-run with correct input |
 | W001 | warning | Research agent failed, continuing with partial results | Retry research or proceed with partial results |
 </error_codes>