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:
@@ -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
|
||||
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."
|
||||
- **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
|
||||
fallback documented" box is unmet.
|
||||
- [ ] **Step 3c (dogfood supersession — Fable #5, PR2 half)** #520 reverses the recorded decision
|
||||
|
||||
Reference in New Issue
Block a user