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

pip install 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

Python API

from cgd_validator import validate, is_valid, detect, validate_file

# Full validation with errors and warnings
result = validate(file_content)
print(result.valid)       # bool
print(result.errors)      # list of ValidationError
print(result.warnings)    # list of ValidationError
print(result.frontmatter) # parsed YAML frontmatter dict

# Quick check
if is_valid(file_content):
    print('Document passes validation')

# Detect if content is .cgd format
if detect(file_content):
    print('This appears to be a .cgd file')

# Validate from file path
result = validate_file('document.cgd')

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