Remove completed ConfigKit planning documents
This commit is contained in:
@@ -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.
|
|
||||||
@@ -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.
|
|
||||||
@@ -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
|
||||||
|
|||||||
@@ -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.
|
||||||
|
|
||||||
|
|||||||
@@ -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.
|
|
||||||
Reference in New Issue
Block a user