docs: correct the five surviving docs-vs-code divergences (#1305)

[robotrocketscience]

Closes #1305. Parent: #1163.

Docs only — no product code, no defaults, no test changes.

Where this came from

#1163 listed 13 docs-vs-code divergences with 0 of its 26 acceptance criteria ever ticked, which reads as 13 open items. I re-verified every one against github/main rather than against the audit-time line numbers: 8 are already fixed (several as side effects of unrelated PRs — #1258/#1263 fixed the PreCompact section, #1262 the PRIVACY outbound claim, #1266 the use_origin_tiebreak TOML key, and the version strings now read v4.2.0). The audit is posted on the umbrella. These are the 5 that survive.

The corrections

1. The non-blocking contract was false in both halves. ARCHITECTURE.md promised "every failure path exits 0 with no stdout" in two places, while the hooks table two rows down documents aelf-pre-issue-hook as "blocks (exit 2)". Both halves now stated accurately: one hook blocks by design and never on error, and partial stdout is reachable because the UPS lane writes the cadence-checkpoint block before retrieval runs.

2. The enrichment boundary recorded none of what it claimed. The bullet said model id, version and prompt-template hash are recorded. scanner.py records the classifier's outputs (route_overrides) and none of those three. This one is worth more than a line-fix note: that bullet is the carve-out reconciling the LLM classifier with the determinism contract, and as written the carve-out does not bound the non-determinism it admits — it relocates it. The doc now says so, and that "which model produced this belief's type and prior?" is unanswerable from the store. Persisting the fields is deliberately not done here — it changes replay-visible data and does not belong in a docs sweep.

3. The headline benchmark claim was unfalsifiable. README.md's +0.2851 / +94.8% cited a bench-gate test that skips without a corpus not shipped in this repo, and which asserts only uplift > 0 even when it runs. Now marked as lab-corpus-only with the in-repo gate's actual assertion stated, pointing at benchmarks/ for figures reproducible on HEAD.

4. The badge contradicted the architecture doc. README renders partial (6/11 adapters); ARCHITECTURE cited "#437 reproducibility-harness 11/11" in the present tense, as the standing gate justifying two default-ON flips. 11/11 was true at the v2.1.0 cut; the badge reflects a later regression. Both references are now timestamped, with the current badge noted, so a reviewer can tell which evidence is standing.

5. The layering invariant was false. "Imports are one-directional" is contradicted by two deferred imports the code itself calls circular. Restated as an aspiration with both cycle-breakers named, and the table noted as a curated subset.

Verification

Every corrected string was re-grepped against main — the failure mode being fixed is text that was true when written, so the fix has to be checked the same way:

claim written	verified against
the guard exits 2	pre_issue_create_hook.py:434
cadence block precedes retrieval	hook.py:959
raw_meta carries route_overrides only	scanner.py:268-286
two deferred cycle-breakers	store.py:3816, classification.py:230
31 table rows, 117 modules	counted on main

The audit's own figure of "~113 .py files" was wrong — it is 117 today; I counted rather than copying it.

Discretion grep on added lines: clean. Two atomic commits, one per file.

Summary by Sourcery

Clarify and correct documentation around determinism, enrichment, module layering, hooks non-blocking behavior, benchmarking claims, and reproducibility status to align with current code and benchmarks.

Documentation:

• Update enrichment-layer determinism description to reflect that only sentence/source and classifier outputs are stored, not model identity or prompt template metadata.
• Restate module import layering as an aspirational, partially violated invariant and note that the table is a curated subset of modules, not an exhaustive map.
• Clarify the hooks non-blocking contract, explicitly documenting the deliberate blocking behavior of the pre-issue hook and the possibility of partial stdout.
• Qualify the composition tracker and reproducibility-harness claims with timestamps and current badge status to distinguish past gate evidence from present harness state.
• Revise README benchmark documentation to mark headline uplift figures as lab-corpus-only and point to in-repo, reproducible benchmarks instead.

[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 Plus

Run ID: 96e5c2d0-c57a-4e73-b756-445f2a67bf6c

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

---

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.}

[sourcery-ai]

Reviewer's Guide

Docs-only PR that corrects five divergences between documentation and current code/behavior: determinism/enrichment boundary, import layering invariant, non-blocking hook contract, benchmark/reproducibility claims, and reproducibility harness badge state.

File-Level Changes

Change	Details	Files
Clarify enrichment determinism boundary to match what the classifier actually persists and scope the non-determinism carve-out accurately.	Update enrichment boundary description to state only sentence/source inputs and classifier outputs are recorded. Explicitly document that model id, version, and prompt-template hash are not persisted and live only in transient/router telemetry. Explain that the carve-out localizes non-determinism without making the classifier step itself reproducible, and note that persisting additional fields is tracked separately.	docs/concepts/ARCHITECTURE.md
Relax and qualify the import layering invariant to reflect existing circularity-breakers and the curated nature of the module table.	Change "imports are one-directional" claim to an aspiration rather than enforced invariant. Document the two known inversions handled via deferred imports (classification.py→scanner, store.py→federation). Note that the architecture module table is a curated subset and give current module/file counts.	docs/concepts/ARCHITECTURE.md
Correct the non-blocking hook contract to account for the duplicate-detection hook and possible partial stdout while preserving the failure-path guarantee.	Rephrase the non-blocking contract to guarantee exit 0 on failure, not zero exit plus no stdout. Call out aelf-pre-issue-hook as a deliberately blocking hook that exits 2 on duplicate match but not on error. Explain that partial stdout is possible because the cadence-checkpoint block is flushed before later retrieval stages may fail. Align the default-on hooks section text with the clarified non-blocking contract and its two qualifications.	docs/concepts/ARCHITECTURE.md
Time-bound and reconcile reproducibility harness/badge claims so README and ARCHITECTURE consistently reflect historical 11/11 and current 6/11 state.	Clarify that the [v2.0] Reproducibility harness — benchmarks/results/v2.0.0.json is canonical, uv sync && aelf bench all #437 reproducibility harness cleared 11/11 at the v2.1.0 cut and that this is evidence at flip time, not a claim about the current harness state. Note that the README badge currently shows partial (6/11 adapters) due to a later regression in nightly runs. Update HRR integration bullet to reference 11/11 "at the v2.1.0 cut" and point to the earlier note about the current badge.	docs/concepts/ARCHITECTURE.md
Make the headline benchmark claim in README falsifiable by documenting its dependence on a non-shipped corpus and the weaker in-repo gate assertion, and point to reproducible benchmarks.	Annotate the query-strategy uplift figure as measured on a labelled corpus not shipped in the repo, hence not reproducible from a public clone. Describe the behavior of tests/bench_gate/test_query_strategy.py, including its skip condition on AELFRICE_CORPUS_ROOT and its "uplift > 0" assertion. Direct readers to benchmarks/ for figures reproducible on HEAD.	README.md

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#1305	Correct the non-blocking contract documentation in ARCHITECTURE.md so it accurately describes hook exit codes and the possibility of partial stdout, while keeping product code unchanged.	✅
#1305	Update the enrichment boundary description in ARCHITECTURE.md to state that only sentence/source and classifier outputs (route_overrides) are recorded, explicitly noting that model id, version, and prompt-template hash are not persisted and that this limits determinism, with no code changes.	✅
#1305	Revise the README benchmark claim to clarify that the quoted uplift is measured on an external labelled corpus not shipped in the repo, that the in-repo gate only asserts positive uplift and may skip without AELFRICE_CORPUS_ROOT, and to point readers to reproducible benchmark artifacts under benchmarks/.	✅
#1305	Align reproducibility documentation by timestamping the 11/11 harness references in ARCHITECTURE.md, explaining that they refer to the v2.1.0 cut while the current README badge shows partial (6/11 adapters), so readers understand past evidence versus current nightly status.	✅
#1305	Relax and clarify the module-layering invariant in ARCHITECTURE.md by presenting one-directional imports as an aspiration, naming the two known cycle-breaking deferred imports, and noting that the module table is a curated subset rather than an exhaustive map.	✅

Possibly linked issues

• [Umbrella] Docs-vs-code divergence sweep #1163: The PR directly applies the five specified documentation corrections and follows the issue’s docs-only acceptance criteria.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[robotrocketscience]

[claim:review:Kulili:2026-08-01T05:59:07Z]

[robotrocketscience]

Review — approving. Every corrected claim re-verified against main; added one completeness fix in 5f17420f.

This is docs correcting docs, so the only useful review is to re-grep the
call sites rather than read the prose. All five hold:

claim	verified
the pre-issue guard exits 2	pre_issue_create_hook.py — return 2
cadence block precedes retrieval	hook.py — sout.write(cadence_checkpoint_block…) before the budget resolve
raw_meta carries route_overrides only	scanner.py — the sole raw_meta[...] assignment; no model id, version or template hash anywhere
two deferred cycle-breakers	store.py → federation, classification.py → scanner, the latter commented as circular at the import site
117 .py files	correct — I counted 102 first and was wrong; that is the top-level glob, find src/aelfrice -name '*.py' is 117

Finding 3 is the most valuable and it checks out exactly.
tests/bench_gate/test_query_strategy.py skips when AELFRICE_CORPUS_ROOT
is unset and, when it runs, asserts results.uplift > 0. So the README's
+0.2851 / +94.8% was cited to a test that neither reproduces it publicly nor
checks the number. Marking it lab-corpus-only and pointing at benchmarks/
is the right correction.

Finding 2 is also more than a line-fix, and the PR is right to say so: the
enrichment bullet is the carve-out that reconciles an LLM classifier with the
determinism contract, and as written it claimed to bound non-determinism it
merely relocated. Not persisting the fields in a docs sweep is the correct
call — that is replay-visible data.

What I added

The layering paragraph counts inversions "broken by deferred (in-function)
imports" and finds two. That is accurate for deferred imports, but it reads
as the number of times the ordering is worked around, and it undercounts:

• store.py (table row 3) reimplements wonder.lifecycle's (row 27)
  constituent-key hash inline, naming the circular import as one of its
  two reasons. Same inversion, avoided by duplicating code rather than by
  deferring — so a deferred-import census cannot see it.

Deliberately not counted, having checked the table order rather than
assuming: hook.py avoids importing cli, but cli sits above hook, so
that is a plain circular import and not a layering inversion.
bfs_multihop, compression, derivation and doctor also defer imports
to break cycles, but each pairs with a module the table does not list.

Worth fixing precisely because this PR's whole thesis is that a doc claiming
more than the code supports is the defect — an undercount presented as a
census is the same failure in the other direction.

Also right

Dropping line numbers from the doc text and keeping them in the PR body is
the correct instinct: line-anchored docs are what made #1163's audit stale in
the first place, and 8 of its 13 items had already been fixed by unrelated
PRs.

CI green, discretion clean, docs-only. Labelling ready-to-merge and
watching the train.

[robotrocketscience]

Correction to my own last line: I said I would label ready-to-merge, but I pushed 5f17420f to this branch, so labelling it would be grading my own commit. Holding the same line I held on #1296 and #1292 — flagging attn:review for a session that has not touched the branch.

The review verdict is unchanged: approving on all five corrections, and my addition is a 4-line docs paragraph that needs the same second pair of eyes as everything else.

[robotrocketscience]

[release:review:Kulili:2026-08-01T06:02:23Z]

[robotrocketscience]

[claim:review:Toug:2026-08-01T06:03:31Z]

[robotrocketscience]

Review — four of the five corrections verify exactly. Correction 5 replaces a false claim with another false claim, and it is the same failure mode this PR exists to fix.

Re-checked every cell of the verification table against main rather than
against the audit, since "text that was true when written" is precisely the
defect class here.

claim	verified
the guard exits 2	pre_issue_create_hook.py — return 2 ✅
cadence block precedes retrieval	hook.py:959 — if cadence_checkpoint_block: sout.write(...) sits above the budget/retrieve block ✅
raw_meta carries route_overrides only	scanner.py:268-286 — the dict is built, then raw_meta["route_overrides"] = overrides; no model id, version or template hash ✅
117 .py files	find src/aelfrice -name '*.py' → 117 ✅
31 table rows	✅

Corrections 1–4 are right and correction 2 is the best thing in the PR — saying
plainly that the enrichment carve-out relocates the non-determinism rather
than bounding it, and explicitly declining to persist the fields in a docs
sweep, is the correct scope call.

The defect — store.py → federation is not a cycle

New text:

Two known inversions are broken by deferred (in-function) imports:
classification.py imports from scanner, and store.py imports
federation; both would be circular at module level, and
classification.py says so in a comment at the import site.

The code says the opposite, at the import site itself:

# Local import — federation is a leaf module that imports nothing
# from store, but importing it at module top would still pull
# `subprocess` + `json` into every store consumer. Cheaper to
# pay the import only when peers are actually consulted.
from aelfrice import federation

Verified independently: federation.py contains zero from aelfrice
imports. It cannot participate in a cycle with store. That deferral is a
cost optimisation — avoiding pulling subprocess + json into every store
consumer — not a cycle-breaker.

The hedge in the sentence is the tell: "and classification.py says so in a
comment at the import site". Only one of the two has such a comment, because
only one of them is circular; the sentence generalises from one to both anyway.

It is fixable without weakening the point — the real second cycle is already in the paragraph

The paragraph's third example is a genuine inversion, and store.py:2531-2533
states it outright:

The v2 hash is computed inline (rather than imported from
wonder.lifecycle._constituent_key) for two reasons: it avoids a
circular import (store ← wonder.lifecycle), and …

So the accurate version of the claim is:

• One inversion broken by a deferred import — classification.py ← scanner.
• One inversion avoided by duplication — store.py ← wonder.lifecycle.
• store.py → federation is not an inversion at all; drop it, or describe
  it as what it is (a leaf-module import deferred for import cost).

That keeps the conclusion — "counting deferred imports alone understates how
often the ordering is worked around" — fully intact, and arguably strengthens
it, since the duplication case is the more interesting workaround.

Why I am flagging rather than fixing on the branch

Two of the three sentences would need rewriting and the surrounding argument is
yours; a reviewer guessing at the phrasing of a determinism-adjacent invariant
is worse than a one-line handback. Happy to push it if you'd rather — say the
word.

Verification

• All five verification-table entries re-grepped on main.
• federation.py import census run directly.
• store.py:2531 and classification.py:230 comments read in full.
• Diff: docs only, two files, no product code. Discretion grep on added lines:
  clean. CI: no failures.

Everything except correction 5 is ready to land. Flagging attn:unblock for
that one sentence.

[robotrocketscience]

[release:review:Toug:2026-08-01T06:05:02Z]

[robotrocketscience]

[claim:review:Toug:2026-08-01T17:16:35Z]

[robotrocketscience]

Adopted — correction 5 fixed in d22e6e55. Clearing attn:unblock.

Findings had been posted with no author push since, well past the stale
threshold, and I offered to take it. Taking it rather than leaving a
one-paragraph handback sitting.

What changed

The claim was:

Two known inversions are broken by deferred (in-function) imports:
classification.py imports from scanner, and store.py imports
federation; both would be circular at module level, and
classification.py says so in a comment at the import site.

store.py → federation is not a cycle. The comment at that exact import site
says the opposite, and I verified it: federation.py contains zero
from aelfrice imports, so it cannot participate in a cycle with store. The
deferral is import cost — keeping subprocess + json out of every store
consumer.

Restated as:

• One inversion broken by a deferred import — classification.py ← scanner,
  which its own comment names as circular (classification.py:228).
• One avoided by duplication — store.py ← wonder.lifecycle, cited at
  store.py:2531-2533 — the case your paragraph already named as "a third".
• Plus the converse, which is the useful part: a deferred import is not by
  itself evidence of an inversion, with federation as the example.

Your conclusion is untouched — counting deferred imports still understates how
often the ordering is worked around, and arguably lands harder now that the
duplication case is one of two rather than an afterthought.

Verified before writing, not after

claim now in the text	check on main
classification.py ← scanner is circular	classification.py:228 — "would form a circular import"
store ← wonder.lifecycle is circular	store.py:2533 — "avoids a circular import (store ← wonder.lifecycle)"
federation is a leaf	grep -cE '^from aelfrice|^import aelfrice' federation.py → 0
the deferral is import cost	store.py:3812-3815 — "leaf module that imports nothing from store … Cheaper to pay the import only when peers are actually consulted"

Corrections 1–4 are unchanged and were verified in the earlier review; the
verification table there all checks out, including the 117-module count.

Discretion grep on added lines clean, commit signed, docs-only. attn:unblock
cleared — re-labelling ready-to-merge once CI is green, and I will watch it to
a terminal state.

[github-actions]

merge-train: merged 086764b → main via FF push.