scarletkc released seiso, a Rust linter that catches stale version numbers and duplicated facts in AI-written project docs

An AI assistant that reads the project README between every change gets confused by the same things a new engineer gets confused by, and twice as fast. scarletkc released seiso v0.3.0 on 29 September 2026, a Markdown linter written in Rust that enforces six rules on how a repository writes documentation, under an MIT licence. The repository was created on 27 September and had reached 156 stars and 8 forks by 1 October.

The six rules the author states on the repository

In the author's own wording: every document declares one kind, such as howto, reference, or ADR, and holds only what that kind is for. Each fact has one home, and other pages link to it instead of retelling it. Long-lived pages do not record values that change faster than the page, such as versions, deployment status, or counts. A pointer names a file or symbol, so the reader does not have to search for what the sentence promised. The finished page does not address whoever asked for it or narrate how it was made. And a judgment call a tool cannot make is written down with a reason; an exception without one is itself a violation.

Why these rules now

The stated reason: "AI writes project docs faster than anyone can review them, and coding agents read those docs back as context for the next change." The rules catch structural failures that make an agent's next output worse than the last: a stale version number sitting on a long-lived page, a fact told two different ways on two pages, and a sentence that promises a pointer and then forgets to name one. Machine-generated prose detection and spelling checks stay with other tools.

What the workflow looks like

seiso init writes a seiso.toml at the repository root with suggested exclusions, kind mappings, and documentation site entries. The author says to review the file before relying on the result. seiso check then runs only the stable rules against the repository; preview rules are gated behind a --preview flag, so an experimental rule does not break a build the day it ships. The tool is distributed through cargo install seiso, pipx install seiso, and npm install -g @scarletkc/seiso, and the repository ships binaries for the common platforms.

The audience it is written for

A team already using an agent to write and read parts of its documentation set is the group the author names in the goal: "projects share the rules instead of negotiating their own." The linter runs in CI the same way ruff or markdownlint does, and the output is a list of file-and-line violations with the rule each one broke. The 156 stars in four days are a signal that enough teams were already looking for this, which is also the risk a reader should price in: a four-day-old linter will catch the easy cases first and get stricter from here.

Source

• scarletkc/seiso, GitHub repository, created 27 September 2026
• seiso v0.3.0 release, 29 September 2026