Mechanics Integrity Check

Validate SENTINEL game data consistency to catch bugs before they surface during play.

When to Use

• After modifying

  regions.json

  , job templates, or favor costs
• Before committing game data changes
• When adding new factions, regions, or mission types
• After updating schema enums
• Periodic health checks on game data

How to Run

Quick Check (Recommended)

Run the validation script directly:

python C:/dev/SENTINEL/sentinel-agent/scripts/check_mechanics.py

JSON Output (for CI/automation)

python C:/dev/SENTINEL/sentinel-agent/scripts/check_mechanics.py --json

Present Results

Format the output as an actionable checklist:

## Mechanics Health Report

### Status: [HEALTHY | NEEDS ATTENTION | BROKEN]

### Issues Found
- [ ] Issue 1 (ERROR) — must fix
- [ ] Issue 2 (WARNING) — should investigate
- [ ] Issue 3 (INFO) — informational

### Recommendations
- ...

What It Checks

Regions (

data/regions.json

)

• All 11 Region enum values have entries

• primary_faction

  and

  contested_by

  reference valid faction IDs

• adjacent

  lists contain valid region IDs
• Adjacency is bidirectional (if A→B then B→A)

Jobs (

data/jobs/*.json

)

• faction

  matches FactionName enum (display names)

• type

  matches MissionType enum

• region

  (if present) matches Region enum

• opposing_factions

  contain valid faction names

• requires_vehicle_tags

  exist in at least one vehicle

• requires_vehicle_type

  matches actual vehicle types

Vehicles (

tui_commands.py

VEHICLE_DATA)

• All job-required tags exist in at least one vehicle
• Reports orphan tags (defined but not used by any job) as INFO

Favors (

systems/favors.py

)

• All FavorType values have costs defined
• All Disposition levels have favor mappings and cost modifiers

Severity Levels

Exit Codes

Tips

• Run after any

  schema.py

  changes that add/remove enum values
• The check is read-only — it never modifies files
• JSON output can be filtered with jq:

  python check_mechanics.py --json | jq '.issues[] | select(.severity == "error")'
  

• Orphan vehicle tags (INFO) are not bugs — they're future-proofing for jobs not yet written

Data Sources

src/state/schema.py

data/regions.json

data/jobs/*.json

src/interface/tui_commands.py

src/systems/favors.py