interface:
  display_name: "Let Fate Decide"
  short_description: "Use a random Tarot spread to guide ambiguous plans"
  icon_small: "assets/trail-of-bits-mark.svg"
  icon_large: "assets/trail-of-bits-mark.svg"
  brand_color: "#D83A34"

# First House

**Domain**: Self, identity, agency, and first motion

## Core Meaning
The First House describes how the work presents itself and how to begin. It
sets the operating stance: decisive or exploratory, cautious or bold, solo or
collaborative.

## Building New Projects
Use this house to choose the initial shape of the project. It points to the
first interface, the first workflow, and the identity the system should have
before supporting details accumulate.

## Vulnerability Discovery
Use this house to identify the attacker's first foothold. It maps to entry
points, externally reachable behavior, trust boundaries, and the first action
that turns a codebase into an attack surface.

## Correctness Verification
Use this house to define what "correct" means at the boundary. It maps to
preconditions, initial states, public APIs, input domains, and the first
invariant that must hold before deeper reasoning is useful.

## Technical Workflow Lenses
- Audit pipeline: scope the first entry points, trust boundaries, and initial
  assumptions before deeper discovery.
- Evidence mode: produce a minimal source trace, call graph, reproduction, or
  boundary test that proves where the work begins.
- Human context: name the decision owner and the first handoff needed to keep
  the effort from drifting.

## Technical Prompt
What is the right stance for beginning, and what first move makes the rest of
the work easier to reason about?

# Second House

**Domain**: Resources, values, constraints, and preservation

## Core Meaning
The Second House describes what is available, what is scarce, and what must not
be wasted. It asks which resources, values, or invariants should constrain the
plan.

## Building New Projects
Use this house to reason about budgets: time, complexity, dependencies,
platform limits, team expertise, and which pieces deserve durable foundations.

## Vulnerability Discovery
Use this house to examine assets and incentives. It maps to funds, secrets,
privileges, quotas, availability, and anything an attacker could steal,
degrade, lock, or manipulate.

Contrast with the Eighth House: the Second House treats secrets and privileges
as assets to protect; the Eighth House focuses on how they change hands,
escalate, or become exposed during transitions.

## Correctness Verification
Use this house to protect invariants. It maps to conservation properties,
resource accounting, bounds, ownership, permissions, and state that must remain
consistent across transitions.

## Technical Workflow Lenses
- Audit pipeline: enumerate assets, privileges, quotas, budgets, and incentives
  before ranking risk.
- Evidence mode: prefer accounting tests, invariant checks, permission traces,
  dimensional analysis, or scarcity proofs.
- Domain lens: in DeFi and crypto, treat units, balances, keys, randomness, and
  token behavior as first-class resources.

## Technical Prompt
What resource or invariant gives this task its real value, and what would be
costly to lose?

# Third House

**Domain**: Communication, learning, interfaces, and local connections

## Core Meaning
The Third House describes exchange: names, messages, protocols, documentation,
small decisions, and the local links between parts of a system.

## Building New Projects
Use this house to shape APIs, component boundaries, naming, docs, schemas, and
the early developer experience. It favors clarity over cleverness.

## Vulnerability Discovery
Use this house to inspect parsers, protocol handling, serialization,
deserialization, request routing, logs, CLI arguments, and any place where
meaning crosses a boundary.

## Correctness Verification
Use this house to verify contracts between components. It maps to type
boundaries, message formats, state synchronization, error propagation, and
whether two parts of the system agree on the same facts.

## Technical Workflow Lenses
- Audit pipeline: inspect parsers, schemas, protocol messages, logs, CLI
  arguments, and API contracts where meaning crosses a boundary.
- Evidence mode: use parser fuzzing, schema tests, protocol diagrams, static
  rules, or spec-to-code comparisons.
- Human context: improve names, docs, and report language when ambiguity is the
  thing creating risk.

## Technical Prompt
Where is meaning being translated, and what misunderstanding would cause the
system to fail?

# Fourth House

**Domain**: Foundations, history, context, and hidden dependencies

## Core Meaning
The Fourth House describes what the work rests on. It points to inherited
architecture, assumptions, persistence layers, deployment context, and the
history that shaped the current state.

## Building New Projects
Use this house to decide the base architecture, storage model, configuration
strategy, and migration path. It warns against building attractive surfaces on
unstable ground.

## Vulnerability Discovery
Use this house to inspect implicit trust, legacy behavior, configuration
defaults, environment assumptions, deployment topology, and persistent state
that outlives a single request.

Contrast with the Twelfth House: the Fourth House covers foundations that still
shape the system; the Twelfth House covers forgotten paths and assumptions that
should be retired or revalidated.

## Correctness Verification
Use this house to verify initialization, recovery, migrations, persistence,
default values, and assumptions inherited from previous states.

## Technical Workflow Lenses
- Audit pipeline: build architectural context before hunting; map persistence,
  deployment topology, privileged foundations, and legacy behavior.
- Evidence mode: use initialization tests, migration checks, config review,
  code graph summaries, or environment reproductions.
- Domain lens: for operations and supply chain work, include devcontainers,
  CI defaults, deployment paths, and dependency roots.

## Technical Prompt
What foundation is this work standing on, and what assumption has become
invisible because it has always been there?

# Fifth House

**Domain**: Creativity, experimentation, expressiveness, and delight

## Core Meaning
The Fifth House describes the creative opening. It points to prototypes, user
delight, sharp examples, playful exploration, and the part of the work that
benefits from imagination.

## Building New Projects
Use this house to identify the prototype, demo path, interactive loop, or
opinionated product choice that makes the project feel alive.

## Vulnerability Discovery
Use this house to try unusual inputs, creative abuse cases, unexpected feature
combinations, and behavior that appears harmless because it was built for
convenience or delight. It maps to debug or demo endpoints, feature flags that
skip validation, overly flexible APIs, upload or template features, and
convenience modes that quietly bypass normal controls.

## Correctness Verification
Use this house to generate examples, edge cases, model-based scenarios,
property tests, and small experiments that reveal whether the abstraction
behaves as intended.

## Technical Workflow Lenses
- Audit pipeline: turn intuition into concrete abuse cases, weird feature
  combinations, fuzz dictionaries, and exploratory probes.
- Evidence mode: prefer prototypes, fuzz harnesses, property tests, mutation
  survivors, screenshots, or small proof-of-concept experiments.
- Domain lens: in product and UX work, validate delight with real workflows
  rather than assuming novelty is useful.

## Technical Prompt
Where would a creative experiment teach more than another round of analysis?

# Sixth House

**Domain**: Practice, service, quality, routine, and maintenance

## Core Meaning
The Sixth House describes the work of making systems reliable. It points to
tests, cleanup, repeatable process, health checks, observability, and the small
habits that compound into quality.

## Building New Projects
Use this house to define the development loop: tests, linting, CI, local setup,
error handling, deploy hygiene, and the maintenance burden the team is willing
to carry.

## Vulnerability Discovery
Use this house to inspect routine paths: retries, cleanup, cron jobs, queues,
rate limits, background workers, monitoring gaps, and ordinary code that rarely
gets dramatic attention.

## Correctness Verification
Use this house to focus on regression tests, invariants in common workflows,
fuzz harness stability, determinism, resource cleanup, and operational
repeatability.

## Technical Workflow Lenses
- Audit pipeline: convert discoveries into repeatable checks, regression tests,
  coverage targets, and maintenance tasks.
- Evidence mode: use CI results, sanitizer output, fuzz coverage, mutation
  scores, invariants, logs, and observability data.
- Human context: reduce recurring toil with documented workflows, ownership,
  and boring automation.

## Technical Prompt
What ordinary practice would prevent this system from drifting into failure?

# Seventh House

**Domain**: Partnership, contracts, users, and external counterparts

## Core Meaning
The Seventh House describes the other side of the relationship. It points to
users, peers, APIs, vendors, collaborators, adversaries, and any contract that
requires two parties to agree.

## Building New Projects
Use this house to shape user workflows, integration contracts, partner APIs,
permissions, handoffs, and the obligations the system accepts on behalf of
others.

## Vulnerability Discovery
Use this house to examine trust between parties: authentication,
authorization, delegation, OAuth flows, webhooks, multi-tenant boundaries, and
third-party integrations.

## Correctness Verification
Use this house to verify contracts, compatibility, permissions, cross-service
state, idempotency, and behavior at integration boundaries.

## Technical Workflow Lenses
- Audit pipeline: inspect authentication, authorization, delegation, webhooks,
  OAuth flows, vendors, and multi-tenant boundaries.
- Evidence mode: use integration tests, contract tests, permission matrices,
  captured traffic, and cross-service traces.
- Human context: clarify obligations between teams, users, APIs, reviewers, and
  external counterparties.

## Technical Prompt
Who is on the other side of this interface, and what agreement could fail under
pressure?

# Eighth House

**Domain**: Transformation, risk, shared state, secrets, and deep change

## Core Meaning
The Eighth House describes what changes under pressure. It points to risk,
shared ownership, irreversible transitions, secrets, migrations, and places
where failure has second-order effects.

## Building New Projects
Use this house to reason about migrations, data ownership, auth, secret
handling, payment flows, destructive actions, and architectural choices that
will be expensive to reverse.

## Vulnerability Discovery
Use this house to inspect privilege escalation, confused deputy behavior,
secret exposure, shared mutable state, reentrancy, unsafe migrations, and
operations that transform authority or value.

Contrast with the Second House: the Second House asks what assets need
protection; the Eighth House asks what can go wrong when those assets,
permissions, or states are transferred, transformed, or partially updated.

## Correctness Verification
Use this house to verify state transitions, rollback behavior, atomicity,
authorization invariants, data lifecycle rules, and whether partial failure
leaves the system in a dangerous state.

## Technical Workflow Lenses
- Audit pipeline: hunt transition bugs: escalation, reentrancy, races, partial
  updates, migrations, secret movement, and shared authority.
- Evidence mode: use state-machine analysis, concurrency tests, exploit PoCs,
  rollback tests, invariant checks, or transaction traces.
- Domain lens: in smart contracts and protocols, focus on value movement,
  authority changes, replay, lifecycle transitions, and cross-component state.

## Technical Prompt
What changes irreversibly here, and what risk appears only when ownership or
state is shared?

# Ninth House

**Domain**: Exploration, principles, standards, and broader strategy

## Core Meaning
The Ninth House describes the larger frame. It points to research, standards,
philosophy, long-term bets, portability, and the principles that should guide
local decisions.

## Building New Projects
Use this house to choose frameworks, platform strategy, architectural
principles, documentation philosophy, and which constraints should be treated
as long-term design commitments.

## Vulnerability Discovery
Use this house to look beyond local code: specs, threat models, ecosystem
patterns, upstream assumptions, cross-runtime or cross-platform behavior, and
classes of bugs known in similar systems.

## Correctness Verification
Use this house to compare implementation against specifications, formalize
properties, check standards compliance, and identify whether the system's
model matches the domain's deeper rules.

## Technical Workflow Lenses
- Audit pipeline: bring in external standards, prior vulnerabilities, threat
  models, protocol specs, and ecosystem patterns.
- Evidence mode: use spec-to-code compliance, formal models, property suites,
  protocol diagrams, Wycheproof-style vectors, or standards checklists.
- Domain lens: for crypto and protocols, translate messages, keys, roles,
  secrecy, authentication, and replay assumptions into explicit properties.

## Technical Prompt
What larger principle or external standard should govern the local choice?

# Tenth House

**Domain**: Delivery, reputation, public outcome, and long-term direction

## Core Meaning
The Tenth House describes what the work becomes in public. It points to
shipping, reliability, responsibility, reputation, leadership, and the outcome
that will be judged by others.

## Building New Projects
Use this house to define the release target, production bar, operational
ownership, success metrics, and what must be true before the work is fit to
ship.

## Vulnerability Discovery
Use this house to prioritize exploitable, high-impact findings over merely
interesting behavior. It maps to production exposure, impact, likelihood,
blast radius, and reportability.

## Correctness Verification
Use this house to focus on user-visible guarantees, service-level behavior,
release blockers, acceptance criteria, and whether correctness holds in the
environment where the system will be judged.

## Technical Workflow Lenses
- Audit pipeline: prioritize reportable impact, exploitability, remediation
  clarity, release blockers, and regression coverage.
- Evidence mode: use production telemetry, acceptance tests, reproducible PoCs,
  severity scoring, report drafts, and stakeholder-ready summaries.
- Human context: make accountability explicit: who signs off, who communicates,
  and what must be true before shipping.

## Technical Prompt
What outcome will this work be accountable for once it leaves the workbench?

# Eleventh House

**Domain**: Community, networks, systems, and shared aspirations

## Core Meaning
The Eleventh House describes the broader system of people and tools around the
work. It points to teams, ecosystems, shared infrastructure, conventions, and
the future others are trying to build with you.

## Building New Projects
Use this house to reason about extensibility, plugin points, team workflows,
shared libraries, open-source fit, deployment ecosystems, and how the project
will participate in a larger technical community.

## Vulnerability Discovery
Use this house to inspect supply-chain risk, dependency trust, shared services,
multi-party workflows, governance, network effects, and vulnerabilities that
emerge only across a system of participants.

## Correctness Verification
Use this house to verify distributed assumptions, compatibility across
versions, shared schemas, ecosystem contracts, and behavior under many users or
many components.

## Technical Workflow Lenses
- Audit pipeline: inspect dependency trust, CI/CD workflows, agentic actions,
  shared infrastructure, open-source health, and governance.
- Evidence mode: use dependency analysis, ownership maps, workflow review,
  compatibility tests, ecosystem scans, and blast-radius analysis.
- Human context: account for communities, maintainers, reviewers, customers,
  and teams who inherit the decision.

## Technical Prompt
What network or community does this work depend on, and how could that shared
context change the right answer?

# Twelfth House

**Domain**: Blind spots, hidden costs, endings, and unconscious assumptions

## Core Meaning
The Twelfth House describes what is hard to see directly. It points to hidden
state, deferred cleanup, unresolved risk, unclear ownership, stale assumptions,
and endings that need to be handled deliberately.

## Building New Projects
Use this house to identify what should be left out, retired, documented as a
risk, or postponed consciously. It warns against invisible complexity and
features that quietly become obligations.

## Vulnerability Discovery
Use this house to inspect forgotten paths: debug modes, test fixtures,
backdoors, stale credentials, abandoned endpoints, implicit fallbacks, and
assumptions no one has revalidated.

Contrast with the Fourth House: the Fourth House asks what foundational context
must be understood; the Twelfth House asks what hidden or obsolete context is
quietly creating risk.

## Correctness Verification
Use this house to test teardown, cancellation, cleanup, error paths,
unreachable states, timeouts, and any case that is easy to exclude from the
happy-path model.

## Technical Workflow Lenses
- Audit pipeline: look for forgotten endpoints, debug paths, stale credentials,
  dead code, false assumptions, hidden scope, and discarded findings.
- Evidence mode: use negative tests, cleanup checks, unreachable-state review,
  log review, secret scans, and false-positive validation.
- Human context: document deferred risk, cleanup ownership, escalation needs,
  and what should intentionally end.

## Technical Prompt
What is hidden, unfinished, or quietly assumed, and what needs to end cleanly?

# Interpretation Guide

How to read the 12 Houses of the Zodiac Tarot spread and map it to technical
decisions.

## The Spread Positions

Each house contains 3 cards:

- The first card is always Major Arcana and sets the house's archetypal theme.
- The second and third cards are Minor Arcana and supply practical details.
- The house file under `houses/` explains how that house maps to technical
  contexts such as building, vulnerability discovery, and correctness work.
- `TECHNICAL_CONTEXT_LENSES.md` maps common technical workflows to reusable
  audit, evidence, domain, failure-class, and human/organizational lenses.

| House | Role | Maps To |
|-------|------|---------|
| 1 - Self | Identity, agency, first impulse | How to begin, the operating stance |
| 2 - Resources | Values, assets, limits | Constraints, dependencies, budget, invariants |
| 3 - Communication | Learning and exchange | Interfaces, naming, docs, coordination |
| 4 - Foundations | Roots and context | Existing architecture, history, hidden coupling |
| 5 - Creativity | Experimentation and play | Prototypes, UI choices, expressive design |
| 6 - Practice | Service and routine | Testing, quality, maintenance, workflow |
| 7 - Partnership | Others and contracts | Users, APIs, integrations, collaboration |
| 8 - Transformation | Risk and shared state | Migrations, secrets, permissions, deep refactors |
| 9 - Exploration | Principles and broad vision | Strategy, standards, research, long-term bets |
| 10 - Calling | Public outcome and reputation | Delivery, reliability, production readiness |
| 11 - Community | Groups and systems | Ecosystem fit, shared tooling, team impact |
| 12 - The Hidden | Blind spots and endings | Unknown risks, cleanup, deferred costs |

## Reading the Cards

### Step 1: Read Each House and Card File

For each house, read its house file. For each drawn card, read its meaning
file. Note both the upright and reversed meanings. Use whichever matches the
card's orientation in the draw.

The `In Technical Context` section in a card file is a starting translation,
not a replacement for the orientation. If that technical note sounds too
decisive for the card's reversed meaning, adapt it through the reversed text
instead of following the sentence literally.

### Step 2: Map to Context

Translate the card's archetypal meaning into the current technical situation:

**Major Arcana** represent big-picture forces:
- Architectural decisions, paradigm shifts, fundamental approaches
- These carry more interpretive weight

**Minor Arcana** represent practical details:
- **Wands** (fire): Action, initiative, creativity, velocity, building
- **Cups** (water): Collaboration, user experience, intuition, satisfaction
- **Swords** (air): Analysis, logic, debugging, cutting through complexity, hard truths
- **Pentacles** (earth): Quality, craft, reliability, testing, maintenance, tangible results

**Court Cards** can represent approaches or roles:
- **Page**: Learning, experimenting, prototyping, beginner's mind
- **Knight**: Focused pursuit, rapid movement, single-minded effort
- **Queen**: Mastery with empathy, nurturing growth, mature judgment
- **King**: Authority, established patterns, proven approaches

When the task resembles a specialized skill workflow, choose the relevant lens
from `TECHNICAL_CONTEXT_LENSES.md` before deciding what action the reading
supports. This keeps the reading grounded in the actual mode of work: audit
pipeline stage, evidence type, technical domain, failure class, or stakeholder
coordination.

### Step 3: Synthesize the Story

Read all 12 houses as a narrative:

1. "The beginning stance is [House 1]..."
2. "The available resources and constraints are [House 2]..."
3. "The communication or interface concern is [House 3]..."
4. "The foundation or hidden dependency is [House 4]..."
5. "The creative opening is [House 5]..."
6. "The quality and maintenance requirement is [House 6]..."
7. "The integration or collaboration point is [House 7]..."
8. "The transformation or risk is [House 8]..."
9. "The guiding principle is [House 9]..."
10. "The delivery target is [House 10]..."
11. "The ecosystem or team impact is [House 11]..."
12. "The blind spot or closure is [House 12]..."

When time is tight, prioritize House 1 for the initial stance, House 6 for
execution quality, House 8 for risk, House 10 for delivery, and House 12 for
blind spots.

### Step 4: Make a Decision

The reading should bias you toward one of the viable approaches. State:
- Which approach the reading supports
- How specific cards influenced the choice
- What the reading suggests you should watch out for

For vulnerability discovery and correctness verification, the decision should
be about where to investigate next or which hypothesis to test. The reading can
prioritize attention, but it cannot prove safety, dismiss a finding, or replace
reproduction, testing, formal reasoning, or source-level evidence.

## Reversed Cards

Reversed cards don't mean "bad." They indicate:
- The energy is internalized rather than expressed
- The quality is blocked, delayed, or needs extra attention
- An alternative or inverted interpretation applies
- Shadow aspects of the card's theme

## Special Patterns

The 12-house spread deals 12 Major Arcana, 24 Minor Arcana, and an
independent reversal flag per card. The patterns below are calibrated to those
baselines (one Major per house is guaranteed, so "multiple Majors" is not a
signal in this spread).

### Heavy Reversal Count
The spread averages 18 reversed cards out of 36. If 24 or more are reversed
(roughly the top 3% of draws), the reading is telling you that many
things are blocked, inverted, or shadowed. Step back and reconsider the
assumptions driving the work before proceeding.

### Heavy Minor Suit Concentration
Each Minor suit is expected to contribute about 6 of the 24 Minor draws. If
one suit contributes 10 or more, the reading carries that suit's thematic
emphasis across many houses:
- Heavy Wands: Focus on action, momentum, and creative drive
- Heavy Cups: Focus on user needs, team dynamics, and emotional state
- Heavy Swords: Focus on analysis, conflict, and clear thinking
- Heavy Pentacles: Focus on craft, resources, and practical quality

### Weighty Majors in Critical Houses
Death, The Tower, The Devil, Judgement, or The World landing in House 1
(Self), House 8 (Transformation), or House 12 (The Hidden) amplifies themes
of identity, deep change, or unseen factors. Treat these as cues to slow
down and investigate before committing.

### Court Cards Clustering in People Houses
Court cards (Page, Knight, Queen, King) appearing in Houses 3 (Communication),
7 (Partnership), or 11 (Community) reinforce a people-oriented reading: the
work hinges on collaboration, contracts, or social dynamics rather than purely
technical execution.

## What the Reading Is NOT

- Not a substitute for requirements gathering when requirements are gettable
- Not permission to ignore best practices
- Not evidence that a security or correctness concern is real or false
- Not a way to avoid thinking critically
- Not deterministic (it's entropy, that's the point)

The reading adds a creative nudge to break analysis paralysis. The cards don't make the decision; they give you a direction to explore when you otherwise have none.

# Technical Context Lenses

These lenses apply across a wide range of technical workflows, but they cluster
into a small set of recurring patterns. Use them to translate a house or card
into the kind of work currently being done.

## Audit Pipeline Stage

Use this lens when the task is part of a security review or codebase critique.
Map the spread to the current phase:

- Scoping and setup: what is in scope, what is excluded, and what must be
  understood first.
- Attack-surface mapping: entry points, trust boundaries, privileged paths,
  assets, state transitions, and external dependencies.
- Discovery: creative hypotheses, known bug classes, unusual inputs, and
  paths that ordinary review may miss.
- Validation: source traces, tests, fuzz cases, proofs, exploitability checks,
  and false-positive elimination.
- Reporting and regression: impact, reproduction, remediation, and tests that
  keep the issue from returning.

## Evidence Mode

Use this lens to decide what kind of evidence should follow the reading. A
Tarot spread can prioritize attention, but the next step should produce one of
these evidence types:

- Source-level trace or code graph path.
- Unit, integration, property, fuzz, mutation, or regression test.
- Static-analysis query, SARIF finding, or semgrep/codeql rule.
- Protocol diagram, formal model, invariant, or spec-to-code comparison.
- Exploit proof, crash reproducer, timing measurement, or production telemetry.
- Written rationale, report section, decision log, or stakeholder-ready summary.

## Domain Lens

Use this lens to adapt general language to the actual domain:

- Smart contracts and DeFi: assets, access control, arithmetic precision,
  state machines, hooks, bridges, governance, MEV, and token behavior.
- Crypto and protocols: transcripts, roles, keys, randomness, authentication,
  secrecy, replay, side channels, and formal security properties.
- Appsec, web, and mobile: endpoints, parsers, sessions, OAuth, uploads,
  webhooks, cloud backends, and captured traffic.
- Native, binary, and systems work: memory safety, integer behavior, races,
  debug data, reverse engineering, crashes, and sanitizer results.
- CI/CD, supply chain, and operations: dependencies, workflow permissions,
  agentic actions, deploy paths, production errors, and ownership.
- Product, docs, and stakeholder work: requirements, usability, report quality,
  positioning, scope, status, and handoff clarity.

## Failure Class Lens

Use this lens when the reading needs to become a concrete bug-hunting prompt:

- Access control, confused deputy behavior, authorization bypass, and privilege
  escalation.
- State-machine mistakes, broken lifecycle transitions, races, retries, and
  partial failure.
- Arithmetic, precision, unit, dimensional, bounds, overflow, and accounting
  errors.
- Parser, serialization, protocol, type-safety, and interface mismatches.
- Secrets, information leakage, side channels, logging exposure, and insecure
  defaults.
- Supply-chain compromise, dependency takeover, CI injection, sandbox escape,
  and unsafe automation.
- Missing tests, weak harnesses, unreachable coverage, survived mutants, and
  unverified invariants.

## Human and Organizational Lens

Use this lens when the work depends on people, teams, or decisions rather than
only code:

- Who owns the decision, risk, artifact, or follow-up?
- What needs to be escalated, documented, or turned into a report?
- What context is missing from stakeholders, users, maintainers, or reviewers?
- What would reduce ambiguity for the next person to touch the work?
- What is the team's capacity, confidence, and tolerance for change?

## House Affinity Map

| House | Strongest Corpus Lenses |
|-------|--------------------------|
| 1 - Self | Scoping, entry points, first assumptions, initial attack surface |
| 2 - Resources | Assets, invariants, budgets, ownership, scarcity |
| 3 - Communication | APIs, protocols, parsers, schemas, docs, logs |
| 4 - Foundations | Architecture, persistence, deployment context, legacy assumptions |
| 5 - Creativity | Fuzzing, abuse cases, prototypes, exploratory testing |
| 6 - Practice | CI, harnesses, regression tests, observability, maintenance |
| 7 - Partnership | Integrations, auth contracts, users, vendors, external APIs |
| 8 - Transformation | State transitions, migrations, secrets, escalation, shared authority |
| 9 - Exploration | Specs, standards, formal models, protocol reasoning, research |
| 10 - Calling | Release readiness, impact, reportability, production accountability |
| 11 - Community | Supply chain, ecosystem, shared infrastructure, governance |
| 12 - The Hidden | Forgotten paths, cleanup, stale assumptions, blind spots |

#!/usr/bin/env python3
"""Draw Tarot cards using the secrets module for cryptographic randomness.

The default draw is the 12 Houses of the Zodiac spread: each house gets one
Major Arcana card plus two Minor Arcana cards. Each card has an independent
50/50 chance of being reversed.
"""
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///

import json
import math
import os
import secrets
import sys

SPREAD_NAME = "12 Houses of the Zodiac"


def _entropy_bits():
    """Conservative unordered-card entropy budget for the default spread."""
    major = math.log2(math.comb(22, 12))
    minor = math.log2(math.comb(56, 24))
    reversals = 36.0
    return {
        "major_arcana": round(major, 2),
        "minor_arcana": round(minor, 2),
        "reversals": reversals,
        "total": round(major + minor + reversals, 2),
    }


ENTROPY_BITS = _entropy_bits()

MAJOR_ARCANA = (
    ("major", "00-the-fool"),
    ("major", "01-the-magician"),
    ("major", "02-the-high-priestess"),
    ("major", "03-the-empress"),
    ("major", "04-the-emperor"),
    ("major", "05-the-hierophant"),
    ("major", "06-the-lovers"),
    ("major", "07-the-chariot"),
    ("major", "08-strength"),
    ("major", "09-the-hermit"),
    ("major", "10-wheel-of-fortune"),
    ("major", "11-justice"),
    ("major", "12-the-hanged-man"),
    ("major", "13-death"),
    ("major", "14-temperance"),
    ("major", "15-the-devil"),
    ("major", "16-the-tower"),
    ("major", "17-the-star"),
    ("major", "18-the-moon"),
    ("major", "19-the-sun"),
    ("major", "20-judgement"),
    ("major", "21-the-world"),
)

RANKS = (
    "ace",
    "two",
    "three",
    "four",
    "five",
    "six",
    "seven",
    "eight",
    "nine",
    "ten",
    "page",
    "knight",
    "queen",
    "king",
)

SUITS = ("wands", "cups", "swords", "pentacles")

ZODIAC_HOUSES = (
    (
        "First House",
        "Self, identity, agency, and first motion",
        "01-first-house",
    ),
    (
        "Second House",
        "Resources, values, constraints, and preservation",
        "02-second-house",
    ),
    (
        "Third House",
        "Communication, learning, interfaces, and local connections",
        "03-third-house",
    ),
    (
        "Fourth House",
        "Foundations, history, context, and hidden dependencies",
        "04-fourth-house",
    ),
    (
        "Fifth House",
        "Creativity, experimentation, expressiveness, and delight",
        "05-fifth-house",
    ),
    (
        "Sixth House",
        "Practice, service, quality, routine, and maintenance",
        "06-sixth-house",
    ),
    (
        "Seventh House",
        "Partnership, contracts, users, and external counterparts",
        "07-seventh-house",
    ),
    (
        "Eighth House",
        "Transformation, risk, shared state, secrets, and deep change",
        "08-eighth-house",
    ),
    (
        "Ninth House",
        "Exploration, principles, standards, and broader strategy",
        "09-ninth-house",
    ),
    (
        "Tenth House",
        "Delivery, reputation, public outcome, and long-term direction",
        "10-tenth-house",
    ),
    (
        "Eleventh House",
        "Community, networks, systems, and shared aspirations",
        "11-eleventh-house",
    ),
    (
        "Twelfth House",
        "Blind spots, hidden costs, endings, and unconscious assumptions",
        "12-twelfth-house",
    ),
)


def build_deck():
    """Build the full 78-card Tarot deck."""
    return list(MAJOR_ARCANA) + build_minor_deck()


def build_minor_deck():
    """Build the 56-card Minor Arcana deck."""
    return [(suit, f"{rank}-of-{suit}") for suit in SUITS for rank in RANKS]


def fisher_yates_shuffle(deck):
    """Shuffle deck in-place using Fisher-Yates with secrets.randbelow()."""
    for i in range(len(deck) - 1, 0, -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 secrets.randbits()."""
    return secrets.randbits(1) == 1


def card_record(suit, card_id, position, role, include_content=False):
    """Return the JSON-serializable record for a drawn card."""
    card = {
        "suit": suit,
        "card_id": card_id,
        "reversed": is_reversed(),
        "position": position,
        "role": role,
        "file": f"cards/{suit}/{card_id}.md",
    }
    if include_content:
        script_dir = os.path.dirname(os.path.abspath(__file__))
        cards_dir = os.path.join(os.path.dirname(script_dir), "cards")
        path = os.path.join(cards_dir, suit, f"{card_id}.md")
        try:
            with open(path) as f:
                card["content"] = f.read()
        except OSError as e:
            card["content"] = f"(error reading card file {path}: {e})"
    return card


def read_reference_file(relative_file):
    """Read a skill-local reference file for --content output."""
    script_dir = os.path.dirname(os.path.abspath(__file__))
    skill_dir = os.path.dirname(script_dir)
    path = os.path.join(skill_dir, relative_file)
    try:
        with open(path) as f:
            return f.read()
    except OSError as e:
        return f"(error reading reference file {path}: {e})"


def draw_cards(n=4, include_content=False):
    """Shuffle the full 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)
    hand = []
    for i in range(min(n, len(deck))):
        suit, card_id = deck[i]
        hand.append(card_record(suit, card_id, i + 1, "card", include_content))
    return hand


def _build_house_record(
    *,
    house_number,
    house_meta,
    major_card,
    minor_pair,
    position,
    include_content,
):
    """Build the JSON record for one zodiac house."""
    house_name, focus, house_id = house_meta
    major_suit, major_id = major_card
    (m1_suit, m1_id), (m2_suit, m2_id) = minor_pair
    house_file = f"houses/{house_id}.md"
    record = {
        "house": house_number,
        "name": house_name,
        "focus": focus,
        "file": house_file,
        "cards": [
            card_record(major_suit, major_id, position, "major_arcana", include_content),
            card_record(m1_suit, m1_id, position + 1, "minor_arcana_1", include_content),
            card_record(m2_suit, m2_id, position + 2, "minor_arcana_2", include_content),
        ],
    }
    if include_content:
        record["content"] = read_reference_file(house_file)
    return record


def draw_zodiac_spread(include_content=False):
    """Draw the default 12 Houses of the Zodiac spread."""
    major_deck = list(MAJOR_ARCANA)
    minor_deck = build_minor_deck()
    fisher_yates_shuffle(major_deck)
    fisher_yates_shuffle(minor_deck)

    houses = []
    for i, house_meta in enumerate(ZODIAC_HOUSES):
        houses.append(
            _build_house_record(
                house_number=i + 1,
                house_meta=house_meta,
                major_card=major_deck[i],
                minor_pair=(minor_deck[2 * i], minor_deck[2 * i + 1]),
                position=1 + 3 * i,
                include_content=include_content,
            )
        )

    bits = ENTROPY_BITS
    return {
        "spread": SPREAD_NAME,
        "houses": houses,
        "entropy_bits": bits,
        "entropy_note": (
            "Assumes secrets.randbelow() provides cryptographically secure "
            "bounded draws. This is a conservative unordered-card budget: "
            f"{bits['major_arcana']} bits from Major Arcana selection, "
            f"{bits['minor_arcana']} bits from Minor Arcana selection, and "
            f"{bits['reversals']} reversal bits. Ordered house assignment "
            "contains more entropy."
        ),
    }


USAGE = "Usage: draw_cards.py [--content] [--legacy [count]]"


def _parse_args(argv):
    """Parse CLI argv into (include_content, legacy, count). Exits on error."""
    args = list(argv)
    include_content = "--content" in args
    if include_content:
        args.remove("--content")
    legacy = "--legacy" in args
    if legacy:
        args.remove("--legacy")
    count = None
    if args:
        if not legacy:
            print(
                f"Error: positional count requires --legacy. {USAGE}",
                file=sys.stderr,
            )
            sys.exit(1)
        try:
            count = int(args[0])
        except ValueError:
            print(
                f"Error: '{args[0]}' is not a valid integer. {USAGE}",
                file=sys.stderr,
            )
            sys.exit(1)
        if count < 1 or count > 78:
            print(f"Error: card count must be 1-78, got {count}", file=sys.stderr)
            sys.exit(1)
    return include_content, legacy, count


def main():
    include_content, legacy, count = _parse_args(sys.argv[1:])
    try:
        if legacy:
            hand = draw_cards(count if count is not None else 4, include_content=include_content)
        else:
            hand = draw_zodiac_spread(include_content=include_content)
    except OSError as e:
        print(f"Error: failed to read system entropy source: {e}", file=sys.stderr)
        sys.exit(1)
    print(json.dumps(hand, indent=2))


if __name__ == "__main__":
    try:
        main()
    except Exception as e:
        print(f"Error: draw_cards.py failed: {e}", file=sys.stderr)
        sys.exit(1)

[project]
name = "let-fate-decide-scripts"
version = "0.0.0"
requires-python = ">=3.11"

[tool.ruff]
line-length = 100
target-version = "py311"

#!/usr/bin/env python3
"""Tests for draw_cards.py."""
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///

import json
import math
import subprocess
import sys
from collections import Counter
from pathlib import Path

# Import the module under test
sys.path.insert(0, str(Path(__file__).parent))
import draw_cards

SKILL_DIR = Path(__file__).parent.parent


def test_build_deck_has_78_cards():
    deck = draw_cards.build_deck()
    assert len(deck) == 78, f"Expected 78 cards, got {len(deck)}"


def test_build_deck_has_22_major_arcana():
    deck = draw_cards.build_deck()
    majors = [c for c in deck if c[0] == "major"]
    assert len(majors) == 22, f"Expected 22 major arcana, got {len(majors)}"


def test_build_deck_has_56_minor_arcana():
    deck = draw_cards.build_deck()
    minors = [c for c in deck if c[0] != "major"]
    assert len(minors) == 56, f"Expected 56 minor arcana, got {len(minors)}"


def test_build_minor_deck_has_56_cards():
    deck = draw_cards.build_minor_deck()
    assert len(deck) == 56, f"Expected 56 minor cards, got {len(deck)}"


def test_build_minor_deck_excludes_major_arcana():
    deck = draw_cards.build_minor_deck()
    assert all(suit != "major" for suit, _ in deck)


def test_build_deck_all_unique():
    deck = draw_cards.build_deck()
    card_ids = [c[1] for c in deck]
    assert len(card_ids) == len(set(card_ids)), "Duplicate card IDs found"


def test_build_deck_four_suits_14_each():
    deck = draw_cards.build_deck()
    suits = Counter(c[0] for c in deck if c[0] != "major")
    for suit in ["wands", "cups", "swords", "pentacles"]:
        assert suits[suit] == 14, f"Expected 14 {suit}, got {suits[suit]}"


def test_draw_cards_returns_requested_count():
    for n in [1, 2, 4, 10]:
        hand = draw_cards.draw_cards(n)
        assert len(hand) == n, f"draw({n}) returned {len(hand)} cards"


def test_draw_cards_default_is_4():
    hand = draw_cards.draw_cards()
    assert len(hand) == 4


def test_draw_zodiac_spread_default_shape():
    hand = draw_cards.draw_zodiac_spread()
    assert hand["spread"] == draw_cards.SPREAD_NAME
    assert len(hand["houses"]) == 12


def test_draw_cards_clamps_to_78():
    hand = draw_cards.draw_cards(100)
    assert len(hand) == 78


def test_draw_cards_zero_returns_empty():
    hand = draw_cards.draw_cards(0)
    assert len(hand) == 0


def test_draw_cards_card_structure():
    hand = draw_cards.draw_cards(1)
    card = hand[0]
    assert "suit" in card
    assert "card_id" in card
    assert "reversed" in card
    assert "position" in card
    assert "file" in card
    assert isinstance(card["reversed"], bool)
    assert card["position"] == 1
    assert card["file"].startswith("cards/")
    assert card["file"].endswith(".md")


def test_draw_cards_positions_are_sequential():
    hand = draw_cards.draw_cards(4)
    positions = [c["position"] for c in hand]
    assert positions == [1, 2, 3, 4]


def test_draw_cards_no_duplicate_cards():
    hand = draw_cards.draw_cards(78)
    card_ids = [c["card_id"] for c in hand]
    assert len(card_ids) == len(set(card_ids)), "Duplicate cards drawn"


def test_zodiac_spread_shape():
    spread = draw_cards.draw_zodiac_spread()
    assert spread["spread"] == "12 Houses of the Zodiac"
    bits = spread["entropy_bits"]
    expected_major = round(math.log2(math.comb(22, 12)), 2)
    expected_minor = round(math.log2(math.comb(56, 24)), 2)
    assert bits["major_arcana"] == expected_major
    assert bits["minor_arcana"] == expected_minor
    assert bits["reversals"] == 36.0
    assert bits["total"] == round(expected_major + expected_minor + 36.0, 2)
    assert bits["total"] >= 100, "Entropy budget must clear the 100-bit floor"
    assert len(spread["houses"]) == 12
    for house in spread["houses"]:
        assert set(house) == {"house", "name", "focus", "file", "cards"}
        assert house["file"].startswith("houses/")
        assert house["file"].endswith(".md")
        assert len(house["cards"]) == 3


def test_zodiac_house_files_exist():
    spread = draw_cards.draw_zodiac_spread()
    for house in spread["houses"]:
        path = SKILL_DIR / house["file"]
        assert path.exists(), f"Missing house file: {path}"


def test_zodiac_focus_matches_house_domain():
    spread = draw_cards.draw_zodiac_spread()
    for house in spread["houses"]:
        text = (SKILL_DIR / house["file"]).read_text()
        domain = next(
            line[len("**Domain**: ") :].strip()
            for line in text.splitlines()
            if line.startswith("**Domain**: ")
        )
        assert house["focus"] == domain, (
            f"focus/Domain drift in {house['file']}: {house['focus']!r} != {domain!r}"
        )


def test_zodiac_house_files_cover_technical_contexts():
    spread = draw_cards.draw_zodiac_spread()
    for house in spread["houses"]:
        text = (SKILL_DIR / house["file"]).read_text()
        assert "## Building New Projects" in text
        assert "## Vulnerability Discovery" in text
        assert "## Correctness Verification" in text
        assert "## Technical Workflow Lenses" in text


def test_technical_context_lenses_reference_exists():
    reference = SKILL_DIR / "references" / "TECHNICAL_CONTEXT_LENSES.md"
    text = reference.read_text()
    assert "## Audit Pipeline Stage" in text
    assert "## Evidence Mode" in text
    assert "## Domain Lens" in text
    assert "## Failure Class Lens" in text
    assert "## Human and Organizational Lens" in text
    assert "## House Affinity Map" in text


def test_security_framing_requires_evidence():
    skill_text = (SKILL_DIR / "SKILL.md").read_text()
    guide_text = (SKILL_DIR / "references" / "INTERPRETATION_GUIDE.md").read_text()
    assert "Security and Correctness Use" in skill_text
    assert "never sufficient by itself" in skill_text
    assert "only evidence can dismiss a security or correctness concern" in skill_text
    assert "cannot prove safety, dismiss a finding, or replace" in guide_text


def test_numbered_ranks_are_numeric_across_all_suits():
    word_ranks = ("Two", "Three", "Four", "Five", "Six", "Seven", "Eight", "Nine", "Ten")
    for card_file in (SKILL_DIR / "cards").glob("*/*.md"):
        if card_file.parent.name == "major":
            continue
        text = card_file.read_text()
        for word in word_ranks:
            assert f"**Rank**: {word}" not in text, (
                f"{card_file} still uses word-form rank '{word}'; use the digit form"
            )


def test_reviewed_cards_avoid_unsafe_shortcuts():
    """Regression guard: these exact phrases were removed in 1.2.0; do not reintroduce.

    This is an exact-string blacklist, not a semantic check. Add new bad phrases
    here as they are identified during review; rewordings of existing phrases
    will not trip this test and must be caught manually.
    """
    risky_phrases = (
        "Follow your intuition on this one",
        "The solution that feels right probably is",
        "Ship it.",
        "The approach is sound.",
        "The approach will succeed.",
        "Speed matters here—refine later.",
    )
    for card_file in (SKILL_DIR / "cards").glob("*/*.md"):
        text = card_file.read_text()
        for phrase in risky_phrases:
            assert phrase not in text, f"{phrase!r} still appears in {card_file}"


def test_zodiac_spread_content_includes_house_content():
    spread = draw_cards.draw_zodiac_spread(include_content=True)
    for house in spread["houses"]:
        assert "content" in house
        assert house["content"].startswith("# ")


def test_zodiac_spread_uses_one_major_per_house():
    spread = draw_cards.draw_zodiac_spread()
    major_cards = []
    for house in spread["houses"]:
        card = house["cards"][0]
        assert card["role"] == "major_arcana"
        assert card["suit"] == "major"
        major_cards.append(card["card_id"])
    assert len(major_cards) == 12
    assert len(set(major_cards)) == 12


def test_zodiac_spread_uses_two_minors_per_house():
    spread = draw_cards.draw_zodiac_spread()
    minor_cards = []
    for house in spread["houses"]:
        for card in house["cards"][1:]:
            assert card["role"] in {"minor_arcana_1", "minor_arcana_2"}
            assert card["suit"] != "major"
            minor_cards.append(card["card_id"])
    assert len(minor_cards) == 24
    assert len(set(minor_cards)) == 24


def test_zodiac_spread_all_cards_can_be_reversed():
    spread = draw_cards.draw_zodiac_spread()
    cards = [card for house in spread["houses"] for card in house["cards"]]
    assert len(cards) == 36
    assert all(isinstance(card["reversed"], bool) for card in cards)


def test_zodiac_spread_positions_are_sequential():
    spread = draw_cards.draw_zodiac_spread()
    positions = [card["position"] for house in spread["houses"] for card in house["cards"]]
    assert positions == list(range(1, 37))


def test_fisher_yates_preserves_elements():
    deck = draw_cards.build_deck()
    original = sorted(deck)
    draw_cards.fisher_yates_shuffle(deck)
    assert sorted(deck) == original, "Shuffle changed deck elements"


def test_fisher_yates_single_element():
    deck = [("major", "00-the-fool")]
    draw_cards.fisher_yates_shuffle(deck)
    assert deck == [("major", "00-the-fool")]


def test_fisher_yates_empty():
    deck = []
    draw_cards.fisher_yates_shuffle(deck)
    assert deck == []


def test_is_reversed_returns_bool():
    for _ in range(20):
        assert isinstance(draw_cards.is_reversed(), bool)


def test_shuffle_produces_varying_orders():
    """Run 5 shuffles; at least 2 should differ (p(all same) ~ 0)."""
    orders = []
    for _ in range(5):
        deck = draw_cards.build_deck()
        draw_cards.fisher_yates_shuffle(deck)
        orders.append(tuple(c[1] for c in deck))
    assert len(set(orders)) >= 2, "All 5 shuffles identical"


def test_reversal_produces_both_values():
    """Over 100 flips, both True and False should appear."""
    results = {draw_cards.is_reversed() for _ in range(100)}
    assert True in results, "Never got reversed=True in 100 flips"
    assert False in results, "Never got reversed=False in 100 flips"


def test_no_os_urandom_import():
    """Verify os.urandom is not used; os may be imported for path operations."""
    source = Path(__file__).parent / "draw_cards.py"
    text = source.read_text()
    assert "os.urandom" not in text, "os.urandom still referenced"


def test_uses_secrets_module():
    """Verify secrets module is used."""
    source = Path(__file__).parent / "draw_cards.py"
    text = source.read_text()
    assert "import secrets" in text
    assert "secrets.randbelow" in text
    assert "secrets.randbits" in text


def test_cli_default_output():
    """Run the script and verify JSON output with the default spread."""
    result = subprocess.run(
        [sys.executable, str(Path(__file__).parent / "draw_cards.py")],
        capture_output=True,
        text=True,
    )
    assert result.returncode == 0
    spread = json.loads(result.stdout)
    assert spread["spread"] == draw_cards.SPREAD_NAME
    assert len(spread["houses"]) == 12


def test_cli_legacy_custom_count():
    result = subprocess.run(
        [sys.executable, str(Path(__file__).parent / "draw_cards.py"), "--legacy", "2"],
        capture_output=True,
        text=True,
    )
    assert result.returncode == 0
    cards = json.loads(result.stdout)
    assert len(cards) == 2


def test_cli_legacy_default_count():
    result = subprocess.run(
        [sys.executable, str(Path(__file__).parent / "draw_cards.py"), "--legacy"],
        capture_output=True,
        text=True,
    )
    assert result.returncode == 0
    cards = json.loads(result.stdout)
    assert len(cards) == 4


def test_cli_positional_count_without_legacy_is_error():
    """Positional count requires --legacy; the new default has a fixed shape."""
    result = subprocess.run(
        [sys.executable, str(Path(__file__).parent / "draw_cards.py"), "4"],
        capture_output=True,
        text=True,
    )
    assert result.returncode == 1
    assert "--legacy" in result.stderr


def test_cli_invalid_arg():
    result = subprocess.run(
        [sys.executable, str(Path(__file__).parent / "draw_cards.py"), "--legacy", "abc"],
        capture_output=True,
        text=True,
    )
    assert result.returncode == 1
    assert "Error" in result.stderr


def test_cli_out_of_range():
    result = subprocess.run(
        [sys.executable, str(Path(__file__).parent / "draw_cards.py"), "--legacy", "0"],
        capture_output=True,
        text=True,
    )
    assert result.returncode == 1

    result = subprocess.run(
        [sys.executable, str(Path(__file__).parent / "draw_cards.py"), "--legacy", "79"],
        capture_output=True,
        text=True,
    )
    assert result.returncode == 1


def test_no_secure_randbelow_function():
    """Regression: the custom secure_randbelow must be removed."""
    source = Path(__file__).parent / "draw_cards.py"
    text = source.read_text()
    assert "def secure_randbelow" not in text, "Custom secure_randbelow still exists"


def test_constants_are_immutable():
    """Constants must be tuples to prevent mutation."""
    assert isinstance(draw_cards.MAJOR_ARCANA, tuple), "MAJOR_ARCANA is not a tuple"
    assert isinstance(draw_cards.RANKS, tuple), "RANKS is not a tuple"
    assert isinstance(draw_cards.SUITS, tuple), "SUITS is not a tuple"
    assert isinstance(draw_cards.ZODIAC_HOUSES, tuple), "ZODIAC_HOUSES is not a tuple"


def test_draw_cards_rejects_non_int():
    """draw_cards() must reject non-int types cleanly."""
    for bad in [None, "3", 2.5, True, False, [4]]:
        try:
            draw_cards.draw_cards(bad)
            assert False, f"draw_cards({bad!r}) should have raised TypeError"
        except TypeError:
            pass


if __name__ == "__main__":
    tests = [v for k, v in sorted(globals().items()) if k.startswith("test_")]
    passed = failed = 0
    for test in tests:
        try:
            test()
            passed += 1
            print(f"  PASS  {test.__name__}")
        except AssertionError as e:
            failed += 1
            print(f"  FAIL  {test.__name__}: {e}")
        except Exception as e:
            failed += 1
            print(f"  ERROR {test.__name__}: {e}")
    print(f"\n{passed} passed, {failed} failed, {passed + failed} total")
    sys.exit(1 if failed else 0)