name: simulation-invariant-auditor description: Proactively audits simulation logic while coding by collecting real artifacts via terminal access, generating helper scripts for repetitive workflows, and validating deterministic invariants across ticks, events, phases, markets, and resources. Use automatically whenever simulation semantics, ordering, lifecycle, persistence, or replay code is written or modified.

Simulation Invariant Auditor

This skill enforces simulation correctness as a contract, not a hope.

It is designed for an agent that is actively writing or modifying code in a tick-based, event-sourced simulation. The skill must be invoked proactively to validate that new or refactored logic preserves invariants before work continues.

In addition to analysis, this skill explicitly empowers the agent to author small helper scripts to accelerate repetitive investigation tasks (artifact discovery, log slicing, event filtering, trip timelines, replay diffs), as long as the scripts are safe, deterministic, and documented.

The auditor:

discovers real artifacts using terminal commands,
writes focused scripts when repetition would slow progress,
checks deterministic invariants against events and state,
identifies the earliest root violation,
produces an evidence-backed report with minimal repro guidance.

This skill does not implement feature changes unless explicitly instructed. It proves safety.

When to use this skill (Agent-centric, mandatory triggers)

The agent MUST invoke this skill automatically in the following situations:

1) After modifying simulation logic

Use immediately after writing or changing code affecting:

tick lifecycle or scheduling
trip phase transitions or dispatch readiness
passenger generation, boarding, release, or backlog handling
market demand allocation or pricing logic
fuel consumption, refueling, or resource constraints
cash flow, costs, or economic outcomes

Purpose: prove invariants still hold before proceeding.

2) After adding or modifying events

Use whenever the agent:

introduces a new event type
changes when an event is emitted
reorders event emission
modifies event payload semantics

Purpose: ensure event sourcing still yields lawful state transitions and determinism.

3) After refactors claiming “no behavior change”

Use during:

module extraction or file splitting
moving logic across modules
renaming or re-exporting APIs
restructuring control flow without intended semantic change

Purpose: detect accidental behavior drift.

4) After writing or updating simulation tests

Use after:

adding integration or end-to-end tests
modifying tests that exercise time, trips, or markets
observing or investigating flaky tests

Purpose: confirm tests rely on clean state and deterministic behavior.

5) Before concluding a fix involving simulation state

Use before finalizing work on bugs related to:

stuck or frozen trips
illegal phase transitions
incorrect occupancy or demand distribution
unexpected fuel or cash outcomes

Purpose: prove the fix, not assume it.

Operating principles (Non-negotiable)

Evidence first
- Every error finding must include concrete evidence: file paths, log line ranges, event ids, snapshot paths.
Determinism only
- No wall-clock time, randomness, or unordered iteration. Always sort before comparing.
Root-cause bias
- Prefer the earliest failing tick or transition over later symptoms.
No silent assumptions
- If required artifacts are missing, emit a warning with instructions to obtain them.
Read-only discipline by default
- Diagnose and recommend. Do not modify product logic unless explicitly instructed.
Scripts are allowed and encouraged
- Write small scripts to speed up repetitive tasks (see “Script Authoring Policy”).

Script Authoring Policy (Empowerment + Guardrails)

The agent is empowered to write scripts that accelerate repetitive diagnosis tasks.

Allowed script purposes

locate artifacts (logs/WAL/snapshots/slots)
slice logs around a tick or panic line
filter events by type/entity_id/tick range
render timelines (TripPhase changes, passenger release, dispatch readiness)
compute invariant checks from event streams (conservation, capacity, monotonicity)
diff replay outputs for determinism drift
generate minimal repro bundles (export subset of events + metadata)

Where scripts must live

Place all scripts under:

.agent/skills/simulation-invariant-auditor/scripts/ or if integrating into repo tooling:
tools/sim_audit/ (only if that folder already exists or is consistent with repo conventions)

Never scatter one-off scripts across the repo root.

Script requirements (must follow)

Small and focused: one job, clearly named.
Deterministic: no time-based behavior, no random seeds unless fixed.
Safe defaults:
- read-only unless a --write flag is passed
- never delete files by default
- never run network calls
Self-documenting:
- supports --help
- prints what it’s doing
- exits non-zero on errors
Portable:
- prefer bash + rg/jq/python3 if present
- avoid heavy dependencies
Idempotent:
- repeated runs produce the same output given the same inputs.

When to write a script vs one-off commands

Write a script when ANY of the following is true:

you repeat a command sequence more than twice
you need consistent slicing/filtering across multiple runs
you need a reusable audit step for CI or future debugging
you are generating structured output (JSON report, timeline)

Otherwise, use ad-hoc terminal commands.

Minimum script set (recommended)

If not already present, create these scripts as needed:

scripts/find_artifacts.sh — locate logs/WAL/snapshots/slots quickly
scripts/slice_log.sh — extract log lines around a pattern or tick
scripts/filter_events.py — filter ndjson events by tick/entity/type
scripts/trip_timeline.py — output trip timeline (phase + pax + readiness)
scripts/diff_replay.sh — compare two replay artifact sets

Scripts should output either:

human-readable text, or
machine-readable JSON when feeding other tools.

Artifact discovery (Terminal usage is mandatory)

If artifact paths are not explicitly provided, the agent MUST locate them using terminal commands or create a script to do it repeatedly.

Required discovery steps

ls
find . -maxdepth 4 -type d -name ".agent" -o -name "logs" -o -name "snapshots" -o -name "wal" -o -name "slots" 2>/dev/null
rg -n "panicked at|panic|Passenger release after boarding closed|freeze|stuck|tick" . 2>/dev/null || true
find . -type f \( -name "*.wal" -o -name "*.ndjson" -o -name "*.json" -o -name "*.snap" -o -name "*.log" \) | head -n 80

If tests are involved (Rust example):

cargo test -q -- --list | head -n 200
cargo test -q <suspect_test_name> -- --nocapture

Record all discovered artifact paths for evidence references.
Invariant catalog (Run in this order)
A. Tick & Time

    INV-TICK-001: tick is monotonic

    INV-TICK-002: tick progresses (detect stalls)

    INV-TICK-003: time and tick are non-decreasing

B. Trip Phase Machine

    INV-TRIP-001: only legal TripPhase transitions

    INV-TRIP-002: BoardingClosed is a hard boundary

    INV-TRIP-003: exactly one active phase per trip

    INV-TRIP-004: trip_id exists before use

C. Passenger Accounting

    INV-PAX-001: passenger conservation across pools

    INV-PAX-002: capacity constraints respected

    INV-PAX-003: no negative passenger counts

D. Economy & Resources

    INV-ECO-001: cash is finite

    INV-ECO-002: no illegal negative cash

    INV-FUEL-001: fuel ∈ [0, tank_capacity]

    INV-FUEL-002: fuel burn consistent with distance/efficiency

E. Market Allocation

    INV-MKT-001: allocations ≤ demand (+ documented rounding)

    INV-MKT-002: backlog is spent when used

    INV-MKT-003: sustained near-100% allocation requires justification

F. UI / Backend Contract

    INV-UI-001: UI dispatch enablement matches backend readiness

    INV-UI-002: selected assets are valid backend candidates

G. Persistence & Replay

    INV-PERSIST-001: detect saved-slot contamination

    INV-REPLAY-001: deterministic replay consistency

Audit procedure
Step 1 — Establish the failure window

From logs or test output:

    identify panic line, tick, event type, entity ids

    capture last known good tick
    If repetitive, write scripts/slice_log.sh.

Step 2 — Extract event/state stream

Prefer WAL or ordered event logs.
If unavailable, operate on snapshots and emit a warning.
If filtering is repeated, write scripts/filter_events.py.
Step 3 — Execute invariants

    Always run A + B first.

    Add others based on affected subsystem.

    Continue collecting findings unless configured to stop early.
    If invariant checks are repeated, write scripts/audit_invariants.py that outputs JSON.

Step 4 — Minimize to first failing tick

    Backtrack to earliest violation.

    Capture smallest tick/event window that reproduces.
    If narrowing is repeated, write scripts/minimize_repro.py.

Step 5 — Emit the Invariant Audit Report (required output shape)

{
  "ok": false,
  "summary": {
    "errors": 1,
    "warnings": 2,
    "checked_invariants": 14,
    "first_error_tick": 18240
  },
  "findings": [
    {
      "id": "INV-TRIP-002",
      "severity": "error",
      "message": "Passenger release occurred after BoardingClosed",
      "tick": 18240,
      "entity_refs": ["trip:1234"],
      "evidence_refs": ["logs/sim.log:4421-4430", "events.wal#89321"],
      "remediation_hint": "Guard passenger release with TripPhase == BoardingOpen in trip_logic.rs"
    }
  ],
  "repro": {
    "suggested_tick_range": { "start": 18210, "end": 18250 },
    "suggested_event_range": { "start_index": 89290, "end_index": 89340 }
  }
}

Remediation hint rules

Every error must include:

    probable subsystem (file/module)

    a concrete next step (assert, guard, ordering fix)

    a suggestion for a permanent invariant/assertion if missing

No generic advice. Be precise.
Suggested default scripts (create if they don’t exist)

The agent may create these scripts when helpful:

    scripts/find_artifacts.sh

    scripts/slice_log.sh

    scripts/filter_events.py

    scripts/trip_timeline.py

    scripts/audit_invariants.py

    scripts/diff_replay.sh

All scripts must support --help and be safe by default.
Final doctrine

This skill is a coding-time safety net.
Use it automatically whenever simulation semantics might be affected.

The job is to prove:

    the simulation remains lawful,

    time and causality remain intact,

    determinism is preserved,

    and repetitive investigation becomes fast through reusable scripts.

simulation-invariant-auditor

SKILL.md