[plainprogrammer]

Closes #264.

What

bin/ci checks gets a step, "Docs: new and changed public code has a comment" (ruby script/yard/comment_ratchet.rb, directly after the YARD step), that fails a branch which adds or changes a public class, module or method with no YARD summary. It looks only at what the branch changed, never at total coverage, so untouched code is never judged and the documentation grows as code is touched.

• It parses the judged files (app/models/, app/helpers/, app/*/concerns/, lib/, spec/support/) at the head and at the merge base with origin/main with YARD, and compares each object's text by qualified name. It reads no diff, so renames, moves and where git places a hunk don't matter.
• It fails, never passes, when it can't see the base (no origin/main, no merge base, a shallow clone, a changed file YARD can't read). The checks job already has fetch-depth: 0.
• Output is one line per offender (path:line: Name has no comment (added|changed)), a count, the rule's path and a line saying staleness and quality are not checked here.
• No allowlist, baseline, skip marker, ADR, gem or change to bin/yard doc. It adds well under a second to bin/ci checks here (0.4 s).

Spec 056 (v1.2.3) supersedes spec 054's Out-of-Scope line "a rule that new code carries comments"; the supersession is recorded in both directions in docs/specs/README.md. The rule (.claude/rules/code-documentation.md), CLAUDE.md's bin/ci line and the release-and-deploy area doc are updated.

Review and evidence

• Spec and plan: Opus reviews, two rounds each (APPROVE WITH CHANGES, nothing blocking at the end).
• Opus code review of the implementation (APPROVE WITH CHANGES): a changed file YARD silently drops, an order-dependent two-file class verdict, symlinks and others, all fixed.
• sdd-review Mode B (Opus): round 1 DRIFT DETECTED, round 2 SPEC-ALIGNED; recorded in docs/specs/056-yard-comment-ratchet/verification.md under ## Implementation review, with every AC mapped to its example and the known limits.
• Local: full bin/ci green at e4bcb6ec (3121 examples, 0 failures), seeds 1 and 42424 green; with an uncommented method added to lib/collector/dev_port.rb, bin/ci checks fails at the new step naming lib/collector/dev_port.rb:22: Collector::DevPort.probe has no comment (added), and passes once reverted.

Needs a decision or a hand

• Spec 056 v1.2.3 (PATCH, confirmed by the maintainer 2026-11-10): a method is new by qualified name across files (a move between files isn't judged); @api private on a class covers its members.
• AC-4.2's CI half (GitHub's checks job failing on a throwaway commit) is pending: the maintainer pushes a scratch branch by hand; this PR's own passing checks run covers AC-4.3's CI time.
• Spec 054's AC-3.7 example now boots the app in a fresh process: the new spec file loads YARD into the RSpec process, which the old in-process defined?(YARD) check forbade (verification.md, Rulings).

🤖 Generated with Claude Code