Orthemology is a formal framework, not a software library. There is no package to install and no API to call. Instead, the repository ships JSON schemas, a normative registry of verdict and notation identifiers, a suite of machine-readable worked examples, and Python validator scripts that check everything against each other. This guide walks you through validating the framework’s own internal consistency, then points you to the first worked episode so you can read the framework in action.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.
All commands assume you are working from the repository root. The validators require Python 3, pyyaml, and jsonschema — all available via
pip. No other runtime dependency is needed.Prerequisites
Before you begin, make sure you have:- Python 3.8 or later —
python --version - pyyaml and jsonschema —
pip install pyyaml "jsonschema>=4.18"
Onboarding steps
Clone the repository
Fetch the repository and move into it:The top-level layout you will navigate most often:
| Path | Contents |
|---|---|
schemas/ | JSON Schema files for every object type |
examples/ | Nine machine-readable episode examples |
docs/verdict-registry.yaml | Normative verdict semantic IDs |
docs/notation-registry.yaml | Symbol table |
scripts/ | Validator scripts |
theory/orthemic-core-formalization.md | Canonical formalization |
manuscript/orthemma-ortheme-systems-revised-draft.md | Current main manuscript |
Validate the JSON schemas
Run the schema validator to confirm that all schemas are internally well-formed and that the normative registries agree with each other:A clean run prints a summary of every schema checked and exits with code 0. If you see errors, the output identifies which schema file and which constraint failed.
Run the full validator suite
The full suite validates every example JSON in The suite covers:
examples/ against its declared schema, runs the deterministic fixture tests, and checks the generated project-state file against the source documents:- Positive fixtures (F1–F7)
- Negative fixtures (I01–I48)
- Registry consistency
Seven deterministic fixtures, each witnessing a distinct cell or boundary condition in the result × pathway matrix:
Each fixture is a fully schema-valid episode record carrying an explicit verdict record whose
| Fixture | What it witnesses |
|---|---|
| F1 | Nominal verification — result correct, pathway adequate |
| F2 | Correct result, defective pathway (stopped-clock case) |
| F3 | Incorrect result, adequate pathway (rare-case miss) |
| F4 | Correct result, defective pathway (defective metaorthemma — wrong reference plane, tolerance, or calibration; result happens to be right) |
| F5 | Undetermined verdict state |
| F6 | Stale-directive case |
| F7 | Safe but sub-optimal routing (V4b advisory) |
pathway_state value is tested for correctness. These fixtures prove the framework’s four result × pathway cells are all representable — not just theoretically, but in the machine-readable format.Read the pillar episode
Open
Once you are comfortable with the pillar episode, the other eight examples in
examples/pillar-episode.json. This is the primary worked example — a construction-site perpendicularity check on pillar B7. It is shaped like a F1 fixture: nominal verification with a correctly bound metaorthemma, result correct, pathway adequate.The file is a JSON array of schema-instance pairs. Reading them in order walks you through the full lifecycle:| Part | Schema | What it records |
|---|---|---|
| 1 | analysis.schema.json | The declared analysis: task, repertoire, axes, tolerance 0.002, evidence rules, boundary |
| 2–3 | metaortheme.schema.json | Two governing metaorthemes: the perpendicularity standard (V-component) and the calibration policy (E-component) |
| 4 | orthemma.schema.json | The concrete case: pillar B7, version as-poured-2026-07-01 |
| 5 | metaorthemma.schema.json | The case-bound configuration token binding the standard to pillar B7, instrument level-114, and datum plane D2 |
| 6 | orthing-episode.schema.json | The episode record: actor fitter-9, time 2026-07-02T08:30–09:00Z, evidence, placement within-tolerance, route release-for-load-transfer |
| 7 | claim-ledger.schema.json | The claim ledger: one placement claim claim-perp, its evidence references, residual burden, and closure assertion |
| 8 | verdict-record.schema.json | The verdict record: all pathway dimensions pass, pathway_state: adequate, ROBUST_NEIGHBORHOOD: not-applicable with stated reason |
The analysis declares two axes:
perpendicularity (exclusive alternatives: within-tolerance / out-of-tolerance) and surface-condition (co-holding values: cracked, stained, clean). The episode’s placement records both — the pillar is within-tolerance and clean. Notice how the verdict record’s required_path field is governance-derived from the episode’s configured metaorthemes, not set by the auditor.examples/ cover different shapes: stale-directive patterns, multi-metaorthemma episodes, and defective-pathway cases.Running the verdict semantics validator
The verdict registry enforces a strict contract between semantic IDs (machine keys such asRESULT_CORRECT, EVIDENCE_SUPPORT) and their display aliases and descriptions. To check that contract in isolation:
docs/verdict-registry.yaml, checks that every semantic ID referenced in example verdict records exists in the registry, and verifies that no two IDs map to the same display alias. It is also called by validate_repo.py, but running it independently is useful when authoring new episode examples.
What to read next
The formal core
The formal core
theory/orthemic-core-formalization.md is the canonical statement of the formalization: type/token resolution, level-indexing, metaortheme and metaorthemma definitions, the verdict layer, and the abbreviation convention for analysis-relative notation. Read §1 (type/token, level-indexing) before §4 (verdicts).The main manuscript
The main manuscript
manuscript/orthemma-ortheme-systems-revised-draft.md is the current full-length research draft. The abstract and §1 give the integration-discipline thesis. §2 defines analyses, orthemmata, orthemes, and profiles formally. §4 defines the verdict vector. §6 covers episode reification and multi-actor settings.Decision records
Decision records
docs/decisions/ contains records 0001–0019. Decision 0001 establishes analysis-relative ground truth; 0003 establishes the result-free pathway core; 0004 freezes the verdict semantic IDs; 0005 freezes the notation registry. Reading these helps you understand why the framework is structured as it is.