docs: state the definition of done and the sanctioned _notify exception - #110
Merged
Conversation
Two gaps in AGENTS.md that cost real rework. The CHANGELOG and docs obligations existed only in the PR checklist, which surfaces at review time rather than while the work happens -- so a change could reach a PR complete except for the two things a user actually reads. Adds a "Definition of done" section naming them, plus the llms-full.txt regeneration step and the tests-first expectation, and points at the PR template as the last gate rather than the first reminder. The "no silent exceptions" hard rule now has one deliberate, shipped counter-example: _notify.py logs and swallows a raising EventListener hook so observability cannot fail a protected call or kill a coordinator lane (#83). Recording it here keeps a future reader from "fixing" it, and bounds it so it is not read as licence to swallow elsewhere.
Coverage report
This PR does not seem to contain any modification to coverable code. |
Contributor
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
Two gaps in
AGENTS.mdthat have each cost rework already.1. The CHANGELOG and docs obligations lived only in the PR checklist. They surface at review time rather than while the work happens, so a change could arrive at a PR complete in every respect except the two things a user actually reads.
#108shipped itsCHANGELOGentry only because the template got opened at the end.Adds a Definition of done section naming them explicitly, together with the
llms-full.txtregeneration step (previously documented only indocs/CLAUDE.md, which an agent working ininterlock/never reads) and the tests-first expectation. The PR template is called out as the last gate, not the first reminder.2. The "no silent exceptions" hard rule now has a deliberate, shipped counter-example.
interlock/_notify.pylogs a raisingEventListenerhook with its traceback and swallows it, so observability cannot replace a protected result, mask a dependency's exception, or kill a coordinator lane (#83). Without that written down, the next reader — human or agent — sees a blindexcept Exceptionin a codebase whose style guide forbids exactly that, and "fixes" it.The note records the exception, states why it is not actually silent (
BaseExceptionstill propagates, the traceback is logged), and bounds it so it is not read as licence to swallow anywhere else.Checklist
uv run ruff format --checkanduv run ruff checkpassuv run mypyanduv run pyrightpassdocs/) for user-facing changes — n/a,AGENTS.mdis contributor-facingCHANGELOG.md[Unreleased]updated — n/a, no user-visible behaviour changeRelated issues
None — follow-up housekeeping after #108 and #109.