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, and identify the committed host-specific raw benchmark files as historical evidence rather than reproducible current measurements.
• Correct the documented package-level public API count. Current reviewability-v1 actually exports 24 names while docs/developer/api.md still says 25; after wallet: Privatize Core descriptor records #64 removes the obsolete public core_descriptors export, the frozen v1 package __all__ should contain 23 names. api: Expose reference-vector helpers #53 adds supported reference-vector helpers at their owning modules and deliberately does not add them to package-level codex32.__all__.
• Update the stale GUI budget in docs/developer/api.md to the separately enforced <2050 logical-line limit. The maintainer explicitly approved gui: Refresh empty wallets automatically #66's GUI-specific increase on 2026-09-30; this is separate from the library <5200 limit.
• Document the Core boundary precisely: ms32 secret and ms32 share require Bitcoin Core for fingerprint-aware recovery/output; ms32 correct connects to Core when a master-seed correction needs fingerprint ranking/output, while valid/no-result paths may finish before that connection. The corresponding generic codex32 secret / share / correct commands are the Core-independent fallback.
• Record the deliberate mid-recovery secret behavior: if the operator supplies a complete valid S while entering shares, recovery stops using the partial share set and deliberately switches to that supplied secret. PR cli: Announce recovery secret switch #95 makes that mode switch explicit to the operator; it belongs in the frozen library/CLI candidate before the handoff.
• Record the deliberate parser divergence for an unshared secret with threshold digit 1: v1 remains stricter than the BIP-93 reference decoder and accepts only the project's documented unshared/shared header forms. State this explicitly so interoperability reviewers do not mistake the difference for an untracked parser bug.
• Point reviewers to the existing installed-package and GUI size-budget tests. The v1 installed-package cap is the maintainer-authorized <5200; do not take a pre-release refactor solely to recover the old <5000 target.
• Record the deliberate v1 exception for mixed-case correction scheduling: the public correction engine and standalone CLI retain parallel orchestration through v1 because their search-planning contracts differ (CorrectionContext generic reachable lengths versus ms32 --bytes/profile/tie-break behavior). Both paths use the same required-before-optional ordering and capture-accounting contract and are covered by focused regressions plus the frozen differential verifier. Centralizing them is post-v1 architecture work; do not take a pre-release refactor solely to remove roughly 100 lines.
• Include the late user-facing v1 documentation before the handoff: docs: Restore the qr steps for offline signing #93 restores the reviewed Bitcoin Core offline-signing QR workflow, docs: Size recovery cards to the backup length #96 supplies the 48- and 74-character printable recovery cards, and docs: Answer first-time questions in the user guide #97 answers the first-time recovery questions against the final wallet: Require the recorded fingerprint before import #57 contract. docs: Size recovery cards to the backup length #96 requires a letter-landscape print-preview of both templates. docs: Answer first-time questions in the user guide #97 must link those two templates from its length answer and state that 54/61/67/127-character backups do not yet have dedicated printable cards. These Claude/agent-authored documentation commits require responsible-human rewrite/squash before integration.
• Freeze and identify both the library/CLI candidate and the GUI integration candidate. The library/CLI candidate must include wallet: Check existing seed before sharing #81's ms32 create --existing wallet-record decision before any new share ceremony, cli: Remove unreachable recovery and search paths #105's final unreachable-path cleanup (the patch-identical replacement for historical cli: Remove unreachable recovery and search paths #98), and cli: Announce recovery secret switch #95's explicit mid-recovery secret-switch notice. The GUI candidate must include gui: Add optional graphical interface #65 plus gui: Refresh empty wallets automatically #66, Tails field-test PR gui: Apply Tails field-test feedback #77 (closing gui: Keep card-count choices neutral #71–gui: Fit the finished wallet identity on one screen #74), gui: Let the home window choose its height #78 (closing gui: Size the home window to its content #75), and the reviewed restore-authentication behavior. gui: Refresh empty wallets automatically #66's automatic wallet refresh must preserve an explicit selection when possible, disable Continue if that wallet disappears, retry transient read-only refresh failures, and allow read-only poll workers to end with the process while mutation/relocking workers remain non-daemon. gui: Apply Tails field-test feedback #77/gui: Let the home window choose its height #78 still require the supported Tails guest-resolution visual checks before the candidate is frozen. gui: Give home actions distinct artwork #76 is explicitly deferred until that Tails visual pass identifies which already-distinct bundled book graphics are being confused; do not guess an asset replacement from source filenames alone.
• 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. Human integration may squash/rewrite stacked AI-assisted follow-ups where the repository authorship policy requires it, after dependency order is settled.

Human integration order

Use this order to avoid repeatedly invalidating reviewed stacks:

1. Wallet: use Core for setup and remove test crypto deps #7 and its focused real-Core fixture follow-up ci: Verify wallet fixtures against Bitcoin Core #51 are merged into reviewability-v1.
2. Review/integrate the correction line through correct: Interpret mixed-case damage #42. Define correction exit statuses #45 and the behavior-preserving cleanup Remove pre-review CLI dead code #46 are already merged into correct: Interpret mixed-case damage #42's head branch. The current correct: Interpret mixed-case damage #42 head also contains the focused grouped-input/immutable-prefix follow-up from the latest review. Current-head CI is green and all inline review threads are resolved; the final deadline thread was closed after benchmark evidence showed both required interpretations finish well inside the shared 10-second deadline. Review Remove pre-review CLI dead code #46's focused cleanup diff as part of this stacked correct: Interpret mixed-case damage #42 review; it is no longer a separate post-correct: Interpret mixed-case damage #42 integration step. Before integration, fold the final grouped-prefix fixup into the mixed-case commit while retaining Define correction exit statuses #45's exit-status change and Remove pre-review CLI dead code #46's cleanup as separate atomic review units.
3. Integrate the refreshed restore line in order wallet: Require the recorded fingerprint before import #57 → cli: Remove unreachable recovery and search paths #105 → wallet: Distinguish unavailable Bails checks #80 → wallet: Check existing seed before sharing #81 → cli: Announce recovery secret switch #95. wallet: Require the recorded fingerprint before import #57 is replayed directly on current correct: Interpret mixed-case damage #42 with an unchanged reviewed patch-id. cli: Remove unreachable recovery and search paths #105 is the patch-identical replacement for historical cli: Remove unreachable recovery and search paths #98 and deliberately moves immediately after wallet: Require the recorded fingerprint before import #57: its reviewed dead-code cleanup reduces that tip to 5,179 logical lines, allowing wallet: Distinguish unavailable Bails checks #80, wallet: Check existing seed before sharing #81 and cli: Announce recovery secret switch #95 to remain below the authorized <5200 cap without another line-saving patch. wallet: Distinguish unavailable Bails checks #80's two reviewed patch-ids and wallet: Check existing seed before sharing #81's five reviewed patch-ids are unchanged. cli: Announce recovery secret switch #95 then makes the already-intended behavior explicit when a complete valid secret replaces a partial share-recovery session. Rerun the identity-mismatch regression, wallet: Distinguish unavailable Bails checks #80 no-record/identifier regressions, wallet: Check existing seed before sharing #81 early-gate regressions, cli: Remove unreachable recovery and search paths #98 correction/CLI regressions, cli: Announce recovery secret switch #95 recovery-mode-switch regression, the real-Core fixture, and the final full suite on the resolved tip. cli: Remove unreachable recovery and search paths #105/wallet: Distinguish unavailable Bails checks #80/wallet: Check existing seed before sharing #81/cli: Announce recovery secret switch #95 are agent-authored follow-ups and require the repository's responsible-human rewrite/squash policy before integration.
4. Refresh onto that settled correct: Interpret mixed-case damage #42 → wallet: Require the recorded fingerprint before import #57 → cli: Remove unreachable recovery and search paths #105 → wallet: Distinguish unavailable Bails checks #80 → wallet: Check existing seed before sharing #81 → cli: Announce recovery secret switch #95 tip, then integrate the small overlapping foundation fixes: wallet: Validate Bitcoin Core state types #12, bip93: Reject non-ASCII normalized input #13, bip93: reject HRPs longer than 83 characters #33, and wallet: Privatize Core descriptor records #64. For wallet: Privatize Core descriptor records #64, replay only the still-relevant API-surface cleanup onto Wallet: use Core for setup and remove test crypto deps #7's Core-native implementation; do not restore its obsolete pre-Wallet: use Core for setup and remove test crypto deps #7 _bitcoin_core.py import-record hunk. Where two overlap, preserve the already-reviewed behavior and perform only the mechanical restack needed by the moved base.
5. Integrate the audit/security/release support work that does not own runtime behavior: docs: Record security audit verdict #23, docs: Define trusted-computer boundary #59, and release: Qualify exact artifacts before publish #52.
6. Refresh api: Expose reference-vector helpers #53 exactly once after bip93: Reject non-ASCII normalized input #13, bip93: reject HRPs longer than 83 characters #33, correct: Interpret mixed-case damage #42/wallet: Require the recorded fingerprint before import #57, and wallet: Privatize Core descriptor records #64 are settled; Wallet: use Core for setup and remove test crypto deps #7 is already in the base. Preserve its supported module-level vector API and centralize the ASCII-only lower helper there. After wallet: Privatize Core descriptor records #64, package-level codex32.__all__ should contain 23 names; api: Expose reference-vector helpers #53's module-level helper publication does not change that count. Rewrite/squash its Codex-authored follow-up under the responsible human author before merge.
7. Refresh the late user-facing documentation on the settled runtime/API tip: docs: Restore the qr steps for offline signing #93, then docs: Size recovery cards to the backup length #96, then docs: Answer first-time questions in the user guide #97. docs: Restore the qr steps for offline signing #93 is already agent-reviewed and CI-green. docs: Size recovery cards to the backup length #96 is agent-reviewed and CI-green but still needs the two-template letter-landscape print-preview. docs: Answer first-time questions in the user guide #97's current head is CI-green and already fixes the random-index/default wording; finish the remaining recovery-card link/rarer-length qualification, rerun its review, then rewrite/squash the Claude/agent-authored documentation commits under the responsible human author.
8. Rebase the clean GUI stack onto the settled library/CLI tip and review it in order: gui: Add optional graphical interface #65 → gui: Refresh empty wallets automatically #66 → gui: Apply Tails field-test feedback #77 → gui: Let the home window choose its height #78. Replay/squash only the reviewed GUI restore-authentication delta from gui: Require the recorded fingerprint before import #28; do not merge gui: Require the recorded fingerprint before import #28's duplicated historical library snapshot. Resolve gui: Give home actions distinct artwork #76 from actual Tails visual evidence, then run the recorded Tails/manual GUI qualifications.
9. Only after those tips are frozen, open the focused handoff-document PR required by this issue and pin the exact candidate commits.
10. Run final artifact qualification and a fresh adversarial review over the frozen library, CLI, GUI, and user-facing recovery documentation before any human-authored master integration.

Keep planning notes out of the shipped documentation. This handoff is intentionally the last documentation change, after the implementation, packaging, security, GUI, and user-facing documentation 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 (refreshed 2026-09-27):

1. Parser/correctness 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 → wallet: Validate Bitcoin Core state types #12. bip93: reject HRPs longer than 83 characters #33's generalized-HRP vectors now cite BenWestgate/bips PR #2 @ 01374bf at head 07024bd; no vector bytes changed. bip93: Require integer header thresholds #11/wallet: Validate Bitcoin Core state types #12/generation: Validate supplied BIP32 seeds #16 show UNSTABLE only because an old synthetic codex-review-gate check has been stuck in_progress with no steps since Sep 21; their parent Actions runs completed successfully. There are no unresolved review threads or changes-requested reviews on this set.
2. Trusted-computer/security-boundary docs: docs: Define trusted-computer boundary #59. Clean and reviewable.
3. Wallet/test dependency line: Wallet: use Core for setup and remove test crypto deps #7 → ci: Verify wallet fixtures against Bitcoin Core #51. Wallet: use Core for setup and remove test crypto deps #7 was refreshed onto current reviewability-v1 at 4ceedeef and its Python 3.10–3.15/full matrix is green. ci: Verify wallet fixtures against Bitcoin Core #51 is restacked on that exact head at 0466510; its pinned real-Core v32.0rc2 fixture job and package matrix are green. Merge Wallet: use Core for setup and remove test crypto deps #7 first, then retarget ci: Verify wallet fixtures against Bitcoin Core #51 to reviewability-v1.
4. Packaging/tooling/CI foundations: build: Package referenced review evidence #14 → build: Remove stale manifest exclusion #54 → Remove repository agent overrides #48 → Restrict test workflow permissions #50 → Test optimized mode and constants in CI #47. All are clean. build: Remove stale manifest exclusion #54 intentionally removes only the stale manifest exclusion; MANIFEST.in remains because it defines the sdist/review-evidence contents.
5. Correction behavior/review-surface stack: correct: Interpret mixed-case damage #42 → Define correction exit statuses #45 → Remove pre-review CLI dead code #46. correct: Interpret mixed-case damage #42 now centralizes majority-case interpretation in one helper shared by standalone correction and interactive recovery; the earlier duplication/line-budget nit is resolved. Define correction exit statuses #45 adds the distinct correct exit-status contract; Remove pre-review CLI dead code #46 is the one-commit mechanical/dead-code cleanup. All three are clean and have no unresolved review threads. The ignored local checklist remains docs/planning/v1-pre-review-cleanup.md, and its concrete items are represented by Remove pre-review CLI dead code #46.
6. Restore accident-safety boundary: wallet: Require the recorded fingerprint before import #57. Clean. The CLI/library gate verifies the recorded fingerprint before any wallet mutation and provides the explicit no-record visual fallback. wallet: Encrypted descriptor backup keyed by the seed #55 remains the separate, human-planned encrypted-descriptor/malicious-tampering defense.
7. Helper/API boundary: api: Expose reference-vector helpers #53 after bip93: Reject non-ASCII normalized input #13/correct: Interpret mixed-case damage #42/wallet: Require the recorded fingerprint before import #57. The public reference-vector workflow no longer requires underscore-prefixed imports; the production private-import audit is documented, package-level codex32.__all__ stays deliberate, and api: Stop requiring private vector helpers #49 can close when this lands.
8. Security-audit record: docs: Record security audit verdict #23 after bip93: reject HRPs longer than 83 characters #33/wallet: Require the recorded fingerprint before import #57 are settled, so its status lines describe the release branch rather than pending fixes.
9. GUI line: review gui: Warn the checksum completer, not just the recoverer #10 first. Then review gui: Require the recorded fingerprint before import #28's GUI-specific restore behavior, but do not merge gui: Require the recorded fingerprint before import #28's current history into the final candidate: it is a sibling of gui: Warn the checksum completer, not just the recoverer #10, carries duplicated shared-library changes that belong in wallet: Require the recorded fingerprint before import #57, and contains Claude co-author trailers from exploratory commits. After gui: Warn the checksum completer, not just the recoverer #10/wallet: Require the recorded fingerprint before import #57 land, replay/squash the reviewed GUI-only delta onto the settled reviewability-v1 GUI integration branch under the responsible human author, resolve the pages.py/docs/user/gui.md overlap, and rerun automated plus manual GUI qualification.
10. Release machinery: release: Qualify exact artifacts before publish #52 after supported-Python, packaging, Core-fixture, restore-gate, and GUI integration changes settle. The workflow is clean; repin/rerun if Bitcoin Core 32 advances beyond the currently pinned rc2 before qualification.
11. Freeze the integrated library/CLI+GUI candidate, run the production-size gate and final artifact qualification, then run one fresh adversarial review against that frozen tip covering library, CLI, and GUI. Only after that write/open the docs: Prepare the v1 review handoff #38 reviewer-handoff change with exact base/integration/candidate SHAs, evidence-regeneration commands, Core-dependency/offline-fallback note, contributor cleanup, and manual-GUI steps.

master CodeQL permissions cleanup #58 is complete: alerts #1 (pylint.yml) and #2 (python-package.yml) are both fixed as of 2026-09-25T15:57:26Z. PR #19 remains separate from this v1 review sequence.

[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 Wallet: use Core for setup and remove test crypto deps #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 Wallet: use Core for setup and remove test crypto deps #7, then merge it. The only Wallet: use Core for setup and remove test crypto deps #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 Wallet: use Core for setup and remove test crypto deps #7 children after Wallet: use Core for setup and remove test crypto deps #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 Wallet: use Core for setup and remove test crypto deps #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 Wallet: use Core for setup and remove test crypto deps #7, then review/merge it. The only Wallet: use Core for setup and remove test crypto deps #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. Wallet: use Core for setup and remove test crypto deps #7 next. It is the central contributor/test-boundary change.
3. After Wallet: use Core for setup and remove test crypto deps #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 Wallet: use Core for setup and remove test crypto deps #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 Wallet: use Core for setup and remove test crypto deps #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 Wallet: use Core for setup and remove test crypto deps #7; no content conflict.
• wallet: Require the recorded fingerprint before import #57: tools/bitcoin_core_regtest.py only. Preserve Wallet: use Core for setup and remove test crypto deps #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.

[BenWestgate]

Release-gate review-order refresh (2026-09-26), incorporating the latest review-thread dispositions and Core monitor:

1. 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 → wallet: Validate Bitcoin Core state types #12. bip93: Reject non-ASCII normalized input #13’s last helper-duplication nit is resolved with the cleanup assigned to api: Expose reference-vector helpers #53. bip93: reject HRPs longer than 83 characters #33 is restored to its prior green head e49d23f; its generalized-HRP provenance nit remains intentionally unresolved after a contents-API attempt to fix only the comment also altered an adjacent long checksum vector and failed the matrix. The accidental commit was rolled back completely.
2. Remove the Python wallet/secp test dependency: Wallet: use Core for setup and remove test crypto deps #7. Its review threads are resolved and current head is green.
3. Stack on Wallet: use Core for setup and remove test crypto deps #7: Support Python 3.10 through 3.15 #36 and ci: Verify wallet fixtures against Bitcoin Core #51. Support Python 3.10 through 3.15 #36 is now based directly on Wallet: use Core for setup and remove test crypto deps #7’s final head and green. ci: Verify wallet fixtures against Bitcoin Core #51’s missing-PR-trigger nit is fixed/resolved; both its Python matrix and real-Core fixture workflow are green. Retarget both to reviewability-v1 after Wallet: use Core for setup and remove test crypto deps #7 lands.
4. Packaging/CI foundations: build: Package referenced review evidence #14 and build: Remove stale manifest exclusion #54 both edit MANIFEST.in; merge build: Package referenced review evidence #14 first, then refresh build: Remove stale manifest exclusion #54 so the final manifest keeps LICENSES/*, adds docs *.csv/*.json, removes the stale provenance exclusion, continues to prune docs/planning, and still includes requirements/tests/tools. Then 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. correct: Interpret mixed-case damage #42 is green and all review threads are resolved. Remove pre-review CLI dead code #46 should be rebased to expose only its substantive cleanup commits once Define correction exit statuses #45 is final.
6. Module/API boundary: api: Expose reference-vector helpers #53 after both bip93: Reject non-ASCII normalized input #13 and correct: Interpret mixed-case damage #42. During that refresh, centralize the duplicated ASCII-only fold as private bech32._ascii_lower, carry mixed-case policy as private _interpret_mixed_case, and keep the supported reference-vector helpers module-level without widening package __all__.
7. Restore accident-safety boundary: wallet: Require the recorded fingerprint before import #57 after the Core/test foundations above. Its verify-before-mutate boundary is green and all threads are resolved. wallet: Encrypted descriptor backup keyed by the seed #55 remains separate malicious-tampering/descriptor-backup hardening, not a prerequisite for the accident-safety release gate.
8. Security/audit documentation: docs: Record security audit verdict #23 after wallet: Require the recorded fingerprint before import #57’s threat-model wording is settled; docs: Define trusted-computer boundary #59 trusted-computer/CLI boundary docs is now green and its 80-column help nit is fixed/resolved.
9. GUI line: gui: Warn the checksum completer, not just the recoverer #10 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 its duplicated shared-library snapshot instead of the integrated library line.
10. Release machinery: release: Qualify exact artifacts before publish #52 after supported-Python, packaging, Core-fixture, restore-gate, and GUI candidate work is settled. Bitcoin Core v32 is still only rc1/rc2 upstream as of 2026-09-26, so rc2 remains pre-final evidence and must be repinned/rerun if rc3/final appears.
11. Final integration gate: assemble the exact library/CLI and GUI candidates, rerun the production <5000 logical-line budget on the complete combined tree (individual PR budget passes are not sufficient), run exact-artifact qualification, and only then open this docs: Prepare the v1 review handoff #38 handoff PR with exact base/integration/candidate SHAs and regeneration commands.

Core requirement to state literally in the handoff: ms32 secret and ms32 share connect to Bitcoin Core for fingerprint-aware recovery; ms32 correct needs Core when master-seed correction requires fingerprint ranking/output, while valid/no-result paths can finish before that connection. The corresponding generic codex32 secret/share/correct commands are the Core-independent fallback.

master CodeQL cleanup is no longer pending: #58 merged, and the two screenshot-era missing-workflow-permissions alerts are fixed. #50 remains the corresponding least-privilege change for the reviewability-v1 workflow.

[BenWestgate]

Review-order delta from the review-submission audit:

• Support Python 3.10 through 3.15 #36 is not final-ACK-ready yet. It is 0 behind Wallet: use Core for setup and remove test crypto deps #7, but current head 1b2e9c9 is still a refresh merge commit. Rebase the Python-compatibility delta linearly onto Wallet: use Core for setup and remove test crypto deps #7 head 90e5460, then rerun CI.
• Define correction exit statuses #45 is also only Concept ACK. Current head 5a826bd still contains two correct: Interpret mixed-case damage #42 refresh merges; rewrite it as a linear correct: Interpret mixed-case damage #42 + substantive exit-status commits before review. Remove pre-review CLI dead code #46 remains downstream and should be rewritten only after Define correction exit statuses #45/wallet: Require the recorded fingerprint before import #57 settle.
• gui: Require the recorded fingerprint before import #28 and wallet: Require the recorded fingerprint before import #57 are functionally ACKed but still have AI_POLICY history conditions. gui: Require the recorded fingerprint before import #28 retains Claude co-author trailers; wallet: Require the recorded fingerprint before import #57 retains both a Claude trailer and a Codex Preflight authored commit. The final GUI re-integration and wallet: Require the recorded fingerprint before import #57 merge must use human-authored rewritten/squashed commits rather than preserving those records.
• docs: Record security audit verdict #23 is ACKed with editorial nits only. Keep its historical findings scoped to audited parent c118a83; after bip93: reject HRPs longer than 83 characters #33/wallet: Require the recorded fingerprint before import #57/gui: Require the recorded fingerprint before import #28 land, add one compact post-audit status section and fix the EOF newline rather than rewriting historical finding text.
• correction: Bound alignment cache growth #24 / Bound correction alignment cache growth #21 security fix is verified and merged: _syndrome_alignment is now lru_cache(maxsize=11), with tests proving attacker-HRP churn remains bounded and one complete unknown-length search still fits in-cache.

These conditions are now the gating details behind the earlier dependency order; none changes the major sequence.

[BenWestgate]

Release-gate sequencing note: I am deliberately not opening the #38 handoff PR yet because this issue's own acceptance criteria require the exact final library/CLI and GUI candidate SHAs, and explicitly say the handoff is the last documentation change. Opening it now would immediately stale those identifiers. Current prerequisites before that one final focused docs PR are: settle #7→#51, #42→#45 plus #57, refresh #53 and #46 onto the integrated reviewability-v1, then integrate #10/#28 into the final GUI candidate and rerun GUI/manual qualification. Once those SHAs are frozen, #38 should be opened as a single final human-authored review-handoff PR.

[BenWestgate]

Release-gate inventory note: this is the only current gate: adversarial review issue without an implementation PR, intentionally. Its acceptance criteria require exact final library/CLI and GUI candidate commits plus the settled review order, so opening the handoff PR before #7/#51, #42/#45/#57/#46, #53, #59, release-workflow refresh, and final GUI integration would immediately stale those identifiers. Keep #38 unimplemented until those stacks land; then open the final focused documentation PR as the last pre-review change.