From 8392c0502ca28fff0318048967080d80fec18d37 Mon Sep 17 00:00:00 2001 From: Jonathan Stokes Date: Mon, 7 Sep 2026 20:15:46 -0500 Subject: [PATCH 1/3] docs: a pull request opens as a draft and the hardware suite runs before it is marked ready contributing.md gains "Before you mark a pull request ready": the suite runs on the final commit, its totals go in the description, a contributor with no unit says so and a maintainer runs it, and a maintainer may waive it for a change that cannot reach the wire. CLAUDE.md carries the same rule for the agent, with why: the 2026-09-07 post-merge run found two stale records a green offline suite had passed. --- CLAUDE.md | 1 + contributing.md | 33 +++++++++++++++++++++++++++------ 2 files changed, 28 insertions(+), 6 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index eb7f794..bd21560 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -33,6 +33,7 @@ Read `docs/STEERING.md` before non-trivial work (new operations, transport or fr - Hardware sessions: quit Cortex Control first - it holds the HID interface exclusively. - Describe the protocol work as documenting the device's protocol as-is (recovered schema, observed traffic). Do not call it "reverse engineering" in docs, comments, commit messages, or issues. - Changed code under a path listed in `docs/STEERING.md` § Owned Paths? Diff and update STEERING/CLAUDE/ADR in the same PR. +- A pull request opens as a DRAFT (`gh pr create --draft`) and is marked ready only after `pytest tests/hardware --hardware` has run on its final commit and the report's totals are in the description - or the human has waived the run, in the description, in so many words. The offline suite and mypy are not a substitute: they prove the library agrees with itself, not that it agrees with the unit, and the 2026-09-07 post-merge run found two stale records that a green offline suite had passed. Never waive the run yourself, and never hand over a link to a pull request that has not been through this. `contributing.md` § "Before you mark a pull request ready" is the contributor-facing statement of the same rule. ## Do not diff --git a/contributing.md b/contributing.md index adfbbb6..bcc9209 100644 --- a/contributing.md +++ b/contributing.md @@ -16,12 +16,16 @@ You do **not** need to ask for access or to be added to the project first. The f 1. **Fork** this repository to your own account. 2. Create a **branch** for your change. -3. Commit your work, push it to your fork, and open a **pull request** against `main`. +3. Commit your work, push it to your fork, and open a **draft pull request** against + `main`. Mark it ready for review once the checks under "Before you mark a pull + request ready" below have run, or the description says why they could not. 4. A maintainer reviews it. Every change is reviewed and approved before it is merged, so please be patient and expect a round or two of feedback. -Continuous integration runs the test suite on every pull request. Please make sure it -is green - a red build will block the merge. +Continuous integration runs the offline suite and mypy on every pull request. Please +make sure it is green - a red build will block the merge. Green proves the library +agrees with itself; only a unit proves it agrees with the device, which is why the +hardware suite below is part of every pull request too. ## Development setup @@ -107,9 +111,26 @@ If your change touches the live device path and you want to verify it on a real (ADR-0020): record what you measure beside the 4.0.1 record in `docs/protocol.md`, dated and named by CorOS version, rather than in its place. -When you confirm behavior on hardware, say so in the pull request: which operation, -which CorOS version, and how you verified it (a read-back, or watching the unit). -That evidence is what keeps [docs/protocol.md](docs/protocol.md) trustworthy. +### Before you mark a pull request ready + +A pull request opens as a draft and is marked ready for review only after the +hardware suite has run on its final commit: + +```bash +pytest tests/hardware --hardware +``` + +Put the report's totals line and its per-operation summary in the pull request +description, with the CorOS version of the unit. That record is what keeps +[docs/protocol.md](docs/protocol.md) trustworthy: a read-back on a unit is the only +evidence that a change did what it says, and the offline suite cannot supply it. + +If you have no unit, say so in the description and mark the pull request ready +anyway; a maintainer runs the suite before merging. If the change cannot reach the +wire (documentation, packaging), a maintainer may waive the run, in the description. +Either way the description says which it was: run, with the numbers, or not run, +with the reason. A description that says nothing about hardware is still a draft, +whatever the button says. ## Adding a device profile From f21d6db093d24ed98f5f746e665fec848e7d0eaf Mon Sep 17 00:00:00 2001 From: Jonathan Stokes Date: Mon, 7 Sep 2026 21:00:28 -0500 Subject: [PATCH 2/3] docs: the PR template carries the Hardware section, the report is named as pytest prints it, and the rule's evidence is PR #53 Triage of the draft found: the template still carried the old optional-hardware rule; "totals line" named output only PR #53's branch prints; the two files disagreed on the no-unit state; nothing tied the run to a commit; the section's parent intro still said "if you want to"; the prerequisites lived elsewhere; "only evidence" overclaimed and dropped the manual read-back ask; and STEERING's pattern row still said hardware verification is manual via examples/. --- .github/PULL_REQUEST_TEMPLATE.md | 15 ++++++++++++--- CLAUDE.md | 2 +- contributing.md | 27 +++++++++++++++++++-------- docs/STEERING.md | 23 ++++++++++++++++++++++- 4 files changed, 54 insertions(+), 13 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 19a9943..8e5d509 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -8,12 +8,21 @@ ## Testing - + + +## Hardware + + ## Checklist +- [ ] Opened as a draft; the Hardware section above is filled in before marking ready - [ ] Tests pass locally (`python -m pytest -q`) - [ ] Added or updated tests for the change - [ ] Updated documentation if behavior or the public API changed diff --git a/CLAUDE.md b/CLAUDE.md index bd21560..606cccf 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -33,7 +33,7 @@ Read `docs/STEERING.md` before non-trivial work (new operations, transport or fr - Hardware sessions: quit Cortex Control first - it holds the HID interface exclusively. - Describe the protocol work as documenting the device's protocol as-is (recovered schema, observed traffic). Do not call it "reverse engineering" in docs, comments, commit messages, or issues. - Changed code under a path listed in `docs/STEERING.md` § Owned Paths? Diff and update STEERING/CLAUDE/ADR in the same PR. -- A pull request opens as a DRAFT (`gh pr create --draft`) and is marked ready only after `pytest tests/hardware --hardware` has run on its final commit and the report's totals are in the description - or the human has waived the run, in the description, in so many words. The offline suite and mypy are not a substitute: they prove the library agrees with itself, not that it agrees with the unit, and the 2026-09-07 post-merge run found two stale records that a green offline suite had passed. Never waive the run yourself, and never hand over a link to a pull request that has not been through this. `contributing.md` § "Before you mark a pull request ready" is the contributor-facing statement of the same rule. +- A pull request opens as a DRAFT (`gh pr create --draft`). It is marked ready only after `pytest tests/hardware --hardware` has run on its final commit, with the commit hash, pytest's summary line and the `operations on ...` block in the description - or after the human has waived the run explicitly in the description, which they may do for a change that cannot reach the wire. The offline suite and mypy are not a substitute: they prove the library agrees with itself, not that it agrees with the unit. PR #53 is the evidence: the 2026-09-07 post-merge run found two stale records that a green offline suite had passed. Never waive the run yourself, and never present a pull request as ready that has not been through this. `contributing.md` § "Before you mark a pull request ready" states the rule for contributors, with one more state for a contributor who has no unit (say so, mark ready, a maintainer runs it before merging); you always work where the unit is, so that state is not yours. ## Do not diff --git a/contributing.md b/contributing.md index bcc9209..4e8ba8a 100644 --- a/contributing.md +++ b/contributing.md @@ -22,7 +22,8 @@ You do **not** need to ask for access or to be added to the project first. The f 4. A maintainer reviews it. Every change is reviewed and approved before it is merged, so please be patient and expect a round or two of feedback. -Continuous integration runs the offline suite and mypy on every pull request. Please +Continuous integration runs the offline suite, mypy and a packaging build on every +pull request. Please make sure it is green - a red build will block the merge. Green proves the library agrees with itself; only a unit proves it agrees with the device, which is why the hardware suite below is part of every pull request too. @@ -99,7 +100,9 @@ Two contracts the tests protect, worth knowing before you change import structur ## Working with hardware -If your change touches the live device path and you want to verify it on a real unit: +Every pull request runs the hardware suite before it is marked ready (see "Before +you mark a pull request ready" below). To run it, or to verify anything else on a +real unit: - Connect the Quad Cortex over **USB**. (Wi-Fi may stay on; it makes no difference.) - **Quit Cortex Control first.** It holds the USB interface exclusively, so nothing @@ -120,17 +123,25 @@ hardware suite has run on its final commit: pytest tests/hardware --hardware ``` -Put the report's totals line and its per-operation summary in the pull request -description, with the CorOS version of the unit. That record is what keeps -[docs/protocol.md](docs/protocol.md) trustworthy: a read-back on a unit is the only -evidence that a change did what it says, and the offline suite cannot supply it. +The prerequisites are the ones above plus the `hid` package from "Development +setup". On macOS prefix the command with `DYLD_LIBRARY_PATH=/opt/homebrew/lib`, and +on a unit other than CorOS 4.0.1 add `--profile` (see "Adding a device profile"). + +Put four things in the pull request description: the short commit hash the run was +made on, the CorOS version of the unit, pytest's own summary line (`N passed, N +failed, N skipped`) and the `operations on ...` block the suite prints after it. If +your change adds or alters an operation, also say how you verified that operation on +the unit (a read-back, or watching the screen), because the suite measures only the +operations a hardware test names. This record is the evidence this project keeps: +the offline suite proves the library agrees with itself, and a unit is what proves +it agrees with the device. If you have no unit, say so in the description and mark the pull request ready anyway; a maintainer runs the suite before merging. If the change cannot reach the wire (documentation, packaging), a maintainer may waive the run, in the description. Either way the description says which it was: run, with the numbers, or not run, -with the reason. A description that says nothing about hardware is still a draft, -whatever the button says. +with the reason. A description that says nothing about hardware is not ready for +review, whatever GitHub shows. ## Adding a device profile diff --git a/docs/STEERING.md b/docs/STEERING.md index 69e123d..9c2cd81 100644 --- a/docs/STEERING.md +++ b/docs/STEERING.md @@ -56,7 +56,7 @@ The model layer holds the state (design in [`domain-model.md`](domain-model.md) | Pattern | What | Why (or `see ADR-000N`) | Canonical example | When the pattern does not apply | |---------|------|-------------------------|-------------------|----------------------------------| | Layered message flow | New operations are a registry entry plus a thin `QuadCortex` method that builds a protobuf and picks `send`/`request`/`await_broadcast` | Wire concerns stay below `client.py`, which keeps the whole API testable with a fake transport (see ADR-0002) | `QuadCortex.switch_scene` in `pyquadcortex/protocol/client.py` | `cli.py`'s `version` subcommand deliberately bypasses the connect handshake (`_open_unconnected`) | -| Fake-per-layer offline tests | Each layer has a purpose-built double: golden captured frames for `framing`, `FakeHid` for `transport`, `FakeTransport` for `client` | see ADR-0002 | `FakeTransport` in `tests/test_client.py` | Hardware verification happens manually via `examples/`, outside the suite | +| Fake-per-layer offline tests | Each layer has a purpose-built double: golden captured frames for `framing`, `FakeHid` for `transport`, `FakeTransport` for `client` | see ADR-0002 | `FakeTransport` in `tests/test_client.py` | Hardware verification is `tests/hardware` behind `--hardware` (ADR-0005), run on every pull request before it is marked ready (contributing.md) | | Evidence-bearing docstrings | Each operation's docstring states what is confirmed on hardware vs inferred from the schema | The device gives no errors for wrong writes, so recorded evidence is the only trail | `QuadCortex.read_preset` in `pyquadcortex/protocol/client.py` | Non-protocol helpers (pure functions) carry ordinary docstrings | | Keyed grid edits | Mutations are row/column-keyed `Grid` UPDATEs | The device applies grid updates by key; wholesale preset writes are silently ignored (see [`architecture.md`](architecture.md), "write_preset is a trap") | `QuadCortex.set_bypass` in `pyquadcortex/protocol/client.py` | Read paths, and non-grid operations | | One translation boundary | Screen values become wire values in exactly one PACKAGE, and a source-reading test proves no other module in the package does it - the whole package outside `protocol/`, not just `device/`. The exemption covers a directory, so a test names the package's modules and a new one has to come through that list | An off-by-one row is silent - the write lands on a real row and reads back perfectly - so a convention cannot be trusted to hold (design principle 5 in [`domain-model.md`](domain-model.md)) | `pyquadcortex/device/translate/` | The protocol layer, which keeps its zero-based COORDINATES. Its scales come from the catalog, and quoting the device's own units is not translating - see ADR-0016 | @@ -138,6 +138,27 @@ Single-device, single-connection USB HID at interactive rates (129-byte reports) ## Change Log +### 2026-09-07 - A pull request is a draft until the hardware suite has run on it + +**What changed:** `contributing.md` gains "Before you mark a pull request ready": +a pull request opens as a draft, the hardware suite runs on its final commit, and +the description records the commit hash, the CorOS version, pytest's summary line +and the `operations on ...` block. A contributor with no unit says so and a +maintainer runs the suite before merging; a maintainer may waive the run, in the +description, for a change that cannot reach the wire. The pull request template +gained a Hardware section with those three states, `CLAUDE.md` states the rule for +the agent, and the section 5 pattern row that said hardware verification happens +manually via `examples/` now names the suite. + +**Why:** the 2026-09-07 post-merge run (PR #53) found two stale records that a +green offline suite had passed, and two pull requests that week were marked ready +without the run. A rule that lives only in memory is skipped under time pressure; +one that lives in the template and the contributor guide is not. + +**Scope of impact:** +- **Updated:** contributing.md, CLAUDE.md, .github/PULL_REQUEST_TEMPLATE.md, STEERING.md section 5 +- **Not updated (intentionally):** ADR.md - this is process, not an architectural decision; ci.yml - nothing enforces the description's contents mechanically yet + ### 2026-09-06 - The profile seam is built (ADR-0020) **What changed:** `connect()` reads the unit's `Version` before the handshake, From 769494116daed3a55bba52b8c59ff250b9ed069f Mon Sep 17 00:00:00 2001 From: Jonathan Stokes Date: Mon, 7 Sep 2026 21:13:24 -0500 Subject: [PATCH 3/3] docs: --profile is for a unit the registry refuses, the report is named in the order pytest prints it, and the agent's rule asks for the CorOS version too --- .github/PULL_REQUEST_TEMPLATE.md | 4 ++-- CLAUDE.md | 2 +- contributing.md | 12 +++++++----- docs/STEERING.md | 4 ++-- 4 files changed, 12 insertions(+), 10 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 8e5d509..4ffb8e2 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -15,9 +15,9 @@ ## Checklist diff --git a/CLAUDE.md b/CLAUDE.md index 606cccf..3d6e866 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -33,7 +33,7 @@ Read `docs/STEERING.md` before non-trivial work (new operations, transport or fr - Hardware sessions: quit Cortex Control first - it holds the HID interface exclusively. - Describe the protocol work as documenting the device's protocol as-is (recovered schema, observed traffic). Do not call it "reverse engineering" in docs, comments, commit messages, or issues. - Changed code under a path listed in `docs/STEERING.md` § Owned Paths? Diff and update STEERING/CLAUDE/ADR in the same PR. -- A pull request opens as a DRAFT (`gh pr create --draft`). It is marked ready only after `pytest tests/hardware --hardware` has run on its final commit, with the commit hash, pytest's summary line and the `operations on ...` block in the description - or after the human has waived the run explicitly in the description, which they may do for a change that cannot reach the wire. The offline suite and mypy are not a substitute: they prove the library agrees with itself, not that it agrees with the unit. PR #53 is the evidence: the 2026-09-07 post-merge run found two stale records that a green offline suite had passed. Never waive the run yourself, and never present a pull request as ready that has not been through this. `contributing.md` § "Before you mark a pull request ready" states the rule for contributors, with one more state for a contributor who has no unit (say so, mark ready, a maintainer runs it before merging); you always work where the unit is, so that state is not yours. +- A pull request opens as a DRAFT (`gh pr create --draft`). It is marked ready only after `pytest tests/hardware --hardware` has run on its final commit, with the commit hash, the unit's CorOS version, the `operations on ...` block and pytest's last line in the description - or after the human has waived the run explicitly in the description, which they may do for a change that cannot reach the wire. The offline suite and mypy are not a substitute: they prove the library agrees with itself, not that it agrees with the unit. PR #53 is the evidence: the 2026-09-07 post-merge run found two stale records that a green offline suite had passed. Never waive the run yourself, and never present a pull request as ready that has not been through this. `contributing.md` § "Before you mark a pull request ready" states the rule for contributors, with one more state for a contributor who has no unit (say so, mark ready, a maintainer runs it before merging); you always work where the unit is, so that state is not yours. ## Do not diff --git a/contributing.md b/contributing.md index 4e8ba8a..3dcab7c 100644 --- a/contributing.md +++ b/contributing.md @@ -123,13 +123,15 @@ hardware suite has run on its final commit: pytest tests/hardware --hardware ``` -The prerequisites are the ones above plus the `hid` package from "Development -setup". On macOS prefix the command with `DYLD_LIBRARY_PATH=/opt/homebrew/lib`, and -on a unit other than CorOS 4.0.1 add `--profile` (see "Adding a device profile"). +The prerequisites are the ones above plus the hidapi library from "Development +setup". On macOS prefix the command with `DYLD_LIBRARY_PATH=/opt/homebrew/lib`. On +a unit the registry refuses (a firmware no profile has measured, or a Mini) add +`--profile` with the class to measure as (see "Adding a device profile"). Put four things in the pull request description: the short commit hash the run was -made on, the CorOS version of the unit, pytest's own summary line (`N passed, N -failed, N skipped`) and the `operations on ...` block the suite prints after it. If +made on, the CorOS version of the unit, the `operations on ...` block the suite +prints, and pytest's own last line after it (the one with the pass, fail, error and +skip counts). If your change adds or alters an operation, also say how you verified that operation on the unit (a read-back, or watching the screen), because the suite measures only the operations a hardware test names. This record is the evidence this project keeps: diff --git a/docs/STEERING.md b/docs/STEERING.md index 9c2cd81..b11fc33 100644 --- a/docs/STEERING.md +++ b/docs/STEERING.md @@ -119,7 +119,7 @@ None yet. Protocol unknowns (the splitter write path, the IR import payload form - **PyPI** for releases (process and credentials handling in [`releasing.md`](releasing.md)) - **GitHub Actions** for the offline suite on every PR (`.github/workflows/ci.yml`) - **hidapi** as the OS-level native library on any machine that talks to hardware -- **One physical Quad Cortex** (CorOS 4.0.1 / d14e) - the scarce resource; hardware verification is manual and serialized on it +- **One physical Quad Cortex** (CorOS 4.0.1 / d14e) - the scarce resource; the hardware suite runs on it before every pull request is marked ready, so runs are serialized ### Workload characteristics @@ -156,7 +156,7 @@ without the run. A rule that lives only in memory is skipped under time pressure one that lives in the template and the contributor guide is not. **Scope of impact:** -- **Updated:** contributing.md, CLAUDE.md, .github/PULL_REQUEST_TEMPLATE.md, STEERING.md section 5 +- **Updated:** contributing.md, CLAUDE.md, .github/PULL_REQUEST_TEMPLATE.md, STEERING.md sections 5 and 10 - **Not updated (intentionally):** ADR.md - this is process, not an architectural decision; ci.yml - nothing enforces the description's contents mechanically yet ### 2026-09-06 - The profile seam is built (ADR-0020)