feat: implement core auction logic and env loader

- Add auction.py with add_bid and find_winner functions
- Add env.py with stdlib-based .env loader (no python-dotenv)
- Add tests/test_auction.py with test cases for auction functions
- Remove .env.example (tokens not meant to be committed)
- Update docs/plan.md to mark Milestone 2 as complete

src/secret_auction/auction.py

@@ -0,0 +1,27 @@
+"""! @file auction.py
+@brief Core blind auction logic (no input/output).
+"""
+
+
+def add_bid(bids: dict[str, float], name: str, amount: float) -> None:
+    """! @brief Record a bid, replacing any earlier bid by the same bidder.
+    @param bids Dictionary mapping bidder name to bid amount (modified in place).
+    @param name Name of the bidder.
+    @param amount Bid amount; must not be negative.
+    @throws ValueError If the amount is negative.
+    """
+    if amount < 0:
+        raise ValueError("Bid amount must not be negative.")
+    bids[name] = amount
+
+
+def find_winner(bids: dict[str, float]) -> tuple[str, float]:
+    """! @brief Find the highest bidder.
+    @param bids Dictionary mapping bidder name to bid amount.
+    @return Tuple of (winner name, winning amount). The first bidder wins ties.
+    @throws ValueError If there are no bids.
+    """
+    if not bids:
+        raise ValueError("No bids have been placed.")
+    winner = max(bids, key=bids.__getitem__)
+    return winner, bids[winner]