159 lines
9.1 KiB
Markdown
159 lines
9.1 KiB
Markdown
# 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](configkit.md) | Stable configuration API, loading, discovery, presence, secrets, and provenance |
|
|
| [PromptKit](promptkit.md) | Native resources and bundled catalog, role integration, execution, and source accounting |
|
|
| [CommandKit](commandkit.md) | 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](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](../../go.mod)
|
|
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](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/88ac6e76e4b164571f4172c01d7679c043b94a02/docs/consumers/guide.md#module-selection);
|
|
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
|
|
|
|
1. **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.
|
|
2. **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.
|
|
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 operator migration guidance.
|
|
6. **Prepare the next major release.** Public configuration, inspection, and CLI
|
|
changes warrant a major release under [release policy](../policy/release.md).
|
|
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](../policy/testing.md); 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](../oss/attribution.md) for the exact selected dependencies
|
|
and toolchain under [OSS policy](../policy/oss.md). 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.
|