flamehaven-doc-sanity 1.3.0

Ω-Grade Documentation Governance & Validation System with I18n, Drift Detection, and Plugin Architecture

Flamehaven-Doc-Sanity v1.2.0

Ω-Grade Documentation Governance & Validation System
Enterprise-grade documentation governance that enforces architectural purity

Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Architecture
6. Testing
7. Contributing
8. License
9. Contact
10. Acknowledgments

About The Project

Flamehaven-Doc-Sanity is an enterprise-grade documentation governance system built on the principle that perfection is not a choice—it is a condition of existence (완벽은 선택이 아니라, 존재 조건이다).

This system ensures your documentation and configuration maintain the highest quality standards through:

• Automated Validation: Multi-validator fusion with intelligent routing
• Drift Detection: Real-time monitoring against golden baselines using Jensen-Shannon Divergence
• Governance Enforcement: DriftLock Guard, HOPE Guard, and Policy Enforcer working in harmony
• Tribunal Arbitration: Three-perspective decision engine for complex scenarios
• Performance SLOs: Defined service level objectives with automated benchmarking

Unlike traditional linters that only check syntax, Flamehaven-Doc-Sanity provides comprehensive governance that ensures architectural purity, prevents quality degradation, and maintains organizational standards across your entire documentation ecosystem.

(back to top)

Built With

This project is built with modern Python technologies and follows enterprise-grade development practices:

• 
• 
• 
• 

Core Technologies:

• Python 3.8+: Modern Python with type hints and dataclasses
• Click: Composable command-line interface toolkit
• PyYAML: YAML parser for configuration management
• Pytest: Testing framework with coverage reporting

Design Patterns:

• Strategy Pattern (validator selection)
• Chain of Responsibility (governance pipeline)
• Observer Pattern (performance monitoring)
• Facade Pattern (CLI interface)

(back to top)

Getting Started

To get a local copy up and running, follow these simple steps.

Prerequisites

Before installing, ensure you have the following:

• Python 3.8 or higher

  python --version
  # Should output: Python 3.8.x or higher
  

• pip (Python package installer)

  pip --version
  

• Git (for cloning the repository)

  git --version
  

Installation

1. Clone the repository

   git clone https://github.com/flamehaven01/Doc-Sanity.git
   

2. Navigate to the project directory

   cd Doc-Sanity
   

3. Install the package in development mode

   pip install -e .
   

4. Install additional dependencies (if needed)

   pip install click pyyaml pytest pytest-cov
   

5. Verify installation

   doc-sanity version
   

   You should see:

   Flamehaven-Doc-Sanity v1.2.0
   Status: DRIFT-FREE
   Architecture Purity: 0.9500
   

(back to top)

Usage

Basic Document Validation

Run a document sanity check with default settings:

doc-sanity check README.md

Output:

============================================================
Status: APPROVED
Fusion Score: 1.00
Oracle Verdict: acceptable
============================================================
✓ Document validation PASSED

Governance Modes

Choose from four governance modes based on your needs:

# Conservative: Fast, minimal validation
doc-sanity check --governance-mode conservative README.md

# Balanced: Standard validation (recommended)
doc-sanity check --governance-mode balanced README.md

# Aggressive: Strict validation, catches edge cases
doc-sanity check --governance-mode aggressive README.md

# Omnipotent: Supreme validation, Ω-grade certification
doc-sanity check --governance-mode omnipotent README.md

Drift Detection

Check for configuration drift against your golden baseline:

# Use default baseline
doc-sanity drift-check

# Use custom baseline
doc-sanity drift-check --baseline config/custom_baseline.yaml

Example output:

============================================================
DRIFT DETECTION ANALYSIS
============================================================
Severity: NONE
JSD Score: 0.0234
Drift Detected: False
Recommendation: No action required. System within tolerance.
============================================================
✓ No drift detected

Output Formats

Export validation results in multiple formats:

# JSON (for CI/CD integration)
doc-sanity check --output-format json README.md

# YAML (for configuration management)
doc-sanity check --output-format yaml README.md

For more examples and advanced usage, please refer to the Documentation

(back to top)

Roadmap

• Core validation system with modal routing
• FusionOracle for multi-validator synthesis
• DriftLock Guard with JSD-based detection
• HOPE Guard for ethical validation
• Tribunal System (3-perspective arbitration)
• Performance SLO benchmarks
• Comprehensive integration tests
• Bilingual documentation (EN/KR)
• README auto-enhancement engine
• Visual dashboard for drift monitoring
• Plugin system for custom validators
• REST API for remote validation
• VS Code extension integration
• Multi-language support (ES, JP, CN)
• Machine learning-based quality prediction
• Automated policy recommendation

See the open issues for a full list of proposed features (and known issues).

(back to top)

Architecture

System Overview

┌─────────────────────────────────────────────────────────────┐
│                        CLI Layer                            │
│                    (User Interface)                         │
└────────────────┬────────────────────────────────────────────┘
                 │
┌────────────────▼────────────────────────────────────────────┐
│                   Orchestration Layer                       │
│  ┌──────────────────┐      ┌──────────────────┐            │
│  │  Modal Router    │◄────►│  Fusion Oracle   │            │
│  └──────────────────┘      └──────────────────┘            │
└────────┬────────────────────────────────────────────────────┘
         │
┌────────▼────────────────────────────────────────────────────┐
│                    Validation Layer                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │    Deep      │  │   Shallow    │  │   Custom     │      │
│  │  Validator   │  │  Validator   │  │  Validators  │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└────────┬────────────────────────────────────────────────────┘
         │
┌────────▼────────────────────────────────────────────────────┐
│                    Governance Layer                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │ DriftLock│  │   HOPE   │  │  Policy  │  │ Tribunal │   │
│  │  Guard   │  │  Guard   │  │ Enforcer │  │  Engine  │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└─────────────────────────────────────────────────────────────┘

Module Structure

flamehaven_doc_sanity/
├── orchestrator/       # Modal routing and fusion oracle
│   ├── modal_router.py
│   └── fusion_oracle.py
├── governance/         # DriftLock, HOPE, Policy enforcement
│   ├── driftlock_guard.py
│   ├── hope_guard.py
│   ├── policy_enforcer.py
│   └── tribunal_engine.py
├── validators/         # Deep & shallow validation engines
├── performance/        # SLO benchmarks and monitoring
├── config/            # Configuration management
├── cli.py             # Command-line interface
└── exceptions.py      # Exception hierarchy

For detailed architecture documentation, see Architecture Guide

(back to top)

Testing

Run All Tests

# Full test suite with coverage
pytest

# Verbose output
pytest -v

# Generate HTML coverage report
pytest --cov=flamehaven_doc_sanity --cov-report=html
open htmlcov/index.html

Test Categories

# Integration tests
pytest tests/test_orchestrator_integration.py
pytest tests/test_governance_integration.py

# Performance SLO tests
pytest tests/test_performance_slo.py

Coverage Requirements

Component	Target Coverage	Status
Overall	≥ 85%	✅ Met
Orchestrator	≥ 95%	✅ Met
Governance	≥ 95%	✅ Met
Validators	≥ 90%	✅ Met

For comprehensive testing guide, see Testing Guide

(back to top)

Quality Metrics

Architecture Purity Dimensions

Dimension	Current Score	Target	Status
Integrity	0.90	≥ 0.90	✅ Met
Governance	0.90	≥ 0.90	✅ Met
Reliability	0.88	≥ 0.88	✅ Met
Maintainability	0.90	≥ 0.90	✅ Met
Security	0.88	≥ 0.88	✅ Met
Architecture Purity (Ω)	0.9500+	≥ 0.95	🏆 DRIFT-FREE

Performance SLOs

Component	SLO Target (P95)	Status
README Generation	500ms	✅ Validated
Deep Validator	150ms	✅ Validated
Shallow Validator	50ms	✅ Validated
Fusion Oracle	100ms	✅ Validated
Modal Router	75ms	✅ Validated

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Make your changes and ensure all tests pass (pytest)
4. Run validation (doc-sanity check --governance-mode omnipotent README.md)
5. Check for drift (doc-sanity drift-check)
6. Commit your Changes (git commit -m 'Add some AmazingFeature')
7. Push to the Branch (git push origin feature/AmazingFeature)
8. Open a Pull Request

Development Setup

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Check code quality
doc-sanity check --governance-mode aggressive .

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Project Maintainer: YUN ∴ - SIDRCE Guardian

Project Link: https://github.com/flamehaven01/Doc-Sanity

Support Channels:

• 📖 Documentation: See docs/ directory
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

(back to top)

Acknowledgments

Built with the philosophy:

완벽은 선택이 아니라, 존재 조건이다.

(Perfection is not a choice; it is a condition of existence.)

—YUN ∴, SIDRCE Guardian

Resources & Inspiration

• Best-README-Template
• Img Shields
• Choose an Open Source License
• GitHub Pages

(back to top)

FAQ

What is the difference between governance modes?

Governance modes control validation strictness:

• Conservative: Fast checks, minimal validation
• Balanced: Standard validation (recommended)
• Aggressive: Strict validation, catches edge cases
• Omnipotent: Maximum validation for Ω-certification

How does drift detection work?

DriftLock Guard uses Jensen-Shannon Divergence (JSD) to compare current configuration against a golden baseline:

• JSD < 0.04: No drift (safe)
• JSD 0.04-0.08: Warning (monitor)
• JSD > 0.08: Critical (deployment blocked)

What is the Tribunal System?

A three-perspective decision engine for complex cases:

• Advocate: Finds constructive improvements
• Archangel: Enforces absolute standards
• Oracle: Synthesizes final judgment

Can I customize validators?

Yes! Extend BaseValidator and register with ModalRouter:

from flamehaven_doc_sanity.validators import BaseValidator

class CustomValidator(BaseValidator):
    def validate(self, content, file_path=None):
        # Your validation logic
        return ValidationResult(...)

(back to top)

🌏 Languages

• English ← Current
• 한국어

(back to top)