review: fix review findings (correctness, hardening, doc-accuracy)

First recursive code-review-harness pass over the authored SDK code (sim/,
config-lint, flowgen, drivers/{relays,freshness}, build/, ci.yml). Four parallel
dimension reviewers; all findings at every severity corrected per workspace rule.

Correctness / reliability:
- freshness.c min_budget_ms: use a `seen` flag, not `best==0`, as the empty
  sentinel — a zero-tolerance (max_stale_ms==0) binding was silently widened to a
  looser neighbour's budget. Regression test added; still 66/66 MC/DC.
- config-lint parse_reserved_ranges: match `reg` as a whole property token (ident
  boundary before, `=` after) so `reg-names` / a `region-*` label no longer
  mis-parses into a bogus reserved range.
- config-lint loader check: fail closed — flag any loader with a LOAD_ADDR that is
  not a known-safe boot component, instead of only known MCU names, so a future
  coprocessor ("Rtos"/"Bl32") can't slip past the 0x40000-brick gate.
- build-kernel.sh: sha256 verification is now mandatory (refuse to build if the pin
  is missing) and the mktemp scratch tree is removed on exit (trap), while a
  caller-provided WORK is left intact for CI artifact upload.

Test quality:
- freshness: added the age==max_stale boundary case and a clock-wraparound
  (now < last_ok) fail-safe-to-UNKNOWN test.
- relays: unsetenv(WARDEN_GPIO_ROOT) at main() so the NULL-env arm is hermetic.

Security / CI:
- ci.yml: top-level `permissions: contents: read` (badges overrides to write);
  pin taiki-e/install-action to commit SHA (v2.86.7).

Maintainability / docs:
- drivers/enforce-mcdc.sh: one shared, name-derived gate replaces the two
  copy-pasted per-driver scripts; Makefiles call ../../enforce-mcdc.sh.
- docs/architecture.md: §3/§4/§6/§7 rewritten to match reality — NPU/RGA models,
  config-lint, and the relays+freshness MC/DC harnesses are done; kernel §6 now
  reflects the 5.10->6.18.46 forward-port (ADR-0001), not the superseded plan44/6.6.
- README: status blurb + layout table corrected (kernel/, .github/; stale ci/ and
  patches/ descriptions fixed). hpmcu "8 tests" -> 7 in docs.
- freshness.{c,h}: ADR reference points at flare-edge ADR-0004 (warden-sdk's
  ADR-0004 is the CI runner — number collision).
- normalize rustfmt drift across sim/ + config-lint.

All green: sim 37 tests, config-lint 8 tests, both drivers 100% MC/DC (relays
40/40, freshness 66/66), clippy clean under -D warnings, gitleaks clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017wB8KB3MMQztRDXCMCkPrf

drivers/README.md

@@ -17,8 +17,11 @@ Self-contained logic with a clean seam, measured to **100% MC/DC** (gcc-14
 
 **Adding a Tier-1 driver:** copy `<name>.{c,h}` here, put the hardware/OS calls behind
 a small injectable seam, then mirror `relays/test/` (a fake backend for the logic
-branches + a real backend over a scratch tree for the plumbing) and
-`enforce-mcdc.sh`. The CI job picks up any `drivers/*/test/Makefile` automatically.
+branches + a real backend over a scratch tree for the plumbing). Reuse the shared
+gate — the Makefile calls `bash ../../enforce-mcdc.sh <gcov.log> build/<name>.c.gcov
+build/test.rc` (it derives the driver name from the `.gcov` file, so there is no
+per-driver copy to keep in sync). The CI `mcdc` job picks up any
+`drivers/*/test/Makefile` automatically.
 
 ## Tier 2 — serious testing + fault-injection + benchmarks
 
@@ -30,7 +33,7 @@ is already modelled and tested here** in `../sim/`:
 |---|---|---|
 | `modbus_engine.c` (RS485 master) | 11 pty scenarios + fault-injection + a compiled corpus walk (flare-edge `tools/modbus-sim/`, green) | `sim::modbus` RTU slave (11 tests, silent-drop/forced-NAK faults) + `modbus_read_holding` benchmark |
 | `warden_rga.c` (RGA offload) | offload-dispatch + CPU-fallback logic | `sim::rga` recording `improcess` fake (programmable IM_STATUS) + `rga_improcess` benchmark |
-| HPMCU supervisor (`hpmcu.rs`) | arm/beat/fire + boot-grace safety property | `sim::hpmcu` (8 tests) + `hpmcu_tick` benchmark |
+| HPMCU supervisor (`hpmcu.rs`) | arm/beat/fire + boot-grace safety property | `sim::hpmcu` (7 tests) + `hpmcu_tick` benchmark |
 
 **Why the Tier-2 *source* isn't vendored here yet:** `modbus_engine.c` and
 `warden_rga.c` pull in shared UI headers (`platform.h`, `settings.h`, `lv_*`) and

drivers/enforce-mcdc.sh

@@ -1,9 +1,16 @@
 #!/usr/bin/env bash
-# Gate: fail unless every unit check passed AND relays.c reached 100% MC/DC
-# (condition) coverage with no uncovered executable lines.
-#   $1 = gcov stdout log   $2 = relays.c.gcov   $3 = test exit-code file
+# Shared Tier-1 MC/DC gate for every driver harness. Each driver's test/Makefile
+# invokes it as:
+#   bash ../../enforce-mcdc.sh <gcov.log> <build>/<name>.c.gcov <test.rc>
+# Fails unless every unit check passed AND <name>.c reached 100% MC/DC (condition)
+# coverage with no uncovered executable lines. The driver name is derived from the
+# .gcov filename so this one script serves all drivers (no per-driver copies to keep
+# in sync).
+#   $1 = gcov stdout log   $2 = <name>.c.gcov   $3 = test exit-code file
 set -uo pipefail
 LOG="$1"; GCOV="$2"; RCFILE="$3"
+base="$(basename "$GCOV")"; base="${base%.gcov}"   # e.g. freshness.c
+name="${base%.c}"                                   # e.g. freshness
 rc=0
 
 testrc="$(cat "$RCFILE" 2>/dev/null || echo 1)"
@@ -20,9 +27,10 @@ fi
 notcov="$(grep -nE "condition[s]? .*not covered" "$GCOV" || true)"
 uncov_lines="$(grep -nE "^ +#####:" "$GCOV" || true)"
 
-# Summary lines for relays.c from gcov stdout. Match the exact file so
-# 'test_relays.c' (which also contains "relays.c") is NOT picked up.
-FMATCH="File '([^']*/)?relays[.]c'"
+# Summary lines for <name>.c from gcov stdout. Match the exact file so the test
+# harness translation unit (test_<name>.c, which also contains "<name>.c") is NOT
+# picked up.
+FMATCH="File '([^']*/)?${name}[.]c'"
 cond_line="$(awk -v patt="$FMATCH" '$0 ~ patt {f=1} f&&/Condition outcomes covered:/{print; f=0}' "$LOG")"
 line_line="$(awk -v patt="$FMATCH" '$0 ~ patt {f=1} f&&/Lines executed:/{print; f=0}' "$LOG")"
 echo "  ${line_line:-Lines executed: (n/a)}"
@@ -34,7 +42,7 @@ if [ -n "$notcov" ]; then
 	rc=1
 fi
 if [ -n "$uncov_lines" ]; then
-	echo "RESULT: uncovered executable lines in relays.c:"
+	echo "RESULT: uncovered executable lines in ${name}.c:"
 	echo "$uncov_lines" | sed 's/^/    /'
 	rc=1
 fi

drivers/freshness/freshness.c

@@ -1,5 +1,5 @@
 /*
- * The UI Freshness Contract engine (ADR 0004) — core, LVGL-free.
+ * The UI Freshness Contract engine (flare-edge ADR-0004) — core, LVGL-free.
  * See freshness.h for the contract. LVGL binding lives in freshness_lv.c.
  */
 #include "freshness.h"
@@ -175,11 +175,16 @@ uint32_t warden_fresh_count(void)
 
 uint32_t warden_fresh_min_budget_ms(void)
 {
+    /* `seen` — not `best == 0` — marks "nothing scanned yet", so a legitimate
+     * zero-tolerance binding (max_stale_ms == 0, "must be fresh every tick") wins
+     * the minimum instead of being mistaken for the empty sentinel and widened. */
     uint32_t best = 0;
+    bool seen = false;
     for(uint32_t i = 0; i < FRESH_MAX; i++) {
         struct warden_fresh *v = &s_vals[i];
-        if(v->used && v->visible && (best == 0 || v->max_stale_ms < best)) {
+        if(v->used && v->visible && (!seen || v->max_stale_ms < best)) {
             best = v->max_stale_ms;
+            seen = true;
         }
     }
     return best;

drivers/freshness/freshness.h

@@ -1,5 +1,5 @@
 /*
- * The UI Freshness Contract engine (ADR 0004) — core, LVGL-free.
+ * The UI Freshness Contract engine (flare-edge ADR-0004) — core, LVGL-free.
  *
  * The panel is read on-site to judge whether hardware is healthy, so a silently
  * *stale* number is worse than a missing one: a stale IP or hashrate reads as

drivers/freshness/test/Makefile

@@ -31,7 +31,7 @@ check: $(BUILD)/test
 	@echo "== MC/DC (condition) coverage of freshness.c =="
 	@$(GCOV) --conditions --branch-probabilities -o $(BUILD) ../freshness.c >$(BUILD)/gcov.log 2>&1 || true
 	@mv -f *.gcov $(BUILD)/ 2>/dev/null || true
-	@bash enforce-mcdc.sh $(BUILD)/gcov.log $(BUILD)/freshness.c.gcov $(BUILD)/test.rc
+	@bash ../../enforce-mcdc.sh $(BUILD)/gcov.log $(BUILD)/freshness.c.gcov $(BUILD)/test.rc
 
 report: check
 	@grep -nE "condition.*not covered|conditions covered" $(BUILD)/freshness.c.gcov || true

drivers/freshness/test/enforce-mcdc.sh

@@ -1,48 +0,0 @@
-#!/usr/bin/env bash
-# Gate: fail unless every unit check passed AND freshness.c reached 100% MC/DC
-# (condition) coverage with no uncovered executable lines.
-#   $1 = gcov stdout log   $2 = freshness.c.gcov   $3 = test exit-code file
-set -uo pipefail
-LOG="$1"; GCOV="$2"; RCFILE="$3"
-rc=0
-
-testrc="$(cat "$RCFILE" 2>/dev/null || echo 1)"
-if [ "$testrc" != "0" ]; then
-	echo "RESULT: unit checks FAILED (test exit $testrc)"; rc=1
-else
-	echo "RESULT: all unit checks passed"
-fi
-
-if [ ! -f "$GCOV" ]; then
-	echo "RESULT: no coverage file ($GCOV) produced"; exit 1
-fi
-
-notcov="$(grep -nE "condition[s]? .*not covered" "$GCOV" || true)"
-uncov_lines="$(grep -nE "^ +#####:" "$GCOV" || true)"
-
-# Summary lines for freshness.c from gcov stdout. Match the exact file so
-# 'test_freshness.c' (which also contains "freshness.c") is NOT picked up.
-FMATCH="File '([^']*/)?freshness[.]c'"
-cond_line="$(awk -v patt="$FMATCH" '$0 ~ patt {f=1} f&&/Condition outcomes covered:/{print; f=0}' "$LOG")"
-line_line="$(awk -v patt="$FMATCH" '$0 ~ patt {f=1} f&&/Lines executed:/{print; f=0}' "$LOG")"
-echo "  ${line_line:-Lines executed: (n/a)}"
-echo "  ${cond_line:-Condition outcomes covered: (n/a)}"
-
-if [ -n "$notcov" ]; then
-	echo "RESULT: MC/DC gaps (conditions not covered):"
-	echo "$notcov" | sed 's/^/    /'
-	rc=1
-fi
-if [ -n "$uncov_lines" ]; then
-	echo "RESULT: uncovered executable lines in freshness.c:"
-	echo "$uncov_lines" | sed 's/^/    /'
-	rc=1
-fi
-
-if ! echo "$cond_line" | grep -q "100.00%"; then
-	echo "RESULT: condition coverage is below 100%"
-	rc=1
-fi
-
-[ "$rc" = "0" ] && echo "RESULT: 100% MC/DC + all checks green ✓"
-exit "$rc"

drivers/freshness/test/test_freshness.c

@@ -44,6 +44,9 @@ static void test_decide(void) {
     EXPECT(warden_fresh_decide(FRESH_UNKNOWN, false, false, 0,   100) == FRESH_RENDER_UNKNOWN);
     EXPECT(warden_fresh_decide(FRESH_UNKNOWN, true,  false, 200, 100) == FRESH_RENDER_UNKNOWN);
     EXPECT(warden_fresh_decide(FRESH_UNKNOWN, true,  false, 50,  100) == FRESH_RENDER_NOCHANGE);
+    /* boundary: age == max_stale is NOT stale (guards a `>`->`>=` regression that
+     * MC/DC alone would not catch — both outcomes are already covered above). */
+    EXPECT(warden_fresh_decide(FRESH_UNKNOWN, true,  false, 100, 100) == FRESH_RENDER_NOCHANGE);
 }
 
 /* --- 2. bind: !produce, !render, valid, and table-full (FRESH_MAX=2) --- */
@@ -121,10 +124,18 @@ static void test_invalidate(void) {
     EXPECT(g_render_calls == 1);
 }
 
-/* --- 6. min_budget: best==0 first, then max_stale<best true and false --- */
+/* --- 6. min_budget: unseen first, then max_stale<best true and false --- */
 static void test_min_budget(void) {
     warden_fresh_reset();
     EXPECT(warden_fresh_min_budget_ms() == 0);     /* nothing bound */
+    /* regression (correctness review): a zero-tolerance binding (max_stale=0) must
+     * win the minimum, not be mistaken for the "nothing scanned" sentinel and
+     * widened to a looser neighbour's budget. */
+    warden_fresh_bind((void*)1, fake_produce, NULL, 0,   "s", fake_render, (void*)9);
+    warden_fresh_bind((void*)1, fake_produce, NULL, 300, "s", fake_render, (void*)9);
+    EXPECT(warden_fresh_min_budget_ms() == 0);
+    warden_fresh_reset();
+    EXPECT(warden_fresh_min_budget_ms() == 0);     /* nothing bound (post-reset) */
     warden_fresh_bind((void*)1, fake_produce, NULL, 300, "s", fake_render, (void*)9); /* best=0->300 */
     warden_fresh_bind((void*)1, fake_produce, NULL, 100, "s", fake_render, (void*)9); /* 100<300 -> 100 */
     EXPECT(warden_fresh_min_budget_ms() == 100);
@@ -160,6 +171,22 @@ static void test_false_arms(void) {
     EXPECT(g_render_calls == 0);
 }
 
+/* --- 8. clock wraparound: a uint32 ms counter wraps every ~49.7 days, so a tick
+ *        can arrive with now_ms < last_ok_ms. The unsigned `now - last_ok_ms` then
+ *        underflows to a huge age; the contract must fail SAFE to UNKNOWN, never
+ *        assert the last value as if still fresh. --- */
+static void test_wraparound(void) {
+    warden_fresh_reset();
+    warden_fresh_bind((void*)1, fake_produce, NULL, 100, "s", fake_render, (void*)9);
+    set_produce(FRESH_OK, "9"); reset_render();
+    warden_fresh_tick(1000);                       /* last_ok_ms = 1000, ever_ok */
+    EXPECT(g_render_calls == 1 && g_render_what == FRESH_RENDER_VALUE);
+    /* now wraps behind last_ok_ms: age underflows -> treated as stale -> UNKNOWN */
+    set_produce(FRESH_UNKNOWN, NULL); reset_render();
+    warden_fresh_tick(10);
+    EXPECT(g_render_calls == 1 && g_render_what == FRESH_RENDER_UNKNOWN);
+}
+
 int main(void) {
     test_decide();
     test_bind();
@@ -168,6 +195,7 @@ int main(void) {
     test_invalidate();
     test_min_budget();
     test_false_arms();
+    test_wraparound();
     fprintf(stderr, "%d checks, %d failures\n", g_checks, g_fail);
     return g_fail ? 1 : 0;
 }

drivers/relays/test/Makefile

@@ -32,7 +32,7 @@ check: $(BUILD)/test
 	@echo "== MC/DC (condition) coverage of relays.c =="
 	@$(GCOV) --conditions --branch-probabilities -o $(BUILD) ../relays.c >$(BUILD)/gcov.log 2>&1 || true
 	@mv -f *.gcov $(BUILD)/ 2>/dev/null || true
-	@bash enforce-mcdc.sh $(BUILD)/gcov.log $(BUILD)/relays.c.gcov $(BUILD)/test.rc
+	@bash ../../enforce-mcdc.sh $(BUILD)/gcov.log $(BUILD)/relays.c.gcov $(BUILD)/test.rc
 
 report: check
 	@grep -nE "condition.*not covered|conditions covered" $(BUILD)/relays.c.gcov || true

drivers/relays/test/test_relays.c

@@ -211,6 +211,11 @@ static void integration_tests(void)
 
 int main(void)
 {
+    /* Hermeticity: layer 1's fake-io tests exercise gpio_root()'s `r && *r` NULL
+     * arm (unset env). Clear any inherited WARDEN_GPIO_ROOT so that outcome is
+     * deterministic instead of depending on the ambient shell (an exported value
+     * would otherwise drop condition coverage and spuriously fail the gate). */
+    unsetenv("WARDEN_GPIO_ROOT");
     unit_tests();
     integration_tests();
     fprintf(stderr, "%d checks, %d failures\n", g_checks, g_fail);