From 46765bd3266b62cd9db0087dbb7a06861d179ebd Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 8 Nov 2026 01:31:18 +0000 Subject: [PATCH] Document native library adoption plans --- docs/roadmap/commandkit.md | 137 +++++++++++++++++++++++++++ docs/roadmap/configkit.md | 111 ++++++++++++++++++++++ docs/roadmap/future.md | 19 ++-- docs/roadmap/library-adoption.md | 158 +++++++++++++++++++++++++++++++ docs/roadmap/promptkit.md | 139 +++++++++++++++++++++++++++ 5 files changed, 551 insertions(+), 13 deletions(-) create mode 100644 docs/roadmap/commandkit.md create mode 100644 docs/roadmap/configkit.md create mode 100644 docs/roadmap/library-adoption.md create mode 100644 docs/roadmap/promptkit.md diff --git a/docs/roadmap/commandkit.md b/docs/roadmap/commandkit.md new file mode 100644 index 0000000..4622dbb --- /dev/null +++ b/docs/roadmap/commandkit.md @@ -0,0 +1,137 @@ +# CommandKit Adoption Outline + +**Updated:** 2026-11-07 + +**Status:** Initial outline. Adoption is part of the agreed target, not an optional +future evaluation. The [master roadmap](library-adoption.md) owns shared direction +and sequencing; ConfigKit and PromptKit integration contracts are developed in +[their](configkit.md) [outlines](promptkit.md). + +## 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.5.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/49f2d09ccde3d91d8c412a44ab934f223bef8fe6/docs/releases/v0.5.0.md), +[ckconfig release](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/5c960532552037d38119941389e558f78bf73aad/integrations/ckconfig/docs/releases/v0.5.0.md), +[ckprompt release](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/88ac6e76e4b164571f4172c01d7679c043b94a02/integrations/ckprompt/docs/releases/v0.5.0.md), +and [consumer guide](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/88ac6e76e4b164571f4172c01d7679c043b94a02/docs/consumers/guide.md) +define the reviewed set. Core uses Cobra/pflag; the matched integrations require +Go 1.27. The former missing diagnostic adapter has been published. There is no +known publication blocker to adoption. + +## Agreed Operator Experience + +- Install the full ckprompt inspection surface: prompt/profile/backend views, + resource and namespace/collection inventories, contextual requirement + inspection, and captured engine configuration through its config scope. + Native reports and namespace selection must remain available; a curated Audita + subset is not a substitute. Inspection success is not execution readiness. +- Adopt standard ckconfig viewing, validation, sources, path discovery, + explanation, and comparison. Use native evidence and common text/YAML/JSON + rendering. Do not recreate removed provider-specific explanation writers. +- Use standard command names and reporting flags. Adapt Audita's existing + `--debug` artifact-capture spelling to avoid colliding with CommandKit's reserved + reporter flag; the final capture spelling is decided below. +- Keep domain transcript serialization and ordinary report files under Audita's + output contracts. Generic report formatting need not transform transcript JSON. + Preserve meaningful partial success: a work-unit model error is not automatically + a failed CLI invocation or a reporter warning. +- Preserve safe library redaction without restricting standard inspection to + today's curated fields. Loading for help/version must not trigger credentials, + provider calls, or domain processing. + +## Work Outline + +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. 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 its selected ReleaseKit + integration. 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. Specify quiet + mode, completion summaries, and write failures before implementation. Standard + command statuses, including comparison status 3, should not be forced into the + old Audita-only status table without a domain reason. +5. Develop concrete request adapters for preview, validation, and any selected + smoke commands. They need correct variables, schema contracts, and credential + handling, not just an engine loader. Keep generic resource inspection independent + of those domain inputs and distinguish generic from Audita-prepared requests. +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. Adopt + the dependencies and exact attribution together. + +## Acceptance and Upstream Requests + +Check the complete standard inspection/configuration inventory and native +formats through the assembled CLI, including failed-load evidence, redaction, +source selection, and missing/partial resources. Check help/version without +configuration and supplied-value handling through domain settings. Exercise +stdout transcript isolation, file output, quiet/verbose/debug behavior, completion +summary placement, cancellation, partial success, and output failures. + +Tagged core and integration suites passed during review, but do not establish +these Audita behaviors. Use offline tests and controlled providers; explicitly +invoked smoke operations may contact providers and incur costs, but are not an +automatic startup or release check. + +CommandKit and integrations are early-stage. Freely propose upstream improvements +where reporting, declaration, or integration APIs are problematic or incomplete. +No request has yet been submitted. First candidates for investigation are support +for result payloads versus diagnostic verbosity and preserving a domain completion +summary alongside stdout data. Use shared upstream improvements where appropriate +instead of bypassing the reporter with a permanent local output layer. + +## Open Decisions + +### Artifact Capture Flag + +**Recommendation:** use `--debug-artifacts` for retained Audita artifacts and keep +`--debug` exclusively for standard reporting verbosity. The meanings are distinct, +and separation follows CommandKit's supported reserved-flag contract. + +**Alternative:** deliberately couple debug verbosity with artifact capture through +supported application hooks. This reduces operator flags but can retain sensitive +request/response artifacts when an operator only wanted verbosity. It would need +clear suite-wide semantics; duplicate declaration of `--debug` is unsupported. + +### Quiet Mode and the Completion Summary + +**Recommendation:** start with CommandKit's normal visibility rules, including +quiet suppression of command output, and document their effect on stdout +transcripts. File artifacts remain domain outputs. Determine whether the existing +always-visible completion summary serves a domain need or can become standard +verbose information. Do not silently hide it merely by changing its implementation +to `Reporter.Info`; make the operator behavior change explicit. + +**Alternative:** preserve transcript payloads under quiet mode or preserve an +ordinary-mode diagnostic summary through a shared upstream reporting capability. +This can serve pipelines and operators who distinguish payloads from messages, +but diverges from current core semantics and needs a concrete use case. Prefer an +upstream change over bypassing standard reporting or inventing local quiet rules. + +### Request Preview, Validation, and Smoke Commands + +**Recommendation:** include standard offline request preview and validation, +and expose smoke diagnostics as explicit operator-invoked commands once the +request adapter is correct. This best supports the suite happy path. Generic +inspection remains available without a runnable request, and smoke results must +retain unknown/unsupported facts rather than imply provider readiness. + +**Alternative:** deliver the agreed full inspection/configuration surface first, +then add request operations in a named follow-up stage if their adapter needs +upstream work. This limits premature request semantics but leaves a temporarily +incomplete suite experience. It is not permission to defer the full inspection +set or to silently omit commands because they were absent from old Audita. diff --git a/docs/roadmap/configkit.md b/docs/roadmap/configkit.md new file mode 100644 index 0000000..9657825 --- /dev/null +++ b/docs/roadmap/configkit.md @@ -0,0 +1,111 @@ +# ConfigKit Adoption Outline + +**Updated:** 2026-11-07 + +**Status:** Initial outline. The [master roadmap](library-adoption.md) owns the +agreed adoption policy, reviewed versions, shared sequencing, and completion. + +## Baseline and Target + +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. +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). + +## Agreed Direction and Migration Work + +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. + 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.modules` entries and 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. Reconcile application configuration fields with PromptKit's native resource + ownership. Do not force PromptKit backend duplication into the Audita schema + simply to preserve today's layout. The [PromptKit outline](promptkit.md) + owns that boundary decision; coordinate any resulting application schema and + credential migration here. + +## Documentation and Acceptance + +Update [configuration](../config.md), relevant [CLI](../cli.md) behavior, +[change recipes](../internal/cli-config.md), maintained examples, migration +guidance, and attribution as the corresponding behavior lands. Public docs +remain descriptions of implemented behavior until then. + +Acceptance should demonstrate native file selection, source composition, +overlays, explicit false/zero/empty values, derived settings, and secret handling +through real ConfigKit loading. Cover the changed inheritance/assignment order, +source errors, useful failure evidence, and secret-safe inspection. Reuse upstream +coverage for generic grammar rather than copying its test matrix. Verify the +standard ckconfig surface through the assembled CLI and run the full application +suite at the coordinated migration boundary. + +The earlier passing configuration suite is useful baseline evidence, not proof +that operators see unchanged semantics. Native semantics and clear migration are +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 +requirement and the smallest integration boundary that satisfies it. + +## Open Decisions + +### Discovery Locations and Import Selection + +**Recommendation:** replace custom discovery with ConfigKit's supported search +API, then select documented paths and import options based on suite conventions. +Evaluate the current system-only search and disabled imports rather than carrying +them forward automatically. Native API adoption is agreed; the exact search +locations and import defaults still need selection before changing operator +behavior. Preserve explicit-path error evidence and distinguish optional from +required imports using native semantics. + +**Alternative:** configure the native API with today's two system locations and +imports disabled. This eases installation migration and remains supported, but +should be retained only if deployment requirements justify it; historical behavior +alone does not satisfy the suite-alignment objective. Conversely, enabling all +possible searches/imports without a selected convention can load unintended +sources and is not required for full API adoption. + +### Application Schema Version + +**Recommendation:** retain `version: 2` only if the resulting application fields +and meaning remain coherent after PromptKit ownership is settled. Do not confuse +it with the library version or PromptKit's source header. This avoids meaningless +schema churn while allowing deliberate field migration. + +**Alternative:** introduce a new application schema version if backend or +credential ownership changes make existing files misleading. It provides a clear +migration boundary, at the cost of updating files and guidance. Decide from the +final schema, not from dependency version numbers alone. diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index 8e9d6bd..1171535 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -81,16 +81,9 @@ or introduce segment-removal machinery as part of span-deletion consistency. ## Library Inspection and Configuration Comparison -ConfigKit and PromptKit provide effective-configuration comparison; PromptKit -also provides prompt/profile listings and contextual prompt requirement -inspection. Exposing these capabilities in Audita is deferred until a concrete -operator or development need arises. The dependency upgrade did not select new -inspection commands. - -If a need emerges, define command ownership, selection syntax, report scope, and -disclosure before implementation. Reuse the libraries' public APIs and consider -shared CLI conventions alongside any separately selected CommandKit adoption. -Requirement discovery is advisory evidence rather than proof of execution -readiness; an empty configuration diff does not prove equivalent execution. -The library-upgrade review remains available in -[Git history](https://gitea.maximumdirect.net/eric/audita/src/commit/4c5536ab78c72dea58d03b3c51834138d429a59a/docs/roadmap/imports.md). +Standard library inspection and configuration comparison have moved into the +accepted [native library adoption roadmap](library-adoption.md). The +[CommandKit outline](commandkit.md) owns the operator surface, including the +full ckprompt inspection set. These capabilities are no longer deferred pending +an additional operator need; consistency across the application suite is the +selected reason for adoption. The domain features above remain separate work. diff --git a/docs/roadmap/library-adoption.md b/docs/roadmap/library-adoption.md new file mode 100644 index 0000000..777b9ea --- /dev/null +++ b/docs/roadmap/library-adoption.md @@ -0,0 +1,158 @@ +# Native Library Adoption Roadmap + +**Updated:** 2026-11-07 + +**Status:** Agreed direction with proposed sequencing. Initial outlines only; +no implementation or dependency changes have been made for this adoption. + +## Objective and Document Ownership + +Align Audita with the supported happy path of ConfigKit, PromptKit, and +CommandKit so operators encounter the same conventions across the application +suite. Existing Audita behavior alone is not a reason to diverge. + +This document owns shared adoption principles, sequencing, dependency selection, +and cross-library decisions. The linked outlines own library-specific outcomes, +work, acceptance criteria, and open decisions: + +| Outline | Responsibility | +| --- | --- | +| [ConfigKit](configkit.md) | Stable configuration API, loading, discovery, presence, secrets, and provenance | +| [PromptKit](promptkit.md) | Native resources and bundled catalog, role integration, execution, and source accounting | +| [CommandKit](commandkit.md) | Standard operator interface, configuration commands, full ckprompt inspection, and reporting | + +These four documents replace the removed `import-upgrade.md`. They retain its +relevant technical evidence but supersede its recommendations to disable the +OpenRouter bundle, defer CommandKit adoption, limit standard inspection, or +preserve Audita's backend ownership restrictions without a domain justification. +They do not select unrelated work in [future.md](future.md). + +## Agreed Adoption Principles + +- **ConfigKit:** fully adopt and adapt to its stable public API and native + conventions. Diverge only where an identified Audita requirement makes it + necessary; a local convenience is not sufficient justification. +- **PromptKit:** follow the mature library's supported path, including its + bundled OpenRouter backend and profiles. Significant blockers or pain points + may justify a focused upstream feature request before adding substantial local + integration machinery. +- **CommandKit and integrations:** adopt the standard suite experience, including + the full ckprompt inspection command set. The libraries are young; problematic + or incomplete behavior is a candidate for an upstream change request rather + than a permanent Audita workaround. +- Audita continues to own transcript formats, correction ordering, domain + validation, structured-response contracts, and truthful partial-success + behavior. Inspect each other restriction against a concrete domain need. +- Standard library inspection and native redaction are part of the target. + Existing curated summaries may survive for a distinct domain purpose, but + cannot replace the full standard inspection surface. + +For each friction point, record the desired outcome, whether the constraint is +library behavior or an Audita domain requirement, the proposed adaptation or +upstream request, and its acceptance evidence. Distinguish agreed decisions from +recommendations. No upstream request has been submitted by this planning work. + +## Baseline and Reviewed Dependency Set + +The reviewed application revision is +`cbcb1b3778d747ced7825d09d9e7536cabc0f0fa`. Its [module file](../../go.mod) +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 reviewed targets are published and mutually aligned: + +| Module | Version | Reviewed source commit | +| --- | --- | --- | +| `go.maximumdirect.net/configkit` | v1.1.0 | `191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9` | +| `go.maximumdirect.net/promptkit` | v0.20.0 | `8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf` | +| `go.maximumdirect.net/commandkit` | v0.5.0 | `49f2d09ccde3d91d8c412a44ab934f223bef8fe6` | +| `go.maximumdirect.net/ckconfig` | v0.5.0 | `5c960532552037d38119941389e558f78bf73aad` | +| `go.maximumdirect.net/ckprompt` | v0.5.0 | `88ac6e76e4b164571f4172c01d7679c043b94a02` | + +The integration tags are `integrations/ckconfig/v0.5.0` and +`integrations/ckprompt/v0.5.0` in CommandKit's repository. Use the +[corrected module selection guide](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/88ac6e76e4b164571f4172c01d7679c043b94a02/docs/consumers/guide.md#module-selection); +the core tag's guide predates integration publication. The former missing +`AdaptDiagnostics` blocker is resolved. Changes to these reviewed targets need +an ordinary compatibility review, not an assumption that later releases are +interchangeable. + +## Proposed Order of Operations + +1. **Resolve the target contracts across all three outlines.** Establish the + standard command inventory, discovery behavior, source ownership, and + reporting expectations before implementation. Identify concrete upstream + requests early; do not postpone CommandKit design until the runtime is done. + Reconcile planned changes with the current architecture policy, especially + application-only credential rules, finite admission, and preference for + standard-library CLI parsing. Update policies with adopted behavior; do not + silently treat old integration choices as permanent requirements. +2. **Prepare toolchain and migration work.** Select Go 1.27 or newer, updating + source/build requirements, CI/bootstrap assumptions, release instructions, + and toolchain attribution. Inventory operator file and CLI migration needs. + 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. Avoid a permanent replacement or dual configuration engine. +4. **Integrate CommandKit and both standard integrations.** Complete the + previously designed operator interface, adapting Audita domain handlers and + resolving upstream issues. This is required target scope, not an optional + follow-up whose justification is deferred. +5. **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 operator migration guidance. +6. **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 existing release process without importing upstream release gates. + +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. + +## Shared Evidence, Validation, and Completion + +The review verified release identities, requirements, and relevant upstream +contracts. 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. +- CLI parent overrides do not rerun ConfigKit inheritance. PromptKit same-ID + replacement drops omitted provider settings; distinct native inheritance can + retain them. Profile null endpoints permit backend fallback. +- Tagged CommandKit core, ckconfig, and ckprompt suites pass independently with + released dependencies, `GOWORK=off`, and no local replacements. + +These are review results, not implementation acceptance. They involved no live +provider calls and do not prove migrated Audita behavior or cross-platform +execution. Use controlled provider boundaries and proportionate tests under +[testing policy](../policy/testing.md); live diagnostics are not release gates. + +Completion requires all three adoption targets, resolved decisions, migrated +examples, useful native inspection, preserved domain behavior, and a passing +assembled application. Upstream requests need an explicit disposition before +calling the dependent behavior complete. Any temporary workaround must name its +reason and removal condition; it is not architecture by default. + +Refresh [attribution](../oss/attribution.md) for the exact selected dependencies +and toolchain under [OSS policy](../policy/oss.md). The reviewed library grants +remain LGPL-3.0-or-later; remove old catalog entries when no longer incorporated +and retain shared license texts. Do not copy upstream policy inventories. + +## Open Decisions + +### Direct ReleaseKit Migration + +**Recommendation:** assess the direct ReleaseKit tool and launcher in a distinct +preparation unit, coordinating its import identity and version reporting if the +new tool is adopted. The library graph brings new-path ReleaseKit v0.9.0 but does +not migrate Audita's old-path v0.4.1 tool. Explicit treatment avoids accidental +release behavior changes and makes the duplicate identities understandable. + +**Alternative:** migrate ReleaseKit within the same toolchain unit. This reduces +duplicate module identities sooner and may simplify attribution, but broadens +that unit into release-workflow compatibility work. Neither choice authorizes +adopting upstream publication gates or publishing a release during implementation. diff --git a/docs/roadmap/promptkit.md b/docs/roadmap/promptkit.md new file mode 100644 index 0000000..6400550 --- /dev/null +++ b/docs/roadmap/promptkit.md @@ -0,0 +1,139 @@ +# PromptKit Adoption Outline + +**Updated:** 2026-11-07 + +**Status:** Initial outline. Follow the [master roadmap](library-adoption.md) +for shared adoption principles, dependency identities, and sequencing. + +## Baseline and Target + +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. +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. +Expose native resource and configuration inspection through the full standard +ckprompt surface described in the [CommandKit outline](commandkit.md). + +PromptKit owns resources, composition, provider settings and credentials, +preparation, transport, structural repair, and backend admission. Audita owns +proposal/validation role selection, transcript processing, domain decisions, +response contracts, and truthful partial-success reporting. Review existing +application-only endpoint and credential restrictions against those boundaries. + +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). +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. + +## Agreed Direction and Migration Work + +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 and maintained operator examples/fixtures. + 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. Do not duplicate PromptKit's full resolver or construct synthetic + requests merely to reproduce the old profile summary. Inspect bundled and + unselected partial resources without requiring them to be runnable. +5. Adopt native credential precedence, including bundled OpenRouter environment + lookup. Migrate any retained application secret references deliberately; + do not blanket-clear library credential sources or reject a valid native + selection merely because it differs from today's Audita backend map. + 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 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. + +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. + +## Acceptance and Upstream Requests + +Verify native bundle inventory and selection, configuration/resource/prepared +view distinctions, inheritance and replacement, credential precedence, optional +fields, source-relative messages and collisions, and captured configuration. +Use controlled providers to verify actual targets, domain schemas, shared +admission, retry/repair budgets, cancellation, and partial success. Standard +inspection must work without model calls; library presence alone does not prove +successful Audita integration. + +No upstream request is yet selected. PromptKit is mature but pre-v1: significant +blockers or awkward public boundaries can justify focused requests. Submit the +minimal reproducer, desired outcome, and domain justification before building +substantial local machinery. A review probe demonstrated distinct base/derived +backend records preserving provider fields; that is an available native technique, +not a decision to retain Audita's old backend ownership model. + +## Open Decisions + +### Backend, Credential, and Admission Ownership + +**Recommendation:** make native PromptKit resources the authoritative backend +configuration and remove duplicate application registration/endpoint enforcement +unless a concrete processing requirement needs it. Keep Audita role selections +and operation budgets, and use native backend capacity settings for workloads. +This makes bundled profiles usable and avoids losing operator fields through a +highest-priority application replacement. Plan the existing backend/secret file +migration with the ConfigKit outline. + +The current architecture policy requires finite shared admission. Determine +whether that remains a domain requirement and how native configuration satisfies +it for bundled and custom selections. Do not silently reject the bundle, impose +an arbitrary cap, or weaken the policy during implementation. Any selected +exception needs a documented reason and an explicit policy update. + +**Alternative:** retain a narrow application capacity or credential policy and +express it through native derived backends/profiles. The probe shows this can +preserve provider fields while supplying application-owned fields. It is viable +if operational requirements demand it, but introduces naming/reference conventions +and can recreate duplicate ownership. Prefer an upstream facility if a justified +policy cannot be applied cleanly without replacing whole resources or resolver +logic. Blanket preservation of today's restrictions is not the selected default. + +### Existing Curated Profile Summary + +**Recommendation:** use standard resource inspection and prepared-request preview +for their distinct meanings; retire the old completed-profile summary unless a +specific Audita role summary remains useful. This avoids a parallel target resolver +and aligns operator expectations. + +**Alternative:** retain a small role-to-resource summary alongside the full native +commands. It helps transcript operators identify proposal and validation choices, +but must clearly describe resource values rather than implying completed request +settings. It adds maintenance and must not constrain native inspection.