Simplify the library migration to target the final integration

docs/roadmap/configkit.md

@@ -136,8 +136,13 @@ The [migration inventory](library-boundary-findings.md#migration-inventory) is t
 field-by-field old-to-new map. The [selected boundary](library-boundary-findings.md#configuration-and-profile-contract)
 owns defaults and semantic choices; the [v0.4.0 overlay results](library-boundary-findings.md#selected-overlay-extension-2026-09-24)
 prove the representative load, inspection, and HTTP path. These packages are
-future work. Complete each dependency and its tests before removing the code it
+future work within one coordinated refactor to adopt both libraries. The order
-replaces. Do not treat the isolated prototype as a second production runtime.
+organizes implementation dependencies, not independently runnable product states.
+Intermediate commits need not build or run; do not add temporary scaffolding,
+compatibility shims, or a processing gate to support them. Remove superseded code
+as its replacement lands. Run focused checks as components become testable, and
+validate the complete application before declaring the refactor finished. The
+isolated prototype is evidence, not a second production runtime.
 
 ### 1. Define and load the complete version-2 configuration
 
@@ -224,43 +229,31 @@ inspection, diagnostics, or errors. Update `internal/cli/run_test.go`,
 `internal/core/config/*_test.go`, and report/diagnostics tests that own these
 outputs.
 
-### 4. Convert runtime inputs without claiming unavailable execution
+### 4. Connect the final configuration directly to PromptKit execution
 
-**Depends on:** packages 1–3. **Owns:** a narrow conversion at the CLI to
+**Depends on:** packages 1–3. **Owns:** the final CLI/runtime assembly boundary,
-`internal/framework/llm`/runner boundary, with focused `internal/cli` and
+`internal/framework/llm`, prompt/schema loading, runner wiring, and relevant tests.
-`internal/framework/llm` tests. Convert retained domain settings to their current
+Implement PromptKit adoption as part of the same refactor. Convert domain settings
-domain structs. Convert selected profile/backend endpoint, model, resolved secret,
+into Audita's existing domain structs and supply the selected profiles, registered
-and per-attempt timeout to existing client setup values for assembly checks; keep
+backends, resolved secrets, retry/repair budgets, and logical-operation deadlines
-library types out of modules, validators, transcript schemas, and ledgers.
+directly to PromptKit. Keep library types out of correction algorithms and ledgers.
 
-The interim conversion has this explicit scope; "assemble" means values can be
+Migrate all module and validator prompts, preserve their domain checks, and map
-validated and converted, not that processing is enabled:
+PromptKit results, classified failures, and observations into Audita reporting and
+redacted diagnostics. Replace the old provider transport, prompt loader,
+structural-output handling, and global/role scheduler composition. Follow the
+[coordinated execution scope](library-adoption.md#4-complete-promptkit-adoption)
+and [execution/observation contract](library-boundary-findings.md#execution-and-failure-mapping).
+Do not build an adapter to feed the old LLM runtime or introduce an interim
+`process` rejection mode.
 
-| New setting or control | Interim disposition |
+**Acceptance/tests:** controlled HTTP tests prove both roles' final model/backend
-| --- | --- |
+selection, overlays and explicit overrides, finite per-backend capacity, explicit
-| `profiles_dir`, proposal/validation profile IDs | Honor for relative-path profile loading, final inheritance, inspection, and target assembly. |
+zero retries, positive structural repair, total-operation deadlines, cancellation,
-| `backends.<id>.endpoint` and `credential` | Honor for selected target validation and client setup; keep ConfigKit secret resolution and redaction. |
+domain acceptance/rejection, and safe observations including partial failures.
-| Profile model and `timeout_seconds` | Convert for old client setup checks; old transport can consume these per-attempt values. |
+Processing uses the new configuration and execution path together. Reuse existing
-| `validation.max_prompt_tokens`; retained domain, output, and diagnostics fields | Honor through existing domain/batching/report inputs after validation. |
+domain coverage and the prototype's integration evidence; update tests tied to the
-| `backends.<id>.concurrency` and `queue_capacity` | Validate and inspect; old global/role pools cannot enforce independent per-backend admission or queue semantics. |
+retired transport and scheduler contracts.
-| `llm.transient_retries` | Validate and inspect; old retry eligibility and explicit-zero behavior differ. |
-| `llm.repair_attempts` | Validate and inspect; old runtime has no PromptKit structural-repair contract. |
-| `llm.operation_timeout` | Validate and inspect; old per-call timeout is not the full logical-operation deadline. |
-| Other PromptKit profile generation controls and execution observations | Inspect only; old transport/reporting cannot claim equivalent behavior. |
-
-The old global/role pools and retry loop must not be presented as equivalents. The
-selected interim behavior is to reject `process` before any LLM request with a
-clear unsupported-runtime classification while ConfigKit has landed but PromptKit
-has not. `config validate` and effective/profile inspection remain usable. This
-is an unreleased development interval, not a user-visible mode or compatibility
-switch. The process gate is removed only when the PromptKit package below proves
-the complete settings through controlled calls.
-
-**Acceptance/tests:** conversion tests verify the representable values and
-redaction; a process subprocess test proves the interim rejection occurs before
-provider transport or output mutation. No test should assert that old retries or
-schedulers implement new settings. The combined migration cannot release with
-this gate in place.
 
 ### 5. Remove superseded configuration paths and update maintained contracts
 
@@ -278,80 +271,21 @@ semantics. Do not leave dual loaders or a permanent translation mode.
 
 **Acceptance/tests:** maintained examples validate offline; removed flags and old
 schema are rejected; relevant config/CLI/subprocess/report tests pass; documentation
-links and `git diff --check` pass. The interim process restriction remains explicit
+links and `git diff --check` pass. Remove the isolated prototype when its useful
-until package 6 and is not documented as a released product feature.
+coverage and examples have moved into the production suite.
 
-### 6. Replace execution with PromptKit, then prepare the combined release
+### 6. Validate the combined end state and prepare release
 
-**Depends on:** packages 1–5. This is the later PromptKit work unit, not part of
+**Depends on:** packages 1–5. Verify the assembled version-2 configuration,
-this ConfigKit implementation. Replace the old provider transport, prompt loader,
+overlay, profile, execution, reporting, and artifact workflows. Run the relevant
-structural-output handling, and scheduler composition as described by the
+full build/test checks, confirm obsolete configuration and LLM machinery is gone,
-[coordinated adoption roadmap](library-adoption.md#4-complete-promptkit-adoption)
+and verify maintained examples and the migration guide against the final behavior.
-and [execution/observation handoff](library-boundary-findings.md#execution-and-failure-mapping).
+There is no requirement to validate or preserve intermediate product states.
-Prove both roles' profile/backend settings, per-backend capacity, explicit-zero
-retry, positive repair, total-operation deadline, domain decisions, and safe
-observations with controlled transport. Remove the interim converter/process gate
-and superseded LLM machinery only after those tests pass. Update report and
-diagnostic contracts and the migration guide. The combined release and license/
-distribution review follow last under the release policy; no publication is
-authorized by this plan.
 
-## Historical Provisional Outline
+The refactor is complete when both ConfigKit and PromptKit are adopted and the
-
+complete application passes its required checks. Release compliance, license/
-The completed [shared-boundary and prototype unit](library-boundary.md) supplies
+distribution review, and publication follow last under the established release
-the initial target settings model and integration evidence. Extend that evidence
+procedure. No publication is authorized by this plan.
-with the selected-overlay work above during the next configuration unit.
-
-### 1. Define the Contract and Coordinate Sequencing
-
-Inventory existing configuration fields, invocation options, environment settings,
-secret handling, inheritance rules, and inspection consumers. Produce an old-to-new
-mapping for migration guidance and identify which concepts should be retained,
-redesigned, or removed. This is an inventory of needs, not a compatibility checklist.
-
-Specify the target ConfigKit conventions and the boundary between configuration
-and invocation-only state. Decide file discovery, the new file schema version,
-CLI shape, validation/inspection behavior, and optional feature scope. Identify
-application requirements that the library cannot express cleanly before building
-workarounds.
-
-Coordinate these decisions with the other planned large changes to Audita. Finalize
-an implementation plan and concrete acceptance criteria before beginning migration.
-
-### 2. Prove a Representative Configuration Path
-
-After detailed planning, implement a bounded path from file selection and CLI
-inputs through ConfigKit to Audita's runtime configuration. Exercise defaults,
-selected overlays, proposal/validation inheritance, concurrency, duration values,
-secrets, and redacted inspection using representative valid and invalid inputs.
-
-Use the result to assess whether domain rules remain clear and substantial old
-infrastructure can be removed. Resolve genuine library gaps deliberately, including
-upstream discussion or changes when justified; avoid rebuilding a parallel loader.
-A prototype is evidence for the design, not a permanent compatibility mode.
-
-### 3. Complete the Migration
-
-Convert the remaining configuration and command paths, remove superseded code and
-legacy interfaces, and update maintained examples and canonical documentation
-alongside the implementation. Replace tests that enforce retired conventions with
-coverage of the new contract; preserve meaningful domain and runtime coverage.
-
-Provide a concise migration guide covering old-to-new fields, flags, environment
-settings, durations, credentials, validation, and inspection behavior. Automated
-conversion tooling is not assumed to be necessary or in scope.
-
-### 4. Validate and Release the Breaking Change
-
-Verify representative loading and CLI workflows, domain resolution, safe secret
-handling, diagnostics, examples, and runtime integration with deterministic tests.
-Confirm obsolete loaders and aliases are gone and that documentation describes the
-implemented model. Use the established [release procedure](../release.md).
-
-Recommend Audita v2.0.0 and a new configuration-file schema version. Clearly reject
-unsupported old file versions and direct users to the migration guide. Final
-release numbering and whether this ships with other breaking changes remain
-sequencing decisions; no publication is authorized by this roadmap.
 
 ## Sequencing Considerations
 
@@ -362,9 +296,9 @@ the same concepts twice. Work independent of configuration can proceed separatel
 
 The [coordinated library-adoption roadmap](library-adoption.md) owns the proposed
 sequence with PromptKit: shared boundary design and a PromptKit prototype, then
-ConfigKit implementation, then PromptKit implementation, followed by a combined
+ConfigKit and PromptKit implementation in dependency order within one refactor,
-v2.0.0 release. Revisit that sequence alongside other major changes. Keep
+followed by a combined v2.0.0 release. Intermediate commits are work in progress,
-implementation units reviewable even when the release combines them.
+not supported configurations or runnable milestones.
 
 The separate [runtime behavior decisions](runtime-behavior.md) track remaining
 questions and the selected retry direction.
@@ -373,8 +307,7 @@ structural repair from the outset. Include separate transient-retry and positive
 repair budgets, plus the total-operation deadline policy, in the shared settings
 design. The selected defaults and ownership are recorded in the
 [boundary findings](library-boundary-findings.md#configuration-and-profile-contract).
-Do not implement the runtime change
+Implement the runtime change explicitly as part of the combined refactor.
-merely as a side effect of replacing the configuration loader.
 Retention and transcript timestamp decisions are not automatically included.
 
 ## Implementation Boundaries
@@ -382,8 +315,8 @@ Retention and transcript timestamp decisions are not automatically included.
 - Pin ConfigKit v0.4.0 in production and align Go/toolchain requirements. ConfigKit requires
   Go 1.25; the combined PromptKit prototype requires Go 1.25.5. Config-only
   adoption does not automatically remove Audita's existing YAML dependency used for glossary parsing.
-- Implement the selected type shape, final role inheritance, and interim runtime
+- Implement the selected configuration and final PromptKit runtime directly,
-  gate above without leaking library concerns throughout the pipeline.
+  without temporary runtime adapters, compatibility shims, or process gates.
 - Enable selected overlays as specified above. Keep imports and secret-directory
   bootstrap disabled unless a separate concrete requirement justifies them.
 - Validation and inspection resolve surviving credential references and fail on

docs/roadmap/implementation.md

@@ -6,6 +6,12 @@
 unit in the [prototype roadmap](library-boundary.md#next-unit-testing-overlays-and-production-migration-plan),
 not the production ConfigKit or PromptKit migrations.
 
+**Production handoff revision:** The completed prototype stages remain recorded
+below. The current [production plan](configkit.md#ordered-production-migration-handoff)
+targets both libraries in one refactor; intermediate commits need not build or run.
+It supersedes the earlier interim-runtime design. No temporary adapter,
+compatibility shim, or processing gate is required.
+
 Execute Stage 1 through Stage 6 in order. Each stage is sized as a separate coding
 prompt for a gpt-5.6-terra agent and ends with a reviewable result. When assigned
 one stage, finish that stage and report the next stage; when assigned the entire
@@ -250,7 +256,7 @@ to a passing test or observed demonstration result. Verify affected links and
 ## Stage 6: Prepare the Production Migration Plan and Close the Unit
 
 **Status:** Complete (2026-09-24). **Depends on:** Stage 5. The ordered ConfigKit
-production handoff records bounded packages, interim runtime behavior, tests,
+production handoff records bounded packages, runtime integration, tests,
 dependencies, and acceptance criteria. Prototype evidence and scope audit passed;
 links and `git diff --check` verified.
 
@@ -272,19 +278,16 @@ components, tests, and acceptance criteria for:
 - Profile loading/inspection and configuration snapshots, including relative-path
   bases, secret redaction, provenance, and clear separation of ConfigKit settings
   from PromptKit execution controls.
-- Runtime conversion and the temporary connection to the existing LLM runtime.
+- Direct integration of the final configuration with PromptKit execution. Specify
-  For each new setting, state whether the interim runtime honors it or cannot yet
+  the final behavior and tests for each setting; do not preserve the old runtime
-  do so. Decide the explicit interim behavior and its tests; do not silently map
+  through temporary adapters or add interim processing gates.
-  per-backend limits to the old global/role pools or pretend old retries implement
-  PromptKit repair/zero semantics. Avoid recreating PromptKit inside the bridge.
 - Removal of superseded configuration machinery, retained domain checks, maintained
   examples, canonical documentation updates, and the combined migration guide.
-- The later PromptKit replacement/removal point and release follow-up. Preserve
+- Removal of superseded LLM machinery and release follow-up. Preserve
   the agreed ordering and defer release compliance/publication to the final unit.
 
-If an interim behavior cannot be settled from the evidence, identify that concrete
+Resolve final integration decisions against the evidence. Record genuine open
-open decision as a prerequisite to its production work package. Do not hide it in
+questions without creating scaffolding to support intermediate commits.
-an adapter or describe an unresolved production step as implementation-ready.
 
 Final audit: map every acceptance criterion in the prototype extension to actual
 files and command results. Verify new relative links/anchors, run `git diff --check`,

docs/roadmap/library-adoption.md

@@ -107,9 +107,11 @@ CLI/configuration conventions, update maintained examples and canonical referenc
 and begin the combined migration guide. Include the selected testing-overlay path
 and its offline integration evidence from the ConfigKit roadmap.
 
-If the existing LLM runtime remains temporarily during this stage, keep translation
+ConfigKit and PromptKit adoption form one refactor. These sections describe
-into it small and explicitly transitional. Do not preserve its old settings merely
+implementation order, not separately runnable milestones. Intermediate commits
-to make the temporary bridge convenient. No compatibility mode is owed to users.
+need not build or run. Build directly toward the final integration without
+temporary adapters, compatibility shims, or an interim processing gate; validate
+the complete application before declaring the refactor finished.
 
 ### 4. Complete PromptKit Adoption
 
@@ -120,7 +122,8 @@ prompt-loading, and scheduling machinery once the replacement is verified.
 Retain Audita's transcript pipeline, semantic and deterministic validators,
 correction application, reports, ledger, and artifact retention. Map PromptKit
 results, errors, metadata, and execution observations into those responsibilities.
-Remove the temporary bridge from the preceding stage.
+Connect the new configuration directly to this execution path and remove the
+superseded configuration and runtime machinery.
 
 ### 5. Validate and Release the Combined Migration
 

docs/roadmap/library-boundary-findings.md

@@ -311,9 +311,9 @@ claims of completion for the prototype.
 
 The new profile/credential/capacity and deadline choices are explicit above; no
 unresolved upstream requirement prevents starting the ConfigKit implementation
-plan. Production report field names and the exact temporary bridge implementation
+plan. Production report field names and final runtime wiring follow the outcome
-must be finalized in their respective implementation units, guided by the outcome
+and observation contract here. The coordinated refactor targets both libraries
-and observation contract here.
+directly; intermediate commits do not require a working legacy runtime.
 
 ### Component-Level Next Unit
 
@@ -324,10 +324,9 @@ Implement ConfigKit adoption first, against this target model:
 | `internal/core/config` | Replace file/env merge and custom duration parsing with ConfigKit definitions, presence-aware resolution, domain validation, and explicit override paths. Retain domain defaults and validation rules identified in the inventory. |
 | `internal/cli` | Separate invocation paths from persistent settings; select one file; parse only supplied setting flags into overrides; remove legacy LLM/role-budget/direct-key flags and all environment overlays. Assemble/inspect selected profiles for validation. |
 | CLI config inspection and diagnostics snapshot | Use ConfigKit redacted output plus Audita-owned selected-profile summary; update command tests and diagnostic snapshot consumers. |
-| ConfigKit-to-old-runtime bridge | Temporary adapter from selected profile/backend to legacy LLM inputs, only until PromptKit migration. It must not pretend to implement structural repair, independent backend pools, explicit-zero retry behavior, or new observations through the old adapter. Keep those execution features unavailable until the PromptKit stage, document the intermediate state, and do not release it. Avoid reconstructing PromptKit mechanics to make the bridge feature-complete. |
 | Configuration tests/examples | Replace v1 discovery/overlay/alias expectations with v2 presence, inheritance, secret, profile, and override contracts; preserve domain validation tests. Add actual production discovery and CLI tests not exercised by this prototype. |
 
-The following PromptKit unit replaces `internal/framework/llm` provider execution
+The PromptKit portion of the refactor replaces `internal/framework/llm` provider execution
 and scheduler composition, `internal/prompts` parsing/rendering, and duplicated
 structural-output validation. Keep a small Audita adapter behind the existing
 structured-call boundary where that contract remains sufficient; revise its return
@@ -341,7 +340,7 @@ assembly, and artifact lifecycle. Update their integration wiring rather than
 rewriting those algorithms. Move all nine prompt definitions and schema references,
 checking each module/validator's variables and helpers; this prototype proves only
 one pair. Migrate actual diagnostic redaction and error classification, then remove
-the old transport/schedulers/prompt loader and the ConfigKit bridge.
+the old transport/schedulers/prompt loader. No temporary runtime bridge is needed.
 
 Documentation work during the respective implementation stages: update
 `docs/config.md`, `docs/cli.md`, examples, README prerequisites, internal config/prompt/

docs/roadmap/library-boundary.md

@@ -36,7 +36,7 @@ Required work:
   alone is insufficient evidence.
 - Record new results separately from the historical v0.3.1 findings. Expand the
   existing ConfigKit roadmap into a concrete production implementation handoff,
-  including the interim runtime boundary and removal of legacy configuration.
+  including final runtime integration and removal of legacy configuration.
 
 Target end state: reviewers can run the prototype with and without the testing
 selection and see both LLM roles switch models. The offline test suite establishes
@@ -254,8 +254,8 @@ This unit is complete only when:
   code is clearly isolated and has a removal/integration destination during the
   production migrations; no second supported runtime is introduced.
 - A component-level follow-up identifies code to replace, domain code to retain,
-  tests to update, documentation/migration-guide work, and any temporary bridge
+  tests to update, documentation/migration-guide work, and direct integration of
-  needed while ConfigKit lands ahead of PromptKit.
+  the final configuration and PromptKit runtime.
 - Licensing/distribution follow-up for the selected dependency graph is identified
   for the later release stage; this prototype does not claim release compliance.
 - Roadmap links and examples resolve, appropriate checks pass, and commits contain