Repository navigation
docs(goal): tighten and cut comments across the agent packages - #698
Merged
Merged
Conversation
Rewrite the comments in goal, mission, governed, evidence, budget, brakes, allowance, dispatch, reconcile, driver, refusal and progress. Each comment now states an invariant, a failure it guards against, an ordering reason, a unit or a contract, and nothing the code already says. Comments that restated the code are deleted, and every exported name keeps a one-line doc. The change is comment-only: with comments dropped, the token stream of every changed file is identical to the base, and directive comments are unchanged. The comment baseline loses the 23 lines for violations that no longer exist. Signed-off-by: Ion Alpha <contact@ionalpha.io>
Remove the comment_baseline.txt lines for comment blocks in the goal, mission, governed, evidence, brakes, allowance, driver, reconcile, refusal and progress packages that no longer violate the gate. Signed-off-by: Ion Alpha <contact@ionalpha.io>
Codecov Report❌ Patch coverage is
📢 Thoughts on this report? Let us know! |
Signed-off-by: Ion Alpha <contact@ionalpha.io>
Signed-off-by: Ion Alpha <contact@ionalpha.io>
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 subscribe to this conversation on GitHub.
Already have an account?
Sign in.
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.
What
Rewrites the comments in goal, mission, governed, evidence, budget, brakes, allowance, dispatch, reconcile, driver, refusal and progress. Production comment lines drop from about 4,910 to 2,183. Comments that restated the code are deleted, the rest are shortened, and 23 now-passing entries are removed from
internal/rigor/testdata/comment_baseline.txt.Why
Doc comments are the published API reference. These packages carried narration, history and restatement that
go docreaders had to wade through, and the comment gate's baseline listed their violations. Each kept comment now states an invariant, a failure it guards against, an ordering reason, a unit or range, or a security or concurrency contract.How to verify
Only comments change. A token-stream comparison of every changed
.gofile against the merge base (comments skipped, directive comments such as//flynn:and//nolintcompared in order) reports 80 of 80 files identical../dev/lintreports 0 issues,go test ./internal/rigor/...passes (comment gate and doc-link resolution), and race tests on the twelve packages pass.Notes for reviewers
The longest remaining comments are on the governance contract in the
UnitSpawnerSpawndoc, the write-window reason inpersistUnits, the gate ordering in the reconciler's advance, and the ledger claim hold. They carry security and concurrency reasoning, and none is near the 14-line block limit. No_test.gofile changed and no baseline count was raised.