maestro-flow 0.4.11 → 0.4.13

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

@@ -40,11 +40,14 @@ $ARGUMENTS — user intent text, or special flags.
 <invariants>
 1. **Skills invoked DIRECTLY in-context** — coordinator runs `$skill {resolved_args}` itself, sequentially. NO spawn_agents_on_csv, NO wave/CSV/worker.
 2. **Coordinator owns the loop** — classify → decompose → resolve chain → for each step: resolve args → invoke skill → read result → persist → next.
-3. **Decomposition contract shared with maestro-ralph** — broad/lifecycle intents run S_DECOMPOSE producing the SAME additive block (`boundary_contract`, `execution_criteria`, `task_decomposition`, `goal_checklist_path`) + `goal-checklist.md`. Reference maestro-ralph `A_DECOMPOSE_TASKS`; do not duplicate logic.
-4. **Goal is tool-created** — `A_DECOMPOSE_TASKS` calls `create_goal` with sub-goal success criteria. `update_goal` on convergence; held while aborted/paused.
-5. **Status JSON: schema-additive + step-dynamic** — decomposition fields OPTIONAL (absent → old flat-chain behavior); `steps[]` is a living array grown at runtime by `post-goal-audit`. `goal_ref` traces dynamically-added steps. Never remove/rename existing fields. `waves` kept as empty array for backward-compat (spawning removed).
-6. **Sequential execution** — one step at a time in index order; each step's result read before the next starts.
-7. **Abort on failure** — failed step → mark remaining skipped → report (goal stays bound for `--continue`).
+3. **Decomposition contract shared with maestro-ralph** — broad/lifecycle intents run S_DECOMPOSE producing the SAME additive block (`boundary_contract`, `execution_criteria`, `task_decomposition`). Reference maestro-ralph `A_DECOMPOSE_TASKS`
+4. **Goal is tool-created** — `A_DECOMPOSE_TASKS` calls `create_goal` with sub-goal success criteria. `update_goal` on convergence; held while aborted/paused
+5. **status.json 唯一真源** — 不生成 `goal-checklist.md`；step 含 `command_scope` + `command_path` + `completion_confirmed`
+6. **Topology awareness** — chain catalog 含 brainstorm / blueprint / analyze-macro(text) / analyze(numeric) / roadmap / plan(三路径) / execute / verify / ...
+7. **D-007 milestone 反查** — 数字 phase 步骤的 `milestone_id` 由 `state.json.milestones[].phase_slugs` 反查
+8. **schema 向后兼容** — decomposition 字段可选；`steps[]` 由 post-goal-audit 动态生长（goal_ref tagged）；既有字段不删不改；`waves` 保留空数组
+9. **Sequential execution** — one step at a time in index order; each step's result read before the next starts
+10. **Abort on failure** — failed step → mark remaining skipped → report (goal stays bound for `--continue`)
 </invariants>
 
 <state_machine>
@@ -152,9 +155,13 @@ Extract:
 | task_type | When user intent is about... |
 |-----------|---------------------------|
 | `quick` | Simple/small task, add a feature, quick change |
+| `blueprint` | Formal spec generation (Product Brief / PRD / Architecture / Epics) |
+| `analyze_macro` | Broad/medium intent w/o numeric phase — explore impact, produce scope_verdict |
+| `plan_from_analyze` | Plan directly from analyze artifact (no roadmap, scope=standalone) |
+| `plan_from_blueprint` | Plan directly from blueprint artifact (scope=standalone) |
 | `plan` | Plan, design, architect a phase |
 | `execute` | Implement, develop, code a phase |
-| `analyze` | Understand, investigate, evaluate code |
+| `analyze` | Understand, investigate, evaluate code (numeric phase) |
 | `verify` | Check goals met, validate results |
 | `review` | Code quality review |
 | `test` | Run or create tests, UAT |
@@ -200,11 +207,16 @@ Extract:
 **Selection priorities:**
 1. `issue_id` present → prefer issue chains
 2. UI/design/界面/页面/原型 → prefer `ui_design`
-3. Multiple lifecycle steps implied → prefer multi-step chains
-4. Single specific action → prefer single-step chains
-5. "问题" describing broken behavior → `debug`; tracked item with ISS-ID → `issue`; ambiguous → `debug`
-6. Simple task, no lifecycle context → `quick`
-7. Global fallback → `quick`
+3. 正式规格/spec-generate/7-phase → `blueprint` (single-step) 或 `blueprint-driven`
+4. 头脑风暴/探索 → `brainstorm-driven`
+5. Broad/medium intent + 无数字 phase → `analyze_macro`（产 scope_verdict）；后续 large→roadmap链；medium/small→`plan_from_analyze`
+6. 已有 analyze artifact 直达 plan → `plan_from_analyze`
+7. 已有 blueprint artifact 直达 plan → `plan_from_blueprint`
+8. Multiple lifecycle steps implied → prefer multi-step chains
+9. Single specific action → prefer single-step chains
+10. "问题" describing broken behavior → `debug`; tracked item with ISS-ID → `issue`
+11. Simple task, no lifecycle context → `quick`
+12. Global fallback → `quick`
 
 **Clarity scoring**: 3=task_type+scope+phase, 2=task_type+scope, 1=task_type only, 0=empty.
 If `clarity < 2` and not `auto_mode` → transition to A_CLARIFY_INTENT.
@@ -251,13 +263,13 @@ Read `.workflow/state.json` and route by condition:
 
 ### A_DECOMPOSE_TASKS
 
-与 maestro-ralph `A_DECOMPOSE_TASKS` 共享分解契约 —— 引用该规范，不重复。Condensed:
+与 maestro-ralph `A_DECOMPOSE_TASKS` 共享分解契约。Condensed:
 
 1. 分类意图广度。narrow / 单步 / `{status,init,quick}` 链跳过
-2. broad/medium → `AskUserQuestion` ≤3 轮：Scope（in/out）| Constraints（兼容/API/perf/test）| Definition of Done
-3. 派生 `execution_criteria`（3-6 条命令式规则）+ `task_decomposition`（outcome 子目标，`done_when` 可校验，绑定到 ralph evidence 产物）
-4. **status.json 为唯一真源**：写入 `boundary_contract` / `execution_criteria` / `task_decomposition` / `goal_checklist_path`；从 status.json 投影渲染 `{session_dir}/goal-checklist.md`（同 maestro-ralph Sync Rule，含 Resume 区块指向 `$maestro --continue`）
-5. 链路末尾（evidence 产出步骤后、milestone-complete/close-out 前）追加 `{ type: "decision", decision: "post-goal-audit", retry_count: 0, max_retries: 2 }`。S_DECISION_EVAL 在该节点动态生长 `steps[]`
+2. broad/medium → `AskUserQuestion` ≤3 轮：Scope / Constraints / Definition of Done
+3. 派生 `execution_criteria` + `task_decomposition`（每个 sub-goal 含 `done_when` + `evidence` + `lifecycle` + `completion_confirmed: false`）
+4. **status.json 唯一真源**：写入 `boundary_contract` / `execution_criteria` / `task_decomposition`；不生成 markdown 清单
+5. 链路末尾（evidence 产出步骤后、milestone-complete/close-out 前）追加 `decision:post-goal-audit`。S_DECISION_EVAL 据此动态生长 `steps[]`
 6. **Register goal via `create_goal`:**
    ```
    create_goal({ objective: "Maestro {chain}: {intent} — converge {N} sub-goals within boundary",
@@ -267,24 +279,38 @@ Read `.workflow/state.json` and route by condition:
 
 ### A_CREATE_SESSION
 
-1. Read `.workflow/state.json` for project context (current phase, milestone, workflow_name)
+1. Read `.workflow/state.json` 获取 phase / milestone（D-007 反查 `phase_slugs`）；读最新 macro analyze artifact 注入 `scope_verdict` + `analyze_macro_id`；读最新 blueprint artifact 注入 `blueprint_id`
 2. Resolve chain's skill list from Chain Map (see appendix)
-3. Create `.workflow/.maestro/maestro-{YYYYMMDD-HHMMSS}/status.json`:
+3. Create `.workflow/.maestro/maestro-{YYYYMMDD-HHMMSS}/status.json`（与 ralph 共用 schema）:
    ```json
-   { "session_id", "source": "maestro", "intent", "task_type", "chain_name",
-     "phase", "milestone", "auto_mode", "context": { "issue_id", "scratch_dir",
-     "plan_dir", "analysis_dir", "brainstorm_dir" },
-     "steps": [{ "index", "type": "skill|decision", "skill", "args", "status": "pending", "goal_ref": null }],
+   {
+     "session_id", "source": "maestro", "intent", "task_type", "chain_name",
+     "phase", "phase_is_new": false, "milestone": "",
+     "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 },
+     "steps": [{
+       "index": 0, "type": "skill|decision",
+       "skill": "", "args": "",
+       "stage": "", "scope": null,
+       "command_scope": "global|project|missing|null",
+       "command_path": "~/.claude/commands/{name}.md | .claude/commands/{name}.md | null",
+       "milestone_id": null, "source_artifact_ref": null,
+       "status": "pending", "goal_ref": null,
+       "completion_confirmed": false, "completion_status": null,
+       "completion_evidence": null, "completed_at": null
+     }],
      "waves": [], "current_step": 0, "status": "running",
-     "_comment": "↓ OPTIONAL additive block — present only if S_DECOMPOSE ran; absent → flat-chain behavior",
      "boundary_contract": {}, "execution_criteria": [],
-     "task_decomposition": [{ "id": "G1", "goal": "", "done_when": "", "evidence": "", "status": "pending|done", "completed_at": null }],
-     "task_decomposition_all_done": false,
-     "goal_checklist_path": "", "goal_checklist_synced_at": null }
+     "task_decomposition": [{ "id": "G1", "goal": "", "done_when": "", "evidence": "",
+       "status": "pending|done", "completion_confirmed": false, "completed_at": null }],
+     "task_decomposition_all_done": false
+   }
    ```
    Decomposition fields written ONLY if A_DECOMPOSE_TASKS produced them (additive)
-4. goal-checklist.md 是 status.json 的投影：从 task_decomposition 渲染（同 maestro-ralph Sync Rule）；Resume 区块写入 `$maestro --continue`
-4. Initialize tracking:
+4. Validate: 所有 step 的 `command_scope != "missing"`；否则 raise E006 列出缺失 skill
+5. Initialize tracking:
    - If decomposed: goal already registered by A_DECOMPOSE_TASKS. Else: `create_goal({ objective: "Maestro {chain}: {N} steps [{skill list}]" })`
    - `update_plan({ plan: steps.map(step => ({ step, status: "pending" })) })`
 
@@ -328,10 +354,9 @@ S_DECISION_EVAL 入口；镜像 maestro-ralph `A_GOAL_AUDIT_EVALUATE`。Condense
 
 ### A_APPLY_GOAL_DONE
 
-1. status.json（真源）：全部 `task_decomposition[*].status="done"` + `completed_at=now` + `task_decomposition_all_done=true`
-2. 从 status.json 重渲染 `goal-checklist.md`（见 Sync Rule）；文件末追加 `ALL_GOALS_DONE`
-3. `update_goal({ status: "complete" })` —— 释放分解 goal
-4. 继续到 chain 的终结步骤
+1. status.json：全部 `task_decomposition[*].status="done"` + `completion_confirmed=true` + `completed_at=now` + `task_decomposition_all_done=true`
+2. `update_goal({ status: "complete" })`
+3. 继续到 chain 的终结步骤
 
 ### A_FINALIZE
 
@@ -361,9 +386,13 @@ S_DECISION_EVAL 入口；镜像 maestro-ralph `A_GOAL_AUDIT_EVALUATE`。Condense
 |-------|---------------|
 | `status` | `manage-status` |
 | `init` | `maestro-init` |
+| `blueprint` | `maestro-blueprint "{intent}"` |
+| `analyze_macro` | `maestro-analyze "{intent}"` |
 | `analyze` | `maestro-analyze {phase}` |
 | `ui_design` | `maestro-impeccable build "{phase}"` |
 | `plan` | `maestro-plan {phase}` |
+| `plan_from_analyze` | `maestro-plan --from analyze:{analyze_macro_id}` |
+| `plan_from_blueprint` | `maestro-plan --from blueprint:{blueprint_id}` |
 | `execute` | `maestro-execute {phase}` |
 | `verify` | `maestro-verify {phase}` |
 | `test_gen` | `quality-auto-test {phase}` |
@@ -413,7 +442,8 @@ S_DECISION_EVAL 入口；镜像 maestro-ralph `A_GOAL_AUDIT_EVALUATE`。Condense
 | `feature` | [B] maestro-plan → [B] maestro-execute → maestro-verify |
 | `quality-fix` | [B] maestro-analyze --gaps → [B] maestro-plan --gaps → [B] maestro-execute → maestro-verify |
 | `deploy` | maestro-verify → maestro-milestone-release |
-| `spec-driven` | maestro-init → [B] maestro-roadmap --mode full → [B] maestro-plan → [B] maestro-execute → maestro-verify |
+| `blueprint-driven` | maestro-init → [B] maestro-blueprint → [B] maestro-plan --from blueprint:{BLP} → [B] maestro-execute → maestro-verify |
+| `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 → maestro-verify |
 | `brainstorm-driven` | [B] maestro-brainstorm → [B] maestro-plan → [B] maestro-execute → maestro-verify |
 | `ui-craft-build` | maestro-impeccable build → [B] maestro-plan → [B] maestro-execute → maestro-verify |
 | `roadmap-driven` | maestro-init → [B] maestro-roadmap → [B] maestro-plan → [B] maestro-execute → maestro-verify |
@@ -436,15 +466,17 @@ S_DECISION_EVAL 入口；镜像 maestro-ralph `A_GOAL_AUDIT_EVALUATE`。Condense
 
 | taskType | Chain |
 |----------|-------|
-| `spec_generate` | `spec-driven` |
+| `spec_generate` | `blueprint-driven` |
+| `spec-driven` | `blueprint-driven` |
 | `brainstorm` | `brainstorm-driven` |
 | `issue_execute` | `issue-full` |
+| `analyze_macro` | `analyze-macro-driven` |
 
 ### Auto-Yes Flag Map
 
 | Skill | Flag |
 |-------|------|
-| maestro-init, maestro-analyze, maestro-brainstorm, maestro-impeccable, maestro-roadmap | `-y` |
+| maestro-init, maestro-analyze, maestro-brainstorm, maestro-blueprint, maestro-impeccable, maestro-roadmap | `-y` |
 | maestro-plan, maestro-execute, maestro-milestone-complete | `-y` |
 | quality-auto-test, quality-retrospective | `-y` |
 | quality-test | `-y --auto-fix` |
@@ -462,15 +494,20 @@ S_DECISION_EVAL 入口；镜像 maestro-ralph `A_GOAL_AUDIT_EVALUATE`。Condense
 | E003 | error | Step skill invocation failed | auto_mode retry once, then abort chain |
 | E004 | error | Context artifact not found | Retry step once, then abort |
 | E005 | error | --continue: no session found | List sessions, prompt |
+| E006 | error | command_scope == "missing" for one or more steps | List missing skills, abort build |
 | W001 | warning | Context artifact partial | Continue with available context |
 
 ### Success Criteria
 
 - [ ] Intent classified and chain resolved
-- [ ] Broad lifecycle intents decomposed (S_DECOMPOSE, ≤3 boundary questions) sharing maestro-ralph contract; narrow/single-step skip
+- [ ] Chain catalog 覆盖 blueprint / analyze_macro / plan_from_analyze / plan_from_blueprint / blueprint-driven / analyze-macro-driven 等新拓扑路径
+- [ ] D-007: 数字 phase 步骤的 `milestone_id` 通过 `state.json.milestones[].phase_slugs` 反查；写入 step
+- [ ] plan step args 支持 `{phase}` / `--from analyze:{ANL_ID}` / `--from blueprint:{BLP_ID}` 三路径，`source_artifact_ref` 写入
+- [ ] Broad lifecycle intents decomposed (≤3 boundary questions); narrow/single-step skip
 - [ ] Goal registered via built-in `create_goal`; status.json decomposition fields additive-only
-- [ ] status.json 为唯一真源；goal-checklist.md 是从 JSON 重渲染的投影视图（Resume 区块指向 `$maestro --continue`）
-- [ ] post-goal-audit node appended as final node (after evidence-producing steps); unmet sub-goals dynamically grow steps[] (goal_ref tagged)
+- [ ] status.json 唯一真源；无 markdown 清单
+- [ ] 每个 step 含 `command_scope` + `command_path` + `completion_confirmed` 字段
+- [ ] post-goal-audit node appended as final node; unmet sub-goals dynamically grow steps[] (goal_ref tagged)
 - [ ] Session dir initialized with status.json before first step
 - [ ] Every skill invoked DIRECTLY in-context — NO spawn_agents_on_csv, NO wave/CSV/worker
 - [ ] Sequential execution; status.json + update_plan persisted after every step

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

@@ -0,0 +1,157 @@
+---
+name: maestro-amend
+description: Generate overlays to fix workflow command deficiencies
+argument-hint: "[description] [--from-verify <dir>] [--from-review <dir>] [--from-session <id>] [--from-issues ISS-xxx,...] [--scan] [--dry-run]"
+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>
+@~/.maestro/workflows/overlays.md
+@~/.maestro/cli-tools.json
+</required_reading>
+
+<context>
+$ARGUMENTS — optional description and/or source flags.
+
+**Signal sources**:
+
+| Flag | Source | Collects |
+|------|--------|----------|
+| `--from-verify <dir>` | verification.json | Workflow gaps from verify failures |
+| `--from-review <dir>` | review.json | Process deficiencies from code review |
+| `--from-session <id>` | Session artifacts | Problems during workflow execution |
+| `--from-issues ISS-xxx,...` | issues.jsonl | Issues tracing to command deficiency |
+| `--scan` | Auto-scan .workflow/ | Discover all workflow-related signals |
+| _(positional text)_ | User description | Direct observation |
+
+Multiple combinable. No flags + no description → interactive (scan + AskUserQuestion).
+
+**Control**: `--dry-run` (preview, don't install), `-y` (skip confirmations)
+
+**CLI targeting**: `"cli": "claude"` (default, patches .claude/commands/), `"codex"` (patches .codex/skills/), `"both"` (both paths)
+
+**Output**: `~/.maestro/overlays/amend-{slug}.json` + optional `~/.maestro/overlays/docs/amend-{slug}.md`
+</context>
+
+<state_machine>
+
+<states>
+S_COLLECT      — 收集信号（从 flags / scan / description）    PERSIST: —
+S_DIAGNOSE     — 映射信号到命令补丁                           PERSIST: —
+S_GROUP        — 分组、规划 overlay 粒度                      PERSIST: —
+S_PREVIEW      — 展示注入点地图、用户确认                     PERSIST: —
+S_DRAFT        — 生成 overlay JSON                            PERSIST: overlay files
+S_INSTALL      — 安装 overlay                                 PERSIST: command files
+S_REPORT       — 报告摘要 + post-patch routing                PERSIST: —
+</states>
+
+<transitions>
+
+S_COLLECT:
+  → S_DIAGNOSE    WHEN: signals found                      DO: A_COLLECT_SIGNALS
+  → ERROR(E001)   WHEN: no signals from any source
+
+S_DIAGNOSE:
+  → S_GROUP       WHEN: command deficiencies identified     DO: A_DIAGNOSE_SIGNALS
+  → ERROR(E003)   WHEN: all signals are code bugs (not command gaps)
+
+S_GROUP:
+  → S_PREVIEW     DO: A_GROUP_OVERLAYS
+
+S_PREVIEW:
+  → S_DRAFT       WHEN: user confirms "Apply all" or selects patches
+  → S_PREVIEW     WHEN: user selects "Edit"                DO: modify signal target/section
+  → END           WHEN: user cancels
+
+S_DRAFT:
+  → S_INSTALL     WHEN: not --dry-run                      DO: A_DRAFT_OVERLAYS
+  → END           WHEN: --dry-run                          DO: display JSON + section map preview
+
+S_INSTALL:
+  → S_REPORT      DO: A_INSTALL_OVERLAYS (`maestro overlay add`, retry max 2 on validation failure)
+
+S_REPORT:
+  → END           DO: display summary (signals collected/applied/skipped, overlay details, skipped code-bug routing)
+
+</transitions>
+
+<actions>
+
+### A_COLLECT_SIGNALS
+
+**If source flags**: extract signals from each specified source.
+**If --scan or interactive**: scan .workflow/ for:
+- verification.json → must_have_failures, anti_patterns (filter for command gap direction)
+- review.json → findings tagged "process" or "workflow"
+- debug understanding.md → root causes with workflow/command cause_type
+- issues.jsonl → status=open AND tags include "workflow"/"command"
+- execution summaries → plan deviations suggesting missing command step
+
+**If only description**: parse for affected command(s), what's missing, expected behavior.
+
+### A_DIAGNOSE_SIGNALS
+
+Per signal, determine:
+- signal_id, source, description, target_command, target_section, patch_mode, fix_direction, severity
+
+**Section mapping**:
+
+| Signal pattern | Section | Mode |
+|---------------|---------|------|
+| Missing pre-check/gate | execution | prepend |
+| Missing post-step/verification | execution | append |
+| Missing reading/context | required_reading / deferred_reading | append |
+| Incomplete success criteria | success_criteria | append |
+| Missing error handling | error_codes | append |
+| Scope/context gap | context | append |
+| Entirely new concern | _(new section)_ | new-section |
+
+Read pristine source from `$PKG_ROOT/.claude/commands/<name>.md` to confirm section.
+Classify: command deficiency → proceed; code bug → skip (suggest /maestro-quick).
+
+### A_GROUP_OVERLAYS
+
+Group by target command + section (merge same command+section).
+Granularity: 1-2 signals → `patch-{command}-{slug}.json`; 3+ cross-command → `amend-{slug}.json`.
+Read target commands to verify sections exist, check existing overlays.
+
+Display section map with injection points per target command.
+
+### A_DRAFT_OVERLAYS
+
+Build overlay JSON per schema: name, description, targets[], cli, priority (60), enabled, patches[{section, mode, content}].
+Content rules: heading includes `(patch: SIG-NNN)`, concise, supplementary doc to `~/.maestro/overlays/docs/` if >10 lines.
+
+### A_INSTALL_OVERLAYS
+
+```bash
+maestro overlay add ~/.maestro/overlays/amend-{slug}.json
+```
+On validation failure: fix JSON, retry (max 2).
+
+</actions>
+
+</state_machine>
+
+<error_codes>
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| E001 | No signals from any source | Verify artifact paths or provide description |
+| 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 |
+| W002 | Target command has >= 3 existing overlays | Consider consolidating |
+</error_codes>
+
+<success_criteria>
+- [ ] Signals classified: command deficiency vs code bug
+- [ ] Pristine command sources read to verify injection points
+- [ ] Section map with injection points confirmed by user
+- [ ] Overlay JSON installed successfully; command files contain overlay markers
+- [ ] Skipped code-bug signals routed to alternatives
+</success_criteria>

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,27 @@ $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. The user controls termination — keep interviewing until convergence; they can interrupt naturally 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 — `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 `context.md` "Interview Decisions" (and mirrored into `analysis.md` in full mode). 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>
+
 <csv_schema>
 
 ### tasks.csv
@@ -62,7 +84,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 +104,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 +177,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 +198,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 +245,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 +258,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>