Files
audita/docs/roadmap/promptkit.md

7.8 KiB

PromptKit v0.23.0 Adoption Roadmap

Status: Accepted target; implementation pending. This pass changes planning documents only. The implementation plan owns the ordered tasks and verification.

Objective and Baseline

Upgrade Audita directly from PromptKit v0.21.0 to v0.23.0 and fully adopt its conversation, coordinator, and execution-group APIs. Removing redundant local machinery is an explicit completion requirement. A dependency-only upgrade or continuation adoption with the old repair loop retained is an intermediate state.

The current dependency manifest pins v0.21.0. Audita captures its own exchange and replay values, reconstructs and compares conversation prefixes, appends repair history, manages the revision loop, and aggregates terminal observations locally. Each role client wraps explicit preparation and execution in a local deadline. See the LLM runtime, pipeline, and diagnostic implementation.

PromptKit v0.23.0 includes the v0.22.0 conversation and accounting capabilities plus the execution controls needed for full coordinator adoption. The former upstream timeout and prepared-request gaps are closed; no intermediate v0.22.0 rollout or further upstream feature gate is required. The Go minimum and dependency versions are unchanged by these upstream releases.

The release review verified Audita's existing suite against the tagged v0.23.0 source through a temporary module override and selected upstream packages with race detection. That is compatibility evidence, not verification of the migration described here. Implementation must use the released dependency, without a local replacement or committed workspace file.

Target Ownership

Responsibility Target owner
Immutable captured history, continuation assembly, and parent run identity PromptKit Exchange, CaptureExchange, and ContinueFrom
Sequential turns, additional-turn budget, callback delivery, and coordination termination PromptKit Engine.Coordinate
Whole-operation deadlines and timeout attribution PromptKit OperationTimeout and ErrOperationTimeout
Exact prepared-request notification before generation PromptKit OnPrepared
Selected run membership, deduplication, and terminal count/usage aggregation PromptKit ExecutionGroup and ComposeObservers
Candidate identity, actionable rejection, feedback, revision decoding, withdrawal, and full revalidation Audita
Branch scheduling, accepted sibling proposals, application order, and transcript mutation Audita
Domain operation labels, failure disposition, reports, redaction, and debug artifact storage Audita

Use the supported public API through Audita's framework adapter boundaries. Keep module and validator contracts domain-oriented. Any bridge needed by the runner must delegate to the real coordinator and retain opaque conversation state, rather than implementing another conversation engine or general workflow framework.

Selected Behavior

Execution and diagnostics

Use ordinary Engine.Run with per-request OperationTimeout and OnPrepared where explicit preparation currently serves only to inspect and execute the same request. Map the resolved Audita operation timeout onto each proposal, validation, and repair operation. Keep provider, transport-retry, structural-repair, and correction-revision budgets distinct.

Use ErrOperationTimeout to identify the selected local budget, while retaining Audita's parent-cancellation and recoverable-provider-failure handling. Do not classify every wrapped preparation error as fatal before considering its timeout identity. Ordinary configuration failures remain fatal. If split preparation is still needed for a concrete consumer, one caller context must cover both calls when a total preparation-plus-execution deadline is required; the upstream prepared-handle duration starts only at execution.

OnPrepared receives the actual detached snapshot. Retain the metadata needed for attribution and credential-source redaction, and capture content for optional debug evidence. Keep the callback short; application validation belongs in the next-turn callback after admission is released. Notification may be absent on preparation/admission failure or cancellation before delivery. Reports must not invent missing snapshots. Optional debug write failures remain nonfatal.

Conversations and correction repair

Capture the proposal exchange when repair needs it. Every rejected candidate's branch starts from that same immutable exchange; subsequent turns remain private to that branch. Follow-ups select the module's repair prompt, role profile, variables, and repair output contract through ordinary PromptKit requests. Retain native operator prompt overrides and the existing domain prompt content.

Use one coordinator per actionable correction. Its initial callback uses existing rejection findings. Each newly delivered response must pass structural validation before decoding; captured content alone does not imply validity. A decoded revision is fully revalidated before acceptance. Withdrawal, unavailable results, and accepted revisions remain Audita outcomes; a normal coordinator stop is not itself an approval.

The last permitted response follows the same assessment path. Further requested work beyond the budget maps to exhaustion. Skip coordination when Audita's correction-repair setting disables it: upstream's zero budget still invokes an initial callback. Cancellation's Undelivered response is diagnostic evidence, not an approved correction, and must not trigger model work after cancellation. Recoverable branch failures preserve independent approvals; fatal failures and caller cancellation retain Audita's cancel-and-join behavior.

Execution groups

Use native groups as the source of aggregate provider-attempt, retry, repair, and available token totals. Explicitly select membership for proposal calls, coordinated continuations, and validator calls. Coordinator observers cover its own turns; nested validators require their own observer selection.

Maintain an invocation group for combined execution totals. Add narrower groups only for accounting views Audita consumes. A shared initial proposal run belongs once to the invocation total; replaying its history does not enroll it again. Each new call's reported history tokens still count. Overlapping group totals must not be summed as disjoint work.

Preserve upstream usage presence/completeness and terminal coverage separately. Keep domain logical-call records and deterministic presentation where needed; their count need not equal observed run membership. Group summaries do not replace Audita's errors/recoveries, validation decisions, or per-operation failure facts.

Delivery and Completion

Implement in ordered, reviewable stages: dependency and execution adapter; captured conversations and coordinator; execution groups; cleanup, integration verification, and canonical documentation. All stages belong to this adoption.

Completion requires removal of local exchange/replay history, prefix checks, repair turn-budget loops, and duplicate terminal aggregation where replaced by PromptKit. Retain local behavior only where it has a concrete Audita domain or presentation responsibility. Preserve transcript correctness, repair prompts, validation semantics, deterministic reports, standard inspection commands, and operator configuration unless a deliberate change is documented and tested.

No product-level open decisions remain. Exact internal bridge signatures are implementation choices governed by this ownership split. Future validator decision recovery and new scheduling behavior remain in the deferred work catalog.