docs: ASCII typography and style normalization across all repo text

Replace every em dash with real punctuation (rewrites, not hyphen swaps) in docs, code comments, scripts, configs, and the port records; convert en dashes, curly quotes, ellipsis glyphs, arrows, and section signs to ASCII; drop machine-writing tell phrases from living docs. ADR titles now use a colon. The M2 bring-up DTS model string carried an em dash into the patch series and its record echoes; fixed at both, and the full series re-verified to apply cleanly onto pristine 6.18.46. One comment in freshness.h deliberately names the em dash glyph the UI renders as the unknown mark; that is data, kept as prose naming it. Verified: cargo tests (sim, config-lint, rs485-bridge), shellcheck, both driver MC/DC harnesses, patches-apply.
2026-08-31 12:31:27 -06:00
parent 80d9a9539b
commit 42fb386f60
111 changed files with 1261 additions and 1261 deletions
@@ -1,4 +1,4 @@
-# ADR 0001 — Kernel Forward-Port
+# ADR 0001: Kernel Forward-Port

 **Status:** Accepted (2026-08-25). Supersedes the README's original plan44/6.6 goal.

@@ -18,7 +18,7 @@ deltas as a reviewable patch series in `patches/`.
 - Done and **hardware-verified on `warden-c8a3`**: clk, pinctrl, eMMC, GMAC, TRNG,
  OTP, SARADC/TSADC, RTC, USB host, PWM/backlight, VOP display, GT911 touch, AIC8800
  wifi, RGA, I2S audio, HPMCU mailbox, open NPU driver, PVTM.
- **uClibc stays load-bearing** — RGA/MPP/ISP/NPU userspace ship as uClibc-only
+- **uClibc stays required**: RGA/MPP/ISP/NPU userspace ship as uClibc-only
  blobs; a glibc swap breaks media (flare-edge #51, wontfix). Any kernel bump
  inherits this.
 - Kernel bumps risk struct-ABI breaks for out-of-tree modules (the AIC8800/VLAN
@@ -1,4 +1,4 @@
-# ADR 0002 — Tiered MC/DC
+# ADR 0002: Tiered MC/DC

 **Status:** Accepted (2026-08-25).

@@ -11,23 +11,23 @@ that code would be theatre, not assurance.
 ## Decision
 A **two-tier** policy, measured against the Hardware Abstraction Seam:

- **Tier 1 — our own hardware-facing code → real 100% MC/DC.** `modbus_engine.c`,
+- **Tier 1, our own hardware-facing code -> real 100% MC/DC.** `modbus_engine.c`,
  `relays.c`, `warden_rga.c` (wrapper), `hpmcu.rs`, `devmem.rs`, `freshness.c`, plus
  the two smallest near-mainline drivers where feasible. Enforced in CI
  (`gcc-14 -fcondition-coverage` + `gcov-14 --conditions`). Rust uses
-  `cargo-llvm-cov` line/region coverage for now — true `--mcdc` needs a nightly
+  `cargo-llvm-cov` line/region coverage for now; true `--mcdc` needs a nightly
  toolchain (`-Z coverage-options=condition`) and is deferred on that tooling skew;
  the C drivers carry the literal MC/DC gate.
- **Tier 2 — ported/vendor drivers → fault-injection + branch coverage + benchmarks**
+- **Tier 2, ported/vendor drivers -> fault-injection + branch coverage + benchmarks**
  against the simulator, behind a stable seam. Explicitly NOT literal MC/DC.

 ## Consequences
 - Matches the user's framing: "as many drivers as possible at 100% MC/DC; for the
  rest, a very serious testing and benchmarking system."
 - The seam is the shared object: the same thing MC/DC is measured against and the
-  simulator implements — the two goals reinforce, not duplicate.
+  simulator implements; the two goals reinforce, not duplicate.
 - Every Tier-1 file gets a `drivers/<name>/test/` host harness (a `Makefile` +
-  `test_<name>.c`) that calls the one shared `drivers/enforce-mcdc.sh` — which derives
+  `test_<name>.c`) that calls the one shared `drivers/enforce-mcdc.sh`, which derives
  the driver name from the `.gcov` file, so there is a single gate to maintain, not a
  per-driver copy. The CI `mcdc` job auto-discovers any `drivers/*/test/Makefile` and
  fails below 100%.
@@ -1,13 +1,13 @@
-# ADR 0003 — Standalone Repo
+# ADR 0003: Standalone Repo

 **Status:** Accepted (2026-08-25). Repo-visibility half superseded by ADR-0007
-(2026-08-30) — warden-sdk went public; the "private for now" consequence below
+(2026-08-30): warden-sdk went public; the "private for now" consequence below
 no longer holds. Original decision kept for the record.

 ## Context
 Our real SDK changes lived as uncommitted edits in a 2GB opaque vendor fork, with
-no CI, tests, or versioning of their own. The SDK requirement (future-features-2
-§SDK) calls for "its own repo, held to firmware standards."
+no CI, tests, or versioning of their own. The SDK requirement (future-features-2,
+SDK section) calls for "its own repo, held to firmware standards."

 ## Decision
 A **private** `warden-sdk` GitHub repo (now `blueflare-energy/bfe-core1106-sdk` and public
@@ -17,7 +17,7 @@ on a passing review run, green CI, and the maintainer's fresh explicit go-ahead.

 ## Consequences
 - flare-edge consumes this repo later (flared depending on `warden-sim`, drivers
-  built from here) — a separate, maintainer-gated integration step; flare-edge is not
+  built from here), a separate, maintainer-gated integration step; flare-edge is not
  edited by the SDK-completion effort.
 - Private for now (references bench devices / in-progress hardening); can be opened
  later once scrubbed, matching how `flare-deployment` is handled.
@@ -1,12 +1,12 @@
-# ADR 0004 — Self-Hosted Runner
+# ADR 0004: Self-Hosted Runner

-**Status:** Superseded in part by ADR-0007 (2026-08-30) — `kernel-build` moved
+**Status:** Superseded in part by ADR-0007 (2026-08-30): `kernel-build` moved
 to GitHub-hosted runners for the public repo and the self-hosted registration
 is retired. Original decision below, kept for the record. (2026-08-25.)

 ## Context
 The heavy kernel/firmware build needs the SDK toolchain and Buildroot's baked-in
-absolute paths — impractical on GitHub-hosted runners. flare-edge already builds on
+absolute paths, impractical on GitHub-hosted runners. flare-edge already builds on
 a repo-scoped self-hosted runner on `bfe-mpc-0640` (label `flare-edge`); a repo-scoped
 registration cannot be shared across repos by label alone.

@@ -1,4 +1,4 @@
-# ADR 0005 — Driver Source of Truth
+# ADR 0005: Driver Source of Truth

 **Status:** Accepted (2026-08-25).

@@ -18,4 +18,4 @@ formalized as a patch series in `patches/`. flare-edge consumes this repo later
 - Realizes the seam architecture (ADR-referenced in `docs/architecture.md`).
 - flare-edge is not edited now; a later integration step points flare-edge at these.
 - Risk: temporary duplication of shared constants between the two repos until the
-  integration lands — tracked, acceptable for the bring-up window.
+  integration lands; tracked, acceptable for the bring-up window.
@@ -1,4 +1,4 @@
-# ADR 0006 — QEMU Device Simulator
+# ADR 0006: QEMU Device Simulator

 **Status:** Accepted (2026-08-29).

@@ -6,7 +6,7 @@
 The two existing simulators cannot test the *device*: `lvglsim` (flare-edge)
 is an SDL rendering harness, and `sim/` models registers behind driver seams.
 Init ordering, the daemons as real processes, networking/enrollment against
-FLARE, OTA, and the watchdog were testable only on a bench panel — flare-edge's
+FLARE, OTA, and the watchdog were testable only on a bench panel; flare-edge's
 fault suite marks five scenarios "HIL, human prompts", its Playwright e2e needs
 a live panel on the LAN, and its OTA desk test stops at "reached APPLYING".

@@ -14,12 +14,12 @@ Two ways to emulate the panel were considered:

 1. **A custom RV1106 QEMU board model.** Nothing exists upstream or in the
   community, so this means writing VOP/CRU/GRF/eMMC/HPMCU device models from
-   scratch and maintaining them against QEMU — months of work that duplicates
+   scratch and maintaining them against QEMU: months of work that duplicates
   what `sim/` already models in Rust. It still could not run the boot chain:
   BootROM is mask ROM and the DDR-init/idblock stages are closed rkbin blobs.
 2. **The generic `-M virt` machine, entering at `-kernel zImage`.** The
   forward-ported 6.18.46 config is multi_v7-derived and already carries
-   `ARCH_VIRT` plus the full virtio set — the canonical RV1106 zImage boots
+   `ARCH_VIRT` plus the full virtio set; the canonical RV1106 zImage boots
   virt **unmodified** (verified 2026-08-29). Peripherals become virtio
   substitutes; SoC-block behavior stays in `sim/`, bridged in (the RS485
   chardev bridge) rather than re-modeled.
@@ -28,11 +28,11 @@ Two ways to emulate the panel were considered:
 Option 2. `qemu/` holds the harness: `qemu-system-arm -M virt,highmem=off
 -cpu cortex-a7 -smp 1 -m 256M` (the RV1106G3's shape), one canonical kernel
 image plus an optional additive config fragment (`qemu/configs/virt.fragment`
-via the `WARDEN_KCONFIG_FRAGMENT` hook — PCI/pci-serial/i6300esb/WireGuard/
+via the `WARDEN_KCONFIG_FRAGMENT` hook: PCI/pci-serial/i6300esb/WireGuard/
 virtio-gpu/virtio-input; the RV1106 build is byte-identical with the variable
 unset). The VM carries the device's real 12-partition `blkdevparts=` A/B
 layout on a virtio disk and populates the `/dev/block/by-name/` contract.
-The name is `qemu/`, not any variant of "sim" — the wikis already warn that
+The name is `qemu/`, not any variant of "sim"; the wikis already warn that
 "sim" is two different things.

 Notable mechanics: `highmem=off` because the non-LPAE 32-bit kernel cannot
@@ -1,4 +1,4 @@
-# ADR 0007 — Hosted-Only CI
+# ADR 0007: Hosted-Only CI

 **Status:** Accepted (2026-08-30). Supersedes the runner half of ADR-0004.

@@ -8,7 +8,7 @@ alignment with the stack philosophy). Two facts change the ADR-0004 calculus:

 1. **A self-hosted runner on a public repo is a standing hazard.** A fork PR
   can modify workflow files; once any run of theirs is approved, workflows
-   can target the repo's registered self-hosted runners — i.e. arbitrary code
+   can target the repo's registered self-hosted runners, i.e. arbitrary code
   on the private host, which also serves production. GitHub's own guidance is
   to never attach self-hosted runners to public repos, and personal-account
   repos have no runner groups to scope the risk away.
@@ -1,11 +1,11 @@
-# ADR 0008 — Panel Development Environment
+# ADR 0008: Panel Development Environment

 **Status:** Accepted (2026-08-30).

 ## Context
 warden-sdk was written as the SDK for WardenOS, and its documentation framed
 it that way: a support repo for one product. Since going public (ADR-0007,
-GPL-2.0-only), the actual audience is wider — anyone with a Luckfox Pico 86
+GPL-2.0-only), the actual audience is wider: anyone with a Luckfox Pico 86
 Panel gets a maintained 6.18 kernel, an off-device development loop, and a
 device simulator out of this repo, none of which exists elsewhere for this
 board. The product-first framing undersold that and confused the entry point
@@ -16,8 +16,8 @@ Position warden-sdk as **a modern, open development environment for the
 Luckfox Pico 86 Panel (RV1106)**. WardenOS is documented as the downstream
 consumer it is, not the purpose. Documentation follows three rules: lead with
 the board, not the product; keep private-repo references clearly marked as
-context; keep titles short — a heading names a section, it does not summarize
-it.
+context; keep titles short (a heading names a section,, it does not summarize
+it).

 ## Consequences
 - README and top-level docs lead with the hardware and the developer loop