Hakobu DocDrift

Inspiration

What it does

How we built it

Challenges we ran into

Accomplishments that we're proud of

What we learned

What's next for Hakobu DocDrift

Inspiration

Docs go stale where review does not look: a diff is read against intent, not prose. Two cases from this build. The first draft of this write-up said the DocDrift flow "runs only when the MR touches code and docs paths", but its trigger is a mention, an assignment, or a reviewer request — wrong before the flow ever ran. And the earlier Nebius deployment of the same app still returns 404 for GET /api/health, because it was built from an older commit; the first scheduled-style probe against it failed, which is the monitor stage doing its job.

What it does

The project runs a supervised loop over seven of nine GitLab stages, all executed on GitLab.com:

plan → verify → secure → package → release → monitor → govern.

DocDrift is cross-cutting, not a stage. A deterministic script (scripts/doc-drift.mjs, CI job doc_drift in verify) checks documented env vars, routes, npm scripts, file paths and model IDs still exist in code, and code-level env vars and routes are documented. On mention, assignment, or reviewer request, the Duo DocDrift flow reads the MR diff and the docs, finds statements the change made false, and comments with the exact doc line and a suggested patch. A human approves only the final MR and the production deploy.

How we built it

• GitLab Duo Agent Platform: issue-to-checklist flow (plan, validated in CI by validate_duo_flows), DocDrift flow, and the docdrift-reviewer agent (read-only tools plus create_merge_request_note).
• GitLab CI/CD: build_and_test, typecheck, SAST, Secret Detection, Dependency Scanning, package (hakobu-build.tgz), deploy_vercel, release on v* tags, and a scheduled monitor_probe of /api/health, / and /api/plan that opens an issue on failure.
• Governance: CODEOWNERS, govern_check (checks CODEOWNERS and the MIT license), tool-limited agents. Protected-branch and approval-rule settings are not changed by this project (my role cannot open those pages).

What I added during the Submission Period (Path B)

Hakobu (MIT, https://github.com/Hwemo-Chung/hakobu) existed as an app and is also entered in the Nebius × NVIDIA hackathon. Everything GitLab-side is new: the pipeline, flows and agent, the DocDrift checks, the monitor job, the governance files, and the Vercel deploy config.

Challenges

• Keeping the agent honest: DocDrift must quote the stale doc line and the code line, or say "no drift".
• The check compares literal tokens only: a model ID changed only in lib/llm.ts is missed while .env.example keeps the old one; semantic drift is left to the Duo flow.
• The Duo catalog rejected my first flow YAML (prompts.N.name: Field required) and the first pipeline failed on a misplaced entrypoint key; both were fixed through merge requests !1 and !2, so the history shows them.
• Duo flows need a mention or assignment to start; the run history below is real, but each run was triggered by me on purpose, not by an organic review.

Accomplishments

Seven of nine stages ran for real: plan, verify, secure, package, release, monitor, govern. create and configure are not claimed.

Real runs on GitLab.com: the issue-to-checklist flow answered issue #2 with a repo-grounded checklist (and correctly noticed that sorting by price already existed, so only the cheapest-row marker was missing). The DocDrift flow reviewed MR !3, which intentionally changes /api/health and the smoke-test port without touching the docs, and reported three stale claims with file:line evidence and suggestion blocks; the MR is left unmerged. Pipelines passed on the merge request, on main and on tag v0.1.0, which produced a GitLab release.

On a scratch copy with seeded drift, the check caught all five cases with exact doc lines: an undocumented env var, a renamed route folder, a removed npm script, a moved file, and a replaced model ID. On a clean tree it prints No documentation drift detected (exit 0).

What's next

• Let DocDrift run on every MR through a reviewer trigger instead of a manual mention.
• Redline export for regulated documents (same engine, compliance manuals).

Built With

• ci/cd
• gitlab
• gitlab-duo-agent-platform
• next.js
• react
• typescript
• vercel