# Festival 4D — Parallel Execution Plan

**Read [`../OPUS_BUILD_INSTRUCTIONS.md`](../OPUS_BUILD_INSTRUCTIONS.md) first — it is the canonical spec** (architecture, repo layout, data model, milestone details M0–M9, pitfalls). This directory only organizes *who builds what, in what order, without colliding*. Lane briefs reference spec milestones by number; they do not restate them.

> **Current phase: 5** (M10–M17) — spec and organization in [`20-phase5.md`](20-phase5.md), lane
> briefs `lane-E/F/G-*.md`. Phases 1–4 below are complete (v0.1.0 + polish); their protocol
> sections (git, status, directives loop, evidence discipline) remain the standing rules.

## Phase map

```
Phase 1 (serial, ONE agent)      Phase 2 (parallel, one agent per lane)      Phase 3 (serial, ONE agent)
┌──────────────────────┐         ┌ lane/a-media ──── M1 ────────────┐        ┌─────────────────────────┐
│ 00-foundation        │         ├ lane/b-recon ──── M2 + geometry ─┤        │ 10-integration          │
│ M0 + M3 + contracts  │──merge──┼ lane/c-viewer ─── M4, M5, M6 ────┼─merge──│ M8 + M9 + README        │
│ branch: foundation   │         └ lane/d-events ─── M7 ────────────┘        │ branch: integration     │
└──────────────────────┘         (independent — merge in any order)          └─────────────────────────┘
```

- Phase 2 lanes depend **only** on foundation, never on each other. Every lane develops and verifies against the synthetic fixture (spec M0).
- Lanes A/B/D are backend; lane C is frontend-only. All four can run simultaneously.

## Git protocol

- Remote: `origin` (already configured). Base branch: `main`.
- Foundation merges to `main` first. Each lane then branches from `main` (`lane/a-media`, `lane/b-recon`, `lane/c-viewer`, `lane/d-events`), commits frequently, and merges back to `main` when its acceptance criteria pass (fast-forward or merge commit; no rebase games needed).
- Integration branches from `main` only after **all four** lanes are merged.
- Run parallel agents in **separate clones or `git worktree`s** — one working directory per lane.

## File ownership (the no-collision rule)

Foundation scaffolds *every* file listed in the spec's repo layout, with lane-owned modules as working stubs (functions exist, raise `NotImplementedError` or return fixture data; CLI subcommands and API endpoints are pre-registered and dispatch into those stubs). After foundation, each lane edits **only** the files it owns:

| Owner | Files |
|---|---|
| Lane A | `backend/festival4d/ingest.py`, `audio_sync.py`, `backend/tests/test_ingest.py`, `test_audio_sync.py` |
| Lane B | `backend/festival4d/frames.py`, `sfm.py`, `geometry.py`, `backend/tests/test_sfm.py`, `test_geometry.py` |
| Lane C | everything under `frontend/` |
| Lane D | `backend/festival4d/events_ai.py`, `backend/tests/test_events_ai.py` |
| Every agent | its own `plan/status/<lane>.md` (and only its own) |
| **Coordinator only** | `plan/DIRECTIVES.md` — agents read, never write |
| **Frozen after foundation** | `db.py` (schema), `api.py` (routes + response shapes), `cli.py`, `config.py`, `synthetic.py`, `pyproject.toml` |

If a lane believes a frozen file must change, it does **not** edit it — it writes the needed change into `plan/CHANGE_REQUESTS.md` (create if absent) with rationale, and works around it locally. The integration agent adjudicates. Adding a *new* file inside your ownership area is always fine; adding a dependency requires a change request.

## Contracts (frozen at foundation merge — every lane relies on these)

1. **Timebase:** `t_video = (t_global − offset_ms/1000) · (1 + drift_ppm·1e−6)`; reference video has offset 0. (Spec §2.)
2. **DB schema** exactly as spec §2.
3. **API routes and JSON shapes** exactly as spec M3 — foundation implements them fully against synthetic data, so lane C treats the API as done.
4. **Pose convention:** COLMAP world→camera quaternion `[w,x,y,z]` + translation, plus pinhole `fx,fy,cx,cy`, as stored/served. The COLMAP→Three.js conversion (spec M5) exists in foundation as `geometry.py::colmap_to_threejs()` **with a passing unit test** and a mirrored JS helper in `frontend/src/lib/pose.js` — lanes B and C consume, never reimplement.
5. **Classifier contract:** `MomentClassification` Pydantic model + `MomentClassifier` protocol as spec M7.
6. **Synthetic fixture** (spec M0) is the universal test bed; its ground-truth JSONs are part of the contract.

## Definition of done (every lane)

- Spec acceptance criteria for the lane's milestones pass.
- `pytest` green (backend lanes) / app runs against synthetic data with no console errors (lane C).
- No edits outside owned files; no new deps without a change request.
- Merged to `main` with the synthetic end-to-end still working (`python -m festival4d synthetic && ... serve` + frontend loads).

## Coordination loop (status + directives)

- **Run order lives in `plan/DIRECTIVES.md`** (coordinator-written, round-numbered). Every agent reads the latest round at session start and after each milestone: `git fetch origin && git show origin/main:plan/DIRECTIVES.md`. Newest round wins over older rounds and lane briefs.
- **Every agent maintains `plan/status/<lane>.md`** per `plan/status/TEMPLATE.md` — updated and pushed at session start, each milestone pass (with evidence), each blocker (immediately), and before merge.
- **Review cadence:** between rounds the coordinator fetches all branches, reads every status file, appends a new round to DIRECTIVES.md on `main`, and pushes. Agents obey the new round on their next read.

## Suggested per-agent kickoff prompts

- Foundation: *"Clone ssh://git@100.71.119.27:222/monster/festifun.git. Read OPUS_BUILD_INSTRUCTIONS.md, plan/00-foundation.md, and the latest round of plan/DIRECTIVES.md. Execute on branch `foundation`; maintain plan/status/foundation.md per plan/status/TEMPLATE.md; merge to main when acceptance passes."*
- Lane X: *"Clone ssh://git@100.71.119.27:222/monster/festifun.git. Read OPUS_BUILD_INSTRUCTIONS.md, plan/README.md, plan/lane-X-*.md, and the latest round of plan/DIRECTIVES.md. Work only on branch `lane/x-...`, only in your owned files; maintain plan/status/lane-X.md per the template; re-read DIRECTIVES.md after each milestone; merge to main when acceptance passes."*
- Integration: *"Clone the repo. Read OPUS_BUILD_INSTRUCTIONS.md, plan/10-integration.md, all of plan/status/, and the latest DIRECTIVES round. All lanes are merged; execute on branch `integration`; maintain plan/status/integration.md."*