Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,10 @@ installable release; see the roadmap in [README.md](README.md).

## [Unreleased]

### Changed

- **PreCompact rebuilder now fires by default** ([#746](https://github.com/robotrocketscience/aelfrice/issues/746)). Flips `DEFAULT_TRIGGER_MODE` in `src/aelfrice/context_rebuilder.py` from `"manual"` to `"threshold"`. The v1.4.0 ship-default of `manual` was a conservative hold pending production telemetry: with that posture the rebuilder was a no-op on every harness compaction unless the user added `[rebuilder] trigger_mode = "threshold"` to `.aelfrice.toml`. Both bench gates have now cleared: [#592](https://github.com/robotrocketscience/aelfrice/issues/592) (eval-harness commit-3, closed 2026-05-13: hot-start 100% at `trigger_threshold <= 0.6`, cold-start 75% across t in {0.5..0.8}) and [#687](https://github.com/robotrocketscience/aelfrice/issues/687) (Cohen's-κ multi-run ratification, closed 2026-05-13). Fresh installs now experience augment-mode rebuild without configuration. Opt out via `[rebuilder] trigger_mode = "manual"` in `.aelfrice.toml` — the config-load and hook-dispatch paths already honor the override; no plumbing changes. Per-compaction token spend rises by the rebuild block size (~5-6 KB observed); for token-sensitive workflows the opt-out remains available.

## [3.0.1] - 2026-05-13

### Security
Expand Down
23 changes: 12 additions & 11 deletions docs/context_rebuilder.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ rebuilder hood).
| Augment-mode coordination with the harness | Shipped |
| `additionalContext` JSON envelope on stdout | Shipped |
| Manual fire via `aelf rebuild` / `/aelf:rebuild` | Shipped (#141) |
| Trigger modes — manual + threshold | Shipped (#141; default `manual`) |
| Trigger modes — manual + threshold | Shipped (#141; default `threshold` since #746) |
| Threshold default sourced from calibration data | Shipped (#141; `benchmarks/context-rebuilder/calibration_v1_4_0.json`) |
| Trigger mode — dynamic | **Parked for v1.5** (#141; see § Dynamic mode (parked v1.5) below) |
| Suppress-mode coordination with the harness | **Parked for v2.x** |
Expand Down Expand Up @@ -128,11 +128,11 @@ investigated separately. Configured via `.aelfrice.toml`:

```toml
[rebuilder]
# v1.4 ship default. The PreCompact hook no-ops unless the user
# explicitly fires the rebuilder via `aelf rebuild` or
# `/aelf:rebuild`. Opt into auto-firing by switching to
# `trigger_mode = "threshold"`.
trigger_mode = "manual"
# Ship default since #746. The PreCompact hook fires when the
# harness compacts; opt out by setting this to "manual" if you
# only want the rebuilder to run on explicit `aelf rebuild` /
# `/aelf:rebuild` invocations.
trigger_mode = "threshold"

# Calibrated default from
# benchmarks/context-rebuilder/calibration_v1_4_0.json. Only
Expand All @@ -143,12 +143,13 @@ trigger_mode = "manual"
threshold_fraction = 0.6
```

- **`manual`** *(default at v1.4.0)*: PreCompact hook never fires
- **`manual`** *(opt-out since #746)*: PreCompact hook never fires
the rebuild block. Only explicit invocations
(`aelf rebuild` / `/aelf:rebuild`) emit a block. This is the
ship default until production telemetry confirms threshold-mode
is safe to default-on.
- **`threshold`**: PreCompact hook fires when called by Claude
(`aelf rebuild` / `/aelf:rebuild`) emit a block. Use this if the
augment-mode token-spend bump (~5-6 KB per compaction) is not
worth the context-preservation win for your workflow.
- **`threshold`** *(default since #746; bench gates #592 + #687
cleared 2026-05-13)*: PreCompact hook fires when called by Claude
Code's harness. The harness's own threshold gating is the trigger
signal; `threshold_fraction` documents the *calibrated operating
point* and is the reproducible source-of-truth for the default
Expand Down
19 changes: 12 additions & 7 deletions src/aelfrice/context_rebuilder.py
Original file line number Diff line number Diff line change
Expand Up @@ -194,13 +194,18 @@
Setting this raises a clear error in the hook path.
"""

DEFAULT_TRIGGER_MODE: Final[str] = TRIGGER_MODE_MANUAL
"""Ship-default trigger mode at v1.4.0.

Manual is the default until production telemetry confirms the
calibrated threshold. The threshold-mode default value is set by
`benchmarks/context_rebuilder/calibration_v1_4_0.json`; the user
opts in via `[rebuilder] trigger_mode = "threshold"`.
DEFAULT_TRIGGER_MODE: Final[str] = TRIGGER_MODE_THRESHOLD
"""Ship-default trigger mode.

Threshold (#746). v1.4.0 shipped with `manual` as a conservative
default pending production telemetry; the eval-harness commit-3
bench (#592) cleared on 2026-05-13 (hot-start 100% at
`trigger_threshold <= 0.6`, cold-start 75% across t in {0.5..0.8}),
ratified by the Cohen's-kappa multi-run gate (#687) the same day.
With both gates closed the rebuilder now fires by default; the
calibrated operating point is set by `DEFAULT_THRESHOLD_FRACTION`.

Opt out: `[rebuilder] trigger_mode = "manual"` in `.aelfrice.toml`.
"""

DEFAULT_THRESHOLD_FRACTION: Final[float] = 0.6
Expand Down
12 changes: 7 additions & 5 deletions tests/test_hook_pre_compact.py
Original file line number Diff line number Diff line change
Expand Up @@ -76,8 +76,9 @@ def _aelfrice_log(cwd: Path, lines: list[dict[str, object]]) -> Path:
p = cwd / ".git" / "aelfrice" / "transcripts" / "turns.jsonl"
p.parent.mkdir(parents=True, exist_ok=True)
p.write_text("\n".join(json.dumps(line) for line in lines) + "\n")
# The v1.4 ship default for `trigger_mode` is "manual"; these
# tests exercise the auto-fire path, so opt them into "threshold".
# Auto-fire is the ship default since #746; we still write the
# threshold mode explicitly so the test is self-documenting and
# robust to any future default flip.
cfg = cwd / ".aelfrice.toml"
if not cfg.exists():
# Disable v1.7 (#364) relevance floor in tests by default;
Expand Down Expand Up @@ -223,9 +224,10 @@ def test_pre_compact_falls_back_to_claude_transcript(
_set_db(monkeypatch, db)
no_git = tmp_path / "no_git"
no_git.mkdir()
# v1.4 default trigger_mode is "manual"; opt into auto-fire. Floor
# disabled so this test's assertion ("kitchen check" appears in
# rebuild output) is not gated on FTS5 indexing of the fixture.
# threshold is the ship default since #746 but we set it explicitly
# so the fixture documents intent. Floor disabled so this test's
# assertion ("kitchen check" appears in rebuild output) is not gated
# on FTS5 indexing of the fixture.
(no_git / ".aelfrice.toml").write_text(
'[rebuilder]\ntrigger_mode = "threshold"\n'
"[rebuild_floor]\nsession = 0.0\nl1 = 0.0\n",
Expand Down
30 changes: 22 additions & 8 deletions tests/test_rebuilder_triggers.py
Original file line number Diff line number Diff line change
Expand Up @@ -126,18 +126,32 @@ def _write_config(cwd: Path, body: str) -> None:
(cwd / ".aelfrice.toml").write_text(body, encoding="utf-8")


# --- TM1: manual mode is the default ------------------------------------
# --- TM1: threshold mode is the default (#746) --------------------------


def test_tm1_default_trigger_mode_is_manual() -> None:
"""Ship default at v1.4.0 must be manual.
def test_tm1_default_trigger_mode_is_threshold() -> None:
"""Ship default is threshold after #746.

The spec is explicit: threshold mode is opt-in until production
telemetry. If this test fails, someone has flipped the ship
default without re-reading the issue's "hard rules".
The v1.4.0 ship-default of manual was a conservative hold pending
production telemetry. Bench gates #592 (eval-harness commit-3)
and #687 (Cohen's-kappa multi-run validation) both closed on
2026-05-13, so #746 flipped the default to threshold. If this
test fails, re-read #746 before flipping back.
"""
assert DEFAULT_TRIGGER_MODE == TRIGGER_MODE_MANUAL
assert RebuilderConfig().trigger_mode == TRIGGER_MODE_MANUAL
assert DEFAULT_TRIGGER_MODE == TRIGGER_MODE_THRESHOLD
assert RebuilderConfig().trigger_mode == TRIGGER_MODE_THRESHOLD


def test_tm1_no_config_file_defaults_to_threshold(tmp_path: Path) -> None:
"""A fresh install with no .aelfrice.toml lands on threshold.

This is the user-visible promise of #746: nothing to configure for
auto-rebuild to fire. Belt + suspenders alongside the constant
check — the constant could be right while the loader returns
something else if a future refactor wires its own fallback.
"""
cfg = load_rebuilder_config(start=tmp_path)
assert cfg.trigger_mode == TRIGGER_MODE_THRESHOLD


def test_tm1_manual_mode_pre_compact_hook_no_ops(
Expand Down
Loading