Remove completed ConfigKit planning documents

This commit is contained in:
2026-11-18 14:31:37 +00:00
parent 932fd6da25
commit 1b1d967fc7
5 changed files with 2 additions and 1231 deletions

View File

@@ -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.

View File

@@ -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.

View File

@@ -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 earlier licensing-only proposal with alignment of the complete applicable
policy set and its supporting documentation. It defines the targeted end state policy set and its supporting documentation. It defines the targeted end state
and required changes. Its completed implementation plan is preserved in Git at and required changes. Its completed implementation plan is preserved in Git at
`git show 8b6c12f912b28ac00016f047f9846798a5de95d9:docs/roadmap/implementation.md`; `git show 8b6c12f912b28ac00016f047f9846798a5de95d9:docs/roadmap/implementation.md`.
the current `implementation.md` belongs to a later work set.
The next release summary should mention the policy and licensing alignment, The next release summary should mention the policy and licensing alignment,
the already-selected GPL-3.0-or-later application grant, and the separate the already-selected GPL-3.0-or-later application grant, and the separate

View File

@@ -25,7 +25,7 @@ from new library APIs.
The reviewed Scriptorium source is commit The reviewed Scriptorium source is commit
`bb5006517b6c27dcbe56074f1d97140bf0999c48`; the last release is v0.15.0. `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` v0.5.0. PromptKit remains v0.11.2, with the OpenRouter and Rakestrawhome `/v2`
catalog modules at v2.20260926.0. catalog modules at v2.20260926.0.

View File

@@ -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.