docs: post-implementation scoring docs pass (#1075)

[robotrocketscience]

Summary

The post-implementation documentation pass the #1075 operator directive
sequenced as the last step before the v4.0.0 cut:

Order: audit PRs merged (incl. #1088) → #1081 + #1086 land → docs pass → cut v4.0.0.

#1081 landed (PR #1101) and #1086 closed on its junk-sink objective, so the
belief-scoring behavior that shipped after the four accuracy tranches is now
documented, and the docs reflect HEAD.

Refs #1075. This does not close the umbrella — the v4.0.0 cut is the final
gate step.

What lands

Documentation for behavior on main at 748a225a:

• Exposure is not endorsement (fix(feedback): make retrieval-exposure audit-only by default (#1086) #1091) — retrieval no longer moves the
  Beta-Bernoulli posterior by default (AELFRICE_EXPOSURE_UPDATES_POSTERIOR,
  default off); a surfacing is logged for the recurrence record but leaves α/β
  untouched. Recurrence is a separate axis (corroboration_count), never
  conflated into μ. → PHILOSOPHY.md, ARCHITECTURE.md, HARNESS_INTEGRATION.md.
• Entity-persistence demotion lane (Entity-persistence demotion prior: a deterministic organic sink for coordination junk (follow-up to #1086/#1081) #1096/fix(store): neutral-only beliefs absent from entity-persistence map (#1098) #1099) and origin-priority
  tie-break (Ingest claude-memory as a default-on source, ranked above conversational capture #1089) — the two new default-off retrieval flags. → CONFIG.md
  (two ### subsections), ARCHITECTURE.md (retrieval-lane section),
  LIMITATIONS.md.
• aelf introspect / retire / restore (Stored beliefs are more conversational expected #1081) — the new belief-curation
  verbs. → COMMANDS.md, SLASH_COMMANDS.md (count 26→29).
• Provenance/limitations touch-ups → PRIVACY.md, ROADMAP.md.
• ### Documentation note under [Unreleased]; ledgered in
  docs/audits/DOCS-AUDIT-2026-07-06-post-impl-scoring.md.

Documents HEAD, not the directive verbatim

The directive's feature list predates the #1086 measurement outcomes. Two
corrections were load-bearing:

• The organic sink is the entity-persistence demotion lane (default-off),
  not decay-to-hibernation — a temporal/cold-decay sink was measured
  empirically inert (the junk is hot, not stale).
• The decided-vs-floated / EDGE_RESOLVES producer did not ship (de-scoped,
  feat(lifecycle): forward-only decided-vs-floated resolution — EDGE_RESOLVES ingest producer (fix #4 of #1086, de-scoped) #1100 closed). introspect reports a floated-vs-decided status off existing
  edges only; no ingest producer was added.

Care taken not to over-correct

• The manual aelf sweep-feedback path still applies a +ε posterior bump
  when run — only the automatic/hook exposure default changed, so those docs
  stay accurate.
• RESOLVES is a real shipped wonder-lifecycle edge type (distinct from the
  de-scoped fix-feat: add Belief/Edge dataclasses and config module #4 producer) — its docs are left as-is.

Verification

Flag names, env vars, defaults, PR numbers, and API symbols cross-checked
against 748a225a code; the two cited regression-lock tests
(test_hook_fire_records_exposure_without_moving_posterior,
test_original_alpha_beta_unchanged_on_hit) confirmed present on main.
Docs-only change; no runtime surface touched.

[sourcery-ai]

Sorry @robotrocketscience, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Important

Review skipped

Ignore keyword(s) in the title.

⛔ Ignored keywords (2)

• docs:
• release:

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: ab61d977-948e-4d4c-9788-c99aae0acbea

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/issue-1075-post-impl-scoring

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

PR-size soft cap

This PR is over the advisory size threshold:

• 117 changed lines (limit: 200)
• 12 changed files (limit: 3)

Bigger PRs collide with more open work, which under the parallel-session workflow tends to produce repeated attn:merge-conflict cycles (see #602). When practical, split into smaller PRs that each touch a focused surface.

This is advisory only — nothing is blocked. If the size is intentional (large refactor, module removal, generated code), apply the size:override label and this comment will be removed on the next push.

[robotrocketscience]

[claim:review:garsecg:2026-07-06T19:50:33Z]

[robotrocketscience]

Review: verified against code at HEAD 748a225a — approve.

Docs-only pass; treated as a factual-accuracy audit of every load-bearing claim vs the actual surface on main:

• AELFRICE_EXPOSURE_UPDATES_POSTERIOR — present; record_retrieval gates update_posterior on _exposure_updates_posterior(), default off (audit-only). ✓
• use_entity_persist_demote / AELFRICE_ENTITY_PERSIST_DEMOTE and use_origin_tiebreak / AELFRICE_ORIGIN_TIEBREAK — both present in retrieval.py, both default False. ✓
• S1 = durable / (durable + transient + 1) — matches store.entity_persistence_scores docstring + body exactly, incl. the durable/transient token classification (file_path/error_code/non-bare identifier vs version/branch/bare-number). ✓
• Penalty clamp min(0, …·log(S1 + ε)) and pure-demotion semantics — match _entity_persist_penalty. ✓
• Origin tie-break is a tie-break, not a rerank lane (refuted feat(retrieval): default-off origin-tier rerank lane de-ranking doc chunks below user facts (#1011) #1013); applies in both ranked tiers — matches _origin_priority + call sites. ✓
• introspect / retire / restore — CLI subparsers registered in cli.py; store methods soft_delete_belief / restore_belief / entity_persistence_scores present; 3 new slash files present; count 26→29 correct. ✓
• Both cited regression tests present on main (test_hook_fire_records_exposure_without_moving_posterior, test_original_alpha_beta_unchanged_on_hit). ✓

CI green; discretion grep clean on added lines; single signed commit; FF on main.

Non-blocking nit (optional): ARCHITECTURE.md/CONFIG.md render the penalty as min(0, log(S1 + ε)), but the code multiplies by ENTITY_PERSIST_DEMOTE_WEIGHT — min(0, WEIGHT·log(S1 + ε)). The shape/sign/clamp are all correct; only the scaling coefficient is elided. Fine to leave as-is or fold the coefficient in on a later touch.

Labeling ready-to-merge. This advances the #1075 docs-pass gate step; it does not cut v4.0.0 (that remains the separate final gate).

[github-actions]

merge-train: merged 8c848ff → main via FF push.

[robotrocketscience]

[release:review:garsecg:2026-07-06T19:54:25Z]