| Both `llm.*.model` | `--model`, `--validation-model` | Replace with profile model; new `--proposal-profile` / `--validation-profile` select whole profiles. |
| Both `llm.*.api_key_env`, direct runtime keys | `--llm-api-key`, `--validation-llm-api-key` | Replace with backend ConfigKit secret reference; remove direct key flags. |
| Both `llm.*.timeout` | `--llm-timeout-seconds`, `--validation-llm-timeout-seconds` | Replace with profile `timeout_seconds`, plus `llm.operation_timeout`; no duplicate timeout flags. |
| Both `llm.*.max_retries` | `--max-retries`, `--validation-max-retries` | Replace with common `llm.transient_retries` and distinct `llm.repair_attempts`; remove misleading old flags. |
| Proposal repair exhausted | No proposals from this section; malformed-output warning. | Continue other work; successful completion may include warnings. |
| Assessment repair exhausted | Reject this batch; malformed-output warning. | Continue other work. |
| Schema-valid invalid/missing/duplicate decision indices | Reject batch and warn; no semantic retry/repair. | Continue other work. |
| Inapplicable/low-confidence proposal or negative assessment | Reject affected proposal; preserve domain reasons. | Continue other work. |
| Provider failure, retry exhaustion, transport or malformed HTTP response | Stop affected operation; retain available observations. | Runtime failure; cancel remaining work, retain existing Audita diagnostic handling. |
| Deadline, caller cancellation, capacity admission failure | Stop affected operation; no outer retry or fabricated output. | Runtime failure with distinct classified cause. |
| Invalid settings/profile/schema setup | Fail before processing where detectable. | Configuration error for user input, runtime error for broken embedded assets. |
Zero transient retries produces one ordinary provider failure, not
`ErrRetriesExhausted`; the latter signals an exhausted **positive** budget.
Provider failures retain a typed cause. Do not expose raw provider messages through
user diagnostics: continue Audita's separate secret-redaction boundary. A failed
logical call may return no result while its observations still record completed
attempts or an earlier successful generation. Already completed domain results can
remain in diagnostics; failure must not be presented as a fully corrected output.
## Observation and Report Handoff
The prototype maps library events into Audita-owned records under a short mutex.
Records contain logical run/role/backend/profile identity, generation and attempt
| Combined budgets | 503 → invalid JSON → repair 503 → valid proposal → assessment: five attempts, two transient retries, one repair. |
| Shared capacity | `TestSharedCapacityAndRecovery`: caps four and two, both roles, a retry and repair, queue rejection, measured peak equal to cap, later successful call. |
| Waiting/cancellation/deadline | `TestQueuedCancellationAndDeadline`; `TestDeadlineStopsRetryAfter`: no queued dispatch after cancellation/deadline and a 60-second provider retry delay interrupted by the operation deadline. |
| Failed-run observations | `TestPartialUsageOnFailedRun`: valid HTTP output with known-zero usage followed by repair failure; nil result, retained events, incomplete known aggregate, correct counts. |
| Representative assets | `TestRealPromptRenderingParity` compares both rendered message pairs to Audita v1.1.0; `TestSchemaFixturesMatchAudita` compares schema bytes. |
Commands executed from `examples/library-adoption` on Linux amd64 with Go 1.26.8:
```sh
GOWORK=off go mod download all
GOWORK=off GOPROXY=off GOSUMDB=off go mod verify
GOWORK=off GOPROXY=off GOSUMDB=off go run .
GOWORK=off GOPROXY=off GOSUMDB=off go test -race ./...
GOWORK=off GOPROXY=off GOSUMDB=off go vet ./...
```
All passed. The demonstration reports accepted=1, rejected=0, attempts=4,
transient_retries=0, structural_repairs=2. Module verification reports all modules
verified. Published tag availability was checked with `git ls-remote --tags` for
ConfigKit v0.3.1 and PromptKit v0.11.0; successful module acquisition verifies this
is not merely a local-checkout experiment. The module has no replacements.
The minimum Go 1.25.5 toolchain was also exercised with offline tests and the same
successful demonstration. The exact installed-toolchain invocation was:
```sh
GOTOOLCHAIN=local GOWORK=off GOPROXY=off GOSUMDB=off /home/eric/go/pkg/mod/golang.org/toolchain@v0.0.1-go1.25.5.linux-amd64/bin/go test ./...
GOTOOLCHAIN=local GOWORK=off GOPROXY=off GOSUMDB=off /home/eric/go/pkg/mod/golang.org/toolchain@v0.0.1-go1.25.5.linux-amd64/bin/go run .
```
An initial attempt to select that cached toolchain through `GOTOOLCHAIN=go1.25.5`
with checksum verification disabled was rejected by Go's toolchain verifier. Using
the installed binary with `GOTOOLCHAIN=local` proved offline execution without
weakening dependency checks. The portable README commands assume an installed
sufficiently new Go executable on PATH and disable toolchain switching.
From the Audita root, `go test ./...` and
`go build -o ./bin/audita ./cmd/audita` passed. These check existing production code;
they do not cover the nested module. Affected relative documentation links,
inventory coverage, and `git diff --check` were checked separately.
### Findings and Limits
No adoption-blocking upstream API gap was found. Two integration details deserve
explicit attention: PromptKit's profile GoDoc calls `timeout_seconds` a generation
deadline, but its built-in HTTP path applies it separately to each attempt; the
consumer therefore needs the selected total-operation deadline. Also,
`APIKeyRequired` is an in-memory profile facility, not a profile-YAML field. The
file-profile design uses the presence of ConfigKit's optional credential reference
to require local secret resolution; it does not invent a new PromptKit YAML key.
The chosen defaults are proposed operational policy, not measured model-quality or
cost recommendations. Tests use controlled transport responses and synthetic data;
they do not establish real provider compatibility, model quality, network behavior,
throughput, cross-process coordination, complete billing, or release compliance.
Only the representative LLM-facing subset is implemented in the prototype; the
inventory specifies the remaining domain fields for the ConfigKit migration.
Production file discovery, CLI parsing, full module chains, all nine prompts,
filesystem diagnostics/redaction, and serialized report migration remain their
assigned production tasks. Those are deliberate scope boundaries, not missing
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
must be finalized in their respective implementation units, guided by the outcome
and observation contract here.
### Component-Level Next Unit
Implement ConfigKit adoption first, against this target model:
| Component | Migration action |
| --- | --- |
| `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
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
metadata only as needed for repair and observation outcomes. Avoid library types
in module proposals, domain validators, transcript schemas, and correction ledgers.