diff --git a/docs/roadmap/promptkit.md b/docs/roadmap/promptkit.md index 90a3421..1d5b73b 100644 --- a/docs/roadmap/promptkit.md +++ b/docs/roadmap/promptkit.md @@ -84,6 +84,37 @@ the affected policies and current contracts with implementation. The ConfigKit outline still owns decisions about file locations, discovery, and imports; those choose how native resources are supplied, not who owns their semantics. +### Bundled Prompts and Operator Replacements — Resolved + +Ship Audita's production default prompt definitions in `embed.FS`, exposed as +`io/fs.FS`. Load them through PromptKit's filesystem inputs into a ConfigKit +underlay, with operator sources at higher priority. Using the shipped prompts +must not require a separate external prompt installation. + +Place all Audita-owned default prompts in the native `audita` collection +namespace. Keep local IDs such as `modules.glossary.proposal`; callers use the +qualified runtime ID `audita/modules.glossary.proposal`. Update registry entries, +call sites, references, examples, and diagnostics accordingly. Mounting a source +does not rewrite references, so qualified references must be explicit. + +Operators may replace individual prompts or supply a complete replacement set +by defining the same collection and local IDs in higher-priority sources. +Unreplaced prompts continue to come from the underlay. Follow native whole-record +replacement semantics for matching IDs and document the required complete prompt +definitions. The namespace identifies Audita's prompts without making them +immutable or requiring a separate development mode. + +The development workflow is edit external definitions and rerun Audita using the +same binary. A newly constructed runtime captures the changed definitions and +message files; live reload within an active run is not required. The same +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 remains part of the ConfigKit discovery/import +decision. This workflow is required PromptKit adoption scope and should use +native composition rather than a separate prompt loader or override system. + ### Migration Work 1. Move to `go.maximumdirect.net/promptkit` together with ConfigKit's new types. @@ -95,7 +126,8 @@ choose how native resources are supplied, not who owns their semantics. 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. +3. Convert the seven embedded prompts into the `audita` collection and update + maintained operator examples/fixtures for the resolved replacement workflow. 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; @@ -158,6 +190,15 @@ failures and optional unauthenticated execution under native semantics. Check 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. +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. + 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