SpecLock

Inspiration

A lot of merge request reviews are still based on reviewer intuition. An issue says what should happen, a merge request shows what changed, and someone has to decide whether those two things actually match. In practice, that often becomes a vague "looks good" approval instead of a structured check against acceptance criteria.

We built SpecLock to make that review step more explicit, evidence-based, and easier to trust.

What it does

SpecLock is a GitLab Duo project with two parts:

• SpecLock Coach helps authors turn vague requirements into clear checklist-style acceptance criteria under an Acceptance Criteria heading.
• SpecLock is a custom GitLab Duo flow that evaluates a merge request against the linked issue's checklist and posts a structured review note with PASS, FAIL, and UNCERTAIN results.

The flow is intentionally narrow, so it is reliable:

• it evaluates merge requests only
• it expects the MR to close exactly one same-project issue, for example Closes #123 -It treats checklist items under Acceptance Criteria as the source of truth
• It requires explicit evidence from the MR metadata or diffs before marking a criterion as PASS.
• If the criteria remain unresolved, it creates a follow-up issue so the work stays visible

How we built it

We built SpecLock as a lightweight GitLab Duo Agent Platform project using:

• a custom GitLab Duo flow defined in YAML
• a companion GitLab Duo chat agent
• shared guardrails to keep the behavior evidence-driven and predictable
• documentation and demo materials designed for both judges and beginners

The project is designed to fit the hackathon workflow: validate the catalog files, publish the asset version, enable the flow in GitLab, and trigger it through the generated service account.

Challenges we ran into

The biggest challenge was staying honest about platform behavior while still building something useful and demo-friendly.

We had to be very careful about:

• schema and validation constraints in custom flow YAML
• trigger behavior and generate service-account naming
• avoiding unsupported assumptions
• keeping the flow narrow instead of overengineering it into a broad repository auditor

One of the most important lessons was that clean-looking YAML is not the same as validator-safe YAML. We had to refine the project around what the platform would actually validate and run reliably.

What we learned

This project reinforced a simple idea: strong AI automation often comes from a clear contract and tight scope, not from trying to do everything.

By keeping SpecLock focused on one merge request, one linked issue, and one checklist, we ended up with a system that is easier to understand, safer to run, and much easier to evaluate in a real GitLab workflow.

What makes SpecLock different

SpecLock is not trying to replace code review or become a general-purpose code-analysis platform. Its value is in turning acceptance criteria into a visible, structured review step inside GitLab.

That makes it useful not only as a hackathon project, but also as a practical pattern for teams that want clearer issue hygiene, more consistent review quality, and less guesswork in merge requests.

Built With

• gitlab
• gitlab-custom-agents
• gitlab-custom-flows
• gitlab-duo-agent-platform
• gitlab-duo-chat
• markdown
• mermaid
• yaml