supersede-outdated-docs

Supersede outdated docs

Correcting curated knowledge is never an edit. It is always a new unit.

The rule

1. Write a new unit file with its own new id, never reusing the old one.
2. Its frontmatter declares supersedes: [<old-id>] (a list -- one unit may supersede several at once, many-to-one).
3. The superseded unit is never edited and never deleted. Its file, its evidence, its anchors -- all of it stays exactly as written. History is not rewritten.
4. If the correction is itself a chain (kb-0001 was already superseded by kb-0002, and kb-0002 also needs correcting), the new unit supersedes the latest unit in the chain, not the original.

Why

derive computes each unit's effective state from supersedes across the whole validated set -- it is never stored on the unit itself. A superseded unit still appears in knowledge-index.md, marked superseded by <ids>, never omitted and never mutated. Editing a unit in place would destroy the record of what was believed and when; superseding preserves it.

Steps

python3 -m validated_memory validate

Validate the whole knowledge/ directory (not just the new file) so the supersedes reference resolves against the unit it points at.

python3 -m validated_memory derive

Re-derive knowledge-index.md afterwards, so its state column reflects the new supersession. If the project gates on a versioned index (derive --check in CI), re-deriving is required before that gate passes again.

If the new unit carries its own anchors, its freshness verdict starts at unknown until detect-stale-documentation runs against it -- the superseded unit keeps whatever verdict it last had recorded, since probe only probes active units.