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.

Current phase: 5 (M10–M17) — spec and organization in 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 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
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."