docs(rules): add comment-content rule + fix stale rules index in CLAUDE.md

[ChaoWao]

Two docs-only changes:

1. New rule .claude/rules/comments.md — a code comment states a
non-obvious present-tense fact about the code as it stands (invariant,
contract, constraint). It never justifies a change, narrates the
modification/history, or acts as an epitaph for a deletion. Rationale and
change-context go in the commit message, PR description, or
docs/investigations/. Litmus test: would the comment still make sense to a
reader who never saw the diff? Sharpens codestyle.md §1 and reconciles
doc-consistency.md §5 terminology.

2. Fix the stale rules index in CLAUDE.md (surfaced by review). The list
referenced architecture and terminology, which are not files —
architecture content lives in ascend.md, and there is no terminology rule —
and it omitted five real rules (ascend, known-issues-tracking,
project-layout, running-onboard, venv-isolation). The index now links
every existing .claude/rules/*.md and references nothing that doesn't exist.

Docs-only; no code changes.

🤖 Generated with Claude Code

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds a new .claude/rules/comments.md document specifying conventions for writing present-tense, fact-based code comments while banning justification, narration, edit-history, and deletion-explanation comments. It also updates CLAUDE.md's Important Rules to reference a broader set of rule documents.

Changes

Comment Rules Documentation

Layer / File(s)	Summary
Add comments rule and wire into CLAUDE.md .claude/rules/comments.md, CLAUDE.md	New rule document defines comment conventions (present-tense facts, no justification/narration/deletion epitaphs, litmus test, pointers to commit/PR/docs for rationale); CLAUDE.md's Important Rules bullet is expanded to reference this and other rule documents.

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

Poem

A rule was born, so crisp and clean,
"State the facts, skip what-has-been!"
No epitaphs for code that's gone,
Just present truths to carry on.
Hop hop, I file this doc with glee 🐇📜

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.
Title check	✅ Passed	The title clearly summarizes the docs rule addition and the CLAUDE.md rules index fix.
Description check	✅ Passed	The description accurately describes both docs-only changes and matches the pull request scope.

---

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.}

[gemini-code-assist]

Code Review

This pull request introduces a new markdown rule file .claude/rules/comments.md that defines guidelines for writing code comments, and updates CLAUDE.md to reference it. The review feedback recommends linking other existing guidelines (architecture, codestyle, and terminology) in CLAUDE.md to their respective files for better consistency and navigation.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.