context-guard: zone resolver + zones.json contract

[kyle-sexton]

Parent

Source: PLAN Phase A2, topic plugin-audit-port — plan locked at commit 40a64b5c on
feat/plugin-audit-port.

What to build

context-zone.sh <session_id>: reads that session's snapshot plus optional machine-scope
~/.claude/context-guard/zones.json and prints exactly one word — smart / acceptable / dumb
/ unknown. Absent, stale, or unparsable snapshot → unknown; used_percentage null or outside
0–100 → unknown (fail-open, mirroring the rate-limit-guard reader-contract posture). Shipped
default bands live in the script (zones.json absent = zero-config): approved defaults smart ≤ 50,
acceptable 50–75, dumb > 75 used_percentage. Malformed zones.json → shipped defaults + visible
stderr notice. Test-first, sandboxed HOME.

Grounding context (verified 2026-07-23): NO auto-compaction threshold percentage is documented
anywhere official (how-claude-code-works, context-window, settings autoCompactEnabled, costs
pages all say only "as you approach the limit") — the defaults are declared judgment values, owner
approved 2026-07-24. Two follow-through tasks in this slice:

1. Re-check the docs for a published threshold at implementation; the reader contract (next slice)
   cites the absence with fetch date.
2. Empirical ordering check: drive a session toward the limit, record the last used_percentage
   before auto-compact fires, and confirm the dumb band starts below it with declared margin (the
   dumb tripwire is useless if auto-compact fires first). Also determine whether
   used_percentage/remaining_percentage are pre- or post-output-buffer values, and document the
   autoCompactEnabled: false variant.

Acceptance criteria

• bash plugins/context-guard/scripts/context-zone.test.sh exits 0 (band edges, zones.json
  override, malformed zones.json fallback + stderr notice, absent/stale → unknown, absurd and
  null used_percentage / null current_usage → unknown)
• Empirical band-vs-compaction observation recorded (value + margin note) in the topic notes
  for the reader-contract slice to cite
• Script prints exactly one of the four zone words on every input tested

Blocked by

• context-guard: scaffold plugin + statusline tee with per-session snapshots #1228

[kyle-sexton]

[kyle-sexton]

Closed by PR #1241 (squash 7a868728). Evidence: context-zone.test.sh 44 assertions green (band edges, override, malformed fallback + stderr notice, stale/absent/null/absurd → unknown, forged non-ISO captured_at → unknown, embedded session-id mismatch → unknown). Empirical band-vs-compaction record: .work/plugin-audit-port/empirical-compaction-notes.md — no auto-compact event exists in machine history (largest session 308k tokens uncompacted, 1M-class window); doc recheck 2026-07-24 confirms no published threshold; ≥15-point declared margin, zones.json is the correction path.