docs: refine code commenting guidelines in AGENTS.md

[cjbarth]

Tightens the code-commenting guidance in AGENTS.md:

• Comment a hazard only when a test can't practically catch it (e.g. the constant-time HMAC comparison); well-written tests and code are otherwise self-documenting.
• Don't narrate history in comments. A bug the code no longer has belongs in the commit message and the PR, where git blame leads.
• Link a spec the code implements, but link an issue only for a tricky edge case where whoever breaks the test might otherwise decide the test is wrong.

Documentation-only; no code or test changes.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Updated comment-writing guidance to emphasize explaining rationale, risks, and non-obvious constraints.
  • Clarified when comments are warranted and when to include links to specifications or issues.
  • Removed guidance focused on documenting historical context or test names.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 6b6c4263-54b8-43b1-af64-5f49b8261eae

📥 Commits

Reviewing files that changed from the base of the PR and between ee4d510 and a4e4a9f.

📒 Files selected for processing (1)

• AGENTS.md

Included review availability: Your plan provides up to 2 included reviews per hour; 1 remains after this review.

---

📝 Walkthrough

Walkthrough

The ## Comments section in AGENTS.md now provides updated guidance for explaining code constraints, documenting hazards, avoiding historical narration, and linking specifications or issues.

Changes

Comment Guidance

Layer / File(s)	Summary
Comment guidance rules AGENTS.md	The guidance now focuses comments on non-obvious constraints, limits hazard comments to cases tests cannot practically catch, excludes historical narration, and distinguishes specification links from edge-case issue links.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~3 minutes

Merge Risk: ⚪ Minimal · up to a4e4a

This documentation-only update refines commenting guidance without changing product behavior or runtime risk, so it is ready to merge after normal checks.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the documentation change to refine code-commenting guidelines in AGENTS.md.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.35%. Comparing base (f5c4d22) to head (a4e4a9f).
⚠️ Report is 7 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #574      +/-   ##
==========================================
+ Coverage   75.95%   77.35%   +1.39%     
==========================================
  Files           9        9              
  Lines        1048     1073      +25     
  Branches      273      275       +2     
==========================================
+ Hits          796      830      +34     
+ Misses        144      137       -7     
+ Partials      108      106       -2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.