@yawlabs/ctxlint 0.19.0 → 0.21.0

package/README.md

@@ -386,12 +386,17 @@ Create a `.ctxlintrc` or `.ctxlintrc.json` in your project root:
     "tierBreakdown": 1000,
     "tierAggregate": 4000
   },
-  "contextFiles": ["CONVENTIONS.md", "docs/ai-rules.md"]
+  "contextFiles": ["CONVENTIONS.md", "docs/ai-rules.md"],
+  "exclude": ["fixtures/**", "examples/**"]
 }
 ```
 
 The `contextFiles` array adds custom file patterns to scan alongside the built-in list. Useful for project-specific context files like `CONVENTIONS.md`.
 
+The `exclude` array is its counterpart: globs of context files to drop from the scan entirely. Use it for files that are not this project's agent context at all — test fixtures, example projects, vendored templates.
+
+`exclude` removes **files**, where `ignore` / `ignoreRules` / `.ctxlintignore` suppress **findings**. That distinction matters for the cross-file checks: `contradictions` and `redundancy/duplicate-content` compare the discovered set and report against the literal `(project)` path, which no per-file glob can match. Excluding the files is the only way to silence a conflict between two files you never wanted linted. Reach for `.ctxlintignore` when a real context file has one noisy finding; reach for `exclude` when the file shouldn't be in the corpus.
+
 ### Config Reference
 
 | Field                           | Type       | Default    | Meaning                                                                                                                                                                                                   |
@@ -407,6 +412,7 @@ The `contextFiles` array adds custom file patterns to scan alongside the built-i
 | `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.                                                                                                                                                  |
+| `exclude`                       | `string[]` | `[]`       | Globs of context files to drop from the scan entirely, matched against each file's project-relative path. Removes files rather than suppressing findings, so excluded files are also invisible to the cross-file checks. |
 | `mcp`                           | `boolean`  | `false`    | Enable MCP config checks by default (same as `--mcp`).                                                                                                                                                    |
 | `mcpOnly`                       | `boolean`  | `false`    | Run only MCP config checks, skip context-file checks (same as `--mcp-only`).                                                                                                                              |
 | `mcpGlobal`                     | `boolean`  | `false`    | Also scan user/global MCP configs (same as `--mcp-global`).                                                                                                                                               |
@@ -511,9 +517,9 @@ ctxlint is the reference implementation of four open specifications for linting
 
 | Spec                                                           | What it covers                                                                                                                                                                                                                            |
 | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **[AI Context File Linting Spec](./CONTEXT_LINT_SPEC.md)**     | 39 rules for validating context files (CLAUDE.md, .cursorrules, AGENTS.md, etc.) across 16 clients. Covers file formats, frontmatter schemas, path/command validation, staleness, token budgets, redundancy, and contradictions.          |
+| **[AI Context File Linting Spec](./CONTEXT_LINT_SPEC.md)**     | 41 rules for validating context files (CLAUDE.md, .cursorrules, AGENTS.md, etc.) across 16 clients. Covers file formats, frontmatter schemas, path/command validation, staleness, token budgets, redundancy, and contradictions.          |
 | **[MCP Config Linting Spec](./MCP_CONFIG_LINT_SPEC.md)**       | 29 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)** | 11 rules for auditing agent session data (history, memory) across 8 agents. Covers cross-project secret consistency, config drift, stale memory, and loop detection.                                                                       |
+| **[Agent Session Linting Spec](./AGENT_SESSION_LINT_SPEC.md)** | 12 rules for auditing agent session data (history, memory) across 8 agents. Covers cross-project secret consistency, config drift, stale memory, and loop detection.                                                                       |
 | **[Agent Skill Linting Spec](./AGENT_SKILL_LINT_SPEC.md)**     | 5 rules for auditing Claude Code skill (`SKILL.md`) and agent (`.md`) definitions under `~/.claude`. Covers frontmatter presence, broken refs, trigger-phrase collisions, orphaned skills, and dead tool restrictions. (v1, experimental) |
 
 All specs include machine-readable rule catalogs for programmatic consumption:

package/agent-session-lint-rules.json

@@ -134,6 +134,16 @@
       "message": "{count} files edited on '{branch}' with no intervening commit",
       "fixable": false,
       "stability": "stable"
+    },
+    {
+      "id": "session/unresolvable-sha",
+      "category": "session",
+      "severity": "warning",
+      "description": "A memory cites a git SHA that does not resolve in the repository.",
+      "trigger": "A 7-40 character hex token outside code fences, preceded on the same line by a commit-citation cue (commit, SHA, HEAD, landed in, reverted, ...), does not resolve via git cat-file. UUID members, digest prefixes, decimal ids and version fragments are excluded before resolution; without a git repository the rule reports nothing.",
+      "message": "cited commit {sha} does not resolve in this repository",
+      "fixable": false,
+      "stability": "experimental"
     }
   ],
   "dataSources": [

package/context-lint-rules.json

@@ -170,6 +170,26 @@
       "fixable": false,
       "stability": "stable"
     },
+    {
+      "id": "commands/exit-status-masked",
+      "category": "commands",
+      "severity": "warning",
+      "description": "A verification command's exit status is discarded by a pipe into a filter, so the success claim that follows cannot fail.",
+      "trigger": "A verifier (tsc, eslint, biome, vitest, pytest, cargo test, or an npm/pnpm/yarn/bun script resolving to one) heads a pipeline whose last stage is a filter or pager (head, tail, grep, sed, awk, less, cat, tee, wc), and the pipeline is followed by && plus a success-announcing echo/printf, or by an echo of $?, with no set -o pipefail in scope.",
+      "message": "\"{cmd}\" — exit status comes from \"{filter}\", not \"{verifier}\"; the success claim cannot fail",
+      "fixable": false,
+      "stability": "experimental"
+    },
+    {
+      "id": "commands/unknown-subcommand",
+      "category": "commands",
+      "severity": "error",
+      "description": "A documented invocation of the project's own binary uses a subcommand the CLI does not implement.",
+      "trigger": "A command invokes a name declared in package.json#bin with a leading non-flag argument that is not in the CLI's known subcommand set, where that set was statically resolved as closed from the entry file.",
+      "message": "\"{cmd}\" — \"{sub}\" is not a subcommand of {bin} (known: {known})",
+      "fixable": false,
+      "stability": "experimental"
+    },
     {
       "id": "staleness/stale",
       "category": "staleness",