audita/docs/roadmap/library-adoption.md

# Next Major Release Roadmap

**Updated:** 2026-11-08

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

## 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.

The release also includes glossary stages that select different glossary inputs.
This is required feature scope alongside the library upgrades.

This document owns shared adoption principles, sequencing, dependency selection,
and cross-library decisions, including the ReleaseKit adoption work below. The
linked outlines own feature-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 |
| [Stage-Specific Glossary Inputs](glossary-stages.md) | Ordered glossary stages that select different input files |

This master roadmap and the three library outlines 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.
- **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.
- **Remove redundant code:** reducing Audita's maintenance burden is an explicit
  adoption goal. Retire local mechanisms, settings, wrappers, and tests superseded
  by supported upstream behavior. Keep the domain logic and integration code that
  Audita needs; retaining existing code is not a success criterion.
- 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.
  Retire the curated profile summary in favor of the standard inspection and
  preview interfaces, as resolved in the [PromptKit outline](promptkit.md).

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. The [CommandKit outline](commandkit.md#upstream-review-shared-debug-input-and-reporting-mode)
records the reporting request and resulting upstream capability plan.

## Baseline and Selected 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 following versions were reviewed as published and mutually aligned.
CommandKit and its integrations are review baselines; final adoption selection
is subject to the release gate below:

| 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.

**CommandKit release gate:** adoption implementation waits for a published core
version providing both the independent shared debug binding for capture and the
resolved reporting-mode accessor for quiet destination validation, as required by
the [CommandKit outline](commandkit.md#adoption-gate-released-debug-binding-and-reporting-mode-access).
Either API alone is insufficient. Replace the reviewed v0.5.0
core target with that release and record compatible released integration versions
and exact source revisions after review. No replacement version is selected yet.

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
   preference for standard-library CLI parsing. Backend, credential, and
   concurrency ownership are resolved in the [PromptKit outline](promptkit.md):
   adopt native behavior and retire Audita's duplicate registry and policies.
   Update application-only credential rules, the finite-admission requirement,
   and other affected contracts with adopted behavior; do not
   silently treat old integration choices as permanent requirements.
   Keep stage-specific glossary inputs in view when choosing configuration and
   CLI contracts; detailed feature design and implementation follow adoption.
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.
   Identify and remove local code made redundant by the adopted facilities as
   part of each migration, rather than leaving cleanup as an unspecified follow-up.
4. **After the CommandKit release gate opens, integrate core and both standard
   integrations.** Confirm both required public APIs are published and
   select the released dependency set as described above before starting this
   implementation stage. Complete the previously designed operator interface,
   adapting Audita domain handlers and resolving upstream issues. Earlier design
   and independent library work may proceed while waiting. This remains required
   scope for the next major release.
5. **Add stage-specific glossary inputs.** After all four library adoptions,
   complete the [glossary-stage roadmap](glossary-stages.md). Use the adopted
   configuration, resource, and CLI conventions to support ordered stages such
   as `party.yml` followed by `spells.yml` in one processing run. This sequencing
   avoids designing the feature around interfaces that the upgrades replace.
6. **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.
7. **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 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](../policy/testing.md); live diagnostics are not release gates.

Completion requires all four library adoption targets, stage-specific glossary
inputs, 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.

Completion also includes retiring superseded local machinery and its obsolete
configuration, documentation, and tests. Preserve evidence for the selected
domain behavior and real integration boundaries without duplicating upstream
implementation tests. Code removal is a desired result, with no deletion quota.

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.