From 1777821e8b9f0448bafba983a0996714e4cf4551 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 3 Oct 2026 17:49:14 +0000 Subject: [PATCH] Record the agreed PromptKit configuration scope --- docs/roadmap/promptkit.md | 79 +++++++++++++++------------------------ 1 file changed, 31 insertions(+), 48 deletions(-) diff --git a/docs/roadmap/promptkit.md b/docs/roadmap/promptkit.md index 0a48b23..260c7d3 100644 --- a/docs/roadmap/promptkit.md +++ b/docs/roadmap/promptkit.md @@ -2,8 +2,9 @@ **Last updated:** 2026-10-03 -**Status:** Proposed. The configuration-source scope decision at the end of -this document should be resolved before preparing the implementation plan. +**Status:** Accepted target scope; ready for implementation planning. The +operator-directory scope decision has been resolved. Implementation has not +begun. ## Purpose and Baseline @@ -54,8 +55,9 @@ own the upstream details. main-file-relative `profiles_dir` resolution remain in place. - Native profile `extends`, field-presence semantics, and source-relative resource rules apply. Documents can contain multiple definitions, and IDs - come from mapping keys rather than filenames. Operator-directory scope is - subject to the open decision below. + come from mapping keys rather than filenames. The existing `profiles_dir` + accepts native unified PromptKit documents containing profiles, backends, + and prompts, including intentional operator prompt overrides. - Application backend endpoints, configured concurrency and queue capacity, and credential ownership remain authoritative for selected roles. Preserve the existing profile-selection and prepared-target checks; do not introduce @@ -100,10 +102,18 @@ registration, endpoint, capacity, or credential requirements. Catalog profile contents may evolve; this upgrade does not promise fixed model choices or live provider availability. -The proposed caller order is embedded Audita prompts, operator definitions, -then application backend settings. Whether operator definitions may include -prompts and backends is an open product decision; that order is a recommendation, -not authorization to add prompt overrides before the decision is resolved. +The accepted caller order is embedded Audita prompts, operator definitions, +then application backend settings. The existing `profiles_dir` accepts native +unified PromptKit documents containing profiles, backends, and prompts. Keep +the name and path setting for continuity, and document its broader accepted +content. This follows the upstream source API without a parallel parser or +top-level filtering. Profiles, provider defaults, and intentional prompt +overrides use the same native composition model. + +Audita continues to ship its domain prompts, enforce its selected-backend +requirements, and supply its per-call schemas. Operator prompt overrides are +an accepted capability of this adoption; documentation, source accounting, +and focused behavioral coverage should reflect them. ## Work Required @@ -127,10 +137,9 @@ Adapt source accounting to the new discovery/capture boundary. The existing recording filesystem wrapper may be replaceable with discovered inputs or upstream source metadata. Protect the host sources actually consumed by the runtime, including inherited and differently named definitions, without -guessing filenames from selected profile IDs. If operator prompt resources are -approved, account for their consumed message files as well. Keep this -proportionate to the existing collision contract; do not add filesystem -concurrency or power-loss guarantees. +guessing filenames from selected profile IDs. Account for consumed operator +message files as well. Keep this proportionate to the existing collision +contract; do not add filesystem concurrency or power-loss guarantees. Keep the existing safe effective-profile summaries and application explanations. Use upstream metadata where useful, but do not expose the full @@ -166,10 +175,12 @@ without requiring every maintained example to use it. ### Documentation, Migration, and Attribution Update the profile section of `docs/config.md` and maintained examples when the -implementation lands. Explain keyed identities, composition versus precedence, -profile inheritance, presence, eager final-definition validation, selected-root -errors, and captured configuration. Link to the pinned upstream reference for -generic field semantics rather than reproducing its entire contract. +implementation lands. Explain the broader accepted content of `profiles_dir`, +operator prompt overrides and their precedence, keyed identities, composition +versus precedence, profile inheritance, presence, eager final-definition +validation, selected-root errors, and captured configuration. Link to the pinned +upstream reference for generic field semantics rather than reproducing its +entire contract. Include operator migration guidance for old profile documents and behaviorally significant zeros/nulls. This is a deliberate format migration, not an automatic @@ -208,6 +219,9 @@ distinct risk. Completion means: - Representative keyed profiles, native inheritance, and explicit presence work through the real runtime. Directory conflicts and invalid final definitions produce useful startup errors without filename-derived identity assumptions. +- Operator prompt and backend contributions follow the accepted source order; + prompt overrides render while Audita retains its per-call schemas and + authoritative application backend settings. - Source collision protection, safe inspection, and operator-versus-asset error classification remain effective at the changed construction boundary. - Representative prepared execution, schema repair, transient retry, and @@ -220,35 +234,4 @@ No live provider calls, new release gates, or CI-success dependency are needed to establish adoption. Guided domain recovery and the other work recorded in [future.md](future.md) remain separate features. Do not expand this upgrade into new report formats, pipeline scheduling, or general configuration-inspection -commands. A staged implementation plan can be prepared after the decision below. - -## Open Decisions - -### Scope of the Operator Configuration Directory - -**Recommendation:** Accept native unified PromptKit documents in the existing -`profiles_dir`, with embedded prompts below operator definitions and application -backend settings above them. Keep the name/path setting for continuity, while -documenting its broader accepted content. This follows the upstream source API -without a parallel parser or arbitrary top-level filtering. It allows profiles, -provider defaults, and intentional prompt overrides to use the same native -composition model. Audita would still ship its domain prompts, enforce its -selected-backend requirements, and supply its per-call schemas. Prompt overrides -would be an intentional new operator capability and need focused documentation -and tests, including resource source accounting; they should not arrive silently. - -**Viable alternative:** Keep this directory profile-only and retain embedded -prompt ownership as the existing operator boundary. This narrows the migration -to profile format and engine assembly, avoids adding prompt customization during -a dependency upgrade, and makes the current directory name accurate. It requires -an explicit contribution-scope check using the libraries' public configuration -facilities, rather than another YAML parser or inheritance engine. Do not also -impose one-profile-per-file, filename/ID equality, or new profile-field -restrictions. The cost is an Audita-specific constraint on a now-unified source -API and continuing maintenance of that boundary. If the public API cannot -express the check simply, reassess the tradeoff or request narrow upstream -support rather than building a general projection layer. - -Either choice can preserve the existing execution workflow. The decision is -whether this adoption should deliberately open operator prompt/backend -contributions; changing the source API by itself does not settle that policy. +commands. A staged implementation plan can now be prepared.