docs(working): handover for the documentation reconciliation

Two-part handover following the repo's existing convention: Part A for a fresh Claude session, Part B for the owner. Part A leads with the trap rather than the deliverables, because it is the thing most likely to cause damage: main advanced 13 commits mid-audit and had already fixed two of the audit's findings, so this branch would have reverted them without the merge. Includes the fetch-and-merge commands to re-check the baseline if main has moved again overnight. Also records, so a future session does not undo them: - The tense split — past-tense records are annotated, never rewritten. "Finishing the job" by rewriting the milestone docs or the 41 completed plans is the wrong instinct and destroys the audit trail. - One finding was WITHDRAWN during the audit (the asset table lists esbuild entry points, so imported-only sources are correctly absent). Adding them back would reintroduce a non-defect. - The known false-positive link-check hit inside a ```diff fence. - The submodule invariant: git diff main..HEAD -- user must stay empty. An earlier git reset -- user here silently reverted main's pin bump; that was caught, and the check is written down so it is not re-broken. - P5's booby trap: removing shortcode-gallery-plusplus may take shortcode-core with it and break stories. Part B is the two things only the owner can do: one command to open the PR (tea needs an interactive TTY), and the 7 recommendation decisions with why each needs a human. Notes that the PR body file lives in a Claude job dir and is reconstructable from the spec if it has been cleaned up. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-07-25 01:10:38 +02:00
1 changed files with 208 additions and 0 deletions
@@ -0,0 +1,208 @@
+# Documentation Reconciliation — Handover
+
+**Date:** 2026-07-25
+**Branch:** `feat/docs-reconcile` (worktree `.worktrees/docs-reconcile`, dev server :8091)
+**State:** Work **complete and pushed**. Remaining: **open the PR** (needs one interactive command) and **decide on 7 logged recommendations**. No code was changed; no `user/` commits were made.
+
+Two audiences:
+- **Part A — Claude → future Claude:** exact state, the one trap that nearly caused a regression, and what must not be "tidied up".
+- **Part B — Mischa:** the two things only you can do.
+
+---
+
+## Part A — Handover (Claude → future Claude)
+
+### What this branch delivers
+
+A whole-repo reconciliation of the documentation against the code, after five weeks in which the app
+changed and the docs did not. **The code was treated as the source of truth throughout.**
+
+Three deliverables:
+
+1. **`docs/reference/superseded-decisions.md`** (new) — the supersession ledger. 14 reversals, each with
+   what was planned, where, what is true now, when it changed, and why. Plus a "decisions that were
+   *not* reversed" section so old planning docs don't all read as suspect.
+2. **Inline `> **Superseded …**` notes** at each stale claim, in the 4 milestone docs, `summary.md`,
+   `pm-analysis.md`, and `design-system-light.md`. Reuses the repo's existing `> History:` /
+   `> **Changed 2026-07:**` patterns — do not invent a third convention.
+3. **Corrections to the nine present-tense docs** (`CLAUDE.md`, `README.md`, `CONCEPTS.md`,
+   `docs/README.md`, `docs/working/README.md`, `reference/architecture.md`,
+   `reference/design-system.md`, `reference/design-system-light.md`, `guides/posting.md`).
+
+Plus the compounded learning (`docs/solutions/conventions/reconciling-drifted-docs-tense-tiering-and-a-supersession-ledger.md`),
+the design/verification record (`docs/working/specs/2026-07-25-docs-reconciliation-design.md`), and the
+unacted findings (`docs/working/2026-07-25-doc-drift-recommendations.md`).
+
+### The governing idea — do not undo this
+
+Scope was split by **tense**, because the halves need opposite treatment:
+
+| Kind | Staleness is | Treatment |
+|---|---|---|
+| Present-tense: `CLAUDE.md`, `reference/`, `guides/`, `README.md`, `CONCEPTS.md` | a **defect** | corrected against the code |
+| Past-tense: `plans/`, `specs/`, `milestones/`, `summary.md`, `pm-analysis.md` | **correct and expected** | annotated only, **never rewritten** |
+
+**A completed plan is supposed to be stale — that is what makes it a record.** If a future session is
+tempted to "finish the job" by rewriting the milestone docs or the 41 completed plans to match today's
+code, that is the wrong instinct and destroys the audit trail. The banners are the fix.
+
+### Commits (all on `feat/docs-reconcile`, all pushed)
+
+`origin/feat/docs-reconcile` == local `HEAD` == `7c9c140`.
+
+- `8202d2a` — the reconciliation: ledger + inline notes + the nine present-tense corrections
+- `d946eaa` — compounded learning into `docs/solutions/conventions/` + new `CONCEPTS.md` Documentation cluster
+- `7c9c140` — **merge of `main`** (see the trap below)
+
+Net diff vs `main` is 19 files, +897/−60, **no deletions**, and the submodule gitlink is byte-identical
+to `main`.
+
+### ⚠️ The trap — `main` moved 13 commits mid-audit
+
+This is the most important thing on this page.
+
+While the audit ran, the location-override work was merged into the outer repo, advancing `main` by 13
+commits. **It independently fixed two of the audit's own findings:**
+
+- `829325c` — carved out the single-map-path exception for `js/src/location-map.js` in `CLAUDE.md`
+- `a517331` — set `2026-07-23-post-form-location-override.md` to `✅ Complete`
+
+Had this branch been merged without first merging `main` in, it would have **reverted both**. Both
+conflicts were resolved **in `main`'s favour** (its wording was better informed in each case), and the
+audit's own notes were then corrected to stop claiming credit for fixes it did not make.
+
+**If you pick this up on 2026-07-26 or later, `main` may have moved again. Do this first:**
+
+```bash
+cd .worktrees/docs-reconcile
+git fetch origin
+git log --oneline HEAD..origin/main        # anything here? then merge before touching the PR
+git merge origin/main                      # read each conflict as a finding, not a chore
+```
+
+Two rules that came out of this, now recorded in the learning doc §6:
+- **Re-check the baseline before publishing, not only before starting.** A long audit races the work it audits.
+- **When the incoming version is better, take it wholesale.** An audit has no special authority over the work it audits.
+
+### Submodule situation
+
+- `user/` in this worktree is on branch `feat/docs-reconcile` at **`dd19995`** — I moved it off the
+  outer repo's older pin (`02fa4e9`) so the audit ran against the state that actually runs. Auditing
+  the pin would have reported a shipped feature as unbuilt.
+- **No commits were made inside `user/`.** `git -C user status` is clean. Nothing to push there.
+- The merge commit **preserves `main`'s pin bump to `dd19995`**. The no-gitlink-commit rule in
+  `CLAUDE.md` is about not bumping the pin as a side effect of routine work — not about discarding a
+  bump `main` already made. An earlier `git reset -- user` here had silently reverted it to the old pin;
+  that was caught and fixed. **Verify before any future commit on this branch:**
+  `git diff main..HEAD -- user` must be empty.
+
+### What was verified, and how
+
+Nothing was inferred from prose. Full table in the spec doc; the load-bearing ones:
+
+| Claim | Verified against |
+|---|---|
+| Nav labels | `partials/base.html.twig:27-31` |
+| Asset sources → outputs | the theme's `package.json` build script |
+| `css-compiled/` provenance | CSS imports in `js/src/*.js`; `assets.addCss` in `base.html.twig:7-8` |
+| No light mode | absence of `prefers-color-scheme` / `data-theme` **and** of light hex values in `css/` |
+| Photo rules (1–6, required) | `user/pages/02.post/post-form.md:35-46` |
+| `entry-actions` routes | `entry-actions.php:63-73` |
+| Env-suffix rule | `Makefile` `guard-env:41-43` + the `make-env-target` macro at `:45-46` |
+| `travel-memories` removal | `git log -- services/` → `a80b0a9`, then a real `docker compose build` failure |
+
+**One finding was withdrawn** after reading `package.json`: the asset table lists esbuild *entry
+points*, so imported-only sources (`api-utils.js`, `location-map.js`, `map-style.js`, `post-form.css`)
+are correctly absent from it. If a future pass "fixes" that table by adding them, it is reintroducing a
+non-defect.
+
+Checks run before pushing: no conflict markers anywhere; `ce-compound`'s frontmatter validator exits 0;
+all relative links resolve. **One link check hit is a known false positive** —
+`../reference/architecture.md` inside a ```diff fence in the learning doc, quoting
+`docs/working/README.md`'s literal content, where that path is correct.
+
+### Not done, deliberately
+
+- **The PR is not open.** `tea` requires an interactive TTY for the SSH passphrase. Command in Part B.
+- **None of the 7 recommendations were acted on**, per instruction. They are decisions, not chores —
+  several are behaviour changes that would have made this diff unreviewable as documentation.
+- **No `user/` changes**, including the `italy-2025` demo fixtures (recommendation P6).
+
+### Do not, without being asked
+
+- Rewrite any past-tense doc to match current code — annotate instead.
+- Act on `docs/working/2026-07-25-doc-drift-recommendations.md`. **P5 in particular is booby-trapped:**
+  removing `shortcode-gallery-plusplus` may take `shortcode-core` with it (it is a GPM dependency and is
+  *not* in `plugins.txt`), which would break stories. Add `shortcode-core` explicitly first, in its own
+  step, then remove and verify a story page renders.
+- Bump the submodule pin beyond preserving `main`'s.
+- `content-push` — nothing here touches content.
+
+### Environment
+
+Worktree dev server on **http://localhost:8091** (`itte_docs-reconcile_grav`, from `.worktree-env`).
+Nothing in this branch needs a running server — it is documentation only — so tearing it down is safe:
+
+```bash
+make worktree-rm NAME=docs-reconcile     # compose down → submodule deinit → worktree remove → prune
+```
+
+The branch is pushed, so removing the worktree loses nothing. Note `main`'s `cfe070e` fixed
+`worktree-rm` so it no longer unregisters `user/` for the main checkout — that fix is in this branch via
+the merge.
+
+---
+
+## Part B — For Mischa
+
+### 1. Open the PR (one command)
+
+```bash
+cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast/.worktrees/docs-reconcile
+tea pr create --login git.gorinskat.nl --repo m038/intotheeast-com \
+  --head feat/docs-reconcile --base main \
+  --title "docs: reconcile documentation against the code; add a supersession ledger" \
+  --description "$(cat /home/mischa/.claude-work/jobs/18e4d444/tmp/pr-body.md)"
+```
+
+Or in the browser: https://git.gorinskat.nl/m038/intotheeast-com/pulls/new/feat/docs-reconcile
+
+⚠️ The body file lives in a Claude job directory and disappears when that job is deleted. If it is
+already gone, the PR description is reconstructable from
+`docs/working/specs/2026-07-25-docs-reconciliation-design.md` plus the recommendations doc.
+
+### 2. Decide on the recommendations
+
+`docs/working/2026-07-25-doc-drift-recommendations.md`, ordered. The first is a live bug:
+
+| | What | Why it needs you |
+|---|---|---|
+| **P1** | `make start` / `make setup` fail on any clean checkout — `docker-compose.yml` still builds `travel-memories`, whose source you removed in `a80b0a9` | Three options (delete the service / put it behind a compose profile / re-point `build`). It is your call whether that project ever runs alongside Grav again. **It works on your machine only because a pre-removal Docker image is cached** — it breaks in every new worktree and after any `docker image prune` |
+| **P2** | A repeatable `make docs-check` | The half you deferred. Every defect this pass found was mechanically checkable, so this is what stops the drift recurring. Sequence it *after* P1, or the first thing it reports is P1 |
+| **P3** | Plan status can silently lag a merge | Three options, cheapest is naming the plan path in the feature commit |
+| **P4** | `README.md` was designated authoritative for a list it did not hold | Structural: either generate the command tables from the `Makefile`, or soften the `CLAUDE.md` pointer |
+| **P5** | `shortcode-gallery-plusplus` has no consumer | ⚠️ See the booby-trap warning in Part A before touching it |
+| **P6** | `italy-2025` demo fixtures still ship `map.md` / `stats.md` for retired views | A `user/` submodule change, so it was out of scope here |
+| **P7** | Structural notes — e.g. whether `design-system-light.md` should move out of `reference/`, since it documents a theme that does not exist | Judgement calls, both defensible |
+
+### 3. Worth knowing
+
+The three findings most likely to have bitten you in practice:
+
+- **`posting.md` would have failed if followed** — it said photos were optional; they are required, 1–6.
+- **Every `make remote-*` command in `README.md` was unrunnable** — all documented without the
+  `-test`/`-prod` suffix `guard-env` requires. `deploy-cycle.md` had it right the whole time; the defect
+  was a second copy of the knowledge drifting from the first.
+- **`docs/working/README.md` advertised `summary.md` as "current state"** while `summary.md` describes
+  Leaflet, `/tracker`, `/map` and `/stats`. An index that vouches for a stale doc is worse than the
+  stale doc, because it defeats your judgement before it engages.
+
+---
+
+## Related
+
+- `docs/working/specs/2026-07-25-docs-reconciliation-design.md` — design, scope rationale, and the full verification table
+- `docs/reference/superseded-decisions.md` — the ledger itself
+- `docs/working/2026-07-25-doc-drift-recommendations.md` — the 7 unacted findings
+- `docs/solutions/conventions/reconciling-drifted-docs-tense-tiering-and-a-supersession-ledger.md` — the compounded learning
+- `docs/solutions/conventions/claude-md-content-tiering.md` — the prior learning this extends; flagged as a consolidation candidate if a third documentation learning appears