notarius/docs/roadmap/implementation.md

# ConfigKit Adoption Implementation Plan

## Purpose And Execution Contract

Implement the target in [ConfigKit Adoption](configkit.md). That document owns
the feature scope and operator choices; this document owns the implementation
sequence. Each numbered stage is one implementation prompt for a
gpt-5.6-terra coding agent. Execute stages in order and finish the named checks
before proceeding. Do not combine the configuration cutover with unrelated
pipeline or security refactoring.

Read `AGENTS.md`, `docs/development.md`, all three documents under
`docs/policy/`, and the relevant focused internal documentation before acting.
Apply the implementation-discipline policy: use the dependency's actual APIs,
preserve the requested flexibility, and do not add application restrictions
under the guise of this migration. Tests protect behavior, not exact helper
structure, incidental formatting, or a duplicated implementation of ConfigKit.

The selected approach requires an upstream extension: ConfigKit v0.2.0 cannot
expose source origins during its resolution callback. See **Upstream
Prerequisite**. Stages 1–6 are independent of that missing capability. Stage 7
and all later stages have an explicit gate; the sprint is not ready for
unattended execution through that gate until the upstream release is available.
Do not mark a gated stage complete by weakening the feature contract.

Temporary coexistence of the old production loader and the new loader during
these stages is implementation scaffolding only. There is no supported dual
version loader in the final product and no release should be tagged midway
through the cutover. Each stage must compile and pass its scoped tests; the
final stage establishes repository-wide readiness.

## Repository Baseline

Planning examined Notarius at `946fa10` plus the outstanding policy and roadmap
changes. The sibling ConfigKit checkout is tagged `v0.2.0`.

Relevant current owners are:

| Area | Repository evidence |
| --- | --- |
| Version 4 YAML and conversion | `internal/core/config/file_config.go`, including `FileConfig`, custom `UnmarshalYAML` methods, `ParseFileConfigYAML`, `LoadFileConfig`, and `ApplyFileConfig` |
| Defaults, runtime ownership, domain validation | `internal/core/config/config.go`, `validation.go`, `effective_config.go`, and their contract tests |
| Field-level environment overrides | `internal/core/config/env.go` and `env_contract_test.go` |
| Configuration discovery and command overrides | `internal/cli/run.go`: `loadConfig`, `runConfigValidate`, `runPipelinesList`, and `runPipelineCommand` |
| Catalog checks and configured/CLI reference behavior | `internal/framework/pipeline/profile.go`, `references.go`, and CLI reference contract tests |
| Dynamic integer consumers | `internal/modules/generic/chunk/units/chunker.go` and `internal/modules/generic/output/json/encoder.go` currently require native `int` |
| Debug configuration and resolved-pipeline output | `internal/core/config/redaction.go`, `internal/core/debugbundle/summary.go`, and the CLI debug handoff |
| Maintained examples | `examples/dnd-minimal.config.yml`, `examples/dnd-complete.config.yml`, `examples/profiles/dnd-extraction.yml`, and CLI production contract tests |
| Direct YAML test dependency | `internal/cli/production_contract_test.go` also parses embedded prompt definitions using `yaml.v3` |
| Upstream contract | ConfigKit `docs/config.md`, `docs/consumers/README.md`, `load.go`, `resolution.go`, `metadata.go`, `records.go`, `path.go`, and consumer examples at v0.2.0 |

The sibling checkout is reference material, not a production dependency path.
Do not commit a local `replace`, modify upstream, or invent a future API as part
of these Notarius stages.

## Decisions Applied Throughout

### Configuration And Dependency Boundary

- Initially pin `gitea.maximumdirect.net/eric/ConfigKit v0.2.0`. Stage 7 may
  require a reviewed release providing the agreed upstream extension. A later
  pin must be explicit, never an unreviewed `main` revision.
- Use a string-backed document version and a `/version` rule accepting exactly
  text `5`; both numeric `version: 5` and quoted `version: "5"` are accepted.
  Maintained examples use the numeric form. Reject missing/null/unsupported
  versions. Numeric v4 fails the application checker with migration guidance.
- Use plain YAML-tagged document structs in `internal/core/config`, without
  custom YAML hooks. Keep runtime framework types independent of ConfigKit.
- Keep the existing runtime `Config`, `ResolveInput`, and `EffectiveConfig`
  boundary where it is useful. A new `LoadedConfig` owns the private ConfigKit
  result and exposes runtime configuration plus safe writer methods. No
  caller may mutate a returned `Result.Config` and expect its frozen inspection
  output to change.
- ConfigKit owns composition, strict decoding, metadata, and safe rendering.
  Notarius owns typed defaults, field semantics, recorded normalization,
  conversion, catalog resolution, and physical run preparation.
- Application paths use typed ConfigKit key/index constructors; never build
  JSON Pointers by concatenating unescaped pipeline IDs or reference keys.

### Document Shape And Presence

Use a distinct finite `ValidatorDocument` containing only `module`,
`llm_profile`, `structured_output_repair_attempts`, `retries`, and `options`.
The producer `BindingDocument` contains those fields plus references,
validation policy, and a validator list. This avoids recursive Go schema types
and makes forbidden nested validator fields strict unknown-field errors.

Use pointer scalars only when nil means inheritance or omission, and ordinary
structs/maps/slices elsewhere as appropriate to the contract. Use ConfigKit
presence before normalization changes paths. Remove custom parser-presence
flags. In particular:

- omitted validators use the production chain; explicit `[]` selects an empty
  chain; present `null` is invalid, matching the existing array contract;
- omitted repair attempts inherit; explicit zero disables repair; present
  null is invalid for this integer setting;
- omitted LLM-profile fields inherit; explicitly blank or null selections are
  invalid;
- omitted optional module bindings permit existing catalog defaults; a present
  binding must be a valid object with a nonempty module;
- reference objects have exactly one selected source: nonempty `path` or a
  complete `artifact` object with step and lane; explicit invalid branches must
  not disappear during pointer conversion;
- preserve the single-step `artifacts` form and the ordered `steps` form;
  reject simultaneous declarations and explicitly empty/null `steps`;
- retain optional null behavior where the existing contract permits clearing
  an optional object or collection; do not impose a universal no-null rule;
- remove the lane-level reference alias. Keep the existing treatment of the
  deprecated lane-level validator list during migration (empty allowed,
  nonempty rejected) rather than adding an unrelated contract removal.

Static defaults stay as currently documented. Derive omitted extraction workers
from the final configured total LLM limit. ConfigKit profile null replacement
is subject to the destination field's existing domain validity; overlay support
does not make null valid for every setting.

### CLI And Path Ownership

| Input | Owner / treatment |
| --- | --- |
| `--config`, `NOTARIUS_CONFIG`, installed fallback | Existing CLI discovery; ConfigKit receives the selected file |
| `--config-profile` | ConfigKit profile selection on all five configuration-loading command forms |
| Explicit `--output-dir` | ConfigKit override at `/output/directory` |
| Explicit `--debug-dir` | ConfigKit override at `/debug/directory`; preserve `--debug` requirement |
| Explicit `--chunk_cache` | ConfigKit override at `/cache/chunk_plans/mode` |
| `--llm-profile` | Existing runtime selection overriding all selected LLM bindings; not a replacement for a single YAML field |
| Input, lanes, session ID, reasoning effort, references, resume/recompute, debug enablement, JSON output | Existing invocation actions outside ConfigKit |
| Seven retired operational environment variables | No longer read or applied; no deprecation-warning scan of process environment |
| PromptKit credential environment variables | Existing PromptKit responsibility |

Only explicitly supplied flags create override records, with safe flag names
as provenance. Preserve current blank-value checks and invocation error classes.
For `--config-profile`, pass the supplied name through ConfigKit's selection
rules; empty and exact `default` select no overlay. Do not invent stricter name
validation or whitespace normalization than the upstream profile contract.

Enable imports without a separate Notarius enablement flag. The canonical
selected file's directory is the configuration root. Relative file references
and PromptKit profile sources use the surviving declaration's directory;
absolute values remain absolute. Resolve these to absolute paths before
runtime conversion, without reading the referenced contents. Output/cache/debug
relative directories retain working-directory semantics. CLI reference paths
retain the existing working-directory semantics and generated-reference
protection. Configuration-root confinement applies only to ConfigKit's imported
configuration and overlay files.

## Stage 1 — Add ConfigKit And The Version 5 Document Types

**Goal:** Establish the new file contract without switching production commands.

**Work:**

1. Pin v0.2.0 in `go.mod`/`go.sum` and inspect its actual exported API.
2. Add `document.go` and `load.go` in `internal/core/config` (or equivalent
   cohesive files) with the complete plain document types, finite validator
   type, explicit reference union, and YAML-tagged validation-policy fields.
3. Provide a private reusable definition factory with fresh static defaults and
   the exact version rule. Define a small application `LoadOptions` for profile
   selection and explicit configuration overrides; avoid a generic loader
   abstraction or exposing parser types.
4. Keep the new load entry point unconnected to production until its
   normalization and validation stages are complete. Mark it internal
   scaffolding; do not advertise partially implemented v5 support.
5. Add the next available ADR (expected `0018-adopt-configkit.md`) recording
   the accepted ownership, v5 break, imports/profiles, and environment policy.
   Record the source-origin dependency without claiming it is implemented.

**Acceptance:** v5 numeric/quoted versions decode; unsupported versions fail
before document decoding; representative canonical bindings and references
decode while shorthand/unknown fields fail. Separate loads do not alias
defaults. The current CLI still works through its existing loader.

**Validation:** `go test ./internal/core/config`; `go test ./...` to confirm the
new dependency and schema types do not break the existing build. Keep tests
small; generic YAML exhaustiveness remains upstream.

**Prompt size:** Small to medium; types, dependency, and version boundary only.

## Stage 2 — Implement Operational Defaults And Normalization

**Goal:** Make operational configuration behavior correct and inspectable.

**Work:**

1. Express existing concurrency, output, cache, debug, and PromptKit-local-backend
   defaults and validations through the definition callbacks.
2. Use recorded `Default`/`Normalize` operations for derived extraction workers,
   path whitespace, cache mode, and endpoint whitespace. Derived defaults must
   follow profile/CLI overlays and preserve explicit zero for validation.
3. Use presence-aware checks for explicit empty/null PromptKit source selectors
   and required fields in a present local-backend object. Preserve mutually
   exclusive profile sources and the existing endpoint/range constraints.
4. Keep filesystem checks and PromptKit profile catalog lookup out of callbacks.
   This stage trims profile-source paths but does not yet resolve their bases.
5. Extract small reusable value checks where needed so runtime validation and
   document validation do not separately implement the same rule. Collect
   independent errors through ConfigKit with safe messages and field paths.

**Acceptance:** defaults and explicit values retain their meanings; worker
derivation follows effective total concurrency; multiple independent field
errors identify their source locations; normalization appears in explanation
without generating warnings.

**Validation:** `go test ./internal/core/config`. Add load-boundary cases for
profiles overriding concurrency, CLI overrides, invalid output versus empty
cache paths, and local backend presence. No live profile resolution.

**Prompt size:** Medium; operational fields only.

## Stage 3 — Implement Pipeline Document Rules

**Goal:** Validate and normalize the complete pipeline file shape before
catalog resolution.

**Work:**

1. Implement one typed traversal of pipelines, steps, lanes, bindings,
   validators, and reference sources. Prefer shared binding helpers and
   explicit walks over reflective generic validation.
2. Perform all presence-sensitive checks against original input paths before
   renaming map keys. Detect whitespace collisions deterministically before
   writing normalized keys. Report both paths where useful.
3. Normalize identifiers, selected profiles, and generated selectors with
   recorded changes. For map-key moves, record the parent operation and relevant
   source dependencies; preserve a load-local original-path mapping for Stage
   7. Do not guess origin from a normalized key after it has moved.
4. Enforce the field and shape contracts above, including global lane-ID
   uniqueness across steps, valid retry values, validation-policy fields, and
   allowed binding-local reference/validator placements.
5. Keep stage/module compatibility and actual option meaning in the existing
   catalog resolver. Do not reject a module based on an embedded allowlist in
   the document schema.
6. Factor shared semantic value checks with `Config.Validate` where necessary.
   Keep file presence/shape checks in the document callback and direct runtime
   construction checks at the runtime boundary; avoid parallel complete
   validators with independently copied rules.

**Acceptance:** single-step and ordered pipelines behave as specified;
explicit empty validator chains and zero repair budgets survive; invalid
references, profile selectors, normalized collisions, and duplicate lane IDs
fail with useful paths. No mutation is hidden from ConfigKit's change recorder.

**Validation:** `go test ./internal/core/config ./internal/framework/pipeline`.
Migrate meaningful rule cases from the old parser tests to the new load
boundary as they gain an owner; retain old-loader coverage until cutover.

**Prompt size:** Medium to large, bounded to pipeline document semantics; do
not combine it with source-origin or CLI work.

## Stage 4 — Convert Documents Into Runtime Configuration

**Goal:** Produce the existing typed runtime composition from the new document.

**Work:**

1. Add a narrow explicit conversion after successful ConfigKit loading. Build
   independently owned `Config` and `pipeline.PipelineProfile` values, preserving
   map identities, step order, inheritance pointers, empty chains, and reference
   source forms. Convert the finite validator document to runtime bindings.
2. Wrap the result in `LoadedConfig`, retaining the private ConfigKit snapshot.
   Provide safe effective/explanation writers and the runtime configuration;
   avoid a public unredacted serialization method.
3. Stop re-deriving workers on the already finalized new-load path. Retain
   programmatic `Config` validation and ownership checks. Any legacy
   recomputation shim needed by the old loader is temporary and removed at
   Stage 12. Runtime callers needing defaults should use the same default values
   as the document definition, not a second literal default table.
4. Keep `Config.Resolve`/`pipeline.ResolvePipeline` responsible for selection,
   capabilities, concrete validation-policy inheritance, options, references,
   and digest generation. Do not add configuration profile name or source
   history to semantic pipeline identity.

**Acceptance:** equivalent canonical documents produce equivalent runtime
pipelines; changing a semantic setting changes identity, while merely importing
an equivalent definition does not. Mutating caller-owned maps/slices cannot
alter the snapshot or resolved pipeline. ConfigKit changes do not force its
types into module interfaces.

**Validation:** `go test ./internal/core/config ./internal/framework/pipeline`.
Use a real test catalog and representative reference/validator chains; resolve
absolute reference fixtures until Stage 7 supplies relative path resolution.

**Prompt size:** Medium; conversion and runtime ownership only.

## Stage 5 — Support ConfigKit Dynamic Integers In Modules

**Goal:** Ensure the module boundary accepts valid ConfigKit options.

**Work:**

1. Inspect every production numeric `map[string]any` option consumer. The known
   sites are generic unit chunking and JSON evidence `window_units`.
2. Add one narrow shared option conversion helper in the existing pipeline
   option-helper area. Accept `int64` from ConfigKit and native `int` from
   programmatically constructed module bindings. Range-check `int64` before
   conversion; keep domain positivity/nonnegativity at the module owner.
3. Preserve rejection of floats and strings. Do not recursively rewrite all
   options, change their serialized representation, or add general numeric
   coercion. Keep options in ConfigKit form through config conversion.
4. Update the old test that rejects `int64` to protect the newly accepted
   boundary. Add representative real-loader-to-module tests, including nested
   JSON evidence options.

**Acceptance:** integral options work from YAML and programmatic bindings;
fractional/string inputs and invalid ranges still fail before preparation.
No unchecked narrowing or YAML round-trip remains at these consumers.

**Validation:** `go test ./internal/modules/generic/... ./internal/framework/pipeline ./internal/core/config`.

**Prompt size:** Small; two known consumers and a narrow shared helper.

## Stage 6 — Prepare Debug Rendering For The ConfigKit Result

**Goal:** Prepare the publication boundary before changing command loading.

**Work:**

1. Add a small writer interface such as `WriteEffective(io.Writer) error` to
   the debug summary boundary. `LoadedConfig` satisfies it without exposing a
   concrete ConfigKit result to debug storage.
2. Add publication of `effective-config.yml` through the existing confined,
   atomic summary file writer. Buffer redacted output before publishing if the
   current file API takes bytes; propagate rendering and write errors.
3. Preserve the existing redacted resolved-pipeline writer and all reference
   content exclusion. The old `effective-config.json` writer remains only until
   the run command switches in Stage 10.
4. Reuse `sensitiveConfigKey` for the definition's dynamic secret predicate at
   nested options paths, including validator options, containers, and moved
   map keys. Keep scalar classification policy in one owner. Do not log raw
   configuration or metadata snapshots that contain values.

**Acceptance:** redacted effective YAML publishes atomically; failure leaves no
partial artifact; nested sensitive values never appear in effective output or
explanation. Resolved runtime summaries still omit materialized references.

**Validation:** `go test ./internal/core/config ./internal/core/debugbundle`.
Test rendering failure and caller mutation at these real local boundaries.

**Prompt size:** Small to medium; rendering interface and publication only.

## Stage 7 — Resolve Declaration-Relative Paths

**Goal:** Normalize file paths using their effective source origins and retain
correct ConfigKit inspection history.

**Prerequisite gate:** A reviewed ConfigKit release must expose surviving input origin and canonical
source information during resolution. Confirm the actual API and pin that
release before implementing this stage. If only v0.2.0 is available, stop here
and report the unmet dependency. Do not implement an upstream fork, reload the
configuration twice, parse YAML independently, or silently change the promised
effective output.

**Work after the gate:**

1. Resolve path origins at original input paths before map-key normalization
   and before recording changes can replace a source origin. Use the scalar
   origin and source ID to get the canonical declaring file; do not pick the
   first origin of a composite parent mapping.
2. Join nonempty relative external reference paths and PromptKit profile-source
   paths to that file's directory. Preserve absolute values. Do not read or
   require existence of referenced files in this callback.
3. Record normalized paths and map moves so the frozen effective view matches
   runtime values and explanation can trace back to the original declaration.
   Keep map collision checks ahead of mutation; process stable sorted keys.
4. Leave destination directories unchanged except existing whitespace
   normalization. CLI reference paths remain runtime-owned. No configuration
   root confinement or symlink policy is added to referenced application files.
5. Enable imports and selected profiles on the public new loader, using
   `File` and the selected file's canonical directory as the root. Use
   ConfigKit's composition and profile behavior directly.

**Acceptance:** root, fragment, and overlay values resolve from their own files;
inherited values retain their base origin; profile-replaced sequences use the
new declarations; normalized enclosing IDs do not lose attribution. Effective
and explanation output agree with the actual paths. Removed/overridden file
values are not opened or resolved. Root containment affects only ConfigKit
configuration sources.

**Validation:** `go test ./internal/core/config ./internal/framework/pipeline`.
Use temporary configuration trees with same-named reference files in different
directories, aliases/symlinks accepted by ConfigKit, profile replacements,
normalized keys, and absolute external paths outside the config root. Use real
reference materialization for one case to prove the intended bytes are chosen.

**Prompt size:** Medium, with a firm upstream gate; no CLI or example migration.

## Stage 8 — Prepare Shared CLI Loading And Diagnostics

**Goal:** Make one command-facing configuration entry point ready for cutover.

**Work:**

1. Add a CLI helper that discovers the file, passes profile selection and
   explicit override records to the new loader, and returns `LoadedConfig`
   plus the selected config path. Keep discovery order and injected test lookup.
2. Add a shared load-error reporter using `errors.As` for ConfigKit load errors
   and `WriteDiagnostics`; supply safe source context using the dependency's
   source records. Do not flatten multi-error output into repeated wrappers or
   print raw parser/source contents. Preserve status 1 for valid invocations
   whose configuration cannot load.
3. Add shared flag registration/parsing only where it reduces actual repeated
   code. Use existing CLI parsing conventions, including flags surrounding
   positional arguments. Preserve missing-value and unexpected-argument checks.
4. Route successful ConfigKit process diagnostics through one reporting owner.
   Define no new application warnings for successful imports, defaulting,
   normalization, or ignored retired environment names. Current application
   rules should ordinarily return no nonfatal configuration diagnostics.

**Acceptance:** the helper returns a fully validated loaded value with safe
diagnostics and uses the requested source/profile. No production command has
switched accidentally; existing command tests remain green.

**Validation:** `go test ./internal/cli ./internal/core/config`. Add direct
helper tests for explicit flags versus parser defaults, discovery, safe
multi-error reporting, and profile selection. Use the real ConfigKit boundary.

**Prompt size:** Medium; helper and diagnostic wiring only.

## Stage 9 — Prepare Validation And Pipeline Listing Commands

**Goal:** Finish the read-only command implementations before the shared
production cutover.

**Work:**

1. Implement v5 handlers for `config validate` and `pipelines list` using the
   new helper and `--config-profile`. Preserve `--pipeline`, `--only`, JSON
   listing, sorting, and exit/stream behavior. Keep production dispatch on the
   old handlers until Stage 10 so all configuration commands switch together.
   Use temporary explicit handler names, not a runtime version switch.
2. Plain validation is configuration-only. Selected-pipeline validation still
   performs catalog and explicit PromptKit profile checks at their existing
   owners, without provider calls or credential requirements beyond existing
   offline profile validation.
3. Test these handlers with dedicated v5 fixtures and production registries.
   Keep existing dispatch and maintained-example tests intact until Stage 10.
   Do not weaken tests to accept both versions or advertise the unconnected
   handlers as implemented CLI features.

**Acceptance:** the new handlers see imported pipelines and overlay changes,
reject v4, and retain useful module/profile failure context. Existing public
command behavior stays coherent until all three handlers switch in Stage 10.

**Validation:** `go test ./internal/cli ./internal/core/config`; run the focused
production validation cases using v5 fixtures, including unknown modules and
incompatible generated references.

**Prompt size:** Medium; two closely related read-only commands.

## Stage 10 — Switch Run And The Maintained V5 Configurations

**Goal:** Complete production cutover and make all runs use one ConfigKit load.

**Work:**

1. Switch `runPipelineCommand` to the new loader. Translate only the three
   config-valued flags in the decision table to ConfigKit overrides; remove
   their direct post-load mutations. Add `--config-profile` consistently to
   argument reordering and missing-value checks. Activate Stage 9's validation
   and listing handlers in the same change and remove superseded handlers.
2. Preserve runtime LLM override, references, input, session identity,
   resume/recompute, scheduler setup, and output receipt semantics. Config
   failures must still occur before source parsing and physical run allocation.
3. Pass the retained loaded result to the effective YAML debug writer. Continue
   to write the separately redacted resolved pipeline after reference
   materialization. Add effective configuration profile selection to debug
   invocation metadata (`config_profile`), with no overlay represented as empty.
   Do not add profile-selection text to checkpoint or pipeline identity.
4. Convert both maintained D&D example configurations to v5 object syntax in
   place, still as self-contained files in this stage. Change the complete
   example's PromptKit source path for declaration-relative interpretation.
5. Migrate run/reference/state tests and the maintained-example loader to v5.
   Split mechanical fixture updates from behavioral assertions within the
   diff so regressions remain reviewable. Retired env-based tests now supply
   YAML or explicit flags; keep one test proving those variables have no effect.
6. Update current CLI, configuration, operations, and consumer references for
   v5, profile selection, environment retirement, and `effective-config.yml`.

**Acceptance:** all production commands use the new helper; imported/profile
configuration and explicit overrides agree with execution and debug output;
the maintained minimal and full fake-provider workflows still complete with
the same artifact families and valid reference handoffs.

**Validation:** `go test ./internal/cli ./internal/core/config ./internal/core/debugbundle ./internal/framework/pipeline`.
Use the existing complete D&D fake LLM test instead of a live backend. Verify
JSON run receipt and stderr warning behavior remain unchanged.

**Prompt size:** Largest cutover prompt, limited to wiring, fixture migration,
and its current documentation. Schema, paths, numeric adapters, diagnostic
helpers, and debug writer must already be complete in earlier stages.

## Stage 11 — Add Effective And Explanation Commands

**Goal:** Expose the accepted operator inspection workflow.

**Work:**

1. Add `config effective` and `config explain` with the syntax in the feature
   roadmap, including `--config` and `--config-profile`.
2. Effective writes only `LoadedConfig.WriteEffective` output. Explain accepts
   exactly one JSON Pointer positional argument, parses it with ConfigKit, and
   calls the safe explanation writer. Accept the empty pointer for the root
   when explicitly supplied; reject malformed escapes/argument shape with
   status 2. A well-formed unknown path returns status 1 and no success output.
3. Use ConfigKit's contextual sequence-index rules. Signed numeric mapping
   keys remain valid keys; `/steps/+0` cannot identify a sequence element.
   Do not add a blanket numeric-token restriction that rejects legal map keys.
4. Preserve writer failure handling. Explanations are human-oriented text;
   effective configuration is YAML. Neither output is promised to be a
   reloadable config or a new durable JSON API. Do not print success banners.
5. Avoid LLM client construction, module preparation, reference materialization,
   state allocation, or pipeline selection. Existing catalog registration at
   CLI composition is acceptable; it must not trigger provider work.
6. Update `docs/cli.md`, the configuration inspection guidance, and help.

**Acceptance:** both commands work against imports/overlays, redaction applies
to history and effective values, removed keys remain explainable, malformed
and unknown paths fail appropriately, and stdout contains only requested data.

**Validation:** `go test ./internal/cli ./internal/core/config`. Use real
ConfigKit with temporary files and a provider factory that fails if called.

**Prompt size:** Medium; two commands sharing the completed load boundary.

## Stage 12 — Remove The Legacy Configuration Machinery

**Goal:** Finish the simplification promised by the adoption.

**Work:**

1. Remove the unused v4 parser, YAML hooks, `FileConfig` application APIs,
   environment-overlay code, parser-only presence flags, and old loading helper.
2. Remove `extractWorkersConfigured`/`defaultedExtractWorkers` inference once
   file defaults are finalized by ConfigKit. Programmatically constructed
   configs treat a supplied worker entry as explicit and derive only an absent
   entry; update internal construction tests accordingly. Keep runtime checks
   through `Config.Resolve` for direct callers, without mutating shared maps.
3. Delete the superseded `effective-config.json` publication method and raw
   configuration summary/redaction functions. Retain runtime ownership cloning
   and resolved-pipeline redaction that still serve real callers.
4. Remove obsolete parser/env tests; retain behavioral coverage at the new
   owner. Remove `yaml.v3` from the embedded-prompt test in
   `production_contract_test.go`: exercise the production PromptKit loader or
   existing asset-loading seam, rather than adopting ConfigKit to parse
   PromptKit assets or adding another YAML dependency for the test.
5. Run `go mod tidy`; remove the direct `gopkg.in/yaml.v3` requirement and verify
   Notarius Go files no longer import a YAML parser. Dependencies may retain
   their private YAML implementation.

**Acceptance:** no alternate loader, environment application layer, redundant
configuration redactor, or parser-only clone remains. Legitimate pipeline and
artifact serialization code is unaffected. Programmatic config behavior has
an explicit tested ownership/default contract.

**Validation:** `go test ./...`; `go vet ./...`; search for `UnmarshalYAML`,
`ApplyFileConfig`, `ApplyEnvOverrides`, `gopkg.in/yaml`, and old effective-config
artifact references. Inspect matches rather than treating historical docs or
negative migration tests as failures.

**Prompt size:** Medium; deletion and ownership consolidation after all callers
have moved.

## Stage 13 — Demonstrate Imports And Development Profiles

**Goal:** Supply two maintained operator examples covering simple and composed
configuration, with a clear distinction between the two profile systems.

**Work:**

1. Keep `examples/dnd-minimal.config.yml` self-contained.
2. Keep `examples/dnd-complete.config.yml` as the complete root and move its
   whole `dnd-session` pipeline into
   `examples/pipelines/dnd-session.yml`, imported through `configkit.imports`.
   Only the root declares version. Fix fragment-relative campaign/catalog
   references to `../dnd-party.txt`, `../dnd-glossary.txt`, and
   `../dnd-spell-catalog.json` where applicable.
3. Move the existing PromptKit example to
   `examples/llm-profiles/dnd-extraction.yml` and point the root's
   `promptkit.profile_file` to `./llm-profiles/dnd-extraction.yml`.
4. Add `examples/profiles/development.yml` as a ConfigKit overlay. Set
   `concurrency.total_llm: 1` and `stage_workers.extract: 1`, plus a development
   output directory. Include a short comment explaining how an operator can
   change the pipeline's `llm_profile` independently; do not invent an
   unavailable model profile just to demonstrate the field. The overlay has
   no version or import directive.
5. Extend the existing maintained-example test to load base and development
   configurations through production code, validate catalogs/profiles offline,
   and exercise complete fake-provider reference materialization from a
   working directory other than the example directory.
6. Update `docs/config.md`, `docs/operations.md`, `docs/consumers/subprocess.md`,
   and `docs/consumers/dnd-pipeline.md` at their canonical scopes. Link the
   examples; explain disjoint composition and whole-sequence replacement
   instead of duplicating complete configs in prose.

**Acceptance:** all example paths resolve, the base and development selections
validate, the full pipeline still contains every implemented D&D lane, and
operators can distinguish `--config-profile` from `--llm-profile`.

**Validation:** `go test ./internal/cli`; production CLI validation for both
roots and the development overlay. No API key or live generation is needed;
use only the documented placeholder if offline PromptKit validation requires
one. Verify all moved example links.

**Prompt size:** Medium; examples and their operator-facing documentation.

## Stage 14 — Final Architecture And Contract Verification

**Goal:** Verify the completed architecture and reconcile canonical docs with
the implemented boundaries.

**Work:**

1. Review the complete diff against `configkit.md` and this plan. Check that no
   stage was bypassed, no source-origin workaround weakened the selected
   contract, and no unsupported step-composition semantics slipped in.
2. Finalize `docs/internal/configuration.md`, `docs/internal/cli.md`,
   `docs/internal/state.md`, and `docs/internal/overview.md`. Add
   `docs/integrations/pkg-configkit.md` for the pinned API boundary and relevant
   upstream semantics; link upstream for general library behavior.
3. Update architecture's configuration ownership/precedence text and finalize
   the adoption ADR. Document public behavior in its canonical owner; do not
   retroactively edit historical release notes or prior accepted ADR decisions.
4. Ensure ConfigKit warning/diagnostic handling, safe rendering, source-relative
   paths, runtime option validation, direct construction, and digest semantics
   all have sufficient focused coverage. Do not duplicate upstream's test
   suite or create exact-output change detectors.
5. Verify current docs no longer recommend v4 syntax, retired environment
   overlays, the former PromptKit example path, or `effective-config.json`.
   Migration explanations and historical records may legitimately name them.
6. Complete the checks below and report any remaining issue explicitly. Do not
   tag a release, push, or retire the active roadmap during implementation
   without a separate request.

**Acceptance:** every feature acceptance criterion holds, current docs and
examples agree with runtime behavior, all required checks pass, and the
remaining configuration code expresses Notarius policy rather than rebuilding
ConfigKit machinery.

**Validation:**

```sh
go test ./...
go vet ./...
go build ./cmd/notarius
go run ./cmd/notarius config validate --config examples/dnd-minimal.config.yml --pipeline dnd-session
go run ./cmd/notarius config validate --config examples/dnd-complete.config.yml --pipeline dnd-session
go run ./cmd/notarius config validate --config examples/dnd-complete.config.yml --config-profile development --pipeline dnd-session
go run ./cmd/notarius pipelines list --config examples/dnd-complete.config.yml --config-profile development --json
go run ./cmd/notarius config effective --config examples/dnd-complete.config.yml --config-profile development
go run ./cmd/notarius config explain --config examples/dnd-complete.config.yml --config-profile development /concurrency/total_llm
git diff --check
```

Use the project's normal link-check mechanism if present; otherwise check
changed relative links and heading anchors manually. Live model evaluation is
unnecessary for a configuration migration.

**Prompt size:** Medium; verification and focused documentation reconciliation,
with no planned production redesign.

## Upstream Prerequisite

### Source Origins During ConfigKit Resolution

**Evidence:** In v0.2.0, `Resolution` exports `IsExplicit`, `Record`, `Error`,
and `Warning`, with generic `Default` and `Normalize` helpers. It does not
expose source metadata. `Result.Metadata()` and `Result.Sources()` become
available only after `Load` returns. Mutating `Result.Config` afterward does
not change `WriteEffective` or `WriteExplanation`, which use frozen snapshots.
Therefore a single v0.2.0 load cannot both use declaration origins to normalize
paths and record that normalization in ConfigKit's inspection history.

**Selected approach:** Request a small upstream API exposing surviving
input origins and canonical source records during the existing resolution
callback. It should distinguish base/profile/CLI/default origins, identify the
declaring file for a scalar, and permit lookup at original paths before
application map-key normalization. Keep the existing recorded mutation API.
Exact method names and the containing release must be confirmed upstream;
none are assumed to exist by this plan. This preserves one load, ConfigKit
ownership of composition/provenance, and the agreed effective-output contract.
The tradeoff is an upstream release dependency at Stage 7. This plan does not
authorize changes to the sibling repository.

**Alternative considered:** Stay on v0.2.0 and resolve paths in the narrow Notarius
runtime converter using completed-result metadata. Preserve original document
paths for origin lookup. Present ConfigKit's effective configuration as a
logical configuration view, and expose resolved runtime paths separately in
debug/inspection output. This is implementable without an upstream change and
keeps composition centralized, but changes the agreed inspection contract,
requires Notarius to own the extra path report, and cannot make ConfigKit's
explanation record the post-load normalization. It requires explicit approval
and revision of Stage 7 and the feature roadmap before dependent work begins;
the user selected the upstream extension instead.

Do not resolve this by silently dropping imports/profiles, changing all file
paths to working-directory-relative, reparsing YAML, or performing a second
load that might observe different files. All other product decisions in this
plan are settled; the upstream release is the sole remaining gate. No product
questions remain open. Once the API is released, review its exact signatures,
update the pinned version and this stage's API mapping, and then resume Stage 7.