# Workflow: milestone-audit

Cross-phase integration audit for milestone completion. Based on artifact registry.

---

## Step 1: Load Milestone Context

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. **Standard milestone** (`type != "adhoc"`):
   - Parse `.workflow/roadmap.md` to identify all phases belonging to this milestone

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

**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"

**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.

---

## Step 3: Ad-hoc Completeness Check

Check all ad-hoc artifacts (`scope == "adhoc"`) for this milestone are completed. WARN if any incomplete (list ids).

---

## Step 4: Execution Completeness Check

For each execute artifact, read `{path}/.task/TASK-*.json` and verify all tasks are completed or skipped. WARN if any tasks remain incomplete: "Plan {plan_dir}: {N} tasks not completed"

---

## Step 5: Integration Check

Spawn `workflow-integration-checker` agent:

```
Agent({
  subagent_type: "workflow-integration-checker",
  prompt: "
    Audit cross-phase integration for milestone {milestone}.

    Artifacts to audit:
    {for each execute artifact: path, phase, scope}

    Check:
    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?
    5. CONFIGURATION -- Are shared configs compatible?
    6. ERROR HANDLING -- Do error flows work across boundaries?

    For each check, report:
    - Status: passed | gap_found
    - 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
    Return: summary with gap count and severity breakdown.
  ",
  run_in_background: false
})
```

---

## Step 5.5: CLI Supplementary Integration Scan (optional)

**Purpose:** Use external CLI tool for broad cross-phase dependency and API consistency checks that complement the agent-based integration checker.

**Skip if** no enabled CLI tools or milestone has only 1 phase.

```
IF no CLI tools enabled OR phases.length <= 1: skip to Step 6

# Collect all modified files across execute artifacts
all_execute_paths = execute_artifacts.map(a => a.path)

Bash({
  command: 'maestro delegate "PURPOSE: Cross-phase integration scan for milestone completion
TASK: Check for import/export consistency across phase boundaries | Detect shared type/interface mismatches | Identify configuration key conflicts between phases
MODE: analysis
CONTEXT: @${all_execute_paths as glob patterns}
EXPECTED: JSON { import_issues: [{ file, import_path, issue }], type_mismatches: [{ type_name, definitions: [{ file, shape }] }], config_conflicts: [{ key, values: [{ file, value }] }] }
CONSTRAINTS: Only check cross-phase boundaries | Ignore intra-phase issues
" --role analyze --mode analysis',
  run_in_background: true
})
```

**On callback:** Parse result, append to integration checker findings. Critical items surface in Step 6 verdict.

---

## Step 6: Audit Report & Verdict

1. Read the audit report generated by the integration checker

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} ({milestone_name})
  ARTIFACTS: {total_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 ✓

VERIFICATION:
  VRF-001: milestone-level verify ✓ (or "not yet run")

INTEGRATION:
  Shared Interfaces:   {passed|N gaps}
  Dependency Chains:   {passed|N gaps}
  Data Contracts:      {passed|N gaps}

VERDICT: PASS | FAIL
====================================================
```

4. Route next step:
   - PASS → suggest `/maestro-milestone-complete`
   - FAIL → suggest specific fix actions
