docs: #1075 tranche-2 doc-file audit — 24 fixes across 16 files

CHANGELOG/v3.md

@@ -615,7 +615,7 @@ The cadence-policy completion + conversation-aware retrieval wave.
 
 - **`urllib3` 2.6.3 → 2.7.0 for CVE patches** ([#640](https://github.com/robotrocketscience/aelfrice/issues/640)). Lockfile-only dependency bump pulled in via `uv lock` to clear two CVEs flagged by GitHub's dependency scanner. `urllib3` is a transitive dep (via `requests` in the publish workflow and the `gh` CLI's Python shim); aelfrice itself does not import it. No source change.
 
-[Unreleased]: https://github.com/robotrocketscience/aelfrice/compare/v3.7.0...HEAD
+[Unreleased]: https://github.com/robotrocketscience/aelfrice/compare/v3.8.0...HEAD
 [3.8.0]: https://github.com/robotrocketscience/aelfrice/compare/v3.7.0...v3.8.0
 [3.7.0]: https://github.com/robotrocketscience/aelfrice/compare/v3.6.0...v3.7.0
 [3.6.0]: https://github.com/robotrocketscience/aelfrice/compare/v3.5.1...v3.6.0

CITATION.cff

@@ -6,9 +6,11 @@ abstract: >
   It records facts, corrections, preferences, and requirements as beliefs
   with Beta-Bernoulli posterior confidence; supports user-locked beliefs
   with sharp decay-floor and demotion-pressure auto-correction; and
-  exposes the same eight operations through a CLI, an MCP server, and
+  exposes the same core operations through a CLI, an MCP server, and
   Claude Code slash commands.
 type: software
+version: 3.8.0
+date-released: "2026-06-30"
 authors:
   - name: "robotrocketscience"
 url: "https://github.com/robotrocketscience/aelfrice"
@@ -27,5 +29,6 @@ preferred-citation:
   title: "aelfrice: Bayesian memory for AI coding agents"
   authors:
     - name: "robotrocketscience"
+  version: 3.8.0
   year: 2026
   url: "https://github.com/robotrocketscience/aelfrice"

docs/audits/DOCS-AUDIT-2026-07-04-docfiles.md

@@ -0,0 +1,131 @@
+# DOCS-AUDIT-2026-07-04-docfiles
+
+**Scope:** tranche 2 of the #1075 v4.0.0 documentation audit — the remaining
+doc-file buckets deferred by `DOCS-AUDIT-2026-07-04.md` (doc-file surface) and
+the in-code ledgers (`-incode.md`, `-tests-bench.md`).
+
+**Audited against:** code at `github/main` HEAD `13f7d0b4` (v3.8.0 + post-release main).
+
+**Method:** 8-batch multi-agent fan-out, every line of every in-scope file read
+and checked; each CRITICAL/HIGH finding independently re-verified against the
+code before its fix was written; source line-pointer corrections re-grepped at
+HEAD before landing. Disposition per this issue's rules: current-behavior docs
+fixed in place; frozen snapshots (`docs/design/historical/`, `docs/adr/`,
+`docs/experiments/`, prior `docs/audits/` records) corrected via
+banner/annotation only; CHANGELOG entries verified against code at the
+corresponding tags; code-side drift filed separately, not papered over in docs.
+
+## Coverage
+
+**95 / 95 files audited (100%).** Every file appears below as a finding or in
+the verified-clean list; absence from the ledger would mean unaudited, not clean.
+
+| Bucket | Files |
+|---|---|
+| `CHANGELOG.md` + `CHANGELOG/v0–v3.md` | 5 |
+| `docs/design/*` (current-behavior) | 58 |
+| `docs/design/historical/*` | 13 |
+| `docs/adr/*` | 5 |
+| `docs/audits/*` (prior + current records) | 7 |
+| `docs/experiments/*` | 1 |
+| `tests/` READMEs + fixture | 4 |
+| `.github/pull_request_template.md` | 1 |
+| `CITATION.cff` | 1 |
+| **Total** | **95** |
+
+## Tally
+
+**24 findings: 0 CRITICAL, 2 HIGH, 14 MEDIUM, 8 LOW.** 24 fixed in place /
+annotated (0 deferred, 0 code-side). 71 files verified clean.
+
+### HIGH
+
+1. **`docs/audits/README.md`** — the audit index omitted
+   `DOCS-AUDIT-2026-07-04-tests-bench.md`, a record present on disk (the
+   tests/+benchmarks in-code tranche). A present record missing from the index
+   fails the coverage rule. → index entry added.
+2. **`docs/design/context_rebuilder.md`** — the delivery section documented the
+   rebuilder as a PreCompact hook emitting `additionalContext` via
+   `emit_pre_compact_envelope()`; superseded by #1031 (the harness rejects
+   PreCompact `additionalContext`; the block now ships on `session_start()` with
+   `source=="compact"`). → delivery-channel banner added; the original design
+   narrative and the `rebuild_v14` code path are unchanged.
+
+### MEDIUM
+
+- **`CHANGELOG/v3.md`** — `[Unreleased]` compare link read `v3.7.0...HEAD`
+  (double-counts everything shipped in v3.8.0) → `v3.8.0...HEAD`.
+- **`CITATION.cff`** — stale fixed operation count ("eight") vs the current
+  CLI / MCP / slash-command surface → version-agnostic phrasing.
+- **`docs/design/bfs_multihop.md`** (×2) — `BFS_EDGE_WEIGHTS` located in
+  `retrieval.py` (actually `bfs_multihop.py:61`, contradicting the doc's own
+  code block); function named `bfs_expand` (shipped as `expand_bfs`,
+  `bfs_multihop.py:118`).
+- **`docs/design/feature-aelf-confirm-cli.md`** — sample output showed
+  `mean 0.500->0.667`; shipped `_cmd_confirm` emits a single post-update mean
+  (`cli.py:2803-2807`).
+- **`docs/design/feature-temporal-spine.md`** — retrieval no-op guard is
+  `store.has_edge_type(EDGE_TEMPORAL_NEXT)` (`retrieval.py:3285`), not
+  `count_edges_by_type()`.
+- **`docs/design/historical/v2_derivation_worker.md`** — frozen spec cites
+  `tests/test_concurrency.py`, renamed post-ship to
+  `tests/test_worktree_concurrency.py` → audit-note annotation (body left as-authored).
+- **`docs/design/hook_hardening.md`** — `_format_hits` line pointer 419 → 1787.
+- **`docs/design/phantom_trigger_generation.md`** (×2) — `<cadence-checkpoint>`
+  pointer `hook.py:807–826` → `853–877`; `is_bfs_enabled` pointer
+  `retrieval.py:2258` → `2385`.
+- **`docs/design/v2_close_the_loop.md`** — dangling link
+  `docs/no_embeddings_first.md` (never existed) → `docs/concepts/PHILOSOPHY.md`
+  § "Determinism is the property".
+- **`tests/corpus/replay_soak/README.md`** (×3) — corpus grew a 7th ingest
+  source kind (`claude_memory`, `INGEST_SOURCE_CLAUDE_MEMORY`): layout tree,
+  row total (60→66), and the "6 non-`legacy_unknown` kinds" note all reconciled
+  to 7 kinds / 66 rows.
+
+### LOW
+
+- **`CITATION.cff`** — added `version: 3.8.0` + `date-released` (CFF 1.2.0 recommends both).
+- **`docs/design/bfs_multihop.md`** — stale `store.py:617` / `store.py:559,576,584`
+  line pointers dropped in favour of symbol names (`propagate_valence`,
+  `_fire_invalidation`).
+- **`docs/design/context_rebuilder.md`** — turn-window default narrative said 10;
+  shipped `DEFAULT_TURN_WINDOW_N = 50`.
+- **`docs/design/feature-correction-detection-eval.md`** — `relationship_detector.py`
+  pointers `:73-78, :322` → `:75-80, :344`.
+- **`docs/design/feature-type-aware-compression.md`** — `resolve_use_type_aware_compression`
+  pointer `retrieval.py:1703-1731` → `2013-2040`.
+- **`docs/design/phantom_trigger_generation.md`** — `hook_manifest.json` count 8 → 10.
+- **`docs/design/relevance-signal.md`** — deferred-note "PreCompact rebuilder
+  injects" reworded to the SessionStart(compact) reality (#1031).
+- **`docs/design/v3_relatedness_philosophy.md`** — `aelf doctor dedup` →
+  `aelf doctor --dedup` (flag, not subcommand).
+
+## Recurring themes
+
+- **#1031 PreCompact→SessionStart(compact) move** recurs across three docs
+  (`context_rebuilder`, `relevance-signal`, and — fixed in prior tranches —
+  the hook/test docstrings). The PreCompact hook no longer injects.
+- **Post-ship default flips / renames** under-documented: `claude_memory`
+  ingest source kind (replay_soak corpus), `expand_bfs` symbol, temporal-spine
+  guard.
+- **Source line-pointer drift** is the dominant LOW class; where a pointer was
+  purely positional it was dropped in favour of the symbol name to resist
+  re-drift.
+
+## Verification limits
+
+- **Lab-sourced measurement numbers** (benchmark F1 / coverage figures cited in
+  design docs and CHANGELOG) cannot be re-derived from the public tree; checked
+  only for internal consistency and treated as externally sourced, per the
+  issue's sole permitted verification limit.
+- **`tests/fixtures/issue_creation_audit/issue_521_body.md`** is a verbatim
+  fixture copy of a past issue body used as test input; verified-clean as a
+  frozen fixture, not audited against current code (it must stay byte-identical
+  for the test).
+
+## Remaining on #1075 after this tranche
+
+Only the **v4.0.0 release cut** to PyPI per `docs/concepts/RELEASING.md`. The
+documentation surface — doc-file (`-07-04.md`), in-code `src/` (`-incode.md`),
+in-code `tests/`+`benchmarks/` (`-tests-bench.md`), and these remaining
+doc-file buckets — is now fully in the ledger set.

docs/audits/README.md

@@ -7,3 +7,5 @@ Point-in-time analysis snapshots. Each file is dated and frozen; if a finding is
 - [`DOCS-AUDIT-2026-06-10.md`](DOCS-AUDIT-2026-06-10.md) — full documentation audit (≈2,500 claims vs HEAD, run at v3.5.0; #957).
 - [`DOCS-AUDIT-2026-07-04.md`](DOCS-AUDIT-2026-07-04.md) — doc-file-surface audit vs HEAD `33b7ddd5` (v3.8.0 + post-release main), v4.0.0 release gate; #1075. 0 CRITICAL/HIGH, 9 MEDIUM, 8 LOW, 1 code-side. In-code documentation layer (552 .py) and remaining doc-file buckets (CHANGELOG, docs/design, ADRs, prior audits, experiments, tests/.github docs, CITATION.cff — ~90 files) deferred to follow-ups.
 - [`DOCS-AUDIT-2026-07-04-incode.md`](DOCS-AUDIT-2026-07-04-incode.md) — in-code documentation layer (docstrings / `--help` / MCP descriptions across 103 `src/aelfrice/` .py) vs HEAD `33b7ddd5`, v4.0.0 release gate; #1075. 4 CRITICAL + 43 HIGH fixed in place; 48 MEDIUM/LOW + 1 discretion-sensitive HIGH confirmed + deferred; 1 rejected on adversarial re-verify. Closes #1077. `tests/` + `benchmarks/` .py docstrings deferred.
+- [`DOCS-AUDIT-2026-07-04-tests-bench.md`](DOCS-AUDIT-2026-07-04-tests-bench.md) — in-code documentation layer of `tests/` (387 .py) + `benchmarks/` (48 .py) vs HEAD `github/main`, v4.0.0 release gate; #1075. 2 CRITICAL + 33 HIGH + 10 MEDIUM + 7 LOW; 49 fixed in place, 2 deferred as code-side defects, 1 dropped on re-verify. Completes the deferred `tests/`+`benchmarks/` docstring tranche.
+- [`DOCS-AUDIT-2026-07-04-docfiles.md`](DOCS-AUDIT-2026-07-04-docfiles.md) — remaining doc-file buckets (CHANGELOG vs tags, `docs/design/*` incl. `historical/`, `docs/adr/*`, prior `docs/audits/*`, `docs/experiments/*`, `tests/` READMEs, `.github/`, `CITATION.cff` — 95 files) vs HEAD `13f7d0b4`, v4.0.0 release gate; #1075. 0 CRITICAL, 2 HIGH, 14 MEDIUM, 8 LOW; 24 fixed/annotated in place. Completes the tranche-2 doc-file surface.

docs/design/bfs_multihop.md

@@ -87,7 +87,7 @@ structure for BFS to find non-trivial chains.
 ### Pseudocode
 
 ```python
-def bfs_expand(
+def expand_bfs(
     store: MemoryStore,
     seeds: list[Belief],          # tier-0 + tier-1 + tier-2.5 hits
     max_depth: int = 2,
@@ -203,7 +203,7 @@ reads labeled fixtures from `tests/corpus/v2_0/derived_from_edge/`. The
 edge remains at weight 0.70 while the gate is pending; below-floor closes
 #388 as `wontfix` and the weight entry drops to 0.0.
 
-Constants live in `src/aelfrice/retrieval.py` next to the BFS
+Constants live in `src/aelfrice/bfs_multihop.py` next to the BFS
 implementation, not in `models.py` — the BFS weights are a
 retrieval-tier hyperparameter, distinct from `EDGE_VALENCE` (which
 governs feedback propagation through `propagate_valence`). Keeping
@@ -269,7 +269,7 @@ Two options were considered:
 duration of one BFS call; before adding a dst to the next frontier,
 check membership. O(1) amortized lookup; trivial cycle prevention;
 matches the existing pattern in `MemoryStore.propagate_valence`
-(`store.py:617`), which already uses this approach in the codebase.
+(`store.py`), which already uses this approach in the codebase.
 
 **(b) LIMIT-based truncation.** Rely on `total_budget_nodes` to
 implicitly terminate any cycle: a cycle would be discovered as a
@@ -306,7 +306,7 @@ BFS is **L3**, sitting after the prior tiers in the unified pipeline:
   query ──> retrieve() ──>│ L0: list_locked_beliefs()            │
                           │ L1: store.search_beliefs(query, ...) │
                           │ L2.5: entity_index.lookup(query, ...)│  (#143)
-                          │ L3: bfs_expand(seeds=L0+L1+L2.5, ...) │  (this spec)
+                          │ L3: expand_bfs(seeds=L0+L1+L2.5, ...) │  (this spec)
                           └──────────────────────────────────────┘
                                           │
                                   token-budget pack
@@ -395,7 +395,7 @@ mutation. BFS expands the cached value (the result list) but does
   current belief contents).
 - The current edge graph is mutated through `insert_edge`,
   `update_edge`, `delete_edge` — all three already fire
-  `_fire_invalidation()` (verified in `store.py:559,576,584`).
+  `_fire_invalidation()` (verified in `store.py`).
 - The current belief contents are mutated through `insert_belief`,
   `update_belief`, `delete_belief` — all three already fire
   invalidation.
@@ -545,12 +545,12 @@ output exactly — same beliefs, same order. BFS is gated.
 
 ## Acceptance criteria for the implementation PR
 
-1. `BFS_EDGE_WEIGHTS` constant lands in `src/aelfrice/retrieval.py`
+1. `BFS_EDGE_WEIGHTS` constant lands in `src/aelfrice/bfs_multihop.py`
    with the values in this spec.
-2. `bfs_expand()` function implemented per the pseudocode above,
+2. `expand_bfs()` function implemented per the pseudocode above,
    stdlib-only.
 3. `retrieve_v2` accepts `use_bfs` and the four BFS kwargs; routes
-   through `bfs_expand` when `use_bfs=True`; populates
+   through `expand_bfs` when `use_bfs=True`; populates
    `RetrievalResult.bfs_chains` with the expansion edge-type paths.
 4. `tests/test_bfs_multihop.py` covers the three fixture chains
    (decisional, pruned informational, contradiction), determinism,

docs/design/context_rebuilder.md

@@ -329,7 +329,7 @@ seed the rebuild query. Source: the project's
 tail of this file directly — fast, no network, no DB roundtrip
 required for the seed.
 
-`N` is a config key. Initial value: 10 (5 user, 5 assistant).
+`N` is a config key. Default: 50 (`DEFAULT_TURN_WINDOW_N`; `[rebuilder] turn_window_n` in `.aelfrice.toml`).
 Eval-tunable.
 
 ### Rebuild algorithm (as shipped at v1.4.0)
@@ -365,6 +365,8 @@ def rebuild_v14(
     """
 ```
 
+> **Delivery channel (updated by #1031):** the rebuild block now ships on the **SessionStart** hook with `source=="compact"` — the harness rejects `additionalContext` emitted from a PreCompact hook, so `pre_compact()` no longer injects. The mechanism described below is the original PreCompact design, retained for context; the block content and the `rebuild_v14` code path are unchanged.
+
 The `pre_compact()` hook in `aelfrice.hook` reads the JSON payload
 from stdin, locates a transcript (canonical `turns.jsonl` first,
 the harness's transcript_path as fallback), drives `rebuild_v14`,

docs/design/feature-aelf-confirm-cli.md

@@ -38,7 +38,7 @@ Exit codes:
 ## Output (stdout on success)
 
 ```
-confirmed <belief-id>: alpha 1.000->2.000, mean 0.500->0.667
+confirmed <belief-id>: alpha 1.000->2.000, mean 0.667
 ```
 
 Fields:

docs/design/feature-correction-detection-eval.md

@@ -240,7 +240,7 @@ The corpus itself does not regress: rows added later strictly grow the fixture,
 
 ## Implementation prereqs
 
-- `src/aelfrice/relationship_detector.py:73-78, :322` — verdict labels + `classify` entry point.
+- `src/aelfrice/relationship_detector.py:75-80, :344` — verdict labels + `classify` entry point.
 - `src/aelfrice/value_compare.py:194, :267` — `extract_values` + `find_conflicts`.
 - `tests/corpus/v2_0/contradiction/django_v0_1.jsonl` — schema precedent (relabel target).
 - `tests/bench_gate/test_contradiction.py`, `tests/bench_gate/test_contradiction_v3.py` — sibling bench-gate patterns to mirror.

docs/design/feature-temporal-spine.md

@@ -33,7 +33,7 @@ Three components, all deterministic and embeddings-free (#605):
    both directions, depth 1, node budget 32
    (`temporal_spine_budget` / `AELFRICE_TEMPORAL_SPINE_BUDGET`).
    Appended after L1 candidates — never displaces them pre-packing.
-   No-op guard via `count_edges_by_type()`: zero spine edges → empty
+   No-op guard via `has_edge_type(EDGE_TEMPORAL_NEXT)`: zero spine edges → empty
    lane at ~zero cost, byte-identical output for spineless stores.
    Telemetry: `LaneTelemetry.temporal_spine` (packed survivors) +
    `temporal_spine_candidates` (pre-pack discoveries); the delta is the

docs/design/feature-type-aware-compression.md

@@ -99,7 +99,7 @@ for cb in compressed_candidates:
 
 ### Configuration
 
-A new `use_type_aware_compression` flag follows the established convention at `retrieval.py:1703-1731` (`resolve_use_type_aware_compression`):
+A new `use_type_aware_compression` flag follows the established convention at `retrieval.py:2013-2040` (`resolve_use_type_aware_compression`):
 
 1. `AELFRICE_TYPE_AWARE_COMPRESSION=1` env var (highest precedence; truthy/falsy normalised).
 2. `retrieve(..., use_type_aware_compression=True)` kwarg.

docs/design/historical/v2_derivation_worker.md

@@ -4,6 +4,8 @@ Spec for issue [#264](https://github.com/robotrocketscience/aelfrice/issues/264)
 
 Status: spec, no implementation. Recommendation included; decision is the user's.
 
+> **Audit note (2026-07-04, #1075):** the concurrency test referenced below as `tests/test_concurrency.py` was renamed post-ship; it now lives at `tests/test_worktree_concurrency.py`. Frozen spec body left as-authored.
+
 ## What's being decided
 
 Four contract calls left open by the issue body:

docs/design/hook_hardening.md

@@ -54,7 +54,7 @@ framing around them was.
 
 ## What the hook actually emits today
 
-`src/aelfrice/hook.py:_format_hits` (line 419) builds the block:
+`src/aelfrice/hook.py:_format_hits` (line 1787) builds the block:
 
 ```
 <aelfrice-memory>

docs/design/phantom_trigger_generation.md

@@ -32,7 +32,7 @@ to fan out `Task` subagents that produce research documents; the
 aelfrice CLI only runs deterministic gap-analysis (`wonder/dispatch.py` — "no
 LLM calls, no randomness, no filesystem writes") and then persists the returned
 documents via `wonder_ingest` (`wonder/lifecycle.py:95`). Every per-turn hook
-(`hook_manifest.json`, 8 entries) is likewise strictly deterministic.
+(`hook_manifest.json`, 10 entries) is likewise strictly deterministic.
 
 This boundary is non-negotiable and is what makes the design tractable:
 **aelfrice can decide *when* a phantom-generation opportunity exists, but it
@@ -80,7 +80,7 @@ act — which is the conservative posture for a feature that spends tokens.
 
 ### 3.2 Precedent: the cadence-checkpoint block
 
-This is not a new injection shape. `hook.py:807–826` already writes a
+This is not a new injection shape. `hook.py:853–877` already writes a
 **default-off, per-turn, fail-soft** `<cadence-checkpoint>` sub-block into the
 UserPromptSubmit stdout ahead of the `<aelfrice-memory>` block (#870). The
 phantom-opportunity note is the same shape: a small tagged block, gated on a
@@ -154,7 +154,7 @@ opt-in posture (#606, ADR-0003 dec-4):
 - **Default-off opt-in flag.** `should_trigger_phantom_generation(explicit, *, start)`
   resolving `AELFRICE_PHANTOM_GENERATION` env > kwarg > `[phantom_generation] enabled`
   TOML > `False`. Byte-for-byte the `is_bfs_enabled` resolver shape
-  (`retrieval.py:2258`). A fresh install is unaffected.
+  (`retrieval.py:2385`). A fresh install is unaffected.
 - **Per-session fire budget.** At most `max_fires_per_session` opportunity notes
   per session (default **3**, §7 decision 4). Stored in `session_ring` state,
   which already carries per-session counters (`update_p3_velocity_state`,
@@ -224,7 +224,7 @@ others as needed.
 - ADR-0003 decision 4 — keep-opt-in default posture (locked).
 - `slash_commands/wonder.md`, `wonder/lifecycle.py`, `wonder/dispatch.py` — the
   existing explicit phantom path and the LLM-dispatch boundary.
-- `hook.py:807–826` — the `<cadence-checkpoint>` default-off per-turn injection
+- `hook.py:853–877` — the `<cadence-checkpoint>` default-off per-turn injection
   precedent.
 - `session_ring.py` — per-session counter + dedup state.
-- `retrieval.py:2258` (`is_bfs_enabled`) — default-off flag-resolver house style.
+- `retrieval.py:2385` (`is_bfs_enabled`) — default-off flag-resolver house style.