diff --git a/docs/roadmap/commandkit.md b/docs/roadmap/commandkit.md index e1f1479..506e56a 100644 --- a/docs/roadmap/commandkit.md +++ b/docs/roadmap/commandkit.md @@ -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. diff --git a/docs/roadmap/configkit.md b/docs/roadmap/configkit.md index 6258b22..57f7b64 100644 --- a/docs/roadmap/configkit.md +++ b/docs/roadmap/configkit.md @@ -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/.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. diff --git a/docs/roadmap/glossary-stages.md b/docs/roadmap/glossary-stages.md index 40a5500..c227e2d 100644 --- a/docs/roadmap/glossary-stages.md +++ b/docs/roadmap/glossary-stages.md @@ -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. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 09d23eb..018edb7 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -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/.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/.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. diff --git a/docs/roadmap/library-adoption.md b/docs/roadmap/library-adoption.md index 1f16088..046cbde 100644 --- a/docs/roadmap/library-adoption.md +++ b/docs/roadmap/library-adoption.md @@ -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. diff --git a/docs/roadmap/promptkit.md b/docs/roadmap/promptkit.md index c5f33c1..4653963 100644 --- a/docs/roadmap/promptkit.md +++ b/docs/roadmap/promptkit.md @@ -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