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>
4.1 KiB
docs/working/ — work in flight
Everything here is a live working document: specs being built from, plans being executed, notes from sessions in progress. Once something is finished it stays (as a record) rather than being deleted — the **Status:** line is how you tell the difference.
Stable facts belong in ../reference/; how-to procedures in ../guides/; write-ups of bugs already solved in ../solutions/.
⚠️ Everything here is written in the past tense, even when it reads present-tense. A completed plan describes the code as it was when the plan landed — that is what makes it a useful record, and it is not a defect when it no longer matches. Several documents here describe features that were later deliberately reversed: there is no
/mappage, no/statspage, no/tracker, no Leaflet, no light theme, and nohero_imageon entries.Before re-creating anything you find in this folder, check
../reference/superseded-decisions.md. Superseded sections also carry an inline> **Superseded …**note pointing there. For the site as it is, read../reference/architecture.md.
What's in here
| Path | Contents |
|---|---|
specs/ |
Design docs — the what and why, written before a plan. Named YYYY-MM-DD-<topic>-design.md |
plans/ |
Implementation plans — the ordered how, with a status line. Named YYYY-MM-DD-<topic>.md |
milestones/ |
Milestone scope documents (milestone-1.md … ) |
qa/ |
Test plans, QA results, readiness audits |
handovers/ |
Session handover notes — context for picking up unfinished work |
learnings/ |
Retrospective notes worth keeping but not yet promoted to ../solutions/ |
backlog.md |
Unscheduled ideas and wishes |
bugs-and-fixes.md |
Running log of bugs found and what fixed them |
summary.md |
Historical wrap-up of the original four-milestone branch (2026-06-21). Not the current state — for that read ../reference/architecture.md |
pm-analysis.md, git-sync-notes.md, dated one-offs |
Standalone notes, kept for reference |
Plan status convention
Every plan in plans/ carries a **Status:** line immediately after its title heading. This is the single place a plan's state is recorded — there is no separate tracker.
| Status | Meaning |
|---|---|
📋 Not started |
Plan written and reviewed; no work begun yet |
🔄 In progress — <note> |
Actively being worked on. The note says where it stopped, so anyone (or any session) can resume |
⏸️ Deferred — <reason> |
Intentionally postponed. Still valid, just not now — the reason matters more than the status |
✅ Complete (YYYY-MM-DD) |
Done and shipped. The date is when it landed, not when the plan was written |
❌ Abandoned — <reason> |
Won't be implemented. Kept so the decision (and its reasoning) is not re-litigated later |
Notes on using it:
- A trailing note after
✅ Completeis normal and encouraged for anything non-trivial — what actually shipped, what was deferred, which commit or environment it landed in. Several plans here carry a paragraph. Deferredis notAbandoned. Deferred means "still want this"; abandoned means "decided against it". Keeping them distinct is the whole point of having both.- Update the status when the work lands, not later. A plan whose status lags reality is worse than no plan, because it is trusted.
Asking Claude what's open
Claude reads these statuses directly (the convention is also in ../../CLAUDE.md, so it applies without being asked). When asked what's open it will surface Not started and In progress, show Deferred items with the label made explicit, and leave out Complete and Abandoned unless you ask for them. It sets the status to ✅ Complete (YYYY-MM-DD) on finishing a plan.
A quick manual sweep of the same thing:
grep -rH '^\*\*Status:\*\*' docs/working/plans/ | grep -v 'Complete\|Abandoned'