audita/docs/roadmap/library-adoption.md

# Next Major Release Roadmap

**Updated:** 2026-11-09

**Status:** Agreed direction with proposed sequencing. Initial outlines only;
no implementation or dependency changes have been made for this plan. Resolve
the two remaining [open decisions](#open-decisions) in the listed order.

## 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 reusable glossary configuration composed through
ConfigKit and stages that select different glossary inputs. This is required
feature scope alongside the library upgrades; the glossary roadmap owns the
configuration handoff and derived runtime representations.

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) | Reusable glossary configuration, stage selections, and derived runtime vocabulary |

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. For standard commands passed through by
  Audita, link concisely to upstream documentation instead of maintaining a local
  reference, warnings, or caveats about upstream capabilities. Document Audita's
  own inputs, wiring, and domain-specific behavior.
- **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's application configuration uses `version: 3` with a hard cutover, as
  resolved in the [ConfigKit outline](configkit.md#application-schema-version--resolved).
- **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 released reporting capabilities and adoption evidence.

## 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 published versions are selected for adoption. CommandKit core and
both integrations use the reviewed v0.6.0 release set; its release gate is
satisfied as recorded 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.6.0 | `1613ff95cab60581de5d86f6e9e2a3cc091a44a0` |
| `go.maximumdirect.net/ckconfig` | v0.6.0 | `5ed947bd26bf2c6d70d1d748b693eca89f18d605` |
| `go.maximumdirect.net/ckprompt` | v0.6.0 | `1ca660e35fb58fc0dc318e411afb6e3631a40ef1` |

The integration tags are `integrations/ckconfig/v0.6.0` and
`integrations/ckprompt/v0.6.0` in CommandKit's repository. Use the
[released module selection guide](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/1ca660e35fb58fc0dc318e411afb6e3631a40ef1/docs/consumers/guide.md#module-selection).
The integration updates retain ConfigKit v1.1.0 and PromptKit v0.20.0 and require
Go 1.27. Changes to these selected versions require an ordinary compatibility
review rather than assuming later releases are interchangeable.

**CommandKit release gate — satisfied:** the published v0.6.0 core provides both
the independent shared debug binding for capture and the resolved reporting-mode
accessor for quiet destination validation. The matching released integrations
were reviewed together. The [CommandKit outline](commandkit.md#adoption-gate-released-debug-binding-and-reporting-mode-access)
records the API contract and review evidence. The selected release set removes
the upstream availability blocker; Audita implementation and acceptance remain
pending under the sequence below.

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. **Integrate the selected CommandKit core and both standard integrations.**
   The upstream release gate is satisfied. Complete the designed operator
   interface using the selected v0.6.0 set, adapting Audita domain handlers and
   verifying the assembled application. Resolve concrete new integration gaps
   upstream. 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 and CLI conventions to compose reusable glossary assets through
   ConfigKit, then derive Audita's runtime views for ordered stages such as a
   party pass followed by a spell pass. Remove the standalone glossary parsing
   path. 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

The concrete workflow and validator selection remain
[open decision 1](#1-releasekit-workflow-and-validator-selection).

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 v0.6.0 suites pass independently
  with released dependencies, `GOWORK=off`, and no local replacements.
- A separate consumer of all three published v0.6.0 modules passes 33 cases
  covering debug capture, reporting-mode ordering, aliases, and quiet transcript
  destination validation. The assembled graph retains the selected ConfigKit and
  PromptKit versions and brings in ReleaseKit v0.9.0.

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.

## Open Decisions

Work through these decisions in order. Recommendations below remain proposals;
the existing adoption principles remain in force. CommandKit release selection
is resolved in the dependency set above.

### 1. ReleaseKit Workflow and Validator Selection

Inventory the current launcher, scripts, CI responsibilities, version integration,
and local release checks against ReleaseKit v0.9.0. Select the concrete workflow,
upstream validators, machinery to remove, and any remaining domain-specific
checks. ReleaseKit adoption and its target version are already agreed.

**Recommendation:** use the upstream-supported release workflow to own as much
orchestration and validation as it supports. Select all ReleaseKit-owned validators
appropriate to Audita's release requirements, and retain local validation only
with a documented domain-specific justification. This directly reduces Audita's
maintenance burden and follows the suite's standard path. The inventory must
establish which facilities cover the current responsibilities and whether an
upstream request is needed.

**Alternative:** let CI explicitly sequence ReleaseKit commands through a thin
repository-owned orchestration layer where the upstream workflow cannot express
Audita's required scheduling or platform coordination. Validation still belongs
upstream except for justified domain checks. This can fit concrete CI needs but
retains local sequencing to maintain; prefer an upstream enhancement for a
reusable gap rather than permanently duplicating release machinery.

### 2. Output-Failure Behavior

Resolve the [output-failure decision](commandkit.md#output-failure-behavior) in
the CommandKit roadmap after the ReleaseKit selection above. That document owns the
recommendation, alternative, and behavior contract. This decision completes the
remaining write-failure detail before implementing the output/reporting boundary.