-
-
Intent Guard
Inspiration
A merge request can be one line long, compile cleanly, pass every test, and still break a product. The day someone narrows "full coverage" from "US citizens and lawful permanent residents" to "US citizens only," the code is correct, but the FAQ, the application guide, the evidence checklist, and a now untouched test all keep promising the old rule. That is the developer pain point we kept hitting: nothing in the review pipeline is responsible for product intent. Linters check syntax. Tests check the behavior someone remembered to assert. But no tool tells a reviewer that a small, valid change has just made the rest of the repository contradict itself, and the contradiction stays invisible at exactly the moment it is cheapest to fix.
What it does
Intent Guard is a flow on the GitLab Duo Agent Platform that detects product-intent drift, and it fixes the pain point by making intent a thing the review can actually check. The project declares its intents in a plain INTENT.md, where each intent names a code anchor, the behavior it requires, the documents (artifacts) that must stay aligned, and the tests that prove it. When a merge request lands, Intent Guard takes the changed symbol and asks GitLab Orbit, the Knowledge Graph, one question: "what else depends on this?" It walks outward through the call graph to compute the blast radius, layers in the declared document coupling that Orbit cannot see on its own, and posts a single review comment naming every intent, file, and test that may now be out of sync.
What changes for the developer is the moment of discovery. Instead of mentally tracing dependencies, or learning about the broken promise from a user weeks later, they open the merge request and the affected artifacts are already listed in the review thread, each with the reason it was flagged: changed directly, or reached transitively through the call graph. In the demo, a one-line eligibility change surfaces all three declared intents, one anchored on the change itself and two reached transitively, plus a test that was never opened and is now silently stale. The product-consistency check that used to live only in a senior engineer's head now runs automatically, in the place where the review already happens.
How we built it
Intent Guard runs as a flow on the GitLab Duo Agent Platform, triggered by an @mention on the merge request and published to the AI Catalog. The core is a Python tool that reads INTENT.md, resolves each anchor against GitLab Orbit, and queries the graph directly: Orbit Local through raw DuckDB SQL over orbit sql, plus the Orbit Remote selector DSL for the hosted graph. For each changed symbol it traverses CALLS edges from dependents back to the anchor to build the transitive set, then renders the findings as a Markdown review comment. A healthcare eligibility repository (eligibility_engine.py plus its coupled docs and tests) serves as the live test bed for end-to-end runs.
Challenges we ran into
The biggest lesson was what a code graph can and cannot see. Module-level constants are not captured as nodes and have no CALLS edges, so a policy expressed as a top-level list is invisible to traversal, which means the policy logic has to live inside function bodies to be reachable. Getting the traversal direction right mattered too: the blast radius is the set of dependents of the change, not its callers. Beyond that, Orbit Local and Orbit Remote speak different query surfaces (raw SQL versus a relationship-selector DSL with required project scoping), the Agent Platform's flow editor expects a different YAML shape than the committed file, and the graph has to be reindexed when it goes stale. Each of these was a quiet trap that only surfaced under real data.
Accomplishments that we're proud of
A clean end-to-end run: a one-line eligibility change produces a review comment that correctly surfaces all three declared intents, two of them reached transitively through the call graph and labeled as such. We are proud that it names a specific, dangerous case (a test that was never touched and is now silently stale) rather than just reporting that files changed. Most of all, we are proud that it changes the developer's day in a concrete way: a class of bug that used to ship quietly now shows up as a checklist in the review, and the reviewer keeps the final call. It is also a use for the Knowledge Graph that was not obvious before, because the graph is not only for helping AI read code, it can protect product intent.
What we learned
We learned to treat the Knowledge Graph as a first-class query target rather than a black box, and to design the source code so the relationships we care about are actually expressible as graph edges. We learned where Orbit's reach ends (code-to-code coupling is captured natively, while code-to-prose coupling still needs a declared bridge) and that being honest about that seam makes the tool more trustworthy, not less. And we learned how much signal lives one or two hops away from a diff, completely out of a reviewer's line of sight.
What's next for Intent Guard
The clear next step is to narrow the seam between graph-traced code dependencies and the hand-written artifacts list: inferring likely document-and-code couplings automatically, and ranking findings by how confidently the graph connects them. After that, move from detection to action by proposing the specific edits each out-of-sync document and test needs, so an Intent Guard comment becomes a set of ready-to-apply fixes rather than a checklist. The graph already knows where the drift is. Intent Guard is learning to write the report, and then the patch.
Log in or sign up for Devpost to join the conversation.