sot-validator

Validator for Source of Truth (.sot) files — epistemic quality verification for AI-safe documentation.

What is a .sot file?

A Source of Truth (.sot) file is a markdown document structured to communicate explicit confidence levels for all claims, enabling readers (human or AI) to calibrate their trust appropriately.

Part of the Clarity Gate ecosystem for epistemic quality verification.

Installation

npm install -g sot-validator

CLI Usage

# Validate a single file
sot-validator project.sot

# Validate multiple files
sot-validator docs/*.sot

# Output as JSON
sot-validator project.sot --json

# Quiet mode (errors only)
sot-validator project.sot -q

API Usage

const { validate, isValid, detect } = require('sot-validator');

// Full validation with errors and warnings
const result = validate(fileContent);
console.log(result.valid);    // boolean
console.log(result.errors);   // array of error objects
console.log(result.warnings); // array of warning objects

// Quick check
if (isValid(fileContent)) {
  console.log('Document passes validation');
}

// Detect if content is .sot format
if (detect(fileContent)) {
  console.log('This appears to be a .sot file');
}

Validation Rules

Required Elements

• -- Source of Truth header
• **Last Updated:** field
• **Owner:** field
• **Status:** field
• ## Verification Status section

Warnings

• Unqualified "VERIFIED" status (should be "with noted exceptions")
• Estimates in Verified Data section
• Missing staleness markers ([STABLE], [VOLATILE], etc.)

Related

• Clarity Gate - Pre-ingestion verification for RAG systems
• Source of Truth Creator - Create .sot files
• cgd-validator - Validate .cgd files

File Format Specification

See the SOT and CGD File Format Specification.

License

CC BY 4.0 — Use freely with attribution.

Author

Francesco Marinoni Moretto
GitHub: @frmoretto