Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/theislampill/orthemology/llms.txt

Use this file to discover all available pages before exploring further.

Orthemology ships a suite of Python validation scripts that check internal consistency across schemas, examples, verdict registries, and fixture files. These are deterministic consistency tools — they prove that the formal objects are well-formed and mutually consistent, not that any empirical claim is true.
All validators use deterministic checks only. A green validator establishes record shape and internal agreement, never source truth.

​
Setup

1

Install Python dependencies

The validators require Python 3 plus pyyaml and jsonschema>=4.18:
pip install pyyaml "jsonschema>=4.18"
2

Clone the repository

All scripts are in the scripts/ directory at the repository root:
git clone https://github.com/theislampill/orthemology.git
cd orthemology
3

Run the full suite

To run every validator at once:
python scripts/validate_repo.py
Output is a series of [PASS] / [FAIL] lines. A non-zero exit code means at least one check failed.

​
Schema Validators

File: scripts/validate_schemas.pyWhat it validates:
  • Every schemas/*.schema.json compiles as valid JSON Schema Draft 2020-12
  • The complete schema inventory matches what is declared in docs/current-state.yaml
  • Every example in examples/*.json validates against its declared schema field
  • The verdict-record.schema.json enum equals the registry’s semantic ID set (registry-driven check)
Run:
python scripts/validate_schemas.py
Expected output pattern:
[PASS] all 8 core schemas present
[PASS] the complete schema inventory declared by current state compiles (10 schemas)
[PASS] schema compiles: analysis.schema.json
[PASS] schema compiles: orthemma.schema.json
...
[PASS] verdict-record enum equals registry semantic IDs
[PASS] example: examples/pillar-episode.json
...
File: scripts/validate_negative_fixtures.pyWhat it validates: Every fixture in tests/invalid/ (I01–I48) is rejected by the schema it declares itself invalid against. This confirms the schemas actually enforce their constraints, not just accept everything.Run:
python scripts/validate_negative_fixtures.py
All 48 negative fixtures cover known invalid patterns, including:
  • Empty task analysis (I01)
  • Duplicate state metaortheme (I03)
  • Unresolved residual without queue (I08)
  • Verdict without objectivity index (I17)
  • Claim path collapsed into episode path (I24)
  • Token anchored to another occurrence (I28)
  • Analysis self-inheritance or cycle (I29–I30)
  • Robustness silently disabled (I48)

​
Semantic Validators

File: scripts/validate_verdict_semantics.pyWhat it validates:
  • All verdict records in examples use only semantic IDs present in docs/verdict-registry.yaml
  • Status values are from the declared status_enum
  • pathway_state is consistent with the statuses on required_path
  • na_reasons is present for every not-applicable status
Run:
python scripts/validate_verdict_semantics.py
File: scripts/validate_cross_record_semantics.pyWhat it validates:
  • A closure_claim in a claim ledger is ill-formed while any residual has disposition: unresolved (Definition 13)
  • TOKEN_TRUTH_LINKED: pass entails RESULT_CORRECT: pass for the same claim
  • Unresolved external references are incompatible with record_mode: audit-ready
This check enforces the whole-state reread rule: resolving one burden may invalidate another, so a closure claim is blocked until all residuals are disposed.Run:
python scripts/validate_cross_record_semantics.py
File: scripts/validate_claim_reasoning_paths.pyWhat it validates:
  • Each claim_reasoning_paths entry’s req_reason is a subset of the episode’s required_path
  • reasoning_path_adequate is the correct conjunction over req_reason verdicts
  • No claim-level reasoning_path_adequate: adequate when any req_reason verdict is fail
Run:
python scripts/validate_claim_reasoning_paths.py

​
Generator Scripts

File: scripts/generate_from_registry.pyWhat it does: Generates derived surfaces from docs/verdict-registry.yaml as the canonical source:
  • The verdict enum in verdict-record.schema.json ($defs.verdict_id.enum)
  • The prose alias table at docs/generated/verdict-aliases.md
Run in check mode (CI drift gate):
python scripts/generate_from_registry.py --check
This verifies that the committed generated files match what would be generated from the registry. Any drift (e.g., a hand-edited alias or enum) causes a failure.Run in write mode:
python scripts/generate_from_registry.py
Do not hand-edit docs/generated/verdict-aliases.md or the $defs.verdict_id.enum in verdict-record.schema.json. Edit docs/verdict-registry.yaml and re-run the generator.

​
Other Validators

The following additional validators are included in the full suite run by validate_repo.py:
ScriptWhat it checks
validate_notation.pyAll documents follow the normative symbol table from notation-registry.yaml; no retired symbols appear in new work
validate_type_token_semantics.pyType/token distinction is correctly applied; episodes are tokens, orthemes are types
validate_source_status.pyreferences/source-status.yaml statuses are consistent across claim families
validate_current_state.pydocs/current-state.yaml is internally consistent; VERSION, README, STATUS agree with it
validate_schemas.py(see above)
validate_latent_state_fixtures.pyLatent-state fixtures in tests/latent-state-fixtures.json validate correctly
validate_reason_fixtures.pyClaim-reasoning fixtures in tests/claim-reasoning-fixtures.json validate correctly
# Run individual validators
python scripts/validate_notation.py
python scripts/validate_source_status.py
python scripts/validate_current_state.py

Build docs developers (and LLMs) love

Get started for freeTalk to us