beads/engdocs/LINTING.md
Chris Sells 0e017821f4 docs: move internal/maintainer docs from docs/ to engdocs/
Relocate contributor- and maintainer-facing material out of docs/ so the
directory can become the user-facing Mintlify site. Moves preserve subpaths
(adr/, design/, staged-for-removal/ intact). messaging.md, UI_PHILOSOPHY.md,
and AGENT_SIGNING.md move per their DOC_INVENTORY dispositions (design doc,
design philosophy, maintainer convention).

Inbound links updated repo-wide: root guides, CONTRIBUTING, AGENTS,
workflows, lint config, scripts (check-doc-freshness now resolves the
inventory at engdocs/DOC_INVENTORY.md), Go comments, and the synced website
metadata page (regenerated via sync-website-docs.sh + generate-llms-full.sh).

The emitted help text in cmd/bd/init_safety_help.go still references
docs/adr/0002-init-safety-invariants.md; changing it would change bd's
runtime output, which is out of scope for this branch (flagged in the PR).
2026-07-12 10:37:07 -07:00

1.9 KiB

Linting Policy

Last reviewed: 2026-05-29

Freshness source: .golangci.yml, .github/workflows/pr.yml, .github/workflows/main.yml, and golangci-lint run --timeout=5m --build-tags=gms_pure_go ./... returning zero issues.

This document explains the required Go lint gate for this codebase.

Current Status

Lint is a required CI gate. The PR and main workflows run golangci-lint with the repository configuration and --build-tags=gms_pure_go; it is expected to pass with zero issues.

Run the same check locally with:

golangci-lint run --timeout=5m --build-tags=gms_pure_go ./...

Formatting is a separate required gate:

make fmt-check

Policy

Treat new lint findings as defects to fix before merge. Do not add a tolerated failing baseline, and do not configure CI with --issues-exit-code=0.

When a linter reports an intentional or false-positive pattern:

  • Prefer a narrow .golangci.yml exclusion tied to a path, linter, and message.
  • Use //nolint:<linter> only when the reason is local to a specific line and the comment explains why the warning is not actionable.
  • Keep broad linter disables as a last resort.

The current configuration already encodes accepted exclusions for intentional patterns such as deferred cleanup errors, controlled subprocess execution, test-fixture file reads, and documented security false positives.

CI Cleanup Decision

pr-lint should stay separate from pr-policy and pr-core so failures are easy to identify and rerun. It should include:

  • make fmt-check
  • golangci-lint run --timeout=5m --build-tags=gms_pure_go ./...

See CI_CLEANUP_PLAN.md for the full CI tier policy.

Future Work

  • Pin the golangci-lint version in CI instead of using version: latest.
  • Move the final CI shape behind a repository-owned scripts/ci/pr-lint.sh wrapper.
  • Periodically audit .golangci.yml exclusions and remove entries that are no longer needed.