---
name: milestone-promote
description: >
  Safely promote from one milestone to the next. Verifies all deliverables
  are complete, runs final validation, updates plan.md and prompt.md,
  captures a review packet, performs milestone-end doc sync, and records the milestone completion. Use when
  all deliverables in the current milestone are checked off.
---

# Milestone Promote — Safe Milestone Transition

Transition from the current milestone to the next one with full verification.

## When to use

- All deliverables in the current milestone are checked off
- All verification commands pass
- You're ready to move to the next milestone

## Pre-flight Checks (must ALL pass before promoting)

### 1. Verify all deliverables are complete

Read `docs/plan.md` and confirm every `- [ ]` under the current milestone
is now `- [x]`. If any remain unchecked, do NOT promote — complete them first.

### 2. Run all verification commands

Execute every verification command listed in the current milestone's
**Verification** section. All must pass.

### 3. Run quality gates

Run the primary quality gate command from `AGENTS.md` §5.

Must pass with zero failures.

### 4. Run doc validation

Run the primary doc validation command from `AGENTS.md` §5.

Must pass with zero errors.

### 5. Run quality audit

Run `$quality-audit` sub-skill to capture the final quality score
for this milestone.

### 6. Capture review packet

Before promotion, build a stable review packet directly in `docs/documentation.md`
so a second agent or human reviewer can audit the scoped diff, validation
evidence, and open risks without reconstructing context ad hoc.

## Promotion Steps (execute in order)

### 7. Update plan.md

- Move the **→** marker from the current milestone to the next one
- Update the current milestone status from "→ in progress" to "✅ done"
- Record the quality score in the Quality Score History table
- Update the Operations Cadence table with milestone-promote and quality-audit due-state
- Check off all deliverables: `- [ ]` → `- [x]`

### 8. Update prompt.md

Replace the entire content of `docs/prompt.md` with the next milestone's
contract. Copy the scope, deliverables, verification commands, and
done-when criteria from the next milestone in `docs/plan.md`.

### 9. Record milestone completion

Add to `docs/documentation.md`:
- Refresh `## Current State` for the next milestone
- Update `## Decision Log` with any milestone-level decisions future sessions must remember

```
## Milestone Complete: <milestone_id> — <date>
- **Goal**: <milestone goal>
- **Deliverables completed**: <count>
- **Quality score**: <score>/100
- **Duration**: <number of iterations>
- **Key decisions made**: <list>
- **Compaction checkpoint**: <copy from plan.md>
```

### 10. Run doc sync

Detect and fix any documentation that drifted during the milestone:
- rerun the primary doc validation command
- refresh any stale module map, milestone state, or execution contract wording
- update `docs/documentation.md` with a `Doc Sync` entry if non-trivial fixes were required

### 11. Archive if needed

If `docs/documentation.md` has more than 20 entries:
- Move entries older than the last 10 to `docs/archive/documentation-YYYY-MM.md`
- Keep only the most recent entries in the main file

### 12. Next-milestone preflight

Before starting work on the next milestone, verify that its assumptions still hold:

- **Prerequisites**: are the dependencies from the previous milestone actually met?
- **Scope**: has anything been discovered during the completed milestone that changes
  the next milestone's scope or approach?
- **New blockers**: are there any newly discovered blockers, missing tools, or
  missing permissions that need resolution before the next milestone?
- **Harness adequacy**: does the harness (docs, scripts, constraints) need any
  upgrades before the next milestone? (Check the harness health from the latest
  quality audit.)

If any prerequisite is not met or a new blocker exists:
- Record the issue in `docs/documentation.md` Decision Log
- If the blocker can be resolved by the agent, add it as a pre-work item
- If the blocker requires human input, escalate per the Uncertainty Protocol
- If the next milestone's scope needs adjustment, update `docs/plan.md` and
  record the reason

## Post-promotion Verification

After all steps:
Run the primary doc validation command again.

Confirm that:
- `docs/prompt.md` now references the next milestone
- `docs/plan.md` → marker points to the next milestone
- Quality Score History has the new entry
- `docs/documentation.md` has the completion record
- Next-milestone preflight passed (or issues are recorded)

## Edge Cases

### Last milestone completed
If there are no more milestones:
1. Record the final milestone completion
2. Update `docs/prompt.md` to say "All milestones complete"
3. Run a final `$quality-audit`
4. Notify the human: "All planned milestones are complete. Quality score: X/100.
   Ready for new goals or maintenance mode."

### Quality score below threshold
If the quality audit reveals a score below 70:
1. Still promote the milestone (deliverables are done)
2. But add a mandatory debt cleanup deliverable to the NEXT milestone
3. Record this in `docs/plan.md` as an additional deliverable
