Skip to content

context-guard: zone resolver + zones.json contract #1234

Description

@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

Activity

  1. added
    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.
    on Jul 24, 2026
  2. added
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Jul 24, 2026
  3. added and removed
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Jul 24, 2026
  4. self-assigned this
    on Jul 24, 2026
  5. kyle-sexton commented on Jul 24, 2026

    @kyle-sexton
    MemberAuthor
    No description provided.
  6. kyle-sexton commented on Jul 24, 2026

    @kyle-sexton
    MemberAuthor

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.

Fields

No fields configured for Feature.

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions