choiyounggi · choiyounggi · Sep 17, 2026
@@ -105,3 +105,4 @@ Append-only. Format: `## [YYYY-MM-DD] <ingest|revise|lint|gap|contradiction|drif
 ## [2026-09-03] ingest | databases/selection — new category: datastore selection by workload (4 pages: choosing-a-datastore-by-workload, relational-jsonb-vs-document-store, vector-search-engine-selection, graph-workloads-relational-vs-graph-db); brave-search research, sources cited per page
 ## [2026-09-04] ingest | infrastructure/agent-orchestration/code-graph-as-orientation-layer (field-tested — 1 new page). A locally built code knowledge graph (graphify) is a freshness-gated, lead-not-evidence orientation layer for planning and parallel task decomposition: gate on graph mtime vs git log, symbol-anchored explain/path only, CLI delivery with bounded output, graph-derived assumptions named in reports. Sources: Developers Digest, AQ Score, Autonoma, Tiare Balbi, graphify README + measurements on graphifyy 0.4.23.
 ## [2026-09-16] ingest | knowledge-flush of the harvested insight queue — 2 new pages, 3 amended pages, 2 domain indexes updated; 4 of 4 claimed candidates ingested, 0 dropped. New: testing/quality/precedence-between-competing-exit-conditions (verified — a test claiming one exit condition beats another must stage the competing condition to become true in the same iteration the condition under test reaches its threshold, derive that iteration from the threshold rather than a literal, prove the assertion by swapping the two source blocks and requiring exactly that test to redden, and assert the loser's side effect did not run; grounded in the mutation-testing infection condition — Vera-Pérez et al. 2019, "the test inputs are not sufficient to infect the state of the program" — plus PIT's per-test kill attribution, with the dev-loop watch-status.sh R6 precedence case as the field measurement), infrastructure/agent-orchestration/escape-hatch-uses-as-a-knowledge-gap-signal (field-tested — a grounding gate's escape hatch is the only place that knows a decision had no source, so the gate emits one gap-queue row at the point it grants the pass, with the decision text, an enumerated reason separating "no page exists" from "page exists but was not found", and a periodic reconciliation of hatch uses against queue rows; the hatch keeps passing. GitHub code scanning's dismissal flow cited as the canonical recorded-hatch shape — mandatory reason, comment on the alert timeline, `dismissed_comment` on the API, reviewable Closed list. Measured locally: plan-gate.sh:166 passes `[no-wiki]` with a bare `continue` while SKILL.md:135 asks in prose for an ingest candidate — 276 non-index pages, exactly one `gap` entry in this log). Amended: infrastructure/agent-orchestration/pane-delivery-confirmation +Do-this #6 / +1 edge row / +1 Instead-of row (skip the pane check entirely on an iteration that sent keys — the pane repaints only after the target consumes the input, so a same-iteration capture can confirm the very state the send just cleared; reproduced 2026-09-16 on tmux/macOS, where a 0.4s-working command left the same-iteration capture reading the stale witness while an instant command repainted in time, making the outcome a function of the target's work time), platforms/processes/driving-a-tui-in-a-tmux-pane +1 edge row pointing at that rule, infrastructure/agent-orchestration/code-graph-as-orientation-layer +2 edge rows and +2 sources (graphifyy 0.4.23 installs post-commit and post-checkout only, while `git pull` runs post-merge — reproduced on git 2.50.1: fast-forward pull and merge-commit pull both fired post-merge alone, a merge commit fired no post-commit, and a fresh clone carried no hooks at all — so "PR merged upstream, then pull" leaves the graph stale with hooks reporting installed; freshness gate stays mandatory, add a post-merge hook, and build from a workspace scan after a clone). Reciprocal related links added both ways (tests-that-cannot-fail, policy-at-several-return-sites, completion-predicates; session-completion-gates, autonomous-decision-rulings, spec-document-gates). Structure checks 278 pages / 13 indexes / 0 findings; no prohibition-lint findings on the touched pages.
+## [2026-09-17] ingest | qa-document-verification-superseding-a-knowledge-record — knowledge-flush of 5 plan-gap candidates (wiki-plan `[no-wiki]` rows from t3-status and t1-reviewer): 1 new page, 4 t3-status rows merged into it, 1 t1-reviewer row dropped. New (verified): a refuted cited record is superseded, not deleted or overwritten — amend in place when the old directive still holds (RFC 2223 §12 *Updates*), write a stand-alone successor and mark the old record superseded with a resolvable successor pointer when it is wrong as a whole (*Obsoletes*; Nygard: "keep the old one around, but mark it as superseded"), move the index row to the successor, keep validity (`status`) separate from evidence strength (`confidence`), let the absent field mean active (MADR: status is optional front matter), and log the transition under the existing `revise` verb. Dropped as not generalizable: the t1-reviewer README agents-tree line (a one-repo scope ruling with no transferable directive). Reciprocal related links added (retiring-a-provisional-marker, spec-document-gates, escape-hatch-uses-as-a-knowledge-gap-signal).
@@ -8,7 +8,7 @@ sources:
   - https://docs.github.com/en/code-security/code-scanning/managing-code-scanning-alerts/resolving-code-scanning-alerts
   - https://github.blog/changelog/2025-07-01-delegated-alert-dismissal-for-code-scanning-is-now-generally-available/
 last_verified: 2026-09-16
-related: [infrastructure-agent-orchestration-session-completion-gates, infrastructure-agent-orchestration-autonomous-decision-rulings, qa-document-verification-spec-document-gates, backend-common-llm-binding-instructions-for-agents]
+related: [infrastructure-agent-orchestration-session-completion-gates, infrastructure-agent-orchestration-autonomous-decision-rulings, qa-document-verification-spec-document-gates, backend-common-llm-binding-instructions-for-agents, qa-document-verification-superseding-a-knowledge-record]
 ---
 
 # Recording Every Use of a Grounding Gate's Escape Hatch

@@ -9,7 +9,7 @@ sources:
   - https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
   - https://www.rfc-editor.org/rfc/rfc7322.html
 last_verified: 2026-08-14
-related: [qa-document-verification-editing-a-gated-document, qa-document-verification-spec-document-gates, qa-process-acceptance-criteria]
+related: [qa-document-verification-editing-a-gated-document, qa-document-verification-spec-document-gates, qa-process-acceptance-criteria, qa-document-verification-superseding-a-knowledge-record]
 ---
 
 # Converting a Provisional Marker to a Settled Statement in a Reviewed Design Document

@@ -17,6 +17,7 @@ sources:
 last_verified: 2026-08-09
 related:
   [
+    qa-document-verification-superseding-a-knowledge-record,
     qa-process-acceptance-criteria,
     testing-quality-tests-that-cannot-fail,
     platforms-environment-unicode-text-matching,

@@ -0,0 +1,86 @@
+---
+id: qa-document-verification-superseding-a-knowledge-record
+domain: qa
+category: document-verification
+applies_to: [general, adr, agent-wiki]
+confidence: verified
+sources:
+  - https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
+  - https://adr.github.io/madr/
+  - https://www.rfc-editor.org/rfc/rfc2223.txt
+  - https://www.rfc-editor.org/faq/
+last_verified: 2026-09-17
+related: [qa-document-verification-retiring-a-provisional-marker, qa-document-verification-spec-document-gates, infrastructure-agent-orchestration-escape-hatch-uses-as-a-knowledge-gap-signal]
+---
+
+# Superseding a Knowledge Record That Turned Out Wrong
+
+## When this applies
+
+A record in a curated set other documents cite by id or path — an ADR, a wiki
+page, a runbook, a spec section — is refuted or replaced by a newer finding,
+and you are deciding between editing it in place, deleting it, or replacing
+it; or you are adding a lifecycle field (`status`, `superseded_by`) to such a
+set's schema.
+
+## Do this
+
+1. **Pick the operation from how much of the old record survives.**
+
+| The new finding | Do |
+|-----------------|----|
+| Adds a case or a source; the old directive still holds | Amend the old record in place (the RFC series calls this *Updates*: the addition "cannot stand on its own") |
+| Refutes the old directive as a whole | Write a new record that stands alone, then mark the old one superseded (*Obsoletes*: the new document "can be used alone, without reference to the older document") |
+| Refutes it and nothing replaces it | Mark the old record retired, with the reason and date in the change log |
+
+2. **Keep the superseded file at its path and id.** Set its status and a
+   pointer to the successor's id; leave the body as it was. Plans, reviews,
+   and commit messages that cited the old id keep resolving, and a reader
+   learns that it *was* the rule and what replaced it.
+3. **Move navigation to the successor in the same change.** The index or
+   routing row now names the new record only, so a reader routing by
+   situation lands on current guidance; the old record stays reachable by id
+   and through the successor's back-link.
+4. **Make the successor pointer resolvable, and check it.** `superseded_by`
+   holds a live record id; the link check that already covers `related:`-style
+   fields covers it too, and `status: superseded` without a pointer is a lint
+   finding.
+5. **Keep validity separate from evidence strength.** `status` answers "is
+   this still the rule"; a confidence or review field answers "how well was it
+   supported when written". A record that was verified against official docs
+   and later superseded carries both values unchanged.
+6. **Let the absent field mean the default state.** Add `status` as an
+   optional key whose absence means active, and show it in the template as a
+   commented line. Existing records need no backfill, and a lint for the
+   field has only the exceptional states to validate.
+7. **Log the transition with the vocabulary the log already has** — a
+   `revise`-class entry reading `<old id> superseded by <new id> — <why>` —
+   when nothing parses the verb set mechanically. Add a verb only when a
+   consumer needs to select these entries by verb.
+
+## Edge cases
+
+| Case | Then |
+|------|------|
+| Only one directive of a multi-directive record is refuted | Amend that directive in place and log the revision; superseding is for a record wrong as a whole |
+| The successor is itself superseded later | Point each record at its direct successor; a reader follows the chain, and the lint checks each hop resolves |
+| A tool loads records by glob, not through the index | Filter on the status field in that tool, or superseded guidance is loaded as current |
+| The old record's id encodes a category the successor does not share | Keep the old id as is; ids are citation targets, and the pointer carries the move |
+| Two records supersede one (a split) | Hold a list of successor ids, and state in each successor which part it took over |
+
+## Instead of
+
+| If you are about to | Do this instead | Why |
+|---------------------|-----------------|-----|
+| Delete the refuted record and create the new one | Mark it superseded, point at the successor, keep the file | Every plan or review that cited the old path becomes a dead link, and the reason for the change is lost |
+| Overwrite the record's body with the opposite directive under the same id | Create the successor under a new id | Citations made under the old directive now silently assert the new one |
+| Add `superseded` as one more confidence value | Add a separate status field | Confidence describes the evidence at writing time; folding validity into it erases how well the old claim was supported |
+| Write `status: active` into every existing record | Treat absence as active | A key that is identical on every record carries no information and makes the migration diff the size of the corpus |
+
+## Sources
+
+- https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions — Nygard's ADR definition: "If a decision is reversed, we will keep the old one around, but mark it as superseded. (It's still relevant to know that it *was* the decision, but is *no longer* the decision.)"; a changed decision "may be marked as 'deprecated' or 'superseded' with a reference to its replacement"
+- https://adr.github.io/madr/ — the MADR template carries status as optional front matter with the value form `superseded by ADR-0123` ("These are optional elements. Feel free to remove any of them.")
+- https://www.rfc-editor.org/rfc/rfc2223.txt — §12 "Relation to other RFCs": *Updates* marks a supplement that "cannot stand on its own"; *Obsoletes* marks a document that "can be used alone, without reference to the older document"
+- https://www.rfc-editor.org/faq/ — "the status of an RFC can change" after publication, and the status is published on the RFC's info page and a list of status changes, apart from the document text
+- Field context 2026-09-17 (dev-loop issue #195): a 276-page agent wiki had no status field, so a refuted page could only be deleted, which broke the page paths recorded in earlier plan documents
@@ -42,6 +42,7 @@ Match your situation to a "load when" line; load only matching pages.
 | [generated-reference-drift-gates](document-verification/generated-reference-drift-gates.md) | Writing or reviewing the reference material that enumerates a closed vocabulary an agent will emit tokens from (DSL verbs, config keys, diagnostic codes, enum members) in a plugin/skill/SDK; deciding whether to hand-write that list or generate it from the owning constant; choosing what gates a generated document beyond a `--check` diff; a documented token compiles to a silent no-op instead of an error |
 | [retiring-a-provisional-marker](document-verification/retiring-a-provisional-marker.md) | Turning provisional markers (`[추정]`, TBD, "assumed", DRAFT) into settled statements in an ADR/RFC/spec that has been through review rounds, so the document also carries a review checklist and a round history referring to those markers; a checklist row stayed `[x]` on evidence you just deleted; a coordinator's marker count and yours disagree while you read the same file |
 | [editing-a-gated-document](document-verification/editing-a-gated-document.md) | Editing or rewording a document that grep/regex gates or a lint config check; a gate fails on wording whose meaning did not change; reflowing prose a test asserts as a verbatim phrase (CI red on one platform only); describing what an upstream spec says without tripping a "do not redefine it" gate; a check matches the pattern your own document quotes; recording an audit verdict inside the document that was audited; deciding which checks to re-run after editing a gated document |
+| [superseding-a-knowledge-record](document-verification/superseding-a-knowledge-record.md) | A cited record (ADR, wiki page, runbook, spec section) is refuted or replaced and you are choosing between amending in place, deleting, or superseding it; adding a lifecycle field (`status`, `superseded_by`) to a record schema; deciding whether validity belongs in the confidence field; deciding whether existing records need a backfilled default status |
 
 ## environments