Add auction custody ADR and auth field clarifications

[punk6529]

Summary

• Accept ADR 0002 for auction custody before P0 auction rewrites.
• Choose explicit escrow custody, canonical auction lifecycle states, no-bid poster settlement, pull-payment-compatible settlement, indexer-ready events, and no-bid NFT claim fallback for contract posters.
• Address late Claude feedback from PR Add drop authorization ADR #20 by pinning ADR 0001 DROP_ID_TYPEHASH and clarifying mode-specific payer, price, auction-field, and poster semantics.
• Close the ADR 0001 auction recipient handoff by keeping signed auction recipient == address(0) and deriving settlement recipients from poster / highestBidder.
• Link the auction ADR from the ADR index, roadmap, test matrix, and autonomous run state.

Closes #21.
Related: #22, #12, #8, #10, #17, #18, #19.

Validation

• rg -n "^#|^##|^###" docs\adr\0001-drop-authorization.md docs\adr\0002-auction-custody.md docs\adr\README.md ops\ROADMAP.md ops\AUTONOMOUS_RUN.md
• rg -n "P0-AUCT-ADR|P0-AUCT-001|P0-AUCT-002|0002-auction-custody|#21|#22|#12|AuctionStatus|SettledWithBid|SettledNoBid" docs\adr\0002-auction-custody.md docs\adr\README.md ops\ROADMAP.md ops\AUTONOMOUS_RUN.md
• rg -n "DROP_ID_TYPEHASH|sale-mode-specific payer violation|fixed-price authorization with non-zero auction fields|auction authorization with non-zero fixed-price field|zero poster|free fixed-price|buy-now|poster == signer|payer != address\(0\)|auctionReservePrice != 0|auctionEndTime != 0|price != 0" docs\adr\0001-drop-authorization.md
• rg -n "pendingNoBidNftClaimant|no-bid NFT claim|contract poster|poster-authorized|recipient == address\(0\)|first valid bid|PRRT_kwDOM7REis6IWRh" docs\adr\0002-auction-custody.md ops\AUTONOMOUS_RUN.md
• git diff --check
• make check passed with 17 tests and known compiler/NatSpec warnings.
• powershell -ExecutionPolicy Bypass -File scripts\check.ps1 passed with 17 tests and known compiler/NatSpec warnings.
• GitHub CI passed on head 6bfa7c7.
• CodeRabbit passed with no actionable comments on head 6bfa7c7.
• Claude review threads were addressed and resolved.

Scope

Docs and roadmap/state only. No Solidity, CI, deployment, or test implementation changes are included in this PR.

Summary by CodeRabbit

• Documentation
  • Added Auction Custody ADR: escrow custody, canonical auction state machine, idempotent settlement, pull-payment rules, event catalog, cancellation and pause requirements, security/migration/test/rollout notes.
  • Marked Auction Custody ADR as Accepted and updated ADR index and roadmap.
  • Updated operational run/rollout records and PR/worklog entries.
  • Clarified authorization rules in the drop-auth ADR and expanded P0 test requirements.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds ADR 0002 accepting explicit auction custody, a canonical auction state machine, pull-payment settlement rules, required events, cancellation/pause constraints, test and rollout plans; updates ADR registry, ROADMAP, and autonomous-run tracking; and tightens ADR 0001 authorization text.

Changes

ADR 0002 Auction Custody Acceptance

Layer / File(s)	Summary
ADR 0002 Introduction and Problem Statement docs/adr/0002-auction-custody.md	Introduces ADR 0002 metadata and issue scope; documents implicit/unsafe custody and missing state-machine and settlement semantics.
Decision and Design Requirements docs/adr/0002-auction-custody.md	Specifies explicit escrow custody with a canonical state machine and idempotent settlement; enumerates public-beta requirements including custody rules, bidding/settlement permissions, no-bid behavior, idempotency, pull-payment enforcement, and cancellation/emergency constraints.
State Machine, Storage, Payment, and Events docs/adr/0002-auction-custody.md	Defines canonical auction states/transitions, required Solidity storage shape (custody, bidder/bids, end time, terminal status), payment/pull-credit policy prohibiting push ETH transfers, and required events/indexing for auction lifecycle.
Cancellation, Pause, and Rejected Alternatives docs/adr/0002-auction-custody.md	Constricts cancellation to pre-first-valid-bid and pre-end-time; requires pause-readiness for mint/auction/bidding/settlement/withdrawal; documents rejected alternatives (payout-address custody, approval-based custody, push refunds/payouts, admin-only settlement).
Impact, Testing, Rollout, Non-Goals, Risks docs/adr/0002-auction-custody.md	Summarizes security and migration impact; provides detailed test plan (creation, bidding/outbid credits, settlement idempotency/failure, cancellation timing, event assertions, emergency-withdrawal constraints); outlines rollout steps and lists non-goals and accepted risks.
ADR Registry and Ops Tracking Updates docs/adr/README.md, ops/AUTONOMOUS_RUN.md, ops/ROADMAP.md	Marks ADR 0002 as Accepted in ADR registry; updates autonomous-run durable state and worklog (PR #20 merged, PR #23 active); converts ROADMAP auction-related entries and appendices to hyperlink/issue-linked format.
Related ADR edits docs/adr/0001-drop-authorization.md	Tightens drop-authorization rules, adds DROP_ID_TYPEHASH, and expands negative-case tests to align with updated authorization semantics.
Ops runlog details ops/AUTONOMOUS_RUN.md	Advances active branch to codex/auction-custody-adr, records PR queue/worklog/decision-log updates reflecting PR #20 merge and PR #23 start.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• [P0-AUCT-001] Formalize auction custody, settlement, and lifecycle state machine #22: ADR 0002 implements the custody, state-machine, and idempotent-settlement design requested by issue #22.
• [P0-AUCT-002] Fix auction bidding reentrancy and convert outbid refunds to pull credits #12: ADR 0002 defines pull-payment/outbid-credit rules relevant to the outbid-refund and settlement behavior discussed in issue #12.

Possibly related PRs

• 6529-Collections/6529Stream#3: Operational-document updates to ops/ files overlap with this PR's autonomous-run and ROADMAP edits.

Poem

🐰 In escrow's burrow logic softly laid,
States march tidy, bids in order paid,
Pull-credit carrots, no push-ETH chase,
Events light paths so indexers can trace,
A rabbit cheers: custody finds its place!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main changes: adding the auction custody ADR (0002) and clarifying auth fields in ADR 0001, which are the primary subjects of this PR.
Linked Issues check	✅ Passed	The PR fully meets all coding and documentation requirements from issue #21: ADR 0002 is added and marked Accepted, canonical state machine defined, custody model specified, settlement semantics documented, cancellation policy included, event schema defined, and follow-up issues linked.
Out of Scope Changes check	✅ Passed	All changes are in scope: ADR documentation, roadmap/state updates, and ADR 0001 clarifications directly supporting the auction custody design decision. No unrelated code changes were introduced.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/auction-custody-adr

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[punk6529]

@claude please review this docs-only ADR PR for auction custody, settlement state-machine completeness, payment-accounting dependency clarity, and whether the roadmap links are issue-ready for the follow-up implementation work.

[punk6529]

@claude please review the latest head. This now includes ADR 0002 plus the still-valid late ADR 0001 clarifications from PR #20: canonical DROP_ID_TYPEHASH, sale-mode-specific payer/price/auction fields, zero poster, and poster attribution semantics.

[punk6529]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[punk6529]

@claude please verify the latest head 4ba0d83 after the state-machine fix. The open thread was addressed by explicitly defining Created -> Active as custody confirmation, adding custody / custodyConfirmed to derived status inputs, and adding required tests for activation plus bid rejection before custody confirmation.