docs: record the registry-guard and issue-amendment conventions in AGENTS.md - #580
Merged
Merged
Conversation
…a PR overtakes Three conventions earned on #534: - Adding an entry to a registry (CliDispatcher.Commands, AuditActions, a mirrored enum) means finding its guards by grepping the registry's readers. A recalled list missed OneShotVerbMinimalConfigTests, which one grep returns. - A guard that inspects call-site syntax has to be read before the call site is authored: AuditVocabularyCoverageTests rejects an action forwarded through a parameter, so the obvious refactor is a build failure, not a review comment. - A PR that ships work an open issue still claims amends that issue in the same PR. #532 shipped AccountSuspensionService while #534 went on claiming it, so #534 was planned against a body that was wrong in most of its bullets.
|
You have reached your Codex usage limits for security reviews. Please try again later. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three conventions earned while shipping #534 (PR #573). No code, no behaviour change.
1. Adding an entry to a registry? Find its guards by grepping the registry's READERS, never by recall. (
Writing a guard)Adding the two lifecycle verbs to
CliDispatcher.Commands, a recalled list of guards producedCliDispatcherTestsandProcessRoleRegistryTestsand missedOneShotVerbMinimalConfigTests, which walksProcessRoles.OneShotVerbsand fails any verb without a minimal-config case. It surfaced at the full-suite step and cost a dispatch round trip. One grep returns all three. This is the section's existing "walk everything, exclude deliberately" rule turned on the guards themselves.2. A guard that inspects call-site SYNTAX has to be read before the call site is authored. (
Writing a guard)AuditVocabularyCoverageTestsaccepts onlyAuditActions.Xor a ternary of two as the action argument toIAuditWriter.WriteAsync, and fails closed on anything else. The obvious refactor — forwarding the action through a shared private helper's parameter — is a build failure, not a review comment, and the rule is not inferable from the code being guarded. #534 caught it in a pre-dispatch review and used a ternary instead.3. A PR that ships work another OPEN issue claims amends that issue in the same PR. (
Git / PR workflow)#532 shipped
AccountSuspensionServicein full — its own header naming #534 as the caller it was waiting for — while #534's body went on listing that service's revocation, epoch bump and stamp rotation as its own scope. #534 was then picked up months later and planned, sized and routed against a description wrong in most of its bullets. The rule keeps the body as written for history and requires an amendment note pointing at a comment stating what shipped, what remains, and which acceptance criteria the shipped code deliberately does not meet — that last part being how #579 got filed instead of being left to rot in a closed issue.Each is a plain convention with no decision-record link, per this file's own rule: they have not yet cost a shipped defect, only review rounds and a round trip.