backend-infra-engineer: Release v0.3.3 snapshot

docs/internal/roadmaps/2025-11-modernization.md

@@ -0,0 +1,46 @@
+# Modernization Plan – November 2025
+
+Status: **Draft**  
+Owner: Core tooling team  
+Scope: `core/asar_wrapper`, CLI/GUI flag system, project persistence, docs
+
+## Context
+- The Asar integration is stubbed out (`src/core/asar_wrapper.cc`), yet the GUI, CLI, and docs still advertise a working assembler workflow.
+- The GUI binary (`yaze`) still relies on the legacy `util::Flag` parser while the rest of the tooling has moved to Abseil flags, leading to inconsistent UX and duplicated parsing logic.
+- Project metadata initialization uses `std::localtime` (`src/core/project.cc`), which is not thread-safe and can race when the agent/automation stack spawns concurrent project creation tasks.
+- Public docs promise Dungeon Editor rendering details and “Examples & Recipes,” but those sections are either marked TODO or empty.
+
+## Goals
+1. Restore a fully functioning Asar toolchain across GUI/CLI and make sure automated tests cover it.
+2. Unify flag parsing by migrating the GUI binary (and remaining utilities) to Abseil flags, then retire `util::flag`.
+3. Harden project/workspace persistence by replacing unsafe time handling and improving error propagation during project bootstrap.
+4. Close the documentation gaps so the Dungeon Editor guide reflects current rendering, and the `docs/public/examples/` tree provides actual recipes.
+
+## Work Breakdown
+
+### 1. Asar Restoration
+- Fix the Asar CMake integration under `ext/asar` and link it back into `yaze_core_lib`.
+- Re-implement `AsarWrapper` methods (patch, symbol extraction, validation) and add regression tests in `test/integration/asar_*`.
+- Update `z3ed`/GUI code paths to surface actionable errors when the assembler fails.
+- Once complete, scrub docs/README claims to ensure they match the restored behavior.
+
+### 2. Flag Standardization
+- Replace `DEFINE_FLAG` usage in `src/app/main.cc` with `ABSL_FLAG` + `absl::ParseCommandLine`.
+- Delete `util::flag.*` and migrate any lingering consumers (e.g., dev tools) to Abseil.
+- Document the shared flag set in a single reference (README + `docs/public/developer/debug-flags.md`).
+
+### 3. Project Persistence Hardening
+- Swap `std::localtime` for `absl::Time` or platform-safe helpers and handle failures explicitly.
+- Ensure directory creation and file writes bubble errors back to the UI/CLI instead of silently failing.
+- Add regression tests that spawn concurrent project creations (possibly via the CLI) to confirm deterministic metadata.
+
+### 4. Documentation Updates
+- Finish the Dungeon Editor rendering pipeline description (remove the TODO block) so it reflects the current draw path.
+- Populate `docs/public/examples/` with at least a handful of ROM-editing recipes (overworld tile swap, dungeon entrance move, palette tweak, CLI plan/accept flow).
+- Add a short “automation journey” that links `README` → gRPC harness (`src/app/service/imgui_test_harness_service.cc`) → `z3ed` agent commands.
+
+## Exit Criteria
+- `AsarWrapper` integration tests green on macOS/Linux/Windows runners.
+- No binaries depend on `util::flag`; `absl::flags` is the single source of truth.
+- Project creation succeeds under parallel stress and metadata timestamps remain valid.
+- Public docs no longer contain TODO placeholders or empty directories for the sections listed above.