Plan the Audita adoption sprint

This commit is contained in:
2026-11-09 16:03:16 +00:00
parent 4920393204
commit 0c7622375f
6 changed files with 689 additions and 311 deletions

View File

@@ -2,11 +2,9 @@
**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.
**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
@@ -20,10 +18,9 @@ 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:
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 |
| --- | --- |
@@ -118,7 +115,7 @@ 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.
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
@@ -126,68 +123,6 @@ 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
@@ -238,34 +173,25 @@ 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
### Release Integration 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.
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