diff --git a/docs/roadmap/configkit.md b/docs/roadmap/configkit.md deleted file mode 100644 index 8b80ad6..0000000 --- a/docs/roadmap/configkit.md +++ /dev/null @@ -1,356 +0,0 @@ -# ConfigKit v1.2.0 Interim Adoption - -## Status And Intent - -Drafted on 2026-11-17. The interim ConfigKit v1.2.0 adoption is implemented; -the [implementation plan](implementation.md) records its verification. The -upcoming PromptKit upgrade retains the separate ConfigKit v1.2.1 and stable -YAML handoff, including retirement of the old module when no longer needed. -This roadmap preserves the interim target, rationale, and scope. - -The maintainer is adopting ConfigKit across an application suite to standardize -configuration semantics. Scriptorium should use the selected ConfigKit's native -loading path, rather than reproduce older processing rules for compatibility. -Configuration migration is acceptable. Application schema and deployment choices -remain Scriptorium's responsibilities under -[ADR 0005](../adr/0005-configkit-boundary.md). - -This replaces the completed v0.5.0 roadmap, preserved at -`ba24b7a879c95e2b306e0d53eb0b45e043e1b29a:docs/roadmap/configkit.md`. -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 - -The reviewed Scriptorium revision is -`ba24b7a879c95e2b306e0d53eb0b45e043e1b29a`. Its selected modules are -`gitea.maximumdirect.net/eric/ConfigKit v0.5.0` and -`gitea.maximumdirect.net/eric/promptkit v0.12.0`, with -`go.yaml.in/yaml/v4 v4.0.0-rc.6`. The consumer Go minimum is 1.25.5; release -validation and hosted builds select Go 1.26.11. - -Application configuration already uses ConfigKit through `internal/config`: - -- `Document`, a fresh defaults factory, a recorded resolver, and a validator - define application settings. `Settings` converts the resolved result without - another merge. -- `Load` selects an explicit file or runs a local `os.Stat` loop over two system - configuration paths, falling back to `NoSource`. File-backed loads enable - imports, one selected overlay, and explicit application CLI overrides. -- Application inspection reuses the retained result. `show` and `explain` use - native writers; `sources` projects `id`, `label`, `layer`, and available - `path` into a Scriptorium-owned JSON array. -- Application path values are working-directory-relative. Framework source - selectors are translated separately into ConfigKit values accepted by - PromptKit's current public API. - -The interim target is `go.maximumdirect.net/configkit v1.2.0` at full commit -`c1c7e87f2cdf77a0cbf3327831ac05578e756b9e`. The locally available v1.2.0 tag and -remotely verified published tag identify that same commit. Canonical references are: - -- [Consumer adoption and migration 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). -- [v1.2.0 release note](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v1.2.0.md). -- [v1.0.0 breaking-change inventory](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v1.0.0.md). - -The interim target requires Go 1.27.0 and retains go-yaml v4.0.0-rc.6. PromptKit -stays at v0.12.0 and continues selecting old-path ConfigKit v0.5.0. ConfigKit's -code grant remains LGPL-3.0-or-later. This review examined release notes, public -contracts, Scriptorium's integration, and a focused dependency compatibility -experiment; it did not migrate or validate the full application against v1.2.0. - -## Intervening Release Review - -All published releases after the selected v0.5.0 through v1.2.1 were reviewed. -Notes through v1.2.0 are linked at the interim target revision. The v1.2.1 note -is linked at its own commit and describes deliberately deferred work. - -| Release | Consumer-facing change and adoption consequence | -| --- | --- | -| [v0.6.0](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v0.6.0.md) | Loading/inspection improvements and Go 1.26.0 minimum. Obtain improvements through the dependency; no Scriptorium performance guarantee or benchmark gate follows. | -| [v0.7.0](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v0.7.0.md) | Effective-configuration `Diff` with combined sensitivity protection. Useful future operator functionality, not required for native loading. | -| [v0.7.1](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v0.7.1.md) | Maintainer-tool update; no application runtime or configuration migration. | -| [v0.8.0](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v0.8.0.md) | Input destinations, sequence-item placement, shared source-version checks, and initial identified sequences. Authored imports can use applicable placement; application version policy and Go identity registrations remain opt-in. | -| [v0.9.0](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v0.9.0.md) | Expanded imports/defaults, author-declared collection operations, identified-record inheritance, and dependency-ready ordering. Imports become optional by default; CLI assignment moves after inheritance and typed decoding. Migrate old syntax and lifecycle assumptions. | -| [v0.10.0](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v0.10.0.md) | Native configuration discovery and expanded absent-main loading. Replace application filesystem probing with a ConfigKit search description. | -| [v0.10.1](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v0.10.1.md) | Internal consolidation without public migration; inherit the fixes rather than reproduce the machinery. | -| [v0.10.2](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v0.10.2.md) | Acquisition, cleanup, projection-limit, and collection fixes. Accept corrected upstream diagnostics without adding application limits or recovery machinery. | -| [v1.0.0](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v1.0.0.md) | New module identity, Go 1.27.0, source-root `config` controls, API cleanup, `main` provenance, source lookup, and inspection fixes. These require migration. | -| [v1.1.0](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v1.1.0.md) | Field-level resolution recording within lists and identity-aware history for registered collections. Remove redundant whole-list normalization recording when leaf records cover all edits. | -| [v1.2.0](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v1.2.0.md) | Main-relative layered companions and derived/fallback overlay contexts. Available for future multi-source application needs; ordinary `Load` remains appropriate today. | -| [v1.2.1](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/docs/releases/v1.2.1.md) | Stable go-yaml v4 and loader-plugin adaptation. Deferred to the PromptKit upgrade because of the shared dependency obstacle below. | - -Upstream release-tool changes do not require Scriptorium to adopt ReleaseKit or -copy upstream publication procedures. - -## Dependency Boundary And Sequencing - -There are two distinct compatibility issues, not just import renaming: - -1. Old and vanity ConfigKit paths have different named Go types. `newEngine` - currently constructs old-path `Input` and `Underlay` values for PromptKit. - New-path application overrides and results cannot simply replace those - types at that boundary. -2. Both paths select the same go-yaml v4 module through Go's module graph. - ConfigKit v1.2.1 requires v4.0.0. Old ConfigKit v0.5.0 imports - `go.yaml.in/yaml/v4/plugin/limit`, which is absent from stable v4. - -An isolated temporary module requiring only old ConfigKit v0.5.0 and go-yaml -v4.0.0 failed a package compile check: -`go test -mod=mod -run '^$' gitea.maximumdirect.net/eric/ConfigKit`. -Package setup failed at that missing import; the selected module graph was -verified. This is a compile-time dependency conflict, not evidence of a -Scriptorium runtime failure. Repository source and dependency files were untouched. - -Retaining old-path adapter imports alone cannot bridge v1.2.1, but the selected -v1.2.0 target still declares the same YAML prerelease as the existing stack. -The interim graph deliberately contains both ConfigKit module identities: - -- Application loading, overrides, callbacks, diagnostics, and application - inspection use `go.maximumdirect.net/configkit v1.2.0`. -- Framework construction and captured framework inspection retain - `gitea.maximumdirect.net/eric/ConfigKit v0.5.0` wherever PromptKit v0.12.0's - public API requires its types. -- Both share `go.yaml.in/yaml/v4 v4.0.0-rc.6`. Validate the complete selected - graph, including transitive requirements; agreement of direct requirements - alone is not proof that the application works. - -Use clear local import aliases where both packages are needed. Build each -owner's values directly with its own public types; serialization or a new -cross-version facade is unnecessary. Framework JSON Pointer parsing and writers -must use the old owner's types, while application diagnostics use the new -owner's types. Review shared source DTOs for named layer-type assignments. -Runtime `AppSettings` and application-owned selector values can continue to -cross the existing adapter boundary without transporting a ConfigKit result -into PromptKit. - -The upcoming PromptKit roadmap owns migration to a compatible framework release, -ConfigKit v1.2.1, stable YAML, and removal of old ConfigKit imports and notices -when no longer used. PromptKit v0.23.2 already demonstrates that dependency -combination, but selecting and assessing its full migration remains later work. -This interim upgrade uses published dependencies without local replacements or -copied loaders under the existing architecture policy. - -The two loaders deliberately have different format generations during this -interval. Migrate application documents and their imports to v1.2.0 controls; -framework files selected for PromptKit remain governed by its v0.12.0 contract, -including any old ConfigKit import controls it supports. Do not bulk-rename -controls across all YAML files or parse framework documents with the new -application loader. - -## Targeted End State - -### One Native Application Loading Path - -`internal/config` consumes the public `go.maximumdirect.net/configkit` package. -All command families use one definition and one completed application load per -selection. Runtime settings come from `result.Config`; inspection uses that -result's captured public views. - -Ordinary `configkit.Load` remains the entry point. A main file with imports and -an overlay does not require artificial underlay groups, embedded defaults, or a -new configuration abstraction. Fresh typed defaults, recorded normalization, -and final domain validation remain definition callbacks. - -### ConfigKit-Owned Discovery - -An explicit `--config` selects `configkit.File` exclusively. Omission selects -`SearchConfig` with ordered `SearchPaths` for -`/usr/local/etc/scriptorium/config.yml` and `/etc/scriptorium/config.yml`. -Delete the `os.Stat` loop and hand-written discovery errors; ConfigKit owns -selection, acquisition, absence, and structured diagnostics. - -These locations are application-selected deployment conventions, not a -compatibility implementation of library processing. ConfigKit does not mandate -one search convention. Its directory presets consider additional filenames and, -in some cases, platform constraints; adopting those or adding user/home/current -directory discovery is a separate application choice. - -Use an optional search and native defaults. Exhaustion contributes no fabricated -source; a selected-file error terminates loading. Enable imports directly: -an absent main has no declarations to traverse, so no existence precheck is -necessary. - -Keep the overlay-name selector and delegate its processing. The current CLI has -no independent overlay filesystem root; without a selected main or explicit -context, an active overlay cannot be located. Report ConfigKit's outcome rather -than create a permanent application prohibition on overlays without a main. -The library supports that combination when an appropriate context is supplied. - -### Native Source Controls, Imports, And Collections - -Application sources use root `config` controls, including fragments and selected -overlays where their controls are allowed. Rename genuine old control blocks in -maintained application examples and fixtures. Do not introduce aliases or -runtime rewriting. Nested `config`, and former `configkit` and `_configkit` -names, follow ordinary schema rules rather than a global reserved-key rule. - -Leave `ImportDefaults` unspecified unless a future application requirement -warrants a choice. In particular: - -- Imports are optional by default. Indispensable maintained fragments declare - `required: true`; intentionally optional imports may omit it. Remove old - `optional` declarations rather than translate them at runtime. -- Native `path`, `dir`, and `glob` selectors, lists, filters, recursion, - destinations, and item placement are available wherever ConfigKit allows. - Directory filename selection is unrestricted by default; YAML-only examples - should author a pattern. Hidden/symlink discovery follows native defaults, - not application filtering. -- Strict peer composition, dependency-ready assembly, inheritance, and - collection policy remain upstream responsibilities. Sources can declare - `config.sequences` for native identity, append, upsert, and replacement. -- `promptkit_sources` has no application identity field. Add no identity - registration, inferred path identity, duplicate prohibition, or forced - replacement solely for this upgrade. Ordinary unkeyed lists replace across - precedence boundaries; authored collection policy may change that behavior. - CLI lists remain whole-list replacements after decoding. - -Import and overlay containment remain library behavior. Application resource -strings such as `schema_dir`, framework selectors, and HTTP artifact roots are -not source-control paths; ConfigKit does not automatically rebase them. Keep -their working-directory-relative interpretation in this scope. Source-relative -resource behavior would require a separate application choice using public -origin/context APIs. No broader filesystem sandbox is introduced. - -### Current Resolution And CLI Lifecycle - -Adopt assembly, inheritance, typed defaults/decoding, explicit CLI assignment, -recorded resolution, credential processing where applicable, and validation in -the current upstream order. Source syntax, composition, inheritance, and decoding -failures cannot be repaired by later CLI overrides. Valid decoded values can -still be replaced before application validation. - -Continue mapping only explicitly visited flags to public `Override` records, -with safe labels and supported built-in values. Preserve explicit empty, false, -zero, and allowed null values according to the application schema. Recorded -normalization may change those values through native helpers. - -Migrate used removed symbols, especially the resolver's generic `Record` call, -to current APIs. Leaf `Normalize` calls now cover individual edits within the -equal-length `promptkit_sources` list; a second whole-list record is unnecessary. -Do not add identity merely to obtain field auditing. Future membership/order -changes use the applicable native container-recording rules. - -The v1 inventory also includes `EntryInfo`, `Sensitive`, -`SourceVersionModeMainOnly`, `SourceVersionEvidence`, -`EmptyImportSelections`, `DestinationIsFallback`, `SearchPaths`, -`FollowSymlinks`/`IncludeHidden`, `LayerMain`, and -`CodeHistoryLimitExceeded`. Update actual uses and tests; this list does not -require implementing features that Scriptorium does not use. - -### Inspection And Disclosure - -Keep `config validate`, `show`, `sources`, and `explain` as the application -inspection surface. Native writers own effective YAML and explanation semantics, -including improved list-field history. Retain the small application source DTO; -its main layer now reports `main`, not `base`. Acquisition order is not -composition order, and load-local source IDs are not durable identities. - -Source lookup, empty optional-selection evidence, and placement metadata remain -available through public results for future focused operator enhancements. -Adoption does not require dumping every source field into the CLI schema. -Existing stream separation, writer-error handling, and application-versus-framework -inspection boundaries remain applicable. - -The application document has no raw API-key field. Migration adds no sensitivity -heuristics, redaction of environment names, or redaction of ordinary provider -parameters. API-key values remain the secret requiring protection; PromptKit -owns framework credential handling. The accepted scoped native redaction of -framework configuration inspection is separate from application inspection. -The renamed `Sensitive` hook does not establish a broader disclosure policy. - -## Required Changes And Supporting Material - -- Update dependency/import identity, used symbols, discovery construction, - normalization records, diagnostics, and application/CLI fixtures. Keep the - PromptKit-owned old types isolated from new application types and retain the - shared YAML prerelease in the selected graph. -- Raise `go.mod`'s consumer minimum to 1.27.0 and select a supported Go 1.27 - release patch for validation and builds. Update current 1.26.11 release - instructions and the hosted image together; no higher consumer patch minimum - or extra platform matrix is implied. -- Migrate application composition examples to `config.imports`, with explicit - requiredness where they depend on a fragment. Demonstrate one useful native - collection composition on the selector list without adding a schema identity - field or universal registration. -- Update configuration/CLI contracts, contributor/toolchain guidance, - architecture dependency descriptions, source/adapter internals, and affected - README/example navigation. Correct obsolete source-internals text about - sorting application backend IDs: those backends were removed and selector - order is meaningful. Preserve accepted ADR decisions and historical notes. -- Update ConfigKit attribution to identify both the new application module at - v1.2.0 and the old module at v0.5.0 still used with PromptKit. Preserve each - revision's applicable notices and exact-commit links, using separate factual - component entries where needed. Leave unchanged PromptKit and YAML selections - and notices accurate; do not prematurely claim stable YAML adoption. Inspect - other affected selected runtime dependencies under the OSS policy. -- Preserve existing faithful LGPL/GPL and other applicable standard texts; - verify changed upstream project notices under the OSS policy. Maintainer - tool requirements may affect module selection without becoming runtime - imports. Their presence alone requires neither Scriptorium tool adoption nor - attribution for tools not incorporated into its distributed material. - -The eventual release should be a new minor version under the adopted release -policy: consumer minimum and configuration contracts change. Notes should -explain control-block migration, required imports, CLI ordering, provenance -naming, and the intentional application/framework version split. Exact version -selection and publication remain separate preparation work. - -## Validation And Completion Criteria - -The eventual implementation is complete when: - -- The published graph selects application ConfigKit v1.2.0, old-path ConfigKit - v0.5.0 for PromptKit v0.12.0, and go-yaml v4.0.0-rc.6. It builds with each - boundary using its owner's public types and without a cross-version shim. -- Explicit-file, native discovery, exhaustion/defaults-only, and selected-file - error cases use one native load. Inspection and execution share the - application definition and resolution boundary. -- Representative application tests cover new controls, optional/required - imports, an applicable expanded selector/placement, native collection and - overlay behavior, and changed CLI timing. Distinguish decode failures from - domain validation that CLI values can legitimately affect. -- Leaf normalization, explicit zero/false/null handling, `main` provenance, - and selector-list explanation work through the public result and CLI without - duplicating upstream's exhaustive test matrix. -- Render and representative CLI/HTTP execution continue through PromptKit - v0.12.0, including shared capacity and existing artifact handling. Application - v1.2.0 controls and inspection do not reinterpret framework configuration as - if its independent loader had also been upgraded. -- Documentation, examples, attribution, and toolchains match the implemented - graph and semantics. Run applicable development checks and existing release - target builds. Add no recurring synchronization checks, scanners, provider - probes, performance promises, or publication gates merely for this upgrade. - -No implementation or full target-graph test pass is claimed by this review. - -## Plausible Future Work Outside This Adoption - -The upcoming PromptKit upgrade includes ConfigKit v1.2.1 and stable go-yaml, -unifies ConfigKit's module identity, and retires this temporary framework -boundary. Completing this v1.2.0 roadmap does not require that later work. - -`config diff` could expose native effective-value comparison for two files or -an overlay's impact using safe snapshots, not rendered-text comparison. It is -useful operator work, but not necessary to standardize existing loading semantics -and remains a separately scoped enhancement. - -Layered application underlays, main-relative companions, bundled defaults, -additional discovery locations, source-relative resources, source-detail -inspection, and source-version policy remain available for concrete future -needs. This scope also leaves HTTP configuration inspection, hot reload, and -secrets-directory bootstrap for separate consideration. None is permanently -prohibited by this roadmap. - -## Confirmed Sequencing Decision - -The maintainer selected v1.2.0 as the complete target of this work set so native -application adoption can precede the larger PromptKit migration. The tradeoff is -temporary coexistence of two ConfigKit generations and deferred stable YAML. -A coordinated cutover to both latest dependencies was considered; it avoids -that intermediate state but would combine the larger framework API migration -with application configuration work. The selected scope keeps those work sets -separate and carries an explicit retirement handoff to the PromptKit roadmap. - -No significant product decisions remain open within this interim scope. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md deleted file mode 100644 index efb1490..0000000 --- a/docs/roadmap/implementation.md +++ /dev/null @@ -1,480 +0,0 @@ -# ConfigKit v1.2.0 Interim Implementation Plan - -## Status, Baseline, And Authority - -Planned on 2026-11-17 for a Luna coding agent against Scriptorium -`a5d8394313c4cbdee8e8618844e65364c70189e9`. Stage completion is recorded below. -The [feature roadmap](configkit.md) owns the target, rationale, native-semantics -policy, and confirmed interim sequencing decision. This document owns the -ordered implementation 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. - -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. - -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. - -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. - -## Sprint Execution Rules - -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. - -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 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. - -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. - -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. - -## Stage 1: Select The Interim Dependencies And Go Toolchain - -**Complete.** Go 1.27.4 and the selected dependency graph were provisioned -from the local cache. Offline `go list -m all` confirmed both ConfigKit -versions, PromptKit v0.12.0, the existing catalogs, and YAML v4.0.0-rc.6. - -**Work** - -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. - -**Verification focus** - -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. - -## Stage 2: Move Application Loading And Resolution To Native v1.2.0 - -**Complete.** Application loading uses native search and v1.2.0 resolution; -`go build ./internal/config` passed with Go 1.27.4. Adapter and test migration -remain assigned below. - -**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 - -**Complete.** CLI adapters retain each loader's types and diagnostic writer; -`go build ./cmd/scriptorium` passed with Go 1.27.4. Fixture and integration -coverage remains assigned below. - -**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 - -**Complete.** `go test ./internal/config` passed with Go 1.27.4. Native -diagnostics for the nonregular discovery case omit the filesystem path; the -test checks the typed diagnostic and that no raw control character leaks. - -**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 - -**Complete.** CLI, HTTP, and report suites passed with Go 1.27.4, including -both native diagnostic paths and collection-example renders. After `go mod -tidy`, the selected graph retains both ConfigKit versions and YAML rc.6; -ReleaseKit, Goldmark, and Go tooling are not executable dependencies. - -**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 - -**Complete.** Updated the owned contracts, contributor and release guidance, -internal boundaries, and separate attributions. Both collection commands ran; -affected local links and pinned ConfigKit copyright and license files were -checked against the corresponding source revisions. - -**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 - -**Complete.** With Go 1.27.4 and the provisioned offline module cache, `go test -./...`, `go test -race ./...`, `go vet ./...`, the native build, and both -Linux release-target builds passed. Ordinary, composed, inheritance, and -collection renders, application explanation, framework source inspection, -workflow YAML and shell syntax, affected local links, formatting, and -`git diff --check` were checked. The module and executable dependency graphs -retain the intended two ConfigKit generations and YAML prerelease; no -workspace, replacement, or vendoring was added. The future PromptKit handoff -still owns ConfigKit v1.2.1, stable YAML, and removal of the old module. - -**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 - 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 - ``` - - 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. diff --git a/docs/roadmap/policy.md b/docs/roadmap/policy.md index 4231e6b..66de1bf 100644 --- a/docs/roadmap/policy.md +++ b/docs/roadmap/policy.md @@ -6,8 +6,7 @@ Agreed and delivered on 2026-09-28. This roadmap replaces the earlier licensing-only proposal with alignment of the complete applicable policy set and its supporting documentation. It defines the targeted end state and required changes. Its completed implementation plan is preserved in Git at -`git show 8b6c12f912b28ac00016f047f9846798a5de95d9:docs/roadmap/implementation.md`; -the current `implementation.md` belongs to a later work set. +`git show 8b6c12f912b28ac00016f047f9846798a5de95d9:docs/roadmap/implementation.md`. The next release summary should mention the policy and licensing alignment, the already-selected GPL-3.0-or-later application grant, and the separate diff --git a/docs/roadmap/promptkit.md b/docs/roadmap/promptkit.md index 7f502bf..7fd3ecf 100644 --- a/docs/roadmap/promptkit.md +++ b/docs/roadmap/promptkit.md @@ -25,7 +25,7 @@ from new library APIs. The reviewed Scriptorium source is commit `bb5006517b6c27dcbe56074f1d97140bf0999c48`; the last release is v0.15.0. -The completed [ConfigKit adoption](configkit.md) selects ConfigKit +The completed ConfigKit adoption selects ConfigKit v0.5.0. PromptKit remains v0.11.2, with the OpenRouter and Rakestrawhome `/v2` catalog modules at v2.20260926.0. diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md deleted file mode 100644 index b1fcb7b..0000000 --- a/docs/roadmap/remediation.md +++ /dev/null @@ -1,392 +0,0 @@ -# Implementation Review Remediation - -## ConfigKit v1.2.0 Interim Adoption Review - -Reviewed on 2026-11-17 at -`eec4fa2d91beca68b176dcf20026a0c7e5a7b7bf`, covering the seven implementation -commits after `222f405`. The review followed each stage of the -[implementation plan](implementation.md) against the code, tests, examples, -documentation, and [feature roadmap](configkit.md). - -The runtime architecture matches the selected interim target. Application -configuration uses public ConfigKit v1.2.0 with native discovery, composition, -post-decode CLI assignment, recorded leaf normalization, and final domain -validation. PromptKit v0.12.0 retains old-path ConfigKit v0.5.0 for framework -sources and captured inspection. Each generation's paths, diagnostics, and -writers remain separate; the shared YAML dependency stays at v4.0.0-rc.6. -No runtime correctness defect, unnecessary compatibility layer, or unrequested -runtime restriction was found. One documentation contract overstatement was -identified; its remediation is complete below. - -| Stage | Review result | -| --- | --- | -| 1: Dependencies and toolchain | Both ConfigKit identities, unchanged PromptKit/catalogs/YAML, Go 1.27.0 consumer minimum, and Go 1.27.4 release image are selected as planned. | -| 2: Native application loading | One native load owns discovery and processing; application callbacks retain schema/domain responsibilities and leaf recording. | -| 3: Adapter type separation | Application and framework values use their respective public types; structured errors and warnings reach the matching native writer. | -| 4: Configuration coverage | Tests cover discovery, optional/required imports, placement, authored collections, CLI timing, presence, normalization, and inspection without new application identity rules. | -| 5: Integration and examples | New application controls coexist with old framework controls; ordinary, composed, inheritance, and collection examples work, including overlay retention. | -| 6: Documentation and attribution | Dependency/toolchain ownership and both notices are aligned; selector-clearing wording is now corrected (R6). | -| 7: End-state validation | Independent tests, builds, example commands, dependency checks, and document checks passed; R6's documentation alignment is now complete. | - -### R6: Qualify Selector Clearing By The Effective Collection Policy - -Priority: P3 (low). Status: Complete. - -Locations: `docs/config.md:62–64` and `docs/config.md:108–109`. - -The selector reference says that omitting `promptkit_sources` or setting it to -`[]` or `null` selects no application-supplied framework sources. The overlay -description also says that explicit nulls replace without qualifying collection -operations. Those statements retain the former simple-list contract even -though the upgrade now exposes native authored collection policies. The later -general statement that policies may combine lists does not explain the -different empty/null behavior. - -Evidence: with this application main document: - -```yaml -config: - sequences: - - destination: [promptkit_sources] - key: file - mode: upsert -promptkit_sources: - - file: ./base-framework.yml -``` - -an overlay containing `promptkit_sources: []` makes `config show` succeed and -retain `base-framework.yml`. An overlay containing `promptkit_sources: null` -instead exits 1 with `sequence.invalid`: append and upsert require a sequence -contribution. These checks used the reviewed binary and temporary application -files; no framework file or provider was needed. The results agree with -[ConfigKit's pinned collection contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/config.md#yaml-declarations-and-policy-lifetime). - -Required change: distinguish an empty final resolved selector list from an -authored source contribution. Under ordinary replacement, an empty list clears -the selection and an allowed null produces no selectors. Under append/upsert, -`[]` contributes no records and null is invalid; omission preserves lower -contributions. Explain or link to the native way to clear an identified -collection: select `mode: replace` at that destination and supply `[]`. -Qualify the overlay null statement accordingly. - -This is a documentation fix. Preserve ConfigKit's current behavior and the -existing CLI whole-list override semantics; do not add special-case clearing, -new validation, or a compatibility merge pass to satisfy the old wording. - -Acceptance: the selector and overlay descriptions agree with the pinned native -contract and the reproduced empty/null cases. Check the affected links and any -added example. No production-code change or new runtime guarantee is required. - -Resolution (2026-11-18): the configuration reference now distinguishes the final -resolved selector list from individual source contributions. It explains -omission, empty lists, nulls, and explicit replacement under the effective -collection policy, qualifies overlay null handling, and links to the pinned -upstream policy-lifetime contract. Runtime behavior and CLI whole-list overrides -are unchanged. All 15 temporary selector-policy checks passed against a fresh -build: omitted/empty/null/explicit-replace overlays under ordinary replacement, -append, and upsert, plus CLI whole-list replacement and no-generation rendering -under each policy. The pinned document and anchor and diff whitespace were -checked. No provider was contacted; no production code or tests changed. - -### Independent Review Verification - -- `go test -count=1 ./...`, `go test -race -count=1 ./...`, and `go vet ./...` - passed with Go 1.27.4 and a provisioned offline cache. -- A native binary and Linux amd64/arm64 binaries built outside the worktree; - cross-builds used the existing cgo-disabled, trimpath, stripped settings. -- All six maintained configuration/overlay selections passed application - validate/show/sources/explain, framework validate/sources, and JSON render. - Framework show/explain also passed. Selected credential variables were unset; - no generation command or live provider was invoked. -- The selected module and executable dependency graphs, `go mod tidy -diff`, - changed-Go formatting, diff whitespace, affected local documentation links, - workflow YAML/shell syntax, both ConfigKit notice revisions, and shared - LGPL/GPL text fidelity were checked. No workspace or vendor tree is committed. -- The only repository change made by this review is this remediation record. - Historical findings below are retained unchanged. - -## PromptKit v0.12.0 Review - -Reviewed on 2026-10-04 at -`58cb02f9732b09740ff7e22096d2a4072ddfddca`, covering the thirteen implementation -commits after `b1bb55a`. The runtime architecture matches the accepted -[feature roadmap](promptkit.md) and [implementation plan](implementation.md). -No runtime regression, missing framework capability, or newly imposed runtime -restriction was identified. Three low-priority documentation/help gaps were -identified; their status and resolutions are recorded below. The first retained -a loading guarantee that was incompatible with -the deliberately selected full-source engine construction. - -### R3: Correct The Definition-Inspection Loading Contract - -Priority: P3 (low). Status: Complete. - -Locations: `docs/cli.md:208–224`; related orientation in -`docs/internal/adapters.md:49–56`. The CLI wording was retained in `b913ef0` -despite the engine-wiring change in `0df2aad`. - -The profile-inspection reference still says it never loads a prompt. Both -definition-inspection commands now construct the same complete selected engine -as execution. PromptKit resolves and validates all final definitions and -captures their message content before the selected inspection runs. Consequently, -an unused prompt with invalid syntax or an unreadable `content_file` can prevent -inspection of an otherwise valid profile. Prompt inspection's unqualified -claim that it does not resolve a profile also needs to distinguish engine -assembly from request-specific target resolution. - -Evidence: inspecting a valid profile in a selected combined file with an -unused prompt referring to a missing message file exits 1 before emitting a -profile report. The existing -`TestProfileInspectionUsesCombinedSourcesAndValidatesUnusedPrompts` also -protects this intentional eager-validation boundary. - -Required change: explain that both commands construct and validate the full -selected configuration, including unused definitions and message resources, -before inspecting the chosen definition. Preserve the distinction that they -do not prepare an execution request, load request-time schemas/artifacts, -resolve credential values, reserve capacity, or call a provider. Clarify that -no prompt collection is mandatory, but selected prompts are not ignored. -Align the internal summary with the CLI contract rather than restating a -stronger independence guarantee. Do not restore the empty-prompt-filesystem -workaround or weaken eager validation to satisfy the stale wording. - -Acceptance: the owning contract and internal summary agree with the roadmap, -shared engine construction, and existing tests. Review the documentation diff -and links; no production-code change or new runtime guarantee is needed. - -Resolution: the CLI contract now distinguishes full-source engine construction -from inspecting a selected definition, explains eager validation/content capture -and unused-definition failures, and retains the request-time exclusions. It -states that no prompt collection is mandatory but selected prompts are not -ignored. The internal summary links to that contract without promising a -separate no-prompt-loading path. Existing definition-inspection tests and -documentation link/diff checks passed; no production code changed. - -### R4: Update The Composed-Example Description - -Priority: P3 (low). Status: Complete. - -Location: `docs/config.md:95–96`, after the example migration in `2027b80`. - -The reference says `examples/config.composed.yml` imports two application -fragments. It now imports only `config-fragments/sources.yml`; the former -backend fragment became `examples/framework/backends.yml`, selected through -`promptkit_sources` rather than imported into the application document. -The example and code are correct, but the explanation confuses the two source -boundaries introduced by this migration. - -Required change: describe the actual source-selection fragment and separately -selected framework backend file, with links where useful. Do not reintroduce -an application backend mapping or add an unnecessary fragment merely to match -the old prose. The old backend fragment had no application defaults to preserve. - -Acceptance: the description matches the maintained files and the existing -composed-overlay render command still succeeds offline. - -Resolution: the configuration reference now links to the one imported -application source-selection fragment and the separately selected framework -backend file, retaining the local-overlay example. The existing composed-overlay -render command passed offline with credential environment variables unset; -the linked files and diff whitespace were checked. No configuration files or -loading behavior changed. - -### R5: Include Framework Configuration Inspection In Built-In Usage - -Priority: P3 (low). Status: Complete. - -Location: `internal/adapter/cli/run.go:742–749` (`printUsage`), following the -new command-family implementation in `2ba2ce1` and `411a67b`. - -The top-level usage lists `inspect prompt`, `inspect profile`, and application -`config`, but omits the implemented `inspect configuration` family entirely. -Invoking the binary without arguments reproduces this omission, so users -relying on its built-in command summary cannot discover the new framework -validation/provenance interface or distinguish it from application inspection. - -Required change: add a concise usage line identifying all four operations, -the supported selection flags, and the `--path` requirement for `explain`. -Preserve existing exit behavior and command parsing; this does not require a -new help subsystem or aliases. Protect discoverability with a small CLI-entry -assertion for the family/operations, not a snapshot of the entire usage text -or its incidental ordering. - -Acceptance: built-in usage advertises the actual family and remains consistent -with `docs/cli.md`; the focused CLI check and development baseline pass. - -Resolution: built-in usage now advertises all four framework operations, the -supported selection flags, and that `--path` is required for `explain`. -`TestUsageAdvertisesFrameworkConfigurationInspection` exercises the CLI entry -point and checks the family, operations, flags, exit status, and output stream -without snapshotting the whole usage text or fixing operation order. It failed -before the usage change and passed afterward. Full tests, race tests, static -checks, a native build outside the repository, formatting, and diff checks -passed; command parsing and exit behavior are unchanged. - -### Remediation Completion - -R3, R4, and R5 are complete. R1's earlier resolution was verified in the current -HTTP timeout test: assertions concern deadlines and cancellation, not context -identity. R2 remains superseded; the current plan and feature roadmap accurately -record completed implementation and separate release preparation. No active -finding remains, and no historical plan or release was rewritten. - -### Review Verification - -- `go test -count=1 ./...`, `go test -race -count=1 ./...`, and - `go vet ./...` passed. A native binary built outside the repository. -- Changed Go files are formatted; diff whitespace checks passed. -- All four maintained application configurations passed both application and - framework validation with provider credentials unset. Both render scripts, - composed-overlay render, and inheritance render passed offline. -- All four captured framework inspection operations passed against the complete - example. Focused tests cover native layering/imports/resource capture, - literal IDs, presence/null inheritance, partial-profile completion, scoped - effective/history redaction, and unchanged existing inspection behavior. -- The selected graph is PromptKit v0.12.0, ConfigKit v0.5.0, and the two `/v3` - catalogs at v3.20260930.0, without a local replacement or workspace. Selected - PromptKit contract and notice links resolved. -- The broader redaction in the new framework-report family, removed legacy - source fields/flags, and eager definition capture are explicitly approved - changes, not accidental strengthening. Shared server capacity, request - independence, HTTP wire behavior, and lexical artifact containment remain - intact. No implementation fixes were made during this review. - -## ConfigKit v0.5.0 Review - -Reviewed on 2026-10-03 at `bcf2ddf`, covering the five implementation -commits after `e1ce526`. The ConfigKit adoption and runtime ownership -boundaries match the accepted roadmap. No runtime defect, missing application -feature, or unrequested strengthening of contracts was identified. One -documentation handoff issue was identified; its current status is recorded below. - -### R2: Correct The Completed Plan's Introductory Status - -Priority: P3 (low). Status: Superseded; no action against the current plan. - -Location: `docs/roadmap/implementation.md:5–9`. - -The introduction still says "All five stages are pending" and directs the -reader to implement Stage 1 through Stage 5. Each stage is actually marked -Complete with completion evidence, and the feature roadmap identifies the -adoption as delivered. These contradictory directions leave the overall -handoff inaccurate and could lead a later coding agent to repeat completed -work. - -This is a completion-documentation issue, not an unfinished runtime feature. -The [documentation policy](../policy/documentation.md) assigns implementation -status to roadmaps; the overall status should agree with the stage evidence. - -Required change: update the introduction to state that all five stages are -complete. Describe the retained steps as implementation history and acceptance -evidence rather than instructions to start the work again. Preserve the -original planning baseline, completed stage records, deferred scope, and -separate release handoff. Do not change application code or rerun the feature -implementation to repair the wording. - -Acceptance: the overall status, individual stages, and feature roadmap agree -that implementation is complete, while release preparation remains separate. -Review the documentation diff and run `git diff --check`; this correction -does not require new tests. - -The ConfigKit plan was replaced by the PromptKit plan in `b1bb55a`. Its -historical snapshot remains in Git, while the current introduction correctly -states that all thirteen PromptKit stages are complete. This old finding does -not direct changes to the new plan or repetition of either implementation. - -### Review Verification - -- `go test -race -count=1 ./...` passed, including the new configuration, - inspection, and engine-adoption tests and existing shared-capacity coverage. -- `go vet ./...`, a native build outside the repository, and diff checks passed. -- All five maintained inheritance example commands succeeded with - `LOCAL_GPU_API_KEY` absent: validate, show, sources, explain, and render. - The child selected its own backend ID with the inherited endpoint, zero queue - capacity and false parameter remained explicit, and explanation retained - the parent/destination/directive relationship. -- Changed upstream documentation and notice links, affected local paths, - and the historical policy-plan reference resolved. -- The work set changes dependency pins, tests, examples, and documentation; - no production Go implementation was changed. ConfigKit v0.5.0 owns inheritance - through the existing single-load integration; Promptkit remains v0.11.2. -- The `extends` reservation is the explicitly accepted upstream compatibility - change, not a new Scriptorium restriction. Parameter and credential-reference - visibility, working-directory-relative paths, ordinary parent registration, - and existing shared server capacity remain as selected. - -## Earlier Promptkit Upgrade Review (Resolved) - -### Scope And Status - -Review baseline: `e177d7c`, covering implementation commits after `5c3b0cf`. -This document records a resolved test-contract issue; it does not authorize -unrelated implementation changes. No runtime defect or missing planned feature -was identified in this review. Release preparation remains separate work. - -### R1: Remove The Unrequested Context-Identity Invariant - -Priority: P3 (low). Status: Complete. - -Original location: `internal/adapter/http/handler_test.go:334–349`, -`TestHandlerRunTimeoutValidationAndContextMapping`, introduced in `7de2b02`. - -The test's `child` field and `(ctx != parent) != tc.child` assertion required -the exact parent context object for omitted/null/zero timeouts and a distinct -object for a positive timeout. The requested contract concerns effective -deadlines and cancellation propagation, not Go interface identity. In -particular, a harmless derived context that preserves the parent's deadline, -values, and cancellation would fail the omission cases despite satisfying the -application contract. - -This elevated an incidental implementation choice into a test-enforced -invariant, contrary to the [agent policy](../policy/agents.md) and -[testing policy](../policy/testing.md). The current handler's context behavior -is correct; this is a maintainability issue, not a runtime cancellation bug. - -#### Required Change - -Remove the identity comparison and the identity-only table field. Retain -behavioral assertions that an earlier parent deadline is not extended and -parent cancellation reaches execution. For omitted/null/zero values, verify -that no deadline is introduced when the parent has none. Retain coverage of -positive deadlines and the distinction between a canceled execution context -and a provider-attempt timeout while the execution context remains live. - -Use the existing runner seam and focused cases; do not introduce a context -wrapper framework, timer abstraction, new public guarantee, or production -refactor solely to change this test. - -#### Completion Criteria - -- Tests protect effective deadline/cancellation behavior without requiring - context object identity. -- A semantically equivalent derived context does not fail merely because it - is a different object. -- Existing timeout validation and HTTP outcome coverage remains intact. - -#### Resolution And Validation - -Removed the identity-only table field and context comparisons. The test now -checks effective deadlines, including omitted/null/zero requests with no -parent deadline, and explicitly checks that parent cancellation reaches the -runner. Existing positive-deadline integration tests and live-context -provider-timeout mapping remain intact. No production code changed. - -Focused HTTP timeout tests, `go test ./...`, `go test -race ./...`, -`go vet ./...`, a native build outside the repository, and `git diff --check` -all passed after remediation. - -### Original Review Verification - -- `go test -race -count=1 ./...` passed, including retry, shared-capacity, - deadline, report, definition-conformance, and architecture-boundary tests. -- `go vet ./...` passed. -- A native `cmd/scriptorium` build passed, with output outside the repository. -- The selected dependency is Promptkit v0.11.0 with its intended v2 catalogs. -- Application code, tests, release automation, and historical releases were - not changed during this review. - -The runtime ownership boundaries remain as intended: Promptkit owns framework -formats, execution, retries, and backend admission; Scriptorium owns executable -adapters, application settings, HTTP artifact policy, deadlines, and terminal -report presentation. No additional runtime restrictions, durable workflow -state, or extra release compliance gates were identified in the reviewed diff.