Document native library adoption plans
This commit is contained in:
158
docs/roadmap/library-adoption.md
Normal file
158
docs/roadmap/library-adoption.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user