diff --git a/docs/roadmap/commandkit.md b/docs/roadmap/commandkit.md index 1a463b0..3f82a45 100644 --- a/docs/roadmap/commandkit.md +++ b/docs/roadmap/commandkit.md @@ -266,7 +266,10 @@ released dependency set when implementing this outline. 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 + 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. @@ -308,6 +311,12 @@ 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. +Verify that automatic prompt replacements and their origins agree between +processing, resource/configuration inspection, and request preview. Apply the +shared loader's source selection to validation and smoke commands as well, using +controlled provider boundaries for smoke acceptance. Inspection must retain the +same source behavior without requiring processing inputs or starting preflight. + Verify that the completion summary and created artifact locations appear only in verbose/debug diagnostics, never in transcript stdout. Reject quiet processing with a stdout destination; requested file outputs remain enabled in valid quiet diff --git a/docs/roadmap/configkit.md b/docs/roadmap/configkit.md index 66cab1c..136ebdc 100644 --- a/docs/roadmap/configkit.md +++ b/docs/roadmap/configkit.md @@ -45,8 +45,9 @@ instructing operators to change the version number. ### Discovery Locations and Import Selection — Resolved -An explicit `--config` selects exactly that file. A missing, inaccessible, or -invalid explicit file is an error; do not fall back to discovery. +For Audita's main application configuration, an explicit `--config` selects +exactly that file. A missing, inaccessible, or invalid explicit file is an error; +do not fall back to discovery. Without an explicit file, search in this order using ConfigKit's native presets and filename rules with application name `audita`: @@ -66,6 +67,12 @@ higher-priority override layers. Missing optional imports may be absent; operators use `required: true` for essential inputs. Invalid declarations, unreadable selected files, and composition conflicts retain native errors. +The PromptKit outline owns [automatic prompt sources](promptkit.md#automatic-prompt-sources--resolved). +Those resource imports compose in the engine's operator underlay independently +of main application-file selection, using the same native import semantics. +Keep application configuration discovery and PromptKit resource acquisition +distinct while sharing their supported ConfigKit mechanisms. + ### No Configuration File Found — Resolved Use ConfigKit's optional-search behavior when automatic discovery finds no file: @@ -116,7 +123,8 @@ file remain terminal. 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. + 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 @@ -170,6 +178,8 @@ integration. Verify that discovery exhaustion permits inspection and sufficientl configured processing, while incomplete processing reports its missing inputs. Cover absent-main provenance and filesystem context for selected overlays or relative resources without weakening explicit-file error behavior. +Verify that application main-file selection and exhaustion preserve the separate +automatic PromptKit source context and precedence specified in its outline. Verify acceptance of the final version-3 schema and rejection of obsolete application versions. Check that no-main-file loading uses version-3 defaults, diff --git a/docs/roadmap/library-adoption.md b/docs/roadmap/library-adoption.md index b447356..ae3a1da 100644 --- a/docs/roadmap/library-adoption.md +++ b/docs/roadmap/library-adoption.md @@ -151,7 +151,9 @@ implemented and accepted in Audita. 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. + 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.** diff --git a/docs/roadmap/promptkit.md b/docs/roadmap/promptkit.md index ecfe105..d818cd3 100644 --- a/docs/roadmap/promptkit.md +++ b/docs/roadmap/promptkit.md @@ -1,8 +1,9 @@ # PromptKit Adoption Outline -**Updated:** 2026-11-07 +**Updated:** 2026-11-09 -**Status:** Initial outline. Follow the [master roadmap](library-adoption.md) +**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. ## Baseline and Target @@ -81,8 +82,9 @@ checks whose purpose was enforcing the removed application backend registry. Remove superseded fields, code, and tests in the major-release cutover and update the affected policies and current contracts with implementation. The ConfigKit -outline owns file discovery and import policy; those choices govern how native -resources are supplied, not who owns their semantics. +outline owns Audita main-file discovery and general import policy; this outline +owns the automatic PromptKit source selection below. PromptKit retains resource +semantics under both policies. ### Bundled Prompts and Operator Replacements — Resolved @@ -111,9 +113,69 @@ mechanism supports production customization. Standard inspection, provenance, and request preview must make effective prompts and their origins understandable. Audita's response schemas and domain validation continue to apply. -External source selection follows the [ConfigKit discovery/import plan](configkit.md). -This workflow is required PromptKit adoption scope and should use -native composition rather than a separate prompt loader or override system. +External source selection follows the [automatic source contract below](#automatic-prompt-sources--resolved), +using the [ConfigKit import policy](configkit.md#discovery-locations-and-import-selection--resolved). +This workflow is required PromptKit adoption scope and uses native composition. + +### Automatic Prompt Sources — Resolved + +Automatically compose optional `./prompts.yml` and YAML files recursively under +`./prompts/`. Both locations are relative to the invocation's working directory, +independent of the selected Audita configuration file's location. The same +loading applies when no main application configuration file is found. + +Supply one operator-source underlay with these native ConfigKit imports: + +```yaml +config: + imports: + - path: prompts.yml + required: false + - dir: prompts + required: false + recursive: true + pattern: ["*.yml", "*.yaml"] +``` + +Enable imports and provide the declaration's host filesystem context through +ConfigKit's public input APIs, rooted at the invocation's working directory. +Keep this host context separate from the embedded prompt filesystem. ConfigKit +owns traversal, composition, inheritance, and provenance; do not add an Audita +directory walker, YAML parser, or replacement mechanism. + +Compose the engine's layers from lowest to highest priority: + +1. PromptKit's default-on bundled OpenRouter catalog. +2. Audita's embedded `audita` prompt underlay. +3. The operator-source underlay containing both automatic imports. + +Load both automatic locations when present. Missing optional sources contribute +nothing; present but unreadable, invalid, or conflicting sources retain native +errors. The file and directory compose as strict peers within one tier. Neither +gains priority from declaration, filename, or discovery order; duplicate resource +identities in that tier are errors. At the boundary above embedded defaults, +native same-ID replacement replaces the complete matching record while retaining +unmatched defaults. Follow the upstream +[source and profile precedence](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/docs/formats.md#source-and-profile-precedence). + +Use native PromptKit documents at the document root, with namespaces and IDs +declared in their content. Each file may define one or several resources, +including supported profiles and backends. Filenames and subdirectories do not +assign identities or namespaces. Replacing an Audita prompt uses the same +`collections.audita` namespace and local prompt ID as its embedded definition, +as specified above; no source-selector setting is required. + +Operators can use `prompts.yml` for definitions or as a manifest importing shared +libraries elsewhere, and organize local definitions beneath `prompts/`. Nested +imports and prompt `content_file` references retain native source-relative +handling. Avoid importing the automatically discovered directory again from the +manifest; repeated inclusion within the tier retains ConfigKit's native error. + +Use one shared engine-loading path for processing, configuration/resource +inspection, request preview, validation, and smoke commands. All must observe +the same layers and captured definitions for the same invocation inputs. +`--config` continues to select Audita's application configuration; it does not +change the working-directory base of these automatic resource imports. ### Profile Inspection and Summary — Resolved @@ -143,6 +205,8 @@ surface and request-preview integration work. 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; @@ -168,8 +232,9 @@ surface and request-preview integration work. 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. + 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, @@ -207,13 +272,23 @@ that no application override layer or direct-key injection defeats native precedence, and that synthetic keys stay out of Audita diagnostics and artifacts. Verify the embedded `audita` prompts work without external prompt definitions. +Cover both automatic locations absent, each present alone, and both present with +distinct resources, including nested YAML files. Exercise missing optional +sources, unreadable/invalid sources, and same-tier identity conflicts through +native loading. Confirm that an explicit application config elsewhere and absent +main-file discovery both retain the invocation working directory as the automatic +source base. Check manifest imports of shared libraries and source-relative +message files, with provenance and consumed-source collision protection intact. Exercise both individual-prompt and complete-set replacements using native collection IDs, checking that unreplaced defaults remain available. Demonstrate that editing external prompt/message files changes a newly constructed runtime's prepared request without rebuilding the binary, while the existing runtime keeps its captured inputs. Check qualified-ID selection, effective prompt inspection, source provenance, and continued response-schema and domain validation with -controlled responses. Include a maintained edit-and-rerun example for developers. +controlled responses. Verify that processing and standard inspection/preview use +the same effective replacements and that the bundled catalog remains available. +Include a maintained edit-and-rerun example using the automatic sources, without +requiring a source-selector setting or binary rebuild. Verify that role selections are visible in application configuration inspection, resources through standard inspection, and completed request settings through