diff --git a/docs/working/handovers/2026-07-25-docs-reconciliation-handover.md b/docs/working/handovers/2026-07-25-docs-reconciliation-handover.md new file mode 100644 index 0000000..c279d9e --- /dev/null +++ b/docs/working/handovers/2026-07-25-docs-reconciliation-handover.md @@ -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