From 7bdb83fb16acd5e92c425fd9d5fac212ef22481b Mon Sep 17 00:00:00 2001 From: Timothy Date: Tue, 21 Jul 2026 11:11:01 +0200 Subject: [PATCH] docs(520): carry #642 orientation bullets into PR2 plan (from a814dd16) Co-Authored-By: Claude Opus 4.8 (1M context) --- ...26-07-21-decision-lifecycle-and-kickoff.md | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/superpowers/plans/2026-07-21-decision-lifecycle-and-kickoff.md b/docs/superpowers/plans/2026-07-21-decision-lifecycle-and-kickoff.md index 00ec3a384..d9319e620 100644 --- a/docs/superpowers/plans/2026-07-21-decision-lifecycle-and-kickoff.md +++ b/docs/superpowers/plans/2026-07-21-decision-lifecycle-and-kickoff.md @@ -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: `' 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