eric/audita
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

Plan ReleaseKit adoption and a major-release hard cutover

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-08 01:40:10 +00:00
parent 46765bd326
commit 259f728f20
3 changed files with 84 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/roadmap/commandkit.md
View File

@@ -57,8 +57,9 @@ known publication blocker to adoption.
establish what execution needs. Review generic override forwarding explicitly.
3. Install standard inspection and configuration commands, native formats,
help/version, and suite-consistent aliases/completion through supported APIs.
Supply the application's version identity from its selected ReleaseKit
integration. Do not use a broad private CLI framework around CommandKit.
Supply the application's version identity from the ReleaseKit v0.9.0
integration selected in the master roadmap. Do not use a broad private CLI
framework around CommandKit.
4. Adapt domain process handlers to reporting/outcome boundaries, preserving
transcript/artifact integrity, cancellation, and partial success. Specify quiet
mode, completion summaries, and write failures before implementation. Standard

22
docs/roadmap/configkit.md
View File

@@ -91,21 +91,23 @@ locations and import defaults still need selection before changing operator
behavior. Preserve explicit-path error evidence and distinguish optional from
required imports using native semantics.
**Alternative:** configure the native API with today's two system locations and
imports disabled. This eases installation migration and remains supported, but
should be retained only if deployment requirements justify it; historical behavior
alone does not satisfy the suite-alignment objective. Conversely, enabling all
**Alternative:** configure the native API with two system locations and imports
disabled if deployment requirements justify that source-selection policy. This
limits discovery flexibility and must stand on its own merits; compatibility with
today's installations carries no weight. Conversely, enabling all
possible searches/imports without a selected convention can load unintended
sources and is not required for full API adoption.
### Application Schema Version
**Recommendation:** retain `version: 2` only if the resulting application fields
and meaning remain coherent after PromptKit ownership is settled. Do not confuse
it with the library version or PromptKit's source header. This avoids meaningless
schema churn while allowing deliberate field migration.
**Recommendation:** design the application schema around the target ownership
boundaries, then choose its version to describe that contract. Keeping `version: 2`
is reasonable only if its meaning remains coherent; compatibility with existing
files is not a selection criterion. Do not confuse the application schema version
with the library version or PromptKit's source header.
**Alternative:** introduce a new application schema version if backend or
credential ownership changes make existing files misleading. It provides a clear
migration boundary, at the cost of updating files and guidance. Decide from the
final schema, not from dependency version numbers alone.
migration boundary; the version alone does not explain the new contract, so
hard-cutover guidance still needs to describe it. Decide from the final schema,
not from dependency version numbers alone, and do not add legacy-schema support.

102
docs/roadmap/library-adoption.md
View File

@@ -7,13 +7,15 @@ no implementation or dependency changes have been made for this adoption.
## Objective and Document Ownership
Align Audita with the supported happy path of ConfigKit, PromptKit, and
CommandKit so operators encounter the same conventions across the application
suite. Existing Audita behavior alone is not a reason to diverge.
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.
This document owns shared adoption principles, sequencing, dependency selection,
and cross-library decisions. The linked outlines own library-specific outcomes,
work, acceptance criteria, and open decisions:
and cross-library decisions, including the ReleaseKit adoption work below. The
linked outlines own library-specific outcomes, work, acceptance criteria, and
open decisions:
| Outline | Responsibility |
| --- | --- |
@@ -40,6 +42,17 @@ They do not select unrelated work in [future.md](future.md).
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.
- 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.
@@ -52,14 +65,14 @@ library behavior or an Audita domain requirement, the proposed adaptation or
upstream request, and its acceptance evidence. Distinguish agreed decisions from
recommendations. No upstream request has been submitted by this planning work.
## Baseline and Reviewed Dependency Set
## 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 reviewed targets are published and mutually aligned:
The following targets were reviewed as published and mutually aligned:
| Module | Version | Reviewed source commit |
| --- | --- | --- |
@@ -77,19 +90,28 @@ the core tag's guide predates integration publication. The former missing
an ordinary compatibility review, not an assumption that later releases are
interchangeable.
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 three outlines.** Establish the
1. **Resolve the target contracts across all four libraries.** Establish the
standard command inventory, discovery behavior, source ownership, and
reporting expectations before implementation. Identify concrete upstream
requests early; do not postpone CommandKit design until the runtime is done.
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
application-only credential rules, finite admission, and preference for
standard-library CLI parsing. Update policies with adopted behavior; do not
silently treat old integration choices as permanent requirements.
2. **Prepare toolchain and migration work.** Select Go 1.27 or newer, updating
source/build requirements, CI/bootstrap assumptions, release instructions,
and toolchain attribution. Inventory operator file and CLI migration needs.
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
@@ -102,17 +124,43 @@ interchangeable.
5. **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 operator migration guidance.
implementation; provide maintained examples and hard-cutover guidance. Validate
the adopted release workflow without publishing a release.
6. **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 existing release process without importing upstream release gates.
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
@@ -131,28 +179,16 @@ 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 three adoption targets, resolved decisions, migrated
examples, useful native inspection, preserved domain behavior, and a passing
assembled application. 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 requires all four adoption targets, 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.
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
### Direct ReleaseKit Migration
**Recommendation:** assess the direct ReleaseKit tool and launcher in a distinct
preparation unit, coordinating its import identity and version reporting if the
new tool is adopted. The library graph brings new-path ReleaseKit v0.9.0 but does
not migrate Audita's old-path v0.4.1 tool. Explicit treatment avoids accidental
release behavior changes and makes the duplicate identities understandable.
**Alternative:** migrate ReleaseKit within the same toolchain unit. This reduces
duplicate module identities sooner and may simplify attribution, but broadens
that unit into release-workflow compatibility work. Neither choice authorizes
adopting upstream publication gates or publishing a release during implementation.