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>
Four rounds of CLAUDE.md reduction (255 -> 305 -> 179 -> 74 lines) turned
up one consistent finding: every stale fact was a *description* of code or
config, never a rule. Two had been written by Claude days earlier.
Documents the operational test ("does this line change what Claude does on
a task where it wouldn't otherwise open the relevant file?"), the tiering
table, why gotchas are the one category that cannot move to a read-on-demand
docs/exceptions/, invariants-over-enumerations, and how to tell when a
reduction pass has hit the floor.
Also surfaces the docs/solutions frontmatter fields in CLAUDE.md's
entry-point table so the store is greppable by module, not just browsable.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The prior model claimed git-sync's add-set is scoped to the configured
`folders` (pages/config/themes), so accounts/ and user/env/ were "safe by
construction." That was wrong: prod auto-commit 9337003 pushed the whole
user/env/<host>/config tree (JWT secret, CSRF salt, git-sync token + webhook
secret), accounts/mischa.yaml, and system.yaml to Gitea — all outside the
configured folders. git-sync stages everything under user/ not gitignored;
.gitignore is the only reliable exclusion.
- Rewrite the architecture-patterns doc around the corrected predicate and
document the incident + remediation (gitignore /env/, rotate token+webhook).
- Correct git-sync-notes.md: env/ is NOT safe on folder scope; drop the
"never reaches Gitea" claim; fix the secret-files table intro + add /env/.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Np4cMQLF77i664CAQXySzU
Knowledge-track: functional Grav plugin config must live in the tracked
user/config/plugins/<name>.yaml override, not the gitignored (and
gpm-update-wiped) user/plugins/<name>/<name>.yaml. Secrets stay in
gitignored *-private.php. Root of the api plugin being unconfigured on
the fresh prod install. Cross-linked with the api/rc.10 install-failure
doc.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Np4cMQLF77i664CAQXySzU
m038andClaude Opus 5