Record the agreed PromptKit configuration scope

docs/roadmap/promptkit.md

@@ -2,8 +2,9 @@
 
 **Last updated:** 2026-10-03
 
-**Status:** Proposed. The configuration-source scope decision at the end of
+**Status:** Accepted target scope; ready for implementation planning. The
-this document should be resolved before preparing the implementation plan.
+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
+  come from mapping keys rather than filenames. The existing `profiles_dir`
-  subject to the open decision below.
+  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,
+The accepted caller order is embedded Audita prompts, operator definitions,
-then application backend settings. Whether operator definitions may include
+then application backend settings. The existing `profiles_dir` accepts native
-prompts and backends is an open product decision; that order is a recommendation,
+unified PromptKit documents containing profiles, backends, and prompts. Keep
-not authorization to add prompt overrides before the decision is resolved.
+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
+guessing filenames from selected profile IDs. Account for consumed operator
-approved, account for their consumed message files as well. Keep this
+message files as well. Keep this proportionate to the existing collision
-proportionate to the existing collision contract; do not add filesystem
+contract; do not add filesystem concurrency or power-loss guarantees.
-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,
+implementation lands. Explain the broader accepted content of `profiles_dir`,
-profile inheritance, presence, eager final-definition validation, selected-root
+operator prompt overrides and their precedence, keyed identities, composition
-errors, and captured configuration. Link to the pinned upstream reference for
+versus precedence, profile inheritance, presence, eager final-definition
-generic field semantics rather than reproducing its entire contract.
+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.
+commands. A staged implementation plan can now be prepared.
-
-## 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.