Scope Guardian AI

Scope Guardian AI monitors your Merge Requests, parses code diffs, and queries the GitLab Orbit property graph to block unplanned features before they slow down your releases.

Comment

💡 Inspiration

In fast-paced Generative AI development, developers often suffer from "feature creep"—adding unplanned customizations, secondary integrations, or over-engineered utility code. This delays releases, increases code-review fatigue, and inflates testing overhead. We were inspired to build a governance companion that automatically warns developers and maintainers when code changes deviate from issue specifications, helping teams ship faster and stay focused.

🔍 What it does

  1. Parses Git Diffs: Reads the code modifications (additions and deletions) inside a Merge Request.
  2. Traverses GitLab Orbit: Queries the Orbit graph database to retrieve parent epics and target issue nodes.
  3. Heuristic Scope Verification: Compares the semantics of added code lines against issue requirements.
  4. Flags Deviations: Automatically alerts developers on specific scope creep triggers (e.g., customizers, extra buttons, secondary features) that are out-of-scope.
  5. Recommends Actions: Assigns clear risk-based decisions:
    • REJECT: Unplanned modules that must be removed.
    • POSTPONE: Valid features that should be deferred to a separate MR or future epic.
    • KEEP: Minor refactors or required code.

⚙️ How we built it

  • Analysis Core (scope_guardian.py): Built using Python 3.12, allowing developers to execute scans locally in command-line terminals or integrate them into CI/CD pipelines.
  • Orbit Graph Representation (orbit_schema.json): Formulated property graph nodes (Epic, Issue, MergeRequest, CodeFile) and edges (IMPLEMENTS, DEVIATES_FROM) to describe how Orbit represents context.
  • Web Portal & Landing Page (src/App.tsx): A high-fidelity dashboard and landing page built with React, Vite, TypeScript, and Vanilla CSS. It provides visual demonstrations of MR scans, interactive graph visualizers, and AI Catalog sync tools.
  • Manifest publishing (ai-catalog-manifest.json): Created the metadata configuration for seamless registration inside the GitLab Duo AI Catalog.

🧠 Challenges we ran into

One major challenge was false positives for code syntax words. For example, standard JS export const syntax was flagged as a "data export widget" deviation. We resolved this by building syntax-aware regex filters that bypass native language keywords and target functional additions (like checking if download features, blobs, or file exports are actually triggered).

🏆 Accomplishments that we're proud of

  • Type Safety: Achieving 100% type safety in TypeScript with no compiler warnings (npx tsc --noEmit runs cleanly).
  • Interactive Visuals: Building a premium, responsive dashboard and a glassmorphic landing page inspired by modern visual trends.
  • Production Readiness: Delivering a dual-mode project that runs as an executable Python script and compiles into a static website ready for Vercel deployment.

📖 What we learned

We learned the power of GitLab Orbit's graph-based representation. By connecting code commits and files directly to issue contexts, AI agents can perform deep reasoning on why a change occurred rather than just what changed, representing a massive shift in automated software engineering governance.

🚀 What's next for Scope Guardian AI

  • Vector Search Extensions: Integrate embedding comparisons to check semantic overlap between issue descriptions and code comment documentations.
  • Automated MR Splitting: Enable the agent to automatically split crept MRs into two separate branches: one containing the compliant issue code, and one containing the postponed extra features.
  • Developer Training Logs: Log creep trends over time to help teams identify who might benefit from design scope training.

Built With

Share this project:

Updates