Define production readiness acceptance gate

.cursor/plans/material_library_and_targeted_drop_2026-07-12.plan.md

@@ -0,0 +1,84 @@
+# Material Library And Targeted Viewport Drop
+
+Working implementation plan for Gitea issues
+[`#16`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/16) and
+[`#18`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/18).
+The shared Material/Material Instance and stable renderer-slot foundation from `#51` is already
+present; this slice completes the production-facing catalog and drag/drop workflow.
+
+## Status
+
+Source audit complete. Implementation starts on a clean branch after collaborative-safety `#49` is
+published, because both slices touch the Asset Browser and should remain independently reviewable.
+
+## Current Gaps
+
+- Material assets are edited inside generic Asset Browser Details; no dedicated Material Library or
+  scene-usage view exists.
+- Viewport material/texture drops act on the existing selection instead of the surface under the
+  pointer.
+- Multi-slot renderers silently assign all slots; the hydrated draw hit already carries
+  `HydratedRendererMaterialBinding`, but the drop path does not use it.
+- Primitive and brush-face targeting is not explicit, and unsupported authored actors can receive a
+  generic `MaterialDesc` instead of an actionable rejection.
+- Drag UI describes an eventual action but does not preview the actual affected surface or restore a
+  preview on cancel/target change.
+
+## Material Library
+
+1. Add a dockable `Material Library` panel, opened from Window and placed in the existing bottom dock
+   without adding another permanent toolbar.
+2. Present project Materials and Material Instances with search, Material/Instance filter, thumbnail
+   grid/list modes, base/dependency health, and source-control status.
+3. Add a scene-usage section that counts renderer-slot, primitive, and brush-face references and can
+   select/locate users. Do not revive ambiguous hidden scene-local material clones.
+4. Reuse the existing guarded Material/Instance drafts for Apply, Revert, Create Instance, and
+   texture-parameter editing. Shared-file edits remain explicit; scene assignment changes use
+   history.
+5. Material and Instance cells are first-class drag sources and preserve the current pointer-following
+   visual identity.
+
+## Targeted Drop Contract
+
+Introduce a frame-updated `ViewportAssetDropTarget` resolved by the existing mesh-picking path:
+
+- A hydrated static/skinned draw maps through `HydratedRendererMaterialBinding` to the authored actor
+  and exact stable slot ID.
+- A primitive maps to its authored actor-level `MaterialDesc`.
+- A brush performs authored face intersection and identifies the stable face ID.
+- An authored but unsupported target remains a visible invalid target with a specific reason.
+- Empty space remains placement-only for placeable assets and invalid for Material/Texture payloads.
+
+Payload matrix:
+
+| Payload | Renderer slot | Primitive | Brush face |
+|---------|---------------|-----------|------------|
+| Material / Material Instance | Assign exact hit slot; one-slot actors may assign directly | Replace actor material reference/values | Replace the hit face material reference |
+| Texture | Reject with guidance to create/edit a Material Instance | Set base-color texture | Set hit-face base-color texture/material binding |
+
+An explicit `Apply All Slots` command remains available from the renderer inspector/library usage
+menu; a viewport hit never silently broadens from one slot to all slots.
+
+## Preview, Commit, And Cancel
+
+1. Start a persistent drop-preview session when a supported Material/Texture payload enters the
+   viewport. Snapshot only the target's affected authored state.
+2. Apply a transient visual preview without pushing history or marking the scene dirty.
+3. When the pointer changes target, restore the previous snapshot before previewing the new target.
+4. On release, restore the transient state first, then commit exactly one typed history/operator
+   transaction to the identified slot, primitive, or face.
+5. On Escape, drag cancellation, leaving the viewport, invalid target, or missing source, restore the
+   exact snapshot and remove every preview/helper marker.
+6. The drag card and target outline name the payload, actor, slot/face, action, and invalid reason.
+
+## Verification
+
+- Unit-test ray-hit to authored target/slot mapping, primitive/face targeting, and invalid reasons.
+- Use `OperatorInvariantHarness` for preview target changes, release commit, Escape/outside cancel,
+  dirty-state preservation, helper cleanup, and one-step undo/redo.
+- Cover static one/multi-slot, skinned multi-slot, primitive, brush face, Texture rejection on a
+  renderer slot, missing material, and linked/locked prefab boundaries.
+- Verify Material Library filtering, scene-usage counts, dependency diagnostics, and drag sources in
+  headless egui tests.
+- Run full source/headless checks. Packaged testing remains deferred until the project owner requests
+  it again; live visual acceptance is still required before closing `#16`/`#18`.

.cursor/plans/production_readiness_acceptance_2026-07-12.plan.md

@@ -0,0 +1,37 @@
+# Production-Readiness Acceptance Gate
+
+Working plan for Gitea issue
+[`#50`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/50).
+This gate is broader than the M7 feature list: it proves the complete daily authoring, content,
+recovery, performance, and release workflow against one exact release-candidate commit.
+
+## Status
+
+Audit in progress. The versioned acceptance matrix exists, but no release candidate is nominated and
+the gate is not signed off. Packaged/release testing remains explicitly deferred until the project
+owner requests it again.
+
+## Sequence
+
+1. Keep one evidence matrix under `docs/editor/evaluations/production-readiness/`; historical H1-H6
+   notes remain context only.
+2. Close implementation blockers before nominating a candidate: collaborative safety `#49`, the
+   remaining Material/drag-drop contract in `#16`, `#18`, and `#51`, terrain `#22`-`#24`, physics
+   placement/diagnostics `#25`-`#26`, and their regression fixtures.
+3. Complete the representative regression project, mutation-invariant coverage, performance budgets,
+   and first-hour workflow tracked by `#32`-`#36`.
+4. Nominate one exact commit, validate it from a clean checkout, and record source/headless results.
+5. When packaged testing is re-enabled, run the candidate's package/build and packaged-runtime
+   matrix without substituting older artifacts.
+6. Run the eight-hour soak and measured performance protocol, consolidate limitations by severity
+   and workaround, and obtain independent first-hour/recovery sign-off.
+7. Post the signed Gitea milestone comment linking the exact commit and immutable evidence. Close
+   `#50` only when every required row passes and no P0 blocker remains.
+
+## Gate Rules
+
+- Feature presence is not acceptance evidence.
+- A local dirty worktree is not a release candidate.
+- Results from another commit or an old package do not transfer to the candidate.
+- Deferred, missing, partial, and implementer-only evidence are not passes.
+- Every failure records an owner ticket or a concrete rerun condition.

docs/README.md

@@ -79,6 +79,7 @@ Immutable-style log of significant decisions. Add a new numbered ADR when changi
 | [editor/collaborative-file-safety.md](editor/collaborative-file-safety.md) | Guarded authored writes, compact Git/read-only status, conflict recovery, and ownership providers |
 | [editor/evaluations/material-renderer-foundation/](editor/evaluations/material-renderer-foundation/) | Live screenshots and acceptance results for the renderer/material/component foundation |
 | [editor/evaluations/navigation-authoring/](editor/evaluations/navigation-authoring/) | Live screenshots and acceptance results for navigation authoring and runtime parity |
+| [editor/evaluations/production-readiness/](editor/evaluations/production-readiness/) | Current versioned production gate, evidence matrix, candidate commands, soak protocol, and independent sign-off requirements |
 
 ## Working plans (not canonical long-term)
 
@@ -98,6 +99,8 @@ Detailed milestone and feature plans live in [`.cursor/plans/`](../.cursor/plans
 | `navigation_authoring_*.plan.md` | M7 navigation bounds, deterministic bake, diagnostics, preview, and runtime query API |
 | `renderer_material_component_foundation_*.plan.md` | Renderer/material slots, skinned pose lifecycle, Surface ABI, and component foundation |
 | `source_control_collaboration_safety_*.plan.md` | Exact authored-file guards, observational Git status, conflict recovery, and provider contract |
+| `production_readiness_acceptance_*.plan.md` | Release-candidate evidence matrix, blocker sequence, clean-checkout checks, soak, budgets, and independent sign-off |
+| `material_library_and_targeted_drop_*.plan.md` | Dedicated Material Library, exact viewport slot/primitive/brush targeting, hover preview, cancel, and grouped history |
 
 ## Crate responsibilities (quick reference)
 

docs/editor/README.md

@@ -26,6 +26,7 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
 | [collaborative-file-safety.md](collaborative-file-safety.md) | Exact authored-file revisions, Git/read-only status, conflict recovery, and optional ownership providers |
 | [evaluations/material-renderer-foundation/](evaluations/material-renderer-foundation/) | Live screenshots and verification record for the renderer/material/component foundation |
 | [evaluations/navigation-authoring/](evaluations/navigation-authoring/) | Live screenshots and verification record for navigation authoring and runtime parity |
+| [evaluations/production-readiness/](evaluations/production-readiness/) | Current #50 release-candidate matrix and required clean-checkout, soak, performance, limitation, and independent-signoff evidence |
 
 ## Subsystems (code → doc)
 

docs/editor/evaluations/h1-signoff.md

@@ -1,5 +1,7 @@
 # H1 Gate Sign-Off — Game Development Ready
 
+> Historical baseline only. Current production authority: [production-readiness matrix](production-readiness/).
+
 **Date:** 2026-05-30  
 **Evaluator:** implementation pass  
 **Result:** Pass (implementation complete; manual dogfood recommended)

docs/editor/evaluations/h2-signoff.md

@@ -1,5 +1,7 @@
 # H2 Gate Sign-Off — Content Pipeline Maturity
 
+> Historical baseline only. Current production authority: [production-readiness matrix](production-readiness/).
+
 **Date:** 2026-05-30  
 **Result:** Pass with waivers
 

docs/editor/evaluations/h3-signoff.md

@@ -1,5 +1,7 @@
 # H3 Gate Sign-Off — Gameplay Authoring
 
+> Historical baseline only. Current production authority: [production-readiness matrix](production-readiness/).
+
 **Date:** 2026-05-30  
 **Result:** Pass
 

docs/editor/evaluations/h4-signoff.md

@@ -1,5 +1,7 @@
 # H4 Gate Sign-Off — Multiplayer Tooling
 
+> Historical baseline only. Current production authority: [production-readiness matrix](production-readiness/).
+
 **Date:** 2026-05-30  
 **Result:** Pass with waivers
 

docs/editor/evaluations/h5-signoff.md

@@ -1,5 +1,7 @@
 # H5 Gate Sign-Off — Extensibility
 
+> Historical baseline only. Current production authority: [production-readiness matrix](production-readiness/).
+
 **Date:** 2026-05-30  
 **Result:** Pass
 

docs/editor/evaluations/h6-signoff.md

@@ -1,5 +1,7 @@
 # H6 Gate Sign-Off — Production / Framework 1.0
 
+> Historical baseline only. Current production authority: [production-readiness matrix](production-readiness/).
+
 **Date:** 2026-05-30  
 **Result:** Pass with waivers
 

docs/editor/evaluations/production-readiness/README.md

@@ -0,0 +1,104 @@
+# Production-Readiness Acceptance Matrix
+
+**Matrix version:** 0.1
+
+**Last audit:** 2026-07-12
+
+**Release-candidate commit:** Not nominated
+
+**Overall result:** **Not ready**
+
+This is the current authority for Gitea
+[`#50`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/50).
+The older H1-H6 files are historical implementation snapshots and do not satisfy this gate.
+
+## Evidence Rules
+
+| State | Meaning |
+|-------|---------|
+| Pass | Candidate-specific evidence proves the full row. |
+| Partial | Some implementation/evidence exists, but the full row is not proven. |
+| Deferred | The project owner has explicitly postponed this check; it is not a pass. |
+| Missing | Required implementation or candidate evidence does not exist. |
+| Fail | Current authoritative evidence contradicts the gate. |
+| External | Requires a person other than the implementer. |
+
+Acceptance evidence must name the exact candidate commit and commands or protocol used. Results from
+another commit, a dirty worktree, or an older package do not transfer to the candidate.
+
+## Exit Gate
+
+| ID | Requirement | State | Current evidence and gap |
+|----|-------------|-------|--------------------------|
+| G1 | Project create/open/resume, scene authoring, autosave/recovery, hierarchy, prefab, and asset integrity pass | Partial | Project/recovery/session/multi-scene/prefab implementations are documented in [project launcher](../../project-launcher.md), [session recovery](../../session-recovery.md), [multi-scene composition](../../multi-scene-composition.md), and [prefab authoring](../../prefab-authoring.md). Candidate-specific end-to-end reruns and the open asset-integrity work remain. |
+| G2 | Brush, material, terrain, physics placement, animation, audio, navigation, PIE, and build/package samples pass | Fail | Animation, audio, navigation, and build foundations are implemented. Material/drag-drop tickets `#16`, `#18`, and `#51` remain open; terrain `#22`-`#24` and physics placement `#25` are not complete; brush acceptance `#37` remains open. Packaged testing is owner-deferred. |
+| G3 | Undo/redo/cancel invariants and helper cleanup cover every production mutation path | Partial | The reusable harness and current tool coverage are documented in [operator regression testing](../../operator-regression-testing.md). Gitea `#33` remains open for terrain-stroke and physics-settle fixtures after those tools exist. |
+| G4 | Representative project completes an eight-hour soak without unbounded memory/target growth or unrecoverable failure | Missing | No candidate soak log, resource timeline, failure ledger, or target-growth measurement exists. |
+| G5 | Cold start, scene open/save, asset refresh, common manipulation, and package-build budgets are documented and measured | Missing | Gitea `#34` is open; no ratified budgets or candidate measurement record exists. |
+| G6 | Headless content validation and CI are green from a clean checkout | Missing | [CI configuration](../../../../.github/workflows/ci.yml) exists and local source/headless checks have passed during feature work, but no clean-checkout candidate run is linked. The current Gitea server does not expose an Actions run endpoint for this repository. |
+| G7 | First-hour UX and recovery QA are signed off by someone other than the implementer | External | No independent sign-off exists. Gitea `#36` remains open; historical H1-H6 implementation-pass notes do not count. |
+| G8 | Known limitations have severity/workaround and no P0 blocker remains | Fail | Limitations are distributed across feature docs rather than one candidate ledger. Open P0 work includes `#16`, `#18`, `#32`, `#33`, `#35`, and `#51`; `#50` cannot close while a gate-relevant P0 remains. |
+
+## Deliverables
+
+| ID | Deliverable | State | Evidence or next action |
+|----|-------------|-------|-------------------------|
+| D1 | Versioned acceptance matrix under `docs/editor/evaluations/` | Pass | This file, version 0.1. |
+| D2 | Release-candidate representative project and reproducible validation commands | Missing | Expand the committed project/regression pack through `#32`, including terrain and physics-placement samples, then nominate an exact commit. |
+| D3 | Signed milestone comment linking evidence, limitations, and exact commit | Missing | Post only after G1-G8 pass; no candidate exists yet. |
+
+## Workflow Coverage
+
+| Workflow | Implementation status | Candidate acceptance |
+|----------|-----------------------|----------------------|
+| Project create/open/resume | Implemented | Not rerun |
+| Scene save, autosave, recovery | Implemented | Not rerun |
+| Hierarchy parenting and prefab structure | Implemented | Not rerun |
+| Multi-scene composition | Implemented | Not rerun |
+| Brush blockout/edit/CSG | Implemented foundation; `#37` open | Not signed off |
+| Material catalog and assignment | Partial; `#16`, `#18`, `#51` open | Blocked |
+| Terrain authoring | `#22`-`#24` open | Blocked |
+| Physics placement | `#25` open | Blocked |
+| Animation | Implemented | Not rerun |
+| Audio | Implemented | Not rerun |
+| Navigation | Implemented | Not rerun |
+| PIE | Implemented | Not rerun |
+| Build/package/runtime | Implemented foundation | Deferred by owner |
+| Collaborative file safety | Local source/headless acceptance; `#49` open | Awaiting publication and live visual QA |
+
+## Candidate Validation Commands
+
+Run these from a fresh clone of the nominated commit with Git LFS content present. Record wall time,
+machine profile, exit code, and artifact hashes. Packaged commands stay disabled until the project
+owner re-enables them.
+
+```bash
+cargo fmt --all -- --check
+cargo check --workspace --all-targets
+cargo clippy --workspace --all-targets -- -D warnings
+cargo clippy -p editor -p game --bins --features dev,hot-reload -- -D warnings
+cargo test --workspace
+cargo validate-levels --project .
+cargo bake-navigation --project . --check
+```
+
+When packaged acceptance is re-enabled, append the exact `package-project` profile/target commands,
+package hash verification, and packaged-runtime smoke protocol used for the candidate.
+
+## Soak Protocol
+
+The final candidate must run for eight continuous hours against the representative project. The
+record must sample process RSS, GPU memory, target-directory size, recovery generations, background
+job counts, and error/warning totals at least every five minutes. Exercise scene switching, save and
+recovery, asset refresh, material editing, brush/terrain/physics tools, animation/audio/navigation,
+PIE transitions, and build UI cancellation without replacing the candidate during the run.
+
+A pass requires no unrecoverable editor failure, no lost authored work, no unbounded upward trend in
+steady-state resource use, bounded recovery/cache behavior, and a triaged explanation for every
+error. Numeric thresholds remain blocked on the performance-budget work in `#34`.
+
+## Independent Sign-Off
+
+The evaluator must not be the implementation agent. They record the candidate commit, machine,
+elapsed first-hour workflow, recovery scenario, defects, severity, and go/no-go decision. Waivers
+must include a workaround and owner ticket; an open P0 cannot be waived.