From 222f4056e6322b7ee17baf36f8c88ca812163c9c Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 17 Nov 2026 20:40:57 +0000 Subject: [PATCH] Plan native ConfigKit migration --- docs/roadmap/configkit.md | 5 +- docs/roadmap/implementation.md | 1176 ++++++++++++-------------------- 2 files changed, 423 insertions(+), 758 deletions(-) diff --git a/docs/roadmap/configkit.md b/docs/roadmap/configkit.md index bd944de..4ece702 100644 --- a/docs/roadmap/configkit.md +++ b/docs/roadmap/configkit.md @@ -16,8 +16,9 @@ remain Scriptorium's responsibilities under This replaces the completed v0.5.0 roadmap, preserved at `ba24b7a879c95e2b306e0d53eb0b45e043e1b29a:docs/roadmap/configkit.md`. -The existing [implementation document](implementation.md) concerns the previous -PromptKit work set and is not the implementation plan for this upgrade. +The [implementation plan](implementation.md) owns the staged changes and +validation for this upgrade. This roadmap owns the target state, scope, and +policy choices; implementation status and stage evidence belong in that plan. ## Reviewed Baseline And Target diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 6f1b57a..c9da53b 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,780 +1,444 @@ -# PromptKit v0.12.0 Implementation Plan +# ConfigKit v1.2.0 Interim Implementation Plan ## Status, Baseline, And Authority -Planned on 2026-10-04 against Scriptorium -`82b0f231b6ba71328f65f9a501143b2eedbe5d9c`. All thirteen stages are complete; -the implementation was delivered after the full audit passed on 2026-10-04. -Separate release preparation remains pending. The -[feature roadmap](promptkit.md) owns the target state, scope, and confirmed -product decisions; this document records implementation steps and status. +Planned on 2026-11-17 for a Luna coding agent against Scriptorium +`a5d8394313c4cbdee8e8618844e65364c70189e9`. All stages below are pending. +The [feature roadmap](configkit.md) owns the target, rationale, native-semantics +policy, and confirmed interim sequencing decision. This document owns the +ordered implementation work. -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. +This replaces the completed PromptKit v0.12.0 implementation plan, preserved at +`a5d8394313c4cbdee8e8618844e65364c70189e9:docs/roadmap/implementation.md`. +Do not execute that earlier plan again. -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. +Adopt application `go.maximumdirect.net/configkit v1.2.0` at +`c1c7e87f2cdf77a0cbf3327831ac05578e756b9e`. Retain +`gitea.maximumdirect.net/eric/ConfigKit v0.5.0` at +`dc09959cca4e105f49ec316c6d4ba585bd2340bd` where the unchanged +`gitea.maximumdirect.net/eric/promptkit v0.12.0` public API needs its types. +Keep go-yaml v4.0.0-rc.6 and the existing PromptKit catalog selections. -## Execution Discipline +Use ConfigKit's pinned +[consumer guide](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/consumers/README.md), +[configuration contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/config.md), +and public root-package declarations. The sibling checkout currently contains +v1.2.1; read the selected tag or downloaded v1.2.0 module, not unqualified sibling +HEAD. Keep PromptKit behavior tied to its existing tagged contract. -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. +Planning evidence: a temporary module resolved both ConfigKit identities, +PromptKit v0.12.0, and the existing YAML prerelease. Package compilation with +`go test -run '^$'` passed for all three libraries on Go 1.27.4. This does not +constitute an application migration or test pass. Stable YAML cannot be selected +in this interim graph because old ConfigKit imports its removed +`plugin/limit` package. -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. +## Sprint Execution Rules -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. +Implement Stage 1 through Stage 7 in order as one end-to-end sprint. Intermediate +stages may fail compilation or tests and need not be independently deployable. +Do not add compatibility layers, temporary alternate loaders, skips, or weakened +tests just to make an intermediate stage green. Use focused checks as useful +feedback, record failures accurately, and continue when the remaining work is +expressly assigned to later stages. Investigate unrelated failures. Only the +completed end state must pass the full validation. -### Bounded Migration Window +Start with working-tree inspection and the task reading guides in +`docs/development.md`. Follow the agent policy and applicable architecture, +testing, documentation, OSS, and release policies. Use the graph for code +discovery. Keep completed-stage evidence here concise and accurate; commit +focused completed units under the agent policy. -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. +The work is native ConfigKit adoption, not preservation of old processing +semantics. Keep application schema, domain defaults, normalization, validation, +path interpretation, and CLI selection choices with Scriptorium under ADR 0005. +Imports, composition, inheritance, decoding, inspection, and processing order +belong to the selected library. Do not introduce new restrictions, limits, +identity rules, sensitivity heuristics, or guarantees because they are convenient +to assert. -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. +This sprint does not upgrade PromptKit, migrate its module path, select ConfigKit +v1.2.1 or stable YAML, add configuration commands/endpoints, change resource paths +to source-relative interpretation, or adopt ReleaseKit. HTTP request independence, +shared backend capacity, artifact handling, credential disclosure, execution +controls, and existing request/response contracts are not redesign targets. +The existing restriction on committed workspaces, replacements, vendoring, and +framework internals remains applicable. -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. +Use real temporary files and the existing assembled collaborators for tests; +provider interactions use existing fakes or loopback HTTP servers. Default tests +stay offline and credential-independent. Prefer typed errors, diagnostic codes, +effective values, and meaningful history over native prose snapshots or fixed +source IDs. Reuse unchanged successful checks; do not run the entire baseline +after every intermediate edit. Final validation is in Stage 7. -## Fixed Implementation Choices +## Stage 1: Select The Interim Dependencies And Go Toolchain -These choices implement the confirmed roadmap without adding another product -decision: +**Work** -- 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. Select Go 1.27.4 for release validation and builds. It is available from the + [official Go downloads](https://go.dev/dl/), and the official + `golang:1.27.4` image supports the existing Linux targets. + Provision the toolchain and dependency cache before offline validation. +2. Set the consumer directive in `go.mod` to `go 1.27.0`, as required by + ConfigKit v1.2.0. Add the exact vanity module version without removing the + old ConfigKit requirement or changing PromptKit, catalogs, or YAML. + The application module path remains unchanged. +3. Use ordinary Go module commands to update required sums. Defer final + `go mod tidy` until source imports are migrated, so the newly selected + dependency is not removed merely because it is not used yet. Do not add a + `tool` entry for upstream maintainer tools or require Go 1.27.4 from all + consumers through a new toolchain directive. +4. Change only the Go build image in `.woodpecker/release.yml` from 1.26.11 to + 1.27.4. Retain `GOTOOLCHAIN=local`, build targets, publication configuration, + and asynchronous delivery behavior. No release-script gate or workflow + redesign is needed. -## Stage 1: Select The Released Module Graph And Update Attribution +**Verification focus** -Status: Complete. The published PromptKit v0.12.0 graph and both selected `/v3` -catalogs are pinned and attributed at their verified commits; ConfigKit and Go -remain unchanged. `go mod tidy` removed obsolete `/v2` and direct YAML -requirements, while `gopkg.in/yaml.v3` remains transitive through both catalogs -and retains its notice. Baseline checks expose the expected removed PromptKit -API references in CLI production code (Stage 3) and HTTP/report test fixtures -(Stage 7); the upgrade is not yet buildable. +Inspect `go list -m all` for the exact selected modules above. Tool-only graph +requirements may appear without being runtime imports; inspect actual selection +rather than delete them or upgrade unrelated modules speculatively. Compile +failures from the remaining application migration belong to subsequent stages. +Do not publish, tag, push, or invoke the release script. -Files: `go.mod`, `go.sum`, `docs/oss/attribution.md`. +## Stage 2: Move Application Loading And Resolution To Native v1.2.0 -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: +**Primary files:** `internal/config/document.go`, `load.go`, and `settings.go`. + +**Work** + +1. Change application ConfigKit imports to `go.maximumdirect.net/configkit`. + Keep `Document`, its field schema, `LoadOptions`, `AppSettings`, and + `Settings` responsibilities. Preserve fresh defaults, selector order, + nullable retry presence, domain validation, and working-directory-relative + application resource strings. Add no framework-resource acquisition to + application validation. +2. Replace the `os.Stat` loop in `Load` with source selection only: + + - explicit selection: `configkit.File(options.Path)`, even for a blank + explicit argument, leaving its failure to ConfigKit; + - implicit selection: + `configkit.SearchConfig("scriptorium", configkit.SearchPaths(defaultConfigSearchPaths...))`. + + Retain the existing ordered two-location slice and test substitution seam. + Construct the search for each load. Remove the `fileBacked` bookkeeping, + filesystem probing, and hand-written discovery error formatting. +3. Call ordinary `configkit.Load` once with the existing definition, selected + overlay, explicit overrides, and `Imports: true`. Leave import defaults, + filesystem context, source-version policy, and sequence registrations unset. + Optional discovery exhaustion follows native absent-main behavior. +4. Keep the existing contextual load-error wrapper with `%w` so the new + `*configkit.LoadError` remains discoverable. Do not recover by searching + another file after a selected candidate fails. +5. In `resolveDocument`, keep field-level `Normalize` calls. Remove the + `sourcePathsChanged` aggregation and redundant generic whole-list + `resolution.Record` call. Simplify the local path-normalization helper's + boolean result if it has no other caller. Use `RecordNormalization` only + for actual direct mutations requiring it; no replacement container record + is necessary for today's same-length list-field edits. +6. Preserve ordinary native control and collection handling. Add neither + legacy control aliases nor application filtering of declared imports, + inference of collection identity, or a second composition pass. + +**Verification focus** + +Review the loader against the selected public lifecycle and the resolver against +v1.1+ leaf recording. Existing unit tests still require import/syntax changes in +Stage 4. Do not broaden `LoadOptions` or introduce a filesystem/merge framework +to preserve the old test setup. + +## Stage 3: Separate Application And Framework Types In CLI Adapters + +**Primary files:** `internal/adapter/cli/application_config.go`, `config.go`, +`run.go`, `inspect.go`, and `framework_config.go`. + +Use `configkit` for the new application package and `legacyconfigkit` for +the old package where both are imported. + +| Boundary | ConfigKit owner | +| --- | --- | +| Application overrides, paths, results, stored diagnostics, and writers | Vanity v1.2.0 | +| `newEngine` input/underlay construction and `promptkit.DirectoryInputs` values | Old-path v0.5.0 | +| Captured framework paths, native source records, diagnostics, and writers | Old-path v0.5.0 | + +**Work** + +1. Migrate `applicationOverrides`, `loadApplicationSettings`, and + `writeApplicationWarnings` to new public types and writers. Migrate stored + application diagnostics in run, serve, common-command, prompt/profile + inspection, and framework-command selection structs. The latter's + `overrides` and pre-engine `diagnostics` are still application-owned. +2. Keep `newEngine`'s `Input`, `Underlay`, and `File` calls old-typed. + Continue passing `promptkit.DirectoryInputs` output directly to that old + boundary. Keep source ordering, underlay grouping, retry defaults, and shared + server engine construction unchanged. +3. `configCommand` uses new paths and writers. Its existing + `configurationSource` DTO uses the new `Layer` type, yielding `main` + for application file sources. Keep its JSON shape and empty-array behavior. +4. Framework `explain` parses paths with `legacyconfigkit.ParsePath` and + passes them to the existing view. Keep `frameworkConfigurationSource`, + `frameworkConfigurationSources`, `Layer`, and `SourceKind` old-typed; + it is already a separate DTO, so no new shared conversion type is needed. +5. In `inspectFrameworkConfigurationCommand`, retain the new application + warning call for `cfg.diagnostics`. Send `view.Diagnostics()` directly + to `legacyconfigkit.WriteDiagnostics`, propagating writer failure through + the existing runtime-error exit. Keep native framework output and its + established scoped redaction. +6. Preserve structured error presentation for both generations. In the existing + common `writeApplicationError` helper, check for the new `*LoadError` + and then the old `*legacyconfigkit.LoadError` with `errors.As`, sending + each one's diagnostics to its matching writer. Retain current handling of + diagnostic-write failure and the fallback for non-load errors. This small + explicit dispatch preserves errors from engine construction as well as + application loading; it is not a cross-version data-conversion layer. +7. Audit actual ConfigKit references by owner rather than globally replacing + imports. No casts, YAML/JSON round trips, or duplicate configuration result + representations are needed between these generations. + +**Verification focus** + +Check both native writer signatures and all CLI construction paths. Compilation +provides useful feedback, but stale tests/fixtures remain assigned below. Neither +successful application configuration validation nor its inspection should +construct a PromptKit engine. + +## Stage 4: Migrate And Extend Application Configuration Tests + +**Primary files:** `internal/config/document_test.go` and `load_test.go`. + +**Work** + +1. Migrate their imports, error assertions, paths, and `LayerBase` references + to the new package and `LayerMain`. Change application input controls from + `configkit` to `config`, marking indispensable imported fixtures + `required: true`. Do not edit framework-definition fixtures as if they + were application documents. +2. Retain and adjust existing discovery/defaults tests. Cover the first + candidate, a missing first candidate selecting the second, optional + exhaustion, explicit missing/blank selection, and a malformed or nonregular + selected candidate that does not fall through to a valid second file. + Reuse `useConfigSearchPaths`; tests that mutate that package state remain + nonparallel and restore it through cleanup. +3. Update `TestLoadDiscoveryErrorQuotesPath` to inspect a typed load error's + rendered diagnostics, not demand that `LoadError.Error()` contain a path. + Keep the real protection: terminal control characters in a failing path are + escaped by the native writer. A deterministic nonregular candidate can be + used instead of requiring host symlink support. +4. Rename/reframe `TestLoadRejectsOverlayWithoutBase` around this application's + absent-main/no-context selection. It should still fail for an active overlay, + while `default` selects none. It must not claim ConfigKit universally + prohibits overlays without a main or imports on an absent main. +5. Add focused import coverage: missing optional input succeeds with omitted + requiredness, the corresponding required input fails, and the removed + `optional` field fails. Use one `dir` import with an authored YAML + pattern and `destination: [server]` to mount a fragment containing `addr`. + Verify final application values and an applicable origin, not a complete + upstream traversal/filter matrix. +6. Demonstrate native collection policy on the existing selector list with + YAML `config.sequences`, `destination: [promptkit_sources]`, `key: file`, + and `mode: upsert`. Use only file-selector records in that fixture. + Distinct imported peers combine; a duplicate authored identity conflicts; + an overlay appends a new identity while retaining lower records. + Contrast unkeyed whole-list replacement and explicit CLI whole-list + replacement. These are authored policies, not Go identity registrations. +7. Cover changed CLI timing with a paired case: a source value with a decoding + type error still fails despite a replacing override; a decodable value + failing application validation can be corrected by an override. + Retain explicit zero/false/empty/allowed-null tests where applicable to the + schema and callbacks; create no new fields solely to assert all categories. +8. Keep effective-value, source-order, snapshot, and normalization coverage. + For a changed selector leaf, assert its normalized result and recorded + normalization history; for an unchanged leaf, assert no invented operation. + Avoid testing incidental history counts or private callback choreography. + +**Verification focus** + +Run `go test ./internal/config` when useful. Preserve distinct regression +protection already present; consolidate overlapping assertions rather than +clone ConfigKit's complete format suite. + +## Stage 5: Migrate CLI Integration Fixtures And Maintain Runnable Examples + +**Primary files:** CLI configuration/execution/inspection tests and +`examples/`. Review HTTP/report test helpers only for their ConfigKit owner. + +**Work** + +1. In CLI tests, use new ConfigKit for application-load errors/diagnostics and + old ConfigKit for framework engine setup and captured view records. + Specifically review `run_test.go`, `framework_sources_test.go`, and + `framework_config_test.go`. Keep the old imports in the HTTP + `newHandlerEngineFromDirectories` helper and report engine-construction + test, because they construct PromptKit sources rather than load application + settings. +2. Migrate application control literals in `config_test.go` and + `run_test.go` to `config.imports`, with explicit requiredness when + absence should fail. Retain framework controls in the generation selected + by PromptKit v0.12.0. Keep pre-existing backend-inheritance coverage in the + framework, where those backend definitions now live. +3. Exercise the Stage 3 dispatch using real failed new application loads and + failed old framework loads. Keep stdout clean on failures, native diagnostics + on stderr, and diagnostic/output writer-failure coverage. Existing framework + `show`, `sources`, and `explain` tests protect the old path, records, and + redaction; update only expectations actually owned by new application loading. +4. Protect an assembled path that loads new application imports and an overlay, + then renders through unchanged PromptKit definitions. Include a framework + file with its supported old import controls so blanket control renaming would + be detected. Continue application-only inspection coverage with nonexistent + framework resources to prove it does not acquire them. +5. Change `examples/config.composed.yml` to root `config.imports` and add + `required: true` to its source-selection fragment. Other ordinary application + and framework examples change only when their actual owner requires it. +6. Add this concrete, small collection example using existing framework files: + + - `examples/config.collections.yml`: ordinary application main; import + directory `config-fragments/collections` with `pattern: "*.yml"` and + `required: true`; declare `promptkit_sources` identity `file` and + `mode: upsert` under root `config.sequences`; set + `schema_dir: ./examples/schemas`. + - In that imported directory, `10-backends.yml`, `20-profile.yml`, and + `30-prompt.yml` each contribute one file selector, respectively + `./examples/framework/backends.yml`, + `./examples/profiles/local-fast.yaml`, and + `./examples/prompts/generic.markdown_summary.yaml`. + - `examples/overlays/collection.yml` adds one file selector for + `./examples/profiles/local-gpu.yml`. The inherited upsert policy retains + the three lower selectors and appends the new one. + + No new `id` field, default registration, runtime merge logic, or copied + framework definition is needed. Application path strings remain relative to + the repository invocation directory. +7. Exercise the maintained collection main and overlay through the application + load and at least one no-generation render with the transcript and glossary + fixtures. Compare effective selector order/retention and a real prepared + result, not a giant native-text golden. Reuse tests from Stage 4 where their + risk is already covered. +8. Finish `go mod tidy` after the imports are in place. Confirm the exact + interim versions and distinguish tool-only module requirements from the + runtime graph. Leave implementation of v1.2.1 and the upcoming PromptKit + roadmap to the separate work set. + +**Verification focus** + +Run affected CLI tests and the existing HTTP/report suites as warranted by +changed imports. All fixtures must eventually compile with both identities. +New source-list composition must reach the old framework boundary in order; +do not sort or deduplicate it to repair a test. + +## Stage 6: Update Canonical Documentation And Both ConfigKit Attributions + +**Work** + +1. Update `docs/config.md` for application ConfigKit v1.2.0 and native + discovery. Describe the actual processing order, optional import default, + explicit `required`, expanded selectors/placement, authored collection + policy, and CLI timing. Correct unconditional statements that overlays always + replace lists and defaults-only loading cannot enable imports. Explain that + this CLI supplies no independent overlay root; the context limitation is + not a universal library prohibition. +2. Clearly distinguish application root `config` controls from the unchanged + PromptKit v0.12.0 framework contract. Keep working-directory-relative resource + values, strict application schema, and current credential handling. Link to + the pinned upstream contract for detailed grammar instead of copying it. +3. Update `docs/cli.md` for application `main` provenance and changed + application loading behavior. Keep source JSON fields, command flags, + streams, and exits otherwise unchanged; framework inspection continues to use + its own old native types and writers. Add no new source-detail or diff command. +4. Update README example navigation and the owned configuration examples. + Add copyable inspection and render invocations for the collection example. + Use `--config-overlay collection` for its added selector and both existing + input fixtures for `generic.markdown_summary`; no provider connection or + credential is needed for these render checks. +5. In `docs/development.md`, document Go 1.27.0 as the consumer floor because + of application ConfigKit, and point release builds to Go 1.27.4. Update + `docs/release.md`'s selected toolchain, installation path example, and version + output to 1.27.4, matching the image from Stage 1. Leave release commands, + gates, footer conventions, and publication completion unchanged. +6. Update `docs/internal/sources.md`, `docs/internal/adapters.md`, and the + overview as affected: native discovery, two ConfigKit generations, leaf + resolution recording, warning/error dispatch, and actual selector conversion. + Remove the obsolete claim that application backend IDs are sorted. + Update only the architecture policy's affected dependency/boundary description + and local date; preserve its base version, upstream provenance, and adopted + decisions. Accepted ADR content stays unchanged. +7. In `docs/oss/attribution.md`, retain a distinct entry for old-path ConfigKit + v0.5.0 used by PromptKit and add application ConfigKit v1.2.0. Use factual + headings/identification to distinguish them, the actual copyright and + `LGPL-3.0-or-later` grant, and shared local LGPL/GPL text links. + New ConfigKit source/notice links use forge commit + `c1c7e87f2cdf77a0cbf3327831ac05578e756b9e`; legacy ConfigKit uses its + retained commit `dc09959cca4e105f49ec316c6d4ba585bd2340bd` at that same + canonical ConfigKit repository. Verify notice files at both revisions. +8. Preserve unchanged PromptKit, catalog, YAML prerelease, and other dependency + notices. Inspect newly selected runtime material and add notices only if + actually incorporated or distributed; upstream ReleaseKit, Goldmark, and + Go module tooling requirements alone are not runtime inclusion. No project + relicense, new standard-text copies, or tool adoption follows automatically. +9. Keep the feature roadmap as target/context rather than a duplicate step log. + Preserve the explicit v1.2.1/stable-YAML/old-module-removal handoff to the next + PromptKit roadmap. Do not overwrite the completed historical PromptKit + roadmap or invent a release version to create a versioned release note. + +**Verification focus** + +Verify current facts against implementation, affected local links and pinned +source paths, license-text fidelity, and changed example commands. Preserve +published release notes and tags. The eventual new minor release and its note +remain separate preparation; this stage does not authorize publication. + +## Stage 7: Validate The End State And Record The Handoff + +**Work** + +1. Review the entire diff for unintended contract strengthening or obsolete + compatibility logic: native search rather than probes; default optional + imports; no default selector identity; post-decode CLI assignment; leaf + normalization; no new redaction, filesystem policy, or framework processing. + Confirm all imports, paths, diagnostics, and writers belong to their owner. +2. Inspect `go list -m all` and `go list -deps ./cmd/scriptorium` under the + selected release toolchain. Verify both ConfigKit identities at their exact + versions, unchanged PromptKit/catalogs/YAML, no replacements/workspaces, and + the intended runtime versus tool-only dependency distinction. Do not freeze + the entire dependency inventory into a new permanent test. +3. Format changed Go code and run the existing development baseline once against + the final source: `go test ./...`, `go test -race ./...`, + `go vet ./...`, and a native `go build` of `./cmd/scriptorium` with + output outside the repository. Use existing offline/provider-independent + fixtures; loopback test servers are local test infrastructure, not live probes. +4. Check both release targets with the existing build settings. With Go 1.27.4 + already selected and the dependency cache provisioned, the following are + validation commands, not publication: ```sh - go get gitea.maximumdirect.net/eric/promptkit@v0.12.0 - go mod tidy + validation_dir=$(mktemp -d) + export GOWORK=off GOTOOLCHAIN=local GOFLAGS=-mod=readonly + export GOPROXY=off GONOPROXY=none GOSUMDB=off + CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags '-s -w' \ + -o "$validation_dir/scriptorium-linux-amd64" ./cmd/scriptorium + CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -trimpath -ldflags '-s -w' \ + -o "$validation_dir/scriptorium-linux-arm64" ./cmd/scriptorium ``` - 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: 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: published versions and exact attribution revisions are selected; -there are no unpublished substitutions or unrelated dependency upgrades. - -## Stage 2: Cut Over The Application Schema And Its Tests - -Status: Complete. `Document` and `AppSettings` now use ordered `promptkit_sources` -selectors with file/directory exclusivity, path normalization and history, and -no framework acquisition. Defaults, application imports/overlays, replacement -precedence, safe validation, and non-backend limits remain covered by config -tests. `go test ./internal/config` passes. Full baseline checks remain blocked -only by the expected CLI API/settings migration (Stage 3) and HTTP/report -fixtures (Stage 7); this intermediate revision is not buildable. - -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. - -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. - -Validation: `go test ./internal/config`, format/diff checks, and attempted -baseline checks. Remaining production CLI references are assigned to Stage 3. - -Acceptance: application configuration has one native source-selection model, -does not read framework files, and preserves existing application semantics -outside the deliberate field removals. - -## Stage 3: Wire Native Sources Through All Existing CLI Engine Paths - -Status: Complete. Existing CLI engine paths now use the ordered native source -selectors, explicit repeated source flags, ConfigKit file inputs and PromptKit -directory inputs; profile/prompt inspection shares the same captured sources. -Retired directory/backend wiring and the empty-prompt filesystem are removed, -and captured diagnostics use the existing safe writer. `go build -o -/tmp/scriptorium-promptkit-native ./cmd/scriptorium`, `go test -./internal/config`, `gofmt`, and `git diff --check` pass. Full test/race/vet -checks reach only the stale CLI fields/fixtures assigned to Stages 5–6 and -removed PromptKit test constructors assigned to Stage 7; those are not -migrated here. - -Files: `internal/adapter/cli/application_config.go`, `run.go`, `inspect.go`, -`config.go`; add a small `framework_sources.go` if useful within this package. - -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. - -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. - -Acceptance: all existing production engine paths use native sources; no -removed constructor API or backend schema remains in production code. - -## Stage 4: Migrate Maintained Definitions, Application Examples, And Testdata - -Status: Complete. Maintained and fixture prompt/profile definitions now use -PromptKit's keyed format, and application examples select ordered native -sources with framework backend data in separate files. The two fixture -versions sharing one prompt ID are in one document so their directory remains -a strict composition group. The old imported backend fragment contained no -application defaults; it was removed after its framework data moved rather -than introducing an unrelated defaults fragment. All four application configs -validate; both maintained render scripts, the composed-overlay render, the -inheritance render without credentials, and offline renders for each maintained -and fixture prompt/version pass. - -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. - -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. - -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. - -Acceptance: maintained inputs use keyed formats and native source lists, and -all effective definitions can be constructed offline with their resource origins. - -## Stage 5: Migrate CLI Parsing And Application-Inspection Tests - -Status: Complete. CLI parser/config tests now protect ordered repeatable source -selection and whole-list overrides, native shared definition helpers, retired -flags and application fields, and application-only inspection with missing or -invalid framework paths. Focused CLI parser/config tests and `internal/config` -pass, as does the native definition-fixture render. The production build passes. -Full CLI tests retain only the execution/inspection fixture migrations assigned -to Stage 6; repository-wide test, race, and vet checks also reach the HTTP/report -constructor migrations assigned to Stage 7. - -Files: `internal/adapter/cli/config_test.go` and parser/configuration sections -and shared helpers of `run_test.go`. - -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. - -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. - -Acceptance: CLI source override presence/order and application-only inspection -are protected without imposing filesystem validation on configured YAML paths. - -## Stage 6: Migrate Existing CLI Execution And Definition-Inspection Coverage - -Status: Complete. CLI run, render, report, deadline, and definition-inspection -fixtures now use native keyed definitions and ordered framework sources. Backend -definitions live in framework files, built-in backend overlays are accepted, -and tests retain source precedence, retries, version selection, required and -optional inputs, profile inheritance, provider data, and inspection boundaries. -`go test ./internal/adapter/cli ./internal/format` passes, as does the native -build. Repository-wide test, race, and vet checks stop only on removed -PromptKit constructors in HTTP/report fixtures assigned to Stage 7. - -Files: remaining execution/inspection sections in -`internal/adapter/cli/run_test.go`; formatting fixtures only if affected. - -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. - -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. - -Acceptance: existing CLI workflows run with native inputs and updated boundary -expectations, without legacy parsing or narrowed valid-definition support. - -## Stage 7: Migrate HTTP And Report Fixtures Without Changing Their Contracts - -Status: Complete. HTTP and report engine fixtures now use keyed prompt/profile -definitions and native ConfigKit underlays; backend tests use PromptKit's keyed -`BackendSource` while retaining explicit pointer-valued limits, including the -zero-capacity queue. Request/status and report assertions remain unchanged. -Focused HTTP/report tests, `go test ./...`, `go test -race ./...`, `go vet -./...`, the CLI build, `gofmt`, `git diff --check`, and a repository-wide search -for removed constructor APIs pass. - -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. - -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. - -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: Complete. Focused CLI-boundary tests now protect same-group conflicts, -ordered overlays, empty sources, invalid lower values replaced before final -validation, malformed and invalid unused definitions, and combined framework -documents. Imported prompt content retains its source-relative resource origin -and construction-time capture while schema and request artifacts remain -preparation-time reads. Native backend/profile inheritance, null and empty-map -semantics, explicit numeric presence at the injected-client boundary, partial -profiles completed by request overrides, and literal whitespace/slash IDs are -covered. Existing full-feature adoption fixtures remain in place. Focused -adoption tests, `go test ./...`, `go test -race ./...`, `go vet ./...`, the CLI -build, `gofmt`, and `git diff --check` pass. - -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: Complete. `inspect configuration validate`, `show`, and `sources` now -load application settings, construct one engine, and use its captured public -inspection view without preparing a request or resolving credentials. Effective -output remains PromptKit's native YAML; source JSON uses the selected DTO fields -and preserves imported locations and source order. Tests cover source-free and -credential-required configurations, invalid final definitions, source layering -and imports, stdout/stderr separation, positional rejection, and writer -failures. Focused inspection tests, `go test ./...`, `go test -race ./...`, -`go vet ./...`, the CLI build, `gofmt`, and `git diff --check` pass. Literal-path -explanations and their redaction coverage remain for Stage 10. - -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: Complete. `inspect configuration explain` now requires an explicitly -provided JSON Pointer, accepts the empty root, parses with ConfigKit, detects -unknown paths before writing, and delegates explanations to the captured -PromptKit inspection view. Tests cover inherited and overlaid history, escaped -slash IDs, dotted keys, root output, malformed/unknown paths, native writer -errors, effective and historical `token`/`password` redaction, visible -environment-reference names and ordinary values, and the unchanged disclosure -behavior of profile inspection and prepared output. Application validation -remains independent of invalid framework definitions, while framework -validation rejects them without a partial report. Focused inspection tests, -`go test ./...`, `go test -race ./...`, `go vet ./...`, the CLI build, -`gofmt`, `git diff --check`, and all four operations against -`examples/config.yml` pass. - -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: Complete. The configuration reference now owns the ordered -`promptkit_sources` sequence, empty/default behavior, source precedence and -paths, application imports/overlays, and the separation from Promptkit -definition and message-resource semantics; obsolete application backend and -directory settings were removed. The CLI reference documents repeated source -flags, removed flags, command-specific options, all four framework inspection -operations, their JSON source projection, JSON Pointer behavior, output and -exit behavior, and limited native redaction. Operations distinguish -application validation from eager framework construction and describe message -capture, restart, runtime schema/artifact/credential boundaries, and sensitive -report handling. A separate executable migration guide covers selector -replacement, backend relocation, keyed IDs/versions, `base_profile` to -`extends`, and zero/null/map review. README dependency/navigation links were -updated while the historical Go-package migration and licensing footer remain -intact. The README and composed render examples, both maintained render -scripts, application validate/explain examples, and framework validate/explain -examples ran offline; `git diff --check` passes. - -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: Complete. Current Promptkit references in the developer guide, internal -component/source/adapter docs, architecture policy, and affected HTTP API and -consumer guidance now target v0.12.0; historical migration and roadmap records -remain pinned to the versions they describe. The developer reading guide now -routes native source selection and captured framework inspection to their -owners without changing its selective policy-reading guidance. Internal docs -describe the application selector sequence, ConfigKit's separate application -and framework schema owners, shared CLI engine assembly, Promptkit-native -configuration reports, and existing server capacity ownership; stale backend -registration, old directory, and application-inheritance claims were removed. -Architecture ownership and the approved show/explain-only native redaction -scope were aligned, with Base Policy Version, Upstream Source, ADR decisions, -shared engine capacity, request independence, and HTTP lexical artifact -containment unchanged. The full-config application validator and all four -framework configuration inspection operations ran offline; the HTTP wire -contract was unchanged and `git diff --check` passes. - -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: Complete. The audit confirmed native ordered Promptkit sources, -keyed definitions and presence, source-origin resource capture, eager final -validation, request/runtime boundaries, all four captured framework inspection -operations with redaction limited to that family, and shared server capacity. -No removed API or application schema, legacy loader, direct catalog/internal -import, module replacement, or workspace remains in executable code or -maintained inputs. The complete Go baseline passed (`go test ./...`, -`go test -race ./...`, `go vet ./...`, `gofmt` check, and a build outside the -worktree); the module graph and attribution links were reviewed. Every -maintained application config passed both application and framework validation; -both render scripts, the composed-overlay render, inheritance render, all four -framework inspection operations with the required backend endpoint pointer, -and existing prompt/profile inspection passed offline without provider -traffic. The final documentation and whitespace checks passed. The breaking -configuration and definition adoption requires a new pre-1.0 minor release and -may share that release with the completed ConfigKit adoption. Version choice, -release notes, publication, and roadmap retirement are subsequent release -preparation, and no release is claimed here. - -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 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. + Keep products outside the worktree. Do not invoke `scripts/release.sh`, + push, tag, poll hosted delivery, or add a new release check. +5. Run the maintained ordinary, composed, inheritance, and new collection + no-generation examples; check collection overlay retention, representative + application inspection, and old framework inspection. Reuse equivalent + unchanged successful checks. Run `git diff --check` and validate affected + documentation links and workflow YAML/shell syntax. +6. Audit every roadmap completion criterion against code, tests, examples, + metadata, and documentation. Fix remaining gaps instead of marking a partly + migrated but green subset complete. Do not carry old PromptKit stage records + forward as evidence for this sprint. +7. Record concise actual validation results and mark stages complete only when + their work is done. Update the feature roadmap status after the complete + audit, retaining its scope and later-upgrade handoff. Commit remaining scoped + changes with a plain-English message, review status, and report residual + uncommitted work or blocked validation accurately. + +Completion means application ConfigKit v1.2.0 is native and operator-visible +where already supported, PromptKit v0.12.0 still works through old ConfigKit, +the shared YAML prerelease remains selected, and all seven stages are delivered. +It does not mean ConfigKit v1.2.1, stable YAML, or a new Scriptorium release has +been delivered. No significant product questions remain open for this sprint.