1# Configurable Auto-Compact Threshold Implementation Plan
2
3> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
4
5**Goal:** Add persisted auto-compaction threshold presets to the interactive TUI settings.
6
7**Architecture:** Keep automatic triggering in `packages/agent/modes`. Thread an optional integer percentage from persisted `agent.Config` into `modes.InteractiveConfig`, normalize missing or invalid values to 85%, and let zero disable only percentage-based triggers. Reuse the settings dialog's existing fixed-option picker and settings-store persistence path.
8
9**Tech Stack:** Go, standard library, Zot's existing TUI settings dialog, JSON configuration.
10
11## Global Constraints
12
13- Supported values are `0` (off), `70`, `80`, `85`, and `90`.
14- Missing or invalid persisted values resolve to `85`.
15- Disabling the threshold does not disable manual compaction or HTTP 413 recovery.
16- Do not add dependencies or change non-interactive compaction behavior.
17- Preserve unrelated working-tree changes and stage only this feature.
18
19---
20
21### Task 1: Configuration and threshold decision
22
23**Files:**
24- Modify: `packages/agent/config.go`
25- Modify: `packages/agent/modes/interactive.go`
26- Create: `packages/agent/modes/auto_compact_test.go`
27- Modify: `packages/agent/cli.go`
28
29**Interfaces:**
30- Produces: `Config.AutoCompactThreshold *int`
31- Produces: `InteractiveConfig.AutoCompactThreshold *int`
32- Produces: `normalizeAutoCompactThreshold(*int) int`
33- Produces: `shouldAutoCompact(inputTokens, contextWindow, thresholdPercent int) bool`
34
35- [ ] **Step 1: Write failing normalization and decision tests**
36
37Add table-driven tests proving nil and invalid values resolve to 85, supported presets survive unchanged, zero disables percentage checks, and 70/80/85/90 trigger exactly at their boundaries.
38
39```go
40func TestNormalizeAutoCompactThreshold(t *testing.T) {
41	tests := []struct {
42		name string
43		value *int
44		want int
45	}{
46		{name: "missing", value: nil, want: 85},
47		{name: "off", value: intPtr(0), want: 0},
48		{name: "seventy", value: intPtr(70), want: 70},
49		{name: "invalid", value: intPtr(42), want: 85},
50	}
51	// Assert normalizeAutoCompactThreshold(test.value) == test.want.
52}
53
54func TestShouldAutoCompactUsesConfiguredThreshold(t *testing.T) {
55	if shouldAutoCompact(84, 100, 85) {
56		t.Fatal("84% must remain below an 85% threshold")
57	}
58	if !shouldAutoCompact(85, 100, 85) {
59		t.Fatal("85% must trigger an 85% threshold")
60	}
61	if shouldAutoCompact(100, 100, 0) {
62		t.Fatal("off must disable percentage-triggered compaction")
63	}
64}
65```
66
67- [ ] **Step 2: Run tests and verify RED**
68
69Run:
70
71```sh
72go test ./packages/agent/modes -run 'TestNormalizeAutoCompactThreshold|TestShouldAutoCompactUsesConfiguredThreshold' -count=1
73```
74
75Expected: compilation failure because the normalization and decision helpers do not exist.
76
77- [ ] **Step 3: Add optional configuration and minimal helpers**
78
79Add `AutoCompactThreshold *int` with JSON name `auto_compact_threshold` to both configuration structs. Implement normalization for exactly `0`, `70`, `80`, `85`, and `90`, defaulting all other values to `85`. Replace the hard-coded fraction check with the normalized percentage helper and pass the config field through `cli.go`.
80
81- [ ] **Step 4: Run focused tests and verify GREEN**
82
83Run:
84
85```sh
86go test ./packages/agent/modes -run 'TestNormalizeAutoCompactThreshold|TestShouldAutoCompactUsesConfiguredThreshold' -count=1
87```
88
89Expected: PASS.
90
91### Task 2: Persistence and TUI preset picker
92
93**Files:**
94- Modify: `packages/agent/settings_store.go`
95- Modify: `packages/agent/settings_store_test.go`
96- Modify: `packages/agent/modes/interactive.go`
97- Modify: `packages/agent/modes/auto_compact_test.go`
98
99**Interfaces:**
100- Extends: `SettingsStore.SetAutoCompactThreshold(percent int) error`
101- Consumes: `normalizeAutoCompactThreshold(*int) int`
102
103- [ ] **Step 1: Write failing persistence and settings-item tests**
104
105Add a settings-store test that writes `70` into an isolated `$ZOT_HOME` and verifies `auto_compact_threshold` plus an unrelated config field. Add a modes test that opens settings with missing configuration and verifies the option values are `0`, `70`, `80`, `85`, `90` with `85` selected.
106
107```go
108func TestConfigSettingsStorePersistsAutoCompactThreshold(t *testing.T) {
109	t.Setenv("ZOT_HOME", t.TempDir())
110	if err := SaveConfig(Config{Theme: "dark"}); err != nil {
111		t.Fatal(err)
112	}
113	if err := (configSettingsStore{}).SetAutoCompactThreshold(70); err != nil {
114		t.Fatal(err)
115	}
116	cfg, err := LoadConfig()
117	if err != nil {
118		t.Fatal(err)
119	}
120	if cfg.AutoCompactThreshold == nil || *cfg.AutoCompactThreshold != 70 {
121		t.Fatalf("auto_compact_threshold = %v, want 70", cfg.AutoCompactThreshold)
122	}
123	if cfg.Theme != "dark" {
124		t.Fatalf("unrelated config changed: theme = %q, want dark", cfg.Theme)
125	}
126}
127```
128
129- [ ] **Step 2: Run tests and verify RED**
130
131Run:
132
133```sh
134go test ./packages/agent ./packages/agent/modes -run 'AutoCompactThreshold|SettingsDialog.*AutoCompact' -count=1
135```
136
137Expected: compilation or assertion failure because persistence and the picker row do not exist.
138
139- [ ] **Step 3: Implement persistence and live setting application**
140
141Add the settings-store method, fixed picker options, choice resolution, action routing, integer parsing, live `InteractiveConfig` update, and status message. Persist only values exposed by the picker; normalize the live value defensively before use.
142
143- [ ] **Step 4: Run focused tests and verify GREEN**
144
145Run:
146
147```sh
148go test ./packages/agent ./packages/agent/modes -run 'AutoCompactThreshold|SettingsDialog.*AutoCompact' -count=1
149```
150
151Expected: PASS.
152
153### Task 3: Documentation and full verification
154
155**Files:**
156- Modify: `README.md`
157- Review: `docs/superpowers/specs/2026-07-28-configurable-auto-compact-threshold-design.md`
158- Review: `docs/superpowers/plans/2026-07-28-configurable-auto-compact-threshold.md`
159
160**Interfaces:**
161- Documents: `auto_compact_threshold`
162- Documents: `/settings` presets and `off` semantics
163
164- [ ] **Step 1: Update user documentation**
165
166Document `off`, `70%`, `80%`, `85%` default, and `90%` in the `/settings` section. Update `/compact` to state that threshold-based auto-compaction is configurable and that payload-too-large recovery remains active when the percentage trigger is off.
167
168- [ ] **Step 2: Format changed Go files**
169
170Run:
171
172```sh
173gofmt -w packages/agent/config.go packages/agent/settings_store.go packages/agent/settings_store_test.go packages/agent/cli.go packages/agent/modes/interactive.go packages/agent/modes/auto_compact_test.go
174```
175
176- [ ] **Step 3: Run the complete test suite**
177
178Run:
179
180```sh
181go test ./...
182```
183
184Expected: PASS.
185
186- [ ] **Step 4: Run static analysis**
187
188Run:
189
190```sh
191go vet ./...
192```
193
194Expected: PASS.
195
196- [ ] **Step 5: Inspect the final change**
197
198Run:
199
200```sh
201git diff --check
202git status --short
203git diff
204```
205
206Confirm only the configuration, TUI, tests, README, design, and plan belong to the feature.
207
208### Task 4: Publish the pull request
209
210**Files:**
211- Stage only the files listed in Tasks 1-3.
212
213**Interfaces:**
214- Produces: branch `codex/configurable-auto-compact-threshold`
215- Produces: one feature commit and a ready GitHub pull request
216
217- [ ] **Step 1: Create the feature branch**
218
219```sh
220git switch -c codex/configurable-auto-compact-threshold
221```
222
223- [ ] **Step 2: Stage explicit feature paths and review**
224
225Stage only the implementation, tests, README, design, and plan. Review `git diff --cached --check` and `git diff --cached`.
226
227- [ ] **Step 3: Commit**
228
229```sh
230git commit -m "Make auto-compact threshold configurable"
231```
232
233- [ ] **Step 4: Push the branch**
234
235Push to the appropriate writable GitHub remote with upstream tracking.
236
237- [ ] **Step 5: Open a ready pull request**
238
239Target the upstream default branch. Include the behavior, compatibility, user impact, and exact validation commands in the PR body.