docs(520): carry #642 orientation bullets into PR2 plan (from a814dd16)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-07-21 11:11:01 +02:00
co-authored by Claude Opus 4.8
parent f4bebd77b8
commit 7bdb83fb16
@@ -1144,6 +1144,29 @@ git -c core.hooksPath=/dev/null commit -m "feat(521): rework decisions guard —
`Gitea-ErsatzTV` wing — "how/why it was worked"); `docs/decisions.md` is **normative** (the `Gitea-ErsatzTV` wing — "how/why it was worked"); `docs/decisions.md` is **normative** (the
current rule). A decision points to its issue; the issue carries the provenance. Canonical current rule). A decision points to its issue; the issue carries the provenance. Canonical
Markdown wins for "current rule"; the issue wins for "context + is there prior/related work." Markdown wins for "current rule"; the issue wins for "context + is there prior/related work."
- **The four load-bearing orientation bullets (the #642 seam — carry VERBATIM into the kickoff +
`docs/README.md`; #642's 283-doc export is retrievable-but-unreached without them):**
1. **Current conventions/decisions → catalog-first.** Start at `docs/decisions/README.md`;
discover via the `ErsatzTV-Decisions` wing (active) / `ErsatzTV-Decisions-Archive` (superseded/
retired). **Resolve by topic/key, never by chasing a file path.**
2. **Issue history → evidence, not authority.** The `Gitea-ErsatzTV` wing is historical narrative
that may be stale; it never overrides current Markdown.
3. **The breadcrumb rule (the crux behavior change).** A file path named inside a *historical
issue comment* (e.g. "grep `docs/decisions.md` 2026-07-17", "see …") is a **breadcrumb, not a
live pointer.** Find the current rule via the catalog / active wing **by concept**; do not
treat the named path as current. (Why it's safe: still-current → in the active wing, breadcrumb
resolves; superseded → the active wing returns the *successor* and a literal follow lands on a
record that announces its own `status: superseded`; retired → the active wing returns nothing,
which is itself the signal. The validator-enforced move-to-`archive/` is what prevents the
catastrophic "superseded rule read as current" case.)
4. **Fallback when MemPalace is stale/down:** `docs/decisions/README.md` catalog, then
``rg '^`key: <dotted.key>`' docs/decisions/``. MemPalace is never authority nor sole fallback.
- **Graceful degradation (calibration, not a correctness cliff):** even an under-oriented agent that
literally greps `docs/decisions.md` post-#521 gets valid-but-*incomplete* results (misses topic
files + archived records), never *wrong* ones — that file holds only active records. So this is a
completeness/latency risk during rollout, not a correctness cliff. (#642 additionally strengthens
each exported doc's authority banner to name the catalog/wing and "don't treat file paths below as
current" — defense-in-depth for the skipped-orientation case.)
Without this the #520 "MemPalace candidate discovery + canonical verification + exact-search Without this the #520 "MemPalace candidate discovery + canonical verification + exact-search
fallback documented" box is unmet. fallback documented" box is unmet.
- [ ] **Step 3c (dogfood supersession — Fable #5, PR2 half)** #520 reverses the recorded decision - [ ] **Step 3c (dogfood supersession — Fable #5, PR2 half)** #520 reverses the recorded decision