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:
00-context-and-rationale.md— what triggered this02-gap-analysis.md— the gaps, ranked03-decisions.md— the architectural choices and why06-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#
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 inISIS_GAPS_TODOS.mdare the only execution truth.✅,**Done**, etc. in prose are notes, not status.- All planning is for the
oshun-lt-2-hetznerbranch; per CLAUDE.md, work pushes to both<branch>and<branch>:mainafter 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).