# Milestone Instructions

Each `MXX-*.md` file in this directory is a self-contained prompt for a **fresh Claude Code session running Sonnet 4.6**. One agent process executes one milestone end-to-end, then stops.

## Why fresh agents per milestone

- Long agent runs accumulate context drift. By M8 a long-running agent would be making decisions based on a fuzzy memory of M2.
- A fresh agent reading a focused prompt makes sharper decisions.
- Hand-offs become explicit and reviewable: each milestone produces a commit and a `PROGRESS.md` entry the next agent reads.
- If a milestone goes wrong, you re-run only that milestone. Nothing earlier is contaminated.

## Setup (do this once, before M01)

1. Place the master spec at the repo root as `SPEC.md`. Every milestone file references it by section number.
2. Initialize git, create an empty `PROGRESS.md` at the repo root with a single header `# Build Progress`.
3. Confirm the agent has access to: filesystem, shell, Docker, composer, npm, php.

## Running a milestone

For each `MXX-*.md` file in order:

1. Open a new Claude Code session.
2. Paste (or attach) the milestone file as the initial user message.
3. Let the agent work. It will read `SPEC.md`, run verification commands, do the work, run acceptance commands, commit, and stop.
4. Review the commit and the `PROGRESS.md` entry.
5. If acceptance passes, move to the next file. If not, see "When a milestone fails."

## Structure of each milestone file

```
# MXX — Title
## Mission                 (what this milestone accomplishes, in 2-3 sentences)
## Before you start        (prerequisites, verification commands)
## Required reading        (specific SPEC.md sections)
## Tasks                   (concrete checklist, in order)
## Implementation notes    (patterns, gotchas, code shapes)
## Out of scope            (DO NOT — explicit guardrails against scope creep)
## Acceptance              (exact commands; all must pass before commit)
## Handoff                 (commit message format, PROGRESS.md template)
```

## When a milestone fails

If acceptance criteria don't pass:
1. **Do not** start the next milestone. Out-of-order work is harder to fix than a stuck milestone.
2. Read the agent's notes in chat and any partial `PROGRESS.md` updates.
3. Either: (a) start a new fresh agent with the same milestone file plus a brief note about what went wrong, or (b) hand-fix and commit, then update `PROGRESS.md` manually.
4. Only proceed when the current milestone's acceptance commands all pass.

## Order

| #   | File                                       | Builds on   |
|-----|--------------------------------------------|-------------|
| M01 | `M01-monorepo-skeleton.md`                 | —           |
| M02 | `M02-database-migrations.md`               | M01         |
| M03 | `M03-api-auth-foundations.md`              | M02         |
| M04 | `M04-token-system-and-ingest.md`           | M03         |
| M05 | `M05-reputation-engine-and-jobs.md`        | M04         |
| M06 | `M06-manual-blocks-allowlist.md`           | M05         |
| M07 | `M07-policies-and-distribution.md`         | M06         |
| M08 | `M08-ui-scaffold-and-auth.md`              | M07         |
| M09 | `M09-ui-ips-history-dashboard.md`          | M08         |
| M10 | `M10-ui-admin-crud-pages.md`               | M09         |
| M11 | `M11-enrichment.md`                        | M07         |
| M12 | `M12-audit-and-settings.md`                | M10, M11    |
| M13 | `M13-polish-openapi-docs.md`               | M12         |
| M14 | `M14-hardening.md`                         | M13         |

M11 (enrichment) only structurally depends on M07; it can be run in parallel with M08–M10 if you have multiple agents available, but the simpler thing is sequential execution.

## Common rules — every milestone obeys these

These are repeated in each file but worth stating once here:

- **Read `SPEC.md` before doing anything.** It is the source of truth. The milestone file is a focused execution plan, not a full design document.
- **Stay in scope.** Each milestone has explicit "out of scope" items. If you encounter something that feels like it should be done now but isn't listed in tasks, it belongs to a later milestone or is intentionally deferred.
- **Stop and ask** if a requirement is ambiguous, contradicts `SPEC.md`, or appears wrong once you're in the code. Do not paper over it. Stopping mid-milestone is correct behavior in that case.
- **No new dependencies** without justifying them in `PROGRESS.md`. The `SPEC.md` tech stack is non-negotiable.
- **Tests must pass** before commit. Linters too. PHPStan level 8 on `src/` and php-cs-fixer.
- **One commit per milestone**, conventional-commit style. Include the milestone number.
- **Update `PROGRESS.md`** at the end with: what was built, what was deferred, anything the next milestone should know.