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