Research workflow: make game-adapter knowledge persistent, indexed and mandatory during save/adaptation work #91

Goal

TrainerOS is going to accumulate increasingly deep per-game knowledge: exact build identity, save structure, semantic models, progression flags, shops, entities, checksums, safe writes, validation evidence and title-specific quirks.

That knowledge must not live only in source code, scattered issue comments, temporary Codex reasoning or one-off implementation docs.

Create a durable in-repository game-adapter research/documentation system and make it part of the required Codex workflow.

The exact folder layout, filenames and schema are not prescribed by this issue. First audit the current repository and design the smallest structure that will remain useful as the number of adapted games grows.

Why

Without a persistent research record, future work will eventually:

• rediscover already-known offsets and structures;
• forget which findings were hypotheses vs independently verified facts;
• accidentally generalize one ROM revision to another;
• repeat destructive save experiments;
• lose the reasoning/evidence behind safe writers;
• scatter adapter knowledge across implementation code and unrelated docs;
• make future shared adapter work from Architecture: audit and strengthen game adapter encapsulation #89 much harder;
• make it difficult for another tool/project to understand what TrainerOS actually knows about a game.

The repository should become the durable memory of the adaptation work.

Required outcomes

The implementation must provide all of the following, while allowing Codex to choose the best concrete representation.

1. A dedicated adapter/research knowledge area

Create one obvious place in the repository where game-specific adaptation knowledge lives.

It must scale to many exact games/builds and should not be mixed randomly into general product documentation.

The structure should make it easy for a contributor or coding agent to answer:

• Is this game/build already known?
• Is it currently being researched?
• What exactly is verified?
• What is still unknown?
• Where are the save/layout details?
• Which reads/writes are proven?
• What evidence exists?
• Which code/tests implement the adapter?

Do not duplicate commercial ROMs, user save files or other copyrighted/private artifacts into Git.

2. A repository-wide adapter/research registry

Maintain a human-readable index of games/builds that are:

• planned / not started;
• currently being researched;
• partially understood;
• read-verified;
• write-verified;
• integrated;
• blocked / unsupported where relevant.

The exact status vocabulary may be designed during implementation, but it must distinguish meaningful research state and must not reduce everything to a misleading single percentage.

The registry should link directly to each game's detailed research/adaptation record.

3. Exact build identity

Every researched game must record the exact identity needed to avoid false compatibility claims, for example where applicable:

• title;
• platform;
• region;
• revision/version;
• ROM/content hash;
• content size or other identifying evidence;
• save format/size;
• runtime used during validation;
• known related revisions that are not yet proven compatible.

The existing rule from #42 remains: one verified build does not imply support for a whole generation/series.

4. Full technical research record

For each researched game/build, preserve enough information that a future developer does not need to reverse-engineer the same facts from scratch.

Record relevant findings such as:

• save layout;
• rotating slots/sections;
• offsets/structures;
• encodings/encryption;
• checksums/integrity;
• counters/keys;
• Party/character/entity records;
• inventory/currency;
• progression/story/location flags;
• shops/vendors;
• collections;
• game-specific semantic systems;
• safe mutation rules;
• invariants and round-trip requirements;
• unresolved areas.

The exact document split is up to Codex.

The goal is not to copy implementation code into Markdown, but to preserve the game knowledge independently from one C++ implementation.

5. Capability record

For every game/build, maintain an explicit record of semantic capabilities and their evidence state.

Examples may include:

PARTY_READ
STORAGE_READ
POKEDEX_READ
INVENTORY_READ
MONEY_READ
MONEY_WRITE
PARTY_HEAL_WRITE
SHOP_READ
SHOP_PURCHASE_WRITE
CURRENT_LOCATION_READ
STORY_MILESTONE_READ
...

Do not assume this exact vocabulary is final; align with #42/#89.

Read and write support must remain separate.

Unknown/unverified must remain distinguishable from unsupported/false.

6. Research log / provenance of conclusions

Codex must preserve meaningful discoveries during the research process, not reconstruct a polished story only after implementation is finished.

The record should make it possible to distinguish:

• hypothesis;
• external claim/reference;
• locally reproduced observation;
• independently verified result;
• physical-device/in-game verification;
• failed approach or disproven assumption when it matters for future work.

This can be a dated research log or another format chosen during implementation.

Do not fill it with low-value narration. Preserve findings that prevent future duplicated work or incorrect assumptions.

7. Validation evidence

A capability must not be described as proven without recording how it was proven.

Useful evidence levels may include, as applicable:

• generated/synthetic fixture;
• private real save test;
• before/after controlled experiment;
• parser/readback validation;
• writer semantic-delta validation;
• checksum/integrity validation;
• physical Flip 2 test;
• normal game loaded the resulting save and displayed the expected result;
• exact restoration/rollback check.

The system should make write verification especially clear.

8. Source/reference tracking

Preserve references that materially contributed to the adapter research, such as:

• decompilation projects;
• emulator/source references;
• reverse-engineering documentation;
• community research;
• game source symbols/functions where legitimately available;
• TrainerOS's own experiments.

Clearly distinguish externally reported information from TrainerOS-independent verification.

9. Machine-readable metadata where useful

Evaluate whether a small machine-readable per-adapter/build descriptor is useful now for:

• exact identity;
• research status;
• capabilities;
• links to implementation/tests/docs;
• future Architecture: audit and strengthen game adapter encapsulation #89 adapter-package work.

Do not prematurely freeze the final portable adapter schema from #89.

If a minimal descriptor helps prevent documentation drift, add one. If it adds no value yet, document why and keep the first implementation human-readable.

10. Codex workflow becomes mandatory

Update the repository agent/development instructions so future game/save adaptation work must use this knowledge base.

At minimum, before starting game-specific research, Codex should be required to:

• check the central registry;
• read existing records for the exact game/build;
• avoid silently repeating already-completed research;
• mark a new/in-progress research target appropriately.

During research it should:

• preserve meaningful findings and unresolved hypotheses;
• keep exact identity and capability status current;
• never promote guesses to verified facts.

Before calling a research/integration increment complete it should:

• update the game/build record;
• update validation evidence;
• update capability state;
• update the central registry;
• commit the documentation together with the implementation/research increment.

Game/save research is not complete if the durable adapter/research record is stale.

Add this requirement to AGENTS.md and any more appropriate development workflow docs.

Existing Emerald knowledge must be migrated/reconciled

Use the current Emerald work as the first real test of the system.

Relevant knowledge already exists across places such as:

• docs/EMERALD_PARTY.md
• docs/SAVE_POKEDEX.md
• docs/EMERALD_HEALING.md
• docs/EMERALD_SHOPS.md
• Emerald reference/shop data files;
• progress/save provider implementation;
• tests;
• physical validation notes.

Do not delete useful existing documents merely to create a new hierarchy.

Instead:

1. audit where Emerald knowledge currently lives;
2. create the new canonical adapter/research entry for the exact supported Emerald build;
3. consolidate or link existing evidence coherently;
4. identify missing documentation that exists only implicitly in code/tests;
5. bring the new record up to the standard future games must follow.

The result should let someone unfamiliar with the code find the Emerald adapter record and understand both what is known and why it is trusted.

Relationship to #42 and #89

• Save integration: build a per-title capability framework and validate games ROM-by-ROM #42 remains authoritative for exact-build save semantics, capabilities and safe writes.
• Architecture: audit and strengthen game adapter encapsulation #89 is auditing the broader portable game-adapter boundary.

This issue should support both without inventing a competing adapter framework.

The research/documentation format should be capable of surviving a later #89 refactor. Prefer recording game knowledge and evidence over documenting transient class names as the primary truth.

Think before choosing the structure

Before implementing the repository layout, Codex should explicitly audit:

• existing Emerald docs;
• current docs/, data/, src/integrations/ and test organization;
• Save integration: build a per-title capability framework and validate games ROM-by-ROM #42 and Architecture: audit and strengthen game adapter encapsulation #89;
• what information would be useful to another future adapter author;
• what should be human-readable vs machine-readable;
• how to avoid duplicated sources of truth.

Then choose and document the recommended structure.

Do not mechanically implement a preselected folder tree just because one was suggested in discussion.

Acceptance

• One clear game-adapter research/documentation area exists in the repository.
• A central registry shows completed, in-progress and future/blocked adaptation work.
• Records are keyed to exact game/build identity rather than loose series assumptions.
• The current supported Emerald build has a complete first-class record assembled from existing docs/code/tests/evidence.
• The record distinguishes hypotheses, external sources and independently verified facts.
• Semantic read/write capabilities and their validation state are visible.
• Safe-write evidence is traceable to actual validation.
• Existing useful documentation is linked/migrated without needless duplication or deletion.
• AGENTS.md requires future Codex save/game research to maintain the knowledge base as part of Definition of Done.
• A future new game can be started by following the documented process without inventing a new research format.
• The solution remains compatible with the architectural direction of Architecture: audit and strengthen game adapter encapsulation #89 and does not prematurely lock a final plugin/adapter ABI.