# ISIS_GAPS — Scene-from-Image Composer Planning Folder

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`](./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`](./00-context-and-rationale.md) — what
   triggered this
2. [`02-gap-analysis.md`](./02-gap-analysis.md) — the gaps, ranked
3. [`03-decisions.md`](./03-decisions.md) — the architectural choices and why
4. [`06-rollout-plan.md`](./06-rollout-plan.md) — the phased schedule

If you're **executing the work**, drive off
[`ISIS_GAPS_TODOS.md`](./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`](./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).
