maestro-flow 0.4.10 → 0.4.12

package/workflows/business-test.md

@@ -28,10 +28,10 @@ Generator-Critic loop: max 3 iterations per layer to distinguish test defects fr
 **Load spec package:**
 
 ```
-1. Read ${PHASE_DIR}/index.json -> extract spec_ref (if present)
-2. IF --spec provided: SPEC_DIR = .workflow/.spec/{spec_ref}/
-   ELSE IF index.json.spec_ref: SPEC_DIR = .workflow/.spec/{spec_ref}/
-   ELSE: try .workflow/.spec/SPEC-*/ (most recent)
+1. Read ${PHASE_DIR}/index.json -> extract blueprint_ref (if present)
+2. IF --spec provided: SPEC_DIR = .workflow/blueprint/{blueprint_ref}/
+   ELSE IF index.json.blueprint_ref: SPEC_DIR = .workflow/blueprint/{blueprint_ref}/
+   ELSE: try .workflow/blueprint/SPEC-*/ (most recent)
 
 3. IF SPEC_DIR found:
    - Read requirements/_index.md (requirement summary + traceability matrix)
@@ -189,7 +189,7 @@ Write `business-test-plan.json` to `.tests/business/`:
 ```json
 {
   "phase": "{phase}",
-  "spec_ref": "{SPEC_DIR name or 'degraded'}",
+  "blueprint_ref": "{SPEC_DIR name or 'degraded'}",
   "spec_mode": "full|degraded",
   "generated_at": "{ISO timestamp}",
   "layers": {
@@ -363,7 +363,7 @@ Write `.tests/business/business-test-report.json`:
 ```json
 {
   "phase": "{phase}",
-  "spec_ref": "{spec reference}",
+  "blueprint_ref": "{spec reference}",
   "spec_mode": "full|degraded",
   "completed_at": "{ISO timestamp}",
   "execution_mode": "gen-code|agent",
@@ -432,7 +432,7 @@ Write `.tests/business/business-test-summary.md`:
 ```markdown
 ---
 phase: {phase}
-spec_ref: {spec reference}
+blueprint_ref: {spec reference}
 completed_at: {ISO timestamp}
 verdict: passed|gaps_found
 ---

package/workflows/codebase-rebuild.md

@@ -72,7 +72,7 @@ Used in Step 2-4 to produce architecture-aware documentation.
 
 ```
 Group components into features by:
-  directory proximity, naming patterns, import relationships, .spec/ mapping.
+  directory proximity, naming patterns, import relationships, blueprint/ mapping.
 
 For each feature group: derive name, collect component IDs, map requirements and phase.
 Build feature entry:
@@ -91,7 +91,7 @@ Back-fill component.feature_ids with assigned feature IDs.
 ### Step 4: Map Requirements (if .spec exist)
 
 ```
-If .workflow/.spec/ exist: parse each SPEC-*/requirements/REQ-*.md,
+If .workflow/blueprint/ exist: parse each SPEC-*/requirements/REQ-*.md,
 match to features by keyword analysis. Build requirement entry:
   {
     "id": "REQ-{NNN}",
@@ -102,13 +102,13 @@ match to features by keyword analysis. Build requirement entry:
     "acceptance_criteria": ["{criteria}"]
   }
 
-If no .spec: requirements = [] (populated later by spec-generate).
+If no blueprint: requirements = [] (populated later by maestro-blueprint).
 ```
 
 ### Step 5: Record Architecture Decisions (if ADRs exist)
 
 ```
-If .workflow/.spec/*/architecture/ADR-*.md exist: parse each ADR,
+If .workflow/blueprint/*/architecture/ADR-*.md exist: parse each ADR,
 map to components by keyword analysis. Build ADR entry:
   {
     "id": "ADR-{NNN}",

package/workflows/harvest.md

@@ -9,7 +9,7 @@ Unlike `retrospective.md` which is phase-scoped and post-execution, harvest oper
 ## Prerequisites
 
 - `.workflow/` initialized (`.workflow/state.json` exists)
-- At least one artifact source present (analysis, brainstorm, debug, lite-plan, lite-fix, scratchpad, or active session)
+- At least one artifact source present (analysis, brainstorm, import, debug, lite-plan, lite-fix, scratchpad, or active session)
 - For wiki routing: `maestro wiki` CLI available
 
 ---
@@ -27,16 +27,21 @@ Unlike `retrospective.md` which is phase-scoped and post-execution, harvest oper
 /manage-harvest <target> --to issue                  → force all findings to issue
 /manage-harvest <target> --to auto                   → auto-classify routing (default)
 /manage-harvest <target> --dry-run                   → preview without writing
+/manage-harvest --prune                              → classify artifacts, graduate to knowhow, archive from state.json
+/manage-harvest --prune --age 14                     → only graduate artifacts older than 14 days
+/manage-harvest --prune --dry-run                    → preview prune plan without modifying state.json
 ```
 
 | Flag | Effect |
 |------|--------|
 | `--to <target>` | Force routing target: `wiki`, `spec`, `issue`, `auto` (default: auto) |
-| `--source <type>` | Filter by source type: `analysis`, `brainstorm`, `debug`, `lite-plan`, `lite-fix`, `scratchpad`, `session`, `all` |
+| `--source <type>` | Filter by source type: `analysis`, `brainstorm`, `import`, `debug`, `lite-plan`, `lite-fix`, `scratchpad`, `session`, `all` |
 | `--recent N` | Only scan artifacts updated within last N days (default: 30) |
 | `--dry-run` | Preview extracted items without writing to any store |
 | `-y` / `--yes` | Skip confirmation prompts, accept all routing |
 | `--min-confidence N` | Minimum extraction confidence 0.0-1.0 (default: 0.5) |
+| `--prune` | State hygiene mode: classify artifacts, graduate harvested ones to knowhow, archive from state.json, prune accumulated_context |
+| `--age N` | Graduation age threshold in days (default: 14). Only artifacts older than N days are prune candidates. Used with `--prune` |
 
 ---
 
@@ -44,10 +49,11 @@ Unlike `retrospective.md` which is phase-scoped and post-execution, harvest oper
 
 ```
 Verify .workflow/ exists (else E001). Parse flags and first non-flag token:
-  mode: "scan" (no target) | "session" (ID match) | "path" (explicit path)
+  mode: "scan" (no target) | "session" (ID match) | "path" (explicit path) | "prune" (--prune flag)
   Defaults: target_filter=auto, source_filter=all, recent_days=30,
-            dry_run=false, auto_yes=false, min_confidence=0.5
+            dry_run=false, auto_yes=false, min_confidence=0.5, age_threshold=14
 Invalid --to → E002. Invalid --source → E003.
+If --prune: mode = "prune", jump to Stage 9 (skip Stages 2-8).
 ```
 
 ---
@@ -61,12 +67,13 @@ Scan `.workflow/` for harvestable artifacts. Each source type has a known struct
 | Source Type | Scan Path | Key Files | ID Pattern |
 |-------------|-----------|-----------|------------|
 | `analysis` | `.workflow/.analysis/ANL-*/` | `conclusions.json`, `*.md` | `ANL-*` |
-| `brainstorm` | `.workflow/scratch/brainstorm-*/` | `guidance-specification.md`, `brainstorm-*.md` | directory name |
+| `brainstorm` | `.workflow/scratch/brainstorm-*/` | `guidance-specification.md`, `*/analysis.md`, `design-research.md` | directory name |
 | `lite-plan` | `.workflow/.lite-plan/*/` | `plan.json`, `plan-overview.md` | directory name |
 | `lite-fix` | `.workflow/.lite-fix/*/` | `fix-plan.json` | directory name |
 | `debug` | `.workflow/.debug/*/` | `debug-log.md`, `hypothesis-*.md` | directory name |
 | `scratchpad` | `.workflow/.scratchpad/` | `*.md`, `*.json` | filename |
 | `session` | `.workflow/active/WFS-*/` | `workflow-session.json` | `WFS-*` |
+| `import` | `.workflow/scratch/*-import-*/` | `context-package.json`, `source.*` | directory name |
 | `knowhow` | `.workflow/knowhow/` | `*.md`, `digest-*.md` | filename |
 
 Scan each source type (filtered by `--source`). For each matching directory/file within `--recent` window, extract: `source_type`, `id`, `path`, `title` (from JSON or H1), `updated_at`, `summary`, `file_count`.
@@ -125,11 +132,17 @@ Parse content to identify discrete knowledge items. Each source type has specifi
 - `risks[]` → each risk is a fragment
 - Markdown sections with `## ` headings → section-level fragments
 
-**Brainstorm (`guidance-specification.md` + notes):**
-- `## Options` or `## Approaches` → each option is a fragment
-- `## Decision` or `## Recommendation` → decision fragment
-- `## Trade-offs` → trade-off fragments
-- Action items (lines starting with `- [ ]` or `TODO`) → task fragments
+**Brainstorm (`guidance-specification.md` + `{role}/analysis.md` + `design-research.md`):**
+- guidance §4-§N Role Decisions tables → each row is a decision fragment
+- guidance §10 Feature Decomposition rows → each feature is a fragment
+- guidance §12 Cross-Role Resolutions table → each resolution is a decision fragment
+- `{role}/analysis.md` §2 Decision Digest tables → decision / interface / position fragments by role
+- `{role}/analysis.md` §3 Cross-Cutting Foundations subsections → architectural / data-model / pitfall fragments by role
+- `{role}/analysis.md` §4 File Index → navigate to sub-files:
+  - `{role}/analysis-F-{id}-{slug}.md` → per-feature decision fragments (one file = one fragment)
+  - `{role}/findings-{slug}.md` → finding / discovery fragments
+- `{role}/analysis.md` §5 Outstanding TODOs → task fragments
+- `design-research.md` "Extractable Patterns" sections → pattern reference fragments
 
 **Lite-plan (`plan.json`):**
 - `tasks[]` → each with rationale → decision fragments
@@ -141,6 +154,14 @@ Parse content to identify discrete knowledge items. Each source type has specifi
 - `fix_strategy` → pattern fragment
 - `verification` → test/validation fragment
 
+**Import (`context-package.json` + `source.*`):**
+- `requirements[]` → each requirement is a feature fragment
+- `constraints[]` → each constraint is a decision fragment
+- `non_goals[]` → each non-goal is a scope fragment
+- `insights[]` → each insight is a knowledge fragment
+- `domain.terminology[]` → each term is a terminology fragment
+- `open_questions[]` → each question is a task/investigation fragment
+
 **Debug (`debug-log.md`, `hypothesis-*.md`):**
 - Final diagnosis → bug fragment
 - Verified hypothesis → pattern/knowhow fragment
@@ -174,6 +195,8 @@ fragment = {
 
 Filter by `--min-confidence`.
 
+**Context Package shortcut**: If any artifact has a `context-package.json` (check `state.json.artifacts[].context_package`), harvest can use it as a pre-extracted summary — skip detailed file parsing and directly convert context-package fields to fragments. The per-item `ref` field provides traceability to original sources.
+
 ---
 
 ## Stage 4: classify_routing
@@ -351,3 +374,154 @@ Next:
   → Connect wiki graph: Skill({ skill: "wiki-connect", args: "--fix" })
   → View specs: Skill({ skill: "spec-load", args: "--role implement" })
 ```
+
+---
+
+## Stage 9: state_hygiene (--prune)
+
+When `--prune` flag is present, skip Stages 2-8 and run state.json hygiene instead. Manages three concerns: **artifact graduation** (harvested → archived via knowhow), **accumulated_context pruning** (remove resolved/stale entries), and **integrity validation**.
+
+### 9a. Load state
+
+```
+Read .workflow/state.json → { artifacts[], accumulated_context{}, current_milestone, milestones[] }
+Read .workflow/harvest/harvest-log.jsonl → build harvested_map: { [source_id]: { fragment_count, routed_count, last_harvested } }
+Defaults: age_threshold = --age value (default 14 days), dry_run = --dry-run flag
+```
+
+### 9b. Classify artifacts
+
+For each artifact in `artifacts[]`, assign a classification:
+
+| Classification | Criteria | Action |
+|---|---|---|
+| `active` | milestone == current_milestone OR age < age_threshold OR referenced by active plan (type=plan, status=completed, linked execute not completed) | **Keep** in artifacts[] |
+| `graduated` | harvested == true AND not active | **Graduate** → knowhow → archive |
+| `stale` | harvested == false AND not active AND age > age_threshold | **Suggest** harvest first |
+| `protected` | type ∈ {plan, execute} AND linked downstream artifact is active | **Keep** regardless of age |
+
+Age = days since `completed_at` (or `created_at` if never completed).
+
+"Referenced by active plan": artifact X is protected if any plan artifact has `depends_on == X.id` or any execute artifact in same phase is active.
+
+### 9c. Classify accumulated_context
+
+Scan `accumulated_context` sub-arrays:
+
+| Field | Prune Criteria | Keep Criteria |
+|---|---|---|
+| `key_decisions[]` | Entry exists verbatim in `specs/architecture-constraints.md` (deduplicated to spec) | Not yet in specs |
+| `deferred[]` | status ∈ {"resolved", "cancelled", "superseded"} | status ∈ {"open", "deferred"} |
+| `blockers[]` | status == "resolved" | status ∈ {"open", "investigating"} |
+
+### 9d. Preview
+
+```
+=== STATE HYGIENE PLAN ===
+
+  Artifacts (23 total):
+    active:     8   (keep)
+    graduated:  11  (→ knowhow → archive)
+    stale:      3   (suggest harvest first)
+    protected:  1   (keep)
+
+  Accumulated Context:
+    key_decisions:  12 total → 4 prunable (already in specs)
+    deferred:        5 total → 2 prunable (resolved)
+    blockers:        3 total → 1 prunable (resolved)
+
+  Stale artifacts (not yet harvested):
+    ANL-003  analysis  2026-03-15  "Security audit P2"
+    BRN-002  brainstorm 2026-03-10  "Cache strategy"
+    WFS-005  session   2026-03-08  "Feature toggle impl"
+    → Run: /manage-harvest ANL-003 BRN-002 WFS-005  (harvest before graduating)
+
+  Estimated state.json reduction: 23 → 9 artifacts, 20 → 13 context entries
+```
+
+`--dry-run` → display and exit. Otherwise (unless `-y`), AskUserQuestion:
+- "Proceed" — apply all
+- "Graduate only" — archive graduated artifacts, skip accumulated_context prune
+- "Harvest stale first" — run harvest on stale artifacts, then re-classify
+- "Abort"
+
+### 9e. Graduate to knowhow
+
+For each `graduated` artifact:
+
+1. **Build compact summary** from harvest-log entries:
+   - Fragment count, routing breakdown (N wiki, N spec, N issue)
+   - Top 3 fragment titles as representative items
+   - Original path for disk reference
+
+2. **Create knowhow entry**:
+   ```bash
+   maestro wiki create --type knowhow \
+     --slug "graduated-{type}-{short_id}" \
+     --title "Graduated: {type} {id}" \
+     --tags "graduated,{type},{milestone}" \
+     --body "{compact_summary}"
+   ```
+
+3. **Archive in state.json**: Move from `artifacts[]` to `artifact_archive[]`:
+   ```json
+   {
+     "id": "ANL-001",
+     "type": "analyze",
+     "milestone": "M1",
+     "path": "scratch/20260315-analyze-P2-security",
+     "graduated_at": "ISO-8601",
+     "knowhow_ref": "graduated-analyze-ANL-001",
+     "summary": "Security audit P2 — 8 fragments → 3 wiki, 2 spec, 3 issue"
+   }
+   ```
+
+4. **Files on disk**: NOT deleted. The `.workflow/{path}/` directory remains for reference. Only the state.json entry moves.
+
+### 9f. Prune accumulated_context
+
+For each prunable entry identified in 9c:
+- `key_decisions[]`: remove entry, log `[PRUNE] key_decision: "{text}" (deduplicated to spec)`
+- `deferred[]`: remove entry, log `[PRUNE] deferred: "{title}" (status: {status})`
+- `blockers[]`: remove entry, log `[PRUNE] blocker: "{title}" (resolved)`
+
+### 9g. Apply
+
+1. **Backup**: Copy `state.json` → `state.json.backup-prune-{timestamp}`
+2. **Write**: Updated state.json with:
+   - `artifacts[]` = active + protected entries only
+   - `artifact_archive[]` = existing archive + newly graduated
+   - `accumulated_context` = pruned version
+   - `last_pruned`: ISO-8601 timestamp
+3. **Validate**: Re-read and confirm artifact count matches expected
+
+### 9h. Report
+
+Append prune results to harvest report:
+
+```
+=== PRUNE COMPLETE ===
+
+  Graduated:  11 artifacts → knowhow
+  Archived:   11 entries moved to artifact_archive[]
+  Pruned:     4 key_decisions + 2 deferred + 1 blocker = 7 context entries
+
+  State reduction: 23 → 9 artifacts, 20 → 13 context entries
+  Backup: .workflow/state.json.backup-prune-20260521T143022
+
+  Stale (not harvested, action needed):
+    → /manage-harvest ANL-003 BRN-002 WFS-005
+
+  Next:
+    → Review graduated knowhow: maestro wiki list --type knowhow --tags graduated
+    → Re-run prune after harvesting stale: /manage-harvest --prune
+```
+
+### Safety invariants
+
+1. **Never prune current milestone artifacts** — active classification takes precedence
+2. **Never delete files on disk** — only state.json entries move; files remain for reference/audit
+3. **Backup before write** — always create `state.json.backup-prune-{timestamp}`
+4. **Stale before graduate** — stale artifacts are flagged, not silently archived (knowledge would be lost)
+5. **Spec dedup is conservative** — key_decision pruned only if verbatim match found in specs
+6. **Idempotent** — re-running `--prune` with no changes produces empty plan

package/workflows/init.md

@@ -42,13 +42,14 @@ state.json exists → Path C (existing) | source files exist → Path B (brownfi
    - "Keep exploring" → continue questioning
 
    If `--auto` flag: skip interactive questioning, extract from @ referenced document.
-   If `--from-brainstorm SESSION-ID`:
-   - Locate brainstorm session directory (`.workflow/scratch/brainstorm-*/`)
-   - Read `guidance-specification.md`:
-     - Problem statement → project vision + core value
-     - Features → project goals (Active requirements)
-     - Non-goals → constraints + Out of Scope requirements
-     - Terminology → project glossary context
+   If `--from <source>` (alias: `--from-brainstorm`):
+   - Locate source directory (`.workflow/scratch/brainstorm-*/`, `.workflow/scratch/*-import-*/`, etc.)
+   - Load `context-package.json` (preferred) or fall back to `guidance-specification.md`:
+     - `domain` (name, description, problem_statement) → project vision + core value
+     - `requirements[]` → project goals (Active requirements)
+     - `constraints[locked]` → key decisions
+     - `non_goals[]` → constraints + Out of Scope requirements
+     - `domain.terminology[]` → project glossary context
    - Skip interactive questioning (context already gathered)
 
 2. **Workflow Preferences** -- Configure project workflow settings:
@@ -86,7 +87,7 @@ state.json exists → Path C (existing) | source files exist → Path B (brownfi
    - "Skip mapping" → proceed
 4. Run Workflow Preferences (same as Path A step 2) → `.workflow/config.json`
 5. Ask user for project vision, goals, constraints (same deep questioning as Path A step 1)
-   - If `--from-brainstorm SESSION-ID`: extract from guidance-specification.md (skip questioning)
+   - If `--from <source>` (alias: `--from-brainstorm`): load context-package.json (skip questioning)
    - For brownfield: infer Validated requirements from existing code (what does codebase already do?)
 6. Create `.workflow/project.md` (include inferred Validated requirements + new Active requirements)
 

package/workflows/maestro.md

@@ -424,7 +424,7 @@ detectNextAction(state):
 | Chain | Steps | Use Case |
 |-------|-------|----------|
 | `full-lifecycle` | plan → execute → verify → review → test → audit | Full milestone completion |
-| `spec-driven` | init → spec-generate → plan → execute → verify | From idea/requirements (heavy) |
+| `blueprint-driven` | init → blueprint → plan → execute → verify | From idea/requirements (heavy) |
 | `roadmap-driven` | init → roadmap → plan → execute → verify | From requirements (light) |
 | `brainstorm-driven` | brainstorm → plan → execute → verify | From exploration |
 | `impeccable-build` | impeccable --chain build → plan → execute → verify | From design system generation |

package/workflows/milestone-audit.md

@@ -8,19 +8,27 @@ Cross-phase integration audit for milestone completion. Based on artifact regist
 
 1. Read `.workflow/state.json`:
    - Determine target milestone (from $ARGUMENTS or current_milestone)
+   - If no milestone: ERROR E001
    - Get `artifacts[]` array
+   - Resolve milestone object from `milestones[]` by id
+   - Determine milestone type: `milestone_obj.type` (default `"standard"` if field missing)
 
-2. Parse `.workflow/roadmap.md` to identify all phases belonging to this milestone
+2. **Standard milestone** (`type != "adhoc"`):
+   - Parse `.workflow/roadmap.md` to identify all phases belonging to this milestone
 
-3. Group milestone artifacts by type → `analyze_artifacts`, `plan_artifacts`, `execute_artifacts`, `verify_artifacts`
+3. **Adhoc milestone** (`type == "adhoc"`):
+   - Skip roadmap.md parsing (roadmap may not exist)
+   - Phases are defined by `milestone_obj.phases[]` (typically `[1]` with slug `"standalone"`)
+
+4. Group milestone artifacts by type → `analyze_artifacts`, `plan_artifacts`, `execute_artifacts`, `verify_artifacts`
 
 ---
 
 ## Step 2: Phase Coverage Check
 
-Parse roadmap.md phases for this milestone. For each phase, verify completed artifacts exist for analyze, plan, and execute types.
+**Standard milestone**: Parse roadmap.md phases for this milestone. For each phase, verify completed artifacts exist for analyze, plan, and execute types. WARN if any phase is missing its execute artifact: "Phase {number} ({title}) missing execute artifact"
 
-WARN if any phase is missing its execute artifact: "Phase {number} ({title}) missing execute artifact"
+**Adhoc milestone**: Skip phase-level coverage check (no roadmap phases to validate). Instead, verify that at least one complete artifact chain exists: plan artifact (PLN) + execute artifact (EXC) with matching milestone ID. WARN if no execute artifact found.
 
 ---
 

package/workflows/milestone-complete.md

@@ -9,6 +9,8 @@ Archive completed milestone, move artifacts to history, and prepare for next.
 1. Read `.workflow/state.json`:
    - Determine target milestone (from $ARGUMENTS or current_milestone)
    - If no milestone: ERROR E001
+   - Resolve milestone object from `milestones[]` by id
+   - Determine milestone type: `milestone_obj.type` (default `"standard"` if field missing)
 
 2. Check milestone audit status:
    - Read `.workflow/milestones/{milestone}/audit-report.md` if exists
@@ -30,9 +32,8 @@ Archive completed milestone, move artifacts to history, and prepare for next.
    ```
 
 2. Snapshot roadmap:
-   ```
-   cp .workflow/roadmap.md .workflow/milestones/{milestone}/roadmap-snapshot.md
-   ```
+   - **Standard milestone**: `cp .workflow/roadmap.md .workflow/milestones/{milestone}/roadmap-snapshot.md`
+   - **Adhoc milestone**: Skip roadmap snapshot (roadmap may not exist)
 
 3. Archive scratch directories: copy each milestone artifact's `.workflow/{artifact.path}` to `.workflow/milestones/{milestone}/artifacts/{basename}/`
 
@@ -91,7 +92,9 @@ Check existing entries to avoid duplicates when appending in Step 3.
 
 2. Clear artifacts array: remove all entries where `milestone == target_milestone`
 
-3. Advance to next milestone: activate first pending milestone → set as `current_milestone`. If none pending → set `current_milestone = null`, `status = "completed"`
+3. Advance to next milestone:
+   - **Standard milestone**: activate first pending milestone → set as `current_milestone`. If none pending → set `current_milestone = null`, `status = "completed"`
+   - **Adhoc milestone**: Do NOT search for next milestone. Set `current_milestone = null`, `status = "idle"` (adhoc milestones are self-contained, no successor)
 
 4. Write state.json (atomic)
 
@@ -135,10 +138,12 @@ Artifacts: {count} archived
 Learnings: {learnings_count} extracted
 
 Archive: .workflow/milestones/{milestone}/
-Next:    {next_milestone or "Project complete"}
+Next:    {next_milestone or "Project complete" or "Ad-hoc task complete"}
 
 Next steps:
   /maestro-milestone-release    -- Cut a release
-  /maestro-analyze              -- Start next milestone
+  /maestro-analyze              -- Start next milestone (standard only)
   /manage-status                -- View project state
 ```
+
+**Adhoc milestone note:** When completing an adhoc milestone, the "Next steps" section omits "Start next milestone" since adhoc milestones have no successor in a roadmap chain.

package/workflows/plan.md

@@ -18,22 +18,68 @@ All output goes to `.workflow/scratch/plan-{slug}-{date}/`.
 ## Scope Resolution
 
 ```
-Input: [phase] argument OR --dir <path>
+Input: [phase] argument OR --dir <path> OR --from <source>
 
 Worktree guard: reject if phase not in .workflow/worktree-scope.json owned_phases
 Auto-bootstrap: create minimal state.json if missing
 
-Resolution priority:
-  --dir <path>   → CONTEXT_DIR = path, scope from state.json artifact or "standalone"
-  no arguments   → scope = "milestone", CONTEXT_DIR = latest analyze artifact for current_milestone
-                   (ERROR E001 if no roadmap)
-  numeric arg    → scope = "phase", resolve PHASE_SLUG from roadmap.md,
-                   CONTEXT_DIR = latest analyze artifact for phase
-                   (ERROR if no init + roadmap)
+Resolution priority (highest to lowest):
+  1. --from analyze:ANL-xxx → CONTEXT_DIR = artifact path, scope = "standalone"
+     Uses analyze conclusions.implementation_scope to seed task generation
+  2. --from blueprint:BLP-xxx → CONTEXT_DIR = blueprint path, scope = "standalone"
+     Uses blueprint requirements + architecture to seed task generation
+  3. --from <other> (@file, path/) → load context-package.json from path, scope = "standalone"
+  4. --dir <path>   → CONTEXT_DIR = path, scope from state.json artifact or "standalone"
+  5. no arguments + roadmap → scope = "milestone", CONTEXT_DIR = latest analyze artifact for current_milestone
+     (ERROR E001 if no roadmap)
+  6. numeric arg    → scope = "phase", resolve PHASE_SLUG from roadmap.md,
+     CONTEXT_DIR = latest analyze artifact for phase
+     (ERROR if no init + roadmap)
+  7. no arguments + no roadmap → search state.json for latest analyze artifact
+     Found → scope = "standalone", CONTEXT_DIR = artifact path
+     Not found → ERROR E001
+
+Phase-to-Milestone resolution (when scope="phase"):
+  FOR each ms in state.json.milestones[]:
+    IF phase_number in ms.phases[]:
+      target_milestone = ms.id
+      BREAK
+  IF no match: target_milestone = current_milestone (fallback)
+
+  Use target_milestone (not current_milestone) for:
+    - artifact registration (P5 Step 4 milestone field)
+    - collision detection scope (P4.5)
+    - prior artifact lookups
+
+OUTPUT_DIR = .workflow/scratch/{YYYYMMDD}-plan-[P{N}-|M{N}-]{slug}/
+```
+
+### Ad-hoc Milestone Auto-Creation (D-008)
+
+When plan resolves to `scope == "standalone"` AND `state.json.current_milestone == null`:
 
-OUTPUT_DIR = .workflow/scratch/plan-{PHASE_SLUG or milestone_slug}-{date}/
+```
+1. Generate adhoc milestone ID: "M-adhoc-{YYYYMMDD}-{HHmmss}"
+2. Create milestone entry:
+   {
+     "id": "M-adhoc-{YYYYMMDD}-{HHmmss}",
+     "type": "adhoc",
+     "name": "Ad-hoc: {plan_slug or analyze_title}",
+     "status": "active",
+     "phases": [1],
+     "phase_slugs": { "1": "standalone" },
+     "roadmap_ref": null,
+     "created_at": "{ISO-8601}"
+   }
+3. Push to state.json.milestones[]
+4. Set state.json.current_milestone = milestone.id
+5. Use this milestone ID for artifact registration (P5 Step 4)
 ```
 
+This ensures downstream commands (verify, milestone-audit, milestone-complete) have a valid milestone context without requiring roadmap.
+
+**Backward compatibility:** If `state.json.milestones[]` already has entries with `current_milestone != null`, skip creation (existing milestone takes precedence). Missing `type` field on legacy milestones defaults to `"standard"`.
+
 ---
 
 ## Flag Processing
@@ -48,6 +94,7 @@ OUTPUT_DIR = .workflow/scratch/plan-{PHASE_SLUG or milestone_slug}-{date}/
 | `--revise [instructions]` | Revise existing plan (skip P1-P3, load → modify → P4). Auto-discovers latest plan or use `--dir` |
 | `--check <plan-dir>` | Standalone plan verification (P4 only, read-only) |
 | `--tdd` | Generate TDD task chains (RED-GREEN-REFACTOR triplets). Load `@~/.maestro/workflows/tdd.md` for discipline and task structure |
+| `--from <source>` | Load upstream context directly (analyze:ANL-xxx, blueprint:BLP-xxx, brainstorm:ID, @file, or path). Bypasses roadmap requirement for analyze/blueprint sources |
 
 ---
 
@@ -78,10 +125,18 @@ When `--tdd` is active:
 ### Steps
 
 1. **Load user decisions**
-   - Read `${CONTEXT_DIR}/context.md` if exists, else warn (no upstream analyze)
-
-2. **Load spec reference** (if `--spec` flag or index.json has spec_ref)
-   - Read from `.workflow/.spec/${spec_ref}/`: spec-summary.md, requirements/_index.md, epics/_index.md
+   - If `--from` specified: resolve to `context-package.json` → load
+     - `constraints[locked]` → immutable constraints (planner must respect)
+     - `constraints[open]` → implementer discretion
+     - `constraints[deferred]` → explicitly scoped out
+     - `requirements[]` → task scope input
+     - `insights[]` → role analysis context (data models, state machines, architecture decisions)
+     - `open_questions[]` → flag areas needing clarification in P2
+   - Else: read `${CONTEXT_DIR}/context.md` if exists, else warn (no upstream analyze)
+   - Merge: if both `--from` and `context.md` exist, context-package takes precedence; context.md supplements
+
+2. **Load spec reference** (if `--spec` flag or index.json has blueprint_ref)
+   - Read from `.workflow/blueprint/${blueprint_ref}/`: blueprint-summary.md, requirements/_index.md, epics/_index.md
 
 3. **Load project specs**
    ```
@@ -106,6 +161,11 @@ When `--tdd` is active:
        - `scope.priority` → task/wave ordering
      - Skip parallel exploration
 
+5b. **Merge context-package insights** (if `--from` was loaded)
+   - If context-package `insights[]` contain `area: "data-model"` or `area: "state-machine"`: inject as planner constraints
+   - Map `insights[].summary` to implementation guidance for relevant tasks
+   - These replace the need for a separate analyze step when brainstorm already provided sufficient role analysis
+
 5. **Parallel exploration** (skip if `--gaps` or upstream analysis loaded)
    - Exploration angles (1-4 based on complexity): architecture, implementation, integration, risk
    - Spawn 1-4 `cli-explore-agent` in parallel, each with phase goal + success_criteria + one angle
@@ -171,9 +231,11 @@ When `--tdd` is active:
 
 **Purpose:** Generate the execution plan.
 
+**Rule:** Main flow MUST NOT create/modify TASK files. All planning delegated to planner agent. Upstream analyze results (conclusions.json / implementation_scope) MUST be passed into planner spawn as `explorationContext` in the same step.
+
 ### Standard Mode (default)
 
-Spawn `workflow-planner` agent with: context.md, spec-ref, doc-index.json, explorationContext (incl. implementationScope), clarificationContext, phase goal + success_criteria, templates (plan.json, task.json).
+Spawn `workflow-planner` agent with: context.md, spec-ref, doc-index.json, explorationContext (incl. implementationScope from P1 Step 5), clarificationContext, phase goal + success_criteria, templates (plan.json, task.json).
 
 **Task count guard**: Before spawning, assess scope complexity:
 - Single feature / simple change → expect **1-2 tasks** max
@@ -236,10 +298,11 @@ Every TASK-*.json MUST include these fields — they are NOT optional:
 
 ### Gap Mode (`--gaps`)
 
-For each gap from explorationContext (P1 Step 6), create `TASK-{NNN}.json`:
-- `type: "fix"`, `description`, `action` (concrete fix_direction), `read_first` (affected files), `convergence.criteria` (grep-verifiable), `issue_id` (if source == "issue")
+Spawn `workflow-planner` agent with: explorationContext (gap list from P1 Step 6), spec-ref, doc-index.json, phase goal + success_criteria, templates, mode = `gap-fix`.
+
+Planner: for each gap emit one task — `type: "fix"`, `description`, `action` (concrete fix_direction), `read_first` (affected files), `convergence.criteria` (grep-verifiable), `issue_id` (if source == "issue"); assign IDs and waves; build plan.json.
 
-Bidirectional linking: update matching issues in `.workflow/issues/issues.jsonl` → `status: "planned"`. Build plan.json with gap-fix tasks.
+Bidirectional linking (main flow, post-planner): update matching issues in `.workflow/issues/issues.jsonl` → `status: "planned"`.
 
 ### Output
 - `plan.json` in PHASE_DIR
@@ -332,6 +395,7 @@ Bidirectional linking: update matching issues in `.workflow/issues/issues.jsonl`
 
 4. **Register artifact in state.json**
    - Find upstream analyze artifact by CONTEXT_DIR path
+   - Determine milestone: use target_milestone from scope resolution; if adhoc milestone was created in this session, use its ID
    - Create artifact: `{ id: "PLN-{NNN}", type: "plan", milestone, phase, scope, path, status: "completed", depends_on, harvested: false, created_at, completed_at }`
    - Append to `state.json.artifacts`, atomic write
 
@@ -389,11 +453,13 @@ Incrementally modify an existing plan without rebuilding from scratch.
      - Update convergence criteria
    - Parse instructions into concrete changes
 
-3. **Apply targeted changes**
-   - Modify affected TASK files in-place
-   - If tasks added/removed: re-sequence task IDs, regenerate wave assignments
-   - Update plan.json summary (task count, wave structure)
-   - Preserve unmodified tasks completely
+3. **Spawn `workflow-planner` agent for revision**
+   - Input: existing plan.json + all `.task/TASK-*.json` + parsed revision instructions + explorationContext (include implementation_scope if conclusions.json exists) + templates
+   - Planner:
+     - Modify affected TASK files in-place
+     - If tasks added/removed: re-sequence task IDs, regenerate wave assignments
+     - Update plan.json summary (task count, wave structure)
+     - Preserve unmodified tasks
 
 4. **Re-run plan-checker (P4)**
    - Validate modified plan with same checker as create mode

package/workflows/roadmap-common.md

@@ -1,6 +1,6 @@
 # Workflow: Roadmap Common
 
-Shared logic for roadmap generation — used by both light mode (roadmap.md) and full mode (spec-generate.md).
+Shared logic for roadmap generation — used by roadmap.md.
 
 ---