diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index a6bdc91..d21f897 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,417 +1,651 @@ -# ConfigKit v0.5.0 Implementation Plan +# PromptKit v0.12.0 Implementation Plan ## Status, Baseline, And Authority -Planned on 2026-10-03 against Scriptorium -`8b6c12f912b28ac00016f047f9846798a5de95d9`. All five stages are pending. -The [feature roadmap](configkit.md) owns scope, intent, and the target state. -This plan gives a Luna coding agent concrete implementation steps and acceptance -checks. Implement Stage 1 through Stage 5 in order, one stage per work unit. +Planned on 2026-10-04 against Scriptorium +`82b0f231b6ba71328f65f9a501143b2eedbe5d9c`. All thirteen stages are pending. +This plan is for a Luna coding agent: implement the stages in sequential order, +normally one stage per implementation prompt. The +[feature roadmap](promptkit.md) owns the target state, scope, and confirmed +product decisions; this document owns the steps and implementation status. -The baseline selects ConfigKit v0.4.2 and Promptkit v0.11.2. The target is the -published ConfigKit v0.5.0 at -`dc09959cca4e105f49ec316c6d4ba585bd2340bd`. -Use its [configuration contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/config.md) -and [consumer guide](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/consumers/README.md). -Inspect this exact revision through the downloaded module, a verified checkout, -or pinned upstream links. Do not adopt unpublished sibling changes. +The baseline selects PromptKit v0.11.2 and ConfigKit v0.5.0. Adopt published +PromptKit v0.12.0 at `4b8169da286917fde7875425bb32b799b12c6af3`, with its selected +OpenRouter and Rakestrawhome `/v3` catalogs at v3.20260930.0. ConfigKit stays at +v0.5.0. Use the pinned upstream +[formats](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/docs/formats.md), +[consumer/migration guide](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/docs/consumers/pkg-promptkit.md), +and public root-package declarations. Verify the selected checkout or downloaded +module before using sibling source; do not substitute newer unpublished work. -The previous content of this filename is the completed policy-alignment plan: -`git show 8b6c12f912b28ac00016f047f9846798a5de95d9:docs/roadmap/implementation.md`. -Do not rerun it. The initial ConfigKit cutover is already delivered; this work -adds upstream inheritance to the existing integration. +This file replaces the completed ConfigKit implementation plan, retained in Git +at `82b0f231b6ba71328f65f9a501143b2eedbe5d9c:docs/roadmap/implementation.md`. +Its five stages are complete despite its stale introductory pending status. +Do not rerun that work or carry its deferred framework-source choices into this +new, explicitly approved PromptKit work set. -## Execution Rules And Fixed Decisions +## Execution Discipline -Before each stage, inspect status and relevant diffs, read -`docs/development.md` and `docs/policy/agents.md`, and select other policies -using the development guide. Architecture, testing, and OSS govern dependency -and integration work; documentation governs examples and prose; release governs -compatibility and the release handoff. Reuse unchanged instructions already in -context. Prefer the repository's code graph for symbol discovery. +Start each stage with working-tree inspection and the applicable reading guide +in `docs/development.md`. Follow `docs/policy/agents.md`, and select architecture, +testing, documentation, OSS, and release policies by their task triggers. Prefer +the code graph for symbol discovery; use file searches for literals, fixtures, +and documents. Read the implementation and tests named by the stage. -Keep the following agreed choices throughout: +Keep changes proportionate and use the public ConfigKit/PromptKit APIs. Do not +add a Scriptorium framework facade, copied catalogs, independent YAML parser, +second inheritance/merge pass, workflow state, hot reload, or new HTTP inspection +routes. Preserve accepted ADR decisions and unrelated policy/template baselines. +The source cutover and new CLI inspection family are the approved changes; +other public requests, responses, deadlines, retries, reports, artifact limits, +and error identities are not invitations to redesign their contracts. -- Retain ordinary `configkit.Load`, the current `Document` schema and - definition callbacks, and the shared execution/inspection result. ConfigKit - already expands inheritance before decoding. Do not add an `Extends` Go - field, application merge pass, opt-in, keyword escape, or compatibility loader. -- Keep current discovery, explicit imports, selected overlay, CLI override - presence, working-directory-relative application paths, and normalization. - Backend conversion still uses resolved values and sorted IDs. -- A parent backend remains an ordinary configured backend. It is registered - and validated with the child. Inheritance copies settings; it does not create - a shared capacity pool across distinct backend IDs or abstract templates. - Existing sharing of each backend's capacity across server requests remains. -- Keep `api_key_env` as a visible environment-name string passed to Promptkit. - Do not resolve it through ConfigKit or mark it secret. Effective and historical - ordinary `extra_params` values stay visible under the maintainer's policy. - Existing raw-key restrictions and credential ownership remain. -- ConfigKit reserves `extends` across application input mappings, including - dynamic provider data and mapping names. Accept that upstream compatibility - change. It does not apply to separately parsed Promptkit definitions or HTTP - payloads. -- Underlays, native filesystem/mapping source APIs, source-relative resources, - schema versioning, secret bootstrap, and hot reload are deferred. Do not add - flags, HTTP configuration routes, source DTO fields, or APIs for them here. -- Keep Promptkit and other dependency versions, public HTTP behavior, accepted - ADR decisions, policy template baselines, release automation, and published - release notes unchanged except for the selected ConfigKit integration. - A concrete upstream defect should be reported with a reproducer; do not copy - its implementation into Scriptorium or assume a different unreleased target. +Use real internal collaborators and temporary files, with small clients or +`httptest` at the provider boundary. Tests are offline and credential-independent. +Test semantic outcomes and typed errors, not exact native writer prose, source +IDs, catalog inventories, context-object identity, or cross-version hash bytes. +Do not weaken a real regression assertion merely to make migration pass. -Production code changes are expected only if validation exposes a real -integration defect. Prefer the existing implementation when it already works. -Use small behavioral tests with real ConfigKit and Promptkit collaborators, -temporary files, and existing helpers. Do not add parser/inheritance matrices, -full prose snapshots, live provider calls, or test frameworks. +### Bounded Migration Window -Each stage must leave a coherent, reviewable state. Record concise completion -evidence under that stage and commit its files with a short plain-English -message under the agent policy. Preserve unrelated user changes. Do not push, -tag, publish, or invoke the release command as part of this implementation. +The dependency removes APIs used across production code and test fixtures. +Stages 1–7 deliberately split that mechanical migration into Luna-sized units: +the tree is not independently deployable during that window. Stage 1 can expose +removed-API compilation failures; Stage 2 can expose stale CLI field references; +Stage 3 must restore the production build. Stages 5–7 finish the existing test +fixture migration. Do not add compatibility shims, skip tests, build tags, or +parallel loaders just to make those intermediate revisions green. -For stages changing modules, Go code, or tests, run the development baseline -before committing: `go test ./...`, `go test -race ./...`, -`go vet ./...`, and `go build ./cmd/scriptorium`. Also run each stage's focused -checks and `git diff --check`; format changed Go files with `gofmt`. -Reuse successful checks for unchanged content. Documentation-only changes need -affected examples and link checks, not unrelated new runtime tests. +Run the development baseline checks for code/dependency/test stages: +`go test ./...`, `go test -race ./...`, `go vet ./...`, and a native +`go build` of `./cmd/scriptorium` with output outside the repository. During the +bounded window, report actual failures and tie them to the explicitly remaining +stages; passing focused checks do not imply a passing full suite. Failures +outside that expected migration must be investigated, not deferred by default. +By the end of Stage 7 these checks must pass. After that, regressions must be +resolved within the stage that introduces them. Reuse successful checks when +their covered content is unchanged. -## Stage 1: Adopt The Published Dependency And Its Compatibility Notice +Format changed Go files, run `git diff --check`, and verify affected examples +and links. Documentation-only stages need their affected examples and links, +not unrelated new tests. Keep this plan's stage status and concise completion +evidence accurate; commit completed work units under the agent policy. Final +completion requires all stages, not merely a restored build. Never push, tag, +publish, run the release command, or change release automation in this work set. -Status: Complete. +## Fixed Implementation Choices -Completion evidence: selected ConfigKit v0.5.0 at -`dc09959cca4e105f49ec316c6d4ba585bd2340bd`, updated its attribution and current -configuration compatibility documentation, and retained the single `Load` -pipeline. `go test ./...`, `go test -race ./...`, `go vet ./...`, -`go build ./cmd/scriptorium`, affected upstream link checks, and -`git diff --check` passed. +These choices implement the confirmed roadmap without adding another product +decision: -Files: `go.mod`, `go.sum`, `docs/oss/attribution.md`, -`docs/config.md`, `docs/development.md`, and -`docs/policy/architecture.md`. +- Replace application `prompt_dir`, `profile_dir`, and `backends` with + `promptkit_sources`, an ordered sequence of selectors. Each selector has + string fields `file` and `directory`; exactly one must be nonblank. Unknown + fields retain ConfigKit strict-decoding treatment. Omitted/null/empty source + sequences mean no caller inputs; there is no minimum count or implicit scan. + Scalar null handling remains ConfigKit's native string-field behavior. +- Keep application discovery, imports, one selected overlay, explicit overrides, + and process-working-directory-relative application paths. Normalize selected + paths with the existing trim/clean approach and record actual changes through + ConfigKit. Do not stat/read configured sources in application schema validation. + Preserve source order; do not sort or deduplicate selectors. +- Each selector is one caller underlay. File inputs use `configkit.File` with + `Imports: true` and its default canonical-parent root. Directory inputs use + `promptkit.DirectoryInputs` unchanged, including disabled imports and retained + resource contexts. Do not widen roots, flatten YAML into mappings, or infer + file priority inside a directory. `Sources.Main` remains nil. +- Register repeatable `--promptkit-source PATH` for `run`, `render`, `serve`, + `inspect prompt`, `inspect profile`, and `inspect configuration` modes. + One occurrence is one path, not a comma/glob expression. Infer file/directory + from ordinary `os.Stat` for these explicit CLI arguments; follow normal + symlink behavior, accept regular files/directories, and report unavailable or + other file types as CLI errors. This classifies CLI arguments only; it is not + framework-content validation or a global containment policy. +- Explicit source flags replace the entire configured list in argument order; + omitted flags do not override it. Submit one ConfigKit override at + `/promptkit_sources`, with `Flag: "--promptkit-source"` and plain + `[]any`/`map[string]any` values, not a named Go slice. Application `config` + commands retain their unrelated overrides, but lose old directory flags; + their source list is configured in YAML, without adding the engine-only flag. +- Existing prompt/profile inspection retains its format/output flags and gains + shared source selection and `--schema-dir`. It loads the same framework + sources as execution; it does not prepare a synthetic request. No command + requires a source list merely to construct an engine. Keep request prompt-ID + requirements and exact ID/version forwarding. +- New `inspect configuration validate|show|sources|explain` accepts `--config`, + `--config-overlay`, `--promptkit-source`, and `--schema-dir`; `explain` also + requires an explicitly supplied `--path`, including `--path ''` for root. + No prompt/profile/input is required. Like application inspection, reports go + to stdout and diagnostics to stderr; no new `--format` or `--out` surface is + needed. Parse/load/output/diagnostic-write failures exit 1; success exits 0. +- New framework reports use native effective YAML and explanation writers. + `sources` emits a newline-terminated JSON array with DTO fields `id`, `label`, + `layer`, `kind`, `underlay_index`, optional `path`, and optional `imported_from` + containing `source_id`, `line`, and `column`. Preserve upstream record order + and values; underlay indices include maintained inputs, not just caller groups. + Do not add fields to the existing application `config sources` DTO. +- Native effective/history redaction applies only to the new framework family. + Keep environment-reference names visible and do not resolve secret bytes for + inspection. Do not redact all provider parameters or change existing + profile/prepared output or outbound provider data. Reports are not guaranteed + safe to disclose. No speculative execution-presence JSON field is required. -1. Review the current `internal/config.Load`, `documentDefinition`, - `resolveDocument`, `validateDocument`, and `Settings`, plus CLI - `loadApplicationSettings` and `newEngine`. Confirm that the existing - ConfigKit lifecycle owns input assembly and no second merge is introduced. -2. Select only the published ConfigKit release: +## Stage 1: Select The Released Module Graph And Update Attribution + +Status: Pending. + +Files: `go.mod`, `go.sum`, `docs/oss/attribution.md`. + +1. Review the removed constructor/source/backend APIs in upstream's migration + guide. Record the current module selections before changing them. +2. Select the release and tidy: ```sh - go get gitea.maximumdirect.net/eric/ConfigKit@v0.5.0 + go get gitea.maximumdirect.net/eric/promptkit@v0.12.0 go mod tidy ``` - Review module and checksum changes. The YAML dependency remains - `go.yaml.in/yaml/v4 v4.0.0-rc.6`; keep Promptkit v0.11.2 and the selected - catalogs. Investigate incidental changes rather than silently including them. - Do not commit a workspace, replacement, or vendored dependency. -3. Inspect the selected upstream COPYRIGHT, LICENSE, and notices. Update only - ConfigKit's attribution entry to v0.5.0 and the full target commit in its - COPYRIGHT, LICENSE, and Source links. Retain its copyright statement, - LGPL-3.0-or-later expression, local LGPL/GPL links, and House Format. - Existing license texts remain applicable; no new policy-document copying - or attribution entry is needed merely to use the library. -4. Update the current ConfigKit version references in development, architecture, - and configuration documentation. Preserve policy Base Policy Version and - Upstream Source; update architecture's Last Updated date when editing its - local dependency statement. Do not revise shared policy language. -5. In `docs/config.md`, add a concise application inheritance subsection - linked to the pinned upstream contract. Explain `extends: sibling`, - inherited settings, explicit replacements, post-overlay/override expansion, - and `extends: null` cancellation. State that parents remain configured - backends, and the keyword applies beyond just the `backends` collection. - Include the reserved-key compatibility notice now so this dependency commit - does not leave accepted syntax incorrectly documented. -6. Explain that quoting does not escape `extends`. Distinguish renameable - application names from literal provider parameters whose names cannot be - changed without provider support. The current target has no escape or opt-out; - a concrete need should be handled upstream. Keep the Promptkit definition - boundary explicit. Stage 4 will add the example and remaining presentation. + Confirm ConfigKit v0.5.0, Go 1.25.5, and both `/v3` catalogs at + v3.20260930.0. Remove obsolete `/v2` requirements and `gopkg.in/yaml.v3` if + unreferenced. Investigate unrelated module changes; do not independently + advance catalogs, commit replacements/workspaces, or vendor dependencies. +3. Check the selected COPYRIGHT/LICENSE/notices. Update PromptKit's House Format + entry to the target commit. Update OpenRouter to + `f17d208cb7ad1fb043cda2266cd3011d11b40aa0` and Rakestrawhome to + `993443d88c451901f4c917fa00c204fd3b54d28d`, with `/v3` identification and + COPYRIGHT, LICENSE, and Source links. Retain applicable existing local LGPL, + GPL, and MIT texts and other component entries. Remove obsolete dependency + notices only when the final module graph no longer incorporates that material. -Validation: run the development baseline, review module/version/notice changes, -and check affected documentation links. Existing tests are expected to pass; -update an expectation only when it encodes the selected upstream change. +Validation: inspect `go list -m all`, module diff, notice destinations, and diff +whitespace. Attempt baseline checks and record the removed APIs still awaiting +Stages 3 and 7. Do not claim the upgrade builds yet. -Acceptance: ConfigKit v0.5.0 is selected, attribution identifies its actual -revision, and current documentation acknowledges the newly reserved syntax. -The application retains the existing single loading pipeline. +Acceptance: published versions and exact attribution revisions are selected; +there are no unpublished substitutions or unrelated dependency upgrades. -## Stage 2: Protect Application Loading, Presence, And Runtime Conversion +## Stage 2: Cut Over The Application Schema And Its Tests -Status: Complete. Depends on Stage 1. +Status: Pending. Depends on Stage 1. -Completion evidence: configuration tests pass for inherited settings and -presence, `Origin.Inheritance` provenance, sorted runtime conversion, imports -and overlays before inheritance, CLI overrides, working-directory-relative -paths, cancellation, and structured reserved-key diagnostics. Focused and full -tests, race tests, vet, build, and `git diff --check` passed. +Files: `internal/config/document.go`, `settings.go`, `load.go`, +`document_test.go`, `load_test.go`; related obsolete default constants only if +they actually become unused. -Files: primarily `internal/config/load_test.go` and -`internal/config/document_test.go`; production configuration files only if a -specific adoption defect requires a fix. +1. Add an application-owned `SourceSelection` value with the two YAML string + fields in the fixed choices. Put `[]SourceSelection` on `Document` and + `AppSettings` as `PromptKitSources`. Remove `PromptDir`, `ProfileDir`, + `Backends`, `BackendDocument`, and `BackendSettings` from this schema and + runtime conversion. Keep unrelated defaults and retry presence untouched. +2. In `resolveDocument`, normalize nonempty selected paths at indexed native + paths, e.g. `configkit.Keys("promptkit_sources").Index(i).Key("file")`. + Preserve order and record only actual trim/clean changes. Validate exactly + one nonblank selector field, with safe index/field diagnostics that do not + echo rejected data. Leave existence, acquisition, and domain checks to the + later engine boundary. `Settings` copies the ordered values without merging + or retaining a backend sorting pass. +3. Migrate application tests to the new schema. Retain tests for discovery, + imports, selected overlays, override precedence, safe diagnostics, + normalization, defaults, and unrelated limits. Use source-list replacement + to demonstrate overlay/explicit-override order and relative application paths. +4. Test omitted/null/empty lists, both file and directory selectors, malformed + selector shapes, unknown/retired fields, and configured nonexistent paths + accepted by application loading. Check recorded indexed normalization and + unchanged list ordering in `Settings`. +5. Remove or relocate backend-specific inheritance, provider-map, raw backend + key, and backend-conversion tests: that data no longer belongs to this schema. + Generic application inheritance remains native ConfigKit behavior; do not + add an opt-out, `Extends` field, or a substitute provider map. -Use existing `loadDocumentBytes` and `writeApplicationFile` helpers and -`TestLoadComposesExplicitImportsAndSelectedOverlay` as patterns. Add the -following bounded scenarios rather than a general fixture framework. +Validation: `go test ./internal/config`, format/diff checks, and attempted +baseline checks. Remaining production CLI references are assigned to Stage 3. -1. Add a backend-inheritance test using an actual `Document`: - - Parent `base` has an endpoint, an environment-reference name, - concurrency limit 2, queue capacity 4, and dynamic parameters - `enabled: true`, `shared: visible`, and `count: 7`. - - Child `child` extends `base`, sets queue capacity 0, and overrides - `enabled` to false. Assert inherited endpoint/reference/limit and - retained shared/count values, plus explicit zero and false replacements. - - A second child extends `base` and sets queue capacity to null. - Assert the nullable pointer remains nil rather than inheriting 4. - - Convert through `Settings(result.Config)`. Assert that all declared - backend IDs, including `base`, survive in the existing sorted order, - inherited settings survive conversion, zero capacity has a non-nil pointer, - and the dynamic integer uses the existing `int64` representation. -2. Query `result.Metadata()` for the inherited child endpoint with - `configkit.Keys("backends", "child", "endpoint")`. - Check `IsExplicit` and `Lookup`, then verify a public - `Origin.Inheritance` step links the parent field, child field, and controlling - `/backends/child/extends` path. Do not assert exact location numbers, - internal traversal counts, or all history records. -3. Add a file-backed assembly test: - - Main input imports a fragment defining `base` and declares a child - extending it. Put a relative `prompt_dir` value in the fragment. - - A selected overlay changes the parent's endpoint and gives the child an - explicit queue capacity of 0. Supply an ordinary explicit CLI override - for `server.addr` through `LoadOptions.Overrides`. - - Assert the child inherits the overlay-adjusted parent endpoint, its own - zero wins, the CLI address wins, and the relative prompt directory keeps - the current cleaning/working-directory-relative representation rather - than becoming relative to the fragment. - - Reuse the same fixture with a cancelling overlay that sets - `extends: null` and gives the child its own valid endpoint. Check that - the child no longer inherits the parent's reference or capacity. -4. Add one reserved-key failure case through `Load`: under a valid backend, - set `extra_params.extends` to a missing sibling name. Require a nil result, - use `errors.As` to reach `*configkit.LoadError`, and find - `CodeInheritanceMissing` at the directive path in `Diagnostics()`. - This protects propagation of the compatibility change without re-testing - upstream's cycle, nesting, grammar, or expansion-limit matrices. +Acceptance: application configuration has one native source-selection model, +does not read framework files, and preserves existing application semantics +outside the deliberate field removals. -Validation: `go test ./internal/config`, development baseline, formatting, -and diff checks. +## Stage 3: Wire Native Sources Through All Existing CLI Engine Paths -Acceptance: inherited input and explicit replacements retain their application -types and presence, source assembly precedes inheritance, structured failures -survive application wrapping, and `Settings` performs no hidden merge. -No new field ranges, secret handling, or source/path policies appear. +Status: Pending. Depends on Stage 2. -## Stage 3: Protect CLI Inspection And Promptkit Engine Adoption +Files: `internal/adapter/cli/application_config.go`, `run.go`, `inspect.go`, +`config.go`; add a small `framework_sources.go` if useful within this package. -Status: Complete. Depends on Stage 2. +1. Replace old directory/backend fields in command configs, common settings, + and `engineSettings` with ordered `[]appconfig.SourceSelection`. Route every + engine-using command through the same resolved settings. Remove directory + prerequisites, `errPromptDirRequired`, and unused directory-validation code. +2. Add a small repeatable source flag implementing `flag.Value` and + `flag.Getter`. Classify explicit paths with `os.Stat` as specified above; + classify the trimmed/cleaned path, but preserve the supplied spelling in + the override for ConfigKit's recorded normalization. Reject a blank argument + rather than cleaning it into the current directory. + `Get` supplies plain sequence/mapping override values. Extend + `applicationOverrides` to submit one whole-list override only when visited. + Remove `--prompt-dir`/`--profile-dir` registrations everywhere; do not keep + deprecated aliases. Retain other flags and explicit-set behavior. +3. Build `promptkit.ConfigurationSources` from the resolved list in `newEngine`. + Append one `configkit.Underlay` per entry, including an empty directory group. + File inputs use `Imports: true`; directories use the public helper and its + returned contexts unchanged. Pass `Sources`, `SchemaDir`, and + `TransientRetries` into `promptkit.Config`, retaining caller runtime options. + Delete the backend-registration loop; do not manufacture profile/backend + mappings from application settings. +4. Remove `WithPromptFS(emptyPromptDefinitionFS{}, ...)` and its filesystem + scaffolding. Both definition inspections use the complete selected sources. + Keep profile/prompt inspection free of request preparation, schema reads, + credential acquisition, and provider calls. +5. Wrap source-assembly failures with application context while preserving their + causes and `promptkit.ErrInvalidConfig`. Preserve constructor `LoadError` + chains. Use existing `writeApplicationError` for engine-load errors so native + structured diagnostics are rendered safely rather than printed as raw trees. + Surface any captured nonfatal framework diagnostics on stderr through the + existing diagnostic writer, without reloading sources. +6. Keep `serve` constructing one engine and injecting the existing restricted + artifact reader. Do not alter HTTP DTOs, retry state, request mapping, + response presentation, or cancellation coordination to repair configuration. + Update top-level usage/help for the source flag. -Completion evidence: CLI coverage passes for inheritance-free structural -inspection, inherited and replaced values, provenance, source DTO stability, -safe reserved-key diagnostics, render preparation through the inherited child, -and Promptkit validation of a configured parent backend. Focused and full tests, -race tests, vet, build, and `git diff --check` passed. +Validation: production native build must pass. Run available package checks and +record stale test field/fixture failures for Stages 5–7. Do not implement a +test-only legacy loader to hide those failures. -Files: `internal/adapter/cli/config_test.go` and -`internal/adapter/cli/run_test.go`; CLI production code only if an actual -boundary defect is demonstrated. +Acceptance: all existing production engine paths use native sources; no +removed constructor API or backend schema remains in production code. -1. Add a small file-backed parent/child fixture for CLI inspection, borrowing - existing `runCLICommand`, `writeAppConfigFile`, and inspection test - patterns. Omit framework source directories and run validation with the - referenced environment variable absent; use a synthetic name and value with - `t.Setenv` for the inspection checks. Check: - - `config validate` succeeds without credentials or a Promptkit engine. - - `config show` exposes resolved inherited endpoint/reference/ordinary - parameters and the child's false/zero values, and omits the structural - `extends` directive from effective backend data. - - `config explain --path /backends/child/endpoint` identifies parent, - destination, controlling directive, and effective endpoint. Use stable - semantic fragments rather than a complete text snapshot. - - Explanation of a replaced child parameter keeps the inherited and - replacement values visible. The environment reference remains visible; - synthetic API-key bytes never appear in successful output. - - `config sources` still uses its current JSON DTO; a one-file fixture - has one acquired file source and no fabricated inheritance source. - Parse structured output where useful; do not add output fields or promise - byte-stable upstream YAML/explanation wording. -2. Check the reserved-key failure from Stage 2 at the CLI boundary once: - `config validate` returns `ExitRuntimeError`, successful stdout is empty, - and stderr identifies the inheritance code/path through existing safe - diagnostic rendering. Avoid a complete error-string assertion. -3. Add a render integration test alongside - `TestRenderCommandUsesConfiguredCustomBackend`. Use a minimal synthetic - prompt/profile selecting a child backend. Define its endpoint on the parent - and only `extends` plus explicit replacements on the child. - Verify preparation succeeds and reports the child's backend ID and inherited - endpoint using the established prepared output contract. Stage 2 owns - detailed assertions on capacity and dynamic value conversion. -4. Demonstrate the parent is not treated as an abstract template: in a focused - variant, give the parent an invalid endpoint and the child its own valid - endpoint. Application loading may succeed, but existing `newEngine` - initialization must return an error identifiable as - `promptkit.ErrInvalidConfig`. Follow - `TestConfiguredBackendValidationComesFromPromptkit` for that boundary. - Do not add endpoint validation to ConfigKit or suppress parent registration. +## Stage 4: Migrate Maintained Definitions, Application Examples, And Testdata -Use render/preparation and real local libraries; no live provider calls or -generation fixture is needed. Reuse existing shared-server capacity tests -rather than adding a new concurrency matrix for copied backend settings. +Status: Pending. Depends on Stage 3. -Validation: `go test ./internal/adapter/cli`, development baseline, -formatting, and diff checks. +Files: maintained prompt/profile YAML under `examples/` and +`testdata/promptkit-v0.9/`; their application configs and scripts; new +framework-only backend files below those roots as described here. -Acceptance: inspection and engine construction consume the same inherited -configuration, provenance is understandable, intentional visibility is retained, -and all configured backends follow existing registration rules. +1. Wrap profile bodies in keyed `profiles` mappings, remove embedded `id`, and + convert `base_profile` to `extends`. Wrap prompts in `prompts: ID: "VERSION":` + and remove embedded identity/version fields. Quote string version keys. + Keep IDs, version selection, message text/files, schema paths, and synthetic + inputs. Do not change meaningful whitespace, session templates, cache + metadata, repair budgets, or output modes merely to modernize formatting. +2. Create `examples/framework/backends.yml` for the ordinary `local-gpu` + definition. Include it as a file group after prompt/profile directories in + both minimal and complete configurations. This is necessary even in the + minimal example: v0.12.0 validates the unused `local-gpu` profile too. +3. Move the parent/child backend definitions from `examples/config.inheritance.yml` + into `examples/framework/inheritance.yml`. That application example selects + prompt/profile directories and this inheritance file instead of the ordinary + backend file, retaining false provider data and explicit zero queue capacity. + Do not accidentally give its child lower-layer explicit values that obscure + the inheritance demonstration. +4. Keep `examples/config.composed.yml` as application imports plus its selected + overlay. Its sources fragment now supplies the complete source list. Remove + framework backend data from the application `config-fragments/backend.yml`; + move its remaining application defaults into a clearly named defaults + fragment and update the import. Retain the existing overlay's application + meaning, not an implicit framework overlay selector. +5. Move fixture-custom backend data from `testdata/promptkit-v0.9/config.yml` + into a framework-only file under that fixture root, selected by its new + application source list. Retain historical directory/script names where + still useful; these names are not format-version contracts. +6. Update scripts only where the source cutover changes invocations. Run every + migrated example through offline `render` or native framework construction. + Repair genuinely invalid unused definitions, rather than excluding their + files from discovery. Keep schema/fixture documents outside definition + directory scans. -## Stage 4: Deliver A Maintained Example And Finish Current Documentation +Validation: run both maintained render scripts, composed render with the local +overlay, and inheritance render with environment credentials absent. Check all +four example application configs with `config validate`. Native builds and +targeted example inspection must work; Go test migration is still in progress. -Status: Complete. Depends on Stage 3. +Acceptance: maintained inputs use keyed formats and native source lists, and +all effective definitions can be constructed offline with their resource origins. -Completion evidence: added and linked the complete inheritance example, finished -the configuration contract, and updated CLI-history and source-internals -summaries. All five documented validate/show/sources/explain/render commands -succeeded without provider access; affected local and pinned upstream links, -current dependency references, and `git diff --check` passed. +## Stage 5: Migrate CLI Parsing And Application-Inspection Tests -Files: new `examples/config.inheritance.yml`, `README.md`, -`docs/config.md`, `docs/cli.md`, `docs/internal/sources.md`, and -`docs/internal/adapters.md` only where its description needs correction. +Status: Pending. Depends on Stage 4. -1. Create `examples/config.inheritance.yml` with the existing example prompt, - profile, and schema directories. Define: - - `local-base`: localhost OpenAI-compatible endpoint, reference - `LOCAL_GPU_API_KEY`, concurrency limit 2, queue capacity 4, and an - illustrative `extra_params.provider_option: true`. - - `local-gpu`: `extends: local-base`, queue capacity 0, and - `extra_params.provider_option: false`. - The existing `examples/profiles/local-gpu.yml` selects the child ID. - Keep both parent and child valid ordinary backend definitions. Add a short - comment that application paths are relative to the repository invocation - directory. No new template collection or credential fixture is needed. -2. Link the new example from README's Examples list and the application - inheritance subsection in `docs/config.md`. Keep complete YAML in the - maintained file, not duplicated in prose. -3. In `docs/config.md`, finish the inheritance description started in Stage 1: - explicit zero/false/empty/null replacement subject to the schema, sibling - lookup, ordinary parent registration, eager resolution of effective - relationships, cancellation, and inspection. Link the pinned ConfigKit - contract for detailed rules. Retain migration guidance for literal keys - and named mapping entries, without implying a universal rename solution. -4. Add structural inheritance to `docs/cli.md`'s explanation-history - description. Commands and flags remain unchanged, and `sources` retains - its documented fields. Do not copy inheritance semantics into the CLI owner. -5. Update `docs/internal/sources.md` to describe post-assembly, pre-decode - inheritance and downstream runtime conversion. Link the owning config - reference. If needed, clarify native writer use in adapter internals; do - not duplicate the configuration contract. -6. Check current ConfigKit version references throughout nonhistorical docs. - Preserve old release records and explicitly historical cutover references. - Keep scope distinctions clear: ordinary application path values and - credential references retain their current meaning; Promptkit formats and - HTTP bodies do not acquire ConfigKit directives. +Files: `internal/adapter/cli/config_test.go` and parser/configuration sections +and shared helpers of `run_test.go`. -Run these example commands from the repository root: +1. Replace old field assertions with ordered source-selector assertions and old + directory arguments with repeated source flags. Retain configuration + selection, strictness, unrelated HTTP/application flags, runtime override + presence, defaults, and output-format behavior. Cases that required a prompt + directory now verify parsing without caller sources succeeds; missing prompt + selection remains an error where already required. +2. Test source flags with an actual temporary file and directory: omission + preserves the configured list; repeated flags replace it, preserve argument + order, and produce one native whole-sequence override. Test a missing/invalid + explicit path once. Use a comma-containing filename to protect one-path-per- + occurrence behavior; do not infer glob parsing or a new path grammar. +3. Migrate shared `writePromptFileWithTemplate`, `writeProfileFile`, and + `writeDefinitionFixtureConfig` to emit native keyed definitions and selectors. + Backend fixture data belongs in an explicit framework file, not application + YAML. Keep small direct helpers, not a generic legacy-to-native transformer. +4. Rewrite application `config` tests around source selections and existing + server/default fields. `config validate/show/sources/explain` must work when + configured framework paths do not exist or contain invalid definitions. + Keep source JSON shape, native history, unknown-path behavior, and safe + diagnostics. Remove app-backend-specific assertions; equivalent framework + coverage belongs in Stages 8–10. +5. Replace all stale typed field references throughout `run_test.go` now so the + CLI test package compiles, even where execution fixture contents are scheduled + for Stage 6. Verify obsolete flags/fields are rejected, not interpreted as a + compatibility path. -```sh -go run ./cmd/scriptorium config validate --config examples/config.inheritance.yml -go run ./cmd/scriptorium config show --config examples/config.inheritance.yml -go run ./cmd/scriptorium config sources --config examples/config.inheritance.yml -go run ./cmd/scriptorium config explain --config examples/config.inheritance.yml --path /backends/local-gpu/endpoint -go run ./cmd/scriptorium render --config examples/config.inheritance.yml --prompt generic.markdown_summary --profile local-gpu --input transcript=./examples/fixtures/transcript.md --input glossary=./examples/fixtures/glossary.yml -``` +Validation: CLI parser/config tests and `go test ./internal/config` must pass. +Attempt the full suite and identify only remaining execution/HTTP/report +fixture migration, not arbitrary parser failures. -The render command prepares output without calling a model. Inspect that its -selected backend is the child and the effective endpoint is inherited. The -sample parameter is illustrative, not a claim of support by a particular -provider. Validate changed local/upstream links and run diff checks. +Acceptance: CLI source override presence/order and application-only inspection +are protected without imposing filesystem validation on configured YAML paths. -Acceptance: a complete example works without credentials or provider access, -users can discover and inspect it, and current documentation describes -implemented native behavior without inventing stronger guarantees. +## Stage 6: Migrate Existing CLI Execution And Definition-Inspection Coverage -## Stage 5: Verify The Complete Work Set And Record The Handoff +Status: Pending. Depends on Stage 5. -Status: Complete. Depends on Stage 4. +Files: remaining execution/inspection sections in +`internal/adapter/cli/run_test.go`; formatting fixtures only if affected. -Completion evidence: reviewed the full change set against the planned baseline, -confirmed the dependency revision and single-load integration, all five stage -acceptance areas, the preserved compatibility and ownership boundaries, and the -absence of deferred interfaces or release automation. Final tests, race tests, -vet, build, diff checks, pinned links, and all five maintained example commands -passed. The feature roadmap now records implementation as delivered, the policy -roadmap points to its historical implementation plan, and the release handoff -is recorded below; no release was created. +1. Migrate every remaining inline prompt/profile body, backend config, engine + setup, and source argument in run/render/inspection/report/deadline tests. + Preserve the original requested behavior and observations; do not drop + optional inputs, multiple versions, profile selection, reasoning/session, + cache usage, retries, or repair coverage as fixture maintenance. +2. Review expected failures at their new boundary. Invalid unused definitions + and static templates fail construction; missing request data, selection, + schema resources, and credentials remain request/runtime concerns. Keep + typed `errors.Is` checks where available instead of old message snapshots. +3. In `TestConfiguredBackendValidationComesFromPromptkit`, replace the old + reserved-built-in-ID rejection with successful built-in backend overlay + coverage. Preserve invalid final endpoint/capacity/standard-provider-field + cases through native files. Catalog IDs are not a forbidden namespace. +4. Move parent/child backend execution tests into framework inputs. Parents + remain effective entries and receive final validation; distinct backend IDs + retain separate capacity identity. Do not require intermediate/lower domain + values to pass independent validation if overlaid before handoff. +5. Verify prompt/profile inspection uses the full source list. A profile in a + combined document must be inspectable; invalid unused prompt content in that + same selected configuration must fail construction. Keep no-provider/no- + credential-acquisition tests without restoring the empty prompt filesystem. +6. Keep prepared/profile output fields and ordinary provider-parameter + visibility unchanged. Review numeric zero expectations against their actual + new definition meaning, not accidental old omission behavior. -Files: this plan and `docs/roadmap/configkit.md`; the historical-reference -portion of `docs/roadmap/policy.md`; other previously affected files only if -a correction is needed within this scope. +Validation: `go test ./internal/adapter/cli ./internal/format` must pass, with +offline `httptest` execution coverage. Remaining full-suite blockers may only be +the explicitly unmigrated HTTP/report fixtures in Stage 7. -1. Review the complete diff against the baseline and check each roadmap - completion criterion. Confirm the dependency/notice revision, ordinary - `Load`, application presence/path/credential handling, inherited backend - mapping, inspection behavior, and maintained example. -2. Confirm no new wrappers, source APIs, redaction rules, HTTP contracts, - abstract backend behavior, cross-ID capacity pooling, unrelated dependency - upgrades, permanent validation gates, or release automation slipped in. - Correct actual divergence rather than weakening the selected tests. -3. Run final development validation if not already successful for the unchanged - Go/module/test content: +Acceptance: existing CLI workflows run with native inputs and updated boundary +expectations, without legacy parsing or narrowed valid-definition support. - ```sh - go test ./... - go test -race ./... - go vet ./... - go build ./cmd/scriptorium - git diff --check - ``` +## Stage 7: Migrate HTTP And Report Fixtures Without Changing Their Contracts - Reuse Stage 4's successful commands and links when those files are unchanged. - Record actual checks and outcomes; do not claim the exploratory review - replaced final validation. No live API, CI polling, cross-platform expansion, - or publication command is needed to complete this work set. -4. Repair the completed policy roadmap's current `implementation.md` link: - replace it with the historical Git reference - `git show 8b6c12f912b28ac00016f047f9846798a5de95d9:docs/roadmap/implementation.md`. - This is a navigation correction, not a new policy adoption. -5. Mark stages complete here only after their acceptance checks pass. - Mark the ConfigKit feature roadmap delivered, retaining target-state rationale - and deferred scope. Do not put the ordered steps into that roadmap. -6. Record a concise release handoff in this plan: ConfigKit v0.5.0, backend - inheritance, globally reserved application `extends`, no keyword escape, - parent registration, and unchanged application path/credential ownership. - The next intended minor is currently v0.16.0. Version availability checks, - its checked-in release note with COPYRIGHT | LICENSE | ATTRIBUTION links, - roadmap retirement, tagging, and publication belong to separate release - preparation under `docs/release.md`. Do not create or publish a release here. -7. Review status and staged changes, commit the completed handoff, and report - completion, verification, commit IDs, and any remaining uncommitted work. - The implementation is complete independently of release publication. +Status: Pending. Depends on Stage 6. -Acceptance: all five stages have truthful completion evidence, the feature -roadmap reflects delivery, historical navigation remains accurate, and the -final application work matches the agreed scope. +Files: `internal/adapter/http/handler_test.go`, +`internal/report/report_test.go`; other test constructors found by removed-API +search. Production HTTP/report changes require an actual integration defect. -### Release Handoff +1. Update `newHandlerEngineWithOptions`, `newDefinitionHandler`, session fixtures, + shared-capacity setup, and `newRetryHandler` to keyed definitions and native + underlays. Replace test `WithBackend` with a keyed backend file or public + `BackendSource` in a later group. Use pointer fields when programmatic zero + is deliberate. Retain injected clients/artifact readers. +2. Migrate the report package's real-engine fixture and any remaining removed + construction APIs. Do not change observation/report data, presence totals, + opt-in behavior, or privacy choices simply because configuration moved. +3. Retain HTTP request/status/strictness tests, input containment and byte limits, + retry/deadline cancellation, shared backend capacity, per-request report + isolation, and response-size behavior. Keep one shared engine in concurrency + tests and measure against test-controlled limits. +4. Reclassify only intentionally changed construction failures; handler request + errors retain existing status/public sentinel mapping. Static definition + errors should not be manufactured as per-request HTTP failures after startup. + Runtime `extra_params` remains provider data, including a literal `extends` + key; do not run request payloads through ConfigKit inheritance. -Scriptorium now selects ConfigKit v0.5.0 and supports backend inheritance. -`extends` is globally reserved in application input mappings and has no escape -in this upstream version. Parent backends remain registered ordinary -backends. Application paths remain working-directory-relative, and -`api_key_env` remains a visible environment-variable name passed to Promptkit; -Scriptorium does not resolve credential values through ConfigKit. The next -intended minor is currently v0.16.0. Version availability checks, its release -note and notice links, roadmap retirement, tagging, and publication are separate -release-preparation work under `docs/release.md`; no release was created here. +Validation: targeted HTTP/report tests followed by all development baseline +checks. The entire repository must now compile and pass, not just selected +packages. Search production and test construction sites for removed APIs. + +Acceptance: the migration window is closed, with existing CLI/HTTP/report +contracts and shared operational state preserved. + +## Stage 8: Protect Native Source And Definition Semantics At The App Boundary + +Status: Pending. Depends on Stage 7. + +Files: a focused `internal/adapter/cli/framework_sources_test.go` and existing +adoption tests where they already own the behavior. Reuse migrated helpers. + +Implement these bounded scenarios with real engine construction: + +1. **Assembly and final values:** two files in one directory conflict on a + scalar; the same definitions in two ordered source entries overlay instead. + An invalid lower domain value replaced by a valid upper value succeeds, + while a malformed source or invalid final unused definition fails. An empty + directory contributes nothing. One combined document supplies backend, + profile, and prompt values. Do not duplicate upstream's grammar matrix. +2. **Origins and capture:** select a file importing a prompt fragment with a + relative `content_file`; inherit that prompt version via native `extends` + and select the derived version. Assert correct fragment-relative content, + not process-relative content. Construct an engine, edit the message file, + and verify its next preparation still uses captured text; a newly constructed + engine observes the edit. Use schema/artifact fixtures to retain existing + preparation-time behavior without adding an all-files atomicity guarantee. +3. **Inheritance and presence:** use two synthetic backends and a child profile + changing its parent's backend/model. Assert the new backend's derived + endpoint/environment source is used while explicit parent controls remain. + In a related profile, clear a provider control/environment source with null, + set `max_tokens: 0`, `timeout_seconds: 0`, and a false nested provider value, + and check recursive retention of other fields. An injected capture client + must inspect `GenerateRequest.TargetPresence` to prove presence reaches the + provider boundary; use recorded HTTP JSON if asserting actual wire inclusion + or omission. Scalar prepared output alone cannot prove either. Cover + whole-map null suppression versus empty-map retention + with a small additional case where needed. +4. Reuse or extend existing tests for partial profiles completed by request + overrides and exact literal prompt/profile/version keys, including a slash + and meaningful whitespace. No adapter trim/re-key operation may invalidate + an otherwise usable native definition. Keep full feature fixtures for cache, + sessions, roles, output validation/repair, and schema linkage. + +Validation: focused adoption tests and development baseline. If a public +upstream capability is defective, report a minimal reproducer instead of +copying internals or silently narrowing supported definitions. + +Acceptance: source order, capture/resource origins, null/presence, and complete +definition plumbing are protected at the actual application boundary. + +## Stage 9: Add Captured Framework Validate, Show, And Sources Commands + +Status: Pending. Depends on Stage 8. + +Files: `internal/adapter/cli/inspect.go`, a small +`framework_config.go` and `framework_config_test.go` in that package. + +1. Dispatch `inspect configuration` separately from existing prompt/profile + modes. Implement the shared parser with the flags in the fixed choices and + the first three operations. Stage 10 adds `explain`; the new family is not + complete until then. Reject positional arguments through normal flag parsing. +2. Load application settings and print their diagnostics, construct exactly one + engine through `newEngine`, and obtain its public `InspectConfiguration` + view. Print applicable captured diagnostics safely. Do not resolve selected + credentials or prepare a placeholder request. All outputs refer to this view. +3. `validate` returns 0 without success output after successful construction; + `show` calls `WriteEffective(stdout)`. Keep native field presence and YAML, + not a reloadable-file promise or a formatter copy. +4. Define the framework source DTO specified above and project `view.Sources()` + into it, including the optional import location. Encode a non-nil ordered + slice with `json.Encoder`; do not expose raw exported Go field names or + filesystem contexts. Keep application `configurationSource` untouched. +5. Test no selection/credential requirement, final-definition failure before + reporting, YAML values, and source JSON kinds/layers/relative ordering. + Identify selected synthetic inputs by path/label; do not pin catalog counts, + literal source IDs, or caller underlay starting indices. Check stdout/stderr + separation and a failing output writer. + +Validation: focused framework inspection tests, existing inspection/config +tests, and development baseline. + +Acceptance: three captured framework operations work without confusing their +scope with application inspection or altering existing presentation contracts. + +## Stage 10: Add Literal-Path Explanations And Prove Scoped Redaction + +Status: Pending. Depends on Stage 9. + +Files: framework inspection parser/handler/tests from Stage 9. + +1. Add `explain`; require explicitly set `--path`, parse via + `configkit.ParsePath`, and allow the empty root pointer. Use `view.Explain` + to detect an unknown path before `WriteExplanation`: PromptKit's native + writer otherwise produces no output for unknown paths. Report malformed or + unknown paths as exit 1 consistently with application inspection. +2. Test inherited and overlaid values, displaced history, root explanation, + `/profiles/team~1summary/model`, and a literal dotted key. Do not convert + IDs into a dotted-path grammar or implement history traversal yourself. + Test missing mode/path, malformed pointer, unknown pointer, and writer errors + at the CLI boundary without exact native prose snapshots. +3. Use controlled lower/upper framework files with ordinary visible parameters + and synthetic `token`/`password` sentinel values. Verify `show` and effective/ + historical `explain` output redact those native-classified fields, while + environment-reference names and ordinary values remain visible. Include a + displaced sentinel to protect history, not just the final effective value. +4. With the same valid profile, verify existing `inspect profile` and prepared + output still expose ordinary configured provider data according to their + existing policy. Inspecting an API-key environment reference must never + emit its synthetic environment value. Do not add new redaction to existing + formatters or change the values sent to a capture client/provider. +5. Keep application `config validate` successful for a valid selector document + referencing an invalid framework definition, while framework `validate` + fails. Test source/load diagnostics on stderr without partial successful + reports for pre-report failures. Native writer failures may leave partial + output, as existing inspection does; add no transactional-output machinery. + +Validation: focused new-family and existing inspection tests, development +baseline, and all four operations against maintained examples. + +Acceptance: the full CLI family uses captured native reports, with the approved +redaction exception limited to it and application/framework scopes distinguishable. + +## Stage 11: Update User Contracts And Upgrade Guidance + +Status: Pending. Depends on Stage 10. + +Files: `docs/config.md`, `docs/cli.md`, `docs/operations.md`, `README.md`, +affected executable-consumer guidance and example scripts. + +1. Make `docs/config.md` own the new sequence shape, selectors, defaults/empty + list, order, relative paths, imports, and application overlay/list replacement. + Remove application backend-field documentation and directory prerequisites. + Describe native framework source assembly briefly and link to v0.12.0 for + definition semantics. Keep application versus message-resource path policies + distinct and preserve HTTP artifact policy. +2. Make `docs/cli.md` own repeated source flags, removed flags, command-specific + accepted flags, all four framework inspection operations, source JSON DTO, + JSON Pointer usage, exit/output behavior, and scoped redaction. Link to owning + configuration/upstream contracts rather than maintaining a second format spec. +3. Update operations for eager validation and captured message content, server + restart to obtain a new engine, runtime schema/artifact/credential boundaries, + and the operator choice between application and framework validation. + Explain sensitive report handling without claiming arbitrary content is safe. +4. Provide concise before/after migration examples for application selectors, + backend relocation, keyed IDs/versions, `base_profile` to `extends`, and + zero/null/map semantics. Put executable upgrade guidance in + `docs/consumers/upgrading-promptkit.md`, linked from the configuration contract + and README; link upstream for details. Complete copyable inputs remain in + `examples/`. Do not rewrite historical releases or the former Go-package + migration's historical version claims as though they were current adoption. +5. Update README's dependency and navigation links, keeping its licensing footer. + Update/rerun affected example commands. No live model calls are needed to + demonstrate migration; leave HTTP generation walkthroughs identified as + requiring a deployed provider, not a default validation task. + +Validation: run changed offline commands and scripts; verify owning facts +against implemented flags/schema, links, and diff whitespace. + +Acceptance: operators can migrate and use the new interfaces without mistaking +framework inspection for application validation or expecting automatic reload. + +## Stage 12: Align Developer, Internal, And Architecture Documentation + +Status: Pending. Depends on Stage 11. + +Files: `docs/development.md`, `docs/internal/overview.md`, `adapters.md`, +`sources.md`, `docs/policy/architecture.md`, and affected current consumer/API +cross-references. No general policy adoption is part of this stage. + +1. Advance current PromptKit links to the selected release. Update the developer + reading guide for native sources and captured framework inspection, leaving + generic selective policy-reading guidance and policy baselines unchanged. +2. Describe implemented source selection and shared wiring in internal docs. + Remove backend-registration/conversion and empty-prompt-filesystem claims. + State that ConfigKit loads both application and framework configuration under + their respective schema/domain owners; Scriptorium does not parse PromptKit + definitions. Keep concrete helpers/package inventory in internal docs. +3. Update architecture's local framework version, ownership description, and + approved scoped framework-report redaction. Preserve upstream policy wording, + Base Policy Version, Upstream Source, and ADR decisions; update its Last + Updated date for the local edits. Keep requests independent and the server + engine/capacity shared. Do not harden HTTP lexical containment into symlink + sandboxing because framework content roots have a different upstream policy. +4. Review current API/consumer references for real migration impact. Preserve + HTTP wire fields and error/status guarantees unless an actual upstream + integration change requires correction. Add no HTTP configuration endpoint, + broad new invariant, secret-display guarantee, or inventory compatibility + promise. Historical roadmap/release/ADR references may remain pinned to the + versions they actually describe. + +Validation: check relevant links and concrete assertions against the new code; +run changed offline commands if any. Review the architecture diff specifically +for unrequested strengthening and duplication of canonical contracts. + +Acceptance: current documentation describes the implemented architecture while +historical records and unrelated policy baselines retain their meaning. + +## Stage 13: Complete The Adoption Audit And Record The Release Handoff + +Status: Pending. Depends on Stage 12. + +Files: small genuine corrections exposed by validation, this plan, and the +feature roadmap's completion status. Release files/automation remain out of scope. + +1. Audit each roadmap requirement against implementation and focused evidence: + native sources, full keyed definitions/presence, resource origins/capture, + eager final validation, request/runtime boundaries, complete framework + inspection, scoped redaction, and shared server capacity. Confirm no removed + API, old application schema, legacy loader, direct catalog/internal import, + replacement, or workspace remains in executable code and maintained inputs. + Do not flag old names merely because they appear in historical docs. +2. Run the complete development baseline on the final code. Review the final + module graph, attribution links, formatting, and affected documentation. + Build outside the tree so no generated binary becomes a committed artifact. +3. From the repository root, validate all maintained application examples and + run both render scripts, composed-overlay render, and inheritance render. + Exercise every new operation with `--config ./examples/config.full.yml`, + including `explain --path /backends/local-gpu/endpoint`, plus existing + prompt/profile inspection. Use synthetic/unset credentials and no provider + traffic. Reuse equivalent completed checks where code/inputs are unchanged. +4. Resolve real remaining failures. Do not mark a stage complete from intent or + partial green checks. Update every stage's evidence, this introduction, and + `promptkit.md` to say implementation is delivered only when the full audit + passes. Keep the roadmap as target/decision context, not a second stage log. +5. Record that the breaking configuration/definition adoption requires a new + pre-1.0 minor release and may share it with the completed ConfigKit work. + Version selection, release notes, roadmap retirement, and publication are + subsequent release-preparation work, not new gates or actions in this sprint. + Review status/index and commit the completed unit with a plain-English message. + +Acceptance: all thirteen stages and the complete roadmap are implemented and +verified; status is internally consistent; the workspace is ready for separate +release preparation without claiming a release has been published. ## Open Questions -None within the accepted scope. Native inheritance and its reserved-key -compatibility change, visible ordinary parameters and reference names, existing -source/path policies, and deferral of new source APIs are already selected. -A future concrete requirement to pass literal provider `extends` data needs -upstream consideration; it is not an unresolved implementation decision for -this work set. +None within the agreed scope. Native source cutover and native framework +inspection with redaction limited to the new family were explicitly confirmed +on 2026-10-04. The implementation choices above resolve the remaining interface +details without adding an upstream dependency on unreleased functionality.