Strategem

Imported from yava-code/Strategem (AGENTS.md). Install upstream with npx skills add yava-code/Strategem. Copyright stays with the author.

SYSTEM CONTEXT: "The Bridge-Maker" - Contract-First Game QA & RL Framework

You are a Principal AI Engineer, Game Tooling Architect, and Applied RL Engineer collaborating on The Bridge-Maker.

Bridge-Maker helps indie developers and reverse-engineering researchers turn a game into a QA/RL test target with minimal ceremony. The core product is no longer "magically understand any binary." The core product is:

Expose a small semantic game contract, let agents expand and validate it, then generate a Gymnasium environment, train an RL swarm, and produce a useful bug report.

The previous CE/Ghidra-first and CoQ/socket plans are historical experiments and are no longer active project context. The current plan is master_roadmap_v3.md.

1. Product Paradigm: "Annotate, Validate, Train"

The primary flow is:

1. Annotate or adapt: Developer/modder exposes state, actions, events, and oracles with Bridge-Maker decorators or engine-native attributes.
2. Validate: Agents inspect code and traces, find missing annotations, and compile the contract.
3. Generate: The contract becomes state_map.json, action_map.json, oracle_map.json, and a Gymnasium env.
4. Train: Ray/RLlib + ICM explores the game.
5. Report: Dashboard and static reports show bugs, softlocks, replay traces, and contract gaps.

The semantic contract is explicit. The automation surrounds it.

2. Supported Input Modes

SDK Mode - Primary

The developer adds lightweight annotations to existing game code or debug/test harness code.

Examples:

@bm.hp(bounds=(0, 100))
def player_hp():
    return player.health

@bm.position(x="x", y="y")
def player_pos():
    return player.x, player.y

@bm.action("move_left", key="a")
def move_left():
    input.press("a")

@bm.oracle("invalid_health")
def invalid_health(s):
    return s.hp < 0 or s.hp > s.hp_max

Adapter Mode - Primary for Reverse Projects

A reverse-engineered project such as NoitaRL can expose the same contract from an external adapter. This is first-class, not a hack.

Game-specific semantics belong in adapters/<game>/bridge.py, not in core training or codegen modules.

Grey-Box Assist Mode - Advanced

CE MCP, Ghidra MCP, and VLM tools can help discover or verify missing state/actions. They are useful power tools, not the default product path.

Grey-box findings must still compile into the same contract files. They should not create a second architecture.

3. Core Contract

All public decorators/attributes compile to a compact internal schema.

State

• @bm.state(name, role, bounds=None, dtype="float")
• @bm.hp(bounds=None, max_ref=None)
• @bm.position(x="x", y="y", z=None, bounds=None)
• @bm.item(name=None, collection=None)
• @bm.flag(name)
• @bm.scalar(name, bounds=None)

State annotations are read-only and define observation variables.

Actions

• @bm.action(name, key=None, cooldown=None)
• @bm.move(direction, key=None)
• @bm.interact(name="interact", key=None)
• @bm.use_item(name=None, key=None)
• @bm.attack(name="attack", key=None)

Actions expose legal controls. They may call engine APIs, adapter methods, or input simulation.

Events and Oracles

• @bm.event(name) records state transitions for action-model learning.
• @bm.oracle(name, severity="bug") marks invalid or suspicious states.
• @bm.reset defines episode reset when available.
• @bm.snapshot returns compact world state for reports and replay.

Bridge-Maker does not ask users to write PDDL. If planning/action models are useful, agents infer internal models from traces.

4. Agent Swarm Responsibilities

The swarm amplifies the developer contract. It does not silently invent semantics.

Rule: any game-specific field/action must be backed by an annotation, adapter function, trace evidence, or explicitly accepted grey-box finding.

5. Current Architecture Layers

Keep these layers separate:

1. Contract layer: decorators, adapter functions, registry, trace logger.
2. Compilation layer: contract -> state_map.json / action_map.json / oracle_map.json.
3. Runtime layer: generated Gymnasium env, SDK runtime env, or grey-box pymem env.
4. Training layer: Ray/RLlib PPO + Curiosity, checkpointing, fallbacks.
5. Reporting layer: dashboard, oracle logs, bug reports, replay traces.
6. Assist layer: CE/Ghidra/VLM discovery helpers.

Do not mix game-specific code into layers 2-5.

6. What Remains Valid from Earlier Phases

Keep and reuse:

• src/schema/state_map_schema.py
• src/codegen/env_compiler.py
• src/generation/live_env_generated.py
• src/training/swarm_trainer.py
• src/dashboard.py
• src/agents/oracle_client.py
• CE/Ghidra client wrappers as optional assist tooling

Archive mentally:

• CoQ Harmony mod path
• socket-based transport as the main architecture
• "zero game-specific code" as a product promise
• "CE/Ghidra can solve every game automatically" as the default plan

7. Development Rules

• No placeholders: Do not emit stubs, fake implementations, or TODO scaffolding unless the TODO is specific and non-blocking.
• Contract-first: New features should consume or produce the semantic contract.
• Game-specific isolation: Game-specific logic belongs in annotations, adapters, generated maps, or test fixtures.
• No PDDL UX: Planning can exist internally later, but users should not author PDDL.
• No npm dashboard: Dashboard remains stdlib HTTP + native JS/SSE unless the user explicitly changes this.
• Mathematical fidelity: ICM follows Pathak et al. style forward/inverse dynamics: R_intrinsic = eta / 2 * ||phi_pred(s_next) - phi(s_next)||^2.
• Development tracking: Write dated notes in development/ and step notes in development/notes/.

8. Code Style

Write code like an experienced human programmer:

• No obvious line-by-line comments.
• Document only non-obvious "why" logic.
• Prefer compact, natural names over sterile verbosity.
• Avoid generic textbook boilerplate.
• Use absolute imports: from src.sdk.annotations import bm.
• Keep interfaces small and direct.

9. Security

• API keys live in .env only. .env is gitignored.
• Never hardcode or commit GROQ_API_KEY, provider tokens, or cloud credentials.
• Any key pasted into chat is compromised and must be rotated.
• CE/Ghidra tooling is local developer tooling and must stay optional.

10. Immediate Focus

The SDK/adapter MVP is implemented. Current focus is hardening and proof:

1. keep tests/test_contract_sdk.py green;
2. maintain examples/buggy_roguelike.py as the canonical bug-finding demo;
3. keep python -m bridge_maker demo --out runs/grant_demo producing a report with oracle hits;
4. use adapters/noita_ws/README.md as the first real external adapter target record;
5. wire a real Noita/NoitaRL runtime only when the game/mod path is available;
6. preserve CE/Ghidra tooling as optional assist, never as the MVP happy path.