69 lines
6.4 KiB
Markdown
69 lines
6.4 KiB
Markdown
# 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.
|
||
|
||
## 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."*
|