fleetlint Policy for a fleet of repositories
v0.6
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. Most capabilities need every stack’s implementation to pass (combine: all); the release capabilities and the changelog generator need one (combine: any), because a release and a changelog belong to the repository rather than to each stack. 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, or .tool-versions/mise.toml naming the tool); 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 or devenv, 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.