kata-audit-milestone

What this skill does

<objective>
Verify milestone achieved its definition of done. Check requirements coverage, cross-phase integration, and end-to-end flows.

**This command IS the orchestrator.** Reads existing VERIFICATION.md files (phases already verified during phase-execute), aggregates tech debt and deferred gaps, then spawns integration checker for cross-phase wiring.
</objective>

<execution_context>

<!-- Spawns kata-integration-checker agent which has all audit expertise baked in -->

</execution_context>

<context>
Version: $ARGUMENTS (optional — defaults to current milestone)

**Original Intent:**
@.planning/PROJECT.md
@.planning/REQUIREMENTS.md

**Planned Work:**
@.planning/ROADMAP.md
@.planning/config.json (if exists)

**Completed Work:**
Glob: .planning/phases/{active,pending,completed}/_/_-SUMMARY.md
Glob: .planning/phases/{active,pending,completed}/_/_-VERIFICATION.md
(Also check flat: .planning/phases/[0-9]_/_-SUMMARY.md for backward compatibility)
</context>

<process>

## 0. Resolve Model Profile

Read model profile for agent spawning:

```bash
MODEL_PROFILE=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-audit-milestone/scripts/kata-lib.cjs" read-config "model_profile" "balanced")
```

Default to "balanced" if not set.

**Model lookup table:**

| Agent                    | quality | balanced | budget |
| ------------------------ | ------- | -------- | ------ |
| kata-integration-checker | sonnet  | sonnet   | haiku  |

Store resolved model for use in Task call below.

## 0.5. Pre-flight: Check roadmap format (auto-migration)

If ROADMAP.md exists, check format and auto-migrate if old:

```bash
if [ -f .planning/ROADMAP.md ]; then
  node "${CLAUDE_PLUGIN_ROOT}/skills/kata-audit-milestone/scripts/kata-lib.cjs" check-roadmap 2>/dev/null
  FORMAT_EXIT=$?

  if [ $FORMAT_EXIT -eq 1 ]; then
    echo "Old roadmap format detected. Running auto-migration..."
  fi
fi
```

**If exit code 1 (old format):**

Invoke kata-doctor in auto mode:

```
Skill("kata-doctor", "--auto")
```

Continue after migration completes.

**If exit code 0 or 2:** Continue silently.

## 1. Determine Milestone Scope

```bash
# Scan all phase directories across states
ALL_PHASE_DIRS=""
for state in active pending completed; do
  [ -d ".planning/phases/${state}" ] && ALL_PHASE_DIRS="${ALL_PHASE_DIRS} $(find .planning/phases/${state} -maxdepth 1 -type d -not -name "${state}" 2>/dev/null)"
done
# Fallback: include flat directories (backward compatibility)
FLAT_DIRS=$(find .planning/phases -maxdepth 1 -type d -name "[0-9]*" 2>/dev/null)
[ -n "$FLAT_DIRS" ] && ALL_PHASE_DIRS="${ALL_PHASE_DIRS} ${FLAT_DIRS}"
echo "$ALL_PHASE_DIRS" | tr ' ' '\n' | sort -V
```

- Parse version from arguments or detect current from ROADMAP.md
- Identify all phase directories in scope (across active/pending/completed subdirectories)
- Extract milestone definition of done from ROADMAP.md
- Extract requirements mapped to this milestone from REQUIREMENTS.md

## 2. Read All Phase Verifications

For each phase directory, read the VERIFICATION.md:

```bash
# Read VERIFICATION.md from each phase directory found in step 1
for phase_dir in $ALL_PHASE_DIRS; do
  [ -d "$phase_dir" ] || continue
  cat "${phase_dir}"*-VERIFICATION.md 2>/dev/null
done
```

From each VERIFICATION.md, extract:

- **Status:** passed | gaps_found
- **Critical gaps:** (if any — these are blockers)
- **Non-critical gaps:** tech debt, deferred items, warnings
- **Anti-patterns found:** TODOs, stubs, placeholders
- **Requirements coverage:** which requirements satisfied/blocked

If a phase is missing VERIFICATION.md, flag it as "unverified phase" — this is a blocker.

## 3. Spawn Integration Checker

Read the integration checker instructions:

```
integration_checker_instructions_content = Read("skills/kata-audit-milestone/references/integration-checker-instructions.md")
```

With phase context collected:

```
Task(
  prompt="<agent-instructions>
{integration_checker_instructions_content}
</agent-instructions>

Check cross-phase integration and E2E flows.

Phases: {phase_dirs}
Phase exports: {from SUMMARYs}
API routes: {routes created}

Verify cross-phase wiring and E2E user flows.",
  subagent_type="general-purpose",
  model="{integration_checker_model}"
)
```

## 4. Collect Results

Combine:

- Phase-level gaps and tech debt (from step 2)
- Integration checker's report (wiring gaps, broken flows)

## 5. Check Requirements Coverage

For each requirement in REQUIREMENTS.md mapped to this milestone:

- Find owning phase
- Check phase verification status
- Determine: satisfied | partial | unsatisfied

## 6. Aggregate into v{version}-MILESTONE-AUDIT.md

Create `.planning/v{version}-v{version}-MILESTONE-AUDIT.md` with:

```yaml
---
milestone: { version }
audited: { timestamp }
status: passed | gaps_found | tech_debt
scores:
  requirements: N/M
  phases: N/M
  integration: N/M
  flows: N/M
gaps: # Critical blockers
  requirements: [...]
  integration: [...]
  flows: [...]
tech_debt: # Non-critical, deferred
  - phase: 01-auth
    items:
      - "TODO: add rate limiting"
      - "Warning: no password strength validation"
  - phase: 03-dashboard
    items:
      - "Deferred: mobile responsive layout"
---
```

Plus full markdown report with tables for requirements, phases, integration, tech debt.

**Status values:**

- `passed` — all requirements met, no critical gaps, minimal tech debt
- `gaps_found` — critical blockers exist
- `tech_debt` — no blockers but accumulated deferred items need review

## 7. Present Results

Route by status (see `<offer_next>`).

## 8. Offer UAT Walkthrough

Use AskUserQuestion:

- header: "UAT Walkthrough"
- question: "Would you like a complete walk-through UAT session?"
- options:
  - "Full walkthrough" — walk through all user-observable deliverables
  - "Integration only" — focus on cross-phase flows
  - "Skip" — done with audit

**If Skip:** Proceed to `<offer_next>`.

**If walkthrough chosen:**

1. Read all phase SUMMARY.md files in milestone scope
2. Extract user-observable deliverables (features, behaviors, UI changes)
3. Classify each deliverable as **user-facing** or **internal**:
   - **User-facing:** Things end-users interact with through the product's normal interface. For a web app: pages, forms, buttons, API responses. For a CLI tool: commands, flags, output. For a library: public API, configuration options. The test is: would the end-user encounter this during normal use?
   - **Internal:** Everything else. Scripts, helper functions, reference docs, test files, build artifacts, refactors, and implementation modules are INTERNAL even if they can be invoked directly from a terminal. If the end-user never runs it, sees it, or interacts with it, it's internal.
4. Design demo scenarios **organized by user journey, not by phase or technical component**:
   - Map the order in which an end-user naturally encounters these features (e.g., project setup → configuration → daily use → completion)
   - Each batch follows one segment of that journey, not one phase or one script
   - "Full walkthrough": walk through the complete user journey, then summarize internal changes
   - "Integration only": demo cross-phase flows only
5. Create `.planning/v{version}-UAT.md` adapted from UAT template format:
   - `milestone: {version}` instead of `phase:`
   - `source:` lists all phase SUMMARY.md files

6. **Set up the environment, then hand off to the user**

   <uat_rules>

   **CRITICAL: The user performs UAT, not you.**

   UAT verifies the milestone's deliverables work from the end-user's perspective. The user interacts with what was built (their app, their CLI, their API). You prepare the environment and give instructions. You MUST NOT run the demo yourself and report results back.

   **What you do:**
   - Start dev servers, seed databases, install dependencies — whatever setup the user needs
   - Run internal verification yourself (tests, build checks) and summarize results
   - Write clear step-by-step instructions telling the user wha