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

Rule catalog

The practices behind the rules are described in the baseline and, per stack, in the stack profiles. Each rule has a page of its own in the rule reference, generated from the catalog.

The rules the fleetlint:* presets ship, grouped by family. The rule reference has the exact requirement, parameters and fix of each.

Presets. minimal is the floor for any repository; recommended (the default) includes it and selects the families below; strict is recommended with every severity raised one step and no exceptions on the security rules; oss is recommended with the public/* rules on whatever the detected visibility; slop is an add-on with the heuristic slop/* rules and the two agent-trace rules for public repositories. The Preset column names the smallest preset that selects a rule.

Capabilities. A rule marked capability states one requirement that each stack meets with its own tools: lint/configured is implemented by lint/configured/go, lint/configured/python and so on, each with its own page. Selecting, overriding or excepting the capability reaches every implementation; the implementation id adjusts one stack. Every implementation that runs must pass. The release capabilities are keyed by published artifact rather than by stack, so each image, package or set of release files is checked on its own; the changelog generator is one rule at the root that any generator satisfies. The capability matrix shows which stack implements which capability, and writing rules how they work.

Severity is the default; repositories may raise it freely and lower it with a reason. Tiers: all, or the tiers the rule applies to.

repo: repository hygiene

RuleSeverityTiersPresetChecks
repo/no-tracked-junkerrorallminimalno OS/editor/build junk in the index (.DS_Store, *.log, __pycache__, …)
repo/no-tracked-enverrorallminimalno .env* with values tracked (.env.example allowed)
repo/no-large-fileswarningallminimalno tracked file over params.max_kb (default 2048) unless under git-lfs
repo/gitignore-presentwarningallminimal.gitignore at the root
repo/editorconfigwarningallrecommended.editorconfig with root = true
repo/gitattributeswarningallrecommended.gitattributes with * text=auto
repo/readme-presentwarningallrecommendedREADME with an install/quickstart section
repo/lockfile-committederror1, 2recommendedcapability: the lockfile of each stack’s dependency manager is tracked
repo/toolchain-pinnedwarning1, 2recommendedcapability: each stack pins its compiler or runtime with a version (the stack’s version file, .tool-versions/mise.toml naming the tool, or devbox.json naming its package with a version); a JDK pin for Java and Kotlin
repo/dev-environmentwarning1, 2recommendedthe tools are reproducible: in a container mode the container; on the machine a Nix flake, devenv or devbox with its lock file (or shell.nix), mise.toml / .tool-versions, or a tools target with pinned versions (outcome rule)
repo/codeownersinfo1recommendedCODEOWNERS in a recognised location

taskrunner: the task-runner contract

RuleSeverityTiersPresetChecks
taskrunner/targetserror1, 2recommendedfmt lint test cover audit check check-fast exist and are not placeholders, in whichever runner is used (Makefile, justfile, Taskfile, package.json scripts; Gradle by convention)
taskrunner/containerwarning1, 2recommendedwhen facts.container is not none: a target called outside the container runs inside it: devcontainer CLI, docker, podman, or an accept:ed way (outcome rule)
taskrunner/check-compositionwarningallrecommendedcheck depends on lint and test (and cover, audit at tier 1)

format, lint, types: static analysis per stack

The per-stack tools and settings are in the stack profiles.

RuleSeverityTiersPresetChecks
format/configuredwarning1, 2recommendedcapability: a formatter is configured or runs (gofumpt, ruff format, rustfmt, Prettier or Biome, Spotless, dart format, dotnet format, clang-format, RuboCop, PHP CS Fixer, …); not applicable to Hugo
lint/configuredwarning1, 2recommendedcapability: a linter is configured (golangci-lint v2, ruff, clippy [lints], ESLint/Biome/oxlint, detekt, Checkstyle/Error Prone/SpotBugs/PMD, .NET analyzers, clang-tidy, RuboCop, PHPStan/Psalm, a Dart lint set; for Hugo hugo --panicOnWarning)
lint/strictwarning1, 2recommendedcapability: the linter’s required checks are on, one finding per missing check (golangci-lint errcheck govet staticcheck errorlint gosec gocognit funlen; ruff E F I B UP SIM BLE S C90 T20; clippy unwrap_used expect_used panic todo dbg_macro; five detekt rules; .NET Nullable, warnings as errors, analysis level; clang-tidy WarningsAsErrors; Java analyzers that fail the build; RuboCop NewCops: enable)
types/strictwarning1, 2recommendedcapability: the type checker runs in strict mode (tsconfig strict flags; mypy or pyright strict; PHPStan max or Psalm level 1; the Dart analyzer’s three strict modes); not applicable where the compiler is the type checker
lint/shellinfoallrecommendedwhen shell scripts are tracked, shellcheck runs as a hook, in the task runner or in CI

quality: behaviour, not configuration

RuleSeverityTiersPresetChecks
quality/check-passeserror1, 2recommendedwith --deep: the task runner’s check exits 0 within the budget
quality/policy-enforcedwarning1, 2recommendedfleetlint check runs as a hook, in the task runner or in CI
quality/coverage-thresholdwarning1, 2recommendedcapability: tests fail below a coverage floor (the stack’s coverage tool with a minimum, diff-cover --fail-under, a codecov target)
quality/duplication-gateinfo1recommendeda duplication detector runs: golangci dupl, jscpd, PMD CPD, pylint duplicate-code, Sonar (outcome rule)
quality/mutation-gateinfo1recommendeda mutation testing tool runs on the core: gremlins, mutmut, cargo-mutants, Stryker, Pitest, mutation_test (outcome rule)

docs and changelog: the documents that must exist

RuleSeverityTiersPresetChecks
docs/architecturewarning1recommendeddocs/ARCHITECTURE.md or an Architecture section in the README
docs/adr-directoryinfo1recommendeddocs/adr/ with at least one record
changelog/presentwarning1, 2recommendedCHANGELOG.md with an Unreleased section
changelog/generator-configuredinfo1recommendedcliff.toml or release-please/changesets

hooks: prek, pre-commit or lefthook

RuleSeverityTiersPresetChecks
hooks/config-presenterror1, 2minimal.pre-commit-config.yaml or a lefthook configuration
hooks/secret-scanerror1, 2minimala pre-commit hook runs a secret scanner (gitleaks, trufflehog, ggshield, detect-secrets, secretlint); detect-private-key alone is a partial result
hooks/shared-hygienewarning1, 2recommendedthe shared hygiene hooks (trailing whitespace, end of file, merge conflicts, large files)
hooks/conventional-commitswarning1, 2recommendeda commit-msg hook checks every message
hooks/pre-push-checkwarning1, 2recommendeda pre-push hook runs the task runner’s check (check-fast does not count)
hooks/revs-pinnedwarning1, 2recommendedevery rev: is a version tag or a commit SHA, never a branch

deps: dependency hygiene

RuleSeverityTiersPresetChecks
deps/locked-installwarning1, 2recommendedcapability: installs use the lockfile strictly (npm ci, uv sync --locked, cargo --locked, composer install, Bundler frozen, …) and nothing rewrites it outside an update target
deps/vulnerability-scanwarning1, 2recommendedcapability: the task runner or CI runs a vulnerability scanner (the stack’s tool, or osv-scanner, trivy, grype and the like for every stack)
deps/license-checkinfo1recommendedcapability: the task runner or CI checks dependency licenses against an allowlist
deps/unused-checkinfo1recommendedcapability: unused dependencies are detected (go mod tidy -diff, deptry, cargo-machete, knip, composer-unused, dependency_validator, …)
deps/update-automationwarning1, 2recommendedRenovate or Dependabot is configured
deps/update-coverageinfo1, 2recommendedthe update automation covers every detected stack, GitHub Actions and Dockerfiles
deps/update-cooldowninfo1, 2recommendedupdates wait a few days after a release: Renovate minimumReleaseAge, Dependabot cooldown
deps/install-scripts-disabledinfo1, 2recommendedNode: install scripts are off or allowlisted (.npmrc, .yarnrc.yml, pnpm onlyBuiltDependencies, bun trustedDependencies)
deps/forks-documentedinfo1, 2recommendedwhen a fork is used: go.mod replace, git sources in Cargo.toml, package.json or Python requirements are documented in FORKS.md, a Forks section, or an inline comment

containers: repositories with a Dockerfile

RuleSeverityTiersPresetChecks
containers/dockerignorewarningallrecommendeda .dockerignore exists
containers/non-root-userwarningallrecommendedevery Dockerfile sets a non-root USER or builds on a :nonroot base; one finding per file
containers/base-image-pinnedinfo1recommendedevery FROM carries @sha256:; scratch, build arguments and earlier stages exempt

ci: the check workflow and its safety

The CI rules read GitHub, Gitea and Forgejo Actions workflows and .gitlab-ci.yml with its local includes. A rule about something only one system has applies to that system only; the rule’s page says which.

RuleSeverityTiersPresetChecks
ci/check-workflowwarning1, 2recommendeda workflow or pipeline on push or pull/merge request runs the task runner’s check (check-fast does not count)
ci/actions-pinnedwarning1recommendedevery uses: is pinned to a commit SHA, docker:// images by digest; GitLab includes and components to a commit SHA
ci/least-privilegewarning1, 2recommendedGitHub and Gitea: top-level or per-job permissions: present and not write-all
ci/no-script-injectionwarning1, 2recommendedActions: no ${{ }} over outsider-controlled event data inside a run: or github-script script:
ci/no-pipe-to-shellwarning1, 2recommendedno download piped into a shell in CI scripts or Dockerfiles
ci/no-pull-request-targeterrorallrecommendedpublic repositories: no pull_request_target workflow checks out or fetches the PR’s code
ci/checkout-no-persist-credentialsinfo1recommendedActions: every actions/checkout sets persist-credentials: false
ci/workflow-lintinfo1recommendedActions workflows are linted with actionlint or zizmor
ci/sastinfo1recommendeda SAST tool runs: CodeQL, Semgrep or Opengrep, GitLab SAST, SonarQube
ci/job-timeoutsinfoallrecommendedevery job sets a timeout (timeout-minutes; GitLab timeout:); one finding per job
ci/concurrency-cancelinfoallrecommendedpull-request pipelines cancel superseded runs (concurrency with cancel-in-progress; GitLab interruptible)

release: producing artifacts (tier 1)

Outcome rules: satisfiers list the known producers; a repository adds its own with accept:. Most apply when a release mechanism or a tag-triggered pipeline exists.

RuleSeverityTiersPresetChecks
release/tag-triggerederror1recommendedreleases come from a tag-triggered pipeline (Actions push: tags:, GitLab $CI_COMMIT_TAG)
release/signingerror1recommendedartifacts are signed in the release pipeline (cosign, GoReleaser signs:, sigstore-python, npm provenance, gpg)
release/sbomwarning1recommendedan SPDX or CycloneDX SBOM is generated in the release pipeline; not checked for registry-only and git-cliff-only releases
release/provenancewarning1recommendedbuild provenance is attested (attest-build-provenance, SLSA generator, cosign attest, npm or PyPI trusted publishing, GitLab artifact metadata)
release/checksumswarning1recommendeda checksums file is produced (GoReleaser default, sha256sum, shasum -a 256)
release/trusted-publishingwarning1recommendedpublishing to npm, PyPI, crates.io or RubyGems uses OIDC trusted publishing, not a registry token from secrets (GitHub and GitLab)
release/semver-tagswarningallrecommendedexisting tags match v?MAJOR.MINOR.PATCH[-pre]; one finding per offending tag
release/signed-tagswarning1recommendedthe newest params.recent (3) version tags carry a PGP, SSH or X.509 signature
release/changelog-in-releaseinfo1recommendedrelease notes come from git-cliff/GoReleaser changelog, not hand-written
release/hosted-builderinfo1recommendedjobs of a tag-triggered GitHub workflow run on GitHub-hosted runners
release/reproducible-buildinfo1recommendedcapability: release builds are reproducible (-trimpath, --remap-path-prefix, outputTimestamp, ContinuousIntegrationBuild, or SOURCE_DATE_EPOCH for any stack)
release/api-compatibilityinfo1recommendedlibraries: the stack’s API check runs against the previous release: gorelease/apidiff, griffe, cargo semver-checks, api-extractor, binary-compatibility-validator (outcome rule)

public: open-source repositories (when: repo.public)

RuleSeverityTiersPresetChecks
public/licenseerrorallminimalLICENSE with a recognised SPDX license
public/security-policywarning1recommendedSECURITY.md
public/contributinginfo1recommendedCONTRIBUTING.md
public/code-of-conductinfo1recommendedCODE_OF_CONDUCT.md
public/manifest-licenseinfo1recommendeda published package’s manifest declares the license (package.json, pyproject.toml, Cargo.toml)
public/issue-templatesinfo1recommendedan issue or pull-request template in .github/ or .gitea/
public/no-agent-fileserrorallslopno agent instruction files tracked (CLAUDE.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md, .cursorrules, .windsurfrules, .clinerules, .aider*, .claude/, .cursor/)
public/no-ai-attributionerrorallslopthe last params.commits (default 200) commits carry no AI tool’s address as author or co-author and no generated-with footer; names are not read

slop: traces of careless or generated code

Catalog and rationale: slop.md. slop/conflict-markers is in fleetlint:minimal, three more are in fleetlint:recommended; the others are heuristics in the add-on preset fleetlint:slop, all info except slop/insecure-patterns (warning). All apply at every tier.

RuleSeverityPresetChecks
slop/conflict-markerserrorminimalno merge conflict markers in source
slop/focused-testserrorrecommendedno .only, fit, fdescribe, solo: true
slop/scratch-scriptswarningrecommendedno fix_*, debug-*, tmp_* scripts at the root
slop/report-documentswarningrecommendedno *_SUMMARY.md, *REPORT*.md, NEXT_STEPS.md and the like
slop/narration-comments, slop/placeholder-comments, slop/banner-comments, slop/todo-without-issue, slop/commented-out-codeinfoslopcomment hygiene
slop/emoji-in-code, slop/typographic-chars, slop/emoji-headingsinfoslopno emoji or typographic characters in code and headings
slop/marketing-wordsinfoslopno marketing filler in Markdown documentation
slop/debug-output, slop/arbitrary-delays, slop/swallowed-errors, slop/escape-hatches, slop/forced-unwraps, slop/vague-errors, slop/placeholder-valuesinfoslopcode smells outside tests
slop/insecure-patternswarningslopno disabled TLS verification, eval(, chmod 777, wildcard CORS
slop/variant-names, slop/variant-files, slop/dumping-ground-filesinfoslopno V2/New/Old variants, no utils dumping grounds
slop/skipped-tests, slop/trivial-assertsinfosloptest hygiene
slop/vague-commit-messages, slop/non-conventional-commits, slop/huge-commitsinfoslophistory of the last params.commits commits

Totals

Count
rules106
of which capabilities12
implementations of the capabilities (per stack and any)129

Not rules: the templates

Three entries of earlier drafts (release/template-shape, release/gitea-parity, ci/same-shape-both-forges) asserted that a repository’s workflows have the shape of fleetlint’s templates. They are not rules: the release and CI rules above check outcomes, so a repository with its own pipeline passes, and a shape rule would fail it for being different. What they stood for is checked on fleetlint’s side instead: a test (internal/engine/templates_test.go) requires that a repository set up from each stack’s templates passes the hook, CI and release rules, and the templates still have to run once on a real GitHub runner (roadmap).

Not rules, but part of 1.0: organization layer (locked rules, severity floors, --require, signed git/OCI catalog sources) and team layer (sources file, layered resolution, per-layer attribution). See ROADMAP.