Subject Boundaries

Screeps Lab tests subject codebases without taking ownership of them.

External Repositories

The primary Screeps colony repository should remain outside Screeps Lab. A common local layout is:

~/projects/
├── screeps/
└── screeps-lab/

A lab configuration may refer to ../screeps, but that target is not committed inside this repository.

Local Paths

Local path subjects are useful for day-to-day development. They are simple, fast, and transparent, but require the developer to manage the checkout.

Ignored Local Workspaces

subjects/local/ is ignored so a developer can place temporary subject workspaces inside the lab checkout without accidentally committing them.

Temporary Clones

Overlord may eventually create temporary subject clones for reproducible runs. Those clones should be ignored and cleaned up or archived deliberately.

Mounts

Container or VM-based workflows may mount a subject repository into the lab runtime. The mounted source remains externally owned.

Future Git Adapters

Git-based subject adapters may eventually resolve branches, tags, or commits. They should capture the exact revision used for each run.

Reproducibility

Reports should eventually record subject path, source type, commit hash when available, dirty-state information when practical, adapter version, and scenario configuration.

Assertion Manifests

Subject-owned assertion manifests live in the external subject checkout and are referenced by subject-relative paths. Screeps Lab records which manifest was used and evaluates only the declarative, generic contract; colony-specific meaning remains owned by the subject repository.

Why Nested Repositories and Submodules Are Deferred

Nested repositories and submodules add workflow complexity and increase the risk of confusing lab code with subject code. They can be reconsidered later through a documented architectural decision if reproducibility or distribution needs justify them.