docs(agents): add errorlint rule, lint gate, and local overlay

[yuanchen8911]

Summary

Add three rules to CLAUDE.md and AGENTS.md:

1. errorlint rule with BAD/GOOD examples for sentinel error checks (errors.Is instead of ==).
2. Mandatory pre-PR golangci-lint gate for any Go change, including PRs labeled as documentation-only.
3. Local Overlay support — agents should also read AGENTS.local.md in the repo when present, and treat it as a per-clone additive layer.

Also gitignore AGENTS.local.md so personal overlays stay out of the shared repo.

Motivation / Context

• errorlint: Discovered during review of refactor(ci): unify GPU Chainsaw layout and validation flow #587 — referencedAssertFiles used err == io.EOF which was rejected by golangci-lint. The rule was only mentioned in the Troubleshooting table as a hint, not as an explicit coding pattern.
• Lint gate: PR docs(agents): add errorlint rule, lint gate, and local overlay #590 originally shipped Go changes labeled as "docs only" without running make qualify, so the lint error was not caught before push. The mandatory gate prevents this class of oversight for both Claude Code and Codex agents.
• Local Overlay: Codex has no native "per-project + personal + local" instruction layer like Claude's memory system. A small convention — read AGENTS.local.md if present, treat as additive and lower-priority than the shared AGENTS.md — gives both Claude and Codex a consistent way to pick up personal preferences (e.g., per-user issue-filing conventions) without committing them to the shared repo.

Related: #587

Type of Change

• Documentation update

Component(s) Affected

• Docs/examples (docs/, examples/)

Implementation Notes

• Added errors.Is() rule to Error Wrapping Rules section with BAD/GOOD code examples and a note about stderrors.Is() aliasing in files importing pkg/errors
• Added corresponding anti-pattern table entry
• Added mandatory lint gate rule to Pull Request Requirements
• Added a short "Local Overlay" section near the top of both files pointing to AGENTS.local.md
• Added AGENTS.local.md to .gitignore
• Verified tools/check-agents-sync still passes

Testing

N/A — documentation only, no code changes.

Risk Assessment

• Low — Isolated change, well-tested, easy to revert

Checklist

• I updated docs if user-facing behavior changed
• Changes follow existing patterns in the codebase
• Commits are cryptographically signed (git commit -S)

Summary by CodeRabbit

• Documentation
  • Added a local-overlay rule: a per-clone overlay file can override shared guidance when present.
  • Strengthened error-handling guidance: sentinel checks must use the language's error-is pattern; anti-patterns and CI enforcement updated.
• Chores
  • Updated ignore rules to exclude the per-clone local overlay file.
• Process
  • New mandatory pre-submit lint gate: PRs that modify Go code must run and resolve local lint checks before pushing.

[ArangoGutierrez]

LGTM. Good addition -- the stderrors.Is alias note is particularly useful since that is a common stumbling point when pkg/errors shadows stdlib.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Added "Local Overlay" handling and .gitignore entry for AGENTS.local.md; mandated sentinel error checks use errors.Is(err, <sentinel>) (with stderrors.Is(...) alias note); updated Anti-Patterns; and required running golangci-lint run -c .golangci.yaml locally for PRs touching .go files.

Changes

Cohort / File(s)	Summary
Agent instruction overlays & linting ​.claude/CLAUDE.md, AGENTS.md	Added "Local Overlay" guidance to read AGENTS.local.md (repo root) as a higher-priority local overlay when present and non-conflicting; required sentinel error comparisons use errors.Is(err, <sentinel>) (or stderrors.Is(...) if pkg/errors aliases stdlib errors); updated Anti-Patterns table; added mandatory local golangci-lint run -c .golangci.yaml requirement for PRs that modify .go files.
Repository ignore .gitignore	Added entry to ignore AGENTS.local.md with an inline comment referencing the "Local Overlay" guidance.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Poem

🐇 I hop through docs with a careful twist,
"Read local overlay" is on my list,
I swap == for .Is() with glee,
Lint hops in, tidy as can be,
A gentle thump — commits, squeaky-free!

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely summarizes the three main changes: adding errorlint rule, lint gate requirement, and local overlay support for agent configuration.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

♻️ Duplicate comments (1)

AGENTS.md (1)

299-308: ⚠️ Potential issue | 🟡 Minor

Same formatting issue as CLAUDE.md (blank lines around code fence).

This section has the same MD031 compliance issue as .claude/CLAUDE.md lines 299-308. Since AGENTS.md is auto-synced from the canonical source, fixing the blank lines in .claude/CLAUDE.md will resolve this in both files.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@AGENTS.md` around lines 299 - 308, The Markdown fenced code block that shows
the Go example comparing err == io.EOF vs errors.Is(err, io.EOF) needs blank
lines immediately before and after the triple-backtick fence to satisfy MD031;
update the canonical CLAUDE.md source section that contains the Go example (the
block referencing errors.Is and io.EOF) to add the missing blank lines around
the code fence so the autogenerated AGENTS.md will be corrected on sync.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.claude/CLAUDE.md:
- Around line 299-308: The Markdown fenced code block around the Go example
needs blank lines before the opening ```go fence and after the closing ``` fence
to satisfy MD031; edit the fenced block that contains the "BAD - fails
errorlint..." and "GOOD - works with wrapped errors..." examples so there is an
empty line immediately above the opening ```go and an empty line immediately
below the closing ```; do not change the code, only insert the two blank lines
surrounding the fence.

In `@AGENTS.md`:
- Around line 299-308: Replace the sentinel error comparison "if err == io.EOF
{" in the test that contains that check with the idiomatic errors.Is(err,
io.EOF) call; if the file imports github.com/pkg/errors and aliases the stdlib
as stderrors, use stderrors.Is(err, io.EOF) instead to handle wrapped errors and
satisfy the errorlint rule.

---

Duplicate comments:
In `@AGENTS.md`:
- Around line 299-308: The Markdown fenced code block that shows the Go example
comparing err == io.EOF vs errors.Is(err, io.EOF) needs blank lines immediately
before and after the triple-backtick fence to satisfy MD031; update the
canonical CLAUDE.md source section that contains the Go example (the block
referencing errors.Is and io.EOF) to add the missing blank lines around the code
fence so the autogenerated AGENTS.md will be corrected on sync.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 65647f4f-7480-4bcb-bbb5-f47093028b0b

📥 Commits

Reviewing files that changed from the base of the PR and between 94fb041 and c98d9db.

📒 Files selected for processing (2)

• .claude/CLAUDE.md
• AGENTS.md

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.claude/CLAUDE.md:
- Line 502: Update the inline CLI example in the "**Mandatory lint gate for Go
changes:**" section so it follows the repo markdown style: prefix the command
with the component name, use explicit flag form and camelCase flag names (e.g.,
componentName command --camelCaseFlag value), and replace the current inline
example at that location with the revised component-prefixed, explicit-flag
version.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: c0f3fe9b-a3f1-4743-9b83-441772c6e561

📥 Commits

Reviewing files that changed from the base of the PR and between cd8ed8a and fd97976.

📒 Files selected for processing (3)

• .claude/CLAUDE.md
• .gitignore
• AGENTS.md

[lockwobr]

lgtm