Consumer report: supersession is a retrieval problem — what a bundle serves when `status: deprecated` has no counterpart

[jackofshadowz]

Reading #158, #148, #182 and #207 changed what this issue is. We set out to propose superseded_by, found that #158 had already named the gap exactly ("the spec's quiet on conflicting content — no contradicts/supersedes") and that #148 and #182 are carrying the vocabulary further than we would. So this is a consumer report instead, on the one part those threads don't cover: what happens on the read path when supersession is absent.

For context, we build Hands, a multi-agent CRM assistant. Each workspace keeps an OKF bundle as its long-term memory: agents write concepts with remember, a scheduled synthesis pass consolidates them into canonical topics, and a recall tool searches the bundle to ground future turns. Producer and consumer are the same system, which is what surfaced this.

The finding: supersession is a retrieval problem before it is a vocabulary problem

Our synthesis pass has always resolved contradictions in favour of recent information — it merges overlapping concepts and prefers the newer fact. That logic was correct and it was invisible, because the only thing it wrote was the winner.

So the corpus contained, simultaneously:

• memory/sruly-owns-android.md — status absent, therefore stable per §5.4
• memory/android-ownership.md — the newer, correct concept

and recall returned both. Ranked by text relevance, the stale one often ranked higher, because it was written when the topic was the whole subject of a conversation rather than one line in a consolidated note.

The system had already decided the first concept was false. It had nowhere to put that decision, so it kept serving it. That is worse than not having the fact at all: a wrong answer with a bundle path attached reads as sourced.

The two existing mechanisms don't close this:

• status: deprecated (§5.4) is the right marker and we now use it, but on its own it only says not current. It doesn't say what to read instead, so a consumer can suppress the bad answer but not repair it.
• log.md (§9) is where a **Deprecation** would conventionally go, but §9 makes both the file and the convention optional, and the entry is prose. Our retrieval path cannot depend on it. Deletion semantics: §5.3 makes removed knowledge indistinguishable from not-yet-written knowledge #207 makes the same observation about deletion from the other direction.

What we shipped

Two extension keys under the §4.1 allowance, in production this week with test coverage:

Key	Written when	Consumer behaviour
superseded_by	synthesis produces a concept that contradicts an existing one	the replacement's bundle-relative path; retrieval can follow it
deprecated_at	same moment	ISO 8601; distinguishes "deprecated in March" from "deprecated yesterday"

Both ride alongside status: deprecated rather than replacing it.

The consumer half is where the value landed. Our recall now reads §5.2 and §5.4 at query time and:

• drops status: deprecated outright
• sinks concepts past their stale_after (§5.5)
• floats human-reviewed above machine-confirmed above unverified (§5.2 tiers)

It over-fetches before filtering, so suppressing a superseded hit doesn't silently return fewer results than asked for.

Two constraints that mattered more than we expected:

Supersession must be narrower than "was consolidated into". Our first cut deprecated every source a topic absorbed. That was wrong: a summary of a March conversation remains a true record of that conversation even after its claims are superseded. Only a concept whose assertions are now false is marked. The distinction is between an episode and a claim, and OKF's document model doesn't currently force producers to notice it.

verified needs a machine writer to be worth anything. We had markConceptVerified for a year with exactly one caller — a human "mark reviewed" button. Every concept sat at unverified, so the §5.2 tiers were dead weight in our consumer. The synthesis pass now promotes a topic to machine-confirmed when a re-derivation still agrees with its sources, and the tiers became a usable ranking signal the same day. If other producers are seeing flat trust distributions, this may be why.

Where we think it belongs

Not as a new thread — we'd rather defer:

• superseded_by as a typed relationship → Proposal: Typed relationships between concepts #148. A supersession is a typed edge; if that proposal lands, this is one of its types and needs no separate key.
• The contradiction signal generally → Convention for maintenance signals — freshness, confidence, contradiction (additive under §4.1) #158, which named it first.
• As a lifecycle key with a home → Producer report: six lifecycle keys in a live OKF exporter, and where each one should land #182's table is the right shape; ours would be two more rows.
• Distinct from deletion → Deletion semantics: §5.3 makes removed knowledge indistinguishable from not-yet-written knowledge #207. A deleted concept and a superseded one differ: the superseded one should stay readable and keep resolving links, which is exactly what §5.4 already promises ("kept for links and history").

One thing we deliberately did not build

Time-range validity (valid_from / valid_to) — "true from March to June". We wanted it, and stopped: it's bitemporal modelling, it's a larger change than the format needs, and git history answers the audit question ("what did we believe in April") for anything short of a compliance requirement. Recording it here only as a considered-and-rejected data point, not a request.

Happy to share the bundle, the tests, or the retrieval ranking code if any of it is useful to the threads above.

[jimy-r]

Agree that supersession is a retrieval problem, and in my experience it has to be solved in two places at once, because a signal on the new record alone never reaches a reader who lands on the old one.

First, banner the superseded record itself. The document that has been replaced says so at its top, names its replacement, and stays on disk. A reader, human or agent, who retrieves the stale record learns which copy governs from the record, without folder archaeology or a catalogue lookup.

Second, keep exactly one canonical copy and make everything else a stated pointer. A pointer can go stale when its target moves, but stale-and-broken is loud. A second copy that drifts is stale-and-plausible, which is the failure you describe, where the old fact outranks the correction because both look authoritative.

Third, at retrieval time, weight the index entry, not the body. The index description is the recall trigger, and it carries the supersession state, so a deprecated bundle can be served as "superseded by X" rather than as content.

I maintain a reference architecture that documents this exact pattern: https://github.com/jimy-r/agent-workspace-architecture/blob/main/PATTERNS.md#17-one-canonical-copy-and-pointers-from-everywhere-else