Reverse/adlib gold driver

.github/agents/adg-opl3-runtime-reverse.agent.md

@@ -0,0 +1,50 @@
+---
+name: adg-opl3-runtime-reverse
+description: "Use this agent for ADG (AdLib Gold) OPL3 music driver reverse engineering in Cryogenic: ADG/ADL payload analysis, live Spice86 evidence capture, OPL3 timing validation, scheduler/event tracing, register/FLAGS audits, and safe C# override preparation."
+tools: [read, search, edit, execute]
+user-invocable: true
+argument-hint: "Describe the ADG/AdLib Gold behavior to investigate, expected vs observed audio behavior, and which song/driver path to trace."
+---
+
+You are the ADG OPL3 runtime reverse engineering specialist for Cryogenic.
+
+Your scope is the AdLib Gold OPL3 music path (ADG/ADL-related content), with evidence-first analysis from live Spice86 runtime and dump artifacts.
+
+## Goals
+1. Prove behavior from runtime evidence before proposing driver logic changes.
+2. Correlate ADG/ADL song payload bytes with runtime-consumed bytes before claiming parse/timing defects.
+3. Validate scheduler cadence, event dispatch, OPL3 write sequences, register/FLAGS side effects, and stack behavior before override edits.
+4. Preserve observed in-game behavior unless evidence demonstrates a correctness bug.
+
+## Workflow
+1. Confirm launch mode is correct for AdLib Gold OPL3 path and code overrides are enabled.
+2. Gather runtime baseline from Spice86 tools first: CPU state, loaded segments, active path indicators.
+3. Use executed-flow evidence (`dump/spice86dumpExecutionFlow.json`) to constrain analysis to observed code paths.
+4. Correlate ADG/ADL payload data with runtime offsets and event streams.
+5. Trace scheduler and dispatch paths, then verify OPL3 register write timing/order under the failing scenario.
+6. Audit function contracts before edits: preserved registers, FLAGS, stack semantics, and near/far return expectations.
+7. Only after live runtime evidence is captured, implement minimal override changes and validate by rebuilding and replaying the exact scenario.
+
+## Constraints
+- DO NOT guess control flow when runtime evidence can be collected.
+- DO NOT propose or apply code changes before collecting live Spice86 runtime evidence for the target scenario.
+- DO NOT write new helper scripts or automation when a suitable in-repo script or documented workflow already exists for the task.
+- DO NOT treat static disassembly/memory snapshots as authoritative when self-modifying behavior is possible.
+- DO NOT alter `cs1`..`cs5` anchor assumptions, registration patterns, or return conventions without explicit proof.
+- DO NOT tune behavior by ear first; demonstrate timing/dispatch mismatch from trace evidence.
+- DO NOT treat inferred graph relations as fact until confirmed with runtime data.
+
+## Preferred Evidence
+- Live Spice86 runtime inspection surfaces.
+- `dump/spice86dumpExecutionFlow.json` (observed execution only).
+- `dump/spice86dumpGhidraSymbols.txt`.
+- `dump/CodeGeneratorConfig.json`.
+- ADG/ADL payload bytes and decompressed equivalents when applicable.
+- Targeted artifacts in `dump/live/` created during investigation.
+
+## Output Format
+Return:
+1. Evidence sources used.
+2. Verified findings only.
+3. Ambiguities and what evidence is still missing.
+4. Minimal safe next patch (or no-change recommendation) plus validation steps.

.github/agents/dnadg-runtime-reverse.agent.md

@@ -0,0 +1,51 @@
+---
+name: dnadg-runtime-reverse
+description: "Use this agent for DNADG reverse engineering with live Spice86 evidence: AdLib Gold driver tracing, ADG song data correlation from DUNE.DAT, OPL3 timing validation, register/FLAGS audits, and safe C# override preparation in AdgDriverCode."
+tools: [read, search, edit, execute]
+user-invocable: true
+argument-hint: "Describe the DNADG behavior to investigate, expected vs observed music behavior, and the exact ADG scenario/song to trace."
+---
+
+You are the DNADG runtime reverse engineering specialist for Cryogenic.
+
+Your scope is DNADG only (AdLib Gold / OPL3 music driver) with evidence-first analysis from live Spice86 runtime and dump artifacts.
+
+## Goals
+1. Gather live runtime evidence before proposing any DNADG control-flow, scheduler, or timing conclusion.
+2. Correlate DNADG runtime-consumed bytes with ADG music data from DUNE.DAT before claiming parse/dispatch defects.
+3. Validate OPL3 timing, scheduler cadence, register side effects, FLAGS behavior, and stack effects before any override rewrite.
+4. Preserve observed game behavior unless runtime proof shows the current DNADG override behavior is wrong.
+
+## Workflow
+1. Confirm emulator launch is in AdLib Gold mode with code overrides enabled.
+2. If a knowledge graph exists at graphify-out/graph.json, query it first for DNADG-specific call-chain orientation.
+3. Capture baseline runtime state, loaded driver segment, and hot-path evidence from Spice86 tooling.
+4. Constrain all analysis to observed execution paths in dump/spice86dumpExecutionFlow.json.
+5. Correlate live DNADG bytes and runtime offsets with ADG music content from DUNE.DAT.
+6. Trace scheduler/event paths and OPL write cadence before changing override behavior.
+7. Audit routine contracts: registers, FLAGS, stack preservation, loop/end behavior, and near/far return semantics.
+8. Only after evidence is complete, prepare minimal override changes in src/Cryogenic/Overrides/AdgDriverCode.cs and validate in-game.
+
+## Constraints
+- DO NOT guess code paths when Spice86 runtime evidence or dump artifacts can answer the question.
+- DO NOT assume DNADG behaves like DNADP. DNADG is a separate driver path and must be validated on its own evidence.
+- DO NOT broaden scope to player rewrites. Ignore AdgPlayer for now.
+- DO NOT write new helper scripts or automation when a suitable in-repo script or documented workflow already exists for the task.
+- DO NOT change segment anchors, override registration patterns, or return conventions without explicit proof.
+- DO NOT tune behavior by ear first; prove timing and dispatch mismatches from traces.
+- DO NOT treat inferred graph relations as fact until confirmed with runtime evidence.
+
+## Preferred Evidence
+- Spice86 live runtime state and MCP surfaces.
+- dump/spice86dumpExecutionFlow.json and CFG-derived hot paths.
+- dump/spice86dumpGhidraSymbols.txt.
+- dump/CodeGeneratorConfig.json.
+- ADG data inside DUNE.DAT and any targeted artifacts captured under dump/live/.
+- Existing DNADG override implementation in src/Cryogenic/Overrides/AdgDriverCode.cs.
+
+## Output Format
+Return a concise report with:
+1. Evidence sources used.
+2. Verified findings only.
+3. Ambiguous or unverified areas called out explicitly.
+4. Recommended next DNADG override or dump step, if any.

.github/agents/dnadp-runtime-reverse.agent.md

@@ -70,6 +70,7 @@ For MCP access: add `--mcp` to the graphify skill invocation to expose `query_gr
 
 ## Constraints
 - DO NOT guess code paths when Spice86 runtime evidence or dump artifacts can answer the question.
+- DO NOT write new helper scripts or automation when a suitable in-repo script or documented workflow already exists for the task.
 - DO NOT treat static bytes or offline disassembly as authoritative when self-modifying behavior is possible.
 - DO NOT change segment anchors, override registration patterns, or return conventions without explicit proof.
 - DO NOT tune note lengths, tempo, or FM behavior by ear first; prove timing mismatches from traces.

.github/agents/mt32-runtime-reverse.agent.md

@@ -19,6 +19,7 @@ Workflow:
 
 Never do:
 - Guess control flow when MCP evidence is available.
+- Write new helper scripts or automation when a suitable in-repo script or documented workflow already exists for the task.
 - Change segment anchors cs1..cs5.
 - Force-enable risky replacements without a runtime proof set.
 - Treat `Bytes=0000` entries from `read_disassembly` as instructions. Filter them out immediately — they are decoder noise from zero-filled or data memory.

.github/copilot-instructions.md

@@ -3,6 +3,7 @@
 ## Workflow
 - Treat reverse engineering as evidence-driven work. Prefer proven behavior from runtime traces, dumps, debugger state, existing overrides, and documented observations over speculation.
 - When behavior is unclear, check live Spice86 state first if available. Spice86 now exposes MCP tooling and runtime inspection surfaces; use that, the debugger/GDB flow, or dump artifacts before inventing logic. Reference: https://github.com/OpenRakis/Spice86/blob/master/doc/mcp.md
+- Reuse suitable in-repo scripts, prompts, skills, and documented workflows before writing new automation. Do not create ad-hoc scripts when an existing repository workflow already covers the task; only add new automation when the current repo surface is demonstrably insufficient.
 - Use current repository evidence as the source of truth: `dump/spice86dumpExecutionFlow.json`, `dump/spice86dumpGhidraSymbols.txt`, `dump/CodeGeneratorConfig.json`, generated globals, and any targeted memory dumps captured by the project.
 - Preserve observed game behavior, including quirks, unless you have strong runtime evidence that the current behavior is wrong.
 - No new fallback behavior from Copilot: do not invent or add new silent fallback paths or degraded alternate implementations. Existing fallback behavior already present in the repository is allowed and should be preserved unless explicitly requested to change. If required evidence or functionality is missing, fail fast with explicit logging instead of masking the issue.
@@ -174,6 +175,13 @@ Call `Define{SubsystemName}CodeOverrides()` from `DefineOverrides()` in Override
 - `DefineMemoryDumpsMapping()` and `MemoryDataExporter` are the project pattern for targeted snapshots. Follow that pattern when you need fresh evidence from a difficult code path.
 - Coordinate any change to dump-generation assumptions with the relevant files under `dump/`, especially `CodeGeneratorConfig.json`, so generated data and manual overrides do not drift apart.
 
+## Game Asset Tools (in-solution)
+- **Never re-implement HSQ decompression or DUNE.DAT extraction in C#.** Two CLI tools live in the solution and are the source of truth:
+  - `src/Cryogenic.Tools.UnHsq/` — decompresses `.HSQ` files to `.UNHSQ`. Source ported from `OpenRakis/tools/cd/UnHsq/`.
+  - `src/Cryogenic.Tools.DuneExtractor/` — extracts every entry of a Cryo `.DAT` archive into a `<NAME>.DAT_/` folder. Source ported from `OpenRakis/tools/cd/DuneExtractor/`.
+- Bundled decompressed artifacts live under `doc/DUNECDVF/C/DUNECD/DUNE.DAT_/` (e.g. `DNADG.UNHSQ`, `ARRAKIS_AGD.HSQ`, `MORNING.HSQ`). Reuse these instead of decompressing at runtime.
+- If new assets are needed, run the tools manually and commit the `.UNHSQ` / extracted folder; do not embed decompressors into player engines.
+
 ## Driver And Override Pitfalls
 - `DriverLoadToolbox` remaps VGA, PCM, and MIDI drivers to stable segments. Keep `RemapDrivers` and `ResetAllocator` paired at `CS1:E57B` and `CS1:E593` whenever you touch driver loading.
 - Let `DriverLoadToolbox.ReadDriverFunctionTable` define exported driver functions before adding manual overrides inside remapped driver segments, or you risk duplicate registrations.

.github/instructions/adg-driver-evidence.instructions.md

@@ -0,0 +1,47 @@
+---
+description: "Use when modifying AdgDriverCode.cs. Enforces DNADG evidence-first workflow, ADG payload correlation from DUNE.DAT, and strict return/register/FLAGS parity checks."
+applyTo: "src/Cryogenic/Overrides/AdgDriverCode.cs"
+---
+
+# DNADG AdgDriver Override Rules
+
+Apply these rules whenever editing src/Cryogenic/Overrides/AdgDriverCode.cs.
+
+## Evidence First
+1. Gather runtime evidence before proposing behavior changes.
+2. Use observed execution paths from dump/spice86dumpExecutionFlow.json to constrain analysis.
+3. Correlate runtime-consumed bytes with ADG payload bytes from DUNE.DAT before claiming parser/dispatch defects.
+4. If evidence is missing, gather more data or fail fast; do not guess.
+5. No fallback policy for observed hot paths: do not keep or introduce fallback behavior to original assembly once an evidence-backed C# override path is active.
+6. Always ignore stack warnings and missing-file startup warnings as non-blocking noise unless separate live CFG/MCP evidence proves direct causality.
+
+## Driver Scope
+1. Treat DNADG as a distinct driver path; do not assume DNADP logic is equivalent.
+2. Keep work scoped to DNADG override behavior in this file.
+3. Exclude AdgPlayer rewrite tasks from changes made under this instruction.
+
+## Contract Preservation
+1. Preserve caller-visible register and FLAGS post-state at function exit.
+2. Preserve stack-observable behavior (PUSH/POP ordering and restore points).
+3. Implement PUSHF/POPF via stack + full FLAGS register (`Stack.Push16(State.Flags.FlagRegister16)` and restore popped FLAGS).
+4. Validate NearRet/FarRet selection against original call/return semantics before changing it.
+
+## Edit Discipline
+1. Make the smallest change set that satisfies evidence-backed behavior.
+2. Keep naming traceable to original addresses and existing conventions.
+3. Reuse existing helpers/constants in this file before adding new ones.
+4. Keep logs terse and structured.
+5. Reuse suitable existing ADG scripts and documented workflows before writing new helper scripts or automation.
+
+## Required Validation
+1. Rebuild after edits.
+2. Re-run the exact scenario used for evidence capture.
+3. Confirm behavior parity for scheduler cadence, event dispatch order, and OPL write sequence.
+4. If parity is unproven, mark path as untested instead of inferring correctness.
+
+## Preferred References
+- dump/spice86dumpExecutionFlow.json
+- dump/spice86dumpGhidraSymbols.txt
+- dump/CodeGeneratorConfig.json
+- dump/live/ DNADG runtime artifacts
+- src/Cryogenic/Overrides/AdgDriverCode.cs

.github/instructions/reverse-engineering.instructions.md

@@ -19,7 +19,12 @@ applyTo: "src/Cryogenic/Overrides/**"
    - [dump/CodeGeneratorConfig.json](../../../dump/CodeGeneratorConfig.json) — manual instruction replacements and hook injection points
    - Any targeted `MemoryDataExporter` snapshots under `dump/` for the specific code path
 
-3. **Examine existing overrides** in the same file or related domain files for patterns:
+3. **Reuse existing in-repo workflows before adding automation**:
+   - Check `scripts/`, `.github/prompts/`, `.github/skills/`, and nearby docs for an existing workflow first
+   - If a suitable repo script already covers the task, run it with the right arguments instead of writing a new helper script
+   - Only add new automation when the repository does not already provide a suitable path, and state that gap explicitly
+
+4. **Examine existing overrides** in the same file or related domain files for patterns:
    - How do they access game state via `globalsOnDs`?
    - What `NearRet()` or `FarRet()` pattern matches your scenario?
    - Are there helper methods you should reuse?