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

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

@@ -0,0 +1,99 @@
+### Task A7: Thread `patches` through the public build API
+
+**Files:**
+- Modify: `R/build_binaries.R` (`build_binary_package`, `execute_package_builds`, `build_single_tag`, `handle_system_dependencies`)
+- Create: `man-roxygen/param-patches.R`
+- Test: `tests/testthat/test-patches.R`
+
+**Interfaces:**
+- Produces: `build_binary_package(..., patches = NULL)` and the internal chain each carry `patches` down to `install_pkg_sys_deps()`. `handle_system_dependencies(..., patches = NULL)` passes `patches` and `arch` through.
+
+- [ ] **Step 1: Write the failing test**
+
+```r
+test_that("handle_system_dependencies forwards patches and arch", {
+  captured <- list()
+  local_mocked_bindings(
+    install_pkg_sys_deps = function(package_name, tag, local_clone_dir_single,
+                                    platform, patches = NULL, arch = NULL) {
+      captured <<- list(patches = patches, arch = arch)
+      invisible(TRUE)
+    }
+  )
+  handle_system_dependencies(
+    "RcppParallel", "5.1.11-2", "ubuntu-2604", tempfile(), "amd64",
+    NULL, NULL, NULL, NULL, NULL, NULL, NULL,
+    patches = "local/patches"
+  )
+  expect_identical(captured$patches, "local/patches")
+  expect_identical(captured$arch, "amd64")
+})
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `Rscript -e 'devtools::load_all("."); testthat::test_file("tests/testthat/test-patches.R")'`
+Expected: FAIL — `handle_system_dependencies` has no `patches` argument.
+
+- [ ] **Step 3: Create the roxygen template**
+
+```r
+# man-roxygen/param-patches.R
+#' @param patches Optional path to a patch registry directory containing a
+#'   `registry.json` (and any referenced diff files). When set, matching
+#'   packages are pre-built as patched binaries and served to `pak` during
+#'   dependency installation. Defaults to `NULL` (no patching).
+```
+
+- [ ] **Step 4: Edit the four functions in `R/build_binaries.R`**
+
+In `build_single_tag()`'s call to `handle_system_dependencies(...)`, add `patches = patches` as the final argument, and add `patches = NULL` to `build_single_tag`'s own signature plus `#' @template param-patches` to its roxygen block.
+
+Change `handle_system_dependencies` signature to end with `metadata_db_sslmode,` then add `patches = NULL`, and change its inner `install_pkg_sys_deps(...)` call from:
+
+```r
+      install_pkg_sys_deps(
+        package_name,
+        tag,
+        local_clone_dir_single,
+        platform
+      )
+```
+
+to:
+
+```r
+      install_pkg_sys_deps(
+        package_name,
+        tag,
+        local_clone_dir_single,
+        platform,
+        patches = patches,
+        arch = arch
+      )
+```
+
+In `execute_package_builds()`, add `patches = NULL` to the signature and pass `patches = patches` into its `build_single_tag(...)` call inside `worker_function`.
+
+In `build_binary_package()`, add `patches = NULL` to the signature (after `s3_package_cache`), add `#' @template param-patches` to its roxygen, and pass `patches = patches` into the `execute_package_builds(...)` call.
+
+- [ ] **Step 5: Document, test, and run package check**
+
+Run:
+
+```bash
+Rscript -e 'devtools::document()'
+Rscript -e 'devtools::load_all("."); testthat::test_file("tests/testthat/test-patches.R")'
+```
+
+Expected: PASS for the new test; `man/build_binary_package.Rd` etc. regenerated.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add R/build_binaries.R man-roxygen/param-patches.R man NAMESPACE tests/testthat/test-patches.R
+git commit -m "feat(patches): thread patches argument through build_binary_package"
+```
+
+---
+