Skip to content

refactor(claude): global context diet — 148.6 KB → 99.0 KB always-loaded, budget test, hook noise fixes#300

Merged
laurigates merged 5 commits into
mainfrom
refactor/scope-repo-specific-rules
Jul 4, 2026
Merged

refactor(claude): global context diet — 148.6 KB → 99.0 KB always-loaded, budget test, hook noise fixes#300
laurigates merged 5 commits into
mainfrom
refactor/scope-repo-specific-rules

Conversation

@laurigates

@laurigates laurigates commented Jul 4, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

What

A context diet for the user-global Claude configuration, in three waves on this branch, ending at 99.0 KB always-loaded (from ~153 KB including an unmanaged orphan), pinned by a regression test at a 110 KB ceiling.

Wave 1 — repo-specific rules out of the global tree

  • Move 7 repo-specific rules from exact_dot_claude/rules/ (loads everywhere) to repo-root .claude/rules/ (loads only here): chezmoi-conventions.md (17 KB), testing.md, shell-completions.md, development.md, document-management.md, zshrc-keybindings.md, fzf-picker-colorize-align.md.
  • Split dependency-management.md: Homebrew-profile + MCP-registry sections → new repo rule package-registries.md.
  • paths: frontmatter on zsh-pattern-expansion-extended-glob, docker-build-context, rustfmt-gate-onboarding.
  • .chezmoiignore: register policy-limits.json / remote-settings.json (Claude Code runtime files the exact_ tree would delete).

Wave 2 — regression test (tests/test-claude-context-budget.sh)

Four checks: total always-loaded budget, 10 KB per-file cap, repo-specific-marker scan with conscious allowlist, paths: frontmatter validity. Wired as a pre-commit local hook (runs in CI via pre-commit run --all-files) and mise run test:context-budget. Red-path verified with canary fixtures — and it caught a real violation mid-branch (unallowlisted marker in the new git-hazards.md).

Wave 3 — consolidation of the remaining global rules (meta-context-diet audit)

  • Captured an unmanaged orphan: verify-machine-facts-before-publishing.md lived only in ~/.claude/rules/, loading every turn while invisible to source and test.
  • Merged the six git merge-hazard rules (21.3 KB) into one distilled git-hazards.md (4.7 KB) — per-hazard invariant + check + fix.
  • Merged the taskwarrior pair (tracking + cross-session, near-duplicates) into one rule.
  • Path-scoped claude-code-auto-mode.md (8.4 KB) and claude-plugins-freshness.md (4.0 KB) to settings-file globs.
  • Distilled to invariants + skill pointers: diagrams (→ d2-diagrams skill), disk-full-recovery (→ macos-disk-usage), telegram, kitty, mise-stale-copies, orbstack, development-process. Dropped private_reporters.md (testing-plugin skills own it) and the CLAUDE.md-duplicate install-priority list.
  • Budget ratcheted 160 KB → 110 KB against the new 98,956-byte baseline.

Hook noise fixes

  • chezmoi-drift-guard: substring *chezmoi*apply* matching fired on commit messages / PR bodies that merely mentioned "chezmoi apply" — anchored to real invocations, and the heads-up now names the drifted files. Matcher unit-checked on 6 cases.
  • chezmoi-workflow-nudge: repeated the identical reminder per Edit (9× in one session) — added a 30-min stamp-file debounce.

Session distill

Why

Everything under ~/.claude/rules/ without paths: frontmatter is paid for on every turn in every project. Roughly a third of it was repo-specific mechanics, near-duplicate pairs, or narrative around one-paragraph invariants whose playbooks already live in plugin skills. The test makes the ceiling deterministic instead of relying on session discipline.

Verification

  • ./tests/test-claude-context-budget.sh → PASS=4 at the 110 KB ceiling; canary red-path verified.
  • chezmoi status ~/.claude clean after apply; orphaned targets of deleted rules removed manually (rules/ is non-exact_).
  • Hook fixes exercised with synthetic payloads: message-mention → silent, real apply → fires with filenames; second nudge in a burst → silent.
  • Cross-references to renamed/removed rules updated (bulk-syntax-sweep, taskwarrior-bulk-operations, session-plugin.local.md, guard-hook comments); shellcheck clean.

Follow-up (not in this PR)

Tier-2 skill promotions are cross-repo work in laurigates/claude-plugins — another ~27 KB once promoted, tracked as one issue each:

🤖 Generated with Claude Code

https://claude.ai/code/session_01RVnFBnQFMWKgd8h4kTCjZy

laurigates and others added 2 commits July 4, 2026 17:24
@laurigates @claude
chore(claude): ignore policy-limits.json and remote-settings.json
9cc25f3 
Claude Code creates these runtime files at the top level of ~/.claude.
Unlisted top-level entries in the exact_ tree are deleted on chezmoi
apply, so register them before they get silently removed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RVnFBnQFMWKgd8h4kTCjZy
@laurigates @claude
refactor(claude): scope repo-specific rules to project .claude/rules
cef70e4 
Seven rules in exact_dot_claude/rules/ (~28 KB) were loaded globally in
every session but only apply when working in this repo. Move them to
the project-scoped .claude/rules/ so other projects stop paying the
context cost:

- chezmoi-conventions.md (17 KB — global sessions keep the CLAUDE.md
  one-liner and the chezmoi-expert skill)
- testing.md, shell-completions.md, development.md,
  document-management.md, zshrc-keybindings.md,
  fzf-picker-colorize-align.md

Split dependency-management.md: the Homebrew profile and MCP server
registry sections (backed by .chezmoidata) move to the new repo rule
package-registries.md; the cross-project mise guidance stays global.

Add paths: frontmatter to three global rules that only matter for
specific file types (zsh-pattern-expansion-extended-glob,
docker-build-context, rustfmt-gate-onboarding) so they lazy-load.

Update the chezmoi guard hooks and tui-keybinding rule to point at the
new chezmoi-conventions.md location.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RVnFBnQFMWKgd8h4kTCjZy
@github-actions github-actions Bot added documentation Improvements or additions to documentation claude size/s labels Jul 4, 2026
@laurigates @claude
test(claude): add regression test for global context budget
561f54e 
Pin the always-loaded global Claude context so repo-specific or bloated
rules can't silently re-accumulate in exact_dot_claude/ after the
PR #300 cleanup. Four checks:

- Total budget: unconditional rules + CLAUDE.md <= 160 KB (baseline
  148.6 KB at introduction; ratchet down as cleanups land)
- Per-file cap: no unconditional rule over 10 KB (chezmoi-conventions
  hit 17 KB before it was migrated out)
- Repo-specific markers: .chezmoidata / dot_zshrc / mise run lint /
  etc. in a global rule fail unless consciously allowlisted
- Frontmatter validity: path-scoped rules must declare a non-empty
  paths: list with a closed frontmatter block

Wired as a pre-commit local hook (runs in CI via pre-commit
run --all-files in smoke.yml) and as mise task test:context-budget,
added to the test task's depends. Red-path verified with canary
fixtures: all four checks fail on injected violations.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RVnFBnQFMWKgd8h4kTCjZy
@github-actions github-actions Bot added the security Security-related fix or improvement label Jul 4, 2026
@github-actions

github-actions Bot commented Jul 4, 2026

Copy link
Copy Markdown
Contributor

⚠️ Broken Links Detected

Summary

Status Count
🔍 Total 163
✅ Successful 153
⏳ Timeouts 0
🔀 Redirected 0
👻 Excluded 9
❓ Unknown 0
🚫 Errors 1

Errors per input

Errors in docs/adrs/0013-nixos-declarative-system-configuration.md

Please fix the broken links before merging.

@github-actions github-actions Bot added size/m and removed size/s labels Jul 4, 2026
@laurigates @claude
refactor(claude): consolidate global rules — 148.6 KB → 99.0 KB alway…
09117b4 
…s-loaded

Second wave of the context diet (audit via meta-context-diet):

- Capture ~/.claude/rules/verify-machine-facts-before-publishing.md into
  source — it was written directly to the target, loading every turn while
  invisible to the source tree and the budget test.
- Merge the six git merge-hazard rules (branch-merge-detection,
  branch-from-pushed-main, stacked-pr-merge-order, squash-merge-orphans,
  textual-merge-duplicates, git-add-atomic-pathspec; 21.3 KB) into one
  distilled git-hazards.md (4.7 KB): per-hazard invariant + check + fix;
  narratives live in git history.
- Merge taskwarrior-tracking + taskwarrior-cross-session (near-duplicates)
  into one taskwarrior-tracking.md.
- Path-scope claude-code-auto-mode.md and claude-plugins-freshness.md to
  settings-file globs (12.4 KB off the unconditional surface).
- Distill to their invariants, pointing at the plugin skills that own the
  full playbooks: diagrams (d2-diagrams skill), disk-full-recovery
  (macos-disk-usage), telegram-communication (telegram skill),
  kitty-agent-interaction, mise-stale-tool-copies, orbstack-gui-quit
  (macos-plugin skills), development-process (blueprint/testing plugins).
- Drop private_reporters.md (testing-plugin skills encode reporter flags)
  and dependency-management's install-priority list (verbatim duplicate of
  CLAUDE.md — now a pointer).
- Ratchet the budget test: 160 KB → 110 KB against the new 98,956-byte
  baseline; swap the marker allowlist entry to git-hazards.md.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RVnFBnQFMWKgd8h4kTCjZy
@laurigates laurigates changed the title refactor(claude): scope repo-specific rules to project .claude/rules refactor(claude): global context diet — 148.6 KB → 99.0 KB always-loaded, budget test, hook noise fixes Jul 4, 2026
@laurigates @claude
fix(claude): reduce hook context noise — drift-guard matcher, nudge d…
8911103 
…ebounce

Two per-turn noise sources found while auditing hooks:

- chezmoi-drift-guard matched `*chezmoi*apply*` as a substring over the
  whole command, so git commits and gh pr edits whose message text merely
  mentioned "chezmoi apply" triggered the heads-up on nearly every call.
  Anchor the match to an actual chezmoi invocation (line start or after
  ;|&|`|$() and name the drifted files in the message so it's actionable
  (verified: commit-message and PR-body mentions no longer fire; real
  apply invocations, bare or chained, still do).
- chezmoi-workflow-nudge repeated the identical reminder on every
  Edit/Write under exact_dot_claude/ (nine copies in one session). Add a
  per-class stamp-file debounce (default 30 min, CHEZMOI_NUDGE_DEBOUNCE_SECS
  to override).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RVnFBnQFMWKgd8h4kTCjZy
@github-actions github-actions Bot added size/xl and removed size/m labels Jul 4, 2026
@laurigates laurigates merged commit 8cf3eef into main Jul 4, 2026
8 checks passed
@laurigates laurigates deleted the refactor/scope-repo-specific-rules branch July 4, 2026 18:34
This was referenced Jul 4, 2026
Closed
Closed
Closed
Closed
Merged
Open
laurigates added a commit that referenced this pull request Jul 5, 2026
@laurigates @claude
docs(claude): non-exact rules/ neither purges orphans nor flags them (#…
dac2379 
…301)

## What

Session distill from the #300 context diet: document in
`.claude/rules/chezmoi-conventions.md` that **non-`exact_` subdirs
neither purge orphaned targets nor flag them** — the flip side of the
existing per-directory-level note.

- Moving/deleting a source file out of `exact_dot_claude/rules/` leaves
the old target orphaned in `~/.claude/rules/`, still loading into every
session, with **no `D` line in `chezmoi status`** to reveal it. Manual
target cleanup + `chezmoi source-path` verification documented.
- The inverse leak too: a rule created directly in the target is never
captured to source and silently loads forever — includes the
unmanaged-file sweep one-liner.

Both directions bit during the #300 diet (7 orphaned targets after the
wave-1 moves; one 4.7 KB unmanaged rule found loading invisibly).

## Why not in #300

The commit was authored on the #300 branch during session wrap-up, but
the PR had already been squash-merged — pushing would have orphaned it
(hazard #2 in the freshly consolidated `git-hazards.md`, fittingly).
Cherry-picked onto a fresh branch from `origin/main`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01RVnFBnQFMWKgd8h4kTCjZy

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
@laurigates laurigates mentioned this pull request Jul 5, 2026
Merged
laurigates added a commit that referenced this pull request Jul 5, 2026
@laurigates @claude
refactor(claude): reduce four skill-promoted rules to pointer stubs (#…
2373af3 
…302)

## Summary

Continues the global context diet (#300). The full content of four
always-loaded rules has been promoted into claude-plugins skills that
load on intent; each rule shrinks to a pointer stub naming its skill.

| Rule (stubbed) | Skill | Tracking |
|---|---|---|
| `taskwarrior-bulk-operations.md` | `taskwarrior-plugin:task-bulk-ops`
| laurigates/claude-plugins#1964 / laurigates/claude-plugins#1981 |
| `tui-keybinding-terminal-interception.md` |
`macos-plugin:tui-keybinding-debug` | laurigates/claude-plugins#1965 /
laurigates/claude-plugins#1984 |
| `huggingface-downloads.md` | `tools-plugin:hf-downloads` |
laurigates/claude-plugins#1966 / laurigates/claude-plugins#1982 |
| `bulk-syntax-sweep-classify-matches.md` |
`code-quality-plugin:bulk-sweep-classify` |
laurigates/claude-plugins#1967 / laurigates/claude-plugins#1986 |

Cross-references updated in the same pass: `disk-full-recovery.md` now
points at the `hf-downloads` skill, `taskwarrior-tracking.md` at
`task-bulk-ops`.

**Impact**: always-loaded global context drops 98,956 → 73,332 bytes
(`test-claude-context-budget.sh` green, −542 lines).

## Draft gate

Kept as a **draft** until the four claude-plugins skill PRs (#1981,
#1982, #1984, #1986) merge **and** the plugins release, so the stubs
never point at skills that don't exist yet
(verify-the-replacement-is-operational discipline). Mark ready + merge
once `/plugin` shows the four skills installed.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_017Eoq2JHmHAEe5VLmV3Kant

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

claude documentation Improvements or additions to documentation security Security-related fix or improvement size/xl

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@laurigates