Comment tense: state invariants rather than change history - #499
Merged
Conversation
Six comments and two test names describe the system as it is. Each held a sentence about what a prior arrangement did, which reads as current fact to anyone who did not watch it change; the hazard each was recording survives as the invariant it implies.
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.
Summary
Six comments and two test names in the activity-variable-contract work described what an earlier arrangement did rather than what the system does. A reader who did not watch the change takes that as a statement about the code in front of them, so each one is a small piece of misinformation with a long shelf life. The repository's documentation rule says as much: definitions, comments and commit subjects state the system as it is.
Nothing behaves differently. What each comment was really recording — a hazard, a reason a thing is arranged the way it is — survives, stated as the invariant it implies rather than as the story of how it was found.
What changes
The session-contract checker explained its no-progress finding by naming a smoke run that once claimed two activities and executed one. The invariant is the one that made that run possible: a driver reporting activities while the session stays put is indistinguishable from one that is working, so a run's own account of what it did is not evidence.
The smoke orchestrator carried three. Where sessions live, which said they used to live somewhere else; the point at which a refused transition goes unnoticed, which said that is when it used to happen; and the turn cap, which said an unresolved checkpoint is what made a refusal look like a success. All three state the standing condition instead.
The step-execution walk described itself as covering the two workflows whose step sequence changed, and both of its tests were named for the step each workflow no longer has. It covers the two workflows the policy matrix leaves out, and each test asserts the sequence its activity runs. The assertions are unchanged — a step id absent from an execution list is still a step id absent from an execution list.
Two smaller ones: the binding-fidelity gate reports an entry with no live finding behind it, and
resume_checkpointreads the most recent response because clearing the active checkpoint leaves no id to key by.Verification
npm run typecheck;npm run check:all— 30 guards, all passing; the three touched test files run green, including both renamed step-execution walks. Comments and test names only, so no behaviour is under test here that was not under test before.🤖 Generated with Claude Code