diff --git a/docs/roadmap/commandkit.md b/docs/roadmap/commandkit.md index 4622dbb..150acf1 100644 --- a/docs/roadmap/commandkit.md +++ b/docs/roadmap/commandkit.md @@ -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 diff --git a/docs/roadmap/configkit.md b/docs/roadmap/configkit.md index 9657825..3aac64f 100644 --- a/docs/roadmap/configkit.md +++ b/docs/roadmap/configkit.md @@ -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. diff --git a/docs/roadmap/library-adoption.md b/docs/roadmap/library-adoption.md index 777b9ea..e980aae 100644 --- a/docs/roadmap/library-adoption.md +++ b/docs/roadmap/library-adoption.md @@ -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.