cot-lint

cot-lint

English | 中文

Lint your repo for chain-of-thought leakage — the session-transcript residue AI assistants leave in docs, comments, and JSDoc.

Your coding agent writes great code and leaks its thinking everywhere around it:

- // This PR adds a retry loop (decision 7) so the diff stays reviewable.
- // The manager used to serialize writes itself; it no longer does after v1.
- // The cast is safe — it simply narrows the union. Probably fine for now.
+ // Retries transient provider failures up to 3 times with jittered backoff.
+ // The shared coordinator serializes writes per session.
+ // The cast narrows a union already validated at the loader boundary.

None of the left column is wrong about the code. It is wrong about its reader: it argues with a reviewer who has left, cites a design session nobody can open, and narrates a change instead of stating behavior.

The one test

Could a reader at HEAD — with no access to any session transcript, PR thread, or uncommitted draft — resolve every reference and verify every claim?

If no, that passage is chain-of-thought leakage. cot-lint finds it.

Quick start

DeepSeek Harness — install the cot-trim fixing skill as a plugin:

dsh plugin add cot-lint

Any repo or CI — zero dependencies, Node ≥ 20:

npx cot-lint                 # scan the repo (Markdown and prose files)
npx cot-lint --json          # machine-readable findings for CI or agents
npx cot-lint --ext ts,py     # also scan source files line-by-line
npx cot-lint --hidden        # descend into dot-directories such as .agents/

Exit codes: 0 clean · 1 findings · 2 usage error — drop it straight into CI.

What it detects

Class	Example
dead design-session citation	(decision 7), design §4.7, phase tokens W3/T4, 设计稿
stack/PR vantage	"this PR adds…", "a later PR in this stack"
change narration / version stamps	"used to", "no longer", "the old X", "the v1 refactor", "today", 旧版/不再
review choreography	"Rejected in review:", "the reviewer confirmed", 上一轮评审
reviewer-addressed justification	"the cast is safe — it simply…"
control-flow narration	"first we X, then we Y", "as you can see"
hedge / planning residue	"probably fine for now", "should be enough"
authoring-language slip	untranslated working-language fragments in the other language

English and Chinese batteries are both built in.

What it deliberately does not flag

The keep-rules are half the tool. A zero-treatment linter that deletes RFC 9110 §10.1.5, a load-bearing TODO(alice):, or "the old connection drains before the new one accepts" (runtime lifecycle, not change history) does more damage than the leakage. So cot-lint mechanically exempts:

• issue references and marked TODO/FIXME/XXX deferrals,
• §-references on lines that cite an external standard such as an RFC,
• lines carrying a cot-lint-ignore suppression — keep the reason next to it.

Batteries over-match by design. Every finding is a candidate, not a verdict; the keep-rules and rewrite method decide what survives.

Fixing, not just finding

The repo ships cot-trim, an agent skill that pairs with the CLI: it runs cot-lint --json, judges every hit against the one test, enumerates the passage's propositions before deleting anything, and fixes owner-first (generated files via their source, model-visible strings via their owning snapshot).

Install it where your agent looks for skills:

• DeepSeek Harness: dsh plugin add cot-lint (or github:YuanyuanMa03/cot-lint) — the cot-trim skill loads through the plugin's skill provider.
• Claude Code / generic agents: copy skills/cot-trim/ into your skills directory (~/.claude/skills/, .agents/skills/, or wherever your agent looks).

How this differs from "AI slop" style linters

Style-slop detectors flag prose that sounds like AI (word choices, em-dash habits). cot-lint flags prose whose vantage is the authoring session — references and narration that only make sense if you were there. Human-written docs can leak (copy-pasted PR descriptions do); AI-written docs can be clean. Different failure class, different tool.

Origin

The taxonomy, keep-rules, and battery approach are distilled from the engineering standards of DeepSeek Harness (MIT) — specifically its prose-hygiene practice for agent-written repositories — generalized here to work with any repo and any coding agent. See their CONTRIBUTING.md for the project's stance on community ecosystem work.

License

MIT