cleanup: scrub environment-specific references, fix lint, update line numbers

Author: tmcarmichael

README.md

@@ -4,7 +4,7 @@
 ![Zero Dependencies](https://img.shields.io/badge/Dependencies-Zero-brightgreen.svg)
 ![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
 ![CI](https://github.com/tmcarmichael/compass-core/actions/workflows/ci.yml/badge.svg)
-![Coverage](<https://img.shields.io/badge/Coverage-71%25_(21.5K_measured)-blue.svg>)
+[![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/tmcarmichael/COVERAGE_GIST_ID/raw/coverage.json)](https://github.com/tmcarmichael/compass-core/actions/workflows/ci.yml)
 
 A layered decision architecture for intelligent behavior in a real-time 3D world.
 
@@ -16,7 +16,7 @@ Compass is a control architecture for agents that must perceive, decide, and act
 
 The architecture evolved in a legacy 3D MMORPG sandbox. It progressed from a monolith through reactive rules, state-machine routines, and utility scoring before arriving at goal-oriented planning. Each transition came when the previous approach broke against the world's complexity.
 
-> **Scope.** This is a cleaned extraction from a private working repo, published as an architecture reference. Live runtime config, environment assets, and operational glue are intentionally omitted. See [docs/samples/](docs/samples/) for real session output.
+> **Scope.** This is a cleaned extraction from a private working repo, published as an architecture reference. Live runtime config, environment assets, and operational glue are intentionally omitted. See [docs/samples/](docs/samples/) for real session output. For a step-by-step trace from perception to motor output, see [`docs/walkthrough.md`](docs/walkthrough.md).
 
 ---
 
@@ -220,7 +220,7 @@ All samples in [docs/samples/](docs/samples/) are real output from live sessions
 | [Forensics buffer](docs/samples/forensics-ring-buffer.md)        | 300-tick ring buffer dump: skeleton aggro interrupts spell memorization, FLEE fires within one tick                  |
 | [Learned encounter data](docs/samples/learned-encounter-data.md) | Cross-session improvement: grade B → A, fight duration 29.5s → 15.9s, auto-tuned parameters drifting from defaults   |
 | [Fight event](docs/samples/structured-fight-event.md)            | Structured `fight_end` event with all 20 fields and embedded world snapshot                                          |
-| [Convergence](docs/samples/convergence.md)                       | 10-session headless run: fight duration drops 53% as encounter history accumulates and cost functions self-correct    |
+| [Convergence](docs/samples/convergence.md)                       | 10-session headless run: fight duration drops 53% as encounter history accumulates and cost functions self-correct   |
 | [Ablation results](docs/samples/ablation-results.md)             | Learning vs. defaults: 97% GOAP cost error reduction, 25x danger discrimination, weight tuning stability             |
 
 ---

docs/architecture.md

@@ -273,7 +273,7 @@ Strategy selection uses learned encounter history when available; after 5+ encou
 
 ### Terrain
 
-Zone geometry is parsed from the game client's asset files own 3D asset files. The parsing pipeline extracts walkable surfaces and produces heightmap caches at 1-unit resolution.
+Zone geometry is parsed from the game client's own 3D asset files. The parsing pipeline extracts walkable surfaces and produces heightmap caches at 1-unit resolution.
 
 Each cell in the heightmap stores:
 

docs/walkthrough.md

@@ -6,7 +6,7 @@ What happens in one tick of the 10 Hz brain loop, traced through the actual sour
 
 ## 1. Clock gate
 
-[`brain/runner/loop.py:552`](../src/brain/runner/loop.py) -- The `TickClock` blocks until the next 100ms boundary. When it releases, the tick counter increments and the loop begins.
+[`brain/runner/loop.py:541`](../src/brain/runner/loop.py) -- The `TickClock` blocks until the next 100ms boundary. When it releases, the tick counter increments and the loop begins.
 
 ```
 _clock.wait_for_next_tick()
@@ -16,25 +16,25 @@ The clock measures `dt` (actual elapsed time since last tick). At 10 Hz with no
 
 ## 2. Perception snapshot
 
-[`brain/runner/loop.py:557-563`](../src/brain/runner/loop.py) -- `_tick_pre_state` calls `reader.read_state(include_spawns=True)`, which traverses the game client's internal pointer chains via `ReadProcessMemory` and returns a frozen `GameState` dataclass. This snapshot is immutable after creation: the brain thread produces it, every subsequent step consumes it, no locks needed.
+[`brain/runner/loop.py:546`](../src/brain/runner/loop.py) -- `_tick_pre_state` calls `reader.read_state(include_spawns=True)`, which traverses the game client's internal pointer chains via `ReadProcessMemory` and returns a frozen `GameState` dataclass. This snapshot is immutable after creation: the brain thread produces it, every subsequent step consumes it, no locks needed.
 
 The `GameState` contains: player position (x, y, z), HP/mana current and max, target info, heading, zone ID, combat flag, sitting flag, and a tuple of `SpawnData` for every visible entity.
 
 If the memory read fails (process not responding, pointer chain broken), the tick is skipped entirely -- the brain never evaluates stale state.
 
 ## 3. World state update
 
-[`brain/runner/loop.py:570`](../src/brain/runner/loop.py) -- `WorldStateUpdater.update_world_state()` refreshes the derived world model: NPC tracking (who appeared, who moved, who despawned), pet status, threat detection (approaching hostile entities), and health monitoring. This runs before rule evaluation so that rules see current-tick derived state.
+[`brain/runner/loop.py:559`](../src/brain/runner/loop.py) -- `WorldStateUpdater.update_world_state()` refreshes the derived world model: NPC tracking (who appeared, who moved, who despawned), pet status, threat detection (approaching hostile entities), and health monitoring. This runs before rule evaluation so that rules see current-tick derived state.
 
 For tick 1147: the world model registers a level-appropriate NPC at 85 units distance that was not present on the previous tick. The threat scanner classifies it as non-hostile (not approaching). The entity enters the world model's tracking table.
 
 ## 4. Pre-rule event detection
 
-[`brain/runner/loop.py:581-583`](../src/brain/runner/loop.py) -- Three pre-rule handlers run: XP tracking (records any XP change), add detection (checks if a new NPC is attacking the pet), and auto-engage scanning (detects if the current target changed). These update `AgentContext` sub-state objects before the decision engine reads them.
+[`brain/runner/loop.py:570-572`](../src/brain/runner/loop.py) -- Three pre-rule handlers run: XP tracking (records any XP change), add detection (checks if a new NPC is attacking the pet), and auto-engage scanning (detects if the current target changed). These update `AgentContext` sub-state objects before the decision engine reads them.
 
 ## 5. Rule evaluation (the decision)
 
-[`brain/runner/loop.py:608`](../src/brain/runner/loop.py) -- `brain.tick(state)` enters the decision engine. Inside [`brain/decision.py:154-161`](../src/brain/decision.py):
+[`brain/runner/loop.py:593`](../src/brain/runner/loop.py) -- `_tick_brain` calls `brain.tick(state)`, entering the decision engine. Inside [`brain/decision.py:173-180`](../src/brain/decision.py):
 
 ```python
 def tick(self, state: GameState) -> None:
@@ -48,7 +48,7 @@ def tick(self, state: GameState) -> None:
 
 ### 5a. Rule scan
 
-[`brain/decision.py:163-255`](../src/brain/decision.py) -- At Phase 0 (binary conditions, insertion-order priority), rules evaluate top to bottom. The first rule whose condition returns `True` wins. After a winner is found, remaining rules are skipped.
+[`brain/decision.py:182`](../src/brain/decision.py) -- At Phase 0 (binary conditions, insertion-order priority), rules evaluate top to bottom. The first rule whose condition returns `True` wins. After a winner is found, remaining rules are skipped.
 
 For tick 1147, the evaluation cascade looks like this (from the decision receipt in the sample data):
 
@@ -86,7 +86,7 @@ For this tick: `tab_target()` sends a Tab keypress. The next perception snapshot
 
 ## 8. Observability
 
-[`brain/runner/loop.py:614`](../src/brain/runner/loop.py) -- `_tick_record_diag` runs after the brain tick completes:
+[`brain/runner/loop.py:599`](../src/brain/runner/loop.py) -- `_tick_record_diag` runs after the brain tick completes:
 
 - **Decision receipt**: a structured record of which rules fired, their scores, the selected routine, lock state, and tick timing. This is the data in [`docs/samples/decision-trace.md`](samples/decision-trace.md).
 - **Forensics ring buffer**: the last 300 ticks of brain state, continuously overwritten. On death or crash, this buffer flushes to disk -- 30 seconds of pre-incident telemetry.
@@ -95,7 +95,7 @@ For this tick: `tab_target()` sends a Tab keypress. The next perception snapshot
 
 ## 9. Heartbeat
 
-[`brain/runner/loop.py:613`](../src/brain/runner/loop.py) -- The heartbeat timestamp updates. A secondary thread monitors this value; if it goes stale for 10+ seconds, the watchdog triggers recovery (process reconnection or graceful shutdown).
+[`brain/runner/loop.py:598`](../src/brain/runner/loop.py) -- The heartbeat timestamp updates. A secondary thread monitors this value; if it goes stale for 10+ seconds, the watchdog triggers recovery (process reconnection or graceful shutdown).
 
 ---
 

src/eq/s3d.py

@@ -22,8 +22,7 @@ def __init__(self, path: str | Path) -> None:
         self.path = Path(path)
         self._entries: dict[str, tuple[int, int]] = {}  # name -> (offset, size)
         raise NotImplementedError(
-            "S3DArchive parser stubbed in public release. "
-            "Provide an environment-specific implementation."
+            "S3DArchive parser stubbed in public release. Provide an environment-specific implementation."
         )
 
     def list_files(self) -> list[str]:

src/eq/wld.py

@@ -10,7 +10,6 @@
 
 from dataclasses import dataclass
 
-
 # ======================================================================
 # Data classes
 # ======================================================================
@@ -147,8 +146,7 @@ class WLDFile:
 
     def __init__(self, data: bytes) -> None:
         raise NotImplementedError(
-            "WLDFile parser stubbed in public release. "
-            "Provide an environment-specific implementation."
+            "WLDFile parser stubbed in public release. Provide an environment-specific implementation."
         )
 
     def extract_meshes(self) -> list[Mesh]:

src/perception/struct_validator.py

@@ -227,7 +227,9 @@ def _check_profile_chain(self) -> CheckResult:
             # Step 2: intermediate
             intermediate = self._r._read_pointer(ci + offsets.CHARINFO_PROFILE_INDIR)
             if intermediate == 0:
-                return CheckResult(name, False, f"character info+0x{offsets.CHARINFO_PROFILE_INDIR:03X} -> null")
+                return CheckResult(
+                    name, False, f"character info+0x{offsets.CHARINFO_PROFILE_INDIR:03X} -> null"
+                )
 
             # Step 3: profile base
             profile_base = self._r._read_pointer(intermediate + offsets.PROFILE_PTR_OFFSET)

src/simulator/runner.py

@@ -294,9 +294,7 @@ def _simulate_encounter_learning(self, scenario: Scenario) -> None:
             self._ctx.metrics.total_casts += 2
             self._ctx.metrics.routine_counts["PULL"] += 1
             self._ctx.metrics.routine_counts["IN_COMBAT"] += 1
-            self._ctx.metrics.routine_time["PULL"] = (
-                self._ctx.metrics.routine_time.get("PULL", 0) + 3.0
-            )
+            self._ctx.metrics.routine_time["PULL"] = self._ctx.metrics.routine_time.get("PULL", 0) + 3.0
             self._ctx.metrics.routine_time["IN_COMBAT"] = (
                 self._ctx.metrics.routine_time.get("IN_COMBAT", 0) + duration
             )

tests/test_eq_parsers.py

@@ -25,7 +25,6 @@
     load_zone_chr,
 )
 
-
 # ===========================================================================
 # zone_chr.py -- data classes (not stubbed)
 # ===========================================================================

tests/test_loadout.py

@@ -9,7 +9,7 @@
 
 import pytest
 
-from eq.spells import SpellDB, SpellRole
+from eq.spells import SpellDB
 
 # ---------------------------------------------------------------------------
 # Helpers -- reuse the _spell factory
@@ -32,7 +32,7 @@ def _spell_data(
     range: int = 200,
     recast_ms: int = 0,
 ):
-    from eq.spells import ResistType, SpellData, TargetType
+    from eq.spells import SpellData
 
     if class_levels is None:
         class_levels = (255,) * 16

tests/test_race_data.py

@@ -9,7 +9,6 @@
 
 from eq.race_data import RACE_NAMES, RaceDB, RaceModelData, load_race_data
 
-
 # ---------------------------------------------------------------------------
 # RACE_NAMES static lookup (stubbed to empty)
 # ---------------------------------------------------------------------------