#973 Carry comment discipline in every agent that writes comments

[williamthorsen]

What

Fixes an issue where agents wrote source comments that argued the change to a reviewer, piled on counterfactuals, or narrated the code's history. Every agent that writes or judges a comment is now instructed on what belongs in one, including the orchestration agents, which previously carried no comment standard at all. The instruction now governs comment text wherever an agent writes it, including a replacement comment proposed inside a review finding. Reviews themselves are held to a narrower bar: They may ask for a comment only when it would record a constraint the code cannot show.

Why

Comment discipline is the largest live feedback cluster on record — roughly 38 reports over a month, seven of them high or critical — and the reports kept arriving eleven days after the doctrine was last rewritten. Rewriting the text again would not have helped: the doctrine sat behind an optional link, so the agents it governed frequently never opened it, and the orchestration agents that produce the most comments never reached it at all. A standard the writer does not hold cannot bind the writing, however well it is written.

Details

🐛 Bug fixes

• The comment doctrine is inlined into every skill that writes, revises, or judges comments, so it is in context at the moment a comment is written rather than behind a runtime link. The orchestration subagents pick it up through the skills already injected into their context, so none of them needed editing.
• The doctrine is scoped by destination rather than by channel: it follows comment text bound for source wherever it is authored, including text an agent proposes inside a review finding. Review comments themselves are not held to the source rules, which would be incoherent — rules that route rationale to the review channel cannot also forbid it there.
• Ten deletion rules and a checklist that restated them are consolidated into three tests, each carrying the phrasings that signal a violation and a worked before-and-after example. Two of the examples are drawn from observed failures: a comment addressed to the reviewer, and a comment padded with a counterfactual.
• Reviewers are directed to hold comment text they propose to the same audit as comment text they write, and to request a comment only when it would record a constraint the code cannot show.
• Keep-in-sync comments are no longer flagged as change narration. A comment recording that code must track an external table states an invariant the next reader needs.

🧪 Tests

• A regression test fails if a skill stops carrying the doctrine, if any file goes back to pointing at it instead of holding it, or if an agent that writes or judges code stops receiving a skill that carries it. The last of these guards the injection graph, which is the one place the design is genuinely fragile.
• Tests that shell out to git no longer read the developer's personal git configuration. A global commit.gpgsign made a test commit block on a passphrase prompt that no test process can answer, surfacing as an unexplained timeout rather than as a configuration problem.

📚 Documentation

• The convention governing where shared agent guidance lives now turns on when the agent needs the content rather than on what kind of content it is, so the next author is directed to inline a doctrine the agent applies as it writes rather than filing it as reference.

Closes #973

[github-actions]

Dependency audit

Production dependency audit passed.