maestro-flow 0.4.11 → 0.4.12

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

@@ -1,66 +1,67 @@
 ---
 name: maestro-roadmap
-description: Generate roadmap from requirements (light or full mode)
-argument-hint: "\"<requirements>\" [--mode light|full] [-y|--yes] [-c] [--phases N] [--skip-research] [--from-brainstorm SESSION-ID] [--revise [instructions]] [--review]"
+description: Generate milestone/phase roadmap from requirements or upstream context
+argument-hint: "\"<requirements>\" [-m progressive|direct|auto] [-y|--yes] [-c] [--phases N] [--skip-research] [--from <source>] [--from-brainstorm SESSION-ID] [--revise [instructions]] [--review]"
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
 <purpose>
-Unified 2-wave roadmap generation using `spawn_agents_on_csv` with dual modes:
+Generate a milestone/phase roadmap using `spawn_agents_on_csv` with 2-wave analysis:
 
-- **Light** (default): Wave 1 parallel analysis (scope, risk, dependency). Wave 2 assembly -> roadmap.md.
-- **Full** (`--mode full`): Wave 1 parallel research (domain, competitive, tech stack). Wave 2 synthesis -> 7-phase spec chain + roadmap.md.
+Wave 1: parallel analysis (scope, risk, dependency). Wave 2: assembly -> roadmap.md with Milestone > Phase hierarchy.
 
 Additional: `--revise` (modify existing roadmap), `--review` (read-only health check).
+
+For formal specification documents (Product Brief, PRD, Architecture, Epics), use `maestro-blueprint` instead.
 </purpose>
 
 <context>
 $ARGUMENTS -- requirement/idea text or @file reference, plus optional flags.
 
 **Flags**:
-- `--mode light|full`: Execution mode (default: light)
 - `-y, --yes`: Skip all confirmations
-- `-m progressive|direct|auto`: Decomposition strategy (default: auto, light only)
-- `--phases N`: Target phase count (light only)
-- `--revise [instructions]`: Revise existing roadmap preserving completed phases (light only)
-- `--review`: Read-only roadmap health assessment (light only)
-- `--skip-research`: Skip Wave 1, jump to doc generation (full only)
-- `--from-brainstorm SESSION-ID`: Import guidance-specification.md as seed
-
-**Session**: `.workflow/.csv-wave/{YYYYMMDD}-roadmap[-full]-{slug}/`
+- `-m progressive|direct|auto`: Decomposition strategy (default: auto)
+- `--phases N`: Target phase count
+- `--revise [instructions]`: Revise existing roadmap preserving completed phases
+- `--review`: Read-only roadmap health assessment
+- `--from <source>`: Load upstream context package (brainstorm:ID, blueprint:BLP-xxx, analyze:ANL-xxx, @file, or path)
+- `--from-brainstorm SESSION-ID`: (backward compat alias for `--from brainstorm:ID`)
+
+**Session**: `.workflow/.csv-wave/{YYYYMMDD}-roadmap-{slug}/`
 **Output**: tasks.csv, results.csv, discoveries.ndjson, context.md, `.workflow/roadmap.md`
-**Full mode additional**: Spec package in `.workflow/.spec/SPEC-{slug}-{date}/`
 </context>
 
+<interview_protocol>
+Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `--revise`, `--review`, `-c`, or input is already specific (clear requirement + mode).
+
+- One decision per turn via request_user_input with 2–4 options + a (Recommended) default; every question must include a `Proceed now` option.
+- Never ask what code can verify — resolve via `state.json`, existing `roadmap.md`, `project.md`, or `maestro spec load`.
+- Walk the decision dependency tree strictly: mode → requirement scope → decomposition strategy → phase dependencies/order. Do not open the next branch until the current one is settled.
+- Scope guard: only decide the shape of the roadmap. Do not pre-resolve intra-phase task breakdown — that belongs to `plan`.
+
+Decision points: scope (MVP / complete / phased) → strategy (progressive / direct / auto) → milestone boundaries → phase dependencies and order.
+
+Exit: on consensus or `Proceed now`, append the table below to a `Roadmap Decisions` section at the top of `.workflow/roadmap.md`:
+`| # | Decision | Choice | Source (user / code / default) |`
+</interview_protocol>
+
 <csv_schema>
 
-### tasks.csv -- Light Mode
+### tasks.csv
 
 ```csv
 id,title,description,analysis_focus,deps,context_from,wave,status,findings,error
 "1","Scope Analysis","Identify features, MVP boundaries, must-have vs nice-to-have, size estimates.","scope","","","1","","",""
 "2","Risk Analysis","Technical/project risks, unknowns, feasibility, risk levels, mitigations.","risk","","","1","","",""
 "3","Dependency Analysis","Feature dependencies, ordering constraints, parallel-safe groups, external deps.","dependency","","","1","","",""
-"4","Roadmap Assembly","Synthesize findings into roadmap.md: phases, milestones, success criteria.","","1;2;3","1;2;3","2","","",""
+"4","Roadmap Assembly","Synthesize findings into roadmap.md: Milestone > Phase hierarchy, success criteria.","","1;2;3","1;2;3","2","","",""
 ```
 
-### tasks.csv -- Full Mode
-
-```csv
-id,title,description,research_focus,doc_phase,deps,context_from,wave,status,findings,output_file,error
-"1","Domain Research","Target users, market needs, existing solutions, terminology.","domain","","","","1","","","",""
-"2","Competitive Analysis","Feature comparison, UX patterns, gaps, opportunities.","competitive","","","","1","","","",""
-"3","Tech Stack Analysis","Languages, frameworks, databases, constraints, scalability.","tech_stack","","","","1","","","",""
-"4","Document Chain","7-phase spec: Product Brief, PRD (REQ-*/NFR-*), Architecture (ADR-*), Data Model, API, UI Wireframes, Epic-to-Roadmap (EPIC-*). + glossary.json.","","1-7","1;2;3","1;2;3","2","","","",""
-```
-
-**Shared column semantics**:
-- Input: id (unique string), title, description (detailed instructions), deps (semicolon-sep IDs), context_from (IDs whose findings needed), wave (1=analysis/research, 2=assembly/synthesis)
+**Column semantics**:
+- Input: id (unique string), title, description (detailed instructions), analysis_focus (scope/risk/dependency), deps (semicolon-sep IDs), context_from (IDs whose findings needed), wave (1=analysis, 2=assembly)
 - Output: status (pending->completed/failed/skipped), findings (max 500 chars), error
-- Light-only: analysis_focus (scope/risk/dependency)
-- Full-only: research_focus (domain/competitive/tech_stack), doc_phase (1-7), output_file
 
-Wave 1: 3 analysis/research rows (parallel). Wave 2: 1 assembly/synthesis row.
+Wave 1: 3 analysis rows (parallel). Wave 2: 1 assembly row.
 </csv_schema>
 
 <invariants>
@@ -74,12 +75,11 @@ Wave 1: 3 analysis/research rows (parallel). Wave 2: 1 assembly/synthesis row.
 <state_machine>
 
 <states>
-S_PARSE      -- 解析参数、检测 mode/operation              PERSIST: --
-S_INPUT      -- 解析输入（text/@file/brainstorm）          PERSIST: --
+S_PARSE      -- 解析参数、检测 operation                    PERSIST: --
+S_INPUT      -- 解析输入（text/@file/upstream context）     PERSIST: --
 S_CSV_GEN    -- 生成 tasks.csv                              PERSIST: tasks.csv
-S_WAVE_1     -- Analysis/Research (parallel spawn)           PERSIST: findings + tasks.csv
-S_WAVE_2     -- Assembly/Synthesis (single agent spawn)      PERSIST: roadmap.md [+ spec package]
-S_SPEC_GEN   -- Spec package generation (full mode only)     PERSIST: .workflow/.spec/SPEC-*/
+S_WAVE_1     -- Analysis (parallel spawn)                    PERSIST: findings + tasks.csv
+S_WAVE_2     -- Assembly (single agent spawn)                PERSIST: roadmap.md
 S_AGGREGATE  -- 精炼、评估、输出                            PERSIST: context.md + .workflow/roadmap.md
 </states>
 
@@ -91,21 +91,16 @@ S_PARSE:
   -> REVIEW_FLOW    WHEN: --review (read-only health assessment)
 
 S_INPUT:
-  -> S_CSV_GEN      DO: parse requirement (text/@file), import brainstorm if --from-brainstorm, codebase detection, load specs
+  -> S_CSV_GEN      DO: parse requirement (text/@file), load context-package.json if --from, codebase detection, load specs
 
 S_CSV_GEN:
-  -> S_WAVE_1       WHEN: normal pipeline     DO: generate mode-specific CSV
-  -> S_WAVE_2       WHEN: --skip-research     DO: generate wave 2 only
+  -> S_WAVE_1       DO: generate analysis CSV
 
 S_WAVE_1:
   -> S_WAVE_2       DO: A_SPAWN_WAVE_1
 
 S_WAVE_2:
-  -> S_SPEC_GEN     WHEN: full mode           DO: A_SPAWN_WAVE_2
-  -> S_AGGREGATE    WHEN: light mode           DO: A_SPAWN_WAVE_2
-
-S_SPEC_GEN:
-  -> S_AGGREGATE    DO: generate 7-phase spec package per spec-generate.md
+  -> S_AGGREGATE    DO: A_SPAWN_WAVE_2
 
 S_AGGREGATE:
   -> END            DO: A_AGGREGATE_RESULTS
@@ -118,16 +113,15 @@ S_AGGREGATE:
 
 Filter wave==1 -> write wave-1.csv -> `spawn_agents_on_csv`.
 
-**Light mode agents**: scope analysis (feature inventory + priority), risk analysis (unknowns + mitigations), dependency analysis (dependency graph + critical path).
-**Full mode agents**: domain research (users, market, solutions), competitive analysis (feature matrix, gaps), tech stack analysis (feasibility, constraints).
+**Agents**: scope analysis (feature inventory + priority), risk analysis (unknowns + mitigations), dependency analysis (dependency graph + critical path).
 
 Merge results -> master tasks.csv.
 
 ### A_SPAWN_WAVE_2
 
-Build prev_context from wave 1. Inject strategy + --phases constraint (light mode). Spawn.
+Build prev_context from wave 1. Inject strategy + `--phases` constraint. Spawn.
 
-**Light mode**: Assembly agent produces roadmap.md with phases (goal, depends-on, requirements, success criteria), milestones, scope decisions.
+Assembly agent produces roadmap.md with Milestone > Phase hierarchy (goal, depends-on, requirements, success criteria), scope decisions.
 
 **Strategy selection** via uncertainty assessment (5 factors):
 | Factor | Low | Medium | High |
@@ -139,26 +133,15 @@ Build prev_context from wave 1. Inject strategy + --phases constraint (light mod
 | Requirement stability | locked | some flux | evolving |
 
 >=3 high -> progressive, >=3 low -> direct, else -> ask (or auto if -y).
-**Full mode**: Document chain agent produces 7-phase spec package + glossary.json.
 
 ### A_AGGREGATE_RESULTS
 
 1. Export results.csv
 2. Interactive refinement (max 3 rounds, skip if -y): Approve / Refine / Regenerate
-3. **Full mode readiness** (4 dimensions, 25% each): Completeness, Consistency, Traceability, Depth. Gate: >=80% pass, 60-79% review with caveats, <60% auto-fix attempt
-4. Generate context.md (light: summary + analysis findings + roadmap stats; full: research findings + doc chain status + readiness scores)
-5. Write .workflow/roadmap.md (both modes)
-6. Write spec package to .workflow/.spec/SPEC-{slug}-{date}/ (full mode):
-   ```
-   SPEC-{slug}-{date}/
-   +-- spec-config.json, product-brief.md, glossary.json, spec-summary.md
-   +-- requirements/ (_index.md, REQ-NNN-{slug}.md, NFR-{type}-NNN-{slug}.md)
-   +-- architecture/ (_index.md, ADR-NNN-{slug}.md)
-   +-- epics/ (_index.md, EPIC-NNN-{slug}.md)
-   +-- readiness-report.md
-   ```
-7. Update state.json milestones + current_milestone
-8. Next-step routing: need analysis -> maestro-analyze; ready to plan -> maestro-plan; UI first -> maestro-impeccable build; full mode setup -> maestro-init
+3. Generate context.md (summary + analysis findings + roadmap stats)
+4. Write .workflow/roadmap.md with Milestone > Phase hierarchy
+5. Update state.json milestones + current_milestone
+6. Next-step routing: need analysis -> maestro-analyze; ready to plan -> maestro-plan; UI first -> maestro-impeccable build; need formal specs -> maestro-blueprint
 
 </actions>
 
@@ -182,20 +165,20 @@ Protocol: read before analysis, append-only, dedup by type+key.
 | Condition | Recovery |
 |-----------|----------|
 | No requirement text provided | Abort: "Requirement text or @file required" |
-| Brainstorm session not found | Abort with available sessions list |
+| Context source not found (--from / --from-brainstorm) | Abort with available sessions/sources list |
 | roadmap.md not found (--revise/--review) | Run maestro-roadmap first |
 | All Wave 1 agents failed | Wave 2 in degraded mode (seed only) |
-| Wave 2 agent failed (light) | Abort: "Roadmap generation failed" |
-| Wave 2 agent failed (full) | Export partial output, log issues |
-| Readiness < 60% (full) | Log issues, proceed with available output |
+| Wave 2 agent failed | Abort: "Roadmap generation failed" |
+| Readiness < 60% | Log issues, proceed with available output |
 </error_codes>
 
 <success_criteria>
+- [ ] Interactive mode: interview decision table appended to `.workflow/roadmap.md` "Roadmap Decisions" section
 - [ ] Wave 1 agents completed (analysis or research)
-- [ ] Wave 2 produced output (roadmap.md + optional spec package)
-- [ ] .workflow/roadmap.md written, state.json updated
+- [ ] Wave 2 produced output (roadmap.md)
+- [ ] .workflow/roadmap.md written with Milestone > Phase hierarchy, state.json updated
 - [ ] context.md generated
-- [ ] Light: uncertainty assessed, strategy selected, phases with milestones + success criteria
-- [ ] Full: spec package in .workflow/.spec/, readiness scored on 4 dimensions
+- [ ] Uncertainty assessed, strategy selected, milestones with phases + success criteria
+- [ ] Artifact registered in state.json with milestone entries
 </success_criteria>
 </output>

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

@@ -0,0 +1,169 @@
+---
+name: maestro-update
+description: Detect version, preview changes, apply workflow upgrades
+argument-hint: "[--dry-run] [--force]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
+---
+<purpose>
+Detect the current `.workflow/` schema version, show available migrations, and interactively apply them step-by-step. Uses a migration registry that supports incremental version upgrades (e.g., 1.0 → 2.0 → 3.0).
+
+Each migration step is previewed before execution. The user confirms each step in a loop.
+</purpose>
+
+<context>
+$ARGUMENTS — optional flags.
+
+**Flags:**
+- `--dry-run` -- Preview migration plan without executing
+- `--force` -- Skip confirmation prompts (apply all pending migrations)
+
+**Migration registry:** `src/migrations/`
+- Each migration is a standalone file (e.g., `v1-to-v2.ts`) exporting a `MigrationDef`
+- All migrations are registered via `src/migrations/index.ts`
+- Registry auto-chains: detects current version → walks chain → applies in order
+- To add a new migration: create `src/migrations/v{N}-to-v{N+1}.ts`, register in `index.ts`
+
+**CLI runner:** `src/migrations/run.ts`
+- Executable entrypoint: `npx tsx src/migrations/run.ts [root] [--dry-run] [--force] [--json]`
+- Outputs JSON (with `--json`) or human-readable text
+
+**State version source:** `.workflow/state.json` → `version` field
+</context>
+
+<execution>
+
+### Step 1: Detect Current State
+
+```
+1. Read .workflow/state.json
+2. Extract version field (default "1.0" if missing)
+3. Display:
+
+   === Maestro Workflow Update ===
+   Project:  {project_name}
+   Version:  {version}
+   Location: {.workflow/ path}
+```
+
+### Step 2: Dry-Run Preview
+
+Run the migration CLI in dry-run + JSON mode to get the full plan:
+
+```bash
+npx tsx src/migrations/run.ts "$(pwd)" --dry-run --json
+```
+
+Parse the JSON output. If status is `up-to-date`:
+```
+Already up to date (v{version})
+```
+→ EXIT
+
+Otherwise display the migration plan:
+```
+Pending Migrations ({N} step(s)):
+
+  1. [v{from} → v{to}] {name}
+     {description}
+
+  2. [v{from} → v{to}] {name}
+     {description}
+```
+
+If `--dry-run` flag was passed by user → display plan and EXIT.
+
+### Step 3: Interactive Confirmation Loop
+
+For each migration step (unless `--force`):
+
+```
+LOOP for step_index = 1 to N:
+
+  Display:
+    --- Step {step_index}/{N}: {name} ---
+    Version: v{from} → v{to}
+
+    Changes:
+      {description, indented}
+
+  IF NOT --force:
+    AskUserQuestion: "Apply this migration?"
+    Options: [yes / skip / abort]
+
+    - "yes"   → proceed to Step 4 (execute)
+    - "skip"  → WARN "Skipping may break the migration chain"
+                 continue to next step
+    - "abort" → display summary of what was applied so far → EXIT
+
+  IF --force:
+    → proceed to Step 4 (execute)
+```
+
+### Step 4: Execute Single Migration
+
+```
+1. Create backup:
+   Bash: cp .workflow/state.json .workflow/state.json.backup-v{from}-{timestamp}
+
+2. Run migration:
+   Bash: npx tsx src/migrations/run.ts "$(pwd)" --json
+   
+   NOTE: The runner executes ALL pending migrations. For step-by-step control,
+   read state.json, call the migration function directly, or use the runner
+   which stops on first failure.
+
+3. Parse result JSON and display:
+
+   {status_icon} Step {N} completed: {name}
+   Summary: {summary}
+   Changes:
+     - {change_1}
+     - {change_2}
+     - ...
+
+4. If failed:
+   Display: "Migration failed: {summary}"
+   Display: "Backup available at: {backup_path}"
+   Display: "Restore with: cp {backup_path} .workflow/state.json"
+   → EXIT
+
+5. Continue loop to next step
+```
+
+### Step 5: Summary
+
+After all steps completed (or user aborted):
+
+```
+=== Migration Complete ===
+Applied: {applied_count} / {total_count} migration(s)
+Skipped: {skipped_count}
+Version: v{original} → v{final}
+Backup:  .workflow/state.json.backup-v{original}-{timestamp}
+
+Next steps:
+  /manage-status  -- Verify project state
+  /maestro        -- Continue workflow
+```
+
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | .workflow/state.json not found | Run /maestro-init first |
+| E002 | error | state.json parse error | Check file for corruption |
+| E003 | error | Migration function failed | Restore from backup |
+| W001 | warning | Skipped migration may break version chain | Re-run /maestro-update later |
+| W002 | warning | tsx not available | Install tsx: npm i -D tsx |
+</error_codes>
+
+<success_criteria>
+- [ ] Current version detected from state.json
+- [ ] Dry-run preview shows full migration plan without execution
+- [ ] Each step confirmed interactively (unless --force)
+- [ ] Backup created before each migration
+- [ ] Migration executed and result displayed with change list
+- [ ] Abort stops cleanly with partial summary
+- [ ] Summary shows applied/skipped counts and version change
+</success_criteria>

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

@@ -94,9 +94,18 @@ S_AGGREGATE  -- 生成报告、创建 issues、修复计划             PERSIST:
 <transitions>
 
 S_PARSE:
-  -> S_MUST_HAVE    WHEN: phase resolved    DO: load index.json, plan.json, TASK-*.json, summaries, uat.md, ARCHITECTURE.md
+  -> S_MUST_HAVE    WHEN: phase resolved    DO: load index.json, plan.json, TASK-*.json, summaries, uat.md, ARCHITECTURE.md; **D-007 milestone reverse lookup** for numeric phase
   -> ERROR          WHEN: phase not found
 
+  **D-007 milestone reverse lookup** (numeric phase arg):
+  ```
+  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
+  ```
+  Write resolved milestone into `session.milestone` and VRF artifact registration. NEVER read `current_milestone` directly for phase-scoped runs.
+
 S_MUST_HAVE:
   -> S_CSV_GEN      DO: establish must-haves from success_criteria (primary), convergence.criteria (per-task), derived behaviors (fallback). Decompose into truth/artifact/wiring layers.
 
@@ -202,7 +211,7 @@ Protocol: read before analysis, append-only, dedup by type+key.
 - [ ] Issues auto-created for gaps + blocker anti-patterns
 - [ ] Post-verify knowledge inquiry triggered when applicable
 - [ ] Phase index.json updated with verification status
-- [ ] VRF artifact registered in state.json
+- [ ] VRF artifact registered in state.json (numeric scope: milestone resolved via D-007 `phase_slugs` reverse lookup, NOT direct `current_milestone` read)
 - [ ] Gap-fix closure loop documented: gaps → plan --gaps → execute → verify (re-run)
 - [ ] Next step routed (quality-review if passed, plan --gaps if gaps, quality-auto-test if low coverage)
 - [ ] discoveries.ndjson append-only throughout

package/.codex/skills/manage-codebase-rebuild/SKILL.md

@@ -82,8 +82,8 @@ When `--yes` or `-y`: Auto-confirm rebuild (implies --force), skip all prompts.
 ```csv
 id,title,description,doc_dimension,output_path,deps,context_from,wave
 "1","Component Scanner","Scan all source directories for components: models, services, controllers, utils, types, config, middleware, core modules. For each component extract exported symbols, determine type, record code locations. Output JSON array of component entries with id (TC-NNN), name, type, code_locations, symbols.","components",".workflow/codebase/doc-index.json#components","","","1"
-"2","Feature Mapper","Group discovered components by domain/functional area using directory proximity, naming patterns, and import relationships. Map features to requirements if .workflow/.spec/ exists. Output JSON array of feature entries with id (FT-NNN), name, status, component_ids, requirement_ids, phase.","features",".workflow/codebase/doc-index.json#features","","","1"
-"3","Requirement Linker","If .workflow/.spec/ exists, scan SPEC-*/requirements/REQ-*.md files. Parse requirement metadata (title, priority, acceptance_criteria). Match requirements to features by keyword analysis. Also scan for ADR-*.md architecture decisions. Output JSON arrays for requirements and architecture_decisions.","requirements",".workflow/codebase/doc-index.json#requirements","","","1"
+"2","Feature Mapper","Group discovered components by domain/functional area using directory proximity, naming patterns, and import relationships. Map features to requirements if .workflow/blueprint/ exists. Output JSON array of feature entries with id (FT-NNN), name, status, component_ids, requirement_ids, phase.","features",".workflow/codebase/doc-index.json#features","","","1"
+"3","Requirement Linker","If .workflow/blueprint/ exists, scan BLP-*/requirements/REQ-*.md files. Parse requirement metadata (title, priority, acceptance_criteria). Match requirements to features by keyword analysis. Also scan for ADR-*.md architecture decisions. Output JSON arrays for requirements and architecture_decisions.","requirements",".workflow/codebase/doc-index.json#requirements","","","1"
 "4","Tech Registry Writer","For each component discovered, generate a markdown documentation file in .workflow/codebase/tech-registry/{slug}.md with: ID, type, features, code locations, exported symbols, dependencies. Generate _index.md with component table. Output file count and paths.","tech-registry",".workflow/codebase/tech-registry/","","","1"
 "5","Feature Map Writer","For each feature discovered, generate a markdown documentation file in .workflow/codebase/feature-maps/{slug}.md with: ID, status, phase, requirements, component table. Generate _index.md with feature table. Output file count and paths.","feature-maps",".workflow/codebase/feature-maps/","","","1"
 ```

package/.codex/skills/manage-harvest/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: manage-harvest
 description: Extract knowledge from artifacts into wiki/spec/issues
-argument-hint: "[<session-id|path>] [--to wiki|spec|issue|auto] [--source <type>] [--recent N] [--dry-run] [-y]"
+argument-hint: "[<session-id|path>] [--to wiki|spec|issue|auto] [--source <type>] [--recent N] [--dry-run] [-y] [--prune] [--age N]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---
 
@@ -31,6 +31,8 @@ $ARGUMENTS — session-id, path, or empty for scan mode.
 - `--dry-run` — Preview without writing
 - `-y` — Skip confirmations
 - `--min-confidence N` — Minimum 0.0-1.0 (default: 0.5)
+- `--prune` — State hygiene mode: classify artifacts, graduate harvested → knowhow, archive from state.json, prune accumulated_context
+- `--age N` — Graduation age threshold in days (default: 14). Used with `--prune`
 
 **Source registry:**
 | Source | Scan Path | Key Files |
@@ -46,7 +48,7 @@ $ARGUMENTS — session-id, path, or empty for scan mode.
 </context>
 
 <execution>
-Follow '~/.maestro/workflows/harvest.md' Stages 1–8.
+Follow '~/.maestro/workflows/harvest.md' Stages 1–8 (standard mode) or Stage 9 (`--prune` mode).
 
 **Key invariants:**
 1. **Read-only until Stage 6** — extraction/classification in-memory only
@@ -65,6 +67,8 @@ Follow '~/.maestro/workflows/harvest.md' Stages 1–8.
 - Issue: append to `issues.jsonl` matching canonical schema
 
 **Next steps:** `/manage-wiki health`, `maestro wiki list --type note`, `/wiki-connect --fix`, `/wiki-digest`, `/manage-issue list --source harvest`
+
+**Prune mode** (`--prune`): Classifies artifacts (active/graduated/stale/protected), graduates harvested artifacts to wiki knowhow, archives from `artifacts[]` → `artifact_archive[]`, prunes resolved entries from accumulated_context. Files on disk are never deleted. Always backs up state.json before writing.
 </execution>
 
 <error_codes>
@@ -88,4 +92,8 @@ Follow '~/.maestro/workflows/harvest.md' Stages 1–8.
 - [ ] harvest-log.jsonl updated with provenance
 - [ ] harvest-report-{date}.md written
 - [ ] No source artifacts modified
+- [ ] If --prune: artifacts classified (active/graduated/stale/protected)
+- [ ] If --prune: graduated artifacts → knowhow + artifact_archive[]
+- [ ] If --prune: accumulated_context pruned (resolved deferred/blockers, deduplicated decisions)
+- [ ] If --prune: state.json backed up before modification
 </success_criteria>

package/.codex/skills/quality-retrospective/SKILL.md

@@ -76,9 +76,16 @@ When `-y`: Accept all routing recommendations without prompting. Route all insig
 
 **Storage read (never modified)** — all resolved via `state.json.artifacts[]`:
 ```
+# D-007 milestone reverse lookup — phase N may belong to a milestone different from current
+target_milestone = resolve_milestone(target_phase)  # see below
 related = artifacts.filter(a =>
-  a.phase === target_phase && a.milestone === current_milestone
+  a.phase === target_phase && a.milestone === target_milestone
 ).sort_by(completed_at asc)
+
+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
 ```
 Each artifact's type determines its outputs at `.workflow/{a.path}/`:
 - **execute** → index.json, plan.json, .task/TASK-*.json, .summaries/TASK-*-summary.md
@@ -168,7 +175,7 @@ spawn_agent({
   task_name: "ctx",
   fork_turns: "none",
   message: `Load and summarize all phase ${targetPhase} artifacts for retrospective.
-    1. Query state.json artifacts[] for phase === ${targetPhase} && milestone === current_milestone
+    1. Query state.json artifacts[] for phase === ${targetPhase} && milestone === resolve_milestone(${targetPhase}) [D-007 reverse lookup via state.json.milestones[].phase_slugs; fallback to current_milestone if phase unmatched]
     2. Load per-artifact outputs (execute→index/plan/tasks/summaries, verify→verification.json, review→review.json, debug→understanding/evidence, test→uat/tests)
     3. Filter issues.jsonl for this phase; read state.json for project context
     EXPECTED: Goals vs outcomes, completion rates, verification/review/UAT results, issue counts, key metrics`

package/.codex/skills/team-lifecycle-v4/roles/analyst/role.md

@@ -75,7 +75,7 @@ EXPECTED: JSON with: tech_stack[], architecture_patterns[], conventions[], integ
 
 ## Phase 4: Context Packaging
 
-1. Write spec-config.json -> <session>/spec/
+1. Write blueprint-config.json -> <session>/spec/
 2. Write discovery-context.json -> <session>/spec/
 3. Inline Discuss (DISCUSS-001):
    - Artifact: <session>/spec/discovery-context.json
@@ -94,7 +94,7 @@ EXPECTED: JSON with: tech_stack[], architecture_patterns[], conventions[], integ
        "discuss_verdict": "<verdict>"
      },
      "data": {
-       "output_paths": ["spec-config.json", "discovery-context.json"]
+       "output_paths": ["blueprint-config.json", "discovery-context.json"]
      }
    }
    ```

package/.codex/skills/team-lifecycle-v4/roles/reviewer/commands/review-spec.md

@@ -22,7 +22,7 @@
 2. Load quality gate thresholds from specs/quality-gates.md
 3. Score each dimension
 4. Run cross-document validation
-5. Generate readiness-report.md + spec-summary.md
+5. Generate readiness-report.md + blueprint-summary.md
 6. Run DISCUSS-003:
    - Artifact: `{session}/spec/readiness-report.md`
    - Perspectives: product, technical, quality, risk, coverage
@@ -41,4 +41,4 @@
 
 Write to `{session}/artifacts/`:
 - readiness-report.md: Dimension scores, issue list, traceability matrix
-- spec-summary.md: Executive summary of all spec docs
+- blueprint-summary.md: Executive summary of all spec docs

package/.codex/skills/team-lifecycle-v4/roles/writer/role.md

@@ -50,7 +50,7 @@ Template-driven document generation with progressive dependency loading.
 
 ### Inputs
 - Template from routing table
-- spec-config.json from <session>/spec/
+- blueprint-config.json from <session>/spec/
 - discovery-context.json from <session>/spec/
 - Prior decisions from context_accumulator (inner loop)
 - Discussion feedback from <session>/discussions/ (if exists)

package/.codex/skills/team-lifecycle-v4/templates/architecture.md

@@ -32,7 +32,7 @@ status: draft
 generated_at: {timestamp}
 version: 1
 dependencies:
-  - ../spec-config.json
+  - ../blueprint-config.json
   - ../product-brief.md
   - ../requirements/_index.md
 ---
@@ -246,9 +246,9 @@ date: {timestamp}
 
 | Variable | Source | Description |
 |----------|--------|-------------|
-| `{session_id}` | spec-config.json | Session identifier |
+| `{session_id}` | blueprint-config.json | Session identifier |
 | `{timestamp}` | Runtime | ISO8601 generation timestamp |
 | `{product_name}` | product-brief.md | Product/feature name |
 | `{NNN}` | Auto-increment | ADR/requirement number |
 | `{slug}` | Auto-generated | Kebab-case from decision title |
-| `{has_codebase}` | spec-config.json | Whether existing codebase exists |
+| `{has_codebase}` | blueprint-config.json | Whether existing codebase exists |

package/.codex/skills/team-lifecycle-v4/templates/epics.md

@@ -32,7 +32,7 @@ status: draft
 generated_at: {timestamp}
 version: 1
 dependencies:
-  - ../spec-config.json
+  - ../blueprint-config.json
   - ../product-brief.md
   - ../requirements/_index.md
   - ../architecture/_index.md
@@ -187,7 +187,7 @@ status: draft
 
 | Variable | Source | Description |
 |----------|--------|-------------|
-| `{session_id}` | spec-config.json | Session identifier |
+| `{session_id}` | blueprint-config.json | Session identifier |
 | `{timestamp}` | Runtime | ISO8601 generation timestamp |
 | `{product_name}` | product-brief.md | Product/feature name |
 | `{EPIC}` | Auto-increment | Epic number (3 digits) |

package/.codex/skills/team-lifecycle-v4/templates/product-brief.md

@@ -23,7 +23,7 @@ generated_at: {timestamp}
 stepsCompleted: []
 version: 1
 dependencies:
-  - spec-config.json
+  - blueprint-config.json
 ---
 
 # Product Brief: {product_name}
@@ -117,7 +117,7 @@ dependencies:
 
 ## References
 
-- Derived from: [spec-config.json](spec-config.json)
+- Derived from: [blueprint-config.json](blueprint-config.json)
 - Next: [Requirements PRD](requirements.md)
 ```
 
@@ -125,7 +125,7 @@ dependencies:
 
 | Variable | Source | Description |
 |----------|--------|-------------|
-| `{session_id}` | spec-config.json | Session identifier |
+| `{session_id}` | blueprint-config.json | Session identifier |
 | `{timestamp}` | Runtime | ISO8601 generation timestamp |
 | `{product_name}` | Seed analysis | Product/feature name |
 | `{executive_summary}` | CLI synthesis | 2-3 sentence summary |

package/.codex/skills/team-lifecycle-v4/templates/requirements.md

@@ -36,7 +36,7 @@ status: draft
 generated_at: {timestamp}
 version: 1
 dependencies:
-  - ../spec-config.json
+  - ../blueprint-config.json
   - ../product-brief.md
 ---
 
@@ -215,7 +215,7 @@ status: draft
 
 | Variable | Source | Description |
 |----------|--------|-------------|
-| `{session_id}` | spec-config.json | Session identifier |
+| `{session_id}` | blueprint-config.json | Session identifier |
 | `{timestamp}` | Runtime | ISO8601 generation timestamp |
 | `{product_name}` | product-brief.md | Product/feature name |
 | `{NNN}` | Auto-increment | Requirement number (zero-padded 3 digits) |