@yawlabs/ctxlint 0.8.0 → 0.9.0

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

@@ -75,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
 
@@ -221,7 +223,7 @@ 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`.
 

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": [