maestro-flow 0.3.7 → 0.3.9

package/workflows/milestone-audit.md

@@ -1,6 +1,6 @@
 # Workflow: milestone-audit
 
-Cross-phase integration audit for milestone completion.
+Cross-phase integration audit for milestone completion. Based on artifact registry.
 
 ---
 
@@ -8,39 +8,73 @@ Cross-phase integration audit for milestone completion.
 
 1. Read `.workflow/state.json`:
    - Determine target milestone (from $ARGUMENTS or current_milestone)
-   - Get phases_summary
+   - Get `artifacts[]` array
 
-2. Identify all phases belonging to this milestone:
-   - Read `.workflow/roadmap.md` to map phases to milestones
-   - Collect phase directories: `.workflow/phases/{NN}-{slug}/`
+2. Parse `.workflow/roadmap.md` to identify all phases belonging to this milestone
 
-3. For each phase, read `index.json`:
-   - Collect: status, goal, success_criteria, verification, validation, uat
-   - Flag any phase not in "completed" status as a warning
+3. Group artifacts by type for this milestone:
+   ```
+   FROM state.json.artifacts
+   WHERE milestone = target_milestone
+   GROUP BY type
+
+   → analyze_artifacts: [ANL-001, ANL-002, ...]
+   → plan_artifacts:    [PLN-001, PLN-002, ...]
+   → execute_artifacts: [EXC-001, EXC-002, ...]
+   → verify_artifacts:  [VRF-001, ...]
+   ```
 
 ---
 
-## Step 2: Pre-audit Validation
+## Step 2: Phase Coverage Check
 
-1. Check all phases are completed:
-   ```
-   incomplete = phases.filter(status != "completed")
-   if incomplete.length > 0:
-     WARN: "Phases not completed: {list}"
-     Ask user: "Continue audit anyway? Some phases are incomplete."
-     if NO → exit with "Complete phases first: /workflow:execute {phase}"
-   ```
+For each phase defined in roadmap for this milestone:
 
-2. Check all phases have verification.json with status "passed":
-   ```
-   unverified = phases.filter(verification.status != "passed")
-   if unverified.length > 0:
-     WARN: "Phases not verified: {list}"
-   ```
+```
+phases_from_roadmap = parse roadmap.md → list of { number, slug, title }
+
+coverage = {}
+FOR each phase IN phases_from_roadmap:
+  has_analyze = artifacts.some(a => a.type == "analyze" && a.phase == phase.number && a.status == "completed")
+  has_plan = artifacts.some(a => a.type == "plan" && a.phase == phase.number && a.status == "completed")
+  has_execute = artifacts.some(a => a.type == "execute" && a.phase == phase.number && a.status == "completed")
+
+  coverage[phase.number] = { has_analyze, has_plan, has_execute }
+
+  IF NOT has_execute:
+    WARN: "Phase {phase.number} ({phase.title}) missing execute artifact"
+```
+
+---
+
+## Step 3: Ad-hoc Completeness Check
+
+```
+adhoc_artifacts = artifacts.filter(a => a.scope == "adhoc" && a.milestone == target_milestone)
+
+incomplete_adhoc = adhoc_artifacts.filter(a => a.status != "completed")
+IF incomplete_adhoc.length > 0:
+  WARN: "Ad-hoc artifacts incomplete: {list ids}"
+```
+
+---
+
+## Step 4: Execution Completeness Check
+
+For each execute artifact, verify all tasks completed:
+
+```
+FOR each exc IN execute_artifacts:
+  plan_dir = exc.path
+  tasks = read all ${plan_dir}/.task/TASK-*.json
+  incomplete = tasks.filter(t => t.status != "completed" && t.status != "skipped")
+  IF incomplete.length > 0:
+    WARN: "Plan {plan_dir}: {incomplete.length} tasks not completed"
+```
 
 ---
 
-## Step 3: Integration Check
+## Step 5: Integration Check
 
 Spawn `workflow-integration-checker` agent:
 
@@ -50,20 +84,20 @@ Agent({
   prompt: "
     Audit cross-phase integration for milestone {milestone}.
 
-    Phases to audit:
-    {for each phase: number, title, goal, success_criteria}
+    Artifacts to audit:
+    {for each execute artifact: path, phase, scope}
 
     Check:
-    1. SHARED INTERFACES -- Do phases that share interfaces have compatible types/contracts?
+    1. SHARED INTERFACES -- Do artifacts that share interfaces have compatible types/contracts?
     2. DEPENDENCY CHAINS -- Are all cross-phase dependencies satisfied?
     3. DATA CONTRACTS -- Do data models used across phases match?
-    4. API CONSISTENCY -- Are API endpoints/interfaces consistent across phases?
+    4. API CONSISTENCY -- Are API endpoints/interfaces consistent?
     5. CONFIGURATION -- Are shared configs compatible?
-    6. ERROR HANDLING -- Do error flows work across phase boundaries?
+    6. ERROR HANDLING -- Do error flows work across boundaries?
 
     For each check, report:
     - Status: passed | gap_found
-    - If gap: description, affected phases, severity (critical/high/medium/low), fix suggestion
+    - If gap: description, affected phases, severity, fix suggestion
 
     Ensure directory exists: mkdir -p .workflow/milestones/{milestone}/
     Write audit report to .workflow/milestones/{milestone}/audit-report.md
@@ -75,56 +109,41 @@ Agent({
 
 ---
 
-## Step 4: Audit Report
+## Step 6: Audit Report & Verdict
 
 1. Read the audit report generated by the integration checker
-2. Display summary:
+
+2. Determine verdict:
+   - PASS: all phases have complete artifact chains + no critical integration gaps
+   - FAIL: missing execute artifacts OR critical integration gaps
+
+3. Display structured report:
 
 ```
 ====================================================
-  MILESTONE AUDIT: {milestone}
-  PHASES AUDITED: {count}
+  MILESTONE AUDIT: {milestone} ({milestone_name})
+  ARTIFACTS: {total_count}
 ====================================================
 
-RESULTS:
-  Shared Interfaces:   {passed|N gaps}
-  Dependency Chains:   {passed|N gaps}
-  Data Contracts:      {passed|N gaps}
-  API Consistency:     {passed|N gaps}
-  Configuration:       {passed|N gaps}
-  Error Handling:      {passed|N gaps}
-
-TOTAL GAPS: {count}
-  Critical: {count}
-  High:     {count}
-  Medium:   {count}
-  Low:      {count}
-====================================================
-```
+PHASE COVERAGE:
+  Phase 1 ({slug}):    ANL-001 → PLN-001 → EXC-001 ✓
+  Phase 2 ({slug}):    ANL-002 → PLN-002 → EXC-002 ✓
 
----
+AD-HOC TASKS:
+  {topic}: ANL-003 → PLN-003 → EXC-003 ✓
 
-## Step 5: Route
+VERIFICATION:
+  VRF-001: milestone-level verify ✓ (or "not yet run")
 
-Based on audit results:
+INTEGRATION:
+  Shared Interfaces:   {passed|N gaps}
+  Dependency Chains:   {passed|N gaps}
+  Data Contracts:      {passed|N gaps}
 
-### All checks passed (0 gaps):
-```
-AUDIT PASSED
-Next: Skill({ skill: "maestro-milestone-complete", args: "{milestone}" })
+VERDICT: PASS | FAIL
+====================================================
 ```
 
-### Gaps found:
-```
-AUDIT FOUND GAPS
-{for each gap}
-  [{severity}] {description}
-    Affected: Phase {N1}, Phase {N2}
-    Fix: {suggestion}
-{/for}
-
-Suggested actions:
-  - Critical/High gaps: Skill({ skill: "quality-debug" }) for each critical gap
-  - Medium/Low gaps: /workflow:plan --gaps {phase} (add fix tasks)
-  - Re-audit after fixes: /workflow:milestone-audit {milestone}
-```
+4. Route next step:
+   - PASS → suggest `/maestro-milestone-complete`
+   - FAIL → suggest specific fix actions

package/workflows/milestone-complete.md

@@ -1,6 +1,6 @@
 # Workflow: milestone-complete
 
-Archive completed milestone and prepare for next.
+Archive completed milestone, move artifacts to history, and prepare for next.
 
 ---
 
@@ -8,22 +8,22 @@ Archive completed milestone and prepare for next.
 
 1. Read `.workflow/state.json`:
    - Determine target milestone (from $ARGUMENTS or current_milestone)
+   - If no milestone: ERROR E001
 
 2. Check milestone audit status:
    - Read `.workflow/milestones/{milestone}/audit-report.md` if exists
-   - If no audit report exists:
-     - WARN: "No audit report found. Run `/workflow:milestone-audit` first."
+   - If no audit report:
+     - WARN: "No audit report found. Run `/maestro-milestone-audit` first."
      - Ask user: "Complete without audit?"
-     - If NO → exit with route to `/workflow:milestone-audit`
+     - If NO → exit
+   - If verdict is FAIL: ERROR E002
 
-3. Verify all phases are completed:
+3. Verify all artifacts completed:
    ```
-   For each phase in milestone:
-     Read phases/{NN}-{slug}/index.json
-     if status != "completed":
-       ERROR: "Phase {NN} ({title}) is not completed (status: {status})"
-       Route: /workflow:execute {NN} or /workflow:verify {NN}
-       EXIT
+   milestone_artifacts = state.json.artifacts.filter(a => a.milestone == target_milestone)
+   incomplete = milestone_artifacts.filter(a => a.status != "completed")
+   IF incomplete.length > 0:
+     ERROR E003: "Incomplete artifacts: {list ids and statuses}"
    ```
 
 ---
@@ -32,24 +32,21 @@ Archive completed milestone and prepare for next.
 
 1. Create archive directory:
    ```
-   mkdir -p .workflow/milestones/v{X.Y}/phases/
+   mkdir -p .workflow/milestones/{milestone}/artifacts/
    ```
 
 2. Snapshot roadmap:
    ```
-   cp .workflow/roadmap.md .workflow/milestones/v{X.Y}/roadmap-snapshot.md
+   cp .workflow/roadmap.md .workflow/milestones/{milestone}/roadmap-snapshot.md
    ```
 
-3. Archive phase directories:
+3. Archive scratch directories:
    ```
-   For each phase in milestone:
-     cp -r .workflow/phases/{NN}-{slug}/ .workflow/milestones/v{X.Y}/phases/{NN}-{slug}/
+   FOR each artifact IN milestone_artifacts:
+     IF directory exists at .workflow/{artifact.path}:
+       cp -r .workflow/{artifact.path} .workflow/milestones/{milestone}/artifacts/{basename}/
    ```
 
-4. Audit report:
-   - Report already exists at `.workflow/milestones/{milestone}/audit-report.md` (written by milestone-audit)
-   - No copy needed; verify file is present in archive directory
-
 ---
 
 ## Step 2.5: Load Existing Learnings
@@ -64,180 +61,116 @@ Check existing entries to avoid duplicates when appending in Step 3.
 
 ## Step 3: Extract Learnings
 
-1. For each phase in milestone, read `reflection-log.md` if exists:
+1. For each execute artifact, read `.summaries/` and `reflection-log.md` if exists:
    - Extract strategy adjustments
    - Extract patterns discovered
    - Extract pitfalls encountered
 
-2. Aggregate learnings and append to `.workflow/specs/learnings.md` under "## Entries", using spec-add entry format for each item:
+2. Aggregate learnings and append to `.workflow/specs/learnings.md`:
    ```
    For each strategy adjustment:
      ### [YYYY-MM-DD HH:mm] decision: {summary}
-
      {content}
      Milestone: {milestone} | Source: milestone-complete
 
-   For each pattern discovered:
+   For each pattern:
      ### [YYYY-MM-DD HH:mm] pattern: {summary}
-
      {content}
      Milestone: {milestone} | Source: milestone-complete
 
-   For each pitfall encountered:
+   For each pitfall:
      ### [YYYY-MM-DD HH:mm] bug: {summary}
-
      {content}
      Milestone: {milestone} | Source: milestone-complete
    ```
 
 ---
 
-## Step 3.5: Update project.md Context
-
-```
-Read .workflow/project.md
+## Step 4: Update State
 
-a. Append milestone summary to "## Context" section:
-   - Milestone version, completion date
-   - Key learnings summary (top 3 from Step 3 aggregated learnings)
-   - Significant strategy adjustments that affect future work
+1. Archive artifact entries to milestone_history:
+   ```json
+   {
+     "milestone_history": [
+       {
+         "id": "{milestone}",
+         "name": "{milestone_name}",
+         "status": "completed",
+         "completed_at": "{now}",
+         "archive_path": "milestones/{milestone}/",
+         "archived_artifacts": [ ...all milestone artifacts entries... ]
+       }
+     ]
+   }
+   ```
 
-   Format:
-     **Milestone {milestone} ({date})**: {1-2 sentence summary of what was accomplished
-     and key insights that inform future work.}
+2. Clear artifacts array (remove milestone-affiliated entries):
+   ```
+   state.json.artifacts = state.json.artifacts.filter(a => a.milestone != target_milestone)
+   ```
 
-b. Update "Last updated" footer timestamp
+3. Advance to next milestone:
+   ```
+   next_milestone = state.json.milestones.find(m => m.status == "pending")
+   IF next_milestone:
+     state.json.current_milestone = next_milestone.id
+     next_milestone.status = "active"
+   ELSE:
+     state.json.current_milestone = null
+     state.json.status = "completed"
+   ```
 
-Write updated project.md
-Display: "project.md: Context updated with milestone {milestone} summary"
-```
+4. Write state.json (atomic)
 
 ---
 
-## Step 4: Update State
+## Step 5: Clean Scratch
 
-1. Read existing `.workflow/state.json` to preserve accumulated values.
+Remove archived scratch directories:
+```
+FOR each artifact IN archived_artifacts:
+  IF directory exists at .workflow/{artifact.path}:
+    rm -rf .workflow/{artifact.path}
+```
 
-2. Determine next milestone from roadmap (read BEFORE any delete):
-   ```
-   a. Read .workflow/roadmap.md
-   b. Scan for all milestone headings (e.g. ## Milestone: vX.Y, ## v1.0, etc.)
-   c. Locate the current milestone heading in the list
-   d. next_milestone = the milestone heading immediately after current
-      (If no next milestone exists in roadmap, next_milestone = null)
-   e. If next_milestone is not null:
-        Scan for phases belonging to next_milestone
-        next_phase_count = count of phases in next milestone
-      Else:
-        next_phase_count = 0
-   ```
+---
 
-3. Calculate updated phases_summary (derived pending):
-   ```
-   new_phases_summary = {
-     "total": next_phase_count,
-     "completed": 0,
-     "in_progress": 0,
-     "pending": next_phase_count - 0 - 0  // total - completed - in_progress
-   }
-   ```
+## Step 6: Generate Summary
 
-4. Clean up completed phase directories:
-   - Remove `.workflow/phases/{NN}-{slug}/` for archived phases
-   - Keep `.workflow/phases/` directory (empty, ready for new milestone)
+Write `.workflow/milestones/{milestone}/summary.md`:
+```markdown
+# Milestone: {milestone} — {name}
 
-5. Remove stale roadmap:
-   - Delete `.workflow/roadmap.md` (already archived as `milestones/v{X.Y}/roadmap-snapshot.md`)
-   - This creates a clear "no roadmap" state that the maestro coordinator detects for next-milestone routing
+**Completed**: {date}
+**Artifacts**: {count} (analyze: {n}, plan: {n}, execute: {n}, verify: {n})
 
-6. Update milestone_history entry for completed milestone:
-   ```
-   FOR each entry IN existing_state.milestone_history:
-     IF entry.name == completed_milestone OR entry.slug == completed_milestone:
-       entry.status = "completed"
-       entry.completed_at = "{timestamp}"
-       entry.archive_path = ".workflow/milestones/{completed_milestone}/"
-       BREAK
-   ```
+## Key Outcomes
+{extracted from audit report + learnings}
 
-7. Record milestone transition in history:
-   ```
-   Append to state.transition_history[] (create array if absent):
-     {
-       "type": "milestone",
-       "from_phase": null,
-       "to_phase": null,
-       "milestone": completed_milestone,
-       "transitioned_at": "{timestamp}",
-       "trigger": "milestone-complete",
-       "force": was --force used (boolean),
-       "snapshot": {
-         "phases_completed": phases in this milestone,
-         "phases_total": existing_state.phases_summary.total,
-         "deferred_count": existing_state.accumulated_context.deferred.length,
-         "verification_status": "completed",
-         "learnings_count": retrospective learnings count (from Step 3)
-       }
-     }
-   ```
+## Learnings
+{top patterns and pitfalls}
 
-8. Write updated `.workflow/state.json`:
-   ```json
-   // If next_milestone exists:
-   {
-     "current_milestone": "{next_milestone}",
-     "current_phase": 1,
-     "status": "idle",
-     "phases_summary": new_phases_summary,
-     "accumulated_context": existing_state.accumulated_context,
-     "milestone_history": existing_state.milestone_history,
-     "last_updated": "{timestamp}"
-   }
+## Next Milestone
+{next milestone name and first phase, or "Project complete"}
+```
 
-   // If next_milestone is null (project complete):
-   {
-     "current_milestone": "{completed_milestone}",
-     "current_phase": null,
-     "status": "completed",
-     "phases_summary": new_phases_summary,
-     "accumulated_context": existing_state.accumulated_context,
-     "milestone_history": existing_state.milestone_history,
-     "last_updated": "{timestamp}"
-   }
-   ```
-   Preserve `accumulated_context` and `milestone_history` -- decisions, deferred items, and milestone history carry forward.
+Update `.workflow/project.md` Context section with milestone summary.
 
 ---
 
-## Step 5: Commit and Route
-
-1. If git repo: commit with message `"chore: complete milestone {milestone}"`
+## Step 7: Report
 
-2. Display completion summary:
-   ```
-   ====================================================
-     MILESTONE COMPLETED: {milestone}
-   ====================================================
-
-   Archived:
-     - {N} phases archived to .workflow/milestones/v{X.Y}/
-     - Roadmap snapshot saved
-     - Audit report archived
-     - {M} learnings extracted to specs/learnings.md
-
-   State reset:
-     - Current milestone: {next_milestone or completed_milestone}
-     - Current phase: {1 or null}
-     - Status: {idle or completed}
-
-   ====================================================
-   ```
-
-3. Route next steps:
-   - If next_milestone exists:
-     - Ask user: "Start planning next milestone?"
-       - YES → Suggest Skill({ skill: "maestro", args: "continue" }) — coordinator auto-detects post-milestone state, loads deferred items from accumulated_context, and routes to roadmap creation
-       - NO → "Project is idle." Suggest Skill({ skill: "manage-status" }) to check state anytime.
-   - If next_milestone is null (project complete):
-     - Display: "All milestones completed. Project is done."
-     - Suggest Skill({ skill: "manage-status" }) to review final state.
+```
+=== MILESTONE COMPLETE ===
+Milestone: {milestone} ({name})
+Artifacts: {count} archived
+Learnings: {learnings_count} extracted
+
+Archive: .workflow/milestones/{milestone}/
+Next:    {next_milestone or "Project complete"}
+
+Next steps:
+  /maestro-milestone-release    -- Cut a release
+  /maestro-analyze              -- Start next milestone
+  /manage-status                -- View project state
+```