maestro-flow 0.4.11 → 0.4.13

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

@@ -1,66 +1,68 @@
 ---
 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. 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`, existing `roadmap.md`, `project.md`, `maestro spec load`, `maestro wiki search`, Glob/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 the `Roadmap Decisions` section at the top of `.workflow/roadmap.md` (create the section if absent). Do NOT batch writeback to the end — partial decisions must already be on disk before the next question.
+- 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 explicit user signal to proceed, finalize the `Roadmap Decisions` section (rows already populated incrementally). Schema:
+`| # | 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 +76,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 +92,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 +114,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 +134,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 +166,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

@@ -81,13 +81,15 @@ 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"
-"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"
+"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. Return JSON array of component entries with id (TC-NNN), name, type, code_locations, symbols via output_schema. Do NOT write files — orchestrator assembles doc-index.json in Phase 3.","components","<ABS_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 <ABS_WORKFLOW>/blueprint/ exists. Return JSON array of feature entries with id (FT-NNN), name, status, component_ids, requirement_ids, phase via output_schema. Do NOT write files.","features","<ABS_WORKFLOW>/codebase/doc-index.json#features","","","1"
+"3","Requirement Linker","If <ABS_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. Return JSON arrays for requirements and architecture_decisions via output_schema. Do NOT write files.","requirements","<ABS_WORKFLOW>/codebase/doc-index.json#requirements","","","1"
+"4","Tech Registry Writer","For each component discovered, use the Write tool to create a markdown documentation file at <ABS_WORKFLOW>/codebase/tech-registry/{slug}.md with: ID, type, features, code locations, exported symbols, dependencies. Also write <ABS_WORKFLOW>/codebase/tech-registry/_index.md with the component table. After all writes, verify every intended file exists with Glob and return file count + absolute paths via output_schema. MUST use the Write tool — files on disk are the deliverable, do NOT return file content as text.","tech-registry","<ABS_WORKFLOW>/codebase/tech-registry/","","","1"
+"5","Feature Map Writer","For each feature discovered, use the Write tool to create a markdown documentation file at <ABS_WORKFLOW>/codebase/feature-maps/{slug}.md with: ID, status, phase, requirements, component table. Also write <ABS_WORKFLOW>/codebase/feature-maps/_index.md with the feature table. After all writes, verify every intended file exists with Glob and return file count + absolute paths via output_schema. MUST use the Write tool — files on disk are the deliverable, do NOT return file content as text.","feature-maps","<ABS_WORKFLOW>/codebase/feature-maps/","","","1"
 ```
 
+**Path resolution (orchestrator MUST do BEFORE writing tasks.csv)**: substitute `<ABS_WORKFLOW>` with the absolute path to the project's `.workflow/` directory (e.g. `D:/maestro2/.workflow`). Agent Write tool requires absolute paths — passing relative `.workflow/...` literals will fail.
+
 **Columns**:
 
 | Column | Phase | Description |
@@ -125,6 +127,8 @@ Single wave generates `wave-1.csv`. No `prev_context` needed (all tasks independ
 6. **Single Wave**: All generators are independent, no wave ordering needed
 7. **Cleanup Temp Files**: Remove wave-1.csv after results are merged
 8. **DO NOT STOP**: Execute until all generators complete or fail
+9. **Absolute Paths Only**: All paths in `description` and `output_path` MUST be absolute before tasks.csv is written. Orchestrator substitutes `<ABS_WORKFLOW>` placeholder; never let it leak into a spawned agent's prompt.
+10. **Writer vs Returner Split**: Tasks 1-3 return data via `output_schema` (no file writes). Tasks 4-5 MUST write files via Write tool + verify with Glob. Mixing the two contracts (e.g., returning markdown content as text from tasks 4-5) is a contract violation.
 </invariants>
 
 <execution>

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
@@ -62,9 +64,11 @@ Follow '~/.maestro/workflows/harvest.md' Stages 1–8.
 - Quality enforcement rules → `quality` category
 - Wiki: `maestro wiki create --type <type> --slug harvest-<source_type>-<short_id>`
 - Spec: `maestro wiki append spec-<file> --body "<content>" --keywords "<kws>"` (unified write path) or `Skill({ skill: "spec-add", args: "<category> <content>" })`
-- Issue: append to `issues.jsonl` matching canonical schema
+- Issue: append to `issues.jsonl` matching canonical schema, with `source: "harvest"` field (distinguishes from `manage-issue-discover`, which uses `source: "discover"` — required for cross-skill dedup when both write concurrently)
 
 **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/manage-issue-discover/SKILL.md

@@ -155,7 +155,7 @@ Also writes to:
 5. **Discovery Board is Append-Only**: Never clear, modify, or recreate discoveries.ndjson
 6. **Skip on Failure**: If all perspective agents failed, skip dedup
 7. **Evidence Required**: Every finding must have file:line reference -- no speculative issues
-8. **Dedup Before Create**: Never append to issues.jsonl without deduplication
+8. **Dedup Before Create**: Never append to issues.jsonl without deduplication. Every appended record MUST include `source: "discover"` so concurrent writers (e.g. `manage-harvest` uses `source: "harvest"`) can be safely distinguished and deduplicated cross-skill.
 9. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
 10. **DO NOT STOP**: Continuous execution until all waves complete
 </invariants>

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

@@ -73,7 +73,7 @@ After write operations, verify:
 <error_codes>
 | Code | Severity | Description |
 |------|----------|-------------|
-| E001 | error | No stores found — run `Skill({ skill: "manage-knowhow-capture" })` or create MEMORY.md |
+| E001 | error | No stores found — for workflow store run `Skill({ skill: "manage-knowhow-capture" })`; for system store run `Skill({ skill: "manage-memory-capture" })` or create MEMORY.md |
 | E002 | error | Entry ID or filename not found |
 | E003 | error | Prune requires at least one filter flag |
 | E004 | error | Cannot delete MEMORY.md — use `edit` subcommand instead |

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

@@ -6,7 +6,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 
 <purpose>
-Pure file-operation CRUD skill for the workflow knowhow library. No agent spawning, no CLI calls, no LLM inference — just parse-infer-append-confirm. Complements `quality-retrospective`: where retrospective extracts insights in bulk from completed phases, `manage-learn` captures one timeless insight at a time during active work. Both write to the same `specs/learnings.md` store, disambiguated by `source` and `lens` fields.
+Pure file-operation CRUD skill for the workflow knowhow library. No agent spawning, no CLI calls, no LLM inference — just parse-infer-append-confirm. Complements `quality-retrospective`: where retrospective extracts insights in bulk from completed phases, `manage-learn` captures one timeless insight at a time during active work. Both write to the same `.workflow/specs/learnings.md` store, disambiguated by `source` and `lens` fields.
 
 ```
 Parse Mode  →  Bootstrap Store  →  Execute Mode  →  Confirm
@@ -94,7 +94,7 @@ Verify `.workflow/` exists (E001 if not). If `.workflow/specs/learnings.md` miss
 2. **Auto-link phase** from `state.json` artifact registry. `--phase 0` forces null.
 3. **Generate INS-id**: `INS-{8 hex}` from `hash(insightText + timestamp)`.
 4. **Build row** with fields: id, title (first 80 chars), summary, source="manual", lens=null, category, tags (includes "manual"), phase, phase_slug, confidence, routed_to=null, created_at.
-5. **Append** entry to `specs/learnings.md` (append-only, never rewrite).
+5. **Append** entry to `.workflow/specs/learnings.md` (append-only, never rewrite).
 6. WikiIndexer auto-indexes the new entry (no manual index update needed).
 
 #### List Mode
@@ -129,7 +129,7 @@ Capture mode: display ID, category, phase, confidence, tags, and next-step comma
 - [ ] Mode parsed correctly (capture, list, search, show)
 - [ ] Learning store bootstrapped on first use
 - [ ] Capture: category inferred from keywords, phase auto-linked, INS-id generated
-- [ ] Capture: entry appended to specs/learnings.md (append-only)
+- [ ] Capture: entry appended to .workflow/specs/learnings.md (append-only)
 - [ ] List: filters applied, newest-first, respects --limit
 - [ ] Search: grep with weighted ranking across title/tags/summary
 - [ ] Show: full record displayed for valid INS-id

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

@@ -223,9 +223,9 @@ Display report: scope, tasks completed/blocked, reflection rounds, strategy adju
 | Result | Next Step |
 |--------|-----------|
 | All tests pass, refactoring complete | `$quality-sync` (update codebase docs) |
-| Test failures remain after refactor | `$quality-debug "{scope}"` |
+| Test failures remain after refactor | `$quality-debug "test failures in {scope} after refactor"` (debug expects bug description, not raw scope) |
 | No test suite available for scope | `$quality-auto-test "{phase}"` |
-| Partial completion (some blocked) | `$quality-debug "{scope}"` for blocked tasks |
+| Partial completion (some blocked) | `$quality-debug "blocked refactor tasks in {scope}: <task titles>"` |
 </execution>
 
 <error_codes>

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

@@ -8,7 +8,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 <purpose>
 Multi-lens retrospective for completed phases. Context-Agent Fork loads phase artifacts once;
 four parallel lens agents (technical, process, quality, decision) analyze independently;
-synthesizer distills insights; outputs are routed to spec stubs, knowhow tips, issues, and specs/learnings.md.
+synthesizer distills insights; outputs are routed to spec stubs, knowhow tips, issues, and .workflow/specs/learnings.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
@@ -125,7 +132,7 @@ Each artifact's type determines its outputs at `.workflow/{a.path}/`:
 7. **Archive before overwrite**: Move existing retrospective.{md,json} to `.history/` with timestamp before writing new ones
 8. **Spec learnings.md backward-compat**: Append to it only if it already exists -- never create it
 9. **Route confirmation**: Unless `-y`, present routing table and ask per-group before writing spec/issue/knowhow
-10. **Lessons always written**: Append to `specs/learnings.md` regardless of `--no-route` -- routing only controls spec/issue/knowhow creation
+10. **Lessons always written**: Append to `.workflow/specs/learnings.md` regardless of `--no-route` -- routing only controls spec/issue/knowhow creation
 </invariants>
 
 <execution>
@@ -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`
@@ -287,6 +294,6 @@ Next steps: `$manage-status`, `$manage-issue "list --source retrospective"`, `$m
 - [ ] Synthesizer produces deduplicated insights with stable INS-ids
 - [ ] Routing applied per insight (spec/issue/knowhow/none) with confirmation
 - [ ] retrospective.{md,json} written to phase directory
-- [ ] Lessons appended to specs/learnings.md regardless of --no-route flag
+- [ ] Lessons appended to .workflow/specs/learnings.md regardless of --no-route flag
 - [ ] Existing retrospective archived before overwrite
 </success_criteria>