From 79088a354624cdeefeed92d317c4e5ce37addb8b Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 17 Nov 2026 20:35:04 +0000 Subject: [PATCH] Plan the ConfigKit native configuration upgrade --- docs/roadmap/configkit.md | 5 +- docs/roadmap/implementation.md | 987 +++++++++++---------------------- 2 files changed, 336 insertions(+), 656 deletions(-) diff --git a/docs/roadmap/configkit.md b/docs/roadmap/configkit.md index 802eea2c..dcb66c89 100644 --- a/docs/roadmap/configkit.md +++ b/docs/roadmap/configkit.md @@ -13,8 +13,9 @@ v1.2.1 and stable go-yaml v4.0.0 belong to the subsequent PromptKit upgrade. [ADR-0020](../adr/0020-delegate-configuration-mechanics-to-configkit.md) owns the boundary: ConfigKit delivers the final resolved application document; Notarius supplies application schema, defaults, normalization, validation, and subsequent -pipeline resolution. This roadmap defines the target and required work. A later -implementation plan will own sequencing. Release publication is separate work. +pipeline resolution. This roadmap defines the target and required work. The +[implementation plan](implementation.md) owns sequencing and stage verification. +Release publication is separate work. ## Reviewed Baseline And Sources diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 082ef6b3..1d028710 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,782 +1,461 @@ -# PromptKit 0.12 Implementation Plan +# ConfigKit 1.2.0 Implementation Plan -## Purpose And Baseline +## Scope And Working Rules -Implement [PromptKit 0.12 Configuration Migration](promptkit.md). That roadmap -owns the accepted target state; this document owns implementation decisions, -ordered steps, and verification. It replaces the completed ConfigKit plan. -Each numbered stage is one bounded prompt for a Luna coding agent. Execute in -order, inspecting the named code and tests before editing. +Implement [the feature roadmap](configkit.md), whose approved choices govern +this plan. The baseline is `2c8b631`: old-path ConfigKit v0.5.0, PromptKit +v0.12.0, Go 1.25.5, and YAML v4.0.0-rc.6. Target new-path ConfigKit v1.2.0 at +`c1c7e87f2cdf77a0cbf3327831ac05578e756b9e`, Go minimum 1.27.0, and the same +PromptKit/YAML versions. Use `git show v1.2.0:` in `../ConfigKit` for pinned +guidance; its moving checkout may contain v1.2.1's incompatible YAML changes. -The starting revision is `aae01a5`: ConfigKit v0.5.0, PromptKit v0.11.2, and -Notarius configuration version 5. Target PromptKit v0.12.0 at full commit -`4b8169da286917fde7875425bb32b799b12c6af3`, with its selected OpenRouter and -Rakestrawhome `/v3` catalogs at `v3.20260930.0`. ConfigKit and Go remain at the -existing v0.5.0 and 1.25.5 baselines. Inspect released source, not a moving -sibling branch. Use `git show v0.12.0:` in `../promptkit` where helpful; -the annotated tag's source commit is `v0.12.0^{commit}`. +During planning, the configuration, CLI, and LLM suites passed with the existing +Go 1.25.5 graph. No upgraded-graph trial was performed; these baseline results +do not establish compatibility with the target dependencies. -The focused LLM, CLI, and module-integration baseline tests passed during -planning. This is not evidence that the upgraded implementation passes. +Each numbered stage is one prompt for Luna, executed in order in a single +end-to-end sprint. Intermediate revisions may fail compilation or tests. Record +those failures and continue with the owning stage; avoid transitional parsers, +type-translation layers, or duplicate machinery just to keep intermediate +commits green. Completion requires all stages and the final acceptance checks. -## Instructions For Every Stage +For every stage: -- Read `docs/development.md`, `docs/policy/agents.md`, and the feature roadmap. - Select applicable architecture, testing, documentation, and OSS policies. - Prefer the code knowledge graph for code discovery. Reuse unchanged policy - context; do not read unrelated policies merely to fill a checklist. -- Use `GOWORK=off` for Go commands. No local dependency `replace`, fork, - legacy-format parser, whole-profile replacement shim, section whitelist, - custom inheritance engine, or filename-priority merger belongs here. -- Keep upstream configuration types in the LLM integration boundary. Modules - retain transport-neutral requests, typed outputs, and asset ownership. The - root `assets` Go package remains content-only. -- Preserve prompt text/order, identities, schema contents, retry budgets, - sessions, reasoning overrides, warnings, scheduling, and artifact/subprocess - contracts. Deliberately update tests for accepted configuration-format, - recursive-overlay, and eager-validation changes, not unrelated expectations. -- Use real loading and offline injected clients or local HTTP fixtures. Add - narrowly owned behavioral tests for actual risks; reuse existing coverage. - Do not mirror the complete upstream suite, snapshot long errors/reports, or - introduce exact shared-prefix-length detector tests. -- Keep credentials and live inference out of default tests. Do not add new - permission enforcement, credential requirements, publication gates, or source - restrictions. Fix actual regressions rather than weakening coverage. -- Review the diff, validate, and commit each nonempty coherent stage with a - plain-English message under agent policy. No empty commits. Record actual - checks and remaining work; do not call the upgrade complete before Stage 15. - Do not push, tag, retire other roadmaps, or publish. +- Read `docs/development.md`, `docs/policy/agents.md`, the feature roadmap, and + applicable architecture/testing/documentation/OSS/release policies. Reuse + unchanged context. Prefer the code graph for discovery. +- Keep ConfigKit responsible for source mechanics and final inspection, per + ADR-0020. Notarius owns application rules and runtime pipeline resolution. +- Preserve configuration version 5, artifact/subprocess contracts, LLM behavior, + cache permissions, and existing retry/scheduling policy. Native composition, + discovery, CLI ordering, and control syntax intentionally change. +- Use `GOWORK=off`. Keep dependencies released and selected through ordinary Go + module resolution. ConfigKit v1.2.1, stable YAML, PromptKit migration, release + publication, and unrelated remediation findings are outside this sprint. +- Test real loading with temporary files. Keep tests offline and credential-free; + inject only external LLM/HTTP boundaries. Reuse coverage instead of mirroring + the entire upstream suite or snapshotting incidental diagnostics. +- Review the diff and commit nonempty units under agent policy. Record actual + validation and deferred checks. No empty commits, pushing, tagging, roadmap + retirement, or changes to accepted ADR bodies. -### Bounded Migration Window +## Settled Implementation Details -The new format and removed APIs are incompatible with the old integration. -Stages 1–5 divide that migration into small prompts. Intermediate revisions -can have expected format/test-compilation failures. Record them precisely; -do not add dual-version machinery to keep every intermediate revision green. -Native application compilation must be restored by Stage 3, the LLM suite by -Stage 4, and the full default suite by Stage 5. Do not deploy intermediate -revisions. Later stages use focused passing checks before committing. +### Package Identity And Loading Handoff -## Settled Implementation Decisions +Application configuration and CLI configuration overrides/diagnostics use +`go.maximumdirect.net/configkit` v1.2.0. PromptKit v0.12.0's source helpers and +inspection continue to use `gitea.maximumdirect.net/eric/ConfigKit` v0.5.0 inside +the LLM adapter and direct integration fixtures. These named types are distinct. +Do not globally replace imports or pass a new-package path/source to old PromptKit. -### Sources And Engine Ownership +Keep `config.Load(path, options)` as an exclusive file convenience. Add +`config.LoadSource(source configkit.Source, options LoadOptions)` for a +production source supplied by the composition boundary, with imports enabled. +Both reach the same definition/callback/load path. Private byte/reader test +helpers may retain their existing explicit import choice. This configuration +package is the explicit ConfigKit integration boundary; upstream values stay +out of runtime pipeline/module contracts. -Build the same source stack for execution, preflight, and inspection: +The CLI selects a source without filesystem probes: -1. Upstream catalogs and PromptKit-owned definitions, supplied by PromptKit. -2. One application underlay containing registered prompt and fallback-profile - inputs, each retaining its own filesystem context. -3. One operator underlay from the selected file or recursively selected - directory. Set `Input.Imports = true` on operator inputs only. Accept native - combined `profiles`, `backends`, and `prompts` documents. -4. A final programmatic underlay for `backends.local` when Notarius's - `local_backend` is configured. Use `BackendSource` with - `LocalBackend(endpoint, concurrencyLimit)` to preserve explicit zero. +1. Trim a nonblank `--config` value and use `File` exclusively. +2. Otherwise use a nonblank `NOTARIUS_CONFIG` via the existing injected + `LookupEnv`, selecting `File` exclusively. +3. Otherwise construct `SearchConfig("notarius", Searches(WorkingDirectory(), + UserConfigDirectory(), UnixSystemDirectories()), SearchOptions{Required:true})`. -Leave `Sources.Main` nil. Use `FilesystemInputs` for embedded views, -`DirectoryInputs` for a directory, and -`configkit.Input{Source: configkit.File(path), Imports: true}` for one file. -Provide native filesystem resource context where necessary. File sources -derive their declaring directory; directory inputs retain the helper's root. -Do not make host files and embedded resources share an artificial root. -Native imports, root rules, and exact-key inheritance remain upstream behavior. +Pass that source into `LoadSource` exactly once. Add a neutral +`LoadedConfig.MainSourcePath()` accessor based on retained sources: select the +non-imported main file (`LayerMain`, `SourceKindFile`, nil `ImportedFrom`). Return +its recorded path, or empty for a non-file private/programmatic load. Do not +infer the main file from source IDs, a particular field's surviving origin, or +another filesystem search. Keep `loadConfigKit`'s selected-path string return +and populate it from this accessor. Debug/invocation provenance then describes +the actual selected main. Its existing flag/discovered category need not expand. -Sources in a group compose strictly; later groups overlay fields recursively. -Missing selected sources fail; empty selected directories contribute nothing. -No operator source means no operator group. Nil optional assets on the existing -profile inspector mean no application group; production supplies registered -assets. Preserve the client's required-assets check. Keep `WithSchemaFS` and -injected runtime options separate from definition sources. Register no catalog -backend manually. +Native search filename groups, missing-candidate behavior, selected-file failure, +and directory-helper timing remain upstream behavior. WorkingDirectory searches +`notarius.yml`, then `notarius.yaml`; generic filenames belong only to the +presets that include them. HomeDirectory is not added. Files are selected, not +automatically layered. NoSource remains a separate explicit programmatic choice. -### CLI Inspection Contract +### Native Collections And Application Resolution -Implement these commands, with flags before positional selectors as in the -current Go flag parser: +Register precisely this identity on the application definition: -```sh -notarius config effective --scope promptkit [--config path] [--config-overlay name] -notarius config explain --scope promptkit [--config path] [--config-overlay name] -notarius config profile [--config path] [--config-overlay name] +```go +configkit.SequenceIdentityMatching(configkit.SequenceSelector{ + configkit.SequenceLiteralKey("pipelines"), + configkit.SequenceAnyMappingKey(), + configkit.SequenceLiteralKey("steps"), +}, "id") ``` -For effective/explain, omitted `--scope` or `--scope notarius` preserves the -current report and avoids constructing a PromptKit engine. Accept only -`notarius` and `promptkit`; explicit blank/unknown scope is a syntax error. -`config profile` inspects PromptKit only and needs no scope flag. Add no input, -pipeline selection, model override, or second source flag to these commands. -Load the selected Notarius configuration, use its normalized PromptKit sources -plus production assets, and inspect one engine without resolving a pipeline or -materializing references. +Use native upsert by default for those identified lists. A matching step is +replaced as a whole, not field-merged; order and clearing follow native rules. +Source authors may select replace/append explicitly and declare identities for +other lists. Do not register validator chains or infer identities elsewhere. +Application validation still checks actual domain constraints after resolution. -Effective output is upstream redacted YAML; explanation output is upstream -human-readable history. Profile output is one Notarius-owned JSON object plus -newline with `profile_id`, `api_key_required`, and `effective_model_params`. -The last object uses the upstream target's lower-case field vocabulary: -`backend_id`, `endpoint`, `model`, `temperature`, `max_tokens`, `top_p`, -`timeout_seconds`, `service_tier`, `reasoning_effort`, `api_key_env`, and -`extra_params`. Include empty `backend_id` for endpoint-only profiles. Copy -fields into a local DTO; do not publish the upstream `ProfileInspection` Go -struct as the CLI contract. These are inspected settings, not provider-default -predictions. Zero sampling values alone do not distinguish omission from -explicit zero; effective/explanation reports supply presence context. +Leave import defaults and source-version mode at native defaults. Maintained +required fragments say `required: true`; other absent imports remain optional. +Keep version 5 main validation without requiring version headers on every fragment. +Do not impose global filename filtering, hidden-file, symlink, or recursion rules. +CLI assignments occur after typed decode/inheritance and before Resolve. -Preserve exact profile IDs. Pointers use canonical JSON Pointer escaping; -an explicitly supplied empty pointer selects root. Use existing exit classes: -0 success, 2 malformed syntax/pointer/scope or wrong argument count, 1 load/ -inspection failure or unknown path/profile. Known historical-only paths are -valid. Check `Explain`'s found result before writing: the upstream writer emits -nothing for an unknown path. Stdout contains only the selected report; -diagnostics go to stderr. Writer errors can leave partial output; add no -transactional-output or byte-stability guarantee. +Replace blanket list recording with leaf records for actual leaf edits. Keep +whole-container records for actual map-key or list structure changes. Normalize +paths and nested reference keys while records still have entry order; use +EntryInfo to follow the source of the original scalar, then record the final +field. ConfigKit composition has already assembled step positions before Resolve. +Step-ID trimming can change correspondence: it does not justify an extra custom +identity matcher or a promise that every transformed record retains a file origin. +Test changed identities with native auditing and record an ancestor when needed. -Inspection never resolves credential values or contacts a provider. Report -credential names and actual upstream `APIKeyRequired` metadata without inferring -availability. Redact credential-shaped provider-parameter keys as upstream -configuration inspection does. Keep reporting projection separate from private -checkpoint hashing. Do not read unrelated environment values to sanitize -reports. Deliberately requested ordinary prompt/provider data remains visible; -add no automatic persistence, confirmation, or permission enforcement. +Map-key normalization remains application behavior. Retain original-path tracking +where a renamed pipeline/lane/reference key requires it; reduce redundant state +only after the updated origin tests prove it unnecessary. Preserve file-relative, +CLI-invocation-relative, default-main-relative, absolute, and empty-cache path +semantics. No new resource-existence or access policy is introduced. -### Captured Checkpoint Identity +## Stage 1 — Select The Mixed Dependency Graph And Toolchain -Compute one immutable identity at execution-engine construction, using public -captured inspection/definition APIs. Retain it on the client; return defensive -copies through `LLMCheckpointFingerprints`. Use name `promptkit_configuration` -and a versioned snapshot marker incorporating PromptKit and both catalog -versions. It supersedes separate profile-file/local-endpoint fingerprints; old -execution checkpoints naturally miss without migration/deletion. Source- -addressed chunk plans are unchanged. +Goal: establish the approved build inputs without migrating PromptKit. -The private digest input contains: - -- The captured effective definition tree from `InspectConfiguration`. -- Every effective profile ID and its `InspectProfile` target and credential- - policy metadata, covering resolved backend defaults/provider parameters. -- Every effective prompt ID/version and `InspectPrompt.PromptHash`, covering - captured message content rather than just content-file paths. - -Obtain the first tree by writing captured effective YAML to a private buffer -and decoding that report into a generic map with the existing YAML v4 -dependency. This is inspection projection, not a second authoritative loader: -it performs no discovery, imports, inheritance, defaults, or validation. Use -its keys to enumerate profiles and prompt versions; sort entries and encode -the digest payload with `encoding/json`. Do not enumerate historical-only -definitions or hash history. Preserve null versus zero/omission in the tree. -Remove only `backends.local.concurrency_limit` and `.queue_capacity` from the -private tree to preserve that backend's established scheduling-only exclusion. -Other identity choices stay conservative; selected-profile optimization is -not required. - -The redacted effective report is insufficient alone: include copied public -profile targets with their actual JSON-compatible provider parameters in the -private payload. This covers execution-relevant values whose names the report -redacts. Never publish the payload, raw sources, paths, endpoint, parameter -values, or prompt bodies as checkpoint metadata. Only its digest is retained. -Public profile inspection can describe partial definitions; do not turn an -incomplete unused profile into a construction failure while fingerprinting. -Constructor validation remains PromptKit's. - -A new engine captures edits; an existing engine/fingerprint remains unchanged. -Preserve module/schema and CLI execution-override fingerprints, actual-used -profile provenance, and reusable-state eligibility. Imported definitions and -operator message edits participate through captured definitions/hashes, not a -separate filesystem scan. - -## Stage 1 — Migrate Embedded And Maintained Definition Assets - -> Completion: complete. - -Goal: convert data without rewriting prompt semantics. - -Inspect `assets/**/prompts/prompt.yaml`, -`assets/dnd/profiles/dnd-extraction.yaml`, -`examples/llm-profiles/dnd-extraction.yml`, their ordered manifests, and the -pinned upstream format reference. +Inspect `go.mod`, `go.sum`, pinned ConfigKit/PromptKit module files, the v1.2.0 +consumer migration guide, and `docs/release.md`. Work: -1. Wrap each prompt body under `prompts: : v1:`; remove embedded - `id`/`version`. Keep every other field and content path. -2. Wrap both profile files under `profiles: dnd-extraction:`. Preserve - `openrouter`, `openai/gpt-5.6-luna`, timeout 240, `service_tier: flex`, and - unset reasoning. Keep filenames/root embedding unchanged. -3. Review identities against manifests and schema registrations. Change no - Markdown fragment, schema, cache control, or message ordering. Leave test - fixture migration to Stages 4–5. +- Set the Go consumer minimum to 1.27.0. Use Go 1.27.0 as the selected validation + toolchain for this sprint and update its release-runbook selection. Later + validation-patch updates remain separate from the consumer minimum. +- Add `go.maximumdirect.net/configkit` v1.2.0 while retaining old-path v0.5.0, + PromptKit v0.12.0, its current catalogs, and YAML rc.6. Tidy after real imports + land; unused new requirements may disappear before then. Retain needed graph + changes, not arbitrary unrelated upgrades. Do not adopt ReleaseKit as a tool. +- Verify both ConfigKit module paths and shared YAML selection. Record API compile + errors for Stage 2 rather than repairing them with replacements or forks. -Acceptance: all production definitions are keyed; non-identity bodies preserve -meaning and inventories select the same files. Only intended data changes land. +Acceptance: required released versions are obtainable and their graph has no +stable-YAML plugin-removal conflict. An unexpected dependency incompatibility is +reported with evidence rather than changing the target or upgrading PromptKit. -Validation: `git diff --check` and YAML-aware/manual comparison with prior -bodies. Legacy-loader failures are expected here, not runtime validation. +Checks: `GOTOOLCHAIN=go1.27.0 GOWORK=off go version`, selected module inspection, +and a compilation attempt. Network/dependency preparation precedes offline tests. -Prompt size: one mechanical conversion, no constructor work. +Prompt size: dependency/toolchain preparation only. -## Stage 2 — Upgrade Dependencies And Assemble Native Source Groups +## Stage 2 — Migrate Application APIs And Separate Old PromptKit Types -> Completion: complete. The native compile pass confirms the expected follow-up -> work: migrate client and inspector constructors in Stage 3, then migrate LLM -> and CLI test fixtures in Stages 4–5; no compatibility wrappers were added. +Goal: move the application loader and CLI to v1 APIs. -Goal: establish v0.12 and shared native source construction. - -Inspect `go.mod`, `go.sum`, `asset_registry.go`, `promptkit_profiles.go`, -`promptkit_client.go`, and upstream source/backend configuration APIs. +Inspect `internal/core/config/{load,loaded_config,operational_document, +pipeline_document,document_paths,document_normalizer}.go`, CLI ConfigKit imports, +and direct PromptKit setup under `internal/framework/llm` and test support. Work: -1. Upgrade PromptKit to v0.12.0 and tidy. Keep ConfigKit v0.5.0 and unrelated - pins; remove obsolete `/v2` catalogs. Promote YAML v4 to a direct dependency - when used for inspection projection without upgrading its version needlessly. -2. Implement source assembly specified above inside `internal/framework/llm`. - Replace source options with filesystem inputs, and backend registration with - keyed `BackendSource`. A registry-facing helper can return configuration - sources plus schema options; migrate direct callers in following stages. -3. Enable imports on operator inputs only. Preserve optional selection, resource - context, exact IDs, group order, and local concurrency zero. Do not auto- - clear retained queue settings if a later limit makes them invalid; native - validation decides. -4. Update PromptKit/catalog attribution, verifying released notices and full - commits: PromptKit `4b8169da286917fde7875425bb32b799b12c6af3`, OpenRouter - `f17d208cb7ad1fb043cda2266cd3011d11b40aa0`, Rakestrawhome - `993443d88c451901f4c917fa00c204fd3b54d28d`. Reuse unchanged standard texts; - change no project grant or unrelated notice. +- Migrate application-side imports. Update InputInfo to EntryInfo, Secret to + Sensitive, LayerBase to LayerMain, removed diagnostic names, and generic Record + calls to named normalization/derived-default methods. Audit stored strings too. +- Temporarily retain sequence ancestor records where the wrapper currently emits + them; simplify scope in Stage 3. Named recording methods record mutations already + performed; Default/Normalize helpers both assign and record. +- Keep old types in PromptKit-facing sources, profile inspection, and integration + fixtures. CLI ordinary configuration errors use new LoadError/WriteDiagnostics; + PromptKit errors remain adapted through its existing neutral facade. +- Introduce the shared LoadSource path and MainSourcePath accessor specified above. + Keep frozen inspection and detached runtime conversion. -Acceptance: selected graph and notices identify released revisions; shared -source construction uses native APIs. Name remaining constructor/test compile -failures for Stages 3–5 rather than hiding them with wrappers. +Acceptance: production imports have explicit owners, and no mixed named types +cross the boundary. Any remaining failures are classified as fixtures, collection +policy, or discovery work. No upstream types enter module/runtime contracts. -Validation: `GOWORK=off go list -m all`, `GOWORK=off go mod tidy -diff`, -`git diff --check`, and a native compilation attempt to locate removed APIs. +Checks: native build to a `mktemp -d` location; focused compile/test attempts for +`./internal/core/config ./internal/cli ./internal/framework/llm`; diff review. -Prompt size: dependency/notices and one source-construction boundary. +Prompt size: API/handoff migration; no discovery implementation or broad fixtures. -## Stage 3 — Switch Runtime And Preflight To Shared Engine Configuration +## Stage 3 — Simplify Recorded Normalization And Preserve Source Bases -> Completion: complete. The native command build passes. Test compilation is -> still blocked by removed PromptKit setup APIs and legacy fixtures in -> `asset_registry_test.go`, `promptkit_client_test.go`, and -> `production_contract_test.go`; the fixture work remains in Stages 4–5. +Goal: use v1.1 field-level auditing instead of old blanket sequence coverage. -Goal: restore application compilation and consistent sources. - -Inspect `NewPromptKitClient`, `NewPromptKitProfileInspector`, -`promptKitProfileSourceEngineOptions`, `PromptKitLocalBackendOption`, -`internal/cli/promptkit_profiles.go`, and production LLM composition. +Inspect document_normalizer.go, document_paths.go, pipeline_document.go, +reference normalization helpers, and existing path/inheritance tests. Work: -1. Construct both engines with shared `Config.Sources`; remove obsolete - directory fields, source options, and `WithBackend`. Production preflight - includes application prompts, not just profiles, for partial overlays. -2. Retain timeout, HTTP client, transient retries, runtime injection options, - recorder, reasoning-pointer copies, and required client assets. Keep - `CompleteStructured` preparation/execution unchanged. -3. Retain safe errors and established `errors.Is`/`errors.As` behavior. Eager - constructor failures must not dump raw configuration/credentials into CLI - diagnostics. Do not classify by parsing upstream error wording. -4. Keep explicit-profile selection and credential-free inspection. Nil optional - inspector assets remain usable in tests; compose no modules in the framework. -5. Remove dead option helpers/fields, except old fingerprint inputs still used - until Stage 7. A new catalog marker is not a substitute for captured identity. +- Remove `inSequence`/whole-list coverage for ordinary leaf edits. Use the public + recording helpers directly or retain only a genuinely useful thin helper. +- Preserve explicitness and source lookup through key normalization. Resolve + reference paths before key/record movement obscures entry addresses; retain + only needed relocation state. Preserve true structural mutation records. +- Verify canonical main-directory initialization against public source evidence + and native version-path protection, including a discovered main. Retain the + existing version-origin lookup where that contract makes it valid; avoid a + second search. Preserve private non-file test-source handling separately. +- Improve existing tests for imported/overlaid/inherited source bases, paths + inside steps, whitespace-normalized IDs, CLI paths, and leaf explanation history. + Fixtures must use distinct directories so incorrect bases cannot also pass. -Acceptance: `cmd/notarius` builds; both construction paths use the same policy. -No upstream type leaks into domain/pipeline contracts. Report remaining test- -only compile failures for fixture migration. +Acceptance: leaf-only normalization is accurately recorded; real structural edits +remain covered; runtime paths match effective output and source history. No +new filesystem constraint or custom provenance-replay mechanism appears. -Validation: native `GOWORK=off go build` of `./cmd/notarius` to an executable -beneath a `mktemp -d` directory outside the repository; `git diff --check`. +Checks: focused config normalization/path/inheritance tests, then all core/config +tests when migrated fixtures allow them. Expected old control-format failures +belong to Stage 5. -Prompt size: constructor/error call sites only. +Prompt size: one resolution/provenance boundary. -## Stage 4 — Migrate LLM Fixtures And Restore The Adapter Suite +## Stage 4 — Register Steps And Exercise Native Collection Semantics -> Completion: complete. `GOWORK=off go test ./internal/framework/llm` passes -> offline; legacy keyed-format and removed-API fixtures are cleared from the -> LLM adapter suite. CLI and registered-module fixtures remain for Stage 5. +Goal: implement the accepted step identity and composition policy. -Goal: exercise released configuration through existing adapter coverage. - -Inspect `promptkit_client_test.go`, `promptkit_observation_test.go`, -`asset_registry_test.go`, and helpers under `internal/framework/llm`. +Inspect documentDefinition, pipeline step validation/conversion, ConfigKit's +pinned sequence/placement contract, and inheritance tests. Work: -1. Convert literal files to keyed documents. Replace `WithProfiles` with - `ProfileSource` inputs and pointer fields preserving omission/explicitness. - Update engine setup to consume registry sources plus schema/runtime options. -2. Translate `base_profile` to `extends`. Deliberately adjust tests of whole- - profile replacement and selection-time failures only. Invalid unused final - entries fail construction; superseded contributions are not independently - domain-validated. -3. Preserve prepared execution, repairs, correction pairs, session/reasoning, - admission, transient errors, observations, cancellation, schemas, and safe - debug coverage. Fix owning adapter regressions instead of weakening tests. -4. Reuse small setup helpers; no legacy-format test converter. Fingerprint - fixtures become keyed now, with behavior changed later in Stage 7. +- Add the exact wildcard registration above. Keep validation/domain IDs unchanged; + ConfigKit owns structural identity comparison, assembly, inheritance, and history. +- Add small real-file cases for distinct imported steps, strict duplicate peers, + inherited/overlaid full-record upsert, replacement/append, and empty-list clearing. + Include one identified-record inheritance case and an unregistered list showing + that broad identity registration has not leaked elsewhere. +- Assert resulting order, full-record replacement, and actual pipeline compatibility. + Cover step-local references declared in different imported files and native CLI + whole-list assignment. Do not add list merging to Notarius. +- Use native leaf histories after composition to expose any Stage 3 defects. + Reuse domain validation for invalid or duplicated normalized step identifiers. -Acceptance: the full LLM suite compiles/passes offline, with no removed API -fixtures. Intentional semantic expectation changes are clear in the diff. +Acceptance: native composition produces the intended typed pipeline and existing +domain rules still apply. Default upsert and explicit replace differ as documented. -Validation: `GOWORK=off go test ./internal/framework/llm`; `git diff --check`. +Checks: config collection/inheritance tests and focused framework resolution tests. -Prompt size: mechanical adapter fixture migration and restoring its suite. +Prompt size: one definition registration and its focused behavior coverage. -## Stage 5 — Restore CLI And Registered-Module Fixture Coverage +## Stage 5 — Migrate Application Fixtures And Restore Configuration Coverage -> Completion: complete. CLI and registered-module fixtures now use keyed -> sources, `GOWORK=off go test ./internal/cli ./internal/modules/...` and -> `GOWORK=off go test ./...` pass offline, and the integration reference -> describes the pinned v0.12 source API. Captured fingerprint migration remains -> scheduled for Stage 7. +Goal: translate existing tests to the selected source contract. -Goal: close the initial format/API migration window. - -Inspect `internal/cli/promptkit_profiles_test.go`, `production_contract_test.go`, -D&D `register/prompt_cache_test.go`, and direct PromptKit setup in chunk, -extract, normalize, and validator prompt asset tests. Discover remaining -legacy fixtures across tests, not just this initial inventory. +Inspect config document/operational/loaded/paths/inheritance tests and CLI +ConfigKit/command/production tests. Discover literals and helpers by consumer. Work: -1. Migrate direct construction and keyed fixtures mechanically through the - new registry boundary. Keep fake outputs and domain expectations intact. -2. Change CLI expectations only for eager definition/source failures; preserve - unknown-profile, credential-free validation, cancellation, and safe errors. - Do not introduce a required API-key placeholder. -3. Prepare registered prompts using representative existing tests. Fix real - content-context/schema/mount regressions without rewriting prompt text. -4. Update the integration reference's supported pin/API links and basic - constructor boundary. Full inspection/deployment docs follow later. +- Rename genuine application-source controls to `config` and update stored pointer + and layer strings. Required file fixtures explicitly declare requiredness; tests + of absent optional imports adopt the native default. Keep old PromptKit sources + and their fixtures under the old reader's syntax and APIs. +- Update tests deliberately for post-decode CLI assignment and identified step + upsert. A CLI override does not repair decoding/structural errors. An explicitly + replaced empty list, null, omission, and empty append/upsert have distinct meanings. +- Preserve version checks, application field validation, dynamic integer option + conversion, redaction, cancellation, and detached runtime/inspection ownership. + Include nested ordinary `config` data in dynamic options to protect control scope. +- Consolidate small fixtures only when it reduces duplication without disguising + the two loader versions. No generic legacy-to-new YAML converter belongs in tests. -Acceptance: the full offline suite compiles/passes, registered assets prepare, -and the integration reference no longer describes removed APIs as current. +Acceptance: existing application configuration coverage exercises v1.2.0 with +intentional semantic changes documented in tests; LLM fixtures still use old types. -Validation: `GOWORK=off go test ./internal/cli ./internal/modules/...`, then -`GOWORK=off go test ./...`; `git diff --check`. +Checks: `GOWORK=off go test ./internal/core/config ./internal/framework/llm` plus +CLI compile/tests, noting discovery assertions assigned to Stages 6–7. -Prompt size: mechanical consumer fixture sweep, no new domain behavior. +Prompt size: mechanical fixture migration; avoid unrelated production refactoring. -## Stage 6 — Prove Native Operator Composition And Credential Policy +## Stage 6 — Delegate CLI Discovery And Publish The Actual Selected File -> Completion: complete. The source-composition tests exercise imported combined -> operator documents through runtime and preflight, layered and strict-group -> behavior, local-backend precedence, and optional/required synthetic -> credentials. `GOWORK=off go test ./internal/framework/llm ./internal/cli` and -> `git diff --check` pass. +Goal: replace filesystem probing with the settled native source selection. -Goal: verify accepted unified sources through the shared boundary. - -Inspect source assembly, profile/preflight tests, and adapter source tests. -Use small real files and real PromptKit loading. +Inspect loadConfigKit, discoverConfigPath/requireConfigFile, command dispatch, +Options.LookupEnv, and invocation/debug use of loadedConfigPath. Work: -1. Add a combined operator document with profiles, a custom backend, a catalog - backend field override, and a partial embedded-prompt overlay. Assert - preflight/runtime construct the same effective definitions. -2. Cover an import, a derived profile, omission retaining a field, explicit - zero/false, and null clearing an inherited tier/provider map. Cover `{}` - versus null only where consequential for the workflow. -3. Cover directory-group conflicts versus valid later-layer overrides, - selected-missing/empty sources, an invalid lower field repaired by an - overlay, and an invalid unused final entry. No raw-layer audit is added. -4. Cover explicit Notarius local endpoint/limit precedence and custom backend - admission through existing injected-client tests, not an upstream matrix. -5. Check optional versus required credential policy with synthetic names. - Inspection succeeds unset; preparation/execution follows native requirements. - Explicit profile environment sources differ from inherited backend sources. +- Construct exclusive File or ordered required SearchConfig sources as specified. + Pass one source to LoadSource. Remove obsolete stat/probe loops and single-default + constants once unused. Keep blank optional flag/environment handling consistent. +- Populate the selected-path return from MainSourcePath. Preserve canonical + source-relative application defaults and the actual path in requested debug data. +- Route load failures through new ConfigKit structured diagnostics/source legends. + Keep ordinary syntax exit 2 and acquisition/validation exit 1 behavior; do not + parse diagnostic prose. Retain old PromptKit error handling for its own reports. +- Update all run/config/report/list callers through the shared boundary. Do not + resolve pipelines or call providers merely to discover/report configuration. -Acceptance: native presence/composition works without a second loader, -whitelist, implicit credential requirement, or generation during preflight. +Acceptance: no manual file search precedes ConfigKit; every config-consuming +command uses the same selected source and its retained provenance. -Validation: `GOWORK=off go test ./internal/framework/llm ./internal/cli`; -`git diff --check`. +Checks: focused CLI load/discovery/report tests and native build. -Prompt size: operator-source fixtures, not identity or content lifecycle. +Prompt size: shared CLI loading boundary, not the full discovery test matrix. -## Stage 7 — Compute Immutable Captured Configuration Identity +## Stage 7 — Verify Discovery, Inspection, And Failure Semantics -> Completion: complete. Checkpoint identity is now a single digest captured -> from each constructed engine's effective configuration, profile targets, -> credential policy, and prompt hashes. Focused tests confirm source edits do -> not mutate an existing engine's identity, provider parameters and prompt -> bodies affect identity without being exposed, and local scheduling values -> remain excluded. `GOWORK=off go test ./internal/framework/llm`, -> `GOWORK=off go mod tidy -diff`, and `git diff --check` pass. +Goal: protect the new operator contract with bounded offline coverage. -Goal: replace live-file fingerprinting with the settled snapshot algorithm. - -Inspect `promptkit_profile_fingerprint.go`, client construction/fingerprint -methods, public inspection APIs, and module/schema identity contributions. +Inspect CLI command_contract/configkit_load/configkit_commands tests and +core/config loaded/source tests. Use real CWD/user-directory behavior in tests +that control process state and are not parallel. Work: -1. Implement the private captured projection and digest specified above using - the just-constructed engine, never a second load or current file scan. -2. Inspect all effective profile IDs, including valid partial definitions. - Hash presence-aware definitions plus resolved targets and captured prompt - hashes; redacted reports or zero-valued targets alone are insufficient. -3. Store only the resulting fingerprint slice. Delete old file/directory scans, - catalog-only marker, local-target fingerprint, and obsolete client fields. -4. Preserve local scheduling-only exclusion and module/schema/override identity. - Change no chunk-plan key or resume eligibility. Update focused fingerprint - tests for the new boundary. +- Cover CLI over environment, environment over discovery, CWD over user selection, + native named-file ordering, and the absence of generic CWD config.yml selection. + Bad explicitly selected files and invalid selected CWD files fail without fallback. +- Isolate user directories with controlled platform environment. Avoid tests that + write /etc or depend on the host's system configuration. Rely on upstream for + preset directory expansion; test required-search exhaustion with a controlled + SearchConfig passed to LoadSource rather than assuming host directories are empty. +- Verify selected-file path and declaring-directory defaults after discovery, + source-local overlays/imports, canonical symlink source behavior, and CLI paths. +- Exercise effective/explain/validate/list and a recorded run with an injected + external client. Assert safe source diagnostics, origins, provider-free reports, + ordinary optional absence without warnings, and unchanged PromptKit scoped reports. -Acceptance: immutable `promptkit_configuration` reflects the captured engine -and pinned graph. The fingerprint API performs no later read/reload. No raw -payload is persisted, returned, or logged. +Acceptance: selection precedence and terminal failures are observable through +commands without a second acquisition pass or host-dependent fixtures. -Validation: `GOWORK=off go test ./internal/framework/llm`; private projection/ -propagation review; `git diff --check`. +Checks: `GOWORK=off go test ./internal/core/config ./internal/cli ./internal/framework/llm`. -Prompt size: one private snapshot/digest mechanism; broader reuse tests follow. +Prompt size: discovery and cross-boundary behavioral verification. -## Stage 8 — Protect Captured Identity And Resume Behavior +## Stage 8 — Maintain Runnable Native Composition Examples -> Completion: complete. Added edit-after-construction coverage for an imported -> inherited profile and its source-relative prompt message: the existing client -> retains its digest and execution behavior, while a new client captures both -> edits. Fingerprint tests cover model, endpoint, credential policy, redacted -> provider parameters, prompt content, null-versus-zero presence, and local -> scheduling exclusions without exposing their values. The recorded-checkpoint -> test confirms same-snapshot reuse and stale execution misses under the new -> `promptkit_configuration` identity; existing override and chunk-plan checks -> remain passing. `GOWORK=off go test ./internal/framework/llm ./internal/cli -> ./internal/modules/integration` and `git diff --check` pass. +Goal: demonstrate the approved features in the existing two top-level examples. -Goal: prove identity correctness across edits and checkpoint reuse. - -Inspect adapter identity tests, CLI fingerprint handoff, and existing recorded- -checkpoint/resume integration fixtures. +Inspect examples/dnd-complete.config.yml, pipelines/dnd-session.yml, development +overlay, profile file, and internal/cli/example_contract_test.go. Work: -1. Construct A from operator definitions/imports/message files. Edit them; - A's captured content and fingerprint remain unchanged. B captures semantic - definition/message changes and receives a different identity. -2. Cover model, endpoint, credential-policy, inherited/imported changes, null - versus zero, and provider parameters whose keys are report-redacted. Cover - local concurrency-only identity separately from local endpoint changes. -3. Check detached fingerprint ownership and absence of raw source/settings/ - bodies in values or ordinary metadata. Compare behavior, not fixed hashes. -4. Extend one recorded-checkpoint workflow: changed captured config prevents - stale execution reuse; same-snapshot reuse, override identity, and source- - only chunk-plan reuse remain intact. +- Change the complete root's import to `config` and make it explicitly required. +- Move its describe-session step into a new sibling fragment + `examples/pipelines/dnd-session.describe-session.yml`, containing the step mapping. + The pipeline fragment imports it with `required: true`, + `destination: [pipelines, dnd-session, steps]`, and `placement: sequence-item`; + retain extract-events in the declaring fragment's steps list. Native dependency- + ready composition places the imported first step before the declaring body. +- Keep the new fragment beside the old one so existing file-relative references + retain their bases. Preserve lane IDs, module options, generated references, + pipeline behavior, and the derived development profile. Leave the old PromptKit + deployment document's syntax unchanged. +- Update example tests to resolve the complete/development pipelines, assert actual + step order and handoffs, and validate without credentials/inference. Retain exactly + the existing two top-level examples; the added fragment is supporting content. -Acceptance: reusable state follows the executing engine, not edited files; -local scheduling-only changes do not accidentally change the chosen identity. +Acceptance: maintained configurations load natively and demonstrate composed steps +plus inheritance with no duplicated complete pipeline or altered D&D execution policy. -Validation: `GOWORK=off go test ./internal/framework/llm ./internal/cli ./internal/modules/integration`; -`git diff --check`. +Checks: existing CLI example tests and module-integration tests; credential-free +CLI validation of minimal, complete, and development selections. -Prompt size: snapshot/resume regressions, no checkpoint redesign. +Prompt size: one supporting fragment and existing example coverage. -## Stage 9 — Verify Source-Relative Content And Capture Lifetime +## Stage 9 — Update Operator And Consumer Documentation -> Completion: complete. Added integration coverage showing imported content -> resolves from its declaring directory, replacement content resolves from its -> replacement source while retaining the embedded prompt's other fields, and -> constructed engines keep captured messages across file edits while rebuilt -> engines observe changes. Static template and missing-file errors remain -> construction failures; missing request variables remain preparation errors. -> `GOWORK=off go test ./internal/framework/llm ./internal/modules/...` and -> `git diff --check` pass. - -Goal: protect resource contexts and static template/content capture. - -Inspect manifests, source construction, and existing prepared/prompt asset -tests; consult upstream origin/frozen-rendering contracts for timing. +Goal: document implemented native behavior and migration in canonical homes. Work: -1. Use directory-distinguishing files to prove an imported/inherited message - resolves from its declaring source. Add a later prompt replacement with - replacement-file-relative content and a partial overlay over embedded base. -2. Existing engines retain captured content/templates; a new engine sees edits. - Bad static syntax/missing message files fail construction, while missing - request variables remain preparation failures. -3. Keep schema preparation timing and inline request inputs unchanged. Preserve - representative rendered bytes/order/cache metadata. Fix only real context - or mounting defects; do not expand host-root policy. +- Update docs/config.md for selected-source order/filename groups, root controls, + optional imports/explicit requiredness, step identity/upsert/replace/append, + record inheritance, destinations, native CLI timing, and path bases. Remove + obsolete universal whole-list-replacement/step-inheritance limitations. +- Update docs/cli.md discovery and report behavior, linking to config's field rules. + Keep explicit --config advice first-class in subprocess/operations guidance. +- Explain the two configuration formats at the temporary boundary: Notarius uses + new controls, PromptKit operator documents still follow its old engine. Show + concise migration snippets and link the maintained complete files. +- Update README's consumer-minimum rationale for the newly selected ConfigKit + requirement and release setup to Go 1.27.0. Keep source-only publication and + existing release gates. Update actual CI toolchain configuration if present; + create no new CI workflow or publication mechanism. -Acceptance: no source is rebased to the caller/CWD; captured definitions remain -distinct from schemas and request artifacts. +Acceptance: operator guidance explains real new semantics and intentional migration +without introducing extra import restrictions or promising unchanged composition. -Validation: `GOWORK=off go test ./internal/framework/llm ./internal/modules/...`; -`git diff --check`. +Checks: relevant example tests, link/command review, and `git diff --check`. -Prompt size: origin/lifecycle cases, not new execution policy. +Prompt size: public references and concise consumer/workflow adjustments. -## Stage 10 — Expose A Provider-Neutral Inspection Facade +## Stage 10 — Update Integration References And Attribution -Goal: support CLI reports without exposing upstream dependency types. - -Inspect profile result/error types, shared source construction, and public -PromptKit inspection APIs. +Goal: make ownership and the temporary mixed graph accurately documented. Work: -1. Add adapter string/writer operations for effective/explanation reports. - Parse canonical pointers privately; preserve writer causes, invalid-versus- - unknown distinctions, and known historical paths. Keep upstream values private. -2. Extend the neutral profile result with copied fields for the settled JSON - DTO. Copy actual target, credential name, and `APIKeyRequired` metadata; do - not infer environment availability or provider defaults. Existing preflight - consumers retain their needed metadata. -3. Redact credential-shaped keys recursively in the reporting copy of provider - parameters. Reuse a suitable helper without reversing dependencies, or add - a small local projection using upstream's case-insensitive vocabulary: - `api_key`, `apikey`, `authorization`, `credential`, `credentials`, - `password`, `secret`, `token`, `access_token`. Do not reject those keys, - redact unrelated content, or mutate the private digest projection. -4. Test detached ownership, safe errors, parameter redaction, escaped pointers, - absent selectors, and unset synthetic credential names. +- Update docs/internal/configuration.md and docs/internal/cli.md for LoadSource, + selected-path provenance, field-level resolution, discovery, and source parity. + Remove stale blanket-list-recording and manual search descriptions. +- Update docs/integrations/pkg-configkit.md to v1.2.0/new module/pinned contracts. + Explain the temporary old dependency in the PromptKit/LLM integration references + without documenting its entire future migration. ADR-0020 already owns the decision. +- Update docs/oss/attribution.md for new ConfigKit at the full source commit, + retain its old-path dependency's notice, and review actually selected transitive + modules/tool requirements. Inspect released COPYRIGHT/LICENSE/notices; reuse + unchanged standard texts. Preserve the project grant and policy provenance. +- Keep upstream release tooling and its gates upstream. Dependency attribution + does not adopt ReleaseKit as Notarius's release implementation. -Acceptance: all three views are available without leaked types, credential -resolution, provider calls, automatic dumps, or mutation of identity. +Acceptance: current docs and factual notices match the selected mixed graph; +historical ADRs/releases remain untouched. No policy or license grant is expanded. -Validation: `GOWORK=off go test ./internal/framework/llm`; `git diff --check`. +Checks: selected module inspection, pinned/local link and notice review, whitespace +check. Reuse unchanged example validation rather than adding documentation snapshots. -> Completion: complete. Added provider-neutral effective-configuration and -> explanation string/writer operations, with canonical pointer parsing and -> distinct invalid/unknown results. Profile inspection now returns a detached -> copy of the effective target and recursively redacts credential-shaped -> provider parameters without resolving credentials. Escaped-pointer, history, -> writer-error, unset-credential, redaction, and ownership coverage passes with -> `go test ./internal/framework/llm`; `git diff --check` passes. +Prompt size: focused internal/integration docs and dependency notices. -Prompt size: one facade/DTO, not CLI parsing. +## Stage 11 — Verify The Entire Target And Finish The Sprint -## Stage 11 — Add Scoped Effective And Explanation Commands - -Goal: expose captured configuration/history through explicit PromptKit scope. - -Inspect `internal/cli/configkit_commands.go`, `runConfig`, usage text, -normalized composition options, and configuration command tests. +Goal: prove all feature-roadmap acceptance on the completed implementation. Work: -1. Add `--scope` with settled values/default; keep the ordinary report branch - unchanged. Only PromptKit scope constructs an inspector using selected - normalized config and registered assets. -2. Route pointer/history and writer failures through the facade and existing - exit classes. Allow empty root and escaped IDs. Do not invoke the LLM client - factory, resolve a pipeline, prepare requests, or materialize references. -3. Add focused CLI coverage for default report preservation, scopes, malformed/ - unknown/historical selectors, import/overlay origins, redaction, and writer - failure. Use zero-call counters at external boundaries. -4. Update help and `docs/cli.md` syntax/output behavior. State that construction - validates/captures definitions and requested reports can contain ordinary - inline prompt/provider data. +- Compare final code, examples, tests, and docs against each target section. + Check new ConfigKit v1.2.0, old v0.5.0 for PromptKit, YAML rc.6, unchanged PromptKit + v0.12.0/catalogs, Go minimum/toolchain, native controls, discovery, step composition, + sources/paths, leaf histories, and frozen inspection. Correct small residual defects. +- Review remaining old imports/control strings by owner, not a blanket grep ban. + Old PromptKit APIs and historical release text legitimately remain. Remove obsolete + application wrappers/probing and contradictions; retain meaningful behavioral tests. +- Run full offline tests, vet, tidy diff, native temporary build, and source/version + inspection. Smoke-test config validate on all maintained selections and both + ordinary/PromptKit inspection reports. Use explicit fixture input only for offline + injected-client run tests; do not invoke a production pipeline for verification. +- Review accidental strengthening: no extra permissions, mandatory secret lookup, + fragment-version requirement, stricter import defaults, hidden list merger, + compatibility shim, or new release gate. Leave unrelated prior findings and + roadmap retirement to their own work sets. +- Report actual checks and remaining limitations. Upgrade completion requires a + buildable graph and passing target behavior, not only a successful go get. -Acceptance: current invocations retain meaning; explicit scope produces only -its requested report without transcript input, credentials, or provider work. - -Validation: `GOWORK=off go test ./internal/cli`; `git diff --check`. - -> Completion: complete. Added opt-in `promptkit` scope for effective and -> explanation reports while preserving the default and explicit `notarius` -> output. The PromptKit path builds its inspector from the selected normalized -> configuration and registered assets, and reports malformed/unknown/history -> selectors and writer failures with the established exit classes. CLI -> coverage verifies imported and fallback origins, escaped pointers, -> credential redaction, and no LLM factory invocation. Updated root help and -> [CLI reference](../cli.md). `GOWORK=off go test ./internal/cli` and -> `git diff --check` pass. - -Prompt size: two scoped branches, not resolved-profile parsing. - -## Stage 12 — Add Resolved Profile Inspection To The CLI - -Goal: report backend-completed profile settings explicitly. - -Inspect command dispatch, the profile facade, preflight, and JSON/error tests; -reuse Stage 11's inspector construction. - -Work: - -1. Add `config profile`, settled flags, and exactly one nonblank literal ID. - Emit the neutral DTO as one JSON object/newline, not the upstream Go struct. -2. Preserve syntax/runtime exit distinctions and safe missing-profile/config/ - writer failures. Inspect no credential availability and apply no run override. -3. Cover inheritance/backend defaults, endpoint-only identity, null suppression, - required unset credentials, credential-shaped params, and unknown profiles. - Assert fields rather than whole JSON snapshots or inferred provider defaults. -4. Update help and `docs/cli.md`: JSON shape, request/default distinction, - zero/presence caveat, failures, and links to effective/explanation. - -Acceptance: detached redacted profile inspection needs no transcript or model -call; preflight/run behavior remains unchanged. - -Validation: `GOWORK=off go test ./internal/cli ./internal/framework/llm`; -`git diff --check`. - -> Completion: complete. Added `config profile` with exact nonblank IDs and one -> neutral JSON object/newline containing the captured resolved target and -> `APIKeyRequired` metadata. Tests cover backend-completed and endpoint-only -> targets, inheritance, null/zero values, credential-shaped parameter -> redaction, required but unset credentials, literal whitespace-bearing IDs, -> safe unknown-profile handling, writer failure, and selected overlays. The -> command performs no credential lookup or model call, and profile IDs now -> remain exact through the inspection adapter. Updated root help and the -> [CLI reference](../cli.md). `GOWORK=off go test ./internal/cli -> ./internal/framework/llm` and `git diff --check` pass. - -Prompt size: one focused subcommand and its contract. - -## Stage 13 — Maintain Examples And Operator Guidance - -Goal: make native features understandable and deployable. - -Inspect the two maintained config examples, imported pipeline/development -variant, deployment profile file, example tests, config and operations docs. - -Work: - -1. Keep two top-level examples and normal default execution policy. Add a - small derived development profile to the existing deployment profile file, - demonstrating `extends` and a supported override without an unavailable - model. Do not select it for the normal complete pipeline or duplicate steps. -2. Explain unified sources, recursion/exact keys, imports, strict directories, - source roots, and Notarius overlays versus PromptKit layers. Use small - snippets for custom/catalog backends, local null clearing, prompt overlays, - and file-root imports. Add no third full pipeline/example framework. -3. Replace old whole-replacement, `base_profile`, embedded-ID, unsupported file - `api_key_required`, and stale format claims with v0.12 behavior. Include - external-file migration guidance, not aliases or a compatibility parser. -4. Add a concise operations workflow using three inspection views. Explain - engine reconstruction, credential names/availability, zero/presence, report - versus prepared/debug data, and operator-owned report handling. -5. Update existing example tests for the additional profile and actual native - behavior. Validate minimal, complete, and inherited development pipelines - offline with no required credentials or file-length assertions. - -Acceptance: valid examples and accurate canonical config/operations guidance, -linked to CLI/upstream contracts rather than duplicating their manuals. - -Validation: `GOWORK=off go test ./internal/core/config ./internal/cli`; -`git diff --check`; verify local/pinned links. - -> Completion: complete. Added a derived `dnd-extraction-development` profile -> with a supported temperature override while leaving the normal pipeline on -> `dnd-extraction`. Updated the canonical configuration guide with v0.12 -> source groups, strict composition, imports, source roots, native migration, -> backend/null/prompt-overlay examples, and exact inheritance. Updated operator -> guidance with the three report workflow, capture lifetime, credential -> metadata, and report handling. Example tests retain exactly two top-level -> configurations and validate the development profile offline without provider -> credentials. `GOWORK=off go test ./internal/core/config ./internal/cli` and -> `git diff --check` pass; reviewed the new local and pinned links. - -Prompt size: maintained examples and two operator documents. - -## Stage 14 — Finish Developer Contracts And Record The Decision - -Goal: document implemented ownership, capture, identity, and inspection. - -Inspect `docs/internal/llm.md`, `docs/internal/cli.md`, -`docs/integrations/pkg-promptkit.md`, ADR-0010/0018, and final implementation. - -Work: - -1. Update LLM internals for shared groups, final-value validation, capture, - snapshot identity, schema lifecycle, and neutral reports. Remove live-file - fingerprint claims. -2. Update CLI internals for scoped/profile reports, source parity, and credential- - free construction. Keep exact syntax/defaults in public references. -3. Finish pinned v0.12 and `/v3` integration guidance. Preserve prepared - execution, observations, corrections, retry separation, omission, and resource - timing. Explain final-only validation, not superseded-source audits; verify - license links. -4. Add `docs/adr/0019-adopt-native-promptkit-configuration.md`: native overlays, - unified sources/ownership, capture, compatibility, and alternatives. Add a - concise status/supersession link to ADR-0010 for only its whole-profile - replacement clause; preserve historical rationale and workload ownership. - ADR-0018's Notarius loader decision remains in force. -5. Repair other genuinely affected links/claims. Do not rewrite policy - provenance, historical releases, or unrelated artifact contracts. - -Acceptance: actual final behavior has canonical owners and a durable decision -record without erasing history or elevating incidental choices into policy. - -Validation: documentation/link review, scoped stale-term search, and -`git diff --check`. Reuse code/example checks when unchanged; no new scanner -or paid inference is required for prose. - -> Completion: complete. Updated the internal LLM, CLI, and PromptKit integration -> guides to describe unified native sources, final-effective validation, -> captured engine lifetime, schema preparation timing, immutable configuration -> identity, inspection output ownership, and credential metadata. Added -> ADR-0019 and linked it from ADR-0010 while preserving the workload and fallback -> ownership decision; ADR-0018 remains unchanged. Scoped stale-claim review and -> local/pinned source and license-link review are complete; the browser could -> not access the private Gitea links, so pinned attribution targets and license -> identifiers were cross-checked against the locally cached pinned modules. -> `git diff --check` passes. - -Prompt size: focused internal/integration references and one short ADR. - -## Stage 15 — Verify Completeness And Remove Only Obsolete Machinery - -Goal: prove the entire target state, not just a green dependency build. - -Work: - -1. Compare code/tests/examples/docs against every target section and settled - decision. Address small finishing defects. Report significant gaps rather - than silently narrowing source, identity, or reporting acceptance. -2. Find genuinely obsolete APIs, formats, option/fingerprint helpers, and - contradictory current documentation. Distinguish historical migration text - and normal application identifiers from obsolete PromptKit definitions. - Remove dead machinery, not retained behavioral tests. Review restrictions/ - guarantees for accidental strengthening. -3. Run full offline tests, vet, tidy diff, and native temporary build. Verify - selected modules. With provider credential variables unset, smoke-test - help, all three new reports, and maintained complete/development pipeline - validation. No real run or inference is needed. -4. Check report source parity/redaction, captured identity/reuse and origin - coverage, attribution/source links, and local navigation. Optional live - evaluation is follow-up evidence, not a new release gate. -5. Report completion and actual validation. Leave release selection/publication - and completed-roadmap retirement to a separate request. No file change means - no empty commit. - -Acceptance: all roadmap capabilities are implemented/demonstrated, deterministic -checks pass, no removed configuration-source API remains in implementation, -and no unrelated contract/restriction was introduced. - -Validation: +Validation commands, with dependencies prepared and Go 1.27.0 selected: ```sh GOWORK=off go test ./... GOWORK=off go vet ./... GOWORK=off go mod tidy -diff -GOWORK=off go list -m gitea.maximumdirect.net/eric/ConfigKit gitea.maximumdirect.net/eric/promptkit gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v3 gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v3 +GOWORK=off go list -m go.maximumdirect.net/configkit gitea.maximumdirect.net/eric/ConfigKit gitea.maximumdirect.net/eric/promptkit go.yaml.in/yaml/v4 git diff --check ``` -Build beneath a `mktemp -d` directory and use that executable for smoke tests; -keep temporary products outside the repository. These are migration checks, -not additions to release policy or production-key requirements. +Build ./cmd/notarius beneath a mktemp directory outside the repository. These +are sprint verification steps, not added permanent release gates. No file changes +means no empty final commit. Release numbering, notes/publication, ConfigKit +v1.2.1/stable YAML, and the full PromptKit upgrade remain separate work. -> Completion: complete. The completeness review found and converted one stale -> invalid-operator-profile test fixture from removed top-level PromptKit syntax -> to a keyed profile, preserving its effective-overlay rejection contract. -> No obsolete source API or fingerprint helper remains in implementation, and -> the review retained historical migration/provenance text. `GOWORK=off go test -> ./...`, `GOWORK=off go vet ./...`, `GOWORK=off go mod tidy -diff`, selected -> module-version inspection, and `git diff --check` pass. A native temporary -> build passed credential-free smoke checks for help, PromptKit effective, -> explanation, and profile reports, plus minimal and inherited development -> pipeline validation. No inference was run. - -Prompt size: final evidence review/small cleanup, no new feature. +Prompt size: final evidence review and small cleanup; significant newly discovered +scope requires an explicit decision rather than silently narrowing acceptance. ## Open Questions -None. Native overlays, unified sources/imports, and operator inspection are -accepted. Command syntax, report shapes, source precedence, captured identity, -and migration boundaries are specified above. Raise any new upstream API -incompatibility with evidence; do not silently drop a feature or add a shim. +None. The intermediate version, source selection, step identity, and native +configuration policies are approved. The mixed graph remains an early technical +verification task; report a concrete incompatibility if one appears instead of +silently selecting another version or adding compatibility machinery.