context-guard: reader contract (session-id discovery, inline floor)

[kyle-sexton]

Parent

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

What to build

plugins/context-guard/reference/reader-contract.md, modeled on rate-limit-guard's reader
contract: snapshot path pattern, file shape, single fixed staleness value consumers inline,
fail-open capability-detection table (null used_percentage / null current_usage → unknown),
zones.json shape + resolver invocation + shipped default bands, untrusted-field warning,
per-session (NOT machine-scope last-writer-wins) semantics, idle-session note, invariants (no
shipped Monitor config; path deliberately outside ${CLAUDE_PLUGIN_DATA} as a cross-plugin seam).

Three load-bearing sections beyond the model:

1. Session-id discovery — documents how a model-context consumer learns its own session id:
   the ${CLAUDE_SESSION_ID} substitution in skill content (skills doc, verified 2026-07-23;
   re-verify at implementation) with the documented fallback (substitution unavailable →
   conservative/unknown path).
2. Inline-floor ownership — this file OWNS the operable floor consumers inline (path pattern,
   staleness value, default zone bands) and states the byte-identity rule; the plugin-quality lane
   carries the matching drift check.
3. Zone-is-not-a-compaction-indicator rule — a compacted session's percentage resets while its
   evidence is already gone; consumers treat known-compacted sessions as evidence-degraded
   regardless of zone. Cites the verified absence of any documented auto-compact threshold (fetch
   date) and the empirical observation from the resolver slice.

Acceptance criteria

• File exists; grep -c 'staleness' plugins/context-guard/reference/reader-contract.md ≥ 1
• Staleness value and snapshot path in the doc byte-match the values in both scripts (grep)
• Zone-defaults section states the shipped numbers AND the documented-threshold absence with
  fetch date
• ${CLAUDE_SESSION_ID} mechanism + fallback documented

Blocked by

• Zone resolver slice (native edge).

[kyle-sexton]

[kyle-sexton]

Closed by PR #1241 (squash 7a868728). Evidence: staleness value (10 minutes), snapshot path pattern, and band line grep-match byte-identically across both scripts and the contract; ${CLAUDE_SESSION_ID} substitution re-verified against the skills doc 2026-07-24 with the no-guess conservative fallback documented; zone-is-not-a-compaction-indicator rule cites the doc-absence (fetch dates) + the empirical no-event observation; consumer drift check landed in lane B and re-ran green post-rebase.