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

Align adoption plans with main-relative loading releases

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-10 15:49:05 +00:00
parent 0c7622375f
commit 40420a217a
6 changed files with 187 additions and 119 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
docs/roadmap/commandkit.md
View File

@@ -1,6 +1,6 @@
# CommandKit Adoption Outline
**Updated:** 2026-11-09
**Updated:** 2026-11-10
**Status:** Adoption target and design decisions resolved; the upstream release
gate is satisfied. Implementation remains pending. The
@@ -11,22 +11,26 @@ revisions; the [implementation plan](implementation.md) owns sequencing. See the
## Baseline and Target
Audita currently uses application-owned CLI parsing, inspection commands, and
reporting, described in the [CLI contract](../cli.md). Adopt CommandKit core,
ckconfig, and ckprompt v0.6.0 as the standard operator interface. Use supported
reporting, described in the [CLI contract](../cli.md). Adopt CommandKit core v0.6.0
with ckconfig and ckprompt v0.7.0 as the standard operator interface. Use supported
command declarations, typed inputs, supplied-value tracking, help/version,
reporting, and formatting. Audita handlers retain transcript processing and
artifact responsibilities.
The upstream [core release](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/1613ff95cab60581de5d86f6e9e2a3cc091a44a0/docs/releases/v0.6.0.md),
[ckconfig release](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/5ed947bd26bf2c6d70d1d748b693eca89f18d605/integrations/ckconfig/docs/releases/v0.6.0.md),
[ckprompt release](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/1ca660e35fb58fc0dc318e411afb6e3631a40ef1/integrations/ckprompt/docs/releases/v0.6.0.md),
and [consumer guide](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/1ca660e35fb58fc0dc318e411afb6e3631a40ef1/docs/consumers/guide.md)
[ckconfig release](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/64f6453b8453f914f272d427bb4ae6f59deacd2b/integrations/ckconfig/docs/releases/v0.7.0.md),
[ckprompt release](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/f369d6a78253b6e6fcb1e023fb2e9c3af1d20ff0/integrations/ckprompt/docs/releases/v0.7.0.md),
and [consumer guide](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/f369d6a78253b6e6fcb1e023fb2e9c3af1d20ff0/docs/consumers/guide.md)
define the selected set. Core uses Cobra/pflag and declares Go 1.26.0; the matched
integrations require Go 1.27. They retain ConfigKit v1.1.0 and PromptKit v0.20.0.
integrations require Go 1.27. They select ConfigKit v1.2.0 and PromptKit v0.21.0.
The integration updates preserve their public adapters; wire processing and all
inspection commands to the shared loaders and recorded application context
described in the ConfigKit and PromptKit outlines.
## Adoption Gate: Released Debug Binding and Reporting Mode Access
**Satisfied by the selected v0.6.0 release set.** Upstream publication, public APIs,
**Satisfied by core v0.6.0 and the selected v0.7.0 integrations.**
Upstream publication, public APIs,
released integration dependencies, and the required behavior were verified in the
[review below](#upstream-review-shared-debug-input-and-reporting-mode).
@@ -357,7 +361,7 @@ shared upstream improvements over a permanent local output layer.
### Upstream Review: Shared Debug Input and Reporting Mode
On 2026-11-09, verified published upstream tags for core, ckconfig, and ckprompt
v0.6.0 against the exact revisions in the master roadmap. Reviewed the core
v0.6.0, the then-selected release set. Reviewed the core
source changes and external public-API tests. Compared with the previous reviewed
integration releases, ckconfig and ckprompt change dependency pins and release
notes without changing integration implementation.
@@ -376,5 +380,10 @@ released dependencies. An isolated consumer importing all three published v0.6.0
modules, without local replacements, passed 33 cases spanning the roadmap's
capture/mode combinations, aliases, and quiet-destination policy. The resolved
graph selected the intended ConfigKit v1.1.0 and PromptKit v0.20.0 dependencies.
On 2026-11-10, the newly selected ckconfig and ckprompt v0.7.0 tagged suites
also passed independently with released dependencies. Their changes update
dependency pins and release documentation without changing adapter implementation.
The new graph selects ConfigKit v1.2.0, PromptKit v0.21.0, and core v0.6.0.
These checks establish the upstream gate; they do not replace Audita's assembled
integration acceptance. No additional upstream request was identified.

67
docs/roadmap/configkit.md
View File

@@ -1,6 +1,6 @@
# ConfigKit Adoption Outline
**Updated:** 2026-11-09
**Updated:** 2026-11-10
**Status:** Target decisions resolved; implementation pending. The
[master roadmap](library-adoption.md) owns shared policy and dependency selection;
@@ -12,16 +12,16 @@ Audita currently uses ConfigKit v0.7.1 through its former import path. Its
[configuration contract](../config.md) describes application file discovery,
overlays, defaults, inheritance, secret references, and explicit CLI settings.
Adopt ConfigKit v1.1.0 and its stable public API as the configuration foundation.
Adopt ConfigKit v1.2.0 and its stable public API as the configuration foundation.
Use its native loading, discovery, presence, composition, resolution, diagnostics,
and inspection mechanisms. Audita supplies domain types and validation; retain
custom loading behavior only for a demonstrated domain requirement. Standard
operator access is implemented through the [CommandKit outline](commandkit.md).
The main upstream references are the
[v1 API migration](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v1.0.0.md),
[v1.1 release](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v1.1.0.md),
and [configuration contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/config.md).
[v1 API migration](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v1.0.0.md),
[v1.2 release](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v1.2.0.md),
and [configuration contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/config.md).
## Agreed Direction and Migration Work
@@ -69,10 +69,32 @@ operators use `required: true` for essential inputs. Invalid declarations,
unreadable selected files, and composition conflicts retain native errors.
The PromptKit outline owns [automatic prompt sources](promptkit.md#automatic-prompt-sources--resolved).
Those resource imports compose in the engine's operator underlay independently
of main application-file selection, using the same native import semantics.
Keep application configuration discovery and PromptKit resource acquisition
distinct while sharing their supported ConfigKit mechanisms.
Those imports compose in a separate engine underlay, using the selected
application main's recorded context under the shared rule below. Keep application
and PromptKit schemas separate while sharing native loading mechanisms.
### Companion Resource Base and Overlays — Resolved
Use the selected main application configuration file's directory as the lookup
base for automatic glossary and prompt companions and named overlays. This applies
to both explicit `--config` and native discovery. Follow ConfigKit's resolved
context: host symlinks use the canonical target directory; a wider containment
root does not move the lookup base. Transitive imports retain their declaring
file's native context, and embedded inputs retain their own filesystem namespace.
For application-owned glossary import declarations, use a non-file underlay
`Input` with `Imports: true` and `MainRelative: configkit.MainRelative()`.
ConfigKit binds it during the single `LoadLayered` call. PromptKit's separate
loader uses the application result's recorded main context, as specified in its
[automatic source contract](promptkit.md#automatic-prompt-sources--resolved).
Do not duplicate main discovery or perform a preliminary full configuration load.
Select native `overlays/<name>.yml` beside the main file. Let `LoadLayered` derive
its overlay context; do not supply an invocation-directory `OverlayFilesystem`
or `OverlayFallback`. No overlay selection loads no overlay; an active selection
requires a usable context and the named file. Aggregate `overlays.yml` is deferred
upstream and is outside this adoption. ConfigKit v1.2.0 satisfies the upstream
API requirement for this decision.
### No Configuration File Found — Resolved
@@ -87,11 +109,14 @@ mechanisms. Report missing command-specific settings clearly; do not invent an
implicit model or profile selection to make incomplete execution settings pass.
Inspection must accurately show that no main file was selected.
Define filesystem context explicitly where overlays or relative resource inputs
need it; do not infer a base from unsuccessful search candidates. Preserve the
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.
When no main context exists, skip automatic optional glossary and prompt
companion imports; retain embedded defaults and explicitly supplied settings.
Do not install a working-directory fallback or infer a base from unsuccessful
search candidates. Use ConfigKit's native absent-base behavior for the glossary
underlay and omit automatic operator prompt inputs in the separate engine load.
An explicitly selected overlay without a usable context fails. Preserve genuine
absent-main evidence rather than manufacturing a placeholder source. Explicit
file errors and failures loading a selected discovered file remain terminal.
### Target Boundaries
@@ -106,7 +131,7 @@ propagate parent edits through resolved children. Native source provenance uses
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.
use the application main context while retaining their separate schema and tiers.
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),
@@ -139,8 +164,11 @@ integration. Verify that discovery exhaustion permits inspection and sufficientl
configured processing, while incomplete processing reports its missing inputs.
Cover absent-main provenance and filesystem context for selected overlays or
relative resources without weakening explicit-file error behavior.
Verify that application main-file selection and exhaustion preserve the separate
automatic PromptKit source context and precedence specified in its outline.
Verify that explicit and discovered mains outside the working directory anchor
companions and overlays beside the selected file. Cover a broader containment
root, native source evidence, and absent-main skipping without a working-directory
fallback. Verify PromptKit receives the same application context while retaining
its separate schema and precedence, through processing and inspection alike.
Verify acceptance of the final version-3 schema and rejection of obsolete
application versions. Check that no-main-file loading uses version-3 defaults,
@@ -153,6 +181,7 @@ the target; preserving incidental old output or validation order is not.
## Upstream Requests
No ConfigKit change request is currently identified. Prefer adapting Audita to
its stable supported API. Record any necessary exception with a concrete domain
The main-relative companion/overlay request is fulfilled by ConfigKit v1.2.0.
No further ConfigKit change request is currently identified. Prefer adapting
Audita to its stable supported API. Record any necessary exception with a concrete domain
requirement and the smallest integration boundary that satisfies it.

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

@@ -1,6 +1,6 @@
# Stage-Specific Glossary Inputs
**Updated:** 2026-11-09
**Updated:** 2026-11-10
**Status:** Accepted feature scope, ownership, and stage-selection semantics for
the next Audita major release, including named collections and recursive import
@@ -181,7 +181,7 @@ change whole-record replacement semantics.
Use typed Go fields for the Audita contract and ConfigKit's native inline
string-keyed map of dynamic values for unmatched fields. Its
[schema binding rules](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/config.md#advanced-type-and-field-rules)
[schema binding rules](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/config.md#advanced-type-and-field-rules)
cover decoding and inspection without a custom decoder. Keep additional data in
the resolved Go configuration and native inspection. ConfigKit still owns its
reserved syntax and supported value shapes; extensibility does not mean
@@ -213,12 +213,13 @@ config:
destination: [glossary_collections]
```
Both locations are relative to the invocation's working directory: `./glossary.yml`
and recursively `./glossary/`. Supply the appropriate host filesystem context for
the underlay declaration through ConfigKit's public input APIs. This base is
independent of the main configuration file's location and also applies when no
main file is found. Do not attempt host discovery through an unrelated embedded
filesystem or add an application-owned directory walker.
Both locations follow the selected main application configuration file's
resolved directory under the shared [resource-base rule](configkit.md#companion-resource-base-and-overlays--resolved).
Supply the declarations in a non-file underlay with imports enabled and
`MainRelative: configkit.MainRelative()`. ConfigKit binds the context during the
application load. With no usable main context, skip these optional imports and
retain independent defaults; do not supply a working-directory fallback. Keep
embedded contexts independent and do not add a local discovery pass or walker.
Load both sources when present; this is composition, not first-match discovery.
Missing optional sources contribute nothing. Present sources retain ConfigKit's
@@ -716,7 +717,7 @@ explicitly supplied CLI values to ConfigKit; preserve false, zero, and empty
values under their per-field rules rather than allowing parser defaults to
override configuration.
Keep CLI functionality within ConfigKit's native capabilities. ConfigKit v1.1.0
Keep CLI functionality within ConfigKit's native capabilities. ConfigKit v1.2.0
does not support sequence-index paths in its CLI override API, so targeted-stage
CLI overrides are not part of this plan. Operators supply stage-specific values
in configuration files. Do not implement a parallel override system, custom
@@ -728,15 +729,15 @@ rules remain within ConfigKit's supported application-resolution lifecycle.
### ConfigKit Support
Use the selected ConfigKit v1.1.0 public lifecycle for this work. Its
[typed decoding contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/config.md#defaults-and-typed-decoding)
Use the selected ConfigKit v1.2.0 public lifecycle for this work. Its
[typed decoding contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/config.md#defaults-and-typed-decoding)
already preserves explicit false, zero, empty, and permitted null values,
recurses through partial mappings, and replaces ordinary sequences. Represent
nullable selectors with nullable typed fields and settings groups with
non-nullable structs. Use native decoding and validation rather than a parallel
parser or generic deep-merge implementation.
Use the native [collection and inheritance contracts](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/config.md#strict-document-composition)
Use the native [collection and inheritance contracts](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/config.md#strict-document-composition)
for glossary definitions. For identified lists, register identity constraints in
Audita's ConfigKit definition so native final validation also covers values from
defaults, CLI, and recorded resolution. YAML-only declarations do not provide
@@ -780,7 +781,7 @@ An explicitly null validation selection needs deliberate application fallback:
fallback and use `Resolution.RecordDerivedDefault` to record the assignment and
its effective proposal-profile dependency, retaining the original explicitness
and history. Follow the native
[recorded-resolution contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/config.md#recorded-application-resolution)
[recorded-resolution contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/config.md#recorded-application-resolution)
for all derived mutations, and use `Definition.Validate` for configuration-contract
checks on effective settings. The execution-readiness check for an empty glossary
stage belongs to Audita preflight after handoff. Keep stage values independent
@@ -864,9 +865,11 @@ and diagnostics retain module and position, with optional IDs when supplied;
inspection exposes effective selections and source origins for every stage.
Confirm stage IDs do not change pipeline composition or add CLI targeting.
Cover default-source loading with only `glossary.yml`, only `glossary/`, both,
and neither present. Verify invocation-directory resolution even with a main file
elsewhere or no main file, optional absence, and normal errors for invalid present
sources. Verify strict-peer conflicts within the underlay, higher-priority main
and neither present. Verify resolution beside explicit and discovered main files
outside the working directory. With no main context, verify optional imports are
skipped without a working-directory fallback. Preserve normal errors for invalid
present sources and preflight rejection of unusable glossary stages. Verify
strict-peer conflicts within the underlay, higher-priority main
configuration additions/replacements under the selected native policies, nested
import destination inheritance, and repeated inclusion within the default tier.
Confirm that an empty main-file import list does not cancel the underlay imports.

77
docs/roadmap/implementation.md
View File

@@ -1,5 +1,7 @@
# Next Major Release Implementation Plan
**Updated:** 2026-11-10
**Status:** Ready for the implementation sprint. This document assigns work;
it does not describe implemented behavior or authorize a release.
@@ -43,9 +45,10 @@ and [ReleaseKit contract](library-adoption.md#releasekit-adoption-work). Work in
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`
2. Select the exact versions from the master roadmap: ConfigKit v1.2.0,
PromptKit v0.21.0, CommandKit core v0.6.0, ckconfig/ckprompt v0.7.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
@@ -87,9 +90,13 @@ execution in this stage.
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.
Follow the resolved [companion resource base](configkit.md#companion-resource-base-and-overlays--resolved).
Let ConfigKit derive the selected overlay context from the main; leave
`OverlayFilesystem` and `OverlayFallback` unset. Native selection uses
`overlays/<name>.yml` beside the main, with no aggregate `overlays.yml`.
Return recorded main source/context evidence for Stage 3's prompt loader;
no main context means optional companions are skipped, with no CWD fallback.
Use field-named literals for the expanded ConfigKit input/options types.
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`,
@@ -115,6 +122,9 @@ execution in this stage.
Evidence: native result/failure and source metadata cover discovery, exhaustion,
selected file errors, imports, overlays, v3 defaults, and changed override order.
Verify selected overlays follow the main directory even with a wider containment
root, and fail without a usable context or named file. Check that the returned
main context supports Stage 3 without another application load.
Exercise final v3 examples after the glossary fields are connected.
## Stage 3: Build the shared PromptKit engine and account for its sources
@@ -129,14 +139,19 @@ Own engine assembly in `internal/framework/llm/runtime.go`,
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
2. Load embedded prompt inputs in their own filesystem underlay. When an
application main context exists, add 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.
enabled and a concrete context derived from Stage 2's recorded application
main context. Preserve its lookup base, containment, and source accounting.
Both sources compose as strict peers. PromptKit's `MainRelative` refers to
its own main, so do not assume it binds to Audita's separate application load.
Do not feed Audita's document into PromptKit or reload it for its directory.
Without an application main context, omit automatic operator inputs and keep
the bundled/embedded tiers. Overlay selection does not relocate the base.
Use one acquisition path for all engine consumers, without a private parser,
directory walker, filename-derived IDs, or 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
@@ -153,7 +168,9 @@ Own engine assembly in `internal/framework/llm/runtime.go`,
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.
capture. Exercise explicit/discovered main files elsewhere, independence from
the invocation directory, recorded-context handoff, and absent-main skipping
while embedded resources remain usable. Preserve consumed-source evidence.
## Stage 4: Adapt native requests, role clients, and artifact redaction
@@ -199,7 +216,7 @@ 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
and the released consumer 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.
@@ -234,7 +251,7 @@ for inspection or overriding native grammar or status behavior.
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.
from ckprompt v0.7.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
@@ -339,9 +356,11 @@ through its default-source and entry-contract sections.
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,
recursive `glossary/` imports mounted at `glossary_collections`. Use a
non-file input with imports enabled and `MainRelative: configkit.MainRelative()`
so ConfigKit binds it to the selected application main during the same load.
Supply no fallback; absent main context skips the optional imports. 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
@@ -555,23 +574,3 @@ in the real repository during this sprint.
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.

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

@@ -1,6 +1,6 @@
# Next Major Release Roadmap
**Updated:** 2026-11-09
**Updated:** 2026-11-10
**Status:** Target decisions are recorded across this roadmap and its four child
roadmaps; implementation and dependency changes remain pending. The
@@ -89,25 +89,27 @@ The reviewed application revision is
uses old-path ConfigKit v0.7.1 and PromptKit v0.14.0, with no CommandKit.
The source minimum is Go 1.26.0; the release runbook selects Go 1.26.8.
The following published versions are selected for adoption. CommandKit core and
both integrations use the reviewed v0.6.0 release set; its release gate is
satisfied as recorded below:
The following published versions are selected for adoption. The reviewed set
uses CommandKit core v0.6.0 with both integrations at v0.7.0. The CommandKit
and main-relative ConfigKit availability gates are satisfied:
| Module | Version | Reviewed source commit |
| --- | --- | --- |
| `go.maximumdirect.net/configkit` | v1.1.0 | `191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9` |
| `go.maximumdirect.net/promptkit` | v0.20.0 | `8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf` |
| `go.maximumdirect.net/configkit` | v1.2.0 | `c1c7e87f2cdf77a0cbf3327831ac05578e756b9e` |
| `go.maximumdirect.net/promptkit` | v0.21.0 | `171fb11f4e967a1da3af57843c6467954b14ba09` |
| `go.maximumdirect.net/commandkit` | v0.6.0 | `1613ff95cab60581de5d86f6e9e2a3cc091a44a0` |
| `go.maximumdirect.net/ckconfig` | v0.6.0 | `5ed947bd26bf2c6d70d1d748b693eca89f18d605` |
| `go.maximumdirect.net/ckprompt` | v0.6.0 | `1ca660e35fb58fc0dc318e411afb6e3631a40ef1` |
| `go.maximumdirect.net/ckconfig` | v0.7.0 | `64f6453b8453f914f272d427bb4ae6f59deacd2b` |
| `go.maximumdirect.net/ckprompt` | v0.7.0 | `f369d6a78253b6e6fcb1e023fb2e9c3af1d20ff0` |
| `go.maximumdirect.net/releasekit` | v0.9.0 | `2180aa868ec2caa95fc8279fd59d5f0ebac41bd4` |
The integration tags are `integrations/ckconfig/v0.6.0` and
`integrations/ckprompt/v0.6.0` in CommandKit's repository. Use the
[released module selection guide](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/1ca660e35fb58fc0dc318e411afb6e3631a40ef1/docs/consumers/guide.md#module-selection).
The integration updates retain ConfigKit v1.1.0 and PromptKit v0.20.0 and require
Go 1.27. Changes to these selected versions require an ordinary compatibility
review rather than assuming later releases are interchangeable.
The integration tags are `integrations/ckconfig/v0.7.0` and
`integrations/ckprompt/v0.7.0` in CommandKit's repository. Use the
[released module selection guide](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/f369d6a78253b6e6fcb1e023fb2e9c3af1d20ff0/docs/consumers/guide.md#module-selection).
The integrations select ConfigKit v1.2.0 and PromptKit v0.21.0. The combined
consumer minimum is Go 1.27.0. Use field-named ConfigKit struct literals for the
new input and layered-option fields. Changes to these selected versions require
an ordinary compatibility review rather than assuming later releases are
interchangeable.
**CommandKit release gate — satisfied:** the published v0.6.0 core provides both
the independent shared debug binding for capture and the resolved reporting-mode
@@ -117,6 +119,14 @@ records the API contract and review evidence. The selected release set removes
the upstream availability blocker; Audita implementation and acceptance remain
pending under the [implementation plan](implementation.md).
**Main-relative loading gate — satisfied:** ConfigKit v1.2.0 implements the
requested companion import binding and derived layered-overlay context. Follow
the [shared resource-base decision](configkit.md#companion-resource-base-and-overlays--resolved).
Load application configuration first, construct PromptKit using its recorded
context, then expose both through the CommandKit integrations. Glossary-stage
execution follows the library foundations; the implementation plan retains that
order. No preliminary discovery/load pass or local directory walker is needed.
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
is complete, with no identified upstream blocker. The agreed
@@ -196,7 +206,15 @@ and runbook describe the selected workflow, validator rationale, and native reco
## Shared Evidence, Validation, and Completion
The review verified release identities, requirements, and relevant upstream
contracts. Disposable checks using Go 1.27.3 established:
contracts. On 2026-11-10, published tags matched the selected commits above.
All packages in the four newly selected releases passed their tagged suites with
Go 1.27.3, `GOWORK=off`, and no local replacements; two PromptKit packages needed
local HTTP test listeners permitted. The ckprompt module graph selected exactly
the ConfigKit, PromptKit, ckconfig, and core versions above. Upstream coverage
includes companion discovery, optional file/directory combinations, precedence,
absent-main handling, and prompt content-file context.
Earlier disposable checks using Go 1.27.3 established:
- Audita's existing core configuration tests pass after import/API adaptation;
the application build still fails at the expected PromptKit API changes.
@@ -207,8 +225,8 @@ contracts. Disposable checks using Go 1.27.3 established:
with released dependencies, `GOWORK=off`, and no local replacements.
- A separate consumer of all three published v0.6.0 modules passes 33 cases
covering debug capture, reporting-mode ordering, aliases, and quiet transcript
destination validation. The assembled graph retains the selected ConfigKit and
PromptKit versions and brings in ReleaseKit v0.9.0.
destination validation. That earlier graph selected ConfigKit v1.1.0 and
PromptKit v0.20.0 and brought in ReleaseKit v0.9.0.
- A disposable Audita copy with the ReleaseKit tool and runtime version import
migrated to v0.9.0, and toolchain references aligned, passes the selected native
validators, Linux amd64 and arm64 builds, and the native version-output check.

48
docs/roadmap/promptkit.md
View File

@@ -1,6 +1,6 @@
# PromptKit Adoption Outline
**Updated:** 2026-11-09
**Updated:** 2026-11-10
**Status:** Adoption direction and automatic operator-source selection resolved;
implementation remains pending. Follow the [master roadmap](library-adoption.md)
@@ -13,7 +13,7 @@ Audita currently uses PromptKit v0.14.0. Its
[LLM runtime](../internal/llm-runtime.md) uses a shared engine, application-owned
backend overrides, curated profile inspection, and prepared execution.
Adopt PromptKit v0.20.0 through its native configuration and execution APIs.
Adopt PromptKit v0.21.0 through its native configuration and execution APIs.
Retain the built-in OpenRouter backend and bundled profiles. They must be usable
through the normal selection and credential mechanisms, not merely visible in
an inventory while Audita rejects them for lacking a duplicate registration.
@@ -26,9 +26,9 @@ proposal/validation role selection, transcript processing, domain decisions,
response contracts, and truthful partial-success reporting. Remove the existing
application-only endpoint and credential restrictions as described below.
Use the pinned [migration guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/docs/consumers/configuration-migration.md),
[format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/docs/formats.md),
and [v0.20 release notes](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/docs/releases/v0.20.0.md).
Use the pinned [migration guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09/docs/consumers/configuration-migration.md),
[format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09/docs/formats.md),
and [v0.21 release notes](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09/docs/releases/v0.21.0.md).
The bundle is default-on; older migration prose about catalog removal does not
mean the current release has no bundled resources. It does not select an implicit
execution profile or make provider calls during construction.
@@ -121,9 +121,10 @@ This workflow is required PromptKit adoption scope and uses native composition.
### Automatic Prompt Sources — Resolved
Automatically compose optional `./prompts.yml` and YAML files recursively under
`./prompts/`. Both locations are relative to the invocation's working directory,
independent of the selected Audita configuration file's location. The same
loading applies when no main application configuration file is found.
`./prompts/`, relative to the selected main application configuration file's
directory. Follow the shared [resource-base and overlay rule](configkit.md#companion-resource-base-and-overlays--resolved).
When no main context exists, skip these automatic inputs and retain the embedded
Audita prompts and bundled catalog; do not fall back to the working directory.
Supply one operator-source underlay with these native ConfigKit imports:
@@ -138,11 +139,16 @@ config:
pattern: ["*.yml", "*.yaml"]
```
Enable imports and provide the declaration's host filesystem context through
ConfigKit's public input APIs, rooted at the invocation's working directory.
Keep this host context separate from the embedded prompt filesystem. ConfigKit
owns traversal, composition, inheritance, and provenance; do not add an Audita
directory walker, YAML parser, or replacement mechanism.
Construct the engine after application loading. Enable imports and supply the
operator declaration's concrete filesystem context from ConfigKit's recorded
application main source/context evidence, preserving its resolved lookup base,
containment root, and source accounting. `Input.MainRelative` inside PromptKit
refers to the engine's own main input; it does not automatically refer to Audita's
separately loaded main. Do not feed the application document into PromptKit's
schema or rediscover/reload it to obtain a directory. When no main context exists,
omit the automatic operator inputs. Keep embedded prompt contexts separate.
ConfigKit owns traversal, composition, inheritance, and provenance; do not add
an Audita directory walker, YAML parser, or replacement mechanism.
Compose the engine's layers from lowest to highest priority:
@@ -157,7 +163,7 @@ gains priority from declaration, filename, or discovery order; duplicate resourc
identities in that tier are errors. At the boundary above embedded defaults,
native same-ID replacement replaces the complete matching record while retaining
unmatched defaults. Follow the upstream
[source and profile precedence](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/docs/formats.md#source-and-profile-precedence).
[source and profile precedence](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09/docs/formats.md#source-and-profile-precedence).
Use native PromptKit documents at the document root, with namespaces and IDs
declared in their content. Each file may define one or several resources,
@@ -175,8 +181,9 @@ manifest; repeated inclusion within the tier retains ConfigKit's native error.
Use one shared engine-loading path for processing, configuration/resource
inspection, request preview, validation, and smoke commands. All must observe
the same layers and captured definitions for the same invocation inputs.
`--config` continues to select Audita's application configuration; it does not
change the working-directory base of these automatic resource imports.
`--config` selects Audita's application configuration and therefore determines
the companion lookup base. Selecting an application overlay does not relocate
that base to the overlay's directory. All engine consumers share this handoff.
### Profile Inspection and Summary — Resolved
@@ -247,9 +254,12 @@ Verify the embedded `audita` prompts work without external prompt definitions.
Cover both automatic locations absent, each present alone, and both present with
distinct resources, including nested YAML files. Exercise missing optional
sources, unreadable/invalid sources, and same-tier identity conflicts through
native loading. Confirm that an explicit application config elsewhere and absent
main-file discovery both retain the invocation working directory as the automatic
source base. Check manifest imports of shared libraries and source-relative
native loading. Confirm that explicit and discovered application mains elsewhere
anchor imports beside that main, independently of the working directory. With no
main context, confirm automatic imports are skipped while bundled and embedded
resources remain available. Verify the recorded-context handoff to the separate
engine, including source accounting and overlay selection without relocation.
Check manifest imports of shared libraries and source-relative
message files, with provenance and consumed-source collision protection intact.
Exercise both individual-prompt and complete-set replacements using native
collection IDs, checking that unreplaced defaults remain available. Demonstrate