@yawlabs/ctxlint 0.6.0 → 0.8.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

@@ -0,0 +1,366 @@
+# Agent Session Data Linting Specification
+
+**Version:** 1.0.0-draft
+**Date:** 2026-04-08
+**Maintained by:** [Yaw Labs](https://yaw.sh) / [ctxlint](https://github.com/YawLabs/ctxlint)
+**License:** CC BY 4.0
+
+---
+
+## What is this?
+
+AI coding agents persist session data -- command history, memory files, learned preferences -- across projects. When a developer runs the same agent across multiple repositories, these files accumulate state that shapes future behavior. Secrets get set in some repos but not others. Config files drift apart. Memory entries go stale or duplicate across projects.
+
+This specification defines a standard set of lint rules for validating agent session data for cross-project consistency. It does NOT define agent session formats (those are owned by each agent vendor). Instead, it defines what to CHECK across the session data that already exists.
+
+The specification includes:
+- A reference of session data locations across 8 AI coding agents
+- 5 lint rules in the `session` category with defined severities
+- A machine-readable rule catalog ([`agent-session-lint-rules.json`](./agent-session-lint-rules.json))
+- Sibling-repo detection for cross-project checks
+
+This is the third pillar alongside context file linting (`CLAUDE.md`, `.cursorrules`) and MCP config linting (`.mcp.json`). Together they cover everything that shapes what an AI agent knows and can do:
+
+| Pillar | What it checks | Specification |
+|---|---|---|
+| Context files | Instructions the agent reads | [CONTEXT_LINT_SPEC.md](./CONTEXT_LINT_SPEC.md) |
+| MCP configs | Tools the agent can use | [MCP_CONFIG_LINT_SPEC.md](./MCP_CONFIG_LINT_SPEC.md) |
+| Session data | History and memory the agent carries | This document |
+
+**Reference implementation:** [ctxlint](https://github.com/YawLabs/ctxlint) (v0.7.0+)
+
+---
+
+## Table of contents
+
+- [1. Agent Session Data Landscape Reference](#1-agent-session-data-landscape-reference)
+  - [1.1 What is agent session data?](#11-what-is-agent-session-data)
+  - [1.2 Data sources by agent](#12-data-sources-by-agent)
+  - [1.3 Scan targets](#13-scan-targets)
+  - [1.4 Sibling detection](#14-sibling-detection)
+- [2. Lint Rules](#2-lint-rules)
+  - [2.1 session/missing-secret](#21-sessionmissing-secret)
+  - [2.2 session/diverged-file](#22-sessiondiverged-file)
+  - [2.3 session/missing-workflow](#23-sessionmissing-workflow)
+  - [2.4 session/stale-memory](#24-sessionstale-memory)
+  - [2.5 session/duplicate-memory](#25-sessionduplicate-memory)
+- [3. Rule Catalog (machine-readable)](#3-rule-catalog-machine-readable)
+- [4. Implementing This Specification](#4-implementing-this-specification)
+- [5. Contributing](#5-contributing)
+
+---
+
+## 1. Agent Session Data Landscape Reference
+
+### 1.1 What is agent session data?
+
+Agent session data is persistent state that carries across conversations. Unlike context files (which are authored by developers) and MCP configs (which are authored once and committed), session data is generated by the agent itself during use. It includes:
+
+- **History files** -- a log of commands the agent executed, prompts it received, or actions it took. Typically appended per-conversation.
+- **Memory files** -- notes the agent writes to itself about the project: conventions it learned, decisions it recorded, file paths it considers important.
+- **Session transcripts** -- full conversation logs including all messages, tool calls, and responses. These can be very large (hundreds of megabytes for active projects).
+- **Learned preferences** -- implicit or explicit settings derived from user behavior: preferred tools, naming conventions, workflow patterns.
+
+This data is usually stored in the user's home directory, not in the project repository. It is rarely version-controlled and is often in undocumented or unstable formats.
+
+### 1.2 Data sources by agent
+
+| Agent | Provider | History Location | Format | Memory / Preferences |
+|---|---|---|---|---|
+| Claude Code | Anthropic | `~/.claude/history.jsonl` | JSONL | `~/.claude/projects/*/memory/*.md` (Markdown with YAML frontmatter) |
+| Codex CLI | OpenAI | `~/.codex/history.jsonl` | JSONL | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` |
+| Aider | Paul Gauthier | `.aider.chat.history.md` (per-project) | Markdown | `.aider.input.history` (per-project, readline format) |
+| Vibe CLI | Mistral | `~/.vibe/sessions/*/messages.jsonl` | JSONL | `~/.vibe/sessions/*/meta.json` |
+| Amazon Q | AWS | `~/.aws/amazonq/history/chat-history-*.json` | JSON | Keyed by workspace path hash |
+| Goose | Block | `~/.local/share/goose/sessions/sessions.db` (Linux/macOS), `%APPDATA%\Block\goose\data\sessions\` (Windows) | SQLite | Schema v9, versioned migrations |
+| Continue.dev | Continue | `~/.continue/sessions/*.json` | JSON | `~/.continue/dev_data/*.jsonl` |
+| Windsurf | Codeium | `~/.windsurf/transcripts/*.jsonl` | JSONL | `~/.codeium/windsurf/cascade/` |
+
+**Platform notes:**
+- On Windows, `~` refers to `%USERPROFILE%` (typically `C:\Users\<name>`).
+- Goose uses platform-specific paths: XDG on Linux, `~/Library/Application Support/` on macOS, `%APPDATA%` on Windows.
+- Aider stores history in the project directory itself, not in the user's home directory. These files are typically gitignored.
+
+**Format stability:**
+- Claude Code's JSONL history and Markdown memory files are the most stable and well-documented formats.
+- Codex CLI's JSONL format is documented via OpenAI's CLI docs.
+- Goose uses SQLite with versioned schema migrations (v9 as of April 2026), making the format stable but requiring a SQLite dependency to read.
+- Amazon Q, Vibe CLI, Windsurf, and Continue.dev formats are largely undocumented and may change without notice.
+
+### 1.3 Scan targets
+
+Session data varies enormously in size and format. This specification targets only lightweight, high-signal data sources for scanning.
+
+**What we scan:**
+
+- **History files** -- command logs in JSONL or Markdown format. Typically under 2 MB per project. Parsed line-by-line for specific patterns (e.g., `gh secret set` commands).
+- **Memory files** -- small Markdown files, typically under 1 MB total per project. Parsed for path references and content overlap.
+- **Sibling repo filesystem** -- file existence checks and file content reads for cross-project comparisons (diverged configs, missing workflows). No deep scanning.
+
+**What we explicitly DO NOT scan:**
+
+- **Full session transcripts** -- too large. Active projects can accumulate hundreds of megabytes of transcript data. Scanning these would be slow and yield low-signal results.
+- **SQLite databases** -- Goose's `sessions.db` requires a SQLite dependency. Out of scope for v1. Future versions may add opt-in SQLite support.
+- **File history or shell snapshots** -- some agents capture filesystem state or shell output. These are agent-internal data and not useful for cross-project linting.
+
+### 1.4 Sibling detection
+
+Several rules in this specification compare the current project against "sibling" repositories -- other projects by the same developer or team. Sibling detection determines which repos to compare against.
+
+**Default strategy:** scan the parent directory of the current project. Filter to directories that contain at least one project indicator file:
+
+- `.git`
+- `package.json`
+- `Cargo.toml`
+- `go.mod`
+- `pyproject.toml`
+
+Skip hidden directories (starting with `.`) and `node_modules`.
+
+**Overflow strategy:** if the parent directory contains more than 50 candidate projects, narrow the set by parsing `git remote get-url origin` in each candidate and filtering to repositories in the same GitHub organization or user namespace. This prevents false positives in shared development directories (e.g., `~/src/` containing forks from dozens of orgs).
+
+**Configuration:** implementors should allow users to override sibling detection with an explicit list of paths if the default heuristics don't match their workspace layout.
+
+---
+
+## 2. Lint Rules
+
+5 rules in 1 category (`session`). All rules in this category perform cross-project checks using sibling detection.
+
+Severity levels:
+- **error** -- the session data reveals a verifiably missing configuration. Should fail CI.
+- **warning** -- the session data reveals likely drift worth investigating. May fail CI in strict mode.
+- **info** -- the session data reveals a potential improvement. Never fails CI.
+
+### 2.1 session/missing-secret
+
+Detects GitHub secrets that have been set on sibling repositories but not the current project.
+
+| Field | Value |
+|---|---|
+| **Rule ID** | `session/missing-secret` |
+| **Severity** | error |
+| **Trigger** | `gh secret set <NAME>` found in agent history for 2+ sibling repos but not the current project |
+| **Message** | `GitHub secret "<name>" is set on <N> sibling repos (<names>) but not on this project` |
+
+**Detection algorithm:**
+
+1. Parse agent history files (JSONL) line-by-line.
+2. Match entries against the pattern: `gh secret set <SECRET_NAME>` (with optional flags like `--repo`, `--body`, `--env`).
+3. Group matches by secret name and the project path the history entry is associated with.
+4. For each secret name, check if it was set on 2+ sibling repos but not on the current project.
+5. Flag each missing secret as an error.
+
+**Example scenario:** A developer uses Claude Code across three repos. They ran `gh secret set NPM_TOKEN` in `lib-a` and `lib-b` but forgot `lib-c`. When linting `lib-c`, this rule flags the missing `NPM_TOKEN`.
+
+### 2.2 session/diverged-file
+
+Detects canonical configuration files that have drifted between the current project and its siblings.
+
+| Field | Value |
+|---|---|
+| **Rule ID** | `session/diverged-file` |
+| **Severity** | warning |
+| **Trigger** | A canonical file exists in both the current project and 1+ siblings, and line-level overlap is 20-90% |
+| **Message** | `<file> has diverged from sibling repos: <sibling> (<N>% overlap)` |
+
+**Canonical files:**
+
+| File path | Purpose |
+|---|---|
+| `release.sh` | Release automation script |
+| `.github/workflows/ci.yml` | CI pipeline |
+| `.github/workflows/release.yml` | Release pipeline |
+| `biome.json` | Biome linter config |
+| `.prettierrc` | Prettier config |
+| `.eslintrc.json` | ESLint config |
+| `tsconfig.json` | TypeScript config |
+| `.gitignore` | Git ignore rules |
+
+**Detection algorithm:**
+
+1. For each canonical file that exists in the current project, check if the same file exists in any sibling repo.
+2. For each pair, compute line-level overlap: the number of lines present in both files divided by the total number of unique lines across both files, expressed as a percentage.
+3. Classify the result:
+   - **Below 20%** -- intentionally different. No flag. The files serve different purposes despite the shared name.
+   - **20-90%** -- drift. Flag as warning. The files were likely once in sync and have diverged.
+   - **Above 90%** -- close enough. No flag. Minor differences are expected (e.g., different project names).
+
+**Notes:**
+- Blank lines and comment-only lines should be excluded from the overlap calculation.
+- Compare each sibling independently. Report the sibling with the lowest overlap percentage first.
+
+### 2.3 session/missing-workflow
+
+Detects GitHub Actions workflow files that exist across sibling repos but are absent from the current project.
+
+| Field | Value |
+|---|---|
+| **Rule ID** | `session/missing-workflow` |
+| **Severity** | warning |
+| **Trigger** | A GitHub Actions workflow file exists in 2+ sibling repos but not in the current project (which has a `.github` directory) |
+| **Message** | `GitHub Actions workflow "<file>" exists in <N> sibling repos (<names>) but not in this project` |
+
+**Detection algorithm:**
+
+1. Check if the current project has a `.github` directory. If not, skip this rule entirely -- the project may not use GitHub Actions at all.
+2. Enumerate `.github/workflows/*.yml` and `.github/workflows/*.yaml` in all sibling repos.
+3. Group workflow filenames across siblings.
+4. For each filename that exists in 2+ siblings but not in the current project, flag it.
+
+**Notes:**
+- Match by filename only, not by content. A `ci.yml` in one repo may be very different from `ci.yml` in another, but the absence of any CI workflow is still worth flagging.
+- Exclude workflow files that are clearly project-specific (e.g., containing the repo name in the filename). Implementors may use heuristics here.
+
+### 2.4 session/stale-memory
+
+Detects Claude Code memory entries that reference file paths which no longer exist in the project.
+
+| Field | Value |
+|---|---|
+| **Rule ID** | `session/stale-memory` |
+| **Severity** | info |
+| **Trigger** | A memory file references file paths that no longer exist in the project |
+| **Message** | `Memory "<name>" references <N> path(s) that no longer exist: <paths>` |
+
+**Scope:** This rule only checks memory files for the current project. Claude Code stores per-project memories in `~/.claude/projects/<encoded-path>/memory/`, where `<encoded-path>` encodes the project's absolute path using `--` as the directory separator.
+
+**Detection algorithm:**
+
+1. Determine the current project's encoded path (see [Section 4](#4-implementing-this-specification) for encoding details).
+2. Read all `.md` files in the corresponding memory directory.
+3. Extract path references from each memory file using the same path extraction logic as context file linting (forward-slash-separated segments, relative paths, etc.).
+4. Check each extracted path against the project filesystem.
+5. Flag memory files that reference 1+ paths that no longer exist.
+
+**Notes:**
+- This rule is `info` severity because stale memories are low-risk -- they waste a small amount of context but don't cause incorrect behavior.
+- Implementors may suggest `claude memory remove` or manual deletion as a fix.
+
+### 2.5 session/duplicate-memory
+
+Detects memory entries from different projects that have significant content overlap.
+
+| Field | Value |
+|---|---|
+| **Rule ID** | `session/duplicate-memory` |
+| **Severity** | info |
+| **Trigger** | Two memory entries from different projects have >60% line overlap |
+| **Message** | `Memory "<nameA>" (<projA>) and "<nameB>" (<projB>) have <N>% overlap` |
+
+**Detection algorithm:**
+
+1. Enumerate all memory files across all projects in `~/.claude/projects/*/memory/*.md`.
+2. Exclude `MEMORY.md` index files (these are auto-generated summaries, not authored memories).
+3. Exclude very short entries (fewer than 50 characters after stripping whitespace) -- too short for meaningful overlap comparison.
+4. Perform pairwise comparison of all remaining memory entries. Skip pairs from the same project.
+5. Compute line-level overlap percentage (same algorithm as `session/diverged-file`).
+6. Flag pairs with >60% overlap.
+
+**Notes:**
+- This rule helps identify boilerplate that has been memorized per-project instead of being placed in a shared context file or user-level config.
+- A common pattern is the same coding conventions memorized independently in 5+ projects. Consolidating to a user-level `CLAUDE.md` or `.claude/settings.json` would be more efficient.
+
+---
+
+## 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).
+
+The catalog schema follows the same structure as the sibling specs' catalogs (`context-lint-rules.json`, `mcp-config-lint-rules.json`). Each rule entry includes:
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | string | Rule ID in `category/rule-name` format |
+| `severity` | `"error"` \| `"warning"` \| `"info"` | Default severity level |
+| `description` | string | One-line description of what the rule checks |
+| `messageTemplate` | string | Message template with `<placeholder>` variables |
+| `category` | string | Rule category (`session`) |
+| `crossProject` | boolean | Whether the rule compares across sibling repos |
+
+See the JSON file for the full catalog.
+
+---
+
+## 4. Implementing This Specification
+
+### Opt-in activation
+
+Session checks are opt-in. Implementors should require an explicit flag (e.g., `--session`) to enable these rules. Rationale:
+
+- Session data lives outside the project directory and may contain sensitive information.
+- Cross-project checks require filesystem access to sibling repos, which is slower than single-project linting.
+- Users should consciously opt into scanning their agent history and memory files.
+
+### Path handling
+
+Sibling detection and history file scanning must handle both Windows and Unix paths correctly.
+
+- Use `path.resolve()` or equivalent to normalize paths before comparison.
+- On Windows, handle both `\` and `/` as separators.
+- Environment variable expansion (`%USERPROFILE%`, `$HOME`, `~`) should work on both platforms.
+
+### History file parsing
+
+Agent history files (JSONL) should be parsed line-by-line using streaming reads. Do not load entire files into memory -- active developers may have history files in the tens of megabytes.
+
+For each line:
+1. Parse as JSON.
+2. Extract the command/action string.
+3. Match against rule-specific patterns (e.g., `gh secret set` regex).
+4. Track the associated project path for cross-project grouping.
+
+### Claude Code project directory encoding
+
+Claude Code encodes project paths in its directory structure using `--` as the path separator. The encoding replaces each directory separator with `--` and strips the leading separator.
+
+**Examples:**
+
+| Actual path | Encoded directory name |
+|---|---|
+| `C:/Users/jeff/yaw/ctxlint` | `C--Users-jeff-yaw-ctxlint` |
+| `/home/dev/projects/my-app` | `-home-dev-projects-my-app` |
+| `/Users/dev/work/api-server` | `-Users-dev-work-api-server` |
+
+Note: each `/` or `\` in the path becomes a single `-` in the encoded name, except when the path component itself contains a hyphen (which is preserved). The `--` separator replaces `:/` on Windows drive letters.
+
+To decode: implementors should reverse the encoding by reading the actual directory names from `~/.claude/projects/` and matching against the current project's absolute path.
+
+### Scope of v1
+
+The v1 specification focuses on:
+
+- **Claude Code and Codex CLI** for history file scanning -- these have well-documented, stable JSONL formats.
+- **Filesystem-based checks** (`session/diverged-file`, `session/missing-workflow`) that work for all agents because they scan the project filesystem, not agent-specific data.
+- **Claude Code** for memory file checks (`session/stale-memory`, `session/duplicate-memory`) -- the only agent with a well-documented, file-based memory system.
+
+Future versions may add support for:
+- Goose SQLite session parsing (requires bundling or requiring SQLite).
+- Aider per-project history parsing.
+- Additional memory/preference formats as agents stabilize their storage.
+
+---
+
+## 5. Contributing
+
+This specification is maintained at [github.com/YawLabs/ctxlint](https://github.com/YawLabs/ctxlint).
+
+To propose changes:
+- **New rules:** Open an issue describing the rule, its severity, trigger condition, and which agents it applies to.
+- **Agent additions:** As new AI coding agents emerge or existing agents change their session data formats, submit a PR updating the data sources table in Section 1.2.
+- **Corrections:** If any agent behavior or file location documented here is inaccurate, open an issue with evidence (agent docs, source code, or reproduction steps).
+
+### Versioning
+
+This specification follows semver:
+- **Patch** (1.0.x): Typo fixes, clarifications, no rule changes
+- **Minor** (1.x.0): New rules added, new agents documented, new canonical files for diverged-file checks
+- **Major** (x.0.0): Rules removed or semantics changed in breaking ways
+
+### Related specifications and tools
+
+- [AI Context File Linting Specification](./CONTEXT_LINT_SPEC.md) -- context file lint rules (the first pillar)
+- [MCP Server Configuration Linting Specification](./MCP_CONFIG_LINT_SPEC.md) -- MCP config lint rules (the second pillar)
+- [ctxlint](https://github.com/YawLabs/ctxlint) -- reference implementation of all three specifications
+- [mcp-compliance](https://github.com/YawLabs/mcp-compliance) -- tests MCP server behavior against the protocol spec
+- [mcp.hosting](https://mcp.hosting) -- managed MCP server hosting

package/README.md

@@ -4,6 +4,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![GitHub stars](https://img.shields.io/github/stars/YawLabs/ctxlint)](https://github.com/YawLabs/ctxlint/stargazers)
 [![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.
 
@@ -11,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
 
@@ -160,7 +169,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...
 
@@ -204,6 +213,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
 
@@ -215,6 +225,14 @@ Commands:
 
 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
@@ -224,6 +242,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
@@ -261,7 +295,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

@@ -0,0 +1,157 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "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
+    },
+    {
+      "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"
+      ]
+    },
+    {
+      "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
+    },
+    {
+      "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
+    },
+    {
+      "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.",
+      "message": "\"{file1}\" and \"{file2}\" have {overlap}% content overlap",
+      "fixable": false
+    }
+  ],
+  "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"
+  ]
+}