docs: belief retention class + aging policy spec (#290)

[robotrocketscience]

Summary

Spec memo for #290. Phase-3 of the #286 redesign — the foundational typing axis that ranking, aging, and promotion all consume. Doc-only — no code change. Posted for ratification.

Core moves:

1. New orthogonal axis retention_class with three live values: fact, snapshot, transient (plus unknown for migration). Distinct from the existing type enum, which describes form not expected lifetime.
2. Defaults per ingest path. Filesystem/git/CLI-remember → fact. Transcript/hook → snapshot. transient requires explicit operator opt-in. Table in §2.
3. Soft down-weight in ranking, not hard expiry. Composite score from Rebuild redesign: silent-vs-always contract + relevance floor #289 gains a retention_age_multiplier(class, age_days) term. Per-class exponential decay with floor (fact ~300d half-life, snapshot 14d, transient 1d). Locks force multiplier = 1.0.
4. Promotion: snapshot → fact when corroboration_count >= 3 AND distinct_sessions >= 2 AND no contradiction. Reuses [phantom-prereqs T1] Belief corroboration tracking — sibling table + ingest recorder #190 corroboration recorder. Doctor-pass opt-in (aelf doctor --promote-retention, mirrors feat(doctor): --classify-orphans pass for un-typed low-prior beliefs (#206) #253). No demotion — contradictions handle correctness.
5. Migration via _maybe_classify_retention_class(), schema-meta gated, heuristic by source_kind. legacy_unknown rows stay unknown.

Decision asks (nine)

Bottom of the memo. Schema shape, defaults table, transient opt-in, multiplier shape, lock override, calibration plan, promotion thresholds, no-demotion, migration heuristic.

What ships if ratified

Three PRs:

1. Schema + score-formula change + migration helper (~500 lines)
2. Per-ingest defaults wired across scanner / ingest / hooks (~250 lines)
3. Promotion lane via aelf doctor --promote-retention (~300 lines)

Test plan

• Memo cross-references Context rebuild redesign — scoping (parent) #286, v2.0 substrate decision: multi-axis vs single-axis uncertainty #196, [v2.0] Phantom promotion-trigger rule — three rejected naive triggers, need a benchmarked rule #229, [phantom-prereqs T1] Belief corroboration tracking — sibling table + ingest recorder #190, feat(doctor): --classify-orphans pass for un-typed low-prior beliefs (#206) #253, fix: re-ingest row inflation — dedup by content_hash (#219) #283, Context rebuild surfaces duplicate + off-topic beliefs; ranking has no relevance floor or output-dedup #281
• Code touchpoints listed in Provenance
• No code change; nothing to test
• Ratification or override comment from maintainer

Refs #290, #286

[robotrocketscience]

[claim:review:Gylf:2026-04-29T02:29:16Z]

[robotrocketscience]

[release:review:Gylf:2026-04-29T02:29:36Z]