docs: Prepare the v1 review handoff

[BenWestgate]

Before freezing the v1 review candidate:

• Add docs/developer/reviewing.md with the exact base and pre-handoff integration commits, scope, review order, PR stack, evidence-regeneration commands, and intentional exclusions.
• Replace the inherited Bitcoin Core boilerplate and dead links in CONTRIBUTING.md.
• Mark the alignment benchmark as a snapshot of commit 6802d86; separate historical measurements from current verification.
• Correct the documented public API count from 25 to 24.
• State plainly that ms32 secret, ms32 share, and ms32 correct require Bitcoin Core, while the corresponding codex32 commands are the Core-independent fallback.
• Point reviewers to the existing size-budget test.
• Freeze and identify both the library/CLI candidate and the GUI integration candidate. The final fresh adversarial review must cover the GUI as well as the library and CLI, with manual GUI test steps recorded for behavior that CI cannot exercise.
• Link the guide from the final human-authored PR description, which must pin the complete candidate commit or commits.

Keep planning notes out of the shipped documentation. This handoff is intentionally the last documentation change, after the implementation, packaging, security, and GUI integration stacks are settled; opening its PR earlier would make the required commit identifiers stale.

Refs #5.

[BenWestgate]

Agent handoff note: the ignored local checklist is docs/planning/v1-pre-review-cleanup.md. Its three mechanical code items are implemented in #46 (commit 11e1a2d); #46 also contains the reviewer-facing checklist comment. Before writing docs/developer/reviewing.md, confirm #46 and the remaining #38–#41 gates are represented in the frozen integration candidate.

[BenWestgate]

Release-gate sequencing note: this is intentionally the last review/handoff change, after the implementation/packaging/security PR stack has been merged or assembled into the candidate branch. Its acceptance criteria require the exact base and pre-handoff integration commits and the complete candidate SHA, so opening it now would immediately make those identifiers stale. The current pass is keeping it as the final dependency-aware handoff rather than inventing placeholder SHAs.

[BenWestgate]

Current dependency-aware human review order from the release-gate audit (final handoff SHAs still wait for integration):

1. Parser/security foundations on reviewability-v1: bip93: Require integer header thresholds #11, bip93: Reject non-ASCII normalized input #13, generation: Validate supplied BIP32 seeds #16, bip93: reject HRPs longer than 83 characters #33, then Core state validation wallet: Validate Bitcoin Core state types #12.
2. Remove the remaining Python wallet/secp test dependency: Remove Python wallet test dependencies #7. Its final frozen-data review nit is fixed and current CI is green.
3. Stack on Remove Python wallet test dependencies #7: Support Python 3.10 through 3.15 #36 (Python 3.10–3.15) and ci: Verify wallet fixtures against Bitcoin Core #51 (scheduled real-Core fixture verification). Refresh/rebase Support Python 3.10 through 3.15 #36 onto the current Remove Python wallet test dependencies #7 head before merge; ci: Verify wallet fixtures against Bitcoin Core #51 is already refreshed.
4. Packaging/tooling/CI foundations: build: Package referenced review evidence #14, build: Remove stale manifest exclusion #54 (both touch MANIFEST.in, so merge one then refresh the other), Remove repository agent overrides #48, Restrict test workflow permissions #50, Test optimized mode and constants in CI #47, api: Expose reference-vector helpers #53.
5. Correction behavior stack: correct: Interpret mixed-case damage #42 → Define correction exit statuses #45 → Remove pre-review CLI dead code #46. If bip93: reject HRPs longer than 83 characters #33/api: Expose reference-vector helpers #53 land first, refresh this stack once rather than making reviewers chase duplicate conflict resolutions.
6. Restore accident-safety boundary: wallet: Require the recorded fingerprint before import #57 after the Core/test foundations above. The current head is green and all review threads are resolved. wallet: Encrypted descriptor backup keyed by the seed #55 remains a separate malicious-tampering/descriptor-backup issue, not a prerequisite for this release accident-safety gate.
7. Security-audit record: docs: Record security audit verdict #23, after the restore threat-model wording and implementation are settled. Its corrected head is green.
8. GUI line: gui: Warn the checksum completer, not just the recoverer #10 can be reviewed independently; then integrate current reviewability-v1 + wallet: Require the recorded fingerprint before import #57 into the GUI base and review gui: Require the recorded fingerprint before import #28's window-specific restore flow. Do not merge gui: Require the recorded fingerprint before import #28's duplicated shared-library snapshot before that integration.
9. Release machinery: release: Qualify exact artifacts before publish #52 after supported-Python, CI, packaging, Core-fixture, and restore-gate changes are settled. Its workflow is green today, but final qualification must repin/rerun if Bitcoin Core 32 advances beyond rc2.
10. master-only CodeQL cleanup ci: Restrict legacy master workflow permissions #58 is independent of the v1 branch. Its permission diff is clean; the legacy master Python 3.13 install failure is unrelated/pre-existing.
11. Final candidate integration, then this docs: Prepare the v1 review handoff #38 handoff PR/documentation with exact base/integration/candidate SHAs and evidence-regeneration commands. Run the release qualification on that frozen candidate.

PR #19 stays out of this review sequence while it remains a draft/bootstrap experiment.

[BenWestgate]

Superseding the earlier sequencing note with merge-preflight evidence from the current heads:

1. Review the small independent correctness/security foundations: bip93: Require integer header thresholds #11, bip93: Reject non-ASCII normalized input #13, generation: Validate supplied BIP32 seeds #16, wallet: Validate Bitcoin Core state types #12, and docs: Define trusted-computer boundary #59. docs: Define trusted-computer boundary #59 is the previously missing Tighten v1 security invariants and define the trusted-computer boundary #4 PR and defines the trusted-computer/intentional-secret-output contract; it composes cleanly with the wallet/security branches.
2. Review and merge Remove Python wallet test dependencies #7. It is the central contributor/test-boundary fix and unblocks a clean .[dev] suite without Python secp256k1 dependencies.
3. Refresh bip93: reject HRPs longer than 83 characters #33 after Remove Python wallet test dependencies #7, then merge it. The only Remove Python wallet test dependencies #7/bip93: reject HRPs longer than 83 characters #33 collision is the import line in tests/test_generic_hrp.py (Core fingerprint stub versus generalized-HRP exceptions); the implementations themselves compose cleanly.
4. Retarget/refresh the Remove Python wallet test dependencies #7 children after Remove Python wallet test dependencies #7 lands: Support Python 3.10 through 3.15 #36 (Python 3.10–3.15) and ci: Verify wallet fixtures against Bitcoin Core #51 (scheduled real-Core fixture verification). Support Python 3.10 through 3.15 #36 has already absorbed the current Remove Python wallet test dependencies #7 head and passed a fresh .[dev] install + 864 tests, but still needs the final retarget onto the new reviewability-v1 tip.
5. Packaging/tooling/CI: build: Package referenced review evidence #14 → build: Remove stale manifest exclusion #54, plus Remove repository agent overrides #48, Restrict test workflow permissions #50, Test optimized mode and constants in CI #47. Preflight shows build: Package referenced review evidence #14/build: Remove stale manifest exclusion #54 merge cleanly despite both touching MANIFEST.in.
6. Correction behavior: correct: Interpret mixed-case damage #42 → Define correction exit statuses #45 → Remove pre-review CLI dead code #46. Then refresh and review api: Expose reference-vector helpers #53. api: Expose reference-vector helpers #53 conflicts with the correction stack in bech32.py, correction.py, and indel.py whichever direction lands first, so doing the correctness stack first avoids making three behavioral PRs chase an API-rename branch.
7. Restore accident-safety: refresh wallet: Require the recorded fingerprint before import #57 after Remove Python wallet test dependencies #7, then review/merge it. The only Remove Python wallet test dependencies #7/wallet: Require the recorded fingerprint before import #57 merge conflict is tools/bitcoin_core_regtest.py; the library/CLI verify-before-mutate reproducer is already proven. wallet: Encrypted descriptor backup keyed by the seed #55 remains separate human-planning work for encrypted-descriptor malicious-tampering resistance.
8. Merge docs: Record security audit verdict #23 after wallet: Require the recorded fingerprint before import #57/docs: Define trusted-computer boundary #59 so the finished audit record describes the settled threat model. It composes cleanly with both.
9. GUI line: review gui: Warn the checksum completer, not just the recoverer #10 independently, then integrate the settled library/CLI candidate plus wallet: Require the recorded fingerprint before import #57 into the GUI base and review gui: Require the recorded fingerprint before import #28 for its window-specific restore flow. The fresh adversarial review must include the resulting GUI candidate.
10. Release machinery: review/refresh release: Qualify exact artifacts before publish #52 only after supported-Python, CI, packaging, Core-fixture, and restore-gate changes have settled. Restrict test workflow permissions #50 + Test optimized mode and constants in CI #47 + release: Qualify exact artifacts before publish #52 compose cleanly in isolation; final qualification must repin/rerun if Bitcoin Core 32 advances beyond rc2.
11. Freeze the integration candidate, then implement this docs: Prepare the v1 review handoff #38 handoff as the final documentation PR with exact SHAs and evidence-regeneration commands. Run release qualification and the fresh adversarial review against that frozen tip.

Two non-merge blockers remain explicit rather than hidden: #49 stays open after #53 for internal cross-module underscore-import cleanup unless the human reviewer explicitly defers that architectural work from the v1 gate; PR #19 remains a draft/bootstrap CI experiment and is outside this sequence. PR #58 is already merged on master.

[BenWestgate]

Superseding the earlier sequencing note with the final preflight corrections from the current heads:

1. Small independent foundations on reviewability-v1: bip93: Require integer header thresholds #11, bip93: Reject non-ASCII normalized input #13, generation: Validate supplied BIP32 seeds #16, wallet: Validate Bitcoin Core state types #12, docs: Define trusted-computer boundary #59.
2. Remove Python wallet test dependencies #7 next. It is the central contributor/test-boundary change.
3. After Remove Python wallet test dependencies #7 lands, refresh bip93: reject HRPs longer than 83 characters #33 (only the tests/test_generic_hrp.py import block conflicts), refresh wallet: Require the recorded fingerprint before import #57 (only tools/bitcoin_core_regtest.py conflicts), and retarget/refresh the Remove Python wallet test dependencies #7 children Support Python 3.10 through 3.15 #36 and ci: Verify wallet fixtures against Bitcoin Core #51 onto the new reviewability-v1 tip.
4. Packaging/tooling/CI: build: Package referenced review evidence #14 → build: Remove stale manifest exclusion #54, plus Remove repository agent overrides #48, Restrict test workflow permissions #50, Test optimized mode and constants in CI #47.
5. Correction behavior: correct: Interpret mixed-case damage #42 → Define correction exit statuses #45 → Remove pre-review CLI dead code #46.
6. Then refresh/review api: Expose reference-vector helpers #53. Its public/reference-vector API work satisfies and should close api: Stop requiring private vector helpers #49; the audit found no benefit in a churn-only rename of the remaining subsystem-private helpers. Do not leave api: Stop requiring private vector helpers #49 open for that.
7. Restore accident-safety: refreshed wallet: Require the recorded fingerprint before import #57. wallet: Encrypted descriptor backup keyed by the seed #55 remains separate human-planning work for encrypted-descriptor / malicious-tampering resistance.
8. docs: Record security audit verdict #23 after wallet: Require the recorded fingerprint before import #57/docs: Define trusted-computer boundary #59 so the finished audit record describes the settled security contract.
9. GUI: gui: Warn the checksum completer, not just the recoverer #10 independently, then integrate the settled library/CLI candidate + wallet: Require the recorded fingerprint before import #57 into the GUI base and review gui: Require the recorded fingerprint before import #28 against that integration. The final adversarial pass must include this GUI candidate.
10. release: Qualify exact artifacts before publish #52 after supported-Python, CI, packaging, Core-fixture, and restore work settle; repin/rerun if Bitcoin Core 32 advances beyond rc2.
11. Freeze the candidate, then implement docs: Prepare the v1 review handoff #38 last with exact SHAs, evidence-regeneration commands, and manual GUI steps; run qualification and a fresh adversarial review against that frozen tip.

Current readiness sweep: all open v1 gate PRs carry gate: adversarial review; no open gate PR has an unresolved inline review thread. #10/#11/#12/#16 currently show only the synthetic codex-review-gate pending even though Codex has already posted a clean result naming each current head. PR #58 is merged on master and is no longer pending release-gate work. PR #19 remains separate bootstrap/review-gate infrastructure, not part of this v1 merge order.

[BenWestgate]

Pre-review integration evidence (2026-09-25): starting from current reviewability-v1 cf1a599, I simulated the first human merge wave in the documented order #11 → #13 → #16 → #12 → #59 → #7. All six merges were conflict-free. The resulting synthetic tip passed 881 tests normally and 881 under python -O, plus Ruff check/format and mypy. No project branch was changed by this simulation.\n\nReview-churn note: #7’s only delta after its last Codex-reviewed commit is the requested extraction/documentation of frozen Core-derived fingerprints into tests/data/wallet_fingerprints.json; it changes no production code. #13’s only post-review commit is the exact resolved P2 fix to fold ASCII case per character while leaving Unicode lookalikes mismatched. I do not recommend spending another automated-review round on either delta.\n\nAfter #7 lands, refresh #33 and #57 for their already-identified one-file conflicts and retarget/refresh the #7 children #36/#51 onto the new reviewability-v1 tip.

[BenWestgate]

Post-#7 refresh preflight against the synthetic first-wave tip found exactly three mechanical conflicts and one clean retarget:

• bip93: reject HRPs longer than 83 characters #33: tests/test_generic_hrp.py import block only. Keep both InvalidChecksum/InvalidLength from bip93: reject HRPs longer than 83 characters #33 and STUB_FINGERPRINT from Remove Python wallet test dependencies #7.
• Support Python 3.10 through 3.15 #36: pyproject.toml only. Keep requires-python = ">=3.10,<3.16" and the 3.10–3.15 classifiers from Support Python 3.10 through 3.15 #36, while preserving build: Include all code license notices #15/base license metadata: license = "MIT AND BSD-3-Clause" and license-files = ["LICENSE*", "LICENSES/*"].
• ci: Verify wallet fixtures against Bitcoin Core #51: clean retarget after Remove Python wallet test dependencies #7; no content conflict.
• wallet: Require the recorded fingerprint before import #57: tools/bitcoin_core_regtest.py only. Preserve Remove Python wallet test dependencies #7’s loop that verifies every frozen CORE_FINGERPRINTS value against real Core, then compute the recovered secret fingerprint as wallet: Require the recorded fingerprint before import #57 does and pass that expected_fingerprint to each initialize() call. Do not resolve by choosing either side wholesale.

These were disposable merge simulations only; no PR branch was rewritten before #7 lands.