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

.superpowers/handoff/final-fix2-bincraft-report.md

@@ -0,0 +1,79 @@
+# final-fix2-bincraft-report
+
+## Summary
+
+Critical correctness fix for the `bincraftr` package-patching feature.
+Without `Built:` in the PACKAGES index, pak recompiles from the source tarball, silently discarding build-time fixes baked in at patch time (e.g. `RCPP_PARALLEL_USE_TBB=0`).
+
+---
+
+## Fix 1 — production code (`R/patches.R`)
+
+One-line change in `prepare_patched_repo()`:
+
+```r
+# BEFORE (broken)
+tools::write_PACKAGES(contrib, type = "source")
+
+# AFTER (fixed)
+tools::write_PACKAGES(contrib, type = "source", fields = "Built")
+```
+
+`tools::write_PACKAGES` only emits extra fields when explicitly requested via the `fields` argument.
+Without it, the `Built:` line present in the tarball's DESCRIPTION is silently dropped from the PACKAGES index.
+
+---
+
+## Fix 2 — regression test (`tests/testthat/test-patches.R`)
+
+Test: `"prepare_patched_repo src/contrib layout is resolvable by available.packages"`
+
+Two additions:
+
+1. The minimal `pkgfoo` DESCRIPTION written into the tarball now includes a `Built:` line:
+   ```
+   Built: R 4.5.3; x86_64-pc-linux-gnu; 2026-06-30 00:00:00 UTC; unix
+   ```
+   This makes the tarball look like a real prebuilt binary package.
+
+2. After `prepare_patched_repo(...)`, a new assertion checks the index:
+   ```r
+   pkgs <- readLines(file.path(out, "src", "contrib", "PACKAGES"))
+   expect_true(any(grepl("^Built:", pkgs)))
+   ```
+
+The real `tools::write_PACKAGES` is used (not mocked) so the assertion is meaningful.
+The older "serves a cached binary and writes an index" test continues to mock `tools::write_PACKAGES` — that is intentional (it tests orchestration only).
+
+---
+
+## RED / GREEN evidence
+
+Verified with a standalone script calling the real `tools::write_PACKAGES` on an identical tarball:
+
+```
+RED  (old, type="source", no fields)  — Built in PACKAGES: FALSE
+GREEN (new, type="source", fields="Built") — Built in PACKAGES: TRUE
+```
+
+---
+
+## Test run (post-fix)
+
+```
+[ FAIL 0 | WARN 0 | SKIP 1 | PASS 42 ]
+```
+
+SKIP: e2e test (`BINCRAFT_PATCH_E2E` not set) — expected.
+All 42 unit/integration tests pass.
+
+---
+
+## Commit
+
+```
+10e610f fix(patches): preserve Built field so pak installs patched binary without recompiling
+```
+
+Branch: `feat/package-patching`
+Repo: `/Users/pjs/git/codefloe.com/rpkgs/bincraftr`