diff --git a/CHANGELOG.md b/CHANGELOG.md index dcfd54f6b..cd3a6e9bc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,8 @@ installable release; see the roadmap in [README.md](README.md). ### Added +- **HRR persistence integration — docs bundle, closes #553 umbrella** ([#699](https://github.com/robotrocketscience/aelfrice/issues/699), closes [#553](https://github.com/robotrocketscience/aelfrice/issues/553)). Final sub-task of the HRR persistence umbrella. `docs/CONFIG.md` documents the `[retrieval] hrr_persist` TOML key (default `true`) and the `AELFRICE_HRR_PERSIST` env var override including the ephemeral-path auto-disable behaviour; `docs/COMMANDS.md` adds an *HRR persistence reporter* section explaining the three `aelf doctor` rows (`hrr.persist_enabled`, `hrr.on_disk_bytes`, `hrr.last_build_seconds`) and the `aelf status` `hrr.persist_state` one-line summary; `docs/feature-hrr-integration.md` acceptance-criteria checklist is updated to reflect shipped state with PR cross-references. Closes the five-PR HRR substrate: PR [#693](https://github.com/robotrocketscience/aelfrice/pull/693) (split-format save/load + cache mmap), PR [#701](https://github.com/robotrocketscience/aelfrice/pull/701) (ephemeral-path auto-disable, #695), PR [#703](https://github.com/robotrocketscience/aelfrice/pull/703) ([retrieval] hrr_persist TOML key, #698), PR [#704](https://github.com/robotrocketscience/aelfrice/pull/704) (`aelf doctor` reporter rows, #696), PR [#706](https://github.com/robotrocketscience/aelfrice/pull/706) (cold-start bench gate at N=50k, #697 — gate-shipped; bench-run capture stays open under `attn:bench-needed`). The `use_hrr_structural` default-flip remains out of scope for #553 and is gated separately on labelled-corpus evidence per the #154 composition tracker. + - **Eval-judge κ runner module** ([#687](https://github.com/robotrocketscience/aelfrice/issues/687)). New `benchmarks/context_rebuilder/kappa.py` implements pure-stdlib Cohen's-κ computation for inter-judge agreement across N≥3 judge-response JSONL files (same shape as `read_judge_responses` in `llm_judge.py`), plus optional judge-vs-baseline κ against a substring-exact-match baseline file. `compute_kappa_report()` aligns turn_idx sets via set-intersection, computes pairwise κ across all run-pairs (key shape `_vs_`), and emits the `judge_kappa.json` artifact specified in `docs/BENCHMARKS.md §Eval-judge calibration`. The `calibrated` boolean gate requires `inter_judge_kappa.min ≥ 0.70` AND `hot_start_fidelity_mean ≥ 0.80` AND `n_runs ≥ 3` — judge-vs-baseline κ is reported but does not gate. `cohens_kappa()` handles the p_e=1 edge case (perfect-agreement raters) by returning 1.0 directly instead of dividing 0/0. CLI entry point at `python -m benchmarks.context_rebuilder.kappa --runs ... --baseline ... --out ...` returns exit 0 when calibrated and exit 1 otherwise for CI gating. Sixteen tests cover known-κ values, perfect-agreement / perfect-disagreement / single-class edges, intersection alignment when judge runs cover different turn_idx sets, calibration thresholds and failure-reason emission, and CLI smoke (calibrated → exit 0, n_runs<3 → exit 1). - **`[retrieval] hrr_persist` TOML key for HRR structural-index persistence** ([#698](https://github.com/robotrocketscience/aelfrice/issues/698)). Config-plumbing follow-up to #691 (persist-aware `HRRStructIndexCache`). Adds a `[retrieval] hrr_persist` boolean key to `.aelfrice.toml` that controls whether the HRR structural index is written to and loaded from `/.hrr_struct_index/`. Resolution precedence: `AELFRICE_HRR_PERSIST` env var (highest — "0"/"false"/"no"/"off" disables; "1"/"true"/"yes"/"on" forces on) → `[retrieval] hrr_persist` TOML key → default `true`. New `is_hrr_persist_enabled()` resolver in `retrieval.py` mirrors the `is_hrr_structural_enabled()` template. New `_env_hrr_persist_override()` helper + `ENV_HRR_PERSIST` / `HRR_PERSIST_FLAG` constants follow the same shape as the other flag constants. `HRRStructIndexCache` gains an optional `persist_enabled: bool | None = None` construction field; `_resolve_persist_dir()` now consults env first (exact truthy/falsy match), then the field, then the default-true path. New `make_hrr_struct_cache()` factory in `retrieval.py` is the canonical construction site: it calls `is_hrr_persist_enabled()` and passes the result into the cache so callers get config-driven persistence without manual flag resolution. Non-boolean `hrr_persist` TOML values trace to stderr and fall through to the default. Nine new unit tests and three integration tests cover every precedence path including the env-wins-in-both-directions invariant. diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md index 26a5898ea..fffcfe2c3 100644 --- a/docs/COMMANDS.md +++ b/docs/COMMANDS.md @@ -36,9 +36,9 @@ DB resolves from `$AELFRICE_DB`, then `/aelfrice/memory.db` when |---|---| | `stats` | Belief / thread / lock / feedback counts. | | `health [--json]` | Structural auditor: orphan threads, FTS5 sync, locked contradictions, corpus volume. Includes a per-edge-type count breakdown (sorted by count desc, then alphabetically); empty store prints `no edges yet`. `--json` emits `{"audit": {...}, "features": {"edges_by_type": {...}}}`. Exits 1 on structural failure; corpus-volume warnings are informational. | -| `status` | Alias for `health`. | +| `status` | Alias for `health`. v3.0+ adds an `hrr.persist_state` summary line — see *HRR persistence reporter* below. | | `regime` | The v1.0 regime classifier output (`supersede` / `ignore` / `mixed` / `insufficient_data`). Informational; always exits 0. | -| `doctor` | Verify hook + statusline commands resolve. Inspects `bash