[Coly010]

What changed

• Comment policy. The root AGENTS.md gains a ## Comments section: comments state the why the code cannot carry, exported symbols get a one-sentence JSDoc summary, inline comments stay at one to three lines, and provenance (Go file.go:NN citations, ticket and PR numbers, review-round notes, "verified empirically" trails), narration, emphasis, section banners, and meta-commentary are out. Directive comments and tool-facing JSDoc tags (@public for knip, @internal, @deprecated) are kept verbatim. apps/cli/AGENTS.md cross-references it from its Go-parity guidance.
• Repo-wide comments-only pass applying that policy across apps/cli, packages/config, packages/stack, apps/cli-e2e, tooling scripts, GitHub workflow YAML, and JSONC configs. Comment lines drop from roughly 60.5k to 31.4k, and non-test source goes from about a 31% comment-to-code ratio to about 18%. Comments that documented a genuine invariant, an external quirk, or a decision that would otherwise read as a bug were kept and compressed; everything that was an author's audit trail was removed.

Why

The existing comments were technically accurate but written as an audit trail rather than for the next reader: multi-paragraph blocks citing Go source line numbers, ticket IDs, review rounds, and empirical verification steps. At that density a human skips them entirely, which defeats the point, and they inflate the token cost of every file an agent reads. The policy exists so the pattern does not grow back.

Reviewer notes

• No code changes are intended anywhere. Every changed TypeScript file was checked by parsing both versions and comparing the reprinted, comment-free output against develop; YAML and JSONC files were parsed and compared as data. One @public JSDoc tag that knip depends on was caught and kept by this check.
• Commits are organised per directory shard, so reviewing commit by commit is practical; the policy is the first commit, and the final commits are small follow-up tightenings plus a merge of develop.
• Test names were out of scope because they are strings, and many still carry (Go parity), PR-number, and review-ID suffixes. That is queued as a separate change.
• packages/config ships its compiled output with tsc, so its published JavaScript carried the full comment volume; the CLI binary was unaffected because bun build strips comments.