Roadmap: remaining items from the 2026-07-03 audit

[jamesagarside]

Tracking the audit findings not yet addressed by PR #2 (which covered the rebrand, auto-restore on display change, the stale-menu fix, storage migration, installer, and repo hygiene).

v0.7 — reliability (the travel use case)

• Stable display-config keys: getDisplayConfigId() uses screen:id() (CGDirectDisplayID), which can change across reboots/reconnects — profiles can silently orphan. Re-key on screen:getUUID() with one-time migration of existing profiles. Blocks Profile visualizer UI: see your display setups, screens, and saved windows #3. ← the big remaining item
• Guard hs.spaces calls: done in Roadmap quick wins: Spaces guards, fuzzy-match fix, dead code removal, CI #14 — every call pcall-guarded; failed Space moves counted and surfaced in the restore alert.
• Verify cross-Space capture: hs.window.filter likely can't enumerate standard windows on non-visible Spaces; test empirically and either make it work or document the limitation precisely.
• Fuzzy-match edge case: done in Roadmap quick wins: Spaces guards, fuzzy-match fix, dead code removal, CI #14 — empty normalized titles score 0, fall through to app slotting; regression tests added.
• Resolve Up/Down inconsistency: done in Architecture: module split, menubar minimap, and README brand visuals #13 — the Action Registry makes divergence unrepresentable; both snap to halves, README matches.

v0.8 — proper project

• Spoon API conventions: obj:init() / obj:start() / obj:stop() (nothing can currently be torn down — watchers, hotkeys, menubar) and standard obj:bindHotkeys(mapping) via hs.spoons.bindHotkeysToSpec, keeping the base-modifier convenience as default.
• Generate docs.json from doc comments (required for the official Spoons registry).
• Module split (snap geometry / matching / storage / actions / minimap) and table-driven snap rects: done in Architecture: module split, menubar minimap, and README brand visuals #13.
• Tests: plain-Lua suite (59 tests, lua tests/run.lua) landed in Architecture: module split, menubar minimap, and README brand visuals #13 and runs in CI since Roadmap quick wins: Spaces guards, fuzzy-match fix, dead code removal, CI #14 — no Hammerspoon mock needed since the pure modules take plain tables (busted plan superseded).
• luacheck + StyLua in CI (test workflow exists; linting not yet wired in).
• Atomic profile writes (tmp + rename, keep a .bak).
• Remove the disabled drag-to-edge watcher: removed in Roadmap quick wins: Spaces guards, fuzzy-match fix, dead code removal, CI #14.
• Minor: cycle-snap uses hs.timer.secondsSinceEpoch() (Roadmap quick wins: Spaces guards, fuzzy-match fix, dead code removal, CI #14); URL handler validates profile names before switching (Roadmap quick wins: Spaces guards, fuzzy-match fix, dead code removal, CI #14).
• Minor: build hotkey config so modifier changes don't need a full hs.reload.
• CHANGELOG: landed in Release docs gate: changelog required, release notes derived from it #15, backfilled to v0.5.0, and enforced — the release workflow fails any tag without a changelog entry and builds the release notes from it.
• Community scaffolding: CONTRIBUTING, issue/PR templates, demo GIF in README (README has the story graphic + dropdown rendering from Architecture: module split, menubar minimap, and README brand visuals #13).

v1.0 — launch

• Stamp obj.version from the git tag in the release workflow — resolved the other way round in Release docs gate: changelog required, release notes derived from it #15: the workflow verifies obj.version matches the tag and fails the release otherwise, so the source of truth stays in the repo.
• Submit to the official Spoons registry; upload assets/social-preview.png in repo Settings → Social preview.
• Announce (r/hammerspoon, Show HN, etc.).

Full audit context: session of 2026-07-03; UI visualizer tracked separately in #3 (first slice — the menubar minimap — shipped in #13).