GitHarness Framework Explained

• - GitHarness is a versioning framework for long-term collaboration between users and LLM-based agents, adapting to three forms of requirement change—completion, elicitation, and shifts—by preserving and reusing work artifacts.
• - The framework distinguishes between requirement states, representing user goals, and work states, representing accumulated execution context and artifacts, using a trainable Git Agent to resolve changes in requirements and select a compatible base to proceed.
• The Git Agent balances exact reuse and branch-patch corrections from historical work states to optimize requirement satisfaction.
• remembering only the most compatible historical executed requirements.
• GitHarness is recommended for scenarios like research synthesis, software engineering, and agentic search, the Git-based framework uses checkpoint-and-restoration for maintaining task fidelity and progress data

GitHarness is a pluggable, Git-style framework for long-horizon collaboration between users and LLM-based agents under changing requirements. It versions two coupled objects: the requirement state, representing the user’s current goals and constraints, and the harness work state, representing evidence, code, queries, plans, drafts, execution context, and other artifacts produced under those requirements. A trainable Git Agent resolves requirement changes, selects a semantically compatible historical state, and directs a downstream task-execution harness to restore, reuse, fork, or freshly construct work. The framework is introduced in “GitHarness: Git Init Your Harness Working Memory for Perpetual User Requirements” (Yang et al., 29 Sep 2026).

1. Concept and scope

GitHarness addresses a specific limitation of long-horizon agent collaboration: user requirements can change after substantial work has already been performed. Such changes may add information, introduce new constraints, or withdraw earlier requirements. A flat conversation history does not explicitly associate accumulated artifacts with the requirements under which they were produced. Consequently, an agent may either retain obsolete information or regenerate unrelated work.

The framework distinguishes three forms of requirement change:

1. Completion: missing information is supplied while the prior direction is retained.
2. Elicitation: a new task dimension or constraint is introduced while existing requirements remain valid.
3. Shift: an earlier requirement is revised, replaced, or withdrawn.

GitHarness is designed to avoid two corresponding failure modes:

• Stale reuse: obsolete requirements, evidence, code, or report content remain active after a change.
• Over-rewriting: unrelated work is discarded or regenerated even when only a local revision is required.

The Git analogy concerns versioned requirements and recoverable work states rather than ordinary source-code version control alone. Earlier requirement–work states can be inspected and restored; divergent revisions can form branches; a compatible historical state can serve as the base for a local update.

GitHarness is a framework layer above a downstream execution harness. The downstream system performs the domain task, while GitHarness determines the effective requirement, chooses where execution should resume, and supplies guidance for updating the selected work state.

2. Versioned requirements and work states

For task instance $i$ and interaction turn $t$, GitHarness maintains a requirement state $\boldsymbol{I}_{i,t}$ and a work state $\boldsymbol{W}_{i,t}$. The requirement state represents the current goal and constraints. The work state represents accumulated execution context and artifacts, including search results, reasoning, plans, code, SQL queries, test results, report drafts, and environment state.

A new user message $q_{i,t}$ can alter the requirement while invalidating only part of the previous work state. The framework therefore seeks to:

1. reconstruct the complete effective requirement;
2. select a compatible historical work state;
3. preserve artifacts that remain valid;
4. exclude artifacts tied to withdrawn requirements; and
5. update only the affected portion when possible.

Versions form a directed graph $\mathcal{G}_{<t}$. Each version contains requirement metadata and a recoverable checkpoint $\mathcal{B}(v)$. The version graph supports continuation from the current head, restoration of an earlier version, branching from a historical state, and preservation of immutable historical states.

The selected historical base need not be the latest version. A user may return to an earlier requirement trajectory and initiate a new branch from that point. If the selected base is the current head, the new version extends the principal path. If it is an earlier version, the resulting execution naturally forms a branch.

A historical state is compatible when its requirement and work remain sufficiently aligned with the newly resolved requirement that the work can be safely reused or locally adapted. Compatibility is semantic rather than syntactic. A compatible state may exactly satisfy the new requirement, partially satisfy it, or be unusable despite superficial similarity.

The framework does not require the Git Agent to identify an exact list of affected files or artifacts. Locality is obtained indirectly: selecting a semantically compatible base allows the downstream executor to operate on a fork containing compatible work while excluding obsolete requirements from its active context.

3. Architecture and execution workflow

GitHarness has three principal components.

Git Agent

The Git Agent is the requirement-management policy. It reasons over the new user feedback, the version graph, requirements attached to previous versions, and the compatibility of historical work. It does not perform the domain task itself. Its responsibilities are to determine the complete current requirement, select a historical base, determine whether an existing version already satisfies the requirement, and provide an update hint to the downstream executor.

Version interface

The version interface connects GitHarness to a downstream harness. It supports operations such as inspecting historical requirement metadata, accessing checkpoints, restoring a version, forking a checkpoint, committing a successful result, and exposing a lightweight work-state manifest.

This abstraction allows GitHarness to operate with different downstream harnesses without redesigning their internal memory or retraining their task executors.

Underlying harness

The underlying harness performs domain-specific execution. The paper evaluates GitHarness with TCRAG, which uses stack-style memory; StackPlanner, which uses hierarchical multi-agent planning; and OpenHands, which uses executable workspaces. GitHarness remains above these systems and controls version selection and restoration.

The execution process is divided into requirement resolution and domain execution:

$$(\boldsymbol{Q}_t,b_t,h_t) = \pi_\theta^G(q_t,\mathcal{G}_{<t}),$$

followed by execution from the selected base:

$$\boldsymbol{W}_t = F(\boldsymbol{W}_{b_t},\boldsymbol{Q}_t,h_t).$$

Here, $\boldsymbol{Q}_t$ is the resolved requirement, $t$0 is the selected historical base, and $t$1 is a non-authoritative update hint.

Only normally terminated executions are committed. If execution fails, the version graph remains unchanged, preventing a failed attempt from corrupting a previously valid checkpoint.

Git Agent actions

The Git Agent uses a short ReAct-style loop with three actions:

• Inspect: read the requirement associated with a previous version.
• Commit: declare the complete current requirement and select a base version.
• Reuse: select a version that already satisfies the requirement and terminate without further execution.

A successful decision returns a resolved requirement, a base version, a target version, and an update hint. Branching is implicit in base selection rather than represented as a separate action.

Execution modes

After requirement resolution, GitHarness selects one of three modes:

1. ExactReuse: an existing checkpoint already satisfies the requirement and is returned without further execution.
2. FreshSolve: no compatible checkpoint is available, so execution starts from an empty workspace.
3. ReuseAndPatch: a partially compatible checkpoint is forked and updated locally.

For ReuseAndPatch, the initial work state is a fork of the selected historical state. On successful termination, the resulting work state is committed as a new immutable version. On failure, it is discarded.

4. Training and reward design

GitHarness trains only the Git Agent. The downstream harness, update agent, task-execution model, tools, and domain-specific verifiers remain fixed. The paper describes this as interface-level black-box reinforcement learning, because the Git Agent is optimized through the interface exposed by the downstream harness without receiving gradients from the internal execution model.

Each Git Agent call records tokenized input, sampled output, and rollout log-probabilities. Only Git Agent output tokens receive training gradients; downstream update-agent calls contribute observations and context but are masked from the policy gradient.

The reward combines final task correctness with requirement tracking.

The outcome reward is:

$t$2

where the domain-specific verifier evaluates the final artifact against the final requirement.

The requirement-tracking reward is supplied by an LLM judge:

$t$3

The judge evaluates:

1. Requirement fidelity: whether the reconstructed requirement omits or invents information.
2. Base optimality: whether the selected historical state offers maximal compatible reuse.
3. Staleness exclusion: whether withdrawn requirements are correctly removed.

These rewards are converted into group-normalized advantages and combined:

$t$4

The resulting advantage is used in a rollout-balanced GRPO objective. Normalization by the number of Git Agent output tokens in each rollout prevents executions with longer inspection histories from dominating solely because they contain more policy tokens.

The reward balance is important. On a 200-task validation set, setting $t$5 produced a query-equivalence score of 47.0 and a task score of 70.0. Setting $t$6 improved query-equivalence to 53.0 but reduced task score to 65.0. The final method therefore uses a balanced reward rather than optimizing requirement tracking independently of downstream task completion.

5. Benchmark and empirical evaluation

GitHarness is evaluated on MTAgentBench, a verifier-preserving multi-turn benchmark covering five domains:

Domain	Benchmark	Native metric
Mathematical reasoning	GSM8K	Accuracy
Text-to-SQL	BIRD	Execution accuracy
Agentic search	BrowseComp-Plus	Answer accuracy
Software engineering	SWE-bench Verified	Resolved rate
Research synthesis	DeepResearch Bench	RACE

The benchmark uses seven-turn interactions in the main evaluation and includes annotations for requirement states, version transitions, requirement changes, task completion, and final or optional turn-level verification. The verifier-preserving design retains the original task answer or executable criterion after transformation into a multi-turn setting.

The principal baselines are:

• Native: ordinary cross-turn continuation.
• Restart: regeneration from a clean workspace.
• U-Fold: intent-aware context folding.
• GCC: Git-style context management.
• GitHarness: training-free Git Agent with versioned execution.
• GitHarness-RL: an RL-adapted Git Agent.

Absolute scores are evaluated within fixed backbone–harness settings because TCRAG, StackPlanner, and OpenHands use different tools and planning procedures.

Training-free GitHarness beats Native in all 30 backbone–harness–domain settings, matches or exceeds the strongest competing baseline in 28 of 30 settings, and achieves 27 strict wins and one tie against the strongest competitor. Under DeepSeek-V4-Flash, it matches or exceeds the strongest baseline in 14 of 15 settings (Yang et al., 29 Sep 2026).

The strongest gains frequently occur in agentic search. With DeepSeek-V4-Flash, TCRAG GitHarness improves over the strongest baseline by 14.0 points, while OpenHands GitHarness improves by 18.0 points. Examples include:

• StackPlanner with Qwen3-32B on SQL: 46.0 to 72.0.
• OpenHands with Qwen3-32B on SQL: 58.0 to 73.0.
• TCRAG with DeepSeek-V4-Flash on Search: 34.0 to 56.0.
• OpenHands with DeepSeek-V4-Flash on Search: 27.0 to 57.0.

GitHarness also reduces average token usage relative to Native by 35.8% on SQL, 54.5% on Search, 73.6% on Code, and 36.7% on Research. The paper attributes these reductions to exact reuse, historical restoration, and avoidance of unnecessary re-execution after local requirement changes.

Ablations show that both historical selection and branch execution contribute to performance. Under StackPlanner with DeepSeek-V4-Flash, removing historical version selection reduces software-engineering performance from 74.0 to 44.0 and increases token usage from 1.291 million to 4.514 million. Removing Inspect yields a 42.0 score and 4.215 million tokens. Removing Exact-State Reuse reduces performance and increases execution cost, whereas removing ReuseAndPatch harms both performance and cost. Removing FreshSolve also degrades every domain, indicating that reuse is not universally safe and that the system must be able to begin from an empty workspace when no compatible state exists.

The RL-adapted Qwen3-8B Git Agent improves under StackPlanner from 51.0 to 81.0 on mathematical reasoning and from 55.0 to 73.0 on text-to-SQL. It outperforms the Qwen3-32B configuration on four of five StackPlanner domains, although the paper notes that the remaining difference from the larger DeepSeek Git Agent may partly reflect model capacity.

In long-horizon interleaving experiments with 10, 15, 20, 25, and 30 turns, GitHarness maintains higher scores than Native, Restart, and U-Fold. At 30 turns, it exceeds the strongest baseline by 6.0 points on mathematical reasoning and 12.79 RACE points on research synthesis.

6. Applications, limitations, and future directions

GitHarness is applicable whenever user feedback can invalidate part, but not necessarily all, of accumulated agent work. Relevant settings include research synthesis, software engineering, text-to-SQL, agentic search, mathematical reasoning, image-generation workflows, and report construction.

A local update may involve removing one report section, changing an image attribute, revising a target population, adding a comparison dimension, or returning to an earlier branch of a research task. In each case, GitHarness seeks to restore a compatible state and create a branch-local update rather than indiscriminately replaying the full history or restarting from scratch.

The framework depends on several assumptions:

• work states can be checkpointed and restored;
• the downstream harness exposes a suitable version interface;
• requirements can be represented in an inspectable form;
• final or turn-level verifiers are available, at least for evaluation;
• the downstream executor can operate meaningfully on a forked work state; and
• semantic compatibility can be inferred sufficiently well by the Git Agent.

The paper identifies several limitations. Ambiguous or conflicting feedback can defeat requirement interpretation. Incorrect historical-state selection can cause stale reuse or unnecessary recomputation. Restoring a compatible state does not guarantee that the downstream executor will preserve every unaffected artifact. The framework currently lacks finer-grained dependency tracking, and MTAgentBench uses synthetic multi-turn trajectories rather than conversations collected from real users. The experiments do not establish performance in substantially longer, real-world collaborations.

The framework also does not provide a complete dependency analysis over every artifact. Its locality property is an architectural objective derived from compatible state selection and branch-local execution, not a guarantee that all unaffected files, evidence, or reasoning will remain unchanged.

Future directions include uncertainty-aware clarification, finer-grained dependency tracking, improved handling of ambiguity and conflict, and evaluation in longer real-world interactions. A plausible implication is that GitHarness could be extended with artifact-level dependency metadata, explicit confidence estimates for base selection, and human clarification when multiple historical states are similarly compatible.

GitHarness’s principal contribution is the separation of requirement resolution from domain execution, combined with versioned coupling between user intent and recoverable work. This allows an agent to treat changing requirements as structured edits to a history rather than as unstructured additions to a conversation. Its empirical results support historical-state selection, exact reuse, branch-local patching, and fallback to fresh execution as complementary mechanisms for preserving valid work while limiting unnecessary recomputation.