Harness Handbook: Making Evolving Agent Harnesses Readable,Navigable, and Editable

# Harness Handbook: Making Evolving Agent Harnesses Readable, Navigable, and Editable
Source: [https://arxiv.org/html/2607.13285](https://arxiv.org/html/2607.13285)
1\]Tencent HY LLM Frontier 2\]Indiana University 3\]University of Maryland, College Park 4\]University of Georgia 5\]National University of Singapore\\contribution⋆Work done at an internship at Tencent Seattle†Lead Project Collaborator\.\\headercontentProject link:[https://ruhan\-wang\.github\.io/Harness\-Handbook/](https://ruhan-wang.github.io/Harness-Handbook/)

Yucheng Shi†Zongxia LiZhongzhi LiYue YuJunyao YangKishan PanagantiHaitao MiDongruo ZhouLeoweiliang\[\[\[\[\[[ruhwang@iu\.edu, yuchengshi@tencent\.com](https://arxiv.org/html/2607.13285v1/mailto:[email protected],%[email protected])

\(July 14, 2026\)

###### Abstract

The capability of a modern AI agent depends not only on its foundation model but also on its harness, which constructs prompts, manages state, invokes tools, and coordinates execution\. As models, APIs, execution environments, and application requirements change, the harness must be continually modified to add capabilities or adapt existing behaviors\. Before a human developer or coding agent can make such a change, they must identify all code locations that implement the target behavior\. This is difficult because production harnesses are often large, tightly coupled, and behaviorally distributed across files, functions, execution stages, and state transitions, whereas modification requests describe what the system should do and repositories are organized by files, functions, and modules\. Existing approaches to code search, repository indexing, and long\-context processing make code easier to inspect, but they still leave developers and coding agents to recover this mapping themselves\. Behavior localization is therefore a central bottleneck in harness evolution\. We introduce theHarness Handbook, a behavior\-centric representation synthesized automatically from a harness codebase through static program analysis and LLM\-assisted behavioral structuring, which organizes implementation knowledge around system behaviors and links each behavior to the corresponding source code\. We also introduceBehavior\-Guided Progressive Disclosure \(BGPD\), which guides coding agents from high\-level behavior descriptions to relevant implementation details and verifies candidate locations against the current source\. We evaluate Harness Handbook on diverse modification requests from two open\-source agent harnesses\. Handbook\-Assisted planning improves behavior localization and edit\-plan quality while using fewer planner tokens\. The largest gains appear for changes involving scattered implementation sites, rarely executed code paths, and cross\-module interactions\. These findings indicate that evolving complex agentic systems depends not only on generating edits, but also on determining where those edits should be made\.

## 1Introduction

Recent advances in large language models \(LLMs\) have accelerated the development of agentic systems\[wang2024survey,yao2022react,huang2025towards\]\. These systems extend model capabilities by interacting with tools, APIs, and complex execution environments\[schick2023toolformer,zhou2024webarena,xie2024osworld,yang2024swe\]\. Such interactions are not governed by the foundation model alone\. They are coordinated by the harness, which constructs prompts, manages state, invokes tools, and controls execution across system components\. The harness therefore determines how model capabilities are translated into system behavior\. As models, APIs, execution environments, and application requirements evolve, the harness must be adapted accordingly\. Harness evolution has consequently become a recurring engineering challenge in modern agent development\[lin2026agentic,lopopolo2026harness,zhong2026ai\]\.

In practice, harness evolution requires changes that add capabilities, adapt existing behaviors, or refine execution workflows\[wang2025federated,wang2026fera\]\. Traditionally, human developers make these changes by reading the repository, tracing the relevant behavior, and editing its implementation\. Coding agents are increasingly expected to perform the same work from natural\-language requests\[yang2024swe,wang2025openhands,zhong2026ai,zhu2026semaclaw\]\. However, a modification request describes what behavior should change, but it does not identify where that behavior is implemented\. Whether the modification is performed by a human developer or a coding agent, the first step is therefore to locate all relevant implementation sites\.

Finding every relevant implementation site is difficult in production\-scale harnesses\[ning2026code\]\. A large harness may span hundreds of functions across many files, with execution logic distributed across stages and connected through shared state\. As a result, a single behavior may depend on several nonadjacent implementation sites\.

We refer to identifying all implementation sites associated with a behavioral request asbehavior localization\. In a large and structurally complex harness repository, this task is costly for both human developers and coding agents\. Human developers must invest substantial time and effort in building a mental model of the system and tracing behavior across files and execution stages\. Coding agents face an additional constraint from limited input context, which prevents them from examining all relevant code at once\. They must therefore explore the repository iteratively and may still overlook scattered or rarely executed paths\[zhang2026swe,tamoyan2026sherloc\]\.

Existing approaches to repository understanding make codebases easier to explore\. Repository maps, code search, code summarization, repository memory, and long\-context editing help coding agents find, inspect, and retain relevant code\[zhang2026swe,bhola2026code,wang2025improving,tamoyan2026sherloc,cao2026coding\]\. However, these approaches organize information around files, functions, and modules, whereas a harness modification request describes a desired behavior\. They may identify individual pieces of relevant code, but they do not show how those pieces work together to produce the behavior or whether every affected location has been found\. The coding agent must still connect these pieces and infer how the requested behavior maps to the underlying implementation\. This missing connection is the gap we address\.

We address this gap withHarness Handbook, an operational behavior representation that connects system behavior to source code\. Instead of organizing implementation knowledge by files and functions, the Handbook organizes it by what the harness does and links each behavior to the code that implements it\. Developers and coding agents can therefore identify the relevant behavior first and then navigate directly to the corresponding code\. We construct Harness Handbook instances automatically using static program analysis and LLM\-assisted behavioral structuring\. To evaluate whether the Handbook improves harness modification, we use realistic requests from two open\-source agent harnesses and compare Baseline and Handbook\-Assisted planning on the same tasks\. Handbook\-Assisted planning improves behavior localization and edit\-plan quality while using fewer planner tokens\. These results show that making the connection between behavior and implementation explicit can make harness evolution more accurate and efficient\. Our contributions are as follows:

- •We definebehavior localizationas finding all code locations that implement the behavior described in a modification request\. This step is necessary before a complete edit can be planned\.
- •We introduceHarness Handbook, which organizes implementation knowledge by what the harness does and links each behavior directly to its source code\. We also develop an automated framework that builds Handbook instances from existing codebases using static program analysis and LLM\-assisted behavioral structuring\.
- •We introduceBehavior\-Guided Progressive Disclosure \(BGPD\), a workflow that guides coding agents from high\-level behavior descriptions to relevant implementation details in stages\.
- •We evaluateHarness Handbookon diverse modification requests from two open\-source harnesses\. We compare Handbook\-Assisted BGPD planning with planning without Handbook access on the same tasks\. Handbook assistance improves behavior localization and edit\-plan quality while using fewer planner tokens\.

## 2Related Work

Our work is closely related to three research directions: agent harnesses, harness evolution, and repository representations for coding agents\. We briefly review each direction and discuss how Harness Handbook differs from existing approaches by introducing an explicit operational behavior representation for behavior localization\.

### 2\.1Agent Harness

Recent work has increasingly recognized the agent harness as a first\-class software abstraction that extends foundation models into deployable agentic systems\. Rather than treating prompting, tool use, memory, and execution logic as implementation details,*Code as Agent Harness*formalizes the harness as an executable and stateful software layer supporting reasoning, acting, feedback, and coordination\[ning2026code\]\. Complementary surveys and engineering efforts further characterize the harness as the runtime infrastructure responsible for prompt construction, state management, tool invocation, control flow, and interactions with external environments\[meng2026agent,he2026harness\]\. This abstraction has been widely adopted by modern agent frameworks and production systems\. Frameworks such as AutoGen and OpenHands expose modular runtime components for agent orchestration, tool execution, environment interaction, and multi\-agent collaboration\[wu2023autogen,wang2025openhands\]\. Industrial systems such as Claude Code and Codex similarly emphasize harness design as a key factor in building reliable long\-running coding agents\[rajasekaran2026harness,openai2025codex\]\. While these works establish the importance of agent harnesses, they primarily focus on harness construction and system design rather than understanding and evolving existing production\-scale harnesses\.

### 2\.2Harness Evolution

As coding agents become increasingly capable, software engineering efforts are gradually shifting from manually implementing functionality to automatically evolving the underlying harness\[yang2024swe,wang2025openhands\]\. Recent work has begun to investigate harness engineering, adaptive harness optimization, and automated harness repair\[zhong2026ai,zhu2026semaclaw,lin2026agentic,chen2026harnessx,chen2026harnessforge,chen2026failed\]\. These approaches improve the capability and reliability of agent systems by constructing, adapting, or repairing harness implementations\. Our work addresses a complementary problem\. Rather than directly modifying harness implementations, we study the prerequisite challenge of harness evolution: behavior localization\. Harness Handbook enables developers and coding agents to identify where behavioral changes should be made before reasoning about how to modify the underlying implementation\.

### 2\.3Behavior Representations

Recent work has proposed various representations to improve repository understanding for coding agents, including structural repository representations, repository indexing, repository memory, and natural\-language artifacts\[cherny2026repository,bhola2026code,wang2025improving,pan2026natural\]\. These representations improve repository navigation, code retrieval, and editing by organizing implementation knowledge into more accessible forms\. However, existing representations remain fundamentally implementation\-centric, organizing information around source code, repository structure, or execution infrastructure\. They do not explicitly capture how system behaviors emerge across distributed execution stages, functional modules, and shared states\. In contrast, Harness Handbook introduces an operational behavior representation that explicitly bridges behavioral requirements and their underlying implementation, enabling behavior localization before repository exploration\.

## 3Harness Handbook

Harness Handbook has three parts for understanding and modifying an agent harness\. The*representation*organizes source around runtime behavior \(Section[3\.1](https://arxiv.org/html/2607.13285#S3.SS1)\)\. The*construction*pipeline builds this representation from a repository \(Section[3\.2](https://arxiv.org/html/2607.13285#S3.SS2)\)\. The*modification*workflow uses the handbook to guide code changes and automatically resynchronizes it after every non\-empty repository diff \(Section[3\.3](https://arxiv.org/html/2607.13285#S3.SS3)\)\.

### 3\.1Harness Handbook Representation

Source repositories show where code is stored, but they do not directly show how a runtime behavior unfolds\. One behavior may cross several files, execution stages, and shared states\. Harness Handbook reorganizes this information around behavior while preserving links to the source\. As Figure[1](https://arxiv.org/html/2607.13285#S3.F1)shows, it contains an L1–L3 document tree𝒟\\mathcal\{D\}and a complementary state\-register view𝒵\\mathcal\{Z\}\.

![Refer to caption](https://arxiv.org/html/2607.13285v1/x1.png)Figure 1:Overview of the Harness Handbook representation\. Its three\-level hierarchy progresses from a system\-level overview to stage\-level component overviews and source\-backed unit details\. The navigation pane provides component and state indexes for direct access and cross\-stage tracing\.A reader normally starts atL1 \(system overview\), which summarizes the architecture, execution model, major stages, and global data flow\. The reader then moves toL2 \(component overview\)for the responsibilities, inputs, outputs, dependencies, and local state of a selected stage\. Finally,L3 \(unit deep dive\)links that stage to source\-grounded implementation entries\. The complementary view𝒵\\mathcal\{Z\}records state relationships that cross stage boundaries\.

Two rules keep the representation useful\.*Progressive disclosure*means that readers move from L1 to L3 only when a task requires more detail\.*Behavior–implementation alignment*means that every active L3 locator must still resolve to the current repository\. If a locator cannot be revalidated, its entry is frozen and excluded from localization until it is refreshed\. The repository therefore remains the authority for implementation details\.

### 3\.2Harness Handbook Construction

Construction builds a handbook from a repositoryℛ\\mathcal\{R\}\. The leaf modeg∈\{function,file\}g\\in\\\{\\mathrm\{function\},\\mathrm\{file\}\\\}, which remains fixed for the lifetime of the handbook, determines the granularity of L3 entries: infunction\-as\-leafmode each L3 entry covers a whole function or one or more contiguous regions, whereas infile\-as\-leafmode each L3 entry represents a file\.

The two modes differ in how the stage skeleton is obtained\.function\-as\-leafstarts from a seed skeleton𝒮0\\mathcal\{S\}\_\{0\}containing the stage and state\-register definitions; we use it when a trustworthy seed skeleton that faithfully reflects the harness’s execution stages is available and function\-level L3 entries fit the available budget\.file\-as\-leafinstead infers the stage skeleton rather than starting from a seed; we use it when no such seed is available or when function\-level organization would exceed the available budget\. Both modes produce the representation described in Section[3\.1](https://arxiv.org/html/2607.13285#S3.SS1), and Algorithm[2](https://arxiv.org/html/2607.13285#alg2)defines the two branches\.

Onceggis chosen, construction proceeds in three phases, illustrated for the function\-as\-leaf branch in Figure[2](https://arxiv.org/html/2607.13285#S3.F2)\.

![Refer to caption](https://arxiv.org/html/2607.13285v1/x2.png)Figure 2:Construction pipeline for Harness Handbook\. Static analysis extracts source\-linked facts, behavioral organization maps source units to execution stages, and hierarchical synthesis builds the L1–L3 handbook\.1. Phase I\.Static Fact Extraction\.Language\-specific adapters parse the repository and extract functions, named external boundaries, source locations, signatures, and call edges\. The program graph𝒢\\mathcal\{G\}keeps only calls that resolve to an internal function or a named boundary\. Unresolved calls are logged rather than assigned guessed targets\. This phase is deterministic and makes no LLM calls\.
2. Phase II\.Behavioral Organization\.The pipeline organizes source units into the execution\-stage skeleton𝒮\\mathcal\{S\}according to the selected leaf mode\. - •*Function\-as\-leaf\.*The pipeline uses source and call\-graph context to propose function\-to\-stage assignments, which are refined through iterative review\. A function can be assigned to one or more execution stages, either as a whole or as contiguous regions when it serves multiple behavioral roles\. Accepted assignments and revisions update the stage skeleton𝒮\\mathcal\{S\}\. - •*File\-as\-leaf\.*The pipeline summarizes the scanned files as cards and combines them with the program graph to infer the stage skeleton𝒮\\mathcal\{S\}\. It then organizes the files by execution stage\. An optional proposal\-and\-review process iteratively refines this structure, while uncovered files and unresolved organizational issues remain explicitly recorded in𝒴\\mathcal\{Y\}\. Appendix[A](https://arxiv.org/html/2607.13285#A1)provides the full organization procedures and validation checks for both modes\.
3. Phase III\.Hierarchical Synthesis and Packaging\.This phase converts the stage skeleton and source organization from Phase II into the L1–L3 document tree and cross\-stage state\-register view\. Each L3 entry is linked to a statically identified source location and validated against the current repository\. This keeps the handbook traceable to the source\. Finally, the pipeline renders𝒱\\mathcal\{V\}and packages the structured data needed for source localization and future resynchronization\.

### 3\.3Handbook\-Guided Modification and Resynchronization

After construction, the handbook serves as a behavior\-oriented guide for modifying the repository\. Given a requestqq, the workflow uses the handbookℋ\\mathcal\{H\}together with its corresponding repositoryℛ\\mathcal\{R\}\. The leaf modeggremains unchanged throughout the process\.

The workflow consists of four steps\. First,*Behavior\-Guided Progressive Disclosure \(BGPD\)*localizes the requested behavior through coarse\-to\-fine handbook navigation\. It progressively reveals relevant information, follows it to candidate source locations, and verifies those locations against the current repository\. This process produces a set of source\-grounded evidence for planning\. Second, the planner converts the evidence into an edit plan𝒫\\mathcal\{P\}and action declarationsΓ\\Gamma\. Third, a separate executor applies𝒫\\mathcal\{P\}to the repository\. Finally, any non\-empty diff triggers handbook resynchronization\. Algorithm[1](https://arxiv.org/html/2607.13285#alg1)summarizes the complete workflow\.

Algorithm 1Handbook\-Guided Modification with Automatic Resynchronization1:request

qq, handbook package

ℋ\\mathcal\{H\}, corresponding repository snapshot

ℛ\\mathcal\{R\}
2:plan

𝒫\\mathcal\{P\}and declarations

Γ\\Gamma; updated repository

ℛ′\\mathcal\{R\}^\{\\prime\}, diff

Δ\\Delta, and handbook package

ℋ′\\mathcal\{H\}^\{\\prime\}
3:

g←LeafMode​\(ℋ\)g\\leftarrow\\mathrm\{LeafMode\}\(\\mathcal\{H\}\)
4:

ℰ^q←BGPD​\(q,ℋ,ℛ\)\\widehat\{\\mathcal\{E\}\}\_\{q\}\\leftarrow\\mathrm\{BGPD\}\(q,\\mathcal\{H\},\\mathcal\{R\}\)
5:

\(𝒫,Γ\)←Plan​\(q,ℰ^q\)\(\\mathcal\{P\},\\Gamma\)\\leftarrow\\mathrm\{Plan\}\(q,\\widehat\{\\mathcal\{E\}\}\_\{q\}\)
6:

ℛ′←Execute​\(ℛ,𝒫\)\\mathcal\{R\}^\{\\prime\}\\leftarrow\\mathrm\{Execute\}\(\\mathcal\{R\},\\mathcal\{P\}\)
7:

Δ←Diff​\(ℛ,ℛ′\)\\Delta\\leftarrow\\mathrm\{Diff\}\(\\mathcal\{R\},\\mathcal\{R\}^\{\\prime\}\)
8:if

Δ≠∅\\Delta\\neq\\emptysetthen

9:

ℋ′←Resyncg​\(ℋ,ℛ,ℛ′,Δ,Γ\)\\mathcal\{H\}^\{\\prime\}\\leftarrow\\mathrm\{Resync\}\_\{g\}\(\\mathcal\{H\},\\mathcal\{R\},\\mathcal\{R\}^\{\\prime\},\\Delta,\\Gamma\)
10:else

11:

ℋ′←ℋ\\mathcal\{H\}^\{\\prime\}\\leftarrow\\mathcal\{H\}
12:endif

13:return

\(𝒫,Γ,ℛ′,Δ,ℋ′\)\(\\mathcal\{P\},\\Gamma,\\mathcal\{R\}^\{\\prime\},\\Delta,\\mathcal\{H\}^\{\\prime\}\)

#### 3\.3\.1Behavior Localization with BGPD

Rather than treating all source locations equally, BGPD uses the handbook to identify candidate sites from coarse to fine\. It then verifies these sites against the current repository\.

Localization begins at the level of execution stages\. BGPD first uses L1 and L2 of𝒟\\mathcal\{D\}to identify the stages directly relevant to the request\. It then follows𝒵\\mathcal\{Z\}to include stages coupled through shared state\. This step captures mutually dependent stages even when they are structurally distant\. Within these stages, BGPD selects the most relevant L3 entries and retrieves their source locators\.

BGPD then expands the candidate set along call relations\. Infunction\-as\-leafmode, it uses the function\-call graph; infile\-as\-leafmode, it uses the induced file\-call graph\. External boundary nodes provide context but are never returned as edit sites\.

Up to this point, BGPD operates on the handbook\. It then opens the current repositoryℛ\\mathcal\{R\}, resolves the candidate locators, and retains only the sites that remain relevant toqq\. This yields the verified evidenceℰ^q\\widehat\{\\mathcal\{E\}\}\_\{q\}\. Each record contains a file path, an optional function or region anchor, and a current source excerpt\. The handbook thus guides the search, while the repository remains the basis for the edit plan\.

#### 3\.3\.2Edit Planning and Execution

The planner convertsℰ^q\\widehat\{\\mathcal\{E\}\}\_\{q\}into an edit plan𝒫\\mathcal\{P\}\. Each edit block specifies where the change should be made, which source evidence supports it, and what should change\. The block records a target file, an optional function or region anchor, a current source excerpt, and the intended change\.

For each edit, the planner also records an action declaration containing the target file, optional anchor, and one of three action types:*modify*,*add*, or*remove*\. The resulting declarations are collected asΓ=\(Γmodify,Γadd,Γremove\)\\Gamma=\(\\Gamma\_\{\\mathrm\{modify\}\},\\Gamma\_\{\\mathrm\{add\}\},\\Gamma\_\{\\mathrm\{remove\}\}\)\. A rename is represented as one removal and one addition\.

The executor applies𝒫\\mathcal\{P\}toℛ\\mathcal\{R\}and produces the updated repositoryℛ′\\mathcal\{R\}^\{\\prime\}\. The resulting diff isΔ=Diff​\(ℛ,ℛ′\)\\Delta=\\mathrm\{Diff\}\(\\mathcal\{R\},\\mathcal\{R\}^\{\\prime\}\)\. BecauseΔ\\Deltais the factual record of what changed, it drives handbook invalidation\. By contrast,Γ\\Gammais used only to check whether execution followed the plan\.

#### 3\.3\.3Handbook Resynchronization

Every non\-empty diffΔ\\DeltatriggersResyncg\\mathrm\{Resync\}\_\{g\}\. Whenever possible, the procedure updates only the affected parts rather than rebuilding the entire handbook\.

First,it reparses the changed source, refreshes the program graph, and aligns the old and new versions to identify added, removed, and modified units: infunction\-as\-leafmode, it matches functions using fingerprints that do not depend on line numbers, and infile\-as\-leafmode, it matches files using file\-set differences and content hashes\.

Second,it determines the update scope\. If the stage skeleton𝒮\\mathcal\{S\}remains valid, only the affected entries and their enclosing structure are refreshed; otherwise, Algorithm[2](https://arxiv.org/html/2607.13285#alg2)is rerun onℛ′\\mathcal\{R\}^\{\\prime\}with the same leaf modeggand stored configurationΘ\\Theta\.

Finally,content that cannot be parsed or classified is handled conservatively: it is frozen or recorded in the coverage record rather than guessed\.

Once the update completes, the new pair\(ℛ′,ℋ′\)\(\\mathcal\{R\}^\{\\prime\},\\mathcal\{H\}^\{\\prime\}\)becomes the starting state for the next request\. Within resynchronization, model calls are limited to four semantic steps: classification, file assignment, within\-stage organization, and description revision\. All other operations are deterministic\.

## 4Experiment

We evaluate Harness Handbook on two open\-source agent harnesses around three research questions, describing the experiment setup in Section[4\.1](https://arxiv.org/html/2607.13285#S4.SS1)and reporting results in Section[4\.2](https://arxiv.org/html/2607.13285#S4.SS2)\.

- •RQ1:Does handbook\-guided localization improve plan quality while reducing planning cost?
- •RQ2:With the handbook, can a weaker planner match the implementation\-site localization of substantially more capable models?
- •RQ3:Do these gains persist across request types and localization difficulty levels?

![Refer to caption](https://arxiv.org/html/2607.13285v1/x3.png)Figure 3:Plan quality and planner token usage on Codex and Terminus\-2\. \(a\) Overall win rates aggregated across the three judges\. \(b\) Win rates reported separately by GPT\-5\.5, Opus 4\.8, and DeepSeek\-V4\-Pro\. \(c\) Average number of planner tokens per request; lower values indicate greater efficiency\.![Refer to caption](https://arxiv.org/html/2607.13285v1/x4.png)Figure 4:Per\-judge win rates for three evaluation dimensions\. Rows show results for Codex and Terminus\-2, while columns show Localization, Scope Control, and Reasoning\.### 4\.1Experiment Setup

##### Evaluation Setting\.

This experiment evaluates localization and edit planning in the modification workflow\. Given a natural\-language request, a read\-only planner built with NexAU\[nexagi2025nexn1\]and powered byDeepSeek\-V4\-Proproduces an edit plan𝒫\\mathcal\{P\}, and we score the quality of𝒫\\mathcal\{P\}directly\.

We compare two arms: the*Baseline*explores the repository directly, whereas the*Handbook\-Assisted*arm locates relevant source code under handbook guidance using a BGPD\-consistent navigation policy\. Apart from handbook access and navigation, the two arms are identical in requests, model, repository, tool permissions, and decoding settings\. The handbook used in the Handbook\-Assisted arm is built from the same source\.

Plan quality is judged independently by three models:GPT\-5\.5,Opus 4\.8, andDeepSeek\-V4\-Pro\.

![Refer to caption](https://arxiv.org/html/2607.13285v1/x5.png)Figure 5:Win rates by \(a\) modification request type and \(b\) localization difficulty\. Q, CF, and SH denote Query, Cross\-file, and Search\-Hostile requests\.
##### Benchmarks and Modification Requests\.

We evaluateTerminus\-2\[merrill2026terminalbench\]andCodex\[openai2025codex\], two open\-source agent harnesses that adopt the two leaf modes from Section[3\.2](https://arxiv.org/html/2607.13285#S3.SS2): Terminus\-2 usesfunction\-as\-leafbecause it has a reliable seed skeleton, and Codex usesfile\-as\-leafto infer the hierarchy at repository scale\.

Each harness contributes 30 behavior\-driven modification requests\. They are grouped by type intoQuery \(Q\), which modifies existing behavior without revealing target locations;Cross\-file \(CF\), which adds an end\-to\-end capability spanning files or modules; andSearch\-Hostile \(SH\), which places relevant implementations in locations that are hard to recover by keyword search\. Requests are also labeledEasy,Medium, orHardby localization difficulty\.

##### Evaluation Metrics\.

We evaluate plan quality, localization accuracy, and planning cost\.

##### Plan quality\.

Three independent judges score each plan on three dimensions:*Localization*\(whether the edit sites are accurate\),*Scope Control*\(whether the plan stays focused, with less scope bloat\), and*Reasoning*\(whether the rationale and supporting evidence are adequate\)\. The weighted score is

S=0\.5​SLoc\+0\.25​SScope\+0\.25​SReason,S=0\.5S\_\{\\mathrm\{Loc\}\}\+0\.25S\_\{\\mathrm\{Scope\}\}\+0\.25S\_\{\\mathrm\{Reason\}\},\(1\)on a 0–100 scale, with Localization receiving the largest weight\. Handbook\-Assisted and Baseline are declared the winner when their scores differ by at leastδ=3\\delta=3points; otherwise the comparison is a tie\. Thewin ratefor any reported slice is the number of wins divided by the number of valid judge–request comparisons in that slice\.

##### Localization accuracy\.

We compare each predicted edit plan with independent reference plans from Opus 4\.8 and GPT\-5\.5, reporting Recall, Precision, F1, and Wrong at file and symbol granularity\. Wrong is the share of valid requests with zero overlap against the reference; lower is better\.

##### Planning cost\.

We report the average number of planner tokens per request, including the handbook and source context consumed during localization and plan construction\.

### 4\.2Experiment Results

The results show three consistent patterns\. Handbook guidance improves plan quality without increasing planner token use\. It also helps a weaker planner produce file\- and symbol\-level predictions that more closely align with reference plans from stronger models\. These gains persist across request types and localization difficulty levels\. The following subsections examine each finding in turn\.

#### 4\.2\.1Better Plans at Lower Token Cost

Figure[3](https://arxiv.org/html/2607.13285#S4.F3)summarizes plan\-quality win rates and average planner token use\. The Handbook\-Assisted arm achieves a higher overall win rate on both harnesses: 38\.3% versus 28\.3% on Codex and 45\.6% versus 26\.7% on Terminus\-2\. The improvement is consistent across all three judges: the gap is 10\.0 percentage points for every judge on Codex and ranges from 13\.3 to 26\.7 points on Terminus\-2\. Thus, the direction of the result does not depend on any single judge\.

Figure[4](https://arxiv.org/html/2607.13285#S4.F4)decomposes these judgments by dimension\. Averaged across the three judges, the Handbook\-Assisted arm has higher win rates for Localization, Scope Control, and Reasoning on both harnesses\. The respective gains are 12\.2, 6\.7, and 4\.5 points on Terminus\-2, and 2\.2, 1\.1, and 3\.3 points on Codex\.

The quality gains are accompanied by lower planner token use\. Average use falls from 0\.102M to 0\.089M tokens per Codex request \(12\.7%\) and from 0\.058M to 0\.053M tokens per Terminus\-2 request \(8\.6%\)\. The simultaneous increase in win rate and decrease in token use shows that the improvement is not explained by a larger planning\-token budget\.

#### 4\.2\.2A Weaker Planner Matches Stronger Models

To assess whether handbook guidance helps a weaker planner approach stronger models in implementation\-site localization, we compare its predicted edit sites with independent reference plans from Opus 4\.8 and GPT\-5\.5 \(Table[1](https://arxiv.org/html/2607.13285#S4.T1)\)\.

Table 1:Reference\-plan localization metrics \(%\)\. Predicted implementation sites are compared against independent reference plans generated by Opus 4\.8 and GPT\-5\.5 at file and symbol granularity\. Metrics are macro\-averaged across valid requests; missing outputs and planner errors are excluded\.*Wrong*indicates zero overlap with the reference plan at the reported granularity, so lower values are better\.Across both harnesses, both reference models, and both granularities, all 24 Recall, Precision, and F1 comparisons are higher for the Handbook\-Assisted arm, with F1 gains ranging from 5\.0 to 18\.8 points\. Recall and precision increase together, so the improvement is not explained by returning more candidate sites at the expense of focus\.

The absolute agreement is highest on Terminus\-2\. With handbook guidance, the weaker planner reaches file\-level F1 scores of 84\.7% and 89\.3%, and symbol\-level scores of 77\.1% and 89\.3%, against the Opus 4\.8 and GPT\-5\.5 references, respectively\. Precision reaches 93\.3% against GPT\-5\.5 at both granularities\. The consistent direction across two independent references shows that the improvement is not specific to one reference model\.

Handbook guidance also reduces complete localization failures\. Wrong, the share of requests with zero overlap against the reference, never increases and falls by as much as 25\.9 points\. Thus, the gains include fewer complete misses, not only better overlap among already plausible plans\.

#### 4\.2\.3Consistent Gains Across Requests and Difficulty

Figure[5](https://arxiv.org/html/2607.13285#S4.F5)stratifies the win\-rate results by request type and localization difficulty\.

All six harness\-by\-type comparisons favor the Handbook\-Assisted arm, with gains ranging from 16\.3 to 33\.3 percentage points\. Codex improves most on Query requests \(26\.7 points\), whereas Terminus\-2 improves most on Search\-Hostile requests \(33\.3 points\)\. Cross\-file requests improve by 16\.3 and 20\.0 points, respectively\. The gains therefore span existing\-behavior changes, cross\-file capabilities, and requests that are difficult to localize through keyword search\.

All six harness\-by\-difficulty comparisons are also positive, ranging from 3\.7 to 33\.3 points\. Codex improves most on Easy requests, whereas Terminus\-2 improves most on Medium requests\. Because the gains are not monotonic in labeled difficulty, the difficulty label alone does not explain their variation\.

## 5Conclusion

This work identifies behavior localization as a central challenge in evolving production\-scale agent harnesses and introduces Harness Handbook, a behavior\-centric representation that links behavioral descriptions to their distributed source implementations\. Harness Handbook reorganizes repository knowledge around runtime behavior, constructs this representation directly from source, and supports modification through behavior\-guided progressive disclosure and automatic resynchronization\.

Our experiments demonstrate the value of this representation along three dimensions\. First, handbook guidance improves plan quality while lowering planning cost: on Codex and Terminus\-2, overall win rates rise by 10\.0 and 18\.9 percentage points, while planner token use falls by 12\.7% and 8\.6%, respectively\. Second, with the handbook a weaker planner matches the implementation\-site localization of substantially stronger models, improving all 24 file\- and symbol\-level Recall, Precision, and F1 comparisons against two independent reference plans\. Third, these gains persist across request types and localization difficulty levels\. Together, these results indicate that making the relationship between behavior and implementation explicit can improve both modification planning and localization efficiency without requiring a larger planning\-token budget\.

The utility of Harness Handbook extends beyond modification planning\. As a behavior\-centric repository representation that stays synchronized with the code, it can also support broader uses such as behavior auditing and regression\-impact analysis\. Our next step is to apply it to harness self\-evolving: using the handbook as a shared behavioral memory, an agent can autonomously close the loop of localization, planning, execution, and resynchronization as the repository evolves, moving the harness toward self\-improvement\.

## References

## Appendix Contents

## Appendix AHarness Handbook Construction Details

This appendix expands the three construction phases in Section[3\.2](https://arxiv.org/html/2607.13285#S3.SS2)\. The selected leaf modeggand construction configurationΘ\\Thetastay fixed through construction and later resynchronization\. Both modes work from the same static facts but organize them differently:function\-as\-leafstarts from a trusted seed skeleton𝒮0\\mathcal\{S\}\_\{0\}and places functions within it, whereasfile\-as\-leafdescribes files first and infers the skeleton\. Both ultimately produce the same reader\-facing handbook—an L1–L3 document tree, a cross\-stage state\-register view, and source locators for L3 entries\. Algorithm[2](https://arxiv.org/html/2607.13285#alg2)summarizes the shared workflow and its mode\-specific branches\.

Algorithm 2Harness Handbook Construction1:repository

ℛ\\mathcal\{R\}; leaf mode

g∈\{function,file\}g\\in\\\{\\mathrm\{function\},\\mathrm\{file\}\\\}; construction configuration

Θ\\Theta; seed skeleton

𝒮0\\mathcal\{S\}\_\{0\}if

g=functiong=\\mathrm\{function\}\(otherwise

∅\\emptyset\)

2:handbook

ℋ\\mathcal\{H\}containing rendered view

𝒱\\mathcal\{V\}, document tree

𝒟\\mathcal\{D\}, register view

𝒵\\mathcal\{Z\}, fixed leaf mode

gg, and synchronization state

𝒦g\\mathcal\{K\}\_\{g\}
3:Phase I: shared static facts\.

4:

𝒢←BuildGraph​\(ℛ\)\\mathcal\{G\}\\leftarrow\\textsc\{BuildGraph\}\(\\mathcal\{R\}\)\# deterministic; no LLM

5:

6:Phase II: mode\-specific behavioral organization\.

7:if

g=functiong=\\mathrm\{function\}then

8:

\(𝒮,𝒰g\)←OrganizeFunctions​\(ℛ,𝒢,𝒮0,Θ\)\(\\mathcal\{S\},\\mathcal\{U\}\_\{g\}\)\\leftarrow\\textsc\{OrganizeFunctions\}\(\\mathcal\{R\},\\mathcal\{G\},\\mathcal\{S\}\_\{0\},\\Theta\)\# budgeted stage and membership review

9:

𝒰g←FinalizeFunctions​\(ℛ,𝒢,𝒮,𝒰g\)\\mathcal\{U\}\_\{g\}\\leftarrow\\textsc\{FinalizeFunctions\}\(\\mathcal\{R\},\\mathcal\{G\},\\mathcal\{S\},\\mathcal\{U\}\_\{g\}\)\# regions, ordering, and unmapped functions

10:else\#g=fileg=\\mathrm\{file\}

11:

\(𝒮,𝒰g\)←OrganizeFiles​\(ℛ,𝒢,Θ\)\(\\mathcal\{S\},\\mathcal\{U\}\_\{g\}\)\\leftarrow\\textsc\{OrganizeFiles\}\(\\mathcal\{R\},\\mathcal\{G\},\\Theta\)\# cards, stage inference, and assignments

12:if

RefinementEnabled​\(Θ\)\\textsc\{RefinementEnabled\}\(\\Theta\)then

13:

\(𝒮,𝒰g\)←RefineFileOrganization​\(ℛ,𝒢,𝒮,𝒰g,Θ\)\(\\mathcal\{S\},\\mathcal\{U\}\_\{g\}\)\\leftarrow\\textsc\{RefineFileOrganization\}\(\\mathcal\{R\},\\mathcal\{G\},\\mathcal\{S\},\\mathcal\{U\}\_\{g\},\\Theta\)
14:endif

15:

𝒰g←FinalizeFiles​\(𝒢,𝒮,𝒰g\)\\mathcal\{U\}\_\{g\}\\leftarrow\\textsc\{FinalizeFiles\}\(\\mathcal\{G\},\\mathcal\{S\},\\mathcal\{U\}\_\{g\}\)\# within\-stage order and coverage

16:endif

17:

18:Phase III: synthesis, grounding, and packaging\.

19:

\(𝒟,𝒵,ℬ\)←Synthesize​\(g,ℛ,𝒢,𝒮,𝒰g,Θ\)\(\\mathcal\{D\},\\mathcal\{Z\},\\mathcal\{B\}\)\\leftarrow\\textsc\{Synthesize\}\(g,\\mathcal\{R\},\\mathcal\{G\},\\mathcal\{S\},\\mathcal\{U\}\_\{g\},\\Theta\)
20:

𝒵←ValidateRegisterRefs​\(𝒵,𝒮\)\\mathcal\{Z\}\\leftarrow\\textsc\{ValidateRegisterRefs\}\(\\mathcal\{Z\},\\mathcal\{S\}\)
21:

𝒟←ValidateAndFreezeLocators​\(𝒟,ℛ,g\)\\mathcal\{D\}\\leftarrow\\textsc\{ValidateAndFreezeLocators\}\(\\mathcal\{D\},\\mathcal\{R\},g\)
22:

𝒦g←Archive​\(g,𝒢,𝒮0,𝒮,𝒰g,ℬ,Θ\)\\mathcal\{K\}\_\{g\}\\leftarrow\\textsc\{Archive\}\(g,\\mathcal\{G\},\\mathcal\{S\}\_\{0\},\\mathcal\{S\},\\mathcal\{U\}\_\{g\},\\mathcal\{B\},\\Theta\)\#𝒮0\\mathcal\{S\}\_\{0\}is stored only in function mode

23:

ℋ←RenderAndPackage​\(𝒟,𝒵,g,𝒦g\)\\mathcal\{H\}\\leftarrow\\textsc\{RenderAndPackage\}\(\\mathcal\{D\},\\mathcal\{Z\},g,\\mathcal\{K\}\_\{g\}\)
24:return

ℋ\\mathcal\{H\}

### A\.1Phase I: Shared Static Fact Extraction

Phase I is a single deterministic analysis shared by both modes\. Language\-specific adapters parseℛ\\mathcal\{R\}and build the program graph𝒢\\mathcal\{G\}\. An internal\-function node records a function’s qualified name, source file, signature, line range, enclosing class, and observed state access; a boundary node represents a named external target, such as a library function\.

The graph keeps a call edge only when the target resolves to an internal function or a named boundary; unresolved calls are written to an audit log rather than assigned a guessed target\. Because this phase uses no LLM, every later organization step builds on the same source\-grounded facts\.

### A\.2Phase II: Behavioral Organization

Phase II organizes the facts in𝒢\\mathcal\{G\}around execution behavior\. Its output is the current stage skeleton𝒮\\mathcal\{S\}together with the mode\-specific organization state𝒰g\\mathcal\{U\}\_\{g\}\. The two leaf modes differ in both their starting point and their unit of organization\.

#### A\.2\.1Function\-as\-Leaf

##### Initial assignment\.

Thefunction\-as\-leafbranch \(g=functiong=\\mathrm\{function\}\) starts from the seed skeleton𝒮0\\mathcal\{S\}\_\{0\}, whose stage and state\-register declarations initialize𝒮\\mathcal\{S\}\. On the first pass, it considers every analyzable internal function—that is, every non\-synthetic function with usable source locations—and attempts to assign it to one or more stages\. The decision uses the function’s source inℛ\\mathcal\{R\}, its callers and callees in𝒢\\mathcal\{G\}, the current neighboring assignments, and the stage descriptions\. A function is normally placed as a whole\. If different parts serve different behavioral roles, it can instead be divided into contiguous source regions and each region placed separately\.

##### Review and convergence\.

A single pass may expose weaknesses in either the assignments or the seed structure, so later rounds review both\. Each round first checks whether stages should be added, removed, merged, or split\. A structural change is accepted only if the resulting hierarchy is valid and every state\-register declaration still refers to an existing stage\. Functions affected by an accepted change are then classified again against the revised structure\.

After reclassification, a global audit checks whether whole\-function placements remain consistent with the surrounding stages, and a separate pass repairs the boundaries of retained regions\. Proposed changes must pass model\-based review before they are applied\. The rounds stop when the stage skeleton and all function or region assignments match the previous round and no function is waiting to be reconsidered\. If this state is not reached, the process stops at the organization budget stored inΘ\\Thetaand keeps the remaining gaps explicit\.

##### Validation and finalization\.

Every accepted assignment must name a valid stage, use a legal source range, and avoid conflicting actions\. Region boundaries are aligned to parser\-derived statement spans when possible, and the enclosed source is hashed for later comparison\. A boundary that cannot be aligned is marked*needs\-review*; Phase III then decides whether its locator can remain active or must be frozen\.

Deterministic cleanup removes a redundant whole\-function entry when retained regions already cover that function in the same stage, without disturbing its assignments to other stages\. The pipeline then rebuilds cross\-stage references, records all functions that remain unmapped, and orders entries within each stage using their purposes and stage\-internal calls\. If the proposed order is incomplete or contains duplicates, file and line order provides a stable fallback\. Together, the finalized memberships, region anchors and hashes, boundary status, within\-stage order, and record of unmapped functions constitute𝒰function\\mathcal\{U\}\_\{\\mathrm\{function\}\}\.

#### A\.2\.2File\-as\-Leaf

Thefile\-as\-leafbranch \(g=fileg=\\mathrm\{file\}\) uses no seed skeleton \(𝒮0=∅\\mathcal\{S\}\_\{0\}=\\emptyset\)\. It first describes each file, then infers𝒮\\mathcal\{S\}from those descriptions, and finally organizes the files within each stage\.

##### Step 1: Build a card for each file\.

The pipeline attempts to create one file card for every scanned file, including files from which static analysis extracts no function\. A successfully generated card describes the file’s purpose, repository role, and place in the execution lifecycle\. When deep card generation is enabled, it also includes a static inventory of function identities, signatures, source ranges, and resolved calls\. The model may explain this inventory but cannot change it\.

Card generation uses a fixed fallback sequence\. A file omitted from a batch is retried individually\. If a deep card still fails, the source is retried in function\-range chunks\. If no prose can be produced, a fallback card is emitted; in deep mode, it retains the graph\-derived inventory\. The file stays available to later steps but is marked undescribed in the coverage record𝒴\\mathcal\{Y\}, so no scanned file is silently dropped\.

##### Step 2: Infer stages and assign files\.

The pipeline groups cards by directory and combines their descriptions with graph\-derived entry points and resolved calls\. From this context, it drafts an ordered stage skeleton and attempts to assign each scanned file to exactly one primary stage, using its card description when available\. That stage is the file’s home in the handbook\. A genuinely cross\-cutting file, such as a logging, protocol, type, or configuration utility, may also name one or two secondary stages\. Missing assignments and assignments to unknown stages remain visible in𝒴\\mathcal\{Y\}rather than being forced into the nearest stage\.

The organization variant stored inΘ\\Thetadetermines whether the initial result is refined\.oneshot, the default, ends after one stage draft and one file\-assignment pass\.doctorstarts from that draft and applies a reviewed refinement loop\.agentuses an agent\-generated draft followed by the same loop; if the agent cannot produce a valid draft, it falls back to the one\-shot draft\. A refinement round may add, remove, merge, or split stages, after which only affected or unassigned files are reconsidered\. The loop stops when all files are assigned and the skeleton is stable, when neither coverage nor stage balance improves for two consecutive rounds, or when the organization budget is reached\. Any files that remain unassigned stay visible in𝒴\\mathcal\{Y\}\.

##### Step 3: Organize files within each stage\.

For each non\-empty stage, the file\-call graph first provides a caller\-before\-callee order\. The file cards are then used to refine that order into thematic groups and a readable sequence\. A deterministic check removes unknown or duplicate paths and verifies that every assigned file appears exactly once\. An omitted file is appended to a fallback group, and a failed organization call falls back to the deterministic flat order\. This step can reorder files within a stage but cannot change the stage skeleton\. Together, the file cards, stage assignments, within\-stage grouping and order, and coverage record𝒴\\mathcal\{Y\}constitute𝒰file\\mathcal\{U\}\_\{\\mathrm\{file\}\}\.

### A\.3Phase III: Hierarchical Synthesis and Packaging

Phase III turns\(𝒮,𝒰g\)\(\\mathcal\{S\},\\mathcal\{U\}\_\{g\}\)into the document tree𝒟\\mathcal\{D\}and state\-register view𝒵\\mathcal\{Z\}, records reusable generation outputs in the cacheℬ\\mathcal\{B\}, and validates both against the repository before packaging\.

##### Synthesizing the document tree\.

In both modes,𝒟\\mathcal\{D\}contains an L1 system overview, an L2 component overview for each included stage, and source\-backed L3 entries\. The modes differ in the direction of synthesis:

- •function\-as\-leafbuilds top\-down\.The known stage skeleton provides the outline\. Generation proceeds from the L1 overview to each L2 component overview and then to the stage’s L3 entries\. Each L3 entry represents one function within that stage; multiple retained regions of the same function are merged into that entry\.
- •file\-as\-leafbuilds bottom\-up\.Assigned file cards become the L3 entries\. A stage is summarized when it owns assigned files or has child stages; empty leaf placeholders are skipped\. The remaining stages are processed from the leaves upward: child summaries and one\-line descriptions of a stage’s own files produce its L2 component overview, and the top\-level summaries produce L1\.

Infunction\-as\-leafmode, each L1, L2, and L3 node uses a bounded generate–review–revise process\. The best draft is retained, and generation stops when it passes the rubric, its score no longer improves, or the generation budget is reached\. Independent stages can be processed in parallel, but L3 entries within one stage are generated in sequence so that a later entry can refer to earlier ones\.

Infile\-as\-leafmode, file cards are rendered directly\. Each stage and system summary is generated once, with a deterministic fallback if generation fails, and each parent summary waits for its child summaries\.

The resulting descriptions and summaries are retained inℬ\\mathcal\{B\}so that unchanged content can be reused during later generation or resynchronization\.

##### Building the state\-register view\.

Infunction\-as\-leafmode, the register identities and stage relationships in𝒵\\mathcal\{Z\}come from the declarations in the current stage skeleton; generation turns these declarations into reader\-facing descriptions without inventing new registers\. Infile\-as\-leafmode, the pipeline instead proposes cross\-stage registers from the top\-level stage summaries and the purposes of data\-model files\. It repeats this search until two consecutive rounds add nothing or the register budget is reached\. References to stages absent from the current structure are removed from the candidate mapping\.

##### Grounding and failure handling\.

The static facts inℛ\\mathcal\{R\}and𝒢\\mathcal\{G\}remain authoritative throughout synthesis\. The model may add behavioral explanations, but it cannot alter file paths, function identities, signatures, source ranges, or resolved calls\. Functions and files that cannot be placed remain explicitly recorded rather than being assigned by guesswork\.

Before rendering, the pipeline resolves every L3 locator in𝒟\\mathcal\{D\}againstℛ\\mathcal\{R\}and compares the located source with the stored evidence\. An entry that cannot be revalidated is marked frozen and excluded from localization until it is refreshed, keeping the repository authoritative even when prose is reused from the cache\.

##### Rendering and saved synchronization state\.

After validation, the pipeline renders𝒟\\mathcal\{D\}and𝒵\\mathcal\{Z\}as the reader\-facing view𝒱\\mathcal\{V\}\. It then packages this view with𝒟\\mathcal\{D\},𝒵\\mathcal\{Z\}, the fixedgg, and the machine\-readable resynchronization state𝒦g\\mathcal\{K\}\_\{g\}as the handbookℋ\\mathcal\{H\}\. Across both modes,𝒦g\\mathcal\{K\}\_\{g\}retains the fixed leaf mode, program graph, current stage skeleton, mode\-specific organization state, construction configuration, and generation cache\. The stored configurationΘ\\Thetarecords the selected organization or refinement variant, card\-detail level, and the budgets for organization, generation, and register extraction where applicable\. In function mode,𝒦g\\mathcal\{K\}\_\{g\}also retains the original seed skeleton𝒮0\\mathcal\{S\}\_\{0\}; no seed is stored in file mode\. Savingℋ\\mathcal\{H\}in this form allows a later code change to refresh affected content without reconstructing unchanged parts of the handbook\.

## Appendix BModification and Resynchronization Details

This appendix expands the four\-step modification workflow in Section[3\.3](https://arxiv.org/html/2607.13285#S3.SS3)using the package contract defined in Appendix[A](https://arxiv.org/html/2607.13285#A1)\. It follows a requestqqthrough BGPD localization, edit planning, execution, and automatic resynchronization\. Throughout the workflow, the handbookℋ\\mathcal\{H\}is paired with its matching repositoryℛ\\mathcal\{R\}, and the stored leaf modeggremains fixed\.

### B\.1Behavior\-Guided Progressive Disclosure

BGPD guides a read\-only agent through the handbook from coarse to fine\. A locator enters the evidence set only after it has been resolved against the current repository\.

##### Stage selection\.

Navigation begins at L1 and L2 of the document tree𝒟\\mathcal\{D\}stored inℋ\\mathcal\{H\}\. The agent reads the system overview and stage index to select the execution stages whose behavior matchesqq\. It then follows the state\-register view𝒵\\mathcal\{Z\}to add stages coupled through shared state\. This step recovers behavior that is structurally distant yet mutually dependent, such as a value written in one stage and consumed several stages later\.

##### Entry selection\.

Within the selected stages, the agent opens the corresponding stage pages and chooses the most relevant L3 entries\. Each entry exposes a summary and a source locator\. Its body is disclosed only when needed, limiting unnecessary context\.

##### Call\-relation expansion\.

The candidate set is expanded along call relations in the program graph𝒢\\mathcal\{G\}retained by the synchronization state𝒦g\\mathcal\{K\}\_\{g\}\. Infunction\-as\-leafmode, expansion follows the function\-call graph; infile\-as\-leafmode, it follows the induced file\-call graph\. Named external boundary nodes may supply context but are never returned as edit sites\.

##### Source verification\.

All preceding steps operate onℋ\\mathcal\{H\}\. The agent then opensℛ\\mathcal\{R\}, resolves each candidate locator, and keeps only the sites that remain relevant toqq\. The result is the verified evidenceℰ^q\\widehat\{\\mathcal\{E\}\}\_\{q\}\. Each record carries a file path, an optional function or region anchor, and a current source excerpt\. The handbook guides the search, while the repository remains the authority for the edit plan\.

### B\.2Edit Planning

The planner convertsℰ^q\\widehat\{\\mathcal\{E\}\}\_\{q\}into an edit plan𝒫\\mathcal\{P\}whose blocks name a target file, an optional anchor, the supporting source excerpt, and the intended change\. In our evaluation implementation, each change is expressed as a verbatim old/new pair\. For every block, the planner also emits an action declaration\. These declarations are collected asΓ=\(Γmodify,Γadd,Γremove\)\\Gamma=\(\\Gamma\_\{\\mathrm\{modify\}\},\\Gamma\_\{\\mathrm\{add\}\},\\Gamma\_\{\\mathrm\{remove\}\}\), with a rename encoded as one removal and one addition\.

### B\.3Execution

Execution is delegated to a separate agent that applies𝒫\\mathcal\{P\}toℛ\\mathcal\{R\}and producesℛ′\\mathcal\{R\}^\{\\prime\}\. The factual record of the change isΔ=Diff​\(ℛ,ℛ′\)\\Delta=\\mathrm\{Diff\}\(\\mathcal\{R\},\\mathcal\{R\}^\{\\prime\}\)\.

In our implementation, the executor can read and write files, perform targeted replacements, and search within a file, but it cannot list directories or access a shell\. It first applies each verbatim replacement directly and reads the target source only if the replacement fails\. It then verifies the touched files and runs a target\-specific syntax gate when one is configured\. The diffΔ\\Deltadrives handbook invalidation, whereasΓ\\Gammais used only to check whether execution followed the plan\.

### B\.4Automatic Resynchronization

Every non\-emptyΔ\\Deltaautomatically invokesResyncg\\mathrm\{Resync\}\_\{g\}, which updates only the affected parts of the handbook whenever possible\. IfΔ=∅\\Delta=\\emptyset, resynchronization is skipped andℋ′=ℋ\\mathcal\{H\}^\{\\prime\}=\\mathcal\{H\}\.

##### Version alignment\.

The procedure reparsesℛ′\\mathcal\{R\}^\{\\prime\}and builds the updated program graph𝒢′\\mathcal\{G\}^\{\\prime\}\. It compares𝒢′\\mathcal\{G\}^\{\\prime\}with the stored graph𝒢\\mathcal\{G\}, usingΔ\\Deltato identify added, removed, and modified units\.

Infunction\-as\-leafmode, functions are matched using body fingerprints that ignore line numbers\. A function that only moves is therefore treated as unchanged, and its locator is shifted by the corresponding line offset\. A rename is detected by matching the body below the signature line\. Infile\-as\-leafmode, file\-set differences identify added and removed files, while content hashes identify changed files\. A path rename therefore appears as one removal and one addition\.

Before the observed actions are compared withΓ\\Gamma, a detected function rename is normalized to one removal and one addition\. This audit does not alter theΔ\\Delta\-driven invalidation scope\.

##### Scoped update\.

Resynchronization next checks whether the current stage skeleton𝒮\\mathcal\{S\}can accommodate the change\. If it remains valid,𝒮′=𝒮\\mathcal\{S\}^\{\\prime\}=\\mathcal\{S\}and the affected part of𝒰g\\mathcal\{U\}\_\{g\}is updated to𝒰g′\\mathcal\{U\}^\{\\prime\}\_\{g\}\. Infunction\-as\-leafmode, this update removes deleted memberships, carries forward matched functions, and reclassifies new or changed functions\. It also refreshes region anchors, source hashes, within\-stage order, and unmapped status\. Infile\-as\-leafmode, it removes obsolete cards and assignments, refreshes cards for new or changed files, assigns new files, reorganizes affected stages, and updates the coverage record𝒴\\mathcal\{Y\}to𝒴′\\mathcal\{Y\}^\{\\prime\}\.

The pipeline then regenerates the affected L3 entries, their enclosing L2/L1 ancestors, and dependent state registers\. This produces the updated document tree𝒟′\\mathcal\{D\}^\{\\prime\}and state\-register view𝒵′\\mathcal\{Z\}^\{\\prime\}\. Unaffected generation outputs are reused fromℬ\\mathcal\{B\}\. The updated cacheℬ′\\mathcal\{B\}^\{\\prime\}retains these reusable entries and adds or replaces the refreshed outputs\.

If𝒮\\mathcal\{S\}can no longer accommodate the change, Algorithm[2](https://arxiv.org/html/2607.13285#alg2)is rerun onℛ′\\mathcal\{R\}^\{\\prime\}with the same leaf modeggand stored configurationΘ\\Theta\. Thefunction\-as\-leafbranch also reuses the stored seed skeleton𝒮0\\mathcal\{S\}\_\{0\}\. Thefile\-as\-leafbranch instead infers a new stage skeleton from the updated repository\. During the full rebuild, Phase I produces𝒢′\\mathcal\{G\}^\{\\prime\}, Phase II produces\(𝒮′,𝒰g′\)\(\\mathcal\{S\}^\{\\prime\},\\mathcal\{U\}^\{\\prime\}\_\{g\}\), and Phase III synthesis produces\(𝒟′,𝒵′,ℬ′\)\(\\mathcal\{D\}^\{\\prime\},\\mathcal\{Z\}^\{\\prime\},\\mathcal\{B\}^\{\\prime\}\)\. These components follow the shared validation and packaging contract described below\.

##### Conservative handling\.

Source that cannot be parsed or classified is not guessed\. An existing L3 entry whose locator or source hash cannot be revalidated is marked frozen and excluded from localization\. Infunction\-as\-leafmode, new or changed functions that cannot be mapped remain explicitly recorded as unmapped in𝒰function′\\mathcal\{U\}^\{\\prime\}\_\{\\mathrm\{function\}\}\. If a changed function previously had an active L3 entry, that entry is frozen until classification succeeds\. Infile\-as\-leafmode, files without a valid card or assignment remain in the coverage record𝒴′\\mathcal\{Y\}^\{\\prime\}within𝒰file′\\mathcal\{U\}^\{\\prime\}\_\{\\mathrm\{file\}\}\.

Parsing, hashing, graph construction, locator roll\-forward, and coverage checks are deterministic\. Model calls are limited to classification, file assignment, within\-stage organization, and description revision\. These categories also cover a full rebuild\. Stage and function decisions count as classification; file\-to\-stage decisions count as file assignment; and file grouping counts as within\-stage organization\. Regenerating cards, document nodes, or registers counts as description revision\.

##### Validation and packaging\.

Both update paths then follow the packaging contract of Appendix[A](https://arxiv.org/html/2607.13285#A1): the pipeline validates the locators in𝒟′\\mathcal\{D\}^\{\\prime\}againstℛ′\\mathcal\{R\}^\{\\prime\}and the stage references in𝒵′\\mathcal\{Z\}^\{\\prime\}against the updated skeleton, archives𝒢′\\mathcal\{G\}^\{\\prime\}and\(𝒮′,𝒰g′\)\(\\mathcal\{S\}^\{\\prime\},\\mathcal\{U\}^\{\\prime\}\_\{g\}\)withℬ′\\mathcal\{B\}^\{\\prime\}, the fixedgg, andΘ\\Theta\(plus𝒮0\\mathcal\{S\}\_\{0\}in function mode\) as𝒦g′\\mathcal\{K\}^\{\\prime\}\_\{g\}, and renders and packages the validated\(𝒟′,𝒵′\)\(\\mathcal\{D\}^\{\\prime\},\\mathcal\{Z\}^\{\\prime\}\)with𝒦g′\\mathcal\{K\}^\{\\prime\}\_\{g\}asℋ′\\mathcal\{H\}^\{\\prime\}\. The pair\(ℛ′,ℋ′\)\(\\mathcal\{R\}^\{\\prime\},\\mathcal\{H\}^\{\\prime\}\)becomes the starting state for the next request\.

## Appendix CExperimental Details

This appendix details the setup summarized in Section[4\.1](https://arxiv.org/html/2607.13285#S4.SS1), where every factor other than handbook access is held fixed across the two arms\. It covers the two evaluated harnesses and their Phase I static facts, the modification requests \(3030per harness, balanced across request type and localization difficulty\), and the two evaluation arms with theSKILL\.mdmanifest that exposes the handbook to the planner\. The evaluation metrics are defined in Section[4\.1](https://arxiv.org/html/2607.13285#S4.SS1)\.

### C\.1Harnesses and Static Facts

We evaluate on two production\-style agent harnesses that differ sharply in scale and language\.

- •Terminus\-2is a Python terminal agent from the Harbor framework\. It drives a real terminal through a tmux session in an observe–decide–act loop: it reads the terminal state, queries an LLM for the next action, sends commands, and reads back the results, repeating until the task finishes or a limit is reached\. It is compact \(6 source files\) but behaviorally rich, with a multi\-stage iteration loop, context management, and cross\-iteration state\.
- •Codexis the Rust monorepo behind the Codex coding agent\. It is large and multi\-surface, spanning a CLI, a TUI, an app\-server, configuration, and sandboxing across many crates, with thousands of files and deep call graphs\.

Following the selection rule in Section[3\.2](https://arxiv.org/html/2607.13285#S3.SS2), Terminus\-2 uses thefunction\-as\-leafmode, since a reliable seed skeleton is available and function\-level entries stay within budget, whereas Codex uses thefile\-as\-leafmode to infer the hierarchy at repository scale\. Table[2](https://arxiv.org/html/2607.13285#A3.T2)reports the Phase I static facts extracted from each repository together with the resulting handbook structure\.

Table 2:Phase I static facts and resulting handbook structure for the two evaluated harnesses\. The upper block reports the program graph𝒢\\mathcal\{G\}produced by static analysis \(Appendix[A](https://arxiv.org/html/2607.13285#A1)\); the lower block reports the built handbook\. For Terminus\-2, an L3 entry covers a whole function or one or more contiguous regions of a function; for Codex, an L3 entry corresponds to one file\.Terminus\-2Codex*Setup*LanguagePythonRustLeaf modefunction\-as\-leaffile\-as\-leaf*Program graph \(Phase I\)*Source files62,267Internal\-function nodes10334,363Boundary nodes414,016Resolved call edges257159,960*Built handbook*Stages \(L2\)20140L3 entries1062,267State registers1062The two repositories differ by roughly two orders of magnitude in files, functions, and call edges, which is precisely why they instantiate the two leaf modes\.

### C\.2Modification Requests

Each harness contributes 30 behavior\-driven modification requests, evenly split into three types\. Each request states an intended behavioral change without revealing target locations\. The two suites are built from the same behavioral intents but phrased against each harness’s own code, so the same goal lands on different implementation sites in Terminus\-2 and Codex\.

- •Query \(Q\)modifies existing behavior, such as a trigger, a timing rule, or a control\-flow decision\.
- •Cross\-file \(CF\)adds an end\-to\-end capability that spans files, schemas, pipeline logic, or interfaces\.
- •Search\-Hostile \(SH\)places relevant sites in mirrored implementations, fallback branches, or cold paths that keyword search alone struggles to recover\.

Table[3](https://arxiv.org/html/2607.13285#A3.T3)gives a representative request of each type, chosen separately for each harness\.

Table 3:Representative modification requests, chosen separately for each harness, with the localization challenge each type poses\.Requests are additionally labeled Easy, Medium, or Hard by localization difficulty, reflecting whether the change touches one primary behavior, requires coordination across stages and files, or requires discovering dependencies along indirect execution paths\. Table[4](https://arxiv.org/html/2607.13285#A3.T4)gives a representative request at each level for both harnesses\.

Table 4:Representative modification requests at each localization\-difficulty level, chosen separately for each harness, with the localization challenge each level poses\.\-\-\-

name:<harness\>\-handbook

description:\>\-

Structuralmapoftheharness,derivedfromitscode\.Useitwhenplanninga

changetofindEVERYcodesitethechangemusttouch\-\-itmapsthecode

stage\-by\-stageandlistseverystateregistertogetherwithallofits

read/writelocations\.Consultitbeforefinalizingaplansothatscatteredor

non\-obvioussitesarenotmissed\.

\-\-\-

\#HarnessHandbook:navigationguide

Thisisastructuralmapoftheharness\.Useittolocatewherearequestedchange

musttakeeffect\-\-especiallysitesthatarenotadjacenttotheobviousone\.

\#\#Referencefiles

\-references/overview\.md\-\-whole\-systemorientation:thelifecycle,themain

loop,andhowthestagesfittogether\.Readfirst\.

\-references/index\.md\-\-themap:everystage\(id,title,whatitdoes,the

leavesitcovers\)andeverystateregister\.

\-references/registers\.md\-\-foreachstateregister:itspurposeandEVERYplace

itiswrittenandread,acrossthewholeharness\.

\-references/stages/<id\>\.md\-\-onestage’sproseplusacardperleaf\(functionor

file\):its<summary\>linegivestheexactcode

location\(path:start\-end\),andthecardholdsthe

interface,behavior,relations,andsource\.

\#\#Howtouseit\(duringplanning,beforeyouwriteyourplan\)

1\.Readreferences/overview\.mdfirsttounderstandthewholesystem\.

2\.Readreferences/index\.mdtoidentifythestages,leaves,ANDstateregisters

yourchangeinvolves\.DoNOTprematurelynarrowtotheoneobviousstage:a

singlechangeoftentouchessitesinseveralstages\.

3\.ForEVERYstateregisteryourchangetouches,readreferences/registers\.mdand

noteEVERYwriteandreadsite\.Thisread/writeregistrysurfacesscattered,

non\-adjacentsitesatop\-downcodereadwouldmiss\.

4\.Opentherelevantreferences/stages/<id\>\.mdfordetailandcoupledassumptions\.

5\.Foreachsitethehandbooknames,opentherealcodewithread\_file/

search\_file\_contentandlocatethepreciselines\.

6\.Yourplanmustaccountforeverysitethehandbooksurfaced\.

ThehandbooktellsyouWHEREthingsliveandhowtheyconnect\.Youstilldecide

whatthechangeshouldbe,andyouverifyeverylocationagainsttherealcode

beforeplanningit\.

Figure 6:TheSKILL\.mdmanifest that exposes a handbook to the planner in the Handbook\-Assisted arm\. The same structure is used in both leaf modes; a leaf is a function infunction\-as\-leafmode and a file infile\-as\-leafmode\.
### C\.3Evaluation Arms

To isolate the effect of the handbook, both arms share the same configuration\. The planner is an agent built on NexAU whose underlying LLM is DeepSeek\-V4\-Pro and whose repository tools are read\-only, and both arms use the same requests, repository snapshot, planning contract, and decoding settings\. They differ only in whether the handbook is available and in the corresponding localization instructions\. The assisting handbook is built from the same repository snapshot used in the evaluation\.

- •Baseline\.Without a handbook, the planner locates edit sites by exploring the repository with read\-only tools \(file read, in\-file search, and directory listing\)\.
- •Handbook\-Assisted\.The planner is additionally given the handbook as a navigable skill and follows the BGPD policy, proposing source locators from the handbook and then verifying them against the repository\.

The handbook is exposed to the planner as a skill: aSKILL\.mdmanifest tells the planner when and how to consult the handbook, and points to the reference files it navigates\. Figure[6](https://arxiv.org/html/2607.13285#A3.F6)shows this manifest\. The same structure is used in both leaf modes; each stage’s leaf cards hold functions infunction\-as\-leafmode and files infile\-as\-leafmode\.

## Appendix DPrompt Templates

This appendix reproduces the main prompts used by the pipeline, organized by the stage in which they are used: those that build the handbook \(Appendix[D\.1](https://arxiv.org/html/2607.13285#A4.SS1)\), those that localize and plan a change under BGPD \(Appendix[D\.2](https://arxiv.org/html/2607.13285#A4.SS2)\), and those that score plans with an LLM judge \(Appendix[D\.3](https://arxiv.org/html/2607.13285#A4.SS3)\)\. The listings are transcribed from the implementation; per\-run fields substituted at runtime are shown as\{\{\.\.\.\}\}or\{\.\.\.\}placeholders, and a few non\-ASCII characters are rendered in ASCII\. Static fields such as qualified names, signatures, source ranges, and call edges are supplied by static analysis and cannot be overwritten by the model\.

### D\.1Handbook Generation

These prompts drive the construction pipeline of Appendix[A](https://arxiv.org/html/2607.13285#A1): they organize source units into execution stages and synthesize the L1–L3 document tree\. Throughout, the statically extracted identities stay fixed and the model only supplies behavioral descriptions\.

#### D\.1\.1Classifying Functions into Stages

Used infunction\-as\-leafPhase II to assign one function to one or more stages, as a whole or as contiguous regions\. The rules block below is followed at runtime by the available stage list, the function’s metadata, its caller/callee context with their current stage assignments, and the line\-numbered source\.

YouareanalyzingonePythonfunctionfromtheTerminus2agentharness,and

classifyingitintooneormorestagesofahand\-authoreddata\-flowskeleton\.

GRANULARITY

\-"function":theentirefunctionisasinglenarrativeunit\.Useforshort,

cohesivefunctions\(<=30linesorwithasingleclearpurpose\)\.

\-"region":thefunctioncontainsmultipledistinctnarrativestepsandshouldbe

splitinto2\-10regions\.Useforlargefunctionswithmultipledecisionpoints

orsequentialphases\.

REGIONRULES\(whengranularity=="region"\)

\-EachregionMUSTbecontiguousandendatacompletestatementboundary\(not

mid\-statement\)\.

\-Providefirst\_lineandlast\_lineastheEXACTtextcontentofthefirstandlast

linesoftheregion\.

\-Eachregionhasitsownstage\_id\.

STAGEASSIGNMENT

\-PickstageIDsONLYfromthelistprovided\.

\-CROSS\-CUTTINGutilityfunctions\(smallutilitiescalledfrommanyplaces\-\-token

counting,outputlengthcapping,recordingmarkers\)gotocrosscut\-X\*ONLY\.Do

NOTaddthemtoconsumingstages\.

\-Afunctionthatusesself\.logger\.XisNOTcross\-cuttingjustbecauseofthat\-\-

assignbyitsprimaryidentity\.

\-Forapi\-surfacemethods\(e\.g\.name\(\),version\(\)\):setfunction\_assignments=\[\]and

granularity="function"\(willberecordedasunmappedapi\_surface\)\.

\-Forsubsystem\-internalfunctions\(intmux\_session\.py/terminus\_\*\_parser\.py/

asciinema\_handler\.py\):assigntothemain\-flowstagethatdrivesthem\.

PURPOSEFIELD\(60\-150words,structuredacross5aspects\)

1\.ACTION:whatthefunctiondoes,concretely\(no"handles"/"manages"\)

2\.INPUTS/STATEREAD:arguments\+self\.\_\*attrsthatdeterminebehavior

3\.OUTPUTS/STATEWRITTEN:returnvalue\+self\.\_\*attrsmutated

4\.WHENINVOKED:whocallsit,underwhatcondition

5\.NON\-OBVIOUS:retrylogic,fallbackpaths,designchoicesareaderwouldmiss

CONSISTENCYWITHCONTEXT

Lookatthecaller/calleecontextprovided\-\-yourclassificationshouldbe

consistentwiththeirstageassignments\.Afunctionthat’sonlycalledfrom

stage\-4\.2’sregiontypicallybelongsnearstage\-4\.2\.

OUTPUT

ReturnONLYaJSONobjectinsidea‘‘‘jsonfencedblock:

\{

"qualname":"<exactqualname\>",

"purpose":"<60\-150word5\-aspectdescription\>",

"granularity":"function"\|"region",

"function\_assignments":\["stage\-X",\.\.\.\],

"regions":\[

\{"line\_range":\[a,b\],"first\_line":"\.\.\.","last\_line":"\.\.\.",

"purpose":"<30\-80word\>","stage\_id":"\.\.\."\},\.\.\.

\]\|null,

"file":"<file\>",

"line\_range":\[<start\>,<end\>\]

\}

Whengranularity=="function",regions=null\.

#### D\.1\.2Reviewing Function Assignments

Each proposed assignment is reviewed by a critic against the source, the stage definitions, and caller/callee evidence\. The reviewer role block \(the “engineer” role\) is followed by the task context, the review evidence, and the proposal under review, then the output rules below\. Reviewers lean toward APPROVE so the pipeline keeps making progress\.

YouareaSENIORENGINEERreviewingaproposedchangetohowafunctionis

classifiedororganizedinahandbookforanAIagentharness\.Yourjobistobe

skepticalandfindrealconcernsrootedincodebehavior\.

Focuson:

\-DoestheproposedclassificationreflectwhatthefunctionACTUALLYdoesatthe

codelevel?

\-Arethelineranges/regionboundariessyntacticallyandsemanticallysound?

\-Doestheproposalmisusecross\-cuttingcategories\(e\.g\.labelingafunction

"crosscut\-X3logging"justbecauseitcallsself\.logger\)?

\-Arecaller/calleerelationshipsconsistentwiththeproposedstagemembership?

YoumayAPPROVE,REVISE\(withconcreteconcerns\),orREJECT\.

DECISIONGUIDELINES

\-APPROVE:theproposalisreasonable,evenifminorwordingcouldbetweaked\.A

correct\-enoughproposalisAPPROVE,notREVISE\.BeGENEROUSwithAPPROVE\.

\-REVISE:onlywhenthereisaSPECIFIC,ACTIONABLEflawthatmateriallyaffects

correctness\(wrongstageassignment,wrongregionboundary,factualerrorabout

thecode\)\.DoNOTREVISEforstyle,phrasing,or"couldbemorethorough"reasons\.

\-REJECT:onlywhentheproposalisfundamentallywrongandrevisioncan’tsaveit\.

BydefaultleanAPPROVE\.Thepipelinemustmakeprogress\.

OUTPUTFORMAT

ReturnONLYasingleJSONobjectwrappedina‘‘‘jsonfencedblock:

\{

"decision":"APPROVE"\|"REVISE"\|"REJECT",

"concerns":\["<concern1\>",\.\.\.\],

"suggested\_revision":\{\.\.\.\}ORnull,

"rationale":"<onesentenceexplanation\>"

\}

Whendecision=="APPROVE",concernsandsuggested\_revisionmaybeempty\.

Whendecision=="REVISE",concernsmustbenon\-emptyANDeachconcernmustpoint

toaconcrete,fixableflaw\.

Whendecision=="REJECT",concernsmustbenon\-empty;suggested\_revisionisnull\.

#### D\.1\.3Generating File Cards

Used infile\-as\-leafPhase II to summarize each scanned file\. In deep mode—where the file is the handbook’s L3 leaf—the model reads the whole file and writes the card content, while the graph\-derived function inventory, line numbers, and call relations are supplied as fixed facts\. The deep\-mode prompt is:

YouarereadingSOURCEFILESINFULLandwritingaplain\-language,easy\-to\-follow

descriptionofeach,forasystemhandbookinwhichtheFILEisthesmallestunit

\(itsleafnode\)\.ThedescriptionyouwriteISthehandbook’scontentforthisfile\.

WHOYOUAREWRITINGFOR:acuriousOUTSIDER\-\-someoneintelligentbutnewtothis

projectandpossiblynotanexpertprogrammerinthisarea\.Theyshouldbeableto

readyourtextandcomeawaygenuinelyunderstandingwhatthisfiledoesandwhyit

matters,WITHOUThavingtoalreadyknowthecodebaseorthejargon\.

HOWTOWRITE\(thismattersasmuchasthecontent\):

\-Useplain,everydaylanguage\.Prefershort,clearsentencesoverdenseones\.

\-ExplaintheWHYandtheWHATinhumantermsbeforeanymechanism:whatreal

problemdoesthisfilesolve,andwhatwouldbreakwithoutit?

\-Whenyoumustuseatechnicaltermoracronym,explainitinplainwordsthe

firsttime\.Neverleavejargonunexplained\.

\-Useabriefeverydayanalogywhenitgenuinelymakessomethingclick\.

\-DoNOTdumpimplementationtrivia\.Favorthebigpictureandintuition\.Itis

finetonamekeytypes/functions,butalwayssaywhatthey’reFORinplainwords\.

\-Stayaccurate\.Simplify,butneversaysomethingthatisactuallywrong\.

\-Avoidemptyfillerlike"handles"/"managesrelatedlogic";bespecific\.

EachfilealsocomeswithitsFUNCTIONLIST\(qualname\+linerange\),derivedfrom

thecallgraph\.Thefunctioninventory,linenumbers,andcallrelationsare

FACTS\-\-doNOTre\-listthem\.Yourjobistheplain\-languageprose\+an

easy\-to\-understandnoteperfunction\(referencedbyitsexactqualname\)\.

ForEACHfilereturn:

\-"purpose":1\-2plainsentencesanewcomercanunderstand:whatthisfileisfor\.

\-"description":anaccessiblewalkthrough\(roughly120\-300words\):whatproblem

thisfilesolvesandwhyitexists;whatitdoes,stepbystep,inplain

language;howitsmainpiecesworktogether;andanysurprisingbehavior\.

\-"functions":oneentryperfunctioninthefile’sfunctionlist,referencedby

itsexact"qualname",eachwith:

\-"purpose":inplainwords,whatthisfunctiondoesandwhy\(1\-3sentences\)\.

\-"data\_flow":whatgoesIN\-\>whatitdoes\-\>whatcomesOUT,toldasasimple

before/afterstoryanon\-expertcanfollow\.

\-"relations":howitfitsintothebiggerflow\-\-whocallsitandwhen,and

whatithandsoffto,groundedintheprovidedcalls/called\-byfacts\.

\-"role":EXACTLYoneof:entrypoint,orchestration,domain\_logic,io\_transport,

data\_model,config,util,test,generated,other\.

\-"lifecycle":SHORThintofwhenintherunthisfileisactive\(e\.g\."startup",

"configload","mainloop","requesthandling","teardown","cross\-cutting"\)\.

OUTPUT\-\-ONLYaJSONobjectina‘‘‘jsonblock:

\{

"purposes":\[

\{"file":"<exactpath\>","purpose":"\.\.\.","description":"\.\.\.",

"role":"<role\>","lifecycle":"\.\.\.",

"functions":\[

\{"qualname":"<fnqualname\>","purpose":"\.\.\.","data\_flow":"\.\.\.",

"relations":"\.\.\."\},\.\.\.\]\},

\.\.\.

\]

\}

Returnoneentryperfilegiven,usingtheexactfilepathsprovided\.

#### D\.1\.4Synthesizing the L1–L3 Document Tree

The two modes synthesize the document tree differently\. Infunction\-as\-leafmode, each L1, L2, and L3 node is produced by a bounded actor–critic–reflexion loop: an actor drafts the node from grounded inputs, a critic scores it against a tier\-specific rubric and returns actionable findings, and the actor revises until the rubric passes, the score stops improving, or the generation budget is reached\. L1 and L2 use long, tier\-specific writing guides \(a whiteboard\-tour style for L1; a problem/main\-flow/state\-flow/hand\-off structure for L2\)\. Infile\-as\-leafmode, the validated file cards from Appendix[D\.1](https://arxiv.org/html/2607.13285#A4.SS1)already are the L3 content, and a single\-pass rollup produces the L2 component overviews and the L1 system overview\.

The L3 \(function\-as\-leaf\) entry is emitted against the output schema below, grounded in the exact source range\(s\); a multi\-region variant returns one gloss per region with function\-level design decisions and relations\.

\#\#Outputformat\(single\)

ReturnaJSONobjectinsidea‘‘‘jsonfence:

‘‘‘json

\{

"schema\_version":1,

"type":"single",

"locator\_role":"<one\-lineroletag,6\-15words\>",

"stage\_context":"<2\-4sentences:whatrolethisplaysinthestage;whenitis

invoked;howitrelatestoitssiblings\>",

"synopsis":"<2\-4sentences:What\+inputs\+outputs\+sideeffects\>",

"interface":\{

"signature":"<fullsignature,e\.g\.\(self,environment\)\-\>None\>",

"params":\[\{"name":"<param\>","type":"<type,or?ifunclear\>",

"role":"<one\-linerole/source\>"\}\],

"reads\_state":\["<self\.\_attributesthisfunctionreads\>"\],

"returns":"<whatitreturns;ifNone,statetherealproduct\(sideeffect\)\>",

"side\_effects":\["<self\.\_attributeswritten/externaleffects\>"\]

\},

"execution\_flow":\[

"<step1:action\+whichargs/state\+what’sproduced\>",

"<step2:\.\.\.\>"

\],

"design\_decisions":\[

"<decision1:thetrade\-offpoint\+whythischoice\+whatanalternativecosts\>",

"<decision2:\.\.\.\>"

\],

"relations":\{

"callers":\["<qualnameorbriefdescription\>"\],

"core\_callees":\["\.\.\."\],

"config\_state\_sources":\["\.\.\."\],

"results\_to":\["\.\.\."\],

"siblings":\[\],

"register\_interactions":\[

\{"action":"write\|read\|clear\|reset","register":"reg\-<id\>",

"note":"<5\-12words:when/why\>"\}

\]

\}

\}

‘‘‘

Countconstraints:

\-interface\.signature:required,copiedaccuratelyfromthesource\.

\-interfaceparams/reads\_state/returns/side\_effects:listthemallfromthe

source;emptyarray/"none"iftherearenone\.

\-execution\_flow:2\-8steps;design\_decisions:1\-5items\.

\-relations\.\{callers,core\_callees,config\_state\_sources,results\_to\}:atleast4

ofthesemustbenon\-empty\.

\-relations\.register\_interactions:listeveryregisterthisfunction

reads/writes/resets;emptyarray\[\]onlyifitinteractswithnone\.

### D\.2BGPD Localization and Planning

This is the planner prompt used under BGPD in the Handbook\-Assisted arm: it localizes by routing through the handbook and then verifying candidate edit sites against the real source before emitting a self\-contained edit plan\. Per\-harness fields substituted at runtime are shown as\{\{\.\.\.\}\}placeholders\.

YouareaseniorsoftwareengineerPLANNINGachangeto\{\{PROJECT\_INTRO\}\},on

behalfofacodereviewer\.

YouaregivenONEnatural\-languagechangerequest\.Inthisphaseyouproducea

precise,SELF\-CONTAINEDPLANoftheedits\-\-youdoNOTeditanyfiles\.Aseparate

executorwillapplyyourplanMECHANICALLY:foreachedititwillsubstituteyour

exactOLDtextwithyourexactNEWtext,WITHOUTre\-readingthefile\.Soyour

plan’sverbatimtextmustbebyte\-exact\.

\#\#Twoartifacts,twodistinctroles

\-ThehandbookisapureLOCATIONINDEXoftheharness,NOTadescriptionofthe

code\.Eachfunctionappearsasaone\-linelocator:‘<summary\><b\>Qualified\.name</b\>

\-\-file:start\-end\.one\-linerole</summary\>‘,optionallyfollowedbyaRelations

block\(callers/callees/registerread\-writesites\)\.AcardhasNOfunctionbodyand

NOsourcecode\.Ontopofthat,‘index\.md‘listseverystagewithitsfunction

locatorsand‘registers\.md‘listseverystatevariablewithitsexactread/write

codesites\.UsethesetodecideWHICHfiles,functionsandsitesareinscope\-\-

theysurfacescattered,non\-obvioussites\(mirrorcopiesintheother

parser/template,aregister’severyread/write,cross\-subsystemtouchpoints\)

thataplaintextsearchcanmiss\.

\-TherealsourcecodeistheGROUNDTRUTHforWHATtochange\.Thehandbooktells

youtheADDRESS\(file:start\-end\);thecodeatthataddressistheonlyreliable

sourceoftheactualstructure\.YouMUSTreadtherealsource\.

\#\#Howtoplan\-\-ROUTEwiththehandbook,READtherealsource,EMITverbatimedits

1\.Understandtherequest’strueintent:thebehaviordelta,andthe

state/conditions/valuesitfixes\.

2\.Routewiththehandbook\.Readits‘SKILL\.md‘,then‘index\.md‘,thenonlythe

‘stages/<id\>\.md‘chaptersand‘registers\.md‘entriesyourintentpointsto\.

Assemblethecandidateset:everyfile\+function\+anchorthechangemusttouch\.

Watchforscattered/mirrorsites\(aparserchangeusuallyhasatwinintheOTHER

parserandinbothprompttemplates;astatechangefansouttoeveryreadsite

listedunderthatregister\)\.

3\.ReadtheREALsourceofeverysiteyouintendtoeditwith‘read\_file‘onthe

actualcodefiles\.Confirmtheexactbody,controlflow,conditions,andthatthe

sitedoeswhatthecardimplied\.

4\.ForEACHedit,produceaself\-containedEDITBLOCK\(formatbelow\)whose

‘old\_string‘iscopy\-pastedverbatimfromthe‘read\_file‘outputyoujustsaw\-\-

neverretypedfrommemory,neverparaphrased\.Matchwhitespaceandindentation

exactly,andincludeatleast3linesofcontextBEFOREandAFTERthechanged

linessothesnippetisUNIQUEinthefile\.

5\.Achangecanalsosilentlybreaksomethingtherequestnevermentions;ifyou

findsuchacoupledassumption,addanedit\(ornoteit\)accordingly\.

6\.Onlyincludeeditsyouareconfidenttherequestrequires\.

\#\#EDITBLOCKformat\(theexecutorappliesthesedirectly\)

Foreveryedit,outputexactly:

\#\#\#EDIT<n\>

\-file:‘<pathrelativetotheworkingdir,e\.g\.\{\{PATH\_EXAMPLE\}\}\>‘

\-where:‘<\{\{WHERE\_EXAMPLE\}\}\>‘\-\-whythischange

‘‘‘old

<EXACTcurrenttext,copiedverbatimfromread\_file\-\-whitespace\-perfect,unique\>

‘‘‘

‘‘‘new

<thereplacementtext\-\-correct,idiomatic,thesmallestchangethatrealizestheintent\>

‘‘‘

Rulesfortheblocks\(theexecutortruststhemblindly,soprecisionisonyou\):

\-‘old‘MUSTbebyte\-exacttothefile’scurrentcontent\.Ifyouarenotcertainit

isverbatim,‘read\_file‘thatregionagainbeforewritingtheblock\.

\-Keepeach‘old‘theSMALLESTspanthatisstillunique\(1\-8linestypically\);do

notpastewholefunctions\.

\-SAME\-FILEeditsmustNOToverlap\.Theexecutorappliesyourblocksinorder

againsttextthatearlierblockshaveALREADYchanged,anditdoesnotre\-read

betweenthem\.Sonoblock’s‘old‘\(includingitscontextlines\)maycontainaline

thatanotherblockinthesamefilechanges\-\-otherwisethesecondmatchwillbe

stale\.Iftwochangesarecloseenoughthattheircontextwouldoverlap,MERGE

themintoONEblockcoveringboth\.Ordersame\-fileblockstop\-to\-bottom\.

\-Forabrand\-NEWfile,useasingleblockwithanempty‘‘‘old‘‘‘andthefull

contentin‘‘‘new‘‘‘,andsay"\(newfile\)"in‘where‘\.

\-Anchoronstablelines;neverlet‘old‘spanaregionyouareunsureof\.

Whendone,call‘complete\_task‘with:ashortprosesummaryoftheedits,thenALL

theEDITblocks,thenthedeclarationsJSON\.DoNOTeditanyfilesinthisphase\.

\#\#Declarations\(machine\-readable\-\-thehandbook\-resyncpipelineconsumesthis\)

EndwithEXACTLYone‘‘‘jsonblockdeclaringthechange\-setatFUNCTION

granularity,using\{\{QUALNAME\_NOTE\}\}:

‘‘‘json

\{\{DECL\_JSON\}\}

‘‘‘

\-‘will\_modify‘\-\-everyEXISTINGfunctionwhoseimplementationyoureditschange\.

\-‘will\_add‘\-\-everybrand\-newfunctionintroduced\.

\-‘will\_remove‘\-\-everyfunctiondeletedoutright\.Arename=remove\(old\)\+add\(new\)\.

### D\.3LLM Judging

Plan quality is scored in two steps\. The judge first builds a leakage\-safe answer key from the request and pristine source, before seeing any plan, and then scores each plan independently against that key\.

#### D\.3\.1Building the Answer Key

The judge builds a leakage\-safe answer key from the request and pristine source before seeing any plan \(hint fields are stripped from the request\)\. This is the Terminus\-2 judge; the Codex judge mirrors it, usingcorrect\_approachin place ofcorrect\_localization\.

\[SYSTEM\]

YouareanexpertPythonengineerbuildingagradingANSWERKEYforacode\-change

taskontheTerminus\-2Pythonagentharness\.

YouareNOTlookingatanysolutionyet\.Readthepristinesourceandindependently

determinewhichconcretefiles,functions,methods,branches,templates,orstate

variablesacorrectsolutionmustlocalizebeforeediting\.

OutputONLYthisJSONobject:

\{"required\_sites":\["<concretefile/function/branch/template/statesite\>"\],

"correct\_localization":"<2\-4sentences:wheretheplannershouldlookandwhy\>",

"pitfalls":\["<easilymissedmirror/fallback/cold/state/templatesites\>"\]\}

\[USER\]

\#\#CHANGEREQUEST

\{query\}

\#\#PRISTINETERMINUS\-2SOURCE

\{pristine\}

Buildthelocalizationanswerkeynow\.OutputtheJSONobjectonly\.

#### D\.3\.2Scoring the Plan

Each plan is scored independently against the answer key on a0\.00\.0–5\.05\.0scale in0\.50\.5steps\. The three dimensions are combined with weights0\.500\.50\(localization\),0\.250\.25\(scope\_bloat\), and0\.250\.25\(reasoning\);scope\_bloatis reported as Scope Control, where a higher value means a more focused plan\.

\[SYSTEM\]

YouareanexpertPythonengineerGRADINGtheLOCALIZATIONqualityofoneplanner’s

PLANforacode\-changetaskontheTerminus\-2Pythonagentharness\.

YoujudgethePLANONLY:whichfiles/functions/state/templatesitesitdecidesto

inspectormodify,andwhetheritsreasoningisgrounded\.DoNOTgradethefinal

codedifforexecutioncorrectness\.Theexecutorissharedacrossarmsandisout

ofscope\.

Gradethesedimensionsfrom0\.0to5\.0in0\.5steps:

\-localization:didtheplanidentifyALLrequiredimplementationsitesinthe

answerkey,includingmirror,fallback,cold\-path,state\-reset,

andtemplatesites?

\-scope\_bloat:didtheplanavoidunrelatedfiles/functionsoroverlybroad

edits?5meanstightlyscoped;lowmeansitwanderedinto

irrelevantareas\.

\-reasoning:istheplan’slocalizationreasoninggroundedintherealcodeand

request,ratherthanvague,circular,orguessed?

OutputONLYthisJSONobject:

\{"localization":X,"scope\_bloat":X,"reasoning":X,

"justification":"<<=60words:decisivelocalizationhit/miss\-\-whichsitesfoundormissed\>"\}

\[USER\]

\#\#CHANGEREQUEST

\{query\}

\#\#ANSWERKEY

\{answer\_key\}

\#\#PRISTINETERMINUS\-2SOURCE

\{pristine\}

\#\#THISARM\-\-plan\.md

\{plan\}

Gradethisarm’sPLANlocalizationagainsttheanswerkey\.OutputtheJSONobjectonly\.

## Appendix EIllustrative Handbook\-Assisted Planning Walkthrough

This appendix walks through one real Handbook\-Assisted run on Terminus\-2 \(caseQ1, DeepSeek\-V4\-Pro planner\), reconstructed from its recorded trace\. The run makes concrete the two moves at the heart of BGPD: the planner first*routes*through the handbook to decide which code sites are in scope, and then*verifies*each candidate against the live source before writing a plan\. Every tool call, source locator, and edit shown below is taken from the run; only whitespace is trimmed\.

Change request \(Q1: triple completion confirmation\)Right now the model only has to marktask\_completeonce to reach the “are you sure?” step, then once more to get graded\. I want a higher bar: the model must mark completionthree consecutive timesbefore we actually grade\. The first two times just re\-show the terminal state and ask “are you sure you want to submit?”\.

The request is Query\-type: it revises an existing control\-flow rule but names no file or function\. The planner’s first task is therefore one of localization — finding every site that implements the completion handshake\.

Phase 1 — Route through the handbookGuided by theSKILL\.mdpolicy, the planner reads the handbook top\-down, narrowing the scope before opening any source:1\.SKILL\.md→\\rightarrowoverview\.md\(L1\)→\\rightarrowindex\.md: locate the stage that owns per\-iteration continuation and termination\.2\.stages/stage\-4\.8\.md\(Completion Gate\) andstages/stage\-4\.7\.md\(Command Execute\): the handshake lives in the gate\.3\.registers\.md: the gate is backed by the state registerreg\-pending\-completion, whose read and write sites span the loop, initialization, and per\-run reset\.Two facts fall out of this\. The change is confined to a single stage \(Completion Gate\) and a single register; and the register’s write sites reveal that initialization and per\-run reset must change together with the loop, not just the obvious return branch\.

Phase 2 — Verify against the live sourceBecause the handbook is a pure location index and stores no source, the planner now opens the realterminus\_2\.pyto confirm each locator\. Onesearch\_file\_contentfor\_pending\_completionreturnsseven occurrences, all interminus\_2\.py, so the change stays within one file\. Reading them shows a single Boolean flag that is set on the first completion mark, tested before returning on the second, and cleared on any non\-completion turn and at the start of each run\. This resolves the handshake to three concrete sites:•Terminus2\.\_\_init\_\_\(∼\\simL292\) — initializes the flag\.•Terminus2\.\_reset\_per\_run\_state\(∼\\simL1574\) — clears it per run\.•Terminus2\.\_run\_agent\_loop\(∼\\simL1427–1440, L1552–1559\) — the observation branch and the completion gate that read and write it\.

##### Edit plan\.

With the sites confirmed, the plan replaces the Boolean\_pending\_completionwith an integer counter\_completion\_confirmations: the loop increments it on each completion mark, resets it on a non\-completion turn, and returns for grading only on the third consecutive mark\. The change set is four*modify*actions, all interminus\_2\.py— initialization, per\-run reset, and the loop’s two branches\. The completion gate itself is the representative edit:

Before— two\-mark Boolean handshake:

ifis\_task\_complete:

ifwas\_pending\_completion:

\#secondtask\_complete:confirmed,gradenow

return

else:

\#firstattempt:asktoconfirm,continue

prompt=observation

continue

After— three\-mark counter:

ifis\_task\_complete:

ifwas\_completion\_confirmations\>=2:

\#thirdconsecutivetask\_complete:confirmed,gradenow

return

else:

\#firstorsecondattempt:asktoconfirm,continue

prompt=observation

continue