241 lines
15 KiB
Markdown
241 lines
15 KiB
Markdown
# 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. 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 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.
|