Eve library

ISIS_GAPS — Scene-from-Image Composer Planning Folder

Other

Revision 1

On this page

This folder captures the architectural plan for closing the remaining gaps that surfaced after the Marble provider and input-grounding gate landed. The goal is the thorough, robust, long-term version of the scene-from-image composer — not a scope-reduced MVP.

Already shipped (context)#

Two adoptions from neilsonnn/image-blaster have already merged on oshun-lt-2-hetzner and main:

Commit Title
ce9a3e9a02 feat(isis): add world labs marble provider for image-to-splat scenes
8524d7e13b feat(isis): add input-grounding gate for hallucination detection

Together they unlock single-image → explorable Gaussian-splat scene generation plus a hallucination-detection QA gate. What they do not unlock is end-to-end composition (env + foreground meshes + ambient SFX + lighting consistency + persistence + observability). That's what this folder plans.

How to read this folder#

If you have 5 minutes, read 02-gap-analysis.md — that's the why, ranked by severity.

If you have 30 minutes, read in order:

  1. 00-context-and-rationale.md — what triggered this
  2. 02-gap-analysis.md — the gaps, ranked
  3. 03-decisions.md — the architectural choices and why
  4. 06-rollout-plan.md — the phased schedule

If you're executing the work, drive off ISIS_GAPS_TODOS.md — every box ticks one task with a file path and acceptance criteria. Per the oshun_task_verification memory rule already in effect across this repo: one task at a time, code read for each, adversarial scan before signoff. The block plans are the "spec" the TODO file refers back to.

Folder layout#

text
ISIS_GAPS/
├── README.md                              ← you are here
├── ISIS_GAPS_TODOS.md                     ← surgical checklist (sole source of truth)
├── 00-context-and-rationale.md            why this exists, what triggered it
├── 01-current-state-survey.md             what already exists in Isis (file:line refs)
├── 02-gap-analysis.md                     the gaps, ranked
├── 03-decisions.md                        ADR-style decisions
├── 04-api-surfaces.md                     proposed public TypeScript APIs
├── 05-test-strategy.md                    corpus, fixtures, golden tests, e2e
├── 06-rollout-plan.md                     three phases with exit criteria
├── 07-risks-and-open-questions.md         known unknowns and deferred decisions
└── block-plans/
    ├── A-orchestrator-checkpoint-primitive.md    foundation for everything else
    ├── B-scene-from-image-composer-library.md    the composer lib itself
    ├── C-foreground-detection-and-provider-routing.md
    ├── D-spz-exporter.md                          deferred task #3, picked up here
    ├── E-mesh-to-gaussians-bake-pipeline.md       the meat of "real composition"
    ├── F-lighting-consistency.md                  why composed scenes look right
    ├── G-job-envelope-and-gpu-dispatch.md         GPU work off the BFF process
    ├── H-state-persistence-and-resume.md          survive process restarts
    └── I-observability-policy-and-consensus.md    gallery, lineage, budget, license

Time estimate#

Phase Blocks Estimate
1 — MVP slice A (minimal) + B (explicit prompts only) ~2 weeks
2 — Thorough C + D + E + F + H ~10 weeks
3 — Production G + I + corpora + load testing ~6 weeks
Total A through I 18–23 weeks

See 06-rollout-plan.md for phase exit criteria.

Conventions used in this folder#

  • File:line refs to existing source are written as path/to/file.ts:123. Verified at the time the doc was written; may drift if the file is edited.
  • Future file paths (things this plan creates) use the same notation but are flagged with (new) on first reference per doc.
  • - [ ] boxes in ISIS_GAPS_TODOS.md are the only execution truth. ✅, **Done**, etc. in prose are notes, not status.
  • All planning is for the oshun-lt-2-hetzner branch; per CLAUDE.md, work pushes to both <branch> and <branch>:main after every task.

Out of scope for this folder#

  • Implementation code. This folder contains plans only.
  • Modifying any existing source files. Implementation work happens in subsequent sessions, gated on the docs in block-plans/.
  • Decisions that fall outside the scene-from-image composer surface (e.g. Marble provider improvements, grounding-gate adapter implementations beyond the fixture; those are tracked elsewhere).