lootforge 0.3.0

package/docs/ROADMAP.md

@@ -0,0 +1,411 @@
+# LootForge Public Release Roadmap
+
+Last updated: 2026-03-06
+
+## Goal
+
+Move LootForge from a strong early foundation (`0.1.x`) to a dependable, public-facing release with:
+
+- controllable generation workflows,
+- measurable quality gates,
+- predictable artifact contracts,
+- clear operational guidance for teams.
+
+## Current Baseline (Shipped in 0.1.x)
+
+- Manifest-driven staged pipeline (`plan -> generate -> process -> atlas -> eval -> review -> select -> package`).
+- Path-safety and reliability hardening across pipeline stages.
+- Style kits with consistency-group semantics and manifest asset validation.
+- OpenAI `edit-first` generation path (edits endpoint, multipart inputs).
+- External soft-adapter execution for CLIP/LPIPS/SSIM in eval.
+- Weighted candidate ranking using profile weights and adapter score contributions.
+- Selection lock + skip-locked generation path for deterministic no-regenerate flows.
+
+## `0.2.0` Progress Snapshot (2026-02-18)
+
+- Added dedicated `lootforge regenerate --edit` flow using approved selection-lock outputs as edit bases.
+- Added per-target score-component detail blocks in review output for eval/review explainability parity.
+- Added style-kit palette auto-ingest (`styleKits[].palettePath`) when target palette policy is unset.
+- Added enforced PR/push CI (`typecheck`, `test`, `build`) plus security workflows (dependency review, `npm audit`, CodeQL).
+
+## Release Principles
+
+- Keep behavior deterministic unless explicitly marked stochastic.
+- Every ranking decision should be explainable from report artifacts.
+- Treat unsafe pathing and silent fallback behavior as release blockers.
+- Keep manifest/schema compatibility explicit and migration-friendly.
+
+## Product Parity Focus (OSS)
+
+- Prioritize functional parity with modern game-asset generators for request semantics, post-processing outputs, and automation interfaces.
+- Keep auth/subscription gating and credit metering out of core LootForge scope.
+- Prefer composable interfaces (CLI + API + MCP wrapper) over product-specific UI coupling.
+
+## Version Plan
+
+| Version | Codename         | Theme                       | Outcome                                                        |
+| ------- | ---------------- | --------------------------- | -------------------------------------------------------------- |
+| `0.2.0` | `Emberforge`     | Public Beta Foundation      | Stable quality gates + practical edit workflows for teams      |
+| `0.3.0` | `Tempered Steel` | Control and Consistency     | Stronger content control, repeatability, and candidate quality |
+| `0.4.0` | `Anvilheart`     | Local Production Path       | Serious local diffusion path (ControlNet/LoRA workflow)        |
+| `0.5.0` | `Runesmelter`    | Team Scale and Integrations | CI/regression dashboards + multi-engine packaging maturity     |
+| `1.0.0` | `Mythic Foundry` | General Availability        | Public release with compatibility promises and ops docs        |
+
+## `0.2.0` Public Beta Foundation (`Emberforge`)
+
+Focus: close the biggest usability/control gaps for day-to-day production use.
+
+### Scope
+
+- Edit-first UX completion:
+  - add a dedicated regen/edit CLI flow (`lootforge regenerate --edit` style path),
+  - preserve target lock provenance when regenerating by edit.
+- Candidate quality:
+  - expose score weighting defaults clearly in init templates/docs,
+  - add per-target score breakdown rendering to review output.
+- Palette and tile reliability:
+  - auto-ingest `styleKits[].palettePath` into quantize defaults when target palette is unset,
+  - add optional seam-heal pass for tile-marked targets.
+- Eval usability:
+  - add adapter health section in eval report (configured, active, failed),
+  - document adapter reference implementation format with examples.
+
+### Exit Criteria
+
+- Beta pack can be generated, reviewed, and regenerated via edit-first without manual JSON surgery.
+- Eval and review artifacts expose enough detail to explain why a candidate won.
+- Tile/palette policies are applied consistently from style kit defaults.
+
+## `0.3.0` Control and Consistency (`Tempered Steel`)
+
+Focus: improve artistic consistency and ranking quality beyond heuristics.
+
+### Scope
+
+- Content-aware ranking expansion:
+  - run adapter scoring during candidate generation and eval with shared contract (already partially landed),
+  - calibrate score weighting presets by target kind (sprite/tile/background/effect).
+- Consistency-group coherence and Identity Stability:
+  - add group-level outlier scoring from LPIPS/CLIP metrics across sibling targets,
+  - implement cross-frame DINO feature similarity to automatically flag character/geometry drift in animations,
+  - surface drift warnings at group level in eval + review.
+- Advanced Tiling Contracts and Palette QA:
+  - formalize a deterministic Tiling Score (TS) for strict Wang-tile topology validation,
+  - add Palette Consistency Score (PCS) to enforce indexed palette constraints on pixel art outputs.
+- Cloud provider edit path parity:
+  - implement Nano/Gemini edit-first flow equivalent to OpenAI path where supported.
+- Scoring profile support:
+  - allow manifest scoring profiles to override default per-kind weight presets.
+- Auto-Correction via LLM/VLM "Agentic Retry":
+  - if a candidate fails the VLM or Edge-Aware QA gates, automatically feed the critique into an edit-first regeneration loop.
+
+### Exit Criteria
+
+- Candidate selection reflects both deterministic gates and content-aware signals.
+- Consistency drift is visible and actionable at group and pack levels.
+- OpenAI and Nano edit-first flows are both supported and documented.
+
+## `0.4.0` Local Production Path (`Anvilheart`)
+
+Focus: deliver high-control local workflows for repeatable professional packs.
+
+### Scope
+
+- Local diffusion production architecture:
+  - explicit ControlNet input contract (pose/edge/depth/segmentation roles),
+  - workflow templates for local service endpoints.
+- Semantic animation control and showcase reliability:
+  - add semantic gait/pose scoring for directional walk cycles so believable stride and forward momentum are evaluated separately from continuity drift,
+  - rank multi-attempt animation captures using semantic motion, footfall, and facing signals instead of prompt-only heuristics,
+  - support deterministic fallback to a locked canonical walk exemplar when stochastic generation cannot produce a release-grade strip.
+- 3D-to-2D Projection & Automating ControlNets:
+  - integrate headless 3D rendering (e.g., three.js) to ingest primitive meshes,
+  - auto-capture isometric Depth/Normal maps to drive ControlNet, guaranteeing 8-way directional consistency.
+- LoRA-ready pack support:
+  - manifest metadata for LoRA/model variants per style kit,
+  - provenance capture of model/control stack used per output.
+- Throughput and queueing:
+  - separate GPU generation queue from CPU post-process workers,
+  - hard concurrency/rate controls with predictable scheduling.
+- Multi-Layer Compositions & Alpha Matting:
+  - implement diffusion matting exporters for fringeless alpha extraction,
+  - support native multi-layer outputs (e.g., z-index layers or PSD equivalents) for UI and characters.
+
+### Exit Criteria
+
+- Local path can produce repeatable packs with structural controls enabled.
+- Provenance is sufficient to reproduce a pack’s generation conditions.
+- Walk-cycle showcase outputs are semantically readable, directionally consistent, and deterministic under release capture.
+
+## `0.5.0` Team Scale and Integrations (`Runesmelter`)
+
+Focus: team operations, CI confidence, and runtime integration maturity.
+
+### Scope
+
+- Evaluation harness maturation:
+  - fixture packs committed for regression tests,
+  - thresholded CI checks for hard gates + selected soft metrics.
+- Reporting and dashboards:
+  - machine-readable eval trend artifacts for CI history,
+  - release quality summary per pack build.
+- Runtime export expansion:
+  - improve metadata exports (anchors/pivots/nine-slice metadata),
+  - add Unity/Godot-oriented output presets.
+- Native Vector Generation:
+  - use LLM/Diffusion-guided SVG synthesis to generate structured, layer-separated true vector assets,
+  - implement style-preserving vector distillation (e.g., IconDM) to expand icon seed sets into massive cohesive packs.
+- First-Class Audio Generation Pipeline:
+  - add LLM-driven audio manifest generation from text prompts,
+  - integrate time-varying control for parameterized SFX (e.g., UI clicks, hits),
+  - support timing-directed prompts and loop-aware inference for seamless ambience/music,
+  - support multi-track stem generation and enforce ITU-R/EBU loudness compliance QA.
+- Generative Dependency DAG ("Asset Lineage"):
+  - treat generation targets as a Directed Acyclic Graph,
+  - automatically inject approved parent assets as IP-Adapter/Style references into child targets for total pack coherence.
+- Native Engine Editor Plugins:
+  - build native Unity/Godot Editor plugins communicating via `serve` mode,
+  - enable direct text-to-asset hot-swapping directly on GameObjects in-editor.
+
+### Exit Criteria
+
+- CI can reject quality regressions automatically and explain why.
+- Pack outputs are straightforward to consume across target engines.
+
+## `1.0.0` General Availability (`Mythic Foundry`)
+
+Focus: stable public contract and operational readiness.
+
+### Scope
+
+- Compatibility and migration:
+  - freeze/stabilize manifest contract for GA line,
+  - provide schema migration notes and version compatibility matrix.
+- Public release operations:
+  - harden docs for setup, adapter integration, and troubleshooting,
+  - publish release checklist and support policy.
+- Security/compliance hygiene:
+  - document model/provider licensing considerations,
+  - define safe defaults for secrets and external adapter execution.
+- The Multimodal Style Bible:
+  - expand `styleKits` scheme to encompass both visual constraints and audio constraints (reverb, loudness, sonic palette),
+  - enforce the single style bible definitively across the entire generative pack pipeline.
+- Temporal Consistency via Video-to-Sprite Inference (Future Focus):
+  - implement `video-to-sprite` target mode utilizing frame-interpolation over generated video,
+  - deliver drift-free 60fps sprite animation exceeding pure image-diffusion bounds.
+- Native 3D Asset Generation (Future Focus):
+  - expand target kinds to support `.gltf`/`.glb` 3D mesh generation for engines like Three.js.
+  - apply QA validation gates for polygon budgets, clean topology, and PBR material consistency.
+
+### Exit Criteria
+
+- Public users can adopt LootForge without internal tribal knowledge.
+- Manifest + output contracts have explicit compatibility guarantees.
+
+## Cross-Version Trackers
+
+These run continuously across versions and should be reviewed per milestone:
+
+- Quality metrics:
+  - candidate acceptance pass rate,
+  - edit-first success rate,
+  - consistency drift incidents,
+  - tile seam failure rate.
+- Reliability:
+  - failed job retry success ratio,
+  - adapter failure frequency,
+  - deterministic rebuild consistency on locked targets.
+- Cost efficiency:
+  - provider calls per approved target,
+  - candidate count per approved target.
+- Operational diagnostics:
+  - run failure rate,
+  - mean time to diagnose failures from provenance/eval artifacts.
+- DX:
+  - setup time for first successful pack,
+  - number of manual manifest edits required per pack iteration,
+  - review minutes per approved target.
+
+## Upcoming (Execution Queue)
+
+These items should be actively planned and ticketed now.
+
+### `0.2.0` Upcoming (Public Beta Foundation / `Emberforge`)
+
+- Scope complete; no remaining upcoming items in `0.2.0`.
+
+Completed 2026-02-18 in this release track:
+
+- Added adapter health section to eval report (`configured`, `active`, `failed`) and shipped adapter contract docs/examples.
+- Added optional `seamHeal` processing pass for tileable targets and `wrapGrid` validation checks.
+- Added `lootforge regenerate --edit` command path and preserved selection/provenance semantics.
+- Added score-component detail blocks to review output.
+- Applied `styleKits[].palettePath` defaults when target palette policy is unset.
+- Added baseline CI/security workflows for PRs and pushes.
+
+### `0.3.0` Upcoming (Control and Consistency / `Tempered Steel`)
+
+Completed 2026-02-20 in this release track:
+
+- Release-gate coverage hardening:
+  - added integration coverage for generate fallback chains, approved lock skip/copy behavior, and candidate replacement selection,
+  - added direct unit coverage for generate CLI arg parsing and boolean flag handling,
+  - tightened CI test gates to fail on missing unit/integration suites and enforce critical-path coverage thresholds.
+
+- Harden path safety for edit/adapters:
+  - enforce in-root normalization for `edit.inputs` paths before provider uploads and adapter payload expansion.
+- Add versioned stage-artifact contract tests:
+  - define authoritative contract schemas for `targets-index`, run provenance, acceptance report, eval report, and selection lock artifacts,
+  - add CI fixture-pack smoke tests that validate contract compatibility end-to-end.
+- Make provider configuration an enforced runtime contract:
+  - consistently apply manifest/env endpoint, timeout, retry, delay, and concurrency settings across all providers,
+  - add capability-claim parity checks so provider feature flags reflect actual runtime behavior.
+- Performance reliability follow-ups:
+  - eliminate repeated candidate-image decode/stats passes during scoring,
+  - run enabled soft adapters in parallel with deterministic result aggregation,
+  - reduce repeated PNG decode work for resize variants and auxiliary map derivation.
+- Add automated VLM candidate grading gates:
+  - add manifest-configurable `generationPolicy.vlmGate` with threshold default `4/5` and optional rubric text,
+  - reject below-threshold candidates before final selection and persist per-candidate VLM decisions in provenance,
+  - surface VLM score/threshold/reason traceability in eval and review artifacts.
+- Add edge-aware quality scoring and hard-gate coverage:
+  - added alpha-boundary metrics (`alphaHaloRisk`, `alphaStrayNoise`, `alphaEdgeSharpness`) to candidate scoring and eval acceptance output,
+  - enforce configurable hard-gate thresholds from evaluation profiles for halo risk, stray noise, and boundary edge sharpness,
+  - surface boundary-focused rejection reasons in candidate score records and acceptance issue diagnostics.
+- Expand acceptance from single-image checks to pack-level invariants:
+  - enforce runtime/output uniqueness across non-catalog targets and spritesheet atlas-family integrity checks,
+  - add spritesheet continuity checks (adjacent-frame silhouette/anchor drift metrics + optional hard-gate thresholds),
+  - add optional profile texture-memory budget gates and propagate pack-level summary into acceptance/eval/review artifacts.
+- Add optional service mode with stable HTTP generation endpoints and MCP wrapper compatibility:
+  - added `lootforge serve` command with stable JSON endpoints (`/v1/health`, `/v1/tools`, `/v1/tools/:name`, `/v1/:name`),
+  - added command/tool metadata discovery and deterministic request/response envelopes for wrapper integration,
+  - kept core service mode intentionally unauthenticated (no auth/credit layer in core).
+- Define a canonical generation request contract and mapping layer between service requests and manifest/pipeline targets:
+  - added `POST /v1/generation/requests` contract endpoint that maps canonical service requests into `plan -> generate`,
+  - added `GET /v1/contracts/generation-request` schema/field descriptor for wrapper discovery,
+  - added inline manifest materialization and normalized request metadata in service response payloads.
+- Implement Nano/Gemini edit-first parity (where supported) with tests:
+  - added Gemini/Nano edit-first request mapping with role-aware input handling for `base`, `mask`, and `reference` inputs,
+  - enforce safe in-root edit input path resolution and explicit Nano edit error codes for unsupported models / unreadable inputs,
+  - added deterministic unit coverage for Nano text-mode and edit-first request execution paths.
+- Add manifest schema scaffolding for directed synthesis controls:
+  - added manifest + planner scaffolding for `targets[].controlImage`, `targets[].controlMode` (`canny|depth|openpose`),
+  - added style-kit scaffolding for `styleKits[].styleReferenceImages`, `styleKits[].loraPath`, and `styleKits[].loraStrength`,
+  - added generation-policy scaffolding for `generationPolicy.highQuality` and optional `generationPolicy.hiresFix`.
+- Implement first-class post-process semantics for pixel-perfect/smart-crop behaviors and explicit variant artifacts:
+  - added manifest schema + normalized planner support for `postProcess.operations.smartCrop`, `pixelPerfect`, and `emitVariants`,
+  - implemented process-stage semantics for smart-crop behavior and pixel-perfect nearest-neighbor resize handling,
+  - added explicit processed artifact emission for `__raw`, `__style_ref`, and `__pixel` variants.
+- Harden pixel-perfect quantization behavior:
+  - enforce deterministic nearest-color exact-palette mapping with alpha-safe handling (transparent RGB zeroing),
+  - add exact-palette strict mode (`palette.strict`) that enforces 100% visible-pixel compliance during process/acceptance/scoring.
+- Add manifest policy coverage checks:
+  - added machine-checkable policy coverage index (`docs/MANIFEST_POLICY_COVERAGE.md`) for documented manifest policy fields,
+  - added `check:manifest-policy` release gate that fails when documented fields are neither `implemented` nor `reserved`,
+  - require test evidence for every implemented policy field and emit CI report artifacts at `coverage/manifest-policy-coverage.json`.
+- Introduce per-kind scoring presets and manifest-level scoring profile overrides:
+  - added deterministic built-in score presets by target kind (`sprite|tile|background|effect|spritesheet`),
+  - added optional `scoringProfiles[]` manifest contract with global and per-kind score-weight overrides,
+  - resolved target scoring weights via `targets[].scoringProfile` (or `evaluationProfileId` fallback) with explicit validation for unknown profiles.
+- Add model capability introspection contract and endpoint for provider feature gating (pixel/high-res/references):
+  - added `GET /v1/contracts/provider-capabilities` and `GET /v1/providers/capabilities` for wrapper capability discovery and runtime feature gating,
+  - added provider/model query support for introspection (`provider`, `model`) with model-aware Nano edit capability differentiation,
+  - added explicit directive-gating capability signals (`pixel`, `highRes`, `references`) with support modes and diagnostics.
+- Add template-driven pack orchestration layer with dependency-aware style-reference chaining:
+  - added manifest `targetTemplates[]` with target-level `templateId`, `dependsOn`, and `styleReferenceFrom`,
+  - added deterministic dependency-aware generate staging with unresolved/cycle validation,
+  - added per-job provenance `styleReferenceLineage` records for effective style-reference inputs.
+- Add consistency-group drift/outlier scoring with configurable warning and ranking influence controls:
+  - added CLIP/LPIPS sibling-group outlier scoring with aggregate warning/outlier summaries in eval/review artifacts,
+  - added `evaluationProfiles[].consistencyGroupScoring` controls (`warningThreshold`, `penaltyThreshold`, `penaltyWeight`) for deterministic ranking influence,
+  - added selection-lock traceability fields (`evalFinalScore`, `groupSignalTrace`) so group-signal ranking deltas remain auditable.
+- Add bounded agentic auto-correction retries for VLM and edge-boundary hard-fails:
+  - added optional `generationPolicy.agenticRetry` controls (`enabled`, `maxRetries`) to drive bounded edit-first self-healing loops,
+  - auto-generated critique instructions from hard-fail signals (`vlm_gate_below_threshold`, alpha-boundary violations) and retried from selected candidate outputs,
+  - persisted attempt-level trigger/delta summaries in run provenance via `agenticRetry` records.
+- Complete coarse-to-fine benchmark evidence and cost analysis tooling:
+  - added stage-weighted run-cost benchmarking utilities and a comparison script (`npm run benchmark:coarse-to-fine`),
+  - added integration benchmark coverage showing reduced cost-per-approved at equivalent acceptance for coarse-to-fine promotion flows,
+  - retained promotion/discarded candidate provenance records as benchmark input artifacts.
+- Add deterministic topology and animation-drift QA follow-ups:
+  - added wrap-grid topology validation modes (`self`, `one-to-one`, `many-to-many`) with explicit mismatch-threshold diagnostics separate from seam scoring,
+  - added spritesheet continuity hard-gates for identity drift and pose drift with per-animation metrics (`maxIdentityDrift`, `maxPoseDrift`) in acceptance/eval artifacts.
+- Add machine-checkable style-bible visual policy checks:
+  - added manifest style-policy contract (`styleKits[].visualPolicy`) for line contrast, shading complexity, and UI rectilinearity constraints,
+  - enforced deterministic acceptance/eval diagnostics with explicit metrics and hard rejection codes (`style_policy_*`).
+- Add layered export + matting-assisted alpha QA pipeline:
+  - added first-class layered artifacts (`__layer_color`, `__layer_matte`) for sprite/UI/VFX workflows with deterministic export contracts,
+  - added matting-derived transparency diagnostics (`maskCoverage`, `semiTransparencyRatio`, `maskConsistency`, `hiddenRgbLeak`) with optional hard-gate thresholds in acceptance/eval artifacts.
+
+Remaining queued items:
+
+#### 2D Investigation Follow-ups (Visual QA + Policy)
+
+- Add machine-checkable visual style-bible policy contracts:
+  - extend beyond current baseline thresholds with richer style-assertion primitives when needed (for example, per-kind policy profiles).
+- Add sprite identity + pose adherence QA modules:
+  - extend beyond current drift thresholds with optional target-specific pose directives when prompts require strict choreography.
+
+## Future (After Upcoming)
+
+These are high-impact but should follow once `0.2.0` and `0.3.0` stabilize.
+
+### `0.4.0` Future (Local Production Path / `Anvilheart`)
+
+- Implement first-class ControlNet execution for local diffusion:
+  - map `targets[].controlImage` + `targets[].controlMode` to provider payloads for Canny/Depth/OpenPose.
+- Add dual-guidance local conditioning workflows:
+  - combine structural ControlNet guidance with optional detail/edge guidance priors for boundary fidelity refinement.
+- Implement IP-Adapter image-prompt integration for local diffusion:
+  - pass `styleKits[].styleReferenceImages` separately from structural ControlNet guide inputs.
+- Implement two-pass Hires Fix workflows behind explicit high-quality policy flags:
+  - low-res generation -> latent upscale -> high-res denoise pass.
+- Implement LoRA loading from style-kit manifest configuration:
+  - support `styleKits[].loraPath` and `styleKits[].loraStrength`,
+  - capture model/control/LoRA provenance per output for reproducibility.
+- Publish local provider payload parity docs for ComfyUI/A1111-compatible mappings:
+  - control, style references, hires-fix, and LoRA field mapping expectations.
+
+### `0.5.0` Future (Team Scale and Integrations / `Runesmelter`)
+
+- Add CI fixture packs, regression dashboards, and thresholded quality gates.
+- Add quality/latency operating profiles:
+  - publish `fast`, `balanced`, and `high-fidelity` presets with explicit candidate-count, refinement-pass, and adapter-eval behavior.
+- Add golden-set quality harness and nightly regression gates:
+  - maintain curated target/reference packs and detect score-quality regressions across providers/models,
+  - add calibration loop outputs for score-weight tuning over time.
+- Add provider budget/rate telemetry and draft-vs-final operational controls.
+- Harden release-grade CI and supply-chain posture:
+  - publish coverage reports with thresholds for critical pipeline modules,
+  - pin workflow action revisions and emit SBOM + build provenance artifacts,
+  - add policy checks for insecure soft-adapter execution configuration.
+- Expand runtime export presets and metadata for Unity/Godot integration.
+
+#### 2D Investigation Follow-ups (Runtime/Export)
+
+- Add first-class autotile runtime contract exports:
+  - emit 4-neighbor bitmask metadata (`4 bits -> 16-entry LUT`) for deterministic tile-index selection,
+  - support tileset variant blocks (e.g., separate `4x4` banks for water-edge vs cliff-edge families) with runtime selection hints.
+  - define canonical neighbor bit ordering, map-boundary behavior, and deterministic variant-picking rules so runtime implementations stay consistent across engines.
+- Add vector/layered asset interoperability gates:
+  - add first-class SVG target support (generation, validation, review, and package/export stages),
+  - validate SVG structure/layer hygiene before packaging and publish deterministic export conventions,
+  - define layered-artifact contracts for downstream toolchains that expect editable layered inputs.
+- Add asset-license provenance release gates:
+  - require machine-readable provenance metadata for visual datasets, reference assets, and model families used per target,
+  - fail packaging/release checks when license status is unresolved or violates configured policy.
+- Add atlas-capacity planning and multipack spillover safeguards:
+  - compute safe atlas frame capacity with padding/extrusion/mip constraints before pack build,
+  - warn/fail on atlas overcommit and auto-spill frames to additional atlas pages when enabled.
+- Add visual review workspace improvements:
+  - thumbnail-first candidate browsing with side-by-side comparison and provenance/decision linkage.
+
+### `1.0.0` Future (General Availability / `Mythic Foundry`)
+
+- Publish compatibility matrix, migration policy, and deprecation process.
+- Formalize adapter/plugin compatibility contracts:
+  - versioned adapter I/O schema, compatibility guarantees, and deprecation path.
+- Publish security/secrets/compliance and licensing documentation.
+- Publish release operations playbook (release checklist, support runbook, onboarding path).
+- Enforce roadmap delivery traceability:
+  - require each release item to map to issue(s), PR(s), tests, and KPI deltas.

package/docs/ROADMAP_ISSUES.md

@@ -0,0 +1,244 @@
+# LootForge Prioritized Issue Backlog
+
+Last updated: 2026-03-06
+
+This list translates `docs/ROADMAP.md` into issue-ready work items with explicit acceptance criteria.
+
+Recent completion (2026-02-20):
+
+- Implemented stage-artifact contract schema coverage and fixture-pack compatibility checks.
+- Implemented provider runtime contract enforcement across OpenAI/Nano/Local with capability parity checks.
+- Implemented automated VLM candidate grading gates with score/threshold/reason traceability in eval/review.
+- Implemented edge-aware alpha-boundary scoring and configurable hard-gate rejection thresholds.
+- Implemented pack-level acceptance invariants, spritesheet continuity checks, and optional texture-memory budget gates.
+- Implemented Manifest Policy Coverage Gate:
+  - added machine-checkable policy index (`docs/MANIFEST_POLICY_COVERAGE.md`),
+  - added release gate script (`npm run check:manifest-policy`) that enforces `implemented|reserved` status and test evidence for implemented fields,
+  - added CI report artifact output (`coverage/manifest-policy-coverage.json`).
+- Implemented per-kind scoring presets and manifest-level scoring profile overrides:
+  - added deterministic default score-weight presets by target kind,
+  - added optional manifest `scoringProfiles[]` contract with per-kind overrides,
+  - validated `targets[].scoringProfile` references and normalized scoring resolution into planned targets.
+- Implemented model capability introspection contract and endpoint for provider feature gating:
+  - added service discovery contract endpoint (`GET /v1/contracts/provider-capabilities`),
+  - added runtime introspection endpoint (`GET /v1/providers/capabilities`) with provider/model query support,
+  - exposed explicit provider-gating signals for `pixel`, `highRes`, and `references`.
+
+Recent completion (2026-02-21):
+
+- Implemented template-driven pack orchestration and dependency-aware style-reference chaining:
+  - added manifest `targetTemplates[]` contract with target-level `templateId`, `dependsOn`, and `styleReferenceFrom`,
+  - enforced deterministic dependency-aware execution stages with unresolved/cycle validation,
+  - recorded effective style-reference lineage in run provenance for each generated target.
+- Implemented consistency-group drift/outlier scoring with deterministic ranking influence:
+  - added group-level CLIP/LPIPS outlier scoring across sibling targets with robust median/MAD-style normalization,
+  - emitted per-target diagnostics (`score`, `penalty`, reasons, metric deltas) in eval/review artifacts,
+  - applied deterministic outlier penalties to final ranking scores and emitted aggregate group summaries.
+- Implemented aggregate consistency-group warning controls and selection traceability:
+  - added `evaluationProfiles[].consistencyGroupScoring` controls for warning threshold, penalty threshold, and penalty weight,
+  - emitted aggregate group warning/outlier summaries (counts, warned/outlier target ids, max score, total penalty) in eval/review artifacts,
+  - added selection-lock trace fields (`evalFinalScore`, `groupSignalTrace`) so group-level ranking effects are auditable in downstream decisions.
+- Implemented bounded agentic auto-correction retries for VLM/edge hard-fails:
+  - added optional `generationPolicy.agenticRetry` controls (`enabled`, `maxRetries`) to trigger edit-first self-healing loops from failed candidates,
+  - generated critique instructions directly from VLM and edge-boundary hard-fail reasons and ran bounded edit-first regeneration attempts,
+  - recorded attempt-level before/after deltas and trigger reasons in provenance (`agenticRetry`) for deterministic auditability.
+- Implemented coarse-to-fine benchmark evidence tooling:
+  - added stage-weighted cost model utilities for run-level cost-per-approved analysis,
+  - added integration benchmark coverage proving reduced cost-per-approved at equivalent acceptance using coarse-to-fine promotion,
+  - added `npm run benchmark:coarse-to-fine` script to compare baseline/coarse provenance runs.
+- Implemented additional 2D visual QA gates for topology and animation drift:
+  - added wrap-grid topology modes (`self`, `one-to-one`, `many-to-many`) with explicit mismatch thresholds and eval diagnostics independent from seam metrics,
+  - added spritesheet continuity hard-gates for identity drift and pose drift (`spritesheetIdentityDriftMax`, `spritesheetPoseDriftMax`) with deterministic pack-invariant metrics and violations.
+- Implemented machine-checkable style-bible visual policy checks:
+  - added manifest-level style constraints (`styleKits[].visualPolicy`) for line contrast, shading bands, and UI rectilinearity,
+  - enforced deterministic acceptance/eval diagnostics with explicit per-target metrics and rejection codes.
+- Implemented layered export and matting-assisted alpha QA coverage:
+  - added deterministic layered variant exports (`__layer_color`, `__layer_matte`) with first-class manifest toggles,
+  - added matting diagnostics (`maskCoverage`, `semiTransparencyRatio`, `maskConsistency`, `hiddenRgbLeak`) and optional hard-gate thresholds in acceptance/eval artifacts.
+
+## P0 (Immediate: `0.3.0`)
+
+### 5) 2D Visual QA + Policy Follow-up Pack
+
+- **Release target:** `0.3.0` stretch / `0.4.0` bridge
+- **Why now:** Remaining visual QA gaps are still a source of production-quality drift.
+- **Acceptance criteria:**
+  - Visual style-bible policy checks are machine-checkable (line/shading/UI geometry) with explicit validate/eval diagnostics. (implemented 2026-02-21)
+  - Sprite identity and optional pose adherence checks can score/reject animation-frame drift. (implemented 2026-02-21)
+  - Tile QA validates topology rules (self/one-to-one/many-to-many adjacency) separately from seam metrics. (implemented 2026-02-21)
+  - Layered export and matting-assisted alpha QA are covered by deterministic artifact contracts and eval diagnostics. (implemented 2026-02-21)
+
+## P1 (Next: `0.4.0`)
+
+### 7) Directed Synthesis Schema + Capability Gating
+
+- **Release target:** `0.3.0` to `0.4.0` bridge
+- **Why now:** Unlock deterministic control without breaking non-local providers.
+- **Acceptance criteria:**
+  - Manifest supports `targets[].controlImage`, `targets[].controlMode`, `styleKits[].styleReferenceImages`, `styleKits[].loraPath`, `styleKits[].loraStrength`, and high-quality flags.
+  - Validation enforces path safety and enum/range constraints.
+  - Non-supporting providers emit explicit unsupported-feature warnings/errors.
+
+### 8) Local ControlNet + Dual Guidance Integration
+
+- **Release target:** `0.4.0`
+- **Why now:** Structural fidelity and edge/detail control are key differentiators.
+- **Acceptance criteria:**
+  - Local provider maps control fields to payload for Canny/Depth/OpenPose.
+  - Optional detail/edge guidance path can run alongside structural guidance.
+  - Provenance captures full control stack used per output.
+
+### 9) IP-Adapter + LoRA Local Workflow
+
+- **Release target:** `0.4.0`
+- **Why now:** Style consistency across large packs requires stronger conditioning than prompt text.
+- **Acceptance criteria:**
+  - Style reference images are sent as IP-Adapter conditioning separate from ControlNet controls.
+  - LoRA path/strength is included in local request payload and validation.
+  - Provenance captures model, IP-Adapter references, LoRA identity, and strength.
+
+### 10) 3D-to-2D Projection & Automating ControlNets
+
+- **Release target:** `0.4.0`
+- **Why now:** Drawing or gathering boundary maps manually for ControlNet scales poorly.
+- **Acceptance criteria:**
+  - Node ingest layer handles `.obj` or voxel primitives and headless rendering scripts.
+  - Configurable isometric 8-way camera array directly outputs precise Depth/Normal rasterized maps to the pipeline's ControlNet payload queue.
+  - Target output perfectly preserves the 3D footprint constraint.
+
+### 11) Semantic Animation QA + Gait Scoring
+
+- **Release target:** `0.4.0`
+- **Why now:** Current spritesheet continuity gates can reject obvious drift, but they still cannot guarantee that a strip reads as a real walk cycle with the intended lead leg, facing, and forward lean.
+- **Acceptance criteria:**
+  - `animationName: "walk"` targets are evaluated with semantic gait scoring that distinguishes believable stride phases from idle leg lifts.
+  - Facing semantics are judged against declared direction using subject-aware analysis rather than simple mirror heuristics alone.
+  - Eval/review artifacts expose semantic animation diagnostics clearly enough to explain why a walk strip passed or failed.
+
+### 12) Animation Multi-Attempt Selection + Canonical Fallback
+
+- **Release target:** `0.4.0`
+- **Why now:** Prompt tuning alone is still too stochastic for release-grade showcase capture, even with multiple attempts.
+- **Acceptance criteria:**
+  - Capture orchestration can try multiple animation-strip attempts and rank them by semantic gait, facing, and motion quality.
+  - Release showcase capture can deterministically keep a previous known-good canonical strip or locked exemplar when no fresh attempt passes.
+  - Provenance and release evidence record attempt ranking, reject reasons, and the final canonical-selection decision.
+
+## P2 (Scale-up: `0.5.0` and `1.0.0`)
+
+### 13) Quality/Latency Operating Profiles
+
+- **Release target:** `0.5.0`
+- **Why now:** Teams need predictable throughput/quality tradeoffs.
+- **Acceptance criteria:**
+  - Presets `fast`, `balanced`, and `high-fidelity` are exposed in CLI/manifest.
+  - Each preset defines candidate count, adapter pass behavior, and refinement policy.
+  - Preset behavior is documented and covered by integration tests.
+
+### 14) Golden-Set Regression Harness
+
+- **Release target:** `0.5.0`
+- **Why now:** Prevent silent quality regressions over time.
+- **Acceptance criteria:**
+  - Curated golden targets and reference expectations are versioned in repo.
+  - Nightly job computes score deltas and fails on configured regressions.
+  - Output includes calibration data for score weight tuning.
+
+### 15) Release-Grade CI and Supply-Chain Hardening
+
+- **Release target:** `0.5.0`
+- **Why now:** Public adoption requires reproducibility and security evidence.
+- **Acceptance criteria:**
+  - Coverage thresholds enforced on critical pipeline modules.
+  - Workflow actions pinned and audited.
+  - SBOM and build provenance artifacts produced for release builds.
+  - Adapter security policy checks run in CI.
+
+### 16) Visual Review Workspace
+
+- **Release target:** `0.5.0`
+- **Why now:** Human-in-loop review is a bottleneck for pack production.
+- **Acceptance criteria:**
+  - Review UI supports thumbnail grids, side-by-side candidate comparison, and quick approve/reject flows.
+  - Decisions link back to provenance, metrics, and VLM/adapters rationale.
+  - Bulk actions exist for approve-passing and reject-outlier workflows.
+
+### 17) Atlas Capacity Planning and Multipack Spillover
+
+- **Release target:** `0.5.0`
+- **Why now:** Prevent runtime sampling artifacts and failed pack builds from overfilled atlases.
+- **Acceptance criteria:**
+  - Atlas planner computes safe frame capacity using target size, padding/extrusion, and mip requirements.
+  - Pre-build validation warns or fails on frame-count overcommit for each atlas group.
+  - Optional auto-spill mode distributes overflow frames into deterministic additional atlas pages.
+  - Packaging outputs include atlas-page mapping metadata for spilled frames.
+
+### 18) Adapter/Plugin Compatibility Contract
+
+- **Release target:** `1.0.0`
+- **Why now:** Ensure long-term adapter ecosystem stability.
+- **Acceptance criteria:**
+  - Versioned adapter I/O schema and compatibility guarantees are published.
+  - Deprecation policy includes grace periods and migration guidance.
+  - Conformance tests validate adapter implementations against contract versions.
+
+### 19) First-Class Audio Generation Pipeline
+
+- **Release target:** `0.5.0`
+- **Why now:** Games need unified aesthetics spanning both visual and auditory spheres.
+- **Acceptance criteria:**
+  - Audio Target specifications support text prompts, timing instructions, and stem definitions.
+  - Pipeline connects to audio generation logic (SFX parameterized models + loop models).
+  - Implements ITU-R BS.1770 / EBU R128 loudness and true peak compliance QA.
+  - Automated loop seam Click/Warble anomaly detectors.
+  - Introduce LLM-driven generation to automatically create structured audio manifests.
+
+### 20) Generative Dependency DAG ("Asset Lineage")
+
+- **Release target:** `0.5.0`
+- **Why now:** True collection-level coherence requires downstream assets to inherit their predecessors perfectly.
+- **Acceptance criteria:**
+  - Support execution DAG where target dependencies physically block child generators until the parent target is "Locked/Approved".
+  - Auto-injection of Parent Lock artifacts into Child inference (e.g., as IP-Adapter styling).
+
+### 21) Native Engine Editor Plugins
+
+- **Release target:** `0.5.0`
+- **Why now:** Reduce workflow friction between generating an asset and verifying it physically fits a map scene.
+- **Acceptance criteria:**
+  - Godot and Unity plugins that wrap `/v1/` `serve` module endpoints.
+  - Developers can type prompts per-GameObject and directly fetch/auto-apply materials/sprites to the scene graph.
+
+### 22) Native SVG & UI Generation
+
+- **Release target:** `0.5.0`
+- **Why now:** Real UI components require cleanly separated vector layers, not just edge-traced bitmaps.
+- **Acceptance criteria:**
+  - Diffusion-driven SVG tools (e.g., LayerTracer) explicitly emit manipulatable, grouped path files.
+  - Implementation of style-reference set distillation rules for icon packs mapping.
+
+### 23) The Multimodal Style Bible
+
+- **Release target:** `1.0.0`
+- **Why now:** Massive projects require absolute guardrails guaranteeing consistency across teams.
+- **Acceptance criteria:**
+  - `styleKits` expands schema validating visual layout, palette rules, and global acoustic footprints.
+  - Validation physically halts runs whose generated artifacts violate the style bible assertions.
+
+### 24) Native 3D Asset Generation (`.gltf` / Three.js)
+
+- **Release target:** `Post-1.0`
+- **Why now:** Broaden the LootForge paradigm from purely 2D/Audio space into the lightweight web 3D ecosystem.
+- **Acceptance criteria:**
+  - Supports structural definitions and LLM parsing to synthesize 3D models directly from prompt boundaries.
+  - Pipeline explicitly emits standard web-ready formats (e.g. `.gltf` or `.glb`).
+  - Validation metrics actively enforce polygon limits, detect broken UV layouts, and ensure standardized PBR materials.
+
+### 25) Roadmap-to-Delivery Traceability Policy
+
+- **Release target:** `1.0.0`
+- **Why now:** Keep roadmap trustworthy as scope expands.
+- **Acceptance criteria:**
+  - Every roadmap item maps to issue(s), PR(s), test IDs, and KPI deltas.
+  - Release notes include traceability matrix for completed items.
+  - CI validates that merged milestone PRs reference a tracked roadmap issue.