Captures the durable learnings from the 2026-07-25 whole-repo documentation
reconciliation as a knowledge-track learning, plus the vocabulary it introduced.
New learning — conventions/reconciling-drifted-docs-tense-tiering-and-a-supersession-ledger.md:
- Tier docs by TENSE, not only by content type. claude-md-content-tiering.md
established "descriptions drift, rules don't" and tiered by content type; that
axis could not say what to do with 41 completed plans, which are neither rules
nor current descriptions. Present-tense docs are defects when stale; past-tense
records are supposed to be stale and get annotated, never rewritten.
- Ledger AND inline notes, because each covers the other's failure: a ledger
alone is a pointer you may not follow, inline notes alone give no changelog
view. Prefer annotation patterns the repo already uses.
- Record what was NOT reversed, or a ledger of only reversals makes every old
doc look suspect and settled decisions get re-litigated.
- Separate "docs are wrong" from "code is wrong" — route code-side findings to a
recommendations doc so a docs diff stays reviewable.
- Verify against the artifact that decides behaviour: the Makefile for commands
(including macro-generated targets a grep misses), the build script for
outputs, imports for source-vs-output, branch history for whether a plan
shipped. An audit that never withdraws a finding has not been checking itself
— one finding here was withdrawn after reading package.json.
- Audit the state that actually runs: a fresh worktree checks out the submodule
PIN, which lagged real HEAD and would have hidden a whole merged feature.
Three structural lessons in "Why This Matters":
- An index describing another document's role is a factual claim that can rot,
and it is worse than the stale document itself — it defeats the reader's
judgement before it engages. This was the tree's single most misleading line.
- Wrong beats absent again, now for commands: README's server runbook documented
every remote-* target without the -test/-prod suffix guard-env requires.
deploy-cycle.md had it right — the defect was a second copy drifting.
- Promoting a doc to "the authoritative list of X" creates a completeness
obligation it did not have as prose, and nothing enforces it.
- A removal is not finished when the code is gone, but when every consumer and
every description of it is gone — travel-memories left a compose service
behind, hidden by a cached Docker image. Local state can mask a breakage
indefinitely, so "it works here" is not evidence.
Overlap with conventions/claude-md-content-tiering.md scored MODERATE (2 of 5
dimensions: same root-cause thesis, overlapping files; different tiering axis
and different prevention), so a new doc was written rather than folding into it.
Flagged in the Related section as a consolidation candidate if a third
documentation learning appears.
CONCEPTS.md — new Documentation cluster (Historical record, Superseded decision,
Plan status) and one flagged ambiguity recording that a present-tense historical
record is not a claim about the current system. These three are now referenced by
CLAUDE.md and both doc READMEs, so they needed defining.
Discoverability check: no edit needed — CLAUDE.md's entry-point table already
surfaces docs/solutions/ with its frontmatter fields and CONCEPTS.md.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Refresh audit of all 13 docs/solutions learnings against the current
codebase. Core guidance verified accurate everywhere; three docs had
reference drift:
- dual-repo-submodule-workflow: point worktree setup/teardown at the
make worktree-new/worktree-rm targets (manual procedure misses
.worktree-env isolation)
- docker-exec-root-owned-bind-mount-files: tracked-plugin list now
includes entry-actions; fix-perms description matches actual target
- grav-plugin-config-without-code-wont-enable: 3-category model's
custom-in-repo list now includes entry-actions
CONCEPTS.md: add Container, Content repo, Outer repo, Pin, Env tree,
Remote-only plugin; refresh Active Trip (switching is one setting now).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0195b3cDdMeize2Mm1FgC2aU
Document the trip publish-toggle cache-invalidation finding: an in-place
trip.md `published` edit under cache.check.method: folder + APCu driver stays
stale because the folder checksum is unchanged AND the web APCu store is
unreachable by a CLI clearcache — fixed with apcu_clear_cache() from the web
request. Cross-link the sibling grav-deleteall doc (the create/delete case) as
necessary-but-not-sufficient here, and add the Published/Draft trip status
concept to CONCEPTS.md.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mpdu3Dt1iVoozHwAMyjrbn
Capture the safe procedure + three non-obvious traps from the standalone-
page cleanup: keep the folder as a routable:false data container, repoint
Back-link fallbacks to the grandparent (silent direct-landing regression),
and sync the gitignored demo source + Makefile or the next demo-load undoes it.
Seed CONCEPTS.md (Trip, Entry, Story, Active Trip) and surface docs/solutions/
+ CONCEPTS.md in CLAUDE.md so future sessions discover them.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
m038andClaude Opus 5