Use PromptKit companion files and namespaced defaults

This commit is contained in:
2026-11-18 15:21:56 +00:00
parent fe44b12073
commit 63e26dc203

View File

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