Specify automatic PromptKit source discovery

This commit is contained in:
2026-11-09 15:49:42 +00:00
parent 866e4b9b23
commit 4920393204
4 changed files with 111 additions and 15 deletions

View File

@@ -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