DocSutra AIDocumentation Truth Audit - v0.2.1 - by Vatsal Shah

Rules reference

Every rule with its severity, category and evidence type. Generated from the same catalog the scanner uses, so it cannot drift.

Rule catalog

RuleSeverityCategoryEvidenceWhat it means
BROKEN_LOCAL_LINKerrorlinkslocal-filesystemA relative or repository-root link points at a file or directory that does not exist.
BROKEN_ANCHORerrorlinkslocal-filesystemA #fragment does not match any heading or id/name attribute in the target Markdown file (GitHub slug rules).
PATH_CASE_MISMATCHerrorlinkslocal-filesystemThe link resolves on case-insensitive filesystems (Windows/macOS) but breaks on Linux and GitHub.
UNDEFINED_REFERENCEerrorlinkslocal-staticA [text][label] reference has no matching [label]: url definition.
MALFORMED_LINKerrorlinkslocal-staticThe URL contains invalid percent-encoding or NUL characters.
UNSAFE_LINK_SCHEMEerrorsecuritylocal-staticA link uses javascript:, file:, vbscript: or another non-web scheme.
OUTSIDE_REPOSITORY_LINKwarninglinkslocal-staticA local link resolves outside the scanned root; it is reported and never opened.
IMAGE_MISSING_ALTwarningaccessibilitylocal-staticMarkdown or HTML image has no alt text (WCAG 1.1.1).
UNCLOSED_CODE_FENCEwarningstructurelocal-staticA fenced code block is never closed, so everything after it renders as code.
CLI_UNKNOWN_SUBCOMMANDerrorcommandsdeclared-contractA documented command uses a subcommand absent from the cliContracts you declared. The declaration itself may be stale.
CLI_UNKNOWN_FLAGerrorcommandsdeclared-contractA documented command uses a --flag absent from the cliContracts you declared. The declaration itself may be stale.
PIPE_TO_SHELLwarningsecuritylocal-staticA snippet pipes a download straight into a shell (curl | sh). Never executed by DocSutra; flagged for manual review.
DESTRUCTIVE_COMMANDwarningsecuritylocal-staticA snippet contains a destructive command (rm -rf, mkfs, dd, chmod -R 777 ...). Never executed; flagged for manual review.
SECRET_IN_DOCSerrorsecuritylocal-staticText matches a known credential format (GitHub/npm/AWS/Slack/Stripe/Google tokens, private keys). The value is redacted in all reports.
DUPLICATE_HEADINGinfostructurelocal-staticDuplicate headings get -1, -2 suffixed anchors, which makes anchor links fragile.
EMPTY_LINK_TEXTwarningaccessibilitylocal-staticA link has an empty label, which is unusable for screen-reader users (WCAG 2.4.4).
HEADING_LEVEL_SKIPinfoaccessibilitylocal-staticA heading jumps more than one level (for example h2 to h4), which weakens document structure.
INVALID_FILEerrorstructurelocal-staticThe file contains invalid UTF-8 or a NUL byte and was not analysed.

Evidence types

TypeMeaning
local-filesystemVerified by checking the real file system
local-staticDerived from the document text alone
declared-contractCompared against a contract you declared; only as good as the declaration

Finding status labels

Findings from a scan are always failed (a reproducible problem). The verification vocabulary used by the skills is: verified, failed, inferred, manual-review, not-run. A timestamp is never a certification.

Stability

Rule IDs are stable. New rules are added in minor versions; behaviour changes to existing rules are listed in the changelog.