Riven

Stop agent-written code before it breaks what you didn't know it touched.

Comment

Inspiration

AI agents are getting good at writing code that looks clean in a merge request, but that is exactly what makes silent breakage more dangerous. A text review can say "looks fine" while a changed function signature quietly severs real downstream callers. We were inspired by GitLab's own thesis around control at agentic scale: if agents are going to author more code, teams need a merge control plane that is grounded in the repository graph, not just in conversational review.

Orbit made the core idea click. Once we confirmed the local graph was real, queryable, and rich enough to expose definitions plus static CALLS edges, the project stopped being a reviewer concept and became infrastructure. That is where Riven came from.

What it does

Riven is an Orbit-powered merge governance layer for AI-written code.

On every merge request, it:

  • indexes or refreshes the repository graph with Orbit Local
  • maps diff hunks to changed gl_definition symbols
  • walks inbound static CALLS edges through gl_edge
  • computes graph-proven blast radius and breaking-change risk
  • emits a machine-readable risk-contract.yaml
  • blocks merge in GitLab CI when the contract fails

It also goes beyond the gate itself:

  • suggests reviewers from CODEOWNERS
  • recommends verification jobs
  • explains an evidence-backed risk score
  • exposes the contract through MCP for other tools and agents
  • can draft remediation proposals and bounded candidate patches without making AI authoritative over the merge decision

How we built it

We built Riven as a TypeScript control-plane tool with a few tightly connected layers:

  1. Orbit analysis layer
    We use Orbit Local as the graph source of truth. Riven discovers relationship kinds at runtime, maps MR diffs to changed definitions, and traverses inbound static CALLS edges to find impacted callers and transitive risk.

  2. Contract layer
    The core artifact is risk-contract.yaml. It records changed definitions, impacted symbols, verification recommendations, suggested reviewers, architecture findings, and a deterministic risk score. GitLab CI enforces this artifact through process exit code.

  3. GitLab integration layer
    We added init, doctor, and gitlab-bootstrap so a repo can adopt Riven without hand-wiring everything. The live GitLab project proves the real merge-gate behavior with a blocked MR and a failing pipeline artifact.

  4. AI and MCP layer
    We exposed the same contract protocol through an MCP server, then added contract-bound AI flows for remediation drafting, patch planning, candidate diff generation, sandbox verification, and evidence recording. The important rule is that AI consumes the contract; it does not replace it.

  5. Verification layer
    We built fixture-based and arbitrary-repo smoke tests so Riven is not just a demo script. It runs against the included planted-break repo, simulated GitLab MR pipelines, temporary repos, and optional larger public repositories.

Challenges we ran into

  • Getting honest about the graph.
    We had to verify Orbit's real schema instead of building around guessed column names. That grounding step mattered, because static impact is only credible when the implementation matches the actual graph.

  • Drawing the line between strong claims and fake claims.
    Static CALLS edges are powerful, but they are not a perfect runtime call graph. We had to be precise about dynamic dispatch, reflection, generated code, and unindexed languages so the product stayed trustworthy.

  • Making the gate real, not theatrical.
    It is easy to build an AI reviewer that leaves a clever comment. It is much harder, and much more useful, to make the contract enforceable through CI and protected branch rules.

  • GitLab pipeline and identity friction.
    We hit the usual practical issues around MR pipeline setup, token scope, action permissions, and project bootstrap. Getting the live GitLab proof working cleanly was one of the most valuable parts of the build.

  • Keeping AI helpful but bounded.
    We wanted AI-generated remediation, but only inside guardrails. That meant designing proposal schemas, patch-plan validation, unified-diff constraints, and sandbox verification so AI output could be useful without becoming hand-wavy authority.

Accomplishments that we're proud of

  • We turned the idea into a real blocked merge gate in GitLab, not just a chat workflow.
  • We proved Orbit can power graph-proven static blast radius on actual MR diffs.
  • We built a machine-readable contract primitive that other tools can consume.
  • We shipped adoption tooling (init, doctor, gitlab-bootstrap) so this can move beyond a hackathon repo.
  • We added MCP and bounded AI remediation flows while preserving CI as the source of truth.
  • We kept the implementation honest with schema verification, deterministic scoring, and real test coverage.

What we learned

  • Orbit is much more compelling when treated as an operational control surface, not just a search layer.
  • The best interface for agent governance is often not a conversation, but a contract artifact that multiple systems can validate and enforce.
  • AI is most useful in this space when it is downstream of evidence.
  • Developer trust depends less on how impressive the explanation sounds and more on whether the system is specific, auditable, and bounded.
  • Shipping something real in GitLab means solving a lot of unglamorous infrastructure details, and those details are part of the product.

What's next for Riven

  • publish the Duo skill and AI Catalog listing cleanly
  • polish the web/docs surface around the real control-plane story
  • make ownership routing richer with SDLC joins
  • add coverage-aware verification planning instead of purely conservative job recommendations
  • add a promotion path from sandbox-verified patch to optional apply workflow
  • make repo onboarding even easier for teams who want to drop Riven into existing GitLab pipelines

Built With

Share this project:

Updates