Enhance Card Game with Parameterization & Telemetry
Budget: $3,000 – $5,000 USD
Scope: Implement determinism, telemetry, and parameterization for a 3-card poker variant with special doubling rules. Working from a pre-existing prototype.
Must-haves:
-Deterministic RNG (seeded) with golden replays and a replay verifier.
-Parameterized rules via a single config file (bet limits, fees, stake cap, double rules, dealer draw policy, rank/tie rules, max buys, post-double behavior) with validation.
-Telemetry conforming to SPEC-TLM-001 (local only), fixed-point per STD-001 via a central Quantizer.
-CLI: bj-eval (EVs/CI) and replay (determinism check).
-Tests + CI: unit/integration, snapshot EVs vs golden files.
-Docs: README, CHANGELOG, JSON schemas, example configs, performance target.
A) Definition of Done ( DoD )
Build compiles, runs, and passes tests on a clean machine.
Deterministic replay: same seed → same outcome; golden files included.
JSON schemas validated; CLI exit codes correct; README explains how to run everything.
B) Testing & CI
Unit + integration tests for: hand ranking, tie rules, dealer draw logic, doubling lock/skip, buy limits.
CI pipeline: build, run tests, run a small deterministic Monte Carlo, compare EV outputs to golden snapshots.
C) Replay & Golden Artifacts
Replay file format defined (seed, ruleset_hash, actions, outputs).
Golden replays shipped in repo; checksum verification step included.
D) Config Surface (your “parameterization,” but explicit)
One config file (JSON/YAML) listing: bet sizing limits, buy fee, stake cap, double/re-double multipliers, rank/tie rules, dealer draw policy, max buys, post-double rules, toggles for future modes.
Validation on load with sensible defaults; reject illegal combos.
E) Numeric Policy
Fixed-point integers at emission per STD-001 (EV_SCALE/UNITS_SCALE/SCORE_SCALE).
Centralized Quantizer; all telemetry and cached EVs pass through it before hashing/logging.
F) Telemetry (pointer, not a dissertation)
Conform to SPEC-TLM-001 v1.1 INTERNAL.
Fields: seed, ruleset_hash, state_hash, action, Q_ev_bp, V_state_bp, outcome, ci_95_bp, samples.
Local files, 7-day rotation; no external upload.
G) CLI Tools
bj-eval CLI: inputs {ruleset, seed/samples}, outputs per-action EV, best action, CI, samples, runtime, version.
replay CLI: consumes a replay, verifies determinism, prints mismatches with diffs.
H) Performance & Limits
Target runtime for a standard sample set (e.g., 100k samples ≤ N seconds on a midrange PC).
Memory cap rough limit; graceful fail with clear error messages.
I) Error Handling & Logging
Structured errors, non-zero exit codes on failure.
Debug logs behind a flag; no secrets, no PII.
J) Documentation & Handoff
Short README with: setup, run commands, config reference, known caveats.
CHANGELOG noting any ruleset or comparator changes that affect replays.
Proper Parameterization
1. Economy / Bet Logic,
2. Hand Rules and Ranks,
3. Round Flow and Limits,
4. Dealer Behavior Parameters
5. EV / Simulation Settings
6. UI / Logging / Telemetry Configs
Must-haves:
-Deterministic RNG (seeded) with golden replays and a replay verifier.
-Parameterized rules via a single config file (bet limits, fees, stake cap, double rules, dealer draw policy, rank/tie rules, max buys, post-double behavior) with validation.
-Telemetry conforming to SPEC-TLM-001 (local only), fixed-point per STD-001 via a central Quantizer.
-CLI: bj-eval (EVs/CI) and replay (determinism check).
-Tests + CI: unit/integration, snapshot EVs vs golden files.
-Docs: README, CHANGELOG, JSON schemas, example configs, performance target.
A) Definition of Done ( DoD )
Build compiles, runs, and passes tests on a clean machine.
Deterministic replay: same seed → same outcome; golden files included.
JSON schemas validated; CLI exit codes correct; README explains how to run everything.
B) Testing & CI
Unit + integration tests for: hand ranking, tie rules, dealer draw logic, doubling lock/skip, buy limits.
CI pipeline: build, run tests, run a small deterministic Monte Carlo, compare EV outputs to golden snapshots.
C) Replay & Golden Artifacts
Replay file format defined (seed, ruleset_hash, actions, outputs).
Golden replays shipped in repo; checksum verification step included.
D) Config Surface (your “parameterization,” but explicit)
One config file (JSON/YAML) listing: bet sizing limits, buy fee, stake cap, double/re-double multipliers, rank/tie rules, dealer draw policy, max buys, post-double rules, toggles for future modes.
Validation on load with sensible defaults; reject illegal combos.
E) Numeric Policy
Fixed-point integers at emission per STD-001 (EV_SCALE/UNITS_SCALE/SCORE_SCALE).
Centralized Quantizer; all telemetry and cached EVs pass through it before hashing/logging.
F) Telemetry (pointer, not a dissertation)
Conform to SPEC-TLM-001 v1.1 INTERNAL.
Fields: seed, ruleset_hash, state_hash, action, Q_ev_bp, V_state_bp, outcome, ci_95_bp, samples.
Local files, 7-day rotation; no external upload.
G) CLI Tools
bj-eval CLI: inputs {ruleset, seed/samples}, outputs per-action EV, best action, CI, samples, runtime, version.
replay CLI: consumes a replay, verifies determinism, prints mismatches with diffs.
H) Performance & Limits
Target runtime for a standard sample set (e.g., 100k samples ≤ N seconds on a midrange PC).
Memory cap rough limit; graceful fail with clear error messages.
I) Error Handling & Logging
Structured errors, non-zero exit codes on failure.
Debug logs behind a flag; no secrets, no PII.
J) Documentation & Handoff
Short README with: setup, run commands, config reference, known caveats.
CHANGELOG noting any ruleset or comparator changes that affect replays.
Proper Parameterization
1. Economy / Bet Logic,
2. Hand Rules and Ranks,
3. Round Flow and Limits,
4. Dealer Behavior Parameters
5. EV / Simulation Settings
6. UI / Logging / Telemetry Configs