skara-brae-common/docs/openup/test/quality-check-procedure.md

Quality Check Procedure

Skara Brae — OpenUP Test · migrated 2026-10-05 from the Joplin note of the same name (markdown is the single content home; Joplin keeps status only). Post-migration update: the three unchecked items below were resolved — rand::rng() direct use by WI-1 (single construction point request_rng()), handler-side business logic by WI-2 (run_adventure extraction) and constants by WI-2 (sb-core::constants).

Purpose

Systematic verification that the implementation matches design notes, passes all code checks, and follows Clean Code / Clean Architecture principles.

Procedure

Step 1: Code Checks

# Rust build + clippy
cd ~/Development/skara-brae/skara-brae-server && cargo clippy -- -W clippy::all 2>&1

# Rust tests
cd ~/Development/skara-brae/skara-brae-server && cargo test 2>&1

# Vue typecheck
cd ~/Development/skara-brae/skara-brae-client && npx vue-tsc --noEmit 2>&1

Step 2: Implementation vs Design Notes

For each design note, verify the implementation matches:

Note (docs/)	What to Check
docs/game/game-concept-overview.md	Character system (races, classes, stats), economy model, adventure structure
docs/game/combat-system-stat-scaling-design.md	BIGINT stats, open-ended d100, crit tables, crit caps by level diff
docs/game/mechanics-source-mapping.md	BT1/RM/IF/Torn mapping consistency
docs/game/tech-stack-architecture.md	Crate structure, dependency direction, deployment
docs/game/skill-magic-system.md	Spell system design vs implementation
docs/game/medals-honours-system.md	Medal system (not yet implemented)
docs/game/idle-fantasy-inspirations.md	Features adopted from IF
docs/openup/analysis-design/architecture-notebook.md	Layers, dependency rule, key abstractions

Check items:

• Stats are i64 (BIGINT) — not i32
• 5 races match design (Human, Elf, Dwarf, Hobbit, HalfElf)
• 10 classes match design (Warrior through Sorcerer, no Cleric)
• Crit damage cap by level difference implemented
• Open-ended d100 combat rolls
• BT1 items (127), enemies (125), spells (79), songs (6) all present
• Zones match BT1 dungeon structure (8 zones)
• Shop economy uses BT1 gold values
• Bard songs with combat integration
• Spell system with SP costs, learning, combat casting
• Training costs gold (not just energy)
• Review Board level-up: XP threshold polynomial (18×100×(level-1)²), gold cost, max level 100

Step 3: Clean Architecture Audit

Check dependency direction:

• sb-shared → no dependencies on other game crates (domain types only)
• sb-core → depends only on sb-shared + sb-common (domain services, no HTTP)
• sb-api → depends on sb-core, sb-shared, sb-auth, sb-db (HTTP adapters)

Check layer violations:

• No serde_json in domain logic (only in LazyLock data loaders)
• No include_str! called during business logic (only module-level const)
• No rand::rng() in domain functions — resolved by WI-1: single construction point request_rng(), domain takes injected rng
• Route handlers delegate to domain services — resolved by WI-2 for adventure; remaining handler-side logic (shop, heal, parts of spells) is recorded debt (Architecture Notebook D1, follow-up question Q3)

Check code quality:

• No magic numbers — resolved by WI-2: sb-core::constants is the audit home
• No abbreviations in variable names
• Functions do one thing, are short
• No duplicated logic across modules
• No comments that restate code
• Fail fast, return early — happy path flat
• No mixed concerns (HTTP + business logic in same function)

Step 4: Bug Scan

• All gold/energy/nerve/SP costs are both displayed AND enforced
• All state mutations happen inside write locks
• No unwrap() on fallible operations in request paths — WI-2 §6 ledger classifies the remaining ones as documented keep-with-reason invariants
• All enum match arms exhaustive
• No integer overflow paths (xp_for_level uses saturating arithmetic)

Audit History

Date	Clippy	Tests	vue-tsc	Criticals Found	Criticals Fixed
2026-08-03 #1	18 warnings	0 tests	clean	3	3
2026-08-03 #2	0	42 pass	clean	4	4
2026-08-03 #3	0	44 pass	clean	1	1

Quality Gate

A check passes when:

• Zero clippy warnings (excluding allowed lints)
• Zero typecheck errors
• All tests pass
• Zero critical architecture violations
• All tracked inconsistencies have a ticket or accepted rationale