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

.superpowers/handoff/task-A4-report.md

@@ -0,0 +1,50 @@
+# Task A4 Report: Build a Patched Binary in Isolation
+
+## Status: COMPLETE
+
+## TDD Evidence
+
+### RED Phase
+Appended the three A4 tests to `tests/testthat/test-patches.R` and ran:
+
+```
+[ FAIL 3 | WARN 0 | SKIP 0 | PASS 26 ]
+```
+
+Failures were exactly as expected:
+- `could not find function "configure_args_to_build_args"`
+- `could not find function "apply_source_patch"`
+- `Can't find binding for 'download_cran_source'` (local_mocked_bindings requires the function to exist in the package namespace)
+
+### GREEN Phase
+Appended four helpers to `R/patches.R`:
+- `download_cran_source` — fetches source tarball from CRAN current or Archive URL
+- `apply_source_patch` — runs `patch -p1 --forward --batch`, returns logical
+- `configure_args_to_build_args` — formats configure args for `pkgbuild::build(args=...)`
+- `build_patched_binary` — orchestrates download → untar → patch → env-scoped build
+
+All 30 tests pass:
+
+```
+[ FAIL 0 | WARN 0 | SKIP 0 | PASS 30 ]
+```
+
+## Commit
+
+SHA: `944c7ec`
+Subject: `feat(patches): build a patched binary in isolation from CRAN source`
+Branch: `feat/package-patching`
+Repo: `/Users/pjs/git/codefloe.com/rpkgs/bincraftr`
+
+## Files Modified
+
+- `R/patches.R` — 4 new helpers appended after `describe_patch`
+- `tests/testthat/test-patches.R` — 3 new `test_that` blocks appended
+
+## Notes / Concerns
+
+- All new helpers carry `@keywords internal` exactly as specified.
+- The `apply_source_patch` test uses a patch targeting `missing.txt` which does not exist in the temp dir, so `patch` exits non-zero → `FALSE`. This correctly validates the failure path without any compilation.
+- The `build_patched_binary` test mocks `download_cran_source` to return `NULL`, so no network or compiler is involved — safe on macOS CI.
+- Implementation is verbatim from the brief; no deviations.
+- `--no-verify` was used as instructed (broken pre-commit hook in this environment).