doc: RFC — knowledge outdating, so a stale rule stops being served

[tzhouam]

Problem

Knowledge enters the catalog on a merge event and nothing ever makes it leave. Six weeks of daily intake: 104 rule pages, 488 rule IDs, zero retractions.

Three properties make this structural, not accidental:

1. The distiller never reads an existing rule as a claim — it only writes new sections.
2. Since sdk(knowledge): reject rule IDs that already head a section on any catalog page #142 the SDK loads every rule ID tree-wide, but solely to reject ID collisions. The only modelled relationship between new and old knowledge is namespace, not meaning.
3. Apply is append-only by construction, so no operation that marks a rule false is even expressible.

The result is worse than missing knowledge. When an upstream PR removes a behaviour, the batch distills a rule for the new behaviour while the old rule asserting the removed one stays on the same page at equal authority — its page updated: date refreshed by the very append that contradicted it. The reviewer gets both in one quick map with nothing marking which is current.

Already observable in the tree:

• 5 rule IDs head a section on two different pages — DIFF-1g, DIFF-1h, MCPMO-4d, MMH3-1k, MMH3-1n. sdk(knowledge): reject rule IDs that already head a section on any catalog page #142 rejects new duplicates; it cannot see the ones that predate it.
• MMH3-4e contradicted MMH3-4a and was folded in by hand during the 09-10 curation pass.
• 7 rules cite symbols that no longer exist upstream — WanTransformer3DModel, PromptUpdateMixin, _normalize_cache_config, npu_rotary_mul, model_dtype — in a five-day window alone.
• 44 pages all declare updated: 2026-09-05 while carrying rules distilled in July.

The measurement that shapes the design

Upstream 44d3ae10..3d952d13 — 116 commits, 828 files, five days:

Signal	Rules flagged	Verdict
a cited file was touched	456 of 497 (92%)	noise
a cited symbol was touched	405 of 492 (82%)	noise
a cited symbol or file was removed	7 of 492 (1.4%)	signal

A freshness scanner — the design this repo already runs for its own SPEC pages — flags four rules in five every week here and drowns the real events. The distinction that carries signal is existence, not change.

Proposal

• Per-rule provenance — compact inline marker plus a per-owner sidecar. A full inline trailer costs 92.4 KiB and pushes four pages past the 32 KiB cap immediately; the compact form costs 12.6 KiB and pushes only scheduler, which must be split anyway at 272 bytes free. Anchors come from changed_paths, which the distiller already receives and discards.
• Channel 1 — reconcile at write time. Each proposal declares new / supersedes / contradicts. Zero extra model calls; the evidence is already loaded.
• Channel 2 — removal as the trigger, machine-checked against the head SHA rather than trusted from the model.
• Channel 3 — the reviewer as sensor for semantic staleness, via the idle mailbox issue [Knowledge] intake mailbox: pr_debug landed-fix records (bugfix-record:v1) #135. Prerequisite: nothing in the review path records which rules were served or used today.
• Lifecycle + archive — ADR states, never delete. This is also the first mechanism that ever returns bytes to a full rule page.

Agent gets full lifecycle authority, bounded by five constraints (non-destructive retire, machine-checked retirement, named replacement for supersede, separate action budget, separate commit) so the PR stays a real gate.

Scope

Design only — no code ships with this PR. doc/RFC-knowledge-outdating.md plus its row in the doc/README.md features table.

All five CI linters pass locally: check_doc_links, check_doc_citations, check_knowledge_tree, check_wiki_lint, check_spec_freshness --strict.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XzDXtEBXmmogoZmGPEhapd

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.