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
|
`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
|
||||||
|
|||||||
Reference in New Issue
Block a user