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

Plan the Audita adoption sprint

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-09 16:03:16 +00:00
parent 4920393204
commit 0c7622375f
6 changed files with 689 additions and 311 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
docs/roadmap/commandkit.md
View File

@@ -4,9 +4,9 @@
**Status:** Adoption target and design decisions resolved; the upstream release
gate is satisfied. Implementation remains pending. The
[master roadmap](library-adoption.md) owns shared direction, exact dependency
revisions, and sequencing; ConfigKit and
PromptKit contracts are developed in [their](configkit.md) [outlines](promptkit.md).
[master roadmap](library-adoption.md) owns shared direction and exact dependency
revisions; the [implementation plan](implementation.md) owns sequencing. See the
[ConfigKit](configkit.md) and [PromptKit](promptkit.md) outlines for their contracts.
## Baseline and Target
@@ -244,10 +244,8 @@ Audita processing context. Request preview and validation operate on supplied
inputs; representative validator candidates can come from maintained fixtures
without running proposal inference as part of request construction.
Establish runtime and request construction first, then wire preview and
validation, followed by smoke commands and assembled-CLI verification. All are
required adoption scope. Address concrete integration blockers upstream rather
than silently omitting standard capabilities.
All three capabilities are required adoption scope. Address concrete integration
blockers upstream rather than silently omitting standard capabilities.
For standard CommandKit commands passed through by Audita, provide a concise
link to the upstream documentation for the adopted version. Upstream owns their
@@ -257,50 +255,23 @@ limitations of the standard capabilities. Audita documentation covers only its
own selectors, request construction, domain inputs, and application-specific
behavior. Apply this documentation boundary to the whole standard command suite.
## Work Outline
## Integration Boundaries
The adoption gate above is satisfied. Follow the master sequence and selected
released dependency set when implementing this outline.
The native `app` and PromptKit configuration scopes are distinct. Both sides of
native comparison use their own selected inputs. Scope validation follows native
scope behavior; process preflight checks what execution needs. The same
engine-loading path and
[automatic source contract](promptkit.md#automatic-prompt-sources--resolved)
serve processing and all standard PromptKit commands. ReleaseKit supplies the
application version; CommandKit owns standard flags, formats, help, completion,
and outcomes, including native comparison status 3.
1. Inventory Audita commands, arguments, flags, supplied empty/false/zero values,
streams, and exit behavior against standard declarations. Record intentional
migrations rather than recreating the old parser around CommandKit.
2. Establish shared loaders and scopes using the native ConfigKit and PromptKit
integrations. Use the same engine-loading path for processing and every
PromptKit inspection, preview, validation, and smoke command, following the
[automatic source contract](promptkit.md#automatic-prompt-sources--resolved).
Keep configuration/resource inspection distinct from preparing
an actual domain request. Standard scope validation need not reproduce the
current combined settings-and-two-roles command; process setup must still
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 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. Apply the
resolved visibility, completion-summary, and
[output-failure rules](#output-failure-behavior--resolved). Establish the
preflight package and its [output preparation](#output-resource-preparation-during-preflight--resolved)
through the output-session component. The later glossary feature extends the
same package with its collection-readiness checks before resource preparation.
Standard command statuses, including comparison status
3, should not be forced into the old Audita-only status table without a domain
reason. Validate quiet mode against the transcript destination before creating
outputs or starting model work, using the released reporting-mode accessor.
Wire processing artifact capture to the released shared debug boolean; replace
Audita's independent debug parsing with the native binding while retaining its
application-owned capture behavior.
5. Enable the standard preview, validation, and full smoke capabilities using the
resolved adapter and sequencing approach above. Share Audita request helpers
where domain additions are needed; keep generic resource inspection independent
of those domain inputs.
6. Update [CLI](../cli.md), [configuration](../config.md), [operations](../operations.md),
[subprocess integration](../integrations/subprocess.md), examples, help,
completion guidance, and migration documentation with implementation. Document
Audita-specific behavior and link to upstream for standard command usage.
Adopt the dependencies and exact attribution together.
Audita supplies typed process inputs, domain request construction, preflight,
and output-session coordination. [Glossary readiness](glossary-stages.md#empty-collections-and-audita-preflight--resolved)
is part of that shared phase. Standard inspection remains independent of
processing inputs. Canonical Audita documentation owns application-specific
behavior and the hard cutover; standard commands link to the adopted upstream
reference. Exact selected dependencies and notices belong in attribution.
## Acceptance and Upstream Requests

89
docs/roadmap/configkit.md
View File

@@ -2,8 +2,9 @@
**Updated:** 2026-11-09
**Status:** Initial outline. The [master roadmap](library-adoption.md) owns the
agreed adoption policy, reviewed versions, shared sequencing, and completion.
**Status:** Target decisions resolved; implementation pending. The
[master roadmap](library-adoption.md) owns shared policy and dependency selection;
the [implementation plan](implementation.md) owns sequencing.
## Baseline and Target
@@ -92,69 +93,29 @@ native absent-main lifecycle instead of manufacturing a placeholder file or
source record. Explicit-file errors and failures loading a selected discovered
file remain terminal.
### Migration Work
### Target Boundaries
1. Move imports to `go.maximumdirect.net/configkit` with the coordinated
PromptKit cutover. Raise the toolchain as specified by the master roadmap.
Replace `Resolution.Record` uses with the appropriate dedicated recording
method; review affected metadata and diagnostics APIs, not only compilation.
Relevant renamed concepts include `EntryInfo`, `Sensitive`, `LayerMain`,
version evidence, and destination fallback. Typed `Secret` and its field tag
retain their spelling.
2. Adopt the native lifecycle: source composition and inheritance, typed decoding,
explicit CLI assignments, then application resolution and validation. CLI
assignments do not repair earlier decoding failures, alter inheritance
relationships, or propagate parent edits through already resolved children.
Update the current loading-order explanation and realistic integration tests.
3. Migrate genuine source-root control blocks to `config:` where present.
Implement the version-3 application schema and hard cutover above. Distinguish
application schema versions from source version evidence; do not impose
headers on every fragment merely because the API supports them.
4. Use identified collections where records have meaningful identity. ConfigKit
upsert replaces matching records in full; inspection follows registered
identities through movement, while list diffs remain atomic. Preserve ordinary
ordered/repeated pipeline stages and explicit empty-pipeline semantics:
these express Audita domain behavior, so uniqueness/upsert is inappropriate.
5. Integrate native source discovery and standard inspection instead of retaining
equivalent private infrastructure. Adopt source diagnostics, explanation,
history, normalization, and safe effective output through ckconfig. Account
for the provenance label changing from `base` to `main`.
6. Apply the resolved [PromptKit ownership decision](promptkit.md#backend-and-credential-ownership--resolved):
remove Audita's separate backend mapping and LLM credential references from
its application schema. Native PromptKit resources own those settings and
their resolution. Coordinate the hard cutover and examples here, using the
resolved discovery and import policy above and the
[automatic PromptKit source contract](promptkit.md#automatic-prompt-sources--resolved).
7. Account for the [root-default and stage-override model](glossary-stages.md#root-defaults-and-stage-overrides--resolved)
in version-3 schema design. Implement it during the glossary feature stage
after library adoption. Each stage resolves independently with explicit-value
presence and source provenance, and its module and validators receive consistent
effective settings. Apply its [selected scope and fallback rules](glossary-stages.md#configuration-scope--resolved)
and [compound-value and clearing rules](glossary-stages.md#compound-values-and-explicit-clearing--resolved),
together with its [CLI precedence and native-support boundary](glossary-stages.md#cli-overrides-and-stage-precedence--resolved).
Use its [separate glossary and protection selections](glossary-stages.md#glossary-selection-and-protected-vocabulary--resolved),
including root protection defaulting through recorded application resolution.
Adopt its [glossary configuration ownership boundary](glossary-stages.md#glossary-configuration-ownership--resolved):
glossary assets use native loading, composition, inheritance, collection
identity, and typed decoding before handoff. Audita derives consumer-specific
runtime views from that result and removes its separate glossary YAML loader.
Use its [named collections and recursive import placement](glossary-stages.md#named-collections-and-recursive-imports--resolved),
retaining native discovery, source context, and tier semantics.
Supply its [optional default glossary sources](glossary-stages.md#default-sources-and-explicit-configuration--resolved)
in one underlay, with higher-priority explicit main configuration.
Register its [collection-scoped entry IDs](glossary-stages.md#entry-identity--resolved)
through native sequence identity registration. Apply its
[extensible entry content contract](glossary-stages.md#entry-content-fields--resolved)
using native typed fields and inline extension data. Honor its
[list-input and handoff contract](glossary-stages.md#list-inputs-and-configuration-handoff--resolved):
complete configuration resolution through ConfigKit before handoff; runtime
consumers treat null selections as empty without restoring defaults. Follow its
[Audita preflight boundary](glossary-stages.md#empty-collections-and-audita-preflight--resolved):
permit empty collection configuration and check glossary-stage readiness in
Audita after handoff, before execution.
Apply its [optional stage identity and attribution contract](glossary-stages.md#stage-identity-and-attribution--resolved)
and complete its required durable decision record. This application scope model
does not change native source composition or sibling-inheritance semantics.
The application uses the `go.maximumdirect.net/configkit` module and native
recorded resolution, discovery, source diagnostics, and safe effective output.
Source composition and inheritance precede typed decoding and explicit CLI
assignment; application resolution and validation follow. CLI assignments do
not repair earlier decoding failures, change inheritance relationships, or
propagate parent edits through resolved children. Native source provenance uses
`main` in place of `base`. Genuine source-root controls use `config:`.
PromptKit [owns backend and credential resources](promptkit.md#backend-and-credential-ownership--resolved).
Audita's v3 schema has no separate backend or LLM credential registry. Native
[automatic resource sources](promptkit.md#automatic-prompt-sources--resolved)
remain independent of main application-file discovery.
The v3 schema includes the glossary roadmap's [scope and inheritance model](glossary-stages.md#configuration-scope--resolved),
[typed handoff](glossary-stages.md#list-inputs-and-configuration-handoff--resolved),
and [optional stage identity](glossary-stages.md#stage-identity-and-attribution--resolved).
Glossary definitions use native composition, [default underlay sources](glossary-stages.md#default-sources-and-explicit-configuration--resolved),
and [collection-scoped identity](glossary-stages.md#entry-identity--resolved).
Pipeline stages remain an ordinary ordered list, including repetitions and
explicit empty-pipeline behavior. The application supplies domain resolution
rules within the native lifecycle, with no second runtime defaulting pass.
## Documentation and Acceptance

51
docs/roadmap/glossary-stages.md
View File

@@ -9,7 +9,8 @@ entry content fields, and optional stage IDs. Active glossary vocabulary takes
precedence over overlapping protection. Empty collections are permitted, with
Audita preflight rejecting empty glossary stages. Design decisions are resolved;
implementation is pending. The
[master roadmap](library-adoption.md) owns sequencing and release completion.
[master roadmap](library-adoption.md) owns release completion; the
[implementation plan](implementation.md) owns sequencing.
## Baseline and Target
@@ -401,8 +402,7 @@ sources, resolve configuration, restore defaults, or change stage inheritance.
Keep the nonempty glossary-stage check in Audita preflight rather than ConfigKit's
configuration-validation callbacks.
Implement this phase in an expressly named `internal/framework/preflight`
package, established during CommandKit adoption and extended by this feature.
The shared `internal/framework/preflight` package owns this phase.
Accept fully resolved configuration and the domain inputs needed for
readiness checks through ordinary Go functions and concrete inputs. Return
errors identifying the affected stage and reason; CLI presentation remains with
@@ -817,44 +817,15 @@ exceptions need a domain rationale. Link to the durable policy rather than copy
the field inventory into multiple developer documents. This documentation work
is part of feature acceptance, not an optional follow-up.
## Sequencing and Work Outline
## Integrated Target
Implement after ConfigKit, PromptKit, CommandKit, and ReleaseKit adoption, and
before final release validation and preparation. This lets the feature use the
adopted configuration and CLI conventions and avoids adapting it twice. Keep the
requirement visible during library design without expanding those migrations
into feature implementation. CommandKit adoption establishes the common preflight
package and output preparation; this feature adds glossary-specific readiness
checks to that phase.
1. Apply named collection selection, default file/directory underlay imports,
recursive placement, and the extensible entry content contract. Apply native
CLI list conventions and the selected stage identity and attribution rules.
Preserve the selected scope, clearing, CLI precedence, and fallback semantics
in version 3.
2. Adopt ConfigKit loading for glossary configuration. Register the selected
collection identities, validate configuration contracts, and deliver final typed
definitions and selections before transcript processing. Remove the redundant
standalone YAML parser and local composition path.
3. Extend `internal/framework/preflight`, established during CommandKit adoption,
with the glossary-stage readiness check after configuration handoff. Reject any
glossary stage whose selected collections supply no entries before output
resource preparation or stage execution. Return readiness errors for CLI
presentation, permit empty collection definitions, and preserve inspection
access to them.
4. Derive rich LLM inputs, deduplicated protection vocabulary, and glossary-stage
exemptions from resolved configuration. Route the appropriate views through
proposal generation and validators without mutating configuration or other
stages. Preserve source attribution for diagnostics and inspection.
5. Verify native composition and the domain behavior together. Account for all
consumed configuration sources in input handling and output-collision
protection. Make repeated stages and their selected collections understandable
in inspection, diagnostics, and reports using optional IDs alongside position
and module identity.
6. Update configuration, CLI, input contracts, pipeline documentation, maintained
examples, and hard-cutover guidance as implementation lands. Complete the ADR,
durable policy, and future-setting classification guidance above. No runtime
compatibility layer for the old glossary file format is required.
The glossary feature uses the adopted ConfigKit and CommandKit conventions and
the shared preflight/output-session boundary. It replaces the standalone glossary
input and parsing path with typed, composed configuration. Runtime consumers
receive derived per-stage views from that handoff; reports identify the stage
and configuration inspection explains its effective selections and origins.
Consumed glossary sources participate in output-collision protection. Maintained
examples and hard-cutover guidance describe the new configuration contract.
## Acceptance Direction

577
docs/roadmap/implementation.md Normal file
View File

@@ -0,0 +1,577 @@
# Next Major Release Implementation Plan
**Status:** Ready for the implementation sprint. This document assigns work;
it does not describe implemented behavior or authorize a release.
Execute the numbered stages in order, one focused assignment per Luna prompt.
Read the named roadmap sections and relevant current contracts before editing.
Use [development guidance](../development.md) and the applicable policies,
especially [agent discipline](../policy/agents.md), [architecture](../policy/architecture.md),
[testing](../policy/testing.md), [documentation](../policy/documentation.md),
[attribution](../policy/oss.md), and [release](../policy/release.md).
The [master roadmap](library-adoption.md) owns the target, selected revisions,
and release requirements. Its child roadmaps own configuration, LLM, CLI, and
glossary behavior. Start from the current implementation: old-path ConfigKit
v0.7.1, PromptKit v0.14.0, ReleaseKit v0.4.1, a standard-library CLI, and one
separately parsed glossary per run. The target is a single hard cutover. Define
final interfaces as work reaches them. Unconverted callers and tests may fail
between stages; do not add transitional parsers, aliases, adapters between
old/new library types, or build-only stubs. Do not make each stage pass the full
suite or require an intermediate release or commit merely to continue. Record
remaining dependent edits at each handoff; run focused checks when their owning
path is available and complete validation at Stage 15.
Follow the selected library behavior where the roadmaps delegate ownership.
Do not turn a useful implementation choice into a new public guarantee or test
requirement. Keep the transcript processing and validator policies outside the
changes expressly selected here. Use existing upstream APIs; if a concrete gap
prevents an agreed result, record the smallest reproducer and affected contract
before proposing an upstream request or local alternative. That is not a new
approval gate for routine work. Use controlled providers for tests. Keep
unrelated [deferred features](future.md) outside the sprint.
## Stage 1: Establish the toolchain and ReleaseKit integration
Read the [selected modules](library-adoption.md#baseline-and-selected-dependency-set)
and [ReleaseKit contract](library-adoption.md#releasekit-adoption-work). Work in
`go.mod`, `go.sum`, `scripts/release.sh`, `.woodpecker/release.yml`,
`releasekit.json`, and the version wiring in `internal/cli`.
1. Set the source minimum to Go 1.27.0. Use Go 1.27.3 for the validated release
toolchain, matching the review. Select its published Bookworm image for
Woodpecker; if unavailable, choose an available Go 1.27 patch and use it
consistently in the image, runbook, validation, and runtime attribution.
Include the C compiler and cgo prerequisites for the selected race check.
2. Select the exact versions from the master roadmap: ConfigKit v1.1.0,
PromptKit v0.20.0, CommandKit/ckconfig/ckprompt v0.6.0, and ReleaseKit v0.9.0,
all under `go.maximumdirect.net`. Move the ReleaseKit runtime `buildinfo`
import and tool registration together. Move ConfigKit/PromptKit consumers in
Stages 2–4. Retire old requirements after their imports disappear; defer
final `go mod tidy` until all real consumers are wired. Prepare dependencies
with `GOWORK=off` and the selected local toolchain. Do not change Audita's
own module major suffix independently of selecting its actual release tag.
3. Adapt the v0.9.0 launcher and tag-delivery recipe linked by the master.
Invoke the full `go.maximumdirect.net/releasekit/cmd/releasekit` tool path
with host GOOS/GOARCH. Preserve tagged-source bootstrap outside the worktree,
Woodpecker variable escaping, annotated-tag peeling, event commit verification,
and `ci-deliver --prepared` with the verified commit. Preserve the actual
remote, product, secret mapping, and Linux amd64/arm64 targets; add
`delivery.forge: "gitea"`. Do not reintroduce comparison with the raw tag SHA.
4. Select the master's native validator settings exactly. Remove generic local
bootstrap/launcher tests covered upstream; retain Audita-specific checks for
product, targets, destination, and version injection. Source publication is
one `publish` after the candidate is pushed to main; `check` is diagnostic.
Keep recovery native and delivery asynchronous. No actual publication here.
Handoff: selected module/tool and workflow wiring, with any not-yet-migrated Go
callers identified. The assembled version and release checks belong to Stage 15.
## Stage 2: Define the v3 application schema and native loader
Read the [ConfigKit outline](configkit.md) and glossary
[scope inventory](glossary-stages.md#configuration-scope--resolved). Own
`internal/core/config` and the application-loading portion of
`internal/cli/config_input.go`. Do not implement glossary projection or stage
execution in this stage.
1. Migrate to `go.maximumdirect.net/configkit` and its recorded resolution API.
Build one typed `LoadLayered` path returning the native result (or native
load error), using `File` for an explicitly supplied path and optional
`SearchConfig` with `Searches(WorkingDirectory(), UserConfigDirectory(),
UnixSystemDirectories())` otherwise. Use application name `audita`. An
explicit empty/invalid selection fails; a selected file's failure does not
resume search. Enable imports on operator sources. Leave the actual main
absent on exhaustion and use result source evidence, not guessed paths.
2. Use typed defaults with application version 3 and the main-only version
rule. Reject supplied obsolete, null, or invalid versions with migration
guidance; when no header is supplied, decode against v3 defaults and schema.
Do not require headers on fragments or construct a pretend main source.
Supply explicit `OverlayFilesystem` rooted at the invocation directory for
a selected overlay (see [Open Questions](#open-questions)). Do not substitute
the overlay base for the main file's native relative-import context.
3. Define the final shape now: global preprocessing/chunking, output,
reporting, and diagnostic-directory settings; root defaults for eligible
stage settings; ordered `pipeline.stages` with `module`, optional `id`,
and stage overrides. Use the existing `thresholds.<module>` root defaults
with a stage-local `confidence_threshold`. Keep field-level `llm`,
`validation`, and `context` groups, and nullable selectors/list values where
the glossary roadmap allows clearing. Use native metadata to distinguish
absent from explicit null or empty. Keep the current default ordered module
sequence expressed as stage records and the existing numeric domain defaults
where the roadmap leaves them unchanged. Do not auto-select profiles or
collections. Stage 10 completes the effective settings callback.
4. Remove `profiles_dir`, the app-owned `backends`/LLM credential configuration,
and `diagnostics.debug` from the new schema. Retain the diagnostic directory
setting; capture comes from the shared CLI boolean. Keep `pipeline.stages`
an ordinary ordered list, including repeated modules and explicit `[]`.
Keep no v2 decoder. Configure shapes for Stage 9 glossary definitions rather
than preserving the old standalone glossary format in the final schema.
5. Apply explicit root overrides through ConfigKit; source composition and
native inheritance/decoding happen first. Keep schema/configuration checks
in the loader, command readiness in preflight, and resource loading out of
configuration validation. Do not reject inspection for lack of a processing
profile, credentials, or populated glossary input.
Evidence: native result/failure and source metadata cover discovery, exhaustion,
selected file errors, imports, overlays, v3 defaults, and changed override order.
Exercise final v3 examples after the glossary fields are connected.
## Stage 3: Build the shared PromptKit engine and account for its sources
Use the [PromptKit outline](promptkit.md), especially its [automatic source contract](promptkit.md#automatic-prompt-sources--resolved).
Own engine assembly in `internal/framework/llm/runtime.go`,
`source_paths.go`, and embedded assets/registry under `internal/prompts`.
1. Build the engine on the new ConfigKit types. Retain PromptKit's default-on
catalog. Convert all seven embedded prompts to identified list records in
`collections.audita`, with calls using `audita/<local-id>`. Preserve text,
templates, schema references, and resource files. Remove version selection
and descriptive prompt version metadata, without changing response-schema
versions. Keep the embedded schemas supplied through `WithSchemaFS`.
2. Load embedded prompt inputs in their own filesystem underlay. Add exactly
one higher-priority operator underlay containing native optional imports of
`prompts.yml` and recursive `prompts/` (`*.yml` and `*.yaml`), with imports
enabled and host root/base set to the invocation directory. Both sources
compose as strict peers. The app's `--config`, absence of a main file, and
overlay selection do not change the import base. Use one acquisition path
for all engine consumers. Do not pre-read/import these files in Audita,
manufacture filenames as IDs, or add an operator-source selector.
3. Use native root resources, collection IDs, sibling inheritance, and whole
same-ID replacement. Remove the generated backend main layer and the
curated profile projection. Preserve helpful classification of bad shipped
assets versus operator source failures using native errors/source evidence
and the existing embedded-only diagnostic where needed. Never execute a
diagnostic fallback engine in place of a failed requested configuration.
4. From captured inspection, collect consumed host source paths and effective
message `content_file` paths for collision checking. Adapt to list-index
coordinates for root and collection resources. Follow effective origins to
the declaring host source and its relative path; handle inherited/moved
evidence and exclude embedded/synthetic sources from host-file collisions.
Reuse native origin evidence and the existing path comparison machinery;
do not rediscover the directory or reopen definitions to reconstruct origins.
Evidence: optional absence, both inputs, nested imports and source-relative
messages, peer conflicts, whole replacement, untouched defaults, and edit/rerun
capture. Exercise external config elsewhere and absent main with the same CWD.
## Stage 4: Adapt native requests, role clients, and artifact redaction
Own `internal/framework/llm`, `structuredoutput`, and request construction in
`proposal_generation` and `validators`. Use the [runtime ownership contract](promptkit.md#backend-and-credential-ownership--resolved)
and [stage budget inventory](glossary-stages.md#configuration-scope--resolved).
1. Replace profile-derived local target plumbing with role clients configured
by explicit profile ID and effective per-operation budgets. Construct clients
against the same captured engine; a caller may select different role clients
per stage. Bind `RunRequest.TransientRetries`, per-call schema and repair
settings, and the logical operation context deadline. Use `PrepareExecution`
and `RunPrepared` on the same handle, discarding unused handles. Retain domain
response validation, observations, and error classification, including
recoverable exhausted operations, fatal setup failures, and parent cancellation.
2. Remove Audita registry/endpoint equality checks, direct key injection,
per-backend secret validation, finite-cap defaults, and local target synthesis.
Native backend/profile fields and null semantics govern execution. Backend
admission settings are engine configuration, not per-request overrides.
The selected ckprompt config scope has no generic `--set` forwarding; do
not add a CLI concurrency flag or a second limiter to supply it.
3. Extract the small shared request helpers needed for prompt IDs, shared
instruction variables, and domain response contracts. Keep the actual
transcript/candidate builders owned by their processing components. Remove
prompt version from logical requests, snapshots, and evidence. Carry native
completed request details only where they have meaning; never relabel
resource inspection as a completed execution target.
4. Preserve artifact/error redaction with native configuration redaction and
Audita's own diagnostic boundary. Replace `ConfiguredSecrets`' dependence
on the deleted backend map: use the selected library's public credential
source metadata, including prepared request information, to mask values from
relevant environment references when required by Audita's artifacts. Reading
a value solely for masking must not choose the credential or reject an
unavailable key during inspection. Keep native prepared/inspection reports
free of resolved keys. Exercise provider errors that echo a synthetic key;
address an actual missing public boundary upstream before adding substantial
credential plumbing. Do not scan or dump the entire environment.
Evidence: local controlled requests prove actual targets, request-specific
budgets, null/zero behavior, credential precedence, shared admission, and
secret-safe failure evidence. Leave stage client selection to Stage 12.
## Stage 5: Install CommandKit routing and native configuration/resource scopes
Read [CommandKit operator experience](commandkit.md#agreed-operator-experience)
and the released v0.6.0 guide linked there. Replace the routing/parser/inspection
parts of `internal/cli`; keep `cmd/audita` responsible for process lifetime and
streams, not the command declarations.
1. Build the app with CommandKit typed declarations, native help/version and
completion, and ReleaseKit's version accessor as application identity.
Preserve the library outcome status, including native comparison status 3.
Help/version do not load application or engine data. Keep a typed `process`
declaration and wire its final handler in Stage 8. Do not preserve the old
parser as a fallback. Keep `--config`, `--overlay`, and supported application
settings under shared typed loaders with explicit supplied-state handling.
2. Install the `app` scope with `ckconfig.FromConfigKit` or its supported suite
adapter over Stage 2's native result/error. Forward standard `--set` and
comparison-side assignments for this scope only where the loader applies
them. Respect each side's independent selections; no global cached load
across comparison sides. Use native effective values, failure evidence,
path discovery, explanation, sources, comparison, and redaction.
3. Install `ckprompt.ConfigScope(loadEngine)` and the native resource and
requirements callbacks from `ckprompt.FromEngine`. Use shared invocation
acquisition for a selected engine and the Stage 3 loader for every call path.
Install the full standard inventories, namespace selection, scopes, and
inspection features; no duplicate `config print-effective` or custom
profile-summary command. Use the released declarations and their scoped
aliases rather than implementing a separate routing convention.
Evidence: native config and resource commands use the intended scope and
source selection, including failure evidence and no-main discovery. Check
help/version without filesystem/provider setup. Avoid requiring process readiness
for inspection or overriding native grammar or status behavior.
## Stage 6: Enable standard PromptKit request and smoke commands
Own the remaining `internal/cli` adapters. Use
[the resolved command scope](commandkit.md#request-preview-validation-and-smoke-commands--resolved)
and `WithRequestPreparation`, `WithRequestValidation`, and `WithSmokeTesting`
from ckprompt v0.6.0. Install all capabilities with the Stage 5 declarations.
1. Forward the released native requests, overrides, namespaces, formats, and
outcomes. Use the same engine acquisition as processing. For Audita-owned
prompt IDs, supply shared instruction variables from the Stage 4 helper
only where absent; leave explicit values and generic requests intact.
Use native profile selection, not a guessed stage or automatic role/profile
default. Use native prompt output definitions for generic requests. Document
the inputs needed to preview the maintained Audita fixtures; where an adapter
adds a domain contract, call the same request helper as processing.
2. Validate and preview supplied fixtures without inference, including a
validator candidate fixture. Keep preparation distinct from resource
inspection. Install the entire upstream smoke surface, including aggregate
behavior; smoke runs only on explicit invocation. Do not add startup probes,
custom output shaping, or acceptance requiring a live provider.
Evidence: assembled CLI wiring uses shared operator replacements across
inspection, preview, validation, and controlled smoke. Verify native output and
status handoff without duplicating the upstream command grammar suite.
## Stage 7: Prepare and finalize output resources
Own `internal/core/diagnostics/output_session.go`, file/path helpers, and
focused tests. Use the [output preparation](commandkit.md#output-resource-preparation-during-preflight--resolved)
and [failure](commandkit.md#output-failure-behavior--resolved) contracts.
1. Separate pure destination selection/collision validation from resource
preparation. Keep inactive report/debug destinations unprobed. Protect
consumed app/engine files, effective message files, and transcript input
against destructive output collisions. Allow intentional in-place final
transcript replacement. Keep the chosen Audita artifact locations and
destination selection rules where the roadmap does not change them.
2. Prepare an open sibling temporary file for a regular transcript output;
keep the final destination untouched until successful delivery. Publish by
closing and replacing after successful writes, returning any required
write/close/replace failure. Keep special pipe/device destinations direct
and unopened until delivery (including `/dev/null`); stdout uses the caller's
writer, which the session does not close. Do not add new parent-directory
creation, special-file restrictions, or filesystem durability guarantees.
3. Initialize enabled ordinary reports before processing, retaining per-file
`in_progress` publication. Keep debug directory and initial artifact
preparation optional and subsequent artifact creation on demand. On failure
or cancellation clean unpublished temporary resources and owned handles;
retain published files/evidence. Return optional debug problems for redacted
warning presentation rather than marking the run failed solely for that loss.
4. Preserve the primary failure when final reporting or cleanup also fails.
Attempt remaining required reports and failed-status finalization as supported
by the output contract. Do not remove an already published transcript,
repeat model calls, or add a transaction spanning the output bundle.
Evidence: required preparation fails before execution, regular file contents
survive preparation and abort, special files are deferred, and late failures
retain already published output and primary failure details.
## Stage 8: Wire processing, common preflight, and reporting modes
Own `internal/cli/process.go` and the new `internal/framework/preflight`.
Use the [named preflight boundary](glossary-stages.md#empty-collections-and-audita-preflight--resolved)
and the [CommandKit reporting decisions](commandkit.md#debug-reporting-and-artifact-capture--resolved).
1. Bind `process` with typed inputs, one transcript operand, `--output`, and
explicitly supplied root overrides for retained settings. Use the shared
`BoolFlag` named `debug` with false default; preserve its boolean for capture
independently of `Invocation.ReportingMode()`. Do not parse raw argv or
map quiet/verbose to the capture bit. Keep `--work-dir` a directory selection
only. Do not re-declare `--glossary` or `--modules` when replacing the parser;
Stage 10 supplies glossary selection inputs and pipeline order lives in v3 YAML.
2. Resolve app settings and engine inputs and acquire transcript data using the
owning loaders. Use the final runner/preflight interfaces, with the
stage-specific input additions in Stages 9–12. Preflight takes resolved
inputs and ordinary Go dependencies; no CLI, provider transport, config
reload, or generic check framework. Check all invocation/readiness conditions
and active collisions before output preparation. Have it coordinate the
output session from Stage 7; the session owns filesystem resources.
3. Before creating artifacts or starting model work, reject effective quiet plus
stdout (including omitted/empty `--output`) with a usage explanation and a
file or `/dev/null` remedy. Use the actual resolved mode, including ordering
and aliases. Help/inspection do not take this processing path. Validate only
selected processing requirements; native credential availability remains a
request-time concern, not an eager all-backend check.
4. Dispatch after required preparation, then finalize required outputs and
return a native CommandKit outcome. Use the supplied raw output writer for
transcript bytes. Emit the summary and created locations as Info/deferred
Info only after successful required delivery; ordinary and quiet modes hide
it. Send redacted optional debug failures as native warnings. Keep stream
write failures under CommandKit's native outcome handling; domain model
recoveries and work-unit errors do not become automatic command failures.
Evidence: actual process integration proves quiet/verbose/debug behavior,
required failure versus optional debug loss, and stdout isolation. Reuse the
roadmap's selected flag combinations; avoid retesting the full upstream parser.
## Stage 9: Compose and validate native glossary definitions
Own the glossary definition types and application load inputs. Read
[glossary ownership and named collections](glossary-stages.md#glossary-configuration-ownership--resolved)
through its default-source and entry-contract sections.
1. Define `glossary_collections` as a typed mapping with ordered `entries`.
Register `SequenceIdentityMatching` for the collection mapping wildcard and
`entries` destination, with literal `id` identity. Use typed known entry
fields and a native inline string-keyed map for extension values. Enforce
the selected entry fields without slug restrictions, global ID uniqueness,
or validation of arbitrary extension contents.
2. Add one application underlay with optional native `glossary.yml` and
recursive `glossary/` imports mounted at `glossary_collections`. Set host
base/root to the invocation directory, independent of discovered/explicit
app main. Preserve peer conflicts, nested relative imports and placement,
source attribution, and native cross-tier whole-record upsert. Do not use
filename identity, a private walker, or infer that main `imports: []`
cancels the application underlay. Use the separate PromptKit underlay for
prompt resources, not this application glossary tier.
3. Validate definition contracts with ConfigKit and allow empty definitions.
Retain complete typed entries for inspection, including extension data.
Capture consumed glossary source paths through the application result for
Stage 8's collision checks. Remove the legacy glossary input/parser path
as consumers move to the typed handoff in Stages 10–12; no parallel loader.
Evidence: representative native peers, layering, collection-scoped identities,
recursion, source placement, extension values, and optional absence with both
explicit and absent main configuration. Test integration, not native grammar again.
## Stage 10: Resolve stage settings and native CLI selection inputs
Own `internal/core/config` resolution and the matching process flag bindings.
Use [stage scope](glossary-stages.md#configuration-scope--resolved),
[clearing](glossary-stages.md#compound-values-and-explicit-clearing--resolved), and
[CLI precedence](glossary-stages.md#cli-overrides-and-stage-precedence--resolved).
1. In `Definition.Resolve`, use `IsExplicit` and `EntryInfo` at real key/index
paths, after root CLI assignment. Derive omitted root protection from a
detached root glossary list with a recorded dependency. Copy the effective
root values into each omitted eligible stage field independently, using
`configkit.Default` and root dependencies. Preserve explicit false, zero,
empty description, `[]`, and null according to the field contract. A partial
group contributes only its children; reject group nulls natively.
2. Apply validation-profile fallback only after combining root and stage values.
Preserve explicit root validation selections, stage replacement, and stage
null clearing. Assign the effective stage proposal profile when no validation
selection remains; record the dependency with `RecordDerivedDefault` for
an explicit null. Do not mistake a derived fallback for an explicit root value.
Record at actual list-field paths, not the whole stage merely to cover a
mutation. Copy mutable values so stages do not share their settings storage.
3. Validate known modules, known selected collection names, effective per-field
settings, and supplied IDs (nonempty, exact, unique; absence valid) through
ConfigKit. Do not register the stage list as an identified collection. Do
not make a root validation selection empty string a synonym for null. Preserve
nullable selectors in the handoff; runtime treats a nil list as empty and
never restores a default. Leave glossary nonempty and required processing
profile readiness to preflight.
4. Bind `--glossaries` and `--protected-terms` as single typed list values using
CommandKit `ValueFlag` and `ParseCLIJSON`, accepting an array of names or
`null`. Send one ConfigKit override per supplied root field; `[]` clears
and omission contributes no override. Use the same native JSON semantics
as ckconfig `--set`. Keep other existing root setting flags whose fields
survive, with CommandKit supplied-state tracking. Remove `--glossary` and
`--modules`; set pipeline order in YAML. Do not implement indexed/ID-targeted
CLI edits or introduce another list-clearing grammar.
Evidence: native inspection shows copied root dependencies and explicit clears;
CLI root changes affect only inheriting stage fields. Check the roadmap's
validation-profile fallback cases and meaningful explicit-value distinctions.
## Stage 11: Derive stage vocabulary and adapt its consumers
Own the glossary-domain projection and the consumers in `internal/modules`,
`internal/validators`, and `internal/framework/proposals`. Use the
[derived views](glossary-stages.md#derived-runtime-representations--resolved)
and [ordering and protection](glossary-stages.md#runtime-vocabulary-and-ordering--resolved)
contracts.
1. Traverse selected collections then their resolved entries in order. Build
rich prompt data from known fields only, retaining first occurrence per
`(collection, id)` and all distinct entries. Do not forward extension
fields or collapse entries by display name. Derive matching vocabulary from
names, aliases, and plurals using existing matcher rules. Deduplicate
spellings while retaining contributing identities for domain checks.
2. Derive protection independently from the selected `protected_terms`. For a
glossary-correction stage subtract active recognized spellings, even when
another protected entry contributes that same spelling. Preserve unrelated
aliases and plurals of non-active entries. Keep configured selections and
entries intact; other stages get independently derived views. Preserve
ambiguous-alias handling, protected-name repetition policy, and other
existing validation business logic outside the selected exemption.
3. Pass the appropriate rich and protection views to module prompts, local
validation, and apply-time protection. Inspect downstream checks so none
reconstructs full protection from the former combined glossary. Non-glossary
modules use their selected context and full protection; empty protection
does not disable other validators. Reuse narrow consumer representations;
no generic runtime glossary merge engine.
Evidence: shared-spelling exemption plus unaffected spellings, ordered rich
input with separate identities, and no mutation/leakage between stage views.
Use controlled candidates for both permitted edits and still-protected cases.
## Stage 12: Execute the ordered effective stages and extend preflight
Own runner/contracts and the processing handoff. Connect Stages 4, 8, 10, and
11 in `internal/framework/runner`, `contracts`, `preflight`, and `internal/cli`.
1. Convert the fully resolved typed list to ordered run specs carrying effective
settings and vocabulary, module key, position, and optional ID. Preserve
separate execution identity even for repeated modules. Create the stage's
role clients from the shared engine and selected effective profiles/budgets;
pass its own batching budget, threshold, context, and views to consumers.
Do not rebuild/mutate backend settings per stage or re-resolve configuration
during execution. Remove the old single-glossary and global role/budget wiring.
2. Extend preflight to check every selected glossary-correction stage for at
least one effective rich entry, including later stages. Keep empty definitions
and inspection valid; an empty protection set is valid. Report stage position,
module, optional ID, and selected collection names when unready. Check needed
selected roles without synthetic requests or provider calls; a deliberately
empty pipeline needs no processing model selection. Finish all readiness and
collision checks before preparing outputs or dispatching work.
3. Normalize and chunk once for the invocation. Run stages in order on the
preceding stage's resulting transcript with fixed sections and deterministic
proposal/apply/report order. Keep the existing fatal cancellation/join and
recoverable local failure behavior, including normalized output when every
model work unit fails recoverably. Preserve domain schemas, validation, and
meaningful partial success; no rechunking or parallel stage traversal.
Evidence: party/spell/grammar controlled workflow, with the second stage seeing
prior edits and independent vocabulary/role settings. Verify late empty-stage
failure before outputs/model work and a valid no-stage normalization run.
## Stage 13: Carry stage identity through ordinary and debug evidence
Own `internal/framework/outcomes`, `processreport`, `structuredoutput` call
context, and `internal/core/reporting`. Use the [stage attribution contract](glossary-stages.md#stage-identity-and-attribution--resolved).
1. Carry stage index/module and optional `stage_id` through work units, error and
recovery records, correction ledger, LLM call evidence, and debug snapshots.
Keep zero-based `stage_index` in machine records; show one-based position in
human labels. Use the operator ID for labels when present, with position and
module available, otherwise identify by position/module. Keep internal and
artifact path identities based on safe generated stage coordinates; do not
treat arbitrary valid user IDs as paths or require a slug format.
2. Preserve the three ordinary files, status semantics, counts, and matrices in
execution order. Add optional attribution fields to the existing schema rather
than create a new reporting system. Escape labels for their output format.
Keep errors/recoveries distinct from CommandKit reporter categories and debug
evidence. Do not add raw prompts, provider causes, or credentials to ordinary
reports. Ensure finalization and summary use the same run facts.
Evidence: named/unnamed/repeated/reordered stages can be distinguished in real
reports and debug artifacts without changing stage order or collapsing records.
Verify existing partial-success and unavailable-candidate evidence survives.
## Stage 14: Finish the cutover documentation, examples, and attribution
Update canonical owners as behavior lands; use this stage to reconcile them.
Follow the [documentation policy](../policy/documentation.md) and glossary
[durable record](glossary-stages.md#durable-decision-record).
1. Update `docs/config.md`, `docs/cli.md`, `docs/operations.md`, affected
integration contracts and internal docs, `docs/development.md`, and README.
Explain v3 application discovery, native resource sources, role/stage scope,
preflight/output lifecycle, shared debug and quiet behavior, and the operator
cutover in `docs/migrations/v3.md`. Link to the adopted upstream CLI reference
for standard commands rather than duplicating their syntax, caveats, or
provider warnings. Describe Audita-specific inputs and effects locally.
2. Reconcile architecture policy with native resource/credential/admission and
CLI ownership, recorded config resolution, and the preflight boundary.
Add `docs/adr/0002-glossary-configuration-and-preflight.md` in Nygard format
for glossary ownership, typed handoff, and output-session coordination.
Index it; do not rewrite
the accepted ReleaseKit ADR. Retain ordinary domain guarantees selected by
the roadmaps, with no new compatibility or performance promises.
3. Replace retired examples with maintained v3 projects: a minimal local run,
a service/profile/overlay example, the embedded-prompt edit-and-rerun flow,
a validator preview fixture, and two campaigns consuming a common glossary
library. Run examples from the documented directory so automatic inputs and
overlay context are accurate. Keep example values synthetic and cover their
integration with controlled providers. Remove old backend/glossary layouts
and obsolete parser-only tests, preserving substantive domain regressions.
4. Align `docs/release.md` and release policy with the selected v0.9.0 workflow,
validators and rationale, supported platform/toolchain choices, and native
recovery. Update `docs/oss/attribution.md` for exact selected sources,
incorporated material and toolchain dependencies; retire old catalog notices
when no longer incorporated. Reuse applicable standard license texts, not
upstream policy inventories. Preserve existing release tags and notes.
Evidence: all examples, canonical contracts, ADR, and notices describe the
assembled target. No publication, new release note, or version tag is required
in the real repository during this sprint.
## Stage 15: Verify the assembled target and hand it off
1. Run `go mod tidy` under the selected toolchain with `GOWORK=off`; inspect the
selected module graph, imports, tool registrations, and attribution together.
Confirm no old library identities, committed workspace files, or filesystem
replacements remain. Review removal of superseded loaders, parser, registry,
curated summary, and release plumbing. Update or remove assertions protecting
obsolete behavior; do not compensate with a deletion quota or blanket tests.
2. Finish any focused integration cases from the earlier stages. Use real loaders
and controlled transports; concentrate on native integration, stage isolation,
source safety, failure handling, and operator-visible behavior. Check link and
example references. Reuse already completed checks on the same final tree.
3. Use the adopted ReleaseKit `check` for assembled validation. It needs a clean
committed candidate on `main` and a matching checked-in release note. If the
actual release version is not selected, make a disposable copy on `main`,
add a temporary matching note for an unused validation version compatible
with the module path, and commit that copy. Run `scripts/release.sh check
VERSION` there. Keep this fixture outside the Audita worktree. This check
supplies the selected offline race suite, vet, formatting, Markdown and
module checks, Linux amd64/arm64 builds, and native version identity; do
not require a duplicate full run on the same source solely for handoff.
4. Exercise Audita's tag-delivery wiring with a disposable annotated tag and
controlled destination/fixtures: check the clone/event commit, native tool
bootstrap and `ci-deliver` handoff, and product/target/asset settings. Use
upstream delivery coverage rather than recreating generic forge tests. Use
synthetic authentication for local fixtures; do not use production delivery
credentials, push a tag, or publish to the hosted release service.
Report the evidence and any live-delivery limit accurately. Neither hosted
availability nor CI completion is a new release gate.
5. Check completion against each child roadmap and the master's target. Report
implementation checks, remaining upstream issues if any, and the resulting
workspace/commit state under agent policy. Release preparation, including
actual major tag/module-path selection, checked-in release notes, and source
publication, remains separate. Do not claim implementation completion on
the basis of the earlier library probes or any unresolved required behavior.
## Open Questions
### Which directory should contain selected overlays?
The roadmap selects native overlays, but does not give `LoadLayered` its
required explicit overlay context. Native automatic discovery selects the main
file during loading, so its path cannot be used to choose that context in advance.
- **Recommendation, used by Stage 2:** use the invocation directory as the
overlay root (`./overlays/<name>.yml`), with or without a main file. This is
consistent with the selected automatic glossary and PromptKit contexts and
permits a single native load. Main-file imports still use their own context.
- **Alternative:** expose an explicit overlay-root selector, defaulting to the
invocation directory. This supports centralized overlays independent of the
invocation directory at the cost of another selection to wire through all
commands and comparison sides. If main-file-relative overlays themselves are
required, seek a native layered-loading facility for that behavior before
adding a second discovery/load pass. The old main-relative behavior carries
no compatibility requirement for this release.

124
docs/roadmap/library-adoption.md
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

90
docs/roadmap/promptkit.md
View File

@@ -4,7 +4,8 @@
**Status:** Adoption direction and automatic operator-source selection resolved;
implementation remains pending. Follow the [master roadmap](library-adoption.md)
for shared adoption principles, dependency identities, and sequencing.
for shared adoption principles and dependency identities, and the
[implementation plan](implementation.md) for sequencing.
## Baseline and Target
@@ -37,7 +38,7 @@ execution profile or make provider calls during construction.
### Backend Concurrency Ownership — Resolved
Adopt PromptKit's native per-backend concurrency behavior, including backend
defaults and supported configuration and CLI overrides. The purpose is to keep
defaults and native configuration. The purpose is to keep
requests within the concurrency a backend can accommodate; no separate Audita
domain requirement has been identified for an additional limit.
@@ -48,10 +49,10 @@ otherwise valid PromptKit configuration. Use the shared PromptKit engine so
proposal and validation work for the same backend share its admission control.
Audita still owns cancellation and deterministic processing around model calls.
Verify the exact upstream override APIs while wiring the adopted configuration
and CLI integrations. Update the architecture policy's finite-admission wording,
runtime documentation, examples, and tests with implementation. Remove superseded
behavior directly in the major release, with hard-cutover guidance.
The selected PromptKit configuration scope does not forward ConfigKit CLI
overrides, and request overrides do not set concurrency. Configure limits on
native backend resources. Architecture policy, runtime documentation, examples,
and tests describe the adopted ownership and hard cutover.
### Backend and Credential Ownership — Resolved
@@ -192,61 +193,32 @@ resolver. Include the retired view and its standard replacements in the
hard-cutover guidance. The [CommandKit outline](commandkit.md) owns the operator
surface and request-preview integration work.
### Migration Work
### Target Request and Source Boundaries
1. Move to `go.maximumdirect.net/promptkit` together with ConfigKit's new types.
Remove the old external catalog dependencies when no longer incorporated;
retain PromptKit's built-in catalog rather than disabling it.
2. Convert root and collection backends, profiles, and prompts to identified lists
with explicit `id` fields. Use sibling `extends: {id: parent}` and complete
same-ID replacement records. Typed source builders use ordered slices.
Preserve provider settings deliberately: partial same-ID replacements no
longer merge fields. Use exact native collection references where collections
are selected; mounting does not rewrite stored references.
3. Convert the seven embedded prompts into the `audita` collection and update
maintained operator examples/fixtures for the resolved replacement workflow.
Implement automatic operator imports above the embedded underlay through the
shared engine loader, including explicit host and embedded filesystem contexts.
Remove prompt version selectors and descriptive `PromptVersion` metadata from
requests, registries, inspection, and diagnostics. Response-schema versions
are separate and need not change. Keep domain instructions and per-call schemas;
this adoption is not a prompt-quality rewrite. Shared instruction variables
remain available to templates, while native operator overrides control their
inclusion. Domain validation remains enforced after model responses.
4. Adapt resource inspection to optional profile fields and separate backend
inspection. These describe resources, not completed requests. Use real
`PrepareExecution` details and `RunPrepared` for execution of the same captured
request. Remove the curated profile view and its supporting projection code;
do not duplicate PromptKit's full resolver or construct synthetic requests
merely to reproduce that summary. Inspect bundled and unselected partial
resources without requiring them to be runnable.
5. Implement the resolved backend and credential ownership decision above.
Replace application backend/credential configuration with native resources
and document the hard cutover. Preserve secret-safe diagnostics using the
library's public boundaries and Audita's domain artifact redaction; evaluate
actual gaps with synthetic keys.
6. Review presence semantics field by field. Null endpoint, credential-source,
and whole provider map now allow backend defaults; explicit empty strings
clear endpoint/credential sources. Null does not suppress the entire backend
provider map. Sampling fields have distinct semantics. Avoid blanket null or
zero conversion and document intentional request changes.
7. Update captured-source accounting for list indexes and collection prefixes,
including inherited/moved content-file origins. Preserve output-collision
protection for consumed host documents, including automatic imports, and
effective message files. Array positions are addresses, not durable resource
identities.
8. Keep self-contained embedded response schemas. The new schema rule does not
require a bundler for Audita's current schemas. Check custom artifact-reader
ownership only where such a reader is actually used. Preserve native retries,
structural repair, cancellation, deadlines, and shared engine admission while
retaining Audita's domain reconciliation and partial-success outcomes.
PromptKit resource sources use identified lists, native sibling `extends`, and
complete same-ID replacement records. Qualified references remain explicit.
Audita requests, registries, inspection, and diagnostics use prompt IDs without
obsolete prompt-version selection or labels. The existing domain instructions,
self-contained response schemas, per-call schema and repair controls, and
proposal/validator behavior remain distinct from resource format changes.
Update [configuration](../config.md), [LLM integration](../integrations/openai-compatible-llm.md),
[runtime internals](../internal/llm-runtime.md), [prompt guidance](../internal/prompts.md),
operator examples, diagnostics metadata documentation, and attribution with the
implementation. Standard inspection replaces curated-only disclosure; prompts
and provider settings may appear where the library's normal inspection exposes
them, with native redaction. Do not accidentally promise old prompt hashes.
Resource inspection shows native optional profile fields and backend definitions;
prepared execution shows the completed request. Audita executes the captured
request it prepared, without a parallel target resolver. Native field-specific
null and presence rules govern defaults. Audita retains logical operation
budgets, cancellation, truthful partial success, and safe diagnostics.
Output-collision protection accounts for consumed host documents, including
imports, and effective source-relative `content_file` resources. Source metadata
tracks inherited and moved values at native list-index and collection paths;
array positions are addresses, not durable resource IDs. Native redaction governs
standard inspection, while Audita owns its artifact redaction.
Canonical [configuration](../config.md), [LLM integration](../integrations/openai-compatible-llm.md),
[runtime](../internal/llm-runtime.md), and [prompt guidance](../internal/prompts.md)
will describe the implemented behavior and cutover, alongside updated examples
and attribution. Standard inspection can show prompts and provider settings
where the library exposes them; old prompt hashes are not a contract.
## Acceptance and Upstream Requests