# Blacksite Editor Production Readiness Program

> **Active plan — desired scope and acceptance, not implementation truth.** Current shipped behavior is indexed in the [canonical documentation](../../docs/README.md).

Working milestone plan for the production expansion tracked by Gitea epic
[`#1`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/1).
The existing Jackdaw-inspired M0-M5 roadmap remains the authoring/tool foundation. This plan adds
the reliability and shipping gates required for daily indie game production.

## Definition Of Production Ready

Blacksite is production ready only when the evidence matrix in Gitea
[`#50`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/50)
is signed off. Feature presence alone is insufficient. Recovery, validation, packaging,
performance, soak, regression, and first-hour workflows must pass against a representative project.

## Immediate Sequence

1. Completed: hierarchy/prefab boundary hardening `#40`, transactional recovery `#39`, stable
   sessions/diagnostics `#41`, and Project Browser/startup boundaries `#3`.
2. Completed: stable scene tabs and composed subscene ownership/validation in `#42`.
3. Completed: nested prefabs, variants, and structural overrides passed production acceptance in
   `#43`; M6 implementation is complete.
4. Completed: authoritative content validation `#45` and the validation-gated packaging/Build
   workflow `#44`.
5. Completed: audio `#47`, animation `#46`, and navigation `#48` passed production acceptance.
   Source-control safety `#49` has complete implementation and source/headless acceptance; live
   visual acceptance remains before the readiness gate `#50`.

## Implemented Slice - Collaborative Authored-File Safety

- Exact BLAKE3 baselines for scene tabs, staged Material/Material Instance documents, and Project
  Settings.
- One guarded atomic publication path for scene save/export, prefab source Apply/history, and
  editable materials, including missing-file and immediate pre-rename race protection.
- Non-destructive background Git porcelain scanning with optional off-thread ownership providers;
  Git/provider absence is quiet.
- Compact active-scene and selected-asset state plus Reload, metadata comparison, Save As, and
  Cancel conflict recovery. No force-overwrite action exists.
- Focused race, read-only, provider-lock, parser, non-repository, modal-render, scene, and material
  tests pass. Live debug-editor visual acceptance remains pending for a desktop-capable QA session;
  packaged acceptance remains owner-deferred.

## M6 - Reliability, Recovery, And Project Workflow

**Exit:** A normal or interrupted editor session cannot silently lose or corrupt authored work, and
projects/scenes/prefabs have stable daily workflows.

| Issue | Capability | Priority |
|-------|------------|----------|
| #3 | Project launcher, templates, recent projects, resume | P0 |
| #39 | Transactional saves, autosave, crash recovery | P0 |
| #40 | Hierarchy, parenting, prefab structure hardening | P0 |
| #41 | Session persistence and crash diagnostics | P0 |
| #42 | Multi-scene tabs, subscenes, level composition | P1 |
| #43 | Nested prefabs, variants, structural overrides | P1 |

## M7 - Content Production And Shipping

**Exit:** A clean checkout can validate, build, package, and run a representative project with the
minimum animation, audio, and navigation authoring loops required by the game.

| Issue | Capability | Priority |
|-------|------------|----------|
| #44 | Build/package profiles and Build panel | P0 |
| #45 | Dependency manifest and content release gate | P0 |
| #46 | Skeletal animation import/preview/authoring | P1 |
| #47 | Audio sources/listeners/buses/spatial preview | P1 |
| #48 | Navigation authoring/bake/path preview | P1 |
| #49 | Source-control status and collaborative file safety | P2 |
| #50 | Production-readiness acceptance matrix | P0 |

## Cross-Cutting Gates

- Authored IDs, scene schema, hydration stripping, and extension boundaries remain authoritative.
- Every mutation supports meaningful undo/redo; modal tools also support cancel without dirty state.
- Editor-only helpers, recovery files, and caches never enter scenes or game packages.
- Interactive and headless validation use the same rules and produce equivalent blocking results.
- Large asset, terrain, navigation, and geometry work is debounced or dirty-region based.
- Visible behavior updates root controls and `docs/editor/`; hard-to-reverse decisions get ADRs.
- Production signoff requires a second-person first-hour QA pass and no open P0 blocker.

## Completed Slice - UI Identity And Structural Dragging

- Near-black Blacksite shell with compact tool identity rather than a Unity clone.
- Pointer-following asset drag preview, viewport reticle, boundary, and corner brackets.
- Full-width hierarchy attach targets plus explicit root/reorder/invalid feedback.
- World-transform-preserving reparent/unparent with grouped history.
- Cycle rejection, subtree-safe multi-drag, parent expansion, and focused regression coverage.

## Completed Slice - Multi-Scene Production Workflow

- Independent scene tabs integrated into the right end of the existing main toolbar.
- Stable `SceneComposition` resources with project-relative references and no runtime entity IDs.
- Recursive missing/cycle/duplicate/path-escape validation shared by editor and CI.
- Runtime-only composed ownership, load/lock/focus controls, and owner-save exclusion.
- Per-saved-tab recovery, composition undo/redo, PIE-active composition consistency, and fixtures.

## Completed Slice - Validation-Gated Build And Packaging

- Shared owner-attributed project validation and runtime-packageability policy in editor, CI, and
  packaging; unknown schemas, missing LFS objects, excluded references, and unsafe traversal block.
- Versioned development/QA/release profiles with Cargo-reported artifacts, rendering/default-scene
  application, Windows QA symbols, supported-target enforcement, and deterministic metadata.
- OS-locked authenticated staging, interrupted-build recovery, complete pre-publish hashing, safe
  replacement, and unchanged-output reuse.
- Non-blocking editor Build/Run/Cancel/Reveal workflow with dirty-tab guard and process-tree cleanup.
- Gitea #44 and #45 closed after headless, focused regression, repeated-build, and live packaged
  development-runtime acceptance.

## Completed Slice - Audio Authoring And Spatial Preview

The stable authoring/runtime contract is recorded in
[ADR 0030](../../docs/adr/0030-audio-authoring-and-bus-schema.md), with controls, runtime behavior,
validation, and the committed sample fixture documented in
[Audio Authoring](../../docs/editor/audio-authoring.md). Gitea #47 closed after automated,
headless, live editor/PIE, and packaged-runtime acceptance.