audita/docs/roadmap/library-adoption.md

Native Library Adoption Roadmap

Updated: 2026-11-07

Status: Agreed direction with proposed sequencing. Initial outlines only; no implementation or dependency changes have been made for this adoption.

Objective and Document Ownership

Align Audita with the supported happy path of ConfigKit, PromptKit, CommandKit, and ReleaseKit so operators and maintainers encounter the same conventions across the application suite. Choose the best target state for Audita; maintaining compatibility with current behavior carries no weight in this major release.

This document owns shared adoption principles, sequencing, dependency selection, and cross-library decisions, including the ReleaseKit adoption work below. The linked outlines own library-specific outcomes, work, acceptance criteria, and open decisions:

Outline	Responsibility
ConfigKit	Stable configuration API, loading, discovery, presence, secrets, and provenance
PromptKit	Native resources and bundled catalog, role integration, execution, and source accounting
CommandKit	Standard operator interface, configuration commands, full ckprompt inspection, and reporting

These four documents replace the removed import-upgrade.md. They retain its relevant technical evidence but supersede its recommendations to disable the OpenRouter bundle, defer CommandKit adoption, limit standard inspection, or preserve Audita's backend ownership restrictions without a domain justification. They do not select unrelated work in future.md.

Agreed Adoption Principles

• ConfigKit: fully adopt and adapt to its stable public API and native conventions. Diverge only where an identified Audita requirement makes it necessary; a local convenience is not sufficient justification.
• PromptKit: follow the mature library's supported path, including its bundled OpenRouter backend and profiles. Significant blockers or pain points may justify a focused upstream feature request before adding substantial local integration machinery.
• CommandKit and integrations: adopt the standard suite experience, including the full ckprompt inspection command set. The libraries are young; problematic or incomplete behavior is a candidate for an upstream change request rather than a permanent Audita workaround.
• ReleaseKit: adopt go.maximumdirect.net/releasekit v0.9.0 and move as much release machinery upstream as possible. Audita may select any number of ReleaseKit-owned validators. Retain local release validation only with a documented domain-specific justification. Treat its maturity as broadly similar to PromptKit, though somewhat lower; significant gaps are candidates for focused upstream requests.
• Major-release cutover: old configuration, CLI, output, and release-workflow behavior impose no compatibility requirement. Do not add compatibility aliases, dual formats, transition modes, or legacy-behavior tests merely to ease adoption. Release guidance may require a hard cutover. Domain requirements still guide the target, but existing implementations and contracts are open to redesign.
• Audita continues to own transcript formats, correction ordering, domain validation, structured-response contracts, and truthful partial-success behavior. Inspect each other restriction against a concrete domain need.
• Standard library inspection and native redaction are part of the target. Existing curated summaries may survive for a distinct domain purpose, but cannot replace the full standard inspection surface.

For each friction point, record the desired outcome, whether the constraint is library behavior or an Audita domain requirement, the proposed adaptation or upstream request, and its acceptance evidence. Distinguish agreed decisions from recommendations. No upstream request has been submitted by this planning work.

Baseline and Selected Dependency Set

The reviewed application revision is cbcb1b3778d747ced7825d09d9e7536cabc0f0fa. Its module file uses old-path ConfigKit v0.7.1 and PromptKit v0.14.0, with no CommandKit. The source minimum is Go 1.26.0; the release runbook selects Go 1.26.8.

The following targets were reviewed as published and mutually aligned:

Module	Version	Reviewed source commit
go.maximumdirect.net/configkit	v1.1.0	191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9
go.maximumdirect.net/promptkit	v0.20.0	8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf
go.maximumdirect.net/commandkit	v0.5.0	49f2d09ccde3d91d8c412a44ab934f223bef8fe6
go.maximumdirect.net/ckconfig	v0.5.0	5c960532552037d38119941389e558f78bf73aad
go.maximumdirect.net/ckprompt	v0.5.0	88ac6e76e4b164571f4172c01d7679c043b94a02

The integration tags are integrations/ckconfig/v0.5.0 and integrations/ckprompt/v0.5.0 in CommandKit's repository. Use the corrected module selection guide; the core tag's guide predates integration publication. The former missing AdaptDiagnostics blocker is resolved. Changes to these reviewed targets need an ordinary compatibility review, not an assumption that later releases are interchangeable.

ReleaseKit v0.9.0 at go.maximumdirect.net/releasekit is also a required target. The library graph already brings in that version, but Audita's direct tool still uses old-path v0.4.1. Direct adoption includes reviewing the v0.9.0 release and validator APIs; the earlier integration checks do not establish its suitability for Audita's complete release workflow.

Proposed Order of Operations

1. Resolve the target contracts across all four libraries. Establish the standard command inventory, discovery behavior, source ownership, and reporting and release-workflow expectations before implementation. Identify concrete upstream requests early; do not postpone CommandKit design until the runtime is done. Reconcile planned changes with the current architecture policy, especially application-only credential rules, finite admission, and preference for standard-library CLI parsing. Update policies with adopted behavior; do not silently treat old integration choices as permanent requirements.
2. Prepare toolchain and migration work. Select Go 1.27 or newer, updating source/build requirements, CI/bootstrap assumptions, release instructions, and toolchain attribution. Upgrade the direct ReleaseKit tool, launcher, and version integration to v0.9.0, implementing the release-machinery work below. Inventory operator file and CLI changes for hard-cutover guidance. Keep implementation units focused; no intermediate public release is needed.
3. Coordinate the ConfigKit and PromptKit cutover. Change both module identities and their exchanged types together, then implement native resource formats, configuration semantics, runtime checks, and standard inspection providers. Avoid a permanent replacement or dual configuration engine.
4. Integrate CommandKit and both standard integrations. Complete the previously designed operator interface, adapting Audita domain handlers and resolving upstream issues. This is required target scope, not an optional follow-up whose justification is deferred.
5. Validate and document the assembled application. Complete the offline behavioral checks from the outlines and the full Audita suite. Update canonical configuration, CLI, operations, integration, and internal documentation with implementation; provide maintained examples and hard-cutover guidance. Validate the adopted release workflow without publishing a release.
6. Prepare the next major release. Public configuration, inspection, and CLI changes warrant a major release under release policy. Exact numbering and publication timing remain release-preparation work. Use the adopted ReleaseKit workflow and selected upstream validators; document required operator changes without requiring a compatibility transition period.

Separate outlines organize responsibility; they do not make the dependency migration independent. The two ConfigKit import identities have distinct Go named types. Early upstream investigation can proceed before the dependent implementation stage is ready.

ReleaseKit Adoption Work

1. Review v0.9.0's supported release workflow, validators, and version integration. Inventory Audita's launcher, scripts, CI responsibilities, and local release checks against those facilities. Select the best target workflow without preserving old invocation or validation behavior for compatibility.
2. Move the direct tool and version integration to the new module identity. Replace local orchestration and validation with supported ReleaseKit facilities wherever possible. Keep repository-specific configuration and necessary domain integration; remove redundant wrappers and checks.
3. Select ReleaseKit-owned validators freely according to the desired workflow; there is no numerical limit or presumption against adopting upstream checks. For every retained local release validator, record its domain-specific purpose and why upstream facilities do not satisfy it. Remove checks without that justification, and propose reusable missing capabilities upstream.
4. Reconcile the release policy and runbook with the selected workflow as it lands, including provisions that would otherwise restrict the chosen upstream validators. Update CI, version reporting, and attribution as needed. The current runbook is a baseline to replace, not a compatibility constraint.
5. Verify the selected validators, version identity, and release orchestration through non-publishing checks. Cover any justified domain validation and verify that removed local checks are no longer duplicated around upstream validation. Adoption work does not authorize publishing a release.

Shared Evidence, Validation, and Completion

The review verified release identities, requirements, and relevant upstream contracts. Disposable checks using Go 1.27.3 established:

• Audita's existing core configuration tests pass after import/API adaptation; the application build still fails at the expected PromptKit API changes.
• CLI parent overrides do not rerun ConfigKit inheritance. PromptKit same-ID replacement drops omitted provider settings; distinct native inheritance can retain them. Profile null endpoints permit backend fallback.
• Tagged CommandKit core, ckconfig, and ckprompt suites pass independently with released dependencies, GOWORK=off, and no local replacements.

These are review results, not implementation acceptance. They involved no live provider calls and do not prove migrated Audita behavior or cross-platform execution. Use controlled provider boundaries and proportionate tests under testing policy; live diagnostics are not release gates.

Completion requires all four adoption targets, resolved decisions, migrated examples, useful native inspection, the selected domain behavior, a passing assembled application, and the adopted ReleaseKit workflow. Every retained local release validator must have a domain-specific justification. Acceptance tests must assert the target contracts; update or remove tests whose sole purpose is preserving superseded behavior. Upstream requests need an explicit disposition before calling the dependent behavior complete. Any temporary workaround must name its reason and removal condition; it is not architecture by default.

Refresh attribution for the exact selected dependencies and toolchain under OSS policy. The reviewed library grants remain LGPL-3.0-or-later; remove old catalog entries when no longer incorporated and retain shared license texts. Do not copy upstream policy inventories.