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