Add diagnostic contract primitives

docs/adr/0015-separate-process-warnings-from-quality-diagnostics.md

@@ -0,0 +1,67 @@
+# ADR-0015: Separate process warnings from quality diagnostics
+
+**Status:** Accepted
+**Date:** 2026-08-27
+
+## Context
+
+Notarius currently represents process degradation, incomplete validation,
+extraction-quality doubt, and routine normalization with one flat warning
+record. That makes ordinary successful runs noisy, loses the framework context
+needed to explain a finding, and gives `warning_count` no stable operational
+meaning. It also permits output encoders to add a warning after the durable
+warning file has already been written.
+
+The application needs one bounded diagnostic model that preserves exact
+occurrence counts while retaining only safe, representative samples. Fresh and
+resumed logical runs must present the same groups. The model must not alter
+validation decisions, retry budgets, rejected-output behavior, or process exit
+policy.
+
+## Decision
+
+Warnings are reserved for a completed run that advanced under an allowed
+process-level degradation or incomplete-work policy. Extraction-quality signals
+are advisories, and routine accepted transformations are observations. A
+non-degraded successful run therefore has zero actionable warnings.
+
+Modules and validators own a diagnostic's disposition, category, reason code,
+scope, and safe message. The framework adds pipeline origin, including stage,
+step, lane, module, validator, and chunk context where applicable. It then
+aggregates deterministically by disposition, category, reason code, and full
+origin. Chunk context remains on representative samples so equivalent findings
+across chunks aggregate together.
+
+Diagnostics carry exact occurrence counts, at most three distinct samples, and
+numeric omitted-sample metadata. Producers and validators are bounded to 64
+local groups. Final actionable warning groups are bounded without truncation;
+the non-warning collection may truncate represented groups while preserving an
+exact total occurrence count and explicit truncation metadata.
+
+The public contracts will be versioned: grouped actionable warnings use
+`notarius.warnings.v2`, grouped advisories and observations use
+`notarius.diagnostics.v1`, and the run receipt uses
+`notarius.run-result.v2`. Successful output encoders return logical files or
+an error; they do not add post-encoding warnings.
+
+## Alternatives considered
+
+- Keep one warning list and filter only CLI output. This would leave durable
+  consumers with the same semantically mixed, unbounded contract.
+- Map reason codes to severity in a central framework registry. This would
+  split module-owned meaning between synchronized policy tables and make new
+  diagnostic meaning implicit.
+- Preserve local omission warning records. They inflate visible group counts
+  and lose exact occurrence semantics.
+- Keep output-encoder warnings. A one-pass encoder cannot include those
+  records consistently in files it has already serialized; a two-phase encoder
+  protocol is deferred until a demonstrated need exists.
+
+## Consequences
+
+The framework gains validated diagnostic primitives, local collection,
+origin-aware aggregation, and versioned durable presentation. Existing warning
+transport remains temporarily while producers migrate. Current architecture,
+operator, integration, and internal documentation will describe the behavior
+only as each implementation step lands; this accepted decision does not claim
+that the migration is complete.

docs/roadmap/implementation.md

@@ -193,7 +193,7 @@ Remove `OutputResult.Warnings`. An output encoder either returns its complete
 logical files or returns an error. It cannot discover a warning after the
 warning file has already been serialized.
 
-## Stage 1 — Record The Decision And Add Core Diagnostic Primitives
+## Stage 1 ✅ — Record The Decision And Add Core Diagnostic Primitives
 
 ### Goal