DokimosEchelon Foundry

Dokimos · Code-quality assurance from Echelon Foundry

Know whether your codebase is getting better.

Dokimos records code-quality evidence at every commit and keeps it. It shows how quality changed, where risk is concentrating, and which observations and policies produced each conclusion.

Explore what Dokimos measures View the project on GitHub

The problem

A single report cannot tell you which way you are moving.

Same file, same commit, two readings.

A static-analysis run answers one question: does this code break a rule right now? It cannot say whether the code is better or worse than last month, whether the team already proved it could do better, or whether a quiet number hides a file that is rewritten every week.

Those are the questions that decide where engineering attention should go. Answering them requires history, and history is only trustworthy if every observation is kept with the revision, analyzer, and metric definition that produced it.

What each approach reports for src/Billing/InvoiceRules.fs at commit H (demonstration data)
QuestionPoint-in-time reportDokimos
Is complexity acceptable?37 is under the warn threshold of 45. Pass.Pass against the threshold, and Warning against the ratchet: +6 points worse than the best demonstrated state (31 at D).
Which way is it moving?Not answerable.+4 since the previous snapshot; −5 since the baseline.
What happened when the analyzer failed?No report, or a report that silently omits the file.Commit E is recorded as Failed. Nothing was evaluated, and nothing was recorded as zero.
Is this file risky?Not answerable.Complex and changed in 7 commits in 90 days: a hotspot, with the same region rewritten repeatedly.

What Dokimos inspects

Quality dimensions, each labelled with how real it is today.

Status is checked against the accepted baseline snapshot at build time.

Implemented measurements are emitted in Dokimos's own accepted baseline. Experimental ones have tested logic that is not yet collected into snapshots. Planned ones are requirements only. Read every metric definition and its limitations.

Quality over time

Code quality is a trajectory, not a snapshot.

Question answered: is this file better or worse than it has been, and does policy care?

Demonstration data. This history describes a fictional repository invented for demonstration. It is not a measurement of any real codebase.

Current (H)

37

points, lexical complexity proxy

Since previous (G)

+4

Deteriorated

Since baseline (A)

−5

Improved

Since best (D)

+6

Deteriorated

Complexity of src/Billing/InvoiceRules.fs across commits A to H Complexity fell from 42 at the baseline to a best of 31 at commit D, has no value at commit E because collection failed, and rose to 37 at commit H. The warn threshold is 45.
The line breaks at commit E: collection failed, so there is no value to draw. The vertical bar at H is the distance from the best demonstrated state. The fail threshold (60) lies above the plotted range.
Data table for this chart
Complexity observations by commit (demonstration data)
CommitDateChangeMeasurementValueNote
A · a41c09e 2026-03-02 Dokimos installed; first snapshot Available 42 Baseline
B · b7d2f31 2026-03-16 Extract discount calculation Available 39
C · c02e8a4 2026-04-06 Replace nested rules with a table Available 34
D · d5f1b70 2026-04-27 Split currency rounding into Money Available 31 Best demonstrated
E · e93a6cd 2026-05-11 Analyzer upgrade failed in CI Failed — Analyzer process exited before producing output.
F · f18c4e2 2026-06-01 Add loyalty discount Available 33
G · a6e7d93 2026-06-22 Rename discount tiers Available 33
H · b0c5a18 2026-07-13 Add partner discount exception Available 37 Current

Ratcheting: the best state you have shown becomes the expectation.

A universal threshold says 37 is fine because it is under 45. But this file reached 31 at commit D. A ratchet keeps that demonstrated state as the bar, so drifting back toward the old condition is visible instead of silently permitted.

The ratchet does not rewrite history or punish the baseline. Legacy debt can stay baselined while new deterioration is still caught. The disposition — observe only, warn, or fail — is policy, and it is chosen per metric.

Threshold: warn above 45, fail above 60
Pass 37 ≤ 45
Ratchet: best demonstrated 31, disposition Warn
Warning 37 > 31

From measurement to judgment

An observation is not a judgment.

Policies can change without falsifying history.

Demonstration data. Examples use the fictional repository from the trajectory above.

  1. Observation

    A fact measured under a versioned definition: complexity.proxy-cyclomatic v1 = 37 for InvoiceRules.fs at b0c5a18.

  2. Evidence

    Observations held in an immutable snapshot with provenance: repository, revision, collector, configuration, time.

  3. Derived signal

    A calculation over evidence: +4 since G; complexity plus change pressure forms a hotspot.

  4. Policy

    An explicit rule applied to the evidence: ratchet at 31, disposition Warn.

  5. Finding

    A durable object with a stable identity, a lifecycle state, and links back to all of the above.

Raw observation

What was measured

Directly observed and never reinterpreted.

  • complexity = 37
  • file changed 7 times in 90 days
  • region applyDiscounts changed in 6 commits
  • collection failed at commit E

Derived assessment

What the evidence implies

Calculated from observations, and decomposable back into them.

  • deteriorated since G
  • improved since the baseline
  • emerging maintainability hotspot
  • finding resurfaced after resolution

Policy judgment

What the organisation decided

An explicit rule with a named disposition.

  • threshold: Pass
  • ratchet: Warning
  • commit E: Not evaluated
  • accepted exception (planned)

Read the full quality model, including measurement states, comparison compatibility, and baselines.

Hotspots

Complexity is a risk only where the code keeps changing.

Question answered: where is risk concentrated right now?

Demonstration data. The same fictional repository, at commit H.

Complex code that nobody touches is a cost you pay rarely. Simple code that changes every week is cheap to change. The files that deserve attention are complex and repeatedly modified. Dokimos keeps both dimensions visible instead of collapsing them into one opaque score.

File-level churn is coarse: a routes file may change often because new routes are appended. When Git evidence allows, Dokimos tracks repeated changes to the same region, with a confidence value, because rewriting the same function again and again is stronger evidence than a busy file.

Complexity against change frequency for five files src/Billing/InvoiceRules.fs: complexity 37, 7 commits, complex and changing; src/Billing/Statements.fs: complexity 22, 4 commits, simple, stable; src/Api/Routes.fs: complexity 7, 9 commits, changing, simple; src/Billing/TaxTables.fs: complexity 48, 1 commits, complex, stable; src/Core/Money.fs: complexity 8, 1 commits, simple, stable
Squares mark files in the complex-and-changing quadrant. A ring marks a repeatedly modified region.
Data table for this chart
Structural and temporal evidence per file (demonstration data)
FileComplexityCommits (90 days)Churn (lines)Most-changed regionClassification
src/Billing/InvoiceRules.fs 37 7 412 applyDiscounts: 6 commits (confidence 0.92) — repeated Complex and changing
src/Billing/Statements.fs 22 4 96 renderLines: 2 commits (confidence 0.81) Simple, stable
src/Api/Routes.fs 7 9 230 registerRoutes: 2 commits (confidence 0.88) Changing, simple
src/Billing/TaxTables.fs 48 1 12 No region evidence Complex, stable
src/Core/Money.fs 8 1 4 No region evidence Simple, stable

Findings have histories

A finding is a durable record, not a console message.

States are the ones defined in the Dokimos domain.

Demonstration data. Maintainability-hotspot finding for src/Billing/InvoiceRules.fs: present when complexity ≥ 30 and the file changed in ≥ 5 commits in 90 days.

  1. A · a41c09e

    First observed

    Complexity 42, 6 commits. No earlier snapshot, so no transition is claimed.

  2. B · b7d2f31

    Improved

    Complexity 39, 6 commits.

  3. C · c02e8a4

    Improved

    Complexity 34, 5 commits.

  4. D · d5f1b70

    Resolved

    Complexity 31, 4 commits.

  5. E · e93a6cd

    Not evaluated

    No complexity value: no transition is recorded.

  6. F · f18c4e2

    Resurfaced

    Complexity 33, 5 commits.

  7. G · a6e7d93

    Persistent

    Complexity 33, 6 commits.

  8. H · b0c5a18

    Regressed

    Complexity 37, 7 commits.

Dokimos does not claim the finding was introduced at A: there is no earlier evidence. At E the evidence is missing, so the state is not evaluated rather than assumed resolved.

Explainability

Every conclusion opens down to its evidence.

Open each level to follow the chain.

Demonstration data. A drill-down for the ratchet warning at commit H.

Summary Warning Ratchet warning on InvoiceRules.fs at H
Policy judgment Ratchet for complexity.proxy-cyclomatic, disposition Warn

Rule: the value must not exceed the best demonstrated state (31, commit D, d5f1b70). Actual 37. Result Warning. The universal threshold (warn above 45) independently evaluates to Pass.

Derived assessment +6 from best, +4 from previous

Compared only with compatible observations (same metric, definition version 1, same unit). Commit E is excluded because collection failed; it is not treated as zero.

Observations 7 available, 1 failed
RevisionMetricScopeStateValueCollector
D · d5f1b70complexity.proxy-cyclomatic v1src/Billing/InvoiceRules.fsAvailable31dokimos-cli/1 (illustrative)
E · e93a6cdcomplexity.proxy-cyclomatic v1src/Billing/InvoiceRules.fsFailed—dokimos-cli/1 (illustrative)
G · a6e7d93complexity.proxy-cyclomatic v1src/Billing/InvoiceRules.fsAvailable33dokimos-cli/1 (illustrative)
H · b0c5a18complexity.proxy-cyclomatic v1src/Billing/InvoiceRules.fsAvailable37dokimos-cli/1 (illustrative)

Dokimos on Dokimos

The first longitudinal dataset is Dokimos itself.

Rendered from the accepted baseline in this repository at build time.

Real Dokimos evidence. Snapshot of kemiller2002/dokimos at 46c8385 (main), collected 2026-09-26 by dokimos-cli/1.

Observations

154

7 metrics across 22 F# files

Findings

2

maintainability-hotspot (present)

Ratchets

2

build.compiler-errors ≤ 0; build.compiler-warnings ≤ 0

Findings in the accepted Dokimos baseline
ScopeFindingEvidence
src/Dokimos.Cli/Program.fsmaintainability-hotspot (present)structural-complexity 19, frequent-change 7, high-churn 101
src/Dokimos.Domain/Domain.fsmaintainability-hotspot (present)structural-complexity 30, high-churn 116

Echelon ecosystem

Dokimos owns quality evidence, and nothing else.

Integration happens through explicit evidence boundaries.

Dokimos
Code-quality evidence, history, comparison, and quality-policy evaluation.
Praxis / ROS
Engineering work, execution attribution, provenance, and development telemetry. Dokimos may correlate with it; it does not re-own it.
Tutela
Security assurance. Security-specific analysis routes there rather than into a competing Dokimos authority.
Aegis
Unexpected operational faults at Git, filesystem, process, and persistence boundaries. Expected outcomes, such as unavailable metrics, stay typed Dokimos results.
Ordo
Engineering and state methodology that Dokimos's repository follows.

Dokimos runs on its own. When an Echelon system is absent, Dokimos records that the evidence is unavailable; it never fails or fabricates data because a neighbour is missing. See the architecture and boundaries.

Start using Dokimos

Measure a repository from source today.

Dokimos is built from source with the .NET 8 SDK. The CLI is deterministic and emits schema-versioned JSON.

git clone https://github.com/kemiller2002/dokimos.git
cd dokimos
dotnet build Dokimos.sln
git log --numstat --find-renames --format='commit %H %aI' -- src > history.txt
dotnet run --project src/Dokimos.Cli -- snapshot src --git-history history.txt \
  --repository owner/repo --revision "$(git rev-parse HEAD)" --ref main
See how an analysis runs Read the source on GitHub