Three phases. Each has explicit deliverables, exit criteria, and what it unblocks downstream. Phase boundaries are merge points, not just dates.
Phase 1 · MVP slice#
Goal: prove the composer's surface end-to-end with the smallest viable implementation. Surfaces stable enough that downstream blocks can extend without reshaping.
Estimate: ~2 weeks.
Blocks shipped:
| Block | Scope in phase 1 |
|---|---|
| A | Minimal — only the approveCheckpoint API + AWAITING_APPROVAL state + auto-approve timeout policy. No persistence yet (in-memory). No escalation-handler. |
| B | Composer with explicit prompts only for ObjectSpec. Transform-only output (no bake). In-process providers. No grounding required (skipped if adapter not supplied). |
Deliverables:
libs/isis/operation-orchestrator/src/checkpoint/(in-memory only).libs/isis/scene-from-image-composer/library scaffolded and exported.composeSceneFromImageandcreateSceneFromImagePipelinepublic APIs callable.- Manifest extension (
metadata.sceneFromImage.placements) shipped. align-mesh-to-splat-frame.ts+ tests.- E2E test: composer with fixture providers produces a manifest with splat + 1 mesh + 1 placement transform + (optional) ambient SFX + preview thumbnail.
- README documenting both APIs.
Exit criteria:
- All phase 1 tests pass.
npx tsc --noEmitclean.- Stub-indicator scan clean.
- A manual end-to-end run with real Marble + fixture mesh provider
- fixture SFX completes in < 10 min and produces a valid manifest.
- The composer's public API is signed off (no breaking changes anticipated); downstream blocks can be developed against it.
What this unblocks: every other block. Phase 2 starts immediately.
Phase 2 · Thorough version#
Goal: every gap from 02-gap-analysis.md closed. Composer produces a single
composed .spz with consistent lighting, full object-source flexibility,
persistent state, and resume-from-checkpoint.
Estimate: ~10 weeks. Several blocks parallelisable (see DAG).
Blocks shipped:
| Block | Scope in phase 2 |
|---|---|
| C | Full — all four object-source modes; foreground detection subphase; IoU merge; foreground/background classifier; cost estimator; MeshProviderRouter; full AnchorSpec DSL with constraint solver. |
| D | Full — bit-exact .spz encoder + decoder, validated against Niantic reference. |
| E | Full — surface-sampling baseline + hybrid path (with CPU reference rasteriser; GPU dispatch in phase 3). Splat merging with depth sort + occlusion cull + dedupe. bake-phase in composer. |
| F | Full — environment SH light field estimation; PBR shading at sample time; composition coherence gate. |
| H | Full — Postgres-backed pipeline state via Prisma; resumePipeline API; in-memory implementation kept for tests. |
Parallel work groups:
- Group A (sequential): block C → block I integration prep
- Group B (sequential): block D → block E baseline → block E hybrid → block F
- Group C (independent): block H
Three engineers can work in parallel on the three groups.
Deliverables:
- All blocks above ship their files per their respective block plans.
- E2E test matrix from
05-test-strategy.mdrows 1–14 + 16 pass. - Visual QA: composer-produced composed
.spzloads inmkkellogg/GaussianSplats3Dviewer with meshes correctly placed and lit. Screenshot in PR. - Performance: end-to-end real-provider single-mesh run completes in < 15 min.
Exit criteria:
- All phase 2 tests pass; CI green.
- Composer can run unattended via
auto-approvecheckpoint policy and produces a fully baked.spzin a single artefact. - Persistence verified via SIGKILL-resume test.
- Composition coherence gate scores > 0.85 on benign reference inputs.
What this unblocks: production deployment (after phase 3).
Phase 3 · Production hardening#
Goal: composer runs at scale. GPU work off the BFF, full observability, policy enforcement, anomaly drift watch, agent-consensus checkpoints, load-tested.
Estimate: ~6 weeks.
Blocks shipped:
| Block | Scope in phase 3 |
|---|---|
| G | Full — job-envelope dispatch for all heavy phases; Redis channel; per-handler implementations; composer's dispatchMode: 'job-envelope'. |
| I | Full — gallery registration; lineage edges; budget enforcer; license compliance via model-governance-3d; anomaly sampler; consensus checkpoint handler. |
Plus:
- Reference corpus runs (20 images from
05-test-strategy.md) on real providers; baseline metrics recorded. - Load test: 50 concurrent composer runs against staging; assert no BFF saturation, no Postgres connection leaks, no Redis backlog.
- Documentation: production runbook covering Marble API key rotation, Hunyuan rate limit handling, ElevenLabs SFX cost monitoring, Postgres maintenance.
Exit criteria:
- All phase 3 tests pass.
- Dispatch via Redis works end-to-end with a real GPU worker pool.
- Budget cap halts a composer run at the next checkpoint when exceeded (asserted via real-provider integration test).
- License gate halts a composer run when the destination license is incompatible (asserted).
- Load test sustains 50 concurrent runs for 1 hour without errors or resource leaks.
- Composer runs surface in the gallery UI with thumbnail + lineage trail.
- Consensus checkpoint policy completes a fixture-driven 3-agent decision.
What this unblocks: general availability of the composer to other domains (Yemaya for creative production, Hathor for worldbuilding assets, Bellona for engine-ready content, Lilith for meditation visuals).
Phase boundaries — what doesn't move between phases#
- API stability. Phase 1 freezes the public API. Phases 2 and 3 only add fields, never reshape. If a phase 2/3 design surfaces a breaking change requirement, it gets a new minor version and parallel-ship.
- Test corpus growth. Phase 1 ships 5 fixture images; phase 2 grows to 15; phase 3 reaches the full 20 + real-provider nightly suite.
- Performance budgets. Phase 1 = correctness only. Phase 2 = unit-test perf targets. Phase 3 = end-to-end load targets.
Risk-weighted phasing#
The phasing above optimises for shippable utility: phase 1 produces a usable
transform-only composer; phase 2 produces a usable single-.spz composer; phase
3 makes it production-grade. If any phase slips, the preceding phase still
ships.
Alternative phasing considered and rejected:
- A → C → B → E → D → F → G → H → I (foundation-first): would push shippable composer artefact 4–5 weeks later. Not worth it.
- D first (codec before everything): would let phase 1 ship baked output. But block D's reference corpus dependency is fragile and could block phase 1. Better to keep transform-only as the phase 1 stop-gap.
Schedule sensitivities#
The schedule will slip if:
- Niantic
.spzreference is harder to obtain or interpret than expected (block D, +1–2w). - Differentiable splat fitting doesn't converge cleanly on real meshes (block E hybrid path, +1–2w).
- Lighting consistency needs path-traced fallback rather than the SH approximation (block F, +1–2w).
- GPU worker integration surfaces unforeseen Redis/job-envelope deltas (block G, +0.5–1w).
Each of these is called out in 07-risks-and-open-questions.md.
Phase parallelism in practice#
Phase 2 expects three concurrent work streams. Concretely:
- Engineer 1 (composer-side): blocks C → bake-phase wiring in composer → coherence-gate wiring in composer → dispatch-mode wiring.
- Engineer 2 (splat-side): blocks D → E baseline → E hybrid → F.
- Engineer 3 (orchestrator-side): block H → consensus-checkpoint-handler prep for I.
If only one engineer is available, phase 2 timeline expands to ~16–18 weeks. Phase 3 contracts somewhat because most of its work piggybacks on finished blocks.
Definition of "shipped" per phase#
Phase exits when:
- All block-level acceptance criteria are met (per each
block-plans/*.md). - The phase's exit-criteria tests pass on
oshun-lt-2-hetznerandmain. - Per
oshun_commit_policy: every task committed and pushed via the two-line push convention. - PR description summarises every block's contribution with links to its block-plan doc.
- Visual QA recordings (where required) attached.
ISIS_GAPS_TODOS.mdboxes for the phase's tasks all checked.