feat(context-budget): ship the startup-payload measurement plugin (0.6.0)

.claude-plugin/marketplace.json

@@ -311,6 +311,12 @@
       "category": "claude-code",
       "tags": ["context-window", "statusline", "tee", "zones", "context-degradation", "session", "skill"]
     },
+    {
+      "name": "context-budget",
+      "source": "./plugins/context-budget",
+      "category": "claude-code",
+      "tags": ["context-window", "startup-payload", "token-budget", "tool-schemas", "measurement", "attribution", "ledger", "skill"]
+    },
     {
       "name": "plugin-quality",
       "source": "./plugins/plugin-quality",

docs/CATALOG.md

@@ -82,6 +82,7 @@ plugin manifests and kept in sync by CI — never hand-edit it; the category voc
 - [`claude-ops`](../plugins/claude-ops) — Claude Code operations toolkit. Ten skills: inventory (read-only enumeration of the complete invocable surface — every built-in CLI command with aliases and hidden/gated status, every bundled skill, and every component of every installed plugin across all marketplaces; reads the shipped binary because upstream publishes no built-in command list, and carries an integrity verdict so a drifted build reports counts as floors rather than silently short totals), audit-install-state (read-only audit of the machine-scope ~/.claude installation directory and ~/.claude.json — full inventory split into an authored surface and rolled-up bulk trees, product-managed retention vs genuinely unmanaged state, filename-scheme resolution before any process-liveness check, and deliberate/mid-experiment detection; reports, never deletes), audit-performance (read-only slowness-diagnostic capture run at the moment the machine or a session feels slow — CLI version, retention-sweep health including the silent unparsable-settings pause, a timed census walk of the install tree as a sweep-cost proxy, active-session and plugin-fleet counts, a process census, and a bundled known-performance-issues reference; separates the three documented suspects — accumulated state, version regression, component bloat — and routes remediation out; reports, never mutates), observability (read locally captured telemetry — OTEL store, collector, hook-event JSONL, ccusage — with trend reports and store pruning), known-issues (search known Claude product GitHub bugs, check service health, maintain a persistent tracked-issue registry), changelog (ingest Claude Code changelog entries and integrate them into the current repo), plugins (bring a machine's plugin fleet current on demand — marketplace refresh, effective-scope updates including in-repo project/local installs, new-plugin install per policy, scope-divergence detection and explicit convergence), morning-brief (read-only gh-based operator morning view — queue-label counts, merge-ready PRs, parked decisions with their RECOMMENDED lines, and loop-lane telemetry freshness), lanes (start/restart/stop/status loop lanes as named background Claude Code sessions seeded from canonical prompt files, with per-lane model/effort, a repo-pull + marketplace-refresh launch step, and a consume-restarts action — an OS-schedulable reader that relaunches stopped lanes whose telemetry carries a restart_request), and a re-runnable setup action that settles where the known-issues registry lives. Plus a family of eight advisory *-audit hooks (API errors, config changes, instruction loads, permission denials, pre-compaction, skill usage, tool failures, and unsurfaced hook failures — the last also warns the user via systemMessage, since a hook that fails to launch enforces nothing and Claude Code surfaces the failure to nobody) that emit the shared hook-telemetry envelope, and a reference sink that maps envelopes into the hook-events.jsonl the observability skill reads.
 - [`rate-limit-guard`](../plugins/rate-limit-guard) — Shared rate-limit guard for loop lanes: a statusline wrapper tees the subscription rate-limit windows to a fixed machine-scope file, a StopFailure hook records rate-limit stops reactively, and a reader contract fixes how consuming sessions pause and resume.
 - [`context-guard`](../plugins/context-guard) — Per-session context-window observability plus the first shipped consumer: a statusline wrapper tees each session's context_window fields to a per-session snapshot file, a zone resolver classifies usage into smart/acceptable/dumb bands (percentage bands plus window-class token bands, conservative-min combination, zones.json SSOT with shipped defaults), a reader contract fixes how consuming sessions interpret the snapshots, and zone-crossing hooks report once per transition into a worse zone across two channels — the continuation menu to the operator, who owns that choice, and to the model only the zone determination plus the counter-steer that a zone word is not a decay signal (advisory by default; an optional blocking mode gates new mutating work on a fresh dumb-zone snapshot with handoff-writing exempt), with a PostCompact hook persisting an evidence-degraded marker.
+- [`context-budget`](../plugins/context-budget) — Measure a Claude Code session's fixed startup context payload per item, on the consumer's machine at a pinned, version-stamped binary — including per-tool attribution of the built-in tool pools that /context reports only as lump sums, derived live by A/B bare-name-deny differencing with enforced comparability rules (skill-listing signature, one mode, one binary), an SDK-primary exact meter degrading to a version-aware headless /context parser and then to an honest structured error (never a wrong number), and a per-project measure-toggle-remeasure ledger under the plugin data directory recording every lever's real before/after delta. Report-only: prints exact config, applies nothing.
 - [`plugin-quality`](../plugins/plugin-quality) — Post-use behavioral audit of Claude Code plugin components: a six-step audit workflow (evidence capture, grounded mapping in a fresh subagent, blindspot pass, interactive contract lock, presence-gated review seams, work-item emit with draft+confirm) over any skill, agent, hook, command, or config you have actually used — zone-informed by context-guard snapshots when present, conservative when not.
 - [`skill-quality`](../plugins/skill-quality) — Skill-authoring QA tooling: a static contract checker that runs twenty-two deterministic checks over a Claude Code skill (frontmatter, per-skill listing-entry cap, trigger-keyword preservation, line caps, broken internal refs, markdownlint, gotchas surface, evals presence, precompute opportunity, injection shell-declaration, fresh-eyes declaration conformance), a shared skill-listing budget reporter across a set of skills, and a bundled evals.json schema plus a deterministic eval-quality lint (duplicate case identities, missing fixtures, empty or vague grading criteria, set-coverage warnings). Runs against any repo's skills directory via the convention-resolution ladder — no baked layout.
 - [`computer-use`](../plugins/computer-use) — Operating knowledge for Claude Code's built-in computer-use MCP server — the desktop screen-control surface. `/computer-use:diagnose` resolves a symptom to a cause instead of retrying: why every screenshot is downscaled to a fixed pixel budget and why zoom (not a bigger display) is the way back to detail, how to read a capture or input failure, and the per-OS quirks that make a synthesized key or menu behave unlike a human's. `/computer-use:setup` verifies the prerequisites the surface cannot verify for itself and reports the environment settings that end a session mid-run.

docs/SKILL-CHEAT-SHEET.md

@@ -158,6 +158,7 @@ owned by [docs/CATALOG-TAXONOMY.md](CATALOG-TAXONOMY.md).
 | [`/code-tidying:tidy`](../plugins/code-tidying/skills/tidy/SKILL.md) | `code-tidying` | Proactively hunt one lane for safe structural tidyings and ship a structure-only PR |
 | [`/codebase-health:audit`](../plugins/codebase-health/skills/audit/SKILL.md) | `codebase-health` | Audit for drift between docs, config, code, and architecture via verified findings |
 | [`/computer-use:diagnose`](../plugins/computer-use/skills/diagnose/SKILL.md) | `computer-use` | Resolve computer-use capture, input, and screenshot symptoms to a cause |
+| [`/context-budget:audit`](../plugins/context-budget/skills/audit/SKILL.md) | `context-budget` | Measure the startup context payload per item and ledger every lever's real delta |
 | [`/coupling:reduce`](../plugins/coupling/skills/reduce/SKILL.md) | `coupling` | Scan for change-transmitting coupling, apply safe reductions in a budgeted batch, route the rest |
 | [`/discipline:do-your-research`](../plugins/discipline/skills/do-your-research/SKILL.md) | `discipline` | Re-anchor research discipline, then audit and correct the current work |
 | [`/discipline:do-your-research-deep`](../plugins/discipline/skills/do-your-research-deep/SKILL.md) | `discipline` | Verify every session claim against primary sources in a heavy fan-out |

docs/conventions/permission-rule-hygiene/CHANGELOG.md

@@ -4,6 +4,18 @@ Notable changes to the permission-rule-hygiene convention. The convention states
 anti-patterns; it is enforced by the `claude-config` plugin's `permission-hygiene` skill (checks
 P1/P2/P3), whose detector and criteria version independently of this document.
 
+## 1.3 — 2026-08-17
+
+- **Refreshed the auto-mode-default citation to the page's current wording.** The block-quoted
+  "Starting August 14, 2026" passage is no longer present at the cited URL; the page now states a
+  version floor (v2.1.228 on macOS/Linux/WSL, v2.1.233 on native Windows) plus the surviving
+  one-time switch-prompt behavior, both quoted verbatim (fetched 2026-08-17). Substance of the
+  convention unchanged. Known gap, recorded for a future revision: the convention reasons only
+  about *loosening* (allow rules surviving auto mode) and says nothing about *tightening* —
+  deny-rule durability across modes — which the `context-budget` design now depends on
+  (shipped as `plugins/context-budget/`; its topic slice pruned per topic-docs, evidence
+  retrievable via PR #2932's pre-prune SHA).
+
 ## 1.2 — 2026-07-26
 
 - **Corrected the known gap: plugin `bin/` delivery is unreliable, not absent.** 1.1 read the gap as

docs/conventions/permission-rule-hygiene/README.md

@@ -25,16 +25,21 @@ When a grant is dropped the failure is silent: it parses, looks correct, and doe
 the session enters auto mode, so the action falls through to the classifier and can be denied even when
 the operator intended to pre-approve it. A convention plus an enforceable check is the durable fix.
 
-## Auto mode is the default from 2026-08-14, not a state you opt into
+## Auto mode is the built-in default, not a state you opt into
 
 Read every "under auto mode" clause below as the **default** condition on the plans this repository's
-operators use, not as a conditional one. Per
+operators use, not as a conditional one. The upstream page no longer dates the rollout — it states a
+version floor. Per
 [permission-modes](https://code.claude.com/docs/en/permission-modes#eliminate-prompts-with-auto-mode)
-(fetched 2026-08-10):
+(fetched 2026-08-17):
 
-> Starting August 14, 2026, auto mode becomes the default permission mode for new sessions on Pro,
-> Max, and Team plans. You can switch modes at any time. A default you set yourself stays in place
-> unless you accept the one-time switch prompt, and a default your organization manages is unchanged.
+> The built-in `auto` default requires Claude Code v2.1.228 or later on macOS, Linux, and WSL, and
+> v2.1.233 or later on native Windows. On earlier versions, the built-in default is Manual.
+
+> On Pro, Max, and Team plans, if your `~/.claude/settings.json` sets a different `defaultMode` and
+> no other settings file sets one, your terminal sessions keep starting in that mode, and Claude
+> Code asks once, in the terminal or in the extension, whether to change the setting to auto mode.
+> If you decline, your setting stays as it is.
 
 Two consequences for this convention, and one non-consequence:
 

docs/topics/context-engineering-claude-5/design/checks-and-sweep.md

@@ -288,7 +288,7 @@ trigger:
 | `/context` | **Adopt as ground truth for what actually loaded**, and treat any filesystem-derived inventory as a candidate set rather than an answer. Startup scope depends on the launch directory: starting from a subdirectory loads that directory's `CLAUDE.md` plus every ancestor's, so a walk that ignores launch directory is wrong by construction |
 | `claudeMdExcludes` | **Adopt as a remediation option**, with its documented floor stated: managed policy files cannot be excluded, and the setting is static rather than per-task |
 | `/doctor` | **Defer to it** for the trim-and-migrate half; see the prerequisite contract below |
-| `debug-your-config`'s wider surface | **Adopt as the native-first inventory list** — `/context`, `/memory`, `/skills`, `/hooks`, `/mcp`, `/permissions`, `/doctor`, `/status`, plus `claude --safe-mode` and `CLAUDE_CONFIG_DIR` for clean-room comparison. The gate is this list, not `/doctor` alone |
+| `debug-your-config`'s wider surface | **Adopt as the native-first inventory list** — `/context`, `/memory`, `/skills`, `/hooks`, `/mcp`, `/permissions`, `/doctor`, `/status`. The gate is this list, not `/doctor` alone. **Corrected 2026-08-17: this row also adopted `claude --safe-mode` and `CLAUDE_CONFIG_DIR` "for clean-room comparison" — measured false at v2.1.232.** Safe mode leaves all bundled skills loaded (42 measured) while zeroing user/plugin skills, and a clean `CLAUDE_CONFIG_DIR` does not unload bundled skills either; safe mode also shifts the `Skills`/`System tools` split via the skill-frontmatter subtraction, so its numbers are not comparable to a normal session's. Neither is a clean room; both remain useful only as *contrast* runs whose regime change is named. Evidence: the `context-budget` evidence record (slice pruned per topic-docs; PR #2932 pre-prune SHA) |
 
 **Output styles are the inventory's hardest case and the reason a filesystem walk alone fails.** They
 modify the system prompt directly, default to *removing* Claude Code's built-in software-engineering

docs/topics/context-engineering-claude-5/design/coverage-matrix.md

@@ -27,7 +27,7 @@ covers it, and states what is left over. Verdict values: `COVERED` (an incumbent
 | S4 | Memory, artifacts, and skills are now destinations that `CLAUDE.md` content should move to | `/doctor` (migrates to skills + nested `CLAUDE.md`); `audit-instructions` I3 (move to skill or path-scoped rule); `claude-memory` (auto-memory) | `PARTIAL` — artifacts are named as a destination by neither |
 | S5 | Absolute rules give way to context-sensitive judgement | `audit-instructions` I6 (bare prohibition → positive reframing), I8 (model-era re-audit of over-prescriptive scaffolding) | `PARTIAL` — I6 and I8 cover the de-prescription itself, but neither carries any a-priori bound on how far it goes, so the stopping condition (S13's carve-out) is a real remainder rather than a covered concern |
 | S6 | Examples constrain; design expressive interfaces instead | `audit-instructions` I9 covers the *negative* half (approach-pinning example blocks) | `PARTIAL` — the *positive* half is unowned: nothing audits whether a skill's `argument-hint`, arguments, enumerations, and frontmatter are expressive enough that prose examples become unnecessary |
-| S7 | Progressive disclosure — file trees, on-demand loading, deferred tools | `/doctor` (migrate always-loaded guidance); `audit-instructions` I3; `skill-quality:check` (line caps) | `PARTIAL` — splitting one long `SKILL.md` into a chapter tree is implied by line caps but never prescribed as a remediation; deferred tool loading is unowned |
+| S7 | Progressive disclosure — file trees, on-demand loading, deferred tools | `/doctor` (migrate always-loaded guidance); `audit-instructions` I3; `skill-quality:check` (line caps) | `PARTIAL` — splitting one long `SKILL.md` into a chapter tree is implied by line caps but never prescribed as a remediation. **Updated 2026-08-17: the "deferred tool loading is unowned" half is now owned by the shipped `context-budget` plugin (`plugins/context-budget/`, PR #2932), with the premise corrected en route — deferral does not shrink the request payload, so the ownable concern is measuring and pruning tool schemas, not deferring them** |
 | S8 | Do not repeat an instruction across surfaces; it belongs at the definition of the thing it governs | `docs-hygiene:extract-ssot` (dedupe to one SSOT) | `PARTIAL` — dedupe picks *a* home; nothing encodes *which* home is correct (the placement rule) |
 | S9 | Auto-memory replaces `#`-hotkey writes into `CLAUDE.md` | `claude-memory:audit` / `stateless`; `/memory` | `COVERED` |
 | S10 | Rich references — HTML artifacts, code-as-spec, test-suite-as-spec, port targets, rubrics driving verifier agents | none | **`GAP`** — wholly unowned |

plugins/claude-config/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "claude-config",
-  "version": "0.38.6",
+  "version": "0.38.7",
   "description": "Nine configuration-health skills (plus setup) for a repo's Claude Code configuration: audit (settings.json / .mcp.json / hooks / plugins / permissions drift), audit-automation-gaps (evidence-gated verdicts on automation gaps), audit-permission-grants (allow-rule / allowed-tools grants for auto-mode durability and portability), audit-permission-state (the permission rules actually in effect — every settings scope merged with per-rule provenance, what auto mode drops on entry, config written where nothing reads it, and which managed intents are enforced versus loosenable), draft-auto-mode-rules (interview and draft a paste-ready autoMode classifier block; prints only, never writes), audit-instructions (locally-owned instruction surfaces vs current model capability — proposes removals/rewrites of instructions the model no longer needs, and detects cross-surface instruction conflicts), audit-prompting-postures (the additive lane — posture guidance the prompting guide says a component's purpose needs but the component does not carry), audit-pass (one coordinated, ordered, resumable pass over a named target — three-scope inventory, run-time-derived exclusion set, stable finding identity, suppression memory, resume, one human gate — delegating every check to the plugin that owns it), and unhobble (the empirical bare-baseline experiment: reversibly strip a repo's standing instructions, log real stumbles against the current model, re-add only what evidence earns).",
   "author": {
     "name": "Melodic Software",

plugins/claude-config/CHANGELOG.md

@@ -3,6 +3,21 @@
 All notable changes to the `claude-config` plugin are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.
 
+## [0.38.7]
+
+### Fixed
+
+- **unhobble: the `CLAUDE_CODE_SIMPLE` gotcha was wrong twice; rewritten against the binary.** It
+  called the variable "undocumented and may vanish" — it has its own row in the official env-vars
+  reference plus the CLI equivalent `--bare` — and it attributed prompt-stripping to it, which
+  belongs to the distinct sibling `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` (both registered independently
+  in the v2.1.232 env map; simple mode disables fetches, keychain reads, and `CLAUDE.md`
+  auto-discovery). The out-of-contract boundary is unchanged and now rests on its real basis:
+  both switches ablate product-owned surfaces, not operator-owned instructions. Eval 8 updated to
+  grade the scope-boundary reasoning instead of the retired undocumented-status claim.
+  Evidence: the `context-budget` evidence record (topic slice pruned per topic-docs;
+  retrievable via PR #2932's pre-prune SHA).
+
 ## [0.38.6]
 
 ### Changed