# API Watchdog Milestones

## Purpose

This document is the execution tracker for the API watchdog line.

It fixes:

1. milestone order
2. owner boundary
3. parallel work split
4. merge order
5. done definition

## Mainline Rule

One person owns mainline closure:

1. API schema
2. planner
3. runner skeleton
4. final integration

Parallel contributors should avoid changing the same mainline files unless
explicitly reassigned.

## Milestone Overview

| Milestone | Goal | Owner | Parallelizable | Status |
| --- | --- | --- | --- | --- |
| `M1-contract` | freeze API contract and planning boundary | mainline | low | `done` |
| `M2-ready-cases` | fill ready-scene API specs | case track | high | `done` |
| `M3-need-data` | prepare seed/data gaps for blocked API scenes | data tracks | high | `in-progress` |
| `M4-planner` | dry-run planner and schema validation for API scenes | mainline | low | `done` |
| `M5-execution` | minimal executable API runner for first-wave P0 | mainline | medium | `pending` |
| `M6-expansion` | unlock quote/security cases after data closure | mixed | medium | `pending` |

## Milestone Details

### `M1-contract`

Goal:

1. freeze API case file shape
2. freeze API scene file shape
3. freeze API report shape
4. define artifact contract

Write scope:

1. `watchdog/api/**`
2. `watchdog/schemas/**`
3. `docs/api-watchdog-milestones.md`
4. `docs/story-flow-api-watchdog-plan.md`

Done when:

1. schema files exist
2. sample files validate against schema
3. planner can enumerate API scenes and cases

### `M2-ready-cases`

Goal:

Fill `ready` scenes without waiting for new data.

Target first:

1. `oauth-compatibility-api`
2. `lead-convert-api`
3. `opportunity-products-api`
4. `opportunity-stage-progress-api`
5. `campaign-add-members-api`

Write scope:

1. `watchdog/api/cases/**`

Do not change:

1. `watchdog/runner/**`
2. `watchdog/schemas/**`
3. shared seed infrastructure

Done when:

1. each case has `*.manual.md`
2. each case has `*.api.yaml`
3. all files validate under planner dry-run

### `M3-need-data`

Goal:

Prepare the missing data required by:

1. `quote-create-api`
2. `approval-submit-api`
3. `security-effective-access-api`

Split into two tracks:

1. `M3A-quote-approval-data`
2. `M3B-security-visibility-data`

Write scope:

1. `watchdog/seeds/**`
2. data-related docs

Do not change:

1. runner mainline
2. API schema
3. unrelated story definitions

Done when:

1. new seed/bucket files exist
2. relationship chain is documented
3. minimal validation queries are provided

### `M4-planner`

Goal:

Add API dry-run planning support:

1. inventory discovery
2. schema validation
3. single scene selection
4. single case selection
5. run plan output

Write scope:

1. `watchdog/api/**`
2. `watchdog/runner/**`
3. `watchdog/schemas/**`

Done when:

1. `--dry-run` can enumerate API scenes
2. invalid case files fail closed
3. output contains scene/case/seed summary

### `M5-execution`

Goal:

Add minimal executable API runner for first-wave P0:

1. auth
2. request execution
3. query execution
4. response assertions
5. report output

Target execution set:

1. `oauth-compatibility-api`
2. `lead-create-persist-api`
3. `lead-convert-api`

Done when:

1. one full local/API run succeeds
2. report output is machine-readable
3. failure location is explicit

### `M6-expansion`

Goal:

Promote `needs-data` scenes into executable state after data closure.

Target:

1. `quote-create-api`
2. `approval-submit-api`
3. `security-effective-access-api`

Done when:

1. data gaps are closed
2. cases validate
3. planner marks them runnable

## Parallel Ownership

### Mainline

Owner:

1. main execution track

Write scope:

1. `watchdog/api/**`
2. `watchdog/schemas/**`
3. `watchdog/runner/**`

### Data Track A

Owner:

1. quote + approval data

Write scope:

1. `watchdog/seeds/**`
2. `docs/api-watchdog-need-data-checklist.md`
3. `docs/story-test-data-catalog.md`
4. `docs/story-test-data-plan.md`

### Data Track B

Owner:

1. security + auth contrast data

Write scope:

1. `watchdog/seeds/**`
2. `docs/api-watchdog-need-data-checklist.md`
3. `docs/story-test-data-catalog.md`
4. `docs/story-test-data-plan.md`

### Case Track

Owner:

1. ready-scene API case specs

Write scope:

1. `watchdog/api/cases/**`

## Merge Order

1. `M1-contract`
2. `M2-ready-cases`
3. `M3A-quote-approval-data`
4. `M3B-security-visibility-data`
5. `M4-planner`
6. `M5-execution`
7. `M6-expansion`

## Coordination Rule

When parallel tracks are active:

1. data tracks do not edit runner
2. case track does not edit shared seed infrastructure
3. mainline does not silently rewrite data contracts owned by data tracks
4. each track reports back with changed files and remaining blockers