Porting Test Drive II from SNES to PC, Part 5: Making generated evidence intentional

The next cleanup problem in this repo was not glamorous.

It was git status.

By March 19, asmdump already had enough archaeology tooling to produce:

• probe traces
• frame dumps
• sequence manifests
• design packs
• renderer fixtures
• gameplay sweep outputs
• late-intro diagnostics

That is good progress, but it creates a new failure mode. If a reverse-engineering repo writes hundreds of files per experiment, then "generated" stops being a useful category.

Some generated files are throwaway scratch.
Some are promoted proof artifacts that the docs and checkpoints depend on.
Some are local intermediate runs that matter for a day and then should disappear.

If the repo does not make those categories obvious, progress gets harder to trust.

The real problem was ambiguity

The current port plan now treats maintainability as a first-class execution track, and that is the right call.

The problem was not that the repo lacked cleanup scripts. It was that the working surfaces had become ambiguous:

• tools/out contained both real evidence and disposable experiments
• emulator outputs could pile up under mutable local folders
• new local runs could flood the worktree even when nothing meaningful had changed

That kind of ambiguity is dangerous in a project like this.

This repo is not just building a game. It is building an argument about the game:

• which frame behavior is understood
• which artifact is authoritative
• which gap is still open
• which experiment is only scratch

If the worktree cannot communicate that distinction, the archaeology gets noisy fast.

Blanket cleanup would have been the wrong fix

There is a tempting cleanup answer for repos like this:

"Just wipe tools/out."

That would have been a mistake here.

tools/out is not just cache. It also contains promoted evidence:

• sequence manifests used by the SDL runtime
• proof bundles referenced by docs
• renderer fixtures
• bridge-visible intro artifacts
• OAM delta reports that now act as the source of truth for specific late-intro frames

So the correct question was not "how do we delete more output?"

The correct question was:

"How do we reduce daily worktree noise without teaching the repo to delete its own evidence?"

That distinction matters.

During this checkpoint, the repo hygiene work actually exposed the edge directly: naming conventions like tmp_* and test_* were not enough on their own, because some files with those names were already tracked on purpose. That is exactly why cleanup policy has to be explicit instead of aspirational.

What changed in the checkpoint

The repo-hygiene commit 8b2e3fc on 2026-03-19 makes that boundary much clearer.

The changes are simple, but the model behind them is the important part:

1. tools/out is now ignored by default

New local runs under tools/out no longer flood git status.

That sounds minor, but it changes the daily workflow a lot. Reverse-engineering and validation tools are now free to emit local working output without pretending every run is a candidate for promotion.

Tracked files already under tools/out still behave normally.

That is the key point: the repo did not stop supporting promoted generated artifacts. It stopped pretending that every new generated file should immediately appear as meaningful worktree noise.

2. Promotion is now explicit

If a new tools/out artifact really should become part of the repo's evidence set, that is now an intentional action with git add -f.

That is healthier than passive promotion.

For a project like this, evidence should be promoted because the team decided it is authoritative, not because it happened to show up in the worktree after one more experiment.

3. Cleanup stayed conservative

The generated-artifact cleaner now handles obvious scratch output such as untracked:

• tmp*
• test_*
• old smoke/makecheck/designtest surfaces

But it now also skips any tracked path.

That guard matters more than the extra patterns do.

It means the cleaner is allowed to reclaim disposable clutter without becoming a silent destroyer of promoted proof artifacts.

That is the right tradeoff for this repo. Cleanup exists to improve trust in the evidence surface, not to erase it.

Why this matters for the actual port work

This is not housekeeping for its own sake.

The active technical blockers are still the same hard ones:

• close the 958..977 bootstrap gap
• fix the 986+ final-screen composition gap
• continue replacing sampled attract segments with native callback/state playback
• keep tightening bank and callback contracts

Those tasks all depend on being able to answer a boring but critical question:

"Which artifact should I trust right now?"

The repo is in a better position to answer that after this checkpoint.

Now the working model is clearer:

• tracked generated artifacts are deliberate evidence
• untracked generated runs are just local working state
• cleanup removes scratch, not proof

That makes later archaeology cheaper, because less time gets wasted re-evaluating whether a file is:

• current
• stale
• authoritative
• disposable

That is especially important now that the project has multiple simultaneous surfaces:

• ROM archaeology
• C/SDL runtime playback
• bridge extraction
• renderer validation
• gameplay-frame tracing

Without hygiene, those surfaces blur together. With hygiene, they reinforce each other.

The next cleanup target is portability

This checkpoint does not finish the cleanup track.

It just closes one important slice: generated evidence is now more intentional.

The next portability-side work in the roadmap is still clear:

• remove hard-coded personal Mesen paths from promoted scripts and Makefiles
• keep validation output isolated and reproducible
• continue the intro-side archaeology against a cleaner workflow

That is the right sequence.

The repo first needed to stop shouting about every local generated file. Now it can move on to making the promoted tooling less machine-specific.

Why this was worth a full checkpoint

Projects like this often under-value cleanup because it does not directly render a better frame.

That is short-term thinking.

When a repo's output surfaces are unclear, every later win gets harder to trust. When promotion is explicit and cleanup is conservative, the repo becomes much better at distinguishing:

• evidence
• scratch
• progress
• noise

That distinction is part of the product.

For a port project built on reverse engineering, the goal is not only to make frames look right. The goal is to make the reasoning behind those frames legible, reproducible, and maintainable.

This checkpoint moves the repo in that direction.