docs: reconcile documentation against the code; add a supersession ledger
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>
This commit is contained in:
Claude Opus 5
@@ -0,0 +1,149 @@
|
||||
# Recommendations from the 2026-07-25 documentation reconciliation
|
||||
|
||||
**Status:** 📋 Proposed — nothing here has been acted on. Decide per item.
|
||||
|
||||
The reconciliation pass (see [`specs/2026-07-25-docs-reconciliation-design.md`](specs/2026-07-25-docs-reconciliation-design.md))
|
||||
corrected the documentation. It also surfaced problems that are **not** documentation problems, plus
|
||||
process changes that would stop this drift recurring. Those are collected here rather than mixed into
|
||||
a docs diff.
|
||||
|
||||
Ordered by what I would do first.
|
||||
|
||||
---
|
||||
|
||||
## P1 — `make start` and `make setup` are broken on any clean checkout
|
||||
|
||||
**What.** `docker-compose.yml` still declares a `travel-memories` service with
|
||||
`build: ./services/travel-memories`. That source was removed in `a80b0a9` ("moved to separate
|
||||
project") and `services/` is gitignored, so the build context does not exist. `make start` is
|
||||
`docker compose up -d` (all services), and `make setup` calls it.
|
||||
|
||||
**Proof.**
|
||||
```
|
||||
$ docker compose build travel-memories
|
||||
unable to prepare context: path ".../services/travel-memories" not found
|
||||
```
|
||||
|
||||
**Why it has stayed hidden.** A machine that built the image before `a80b0a9` still has
|
||||
`travel-blog-intotheeast-travel-memories:latest` cached, so `docker compose up -d` reuses it and never
|
||||
rebuilds. It breaks for a fresh clone, for every new worktree (different `COMPOSE_PROJECT_NAME` →
|
||||
different image name → forced rebuild), and on the main checkout after any `docker image prune`. This
|
||||
is why `make worktree-new` calls `start-grav`, not `start`.
|
||||
|
||||
**Options.**
|
||||
1. **Delete the service from `docker-compose.yml`** (recommended). It lives in another project now. If
|
||||
that project needs to run alongside Grav, it can carry its own compose file.
|
||||
2. Move it into a compose profile (`profiles: [tools]`) so `docker compose up -d` skips it by default.
|
||||
3. Keep it and point `build` at the new location — only if you actually want the two coupled again.
|
||||
|
||||
Until this is decided, `CLAUDE.md` and `README.md` now warn to use `make start-grav`. That is a
|
||||
signpost around a bug, not a fix.
|
||||
|
||||
---
|
||||
|
||||
## P2 — A repeatable drift check
|
||||
|
||||
Deliberately out of scope for the one-time pass; this is the item that stops the whole problem
|
||||
recurring. Every defect found was mechanically checkable — a route, a path, a token name, a make
|
||||
target, a field rule.
|
||||
|
||||
**Proposal.** A `make docs-check` target that fails loudly when the present-tense docs assert
|
||||
something the code contradicts:
|
||||
|
||||
- Grep `CLAUDE.md`, `docs/reference/`, `docs/guides/`, `README.md`, `CONCEPTS.md` for references to
|
||||
retired routes (`/map`, `/stats`, `/tracker`, `/dailies`, `/stories`) and dead tech (`Leaflet`).
|
||||
These are already forbidden by `CLAUDE.md`, so any hit is a defect.
|
||||
- Assert every `templates/*.html.twig` and `templates/partials/*.html.twig` named in
|
||||
`architecture.md` exists, and flag templates that exist but are undocumented. Both directions of
|
||||
drift were present this pass.
|
||||
- Diff the `--color-*` token names in `design-system.md` against `css/tokens.css`. Six were missing.
|
||||
- Assert every `make <target>` mentioned in `README.md` is a real target, **and** that no bare
|
||||
`remote-*` target is documented without an env suffix. This alone would have caught P4.
|
||||
- Assert file paths cited in `CLAUDE.md` exist. A prior pass shipped a path to
|
||||
`js/src/maplibre-utils.js`, which never existed.
|
||||
|
||||
Deliberately **excluded**: `docs/working/`. Those documents are records and are supposed to drift;
|
||||
scanning them would produce permanent noise.
|
||||
|
||||
Sequence this after P1 — otherwise the first thing the check reports is P1.
|
||||
|
||||
---
|
||||
|
||||
## P3 — Plan status can silently lag a merge
|
||||
|
||||
`plans/2026-07-23-post-form-location-override.md` read `📋 Not started` while the feature was merged
|
||||
in `user/` as `dd19995`. Nothing connects a plan's status line to the commit that lands it, so the
|
||||
convention depends entirely on remembering.
|
||||
|
||||
**Options.**
|
||||
1. **Add the plan path to the feature's commit or PR body**, so `git log --grep` can find plans whose
|
||||
work landed but whose status never moved. Cheapest, no tooling.
|
||||
2. Extend the P2 check: for each plan not `✅ Complete`/`❌ Abandoned`, look for a merged branch whose
|
||||
name matches the plan slug and warn. Catches it automatically; some false positives.
|
||||
3. Accept it and rely on the convention. Reasonable — this was one miss across 41 plans.
|
||||
|
||||
---
|
||||
|
||||
## P4 — `README.md` was designated authoritative for a list it did not hold
|
||||
|
||||
`CLAUDE.md`'s entry-point table sends readers to `README.md` for "the full `make` command list".
|
||||
Before this pass, README documented 7 of ~20 `remote-*` targets, and documented all of them **without
|
||||
the `-test`/`-prod` suffix that `guard-env` requires** — so its server runbook was not executable.
|
||||
|
||||
Corrected now, but the structural point stands: **a doc promoted to "the authoritative list of X"
|
||||
acquires a completeness obligation it did not have as prose.** The `Makefile` is the real source of
|
||||
truth. Consider either generating the command tables from `Makefile` comments, or softening the
|
||||
CLAUDE.md pointer to "common commands" and letting `make help` be authoritative.
|
||||
|
||||
Related: `docs/guides/deploy-cycle.md` had the env-suffix rule right the whole time. The defect was
|
||||
README duplicating the same knowledge and drifting. Fewer copies would have prevented it.
|
||||
|
||||
---
|
||||
|
||||
## P5 — `shortcode-gallery-plusplus` is installed with no consumer
|
||||
|
||||
`plugins.txt` lists it, but there is no `[gallery]` shortcode anywhere in `templates/` or `pages/`.
|
||||
Entry galleries are PhotoSwipe, wired in `js/src/main.js` against `.pswp-gallery` markup from
|
||||
`partials/entry-journal.html.twig`.
|
||||
|
||||
**Careful before removing it.** `plugins.txt` does **not** list `shortcode-core`, which is present as
|
||||
a GPM dependency — and `story-blocks` needs `shortcode-core`. Dropping
|
||||
`shortcode-gallery-plusplus` could take `shortcode-core` with it and break stories.
|
||||
|
||||
**Recommendation.** Add `shortcode-core` to `plugins.txt` as an explicit, first-class dependency
|
||||
*first*, then remove `shortcode-gallery-plusplus` and verify a story page still renders. Do not do
|
||||
these in one step.
|
||||
|
||||
---
|
||||
|
||||
## P6 — Demo fixtures still contain retired views
|
||||
|
||||
`user/docs/demo/trips/italy-2025/` ships `map.md`, `stats.md` and `stories.md` — pages for views
|
||||
retired on 2026-07-04. The newer `italy-2026-demo` fixture has no `map.md`/`stats.md`, so the fixtures
|
||||
disagree with each other.
|
||||
|
||||
Low impact (demo trips are gitignored in the pages tree and loaded on demand), but `make demo-load`
|
||||
copies them in, so a demo trip can materialise pages for views that no longer exist. Delete
|
||||
`map.md` and `stats.md` from `italy-2025`; keep `stories.md` only if the container is still needed.
|
||||
|
||||
This is a `user/` submodule change, which is why it was left out of this pass.
|
||||
|
||||
---
|
||||
|
||||
## P7 — Structural notes worth a decision
|
||||
|
||||
**`design-system-light.md` is a record, not a reference.** It documents an unimplemented palette and
|
||||
now carries a banner saying so, but it still sits in `reference/` — the "stable facts" tier. Moving it
|
||||
to `docs/working/` would make its status structural rather than dependent on a reader seeing the
|
||||
banner. Counter-argument: it is the natural starting point if a light theme is ever built, and
|
||||
`reference/` is where someone would look. Either is defensible; the banner makes it safe for now.
|
||||
|
||||
**`milestone2-template-refactor-brief.md` sits loose in `docs/working/`** while the milestone docs live
|
||||
in `working/milestones/`. Cosmetic, but it is the kind of thing that makes a folder stop being
|
||||
self-explanatory.
|
||||
|
||||
**The `summary.md` lesson generalises.** The single most misleading line in the tree was
|
||||
`working/README.md` advertising `summary.md` as "current state". A stale document is survivable; an
|
||||
*index* that points at a stale document as authoritative is not, because it defeats the reader's
|
||||
judgement. Worth remembering the next time an index gets written: **describing a document's role is
|
||||
itself a factual claim that can rot.**
|
||||
+12
-1
@@ -4,6 +4,17 @@ Everything here is a live working document: specs being built from, plans being
|
||||
|
||||
Stable facts belong in [`../reference/`](../reference/); how-to procedures in [`../guides/`](../guides/); write-ups of bugs already solved in [`../solutions/`](../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 `/map` page, no `/stats` page, no `/tracker`, no Leaflet, no
|
||||
> light theme, and no `hero_image` on entries.
|
||||
>
|
||||
> **Before re-creating anything you find in this folder, check
|
||||
> [`../reference/superseded-decisions.md`](../reference/superseded-decisions.md).** Superseded sections
|
||||
> also carry an inline `> **Superseded …**` note pointing there. For the site as it is, read
|
||||
> [`../reference/architecture.md`](../reference/architecture.md).
|
||||
|
||||
---
|
||||
|
||||
## What's in here
|
||||
@@ -18,7 +29,7 @@ Stable facts belong in [`../reference/`](../reference/); how-to procedures in [`
|
||||
| `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` | Project summary / current state |
|
||||
| `summary.md` | **Historical** wrap-up of the original four-milestone branch (2026-06-21). *Not* the current state — for that read [`../reference/architecture.md`](../reference/architecture.md) |
|
||||
| `pm-analysis.md`, `git-sync-notes.md`, dated one-offs | Standalone notes, kept for reference |
|
||||
|
||||
---
|
||||
|
||||
@@ -2,6 +2,18 @@
|
||||
|
||||
**Goal:** Every entry is richer out of the box — location name shown, weather auto-captured, photos in a proper gallery, hero image visible on the feed.
|
||||
|
||||
> **Historical — written 2026-06-21. Mostly shipped as specified; three details reversed.**
|
||||
>
|
||||
> Still true: the location badge, Open-Meteo weather auto-fetch with its eight `weather_desc` values,
|
||||
> and the entry photo gallery. Reversed since:
|
||||
> - **§1.5 gallery** is PhotoSwipe, not `shortcode-gallery-plusplus` (R10).
|
||||
> - **§1.6 `hero_image`** no longer exists on entries — the hero is the first uploaded photo, and the
|
||||
> owner controls photo order by drag-reorder (R7). Stories still use `hero_image`.
|
||||
> - **Photos are now required** (1–6 per entry), not optional (R8).
|
||||
> - **"Tracker feed"** is the trip page and the home active-trip view; there is no `/tracker` (R3).
|
||||
>
|
||||
> Details: [`../../reference/superseded-decisions.md`](../../reference/superseded-decisions.md).
|
||||
|
||||
---
|
||||
|
||||
## User Stories
|
||||
|
||||
@@ -2,6 +2,21 @@
|
||||
|
||||
**Goal:** A `/map` page shows all entries as markers on an interactive Leaflet.js map, connected by a chronological route line, with popups linking to entries.
|
||||
|
||||
> **Superseded — written 2026-06-21. Neither the `/map` page nor Leaflet exists.**
|
||||
>
|
||||
> - **No `/map` route.** The map renders inline on the trip page via the single shared partial
|
||||
> `templates/partials/entry-map.html.twig` (R1, retired 2026-07-04). `CLAUDE.md` forbids
|
||||
> re-creating it or linking to it.
|
||||
> - **Leaflet + OpenStreetMap tiles → MapLibre GL JS** with a CartoDB dark-matter basemap (R4,
|
||||
> 2026-06-20).
|
||||
> - **§2.6 nav link** is gone with the page (R6).
|
||||
>
|
||||
> The *substance* of this spec survived — markers per entry, chronological route line, popups linking
|
||||
> to entries, bounds fitting, mobile touch handling — it all lives in `MapUtils.initEntryMap()` in
|
||||
> `user/themes/intotheeast/js/maplibre-utils.js`. Only the page and the library changed.
|
||||
>
|
||||
> Details: [`../../reference/superseded-decisions.md`](../../reference/superseded-decisions.md).
|
||||
|
||||
---
|
||||
|
||||
## User Stories
|
||||
|
||||
@@ -2,6 +2,17 @@
|
||||
|
||||
**Goal:** A `/stats` page showing key trip numbers: days on the road, entries posted, countries visited, and approximate distance traveled.
|
||||
|
||||
> **Superseded — written 2026-06-21. There is no `/stats` page.**
|
||||
>
|
||||
> The stats themselves shipped and still work — days on the road, entries posted, countries visited,
|
||||
> distance (exact from GPX, or a `~`-prefixed haversine estimate without it). They render **inline on
|
||||
> the trip page** behind a toggle, computed by `window.initTripStats()` in `js/src/main.js`
|
||||
> (R2, retired 2026-07-04). `CLAUDE.md` forbids re-creating the standalone view.
|
||||
>
|
||||
> Also reversed: **§3.7 nav link** (R6), and the `/tracker` references (R3).
|
||||
>
|
||||
> Details: [`../../reference/superseded-decisions.md`](../../reference/superseded-decisions.md).
|
||||
|
||||
---
|
||||
|
||||
## User Stories
|
||||
|
||||
@@ -2,6 +2,20 @@
|
||||
|
||||
**Goal:** Embed a compact interactive map above the entry feed on the tracker page, showing recent entry positions and the current location, giving readers immediate spatial context.
|
||||
|
||||
> **Superseded — written 2026-06-21. The idea won; this implementation did not.**
|
||||
>
|
||||
> A map beside the feed is exactly what the site does now — but not as a separate "mini-map":
|
||||
> - **No `/tracker` page** to embed it above (R3). The map sits in a column on the trip page and the
|
||||
> home active-trip view.
|
||||
> - **No second map implementation.** This spec's `feed-map` variant with its own inline init was
|
||||
> deleted; everything goes through the one shared `partials/entry-map.html.twig` +
|
||||
> `MapUtils.initEntryMap()` path (R12, consolidated 2026-06-27). Adding a second display map is
|
||||
> forbidden by `CLAUDE.md`.
|
||||
> - **Leaflet → MapLibre GL JS** (R4), so §4.1's `if (typeof L === 'undefined')` guard is obsolete.
|
||||
> - **No "View full map →" link** — there is no full map page to link to (R1).
|
||||
>
|
||||
> Details: [`../../reference/superseded-decisions.md`](../../reference/superseded-decisions.md).
|
||||
|
||||
---
|
||||
|
||||
## User Stories
|
||||
|
||||
@@ -11,7 +11,7 @@ execution: code
|
||||
|
||||
# Post Form Location Override - Plan
|
||||
|
||||
**Status:** 📋 Not started
|
||||
**Status:** ✅ Complete (2026-07-24) — merged to `user/` `main` as `dd19995` ("Merge feat/post-location-override into main"). Delivered `js/src/location-map.js` (the lazy-imported single-draggable-marker pin editor) and `js/src/map-style.js` (`MAP_STYLE`, now the single source of the basemap URL for both map paths), plus the "More location details" disclosure with city/country search-by-lookup in `js/src/post-form.js`. The status line lagged the merge and was corrected during the 2026-07-25 documentation reconciliation; the second map engine is now recorded as the one sanctioned exception to the single-map-path rule in `CLAUDE.md` and in [`../../reference/superseded-decisions.md`](../../reference/superseded-decisions.md) → R13.
|
||||
|
||||
## Goal Capsule
|
||||
|
||||
|
||||
@@ -2,6 +2,15 @@
|
||||
|
||||
*Role: Senior Product Manager. Audience: one solo traveler (Mischa), platform: Grav CMS flat-file PHP, no native app.*
|
||||
|
||||
> **Historical — written 2026-06-21. The verdicts still hold; some delivery mechanisms do not.**
|
||||
>
|
||||
> The **SKIP** column is still the standing decision and has not been revisited — background GPS,
|
||||
> followers, comments, social discovery, reactions, reels, 3D flyover, print, and AI itineraries
|
||||
> remain deliberately out of scope. What changed is *how* some **BUILD** items shipped: the map and
|
||||
> stats render inline on the trip page rather than as `/map` and `/stats`, MapLibre replaced Leaflet,
|
||||
> galleries use PhotoSwipe rather than `shortcode-gallery-plusplus`, and `hero_image` was dropped for
|
||||
> entries. See [`../reference/superseded-decisions.md`](../reference/superseded-decisions.md).
|
||||
|
||||
---
|
||||
|
||||
## Starting position
|
||||
|
||||
@@ -0,0 +1,109 @@
|
||||
# Docs Reconciliation — Design
|
||||
|
||||
**Date:** 2026-07-25
|
||||
**Status:** Implemented
|
||||
|
||||
Reconcile the documentation against the code after five weeks of undocumented evolution, so that a
|
||||
repeat review returns "ok".
|
||||
|
||||
---
|
||||
|
||||
## Problem
|
||||
|
||||
Documentation for this project began as thoughts and plans. The app then changed — features were
|
||||
built differently, some were dropped, and the owner changed his mind about what he needed. Those
|
||||
decisions were recorded ad hoc or not at all. The result is a tree where some docs describe a site
|
||||
that no longer exists, and nothing marks them as historical.
|
||||
|
||||
Concretely, before this pass:
|
||||
|
||||
- `docs/working/README.md` advertised `summary.md` as the project's **current state**, while
|
||||
`summary.md` described Leaflet, a `/tracker` feed, a `/map` page, a `/stats` page, and a
|
||||
"Journal · Map · Stats" nav — none of which exist.
|
||||
- `docs/reference/design-system-light.md` documented a light-mode palette in present tense. No light
|
||||
mode is implemented anywhere: `tokens.css` has a single `:root` block and no
|
||||
`prefers-color-scheme` / `data-theme` mechanism.
|
||||
- `CLAUDE.md` — the always-loaded file — asserted a source relationship that does not exist
|
||||
(`css-compiled/` generated from `css/style.css` + `css/tokens.css`).
|
||||
- `README.md`'s server runbook documented every `make remote-*` command without the `-test`/`-prod`
|
||||
suffix that `guard-env` requires, so the documented commands cannot run.
|
||||
- `docker-compose.yml` still defines a `travel-memories` service whose source was deleted in
|
||||
`a80b0a9` ("moved to separate project"), so `make start` fails on any clean checkout.
|
||||
|
||||
## Root cause
|
||||
|
||||
Per [`docs/solutions/conventions/claude-md-content-tiering.md`](../../solutions/conventions/claude-md-content-tiering.md),
|
||||
descriptions drift because the code moves and the prose does not; rules do not drift, because they
|
||||
encode intent rather than state. This pass confirms that finding again: every defect found was a
|
||||
description of code, config, or a command — not one was a rule that had become wrong on its own.
|
||||
|
||||
The compounding factor is **tense**. The tree mixes two kinds of document with no marker
|
||||
distinguishing them:
|
||||
|
||||
| Kind | Files | Staleness is |
|
||||
|---|---|---|
|
||||
| Present-tense — "this is how it is" | `CLAUDE.md`, `reference/`, `guides/`, `README.md`, `CONCEPTS.md` | a defect |
|
||||
| Past-tense — "this is what we decided then" | `working/plans/`, `working/specs/`, `working/milestones/`, `summary.md`, `pm-analysis.md` | correct and expected |
|
||||
|
||||
A completed plan *should* be stale — it is a record. It only becomes a problem when nothing tells a
|
||||
reader it is a record. `milestones/milestone-2.md` opens by describing a Leaflet `/map` page in
|
||||
confident present tense with no date qualifier.
|
||||
|
||||
## Approach
|
||||
|
||||
Two mechanisms, combined:
|
||||
|
||||
**A — one authoritative supersession ledger.** `docs/reference/superseded-decisions.md` records every
|
||||
reversal in one table: what was planned, where it was planned, what is true now, when it changed, and
|
||||
why. This answers "what did I change my mind about?" in a single place, which is the question a
|
||||
review actually asks.
|
||||
|
||||
**B — inline notes at the point of staleness.** Every superseded section carries a
|
||||
`> **Superseded …**` blockquote where the stale claim sits, so the claim can never be read
|
||||
un-corrected. This pattern is not invented here — `docs/reference/architecture.md` and
|
||||
`docs/guides/trip-switching.md` already use `> History:` and `> **Changed 2026-07:**` notes.
|
||||
|
||||
A alone has an indirection problem (a pointer you may not follow). B alone has a completeness problem
|
||||
(no changelog view, and coverage is only as good as the annotation pass). Together each covers the
|
||||
other's gap.
|
||||
|
||||
### Scope, split by tense
|
||||
|
||||
- **Present-tense docs are corrected against the code.** The code is the source of truth. Every
|
||||
factual claim was verified by reading the code, config, or `Makefile` — not inferred.
|
||||
- **Past-tense docs are annotated only, never rewritten.** 41 plans and 25 specs, ~30k lines. Their
|
||||
`✅ Complete` trailing notes are good records; rewriting them would destroy the audit trail and is
|
||||
unbounded work.
|
||||
- **Code-side inconsistencies are logged, not fixed.** Mixing behaviour changes into a documentation
|
||||
diff would make it unreviewable. They go to
|
||||
`docs/working/2026-07-25-doc-drift-recommendations.md` for a separate decision.
|
||||
|
||||
### Out of scope
|
||||
|
||||
- A repeatable drift check (script with an exit code). Deliberately deferred — the owner asked for the
|
||||
one-time reconciliation first. It is the lead recommendation in the recommendations doc.
|
||||
- Fixing the `travel-memories` / `docker-compose.yml` breakage, the unused
|
||||
`shortcode-gallery-plusplus`, and the `italy-2025` demo fixtures. All logged as recommendations.
|
||||
|
||||
## Verification
|
||||
|
||||
Claims were checked against, not assumed from:
|
||||
|
||||
| Claim area | Verified against |
|
||||
|---|---|
|
||||
| Nav labels | `templates/partials/base.html.twig:27-31` |
|
||||
| Template + partial inventory | `ls templates/`, `ls templates/partials/` |
|
||||
| Asset sources → outputs | `user/themes/intotheeast/package.json` build script |
|
||||
| `css-compiled/` provenance | CSS imports in `js/src/*.js`; `assets.addCss` in `base.html.twig:7-8` |
|
||||
| Design tokens | `css/tokens.css` |
|
||||
| Light mode | absence of `prefers-color-scheme` / `data-theme` and of light hex values in `css/` |
|
||||
| Photo field rules | `user/pages/02.post/post-form.md:35-46` |
|
||||
| `hero_image` removal | `post-form.md:149-151` |
|
||||
| `entry-actions` routes | `user/plugins/entry-actions/entry-actions.php:63-73` |
|
||||
| `make` targets + env guard | `Makefile` (`guard-env:41-43`, `make-env-target:45-46`) |
|
||||
| `travel-memories` removal | `git log -- services/` → `a80b0a9`; `docker compose build` failure |
|
||||
| Plan status vs reality | `user/` HEAD `dd19995` |
|
||||
|
||||
The `user/` submodule was moved off the outer repo's pin to its real HEAD (`dd19995`) before
|
||||
auditing, because the pin lagged and would have produced findings against a state that is no longer
|
||||
current.
|
||||
@@ -2,6 +2,16 @@
|
||||
|
||||
*Branch: `experimental-polar-steps`. Ready for morning review.*
|
||||
|
||||
> **Historical — written 2026-06-21. This is not the current state of the site.**
|
||||
>
|
||||
> This was the wrap-up of the four-milestone experimental branch. Much of what it describes has since
|
||||
> been deliberately reversed: there is no `/map` page, no `/stats` page, no `/tracker` feed, no
|
||||
> Leaflet, and the nav is not "Journal · Map · Stats". Every reversal is listed in
|
||||
> [`../reference/superseded-decisions.md`](../reference/superseded-decisions.md).
|
||||
>
|
||||
> For the site as it actually is, read
|
||||
> [`../reference/architecture.md`](../reference/architecture.md).
|
||||
|
||||
---
|
||||
|
||||
## What Was Done
|
||||
|
||||
Reference in New Issue
Block a user