docs: Prepare the v1 review handoff

Before freezing the v1 review candidate:

Field-test follow-ups #99–#104 now have a concrete v1 disposition. #99 removed the unrelated <5250 cap change, is below the authorized <5200 limit, has a current-head Codex ACK plus green Python/Core CI, and belongs in v1 because it closes the supplied adversarial audit's Bitcoin-Core-boundary UX gap. #100 is explicitly deferred to post-v1. #104 is also explicitly deferred: its recovery-identity delta has a focused security ACK, but the current implementation exceeds <5200 and is not required to close the supplied audit. #101 removed its cap change, is below <5200, and has a current-head Codex ACK plus green Python CI. #102 is docs-only, reviewed, and green. #103 is below <5200, has a complete focused security review with no reportable finding, a current-head follow-up ACK, and green exact-head CI. Before freeze, integrate or explicitly defer #101/#102/#103; no v1 decision depends on approving <5250.

The focused cleanup PRs are #115 (contributor guide), #116 (historical benchmark evidence), #117 (Core test-double signature), and #127 (all-report disposition ledger and remaining contract clarifications). #126 separately closes the previously missed existing-secret BIP32-root path from #125; merged #16 covered only raw bytes. The local ignored checklist docs/planning/v1-pre-review-cleanup.md records mechanical follow-ups for agents working in this checkout; verify each item on the frozen integration tip before the one-commit cleanup.

Post-audit release-gate fixes are #130 (#128, unauthenticated unused descriptor API) and #132 (#129, correction-edit default-rendering disclosure). Keep both in the frozen library candidate; they were found after the four supplied reports and are not retroactively attributed to those reviewers.

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 exports 24 names; focused api: Remove unused public entry points #130 supersedes wallet: Privatize Core descriptor records #64 by removing obsolete core_descriptors plus unused fresh Core Lightning generation exports, so the frozen v1 package __all__ should contain 22 names after api: Remove unused public entry points #130. 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__.
The maintainer approved a separate GUI cap of <2250 logical lines for the restore-identity gate. Draft gui: Require wallet identity before restore #118 updates the enforcement test and both developer guides; its GUI measures 2,177 lines. Keep the library <5200 cap separate.
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 handoff: docs: Trim offline signing to what Core's tutorial lacks #93 now documents only Tails/offline setup and links the maintained Core tutorial; the maintainer cNACK removed bespoke QR/signing mechanics. docs: Size recovery cards to the backup length #96 supplies the 48- and 74-character printable cards. docs: Answer first-time questions in the user guide #97 answers first-use questions against wallet: Require the recorded fingerprint before import #57, correctly distinguishes unshared fingerprint-derived identifiers, and includes the identical 256-bit template so its link resolves without depending on docs: Size recovery cards to the backup length #96. Integrate docs: Size recovery cards to the backup length #96 first for the standard-card update. docs: Size recovery cards to the backup length #96's exact head a77f83b was printed by Chromium 154 on 2026-10-04: both templates are one 792×612 pt US-letter landscape page; 160-dpi raster inspection found all 12 and 19 numbered boxes visible, including the half-width final box, with no clipping or overlap. A physical paper proof remains optional human qualification. docs: Answer first-time questions in the user guide #97 states that 54/61/67/127-character backups do not yet have dedicated templates. 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), cli: Name the real Bitcoin Core requirement when it is missing #99's audited Core-boundary/error-path fix, 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:

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.
Already integrated into reviewability-v1: Wallet: use Core for setup and remove test crypto deps #7, correct: Interpret mixed-case damage #42, Define correction exit statuses #45, and Remove pre-review CLI dead code #46. Verify the current base tip, then begin the remaining restore stack at wallet: Require the recorded fingerprint before import #57; do not replay the historical correct: Interpret mixed-case damage #42 fixups.
Integrate the refreshed library/CLI line in order wallet: Require the recorded fingerprint before import #57 → cli: Remove unreachable recovery and search paths #105 → cli: Name the real Bitcoin Core requirement when it is missing #99 → 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 deliberately moves immediately after wallet: Require the recorded fingerprint before import #57 because its reviewed dead-code reduction keeps later tips below the authorized <5200 cap. cli: Name the real Bitcoin Core requirement when it is missing #99 is already based on cli: Remove unreachable recovery and search paths #105, has a current-head code ACK and green Python/Core CI, and closes the supplied audit's misleading hard-Core-boundary UX; place it before wallet: Distinguish unavailable Bails checks #80 because both cli: Name the real Bitcoin Core requirement when it is missing #99 and wallet: Distinguish unavailable Bails checks #80 touch the Core/CLI boundary. Then refresh wallet: Distinguish unavailable Bails checks #80 once onto cli: Name the real Bitcoin Core requirement when it is missing #99 and carry wallet: Check existing seed before sharing #81/cli: Announce recovery secret switch #95 forward without changing their reviewed behavior. Rerun the identity-mismatch regression, cli: Name the real Bitcoin Core requirement when it is missing #99 missing-Core/fallback regressions, 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 #105 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/cli: Name the real Bitcoin Core requirement when it is missing #99/wallet: Distinguish unavailable Bails checks #80/wallet: Check existing seed before sharing #81/cli: Announce recovery secret switch #95 contain agent-authored follow-ups and require the repository's responsible-human rewrite/squash policy before integration.
Refresh onto that settled wallet: Require the recorded fingerprint before import #57 → cli: Remove unreachable recovery and search paths #105 → cli: Name the real Bitcoin Core requirement when it is missing #99 → 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 in dependency order: api: Remove unused public entry points #130 → wallet: Validate Bitcoin Core state types #12 → bip93: Reject non-ASCII normalized input #13 → bip93: reject HRPs longer than 83 characters #33 → correct: Redact correction edit characters #132. api: Remove unused public entry points #130 supersedes wallet: Privatize Core descriptor records #64 and should be replayed as its focused current API-removal patch, without restoring obsolete pre-Wallet: use Core for setup and remove test crypto deps #7 Core code. correct: Redact correction edit characters #132 follows bip93: reject HRPs longer than 83 characters #33 because both touch correction.py; preserve the reviewed bip93: reject HRPs longer than 83 characters #33 HRP behavior and apply the narrow correct: Redact correction edit characters #132 CorrectionEdit rendering change afterward. Where two overlap, preserve already-reviewed behavior and perform only the mechanical restack needed by the moved base.
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.
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, api: Remove unused public entry points #130, and correct: Redact correction edit characters #132 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 api: Remove unused public entry points #130, package-level codex32.__all__ should contain 22 names; the api: Expose reference-vector helpers #53 module-level helper publication does not change that count. Rewrite/squash its Codex-authored follow-up under the responsible human author before merge. Then integrate focused generation: Validate roots before re-sharing #126 (existing-secret root validation; 953 normal and 953 optimized tests pass) and docs: Close adversarial audit tracking gaps #127 (complete finding dispositions and remaining API/user-guide clarifications). Both target the api: Expose reference-vector helpers #53 branch, not master. Their cleanup keeps the composed cli: Name the real Bitcoin Core requirement when it is missing #99 + root-validation proof below the existing library cap; no <5250 increase is needed.
Refresh late user documentation on the settled runtime/API tip: docs: Trim offline signing to what Core's tutorial lacks #93 → docs: Size recovery cards to the backup length #96 → docs: Answer first-time questions in the user guide #97. docs: Trim offline signing to what Core's tutorial lacks #93's current bbf4daa defines the prepared Tails stick, shuts Core down before cloning Persistent Storage, separates the offline boot USB from transfer media, and requires unlocking storage with networking disabled. Its checks are completing. docs: Size recovery cards to the backup length #96 is reviewed and CI-green; both card print previews were verified at a77f83b. docs: Answer first-time questions in the user guide #97's 1cf1a17 is CI-green and fixes the two latest review findings: unshared identifier wording and the missing 256-bit card target. Record current-head review of these follow-ups, then apply the responsible-human rewrite/squash policy.
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 → test: Match GUI card walkthrough to responsive layout #119. test: Match GUI card walkthrough to responsive layout #119 updates the stale fixed-four-column Xvfb walkthrough and developer guide for gui: Apply Tails field-test feedback #77's intentional responsive card layout; its headless walkthrough passes, while the Tails visual resize pass remains required. Replay/squash the focused GUI restore-identity commit from draft gui: Require wallet identity before restore #118 after the clean GUI stack is on the settled library/CLI tip. gui: Require wallet identity before restore #118 uses a disposable gui: Let the home window choose its height #78 + bip93: reject HRPs longer than 83 characters #33 integration base only to make its diff testable; do not merge that staging base or gui: Require the recorded fingerprint before import #28's duplicated historical library snapshot as release commits. Resolve gui: Give home actions distinct artwork #76 from actual Tails visual evidence, then run the recorded Tails/manual GUI qualifications.
Only after those tips are frozen, open the focused handoff-document PR required by this issue and pin the exact candidate commits.
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.

The finished finding map is proposed in #127 at docs/security/adversarial-2026-10-04.md; it is not the final frozen-tip handoff. On 2026-10-04, a local #53/#126 proof with the reviewed #99 delta and #127's AST-equivalent cleanup passed 59 focused Core/CLI/disclosure tests and the official Core 32.0rc2 regtest fixture. These limited checks do not replace the final integrated full suite, artifact qualification, Tails visual pass, or GUI-to-Core qualification.

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.

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.

Current dependency-aware human review order from the release-gate audit (refreshed 2026-09-27):

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.
Trusted-computer/security-boundary docs: docs: Define trusted-computer boundary #59. Clean and reviewable.
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.
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.
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.
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.
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.
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.
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.
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.
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.

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

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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.

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

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.
Wallet: use Core for setup and remove test crypto deps #7 next. It is the central contributor/test-boundary change.
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.
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.
Correction behavior: correct: Interpret mixed-case damage #42 → Define correction exit statuses #45 → Remove pre-review CLI dead code #46.
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.
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.
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.
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.
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.
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.

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.

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.

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

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.
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.
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.
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.
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.
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__.
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.
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.
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.
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.
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.

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.

cli: Remove pre-review dead code

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.

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.

Remove stale manifest exclusion

Audit-tracker correction (Codex, maintainer-authorized): the 2026-10-05 03:42 comment is stale where it says #130 also closes #129. The fixes were split after review: #130 head 2cbd2793ae fixes #128 / removes the unused descriptor and fresh-CL-generation APIs; #132 head f64da6f9d9 separately fixes #129 by redacting CorrectionEdit.observed / replacement from default repr. Both exact heads have green current checks and exact-head Codex no-major-issue reviews. The issue body and #127 ledger already carry the correct split; use them instead of the older comment when preparing the human integration order.

docs: Address contributor review feedback

docs: Fix Windows pip quoting

docs: Restore contributor workflow structure

docs: Correct contributor task-list link

2026-10-05 gate refresh from current GitHub state:

docs: Trim offline signing to what Core's tutorial lacks #93 latest maintainer cNACK is addressed at 1dcee71; both new inline threads are resolved. Exact-head Python-package run 823 and one current-head Codex review are pending.
docs: Replace contributor boilerplate #115 contributor-guide review finding is fixed at 2511af8; exact-head run 821 is pending. Its only unresolved thread is the deliberate responsible-human authorship/rewrite gate.
gui: Add optional graphical interface #65 intentionally retains one unresolved parent-only restore-mode finding; mandatory gui: Refresh empty wallets automatically #66 removes that transition and is green. Do not integrate gui: Add optional graphical interface #65 without gui: Refresh empty wallets automatically #66.
Every other PR in the current docs: Prepare the v1 review handoff #38 audit/release matrix has a SUCCESS check rollup and zero unresolved review threads, and all carry gate: adversarial review.

No human integration was performed. This comment is current-state metadata only and does not change the planned integration order.

Integration-order clarification for the audit closeout (2026-10-05): after the runtime/foundation line and before the final handoff freeze, include the focused cleanup PRs #115 → #116 → #117 with the audit/release-support work. #115 now preserves the upstream contributor workflow while adapting python-codex32 setup/policy, and its latest content review finding (the task-list URL) is fixed at 2511af8; the only intentionally open review thread is the responsible-human authorship/rewrite requirement. #116 and #117 are exact-head CI-green with no unresolved review threads. This comment fills the omission in the numbered order; it does not change their scope.

Also, the step-7 #93 head named in the issue body is stale: maintainer follow-ups are now at 1dcee71, with all review threads resolved; its current exact-head matrix is still settling. Use the PR head, not the older bbf4daa, when freezing the documentation stack.

cli: Trim two lines from the early record gate

cli: Announce recovery secret switch

tests: Match Core initializer signature

cli: Trim two lines from the early record gate

cli: Announce recovery secret switch

2026-10-06 current-head review refresh (maintainer-authorized):

The audit-critical runtime/foundation line now has direct current-head AI reviews at #105 9ea48de, #99 27f4cc6, #80 096b654, #81 ada987b, #95 278be78, #130 71a792b, #12 bbcfb56, #13 4f01561, and #33 b1b1b27. Exact-head CI is green for each applicable current head; #130's Python matrix and Core fixture both completed successfully. #117 f4004a3, #23 d07024a, #59 ede98a8, #52 9cf9f44, #93 23d909f, #96 a77f83b, and GUI restore gate #118 f871e59 also have current-head AI reviews. #115/#116/#126/#127/#53 already had current-head AI review evidence.

Post-audit rendering hardening now also includes #133 58addc6, following merged #132: WorksheetCorrection.addend is excluded from default repr, exact-head CI is green, and current-head review found no blocker. Include #133 in the frozen library candidate after the settled correction surface; do not treat it as an original four-report finding.

GUI parent #65 d6dfa81 has been reviewed explicitly as a stack parent only. It still contains the known standalone manual-refresh restore-mode defect fixed by mandatory #66 and is currently non-mergeable against the advanced library base. Do not integrate #65 alone; keep the planned #65 → #66 → #77 → #78 → #119 stack, then replay #118.

#97 remains CI-green and previously current-head reviewed but is presently non-mergeable; refresh it once after the runtime/API tip settles, as already planned. No human integration or signatures were performed by this update.

docs: Replace contributor boilerplate

Navigation Menu

Repository navigation

docs: Prepare the v1 review handoff #38

Human integration order

63 remaining items

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

docs: Prepare the v1 review handoff #38

Description

Human integration order

Activity

BenWestgate commented on Sep 24, 2026

BenWestgate commented on Sep 25, 2026

BenWestgate commented on Sep 25, 2026

BenWestgate commented on Sep 25, 2026

BenWestgate commented on Sep 25, 2026

BenWestgate commented on Sep 25, 2026

BenWestgate commented on Sep 25, 2026

BenWestgate commented on Sep 27, 2026

BenWestgate commented on Sep 27, 2026

BenWestgate commented on Sep 27, 2026

BenWestgate commented on Sep 27, 2026

63 remaining items

BenWestgate commented on Oct 5, 2026

BenWestgate commented on Oct 5, 2026

BenWestgate commented on Oct 5, 2026

BenWestgate commented on Oct 7, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions