diff --git a/docs/roadmap/promptkit.md b/docs/roadmap/promptkit.md index 4e6850ec..3f2d6596 100644 --- a/docs/roadmap/promptkit.md +++ b/docs/roadmap/promptkit.md @@ -59,23 +59,39 @@ Introduce application configuration version 6 as the only supported application version. Version 6 retains unrelated pipeline structure, discovery, and resolution behavior. ConfigKit continues to own application loading and composition under [ADR-0020](../adr/0020-delegate-configuration-mechanics-to-configkit.md). -The proposed operator seam is an optional `promptkit.config_file` pointing to a -native PromptKit main source. Resolve this selector relative to the Notarius -file that declares it; leave imports and resource paths *inside* the selected -source to the upstream loader. Retire `profile_file`, `profile_dir`, and -`local_backend`: express related sources through native imports and local -endpoints through native backend records. Preserve the ability to override -transport retries through the PromptKit engine option; leave the upstream -default in effect when the operator does not override it. +Retire `profile_file`, `profile_dir`, and `local_backend` in favor of native +PromptKit companion files. There is no separate `promptkit.config_file` selector. +Preserve the ability to override transport retries through the PromptKit engine +option; leave the upstream default in effect when the operator does not +override it. -Pass the selected main source and application asset underlay through one source -assembly used by runtime, preflight, and inspection. Use the bundled OpenRouter -underlay as supplied by PromptKit. That bundle is a different inventory from -the former external catalogs and supplies no backend-local concurrency limit. -It does not implicitly select a model for any Notarius request. Migrate -deployments that use removed profiles or backends to intentionally selected -native records. The application-wide LLM ceiling remains independent of -backend-local settings. +### Companion Files And Embedded Defaults + +Adopt Audita's companion-file convention. Use the directory of the main +Notarius configuration actually selected by ConfigKit, whether explicit or +discovered. Load the optional `prompts.yml` and recursive `.yml` and `.yaml` +files under `prompts/` beside it as one higher-priority operator underlay +using native ConfigKit imports. Do not add a working-directory fallback +for companion discovery. Configurations in the same directory share those +companions. Missing companions are fine; loading errors follow upstream +semantics rather than silently falling back to embedded assets. Native +imports and source-relative resource paths govern any files reached from the +companions. The two companion locations are strict peers; filenames do not +set precedence between conflicting operator records. + +Use one source assembly for runtime, preflight, and inspection: PromptKit's +bundled OpenRouter underlay, Notarius's embedded underlay, then the operator +underlay when present. Embed all Notarius default prompts and profiles under +`collections.notarius` in the application underlay. Operator companion files +can replace individual defaults by defining complete records with the same +local IDs in that same collection. They can also define new resources and +local backends using the native format. + +The bundled OpenRouter inventory differs from the former external catalogs +and supplies no backend-local concurrency limit. It does not implicitly +select a model for any Notarius request. Migrate deployments that use removed +profiles or backends to intentionally selected native records. The +application-wide LLM ceiling remains independent of backend-local settings. ### Native Prompt And Profile Resources @@ -86,16 +102,20 @@ record replaces the earlier record in full. Explain complete replacements, distinct inherited variants, and the new backend fallback semantics for profile nulls. The optional PromptKit source specification header is version 2; it is not the -Notarius application version. Keep source-local message resolution and use -native collections when deployments need namespaces. Do not translate -legacy resource files, synthesize aliases, or reconstruct old recursive -same-ID overlays. +Notarius application version. Do not translate legacy resource files, +synthesize aliases, or reconstruct old recursive same-ID overlays. Select prompts by ID alone and remove the obsolete PromptKit version selector and metadata from Notarius's request, debug, and reconciliation identity plumbing. Review affected diagnostic fields and document deliberate changes. -Retain logical workload IDs, including `dnd-extraction` and its current -explicit model/settings. Retain message roles, bytes, order, cache boundaries, +Keep the current local resource IDs and use their qualified forms in +lookups and references, for example `notarius/dnd.spells` and +`notarius/dnd-extraction`. Update prompt profile references, application +profile selections, and inspection examples to use the qualified IDs. +The `dnd-extraction` profile retains its current model and settings and +continues to reference the unqualified bundled `openrouter` backend. A +profile that extends it belongs in the same collection and uses its local +sibling ID in `extends`. Retain message roles, bytes, order, cache boundaries, and intended output/repair behavior while changing the declaration format. Keep module-owned asset selection and embedded filesystem contexts intact. Verify maintained private response schemas work under upstream's @@ -163,20 +183,25 @@ the existing retry policy. ## Migration And Verification -Update the maintained minimal and complete D&D examples, including operator -profile inheritance, and document how to convert a directory deployment, -declare a local backend, and replace an embedded prompt or profile. Explain -retired catalog IDs, the changed profile report, and any new checkpoint cold -misses. Update the canonical configuration, CLI, operations, and integration -guides when behavior lands. Record the changed decisions about source -precedence and inspection in a successor to +Update the maintained minimal and complete D&D examples to distinguish +embedded-only operation from companion configuration. Use separate example +directories if necessary to demonstrate those deployments independently. +Document how to move existing PromptKit sources into the companion layout +or import them from it, declare a local backend, and replace or extend an +embedded resource. Explain qualified IDs, retired catalog IDs, the changed +profile report, and any new checkpoint cold misses. Update the canonical +configuration, CLI, operations, and integration guides when behavior lands. +Record the changed decisions about source precedence and inspection in a +successor to [ADR-0019](../adr/0019-adopt-native-promptkit-configuration.md) rather than rewriting its accepted decision text. Release preparation is separate. Verify the dependency graph and offline examples after the cutover. Use focused behavior tests for the new format and intentional rejection of the -old one, native same-ID replacement and relative imports, and shared source -selection across preflight, inspection, and runtime. Exercise preparation, +old one, main-relative companion discovery, and native relative imports. +Verify that a companion can replace a qualified embedded prompt or profile +without changing unrelated defaults, and that preflight, inspection, and +runtime use the same effective definitions. Exercise preparation, generation, structural repair, and semantic retries through the maintained fake-provider integration. Check that real message or target changes affect checkpoint reuse, and that session routing, cache controls, diagnostics, and @@ -190,20 +215,6 @@ for deployment confidence, not a requirement of the offline suite. ## Open Decisions -### Operator Source Selection - -**Recommendation:** Expose one optional native main-file selector. It gives -operators a single entry point for native file and directory imports, -collection mounting, and relative resource resolution, while keeping source -composition out of Notarius. - -**Alternative:** Expose an explicit list of file or directory inputs assembled -into native PromptKit source groups. This is useful if a caller must select -independent inputs without owning a common entry file. It also requires -Notarius to define group ordering, path resolution, and precedence for a -second composition surface. Prefer the main file unless that workflow is -needed. - ### How Far Offline Preflight Goes **Recommendation:** Check that the captured configuration is valid and that