let-fate-decide: replace os.urandom with secrets.randbelow (#125)

* galvanize(iter1): replace os.urandom with secrets.randbelow, add tests

Switch card selection from hand-rolled secure_randbelow(os.urandom)
to stdlib secrets.randbelow(). Update all docstrings, SKILL.md, and
README.md references. Add 25-test suite covering deck construction,
shuffle invariants, CLI validation, and migration regression checks.

* Bump version to 1.1.0 and fix stale rejection sampling claim

- Bump version in plugin.json and marketplace.json (1.0.0 → 1.1.0)
- Update SKILL.md to say "via secrets.randbelow()" instead of claiming
  the script itself implements rejection sampling

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Fix ruff format: collapse line continuation in test assertion

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Merge Scott's PR #128 improvements + vivisect fixes

Incorporates unique changes from Scott's closed PR #128:
- Broadened trigger patterns (casual delegation, YOLO, shrug-like
  brevity, expanded Yu-Gi-Oh references) in README.md and SKILL.md
- Improved SKILL.md frontmatter description with casual/playful
  tone guidance and prefer-over-ask-questions-if-underspecified note
- is_reversed() uses secrets.randbits(1) (more idiomatic coin flip)

Additional fixes from vivisect analysis:
- Converted MAJOR_ARCANA, RANKS, SUITS from lists to tuples
  (prevents silent deck corruption if imported as library)
- Added type guard in draw() rejecting non-int/bool inputs
- Added test_constants_are_immutable and test_draw_rejects_non_int

Co-Authored-By: Scott Arciszewski <scott.arciszewski@trailofbits.com>

* let-fate-decide: improve performance by avoiding text-only turns

---------

Co-authored-by: Dan Guido <dan@trailofbits.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Scott Arciszewski <scott.arciszewski@trailofbits.com>

Author: 4 people

plugins/let-fate-decide/README.md

@@ -1,6 +1,6 @@
 # let-fate-decide
 
-A Claude Code skill that draws Tarot cards using `os.urandom()` to inject
+A Claude Code skill that draws Tarot cards using `secrets` to inject
 entropy into vague or underspecified planning decisions.
 
 ## What It Does
@@ -12,16 +12,17 @@ spread and uses the reading to inform its approach.
 
 ## Triggers
 
-- Vague or underspecified prompts where multiple approaches are equally valid
-- "I'm feeling lucky"
-- "Let fate decide"
-- Nonchalant delegation ("whatever you think", "surprise me", "dealer's choice")
-- Yu-Gi-Oh references ("heart of the cards", "I believe in the heart of the cards")
+- Vague or ambiguous prompts where multiple reasonable approaches exist
+- "I'm feeling lucky", "let fate decide", "dealer's choice", "surprise me", "whatever you think", "YOLO"
+- Casual delegation ("whatever", "up to you", "your call", "idk", "just do something", "wing it", "I trust you", "doesn't matter", "do what you want", "I don't care", "any approach works", "you pick")
+- Yu-Gi-Oh references ("heart of the cards", "I believe in the heart of the cards", "you've activated my trap card", "it's time to duel")
+- Shrug-like brevity -- very short prompts that fully delegate the decision
+- About to arbitrarily pick between 2+ valid approaches (draw cards instead)
 - "Try again" on a system with no actual changes (redraw)
 
 ## How It Works
 
-1. A Python script uses `os.urandom()` to perform a Fisher-Yates shuffle
+1. A Python script uses `secrets` to perform a Fisher-Yates shuffle
 2. 4 cards are drawn from the top of the shuffled deck
 3. Each card has an independent 50% chance of being reversed
 4. Claude reads the drawn cards' meaning files and interprets the spread

plugins/let-fate-decide/skills/let-fate-decide/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: let-fate-decide
-description: "Draws 4 Tarot cards using os.urandom() to inject entropy into planning when prompts are vague or underspecified. Interprets the spread to guide next steps. Use when the user is nonchalant, feeling lucky, says 'let fate decide', makes Yu-Gi-Oh references ('heart of the cards'), demonstrates indifference about approach, or says 'try again' on a system with no changes. Also triggers on sufficiently ambiguous prompts where multiple approaches are equally valid."
+description: "Draws 4 Tarot cards to inject entropy into planning when prompts are vague, ambiguous, or casually delegated. Interprets the spread to guide next steps. Use when the user says 'let fate decide', 'YOLO', 'whatever', 'idk', or other nonchalant phrases, makes Yu-Gi-Oh references, or when you are about to arbitrarily pick between multiple reasonable approaches. Prefer over ask-questions-if-underspecified when the user's tone is casual or playful rather than precision-seeking."
 allowed-tools:
   - Bash
   - Read
@@ -29,29 +29,30 @@ When the path forward is unclear, let the cards speak.
 
 ## When to Use
 
-- **Vague prompts**: The user's request is ambiguous and multiple valid approaches exist
-- **Explicit invocations**: "I'm feeling lucky", "let fate decide", "dealer's choice", "surprise me", "whatever you think"
+- **Vague prompts**: The user's request is ambiguous and multiple reasonable approaches exist
+- **Explicit invocations**: "I'm feeling lucky", "let fate decide", "dealer's choice", "surprise me", "whatever you think", "YOLO"
+- **Casual delegation**: "whatever", "up to you", "your call", "idk", "just do something", "wing it", "I trust you", "doesn't matter", "do what you want", "I don't care", "any approach works", "you pick"
 - **Yu-Gi-Oh energy**: "Heart of the cards", "I believe in the heart of the cards", "you've activated my trap card", "it's time to duel"
-- **Nonchalant delegation**: The user expresses indifference about the approach
+- **Shrug-like brevity**: Very short prompts that fully delegate the decision without expressing a preference
 - **Redraw requests**: "Try again" or "draw again" when no actual system changes occurred (this means draw new cards, not re-run the same approach)
-- **Tie-breaking**: When you genuinely cannot decide between equally valid approaches
+- **Tie-breaking**: When you are about to arbitrarily pick between 2+ valid approaches, draw cards instead of silently choosing one
 
 ## When NOT to Use
 
 - The user has given clear, specific instructions
 - The task has a single obvious correct approach
 - Safety-critical decisions (security, data integrity, production deployments)
 - The user explicitly asks you NOT to use Tarot
-- A more specific skill (like `ask-questions-if-underspecified`) would better serve the user by gathering actual requirements
+- The user's tone is precision-seeking rather than casual -- use `ask-questions-if-underspecified` instead to gather actual requirements
 
 ## How It Works
 
 ### The Draw
 
-The script uses `os.urandom()` for cryptographic randomness:
+The script uses `secrets` for cryptographic randomness:
 
 1. Builds a standard 78-card Tarot deck (22 Major Arcana + 56 Minor Arcana)
-2. Performs a Fisher-Yates shuffle using rejection sampling (no modulo bias)
+2. Performs a Fisher-Yates shuffle via `secrets.randbelow()` (no modulo bias)
 3. Draws 4 cards from the top
 4. Each card independently has a 50% chance of being reversed
 
@@ -85,6 +86,10 @@ Key rules:
 - Major Arcana cards carry more weight than Minor Arcana
 - The spread tells a story across all 4 positions; don't interpret cards in isolation
 - Map abstract meanings to concrete technical decisions
+- **Never output interpretation as a text-only turn.** Include the
+  interpretation alongside your next tool call (the action that
+  implements the chosen option). Read all 4 cards in parallel if
+  possible.
 
 ## Example Session
 

plugins/let-fate-decide/skills/let-fate-decide/scripts/draw_cards.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Draw Tarot cards using os.urandom() for cryptographic randomness.
+"""Draw Tarot cards using the secrets module for cryptographic randomness.
 
 Shuffles a full 78-card deck via Fisher-Yates and draws 4 from the top.
 Each card has an independent 50/50 chance of being reversed.
@@ -10,10 +10,10 @@
 # ///
 
 import json
-import os
+import secrets
 import sys
 
-MAJOR_ARCANA = [
+MAJOR_ARCANA = (
     ("major", "00-the-fool"),
     ("major", "01-the-magician"),
     ("major", "02-the-high-priestess"),
@@ -36,9 +36,9 @@
     ("major", "19-the-sun"),
     ("major", "20-judgement"),
     ("major", "21-the-world"),
-]
+)
 
-RANKS = [
+RANKS = (
     "ace",
     "two",
     "three",
@@ -53,9 +53,9 @@
     "knight",
     "queen",
     "king",
-]
+)
 
-SUITS = ["wands", "cups", "swords", "pentacles"]
+SUITS = ("wands", "cups", "swords", "pentacles")
 
 
 def build_deck():
@@ -67,42 +67,23 @@ def build_deck():
     return deck
 
 
-def secure_randbelow(n):
-    """Return a cryptographically random integer in [0, n).
-
-    Uses os.urandom() with rejection sampling to avoid modulo bias.
-    """
-    if n <= 0:
-        raise ValueError("n must be positive")
-    if n == 1:
-        return 0
-    # Number of bytes needed to cover range
-    k = (n - 1).bit_length()
-    num_bytes = (k + 7) // 8
-    # Rejection sampling: discard values >= n to avoid bias
-    while True:
-        raw = int.from_bytes(os.urandom(num_bytes), "big")
-        # Mask to k bits to reduce rejection rate
-        raw = raw & ((1 << k) - 1)
-        if raw < n:
-            return raw
-
-
 def fisher_yates_shuffle(deck):
-    """Shuffle deck in-place using Fisher-Yates with os.urandom()."""
+    """Shuffle deck in-place using Fisher-Yates with secrets.randbelow()."""
     for i in range(len(deck) - 1, 0, -1):
-        j = secure_randbelow(i + 1)
+        j = secrets.randbelow(i + 1)
         deck[i], deck[j] = deck[j], deck[i]
     return deck
 
 
 def is_reversed():
-    """Return True with 50% probability using os.urandom()."""
-    return os.urandom(1)[0] & 1 == 1
+    """Return True with 50% probability using secrets.randbits()."""
+    return secrets.randbits(1) == 1
 
 
 def draw(n=4, include_content=False):
     """Shuffle deck and draw n cards, each possibly reversed."""
+    if not isinstance(n, int) or isinstance(n, bool):
+        raise TypeError(f"n must be int, got {type(n).__name__}")
     deck = build_deck()
     fisher_yates_shuffle(deck)
     # Resolve cards directory relative to this script