Summary / 03. Repository reconnaissance / Document
Paper 2026-09-04
Shared copy: the operator's name and machine names are replaced by roles. Nothing else is changed.
Rendering…
# Reading the Map Before You Dig: Deterministic, Graph-Backed Repository Reconnaissance for a Weak-Model Coding Harness *Component 03 of 27 — Coding-Harness Program. This document specifies the repository-reconnaissance stage that sits beneath the Action-Calling Interface (component 01) and the tool-calling policy (component 02). It is written to drive a reversible build; the executable specification follows in a companion document.* --- ## Abstract Repository reconnaissance — determining what a codebase is and which portions are relevant before the first edit — is usually treated as incidental exploration that the model does on the fly. This paper argues it should be deterministic-first and graph-backed. The harness constructs two artifacts entirely in code, before the language model runs: an evidence-backed repository manifest (build, test, package, and layout architecture) and a line-level structural dependency graph of definitions and references. Retrieval is then demand-driven: a deterministic gate decides whether any cross-module context is needed at all, and only on positive evidence does the harness escalate through a bounded ladder of retrieval levels, ultimately exposing a k=1 ego-graph of roughly twelve nodes rather than the repository. For a weak model on CPU-only hardware, this allocation is forced: every node in the manifest, the graph, the gate, and the retrieval path is deterministic software (tree-sitter/ast, milliseconds to seconds), and the model receives only a tiny, structurally-grounded slice. The paper derives five design principles from the retrieval, graph, and measurement literature, specifies a concrete architecture with every node labeled deterministic or learned, states a token budget, and defines a reconnaissance-only evaluation protocol. ## 1. Introduction The coding-harness program decomposes the problem of software engineering into a sequence of questions. Component 01 asked the first: *given the code, how do I interact with it?* — and answered with an Action-Calling Interface, a menu of primitives and their side-effect contracts. Component 02 asked the second: *how do I choose an action?* — and answered with a tool-calling policy, a sequential decision procedure that acts rarely and verifies what it is told. This paper asks a question that is logically prior to both: *before any of that, what is this repository, and which parts of it matter?* Component 03, repository reconnaissance, is the stage that produces the map from which the interface of component 01 and the decisions of component 02 are read. The reason reconnaissance deserves its own stage — rather than being folded into "the model looks around first" — is that skipping it produces a distinctive and predictable family of failures. A model that has not established what a codebase is will hallucinate APIs and imports that do not exist, calling functions that were never defined and importing modules that were never shipped. It will reimplement helpers that already exist, duplicating a parser or a serializer it never learned was present. It will edit vendored or third-party code as if it were first-party, corrupting dependencies it should have recognized and left alone. It will operate at the wrong layer — patching a symptom in a caller when the defect lives in a callee, or vice versa. And it will guess at the test runner, the build command, and the entry point, so that its one reliable source of ground truth — execution — is never actually invoked. Each of these failures is a localization error in the widest sense: an error about where the work is and what the code is, made before a single token of a fix is written. These failure modes are not theoretical, and they are not the model's fault. They are the consequence of a specific resource regime. The model is weak: it has limited capacity for multi-step planning, for holding a large repository in working memory, and for recovering from its own misreadings. The hardware is CPU-only, which makes every forward pass and every token of context a real cost rather than an accounting detail. The operating bias is agentless-first: the harness should prefer not to act, and should prefer the minimal action when it does act. Under these constraints the reconnaissance stage cannot be a prompt that says "explore the repository carefully," because that instruction asks the weakest component of the system — the model — to do the most expensive work. It must instead be a deterministic pipeline that hands the model a finished map and asks it only to read the map. This inversion is the paper's central claim. The map — the manifest and the dependency graph — is built by deterministic software, because building a map is structural work and structure is exactly what tree-sitter and abstract syntax trees do in milliseconds. The reading of the map — deciding which region is relevant to a task — is also, in the first instance, deterministic, because relevance can be read off cheap signals: an unresolved symbol, a cross-file import, the location of a failing test, a configuration reference. Only the final step, interpreting the small retrieved slice and forming a hypothesis about what to do next, is genuinely language-model work. The literature reviewed in Section 2 supports this allocation with unusual unanimity, and Section 5 turns it into a concrete architecture. The paper proceeds as follows. Section 2 reviews related work across three groups — retrieval mechanics, graph and structure, and measurement — with a reference-only note on the two ancestors already treated in component 01. Section 3 derives five design principles. Section 4 specifies the architecture, labeling every node deterministic (D) or learned (L) and stating the token budget. Section 5 states the recursive self-improvement protocol. Section 6 gives the measurement plan. Section 7 concludes. ## 2. Related Work The literature divides into groups that map onto the reconnaissance stage's three questions: how to retrieve relevant context (retrieval mechanics), how to represent the repository's structure (graph and structure), and how to score reconnaissance separately from coding (measurement). ### 2.1 Retrieval mechanics **RepoCoder** [1] is the founding result on repository-level retrieval for code completion, and its central insight is that *iteration*, not retriever quality, is the lever. Its Iterative Retrieval-Generation (IRG) framework alternates: retrieve relevant snippets, draft a continuation using them, then re-retrieve using the draft as the query. The second pass closes the similarity gap between the sparse initial query and the actual need, because the draft encodes information about what the model now believes it needs. The evidence that the retriever is not the bottleneck is striking: a sparse Jaccard/token retriever performs approximately as well as a dense one, and iteration two captures nearly all of the gain — additional iterations add little. The headline for this paper is the substitution effect: CodeGen-350M with RepoCoder's cheap retrieval approximately matches GPT-3.5-Turbo on the in-file setting. Cheap, deterministic retrieval buys back model size — which is precisely the trade this program wants to make, since model size is the one resource it cannot afford. RepoCoder's evaluation corpus, RepoEval, spans 14 repositories and roughly 3,573 samples, and it is the direct template for the reconnaissance-only probes of Section 6. **RepoBench** [2] (Liu et al.) supplies the measurement discipline. It decomposes repository-level code completion into three independently scored subtasks — RepoBench-R (retrieval), RepoBench-C (completion), and RepoBench-P (pipeline) — so that *finding* the relevant context is measured separately from *using* it. Its empirical conclusions invert a natural assumption. Retrieval, measured alone, is easy and low-stakes: even random cross-file context helps on average, which means the retrieval score alone overstates competence. The real bottleneck is generation-with-context — the model's ability to use the retrieved material once it has it. And the context has to be *placed* correctly: relevant snippets must sit adjacent to the completion point, or the model fails to use them — an early statement of what later work calls lost-in-the-middle. The implication for reconnaissance is that the stage's job is not merely to find the region but to position it, in a compact and local form, directly against the point of need. **Repoformer** [3] is the cautionary complement to RepoCoder's enthusiasm. Its claim is that retrieval is *not automatically beneficial*: across the relevant cases, only about 20% of retrievals actually help, and the rest are wasted tokens at best and distractions at worst. The constructive result is that retrieval can be made selective with large savings: roughly 70% inference-latency savings from retrieving only when warranted, and greater than 85% abstention accuracy — the system correctly declines to retrieve in the cases where retrieval would not help. Repoformer-3B with selective retrieval approximately matches the far larger StarCoder-16B, the same substitution effect RepoCoder reports, now achieved by *withholding* context rather than adding it. The decisive point for this paper is methodological: Repoformer's decision about whether to retrieve can be implemented deterministically. A level-0 gate keyed on signals such as an unresolved symbol, a cross-file import, a failing-test location, or a config reference is a faithful, non-learned implementation of Repoformer's abstention logic. A weak model need not be asked to decide whether it needs help; the signal is read off the repository. ### 2.2 Graph and structure **RepoGraph** [4] is the closest prior art to the architecture of Section 4. It builds a line-level definition/reference graph with two edge types — *invoke* (a call site to a definition) and *contain* (a definition to its enclosing scope) — entirely deterministically with tree-sitter, in three steps: parse every file, filter out builtins, standard-library, and third-party symbols, and organize the remainder into the graph. Retrieval is then a k-hop ego-graph around the relevant entity. The shape of that ego-graph is the paper's most important number: at k=1 it averages roughly 11.6 nodes and 37.1 edges; at k=2 roughly 54.5 nodes and 89.9 edges. RepoGraph adds +2.34 absolute points to the Agentless baseline on SWE-bench-Lite (27.33% to 29.67%), and improves localization at every granularity: file-level 68.7 to 74.3, function-level 51.0 to 54.0, line-level 34.3 to 36.7. Two findings carry the lesson. First, the k=1 flattened graph is best; the k=2 flattened graph *hurts*, dropping to 26.0% — below the baseline. Less is more, and the deeper graph is not merely wasteful but actively harmful. Second, the construction is cheap: milliseconds per file, a one-time offline parse, and it transfers to DeepSeek-Coder-V2-Lite — a weak model, by the standards of the field. RepoGraph is, in effect, proof that the deterministic, graph-backed, smallest-relevant-subgraph design of this paper is not an aspiration but a demonstrated result. **LocAgent** [5] extends the same idea to a richer graph and a sparser index. Its directed heterogeneous graph includes directories, files, classes, and functions, with contain, import, invoke, and inherit edges. Its index is built without embeddings — a fully-qualified-name index, a name dictionary, BM25, and code chunks — and is constructed in seconds. It exposes exactly three tools — SearchEntity, TraverseGraph, and RetrieveEntity — and, decisively for a weak model, renders graph output as a *tree*, which language models reason over more reliably than edge lists. The numbers are strong: file-level Acc@5 of 92.7 to 94.16%, an 86% cost reduction, and a +12% downstream Pass@10. LocAgent's contribution to this paper is the confirmation that a sparse, seconds-to-build index and a tree-shaped rendering are sufficient for graph-guided localization — no embeddings, no dense retrieval, no GPU. **RIG** — the Repository Intelligence Graph [6] — moves one level up, from the code graph to the *architectural* map. It is a deterministic map of components, aggregators, runners, tests, external packages, and package managers, with dependency and test-coverage edges, and every fact carries a file:line evidence pointer. Its output is a roughly 5K-token flat JSON — a shape that fits comfortably in a weak model's context window. RIG reports a +12.2% improvement in architecture-question accuracy, a 53.9% reduction in completion time, and a 57.8% reduction in seconds-per-correct answer, with the largest win on medium-difficulty questions, which collapse into single lookups. Its stated limitation is instructive: the SPADE extractor is CMake/CTest-centered, and non-CMake build systems must be authored manually — a warning that the manifest of Section 4 must be written per-ecosystem rather than assumed universal. RIG is a 2026 preprint and is flagged as such here. **SeeRepo** [7] ("LLM Agents Can See Code Repositories") renders repository structure as an *image* for a multimodal agent, reporting a 26% token reduction. It is noted here for completeness and set aside: the image modality presupposes a vision-capable model and is not the CPU path this paper targets. Its value is the reminder that the *representation* of the map — text, tree, image — is itself a lever, and that the tree rendering LocAgent chose is one point on a spectrum this harness can revisit. ### 2.3 Measurement **SWE-Explore** [8] isolates exploration — given a repository and an issue, rank the relevant code regions under a fixed line budget — as its own task, across 848 issues, 10 languages, and 203 repositories, with ground truth derived from at least two successful agent trajectories per issue. Its central finding is that exploration metrics *strongly track* downstream repair: Context Efficiency correlates with repair at Pearson r=0.950, and recall-at-100 correlates at Spearman ρ=0.845. This is the empirical warrant for Section 6's insistence that reconnaissance be scored separately yet validated against the repair it enables. SWE-Explore is a June 2026 preprint and is flagged as such. Two ancestors are already treated in component 01 and are cited here only for lineage. **AutoCodeRover** [9] established the structure-aware retrieval baseline, and **Agentless** [10] established hierarchical localization — file-level, then code-block-level — as a deterministic pipeline. Both are the scaffolding on which RepoGraph's graph construction and this paper's manifest-plus-graph design are built. ## 3. Design Principles Five principles follow from the review, each tied to the evidence above. **P1 — Deterministic-first.** The manifest and the dependency graph are built in code, before the language model runs. The model never reverse-engineers the build system from a directory listing, never reconstructs symbol relationships from a pile of snippets, and never guesses the test runner. This is the direct transfer of RepoCoder's finding that the retriever is not the lever [1] and RepoGraph's that the graph is a milliseconds-per-file, one-time parse [4]: the map is structural work, and structural work is done by deterministic software. The model is a consumer of the map, not its author. **P2 — Graph-backed.** Navigation proceeds over a structural graph — definitions, references, containment, imports — not over blind text or embedding similarity. RepoGraph [4] and LocAgent [5] both show that a graph built by tree-sitter and indexed by names and BM25 is sufficient, and LocAgent's seconds-to-build sparse index shows that dense embeddings add cost without adding capability [5]. A weak model that reasons over a tree-shaped rendering of a graph outperforms one left to reason over raw files; the graph is the interface that compensates for the model's weakness. **P3 — Demand-driven.** Retrieval is selective, not automatic. Repoformer's finding that only about 20% of retrievals help [3] is the governing constraint: the default is to retrieve nothing, and a level-0 deterministic gate decides whether *any* cross-module context is needed at all. Only on positive evidence does the harness escalate through the retrieval ladder R0→R4, each step gated on the previous step's evidence. This is Repoformer's abstention logic implemented non-learnedly [3], and it is what makes the weak model's context budget go further than a strong model's. **P4 — Smallest-relevant-subgraph.** What is exposed is a k=1 ego-graph — roughly a dozen nodes — plus skeleton signatures, never the whole repository. RepoGraph's result that the k=1 flattened graph is best and the k=2 flattened graph is actively harmful (26.0%, below baseline) [4] is the strongest possible statement of this principle: more context is not merely wasteful, it degrades the model. The principle is the reconnaissance-stage instance of component 01's finding that windowed viewing beats full-file dumps. **P5 — Measured-separately.** Reconnaissance is scored as its own task — did the harness surface the gold region under budget? — independently of whether the eventual patch is correct. RepoBench's separation of retrieval from completion [2] and SWE-Explore's isolation of exploration [8] are the templates; the correlation evidence (r=0.950 for Context Efficiency) [8] is the guarantee that the separated score still predicts the thing that matters. ## 4. The Architecture The stage produces two artifacts and then retrieves. Every node is labeled deterministic (D) or learned (L); the design target is that the manifest, the graph, the gate, and the retrieval ladder are all D, and only the final "what does the model decide to inspect next" is L. **(1) Deterministic scan → two artifacts (D).** The first pass walks the repository and emits the *repository manifest*: build system and commands, test framework and runner, package manifest and dependency set, layout and entry points, and the governing conventions. This is RIG's architectural map [6], implemented per-ecosystem (the CMake/CTest-centrism of RIG's SPADE extractor [6] is the explicit caution: each ecosystem — CMake, npm, pip, cargo, Maven — gets its own parser rather than a universal one). The manifest is a flat, evidence-backed JSON on the order of 5K tokens, with a file:line pointer for every claim, sized to sit inside a weak model's context without crowding out the task [6]. The second pass emits the *line-level code graph*: a definition/reference graph with invoke and contain edges (RepoGraph's design [4]), built by tree-sitter in three steps — parse every file, filter builtins, standard-library, and third-party symbols, and organize the remainder — with the sparse name-and-BM25 index of LocAgent [5] for lookup. Construction is milliseconds per file and done once, offline. **(2) Demand-driven retrieval (D-gated, L-leaf).** Retrieval is a ladder, and the first rung is a gate. The *level-0 deterministic gate* inspects the task against the manifest and graph for any of: an unresolved symbol, a cross-file import, a failing-test location, a dependency edge, a config reference, or a task that names a component outside the current module. If none fires, the harness retrieves *nothing* — the model works in the current module alone, honoring Repoformer's finding that most retrievals do not pay [3]. If the gate fires, the harness escalates, each rung gated on the previous rung's evidence: - **R0** — the task plus the named entity (the symbol or file the task references); - **R1** — the local map: the entity's own scope and immediate neighbors; - **R2** — the dependency neighborhood: a k=1 ego-graph over the invoke/import edges, roughly a dozen nodes and about forty edges [4]; - **R3** — the subsystem: the containing component and its aggregators and runners [6]; - **R4** — repository-wide: the manifest and global entry points, reached only on explicit cross-subsystem evidence. At every rung the injected context is a *tree-encoded* k=1 ego-graph plus skeleton signatures — signatures, not bodies, per Agentless's skeleton-localization result [10] — and the rendering follows LocAgent's tree form, which models read better than edge lists [5]. **(3) The injected slice and the budget (D).** The label discipline is the point. Manifest, graph, gate, and retrieval are all deterministic; the only learned node is the model's decision, on seeing the retrieved slice, about what to inspect next — and even that decision is expressed through the bounded primitives of component 01 rather than free exploration. The token budget is explicit: the manifest is roughly 5K tokens and is injected once; the retrieved subgraph is bounded at roughly 12 nodes and 40 edges, rendered as a tree; the total reconnaissance context handed to the model at any moment is on the order of a few thousand tokens, leaving the rest of the window for the task and the patch. The k=2 flattening is deliberately excluded — RepoGraph shows it is worse than nothing [4]. ## 5. Recursive Self-Improvement Protocol This is component 03 of a 27-component program, and it follows the discipline of components 01 and 02. The specification is written against the complete stage — the 100% target: full manifest coverage across all ecosystems in the corpus, the full line-level graph, and the complete R0→R4 ladder. The first implementation round is expected to land at roughly 80%, with the gap concentrated in the least-common ecosystems (the manually-authored non-CMake manifest parsers RIG itself defers [6]) and the deepest rungs of the ladder. Every change is A/B-gated: a candidate revision of the gate's signal set, the ego-graph radius, or the manifest schema is deployed behind a gate and accepted only if it improves the metrics of Section 6 on a fixed evaluation sample. The stage is reversible by construction — each node is a swappable module — so a regression is a rollback, not a rewrite. ## 6. Measurement & Evaluation Reconnaissance is graded on reconnaissance, not on the patch. Three instrument families do the grading. **Ranked-region recall under a line budget (RepoBench-R / SWE-Explore style).** Given a repository and a task, the harness must rank code regions under a fixed line budget. The scores are recall-at-k against the gold region, and Context Efficiency — the fraction of the budget spent on the gold region. The ground truth is derived, in SWE-Explore's manner, from multiple successful agent trajectories [8]; the correlation evidence (Context Efficiency r=0.950) is the validation that this proxy tracks repair [8]. **The deterministic-questions battery.** Because the manifest claims to answer architectural questions, it must be interrogated: *where are the tests for Foo? what module defines Bar? what command builds this? which config selects the database? which files does changing API X plausibly affect?* These are the questions RIG measures [6], and they are graded for correctness against the file:line evidence pointer rather than against model output — a pure test of the deterministic artifact, runnable without the model at all. **The gate's selectivity.** The level-0 gate is tested for abstention accuracy in Repoformer's sense [3]: on a sample of tasks, the gate should decline to retrieve where retrieval would not help, and retrieve where it would. The metric is the fraction of retrievals that actually changed the downstream outcome, with the ~20% figure [3] as the field's reference point, not a target to be assumed. Two honesty constraints close the section. First, the absolute numbers above were measured on models far stronger than this harness's; they are directions, not guarantees, and the reconnaissance-only battery must be run on the weak model itself. Second, the meta-hypothesis to be tested alongside the stage is the ordering claim: that *deterministic graph construction, selective retrieval, and the smallest-relevant-subgraph all survive the transfer to a weak model even though the absolute numbers do not*. If the ordering holds — and RepoGraph's transfer to DeepSeek-Coder-V2-Lite [4] is the encouraging precedent — the design is sound and needs only threshold tuning. If it inverts, the architecture's modularity means the correction is a parameter change, not a redesign. ## 7. Conclusion Repository reconnaissance is the stage that precedes every edit, and its failure modes — hallucinated APIs, reimplemented helpers, edited vendored code, the wrong layer, the unknown test runner — are localization errors made before the first token of a fix. For a weak model on CPU-only hardware, the stage cannot be a prompt; it must be a pipeline. The map is built by deterministic software — a 5K-token evidence-backed manifest and a line-level definition/reference graph, both constructed in milliseconds by tree-sitter and AST tooling. Retrieval is demand-driven: a deterministic gate decides whether any context is needed, and only on positive evidence does the harness escalate through a bounded ladder to expose a k=1 ego-graph of roughly twelve nodes, tree-encoded, with signatures rather than bodies. The literature is unusually unanimous that this is right: iteration not retriever quality [1], selective not automatic retrieval [3], and less context rather than more [4]. What remains for the model is only the final act of reading a small, true map — which is, after all, what a map is for. --- ## References 1. Zhang, F., et al. *RepoCoder: Repository-Level Code Completion Through Iterative Retrieval and Generation.* arXiv:2303.12570. EMNLP 2023. 2. Liu, T., et al. *RepoBench: Benchmarking Repository-Level Code Auto-Completion Systems.* arXiv:2306.03091. ICLR 2024. 3. *Repoformer: Selective Retrieval for Repository-Level Code Completion.* arXiv:2403.10059. ICML 2024. 4. *RepoGraph: Enhancing AI Software Engineering with Repository-Level Code Graph.* arXiv:2410.14684. ICLR 2025. 5. *LocAgent: Graph-Guided LLM Agents for Code Localization.* arXiv:2503.09089. ACL 2025. 6. *RIG / Repository Intelligence Graph.* arXiv:2601.10112. 2026. **Preprint** — treat findings as provisional. 7. *LLM Agents Can See Code Repositories (SeeRepo).* arXiv:2606.14061. ASE 2026. **Preprint** — treat findings as provisional. 8. *SWE-Explore.* arXiv:2606.07297. June 2026. **Preprint** — treat findings as provisional. 9. Zhang, Y., et al. *AutoCodeRover: Autonomous Program Improvement.* arXiv:2404.05427. ISSTA 2024. 10. Xia, C. S., et al. *Agentless: Demystifying LLM-based Software Engineering Agents.* arXiv:2407.01489. 2024.