Technical Article · Genetic Engineering PROPOSED
Deterministic Grounding for Agent Software Engineering
An AI agent can pass all the tests and still deliver the wrong change. This article shows why and proposes a way to reduce this risk.
The agent works with what he believes he knows about the repository: context recovered, memory, a plan. If this information is no longer valid, the code may be correct in isolation and wrong for today's project, violating architecture, authorized scope or privacy.
Deterministic Grounding it is the provisional name that this article proposes (it is not standardized terminology) for a practice in three parts: anchor what the agent knows in a verifiable state of the repository, limit what it is allowed to do and validate each change with recorded evidence. The mechanisms described are proposed, yet without measurement of efficacy; see the limitations in Scene 09.
What the agent believes
Request: "Add PDF export route"
Recovered context: commit C1 index
Assumption: the dependency 'pdf-kit' v1.2 is in the project
Plan: edit src/api/export.js and package. json
What the repository now has
Snapshot: commit C2 (most recent)
Lockfile: 'pdf-kit' has been removed in C2
Rule: src/api/ restricted by ADR-014 (architecture decision record)
Result: the change made on C1 conflicts with C2
It's like opening a Pull Request from a copy of the project a week ago: on its own, the code is correct; against what the team has changed since then, it's been born broken.
The colored seals next to the titles indicate the degree of certainty of each section: OBSERVED (observed), ESTABLISHED (established), DOCUMENTED (documented), PROPOSED (proposal) and INFERENCE (inference).
- Format
- Article
- Depth
- In-depth reading · ~7 min for central idea · ~19 min complete
You prefer the essentials first? Read synthesis (~1 min)
Scene 01 · The Agent–Repository Gap
Five sources of truth, each with limited authority
The error of the example above arises from treating information from different origins as if it were a single context. Each source can only assert certain things, and none can speak in the other's place. Click on each card to see what it authorizes to state and what it does not authorize.
Current State
Authority: The repository and the execution environment, the way they are now
Which allows you to say:
- Tell which is the current commit, which files exist and which dependencies are installed.
- Telling which files have changed since the last commit.
Which does NOT allow to state:
- Tell them what the team intends to do or what the requirements will require in the future.
- Ensure that the desired architecture is being followed. That needs a separate check.
When two sources disagree
These states do not always agree: the specification asks one thing, the repository shows another, the memory holds a third. The model does not solve this conflict in silence. The system:
- records the verdict CONFLICK;
- preserves where all information came from (the provenance);
- verifies the scope and freshness of each source (which commits it and still applies);
- sends for human review the conflicts of intent, security or high impact.
There is still a sixth type of information, the derived structural status: the code graph extracted from the repository (Cena 04). It's derived, not primary source. The repository has the final word about what exists now.
What happened: the agent recovered the context index built in the commit C1. The repository was already in C2, where a new rule of architecture prohibits direct calls to the bank from inside the controller.
Because it seemed successful: the code generated compiles and passes the unit tests.
What no one had checked: if the index still corresponded to the current commit (C2) and whether the new layer rule was valid for the changed passage.
Lesson: A recovered index may seem consistent and outdated. Compare his commit to the current one before use.
Scene 02 · Identity of State PROPOSED
Snapshot Capsule: prove where the agent is looking
Think of a festival bracelet: it's for one night and a gate, you can't re-use it another day, and without it security won't let you in. Snapshot Capsule (a sealed envelope with the exact identity of the repository) does the same with the context of the agent: no recovered context reaches it without being sealed with the 7 attributes below. If one of them is missing, the whole context will be treated as unreliable.
Snapshot Identity Digest
SEALEDCurrent status: The 7 attributes are present and match the repository: the snapshot identity is verified.
Scene 03 · Contracts & Requirements PROPOSED
Prompt is not a contract
A request in natural language is an intention, not a specification that you can test. Between the need of those who asked and the proof that it was met there is a chain of transformations. It's skipping steps that requirements that seem obvious, like privacy, get lost along the way.
Oracle (oracle) is any automatic verification that gives a verdict on a property: a test, a linter (checking style and code patterns), a security scanner.
The contract is like reviewing the same Pull Request in four zooms. Each level can approve something the other would fail:
Level 1 · Interface
Does the shape match? Types, schemas, signatures of methods and message formats.
Level 2 · Behavior
You do what you promise, and that's it? Preconditions, post-conditions, invariants (which can never change) and side effects.
Level 3 · Architecture
Do you live where you should live? Layers, boundaries between modules, permitted dependencies and isolation.
Level 4 · Semantics
Is it safe and compliant? Who owns the data, privacy, retention and regulatory impacts.
Declaring a rule is not the same as making it fulfilled, and validating an action does not prove that it is correct in general. So the chain below separates each paper:
- Constraint: Which must be true, or what limits the solution.
- Policy: which is authorized or prohibited.
- Enforcement: the mechanism that prevents rape. Declaring a policy does not prevent anything on its own.
- Validation: how a property is valued.
- Evidence: what result was produced.
What happened: the agent implemented a photo upload service. All API tests (levels 1 and 2 of the contract) gave PASS.
Because it seemed successful: the API received and stored the photos with great response time.
What no one had checked: the implementation recorded EXIF (camera metadata, including location) on open logs and shared these metadata with third parties without consent. It's a Level Four violation.
Lesson: The main path remains green, and a side trail is left unattended because no oracle was written for it.
Scene 04 · Structural Analysis PROPOSED
Static analysis sees what is written, not what happens in execution
Static analysis (read the code without executing it) and code graphs (AST/CST, the syntactic tree of the code, plus symbols and relationships between them) form a reliable map of everything that is written. But the map does not show what only happens during execution: no static analysis captures runtime altogether.
Scene 05 · Governance of Action PROPOSED
Autonomy is not authority: Action Gateway
An advanced model can assemble complex plans on its own. That's... autonomy: how much he plans and chain actions. Authority is another thing: the permission to actually change the repository, shoot a deploy or call a privileged tool. In the design proposed here, who decides that is the Action GatewayAnd just him.
Think of it as an automatic and inflexible Pull Request reviewer: if the change touches a file outside the allowed list, it blocks, no matter how good the code is.
Low Autonomy · Low Authority
Rigid automation, local scripts and routine reading. Low risk and low capacity.
Low Autonomy · High Authority
Deploy Scripts with large radius blast (how much an error can spread) and no judgment to realize that something is wrong.
High Autonomy · Low Authority (Recommended Zone)
The agent investigates, plans and proposes. The execution is always intermediated and limited to a sandbox (insulated environment).
High Autonomy · High Authority (High Risk Zone)
The agent decides and executes directly in production: decision and execution in the same step, without barrier in the middle.
Action Gateway · the 12 steps (proposal of this article) in 3 steps
The 12 steps and Diff Lens are a design of this article, not an established standard. Before any real effect, each proposal would go through 12 checks: understand the request (1 to 5), decide whether it is allowed (6 to 9) and execute and prove (10 to 12).
Diff Lens · the Gateway comparing the order with the scope allowed
Gateway does not only approve half of the proposal: it blocks the entire action until the scope is corrected.
He can only block what his rules, permissions and schemas cover. A tool that no one has mapped passes it without being seen. That's why Gateway's coverage and effectiveness need to be demonstrated, not presumed.
What happened: a non-risk reading tool (release status), is usually called. A ticket induces the agent to call inside a second tool (sync environment) which has written permission.
Because it seemed successful: the first call passes the reading check.
What no one had checked: the second call is a new action in the flow and needs to be evaluated by Action Gateway on its own. She doesn't inherit approval from the first.
Lesson: Valid format and approval of the main call do not authorize chained calls with more privilege.
Scene 06 · Epistemological Force STABLISHED
Passing the test isn't the same as being right
A test that passes (PASS) proves one thing: the property he checks was satisfied in the conditions in which he drove. It doesn't prove the system is correct or that there were no side effects. The table shows 10 types of verification (oracles), which each PASS guarantees and which remains unsecured.
The possible verdicts: PASS (passed), FAIL (failure), UNKNOWN (without basis for completion by jump test, timeout or absence of test) and CONFLICK (valid records with results incompatible with each other).
| Verification (oracle) | Verdict | Which guarantees when it passes | What remains unsecured |
|---|---|---|---|
| 01. Parser (syntax) | PASS | The entry is valid according to the grammar of the language. | Right types, right meaning or working. |
| 02. Type Checker (types) | PASS | Guys respect the rules of the type system. | Running behavior and logic bugs. |
| 03. Static analysis / Linter | PASS | The set rules and standards have been respected. | That nothing is missing and that there is no functional regression. |
| 04. Unit test | PASS | The case tested passed with the inputs used. | Border cases that no one has written and forgotten requirements. |
| 05. Integration test | PASS | The components worked together in the tested scenario. | Behavior under a lot of competition or production. |
| 06. Security Scanner | PASS | No known vulnerability was found. | Business logic failures that have never been catalogued. |
| 07. Runtime Monitor | UNKNOWN | The metrics were normal in the observed window. | What happens outside this window, like at peak times. |
| 08. Model Checker (formal model) | FAIL | The formal model respects invariants. | That the model faithfully represents the real code. |
| 09. Formal Checker | CONFLICK | Mathematical proof that the code matches the specification. | That the specification captures what the person really wanted. |
| 10. Human Review | PASS | One person assessed and approved the change, according to his judgment. | Protection against something the person missed. |
What happened: the test test rejects negative amount() failure after a change. For the suite to pass again, it is marked with skip (jumping)
Because it seemed successful: The test suite is 100% green, with no fault in sight.
What no one had checked: the coverage of what should be tested decreased. The skip hides the gap instead of solving it.
Lesson: Less failed testing does not mean more correct software. It can mean just less being watched.
Scene 07 · Auditability STABLISHED
Evidence Record: the receipt of each validation
All validation should generate a Evidence Record Unchangeable. It does not only keep the result: it records where it came from (the provenance), which version of the validator ran, in which environment and what remained outside. It's a receipt, not a certificate: proof that you passed that test in those conditions, and you don't guarantee that anything will break after.
Target (URI Subject): git://repo@a8f3d1e/src/api/export.js
Commit: a8f3d1e992b47c01
Request: REQ-EXPORT-001
Verified property (predicate): POST /export returns a valid PDF
Verification (oracle): orc nodest v22 (integration test)
Executor (validator): Node-test-runner:v22.22.1
Implementation environment: Docker Sandbox / isolated network
What was out: 88% of the covered lines / EXIF logging NOT covered
Limitations declared: does not cover competition or malformed entries
Origin Signature (Provinance): sig: sha256:990a1f...
Notice the highlighted field: the record states the blind spot itself. Here, PASS with 88% coverage says nothing about Case 2 EXIF logging. The oracle type matters: a parser PASS and a PASS of a formalized business rule do not have the same weight (Cena 06).
Scene 08 · Decision & Closing PROPOSED
From evidence to decision, and where to start
Reconciliation is the time to decide what to do with change. It compares the desired state, the current state, the evidence obtained and the policy rules, and produces one of seven possible decisions, not only accept or reject.
01. Desired State
Acceptance requirements and rules that can never be broken.
02. Current State
The diff (the difference between the code before and after) of the repository after the agent action.
03. Evidence State
The Evidence Record, with verdicts and limits.
04. Policy State
The list of permissions and approvals of the action.
The 7 possible decisions
Grounding is a cycle, not a step
Five words appear in this article and mean different things: grounding (associate something to the observed reality), levy (restring or blocking), validation (assess properties), evidence (record the result) and reconciliation (compare states and decide). The grounding cycle runs through five moments:
| Moment | What do you do? | Mechanism in this article |
|---|---|---|
| Background | It associates the recovered context with current facts and entities. | Snapshot Capsule (Cena 02) |
| Planning | Face the plan with the current state and specification. | Contract and Desired State (Cena 03) |
| Implementation | Restricts authorized actions. | Action Gateway (Cena 05) |
| Validation | Evaluate action against defined properties. | Oracles (Scene 06) |
| Reconciliation | Compare desired status, current status and evidence. | The 7 decisions (this scene) |
Experiment: What if you turn off a control?
Turn off the mechanisms below and see which of the 5 classes of deviation (invented dependence, outdated context, out-of-scope change, violation of architecture and divergent status of the repository) are back to unprotected. Each class depends on at least one control, and the violation of architecture depends on two (validation and grounding). It's a simulation of the coverage logic, not a measured result in real projects.
Start with an MVA (Minimum Viable Architecture)
An MVA is the smallest version of the pipeline worth running. Mount him with a low risk, following these seven actions:
- Choose a small, low-impact task.
- Fix Snapshot Capsule (the commit SHA, tree digest and lockfile hash).
- Declar in Action Gateway the list of allowed and prohibited files.
- Turn at least one requirement into a contract, with an independent oracle to verify it.
- Turn the agent in a sandbox, without any implied authority.
- Register PASS, FAIL, UNKNOWN and CONFLICK verdicts at Evidence Record.
- Compare the result with a baseline (the same task without grounding).
Scene 09 · Limitations
What this article still does not prove
This text describes an architecture proposal, not a measured result. Before adopting any part of it, consider:
- It's a proposition. Snapshot Capsule, Action Gateway (with 12 steps and Diff Lens) and Evidence Record are drawings of this article. There is no measurement of their effectiveness so far.
- The name is provisional. "Deterministic Grounding" is not standardized terminology.
- Scene 08's experiment is a simulation. It shows that control covers what class of deviation, not how much each reduces errors in practice.
- Gateway only blocks what he knows. Tool effects without rule, permission or corresponding schema escape from it.
- Digest proves identity, not completeness. It covers the artifacts included in the capsule, and only them.
- Static analysis does not see dynamic code (Scene 04), and a PASS applies only to the property and environment in which it was obtained (Scene 06).
- Sources are missing. The article still does not cite primary sources with verification date. The statements are the author's proposal, not the result of a literature review.
Scene 10 · Glossary
The terms, in common language
The original terms remain correct and appear throughout the article. This table is the shortcut to remember what each one means.
| Original term | In common language | Which means |
|---|---|---|
| Agent–Repository Gap | Misalignment | The difference between what the agent believes to know about the repository and what's really there now. In academic texts appears as G t = A t − S t, where A t is what the agent assumes in instant t and S t is the actual state of the repository at this instant. |
| Snapshot Capsule | The context seal | Sealed envelope that proves which commit and what environment the agent is viewing. |
| Action Gateway | The Pull Request inflexible reviewer | The barrier that decides what the agent can actually execute. |
| Allowlist | List of permissions | Only what's on the list can be touched. The rest is blocked. |
| Policy-as-Code | Rule written as code | Versioned permitted and prohibited rules, instead of a PDF policy that nobody consults. |
| Blast radius | Damage radius | How much action can spread if it goes wrong. |
| Oracle (oracle) | Automatic verification | Any automatic check that gives a verdict on a property: test, linter, scanner. |
| Evidence Record | The validation receipt | Unchangeable record of what was checked, by whom and under what conditions. |
| Coverage Boundary | What was left out of the test | The explicit limit of what validation did not cover. |
| Provenance | Source Track | The checkable chain of who generated and signed evidence. |
| Desired State | What should be true | Declared acceptance requirements and criteria. |
| Current State | What's true now | The observable status of the repository at this time. |
| Contract of 4 levels | 4 zoom revision | Interface, behavior, architecture and semantics. Each level can approve what another would fail. |
| Autonomy vs. Authority | Thinking alone vs. being able to execute | When the agent plans without help, against how much he can really change. |
| Reconciliation | The final decision | Stage that joins requirement, state, evidence and politics and decides the next step. |
| Determinism (in this article) | Same input, same result | Same input, same version of the validator, same configuration, same dependencies and even controlled environment produce the same verification result. |
| Constraint / Policy / Enforcement | Restriction / rule / imposition | The restriction says what must be true, the policy says what is authorized and the imposition is the mechanism that prevents the violation. |
| Grounding lifecycle | The Grounding Cycle | The five moments when the agent is anchored in reality: context, planning, execution, validation and reconciliation. |
| MVA (Minimum Viable Architecture) | The least it's worth rolling | The smallest version of the governance pipeline that already brings benefits. |