festifun/plan/README.md

Festival 4D — Parallel Execution Plan

Read ../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.

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 worktrees — 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
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).

Suggested per-agent kickoff prompts

• Foundation: "Read OPUS_BUILD_INSTRUCTIONS.md and plan/00-foundation.md. Execute on branch foundation, merge to main when acceptance passes."
• Lane X: "Read OPUS_BUILD_INSTRUCTIONS.md, plan/README.md, and plan/lane-X-.md. Work only on branch lane/x-..., only in your owned files. Merge to main when acceptance passes."*
• Integration: "Read OPUS_BUILD_INSTRUCTIONS.md and plan/10-integration.md. All lanes are merged; execute on branch integration."