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

Severity	Meaning	Action
ERROR	Breaks game functionality	Must fix
WARNING	Inconsistency that may work	Should investigate
INFO	Suggestion or design note	Optional

Exit Codes

Code	Meaning
0	All checks passed (HEALTHY)
1	Warnings only (NEEDS ATTENTION)
2	Errors found (BROKEN)

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

Data	Location
Schema enums	src/state/schema.py
Regions	data/regions.json
Jobs	data/jobs/*.json
Vehicles	src/interface/tui_commands.py
Favors	src/systems/favors.py