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 version. Version 6 retains unrelated pipeline structure, discovery, and
resolution behavior. ConfigKit continues to own application loading and resolution behavior. ConfigKit continues to own application loading and
composition under [ADR-0020](../adr/0020-delegate-configuration-mechanics-to-configkit.md). 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 Retire `profile_file`, `profile_dir`, and `local_backend` in favor of native
native PromptKit main source. Resolve this selector relative to the Notarius PromptKit companion files. There is no separate `promptkit.config_file` selector.
file that declares it; leave imports and resource paths *inside* the selected Preserve the ability to override transport retries through the PromptKit engine
source to the upstream loader. Retire `profile_file`, `profile_dir`, and option; leave the upstream default in effect when the operator does not
`local_backend`: express related sources through native imports and local override it.
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.
Pass the selected main source and application asset underlay through one source ### Companion Files And Embedded Defaults
assembly used by runtime, preflight, and inspection. Use the bundled OpenRouter
underlay as supplied by PromptKit. That bundle is a different inventory from Adopt Audita's companion-file convention. Use the directory of the main
the former external catalogs and supplies no backend-local concurrency limit. Notarius configuration actually selected by ConfigKit, whether explicit or
It does not implicitly select a model for any Notarius request. Migrate discovered. Load the optional `prompts.yml` and recursive `.yml` and `.yaml`
deployments that use removed profiles or backends to intentionally selected files under `prompts/` beside it as one higher-priority operator underlay
native records. The application-wide LLM ceiling remains independent of using native ConfigKit imports. Do not add a working-directory fallback
backend-local settings. 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 ### 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 distinct inherited variants, and the new backend fallback semantics for
profile nulls. profile nulls.
The optional PromptKit source specification header is version 2; it is not the The optional PromptKit source specification header is version 2; it is not the
Notarius application version. Keep source-local message resolution and use Notarius application version. Do not translate legacy resource files,
native collections when deployments need namespaces. Do not translate synthesize aliases, or reconstruct old recursive same-ID overlays.
legacy resource files, synthesize aliases, or reconstruct old recursive
same-ID overlays.
Select prompts by ID alone and remove the obsolete PromptKit version selector Select prompts by ID alone and remove the obsolete PromptKit version selector
and metadata from Notarius's request, debug, and reconciliation identity and metadata from Notarius's request, debug, and reconciliation identity
plumbing. Review affected diagnostic fields and document deliberate changes. plumbing. Review affected diagnostic fields and document deliberate changes.
Retain logical workload IDs, including `dnd-extraction` and its current Keep the current local resource IDs and use their qualified forms in
explicit model/settings. Retain message roles, bytes, order, cache boundaries, 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. and intended output/repair behavior while changing the declaration format.
Keep module-owned asset selection and embedded filesystem contexts intact. Keep module-owned asset selection and embedded filesystem contexts intact.
Verify maintained private response schemas work under upstream's Verify maintained private response schemas work under upstream's
@@ -163,20 +183,25 @@ the existing retry policy.
## Migration And Verification ## Migration And Verification
Update the maintained minimal and complete D&D examples, including operator Update the maintained minimal and complete D&D examples to distinguish
profile inheritance, and document how to convert a directory deployment, embedded-only operation from companion configuration. Use separate example
declare a local backend, and replace an embedded prompt or profile. Explain directories if necessary to demonstrate those deployments independently.
retired catalog IDs, the changed profile report, and any new checkpoint cold Document how to move existing PromptKit sources into the companion layout
misses. Update the canonical configuration, CLI, operations, and integration or import them from it, declare a local backend, and replace or extend an
guides when behavior lands. Record the changed decisions about source embedded resource. Explain qualified IDs, retired catalog IDs, the changed
precedence and inspection in a successor to 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 [ADR-0019](../adr/0019-adopt-native-promptkit-configuration.md) rather than
rewriting its accepted decision text. Release preparation is separate. rewriting its accepted decision text. Release preparation is separate.
Verify the dependency graph and offline examples after the cutover. Use Verify the dependency graph and offline examples after the cutover. Use
focused behavior tests for the new format and intentional rejection of the focused behavior tests for the new format and intentional rejection of the
old one, native same-ID replacement and relative imports, and shared source old one, main-relative companion discovery, and native relative imports.
selection across preflight, inspection, and runtime. Exercise preparation, 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 generation, structural repair, and semantic retries through the maintained
fake-provider integration. Check that real message or target changes affect fake-provider integration. Check that real message or target changes affect
checkpoint reuse, and that session routing, cache controls, diagnostics, and 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 ## 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 ### How Far Offline Preflight Goes
**Recommendation:** Check that the captured configuration is valid and that **Recommendation:** Check that the captured configuration is valid and that