From c9928a399ea5442b92c40c468e0ce13be3cc18ce Mon Sep 17 00:00:00 2001 From: Derek Ross Date: Wed, 28 Oct 2026 16:17:10 -0400 Subject: [PATCH 1/2] docs/review: 19 lessons and 3 corrections from the twenty-fifth round The confirmed candidates from round 25 (L-260 to L-278): the 9a slot B marking as a devinfo question, cross-repository links, squash-merged stacks and version files, stale hand-built prebuilts, and before-merge Pixel 7 Pro runs on omamobile-int. C-16 to C-18 correct our own earlier comments on kernel #98, kernel #80 and #74; L-241 is corrected in place. Co-Authored-By: Claude Opus 5.5 --- docs/review/LESSONS.md | 143 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 142 insertions(+), 1 deletion(-) diff --git a/docs/review/LESSONS.md b/docs/review/LESSONS.md index 8e9f64405..5bc6ffb18 100644 --- a/docs/review/LESSONS.md +++ b/docs/review/LESSONS.md @@ -18,6 +18,22 @@ never change, so reviews can cite them. ## Safety model (AGENTS.md section 1) +- **L-267. A recovery report that says "marked again" is a `devinfo` + question.** On the 9a, marking slot B successful is a `devinfo` write, + agreed only through `omamobile-bootctl` with a fresh backup and a full + before/after compare. A thread or an AGENTS rule that cites another tool, or + one outside the repository (`logs/…py`), is a second writer. *Check:* `git + grep` the tool's name, then the device NOTES for the agreed operation and + its preconditions. Extends L-36 and L-186. *From:* issue #28 with #125, + round 25. +- **L-261. A safety rule that prescribes a protected-partition write is held + to the exact approval on record.** #125 turned the one approved tegu + `devinfo` operation (`omamobile-bootctl mark-successful`, with a fresh + backup and before/after bytes) into a standing "after every flash" step, run + by an unreviewed script. *Check:* for any AGENTS or CONTRIBUTING text that + tells people to write `devinfo`, the GPT or `persist`, find the approving + review and diff the tool and conditions against it; ask whether writes + already made met it. Extends L-2 and L-224. *From:* #125, round 25. - **L-223. An installer step that writes the phone runs after the typed codename and is listed in the "only these commands" banner.** #111's `install-phone` RAM-booted a bootloader copy straight after `getvar`, before @@ -251,6 +267,23 @@ never change, so reviews can cite them. ## Shared code and the reference device +- **L-273. A before-merge Pixel 7 Pro run on `omamobile-int` compares the + touched file on int with the base first.** Where they differ, the run covers + the PR's hunk inside int's code, and the runbook and merge comment say + "tested on int + the commit"; where the cherry-pick conflicts, show that the + untestable commit is neutral on gs201. Kernel #82's `synaptics_tcm.c` and + #71's `net/nfc/core.c` differ between int and the base, and #88's gs-decon + commit doesn't apply to int. *Check:* `git rev-parse omamobile-int: + github/omamobile:`, then `git merge-tree --merge-base ^ omamobile-int + `. Extends L-206 and L-45. *From:* kernel #82, #71, #88, round 25. +- **L-268. A package that installs a hand-built prebuilt publishes a stale + binary when only its source changes.** fingerprint 0.1.9 changed the + bridge's C source, but the package installs `prebuilt/omamobile-fp-bridge` + as it finds it; gnss 0.2.4 builds without the 9a client and says so only in + the log. *Check:* for a package PR that touches a prebuilt's source, ask + whether the build machine rebuilt the prebuilt, and prefer a test that + compares the prebuilt's build ID or date with its source. Extends L-259. + *From:* issue #109, round 25. - **L-228. A board DT property that only the contributor's board sets counts as its match data under CONTRIBUTING §6.2.** It holds when no base DTS, cheetah overlay in `DTB_OVERLAYS` or open PR sets it, and the object diff @@ -448,6 +481,12 @@ never change, so reviews can cite them. ## Shell and scripts +- **L-264. A udev `SYSTEMD_WANTS` hook fires only when the device first + becomes active.** We nearly flagged #113's rule as restarting feedbackd on + every `udevadm trigger` change event; systemd.device(5) says change events + don't act on `Wants=`. *Check:* read systemd.device(5) before flagging + repeat starts; a replay with `--action=add` is the test. *From:* #113, round + 25 (a near miss). - **L-235. An edge-triggered "stop when X" is undone by every other actor that restarts the thing.** #99 stops neard polling once on the lit-to-dark transition; the sleep hook, its own unblock path and a neard restart all @@ -498,6 +537,13 @@ never change, so reviews can cite them. ## Kernel (linux-omarchy-mobile) +- **L-269. A power sequencer keeps a shared supply up only while another of + its targets has a consumer.** `pwrseq-qcom-wcn` reference-counts its + regulators across the Bluetooth and Wi-Fi targets; with Bluetooth as the + only consumer (lynx has no PCIe Wi-Fi node), Bluetooth off still drops the + buck. *Check:* read the sequencer's unit dependencies and the core's + `enable_count`, then list which targets have a consumer in that board's DT. + Corrects L-241's advice; see C-16. *From:* kernel #98, round 25. - **L-236. A binding's numeric constraints are checked against the stock value of every phone that may use the property, the reference phone first.** #95's `multipleOf: 47000` rejects stock cheetah's @@ -534,7 +580,8 @@ never change, so reviews can cite them. Google's driver never drops that pin. *Check:* read each consumer's power-off and runtime-PM paths, compare with the vendor driver, and prefer the upstream power sequencer (`qcom,wcn6855-pmu`). Extends C-9 and L-67. - *From:* kernel #98, round 24. + *From:* kernel #98, round 24. *Corrected 2026-10-28:* the sequencer keeps + the buck up only while Wi-Fi is also its consumer (L-269, C-16). - **L-242. A firmware-naming driver can pick different files for two revisions of one chip.** btqca adds a `g` NVM variant for some `soc_id` values, so lynx's two revisions load different files; one phone's @@ -887,6 +934,16 @@ never change, so reviews can cite them. ## The gates themselves +- **L-271. An AI author address on an early commit of a squash-merged PR lands + on main as `Co-authored-by:`,** even after later commits fix the identity, + and `tools/pr-check` checks only `Signed-off-by:`. *Check:* `git log + --format='%an <%ae>' base..head` on omarchy-mobile PRs; ask for a + self-squash or strip the trailer at merge. *From:* #98, round 25. +- **L-262. An AGENTS or CONTRIBUTING line links only tracked files.** #125 + linked `docs/HANDOFF.md`, which doesn't exist, and a script under the + gitignored `logs/`. *Check:* `git ls-files --error-unmatch ` for every + path the line names; `tools/pr-check` could do this for both files. *From:* + #125, round 25. - **L-246. A base build is asked only for targets the base has, with `make -k`, and a stopped base build is reported, never hidden.** On kernel #108 the gate asked the base for a new board's DTB it had no source for; make @@ -1075,6 +1132,49 @@ never change, so reviews can cite them. ## Reviews and merging +- **L-278. A re-pushed stack with identical sources is proved once.** Where + every PR's tree id equals the old head's, the review is tree ids plus a + range-diff per PR, then one gate on a scratch rebase of the top; DTB hashes + of old head and rebased head carry the earlier content review over. *From:* + the tegu stack, round 25 (12 heads, one message change). +- **L-277. A promised userspace guard is checked in every open package for + that device, other owners' included.** Kernel #90 was accepted on W4HO's + promise that `allow_tx` is set only for `google-tg4c`; h4rkl's #74 sets + `allow_tx=1` for every panel, and our #74 review missed it (C-18). *Check:* + `git grep -n '