StaleSeal

Your docs declare the code they cover. A fingerprint seal proves they still match it. When code moves and docs don't, StaleSeal names the file — deterministically — and GitLab Duo flows do the fixing.

Comment

Inspiration / the problem

Documentation rots silently. A guide is reviewed and correct on Monday; on Tuesday someone changes the code it describes, and nothing anywhere notices. Readers trust the doc, the doc is wrong, and the team finds out from a confused user or a production mistake. Existing drift tools mostly ask a language model "does this doc still look right?" — a probabilistic opinion that costs tokens on every check and can be confidently wrong in both directions.

What it does

StaleSeal combines four pieces — the combination is the product:

  1. In-doc covers: declarations. Each Markdown doc carries front matter listing the code files it describes. The declaration lives in the doc itself, next to the prose it makes a claim about — no central registry to fall out of sync.
  2. A stored fingerprint seal. Next to covers:, the doc stores a SHA-256 fingerprint (staleseal-fp-v1, specified in staleseal/fingerprint.py) of the covered files, plus the per-file digests it was computed from. The seal is written by bless at the moment a human or agent has reviewed the doc against the code.
  3. A deterministic verdict. A scan recomputes the fingerprint and compares. Match → FRESH. Mismatch → STALE, citing exactly which covered file(s) changed (or went missing). Same tree, same verdict, every machine, every time — no LLM, no tokens, no network in detection. Detection is a hash comparison, and StaleSeal never pretends otherwise.
  4. An inverted coverage map. The scan also flips the question: which source files does no doc cover? Those are flagged UNCOVERED, with a coverage score — the blind spots a per-doc check can never see.

Verdicts land in a prioritised review queue (JSON + a self-contained HTML dashboard), ordered worst-first, ready for a human or an agent to work through. CI-friendly exit codes: 0 clean, 1 findings.

What StaleSeal is not: it is not a doc writer or generator. It does not write documentation. It watches documentation — a monitor + govern + verify tool for the post-code lifecycle. The writing, when a fix is needed, is the Duo remediation flow's job, and a human approves it.

How GitLab Duo Agent Platform was used

Detection is deterministic (above). Judgment and remediation are where GitLab Duo Agent Platform acts, via two custom flows built in the AI Catalog on the project:

  • StaleSeal Remediation (trigger: issue assignment) — reads the scan report, updates the stale doc so it matches the current code, re-seals it using the scanner's computed hashes (never hashes it invents), and opens a merge request with a summary. It stops there.
  • StaleSeal Triage (trigger: issue mention) — reads the review queue, ranks the STALE/UNCOVERED items that matter most, and posts its assessment on the issue so a human starts from a ranked list, not a raw dump.

AGENTS.md is wired into every flow component as an explicit input, so the flows follow the same rules as any other contributor: allowlist, no merging, no invented seals. The flow definitions live in .gitlab/duo/flows/ in the repo, and the execution environment (.gitlab/duo/agent-config.yml) is committed on main, as the platform requires.

Proven live, Oct 24, 2026: Issue #2 (a STALE shipping-rates doc whose code had gained a 4% fuel surcharge) → remediation flow → MR !1 → human bless step → green pipeline → human merge → Issue #2 auto-closed, and the post-merge pipeline on main passed all 5 jobs. The flow diagnosed correctly on its first run and stopped rather than invent a fingerprint it could not verify — the guardrails working, not failing. The full audit trail is on MR !1.

Autonomy level declared: Supervised

Supervised. Agents execute the multi-step workflow — reading the report, updating the doc, re-sealing, opening the MR, clearing the pipeline gates — and a human reviews and approves the outcome, the merge request. Stated plainly: Duo flows cannot merge merge requests (no such tool exists on the platform), and StaleSeal does not claim otherwise. The human merge is the supervised gate, and it is demonstrated on MR !1, not just asserted.

How it's built

  • Python 3 standard library only; zero dependencies; 57-test unittest suite, including regression tests from an independent code review (path-escape confinement, symlink-safe bless, per-doc error verdicts).
  • Deterministic core: staleseal/fingerprint.py specifies the staleseal-fp-v1 algorithm; detection is a hash comparison.
  • GitLab CI: test → verify (unit tests, fixture eval, SAST, Secret Detection) → package (container image) → release (Cloud Run — live, see Links) → monitor (re-scan job defined in CI; no pipeline schedule created; Duo flow triggers paused at submission per the freeze rule).
  • All code, docs, fixtures, and flow YAML written fresh for this hackathon (Path A: Start Fresh). Fixtures are a fictional "ParcelTrack" mini-app, labelled fictional.

Links

Try it out

Locally, no install beyond Python 3:

python -m staleseal scan samples/parceltrack

The fixture tree demonstrates the verdicts: docs that match their code scan FRESH, and the source file no doc covers is flagged UNCOVERED. Change one line in a covered file and scan again, and that doc scans STALE naming the file.

Built With

Share this project:

Updates

Submission history