BGPD explained — from a behavior request to verified edit sites.

Behavior-Guided Progressive Disclosure, or BGPD, is the operating procedure for using a Harness Handbook. Begin with the request and the high-level map. Select relevant execution stages. Follow shared state into coupled stages. Open only the most relevant L3 units. Expand along verified call relations. Then leave the handbook and inspect current source. The resulting evidence set contains paths, optional function or region anchors, and current excerpts. A planner turns that evidence into bounded edit blocks and action declarations. A separate executor may apply the plan. Any non-empty diff triggers resynchronization so changed source facts, affected handbook entries, ancestors, and registers move forward together. The handbook guides; the repository proves; the diff decides what became stale.

Suppose a user asks: “Let each command carry its own environment variables, but do not leak them into later commands.” The request says nothing about files. A naive planner searches env, sees hundreds of matches, and spends most of its context deciding what to ignore. A dangerously confident planner finds one process-spawn function and stops. BGPD gives the planner a repeatable route between those extremes.

The route matters because the handbook itself can be large. The generated Codex example contains many stages and thousands of file entries. Feeding the entire handbook to the agent would recreate the original context problem in a friendlier format. Progressive disclosure turns the handbook into an index that reveals detail only after the request narrows the question.

The full modification loop in plain language

The paper's Algorithm 1 has four conceptual steps. First, BGPD localizes source-grounded evidence for the request. Second, the planner writes an edit plan and declarations that say which files or units should be modified, added, or removed. Third, an executor applies the plan to a repository snapshot. Fourth, the resulting diff updates the handbook when the source changed.

The input is a request, a handbook package, and the matching repository snapshot. The output is a plan, declarations, an updated repository, a factual diff, and an updated handbook. The selected leaf mode remains unchanged. If the diff is empty, the handbook is not resynchronized because no implementation fact changed.

This separation creates useful accountability. The handbook is a navigation artifact. The plan is an intention. The executor performs actions. The diff is the factual record. Resynchronization follows the diff, not the planner's confidence. Declarations are checked against what happened, but they do not define reality.

BGPD step 1: read L1 for the execution neighborhood

The planner begins with the system overview, not a global source search. It asks where the requested behavior sits in the full lifecycle. For command-specific environment variables, the relevant flow likely begins when a tool call is decoded, passes through command orchestration and approval, reaches a process-spawn backend, then returns output to the conversation.

L1 gives the planner enough context to avoid obvious category errors. Environment variables may also appear during startup, authentication, plugin loading, or shell snapshot creation. Those uses are real but not necessarily part of a per-command override. The system flow distinguishes the runtime action path from general environment setup.

The goal at this level is not to name edit sites. It is to name the operational neighborhood and its boundaries. A planner should be able to state what enters the behavior, what outcome is required, and which upstream or downstream stages could preserve or violate that outcome.

BGPD step 2: select L2 stages and follow state

Next, the planner opens stage overviews whose responsibilities match the request. It might select tool-schema assembly, shell or unified-exec orchestration, approval and sandbox preparation, process execution, and specification tests. L2 cards expose their inputs, outputs, dependencies, and key state.

Then the planner follows the register view. A per-command environment map may enter through a tool argument, become a typed request field, pass through an execution session, merge with inherited process state, and disappear after spawn. If the map is stored in shared session state rather than passed by value, later commands could inherit it accidentally. The register relationship makes this non-leakage requirement visible.

State tracing also identifies negative requirements. “Do not affect later commands” implies that the implementation must avoid mutating a persistent global environment or cached shell snapshot. The planner should locate both the writer and the lifetime boundary. Behavior localization is not only finding where a feature is added; it is finding where its containment must be enforced.

BGPD step 3: open relevant L3 entries

Within selected stages, the planner opens only L3 entries likely to implement the behavior. In file mode, those entries provide file cards and static inventories. In function mode, they may point directly to functions or regions. The planner reads triggers, data transformations, exceptional paths, and source locators.

At this point the handbook can propose candidate sites such as a schema factory, request type, shell execution handler, unified-exec handler, process spawn helper, and mirrored schema tests. A candidate is not yet evidence. It is a hypothesis produced by the behavior map.

Progressive disclosure is valuable here because L3 detail is expensive. The agent does not need every authentication or UI file. It needs enough detail to test the current request against the selected execution chain. If an L3 card shows an unexpected dependency, the planner can return to L2 or registers and widen deliberately.

BGPD step 4: expand along call relations

A behavior card may identify the obvious implementation but miss adjacent callers or callees that carry the value. BGPD expands candidates along the program graph. Function mode uses function calls. File mode uses an induced file-call graph. Named external boundaries can provide context but are not returned as editable internal sites.

Expansion should remain request-guided. Following every transitive call would recreate whole-repository exploration. The planner asks whether the neighbor participates in input construction, validation, state transfer, execution, error handling, or verification for the requested behavior. A generic logging callee might be context; a spawn helper that merges environments is likely evidence.

Call expansion also discovers mirrored paths. A harness can have a classic shell tool and a newer unified-exec tool. Their schemas and handlers may be separate even though users perceive one “run command” behavior. A call graph plus stage organization makes this symmetry easier to spot than one keyword query.

BGPD step 5: verify against the current repository

Everything so far has operated on the handbook. Now the planner opens the actual repository. It resolves each locator, reads the current source, and retains only locations that still matter to the request. The output is the verified evidence set.

Each evidence record contains a file path, an optional function or source-region anchor, and a current excerpt. This structure makes the later plan reviewable. A reviewer can see not only where the agent wants to edit but what code justified the decision. If a handbook card says a function handles environment merging but the current function delegates elsewhere, the stale candidate is removed and the delegated location is investigated.

This step is the safety valve for generated organization and code drift. It also prevents a subtle shortcut: copying a source locator from documentation without checking whether the behavior still exists there. BGPD is handbook-assisted localization, not handbook-trusting localization.

Turn evidence into an edit plan

The planner converts verified evidence into edit blocks. Each block specifies a target file, optional function or region anchor, current supporting excerpt, and intended change. The plan should describe the behavioral reason for each edit and the dependency between blocks.

For the environment-variable example, a plan may include these categories:

1. Add an optional environment map to the tool input schema and typed request.
2. Thread the value through shell and unified-exec orchestration without storing it globally.
3. Merge the temporary map with the inherited environment at process spawn, with a documented precedence rule.
4. Ensure retries and resumed execution preserve only the command's own map.
5. Update mirrored tool-spec tests and runtime tests, including a two-command non-leakage case.
6. Check platform-specific execution paths where environment inheritance differs.

The paper's evaluation implementation uses verbatim old/new pairs. That makes execution precise but can be brittle when source changes between planning and application. The broader principle is evidence-backed specificity: name the current anchor and intended semantic change clearly enough that an executor and reviewer can detect mismatch rather than improvising silently.

Action declarations: make scope machine-checkable

For every edit block, the planner records a declaration with a target file, optional anchor, and one action type: modify, add, or remove. A rename is represented as one removal and one addition. The declarations form a compact statement of intended scope.

Declarations are useful for auditing execution. If the plan declared changes in four files but the executor touched twelve, the mismatch deserves review. If a declared addition never appears, the execution may be incomplete. The declarations do not drive handbook invalidation, because intentions can be wrong. They are compared with observed actions as a conformance check.

This is a clean separation between what we meant to do and what the repository says happened. Many agent workflows blur those concepts. Harness Handbook's resynchronization design treats the diff as factual and declarations as expected scope.

Execution is a separate responsibility

Algorithm 1 includes a separate executor that applies the plan and produces an updated repository. The paper's appendix describes an implementation with constrained tools: targeted replacement, file reads when a replacement fails, touched-file verification, and a target-specific syntax gate. It cannot list directories or access a shell.

However, the public repository's planner helper is explicitly plan-only. Its README says the single read-only agent emits a plan and does not execute or produce a diff. Resynchronization is run separately against a real changed tree supplied by the user. This distinction is important when translating research into practice: the paper describes the full workflow; the released helper focuses on planning and handbook updates.

A production adoption can pair the planner with any controlled executor, but it should preserve the boundaries: verify current source, constrain writes to the plan, run syntax and tests, inspect the diff, and require approval appropriate to the risk. Better localization does not authorize unsafe mutation.

Artifact	Meaning	Authority
Handbook candidate	A likely behavior-related source site	Navigation hint only
Verified evidence	Current source still supports relevance	Basis for the plan
Edit plan	Intended changes and rationale	Reviewable intention
Action declarations	Expected add/modify/remove scope	Conformance check
Repository diff	Observed source changes	Factual invalidation record

Why automatic resynchronization is necessary

A behavior map starts aging the moment code changes. A path can move, a function can be renamed, a file can split, a new execution variant can appear, or a stage can become obsolete. If developers use a stale handbook for the next change, its strongest feature—source-backed navigation—becomes a liability.

Every non-empty diff therefore triggers resynchronization. The pipeline reparses changed source, builds an updated program graph, and aligns old and new units. It then decides whether the current stage skeleton can still accommodate the change. If yes, it refreshes only affected organization and generated content. If no, it reruns construction with the same leaf mode and stored configuration.

Incremental updates matter for cost and stability. Regenerating a large repository after every small patch wastes tokens and can rewrite unrelated descriptions. Reusing cached generation for unaffected entries keeps diffs focused. At the same time, the system must be willing to rebuild when a local patch represents an architectural change.

Version alignment in function mode

Line numbers are fragile. Add ten lines near the top of a file and every later location moves. Function-mode resynchronization therefore uses body fingerprints that do not depend on line numbers. A function whose body is unchanged but moved can keep its handbook entry while its locator shifts.

A rename can be detected by matching the body below the signature line. Before comparing observed actions with declarations, that rename is normalized into a removal plus an addition. Modified, added, and removed functions update memberships, region anchors, hashes, within-stage order, and unmapped status.

Fingerprints are a practical heuristic, not mathematical identity. Two tiny functions can share a body; refactoring can change the body while preserving behavior; generated code can repeat patterns. Ambiguous alignment should fall into conservative review rather than force a match.

Version alignment in file mode

File mode compares file sets and content hashes. New and removed paths are straightforward. A changed hash marks a file for card refresh and possible reorganization. A path rename appears as one removal and one addition rather than a magical identity transfer.

The update removes obsolete cards and assignments, refreshes new or changed cards, assigns new files, reorganizes affected stages, and updates the coverage record. If the skeleton remains valid, unaffected stages and generation outputs are reused. If a major reorganization invalidates the skeleton, the file pipeline infers a new one from the updated repository.

This is deliberately less clever than a universal semantic rename detector. A conservative removal/addition may regenerate extra content, but it is easier to audit than a mistaken claim that two files are the same unit.

Scoped regeneration: refresh the dependency cone

Changing an L3 entry can affect its enclosing L2 stage description, the L1 system overview, and state registers that depend on that unit. Resynchronization regenerates this dependency cone while reusing unrelated cached content.

For example, adding per-command environment input changes the tool schema L3 entry, execution-handler entries, process-spawn logic, and tests. Their stage summaries may need new input and state descriptions. The system overview may not need a meaningful rewrite if the lifecycle is unchanged. A register describing command execution state may need the new field and lifetime. Scoped regeneration follows those dependencies.

Within resynchronization, the paper limits model calls to semantic steps such as classification, file assignment, within-stage organization, and description revision. Parsing, graph updates, hashing, diff analysis, and validation remain deterministic. This preserves the original facts-first boundary during updates.

Conservative handling: freeze, record, and refuse to guess

If changed source cannot be parsed or classified, the pipeline does not invent a placement. An old L3 entry whose locator or source hash cannot be revalidated is frozen and removed from active localization. A new or changed function that cannot be mapped remains explicit. File-mode gaps stay in the coverage record.

This behavior may make the handbook look temporarily incomplete. That is honest. A planner can route around a visible gap by searching current source, and a maintainer can repair the adapter or organization. An invisible hallucinated mapping is harder to detect and more likely to create a wrong edit.

A practical BGPD planning template

REQUEST
  Desired behavior:
  Explicit non-goals:
  Success and safety conditions:

L1 — SYSTEM CONTEXT
  Entry point:
  Main execution path:
  Exit / failure paths:

L2 — BEHAVIOR UNITS
  Direct stages:
  State-coupled stages:
  Excluded stages and why:

L3 — CANDIDATES
  Candidate locator:
  Behavioral role:
  Call/state relationship:

CURRENT-SOURCE VERIFICATION
  Resolved path + anchor:
  Current excerpt:
  Relevant / rejected / uncertain:

EDIT PLAN
  Target + action:
  Evidence:
  Intended semantic change:
  Test or proof:

COMPLETENESS CHECK
  Mirrors, fallbacks, platforms, retries, headless mode:
  Persistent-state leakage:
  Public schema and tests:
  Remaining unknowns:

This template is not part of the paper verbatim; it is a practical translation of its workflow. Its value is forcing each leap to be visible. The planner cannot jump from a request to an edit without naming the behavior unit and current evidence. A reviewer can challenge an exclusion or unknown before code is changed.

When BGPD helps most—and when it may not

BGPD is most useful when a request spans modules, hides behind different names, passes through shared state, or touches rarely exercised paths. The paper's results show gains for cross-file and search-hostile requests, consistent with this intuition. Repeated work on a large harness can amortize handbook construction and maintenance.

For a tiny repository or a change with an exact symbol and one implementation, direct source inspection can be faster. If the handbook is stale, poorly covered, or built with an unsupported parser, it can mislead unless source verification is enforced. If the organization adds more navigation steps than it saves, the representation is too heavy for that task.

The right comparison is not “handbook or search.” A good workflow uses the handbook to choose where to search and uses search, source reads, tests, and runtime evidence to prove the result. BGPD is a routing discipline for attention.

A worked completeness review for the command example

Before approving the environment-variable plan, walk the behavior from contract to cleanup. At the contract boundary, confirm the field is optional, its key and value types are constrained, empty input has a clear meaning, and unknown fields follow the harness's normal validation policy. If two tool schemas describe command execution, compare them side by side. A change that updates only the visible schema can fail when the model chooses the mirrored tool.

At the orchestration boundary, trace how the field moves into typed runtime state. Check serialization and deserialization if commands can be queued, resumed, or sent over a protocol. Check whether approval text needs to display environment overrides without exposing secrets. Decide whether the planner should redact values while still showing which keys change. This is where a seemingly functional feature becomes a security and user-experience concern.

At the execution boundary, define precedence. Does a command-specific value override the inherited process environment? Can it remove an inherited key, or only replace it? Is the merge performed on a fresh map per process, or does it mutate a session object? What happens on Windows, remote execution, a PTY, or a sandbox broker? The exact list depends on the harness; completeness comes from identifying variants, not from assuming one implementation.

At the lifetime boundary, prove non-leakage. Run command A with DEMO_FLAG=one, then command B without the field and assert that B cannot see it. Repeat after a retry and after a persistent execution session is reused. If the harness supports background processes, decide whether descendants should retain the value. “Temporary” needs an explicit scope.

At the failure boundary, test invalid keys, oversized values, denied execution, spawn failure, timeout, and cancellation. An approval rejection should not cache the environment for a later retry. A failed spawn should not leave global state modified. Error messages should be useful without echoing secret values. Logs should record enough structure to debug without turning the environment into telemetry.

At the verification boundary, update schema snapshots, unit tests for merge behavior, integration tests for both execution paths, platform-specific cases, and documentation that describes precedence and security. Review the final diff against action declarations. If an undeclared shared-state file changed, investigate why. Then feed the factual diff to resynchronization and inspect whether the tool, execution, and state-register descriptions all refresh.

This review shows what BGPD contributes. The handbook does not decide the product semantics for environment removal or secret display. It helps reveal the places where those decisions become code. Human engineering still defines the rule, evaluates risk, and decides what proof is sufficient.

The same completeness frame generalizes to other requests. For retries, trace the error classification, retry budget, state restoration, idempotency boundary, and final reporting. For file deletion, trace every tool and patch path, approval state, sandbox enforcement, headless policy, and audit log. For memory, trace creation, compaction, persistence, reload, deletion, and redaction. The nouns change; the method stays stable: contract, orchestration, execution, lifetime, failure, and verification. A handbook is useful when it makes each boundary discoverable without pretending that discovery answers the design question.

Write the completeness frame into the plan, not only into private reasoning. A reviewer should see why a platform path was excluded, why one test is evidence for non-leakage, and which dynamic plugin route remains uncertain. Explicit unknowns let the executor stop safely if new source contradicts the plan. They also give resynchronization a clear place to record newly mapped behavior.

After execution, compare the final diff with the evidence chain in both directions. Every changed production file should point back to a plan block or an explicitly reviewed discovery. Every plan block should have a corresponding diff or a documented reason it was unnecessary. Then compare tests with behavioral risks: a schema snapshot proves the public contract, but not process isolation; a merge-unit test proves precedence, but not that the alternate executor passes the field. This two-way check separates a syntactically faithful execution from a behaviorally complete one.

If the diff reveals a source site the handbook did not surface, treat it as a learning signal. Determine whether the call graph missed a dynamic relation, the stage assignment was wrong, the register view lacked a value, or the planner widened the design beyond the request. Update the appropriate layer and add the request to the regression set. Resynchronization keeps the artifact current; this feedback loop improves whether it is useful.

Conversely, if the handbook repeatedly suggests sites that current-source verification rejects, measure that precision debt. Frozen locators are obvious, but semantically stale descriptions can still resolve. Sample accepted candidates against the requested behavior, and refresh stage prose when code meaning changes without a path change.

Takeaways

• Start from behavior and system flow, then narrow to stages, state, and L3 units before opening source.
• Expand candidate sites along request-relevant call relations, not the entire transitive graph.
• Only current, resolved source enters the verified evidence set.
• Edit blocks cite current evidence; action declarations make intended scope auditable.
• The diff, not the plan, determines which handbook content is invalidated.
• Incremental resynchronization refreshes affected leaves, ancestors, and registers while reusing unrelated content.
• Freeze uncertainty instead of letting stale or unparseable entries guide future plans.

Frequently asked questions

What does BGPD add beyond clicking through documentation?

It defines a behavior-driven order: choose stages from L1/L2, follow cross-stage state, select L3 entries, expand along calls, and verify candidates in current source. The output is a structured evidence set for planning.

Why use a separate executor?

Separating localization, planning, and execution makes permissions and accountability clearer. A plan can be reviewed before writes, and the executor can be constrained to declared targets with syntax and test gates.

Does the public repository execute the plan?

The current public helper described by the authors is plan-only. It emits a read-only localization plan. Resynchronization consumes a real changed tree and optional diff supplied separately.

Why does the diff outrank action declarations?

Declarations record intention. The diff records observed repository changes. Invalidation must follow what actually changed, while declaration mismatch is useful as an audit signal.

What if the stage skeleton no longer fits after a refactor?

The pipeline reruns construction on the updated repository using the same leaf mode and stored configuration. Function mode can reuse its seed skeleton; file mode infers a new stage structure.

References and further reading

This series distinguishes the authors' measured findings from practical interpretation. The paper and official artifacts below are the primary sources; the final source provides broader context for why harness code matters.

• Paper (arXiv 2607.13285v1) ↗
  Wang et al., submitted July 14, 2026. The primary source for the representation, algorithms, experiment, and reported results.
• Official project page ↗
  The authors' visual explanation, live examples, Codex handbook, Terminus-2 handbook, and Studio walkthrough.
• Official implementation ↗
  Open-source generators, planner helper, resynchronization workflow, and setup instructions.
• Generated Codex Handbook ↗
  A large file-as-leaf example showing how the behavior map looks on a real production coding-agent repository.
• Generated Terminus-2 Handbook ↗
  A smaller function-as-leaf example with a supplied execution skeleton.
• Code as Agent Harness ↗
  Related survey that frames code as the operational substrate for reasoning, action, state, feedback, and coordination.