fleetlint Policy for a fleet of repositories
v0.7
Getting started

Slop catalog

The traces careless or generated code leaves behind. Experienced reviewers notice them within minutes, and most of them predict real bugs. Each entry names the rule that finds it, or says that it is a review item.

The rules are in three places. fleetlint:minimal carries slop/conflict-markers; fleetlint:recommended adds the other three that are never acceptable in a commit (slop/focused-tests, slop/scratch-scripts, slop/report-documents). The preset fleetlint:slop carries the heuristics, and the two rules about agent traces in public repositories (public/no-agent-files, public/no-ai-attribution): add it next to another preset.

extends: [fleetlint:recommended, fleetlint:slop]

The heuristics are regular expressions over tracked source files (vendored, generated and build paths are skipped). They produce false positives: treat their findings as a review list, use exceptions with a reason for the ones that are intended, and let the stack’s linter (see stacks.md) enforce what it can enforce exactly.

Comments and text

SmellWhy it mattersRule / clean up
Narration comments: “Now uses X”, “Updated to…”, “Fixed:”, “NEW:”, “as requested”describes a diff or a conversation, not the code; stale immediatelyslop/narration-comments. Delete; the why goes in a comment only if it is not obvious, what changed goes in the commit message
Restating comments: // increment counter, doc comments that repeat the namenoise that hides the comments that matterreview. Keep comments for constraints, workarounds, invariants, links
Banner and divider commentssign of a file doing too many thingsslop/banner-comments. Split the file at the banners
Emoji and decorative symbols in code and logslog noise, encoding problemsslop/emoji-in-code, slop/typographic-chars
Placeholder or hedge comments: “In a real app…”, “for simplicity”, “not implemented yet”admits the code is not realslop/placeholder-comments. Implement it, or remove the feature and open an issue
TODO/FIXME without an issue referencenever gets done; nobody owns itslop/todo-without-issue. Format TODO(#123): …
Commented-out codedead weight; git already remembersslop/commented-out-code. Delete
Vague errors: “Something went wrong”, “An error occurred”users and logs learn nothingslop/vague-errors. Name the operation and the input that failed

Code structure

SmellWhy it mattersRule / clean up
Variant copies: fetchDataV2, parseNew, handlerFixed, utils_old.py, Foo copy.tstwo code paths, one of them wrong; fixes land in only oneslop/variant-names, slop/variant-files. Change the original, update callers, delete the copy
Near-duplicate functions across filesthe same bug in several placesreview; the stack’s duplication tool
utils / helpers / common / misc dumping groundsno owner, grows forever, hidden couplingslop/dumping-ground-files. Move each function to the module that owns its concept
Pass-through layers that only delegate; single-implementation interfaces without a test seamindirection without meaningreview. Collapse layers that add nothing
Arbitrary sleeps and retry loops around flaky behaviourhides race conditions; slow and still flakyslop/arbitrary-delays. Await the real event, fix the ordering
Defensive overkill: null checks on non-null values, defaults everywhere, try/catch around everythingmasks bugs and turns crashes into silent wrong behaviourreview. Validate once at the boundary
Options, flags and settings nobody uses; compatibility shims for data that never shippedmore states to testreview. Delete until there is a real need
Stub implementations returning hard-coded data in production codesilent wrong behaviourslop/placeholder-comments, slop/placeholder-values. Implement or remove
Reinvented standard library; JSON, URLs, HTML or dates parsed with regular expressionsedge cases wrongreview. Use the standard library or a proper parser
Two HTTP clients, two date libraries, three state approachesevery change needs to know all of themreview. Pick one, record it in an ADR, migrate the rest

Errors, types and robustness

SmellWhy it mattersRule / clean up
Empty catches, except: pass, _ = err, .catch(() => {})failures vanishslop/swallowed-errors (single-line forms); the stack’s linter for the rest
Escape hatches: any, @ts-ignore, # type: ignore, // ignore:, nolintturns the checker off exactly where it would helpslop/escape-hatches lists them. Fix the type; justified suppressions carry a reason
Forced unwraps: .unwrap() in Rust, !! in Kotlin, try! in Swift, outside testsa crash where an error was expectedslop/forced-unwraps lists them. Handle the case, or state the invariant with .expect("why")
Debug-print sprawllog noise, leaks dataslop/debug-output. Structured logger
Disabled TLS verification, eval, chmod 777, wildcard CORSa shortcut that removes a protection for everyoneslop/insecure-patterns
Fire-and-forget async, missing awaits, listeners and timers never cancelledleaks, lost errorsreview; unawaited-future lints

Tests

SmellWhy it mattersRule / clean up
Assertion-free tests, expect(true), tests that only check “no exception”coverage without protectionslop/trivial-asserts; mutation testing exposes the rest
Mocking the unit under test, or re-implementing its logic to compute the expected valuethe test cannot failreview. Fakes only at outer boundaries; hard-code expected values
Expected values changed to match buggy outputthe bug is locked inreview of test diffs
Skipped tests (.skip, @Ignore, t.Skip)silent gapsslop/skipped-tests. A quarantined test references an issue
Focused tests (.only, fit)disables the rest of the suiteslop/focused-tests (error)
Sleep-based timing in testsflakyreview. Fake clocks, wait for conditions

Dependencies

SmellWhy it mattersRule / clean up
Invented or typo-squatted package namessupply-chain attacks target exactly thesereview of every new dependency: exists, maintained, right publisher
A dependency for a few lines of code; several libraries for the same jobattack surface and churnreview
Forked or vendored copies without documentationcannot be patchedreview. Document upstream, base version and changes, or switch back
Missing lockfileunreproducible buildsrepo/lockfile-committed

Repository and files

SmellWhy it mattersRule / clean up
Junk files: .DS_Store, *.bak, *.orig, *.log, build outputnoise; sometimes leaks datarepo/no-tracked-junk
Scratch scripts in the root: fix_imports.py, debug-auth.js, tmp_check.shunmaintained code pathsslop/scratch-scripts. Real tools go in scripts/
Report documents: IMPLEMENTATION_SUMMARY.md, FIXES.md, REFACTORING_PLAN.md, NEXT_STEPS.mdalways staleslop/report-documents
Tracked .env files, keys, tokenscredential leakrepo/no-tracked-env, hooks/secret-scan. Rotate what leaked
Agent instruction files in public repositories (CLAUDE.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md, .cursorrules, .windsurfrules, .clinerules, .aider*, .claude/, .cursor/)a public repository shows what its maintainers wrotepublic/no-agent-files
Merge conflict markersthe file means what neither side intendedslop/conflict-markers (error)
Lint rules disabled in configuration to get greenhides real bugsreview. Ratchet with a baseline instead

Documentation

SmellWhy it mattersRule / clean up
Marketing filler: seamless, blazing fast, cutting-edge, leverage, delve (the list is in the rule)says nothing a reader can act onslop/marketing-words (Markdown outside code blocks and CHANGELOG.md)
Emoji headingsbreak anchors and searchslop/emoji-headings
Feature lists the code does not implement; badges for services that do not existmisleadingreview. Every claim is true today
Overview, Conclusion and Summary filler; the same content in several fileswalls of text nobody readsreview. One place per fact
Instructions and examples that do not runwrong documentation is worse than nonereview. Run them; use doc tests where the stack has them

Commits and history

SmellWhy it mattersRule / clean up
Vague messages: “fix”, “update”, “wip”, “changes”the history is useless for debuggingslop/vague-commit-messages; hooks/conventional-commits prevents new ones
Subjects that are not Conventional Commitschangelog and version cannot be computedslop/non-conventional-commits
Huge commits mixing many concernscannot be reviewed or revertedslop/huge-commits
A message that does not match the diffmisleading historyreview. Write the message from the diff
AI author, co-author trailers or “generated with” footers in public repositoriesa public history shows human authorshippublic/no-ai-attribution (AI tools’ addresses and generator footers; names are not read)