check

docs-ssot check

Check docs for SSOT violations by detecting near-duplicate sections across Markdown files.

docs-ssot check [flags]

Uses TF-IDF cosine similarity to compare sections at the specified heading level. Sections scoring above the threshold are reported as potential SSOT violations — places where the same information exists in multiple source files.

Flags

Flag	Default	Description
--root	docs	Root directory to scan for Markdown files
--threshold	0.82	Similarity cutoff (0.0–1.0); pairs above this score are reported
--min-chars	120	Minimum character count for a section to be included in comparison
--section-level	2	Heading level used as section boundary (1–6)
--format	text	Output format: text or json
--exclude	—	Exclude path pattern (repeatable)

Examples

Basic check with default settings:

docs-ssot check

Lower threshold to catch more candidates:

docs-ssot check --threshold 0.75

Compare at H3 level, exclude changelogs, output JSON:

docs-ssot check --section-level 3 --exclude docs/changelog/** --format json

Output

Text output (one block per similar pair):

score=0.891
A: docs/auth/overview.md [API > Authentication]
B: docs/setup/login.md [Setup > Authentication]
A title: Authentication
B title: Authentication
A snippet: Authentication tokens must be refreshed before they expire...
B snippet: Access tokens must be renewed prior to expiry...
----------------------------------------------------------------------------------------------------

A score of 1.0 means identical content; 0.82 (default threshold) catches near-duplicates while filtering loosely related content.

Exit behaviour

Exits 0 whether or not duplicates are found. Use --format json and inspect result_count in CI pipelines.