Files
scriptorium/docs/roadmap/implementation.md

652 lines
39 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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: Pending.
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: Pending. Depends on Stage 1.
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: Pending. Depends on Stage 2.
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.