7.4 KiB
7.4 KiB
Modernization Debt Log
Status: live Last updated: 2026-06-01
Every shortcut, temporary adapter, retained vendored dependency, skipped platform gate, compatibility shim, or incomplete automation path must be recorded here before it lands. Entries must be specific enough for a future agent or engineer to remove them without reconstructing context from chat.
Entry Rules
- Add an entry before merging the shortcut.
- Reference the debt id in code comments, TODOs, ADRs, or roadmap notes.
- Include an owner, reason, validation command, and removal condition.
- Do not close an entry until the removal condition is met and validated.
- Prefer deleting shortcuts over expanding this log.
Open Debt
| ID | Status | Owner | Item | Reason | Validation | Removal Condition |
|---|---|---|---|---|---|---|
| DEBT-0001 | Open | Modernization | Existing platform build files remain alongside new CMake | Required for incremental migration without losing platform coverage | Existing platform builds plus new CMake configure | Remove after all platform builds consume shared CMake targets |
| DEBT-0002 | Open | Modernization | Vendored SDK and patched libraries retained initially | Some dependencies are SDK-only, patched, or have platform-specific binaries | Dependency inventory and platform build smoke tests | Replace with vcpkg packages or document permanent vendored status after triplet evaluation |
| DEBT-0003 | Open | Modernization | Existing singletons remain during initial split | Avoid behavior changes while introducing component boundaries | App launch and component tests | Replace singleton reaches with context/service injection at component boundaries |
| DEBT-0004 | Open | Modernization | Android, Linux, WebGL, Apple, and AppX build files remain platform-specific until root CMake alignment reaches them | Prevent platform regressions during incremental migration; raw Windows .sln/.vcxproj files were removed on 2026-05-31 by user decision |
cmake --preset windows-msvc-default; platform-specific configure/build smoke checks as each platform is migrated |
Root CMake owns every platform source list and package path |
| DEBT-0005 | Open | Modernization | Temporary local CTest harness is used before Catch2 is wired through vcpkg | vcpkg is not currently on PATH, but headless tests need to run now |
ctest --preset desktop-fast --build-config Debug |
Replace tests/test_harness.h tests with Catch2 tests once vcpkg toolchain/presets are validated |
| DEBT-0007 | Open | Modernization | vcpkg.json and windows-msvc-vcpkg-headless are validated for the headless Windows component matrix, but app targets still use vendored libraries and Android/Apple triplets are not proven |
Dependency migration must stay incremental while SDK/patched/vendor dependencies remain in use | $env:VCPKG_ROOT="C:\Program Files\Microsoft Visual Studio\2022\Community\VC\vcpkg"; cmake --preset windows-msvc-vcpkg-headless; ctest --preset desktop-fast-vcpkg --build-config Debug |
Component targets consume vcpkg packages where reliable and desktop app, Android, and Apple triplets are validated or explicitly documented as permanent vendor exceptions |
| DEBT-0008 | Open | Modernization | windows-msvc-default preset is used for local validation because the VS 2026 generator is not installed here |
The target VS 2026 preset must remain, but this machine configures with Visual Studio 17 2022 | cmake --preset windows-msvc-default; ctest --preset desktop-fast --build-config Debug |
Validate windows-vs2026-x64 on a machine with Visual Studio 2026 installed and make it the default Windows validation preset |
| DEBT-0009 | Open | Modernization | Android root CMake validation currently builds headless targets only, not APK/package variants | Platform app entrypoints still live in legacy Gradle/CMake projects and need Phase 6 alignment | powershell -ExecutionPolicy Bypass -File scripts\automation\platform-build.ps1 -Presets android-arm64 |
Android standard, Quest, and Focus/Wave package targets consume shared component targets and have package smoke commands |
| DEBT-0010 | Open | Modernization | pp_document is a pure layer/frame/document/undo-history model but is not yet wired to legacy Canvas, PPI load/save, selection masks, or legacy action commands |
Keep extraction incremental while preserving app behavior | ctest --preset desktop-fast --build-config Debug; pano_cli create-document --width 64 --height 32 --layers 2 |
Legacy document behavior is represented by pp_document tests and the app consumes it through a boundary/facade |
| DEBT-0011 | Open | Modernization | package-smoke validates the Windows CMake app artifact only, not AppX/APK/Apple/WebGL package outputs |
Platform package targets are not migrated to root CMake yet | powershell -ExecutionPolicy Bypass -File scripts\automation\package-smoke.ps1 -Preset windows-msvc-default -Configuration Debug |
Package-smoke covers Windows AppX, Android APK variants, Apple bundles, and WebGL output where local toolchains are present |
| DEBT-0012 | Open | Modernization | pp_ui_core uses vcpkg tinyxml2 on windows-msvc-vcpkg-headless, but retains pp_vendor_tinyxml2 for default and unproven platform presets |
Mobile/AppX/Apple triplets and app packaging still need validation before removing the vendored fallback | ctest --preset desktop-fast-vcpkg --build-config Debug; ctest --preset desktop-fast --build-config Debug; powershell -ExecutionPolicy Bypass -File scripts\automation\platform-build.ps1 -Presets android-arm64 |
All supported presets consume vcpkg tinyxml2 or document a permanent vendored exception |
| DEBT-0013 | Open | Modernization | pp_assets and pano_cli inspect-project validate the fixed PPI header, thumbnail/body byte layout, body summary, and dirty-face PNG payload metadata, but do not yet deserialize layer face PNG pixels into document/layer/frame data |
Full PPI parsing requires staged extraction of legacy Canvas serialization and image/layer payload handling |
ctest --preset desktop-fast --build-config Debug; pp_assets_ppi_header_tests; pano_cli_inspect_project_layout_smoke |
Full PPI load/save fixtures cover thumbnail, decoded layer face payloads, frames, metadata, corrupt payloads, and round-trip compatibility |
| DEBT-0014 | Open | Modernization | windows-clangcl-asan now configures as a headless Ninja/clang-cl preset and uses the release MSVC runtime required by ASan, but local builds still fail because installed clang-cl 18.1.8 is paired with VS 2026-preview STL headers that require Clang 20 or newer |
Sanitizer validation should be local and repeatable, but this machine's compiler/header pairing is incompatible | cmake --fresh --preset windows-clangcl-asan; cmake --build --preset windows-clangcl-asan --target pp_foundation |
Install/use Clang 20+ with the VS 2026 STL, or point the preset at a compatible VS 2022 toolchain, then make platform-build.ps1 -Presets windows-clangcl-asan pass for the headless matrix |
Closed Debt
| ID | Status | Owner | Item | Reason | Validation | Removal Condition |
|---|---|---|---|---|---|---|
| DEBT-0006 | Closed | Modernization | pano_cli create-document validates and emits JSON command contracts but does not yet invoke the legacy document/app model |
The document model had not been extracted from Canvas/App yet |
ctest --preset desktop-fast --build-config Debug; pano_cli_create_document_smoke |
Closed on 2026-05-31: command now constructs a real pp_document::CanvasDocument |