npm - @yawlabs/ctxlint - Versions diffs - 0.9.0 → 0.9.2 - Mend

@yawlabs/ctxlint 0.9.0 → 0.9.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/AGENT_SESSION_LINT_SPEC.md +27 -0
package/CONTEXT_LINT_SPEC.md +23 -5
package/README.md +109 -59
package/action.yml +1 -1
package/agent-session-lint-rules.json +10 -0
package/context-lint-rules.json +40 -0
package/dist/index.js +2651 -2113
package/package.json +7 -8

package/AGENT_SESSION_LINT_SPEC.md CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -6,7 +6,7 @@
 [![CI](https://github.com/YawLabs/ctxlint/actions/workflows/ci.yml/badge.svg)](https://github.com/YawLabs/ctxlint/actions/workflows/ci.yml)
 [![Release](https://github.com/YawLabs/ctxlint/actions/workflows/release.yml/badge.svg)](https://github.com/YawLabs/ctxlint/actions/workflows/release.yml)
-**Lint your AI agent context files and MCP server configs against your actual codebase.** Context linting + MCP config linting. 21+ context formats, 8 MCP clients, auto-fix. Works as a CLI, CI step, pre-commit hook, or MCP server.
+**Lint your AI agent context files, MCP server configs, and session data against your actual codebase.** Context linting + MCP config linting + session auditing. 21+ context formats, 8 MCP clients, cross-project consistency, auto-fix. Works as a CLI, CI step, pre-commit hook, or MCP server.
 Your `CLAUDE.md` is lying to your agent. Your `.mcp.json` has a hardcoded API key. ctxlint catches both.
@@ -66,38 +66,44 @@ Useful if you want `ctxlint` available in every project without per-project setu
 ## What It Checks
-| Check | What it finds |
-|-------|--------------|
-| **Broken paths** | File references in context that don't exist in your project |
-| **Wrong commands** | Build/test commands that don't match your package.json scripts or Makefile targets |
-| **Stale context** | Context files not updated after recent code changes |
-| **Token waste** | How much context window your files consume per session |
-| **Redundancy** | Content the agent can already infer (e.g. "We use React" when react is in package.json) |
-| **Contradictions** | Conflicting directives across context files (e.g. "use Jest" in one, "use Vitest" in another) |
-| **Frontmatter** | Invalid or missing YAML frontmatter in Cursor .mdc, Copilot instructions, and Windsurf rules |
-| **CI coverage** | Release/deploy workflows in `.github/workflows/` not documented in any context file |
-| **CI secrets** | Secrets used in CI workflows (`${{ secrets.X }}`) not mentioned in context files |
+| Check                 | What it finds                                                                                 |
+| --------------------- | --------------------------------------------------------------------------------------------- |
+| **Broken paths**      | File references in context that don't exist in your project                                   |
+| **Wrong commands**    | Build/test commands that don't match your package.json scripts or Makefile targets            |
+| **Stale context**     | Context files not updated after recent code changes                                           |
+| **Token waste**       | How much context window your files consume per session                                        |
+| **Redundancy**        | Content the agent can already infer (e.g. "We use React" when react is in package.json)       |
+| **Contradictions**    | Conflicting directives across context files (e.g. "use Jest" in one, "use Vitest" in another) |
+| **Frontmatter**       | Invalid or missing YAML frontmatter in Cursor .mdc, Copilot instructions, and Windsurf rules  |
+| **CI coverage**       | Release/deploy workflows in `.github/workflows/` not documented in any context file           |
+| **CI secrets**        | Secrets used in CI workflows (`${{ secrets.X }}`) not mentioned in context files              |
+| **Missing secrets**   | GitHub secrets set on sibling repos but missing from current project                          |
+| **Diverged configs**  | Canonical config files (CI, tsconfig, etc.) drifting across sibling projects                  |
+| **Missing workflows** | GitHub Actions workflows present in 2+ siblings but absent here                               |
+| **Stale memory**      | Claude Code memory entries referencing paths that no longer exist                             |
+| **Duplicate memory**  | Near-duplicate memories across projects (>60% content overlap)                                |
+| **Loop detection**    | Agent stuck in loops — repeated commands or cyclic patterns in session history                |
 ## Supported Context Files
-| File | Tool |
-|------|------|
-| `CLAUDE.md`, `CLAUDE.local.md`, `.claude/rules/*.md` | Claude Code |
-| `AGENTS.md`, `AGENT.md`, `AGENTS.override.md` | AAIF / Multi-agent standard |
-| `.cursorrules`, `.cursor/rules/*.md`, `.cursor/rules/*.mdc`, `.cursor/rules/*/RULE.md` | Cursor |
-| `.github/copilot-instructions.md`, `.github/instructions/*.md`, `.github/git-commit-instructions.md` | GitHub Copilot |
-| `.windsurfrules`, `.windsurf/rules/*.md` | Windsurf |
-| `GEMINI.md` | Gemini CLI |
-| `.clinerules` | Cline |
-| `.aiderules` | Aider |
-| `.aide/rules/*.md` | Aide / Codestory |
-| `.amazonq/rules/*.md` | Amazon Q Developer |
-| `.goose/instructions.md`, `.goosehints` | Goose by Block |
-| `.junie/guidelines.md`, `.junie/AGENTS.md` | JetBrains Junie |
-| `.aiassistant/rules/*.md` | JetBrains AI Assistant |
-| `.continuerules`, `.continue/rules/*.md` | Continue |
-| `.rules` | Zed |
-| `replit.md` | Replit |
+| File                                                                                                 | Tool                        |
+| ---------------------------------------------------------------------------------------------------- | --------------------------- |
+| `CLAUDE.md`, `CLAUDE.local.md`, `.claude/rules/*.md`                                                 | Claude Code                 |
+| `AGENTS.md`, `AGENT.md`, `AGENTS.override.md`                                                        | AAIF / Multi-agent standard |
+| `.cursorrules`, `.cursor/rules/*.md`, `.cursor/rules/*.mdc`, `.cursor/rules/*/RULE.md`               | Cursor                      |
+| `.github/copilot-instructions.md`, `.github/instructions/*.md`, `.github/git-commit-instructions.md` | GitHub Copilot              |
+| `.windsurfrules`, `.windsurf/rules/*.md`                                                             | Windsurf                    |
+| `GEMINI.md`                                                                                          | Gemini CLI                  |
+| `.clinerules`                                                                                        | Cline                       |
+| `.aiderules`                                                                                         | Aider                       |
+| `.aide/rules/*.md`                                                                                   | Aide / Codestory            |
+| `.amazonq/rules/*.md`                                                                                | Amazon Q Developer          |
+| `.goose/instructions.md`, `.goosehints`                                                              | Goose by Block              |
+| `.junie/guidelines.md`, `.junie/AGENTS.md`                                                           | JetBrains Junie             |
+| `.aiassistant/rules/*.md`                                                                            | JetBrains AI Assistant      |
+| `.continuerules`, `.continue/rules/*.md`                                                             | Continue                    |
+| `.rules`                                                                                             | Zed                         |
+| `replit.md`                                                                                          | Replit                      |
 ## MCP Server Config Linting
@@ -116,28 +122,28 @@ npx @yawlabs/ctxlint --mcp-global
 ### What MCP config files are scanned
-| File | Client |
-|------|--------|
-| `.mcp.json` | Claude Code (universal project config) |
-| `.cursor/mcp.json` | Cursor |
-| `.vscode/mcp.json` | VS Code / GitHub Copilot |
-| `.amazonq/mcp.json` | Amazon Q Developer |
-| `.continue/mcpServers/*.json` | Continue |
+| File                          | Client                                 |
+| ----------------------------- | -------------------------------------- |
+| `.mcp.json`                   | Claude Code (universal project config) |
+| `.cursor/mcp.json`            | Cursor                                 |
+| `.vscode/mcp.json`            | VS Code / GitHub Copilot               |
+| `.amazonq/mcp.json`           | Amazon Q Developer                     |
+| `.continue/mcpServers/*.json` | Continue                               |
 With `--mcp-global`, also scans Claude Desktop, Cursor, Windsurf, and Amazon Q global configs.
 ### What MCP config checks catch
-| Check | What it finds |
-|-------|--------------|
-| **Schema** | Invalid JSON, wrong root key (`servers` vs `mcpServers`), missing required fields |
-| **Security** | Hardcoded API keys and Bearer tokens in git-tracked config files |
-| **Commands** | Missing `cmd /c` wrapper for npx on Windows, broken file paths in args |
-| **Deprecated** | SSE transport usage (deprecated March 2025, use Streamable HTTP) |
-| **Env vars** | Wrong env var syntax for the client (`${VAR}` vs `${env:VAR}` vs `${{ secrets.VAR }}`) |
-| **URLs** | Malformed URLs, localhost in project configs, missing path component |
-| **Consistency** | Same server configured differently across client configs |
-| **Redundancy** | Disabled servers, identical configs at multiple scopes |
+| Check           | What it finds                                                                          |
+| --------------- | -------------------------------------------------------------------------------------- |
+| **Schema**      | Invalid JSON, wrong root key (`servers` vs `mcpServers`), missing required fields      |
+| **Security**    | Hardcoded API keys and Bearer tokens in git-tracked config files                       |
+| **Commands**    | Missing `cmd /c` wrapper for npx on Windows, broken file paths in args                 |
+| **Deprecated**  | SSE transport usage (deprecated March 2025, use Streamable HTTP)                       |
+| **Env vars**    | Wrong env var syntax for the client (`${VAR}` vs `${env:VAR}` vs `${{ secrets.VAR }}`) |
+| **URLs**        | Malformed URLs, localhost in project configs, missing path component                   |
+| **Consistency** | Same server configured differently across client configs                               |
+| **Redundancy**  | Disabled servers, identical configs at multiple scopes                                 |
 ### Example MCP config output
@@ -168,10 +174,47 @@ The full specification for MCP config linting rules, the cross-client config lan
 - **[`MCP_CONFIG_LINT_SPEC.md`](./MCP_CONFIG_LINT_SPEC.md)** — 23 lint rules across 8 categories, the complete client/format reference, and implementation guidance. Tool-agnostic — any linter can implement it.
 - **[`mcp-config-lint-rules.json`](./mcp-config-lint-rules.json)** — Machine-readable rule catalog for programmatic consumption by AI agents, CI systems, and other tools.
+## Session Linting
+ctxlint can audit AI agent session data — history files and memory entries — for cross-project consistency. Session checks compare your current project against sibling repos to catch drift and missing setup.
+```bash
+# Lint context files + session data
+npx @yawlabs/ctxlint --session
+# Lint only session data
+npx @yawlabs/ctxlint --session-only
+```
+Session checks are **opt-in** because they access files outside the project directory (agent history in your home directory, sibling repos in the parent directory).
+### What session files are scanned
+| Agent       | History                   | Memory                             |
+| ----------- | ------------------------- | ---------------------------------- |
+| Claude Code | `~/.claude/history.jsonl` | `~/.claude/projects/*/memory/*.md` |
+| Codex CLI   | `~/.codex/history.jsonl`  | —                                  |
+### What session checks catch
+| Check                 | What it finds                                                                                                                                    |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Missing secrets**   | `gh secret set` ran on 2+ sibling repos but not this one                                                                                         |
+| **Diverged configs**  | Shared config files (CI workflows, tsconfig, .prettierrc, etc.) with 20-90% line overlap — enough to be related, different enough to be drifting |
+| **Missing workflows** | GitHub Actions workflows in 2+ siblings but absent from this project                                                                             |
+| **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                                                            |
+### 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-rules.json`](./agent-session-lint-rules.json)** — Machine-readable rule catalog.
 ## Example Output
 ```
-ctxlint v0.7.0
+ctxlint v0.9.0
 Scanning /Users/you/my-app...
@@ -214,6 +257,8 @@ Options:
   --mcp                Enable MCP config linting alongside context file checks
   --mcp-only           Run only MCP config checks, skip context file checks
   --mcp-global         Also scan user/global MCP config files (implies --mcp)
+  --session            Enable session audit checks (cross-project consistency)
+  --session-only       Run only session checks, skip context and MCP checks
   --mcp-server         Start the MCP server (for IDE/agent integration)
   --watch              Re-lint on context file changes
   -V, --version        Output the version number
@@ -223,9 +268,9 @@ 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`
+**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 `mcp-*` check name implies `--mcp`. Passing any `session-*` check name implies `--session`.
 ## Watch Mode
@@ -297,7 +342,7 @@ Add to your `.pre-commit-config.yaml`:
 ```yaml
 repos:
   - repo: https://github.com/yawlabs/ctxlint
-    rev: v0.7.0
+    rev: v0.9.0
     hooks:
       - id: ctxlint
 ```
@@ -315,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"]
 }
@@ -327,7 +374,7 @@ CLI flags override config file settings. Use `--config <path>` to load a config
 ## Use as MCP Server
-ctxlint ships with an MCP server that exposes five tools (`ctxlint_audit`, `ctxlint_mcp_audit`, `ctxlint_validate_path`, `ctxlint_token_report`, `ctxlint_fix`). All read-only tools declare annotations so MCP clients can skip confirmation dialogs.
+ctxlint ships with an MCP server that exposes six tools (`ctxlint_audit`, `ctxlint_mcp_audit`, `ctxlint_session_audit`, `ctxlint_validate_path`, `ctxlint_token_report`, `ctxlint_fix`). All read-only tools declare annotations so MCP clients can skip confirmation dialogs.
 ### With Claude Code
@@ -407,16 +454,19 @@ Returns structured JSON with all file results, issues, and summary — useful fo
 ## Specifications
-ctxlint is the reference implementation of two open specifications for linting AI agent interfaces. These specs are tool-agnostic — any linter, IDE extension, or CI system can implement them.
+ctxlint is the reference implementation of three open specifications for linting AI agent interfaces. These specs are tool-agnostic — any linter, IDE extension, or CI system can implement them.
+| Spec                                                           | What it covers                                                                                                                                                                                                                     |
+| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **[AI Context File Linting Spec](./CONTEXT_LINT_SPEC.md)**     | 19 rules for validating context files (CLAUDE.md, .cursorrules, AGENTS.md, etc.) across 17 clients. Covers file formats, frontmatter schemas, path/command validation, staleness, token budgets, redundancy, and contradictions.   |
+| **[MCP Config Linting Spec](./MCP_CONFIG_LINT_SPEC.md)**       | 23 rules for validating MCP server configs (.mcp.json, .cursor/mcp.json, .vscode/mcp.json, etc.) across 8 clients. Covers schema validation, hardcoded secrets, env var syntax, deprecated transports, and cross-file consistency. |
+| **[Agent Session Linting Spec](./AGENT_SESSION_LINT_SPEC.md)** | 7 rules for auditing agent session data (history, memory) across 8 agents. Covers cross-project secret consistency, config drift, stale memory, and loop detection.                                                                |
-| Spec | What it covers |
-|------|---------------|
-| **[AI Context File Linting Spec](./CONTEXT_LINT_SPEC.md)** | 19 rules for validating context files (CLAUDE.md, .cursorrules, AGENTS.md, etc.) across 17 clients. Covers file formats, frontmatter schemas, path/command validation, staleness, token budgets, redundancy, and contradictions. |
-| **[MCP Config Linting Spec](./MCP_CONFIG_LINT_SPEC.md)** | 23 rules for validating MCP server configs (.mcp.json, .cursor/mcp.json, .vscode/mcp.json, etc.) across 8 clients. Covers schema validation, hardcoded secrets, env var syntax, deprecated transports, and cross-file consistency. |
+All specs include machine-readable rule catalogs for programmatic consumption:
-Both specs include machine-readable rule catalogs for programmatic consumption:
 - [`context-lint-rules.json`](./context-lint-rules.json) — context file rules and 16 supported format definitions
 - [`mcp-config-lint-rules.json`](./mcp-config-lint-rules.json) — MCP config rules and 8 client definitions
+- [`agent-session-lint-rules.json`](./agent-session-lint-rules.json) — session lint rules and 8 agent data source definitions
 ## Also By Yaw Labs

package/action.yml CHANGED Viewed

@@ -18,7 +18,7 @@ runs:
   using: 'composite'
   steps:
     - name: Set up Node.js
-      uses: actions/setup-node@v4
+      uses: actions/setup-node@v6
       with:
         node-version: '20'

package/agent-session-lint-rules.json CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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",