docs/superpowers/plans/2026-09-06-appearance-merge-review.md

Ref: main worktree-web-client-spec   Size: 2.7 KiB   History

# Appearance branch review before merge

Scope: `main` at `bb91afde` through `ui-exploration` at `6c341990`, covering all
three appearance slices, the QUIC shutdown prerequisite, tests and delivery docs.
The user requested review, correction of findings, merge, then a fresh worktree
for GUI/TUI parity. Appearance demos are approved; ligatures remain deferred.

## Review and fixes

Terra reviewed CLI/config/theme ownership, strict parsing, precedence, diagnostics,
defaults and render integration. Luna reviewed the combined font/render changes
against main, including scale rebuilds, selected-family lifetime, monospace
validation and framebuffer oracles. Root reviewed build/native gate wiring,
QUIC shutdown ordering, the full scope and integration evidence. Neither agent
found an actionable production regression. Root corrected two stale claims:

- `CLAUDE.md` now lists config/theme under the native rendering module.
- `Server.quicListener` now accurately documents teardown: notify peers through
  the accessor, close client sinks, then free only the owned listener. Its old
  comment said deinit did not call the accessor, contradicted by the shutdown fix.

No runtime behavior changed during this review. CONNECTION_CLOSE still occurs
before client sinks free their connection state; borrowed listener destruction
remains the caller's responsibility. Existing QUIC close tests and the real
session-stop integration exercise the underlying behavior.

## Validation

Fresh review logs live in `dist/appearance-merge-review/` in the appearance
worktree. Full `make ci` passed (check, terminal integration, agent and
throughput), as did the final `make check` after the comment correction. Native
build/units/core and full native integration passed, including font/config/theme
cases. No gate or timeout was relaxed. The only source edit during these gates
was the documentation comment above; runtime code remained frozen.
The original appearance delivery record retains the actual NVIDIA demos, scale
checks and default/configured stress passes. Those apply to the unchanged runtime
behavior; this review does not claim a new GPU measurement or macOS validation.
Earlier intermittent NVIDIA misses and offscreen-growth captures remain open.

## Handoff

Fast-forward main only after final checks, preserving its staged
`RETRO.pre-native-merge.md` byte-for-byte and in the index. Retain the appearance
worktree because it holds the private review pages and evidence. Create a new
`gui-wheel-scrolling` worktree from merged main, with a bounded plan for issue
`8b16e26b`: pane wheel history, app-mode wheel input and stale-reply handling.
Wheel implementation and its demo are a subsequent functional delivery.