Observation
One measured fact: metric, definition version, scope (repository, project, component, file, type, or member), measurement, and provenance — collector, collector version, configuration, and collection time.
Quality model
Five objects, never blurred together.
Dokimos keeps what was measured apart from what it implies and apart from what an organisation decided. Thresholds can change tomorrow without falsifying anything recorded today.
The layers
Observation, evidence, derived signal, policy, finding.
Every aggregate must decompose into these.
Evidence
Observations held in an immutable snapshot for a repository revision. Evidence is appended, never edited. New analyzer versions create new evidence.
Derived signal
A calculation over evidence: a delta, a direction, a correlation. It records which observations it used, so it can always be taken apart.
Policy
An explicit, versioned rule — threshold or ratchet — with a disposition: observe only, warn, or fail. Policy reads evidence; it never rewrites it.
Finding
A durable record with a stable identity, rule, location, evidence, disposition, first-seen and last-seen snapshots, and a lifecycle state.
Measurement states
Unknown is not good. Unknown is not zero.
Domain type: Measurement in src/Dokimos.Domain/Domain.fs.
| State | Meaning | Example |
|---|---|---|
| Available | A value and unit were measured. | complexity.proxy-cyclomatic = 19 points |
| Unavailable | No value exists, for a stated reason: unsupported, not configured, or insufficient evidence. | No coverage tool configured for this repository. |
| Failed | Collection was attempted and failed, with an error code and message. | Analyzer process exited before producing output. |
A tool that prints nothing when it fails, or records zero warnings when the build never ran, turns missing evidence into false reassurance. Dokimos refuses to: unavailable and failed evidence are carried forward as themselves, and policy evaluates them as not evaluated.
Versioned definitions
A changed definition starts a new series.
Domain type: ComparisonCompatibility.
Every metric has a durable identifier and an integer definition version. Two observations are compatible only when they share the metric, the version, and the unit. Only compatible observations produce a delta.
If the definition of complexity changes from version 1 to version 2, Dokimos reports the comparison as incompatible rather than drawing a line between numbers that mean different things. History keeps its original meaning.
Derived assessments
Trends and correlations, each decomposable.
Sources: Trend.fs, Correlation.fs.
A trend compares two compatible observations under a declared preference and reports its delta and a direction: Improved, Unchanged, Deteriorated, or Not comparable when either side is missing or incompatible.
Correlations require at least two independent kinds of evidence. The table lists the rules the domain defines today; the metrics page shows which of their input signals are collected.
| Correlation | Requires |
|---|---|
| Maintainability hotspot | Structural complexity + frequent change or high churn |
| Unstable public surface | API instability + frequent change or a repeatedly modified region |
| Untested high change | No corresponding test change + high churn or frequent change |
| Agent-generated risk pattern | Type weakening or dependency additions + no corresponding test change. Does not assert authorship. |
| Persistent debt hotspot | Aged debt + frequent change or a repeatedly modified region |
Policy
Thresholds, ratchets, and their results.
Source: src/Dokimos.Core/Policy.fs.
A threshold is a fixed limit with a disposition. It answers: is this value acceptable by an organisational standard?
A ratchet is a limit set by the best accepted value the repository has demonstrated, with a declared preference (lower or higher is better) and a disposition. It answers: has this code slipped from a state it already proved it could reach?
| Result | When |
|---|---|
| Pass | Evidence available and within the limit, or the disposition is observe-only. |
| Warning | Evidence exceeds the limit and the disposition is warn. Reports the actual value and the limit. |
| Failure | Evidence exceeds the limit and the disposition is fail. Reports the actual value and the limit. |
| Not evaluated | Evidence is unavailable or collection failed. Missing evidence never passes and never fails a gate by being read as zero. |
Finding lifecycle
Findings have a past, not just a present.
Domain type: FindingState. Transitions: Findings.fs.
| State | Transition rule |
|---|---|
| Introduced | Absent in the previous snapshot, present now. |
| Persistent | Present in both, with the same magnitude (or no magnitude). |
| Improved | Present in both, with a smaller magnitude now. |
| Regressed | Present in both, with a larger magnitude now. |
| Resolved | Present previously, absent now. |
| Resurfaced | Present again after having been resolved. |
If either snapshot's evidence is unknown, no transition is recorded. Finding identities use fingerprints of rule, semantic scope, and location; when code moves and identity becomes uncertain, the match is recorded as uncertain instead of asserted. Suppressions and accepted exceptions — with reason, scope, author, and expiry — are required (R3) but not yet implemented.
Baselines
Legacy debt can be baselined without permitting new debt.
Requirement R4.
| Baseline | Status | Detail |
|---|---|---|
| Accepted baseline | Implemented | BASELINE-0001: promoted only after verified green CI; stored as baselines/accepted-snapshot.json. |
| Best-demonstrated ratchet | Implemented | A metric may not deteriorate beyond its best accepted value (Policy.evaluateRatchet). |
| Fixed baseline | Experimental | Any compatible snapshot can be compared with dokimos compare; there is no named fixed-baseline registry yet. |
| Branch baseline | Planned | Compare a branch with its own accepted state (R4). |
| Release baseline | Planned | Compare release to release (R4, R5). |
See ratcheting in action on the overview's demonstration trajectory.