diff --git a/docs/roadmap/commandkit.md b/docs/roadmap/commandkit.md index 3f82a45..e1f1479 100644 --- a/docs/roadmap/commandkit.md +++ b/docs/roadmap/commandkit.md @@ -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 diff --git a/docs/roadmap/configkit.md b/docs/roadmap/configkit.md index 136ebdc..6258b22 100644 --- a/docs/roadmap/configkit.md +++ b/docs/roadmap/configkit.md @@ -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 diff --git a/docs/roadmap/glossary-stages.md b/docs/roadmap/glossary-stages.md index a1fd980..40a5500 100644 --- a/docs/roadmap/glossary-stages.md +++ b/docs/roadmap/glossary-stages.md @@ -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 diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md new file mode 100644 index 0000000..09d23eb --- /dev/null +++ b/docs/roadmap/implementation.md @@ -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.` 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/`. 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/.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 ae3a1da..1f16088 100644 --- a/docs/roadmap/library-adoption.md +++ b/docs/roadmap/library-adoption.md @@ -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 diff --git a/docs/roadmap/promptkit.md b/docs/roadmap/promptkit.md index d818cd3..c5f33c1 100644 --- a/docs/roadmap/promptkit.md +++ b/docs/roadmap/promptkit.md @@ -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