@yawlabs/ctxlint 0.9.1 → 0.9.3

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

@@ -205,10 +205,11 @@ Session checks are **opt-in** because they access files outside the project dire
 | **Stale memory**      | Memory entries referencing file paths that no longer exist                                                                                       |
 | **Duplicate memory**  | Near-duplicate memory entries across projects (>60% overlap)                                                                                     |
 | **Loop detection**    | Agent stuck in a loop — 3+ consecutive identical commands, or cyclic A,B,A,B patterns                                                            |
+| **Memory index overflow** | `MEMORY.md` exceeds Claude Code's documented 200-line / 25KB session-load cap, so entries past the cap are invisible to the agent            |
 
 ### Session Linting Specification
 
-- **[`AGENT_SESSION_LINT_SPEC.md`](./AGENT_SESSION_LINT_SPEC.md)** — 7 lint rules, the agent session data landscape across 8 agents, sibling detection strategy, and implementation guidance.
+- **[`AGENT_SESSION_LINT_SPEC.md`](./AGENT_SESSION_LINT_SPEC.md)** — 8 lint rules, the agent session data landscape across 8 agents, sibling detection strategy, and implementation guidance.
 - **[`agent-session-lint-rules.json`](./agent-session-lint-rules.json)** — Machine-readable rule catalog.
 
 ## Example Output
@@ -268,7 +269,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`.
 
@@ -287,7 +288,15 @@ Re-lints automatically when any context file, MCP config, or `package.json` chan
   run: npx @yawlabs/ctxlint --strict
 ```
 
-Exits with code 1 if any errors or warnings are found.
+### Exit Codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success — no issues, or issues below the strict threshold |
+| `1` | Strict mode caught at least one error or warning (`--strict` is set) |
+| `2` | Config error, invalid CLI option, or internal failure |
+
+In non-strict mode ctxlint always exits `0` — it's a reporting tool by default. Pass `--strict` to enforce in CI.
 
 ### GitHub Action
 
@@ -360,7 +369,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"]
 }
@@ -368,6 +379,26 @@ Create a `.ctxlintrc` or `.ctxlintrc.json` in your project root:
 
 The `contextFiles` array adds custom file patterns to scan alongside the built-in list. Useful for project-specific context files like `CONVENTIONS.md`.
 
+### Config Reference
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `checks` | `string[]` | all checks | Checks to run. Check names include `paths`, `commands`, `tokens`, `tier-tokens`, `redundancy`, `contradictions`, `frontmatter`, `staleness`, `ci-coverage`, `ci-secrets`, plus any `mcp-*` / `session-*`. |
+| `ignore` | `string[]` | `[]` | Checks to skip, evaluated after `checks`. |
+| `strict` | `boolean` | `false` | Exit non-zero on any warning or error. |
+| `tokenThresholds` | `object` | see below | Per-file and cross-file token thresholds. |
+| `tokenThresholds.info` | `number` | `1000` | Per-file info threshold for `tokens/info`. |
+| `tokenThresholds.warning` | `number` | `3000` | Per-file warning threshold for `tokens/large`. |
+| `tokenThresholds.error` | `number` | `8000` | Per-file error threshold for `tokens/excessive`. |
+| `tokenThresholds.aggregate` | `number` | `5000` | Cross-file total threshold for `tokens/aggregate`. |
+| `tokenThresholds.tierBreakdown` | `number` | `1000` | Always-loaded file threshold for `tier-tokens/section-breakdown`. |
+| `tokenThresholds.tierAggregate` | `number` | `4000` | Combined always-loaded threshold for `tier-tokens/aggregate`. |
+| `contextFiles` | `string[]` | `[]` | Extra glob patterns to scan alongside the built-in list. |
+| `mcp` | `boolean` | `false` | Enable MCP config checks by default (same as `--mcp`). |
+| `mcpGlobal` | `boolean` | `false` | Also scan user/global MCP configs (same as `--mcp-global`). |
+
+Config file resolution order: `.ctxlintrc` → `.ctxlintrc.json` in the project root. Use `--config <path>` to point elsewhere. CLI flags override config fields.
+
 CLI flags override config file settings. Use `--config <path>` to load a config from a custom location.
 
 ## Use as MCP Server

package/agent-session-lint-rules.json

@@ -21,7 +21,8 @@
       "description": "GitHub secret set on sibling repos but not this project.",
       "trigger": "gh secret set command found in agent history for 2+ siblings but not current project.",
       "message": "Secret \"{name}\" is set on {count} sibling repos but not this project",
-      "fixable": false
+      "fixable": false,
+      "stability": "stable"
     },
     {
       "id": "session/diverged-file",
@@ -40,7 +41,8 @@
         ".eslintrc.json",
         "tsconfig.json",
         ".gitignore"
-      ]
+      ],
+      "stability": "stable"
     },
     {
       "id": "session/missing-workflow",
@@ -49,7 +51,8 @@
       "description": "GitHub Actions workflow missing from this project.",
       "trigger": "Workflow file exists in 2+ siblings but not current project (which has .github).",
       "message": "Workflow \"{workflow}\" exists in {count} sibling repos but not this project",
-      "fixable": false
+      "fixable": false,
+      "stability": "stable"
     },
     {
       "id": "session/stale-memory",
@@ -58,7 +61,8 @@
       "description": "Memory file references paths that no longer exist.",
       "trigger": "Claude Code memory file contains path references to files that have been deleted or moved.",
       "message": "Memory references \"{path}\" which no longer exists",
-      "fixable": false
+      "fixable": false,
+      "stability": "stable"
     },
     {
       "id": "session/duplicate-memory",
@@ -67,7 +71,8 @@
       "description": "Near-duplicate memory entries across projects.",
       "trigger": "Two memory files from different projects have >60% line overlap.",
       "message": "\"{file1}\" and \"{file2}\" have {overlap}% content overlap",
-      "fixable": false
+      "fixable": false,
+      "stability": "stable"
     },
     {
       "id": "session/consecutive-repeat",
@@ -76,7 +81,8 @@
       "description": "Same command run 3+ times consecutively in agent history.",
       "trigger": "Agent history for the current project shows the same display string 3+ times in a row.",
       "message": "Command run {count} times consecutively: \"{command}\"",
-      "fixable": false
+      "fixable": false,
+      "stability": "experimental"
     },
     {
       "id": "session/cyclic-pattern",
@@ -85,7 +91,19 @@
       "description": "Cyclic command pattern detected in agent history.",
       "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
+      "fixable": false,
+      "stability": "experimental"
+    },
+    {
+      "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",
+      "stability": "stable"
     }
   ],
   "dataSources": [