ctxknobs

Documentation

Overview

Package ctxknobs is the MANUAL-OVERLAY COUNTER — R1 of the zero-knob automatic-context epic (#2199, epic #2198; spine docs/notes/CONCEPT-AUTOMATIC-CONTEXT-2026-07-01.md).

The doctrine it witnesses

"Nobody manages the context window." A user- or agent-facing instruction, habit, flag, or skill whose ONLY purpose is context management is a defect (doctrine L5). The knobs may survive as operator/debug surfaces; the DEFAULT path must never require one. This package enumerates the surviving overlays, classifies each, and ratchets the DEFECT count so a new one cannot land silently.

What it walks

• cmd/fak flag registrations and env lookups whose name touches context/cache/session budgets → classified operator-debug (an operator surface off the default path — fine per L5).
• .claude/skills/*/SKILL.md whose PURPOSE is managing the context window or memory store → classified user-required (the defect: a skill an agent or human must run to keep context healthy). The memory-compact skill is the canonical one.

Harness-prompt warnings ("don't read large files, it will overflow your context", the A1 overlay) live in the EXTERNAL agent harness, not in this repo, so they are not enumerable here; they are R6's scalp, tracked separately. This counter is honest about what it can and cannot see.

Why flags are operator-debug and skills are the defect

A static walk cannot tell whether the DEFAULT path forces a flag — that is a runtime property (R5 auto-envelope territory). So the counter takes the conservative, doctrine-faithful line: a flag/env is an operator surface (fine), and the enforced ratchet is over the clearly user-facing overlays — the skills/instructions whose reason for existing is context management.

The ratchet (architest/pythongate style)

The set of user-required knob keys at HEAD is frozen in baseline.go. The count may only go DOWN. A new user-required overlay whose key is not in the baseline is refused by TestNoNewUserRequiredKnobs (which runs under `make ci`), naming the offending file:line — until the baseline is updated in the SAME commit. Like pythongate, the gate does not ban context knobs; it bans NEW user-required ones.

Index

• Constants
• Variables
• func BaselineCount() int
• type Class
• type Inventory
  • func Scan(root string) (Inventory, error)
• type Kind
• type Knob
  • func RatchetOffenses(inv Inventory, baseline []string) []Knob
  • func (k Knob) Key() string

Constants

const ReasonNewUserRequiredKnob = "NEW_USER_REQUIRED_KNOB"

ReasonNewUserRequiredKnob is the closed-vocabulary refusal code the ratchet emits for a user-required context overlay that is not in the frozen baseline.

Variables

var BaselineUserRequired = []string{
	"skill:memory-compact",
}

BaselineUserRequired is the frozen set of user-required context-knob keys (kind:name) at the day the R1 ratchet shipped (#2199). It is committed DATA: the manual-overlay defects the tree still carries.

The count may only go DOWN. Adding a new user-required overlay reds TestNoNewUserRequiredKnobs (run by `make ci`) until this list is updated in the SAME commit — and it may only be EXTENDED with an explicit, reviewed reason, never to re-admit an overlay a cleaner default could retire. When an overlay is genuinely removed from the tree, delete its key here too (the ratchet tightening, pythongate-style).

Today the only enumerable user-required overlay is the memory-compact skill: a skill whose reason for existing is keeping the auto-memory store under the harness context cap. Retiring it (R6 / memview wiring) is the doctrine's first scalp; when that lands, this list shrinks to empty.

Functions

func BaselineCount

func BaselineCount() int

BaselineCount is the frozen user-required floor the ratchet holds.

Types

type Class

type Class string

Class is the two-valued classification of a context knob (doctrine L5).

const (
	// OperatorDebug is a knob that survives as an operator/debug surface — fine.
	OperatorDebug Class = "operator-debug"
	// UserRequired is an overlay a user or agent must engage to manage context — a defect.
	UserRequired Class = "user-required"
)

type Inventory

type Inventory struct {
	Knobs         []Knob `json:"knobs"`
	UserRequired  int    `json:"user_required"`
	OperatorDebug int    `json:"operator_debug"`
}

Inventory is a full, sorted scan of the tree's context knobs.

func Scan

func Scan(root string) (Inventory, error)

Scan walks root and returns the sorted context-knob inventory. It is deterministic: the same tree yields byte-identical output (the "run twice → identical" witness). A missing scan root (no cmd/fak or no .claude/skills) is not an error — that source simply contributes nothing.

type Kind

type Kind string

Kind is what sort of overlay a knob is.

const (
	KindFlag  Kind = "flag"  // a cmd/fak flag registration
	KindEnv   Kind = "env"   // a cmd/fak environment lookup
	KindSkill Kind = "skill" // a .claude/skills context-management skill
)

type Knob

type Knob struct {
	Kind     Kind   `json:"kind"`
	Name     string `json:"name"`
	Class    Class  `json:"class"`
	File     string `json:"file"` // repo-relative, forward slashes
	Line     int    `json:"line"`
	Evidence string `json:"evidence"`
}

Knob is one context-management overlay with file:line provenance.

func RatchetOffenses

func RatchetOffenses(inv Inventory, baseline []string) []Knob

RatchetOffenses returns the user-required knobs whose Key is NOT in the baseline set — the new manual overlays the ratchet refuses. Operator-debug knobs are never offenses (they are permitted surfaces). The result preserves the inventory's sorted order.

func (Knob) Key

func (k Knob) Key() string

Key is the stable identity the ratchet baseline is keyed on (kind:name).