context-kit

Token-economics-aware context management for stateless agent sessions: an index-first reading toolset, a session-start hook that assembles a compact brief, a meter that tracks the always-loaded surface against a committed baseline, one gate over its governed always-loaded sections, a close-stage brevity pass that reacts to the meter’s delta, and a memory-off gate pair (settings pins plus a local memory-dir scan) that keeps the harness’s ungoverned auto-memory surface disabled.

Why: a stateless session pays for context twice. The on-demand cost is opening a whole SPEC or source file when one section was needed — the index tools cut that (“index, then read the one you need”). The standing cost is the always-loaded surface (the instructions file, the session-start hook output) where every added line is a recurring per-session tax that grows silently, because no single session sees the trend — the meter, the gate, and the close-stage pass make that growth visible and actionable. See SPEC.md for the full contracts.

This file ships in the installer payload; what that payload withholds, and where this page’s SPEC.md links then resolve, is gate-sdk/SPEC.md §Consumer payload.

Install

Vendor the kit beside gate-sdk (required); the meter’s default hook approximation and the session-context hook also expect queue-kit. Then:

Register the gates — add to your gates.list:
```
check-brevity
check-surface-ratchet
check-settings-pins
check-settings-paths
check-memory-off
```
They resolve through gate-sdk’s registry path (your gates dir first, then each kit’s checks/), and the pre-commit hook runs those their # graph: manifests trigger, read at commit. --install-hooks on the gate binary GATE_SDK_NATIVE_BIN names places both hooks in a clone once, and a gate registered later is reached with no re-install. Two of them wait on a step of yours: check-settings-pins skips clean until you create settings-pins.conf naming the settings keys to hold, such as the auto-memory-disabling ones (SPEC.md §check-settings-pins); and check-surface-ratchet arms once you commit the ceilings --emit always-loaded --ceiling stamps (SPEC.md §The surface ratchet).
Wire the session-start hook — merge templates/settings-sessionstart.json into your harness settings file (CONTEXT_KIT_SETTINGS_FILE). The brief’s layout judgments are the CONTEXT_KIT_BRIEF_* knobs, set in your knob file.
Set the baseline — run --emit always-loaded --update-baseline on the gate binary GATE_SDK_NATIVE_BIN names and commit .workflow/always-loaded-baseline.txt.
Seed your env profile — the gate binary’s --emit env-probe arm writes a marker-bounded machine profile (OS, package manager, toolchain versions, absent tools) into ENV.local.md and seeds a hand-authored gotchas scaffold above the markers. The file is local-only (gitignore it); re-run on demand when the box changes. The session-context hook emits it when present.
Optional — retune: copy templates/context-config.knobs into your gates dir and override any knob (surfaces, hook-body command, brevity file/section set/ budget/pointer pattern, env-profile file). Defaults are this repo’s layout. Splice templates/close-brevity.md into your close skill.

Use

Run these arms with the gate binary GATE_SDK_NATIVE_BIN names, where init places it. In PowerShell, spell each line ./scripts/checkwright-gates <arm> at the repository root, with .exe on native Windows:

gates="${GATE_SDK_NATIVE_BIN:-./scripts/checkwright-gates}"
"$gates" --emit md-index [paths…]            # markdown heading index + first sentences
"$gates" --emit md-section <file> <heading>  # print one section by heading
"$gates" --emit pub-index [paths…]           # public API surface (per-language extractors; ships rust, ts)
"$gates" --emit always-loaded                 # standing surface vs baseline (one line)
"$gates" --emit always-loaded --update-baseline   # a close-stage act
"$gates" --emit env-probe     # re-probe the local machine profile (ENV.local.md)

Test

Run these arms the same way:

gates="${GATE_SDK_NATIVE_BIN:-./scripts/checkwright-gates}"
"$gates" --run-gate-tests context-kit/gate-tests context-kit/checks  # the gate fixture pairs
"$gates" --run-index-tests                               # the advisory tools vs golden output

License

Licensed under Apache-2.0, with the text in LICENSE beside this file in an installed copy and at the repository root in the source tree.