# Risks, Assessments, and Confidence Levels Defined for Claims in Claude-Obsidian

> Understand risks, assessments, and confidence levels for claims in Claude-Obsidian. Discover how the taxonomy centralizes and validates claim data.

- Repository: [Agrici.Daniel/claude-obsidian](https://github.com/AgriciDaniel/claude-obsidian)
- Tags: deep-dive
- Published: 2026-08-29

---

**Claude-Obsidian enforces a strict taxonomy of risk, assessment, and confidence attributes for every knowledge claim, defined centrally in [`claude_obsidian/ledgers.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/ledgers.py) and validated through the `validate_claim_ledger` function.**

The claude-obsidian project implements a structured knowledge management system where machine-readable claim ledgers track the provenance and reliability of assertions. Understanding the specific risks, assessments, and confidence levels defined for claims in claude-obsidian ensures your metadata validates correctly against the built-in linting engine.

## Core Claim Attributes in [`claude_obsidian/ledgers.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/ledgers.py)

The canonical definitions reside in [`claude_obsidian/ledgers.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/ledgers.py), where three Python sets establish the allowed values for claim metadata. These constants provide the single source of truth used across validation, linting, and export pipelines.

### Risk Levels

Claims declare risk using one of two categorical values:

- `normal` – Standard claims with typical downstream impact
- `high` – Assertions requiring elevated scrutiny or manual review

These values are defined at **line 40** in [`claude_obsidian/ledgers.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/ledgers.py) within the `CLAIM_RISKS` set.

### Assessment States

The assessment field captures the epistemic status of a claim using one of five states defined at **lines 41-47**:

- `accepted` – Validated and trusted assertions
- `provisional` – Tentative claims awaiting further evidence
- `contested` – Claims with conflicting evidence or active dispute
- `unsupported` – Assertions lacking sufficient backing
- `deprecated` – Outdated or superseded claims

### Confidence Ratings

Confidence quantifies certainty on a four-tier scale defined at **line 48** within the `CONFIDENCES` set:

- `high`
- `medium`
- `low`
- `unknown`

## Validation Logic and Enforcement

The `validate_claim_ledger` function enforces these constraints during ledger processing, emitting specific errors for taxonomy violations.

**Risk validation** occurs at **lines 56-58**, verifying that `record["risk"]` exists in `CLAIM_RISKS`. **Assessment validation** follows at **lines 59-60**, checking `record["assessment"]` against `CLAIM_ASSESSMENTS`. **Confidence validation** completes the triad at **lines 61-63**, ensuring `record["confidence"]` membership in `CONFIDENCES`.

Deviation triggers precise error messages: `unsupported risk`, `unsupported assessment`, or `unsupported confidence`. This whitelist approach guarantees consistent, machine-readable provenance across the vault.

## Practical Implementation Examples

### Creating a Valid Claim Ledger Entry

The following JSON structure conforms to the defined enums:

```json
{
  "schema": "claude-obsidian.claim-ledger.v1",
  "generated_at": "2024-09-15T12:00:00Z",
  "claims": {
    "clm-001": {
      "text": "Artificial intelligence will continue to improve language models.",
      "risk": "normal",
      "assessment": "accepted",
      "confidence": "high",
      "location": {
        "path": "wiki/ai_overview.md",
        "anchor": null
      }
    }
  }
}

```

### Constructing Claims Programmatically

Import the canonical sets from `claude_obsidian/ledgers` to ensure compliance:

```python
import json
from pathlib import Path
from claude_obsidian.ledgers import (
    CLAIM_RISKS, CLAIM_ASSESSMENTS, CONFIDENCES,
)

claim = {
    "schema": "claude-obsidian.claim-ledger.v1",
    "generated_at": "2024-09-15T12:00:00Z",
    "claims": {
        "clm-001": {
            "text": "Artificial intelligence will continue to improve language models.",
            "risk": "normal",                       # must be in CLAIM_RISKS

            "assessment": "accepted",               # must be in CLAIM_ASSESSMENTS

            "confidence": "high",                   # must be in CONFIDENCES

            "location": {
                "path": "wiki/ai_overview.md",
                "anchor": None,
            },
        }
    },
}

(Path.cwd() / "wiki/meta/ledgers/claim-ledger.json").write_text(
    json.dumps(claim, indent=2)
)

```

### Validating via CLI

Run the validator to confirm adherence:

```bash
python -m claude_obsidian.scripts.validate claim-ledger.json

```

Changing `risk` to `"critical"` (outside `CLAIM_RISKS`) produces:

```

unsupported risk

```

## Summary

- **Risk taxonomy** supports `normal` and `high` levels defined in [`claude_obsidian/ledgers.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/ledgers.py) line 40
- **Assessment taxonomy** includes five states (`accepted`, `provisional`, `contested`, `unsupported`, `deprecated`) at lines 41-47
- **Confidence taxonomy** comprises four tiers (`high`, `medium`, `low`, `unknown`) at line 48
- **Validation** occurs in `validate_claim_ledger` (lines 56-63), rejecting non-compliant values with specific error messages
- **Test coverage** exists in [`tests/test_lint_engine.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/tests/test_lint_engine.py) and [`tests/test_ledgers.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/tests/test_ledgers.py)

## Frequently Asked Questions

### What error occurs if I specify an invalid risk level?

The validator emits `unsupported risk` when the `risk` field contains any value outside the `CLAIM_RISKS` set. This enforcement occurs at lines 56-58 of [`claude_obsidian/ledgers.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/ledgers.py) during `validate_claim_ledger` execution.

### Can I add custom risk or assessment categories?

No. The validation logic strictly whitelists values against `CLAIM_RISKS`, `CLAIM_ASSESSMENTS`, and `CONFIDENCES`. Extending these taxonomies requires modifying the source definitions in [`claude_obsidian/ledgers.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/ledgers.py) and updating the corresponding test suites.

### How do I access the allowed values programmatically?

Import the constant sets directly from the ledgers module: `from claude_obsidian.ledgers import CLAIM_RISKS, CLAIM_ASSESSMENTS, CONFIDENCES`. These Python sets contain the authoritative strings used throughout the codebase.

### Which files contain the validation tests?

The validation logic for risks, assessments, and confidence levels is exercised in [`tests/test_lint_engine.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/tests/test_lint_engine.py) and [`tests/test_ledgers.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/tests/test_ledgers.py). These unit tests verify that claims with valid enum values pass validation while invalid entries trigger appropriate error messages.