What Are the Assessment States for Claims in Claude-Obsidian?

Claude-Obsidian defines five distinct assessment states—accepted, provisional, contested, unsupported, and deprecated—to track the reliability and evidentiary status of every knowledge claim in the vault.

The AgriciDaniel/claude-obsidian repository implements a structured knowledge-management system where each claim's credibility is explicitly tracked via an assessment field inside the claim ledger. Understanding these assessment states is essential for maintaining data integrity and accurately representing the evidentiary confidence of your Obsidian vault contents.

The Five Assessment States Defined

The permissible assessment values are codified as the CLAIM_ASSESSMENTS constant in claude_obsidian/ledgers.py at lines 41-47. Each state carries specific semantic weight regarding the claim's evidentiary standing.

Accepted

A claim marked accepted is regarded as reliable and uncontroversial within the knowledge base. This status indicates the claim may be used as a factual foundation for reasoning without requiring additional justification or caveats.

Provisional

The provisional state indicates tentative acceptance. While the claim is treated as likely valid, it awaits further evidence, peer review, or corroboration before graduating to full acceptance. This serves as a flag for claims that require monitoring.

Contested

When conflicting evidence exists or consensus is fractured, a claim is marked contested. This state signals that the claim's status is disputed and requires adjudication, additional research, or cross-referencing with contradictory sources before it can be relied upon.

Unsupported

Claims lacking any backing evidence receive the unsupported assessment. This state prevents the claim from being treated as factual within the system while still preserving the claim record for future documentation.

Deprecated

A deprecated claim has been superseded by newer evidence, rendered obsolete, or invalidated within the knowledge base. This state explicitly marks the claim as no longer valid while maintaining historical record for audit purposes.

Where Assessment States Are Defined in the Source Code

In claude_obsidian/ledgers.py, the complete enumeration of valid states is stored in the CLAIM_ASSESSMENTS constant. This centralized definition ensures schema consistency across the codebase:

# From claude_obsidian/ledgers.py (lines 41-47)

CLAIM_ASSESSMENTS = [
    "accepted",
    "provisional", 
    "contested",
    "unsupported",
    "deprecated"
]

This constant is referenced throughout the validation and transaction layers to ensure only these five string values are permitted in the assessment field.

Validation and Enforcement

The ledger validation routine validate_claim_ledger enforces assessment integrity at lines 958-960 of claude_obsidian/ledgers.py. This function verifies that every claim's assessment field is a string belonging to the CLAIM_ASSESSMENTS set, raising a validation error if an invalid or missing assessment is detected.

Additionally, the test suite in tests/test_ledgers.py exercises these validation rules, ensuring that claim ledgers reject malformed assessment values before being committed to disk.

How to Assign Assessment States to Claims

When constructing a claim entry programmatically, import the ledger utilities and set the assessment field to one of the five valid strings:

from claude_obsidian.ledgers import stable_source_id, empty_claim_ledger

# Generate a stable source identifier

src_id = "src-1234567890abcdef"

# Construct a claim with assessment state

claim = {
    "source_id": src_id,
    "content_kind": "document",
    "authority": "official",
    "review_status": "active",
    "assessment": "contested",  # Must be one of the five valid states

    "evidence": [
        {
            "relation": "contradicts",
            "source_id": "src-0987654321fedcba"
        }
    ],
    "notes": "Evidence from recent study conflicts with earlier data."
}

# Initialize and populate the ledger

ledger = empty_claim_ledger()
ledger["claims"][f"claim-{src_id}"] = claim

The claude_obsidian/transaction.py module handles the atomic reading and writing of these ledgers, integrating the assessment field into the broader data-integrity workflow.

Claim Ledger Storage Format

Assessment states are persisted in wiki/meta/ledgers/claim-ledger.json. Below is the JSON representation of a claim with the contested assessment:

{
  "schema": "claude-obsidian.claim-ledger.v1",
  "generated_at": "2024-11-08T12:34:56Z",
  "claims": {
    "claim-src-1234567890abcdef": {
      "source_id": "src-1234567890abcdef",
      "content_kind": "document",
      "authority": "official",
      "review_status": "active",
      "assessment": "contested",
      "evidence": [
        {
          "relation": "contradicts",
          "source_id": "src-0987654321fedcba"
        }
      ],
      "notes": "Evidence from recent study conflicts with earlier data."
    }
  }
}

Summary

• Accepted, provisional, contested, unsupported, and deprecated are the five valid assessment states defined in CLAIM_ASSESSMENTS within claude_obsidian/ledgers.py.
• The assessment field in wiki/meta/ledgers/claim-ledger.json tracks each claim's evidentiary confidence.
• Validation occurs via validate_claim_ledger (lines 958-960), which rejects any assessment value outside the defined set.
• The transaction layer in claude_obsidian/transaction.py persists these states atomically to disk.

Frequently Asked Questions

What happens if I use an invalid assessment value?

The validate_claim_ledger function raises a validation error during ledger processing. According to the source code enforcement at lines 958-960 of claude_obsidian/ledgers.py, only the five strings defined in CLAIM_ASSESSMENTS are permitted; any other value will prevent the ledger from being saved.

Can I change a claim's assessment after creation?

Yes. The claim ledger in wiki/meta/ledgers/claim-ledger.json is mutable within transactions managed by claude_obsidian/transaction.py. You can update the assessment field from provisional to accepted (or any other valid transition) as new evidence emerges, provided the new value remains within the CLAIM_ASSESSMENTS constant.

What is the difference between "contested" and "unsupported"?

Contested indicates active conflicting evidence exists against the claim, requiring resolution. Unsupported means the claim currently lacks any evidence backing it, but does not necessarily imply contradiction. A claim can move from unsupported to accepted by adding evidence, whereas contested typically requires adjudication of conflicting sources.

How does Claude-Obsidian handle deprecated claims?

The deprecated state explicitly marks claims as invalid or superseded while preserving them in claim-ledger.json for historical context. Unlike deleted records, deprecated claims remain queryable for audit trails but are flagged to prevent their use as factual foundations in current knowledge synthesis.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}