[#201] Style → Cap comment length and ban issue references - #204

Resolves #201

Problem

• Comments make up 24% of source lines, and the longest single block runs to 29 lines
• typescript-as-go already caps a doc comment at one sentence, but nothing enforced it, so design rationale accumulated above type aliases where it cannot be reviewed and goes stale unnoticed
• Rationale is often restated above two or three symbols, and references such as (#86) mean nothing to a reader without access to the tracker

Why

• Reviewers spend their attention on prose rather than code, and a change to one line of logic drags fifteen lines of comment along with it
• Rationale kept in docs/ reads as one argument rather than three fragments, and outlives the code it describes
• Putting the rule in CI is what stops it decaying back into a preference nobody holds

Greptile Summary

The PR formalizes concise TypeScript comment standards, adds an automated CI check, and moves extensive design rationale into reorganized technical documentation.

• Adds a three-line comment-block limit and bans tracker references in source comments.
• Introduces scripts/check-comments.mjs and runs it through a dedicated CI job.
• Updates existing TypeScript comments to satisfy the policy.
• Reorganizes technical documentation around the affected subsystems.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

_{Reviews (5): Last reviewed commit: "Add to AGENTS" | Re-trigger Greptile}