Skip to content

docs(goal): tighten and cut comments across the agent packages - #698

Merged
ion-alpha-dev merged 6 commits into
mainfrom
docs/comments-goal-mission
Nov 15, 2026
Merged

ion-alpha-dev merged 6 commits into
mainfrom
docs/comments-goal-mission

Conversation

@ion-alpha-dev

Copy link
Copy Markdown
Collaborator

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 doc readers 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 .go file against the merge base (comments skipped, directive comments such as //flynn: and //nolint compared in order) reports 80 of 80 files identical. ./dev/lint reports 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 UnitSpawner Spawn doc, the write-window reason in persistUnits, 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.go file changed and no baseline count was raised.

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

codecov Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 90.62500% with 3 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
goal/worker.go 71.42% 2 Missing ⚠️
goal/reconciler.go 83.33% 1 Missing ⚠️

📢 Thoughts on this report? Let us know!

@ion-alpha-dev
ion-alpha-dev merged commit 2ae3912 into main Nov 15, 2026
34 checks passed
@ion-alpha-dev
ion-alpha-dev deleted the docs/comments-goal-mission branch November 15, 2026 10:17
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 15, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant