9.1 KiB
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, and CommandKit so operators encounter the same conventions across the application suite. Existing Audita behavior alone is not a reason to diverge.
This document owns shared adoption principles, sequencing, dependency selection, and cross-library decisions. 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.
- 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 Reviewed 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 reviewed targets are 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.
Proposed Order of Operations
- Resolve the target contracts across all three outlines. Establish the standard command inventory, discovery behavior, source ownership, and reporting 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.
- Prepare toolchain and migration work. Select Go 1.27 or newer, updating source/build requirements, CI/bootstrap assumptions, release instructions, and toolchain attribution. Inventory operator file and CLI migration needs. Keep implementation units focused; no intermediate public release is needed.
- 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.
- 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.
- 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 operator migration guidance.
- 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 existing release process without importing upstream release gates.
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.
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 three adoption targets, resolved decisions, migrated examples, useful native inspection, preserved domain behavior, and a passing assembled application. 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.
Open Decisions
Direct ReleaseKit Migration
Recommendation: assess the direct ReleaseKit tool and launcher in a distinct preparation unit, coordinating its import identity and version reporting if the new tool is adopted. The library graph brings new-path ReleaseKit v0.9.0 but does not migrate Audita's old-path v0.4.1 tool. Explicit treatment avoids accidental release behavior changes and makes the duplicate identities understandable.
Alternative: migrate ReleaseKit within the same toolchain unit. This reduces duplicate module identities sooner and may simplify attribution, but broadens that unit into release-workflow compatibility work. Neither choice authorizes adopting upstream publication gates or publishing a release during implementation.