The Project Before the Experiment: Git, Baselines, and Ownership
OpenResearch begins its reproducibility story before it creates an experiment. This chapter focuses on the local project—the record that connects a repository to a baseline branch, a run command, paper context, and later results—and explains what that record owns that a raw checkout does not. By the end, the important distinction should be clear: a repository contains source, while an OpenResearch project gives that source a durable research identity from which comparable experiments can begin.
That distinction is easy to miss because the project may point at an ordinary Git repository. The files and history are still there. What changes is the surrounding contract. OpenResearch needs to know which local repository is being treated as a project, which branch is the starting point, where the research state is recorded, and how a future run is supposed to be invoked. Without those facts, an agent can edit code, but the system cannot reliably say which work belongs to which research effort.
A repository becomes a research container
The local project record holds a name and slug for human and machine identity, a repository path, a baseline branch, and an optional fixed run command. It can also retain a paper identifier and GitHub publication metadata. Those fields do not make the project a second copy of the code. They bind the code to the context in which it will be explored.
The repository path is the ownership anchor. The baseline branch is the fork point from which the experiment tree can grow. The run command is the operational agreement about how a branch will be evaluated. Paper context can explain where the project began, while publication metadata can make selected branches visible to collaborators. Each relationship answers a different question, and keeping them distinct prevents a common category error: treating a link to a paper or a remote repository as if it were the record of an experiment.
The fixed command deserves special attention. An experiment is not only a diff; it is a change evaluated by a particular execution recipe. If one variant is launched with one command and another with a different, hidden command, their outputs may not be comparable even when the code change is obvious. OpenResearch's broader experiment workflow therefore treats the command as something configured once and inherited by children, while the research question changes on the branch. The project gives that convention a place to live before the first child is made.
This is also why Git matters beyond version control. OpenResearch uses local Git history as the experiment-history database. A project may optionally publish branches to GitHub, but publication is not required to run compute. The local repository remains sufficient to identify the branch and commit that define the experiment. Collaboration can add a visibility path; it should not be confused with the execution path.
The project therefore sits between two kinds of state. The repository holds source state: files, branches, and commits. The local store holds research state: project records, experiment records, run records, chat sessions, and related local metadata. The dashboard can display both, but their responsibilities differ. A changed file is not automatically a hypothesis, and a conversation about a hypothesis is not automatically a measured result.
A useful way to read the project record is as a set of ownership questions. Which checkout does this research effort mean? The repository path answers that. Where do new experiments begin? The baseline branch answers that. How will a branch be evaluated? The run command answers that. What earlier work gives the question context? A paper identifier can answer that, without pretending that the paper is the result of the current experiment. Which work should collaborators be able to see? Publication metadata can answer that, without making a public remote repository the place where the run is defined.
Those questions matter because the agent's working directory is not a durable research identity. A session may be recreated, a worktree may be removed, and a terminal may close while the repository and local store remain. The project record survives those changes and gives later operations a stable reference. It also lets the dashboard and command-line plane resolve the same project, experiment, and run relationships instead of forcing a researcher to reconstruct them from shell history.
The ordering of those relationships is intentional. First, a repository is checked and registered. Then a baseline can be created as an experiment node. Only after that does a child have a meaningful parent. If the system created a baseline automatically every time a folder was imported, registration itself would look like a scientific conclusion. If it allowed a child branch without a known fork point, later differences would be hard to interpret. The project is the quiet stage on which those decisions become explicit.
The fixed run command also has a social meaning, not only a technical one. It tells collaborators and agents what the project considers a comparable evaluation. A researcher can change source code on a child branch, but a hidden change to the invocation would make the branch owe a different question. By recording the command at project or experiment level and inheriting it into the tree, OpenResearch makes the burden visible: if the evaluation recipe must change, that change should be treated as part of the research decision rather than smuggled in through a launcher's ad hoc arguments.
Paper context and GitHub visibility are deliberately looser relationships. The paper can establish motivation, terminology, or a starting implementation. A published branch can support collaboration or review. But neither relationship owns the local run. This separation is valuable when a researcher wants to preserve a public upstream while testing private changes, or when a paper project needs a local source snapshot before any result exists. The project can hold the relationship without allowing it to overwrite the experiment's own provenance.
The relationships in this model are deliberately uneven. Every project has a repository anchor and can contain experiments. An experiment can produce runs. Paper context and publication are optional because they enrich interpretation or collaboration but do not define whether a branch ran. The diagram is not a database inventory; it is a reminder that source, research identity, execution, and communication are different responsibilities.
From import to baseline
OpenResearch can adopt an existing repository, clone a public repository, or initialize a repository for a blank or paper-oriented project. In each case, the intended flow is to establish a valid local repository first and then register it as a project. The product checks repository state rather than assuming that any folder with files is ready. It also has safeguards around initial imports, including treatment of oversized files, because a research container cannot be reliable if its initial snapshot silently exceeds the storage assumptions on which later operations depend.
Adoption and cloning express different forms of ownership. When an existing checkout is adopted, its repository is already the source of truth and OpenResearch records the project around it. When a public source is cloned for a new project, the clone becomes the local working repository from which experiments are created. When a blank or paper project is initialized, OpenResearch can create the repository that will hold the new work. These routes converge on the same requirement: the project must resolve to a usable Git repository with a current branch that can serve as a fork point.
Registration does not immediately create a baseline experiment. The experiment tree starts empty. The first experiment created without a parent becomes the root baseline, while later no-parent creation normally attaches to the existing project root unless a new baseline is explicitly requested. This lazy step preserves an important conceptual boundary. A user can register a repository, set its run command, inspect its condition, or prepare a paper context without claiming that the starting code has already answered a research question.
A baseline is a control, not a conclusion. It gives later variants something to be measured against, but it is not evidence that the starting design is good. That is why the baseline is represented as a node in the experiment tree only when the researcher creates it, and why later results should remain attached to the branch and commit that produced them. The baseline can be disappointing, incomplete, or merely convenient. Its value is that it makes the comparison explicit.
The distinction also protects the mutable project surface. OpenResearch's current experiment design gives each modern root its own experiment branch, while the project's base branch remains available for mutable materials such as a README, notebooks, or a publication surface. Experiment branches hold the code associated with recorded hypotheses. This separation reduces the chance that an ordinary documentation edit will silently become part of a measured node—or that a historical node will be rewritten to accommodate a later explanation.
There are practical limits to the container. An arbitrary repository may have invalid Git state, a detached head, nested repositories, very large files, or other conditions that make import unsafe or ambiguous. The implementation includes validation and cleanup behavior for these cases, but repository tests are not the same as a guarantee that every project shape will import without intervention. The right conclusion is narrower: OpenResearch makes repository readiness an explicit precondition instead of hiding it behind an optimistic folder scan.
This precondition is easy to underestimate when an import looks like a one-time administrative action. The initial repository state determines the branch from which the baseline is later created. If the import silently drops a file, adopts the wrong enclosing repository, or leaves the project without a usable current branch, every later experiment inherits the ambiguity. Validation at the beginning is therefore not bureaucratic friction; it is a way to keep an unexamined storage problem from appearing later as a mysterious scientific result.
The same logic applies to large or awkward project contents. Research repositories often sit beside generated data, checkpoints, notebooks, and intermediate artifacts. Not all of those belong in the source snapshot that defines a code experiment. OpenResearch's import behavior includes safeguards for oversized files and repository structure rather than pretending that every byte in a folder has the same status. That is a boundary to understand, not a promise that the tool has solved data management. A researcher still needs to know which data a run expects and whether that data is available at execution time.
Nor does a project record every condition that will matter to a result. It can identify the repository and command, but it does not by itself prove that dependencies, datasets, random seeds, or hardware behavior will be identical across machines. Those limitations do not make the project record unnecessary. They show why ownership should be layered: the project establishes source and research identity; later mechanisms must establish experiment lineage, source snapshots, runtime evidence, and scientific interpretation.
Why ownership must precede comparison
Suppose an agent receives a prompt to improve a training script. Without a project boundary, it may edit whatever checkout happens to be current, run a command whose arguments are not recorded, and leave its output in a terminal that disappears with the session. A human may still recover the files, but the research question has no stable owner. It becomes difficult to tell whether a later branch is a continuation, a reset, or an unrelated attempt.
With a project in place, the same prompt has a more constrained route. The repository and baseline are known. The experiment tree can give the change a parent. The run command supplies a common execution contract. The local store can associate a run with the project and experiment. Later chapters will add private agent worktrees and immutable source snapshots, but those mechanisms depend on the project record established here. They are not substitutes for it.
This ordering also clarifies what paper integration and GitHub publication can and cannot do. A paper identifier can preserve the work's starting context and support literature retrieval. A GitHub branch can make code visible to collaborators. Neither tells OpenResearch which metric to trust, which branch was the intended control, or whether a run used the effective configuration that the researcher thinks it used. Context and visibility are valuable, but comparison still depends on project ownership, branch lineage, and the run contract.
The project is therefore a small but consequential piece of infrastructure. It does not perform the scientific reasoning, and it does not turn a repository into a validated result. It gives the reasoning a place to attach: a named source, a baseline, an execution convention, and a local record of what follows. Once that foundation exists, the next problem is to express changes as a structured family of hypotheses rather than a pile of branches. That is the work of the experiment tree.