@yawlabs/ctxlint 0.9.1 → 0.9.2

package/AGENT_SESSION_LINT_SPEC.md

@@ -46,6 +46,7 @@ This is the third pillar alongside context file linting (`CLAUDE.md`, `.cursorru
   - [2.5 session/duplicate-memory](#25-sessionduplicate-memory)
   - [2.6 session/consecutive-repeat](#26-sessionconsecutive-repeat)
   - [2.7 session/cyclic-pattern](#27-sessioncyclic-pattern)
+  - [2.8 session/memory-index-overflow](#28-sessionmemory-index-overflow)
 - [3. Rule Catalog (machine-readable)](#3-rule-catalog-machine-readable)
 - [4. Implementing This Specification](#4-implementing-this-specification)
 - [5. Contributing](#5-contributing)
@@ -312,6 +313,32 @@ Detects short repeating cycles of commands, indicating an agent stuck in a loop.
 
 ---
 
+### 2.8 session/memory-index-overflow
+
+Detects when `MEMORY.md` exceeds Claude Code's session-load cap. Claude Code loads the first 200 lines OR 25KB of `MEMORY.md` at session start — whichever comes first. Entries past the cap are silently dropped, so auto-memory pointers beyond that point are effectively invisible to the agent.
+
+| Field | Value |
+|---|---|
+| **Rule ID** | `session/memory-index-overflow` |
+| **Severity** | warning |
+| **Trigger** | `~/.claude/projects/<encoded-project>/memory/MEMORY.md` exceeds 200 lines OR 25,600 bytes |
+| **Message (lines)** | `MEMORY.md has <N> lines — only the first 200 are loaded. <excess> line(s) are effectively invisible.` |
+| **Message (bytes)** | `MEMORY.md is <N> bytes — only the first 25,600 bytes are loaded. ~<excess> bytes are effectively invisible.` |
+| **Source** | [code.claude.com/docs/en/memory](https://code.claude.com/docs/en/memory) |
+
+**Detection algorithm:**
+
+1. Resolve `MEMORY.md` via the Claude-encoded project directory: `~/.claude/projects/<encode(currentProject)>/memory/MEMORY.md`.
+2. If the file doesn't exist, no-op.
+3. Count lines and bytes. Emit a warning for each dimension that exceeds its cap.
+
+**Notes:**
+- Each MEMORY.md entry should stay under ~150 characters (one-line pointer, not content).
+- The remediation is to trim older entries, consolidate duplicates, or move detail into the corresponding topic file — topic files stay on-demand and don't count toward the cap.
+- Both line and byte caps can fire independently (a short file with very long lines trips the byte cap first; a long file with short lines trips the line cap first).
+
+---
+
 ## 3. Rule Catalog (machine-readable)
 
 A machine-readable JSON catalog of all rules is available at [`agent-session-lint-rules.json`](./agent-session-lint-rules.json).

package/CONTEXT_LINT_SPEC.md

@@ -380,13 +380,31 @@ Monitors context file size to help teams manage context window consumption.
 | `warning` | 3000 | Per-file warning |
 | `error` | 8000 | Per-file error |
 | `aggregate` | 5000 | Cross-file combined warning |
+| `tierBreakdown` | 1000 | Triggers `tier-tokens/section-breakdown` on an always-loaded file |
+| `tierAggregate` | 4000 | Triggers `tier-tokens/aggregate` across always-loaded files |
+
+### 3.5 tier-tokens — tier-aware token accounting
+
+Reports token cost attributable to the **always-loaded** tier: files Claude Code (and similar agents) load into every session regardless of request. Complements `tokens` by surfacing which sections / files are costing budget every turn — and which inviolable rules need hook-based enforcement to actually bind.
+
+"Always-loaded" basenames: `CLAUDE.md`, `CLAUDE.local.md`, `AGENTS.md`, `AGENTS.override.md`, `AGENT.md`, `GEMINI.md`, `.cursorrules`, `.windsurfrules`, `.clinerules`, `.aiderules`, `.continuerules`, `.rules`, `.goosehints`, `replit.md`, `.github/copilot-instructions.md`, `.junie/guidelines.md`, `.goose/instructions.md`. Rules files in `/rules/` directories are classified by frontmatter: if `paths:` is set they're path-scoped on-demand; otherwise they're always-loaded.
+
+| Rule ID | Severity | Trigger | Message |
+|---|---|---|---|
+| `tier-tokens/section-breakdown` | info | Always-loaded file exceeds `tierBreakdown` tokens AND has H1/H2 sections | `{N} tokens loaded every session — heaviest top-level section(s): ...` |
+| `tier-tokens/aggregate` | warning | Two or more always-loaded files combined exceed `tierAggregate` tokens | `{count} always-loaded files total {N} tokens — loaded every session` |
+| `tier-tokens/hard-enforcement-missing` | info | Line in an always-loaded file uses inviolable framing (NEVER/ALWAYS/DO NOT/MUST NOT) with a backticked command, and no matching PreToolUse hook or `permissions.deny` entry exists in `.claude/settings.json` or `~/.claude/settings.json` | `Inviolable framing ("{line}") without a hook to back it up` |
+
+**Note on overlap with `tokens`:** `tokens/info` and `tier-tokens/section-breakdown` both fire on a large CLAUDE.md. They're complementary — `tokens` is tier-agnostic ("this file is large"), `tier-tokens` adds the always-loaded attribution and demotion guidance. Use `--ignore tokens` or `--ignore tier-tokens` to pick one.
+
+**Source:** [Claude Code memory docs](https://code.claude.com/docs/en/memory). Rule behavior is grounded in the documented loading model ("there's no guarantee of strict compliance" → hard-enforcement-missing; section-demotion-to-skills → structurally reduces per-session cost).
 
 **Suggestions:**
 - For `excessive`: `Consider splitting into focused sections or removing redundant content.`
 - For `large`: `Consider trimming — research shows diminishing returns past ~300 lines.`
 - For `aggregate`: `Consider consolidating or trimming to reduce per-session context cost.`
 
-### 3.5 redundancy — inferable content
+### 3.6 redundancy — inferable content
 
 Detects content that the agent can already infer from project metadata, reducing unnecessary context window consumption.
 
@@ -442,7 +460,7 @@ Implementations should maintain and extend this mapping as the ecosystem evolves
 
 **Suggestion for `duplicate-content`:** `Consider consolidating into a single context file.`
 
-### 3.6 contradictions — cross-file conflicts
+### 3.7 contradictions — cross-file conflicts
 
 Detects conflicting directives across multiple context files. This is a cross-file check.
 
@@ -518,7 +536,7 @@ Detects conflicting directives across multiple context files. This is a cross-fi
 - Only flag contradictions *across* files. A single file contradicting itself is unusual and likely intentional (e.g., "use camelCase for variables, PascalCase for components").
 - Include the exact line numbers and text from both files in the detail.
 
-### 3.7 frontmatter — client metadata validation
+### 3.8 frontmatter — client metadata validation
 
 Validates YAML frontmatter required by specific clients. Only applies to file formats that use frontmatter.
 
@@ -539,7 +557,7 @@ Validates YAML frontmatter required by specific clients. Only applies to file fo
 
 ---
 
-### 3.8 ci-coverage — CI workflow documentation
+### 3.9 ci-coverage — CI workflow documentation
 
 Checks that release/deploy CI workflows are documented in context files. When agents encounter a project with CI release workflows but no documentation about how releases work, they guess — often incorrectly.
 
@@ -558,7 +576,7 @@ Checks that release/deploy CI workflows are documented in context files. When ag
 
 ---
 
-### 3.9 ci-secrets — CI secrets documentation
+### 3.10 ci-secrets — CI secrets documentation
 
 Checks that secrets referenced in CI workflow files are mentioned in context files. Undocumented secrets are a common source of agent looping — agents try to create new tokens, pull from `.npmrc`, or guess at auth setup.
 

package/README.md

@@ -268,7 +268,7 @@ Commands:
   init                 Set up a git pre-commit hook
 ```
 
-**Available checks:** `paths`, `commands`, `staleness`, `tokens`, `redundancy`, `contradictions`, `frontmatter`, `ci-coverage`, `ci-secrets`, `mcp-schema`, `mcp-security`, `mcp-commands`, `mcp-deprecated`, `mcp-env`, `mcp-urls`, `mcp-consistency`, `mcp-redundancy`, `session-missing-secret`, `session-diverged-file`, `session-missing-workflow`, `session-stale-memory`, `session-duplicate-memory`, `session-loop-detection`
+**Available checks:** `paths`, `commands`, `staleness`, `tokens`, `tier-tokens`, `redundancy`, `contradictions`, `frontmatter`, `ci-coverage`, `ci-secrets`, `mcp-schema`, `mcp-security`, `mcp-commands`, `mcp-deprecated`, `mcp-env`, `mcp-urls`, `mcp-consistency`, `mcp-redundancy`, `session-missing-secret`, `session-diverged-file`, `session-missing-workflow`, `session-stale-memory`, `session-duplicate-memory`, `session-loop-detection`, `session-memory-index-overflow`
 
 Passing any `mcp-*` check name implies `--mcp`. Passing any `session-*` check name implies `--session`.
 
@@ -360,7 +360,9 @@ Create a `.ctxlintrc` or `.ctxlintrc.json` in your project root:
     "info": 500,
     "warning": 2000,
     "error": 5000,
-    "aggregate": 4000
+    "aggregate": 4000,
+    "tierBreakdown": 1000,
+    "tierAggregate": 4000
   },
   "contextFiles": ["CONVENTIONS.md", "docs/ai-rules.md"]
 }

package/agent-session-lint-rules.json

@@ -86,6 +86,16 @@
       "trigger": "Agent history shows a repeating sequence of 2-3 commands (e.g. A,B,A,B) repeated 2+ times.",
       "message": "Cyclic pattern repeated {count} times: {cycle}",
       "fixable": false
+    },
+    {
+      "id": "session/memory-index-overflow",
+      "category": "session",
+      "severity": "warning",
+      "description": "MEMORY.md exceeds Claude Code's session-load cap. The first 200 lines / 25KB are loaded every session; anything beyond is effectively invisible to the agent.",
+      "trigger": "~/.claude/projects/<encoded-project>/memory/MEMORY.md exceeds 200 lines OR 25,600 bytes.",
+      "message": "MEMORY.md has {N} lines — only the first 200 are loaded. {excess} lines are effectively invisible.",
+      "fixable": false,
+      "source": "code.claude.com/docs/en/memory"
     }
   ],
   "dataSources": [

package/context-lint-rules.json

@@ -29,6 +29,12 @@
       "description": "Monitors context file size to help teams manage context window consumption.",
       "scope": "per-file and cross-file"
     },
+    {
+      "id": "tier-tokens",
+      "name": "Tier-Aware Token Accounting",
+      "description": "Reports per-section token cost for always-loaded context files and flags demotion candidates for on-demand tiers (skills, subagents, memory).",
+      "scope": "per-file"
+    },
     {
       "id": "redundancy",
       "name": "Inferable Content",
@@ -196,6 +202,40 @@
       "configurable": true,
       "defaultThreshold": 5000
     },
+    {
+      "id": "tier-tokens/section-breakdown",
+      "category": "tier-tokens",
+      "severity": "info",
+      "description": "Reports the heaviest top-level sections in an always-loaded context file and suggests demoting the largest to an on-demand tier (skill, subagent, or memory).",
+      "trigger": "An always-loaded context file (CLAUDE.md, AGENTS.md, .cursorrules, etc. — excluding path-scoped rules files) exceeds the tierBreakdown threshold (default 1000 tokens) and contains H1 or H2 sections.",
+      "message": "{N} tokens loaded every session — heaviest top-level section(s): ...",
+      "fixable": false,
+      "configurable": true,
+      "configKey": "tokenThresholds.tierBreakdown",
+      "defaultThreshold": 1000
+    },
+    {
+      "id": "tier-tokens/aggregate",
+      "category": "tier-tokens",
+      "severity": "warning",
+      "description": "Combined token cost of always-loaded context files exceeds the recommended budget.",
+      "trigger": "Two or more always-loaded files total more than the tierAggregate threshold (default 4000 tokens).",
+      "message": "{count} always-loaded files total {N} tokens — loaded every session",
+      "fixable": false,
+      "configurable": true,
+      "configKey": "tokenThresholds.tierAggregate",
+      "defaultThreshold": 4000
+    },
+    {
+      "id": "tier-tokens/hard-enforcement-missing",
+      "category": "tier-tokens",
+      "severity": "info",
+      "description": "An always-loaded file uses inviolable framing (NEVER / ALWAYS / DO NOT / MUST NOT) paired with a concrete command, but no corresponding PreToolUse hook or permissions.deny entry exists in settings.json. Rules in always-loaded files are advisory — without a hook the agent may still run the command.",
+      "trigger": "Line in an always-loaded file matches NEVER|ALWAYS|DO NOT|MUST NOT with a backticked command, and .claude/settings.json / ~/.claude/settings.json does not contain a matching PreToolUse hook or permissions.deny entry.",
+      "message": "Inviolable framing without a hook to back it up",
+      "fixable": false,
+      "source": "code.claude.com/docs/en/hooks-guide"
+    },
     {
       "id": "redundancy/tech-mention",
       "category": "redundancy",