💻 computer science

Contract-Coding: Towards Repo-Level Generation via Structured Symbolic Paradigm

The paper introduces Contract-Coding, a structured symbolic paradigm that bridges vague user intents and executable code via Autonomous Symbolic Grounding to overcome context-fidelity trade-offs in repo-level generation, achieving significantly higher functional success and structural integrity on the Greenfield-5 benchmark compared to state-of-the-art agents.

Original authors: Yi Lin, Lujin Zhao, Yijie Shi

Published 2026-04-16

📖 5 min read🧠 Deep dive

CC BY 4.0

Original authors: Yi Lin, Lujin Zhao, Yijie Shi

Original paper licensed under CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ This is an AI-generated explanation of the paper below. It is not written or endorsed by the authors. For technical accuracy, refer to the original paper. Read full disclaimer

The Big Problem: The "Vibe Coding" Chaos

Imagine you ask a team of brilliant but slightly confused architects to build a massive, 20-story skyscraper. You don't give them blueprints; you just say, "Build me a cool place where people can live, work, and fly drones." This is what the paper calls "Vibe Coding" (or Intent-Driven Engineering).

In the past, AI agents tried to do this by talking to each other in a long, linear line:

Agent A says, "Okay, I'll build the foundation."
Agent B reads Agent A's notes, says, "Okay, I'll build the first floor," but accidentally changes the door width.
Agent C reads Agent B's notes, says, "Okay, I'll build the second floor," but forgets that the door is now too narrow.

As the building gets taller, the instructions get messy. By the time they reach the 20th floor, the foundation is wrong, the elevators don't fit, and the whole thing collapses. This is called Architectural Collapse. The AI gets "lost in the middle" of too many details.

The Solution: The "Language Contract"

The authors propose a new way called Contract-Coding. Instead of letting the agents talk to each other directly, they force them to all agree on a Master Blueprint first.

Think of this Language Contract as a strict, unchangeable rulebook or a legal contract that acts as the "Single Source of Truth."

Here is how it works, step-by-step:

1. The "Architectural Thumbnail" (The Contract)

Before anyone lays a single brick, the AI creates a high-level summary of the building.

Old Way: Agents try to remember every detail of the foundation while building the roof.
New Way: The AI writes a "Contract" that says: "The foundation must be 10 meters wide. The first floor must have a 2-meter door. The roof must be red."
The Magic: This contract is short and simple. It doesn't contain the messy details of how to build the door, just what the door must look like.

2. The "Topological Hypervisor" (The Traffic Controller)

Once the Contract is written, it acts like a traffic controller or a game master.

In the old way, Agent B had to wait for Agent A to finish before starting.
In this new way, the Contract allows everyone to work at the same time.
Agent A builds the foundation. Agent B builds the first floor. Agent C builds the roof.
Why? Because they aren't looking at each other's messy notes. They are all looking at the same Contract. As long as they follow the rules in the Contract, they can't mess each other up.

3. The "Referee" (The Auditor)

This is the most clever part. The system has a Referee (an Auditor agent) that constantly checks the work.

If Agent B builds a door that is 3 meters wide (violating the Contract), the Referee immediately stops them.
The Referee doesn't just say "Wrong." It goes back to the Contract and updates it: "Okay, we need a 3-meter door now."
Then, it tells Agent A (who built the foundation) to fix their work to match the new rule.
This prevents small mistakes from becoming big disasters later.

Why is this better? (The "Sub-linear" Magic)

The paper uses a fancy term: Sub-linear Context Scaling. Let's translate that.

The Old Problem: If you want to build a 100-story building, the AI has to read 100 pages of notes. If you want to build a 1,000-story building, it has to read 1,000 pages. Eventually, the AI's brain (memory) gets full, and it forgets the beginning.
The Contract-Coding Solution: No matter how big the building gets, the Contract stays roughly the same size. It's like a map. Whether you are walking a mile or a thousand miles, you only need to look at the map, not read a diary of every step you've taken.
Result: The AI can build huge, complex systems without getting confused or forgetting the rules.

Real-World Analogy: The Orchestra

Old Way (Linear): A conductor tells the violinist to play, then the violinist tells the drummer, who tells the bassist. If the violinist makes a mistake, the drummer gets confused, and the bassist plays the wrong song.
Contract-Coding: The conductor hands out a sheet of music (The Contract) to every musician. Everyone reads the same sheet. They can all play their parts at the exact same time (Parallelism). If a musician plays a wrong note, a Sound Engineer (The Auditor) hears it, stops the music, and updates the sheet of music for everyone to see.

The Results

The researchers tested this on building complex software "games" (like a city simulator or a dungeon crawler).

Competitors: Other AI systems often built "hollow skeletons" (buildings with no rooms) or "logical detachments" (doors that lead nowhere).
Contract-Coding: Even though it wasn't perfect at every tiny detail, it built structurally sound systems. The "building" didn't collapse. The doors were in the right place, and the elevators worked.

Summary

Contract-Coding is like giving a team of AI builders a strict, shared rulebook instead of letting them chat in a chaotic line.

Define the Rules First: Create a short, clear contract.
Work in Parallel: Let everyone build at the same time based on the rules.
Audit Constantly: A referee checks if the work matches the rules and updates the rules if needed.

This stops the AI from getting overwhelmed by complexity and allows it to build massive, reliable software systems that used to be impossible.

1. Problem Statement: The Context-Fidelity Trade-off

The paper addresses a critical bottleneck in Intent-Driven Software Engineering (often called "Vibe Coding"), where users provide vague, high-level goals rather than strict specifications. Current Large Language Model (LLM) agents struggle to generate complex, multi-file repositories from these intents due to two systemic failures:

Sequential Entropy Accumulation: Traditional "Chain-of-Thought" (CoT) workflows process tasks sequentially. Early architectural ambiguities or errors propagate and amplify as semantic noise, leading to global architectural collapse.
The Context Bottleneck: As the number of files ( $N$ ) increases, the cumulative context of previous implementations exhausts the model's attention window. This causes Symbolic Hallucination (inventing non-existent APIs) and Architectural Collapse, where the model loses track of global dependencies.

The authors argue that the root cause is the entanglement of control complexity and implementation volume. Existing methods force agents to reason over raw, noisy code history rather than abstract, decoupled specifications.

2. Methodology: The Contract-Coding Paradigm

The authors propose Contract-Coding, a framework that bridges unstructured user intent and executable code via Autonomous Symbolic Grounding. The core innovation is the Language Contract, which acts as a Single Source of Truth (SSOT).

A. The Language Contract (Symbolic Grounding)

Instead of generating code directly, the system first synthesizes a Language Contract ( $C$ ). This is a dual-layer entity:

Constraint Projection (Structure): High-level natural language sections (Product Requirements, API Specs) providing context for LLM reasoning.
Executable Kernel (Symbolic): A rigorous logical kernel ( $K = \langle N, \Sigma, \Delta \rangle$ ) mapping modules to file paths, defining strict type signatures, and representing state spaces. This kernel serves as a "topological hypervisor."

B. Probabilistic Reformulation

The paper mathematically reformulates the generation task.

Traditional (Sequential): $P(R | I) = \prod P(f_i | f_{<i}, I)$ . This relies on raw implementation history ( $f_{<i}$ ), causing error propagation.
Contract-Coding (Decoupled): $P(R | I) \approx P(C | I) \times \prod P(f_i | C)$ .
By conditioning file generation ( $f_i$ ) solely on the Contract ( $C$ ) rather than other files, the system achieves Conditional Independence. This allows for Architectural Parallelism, where multiple agents generate files simultaneously without lock-step synchronization.

C. The Three-Phase Workflow

Symbolic Projection: An agent synthesizes the initial Contract ( $C_0$ ) from the user intent using a Discrete Symbolic Evolution (DSE) process. This involves a "Generator" proposing mutations and a "Discriminator" auditing for architectural soundness (acyclicity, completeness).
Topological Orchestration (HEG): The system constructs a Hierarchical Execution Graph (HEG). Tasks are scheduled based on the Contract's state.
- Generative Expansion: Workers generate code conditioned only on the Contract (not other files).
- Normative Verification: A "Critic" agent validates the code against the Contract's signatures, not just for "looking good."
Active Contract Auditing: A Contract Auditor acts as a homeostatic controller. It continuously monitors the graph state and performs Topological Interventions:
- Structural Alignment: Injects tasks if a required symbol is missing.
- State Synchronization: Regresses task status (e.g., from DONE to ERROR) if logic bugs are found.
- Consistency Control: Enforces alignment between the Contract's recorded signatures and the actual workspace code, preventing silent drift.

3. Key Contributions

Formalization of the Language Contract: A mechanism to autonomously operationalize vague "vibes" into a deterministic, structured symbolic paradigm, bridging the gap between Vibe Coding and rigorous Spec-Coding.
Contract-Driven Hierarchical Graph (HEG): A paradigm that decouples implementation details, reducing informational dependency depth. This unlocks massive Architectural Parallelism and enables Sub-linear Context Scaling (the contract size grows much slower than the code size).
Empirical Validation of Sub-linear Scaling: Demonstrated that while repository scale expands, the symbolic contract remains compact, effectively compressing the reasoning context and mitigating the "Lost-in-the-Middle" phenomenon.

4. Experimental Results

The framework was evaluated on Greenfield-5, a benchmark suite of five increasingly complex greenfield projects (from logic puzzles to a 25-file Roguelike game).

Performance vs. SOTA:
- Legacy Agents (MetaGPT, ChatDev, OpenHands): Suffered from Architectural Collapse on complex tasks (e.g., OpenHands dropped to 30% success on the Roguelike task). They failed to manage deep inter-file dependencies.
- Commercial AI IDEs (Lingma, Trae, Gemini Studio): Achieved high success rates but relied on massive context windows (brute-force scaling) and often produced bloated code or suffered from "Probabilistic Drift" and "Logical Detachment."
- Contract-Coding: Achieved 47% functional success on the most complex task (Roguelike) while maintaining near-perfect structural integrity (100% in many cases). Crucially, it achieved this with a 16k token limit, whereas commercial tools often rely on >200k context windows.
Token Compression: The system achieved a 4.6x compression ratio. For a 8,857-token project, agents only needed to attend to a ~1,900-token contract, avoiding context exhaustion.
Self-Healing: In case studies (e.g., Plane Battle), the system autonomously detected semantic mismatches between parallel agents (e.g., missing attributes) and retroactively patched the Contract to resolve the conflict, preventing error propagation.

5. Significance and Conclusion

The paper marks a paradigm shift in Automated Software Engineering (ASE):

From Specification-Following to Intent-Driven Synthesis: It proves that robust, large-scale code generation is possible without pre-existing formal specifications, provided a structured symbolic layer (the Contract) is used to ground the intent.
Scalability over Brute Force: It challenges the notion that larger context windows are the only solution to complexity. Instead, Architectural Decoupling via symbolic contracts offers a more scalable path.
Reliability: By enforcing a "Single Source of Truth," the framework prevents the "Silent Failures" common in sequential agents, ensuring that local logic errors do not cascade into global system failures.

In summary, Contract-Coding demonstrates that by treating the software architecture as a decoupled, auditable symbolic graph, autonomous agents can generate complex, multi-file repositories with high structural integrity, even under strict context constraints.