fix(lint): correct golangci.yml header — vendor pattern, not include URL

[ensarkovankaya]

Summary

The shared golangci.yml header comment previously promised:

Service repos extend via:
  include:
    - "https://raw.githubusercontent.com/paper-board/.github/main/golangci.yml"

golangci-lint v2 (2.11.x) does NOT support include: at the top level. The schema validator rejects it as an additional property and the entire config fails to load (jsonschema: "" does not validate with "/additionalProperties": additional properties 'include' not allowed).

Discovered while doing paper-board/agents#14 (Task 26): consumer service tried to follow the comment, lint blew up, fell back to vendoring the file verbatim. Correcting the comment so future service repos don't repeat the cycle.

What changed

• Removed the misleading include: example.
• Replaced with the actual practice: vendor verbatim.
• Added a forward-looking note about a nightly drift-CI job (planned for service-template Task 32) that will diff vendored copies against this baseline and flag divergence.
• Inline override guidance kept (linters.settings.* + linters.exclusions.rules) so future readers see where to layer service-local overrides without removing baseline rules.

Why not implement URL include first

• golangci-lint URL-include is an upstream feature request, not in v2.x.
• Vendoring + drift CI is the pattern most multi-repo Go orgs converge on (kubernetes, prometheus). Documents real practice, not aspirational.

Test plan

• No code change — comment-only.
• golangci-lint config verify against the vendored agents copy: passes.
• Reviewer eyeball: comment accuracy.

Refs: paper-board/agents#14 (vendor copy that surfaced the issue); agent-manager/tasks/2026-05-02-adr-0010-gap-analysis.md Task 26 status.

Generated with Claude Code.

[greptile-apps]

Greptile Summary

• Removes the misleading include: <URL> example from the header comment, which is rejected by golangci-lint v2's schema validator (additionalProperties not allowed), and replaces it with the correct vendor-verbatim pattern.
• Adds inline guidance on where service-local overrides belong (linters.exclusions.rules and linters.settings.*), which is consistent with the actual structure of the file.
• Documents a planned nightly drift-CI job (service-template Task 32) that will detect vendored copies diverging from this baseline.

Confidence Score: 5/5

Comment-only change; no runtime behavior is modified and the new instructions accurately reflect golangci-lint v2 constraints.

No code is changed — only header comments are updated. The new guidance is factually correct (golangci-lint v2 does not support a top-level include: key), consistent with the actual file structure (linters.settings.* and linters.exclusions.rules both exist in the file), and removes actively harmful documentation that caused at least one service repo to fail linting.

No files require special attention.

Important Files Changed

Filename	Overview
golangci.yml	Comment-only header update: removes the incorrect include: URL example (unsupported in golangci-lint v2) and replaces it with accurate vendor-verbatim consumption guidance, override placement hints, and a forward-looking drift CI note.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[paper-board/.github/golangci.yml\nbaseline] -->|vendor verbatim| B[service-repo/.golangci.yml]
    B --> C{Need service-local overrides?}
    C -->|path-based exclusions| D[linters.exclusions.rules\nin vendored copy]
    C -->|linter config tweaks| E[linters.settings.*\nin vendored copy]
    C -->|No overrides needed| F[Use as-is]
    A -.->|planned: nightly drift CI\nservice-template Task 32| G[Diff vendored copies\nvs baseline → open issue on divergence]

Loading

_{Reviews (1): Last reviewed commit: "fix(lint): correct golangci.yml header —..." | Re-trigger Greptile}