AGENTS.md now holds the instructions and CLAUDE.md and GEMINI.md are
pointers to it. Three files of instructions become three files that
disagree; one file every agent reads cannot.
The content is reorganised rather than rewritten, into: the invariants,
the guards that fail the build, the validation this codebase deliberately
does not perform, the environment, and where to read next. Every guard
now names the test that catches it, and the two rules with no test behind
them are called out as such, because "only review catches this" is
information the reader needs.
Restructuring surfaced one rule that was missing here entirely — sw.js
must stay unhashed and be served no-cache — which had only ever been
written down in ARCHITECTURE.md.
Dropped: the `bun init` boilerplate code samples. Every rule they carried
is still stated; the hello-world test and the three frontend snippets are
not.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
ARCHITECTURE, PRODUCT and TODO move out of the repository root, and
docs/superpowers/{specs,plans} flattens to docs/{specs,plans}:
"superpowers" names the tool that wrote those documents, not a kind of
document.
No content changes. This commit is the move, plus the roughly thirty
cross-references the move invalidated.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Sub-project 2 of 4 of the visual redesign. Spec in
docs/superpowers/specs/2026-09-02-month-view-design.md; the owner chose
each of the three directions from concrete alternatives.
Three problems, all found by looking at the rendered page rather than at
the code:
- The totals block was four peer figures with no relationship between
them, and the income *input* sat in the same visual register as three
numbers derived from it. Nothing answered PRODUCT.md's second question
at the month level: with Transport at -3,200 you had to read down the
Remaining column to find out. It now reads income -> allocation meter
-> spend, with the overspent-post count stated in both directions.
- The carry meter rendered 21px below its own row and 22px above the
next, so it read as a divider rather than as a property of a post. One
tbody per post now holds the figures AND their meter, which is both
what pulls it tight under its own row and the only way to hover the
pair as one block.
- Phone width was broken and nothing recorded it: the 5-column table
overflowed at 390px with Spent and Remaining off-screen, and every
figure wrapped its currency onto a second line. Below sm: each post is
now a two-line block, and the currency is stated once in the legend
because every figure in that table is base currency.
Meter geometry moves to src/ui/meterSegments.ts, pure and tested, with
<Meter> as the only thing that paints it. The allocation meter scales to
max(income, allocated) so over-allocating overflows instead of capping
at a full bar — over-budget is always allowed, so it has to be drawable.
Negatives clamp rather than invert: a segment of negative width puts the
gradient's stops out of order, which paints something arbitrary instead
of failing.
Rejected: one reflowing CSS grid carrying role="table". It deduplicates
the markup, but at 390px the layout genuinely is not a table any more,
and table roles would describe rows and columns to a screen reader that
no longer exist on screen.
Verified: 443 tests, tsc clean, build clean, and read in both themes at
1280px and 390px. Not verified, because it is not verifiable here —
whether it reads better than what it replaced.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Two things this session depended on lived only in a scratchpad, so the next
agent would have had to reinvent them from a prose hint:
- scripts/screenshot-fonts.conf, now applied by screenshot.ts itself. Without
it this container renders every generic font family as Fira Code and the UI
looks monospaced in a way no user sees — a trap that nearly produced a "fix"
for a font bug that does not exist.
- scripts/demo-data.ts, which seeds a visibly synthetic dataset. Without it
every screenshot shows an app full of zeros, because Chrome starts from a
fresh profile each run.
CLAUDE.md now carries the two-command recipe verbatim instead of "point
FONTCONFIG_FILE at an override", and says why --reload is mandatory. Verified
from a clean shell with no environment set.
Also flags docs/superpowers/plans/2026-09-01-budget-app.md as a historical
record: its snippets still show CURRENCIES and CURRENCY_DIGITS, which no
longer exist, and an agent reading it as current would be misled.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Records why the brand teal is --primary rather than --accent, why @font-face
cannot live in the bundled stylesheet (measured: 70 KB -> 303 KB of
render-blocking bytes, and unicode-range subsetting defeated), why the theme
preference is not in the dataset, and the carry-meter regression that earned
the undefined-token guard.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Six tasks. Task 1 is deliberately large because the model change is atomic
under TypeScript: Post.standingRule -> Post.rules will not compile as a partial
change, so everything referencing it moves together, with the settings UI
getting only a read-only summary until Task 5.
Self-review closed two spec requirements that had no test: a version dated
before the fold start is legal but inert, and an archived post still resolves
its rules because it still folds.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
A post's allocation rule becomes a dated series: a version takes effect in its
month and continues until the next replaces it. Per-month overrides survive
alongside as one-month exceptions, because collapsing the two loses the
distinction between a permanent change and a temporary one.
A post with no version yet allocates zero rather than applying its earliest
rule backwards, which would invent budget for months never budgeted and let
the rollover fold carry that fiction forward.
Requires the project's first real migration (schemaVersion 1 -> 2). It is a
pure shape change and behaviour-preserving by construction, and the spec makes
that a tested property rather than an assumption: every month's allocation must
be identical before and after.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Three entry-form changes specified together because they share the same tab
order: keyboard-driven bulk rows, purchases that no longer demand a day, and
an optional note per purchase.
Records why the date change widens IsoDate rather than splitting it into
month + optional day: the split is the better model but changes a type every
layer depends on and needs a migration run in the browser against the user's
only copy of their data, for an identical user-visible outcome. Verified that
monthOf() already parses both date shapes and still rejects out-of-range
months.
Time-versioned allocation rules are explicitly out of scope and get their own
cycle.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
25 TDD tasks across five phases: foundation, pure domain core, IndexedDB
persistence, JSON/ODS export, UI, and shipping (PWA + Docker + CI).
Self-review caught five defects, fixed inline:
- distributeByWeight divided by zero on all-zero weights, which a
zero-total purchase reaches and which would take the whole fold down
- summaryView's fold binding needed an explicit type or CI typecheck fails
- a duplicated module import in registerSw.ts
- a shell render test that would break once its routes read the store,
since happy-dom has no IndexedDB
- an unreadable assertion in the ODS numeric-cell test
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Design for a personal budgeting PWA replacing a spreadsheet workflow.
Key decisions captured:
- Static SPA, no backend in the data path, so it deploys to both GitHub
Pages and a self-hosted Docker image from one build artifact
- Bun toolchain (bun init --react=shadcn); no Vite, no Electron
- Pure derivation core over an IndexedDB fact store; envelope rollover
makes caching worthless, so every figure is folded from raw facts
- One Purchase entity covers simple, split, and financed purchases, which
is what lets splits and finance plans compose without special-casing
- Money is a float, with mandatory rounding at boundaries and last-part-
by-subtraction so distributed parts sum exactly to the whole
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
