From 89eb2e28ac248eac7301ab03f22fb85d4e085b3a Mon Sep 17 00:00:00 2001 From: cayossarian <23534755+cayossarian@users.noreply.github.com> Date: Fri, 9 Oct 2026 11:06:13 -0700 Subject: [PATCH 1/2] docs: record lessons from review in AGENTS.md Rules that review has already had to enforce once, here or in the emitter this library is tested against: prove a test by breaking what it guards, treat docstrings, the README and the changelog as shipped, keep the public surface complete and free of dormant parameters, read captured data as published, check against every capture, cite the specification, and report only results that were run. --- AGENTS.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index b78ff28..e0a7616 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -59,3 +59,20 @@ Captures are byte copies and must stay that way: The schema-1 reference tree (`packages/schema-1/src/span_panel_api_schema_1/reference/parent_child_tree.json`) is package data, produced by `scripts/capture_parent_child_reference.py` from `scripts/reference_panel.yaml` with the pinned emitter; DEVELOPMENT.md, "Regenerating a vendored capture", has the procedure. Change the manifest, never the output, and keep every circuit inside the position range `PANEL_POSITIONS_BY_MODEL` gives the panel's model: the adapter reports the table's range and warns once for a panel whose circuits fall outside it. A changed capture is a release of the adapter that ships it (RELEASE.md). + +## Lessons from review + +Each of these was a defect that review has already caught at least once, in this repository or in the emitter it is tested against. + +- **Prove a test or a guard by breaking what it guards.** Revert the fix or mutate the code and confirm the test fails; a guard that survives every mutation guards nothing. Assert what a consumer can observe, the snapshot value or the published outcome, + not an internal step. +- **A test that keeps documentation runnable reads the documentation.** A hand-copied recipe pins the sequence but lets the document rot. +- **Docstrings and the README ship.** A docstring is in the wheel and is what `help()` and an IDE show, and a package README is its PyPI page. A recipe in either runs as written and describes every path the code has. +- **A changelog is checked, not just written.** A `Fixed` entry is for a defect a released version had, not a revision between drafts. Check where each entry lands, since a new heading inserted above an entry re-files it with no deletion in the diff, and + re-derive every count or list against the source at the tag. +- **The public surface is complete and nothing more.** Every type a public signature names is exported and recorded in `tests/test_public_api_unchanged.py`. Do not add a parameter or flag that gates nothing yet; a dormant surface reads as a feature and has + to be un-shipped later. +- **Read data as published.** A `null` or empty value in a capture means unpublished, never zero. A predicate that reads declared metadata refuses what it cannot interpret instead of guessing. +- **One capture is not the firmware.** Check a change against every capture available; panels on the same firmware release do not always publish a value in the same form. +- **Cite the specification.** Where the eBus specification and a migration guide disagree, the specification wins, and a rule it states is implemented against the signal it names. +- **Measure claims.** A statement about a real panel, broker or built artifact is checked there, and a result is reported only after it has actually been run. From 14c763ffe40de5d6d1e0e052a7544957fbce57e3 Mon Sep 17 00:00:00 2001 From: cayossarian <23534755+cayossarian@users.noreply.github.com> Date: Fri, 9 Oct 2026 11:15:44 -0700 Subject: [PATCH 2/2] docs: keep only the verification lessons in AGENTS.md What a change must do is settled in its specification; AGENTS.md keeps the checks made while writing and verifying it: break what a test guards, read the docs a docs test protects, check the changelog as it ships, read data as published, check every capture, and measure claims. --- AGENTS.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e0a7616..efea381 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -62,17 +62,12 @@ warns once for a panel whose circuits fall outside it. A changed capture is a re ## Lessons from review -Each of these was a defect that review has already caught at least once, in this repository or in the emitter it is tested against. +What a change must do is decided before it is written; these are the checks made while writing and verifying it. Each was a defect that review has already caught at least once, in this repository or in the emitter it is tested against. - **Prove a test or a guard by breaking what it guards.** Revert the fix or mutate the code and confirm the test fails; a guard that survives every mutation guards nothing. Assert what a consumer can observe, the snapshot value or the published outcome, not an internal step. - **A test that keeps documentation runnable reads the documentation.** A hand-copied recipe pins the sequence but lets the document rot. -- **Docstrings and the README ship.** A docstring is in the wheel and is what `help()` and an IDE show, and a package README is its PyPI page. A recipe in either runs as written and describes every path the code has. -- **A changelog is checked, not just written.** A `Fixed` entry is for a defect a released version had, not a revision between drafts. Check where each entry lands, since a new heading inserted above an entry re-files it with no deletion in the diff, and - re-derive every count or list against the source at the tag. -- **The public surface is complete and nothing more.** Every type a public signature names is exported and recorded in `tests/test_public_api_unchanged.py`. Do not add a parameter or flag that gates nothing yet; a dormant surface reads as a feature and has - to be un-shipped later. +- **Check the changelog as it will ship.** Check where each entry lands, since a new heading inserted above an entry re-files it with no deletion in the diff, and re-derive every count or list against the source at the tag. - **Read data as published.** A `null` or empty value in a capture means unpublished, never zero. A predicate that reads declared metadata refuses what it cannot interpret instead of guessing. - **One capture is not the firmware.** Check a change against every capture available; panels on the same firmware release do not always publish a value in the same form. -- **Cite the specification.** Where the eBus specification and a migration guide disagree, the specification wins, and a rule it states is implemented against the signal it names. - **Measure claims.** A statement about a real panel, broker or built artifact is checked there, and a result is reported only after it has actually been run.