audita/docs/roadmap/library-adoption.md

# Next Major Release Roadmap

**Updated:** 2026-11-09

**Status:** Target decisions are recorded across this roadmap and its four child
roadmaps; implementation and dependency changes remain pending. The
[implementation plan](implementation.md) owns the sprint sequence.

## 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, dependency selection, and
cross-library decisions, including the ReleaseKit target below. The linked
outlines own feature-specific outcomes and acceptance criteria:

| 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` |
| `go.maximumdirect.net/releasekit` | v0.9.0 | `2180aa868ec2caa95fc8279fd59d5f0ebac41bd4` |

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 [implementation plan](implementation.md).

The reviewed target dependency graph includes ReleaseKit v0.9.0, but Audita's
direct tool still uses old-path v0.4.1. The release, workflow, and validator review
is complete, with no identified upstream blocker. The agreed
[ReleaseKit adoption work](#releasekit-adoption-work) below remains to be
implemented and accepted in Audita.

## ReleaseKit Adoption Work

### Workflow and Validator Selection — Resolved

Adopt ReleaseKit v0.9.0's standard publication and asynchronous delivery workflow.
This implements the ownership decision in [ADR 0001](../adr/0001-releasekit.md).
Audita already delegates publication, builds, and delivery to ReleaseKit; the
upgrade modernizes that integration and removes duplicated generic tests. No
additional Audita-owned release validator or upstream feature request is needed
for the reviewed requirements. Audita's domain tests remain in the ordinary
offline suite executed by ReleaseKit.

The selected workflow is:

1. Prepare the release note and final committed candidate, then push that
   candidate to the authoritative `main` branch.
2. Use one ReleaseKit `publish` invocation to validate the candidate, check the
   required builds and version identity, and publish the annotated tag. Keep
   `check` available for diagnosis; do not require it before `publish` repeats
   validation.
3. Use the maintained Woodpecker tag-delivery workflow to invoke `ci-deliver`
   from the tagged source. Deliver the hosted release page, Linux amd64 and arm64
   binaries, and checksums asynchronously. Successful tag publication completes
   the source release; report artifact delivery separately.
4. Use ReleaseKit's standard recovery commands and procedures for publication
   and delivery failures, without a separate Audita recovery layer.

Use the reviewed upstream [publication guide](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.9.0/docs/consumers/publish.md),
[delivery guide](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.9.0/docs/consumers/delivery.md),
and [configuration reference](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.9.0/docs/config.md)
for standard behavior. Select these checks through the native release profile:

| Capability | Selection | Reason |
| --- | --- | --- |
| Standard offline Go test suite and candidate/publication guards | Retain ReleaseKit's built-in checks | Validate Audita's behavior and the exact source being published. |
| Race detection | `validation.go.race: true` | Audita's concurrent processing and cancellation warrant race detection in the single standard suite. |
| Full Go vet | `validation.go.full_vet: true` | Add static checks; ReleaseKit disables test-time vet to avoid duplication. |
| Go formatting | `validation.go_format: true` | Enforce consistent formatting through the shared implementation. |
| Local Markdown links and heading references | `validation.markdown: {}` | Protect documentation navigation using upstream defaults. |
| Committed workspace files | `validation.module_distribution.workspace_files: true` | Keep development workspace files out of releases. |
| Filesystem module replacements | `validation.module_distribution.local_replacements: true` | Prevent releases depending on local dependency checkouts. |
| Application builds and version identity | Retain `build.targets` for `linux/amd64` and `linux/arm64`, with ReleaseKit's native version check | Verify the required production binaries and their embedded version. |
| Additional compile-only targets | Omit `validation.go.compile_targets` initially | Limited additional value alongside the required application builds. |
| File-size limits | Omit `validation.file_size` initially | No application-specific size ceiling has been selected. |
| Forbidden-file paths | Omit `validation.forbidden_files` initially | Delivery uses the existing CI secret; no release-token file is configured. |

Do not duplicate these checks in profile `checks`, custom release hooks, or
surrounding scripts. Any future local release validator requires a documented
domain-specific justification; reusable gaps should be addressed upstream.

### Release Integration Acceptance

The direct tool and runtime version accessor use the same v0.9.0 module identity.
The launcher and Woodpecker bootstrap follow the v0.9.0
[adoption recipes](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.9.0/docs/consumers/adoption.md)
and [tag-delivery template](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.9.0/examples/woodpecker/tag-delivery.yml),
including host target selection, full tool-package invocation, and prepared tag
checkout verification. Audita retains its product, Linux production targets,
delivery destination, and CI secret mapping, with `delivery.forge: "gitea"`.
Local validation and CI use the selected Go 1.27-or-newer toolchain; maintainer
setup includes the C compiler and cgo prerequisites for race detection.

ReleaseKit owns generic bootstrap, launcher, and selected native validation
mechanisms. Audita retains focused evidence for its product settings, targets,
destination, and version integration. Acceptance covers the selected validators,
both production builds, version identity, and assembled launcher/CI wiring,
without publishing a release. The disposable local check below is evidence for
local candidate validation and does not establish hosted delivery. Adopted policy
and runbook describe the selected workflow, validator rationale, and native recovery.

## 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.
- A disposable Audita copy with the ReleaseKit tool and runtime version import
  migrated to v0.9.0, and toolchain references aligned, passes the selected native
  validators, Linux amd64 and arm64 builds, and the native version-output check.
  This exercised local `check` only; no release was published and hosted delivery
  was not exercised.

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.