docs(context-guard): document the verified auto-compact surfaces and zone interplay - #3042
Conversation
…zone interplay The reader contract stated that no auto-compaction threshold is documented and stopped there, which read as "the trigger is opaque". The *default* is unpublished, but the trigger is operator-tunable — and none of the surfaces that tune it appeared anywhere in the plugin. Name all three in the reader contract, each verified 2026-08-17 against two independent pools (the official settings reference and the shipped binary's schema strings, v2.1.233): - autoCompactWindow (settings.json, 100,000-1,000,000 tokens, no numeric default; written by /autocompact, one-launch --autocompact flag) - CLAUDE_CODE_AUTO_COMPACT_WINDOW (environment, highest precedence) - autoCompactEnabled / DISABLE_AUTO_COMPACT (off switch, distinct from DISABLE_COMPACT) Add the bands-below-the-trigger rule with its rationale: a firing means the boundary decision was reached too late, since auto-compact offers no steering hook. Only the diagnostic half of that stance is adopted — auto-compact stays enabled as a last-resort safety net, because unattended sessions have no human at the boundary and a degraded continuation beats a hard stall. Record the vendored Boris section 64 rot figure as a named practitioner anchor carrying its Opus 5 amendment, never as an adopted number. Give the evidence-degraded marker's trigger field consumer guidance: the values were documented, but not what to do with them. Consumers deliberately do not differentiate on trigger (evidence degradation is trigger-independent); the track-on-event condition that would revisit that stance is recorded, with the field itself as the observable. Documentation only; no behavior change. Verified against the hooks' emitted strings rather than their header comments. Closes #2995 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QbfCrj3X9FfGL7VRZYmrn4
|
Claude finished @kyle-sexton's task in 4m 55s —— View job Claude Code Review
Scope: Documentation-only change ( What I verified independentlyI fetched the live upstream docs (
Finding posted inlineOne Important finding on No other correctness or maintainability issues found — the changelog entry placement, version bump, cross-references to |
|
Claude finished @kyle-sexton's task in 33s —— View job Security review —
|
|
Last security-reviewed head: |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: da0fdc0845
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
|
Claude has reviewed this PR 3 times. The lane skips further automatic reviews after 5; deleting this comment resets the count. |
…band comparison Two review findings on #3042, both verified against live docs before acting. 1. The enumeration was incomplete. CLAUDE_AUTOCOMPACT_PCT_OVERRIDE is a live documented env var that moves the same trigger — a percentage (1-100) of the auto-compact window, lower-only, applying to subagents as well as the main conversation. Added as a fourth row; "three surfaces" corrected throughout. 2. The worked example equated quantities this very contract forbids equating. It compared a 400000-token window against the 400000 occupancy band, but occupancy is input+output and answers distance to quality loss, while the trigger is a fill threshold in the percentage shape's input-token accounting. The example now normalizes: a 400000-token window on a 1M-class model puts the trigger at 40% of the full window, inside the shipped smart band, so auto-compact fires while every zone still reads green. That is both correct and a sharper hazard than the original claim. The re-verification surfaced two further facts worth recording: - used_percentage always measures against the model's FULL context window, so once the auto-compact window is lowered the percentage no longer indicates when compaction will run. Directly load-bearing for a contract about reading that field. - Upstream is now more specific than the "when approaching context limits" phrasing the existing paragraph quotes: unconfigured sessions compact at the model's context limit, with enumerated earlier-firing exceptions. A percentage default is implied by the new env var but still unpublished as a number, so the bands stay declared judgment defaults — but the trigger is model- and environment-dependent, so no single band set is correct everywhere. Also records the env var's plain-integer-only parsing (500k reads as 500 and clamps to the 100K minimum) and that DISABLE_COMPACT is binary-strings-sourced, not confirmed on the env-vars page as of 2026-08-19. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QbfCrj3X9FfGL7VRZYmrn4
|
Claude finished @kyle-sexton's task in 5m 35s —— View job Claude Code Review
Scope: this push ( Independent verificationI fetched the live docs ( Confirmed accurate, verbatim or near-verbatim:
Two findings posted inline:
No other correctness issues found in this commit — the CHANGELOG/README updates are consistent with the contract, no other file in the plugin still says "three surfaces," and markdown structure (headings, table columns) is intact. |
…t compounds Two review findings on #3042, both verified against the model-config page. The refinement paragraph enumerated three of upstream's five documented exceptions to "compaction fires at the model's context limit" and dropped Sonnet 5's own. The docs state it compacts "at about 967K tokens by default" on its 1M window — the one published number in the set, and worth naming precisely because the paragraph exists to be more specific than the phrasing it replaces. Recorded with the reading that matters here: at ~97% of the window it sits well above the shipped dumb band, so unlike a lowered window it does not eat into the bands-below-the-trigger margin. Also rejoins "auto-compact" where it wrapped across a soft line break. GFM collapses the newline to a space, so it rendered as "auto- compact". The same defect existed pre-existing a few lines above, where "hard-stops" was split as "hard" / "-stops"; fixed both, since leaving one repaired and one broken in adjacent paragraphs would be worse than either. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QbfCrj3X9FfGL7VRZYmrn4
|
Claude finished @kyle-sexton's task in 1m 37s —— View job Claude Code Review
Scope: This push ( Independent verificationI re-fetched
Both prior findings are resolved
Consistency check
No new issues found in this commit. Nothing further to report. |
2 participants
Closes #2995
Summary
The reader contract stated that no auto-compaction threshold is documented and stopped there, which reads as "the trigger is opaque". The default is unpublished, but the trigger is operator-tunable — and none of the surfaces that tune it appeared anywhere in the plugin. Consumers tuning zone bands therefore had no guidance on how the bands relate to the auto-compact trigger, and the PostCompact marker's
triggerfield had documented values but no consumer guidance.Documentation only; no behavior change. context-guard 0.7.15 → 0.7.16.
Fix
reference/reader-contract.md— the four auto-compact config surfaces. Verified 2026-08-17 against two independent pools (the official settings reference and the shipped binary's schema strings, v2.1.233), and re-verified 2026-08-19 against the live settings, env-vars, and model-config pages:autoCompactWindowsettings.json100000–1000000; no numeric default (model-tuned when unset). Written by/autocompact;--autocompactsets it for one launch and, unlike the command, isn't preempted by a higher-priority settings scope.CLAUDE_CODE_AUTO_COMPACT_WINDOW500kreads as500and clamps to the 100K minimum.CLAUDE_AUTOCOMPACT_PCT_OVERRIDEautoCompactEnabled/DISABLE_AUTO_COMPACTsettings.json(defaulttrue) / environmentDISABLE_COMPACTis recorded as binary-strings-sourced and unconfirmed by docs as of 2026-08-19.)The bands-below-the-trigger rule, with rationale. Whatever the trigger resolves to,
dumbshould be reached first: auto-compact offers no steering hook, so a firing means the boundary decision was reached too late.Comparisons are normalized into the percentage shape, never occupancy. The contract already forbids equating its two zone shapes; the new guidance honors that explicitly. A configured window is a fill threshold in the percentage shape's input-token accounting, not the token shape's occupancy. Worked example: a 400,000-token window on a 1M-class model puts the trigger at 40% of the full window — inside the shipped
smartband (≤ 50), so auto-compact fires while every zone still reads green. Recorded with the docs' own consequence:used_percentagealways measures against the model's full context window, so a lowered window stops being visible in the percentage at all.Only the diagnostic half of the house stance is adopted. The prescription that usually travels with it (disable auto-compact) is explicitly rejected: unattended cloud and autonomous sessions have no human at the boundary, and a degraded continuation beats a hard stall at the window. Auto-compact stays enabled as the last-resort safety net beneath the instrumented ladder.
The Boris §64 rot figure (300–400k;
CLAUDE_CODE_AUTO_COMPACT_WINDOW=400000) is recorded as a named practitioner anchor, never an adopted number — carrying its own amendment, that the calibration is Opus 4.7-era and the Opus 5 prompting guide (verified 2026-08-08) removes its degradation premise. Consistent with claim-ladder bucket ii.The marker's
triggerfield now has consumer guidance. Consumers deliberately do not differentiate on it — evidence degradation is trigger-independent, holding identically for a steered/compactand an auto-compact. The field is captured anyway so the stance is falsifiable: it is the observable for the track-on-event condition recorded indocs/upstream/aihero-course.mdlane 3.A dated refinement to the adjacent "no documented threshold" paragraph. Upstream is now more specific than the "when approaching context limits" phrasing that paragraph quotes: an unconfigured session compacts at the model's context limit, with five enumerated earlier-firing exceptions — including Sonnet 5 at "about 967K tokens by default". The conclusion is unchanged (no percentage default is published, so the bands stay declared judgment defaults), but the trigger is now documented as model- and environment-dependent, which is why no single band set is correct everywhere.
README.mdgains a pointer naming the four surfaces, the below-the-trigger rule, and the full-window percentage caveat, deferring to the contract as SSOT.Verification
Every claim about shipped behavior was checked against the hooks' emitted strings, not their header comments:
hooks/post-compact-mark.shregex-capturesmanual|auto, defaultsunknown, and writes the marker unconditionally (no boundary-timed carve-out), matching what the contract now states. Every upstream claim was checked against a live fetch of the primary page, not from memory.Full local gate, re-run after each of the three commits:
scripts/validate-plugins.sh— all manifests + catalog passgenerate-catalog.mjs --check/generate-cheatsheet.mjs --check— both in synccheck-changelog-parity.shall four modes —--check,--check-order,--check-bump origin/main,--check-preserved origin/main(40 headings compared, all preserved — the entry was inserted above## [0.7.15], not over it)check-changed-skills.sh origin/main— no skills touchedmarkdownlint-cli2on every touched file — 0 issuestyposonplugins/context-guard/— cleanzones-inline-drift.test.sh11/0,context-zone.test.sh73/0,statusline-tee.test.sh47/0,statusline-shim.test.sh36/0 — 167 passed, 0 failed. The drift suite matters here specifically: the reader contract's operable-floor values are inlined by consumers, and none of them were altered.Review rounds
Four findings raised across three review passes, all verified against primary sources before acting, all fixed and resolved:
a4168554.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE. Confirmed against a live fetch and added ina4168554.7c88cee5.auto-compactsplit across a soft line break rendered as "auto- compact". Fixed in7c88cee5, along with a pre-existing instance of the same defect (hard/-stops) a few lines above.Related
🤖 Generated with Claude Code
https://claude.ai/code/session_01QbfCrj3X9FfGL7VRZYmrn4