m038andClaude Opus 5
8202d2a257
Five weeks of undocumented evolution left the docs describing a site that
partly no longer exists, with nothing marking which documents were historical.
The code is treated as the source of truth throughout; every claim below was
verified against code, config or the Makefile rather than inferred.
Two mechanisms, following patterns the repo already used:
- docs/reference/superseded-decisions.md (new) — one authoritative table of all
14 reversals: what was planned, where, what is true now, when, and why. Plus
a short list of decisions that were NOT reversed, since their planning docs
are old enough to look suspect.
- Inline "> **Superseded ...**" notes at each stale claim, so a claim can never
be read un-corrected. This mirrors the existing "> History:" notes in
architecture.md and "> **Changed 2026-07:**" in trip-switching.md.
Scope split by tense: present-tense docs (CLAUDE.md, reference/, guides/,
README.md, CONCEPTS.md) are corrected; past-tense records (plans/, specs/,
milestones/, summary.md, pm-analysis.md) are annotated only, never rewritten —
their staleness is what makes them records.
Present-tense corrections:
- CLAUDE.md asserted css-compiled/ is generated from css/style.css and
css/tokens.css. That source relationship does not exist: css/ is hand-authored
and served directly via assets.addCss in partials/base.html.twig, while
css-compiled/ is esbuild output from the CSS imports inside js/src/*.js.
Highest-severity finding — an always-loaded file inviting a hand-edit of a
generated bundle.
- README.md documented every remote-* target without the -test/-prod suffix
guard-env requires, so its entire server runbook was unrunnable, and listed
7 of ~20 targets while CLAUDE.md designates it authoritative for the full
list. Rewritten with all targets, grouped, and the suffix rule stated.
- README.md told readers to "git clone" into user/, which is a submodule.
- architecture.md: nav is Home + Trips + (authenticated) New Post, not
"Home + Past Trips only"; template tree omitted trips.html.twig,
post-form.html.twig and forms/, and placed base.html.twig at templates/ root
rather than in partials/; entry-actions has three API routes, not just delete;
added the undocumented css-compiled/maplibre-gl.css output and a section on
the /post pin editor as the one sanctioned non-entry-map map.
- design-system.md: documented 13 colour tokens against 19 in tokens.css
(missing --color-error, --color-draft-accent and four glass overlays); claimed
"all 3 map templates"; and described --color-canvas as "white".
- design-system-light.md documented a light palette in present tense. No light
mode exists — tokens.css has a single :root block, no prefers-color-scheme or
data-theme switch, and no light hex appears in css/. Banner added.
- posting.md said photos were optional; they are required, 1-6. It documented
hero_image, which was removed for entries (stories keep it). It had no mention
of the frontend edit flow or photo editor, both shipped 2026-07-08. Photo
files are photo-01..NN, zero-padded.
- working/README.md advertised summary.md as the project's "current state" while
summary.md describes Leaflet, /tracker, /map and /stats. Most misleading line
in the tree.
- CLAUDE.md: recorded js/src/location-map.js as the one sanctioned exception to
the single-map-path rule, and documented that make start/setup fail on a clean
checkout because docker-compose.yml still builds a travel-memories service
whose source moved out in a80b0a9.
Also: 2026-07-23-post-form-location-override.md read "Not started" while merged
in user/ as dd19995; status corrected.
Findings that are not documentation problems — the compose breakage, a
repeatable drift check, the unused shortcode-gallery-plusplus, and demo fixtures
for retired views — are collected in
docs/working/2026-07-25-doc-drift-recommendations.md and deliberately not acted
on. Design and verification method: docs/working/specs/2026-07-25-docs-reconciliation-design.md
The submodule gitlink is deliberately not bumped.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
8.0 KiB
8.0 KiB
Superseded decisions
Things this project planned, built, and then deliberately reversed. One row per reversal.
Why this file exists. The plans and milestones under docs/working/ are historical records — they
say what was decided then, and they are correct as records. But a reader who opens
milestones/milestone-2.md finds a confident present-tense description of a Leaflet /map page that
has not existed since 2026-07-04. This file is the changelog of "what did we change our mind about",
so that question has one answer instead of requiring a re-derivation from the code.
How to use it. Each superseded section in the old docs carries a > **Superseded …** note
pointing back here. If you are about to re-create something you found in an old plan, check here
first — the reversal is usually deliberate, and several are load-bearing rules in
CLAUDE.md.
Keep it current. When a decision is reversed, add a row in the same commit as the reversal. A ledger that lags is worse than no ledger, because it is trusted.
The reversals
| # | Originally planned | Planned in | True now | Changed | Why |
|---|---|---|---|---|---|
| R1 | A standalone /map page — full-height Leaflet map, marker per entry, popups |
milestones/milestone-2.md (whole doc); summary.md |
No /map route. The map renders inline on the trip page through the single shared partials/entry-map.html.twig |
2026-07-04 | plans/2026-07-04-standalone-page-cleanup.md. One consolidated trip page beat four thin views; a separate map page meant a second map implementation to keep in sync |
| R2 | A standalone /stats page — days on the road, entries, countries, distance |
milestones/milestone-3.md (whole doc); summary.md |
No /stats route. Stats render inline on the trip page behind a toggle, via initTripStats() |
2026-07-04 | Same cleanup. The numbers are trip context, not a destination |
| R3 | A /tracker feed route as the entry list |
milestones/milestone-1.md §1.6; milestone-2.md; milestone-3.md; summary.md |
No /tracker. The feed is the trip page plus the home active-trip view, sharing partials/trip-feed-col.html.twig |
Restructured 2026-06-19 (plans/2026-06-19-trip-entity.md), fully retired 2026-07-04 |
The Trip entity became the organising unit, so a global tracker had nothing to track |
| R4 | Leaflet.js with OpenStreetMap tiles | milestone-2.md; milestone-4.md; summary.md; pm-analysis.md |
MapLibre GL JS, CartoDB dark-matter basemap. Style URL is single-sourced as MAP_STYLE in js/src/map-style.js |
2026-06-20 | plans/2026-06-19-maplibre-migration.md. Vector tiles, GPU rendering, and a dark basemap that suits the dark theme |
| R5 | A standalone /dailies journal view and /stories story view |
plans/2026-06-19-trip-entity.md era |
Both routes retired. 01.dailies/ and 04.stories/ survive as routable:false data containers whose children the trip page aggregates |
2026-07-04 | Same cleanup. The folders are load-bearing — retiring a view must never delete its container (see CONCEPTS.md → Container) |
| R6 | Site nav "Journal · Map · Stats" | summary.md |
Home · Trips, plus New Post when authenticated (partials/base.html.twig:27-31) |
Sub-views retired 2026-07-04; "Past Trips" renamed "Trips" 2026-07 (6cf5092) |
Nav should not link to views that no longer exist |
| R7 | hero_image frontmatter on entries, to pin a feed-card hero |
milestone-1.md §1.6; summary.md; pm-analysis.md |
No hero_image field on journal entries. The hero is the first uploaded photo (entry-journal.html.twig uses entry.media.images|first). Photo order is owner-controlled, so an explicit filename was redundant. Stories still use hero_image |
2026-07 | plans/2026-07-05-photo-editor-media-api.md gave the owner drag-reorder over photos, which made "first photo" a deliberate choice rather than an accident |
| R8 | Photos optional on an entry | milestone-1.md §1.5; guides/posting.md (pre-2026-07-25) |
Photos are required — minimum 1, maximum 6 (post-form.md:35-46, enforced in post-form.js initValidation) |
2026-07 | plans/2026-07-04-journal-post-form.md. Photos come first in the form because they anchor what you write |
| R9 | A light-mode colour palette alongside dark | reference/design-system-light.md (whole doc); plans/2026-06-19-dark-mode.md |
Dark only. css/tokens.css has a single :root block; there is no prefers-color-scheme or data-theme switch, and no light-palette hex appears in css/ |
2026-06-20 | Dark mode shipped as the theme, not as one of two. The light palette was the pre-dark-mode original and was never re-implemented as a switchable theme |
| R10 | shortcode-gallery-plusplus as the entry photo gallery |
pm-analysis.md |
Galleries are PhotoSwipe, wired in js/src/main.js against .pswp-gallery markup emitted by partials/entry-journal.html.twig. No [gallery] shortcode is used anywhere in templates/ or pages/ |
2026-06-21 (30c8937, "replace custom lightbox with PhotoSwipe v5") |
A lightbox the theme controls beat a plugin's markup. ⚠️ The plugin is still listed in plugins.txt with no consumer — see recommendations |
| R11 | travel-memories as an in-repo service on :8082, built from ./services/travel-memories |
plans/2026-06-21-travel-memories.md; specs/2026-06-21-travel-memories-design.md; working/2026-06-21-travel-memories-handover.md |
Extracted to a separate project. services/ is gitignored and the source is absent from this repo |
a80b0a9 — "remove travel-memories service from repo (moved to separate project)" |
It was an independent Flask app with its own lifecycle. ⚠️ docker-compose.yml still declares the service, so make start fails on a clean checkout — see recommendations |
| R12 | Three map template variants (feed-map.html.twig partial with inline init, plus full-page map.html.twig) |
pre-2026-06-27 templates | One display map path — MapUtils.initEntryMap() in js/maplibre-utils.js, invoked through partials/entry-map.html.twig |
Consolidated 2026-06-27, variants deleted 2026-07-04 | plans/2026-06-27-map-init-consolidation.md. Three implementations drifted apart |
| R13 | A single map code path, no exceptions | CLAUDE.md (pre-2026-07-25 wording) |
One display path (R12) plus one sanctioned editor — js/src/location-map.js for the /post pin picker: one draggable marker, no popups/GPX/bounds, maplibre-gl lazy-imported. Shares only MAP_STYLE with the display path |
2026-07-24 (dd19995) |
plans/2026-07-23-post-form-location-override.md. An editor map has none of a display map's concerns; folding them together would have compromised both |
| R14 | post-form.md carries a static pageconfig.parent naming the write target |
pre-2026-07 form config | No parent in post-form.md. cache-on-save derives it from site.active_trip at submit time |
2026-07 | The two settings silently desynced. Never re-add it — this is a hard rule in CLAUDE.md |
Decisions that were not reversed
Worth stating, because their planning docs are old enough to look suspect:
- The SKIP list in
pm-analysis.mdstill holds. Background GPS tracking, followers, comments, social discovery, reactions, trip reels, 3D flyover, printed books, and AI itinerary building were all deliberately rejected for a solo flat-file blog. That reasoning has not changed — only some of the BUILD items' delivery mechanisms did (R1, R2, R4, R7, R10). - Weather via Open-Meteo, no API key, with the eight allowed
weather_descvalues — still exactly as planned inmilestone-1.md§1.2, and still matching the blueprint and the post form. - Location badge (
📍 City, Country) on cards and entry pages — as planned. - Distance/stats computation from frontmatter and GPX — the numbers survived; only their
location moved from a
/statspage to the trip page (R2).