Gladius

A plan before any code

The first commit was a written spec, a staged build plan and the project's documentation, with no application code. Studying the original showed it was a single sheared horizontal strip, not the grid the brief had assumed. Highlighting a tile would never touch the desktop; only an explicit pick sets a wallpaper, which avoids registry churn and any restore logic.

Brian's call A faithful port of the strip over a grid that might have been more practical for a large collection. Fidelity to the original was the product; a grid was parked as a later idea.

Two unknowns spiked first

Two questions could have forced design changes, so they were tested before the build. Windows' documented backdrop API reported success but painted a flat grey panel on this kind of window, so an older undocumented call that produces real blur won, with its tint lightened so the blur stays visible. A plain tool-window flag turned out to be enough to keep the komorebi tiling manager from grabbing the overlay, so Gladius edits no other tool's config.

Method Blur was judged by measuring high-frequency detail in captured frames, not by return codes, because the losing API reports success.

Built bottom-up, one stage per commit

Config, then the folder scan and thumbnail cache, then the wallpaper setter, the command line, the strip, the overlay window and the settings panel, each in its own commit. The thumbnail cache was keyed by path, modification time and size, which fixed the original's stale-thumbnail, blank-first-run and filename-collision bugs at the root. The scroll and layout constants were carried over from the original because they are why the strip feels the same.

Method Pure logic was written test-first; the GUI stages were checked by driving the real widgets with synthetic input events.

Hardened for machines it never ran on

Because strangers would run it on other hardware and heavily customised Windows setups, a pass beyond the planned scope covered failures that would be invisible on the build machine. Thumbnail resolution now tracks the display so 4K panels stay sharp, the hand-edited config file is treated as hostile input that degrades to defaults instead of failing, and an empty wallpaper folder shows a dialog instead of a hotkey that silently does nothing. Random mode stays dialog-free so an unattended logon task can never hang on a modal box.

A wallpaper that reported success and never appeared

During acceptance, converted images set under a Microsoft Store install of Python returned success while the desktop kept the old wallpaper. Store-packaged apps have some file writes redirected into a private folder, and Windows reads the wallpaper from outside that sandbox, so the path it was given pointed at nothing. Resolving the real path before handing it to Windows fixed it, at the cost of one call.

Live acceptance under komorebi

All eight acceptance criteria passed, with the overlay summoned by the real hotkey while komorebi was running. A warm launch measured 0.30 seconds against a 1.5-second budget, and a cold run generated 72 thumbnails behind placeholders. The record states which checks were driven by synthetic events and which were done live, since synthetic input cannot prove the system delivers real keystrokes to the window.

Method Whether Windows actually took each image format was confirmed from Windows' own record of the file it last used, not the API's return value.

Public release gated behind living with it

With v1 complete, the planning documents were distilled into the permanent docs and deleted, each part checked to have a home first. A shakedown phase of daily use was added between acceptance and release, because a scripted run cannot judge how a wallpaper picker feels. Old commits still held machine-specific paths, so cleaning the history was recorded as a step before going public.

Brian's call Hold the repository private until real-world use had shaken out the annoyances a test run cannot reach.

A version, and an update check off the launch path

Gladius had no version string at all, so one became the single source for the command line, the build and the update check. The overlay only reads a small cached file; the network check runs after the window is up, at most once a day, and can only affect the next launch. A newer version shows as one quiet footer line naming the right upgrade command, and Gladius never updates itself.

One build for every channel

The app is packaged as a zipped folder bundle rather than a single self-extracting exe, which would unpack itself on every launch and cost seconds. The bundle started in 0.26 seconds, faster than running the script directly, and needs neither Python nor admin rights. The same zip serves winget, Scoop and a manual download, which also puts it in UniGetUI; Chocolatey was skipped for now because its per-version moderation suits a settled release, not a v1 still in testing.

Method The Scoop manifest is generated by the release pipeline from the hash of the file it just uploaded, so it cannot disagree with what people download.

An icon taken from the app

The packaged exe had a default icon and a blank Properties pane. The new icon is three tiles sheared at the same angle as the strip, the middle one selected in the default border colour, built as a real multi-size icon file, and the exe now carries product, version and licence details.

The release pipeline, proven without a release

The release workflow ran green twice on manual runs: tests, build, an exe smoke test and a 46 MB artifact matching the local build. Its actions were moved off a runtime the build servers were deprecating, so the problem would not surface on a release day. The tag-triggered half, which publishes the release and fills the Scoop bucket, cannot be rehearsed without cutting a real release and was recorded as the part to watch.

History scrubbed, the source made public

Every commit was rewritten to replace machine-specific paths with placeholders, and the repository was recreated so no pre-rewrite version is reachable; a secret scan over the full history came back clean. The pre-publish check had already separated the two kinds of name in the repo: the author's name on the licence and manifests is meant to be public, while machine paths had to be zero. The source went public under MIT. The first tagged release, a test on a second machine without Python and the winget submission are still ahead.