From 468f96f438cc01e3040b9a437578df135e8b5c49 Mon Sep 17 00:00:00 2001 From: Scott Jones Date: Mon, 5 Oct 2026 10:22:10 -0400 Subject: [PATCH 1/5] Add test rules learned from the Touch ID work to AGENTS.md Reviews of the Touch ID branches kept finding the same kinds of slip: a test that passed only because the Mac running it had Omarchy installed, a detection path that could hide the one before it, an integration test that skipped silently in CI, a green run that never reached the code, a udev add rule that missed the upgrade installing it, and a once-only invitation that could fire before its dependencies shipped. AGENTS.md now says so. Co-Authored-By: Claude Opus 5.5 (1M context) --- AGENTS.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 421e5ee..92e2984 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,6 +17,15 @@ CI rejects files outside these, the root documents and `.github/`. - Run the suite of every package you change, and `test/integration/all` with `OMARCHY_TEST_RUNTIME` set when a change touches what the runtime reads. - `omarchy-mac-boot` covers what stays installed and runs again at updates. What runs once to install a Mac belongs in omacom/omarchy-mac-installer. - Change the manual in the same commit as the behaviour it describes. +- A udev rule that acts on `add` also gets a pacman hook that does the same work, skipped in a chroot or an unbooted root: on the upgrade that installs it the device already exists, so no `add` comes. +- A step the owner sees only once, such as an invitation, ships only after everything it leads to is published. + +## Tests + +- A test passes or fails the same on every machine. It never reads what the machine running it has installed: the platform root `/usr/share/omarchy-platform`, `/usr/bin/omarchy-*`, `/sys` or running services. Stage into a temporary root, point copies at fixtures, and stub the runtime's commands; run `systemd-analyze verify` with `--root` at the staged package. A pass on a Mac with Omarchy installed says nothing about CI. +- When a change adds a detection path or a fallback, test the inverse too: the new path never hides what the old one found. +- A test that needs something the runtime gained at a later commit moves `test/integration/runtime` to that commit; it does not skip while the pinned runtime lacks it. +- Before calling a change tested, check that CI ran it: a skipped test, or a job that failed before reaching the tests, is not a pass. ## Style From 0fc00085bb12e44967b8319c86e4ea25adde1eae Mon Sep 17 00:00:00 2001 From: Scott Jones Date: Mon, 5 Oct 2026 18:28:19 -0400 Subject: [PATCH 2/5] Narrow the AGENTS.md hook, invitation, host-read and pin rules Wording from Marcelo's review, so agents don't over-apply them: the hook rule covers only an add that must reach a device already present, and the hook never fails the transaction; the once-only rule is about invitations, not first boot; tests may read /sys fixtures, never the host's; and the pin rule doesn't touch the skip when OMARCHY_TEST_RUNTIME is unset. Co-Authored-By: Claude Opus 5.5 (1M context) --- AGENTS.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 92e2984..0f21c27 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,14 +17,14 @@ CI rejects files outside these, the root documents and `.github/`. - Run the suite of every package you change, and `test/integration/all` with `OMARCHY_TEST_RUNTIME` set when a change touches what the runtime reads. - `omarchy-mac-boot` covers what stays installed and runs again at updates. What runs once to install a Mac belongs in omacom/omarchy-mac-installer. - Change the manual in the same commit as the behaviour it describes. -- A udev rule that acts on `add` also gets a pacman hook that does the same work, skipped in a chroot or an unbooted root: on the upgrade that installs it the device already exists, so no `add` comes. -- A step the owner sees only once, such as an invitation, ships only after everything it leads to is published. +- A udev `add` action that must reach a device already present also gets a pacman hook that does that work on install and upgrade, since on the upgrade that installs the rule no `add` comes. The hook exits 0 in a chroot or an unbooted root, and never fails the transaction. An `add` that should only run when the device appears, such as one tied to the boot splash, does not. +- An invitation the owner sees only once ships only after everything it leads to is published. ## Tests -- A test passes or fails the same on every machine. It never reads what the machine running it has installed: the platform root `/usr/share/omarchy-platform`, `/usr/bin/omarchy-*`, `/sys` or running services. Stage into a temporary root, point copies at fixtures, and stub the runtime's commands; run `systemd-analyze verify` with `--root` at the staged package. A pass on a Mac with Omarchy installed says nothing about CI. +- A test passes or fails the same on every machine. It never reads the host's `/usr/share/omarchy-platform`, installed `omarchy-*` commands, `/sys` or running services: stage into a temporary root, point copies at fixtures, and stub the runtime's commands. Run `systemd-analyze verify` with `--root` at the staged package. A pass on a Mac with Omarchy installed says nothing about CI. - When a change adds a detection path or a fallback, test the inverse too: the new path never hides what the old one found. -- A test that needs something the runtime gained at a later commit moves `test/integration/runtime` to that commit; it does not skip while the pinned runtime lacks it. +- A test that needs something the runtime gained at a later commit moves `test/integration/runtime` to that commit; it does not skip because that pin lacks it. - Before calling a change tested, check that CI ran it: a skipped test, or a job that failed before reaching the tests, is not a pass. ## Style From 87dd3d52bd854a27159e259b40026c00291de811 Mon Sep 17 00:00:00 2001 From: Marcelo Alcantara Date: Fri, 9 Oct 2026 11:32:09 +1000 Subject: [PATCH 3/5] Keep the real commands under test in the AGENTS.md test rule --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 0f21c27..588dfb2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,7 +22,7 @@ CI rejects files outside these, the root documents and `.github/`. ## Tests -- A test passes or fails the same on every machine. It never reads the host's `/usr/share/omarchy-platform`, installed `omarchy-*` commands, `/sys` or running services: stage into a temporary root, point copies at fixtures, and stub the runtime's commands. Run `systemd-analyze verify` with `--root` at the staged package. A pass on a Mac with Omarchy installed says nothing about CI. +- A test passes or fails the same on every machine. It never reads the host's `/usr/share/omarchy-platform`, installed `omarchy-*` commands, `/sys` or running services: stage into a temporary root, point copies at fixtures, and stub external dependencies, keeping the real commands under test. Run `systemd-analyze verify` with `--root` at the staged package. A pass on a Mac with Omarchy installed says nothing about CI. - When a change adds a detection path or a fallback, test the inverse too: the new path never hides what the old one found. - A test that needs something the runtime gained at a later commit moves `test/integration/runtime` to that commit; it does not skip because that pin lacks it. - Before calling a change tested, check that CI ran it: a skipped test, or a job that failed before reaching the tests, is not a pass. From 555acba97ad24fa224ff9ae694c1d65e1f903f73 Mon Sep 17 00:00:00 2001 From: Scott Jones Date: Fri, 9 Oct 2026 20:23:06 -0400 Subject: [PATCH 4/5] Define the invitation in the AGENTS.md once-only rule Marcelo noted "invitation" is defined nowhere else in the repo, so an agent could not act on the rule. It now names the one-time post-update fingerprint setup offer and the change that triggers it, a new entry in fingerprint-readers. Co-Authored-By: Claude Opus 5.5 (1M context) --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 588dfb2..28afcb1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,7 +18,7 @@ CI rejects files outside these, the root documents and `.github/`. - `omarchy-mac-boot` covers what stays installed and runs again at updates. What runs once to install a Mac belongs in omacom/omarchy-mac-installer. - Change the manual in the same commit as the behaviour it describes. - A udev `add` action that must reach a device already present also gets a pacman hook that does that work on install and upgrade, since on the upgrade that installs the rule no `add` comes. The hook exits 0 in a chroot or an unbooted root, and never fails the transaction. An `add` that should only run when the device appears, such as one tied to the boot splash, does not. -- An invitation the owner sees only once ships only after everything it leads to is published. +- An invitation is a prompt the runtime shows the owner once, such as the offer after an update to set up a fingerprint reader `omarchy-hw-fingerprint` has just found. A change that makes one appear, such as a new entry in `fingerprint-readers`, ships only after everything the invitation leads to is published. ## Tests From 86eef556c14838597f96504b7df2c10c04395eb4 Mon Sep 17 00:00:00 2001 From: Scott Jones Date: Fri, 9 Oct 2026 21:11:03 -0400 Subject: [PATCH 5/5] Tighten the invitation rule, and loosen the pin and verify rules From Marcelo's review: the invitation rule now says where its names come from (omarchy-hw-fingerprint, the runtime's detector, reads fingerprint-readers, the platform file omarchy-mac ships in #12), and "published" means published to the repositories Macs update from. systemd-analyze verify --root applies where the container can verify units, at whatever tree is staged. The runtime pin moves to a commit that has what a test needs, not the exact commit that added it. Co-Authored-By: Claude Opus 5.5 (1M context) --- AGENTS.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 28afcb1..8d0cc63 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,13 +18,13 @@ CI rejects files outside these, the root documents and `.github/`. - `omarchy-mac-boot` covers what stays installed and runs again at updates. What runs once to install a Mac belongs in omacom/omarchy-mac-installer. - Change the manual in the same commit as the behaviour it describes. - A udev `add` action that must reach a device already present also gets a pacman hook that does that work on install and upgrade, since on the upgrade that installs the rule no `add` comes. The hook exits 0 in a chroot or an unbooted root, and never fails the transaction. An `add` that should only run when the device appears, such as one tied to the boot splash, does not. -- An invitation is a prompt the runtime shows the owner once, such as the offer after an update to set up a fingerprint reader `omarchy-hw-fingerprint` has just found. A change that makes one appear, such as a new entry in `fingerprint-readers`, ships only after everything the invitation leads to is published. +- An invitation is a prompt the runtime shows the owner once, such as the post-update offer to set up a newly found fingerprint reader. A change that makes one appear, such as a new `fingerprint-readers` entry, ships only after everything the invitation leads to is published to the repositories Macs update from. `omarchy-hw-fingerprint`, the runtime's detector, reads `fingerprint-readers`, a platform file omarchy-mac ships (#12). ## Tests -- A test passes or fails the same on every machine. It never reads the host's `/usr/share/omarchy-platform`, installed `omarchy-*` commands, `/sys` or running services: stage into a temporary root, point copies at fixtures, and stub external dependencies, keeping the real commands under test. Run `systemd-analyze verify` with `--root` at the staged package. A pass on a Mac with Omarchy installed says nothing about CI. +- A test passes or fails the same on every machine. It never reads the host's `/usr/share/omarchy-platform`, installed `omarchy-*` commands, `/sys` or running services: stage into a temporary root, point copies at fixtures, and stub external dependencies, keeping the real commands under test. Where the container can verify units, run `systemd-analyze verify` with `--root` at the staged tree. A pass on a Mac with Omarchy installed says nothing about CI. - When a change adds a detection path or a fallback, test the inverse too: the new path never hides what the old one found. -- A test that needs something the runtime gained at a later commit moves `test/integration/runtime` to that commit; it does not skip because that pin lacks it. +- A test that needs something the runtime gained at a later commit moves `test/integration/runtime` to a commit that has it; it does not skip because the current pin lacks it. - Before calling a change tested, check that CI ran it: a skipped test, or a job that failed before reaching the tests, is not a pass. ## Style