diff --git a/docs/review/LESSONS.md b/docs/review/LESSONS.md index 8e9f64405..793692cd0 100644 --- a/docs/review/LESSONS.md +++ b/docs/review/LESSONS.md @@ -18,6 +18,36 @@ never change, so reviews can cite them. ## Safety model (AGENTS.md section 1) +- **L-285. "The approved tool did the write" is checked for what made the + target writable.** `omamobile-bootctl` only opens `devinfo` for writing; the + guard bypass (`--setrw` on the partition and its parent for 30 s) was in the + owner's laptop script around it. An approval that names the tool leaves the + wrapper unreviewed. *Check:* for any write outside the allowlist, find who + lifts the read-only flag and whether that code was reviewed. Extends L-2 and + L-261. *From:* #125, round 26. +- **L-284. A hold on a safety step is checked for what it forces next.** + Telling the 9a owner "don't mark B" without also saying "don't `flash`" + would have led straight to the next fallback, because `flash` unmarks B and + the marking is what keeps the root. *Check:* for any "don't do X until I + decide", walk the owner's next routine step with X missing, and give the + safe interim path (here, `push` only). Extends L-81 and L-158. *From:* #125, + round 26 (a near miss in drafting). +- **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 +281,37 @@ never change, so reviews can cite them. ## Shared code and the reference device +- **L-282. An env-default variable in a shared build library is an input to + the maintainer's builds too.** #79's `ALARM_LOCAL_KEY=${ALARM_LOCAL_KEY:-}` + in `tools/lib/alarm.sh` lets a leftover export widen trust in a build + without `--local`. *Check:* for each new `VAR=${VAR:-}` in `tools/lib/`, + confirm the maintainer's path sets or clears it explicitly. Extends L-7 and + L-171. *From:* #79, round 26. +- **L-280. A per-device flag that gates new behaviour in a shared runner is + checked by building the command line under both values.** #101's + `MAP_STORES` adds storageproxyd arguments through an array, and an empty + `"${maps[@]}"` must vanish under `set -u`; a grep test can't show that. Run + with both images present, cheetah got the same 9 arguments as main and tegu + 15. *Check:* extract the argument-building block and run it under `set -euo + pipefail` with each flag value and the triggering files present. Extends L-8 + and L-234. *From:* #101, round 26. +- **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 +509,20 @@ never change, so reviews can cite them. ## Shell and scripts +- **L-289. A "retried" claim in a GLib timeout path is checked once per + caller.** A helper's `True` return only reschedules when the helper is + itself the registered callback: #99's `start_polling` returns True to retry, + but `follow_screen` calls it once at screen-on and discards the result, so a + failed power-on there stays off until the next dark/lit cycle. *Check:* list + every caller of a function that returns "try again", confirm the value + reaches GLib or the next tick calls it again, and run a stub bus whose call + fails once. Extends L-14 and L-235. *From:* #99, round 26. +- **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 +573,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 +616,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 +970,32 @@ never change, so reviews can cite them. ## The gates themselves +- **L-293. An empty diff is checked for empty inputs.** Comparing the gs201 + DTBs before and after kernel #123 with the host's `dtc` printed no + difference, because the host has no `dtc` and both sides decompiled to + nothing. *Check:* confirm each side of a comparison is non-empty (or use the + build's own `scripts/dtc/dtc`) before reading "no change". Extends L-102. + *From:* kernel #123, 2026-10-28. +- **L-288. A stack with several tops is gated once on a combined commit.** + Combine the heads with `git merge-tree --write-tree` and `commit-tree` into + one commit (the gate skips merge commits in its commit checks) and gate + that, which covers how the tops interact; gate the landing PR on its own + too, since its DTB differs. Extends L-196. *From:* the tegu stack, round 26. +- **L-281. A re-push can leave CI at `action_required`, so "rebased, CI should + be green" means nothing until the run is approved.** #79's re-push sat with + no checks reported. *Check:* `gh run list --branch ` on every + follow-up round, and say in the draft that the maintainer will approve the + run. Extends L-59 and L-38. *From:* #79, round 26. +- **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 +1184,74 @@ never change, so reviews can cite them. ## Reviews and merging +- **L-292. Merge only after every check has finished, not on the first + green.** #126 was merged with the policy job passed and the tests job still + pending; the tests passed afterwards, but the merge didn't know that. + *Check:* `gh pr checks N` shows no pending job (or `gh run watch + --exit-status`) before `gh pr merge`. Extends C-15. *From:* #126, + 2026-10-28. +- **L-291. When the bottom of a squash-merged stack moves after we've posted a + cherry-pick plan, re-simulate the plan.** #115 and #117 still carry #99's + old head, and #117's list grew from two commits to three. *Check:* squash + the new bottom onto main, cherry-pick the listed commits, and diff the + result against the top head, expecting only the bottom's new change. Extends + L-195 and L-214. *From:* #99, #115, #117, round 26. +- **L-287. A silent re-push is diffed per PR before any reply.** The tegu + stack's 20:38Z push looked like an answer to everything but carried only the + Makefile resolution; #106's and #122's points were untouched. *Check:* `git + range-diff` against the last round's refs, then one status line per open + point rather than a re-post. Extends L-183 and L-248. *From:* kernel #80 to + #122, round 26. +- **L-279. A PR that carries a merged fix PR's commits is diffed against main, + and its squash body written by hand.** #101 still carried #107's audio + commits; `git diff origin/main -- packages/omamobile-audio` was + empty, but GitHub's default squash body would still list "omamobile-audio + 0.5.5" under the fingerprint title. *Check:* after the fix PR merges, diff + each rider against main for the fix's package. Extends L-255. *From:* #101, + round 26. +- **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 '