How, when, and why to run the meta-lint and mutation-edge-check pipeline
The project has two complementary lint tools that compose into a full validation pipeline. Every agent who creates or modifies .lua files under src/meta/ should run the linter before committing. This skill defines how.
Applies when:
.lua file in src/meta/ (objects, creatures, rooms, injuries, materials, levels, templates)scripts/meta-lint/lint.pyWhat: 306 rules across 20 categories validating object structure, naming, GUIDs, sensory fields, FSM, transitions, mutations, materials, rooms, cross-file references, creatures, injuries, and more.
Run on a single file:
python scripts/meta-lint/lint.py src/meta/objects/candle.lua
Run on all files:
python scripts/meta-lint/lint.py src/meta/
JSON output (for CI/scripting):
python scripts/meta-lint/lint.py src/meta/ --format json
With environment profile:
python scripts/meta-lint/lint.py src/meta/ --env dev # development rules
python scripts/meta-lint/lint.py src/meta/ --env prod # production rules (stricter)
Skip cache (full re-scan):
python scripts/meta-lint/lint.py src/meta/ --no-cache
Requires: Python 3.8+
scripts/mutation-edge-check.luaWhat: Scans all .lua files under src/meta/, extracts mutation edges from 12 mechanisms, verifies target files exist.
Human-readable report:
lua scripts/mutation-edge-check.lua
Target paths only (for piping to lint.py):
lua scripts/mutation-edge-check.lua --targets
JSON output:
lua scripts/mutation-edge-check.lua --json
Requires: Lua 5.4 (or 5.1 with setfenv fallback). Zero dependencies.
Exit codes: 0 = no broken edges, 1 = broken edges found.
scripts/mutation-lint.ps1 / scripts/mutation-lint.shWhat: Runs both tools in sequence: edge check first, then Python lint on all valid mutation targets.
PowerShell (Windows):
.\scripts\mutation-lint.ps1 # Full pipeline
.\scripts\mutation-lint.ps1 -EdgesOnly # Skip Python lint, just check edges
.\scripts\mutation-lint.ps1 -Env prod # Use production rules
.\scripts\mutation-lint.ps1 -ThrottleLimit 8 # More parallel workers (PS7)
Shell (Unix):
./scripts/mutation-lint.sh # Full pipeline (4 workers default)
./scripts/mutation-lint.sh 8 # 8 parallel workers
Parallel execution: Per D-MUTATION-LINT-PARALLEL, lint runs on multiple files concurrently (PS7 -Parallel / Unix xargs -P) but output is collected per-file and displayed sequentially with --- {file} --- headers to prevent interleaving.
| Situation | Tool | Why |
|---|---|---|
| Edited a single object file | python scripts/meta-lint/lint.py {file} | Quick single-file validation |
| Created a new mutation target | lua scripts/mutation-edge-check.lua | Verify the edge resolves |
| Before committing meta changes | lua scripts/mutation-edge-check.lua && python scripts/meta-lint/lint.py src/meta/ | Catch issues pre-commit |
| At a gate checkpoint | .\scripts\mutation-lint.ps1 | Full pipeline validation |
| In CI (automated) | Edge check step in squad-ci.yml | Catch regressions on push |
| Pre-deploy | Edge check in run-before-deploy.ps1 | Fast safety net |
| Level | Meaning | Action |
|---|---|---|
| ERROR | Rule violation that will cause runtime failure | Must fix before merge |
| WARNING | Potential issue, may cause unexpected behavior | Should fix, can defer with justification |
| INFO | Style/convention suggestion | Optional fix |
Every lint violation includes an owner field indicating which squad member should fix it. Default routing:
| Rule prefix | Owner |
|---|---|
| OBJ-, SEN-, MAT-, FSM-, MUT-* | Flanders (objects) |
| EXIT-, ROOM- | Moe (rooms) |
| CREATURE-, LOOT- | Flanders (creatures) |
| GUID-, XF-, XR-* | Bart (cross-cutting) |
| INV-* | Bart (inventory engine) |
| LV-* | Bart (level structure) |
All team members: New meta file additions should pass python scripts/meta-lint/lint.py with zero new findings before PR. This is an active decision — treat it as a gate.
scripts/meta-lint/lint.py without coordinating with Wiggum — single-file bottleneck, per D-LINTER-IMPL-WAVES--no-cache only for validation passes, not regular CI.meta-check.json — Project-level lint config (orphan allowlist, rule overrides).meta-lint-cache.json — Incremental cache (gitignored), keyed by SHA-256 hashscripts/requirements.txt — Python dependencies for meta-lint