diff --git a/docs/internal/dnd.md b/docs/internal/dnd.md index d3c0b2ef..97aa9cfc 100644 --- a/docs/internal/dnd.md +++ b/docs/internal/dnd.md @@ -149,7 +149,7 @@ rule. Configuration owns the exact validator key and chain position. Normalizers are deterministic for spells, combat turns, item occurrences, NPC occurrences, scene descriptions, enemy events, and location occurrences. They canonicalize display values and evidence, use source-document order for stable -output, and issue bounded warnings for changes or collapsed duplicates. NPC, +output, and emit bounded normalization observations for changes or collapsed duplicates. NPC, item, and location registry normalizers are intentional exceptions: each first produces a deterministic candidate set, then may use a bounded structured-LLM proposal to reconcile identity groups. diff --git a/docs/internal/modules.md b/docs/internal/modules.md index a28a11e4..b8e7531b 100644 --- a/docs/internal/modules.md +++ b/docs/internal/modules.md @@ -102,7 +102,7 @@ returned duplicate groups into a stable non-overlapping plan. The normalizer then applies that plan through a typed `ApplicationPolicy`. The core preserves ungrouped records, contribution order, and provenance while the artifact family owns group guards, field and evidence consolidation, durable -ID derivation, retry and fallback presentation, warnings, and postconditions. +ID derivation, retry and fallback presentation, classified diagnostics, and postconditions. Request-local handles do not enter the typed value or durable artifact. Fewer than two eligible candidates skips model invocation; exceeding a candidate or combined-material bound preserves the deterministic result under the family's diff --git a/docs/internal/pipeline.md b/docs/internal/pipeline.md index f2656c06..4655da5c 100644 --- a/docs/internal/pipeline.md +++ b/docs/internal/pipeline.md @@ -150,8 +150,8 @@ oversized aggregate is a framework contract error; guidance is never inferred or truncated. The runner applies the binding's retry policy around a stage operation and its -complete validation chain. It preserves warnings only from the final accepted -or rejected attempt, plus one fixed warning per validator whose execution +complete validation chain. It preserves terminal diagnostics only from the final accepted +or rejected attempt, plus one fixed validation-incomplete warning per validator whose execution budget was exhausted under `warn_continue`. Cancellation stops retries. Normalizer-specific retry directives consume this same budget and validate any final safe fallback through the normalizer chain. @@ -171,13 +171,13 @@ Chunk planning uses this state machine for generated plans. A rejected or validation-incomplete automatic cache hit is not model material and therefore falls through to a fresh initial generation at producer attempt one; it neither receives a correction, consumes retry budget, promotes cached-candidate -warnings, nor overwrites the stored record. An incomplete cache validation +diagnostics, nor overwrites the stored record. An incomplete cache validation under `fail_run` terminates instead. Only a newly generated, completely validated plan is published to the chunk-plan store. Rejected plans never advance, and validation-incomplete plans remain unpublishable. After terminal lane work, the runner assembles manifest provenance, normalized -artifacts, rejections, warnings, and an optional accepted chunk map. When an +artifacts, rejections, final grouped diagnostics, and an optional accepted chunk map. When an output policy selected evidence lanes, it decodes accepted serialized normalize outputs through their registered codecs and invokes the prepared typed projectors. Rejected or absent lanes contribute nothing. This reconstruction is diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index b95d2ed8..9bb1407d 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -146,8 +146,9 @@ lanes, validators, and LLM profile: the canonical source digest selects the plan, while the current run still applies its configured chunk validators to the materialized chunks. -The framework owns orchestration and handoff provenance. Modules return logical -results and warnings; they do not own CLI reporting, physical output, cache, or +The framework owns orchestration, origin enrichment, aggregation, and handoff +provenance. Modules return logical results and classified diagnostics; they do +not own CLI reporting, physical output, cache, or debug roots, durable file placement, or checkpoint and debug lifecycle. After pipeline-wide chunking, extraction uses bounded framework concurrency. @@ -159,17 +160,26 @@ may overlap. The framework must not create unbounded goroutines per lane or chunk. Completion timing does not choose public ordering or errors. The coordinator -orders accepted artifacts, warnings, rejections, checkpoint events, and +orders accepted artifacts, grouped diagnostics, rejections, checkpoint events, and framework errors by stable pipeline scope. Rejections do not cancel unrelated work. A framework error cancels derived work, prevents undispatched work from starting, waits for started work, and prevents output encoding. +Warnings are process-only signals: configuration degradation, approved fallback, +or incomplete configured validation. Quality uncertainty and grounding findings +are advisories; successful canonicalization and cleanup are observations. +Modules choose that semantic classification, while the framework attaches +origin, aggregates groups, enforces bounds, and presents final collections. +An ordinary successful run therefore has zero warnings. See +[ADR-0015](../adr/0015-separate-process-warnings-from-quality-diagnostics.md) +for the decision rationale. + ## Validation Validation is a framework-managed boundary around outputs from chunk, extract, merge, and normalize stages. Validators receive immutable stage output and -make an explicit whole-output decision: approve, approve with warnings, -reject, fail, or skip when a runtime prerequisite is unavailable. +make an explicit whole-output decision: approve, reject, fail, or skip when a +runtime prerequisite is unavailable. Typed artifact validators receive the domain value directly. Chunk validators receive source-zone chunks, while serialized validators receive immutable diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 6e27813f..712a4232 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -632,7 +632,7 @@ in diagnostic tests. This stage is appropriately sized for one `gpt-5.6-terra` prompt. -## Stage 12 — Update Architecture And Internal Producer Documentation +## Stage 12 ✅ — Update Architecture And Internal Producer Documentation ### Goal