festifun/plan/DIRECTIVES.md

Coordinator Directives

Written only by the coordinator (the human's planning session). Agents: read the latest round at session start and after every milestone via git fetch origin && git show origin/main:plan/DIRECTIVES.md. The newest round addressed to your lane overrides older rounds and, where in conflict, your lane brief. Never edit this file.

---

Round 2 — 2026-07-16 — Integration complete; v0.1.0 shipped

Integration merged to main (e5d6b2c) and tagged v0.1.0. M8 (annotation→3D correction + triangulation) and M9 (keyframed camera paths) are done; README rewritten for v0.1.0. Both change requests adjudicated and applied (CR-1, CR-2 — additive only; timebase/schema-columns/ pose/API shapes otherwise unchanged).

Verification (coordinator-run on merged tree): 101 backend tests pass (up from the 96 floor); two-view stage-corner recovery err 0.00000 (< 0.2); frontend build clean; live in-browser M8 triangulation (gap 0.21) and M9 path (camera lands exactly on keyframe at t); M4 sync ~16 ms via deterministic pump. Worktrees removed, debris stash dropped, frontend/dist gitignored.

One open item for the human (not code-blocking): the automated browser pane runs document.hidden=true, which throttles requestAnimationFrame, so continuous multi-cam playback sync could only be verified deterministically, not by eye. Open the app in a normal focused browser window once (python -m festival4d serve + cd frontend && npm run dev) and confirm the top-right sync panel stays green (<50 ms) during continuous playback.

Next: the pipeline is ready for real footage — drop 2–4 overlapping concert clips into data/raw/ and run ingest → sync → reconstruct → events → serve (see README).

Round 1 — 2026-07-16 — All lanes merged & verified; integration begins

Coordinator review result: foundation + all four lanes are merged to main (merge commits e28dc78 A, 2cad2f7 B, 9d17b47 C; D fast-forwarded earlier at 5c2d7c6). Independently verified on the merged tree: 96 backend tests pass, synthetic ingest → sync recovers ground-truth offsets exactly (+0 / +1370 / −842 ms, drift 0), events finds 3 candidates and degrades gracefully unconfigured, frontend production build clean. Excellent evidence discipline across all lanes — keep it.

Directives:

1. Integration phase starts now — one agent, branch integration from main, per plan/10-integration.md. Maintain plan/status/integration.md.
2. CR-1 (lane D, test_api.py stub assertion): APPROVED by coordinator. The edit was a direct consequence of M7 landing and touched no frozen contract file. Integration agent: mark the Decision line in plan/CHANGE_REQUESTS.md and confirm the new assertion matches the spec M3 POST /api/events/detect response shape ({result, events}).
3. Integration additions to the plan/10-integration.md scope (small, discovered in review):
   • The shared-worktree collision (see lane A/C status round 0) left a coordinator-stashed debris stash in the main working dir (git stash list — "stale lane A/B debris"). After confirming nothing of value remains, drop it, and remove the now-merged worktrees ../festifun-laneA and ../festifun-laneB (git worktree remove).
   • Lane C's env note: continuous-playback sync was verified deterministically because the automated browser tab was backgrounded. During your full-system pass, verify the M4 sync overlay (<50 ms) once in a real focused browser window.
   • Test count sanity: suite is 96 passed on merge day; it must never drop below that.
4. Worktree protocol lesson (standing): integration runs single-agent, so use the main working directory directly on branch integration. If parallel agents are ever launched again, each MUST create its own git worktree before its first edit — never share a working directory.

Round 0 — 2026-07-16 — Run order & protocol

Execution order:

1. Now: foundation only. Nothing else starts until foundation merges to main. Foundation agent: contracts correctness beats speed — lanes will hard-depend on your API shapes, schema, pose math, and synthetic fixtures.
2. After foundation merges — start lanes in this priority order (all four concurrently if capacity allows; if running fewer sessions, start in this order):
   1. Lane C (viewer) — longest lane and the earliest validation of the API contract; starts first.
   2. Lane A (media) — the core real-footage capability; small surface, should finish early.
   3. Lane D (events) — small and fully independent.
   4. Lane B (recon) — heaviest external dependency (COLMAP) and the most graceful-degradation slack; safe to start last.
3. Merge policy: merge to main as soon as your lane's acceptance passes — do not wait for other lanes. Expected finish order: A, D, then C, then B.
4. After all four merge: integration.

Standing protocol (all agents):

• Maintain plan/status/<your-lane>.md per plan/status/TEMPLATE.md — session start, every milestone, every blocker, before merge. Push status commits to your branch immediately; the coordinator reviews between rounds by reading these files.
• If blocked > 30 minutes on an ambiguity, write the blocker to your status file, push, and move to another task in your lane rather than guessing on a frozen contract.
• Evidence discipline: a checked acceptance box must name the test or the exact command + output that proves it.

(Future rounds will be appended above this line as the coordinator reviews status files.)