maestro-plan

<purpose>
Create, revise, or verify execution plans (5-stage pipeline).
Produces plan.json + TASK files; registers PLN artifact in state.json.
</purpose>

<required_reading>
@~/.maestro/workflows/plan.md
</required_reading>

<deferred_reading>
- [plan.json](~/.maestro/templates/plan.json) — read when generating plan output
- [task.json](~/.maestro/templates/task.json) — read when generating task files
- [state.json](~/.maestro/templates/state.json) — read when registering artifact
- [boundary-grill.md](~/.maestro/workflows/boundary-grill.md) — read when boundary conflicts detected (in P4)
</deferred_reading>

<context>
$ARGUMENTS — phase number, or no args for milestone-wide planning, with optional flags.

Scope routing, base flags (`--collab`, `--spec`, `-y`, `--gaps`, `--dir`), output directory format, and artifact registration are defined in workflow plan.md.

**Command-level flags** (extensions beyond workflow base):
- `--from <source>`: Load upstream context directly (bypasses roadmap requirement):
  - `analyze:ANL-xxx` → CONTEXT_DIR = artifact path, scope = "standalone"
  - `blueprint:BLP-xxx` → CONTEXT_DIR = blueprint path, scope = "standalone"
  - `@file` or `path/` → load context-package.json from path
- `--revise [instructions]` -- See workflow plan.md § Revise Mode
- `--check <plan-dir>` -- See workflow plan.md § Check Mode

**Upstream context (resolution priority):**
1. `--from analyze:ANL-xxx` → uses analyze conclusions.implementation_scope directly
2. `--from blueprint:BLP-xxx` → uses blueprint requirements + architecture
3. `--dir <path>` → explicit context directory (unchanged)
4. Numeric arg → scope = "phase", resolve from roadmap (unchanged)
5. No args + roadmap → scope = "milestone" (unchanged)
6. No args + no roadmap → search state.json for latest analyze artifact, fallback standalone

**Ad-hoc milestone (D-008):** When scope resolves to "standalone" via the standard standalone resolution (no `--from` source), and `current_milestone == null`, plan auto-creates an adhoc milestone (`type: "adhoc"`) in state.json before proceeding. This ensures downstream milestone-audit/complete have a valid milestone context. See workflow plan.md § "Ad-hoc Milestone Auto-Creation".

**`--from analyze:*` / `blueprint:*`**: scope=standalone → skip adhoc milestone auto-creation.

### Role Knowledge
`maestro search --category arch` → select relevant → `maestro load --type knowhow --id`
</context>

<execution>
### Pre-flight: team conflict check

Before starting the plan pipeline, run:
```
Bash("maestro collab preflight --phase <phase-number>")
```
If exit code is 1, present warnings and ask whether to proceed.

Follow '~/.maestro/workflows/plan.md' completely.

### Phase Gates (MANDATORY, BLOCKING — Create mode only)

**GATE P1 → P2: Context Collection → Clarification**
- REQUIRED: Context files loaded (roadmap, analyze artifact, or --from source).
- REQUIRED: Codebase docs read if available (ARCHITECTURE.md, FEATURES.md).
- REQUIRED: Wiki searched for prior knowledge related to phase keywords.
- BLOCKED if missing: no context source found — cannot plan without upstream input (E001).

**GATE P2 → P3: Clarification → Plan Generation**
- REQUIRED: Ambiguous requirements resolved via AskUserQuestion (<=3 rounds).
- BLOCKED if: unresolved ambiguities remain after 3 clarification rounds — escalate to user before proceeding.

**GATE P3 → P4: Plan Generation → Plan Check**
- REQUIRED: Plan generated by planner agent — `plan.json` + `.task/TASK-*.json` files written.
- REQUIRED: Main flow inline planning is FORBIDDEN (see P3 Agent Constraint below).
- BLOCKED if missing: plan.json or TASK files not produced by planner agent — do not proceed to checking.

**GATE P3.5 → P4: Boundary Grill → Plan Check**
Run boundary grill per `~/.maestro/workflows/boundary-grill.md`.
Input: plan.json tasks + convergence criteria + upstream context. Scope guard: "only plan scope; do not re-analyze or re-scope".
IF conflicts → results to plan.json `boundary_grill` section + affected TASK files. DEC conflicts add `boundary_warning` to confidence.
NON-BLOCKING: warnings, not hard stops.

**GATE P4 → P5: Plan Check → User Confirmation**
- REQUIRED: Plan-checker passed (or minor issues acknowledged).
- REQUIRED: Boundary grill completed (conflicts resolved or accepted as risks).
- REQUIRED: Confidence scored with 5-dimension factor model.
- REQUIRED: Pressure pass completed on highest-complexity task.
- REQUIRED: If plan touches UI (检出 `dashboard/` 或 UI 关键词 `landing|page|dashboard|frontend|UI|component|界面`), each delivery wave has ≥1 `[UI-observable]` convergence criterion (vertical-slice delivery, not backend-only).
- BLOCKED if: plan-checker found critical issues, OR UI plan missing `[UI-observable]` coverage — fix plan before presenting to user.

**GATE P5 → Completion: User Confirmation → Done**
- REQUIRED: User confirmation captured (execute/modify/cancel).
- REQUIRED: PLN artifact registered in state.json.
- BLOCKED if missing: no user confirmation — do not register artifact or report completion.

### Artifact Verification (before completion)

```
REQUIRED_ARTIFACTS = [
  "plan.json",                    // Task definitions, waves, summary
  ".task/TASK-*.json" (per task)   // Individual task files with convergence criteria
]
```
Every task MUST have `convergence.criteria[]` with grep-verifiable conditions. If any task lacks verifiable criteria: DO NOT report completion — fix the criteria first.

### P3 Agent Constraint (MANDATORY)

Main flow **MUST** spawn a planner agent (Agent tool) for P3 planning — inline planning by main flow is FORBIDDEN. The agent produces both `plan.json` and `.task/TASK-*.json` files. Main flow only passes context and validates output.

### Codebase Docs Loading (P1 addition)

During P1 Context Collection, after loading context files, load codebase documentation if available:

```
IF exists(.workflow/codebase/doc-index.json):
  codebase_ctx = Read(.workflow/codebase/ARCHITECTURE.md) + Read(