### Install and Run Clarity Gate CLI (npm/PyPI)

Source: https://github.com/frmoretto/clarity-gate/blob/main/docs/DEPLOYMENT.md

Installs the Clarity Gate package using npm or pip and demonstrates basic CLI usage for checking documents. This is suitable for developers and CI/CD integration.

```bash
npm install clarity-gate
clarity-gate check your-document.cgd.md
```

```bash
pip install clarity-gate
clarity-gate check your-document.cgd.md
```

--------------------------------

### HITL Protocol Example (YAML)

Source: https://github.com/frmoretto/clarity-gate/blob/main/docs/ARCHITECTURE.md

A YAML-formatted example illustrating the HITL protocol for a specific claim. It includes the claim, automated result, reason for review, required human actions, and deadline.

```yaml
claim: "Our system achieves 99.9% uptime"
automated_result: CANNOT_VERIFY
reason: No source of truth for uptime metrics
round: B

human_action_required:
  options:
    - provide_source: "Link to monitoring dashboard or SLA report"
    - add_marker: "Mark as [TARGET] or [PROJECTED]"
    - reject: "Remove claim or rewrite with evidence"
  
  deadline: Before document enters knowledge base
```

--------------------------------

### Queue File Schema Example

Source: https://github.com/frmoretto/clarity-gate/blob/main/docs/CLARITY_GATE_FORMAT_SPEC.md

An example of the queue file schema, including version, generation and expiry timestamps, source file hashes, and document details with claims.

```yaml
schema-version: 1.0
generated: 2026-01-12T10:30:00Z
expires: 2026-01-19T10:30:00Z           # 7 days from generation
source-files-hash: <sha256>

documents:
  - file: docs/api-pricing.cgd.md
    file-hash: <sha256>
    claims:
      - id: claim-75fb137a
        text: "Base price is $99/mo"
        location: "api-pricing/1"
        round: B
        response: null                   # true | false | "estimated"
        notes: ""

```

--------------------------------

### Round A: Derived Data Confirmation Example

Source: https://github.com/frmoretto/clarity-gate/blob/main/docs/ARCHITECTURE.md

An example of the format for Round A of HITL verification, used for claims where the LLM found a source and a human was present. This format is a simple list for quick confirmation.

```markdown
## Derived Data Confirmation

These claims came from sources found in this session:

- o3 prices cut 80% June 2025 (OpenAI blog)
- Opus 4.5 is $5/$25 (Anthropic pricing page)

Reply "confirmed" or flag any I misread.
```

--------------------------------

### Example Document with Exclusion Block

Source: https://github.com/frmoretto/clarity-gate/blob/main/docs/CLARITY_GATE_FORMAT_SPEC.md

This example demonstrates a complete YAML frontmatter and markdown content, including a Clarity Gate exclusion block marked with <!-- CG-EXCLUSION:BEGIN --> and <!-- CG-EXCLUSION:END --> comments.

```markdown
---
clarity-gate-version: 2.0
processed-date: 2026-01-12
processed-by: Claude
clarity-status: CLEAR
hitl-status: REVIEWED_WITH_EXCEPTIONS
hitl-pending-count: 0
points-passed: 1-6
document-sha256: 7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730
rag-ingestable: false
exclusions-coverage: 0.15
exceptions-reason: "Legacy prose; no SME available."
exceptions-ids:
  - auth-legacy-1
hitl-claims: []
---

# API Documentation

## Overview

This API serves *(estimated)* 500 users *(as of 2026-01-09)*.

## Authentication

<!-- CG-EXCLUSION:BEGIN id=auth-legacy-1 -->
Legacy OAuth implementation details that require SME review...
<!-- CG-EXCLUSION:END id=auth-legacy-1 -->

<!-- CLARITY_GATE_END -->
Clarity Gate: CLEAR | REVIEWED_WITH_EXCEPTIONS
```

--------------------------------

### Internal Consistency Check Output Example (YAML)

Source: https://github.com/frmoretto/clarity-gate/blob/main/docs/ARCHITECTURE.md

This YAML output demonstrates a discrepancy found during an internal consistency check, specifically between a figure and accompanying text. It details the type of discrepancy, locations, values, and the recommended action.

```yaml
check: internal_consistency
status: DISCREPANCY_FOUND

findings:
  - type: figure_vs_text
    figure_location: Figure 3, panel B
    figure_value: "beta = 1/3 = 0.33"
    text_location: Section 4.2, paragraph 3
    text_value: "beta = 11/15 = 0.73"
    delta: 0.40
    severity: HIGH

action: BLOCK - Resolve discrepancy before ingestion
```

--------------------------------

### Clarity Gate YAML Schema Example

Source: https://github.com/frmoretto/clarity-gate/blob/main/docs/CLARITY_GATE_FORMAT_SPEC.md

Provides a comprehensive example of the YAML schema required for Clarity Gate documents, including required fields, optional HITL claims, computed fields, and exclusion fields.

```yaml
---
# === REQUIRED FIELDS ===
clarity-gate-version: 2.0
processed-date: 2026-01-12              # Format: YYYY-MM-DD (ISO 8601 date)
processed-by: Claude                    # Claude | automated | <name>
clarity-status: CLEAR                   # CLEAR | UNCLEAR
hitl-status: REVIEWED                   # PENDING | REVIEWED | REVIEWED_WITH_EXCEPTIONS
hitl-pending-count: 0
points-passed: 1-9                      # Format: N or N-M where N,M in 1-9
document-sha256: <64-char lowercase hex>

# === HITL CLAIMS (may be empty list) ===
hitl-claims:
  - id: claim-75fb137a                  # Stable hash-based ID
    text: "Base price is $99/mo"        # Full claim text
    value: "$99/mo"                     # Extracted value (optional)
    source: "Pricing page"              # Source of verification
    location: "api-pricing/1"           # heading_slug/ordinal
    round: B                            # A (interactive) | B (CLI)
    confirmed-by: Maria                 # OPTIONAL: may be omitted for automated verification
    confirmed-date: 2026-01-12

# === COMPUTED FIELDS (written by validators) ===
rag-ingestable: true                    # Computed: see §9.1
exclusions-coverage: 0.0                # Computed: see §9.2

# === EXCLUSION FIELDS (when REVIEWED_WITH_EXCEPTIONS) ===
exceptions-reason: "Legacy OAuth; no SME available"
exceptions-ids:
  - auth-legacy-1

# === TIER BLOCK (optional — present only for SOT) ===
tier:
  level: SOT
  owner: Platform Team
  version: 1.0
  promoted-date: 2026-01-12
  promoted-by: Maria
---
```

--------------------------------

### Full SOT CGD Example (Markdown)

Source: https://github.com/frmoretto/clarity-gate/blob/main/docs/CLARITY_GATE_FORMAT_SPEC.md

An example of a full Clarity Gate Document (CGD) in Markdown format, representing a 'Source of Truth' (SOT) tier. It includes detailed YAML frontmatter, claims, and tier information.

```markdown
---
clarity-gate-version: 2.0
processed-date: 2026-01-12
processed-by: Claude
clarity-status: CLEAR
hitl-status: REVIEWED
hitl-pending-count: 0
points-passed: 1-9
document-sha256: f6e5d4c3b2a1...
rag-ingestable: true
hitl-claims:
  - id: claim-75fb137a
    text: "Base price is $99/mo"
    value: "$99/mo"
    source: "Pricing page"
    location: "api-pricing/1"
    round: B
    confirmed-by: Maria
    confirmed-date: 2026-01-12
tier:
  level: SOT
  owner: Pricing Team
  version: 1.0
  promoted-date: 2026-01-12
  promoted-by: Maria
---

# API Pricing

Base price is **$99/mo** *(verified 2026-01-12)*.

## Verified Claims

| Claim | Value | Source | Verified |
|-------|-------|--------|----------|
| Base price is $99/mo | $99/mo | Pricing page | 2026-01-12 |

<!-- CLARITY_GATE_END -->
Clarity Gate: CLEAR | REVIEWED
```

--------------------------------

### Round B: HITL Verification Required Example

Source: https://github.com/frmoretto/clarity-gate/blob/main/docs/ARCHITECTURE.md

An example of the format for Round B of HITL verification, used for claims requiring true human verification due to lack of source, human's own data, LLM inference, or conflicting sources. This format uses a full table for detailed confirmation.

```markdown
## HITL Verification Required

| # | Claim | Why HITL Needed | Human Confirms |
|---|-------|-----------------|----------------|
| 1 | Benchmark scores (100%, 75%→100%) | Your experiment data | [ ] True / [ ] False |
```

--------------------------------

### Minimal CGD Example (Markdown)

Source: https://github.com/frmoretto/clarity-gate/blob/main/docs/CLARITY_GATE_FORMAT_SPEC.md

An example of a minimal Clarity Gate Document (CGD) in Markdown format. It includes YAML frontmatter with processing details and a simple document body, ending with the Clarity Gate end marker.

```markdown
---
clarity-gate-version: 2.0
processed-date: 2026-01-12
processed-by: Claude
clarity-status: CLEAR
hitl-status: REVIEWED
hitl-pending-count: 0
points-passed: 1-9
document-sha256: d4db0fcd3493313c59eb2d59b8f3f9aaec1cfb578e6ce7c589a225ee48741545
rag-ingestable: true
hitl-claims: []
---

# Test Document

Hello world.

<!-- CLARITY_GATE_END -->
Clarity Gate: CLEAR | REVIEWED
```

--------------------------------

### Hash Computation Test Vector Input (Markdown)

Source: https://github.com/frmoretto/clarity-gate/blob/main/docs/CLARITY_GATE_FORMAT_SPEC.md

An input file example for hash computation testing in Clarity Gate. It demonstrates the structure of a document with a pending SHA256 hash, intended for verification.

```markdown
---
clarity-gate-version: 2.0
processed-date: 2026-01-12
processed-by: Claude
clarity-status: CLEAR
hitl-status: REVIEWED
hitl-pending-count: 0
points-passed: 1-9
document-sha256: PENDING
hitl-claims: []
---


```

--------------------------------

### Clarity Gate CLI Commands

Source: https://github.com/frmoretto/clarity-gate/blob/main/docs/DEPLOYMENT.md

Provides a list of common commands for the Clarity Gate command-line interface, including file validation and type detection. These commands are essential for programmatic interaction with Clarity Gate.

```bash
clarity-gate check <file>        # Auto-detect and validate
clarity-gate validate-cgd <file> # Validate as CGD
clarity-gate validate-sot <file> # Validate as SOT
clarity-gate detect <file>       # Detect document type
```

--------------------------------

### Claim Matching Warning Example

Source: https://github.com/frmoretto/clarity-gate/blob/main/docs/CLARITY_GATE_FORMAT_SPEC.md

Illustrates a warning message when claim IDs match but the text has minor differences (e.g., whitespace, punctuation). This indicates the claim will be applied despite the text variation.

```text
WARNING: Claim text differs from queue. Applying anyway.
  Queue: "Base price is $99/mo"
  Doc:   "Base price is $99/mo."
```

--------------------------------

### Promote Command Basic Usage (Bash)

Source: https://github.com/frmoretto/clarity-gate/blob/main/docs/CLARITY_GATE_FORMAT_SPEC.md

Demonstrates the basic command-line usage for promoting a document. It specifies the document file, owner, and version.

```bash
clarity-gate promote doc.cgd.md --owner "Team" --version 1.0
```

--------------------------------

### Promote Command Behavior Steps

Source: https://github.com/frmoretto/clarity-gate/blob/main/docs/CLARITY_GATE_FORMAT_SPEC.md

Outlines the sequential steps performed by the 'promote' command, including validation, table checking, error handling, YAML modification, and metadata updates.

```text
1. Validate document is CGD (no tier block)
2. Check for existing table:
   a. If ## Verified Claims exists → validate and proceed
   b. If ## Claims (Archived from SOT) exists → restore
   c. If neither → auto-generate from hitl-claims
3. If no claims and no table → ERROR: E-PM01
4. Add tier block to YAML
5. Recompute document-sha256
6. Update processed-date
```

--------------------------------

### Invalid Exclusion Marker Examples

Source: https://github.com/frmoretto/clarity-gate/blob/main/docs/CLARITY_GATE_FORMAT_SPEC.md

Provides examples of malformed exclusion markers that would trigger specific error codes (E-EX00), such as those with extra attributes, incorrect casing, or inline content.

```text
- Extra attributes: `<!-- CG-EXCLUSION:BEGIN id=foo reason="bar" -->`
- Case variation: `<!-- cg-exclusion:begin id=foo -->`
- Inline with content: `text <!-- CG-EXCLUSION:BEGIN id=foo --> more text`
```

--------------------------------

### Use ClarityGateTool with LangChain (Python)

Source: https://github.com/frmoretto/clarity-gate/blob/main/docs/ARCHITECTURE.md

This Python code snippet illustrates how to use the ClarityGateTool within the LangChain framework. It shows creating an agent that has access to the ClarityGateTool, enabling the agent to perform Clarity Gate checks as part of its operations.

```python
from langchain.tools import ClarityGateTool

tools = [ClarityGateTool()]
agent = create_agent(tools=tools)
```

--------------------------------

### Mismatch Handling Error Example

Source: https://github.com/frmoretto/clarity-gate/blob/main/docs/CLARITY_GATE_FORMAT_SPEC.md

An example of an error message generated by Clarity Gate when there is a mismatch between the YAML frontmatter status and the end marker status in a document. This highlights the enforcement rule E-SC05.

```text
ERROR: E-SC05
  YAML says: UNCLEAR | PENDING
  End marker says: CLEAR | REVIEWED
  
  YAML is authoritative. Update end marker to match.
```

--------------------------------

### CGD with Exclusions Example (Markdown)

Source: https://github.com/frmoretto/clarity-gate/blob/main/docs/CLARITY_GATE_FORMAT_SPEC.md

An example of a Clarity Gate Document (CGD) in Markdown format that includes specific sections marked for exclusion from processing. This is useful for handling legacy or non-standard content.

```markdown
---
clarity-gate-version: 2.0
processed-date: 2026-01-12
processed-by: Claude
clarity-status: CLEAR
hitl-status: REVIEWED_WITH_EXCEPTIONS
hitl-pending-count: 0
points-passed: 1-6
document-sha256: 7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730
rag-ingestable: false
exclusions-coverage: 0.15
exceptions-reason: "Legacy OAuth; no SME available"
exceptions-ids:
  - auth-legacy-1
hitl-claims: []
---

# API Documentation

## Overview

This API serves *(estimated)* 500 users.

## Authentication

<!-- CG-EXCLUSION:BEGIN id=auth-legacy-1 -->
Legacy OAuth implementation details...
<!-- CG-EXCLUSION:END id=auth-legacy-1 -->

<!-- CLARITY_GATE_END -->
Clarity Gate: CLEAR | REVIEWED_WITH_EXCEPTIONS
```

--------------------------------

### Demote Command Basic Usage (Bash)

Source: https://github.com/frmoretto/clarity-gate/blob/main/docs/CLARITY_GATE_FORMAT_SPEC.md

Illustrates the basic command-line usage for demoting a document, including the document file and the reason for demotion.

```bash
clarity-gate demote doc.cgd.md --reason "Superseded by v2"
```

--------------------------------

### Verify Document (Workflow 1)

Source: https://github.com/frmoretto/clarity-gate/blob/main/docs/CLARITY_GATE_PROCEDURES.md

Part of the 'New Document Creation' workflow, this command runs the initial verification on a draft document.

```bash
clarity-gate verify draft.md
```

--------------------------------

### Integrate ClarityGateChecker with LlamaIndex (Python)

Source: https://github.com/frmoretto/clarity-gate/blob/main/docs/ARCHITECTURE.md

This Python code snippet demonstrates how to integrate the ClarityGateChecker as a component within LlamaIndex. It shows initializing the checker, verifying a document, and then either inserting the document into the index or routing it for review based on the verification result.

```python
from clarity_gate import ClarityGateChecker

checker = ClarityGateChecker()
result = checker.verify(document)

if result.status == "PASS":
    index.insert(document)
else:
    route_to_review(document, result.findings)
```

--------------------------------

### LangChain Tool for Document Verification

Source: https://github.com/frmoretto/clarity-gate/blob/main/docs/ROADMAP.md

Shows how to create a LangChain Tool that wraps the `verify_document` function from Clarity Gate. This allows LangChain agents to use Clarity Gate for verifying the epistemic quality of documents.

```python
from langchain.tools import Tool
from clarity_gate import verify_document

clarity_gate_tool = Tool(
    name="clarity_gate",
    func=verify_document,
    description="Verify epistemic quality of a document before use"
)
```

--------------------------------

### Demote Command Behavior Steps

Source: https://github.com/frmoretto/clarity-gate/blob/main/docs/CLARITY_GATE_FORMAT_SPEC.md

Details the steps involved in the 'demote' command, such as validating the document type, removing the tier block, archiving claims, and updating metadata.

```text
1. Validate document is SOT (has tier block)
2. If no tier block → WARNING, exit 0 (no-op)
3. Remove tier block from YAML
4. Find `## Verified Claims` section
5. Generate unique archive ID: `arch-<8-char-hex>`
6. Add archive comment with ID:
   ```markdown
   <!-- CLARITY_GATE_ARCHIVED: id=arch-x7y8z9, date=2026-01-12, reason="Superseded by v2" -->
   ## Claims (Archived from SOT)
   ```
7. Recompute document-sha256
8. Update processed-date
```

--------------------------------

### Low-Risk Deployment Security Configuration (YAML)

Source: https://github.com/frmoretto/clarity-gate/blob/main/docs/THREAT_MODEL.md

Illustrative YAML configuration for low-risk use cases like internal documents and drafts. It suggests optional HITL for round A, required for round B, spot-checking source verification, and recommends an audit trail. Adjust thresholds as needed.

```yaml
# Illustrative configuration — adjust thresholds to your needs
minimum_security:
  hitl_round_a: optional
  hitl_round_b: required
  source_verification: spot-check  # e.g., 10%
  audit_trail: recommended

```

--------------------------------

### Redaction of Exclusion Block Content

Source: https://github.com/frmoretto/clarity-gate/blob/main/docs/CLARITY_GATE_FORMAT_SPEC.md

This example illustrates how the content within an exclusion block is replaced with '[REDACTED]' during the redaction process, while preserving the exclusion markers.

```markdown
<!-- CG-EXCLUSION:BEGIN id=auth-legacy-1 -->
[REDACTED]
<!-- CG-EXCLUSION:END id=auth-legacy-1 -->
```