[#455] Task 6: document status taxonomy + breaking change in CHANGELOG/README

[sgbett]

Part of #455.

Summary

User-facing documentation and changelog for the status-taxonomy realignment. Breaking change — must be clearly flagged for consumers.

Scope

• gem/bsv-wallet/CHANGELOG.md
• gem/bsv-wallet/README.md
• docs/gems/wallet.md

Skip: no CLAUDE.md edits needed.

Changes

gem/bsv-wallet/CHANGELOG.md

Add an entry under the next unreleased version (0.8.x or 0.9.0 — TBD by release tagger):

• Breaking change marker.
• Summary: 'completed' now means "proven on-chain" (merkle proof stored). Post-broadcast success is now 'unproven' until a proof arrives.
• WalletError now raised when create_action/sign_action is called without a broadcaster and without no_send: true.
• Link to HLR [HLR] Align action status taxonomy with reference SDK; fail loudly on broadcast misconfiguration #455 and upstream incidents: x402-rack [Task 3] S1: Use BN.mod_add in PrivateKey#derive_child #148, x402-rack [Task 2] Testing: SymmetricKey specs with cross-SDK vectors #158, x402-doom [HLR] Implement BRC-100 Wallet Interface as bsv-wallet companion gem #196.
• Migration notes for consumers querying list_actions(status: 'completed'): they will see fewer results until a proof-watcher lands (out of scope per HLR). To find successfully-broadcast actions, query status: 'unproven'.

gem/bsv-wallet/README.md

Add or expand a "Status values" section with a table matching the HLR taxonomy:

Status	Meaning
'nosend'	Caller explicitly opted into no_send: true; transaction built but not broadcast.
'unprocessed'	(Reserved for async queue between enqueue and dispatch — currently unused in inline path.)
'sending'	Async queue has accepted the job; worker has not yet attempted broadcast.
'unproven'	Broadcast succeeded; awaiting merkle proof.
'completed'	Merkle proof received and stored.
'failed'	Broadcast attempted and rejected by the network.

Document the broadcaster requirement: create_action requires either a broadcaster: passed to WalletClient.new, a broadcast_queue: whose adapter has an embedded broadcaster, or options: { no_send: true } per call.

docs/gems/wallet.md

Add a "Status meanings" section mirroring the README table. Additionally:

• Explain the consumer-visible impact: list_actions(status: 'completed') returns fewer results until a proof-watcher lands (follow-up; out of scope for HLR [HLR] Align action status taxonomy with reference SDK; fail loudly on broadcast misconfiguration #455).
• Note that wallets configured with a SolidQueueAdapter carrying an embedded broadcaster satisfy the broadcaster requirement even if the WalletClient itself has broadcaster: nil.

Acceptance criteria

• CHANGELOG.md has a breaking-change entry citing HLR [HLR] Align action status taxonomy with reference SDK; fail loudly on broadcast misconfiguration #455 and the upstream incidents (x402-rack [Task 3] S1: Use BN.mod_add in PrivateKey#derive_child #148, [Task 2] Testing: SymmetricKey specs with cross-SDK vectors #158; x402-doom [HLR] Implement BRC-100 Wallet Interface as bsv-wallet companion gem #196).
• README documents the status taxonomy with a plain-language explanation of each value.
• README documents the broadcaster requirement and the three ways to satisfy it.
• docs/gems/wallet.md explains the consumer-visible impact of the 'completed' semantic shift.
• All three docs use British English consistently.

Files modified

• gem/bsv-wallet/CHANGELOG.md
• gem/bsv-wallet/README.md
• docs/gems/wallet.md

Sequencing

Can be written in parallel with Tasks 1-5 (no code dependency). Must land before release (Task 7).

[sgbett]

Completed in d925c86. gem/bsv-wallet/CHANGELOG.md has a breaking-change entry under 0.9.0 (unreleased) with full migration notes and references to the upstream incidents. gem/bsv-wallet/README.md has Status values and Broadcaster requirement sections. docs/gems/wallet.md has a Status meanings section with the consumer-impact note. Landed via PR #463.