Blacksite/.cursor/plans/blacksite_production_readiness_2026-07-10.plan.md

Blacksite Editor Production Readiness Program

Active plan — desired scope and acceptance, not implementation truth. Current shipped behavior is indexed in the canonical documentation.

Working milestone plan for the production expansion tracked by Gitea epic #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 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, with controls, runtime behavior, validation, and the committed sample fixture documented in Audio Authoring. Gitea #47 closed after automated, headless, live editor/PIE, and packaged-runtime acceptance.