YOUR ARCHITECTURE DIAGRAMS CAN'T SILENTLY LIE

stalemaid is a CI gate that fails a pull request when code a mermaid diagram describes changes but the diagram doesn't change with it. You put a one-line provenance header on each diagram saying which code it models; stalemaid checks that the two move together. Drift becomes a build error instead of a slow rot that misleads everyone who reads the diagram next. Deterministic, runs in GitHub Actions or as a pre-commit hook. Free and open source.

Source on GitHub Use the GitHub Action How it works

Node 18+ · CLI + GitHub Action · zero config v0.1.0 · Apache-2.0 OR MIT · on npm as stalemaid · npmjs.com/package/stalemaid

$ stalemaid check stalemaid: 5 checks run, 1 failure(s) FAIL [drift] docs/diagrams/billing.md: code file src/billing.ts changed but the diagram wasn't updated — update it and bump last_verified # you update the diagram in the same PR, then: $ stalemaid check stalemaid: 5 checks run, 0 failure(s) ✓

How it works

Each diagram is a plain markdown file with mermaid plus a small frontmatter header:

---
title: "Billing flow"
models: "src/billing.ts, src/lib/charge.ts"   # the code this diagram describes
source_of_truth: code                          # diagram | code | spec
last_verified: a1b2c3d 2026-06-15              # short SHA + date
diagram_type: flowchart
---

You declare what each diagram models. The models: field lists the code paths the picture explains.
stalemaid runs in CI on every pull request (or locally as a pre-commit hook).
If a modeled file changed but its diagram didn't, the PR fails — with a message naming the file and telling you what to fix.
The lifecycle is built in: diagram (the contract, drawn before code) → code (derived view, now gated for drift) → spec (external authority; drift means your code is wrong). Only code diagrams are drift-gated.

The five checks

frontmatter	every diagram has title, models, source_of_truth, last_verified
freshness	last_verified SHA is inside the recent-commit window
mermaid	every ```mermaid block actually parses
forward-ref	the models: paths on a code diagram exist on disk
drift ★	a models: file changed in the PR but the diagram didn't

The drift check is the one nobody else ships: a deterministic, in-the-PR co-change gate, on mermaid diagrams.

Use it

As a GitHub Action on every pull request:

# .github/workflows/diagrams.yml
on: pull_request
jobs:
  stalemaid:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0          # drift + freshness need git history
      - uses: Attestrum/stalemaid@v0
        with:
          root: docs/diagrams

Or locally, as a pre-commit hook — it checks the staged set, so drift is caught before the commit is even made:

# .git/hooks/pre-commit
npx stalemaid check --root docs/diagrams || exit 1

Why we built it

stalemaid comes out of how we work on Attestrum: we draw a diagram of every module, flow, and schema before we write the code, because catching a design error in a picture is far cheaper than catching it in code. The discipline only holds if the picture stays true — a stale diagram is worse than none, because people trust it. So we treat drift as a bug, and stalemaid is what enforces that. Same posture as the rest of Attestrum's work on verifiable, local-controlled provenance: the artifact has to match reality, and you can prove it.