fix(patches): validator portability, clearer docs, broader hook trigger

.superpowers/handoff/task-A8-brief.md

@@ -0,0 +1,69 @@
+### Task A8: End-to-end patch test (guarded) and version bump
+
+**Files:**
+- Modify: `tests/testthat/test-patches.R`
+- Modify: `DESCRIPTION` (version), `NEWS.md`
+
+**Interfaces:**
+- Produces: a guarded e2e test proving a dependent package builds when its failing dependency is patched.
+
+- [ ] **Step 1: Add the guarded e2e test**
+
+```r
+test_that("a patched dependency unblocks a dependent build (e2e)", {
+  skip_if_not(nzchar(Sys.getenv("BINCRAFT_PATCH_E2E")))
+  skip_if_offline()
+
+  patches_dir <- withr::local_tempdir()
+  jsonlite::write_json(
+    list(list(
+      package = "RcppParallel", versions = "*", platforms = list("*"),
+      env = list(RCPP_PARALLEL_USE_TBB = "0"),
+      reason = "bundled TBB fails on this toolchain"
+    )),
+    file.path(patches_dir, "registry.json"), auto_unbox = TRUE
+  )
+
+  out <- withr::local_tempdir()
+  result <- build_binary_package(
+    "rts2", tag = "latest", local_output_dir_root = out,
+    upload = FALSE, archive = FALSE, patches = patches_dir
+  )
+  expect_true(isTRUE(result) || identical(result, "skipped"))
+})
+```
+
+- [ ] **Step 2: Run the e2e test in a container**
+
+Run:
+
+```bash
+docker run --rm -e BINCRAFT_PATCH_E2E=1 -v "$PWD":/work -w /work \
+  reg.devxy.io/rpkgs/build-env-ubuntu:2604 \
+  Rscript -e 'devtools::load_all("."); testthat::test_file("tests/testthat/test-patches.R")'
+```
+
+Expected: the e2e test runs (not skipped) and PASSES; build log shows `Applying patch to RcppParallel`.
+
+- [ ] **Step 3: Bump version and changelog**
+
+In `DESCRIPTION`, bump `Version:` to `4.3.0.9999`. Prepend to `NEWS.md`:
+
+```markdown
+# bincraft 4.3.0
+
+* `build_binary_package()` gains a `patches` argument: a registry of
+  per-package env / configure / Makevars overrides and source diffs that are
+  pre-built into patched binaries and served to pak, fixing compiler- and
+  OS-specific failures (e.g. RcppParallel) including for transitive deps.
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add tests/testthat/test-patches.R DESCRIPTION NEWS.md
+git commit -m "test(patches): guarded end-to-end test; bump to 4.3.0.9999"
+```
+
+---
+