repixelizer/notes/fresh-workspace-handoff.md
2026-04-26 18:59:39 +01:00

6.7 KiB

Fresh Workspace Handoff

This is the re-entry packet for E:\Projects\repixelizer.

It is intentionally short. Historical proof belongs in git history, diagnostics, benchmark artifacts, and the distilled state/evidence.jsonl ledger; exact control flow belongs in docs/lean-optimizer-algorithm-map.md; forward planning belongs in docs/implementation-plan.md.

Rehydrate

From the repo root:

.\.venv\Scripts\python .\tools\repixelizer_state.py status
Get-Content '.\state\map.yaml'
Get-Content '.\notes\fresh-workspace-handoff.md'
Get-Content '.\docs\lean-optimizer-algorithm-map.md'
Get-Content '.\docs\implementation-plan.md'
git status --short --branch
git log --oneline -5
Get-Content '.\state\evidence.jsonl' -Tail 8

Do not trust this file for the exact live HEAD. Always check git.

Current Orientation

  • phase-field is the only live reconstruction engine.
  • The live pipeline is source -> lattice inference -> edge analysis -> phase-field reconstruction -> cleanup -> optional palette fit -> diagnostics.
  • searched lattice inference now trusts autocorrelation only; it keeps a tiny near-best lag plateau and looks for cross-axis consensus before collapsing to one lattice family. the old change-interval / pixel-walk sizing path was cut after it kept steering the badge away from the 126 family, and the projected edge-energy spectral pass was also removed after floor-hugging to 2px / 626-family aliases on the dense landscape fixture
  • The low-confidence phase rerank path is a short preview solve, not a second full optimizer.
  • the phase field now has a wider displacement budget, so moderate phase mistakes are allowed to get corrected by the field instead of relying purely on rerank ceremony
  • Cleanup is secondary and usually a no-op; the core result is supposed to come from the solver, not cleanup cosplay.
  • The current tracked weakness is the widened dark contour near the badge sword tip on tapered shapes.
  • source_structure exists because lattice-only source_fidelity could call visibly better outputs worse.
  • The old tray optimizer is dead and should stay dead unless the entire machine map changes for a real reason.
  • E:\Projects\Heimdall\docs\architecture.md is the future shared design for reusable GameCult-hosted access across experiments.
  • E:\Projects\Heimdall\docs\app-profiles\repixelizer.md is the Repixelizer-specific binding onto that future shared access layer.
  • current hosted-demo truth is still just the queue and limit machinery in src/repixelizer/gui.py plus the frontend runtime-config plumbing.
  • product strategy is hosted convenience first: keep the code open, let self-hosters suffer voluntarily, and do not burn time on native desktop packaging unless it clearly beats hosting on revenue, support, or strategy.

Critical Doctrine

  • Persistent state is the agent's mind.
  • Cut persistent memory as ruthlessly as code; stale context is bad thought, not harmless clutter.
  • Remember Jenga: growing diffs, growing notes, and growing confidence are not proof that the system still makes sense.
  • If compaction hits while source gathering or slice planning is still unpersisted, that work is gone. Re-gather it instead of pretending continuity happened.
  • Keep the machine explainable in plain language and anchored to code. If a change cannot be explained against the algorithm map, it is not ready to land.

Landed Machine

The current spine:

  • lattice inference with fixed-size and searched-size paths
  • searched lattice inference currently trusts autocorrelation only, not the rejected pixel-walk or spectral priors
  • low-confidence phase rerank through short preview reconstruction
  • edge analysis feeding one projected displacement-field optimizer with a wider displacement leash
  • nearest-source final sampling from uv0_px + disp_t
  • cleanup, optional palette fit, diagnostics, compare mode, tuning, and GUI observer events on the live path
  • source_structure plus source_fidelity in run summaries and comparisons
  • focused sword-tip fixture in tests/fixtures/real/ai-badge-tip-focus.json

The exact current control flow is documented in docs/lean-optimizer-algorithm-map.md.

Boundaries

  • Do not reintroduce tray optimizers, candidate sets, portrait layers, or multi-stage solver religions casually.
  • Do not trust a metric win that makes the image look worse.
  • Do not let cleanup become the real solver.
  • Do not let state/evidence.jsonl turn into an activity feed.
  • Do not restart broad exploratory surgery when the current weak spot is still one bounded tapered-contour blemish.
  • Do not drift into desktop-app fantasies just because the web GUI is nice now. The default commercial path is still hosted access.

Verification Guardrails

  • For scaffolding or note changes, run the repo-local state helper and compaction helper.
  • For Python changes, run:
.\.venv\Scripts\python -m pytest -q
  • For solver behavior changes, reproduce the pinned badge case from docs/implementation-plan.md, inspect the sword-tip focus fixture, and compare both the image and source_structure.

Persistent State Hygiene

Rules now in force:

  • state/map.yaml is canonical current truth.
  • state/scratch.md is disposable scratch.
  • state/evidence.jsonl is a distilled durable belief ledger.
  • tools/repixelizer_prepare_compaction.py is the pre-compaction persistence check; run it before and after imminent-compaction persistence passes.
  • this handoff is a compact re-entry packet.
  • docs/implementation-plan.md is the forward plan.
  • docs/lean-optimizer-algorithm-map.md is the source-grounded control-flow map.
  • E:\Projects\Heimdall\docs\architecture.md is future shared auth/access design, not live implementation truth.
  • E:\Projects\Heimdall\docs\app-profiles\repixelizer.md is the app-specific future binding, also not live implementation truth.
  • local docs/gamecult-hosted-access-architecture.md and docs/repixelizer-hosted-access-profile.md are redirect stubs.

Do not let any one note become all of those things. That is how the tower grows sideways and starts calling itself architecture.

Next Real Move

Do not continue implementation automatically from a rehydrate-only request.

If the user asks to continue, the current next move is to take one bounded hypothesis for tapered-contour behavior in src/repixelizer/phase_field.py, check it against the pinned badge case and tests/fixtures/real/ai-badge-tip-focus.json, and revert it if the visual result or source_structure does not clearly improve.

Immediate Re-entry Instruction

After compaction, first rehydrate and reorient from the listed files and git state. Do not continue implementation merely because the state names a next move. Wait for the user's next instruction unless they explicitly say to continue.