@yawlabs/ctxlint 0.7.0 → 0.9.0

package/.pre-commit-hooks.yaml

@@ -5,4 +5,3 @@
   language: node
   always_run: true
   pass_filenames: false
-  types: [file]

package/AGENT_SESSION_LINT_SPEC.md

@@ -44,6 +44,8 @@ This is the third pillar alongside context file linting (`CLAUDE.md`, `.cursorru
   - [2.3 session/missing-workflow](#23-sessionmissing-workflow)
   - [2.4 session/stale-memory](#24-sessionstale-memory)
   - [2.5 session/duplicate-memory](#25-sessionduplicate-memory)
+  - [2.6 session/consecutive-repeat](#26-sessionconsecutive-repeat)
+  - [2.7 session/cyclic-pattern](#27-sessioncyclic-pattern)
 - [3. Rule Catalog (machine-readable)](#3-rule-catalog-machine-readable)
 - [4. Implementing This Specification](#4-implementing-this-specification)
 - [5. Contributing](#5-contributing)
@@ -125,7 +127,7 @@ Skip hidden directories (starting with `.`) and `node_modules`.
 
 ## 2. Lint Rules
 
-5 rules in 1 category (`session`). All rules in this category perform cross-project checks using sibling detection.
+7 rules in 1 category (`session`). All rules in this category perform cross-project checks using sibling detection or per-project history analysis.
 
 Severity levels:
 - **error** -- the session data reveals a verifiably missing configuration. Should fail CI.
@@ -263,6 +265,53 @@ Detects memory entries from different projects that have significant content ove
 
 ---
 
+### 2.6 session/consecutive-repeat
+
+Detects when an agent runs the same command 3 or more times consecutively, indicating a loop.
+
+| Field | Value |
+|---|---|
+| **Rule ID** | `session/consecutive-repeat` |
+| **Severity** | warning |
+| **Trigger** | 3+ consecutive history entries with identical `display` values for the current project |
+| **Message** | `Command run <N> times consecutively: "<command>"` |
+
+**Detection algorithm:**
+
+1. Filter history entries to the current project path (normalized).
+2. Sort entries by timestamp.
+3. Slide a window over the sorted entries. For each run of 3+ entries with identical `display` values, emit a warning.
+
+**Notes:**
+- Truncates long command strings to 80 characters in the message for readability.
+- This rule helps surface cases where an agent is stuck retrying a failing command instead of changing approach.
+
+---
+
+### 2.7 session/cyclic-pattern
+
+Detects short repeating cycles of commands, indicating an agent stuck in a loop.
+
+| Field | Value |
+|---|---|
+| **Rule ID** | `session/cyclic-pattern` |
+| **Severity** | warning |
+| **Trigger** | A sequence of 2-3 distinct commands repeating 2+ times consecutively (e.g. A,B,A,B) |
+| **Message** | `Cyclic pattern repeated <N> times: <cycle>` |
+
+**Detection algorithm:**
+
+1. Filter history entries to the current project, sorted by timestamp.
+2. For cycle lengths 2 and 3, slide a window checking if the next `cycleLen` entries match the current cycle.
+3. Cycles where every element is the same are excluded (already caught by `session/consecutive-repeat`).
+4. Subsumption: if a shorter cycle is fully contained within an already-reported longer cycle at the same position, skip it.
+
+**Notes:**
+- A cycle like "edit file → run tests → edit file → run tests" is a common pattern when an agent is making iterative fixes. This rule flags when the cycle repeats enough times to suggest the agent isn't making progress.
+- The suggestion directs users to check if a context file is missing workflow instructions.
+
+---
+
 ## 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

@@ -15,7 +15,7 @@ This specification defines a standard set of lint rules for validating AI agent
 
 The specification includes:
 - A complete reference of context file formats across 17 AI coding clients (21+ file patterns)
-- 19 lint rules organized into 7 categories with defined severities
+- 21 lint rules organized into 9 categories with defined severities
 - A machine-readable rule and format catalog ([`context-lint-rules.json`](./context-lint-rules.json))
 - Auto-fix definitions for rules that support automated correction
 - Frontmatter schema requirements per client
@@ -45,6 +45,8 @@ The specification includes:
   - [3.5 redundancy — inferable content](#35-redundancy--inferable-content)
   - [3.6 contradictions — cross-file conflicts](#36-contradictions--cross-file-conflicts)
   - [3.7 frontmatter — client metadata validation](#37-frontmatter--client-metadata-validation)
+  - [3.8 ci-coverage — CI workflow documentation](#38-ci-coverage--ci-workflow-documentation)
+  - [3.9 ci-secrets — CI secrets documentation](#39-ci-secrets--ci-secrets-documentation)
 - [4. Rule Catalog (machine-readable)](#4-rule-catalog-machine-readable)
 - [5. Implementing This Specification](#5-implementing-this-specification)
 - [6. Contributing](#6-contributing)
@@ -298,7 +300,7 @@ Context files consume an agent's context window. Counting tokens helps teams und
 
 ## 3. Lint Rules
 
-19 rules organized into 7 categories.
+21 rules organized into 9 categories.
 
 Severity levels:
 - **error** — the context file has a verifiably incorrect reference or invalid metadata. Should fail CI.
@@ -537,6 +539,43 @@ Validates YAML frontmatter required by specific clients. Only applies to file fo
 
 ---
 
+### 3.8 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.
+
+| Rule ID | Severity | Trigger | Message |
+|---|---|---|---|
+| `ci/no-release-docs` | info | `.github/workflows/` contains release/deploy/publish workflow(s) but no context file mentions the release process | `Release workflow(s) found but no context file documents the release process` |
+
+**Detection algorithm:**
+
+1. Check if `.github/workflows/` exists. If not, skip.
+2. Scan workflow filenames for release-related patterns: `release`, `deploy`, `publish`, `cd`.
+3. For workflows not matched by filename, read the YAML `name:` field and check for the same patterns.
+4. If no release-related workflows exist, skip (only CI/test workflows — no documentation gap).
+5. Search all context file content for release documentation phrases (e.g., "release process", "push a v* tag", "npm publish", "deploy to").
+6. If no context file mentions release processes, emit one info-level issue.
+
+---
+
+### 3.9 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.
+
+| Rule ID | Severity | Trigger | Message |
+|---|---|---|---|
+| `ci/undocumented-secret` | info | `${{ secrets.NAME }}` found in workflow YAML but `NAME` not mentioned in any context file | `CI secret "{name}" is used in {workflow} but not mentioned in any context file` |
+
+**Detection algorithm:**
+
+1. Check if `.github/workflows/` exists. If not, skip.
+2. Read all `.yml`/`.yaml` files and extract `${{ secrets.NAME }}` references via regex.
+3. Exclude GitHub-provided secrets: `GITHUB_TOKEN`, `ACTIONS_RUNTIME_TOKEN`, `ACTIONS_RUNTIME_URL`, `ACTIONS_CACHE_URL`, `ACTIONS_ID_TOKEN_REQUEST_TOKEN`, `ACTIONS_ID_TOKEN_REQUEST_URL`, `ACTIONS_RESULTS_URL`.
+4. For each remaining secret, search all context files for the secret name (case-insensitive, flexible underscore/space matching).
+5. Emit one info-level issue per undocumented secret.
+
+---
+
 ## 4. Rule Catalog (machine-readable)
 
 A machine-readable JSON catalog of all rules and supported context file formats is available at [`context-lint-rules.json`](./context-lint-rules.json).
@@ -572,7 +611,7 @@ For each discovered file:
 
 Run per-file checks (paths, commands, staleness, tokens, redundancy, frontmatter) independently per file. These can be parallelized.
 
-Run cross-file checks (aggregate tokens, duplicate content, contradictions) after all per-file parsing is complete. These need the full set of parsed files.
+Run cross-file checks (aggregate tokens, duplicate content, contradictions, ci-coverage, ci-secrets) after all per-file parsing is complete. These need the full set of parsed files.
 
 ### Reporting
 

package/README.md

@@ -12,15 +12,23 @@ Your `CLAUDE.md` is lying to your agent. Your `.mcp.json` has a hardcoded API ke
 
 ## Why ctxlint?
 
-Context files rot fast. You rename a file, change a build script, or switch from Jest to Vitest — and your `CLAUDE.md` still says the old thing. Your agent follows those instructions faithfully, then fails.
+Every AI coding tool ships a context file: `CLAUDE.md`, `.cursorrules`, `AGENTS.md`, `.mcp.json`. These files are the single most important interface between you and your agent — they tell it what to build, how to test, where things live.
 
+But context files rot fast. You rename a file, change a build script, or switch from Jest to Vitest — and your `CLAUDE.md` still says the old thing. Your agent follows those stale instructions faithfully, then fails. You lose 10 minutes debugging what turns out to be a wrong path in line 12 of a markdown file.
+
+Multiply that across a team with 5 context files, 3 MCP configs, and 2 people who touched the build system last week — and you have a real problem with no existing solution.
+
+ctxlint is a linter purpose-built for this. It reads your context files, cross-references them against your actual codebase, and catches the drift before your agent does.
+
+- **Instant startup** — ships as a single self-contained bundle with zero runtime dependencies. `npx` downloads ~200 KB and starts immediately
 - **Catches real problems** — broken paths, wrong commands, stale references, contradictions across files
 - **Smart suggestions** — detects git renames and fuzzy-matches to suggest the right path
 - **Auto-fix** — `--fix` rewrites broken paths automatically using git history
 - **Token-aware** — shows how much context window your files consume and flags redundant content
 - **Every AI tool** — supports Claude Code, Cursor, Copilot, Windsurf, Gemini, Cline, Aider, and 14 more
 - **Multiple outputs** — text, JSON, and SARIF (GitHub Code Scanning)
-- **MCP server** — 5 tools for IDE/agent integration with tool annotations for auto-approval
+- **MCP server** — 6 tools for IDE/agent integration with tool annotations for auto-approval
+- **Watch mode** — `--watch` re-lints automatically when context files change
 
 ## Install
 
@@ -67,6 +75,8 @@ Useful if you want `ctxlint` available in every project without per-project setu
 | **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 |
 
 ## Supported Context Files
 
@@ -161,7 +171,7 @@ The full specification for MCP config linting rules, the cross-client config lan
 ## Example Output
 
 ```
-ctxlint v0.6.0
+ctxlint v0.7.0
 
 Scanning /Users/you/my-app...
 
@@ -205,6 +215,7 @@ Options:
   --mcp-only           Run only MCP config checks, skip context file checks
   --mcp-global         Also scan user/global MCP config files (implies --mcp)
   --mcp-server         Start the MCP server (for IDE/agent integration)
+  --watch              Re-lint on context file changes
   -V, --version        Output the version number
   -h, --help           Display help
 
@@ -212,10 +223,18 @@ Commands:
   init                 Set up a git pre-commit hook
 ```
 
-**Available checks:** `paths`, `commands`, `staleness`, `tokens`, `redundancy`, `contradictions`, `frontmatter`, `mcp-schema`, `mcp-security`, `mcp-commands`, `mcp-deprecated`, `mcp-env`, `mcp-urls`, `mcp-consistency`, `mcp-redundancy`
+**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`
 
 Passing any `mcp-*` check name implies `--mcp`.
 
+## Watch Mode
+
+```bash
+npx @yawlabs/ctxlint --watch
+```
+
+Re-lints automatically when any context file, MCP config, or `package.json` changes. Useful during development when you're editing context files alongside code.
+
 ## Use in CI
 
 ```yaml
@@ -225,6 +244,22 @@ Passing any `mcp-*` check name implies `--mcp`.
 
 Exits with code 1 if any errors or warnings are found.
 
+### GitHub Action
+
+```yaml
+- name: Lint context files
+  uses: yawlabs/ctxlint-action@v1
+```
+
+Or with options:
+
+```yaml
+- name: Lint context files
+  uses: yawlabs/ctxlint-action@v1
+  with:
+    args: '--strict --mcp'
+```
+
 ### SARIF Output (GitHub Code Scanning)
 
 ```yaml
@@ -262,7 +297,7 @@ Add to your `.pre-commit-config.yaml`:
 ```yaml
 repos:
   - repo: https://github.com/yawlabs/ctxlint
-    rev: v0.6.0
+    rev: v0.7.0
     hooks:
       - id: ctxlint
 ```

package/action.yml

@@ -0,0 +1,27 @@
+name: 'ctxlint'
+description: 'Lint AI agent context files and MCP server configs against your actual codebase'
+branding:
+  icon: 'check-circle'
+  color: 'blue'
+
+inputs:
+  args:
+    description: 'CLI arguments to pass to ctxlint (default: --strict)'
+    required: false
+    default: '--strict'
+  version:
+    description: 'ctxlint version to use (default: latest)'
+    required: false
+    default: 'latest'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+
+    - name: Run ctxlint
+      shell: bash
+      run: npx -y @yawlabs/ctxlint@${{ inputs.version }} ${{ inputs.args }}

package/agent-session-lint-rules.json

@@ -68,6 +68,24 @@
       "trigger": "Two memory files from different projects have >60% line overlap.",
       "message": "\"{file1}\" and \"{file2}\" have {overlap}% content overlap",
       "fixable": false
+    },
+    {
+      "id": "session/consecutive-repeat",
+      "category": "session",
+      "severity": "warning",
+      "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
+    },
+    {
+      "id": "session/cyclic-pattern",
+      "category": "session",
+      "severity": "warning",
+      "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
     }
   ],
   "dataSources": [

package/context-lint-rules.json

@@ -46,6 +46,18 @@
       "name": "Client Metadata Validation",
       "description": "Validates YAML frontmatter required by specific AI coding clients.",
       "scope": "per-file"
+    },
+    {
+      "id": "ci-coverage",
+      "name": "CI Workflow Documentation",
+      "description": "Checks that release/deploy CI workflows are documented in context files.",
+      "scope": "cross-file"
+    },
+    {
+      "id": "ci-secrets",
+      "name": "CI Secrets Documentation",
+      "description": "Checks that CI secrets used in workflows are documented in context files.",
+      "scope": "cross-file"
     }
   ],
   "rules": [
@@ -269,6 +281,24 @@
       "message": "No activation field — rule may not be applied automatically",
       "fixable": false,
       "appliesTo": ["cursor-mdc"]
+    },
+    {
+      "id": "ci/no-release-docs",
+      "category": "ci-coverage",
+      "severity": "info",
+      "description": "Release/deploy CI workflow exists but no context file documents the process.",
+      "trigger": ".github/workflows/ contains release/deploy/publish workflow but no context file mentions the release process.",
+      "message": "Release workflow found but no context file documents the release process",
+      "fixable": false
+    },
+    {
+      "id": "ci/undocumented-secret",
+      "category": "ci-secrets",
+      "severity": "info",
+      "description": "CI workflow references a secret not mentioned in any context file.",
+      "trigger": "${{ secrets.NAME }} found in workflow YAML but NAME not mentioned in any context file. GitHub-provided secrets (GITHUB_TOKEN, etc.) are excluded.",
+      "message": "CI secret \"{name}\" is used in {workflow} but not mentioned in any context file",
+      "fixable": false
     }
   ],
   "formats": [