standards: remediation report (applied items, exclusions, stale-CI findings)

Records the 2026-10-08 time-to-value standards pass: configs and doc
changes applied, kernel/** SPDX and CI enforcement left as follow-ups with
reasons, and the stale CI references (three insmodded-but-never-built test
modules, orphaned gsp_rpc_test.c, legacy driver/ build, advisory
checkpatch/cppcheck) with exact file:line for a future PR.

1 files changed, 114 insertions, 0 deletions

diff --git a/CODESTD-REPORT-2026-10-08.md b/CODESTD-REPORT-2026-10-08.md
new file mode 100644
index 0000000..e07c4a9
--- /dev/null
+++ b/CODESTD-REPORT-2026-10-08.md
@@ -0,0 +1,114 @@
+# Code-standards remediation report — 2026-10-08
+
+Branch: `ws/code-standards` (worktree `/tmp/opencode/wt-codestd`, base
+`master` @ `3956a2f3`). Source of improvements:
+`handoff-code-standards.txt` §4 (prioritized), items 1–5 of the task brief.
+Scope limits honoured: no GPU/module/QEMU/guest/ssh operations, no CI
+behaviour changes, no non-public-path prose in tracked files.
+
+## Applied
+
+| # | Item | Files | Commit |
+|---|---|---|---|
+| 1 | `.editorconfig` (root) + `.clang-format` for `kernel/`, `userspace/`, `tools/` | 4 | `c1b99f89` |
+| 2 | `docs/07-developers/onboarding-and-standards.md` §3.2: real userspace C style + userspace rules | 1 | `1abab5b6` |
+| 4 | Same doc, new §3.4: de facto commit/doc/config/SPDX conventions | (same commit) | `1abab5b6` |
+| 3 | SPDX sweep: `userspace/` (ours), `tools/`, `scripts/` | 155 | `8367674c` |
+
+Details:
+
+* **Item 1 (config-only).** Root `.editorconfig` (UTF-8, LF, final newline,
+  trim trailing whitespace; tabs for Makefiles and `kernel/**`, 4 spaces for
+  `userspace/**` and `tools/**`). `kernel/.clang-format` is Linux kernel
+  style (tabs, tab width 8, 80 columns, `BreakBeforeBraces: Linux`).
+  `userspace/.clang-format` and `tools/.clang-format` are LLVM base, 4-space
+  indent, 100 columns. Headers state that existing files are not to be
+  mass-reformatted. All three files parse as YAML (checked; `clang-format`
+  itself is not installed on this host).
+* **Item 2.** §3.2 previously said "C: same style as the kernel module where
+  practical" — contradicted by every userspace source (4-space indent, e.g.
+  `libvgpu.c` 523 space-indented lines / 0 tabs). Rewritten to state the
+  actual 4-space/~100-column style, naming (`snake_case`, `*_t`,
+  `_LIBVGPU_H_` guards, `extern "C"`), status-type error handling
+  (`vgpu_error_t`, `map_errno` at the syscall boundary, no `abort()` in
+  libraries), the SPDX rule, and the shell `set -e` / `set -euo pipefail`
+  practice.
+* **Item 4.** New §3.4 records: commit messages
+  (`<subsystem>: <description>`, issue refs `(ISSUE-0001)`), doc conventions
+  (`> Status:` preamble + `<!-- change (YYYY-MM-DD): ... -->` markers,
+  referencing `debug/risc-v-gsp-rm-vm/docs/`), `config/hardware` +
+  `config/versions` and `firmware/<SERIES>-GSP/<MAJOR.MINOR>/` layouts, and
+  the per-file SPDX enforcement point (BSD-3-Clause vs GPL-2.0).
+* **Item 3.** 159 tracked sources under `userspace/`, `tools/`, `scripts/`
+  lacked an SPDX identifier (none of the 20 `scripts/` files had one; 12
+  were in `userspace/`; the remaining 127 in `tools/`). Added the minimal
+  header to the 155
+  that are ours — `/* ... */` for `.c`/`.h`, `# ...` for `.py`/`.sh`, after
+  any shebang/coding line — plus `Copyright (c) 2026 Open-IOV contributors`,
+  matching the existing line in `tools/gen_gsp_bindata.py`. Exactly 2 lines
+  added per file, no other content touched (verified: 310 insertions, 0
+  deletions). Shell files pass `bash -n`; the 56 Python files compile.
+  * Excluded: `userspace/extern/{inc,src}` (4 files, vendored MIT) —
+    relicensing third-party code would be wrong.
+  * Note on the brief's "(0 in userspace)": the handoff actually reports
+    "no SPDX headers at all in userspace/lib or userspace/tests"; live
+    verification agreed (12 userspace files missing, 8 of them ours).
+* Docs link checker (`scripts/check-docs-links.py`): 62 files, no broken
+  relative links after the doc edit.
+
+Changed-file counts: 4 + 1 + 155 + report = 161 files across the branch;
++125 / +48 / +310 lines (report excluded).
+
+## Not applied (with reasons)
+
+* **`kernel/**` SPDX sweep + `MODULE_LICENSE("GPL v2")` normalization** —
+  explicitly out of scope for this branch ("do NOT touch kernel/** (record as
+  follow-up)"). State at base: SPDX in 17/42 top-level kernel `.c`/`.h`
+  files (22 incl. subdirs), 6× `MODULE_LICENSE("GPL")` and 1× `"GPL v2"`.
+  Needs a GPL-2.0 pass of its own; recommend it as the next standards task.
+* **CI enforcement (drop `|| true` for checkpatch/cppcheck, shellcheck +
+  `.shellcheckrc`, SPDX-header check, ruff config)** — improvement #3, but
+  the task's hard constraints forbid CI behaviour changes. Reported only
+  (below) for a future PR.
+* **Formatting `kernel/gsp_emulation.c` and `kernel/dynamic_rpc_dispatcher.c`**
+  — improvement #1 allows "convert or record an explicit exemption"; this
+  branch is config-only (no mass reformatting), so the configs carry the
+  no-mass-reformat note and these two files remain outliers until a
+  dedicated, behaviour-neutral formatting commit.
+* **Root `CONTRIBUTING.md`** (improvement #8) — not among task items 1–5.
+* **`userspace/extern/**`** — vendored MIT (cargs, tomlc99); identifiers
+  intentionally left as upstream.
+* **Study-material discipline (improvement #9)** — conventions for study
+  material are recorded alongside that material, not in this public worktree.
+* **greeneye session-format rules in tracked docs** (improvement #6, partial)
+  — §3.4 covers commit/doc/config/SPDX conventions; the session-format rules
+  already live in `debug/risc-v-gsp-rm-vm/docs/01-DESIGN.md` and
+  `26-ARCHITECTURE.md`, so they were not duplicated.
+
+## CI findings (report-only, no changes)
+
+Verified against `.github/workflows/ci.yml` and `kernel/tests/Makefile`.
+
+1. **Kernel test modules built nowhere, insmodded anyway** —
+   `.github/workflows/ci.yml:78` `sudo insmod
+   gsp_vgpu_comprehensive_test.ko` (and `:81` rmmod); `:87`
+   `gsp_vgpu_kunit_test.ko` (and `:90`); `:95` `gsp_vgpu_mock_test.ko` (and
+   `:98`). None of these modules is produced: `kernel/tests/Makefile:1` has
+   only `obj-m += gsp_emulation_test.o`. The `insmod` invocations fail the
+   step (no `|| true`), so the `kernel-test` job cannot be green as written.
+2. **Orphaned test source** — `kernel/tests/gsp_rpc_test.c` has no `obj-m`
+   entry in `kernel/tests/Makefile`, so it is never compiled.
+3. **Legacy guest-driver build** — `.github/workflows/ci.yml:69-70`
+   `make -C driver KDIR=...`; there is no `driver/` directory in the
+   repository (0 tracked files), so the step fails after `make kernel`
+   succeeds.
+4. **Advisory static analysis** — `.github/workflows/ci.yml:221`
+   checkpatch ends with `|| true` and `:226` cppcheck ends with `|| true`;
+   both can never fail the job (matches handoff §2.3).
+5. **Note (intentional):** `.github/workflows/ci.yml:249` runs
+   `./test_vgpu_userspace ... || true` with the comment "Expected to fail
+   without driver, but should run" — documented behaviour, not a defect.
+
+Suggested future PR (out of scope here): reconcile the test-module names or
+build the missing modules, drop the `driver/` step, gate checkpatch/cppcheck
+on changed files, and add shellcheck/SPDX checks.