audita/docs/roadmap/library-adoption.md

# Next Major Release Roadmap

**Updated:** 2026-11-09

**Status:** Design decisions are resolved across the master and all four child
roadmaps; ready for implementation planning. Implementation and dependency
changes remain pending. The sequence below includes common preflight and output
preparation during CommandKit adoption, followed by glossary-specific readiness
checks with the glossary feature.

## 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` |
| `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 sequence below.

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.

## Proposed Order of Operations

1. **Carry the agreed contracts into implementation planning.** Use the selected
   standard command inventory, discovery behavior, source ownership, and
   reporting and release-workflow expectations to define implementation units.
   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. Include the [automatic prompt-source workflow](promptkit.md#automatic-prompt-sources--resolved)
   and a shared engine loader for processing and standard inspection.
   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. Establish the named preflight package
   and its [output preparation](commandkit.md#output-resource-preparation-during-preflight--resolved),
   applying the [resolved output-failure rules](commandkit.md#output-failure-behavior--resolved).
   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 and extend the common preflight package with glossary-stage readiness
   checks before output preparation. 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

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

### Required Implementation and Acceptance

1. Migrate the direct tool declaration and runtime `buildinfo` import together
   to `go.maximumdirect.net/releasekit` v0.9.0 so build-time version injection
   and runtime reporting use the same implementation. Remove superseded direct
   dependencies and tool registrations.
2. Update the launcher and Woodpecker workflow from 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).
   Include Go host-platform selection and invocation by the full tool-package
   path; a dependency upgrade alone does not update copied recipes. Keep only
   necessary repository wiring around the maintained upstream workflow.
3. Apply the selected checks in `releasekit.json`, add the required
   `delivery.forge: "gitea"`, and retain Audita's product, production targets,
   delivery destination, and CI secret mapping. Align local validation and CI
   with the selected Go 1.27-or-newer toolchain. Include the C compiler and cgo
   prerequisites required by race detection in the maintainer setup.
4. Remove generic launcher and bootstrap tests already covered by ReleaseKit.
   Retain focused checks for Audita's product settings, targets, destination,
   and version integration. Reconcile the release policy and runbook with the
   selected workflow and validator rationale as implementation lands; update
   attribution and link to standard upstream recovery documentation.
5. Verify the selected validators, both production builds, version identity,
   and assembled launcher/CI wiring without publishing a release. Confirm that
   removed local checks are no longer duplicated around upstream validation.
   Hosted-delivery integration remains implementation acceptance work; the
   disposable local check below does not establish it. 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.
- 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.