intotheeast-com/docs/working/handovers/2026-07-25-docs-reconciliation-handover.md

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:

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:

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)

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