From e3ea739d7c7d6d58e5ef24c075108841c50451ce Mon Sep 17 00:00:00 2001
From: Matt Stanley <1379tech@gmail.com>
Date: Wed, 21 Oct 2026 13:25:01 -0700
Subject: [PATCH] Check BIOS stamps on PRs and clarify regeneration and commit
 guidance (#729)

---
 .github/workflows/pr-bios-stamps.yml | 17 +++++++++++++++++
 AGENTS.md                            |  4 ++++
 CONTRIBUTING.md                      | 20 ++++++++++++++++++++
 runtime/runtime.cmake                |  9 ++++++++-
 4 files changed, 49 insertions(+), 1 deletion(-)
 create mode 100644 .github/workflows/pr-bios-stamps.yml

diff --git a/.github/workflows/pr-bios-stamps.yml b/.github/workflows/pr-bios-stamps.yml
new file mode 100644
index 00000000..d6fa5e16
--- /dev/null
+++ b/.github/workflows/pr-bios-stamps.yml
@@ -0,0 +1,17 @@
+name: BIOS emitter stamps
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  bios-stamps:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Check committed BIOS emitter stamps
+        shell: bash
+        run: bash tools/ci/check_bios_stamps.sh --framework .
diff --git a/AGENTS.md b/AGENTS.md
index 36e7ca73..24dbeb89 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -13,3 +13,7 @@ shared HLE work is `beads-wuhs`. Do not initialize a local issue database.
 Work solo unless the owner authorizes delegation for the task. For the approved
 parity campaign, serialize title builds and game runs: two compile jobs per
 build, one game instance, and preserve the owner's sessions and personal saves.
+
+Commit messages use a subject only by default. Add a body only when the reason
+is not clear from the diff, and keep it to 1-3 lines. Do not add per-file
+changelogs or repeat the diff or PR description.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c0871f53..33ffc99e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -82,6 +82,26 @@ written — is likely to be rejected if it:
 - Contains code the contributor cannot reasonably explain, or whose verification
   cannot be stated.
 
+### Commit messages
+
+Use a subject only by default. Add a body only when the reason is not clear
+from the diff, and keep it to 1-3 lines. Do not add per-file changelogs or
+repeat the diff or PR description.
+
+### BIOS emitter changes
+
+After changing a BIOS fingerprint input, run
+`bash tools/regen_bios.sh --config bios/OpenBIOS.toml` and commit the regenerated
+OpenBIOS output and stamp together. PR CI checks the committed stamps without
+requiring a retail BIOS dump. Never update a stamp without regenerating.
+
+Retail-dump users must also regenerate each linked retail stem, for example
+`bash tools/regen_bios.sh --config bios/SCPH1001.toml`. Retail dumps and generated
+retail C/stamps stay local and gitignored. In the PR validation notes, name the
+BIOS stems checked and whether their output changed; explicitly say when a
+retail stem was not checked. Unchanged OpenBIOS output does not establish
+unchanged SCPH1001 output.
+
 ## Game-specific work belongs in game repos
 
 The framework stays game-agnostic. Per-game patches, launcher UI, assets, memory
diff --git a/runtime/runtime.cmake b/runtime/runtime.cmake
index f84eab05..f4d8d849 100644
--- a/runtime/runtime.cmake
+++ b/runtime/runtime.cmake
@@ -907,6 +907,13 @@ if(NOT PSXRECOMP_SKIP_BIOS_STALE_CHECK AND _psxrt_bios_linked)
                     else()
                         set(_psxrt_stale_sev WARNING)
                     endif()
+                    if(_psxrt_chk_stem MATCHES "^SCPH")
+                        set(_psxrt_stale_publish
+                            "Retail dump/generated outputs stay local and gitignored; do not commit them.")
+                    else()
+                        set(_psxrt_stale_publish
+                            "Commit the regenerated ${_psxrt_chk_stem}_*.c and .emitter.sha together.")
+                    endif()
                     message(${_psxrt_stale_sev}
                         "BIOS generated/${_psxrt_chk_stem}_*.c is STALE vs the recompiler "
                         "emitter (fingerprint mismatch).\n"
@@ -915,7 +922,7 @@ if(NOT PSXRECOMP_SKIP_BIOS_STALE_CHECK AND _psxrt_bios_linked)
                         "  The committed C may not match the current emitter source, "
                         "seeds or profile.\n"
                         "  Fix:  tools/regen_bios.sh --config bios/${_psxrt_chk_stem}.toml "
-                        "and commit generated/${_psxrt_chk_stem}_*.c + .emitter.sha\n"
+                        "\n  ${_psxrt_stale_publish}\n"
                         "  (Suppress locally: -DPSXRECOMP_SKIP_BIOS_STALE_CHECK=ON)")
                 endif()
             endif()