Prepare the v0.4.0 release

docs/releases/v0.4.0.md

@@ -0,0 +1,83 @@
+# Notarius v0.4.0
+
+This release strengthens LLM reliability and validation throughout the
+configured pipeline, upgrades the PromptKit integration, and establishes the
+source-release and downstream-consumer workflows needed for broader D&D
+pipeline integration.
+
+## Summary
+
+Notarius now distinguishes PromptKit structural-output repair from
+application-owned semantic validation retries. Producer candidates can run
+through complete deterministic validator chains, receive bounded semantic
+correction guidance, and retry under explicit stage policies. Final run
+receipts and manifests preserve bounded validation provenance, while outputs
+that advance with incomplete validation remain available to the current run
+without entering reusable checkpoint state.
+
+The release also adds a maintained complete D&D subprocess-consumer workflow,
+diagnostic build versions, and the source-only release procedure used to
+publish this version.
+
+## Compatibility
+
+- Configuration files must use schema version 4. Version 3 is not decoded or
+  rewritten; rename the top-level `scriptorium` section to `promptkit` when
+  migrating. See [Configuration](../config.md#migrating-version-3-configuration).
+- PromptKit is pinned to v0.9.0. Operator profile files use PromptKit's v0.9.0
+  format and may use its profile-inheritance support. Notarius continues to
+  resolve operator profiles before embedded fallbacks.
+- Structural-output repair and semantic stage retries are separate bounded
+  mechanisms. Maintained production prompts request one structural repair by
+  default; explicit configuration can override the supported repair count.
+- Validation policy can now fail a run, reject an output, or permit an
+  otherwise valid candidate to advance with incomplete-validation provenance.
+  The application defaults are documented in
+  [Configuration](../config.md#pipelines).
+- The `notarius.run-result.v1` receipt remains at schema version 1 and adds
+  optional validation summaries plus a required validation-status field.
+  Consumers of this pre-release contract should follow the current
+  [run-result receipt](../integrations/run-result.md).
+- Existing D&D artifact schema identities remain unchanged. Validation and
+  producer-policy changes can nevertheless cause previously accepted weak
+  candidates to retry, reject, or fail instead.
+
+## Upgrade
+
+1. Migrate every Notarius configuration to version 4 and rename `scriptorium`
+   to `promptkit`.
+2. Review deployed PromptKit profiles against the pinned v0.9.0 profile format
+   and ensure their credential environment variables are available at run
+   time.
+3. Run `notarius config validate --config <path> --pipeline <id>` before the
+   first production invocation.
+4. Review `structured_output_repair_attempts`, producer retry counts, and
+   `validation_policy` wherever the deployment needs behavior different from
+   the documented defaults.
+5. Update subprocess consumers to inspect receipt `validation_status` and to
+   tolerate the optional bounded `validation_summaries` field. A consumer that
+   requires fully validated artifacts should require `approved`.
+
+## Changes
+
+- Upgraded PromptKit from v0.5.0 through v0.9.0 and adopted profile
+  inheritance, structured-output repair, typed error classification, and the
+  correction-aware completion protocol.
+- Added pipeline and binding configuration for structural repair and terminal
+  validation policy, with strict startup validation and effective-setting
+  provenance.
+- Added feedback-aware retries for chunking, extraction, merge, normalize, and
+  semantic reconciliation producers. Retry prompts contain the exact defective
+  response and actionable semantic correction guidance without exposing
+  internal reason codes or opaque entity identifiers.
+- Added complete validator-chain execution, validator retry handling, bounded
+  warnings, terminal dispositions, and durable validation summaries.
+- Prevented validation-incomplete artifacts and all derived lineage from
+  loading or publishing reusable checkpoints while preserving same-run
+  generated-reference handoff.
+- Tightened cached chunk-plan validation so only completely validated plans are
+  reused or replace stored plans.
+- Added a machine-readable subprocess receipt workflow and complete D&D
+  consumer documentation covering all maintained artifacts.
+- Added source-release checks, immutable lightweight-tag guidance, Linux and
+  Darwin build verification, and diagnostic `notarius --version` output.