cgd-validator

Validator for Clarity-Gated Document (.cgd) files — documents verified and annotated for safe LLM ingestion.

What is a .cgd file?

A Clarity-Gated Document (.cgd) file is a markdown document that has passed epistemic verification and contains inline annotations ensuring safe interpretation by LLMs.

Part of the Clarity Gate ecosystem for epistemic quality verification.

Installation

npm install -g cgd-validator

CLI Usage

# Validate a single file
cgd-validator document.cgd

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

# Output as JSON
cgd-validator document.cgd --json

# Quiet mode (errors only)
cgd-validator document.cgd -q

API Usage

const { validate, isValid, detect } = require('cgd-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
console.log(result.frontmatter); // parsed YAML frontmatter

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

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

Validation Rules

Required Elements

• YAML frontmatter with:
  • clarity-gate-version
  • verified-date
  • verified-by
  • hitl-status
• ## Clarity Gate Verification section

Warnings

• HITL status not "CONFIRMED"
• Projections ("will be") without *(projected)* marker
• Vague quantifiers without annotation

Related

• Clarity Gate - Pre-ingestion verification for RAG systems
• Source of Truth Creator - Create .sot files
• sot-validator - Validate .sot 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