@yawlabs/ctxlint 0.18.7 → 0.19.0

package/CONTEXT_LINT_SPEC.md

@@ -672,6 +672,17 @@ The catalog enables:
 
 See the JSON file for the full schema.
 
+### Catalog rule IDs vs. reference-implementation ruleIds
+
+For all but two rules the catalog ID and the emitted `ruleId` are identical. The `ci` rules are the exception: their catalog IDs use a pillar-stable `ci/<slug>` form -- these are the cross-tool names to use in documentation, configuration, and issue reports -- while the reference implementation namespaces the `ruleId` it emits (in `--format json` output) by check module. The full correspondence (pinned by a consistency test in the reference implementation):
+
+| Catalog rule ID | Emitted `ruleId` (reference implementation) |
+|---|---|
+| `ci/no-release-docs` | `ci-coverage/no-release-docs` |
+| `ci/undocumented-secret` | `ci-secrets/undocumented-secret` |
+
+Other implementations of this specification may emit either form; when interoperating, treat the catalog IDs as canonical and map implementation-specific ruleIds onto them as above. The same two-level arrangement is documented for the session pillar in [`AGENT_SESSION_LINT_SPEC.md`](./AGENT_SESSION_LINT_SPEC.md) section 3.
+
 ---
 
 ## 5. Implementing This Specification

package/README.md

@@ -513,7 +513,7 @@ ctxlint is the reference implementation of four open specifications for linting
 | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **[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.          |
 | **[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)** | 8 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)** | 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 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

@@ -1,193 +1,223 @@
-{
-  "$schema": "https://raw.githubusercontent.com/YawLabs/ctxlint/main/schemas/ctxlint-catalog.schema.json",
-  "title": "AI Agent Session Lint Rules",
-  "description": "Machine-readable catalog of lint rules for AI agent session data cross-project consistency",
-  "specVersion": "1.0.0-draft",
-  "specDate": "2026-04-08",
-  "repository": "https://github.com/YawLabs/ctxlint",
-  "categories": [
-    {
-      "id": "session",
-      "name": "Session Audit",
-      "description": "Cross-project consistency checks using AI agent session data.",
-      "scope": "cross-project"
-    }
-  ],
-  "rules": [
-    {
-      "id": "session/missing-secret",
-      "category": "session",
-      "severity": "error",
-      "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,
-      "stability": "stable"
-    },
-    {
-      "id": "session/diverged-file",
-      "category": "session",
-      "severity": "warning",
-      "description": "Canonical file has diverged from sibling repos.",
-      "trigger": "File exists in current project and siblings with 20-90% line overlap.",
-      "message": "\"{file}\" has {overlap}% overlap with {sibling} — may have diverged",
-      "fixable": false,
-      "canonicalFiles": [
-        "release.sh",
-        ".github/workflows/ci.yml",
-        ".github/workflows/release.yml",
-        "biome.json",
-        ".prettierrc",
-        ".eslintrc.json",
-        "tsconfig.json",
-        ".gitignore"
-      ],
-      "stability": "stable"
-    },
-    {
-      "id": "session/missing-workflow",
-      "category": "session",
-      "severity": "warning",
-      "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,
-      "stability": "stable"
-    },
-    {
-      "id": "session/stale-memory",
-      "category": "session",
-      "severity": "info",
-      "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,
-      "stability": "stable"
-    },
-    {
-      "id": "session/duplicate-memory",
-      "category": "session",
-      "severity": "info",
-      "description": "Near-duplicate memory entries across projects.",
-      "trigger": "Two memory files from different projects have >60% line overlap, and at least one of the pair belongs to the current project (otherwise every lint run from any repo would resurface the same unrelated cross-project duplicates).",
-      "message": "\"{file1}\" and \"{file2}\" have {overlap}% content overlap",
-      "fixable": false,
-      "stability": "stable"
-    },
-    {
-      "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 (entries lacking a project path or timestamp are excluded), grouped into sessions (by provider + session ID, split at >30-minute timestamp gaps), shows the same display string 3+ times in a row within a single session segment. Single-command sessions are additionally merged per provider into one stream (split at the same gaps) so rapid one-shot respawn loops are caught.",
-      "message": "Command run {count} times consecutively: \"{command}\"",
-      "fixable": false,
-      "stability": "experimental"
-    },
-    {
-      "id": "session/cyclic-pattern",
-      "category": "session",
-      "severity": "warning",
-      "description": "Cyclic command pattern detected in agent history.",
-      "trigger": "Within a single session segment (same provider + session ID, split at >30-minute gaps; entries lacking a project path or timestamp are excluded), agent history shows a repeating sequence of 2-3 commands (e.g. A,B,A,B) repeated 2+ times. Spans already reported by session/consecutive-repeat are not re-reported. The merged one-shot stream is not scanned for cycles.",
-      "message": "Cyclic pattern repeated {count} times: {cycle}",
-      "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": [
-    {
-      "id": "claude-code",
-      "name": "Claude Code",
-      "provider": "Anthropic",
-      "historyLocation": "~/.claude/history.jsonl",
-      "historyFormat": "JSONL",
-      "memoryLocation": "~/.claude/projects/*/memory/*.md",
-      "documented": true
-    },
-    {
-      "id": "codex-cli",
-      "name": "Codex CLI",
-      "provider": "OpenAI",
-      "historyLocation": "~/.codex/history.jsonl",
-      "historyFormat": "JSONL",
-      "sessionsLocation": "~/.codex/sessions/**/*.jsonl",
-      "documented": true
-    },
-    {
-      "id": "aider",
-      "name": "Aider",
-      "provider": "Paul Gauthier",
-      "historyLocation": ".aider.chat.history.md",
-      "historyFormat": "Markdown",
-      "documented": true,
-      "notes": "History file is per-project, stored in the project root."
-    },
-    {
-      "id": "vibe-cli",
-      "name": "Vibe CLI",
-      "provider": "Mistral",
-      "historyLocation": "~/.vibe/sessions/*/messages.jsonl",
-      "historyFormat": "JSONL",
-      "documented": false,
-      "notes": "Partially documented."
-    },
-    {
-      "id": "amazon-q",
-      "name": "Amazon Q Developer",
-      "provider": "AWS",
-      "historyLocation": "~/.aws/amazonq/history/chat-history-*.json",
-      "historyFormat": "JSON",
-      "documented": false,
-      "notes": "Semi-documented; file layout inferred from observation."
-    },
-    {
-      "id": "goose",
-      "name": "Goose",
-      "provider": "Block",
-      "historyLocation": "~/.local/share/goose/sessions/sessions.db",
-      "historyFormat": "SQLite",
-      "documented": true,
-      "notes": "Requires SQLite dependency to read session data."
-    },
-    {
-      "id": "continue",
-      "name": "Continue",
-      "provider": "Continue.dev",
-      "historyLocation": "~/.continue/sessions/*.json",
-      "historyFormat": "JSON",
-      "documented": false,
-      "notes": "Partially documented."
-    },
-    {
-      "id": "windsurf",
-      "name": "Windsurf",
-      "provider": "Codeium",
-      "historyLocation": "~/.windsurf/transcripts/*.jsonl",
-      "historyFormat": "JSONL",
-      "documented": false,
-      "notes": "Partially documented; format marked unstable by vendor."
-    }
-  ],
-  "agents": [
-    "claude-code",
-    "codex-cli",
-    "aider",
-    "vibe-cli",
-    "amazon-q",
-    "goose",
-    "continue",
-    "windsurf"
-  ]
-}
+{
+  "$schema": "https://raw.githubusercontent.com/YawLabs/ctxlint/main/schemas/ctxlint-catalog.schema.json",
+  "title": "AI Agent Session Lint Rules",
+  "description": "Machine-readable catalog of lint rules for AI agent session data cross-project consistency",
+  "specVersion": "1.0.0-draft",
+  "specDate": "2026-04-08",
+  "repository": "https://github.com/YawLabs/ctxlint",
+  "categories": [
+    {
+      "id": "session",
+      "name": "Session Audit",
+      "description": "Cross-project consistency checks using AI agent session data.",
+      "scope": "cross-project"
+    }
+  ],
+  "rules": [
+    {
+      "id": "session/missing-secret",
+      "category": "session",
+      "severity": "error",
+      "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,
+      "stability": "stable"
+    },
+    {
+      "id": "session/diverged-file",
+      "category": "session",
+      "severity": "warning",
+      "description": "Canonical file has diverged from sibling repos.",
+      "trigger": "File exists in current project and siblings with 20-90% line overlap.",
+      "message": "\"{file}\" has {overlap}% overlap with {sibling} — may have diverged",
+      "fixable": false,
+      "canonicalFiles": [
+        "release.sh",
+        ".github/workflows/ci.yml",
+        ".github/workflows/release.yml",
+        "biome.json",
+        ".prettierrc",
+        ".eslintrc.json",
+        "tsconfig.json",
+        ".gitignore"
+      ],
+      "stability": "stable"
+    },
+    {
+      "id": "session/missing-workflow",
+      "category": "session",
+      "severity": "warning",
+      "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,
+      "stability": "stable"
+    },
+    {
+      "id": "session/stale-memory",
+      "category": "session",
+      "severity": "info",
+      "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,
+      "stability": "stable"
+    },
+    {
+      "id": "session/duplicate-memory",
+      "category": "session",
+      "severity": "info",
+      "description": "Near-duplicate memory entries across projects.",
+      "trigger": "Two memory files from different projects have >60% line overlap, and at least one of the pair belongs to the current project (otherwise every lint run from any repo would resurface the same unrelated cross-project duplicates).",
+      "message": "\"{file1}\" and \"{file2}\" have {overlap}% content overlap",
+      "fixable": false,
+      "stability": "stable"
+    },
+    {
+      "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 (entries lacking a project path or timestamp are excluded), grouped into sessions (by provider + session ID, split at >30-minute timestamp gaps), shows the same display string 3+ times in a row within a single session segment. Single-command sessions are additionally merged per provider into one stream (split at the same gaps) so rapid one-shot respawn loops are caught.",
+      "message": "Command run {count} times consecutively: \"{command}\"",
+      "fixable": false,
+      "stability": "experimental"
+    },
+    {
+      "id": "session/cyclic-pattern",
+      "category": "session",
+      "severity": "warning",
+      "description": "Cyclic command pattern detected in agent history.",
+      "trigger": "Within a single session segment (same provider + session ID, split at >30-minute gaps; entries lacking a project path or timestamp are excluded), agent history shows a repeating sequence of 2-3 commands (e.g. A,B,A,B) repeated 2+ times. Spans already reported by session/consecutive-repeat are not re-reported. The merged one-shot stream is not scanned for cycles.",
+      "message": "Cyclic pattern repeated {count} times: {cycle}",
+      "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"
+    },
+    {
+      "id": "session/shared-temp-path",
+      "category": "session",
+      "severity": "error",
+      "description": "A fixed, non-session-scoped temp path is written and later read back.",
+      "trigger": "Agent history writes a literal path under /tmp, /var/tmp, $TMPDIR or %TEMP% with no per-run component, then reads the same path.",
+      "message": "Fixed temp path \"{path}\" is written and later read back",
+      "fixable": false,
+      "stability": "stable"
+    },
+    {
+      "id": "session/unverified-gate-claimed-clean",
+      "category": "session",
+      "severity": "warning",
+      "description": "A quality gate is asserted as passing while its invocation failed or produced no output.",
+      "trigger": "A lint/typecheck/test/build command errors or emits nothing, and nearby agent prose claims it passed.",
+      "message": "'{gate}' asserted as passing, but the invocation produced no output",
+      "fixable": false,
+      "stability": "stable"
+    },
+    {
+      "id": "session/default-branch-accumulation",
+      "category": "session",
+      "severity": "warning",
+      "description": "Many files edited on the default branch with no intervening commit.",
+      "trigger": "Ten or more distinct files written while on main/master without a commit or branch-away in between.",
+      "message": "{count} files edited on '{branch}' with no intervening commit",
+      "fixable": false,
+      "stability": "stable"
+    }
+  ],
+  "dataSources": [
+    {
+      "id": "claude-code",
+      "name": "Claude Code",
+      "provider": "Anthropic",
+      "historyLocation": "~/.claude/history.jsonl",
+      "historyFormat": "JSONL",
+      "memoryLocation": "~/.claude/projects/*/memory/*.md",
+      "documented": true
+    },
+    {
+      "id": "codex-cli",
+      "name": "Codex CLI",
+      "provider": "OpenAI",
+      "historyLocation": "~/.codex/history.jsonl",
+      "historyFormat": "JSONL",
+      "sessionsLocation": "~/.codex/sessions/**/*.jsonl",
+      "documented": true
+    },
+    {
+      "id": "aider",
+      "name": "Aider",
+      "provider": "Paul Gauthier",
+      "historyLocation": ".aider.chat.history.md",
+      "historyFormat": "Markdown",
+      "documented": true,
+      "notes": "History file is per-project, stored in the project root."
+    },
+    {
+      "id": "vibe-cli",
+      "name": "Vibe CLI",
+      "provider": "Mistral",
+      "historyLocation": "~/.vibe/sessions/*/messages.jsonl",
+      "historyFormat": "JSONL",
+      "documented": false,
+      "notes": "Partially documented."
+    },
+    {
+      "id": "amazon-q",
+      "name": "Amazon Q Developer",
+      "provider": "AWS",
+      "historyLocation": "~/.aws/amazonq/history/chat-history-*.json",
+      "historyFormat": "JSON",
+      "documented": false,
+      "notes": "Semi-documented; file layout inferred from observation."
+    },
+    {
+      "id": "goose",
+      "name": "Goose",
+      "provider": "Block",
+      "historyLocation": "~/.local/share/goose/sessions/sessions.db",
+      "historyFormat": "SQLite",
+      "documented": true,
+      "notes": "Requires SQLite dependency to read session data."
+    },
+    {
+      "id": "continue",
+      "name": "Continue",
+      "provider": "Continue.dev",
+      "historyLocation": "~/.continue/sessions/*.json",
+      "historyFormat": "JSON",
+      "documented": false,
+      "notes": "Partially documented."
+    },
+    {
+      "id": "windsurf",
+      "name": "Windsurf",
+      "provider": "Codeium",
+      "historyLocation": "~/.windsurf/transcripts/*.jsonl",
+      "historyFormat": "JSONL",
+      "documented": false,
+      "notes": "Partially documented; format marked unstable by vendor."
+    }
+  ],
+  "agents": [
+    "claude-code",
+    "codex-cli",
+    "aider",
+    "vibe-cli",
+    "amazon-q",
+    "goose",
+    "continue",
+    "windsurf"
+  ]
+}