45 KiB
PromptKit v0.12.0 Implementation Plan
Status, Baseline, And Authority
Planned on 2026-10-04 against Scriptorium
82b0f231b6ba71328f65f9a501143b2eedbe5d9c. Stages 1–9 are complete; stages
10–13 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 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,
consumer/migration guide,
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, andbackendswithpromptkit_sources, an ordered sequence of selectors. Each selector has string fieldsfileanddirectory; 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.FilewithImports: trueand its default canonical-parent root. Directory inputs usepromptkit.DirectoryInputsunchanged, including disabled imports and retained resource contexts. Do not widen roots, flatten YAML into mappings, or infer file priority inside a directory.Sources.Mainremains nil. - Register repeatable
--promptkit-source PATHforrun,render,serve,inspect prompt,inspect profile, andinspect configurationmodes. One occurrence is one path, not a comma/glob expression. Infer file/directory from ordinaryos.Statfor 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, withFlag: "--promptkit-source"and plain[]any/map[string]anyvalues, not a named Go slice. Applicationconfigcommands 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|explainaccepts--config,--config-overlay,--promptkit-source, and--schema-dir;explainalso 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--formator--outsurface is needed. Parse/load/output/diagnostic-write failures exit 1; success exits 0. - New framework reports use native effective YAML and explanation writers.
sourcesemits a newline-terminated JSON array with DTO fieldsid,label,layer,kind,underlay_index, optionalpath, and optionalimported_fromcontainingsource_id,line, andcolumn. Preserve upstream record order and values; underlay indices include maintained inputs, not just caller groups. Do not add fields to the existing applicationconfig sourcesDTO. - 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.
-
Review the removed constructor/source/backend APIs in upstream's migration guide. Record the current module selections before changing them.
-
Select the release and tidy:
go get gitea.maximumdirect.net/eric/promptkit@v0.12.0 go mod tidyConfirm ConfigKit v0.5.0, Go 1.25.5, and both
/v3catalogs at v3.20260930.0. Remove obsolete/v2requirements andgopkg.in/yaml.v3if unreferenced. Investigate unrelated module changes; do not independently advance catalogs, commit replacements/workspaces, or vendor dependencies. -
Check the selected COPYRIGHT/LICENSE/notices. Update PromptKit's House Format entry to the target commit. Update OpenRouter to
f17d208cb7ad1fb043cda2266cd3011d11b40aa0and Rakestrawhome to993443d88c451901f4c917fa00c204fd3b54d28d, with/v3identification 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.
- Add an application-owned
SourceSelectionvalue with the two YAML string fields in the fixed choices. Put[]SourceSelectiononDocumentandAppSettingsasPromptKitSources. RemovePromptDir,ProfileDir,Backends,BackendDocument, andBackendSettingsfrom this schema and runtime conversion. Keep unrelated defaults and retry presence untouched. - 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.Settingscopies the ordered values without merging or retaining a backend sorting pass. - 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.
- 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. - 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,
Extendsfield, 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.
- Replace old directory/backend fields in command configs, common settings,
and
engineSettingswith ordered[]appconfig.SourceSelection. Route every engine-using command through the same resolved settings. Remove directory prerequisites,errPromptDirRequired, and unused directory-validation code. - Add a small repeatable source flag implementing
flag.Valueandflag.Getter. Classify explicit paths withos.Statas 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.Getsupplies plain sequence/mapping override values. ExtendapplicationOverridesto submit one whole-list override only when visited. Remove--prompt-dir/--profile-dirregistrations everywhere; do not keep deprecated aliases. Retain other flags and explicit-set behavior. - Build
promptkit.ConfigurationSourcesfrom the resolved list innewEngine. Append oneconfigkit.Underlayper entry, including an empty directory group. File inputs useImports: true; directories use the public helper and its returned contexts unchanged. PassSources,SchemaDir, andTransientRetriesintopromptkit.Config, retaining caller runtime options. Delete the backend-registration loop; do not manufacture profile/backend mappings from application settings. - 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. - Wrap source-assembly failures with application context while preserving their
causes and
promptkit.ErrInvalidConfig. Preserve constructorLoadErrorchains. Use existingwriteApplicationErrorfor 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. - Keep
serveconstructing one engine and injecting the existing restricted artifact reader. Do not alter HTTP DTOs, retry state, request mapping, response presentation, or cancellation coordination to repair configuration. Update top-level usage/help for the source flag.
Validation: production native build must pass. Run available package checks and record stale test field/fixture failures for Stages 5–7. Do not implement a test-only legacy loader to hide those failures.
Acceptance: all existing production engine paths use native sources; no removed constructor API or backend schema remains in production code.
Stage 4: Migrate Maintained Definitions, Application Examples, And Testdata
Status: Complete. Maintained and fixture prompt/profile definitions now use PromptKit's keyed format, and application examples select ordered native sources with framework backend data in separate files. The two fixture versions sharing one prompt ID are in one document so their directory remains a strict composition group. The old imported backend fragment contained no application defaults; it was removed after its framework data moved rather than introducing an unrelated defaults fragment. All four application configs validate; both maintained render scripts, the composed-overlay render, the inheritance render without credentials, and offline renders for each maintained and fixture prompt/version pass.
Files: maintained prompt/profile YAML under examples/ and
testdata/promptkit-v0.9/; their application configs and scripts; new
framework-only backend files below those roots as described here.
- Wrap profile bodies in keyed
profilesmappings, remove embeddedid, and convertbase_profiletoextends. Wrap prompts inprompts: 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. - Create
examples/framework/backends.ymlfor the ordinarylocal-gpudefinition. 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 unusedlocal-gpuprofile too. - Move the parent/child backend definitions from
examples/config.inheritance.ymlintoexamples/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. - Keep
examples/config.composed.ymlas application imports plus its selected overlay. Its sources fragment now supplies the complete source list. Remove framework backend data from the applicationconfig-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. - Move fixture-custom backend data from
testdata/promptkit-v0.9/config.ymlinto 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. - Update scripts only where the source cutover changes invocations. Run every
migrated example through offline
renderor native framework construction. Repair genuinely invalid unused definitions, rather than excluding their files from discovery. Keep schema/fixture documents outside definition directory scans.
Validation: run both maintained render scripts, composed render with the local
overlay, and inheritance render with environment credentials absent. Check all
four example application configs with config validate. Native builds and
targeted example inspection must work; Go test migration is still in progress.
Acceptance: maintained inputs use keyed formats and native source lists, and all effective definitions can be constructed offline with their resource origins.
Stage 5: Migrate CLI Parsing And Application-Inspection Tests
Status: Complete. CLI parser/config tests now protect ordered repeatable source
selection and whole-list overrides, native shared definition helpers, retired
flags and application fields, and application-only inspection with missing or
invalid framework paths. Focused CLI parser/config tests and internal/config
pass, as does the native definition-fixture render. The production build passes.
Full CLI tests retain only the execution/inspection fixture migrations assigned
to Stage 6; repository-wide test, race, and vet checks also reach the HTTP/report
constructor migrations assigned to Stage 7.
Files: internal/adapter/cli/config_test.go and parser/configuration sections
and shared helpers of run_test.go.
- 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.
- 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.
- Migrate shared
writePromptFileWithTemplate,writeProfileFile, andwriteDefinitionFixtureConfigto 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. - Rewrite application
configtests around source selections and existing server/default fields.config validate/show/sources/explainmust 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. - Replace all stale typed field references throughout
run_test.gonow so the CLI test package compiles, even where execution fixture contents are scheduled for Stage 6. Verify obsolete flags/fields are rejected, not interpreted as a compatibility path.
Validation: CLI parser/config tests and go test ./internal/config must pass.
Attempt the full suite and identify only remaining execution/HTTP/report
fixture migration, not arbitrary parser failures.
Acceptance: CLI source override presence/order and application-only inspection are protected without imposing filesystem validation on configured YAML paths.
Stage 6: Migrate Existing CLI Execution And Definition-Inspection Coverage
Status: Complete. CLI run, render, report, deadline, and definition-inspection
fixtures now use native keyed definitions and ordered framework sources. Backend
definitions live in framework files, built-in backend overlays are accepted,
and tests retain source precedence, retries, version selection, required and
optional inputs, profile inheritance, provider data, and inspection boundaries.
go test ./internal/adapter/cli ./internal/format passes, as does the native
build. Repository-wide test, race, and vet checks stop only on removed
PromptKit constructors in HTTP/report fixtures assigned to Stage 7.
Files: remaining execution/inspection sections in
internal/adapter/cli/run_test.go; formatting fixtures only if affected.
- 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.
- 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.Ischecks where available instead of old message snapshots. - 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. - 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.
- 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.
- Keep prepared/profile output fields and ordinary provider-parameter visibility unchanged. Review numeric zero expectations against their actual new definition meaning, not accidental old omission behavior.
Validation: go test ./internal/adapter/cli ./internal/format must pass, with
offline httptest execution coverage. Remaining full-suite blockers may only be
the explicitly unmigrated HTTP/report fixtures in Stage 7.
Acceptance: existing CLI workflows run with native inputs and updated boundary expectations, without legacy parsing or narrowed valid-definition support.
Stage 7: Migrate HTTP And Report Fixtures Without Changing Their Contracts
Status: Complete. HTTP and report engine fixtures now use keyed prompt/profile
definitions and native ConfigKit underlays; backend tests use PromptKit's keyed
BackendSource while retaining explicit pointer-valued limits, including the
zero-capacity queue. Request/status and report assertions remain unchanged.
Focused HTTP/report tests, go test ./..., go test -race ./..., go vet ./..., the CLI build, gofmt, git diff --check, and a repository-wide search
for removed constructor APIs pass.
Files: internal/adapter/http/handler_test.go,
internal/report/report_test.go; other test constructors found by removed-API
search. Production HTTP/report changes require an actual integration defect.
- Update
newHandlerEngineWithOptions,newDefinitionHandler, session fixtures, shared-capacity setup, andnewRetryHandlerto keyed definitions and native underlays. Replace testWithBackendwith a keyed backend file or publicBackendSourcein a later group. Use pointer fields when programmatic zero is deliberate. Retain injected clients/artifact readers. - 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.
- 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.
- 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_paramsremains provider data, including a literalextendskey; do not run request payloads through ConfigKit inheritance.
Validation: targeted HTTP/report tests followed by all development baseline checks. The entire repository must now compile and pass, not just selected packages. Search production and test construction sites for removed APIs.
Acceptance: the migration window is closed, with existing CLI/HTTP/report contracts and shared operational state preserved.
Stage 8: Protect Native Source And Definition Semantics At The App Boundary
Status: Complete. Focused CLI-boundary tests now protect same-group conflicts,
ordered overlays, empty sources, invalid lower values replaced before final
validation, malformed and invalid unused definitions, and combined framework
documents. Imported prompt content retains its source-relative resource origin
and construction-time capture while schema and request artifacts remain
preparation-time reads. Native backend/profile inheritance, null and empty-map
semantics, explicit numeric presence at the injected-client boundary, partial
profiles completed by request overrides, and literal whitespace/slash IDs are
covered. Existing full-feature adoption fixtures remain in place. Focused
adoption tests, go test ./..., go test -race ./..., go vet ./..., the CLI
build, gofmt, and git diff --check pass.
Files: a focused internal/adapter/cli/framework_sources_test.go and existing
adoption tests where they already own the behavior. Reuse migrated helpers.
Implement these bounded scenarios with real engine construction:
- 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.
- Origins and capture: select a file importing a prompt fragment with a
relative
content_file; inherit that prompt version via nativeextendsand 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. - 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 inspectGenerateRequest.TargetPresenceto 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. - Reuse or extend existing tests for partial profiles completed by request overrides and exact literal prompt/profile/version keys, including a slash and meaningful whitespace. No adapter trim/re-key operation may invalidate an otherwise usable native definition. Keep full feature fixtures for cache, sessions, roles, output validation/repair, and schema linkage.
Validation: focused adoption tests and development baseline. If a public upstream capability is defective, report a minimal reproducer instead of copying internals or silently narrowing supported definitions.
Acceptance: source order, capture/resource origins, null/presence, and complete definition plumbing are protected at the actual application boundary.
Stage 9: Add Captured Framework Validate, Show, And Sources Commands
Status: Complete. inspect configuration validate, show, and sources now
load application settings, construct one engine, and use its captured public
inspection view without preparing a request or resolving credentials. Effective
output remains PromptKit's native YAML; source JSON uses the selected DTO fields
and preserves imported locations and source order. Tests cover source-free and
credential-required configurations, invalid final definitions, source layering
and imports, stdout/stderr separation, positional rejection, and writer
failures. Focused inspection tests, go test ./..., go test -race ./...,
go vet ./..., the CLI build, gofmt, and git diff --check pass. Literal-path
explanations and their redaction coverage remain for Stage 10.
Files: internal/adapter/cli/inspect.go, a small
framework_config.go and framework_config_test.go in that package.
- Dispatch
inspect configurationseparately from existing prompt/profile modes. Implement the shared parser with the flags in the fixed choices and the first three operations. Stage 10 addsexplain; the new family is not complete until then. Reject positional arguments through normal flag parsing. - Load application settings and print their diagnostics, construct exactly one
engine through
newEngine, and obtain its publicInspectConfigurationview. Print applicable captured diagnostics safely. Do not resolve selected credentials or prepare a placeholder request. All outputs refer to this view. validatereturns 0 without success output after successful construction;showcallsWriteEffective(stdout). Keep native field presence and YAML, not a reloadable-file promise or a formatter copy.- Define the framework source DTO specified above and project
view.Sources()into it, including the optional import location. Encode a non-nil ordered slice withjson.Encoder; do not expose raw exported Go field names or filesystem contexts. Keep applicationconfigurationSourceuntouched. - 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.
- Add
explain; require explicitly set--path, parse viaconfigkit.ParsePath, and allow the empty root pointer. Useview.Explainto detect an unknown path beforeWriteExplanation: PromptKit's native writer otherwise produces no output for unknown paths. Report malformed or unknown paths as exit 1 consistently with application inspection. - 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. - Use controlled lower/upper framework files with ordinary visible parameters
and synthetic
token/passwordsentinel values. Verifyshowand effective/ historicalexplainoutput 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. - With the same valid profile, verify existing
inspect profileand 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. - Keep application
config validatesuccessful for a valid selector document referencing an invalid framework definition, while frameworkvalidatefails. 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.
- Make
docs/config.mdown 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. - Make
docs/cli.mdown 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. - 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.
- Provide concise before/after migration examples for application selectors,
backend relocation, keyed IDs/versions,
base_profiletoextends, and zero/null/map semantics. Put executable upgrade guidance indocs/consumers/upgrading-promptkit.md, linked from the configuration contract and README; link upstream for details. Complete copyable inputs remain inexamples/. Do not rewrite historical releases or the former Go-package migration's historical version claims as though they were current adoption. - 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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, includingexplain --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. - 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.mdto say implementation is delivered only when the full audit passes. Keep the roadmap as target/decision context, not a second stage log. - 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.