diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md new file mode 100644 index 0000000..24475b5 --- /dev/null +++ b/docs/roadmap/implementation.md @@ -0,0 +1,896 @@ +# Shared reporting and PromptKit v0.20.0 implementation plan + +Status: ready for implementation; no stages completed. + +## Scope, authority, and execution + +Implement the accepted target in the [feature roadmap](promptkit-v0.20.0.md). +That document owns operator intent, selected behavior, OD-1 through OD-11, and +exclusions. This plan owns the transition, API design choices, stage order, and +verification. Read [development](../development.md), the +[agent policy](../policy/agents.md), and applicable policies before each stage. +Use [architecture](../policy/architecture.md), [testing](../policy/testing.md), +[documentation](../policy/documentation.md), [OSS](../policy/oss.md), and +[release](../policy/release.md) for their respective work. The +[ADRs](../adr/README.md) explain the accepted architecture. + +Execute the numbered stages in order. Each stage is sized for one focused Luna +implementation prompt. This is one end-to-end sprint: intermediate stages may +fail to compile while dependent callers are being converted. Do not introduce +compatibility layers or temporary public APIs to keep those stages green. +Carry relevant tests and GoDoc with their owning change; defer broad suites +until their dependencies exist. Record completed stages and actual validation +here, commit completed reviewable units under repository policy, and preserve +unrelated work. A stage boundary is not a publication or compatibility boundary. + +The inspected baseline is `cb7e05284c554f0da170dc17a0e2e3eac2aed0bc`. +It has core v0.3.0 requirements in both integrations, ckconfig v0.3.0 in +ckprompt, PromptKit v0.18.0, and ConfigKit v1.1.0. The feature roadmap records +the pinned PromptKit v0.20.0 and ConfigKit v1.1.0 evidence. Use those released +sources only. Do not follow unreleased upstream work or change sibling repos. + +Use Go 1.27.0 on PATH as described in the [release procedure](../release.md). +Preserve the ignored aligned `go.work`, `go.work.sum`, and local credentials. +Never inspect token contents. Do not commit workspace files, local replacements, +or invented checksums. Core retains its Go 1.26.0 consumer minimum; integrations +retain 1.27.0. During joint development use the aligned workspace. Stages 24–26 +explicitly handle released requirements and independent builds. + +Public names below select a concrete design, not existing API. Private file +splits and helper names may follow idiomatic implementation needs. If a concrete +API adjustment is necessary, preserve the selected behavior, explain the reason, +and update dependent stages; do not reopen settled scope or silently add policy. +No arbitrary deep-copy, concurrent-dispatch, exact-byte output, transactional +writer, or upstream-domain correctness guarantee is added by this plan. + +## Coverage and checkpoints + +| Target owner in the feature roadmap | Implementing stages | +| --- | --- | +| Shared reporting, safe conversion, universal formats, and output inventory | 1–4, 7–9, 23 | +| Public CLI JSON and ordered typed bindings | 5–6 | +| Released adoption, resource reports, native errors, and smoke evidence | 8–9 | +| OD-1 prepared preview and OD-2 controls/input/aliases | 10–11, 13 | +| OD-3 namespace defaults and applicability | 12 | +| OD-4 metadata discovery and OD-8 focused inspection | 14, 17–18 | +| OD-5 detailed diff and OD-10 assertion outcomes | 19 | +| OD-6 failure evidence and aggregate validation | 14, 18, 20 | +| OD-9 independent comparison and OD-11 overrides | 15–16 | +| Maintained consumers and canonical contracts | 21–23 | +| OD-7 releases, real dependency alignment, and final validation | 24–26 | + +## Stage 1: Shared report representation and safe YAML conversion + +Start in the root package beside [reporter.go](../../reporter.go). Add private +report normalization using `encoding/json`: marshal the original report value, +then decode with `UseNumber` into maps, sequences, scalars, null, and +`json.Number`. Honor JSON tags, omissions, and custom serialization once for +all core-serialized formats. Keep numeric tokens intact instead of routing them +through float64. Strings remain ordinary strings. Unsupported serialization is +an observable error; no stringification fallback. + +Add public `DecodeYAMLReport(io.Reader) (any, error)` for one safe inspection +YAML document. Use the existing YAML v4 dependency and a private node walk to +produce ordinary JSON-compatible values. Preserve scalar types, presence, +null/empty distinctions, sequence order, and numeric value. Standard +`json.Number` may retain JSON numeric tokens without imposing Stage 5's CLI +number policy. Convert supported YAML numeric notation faithfully; report an +unrepresentable value rather than rounding or silently treating it as text. +The helper is explicitly for the restricted inspection value model, not a +lossless YAML editor. Reject unsupported meanings, such as a non-string mapping +key or multiple logical documents, with a conversion error. Do not parse report +strings heuristically or read application configuration structs or source files. + +Build one private conversion from the normalized representation to YAML nodes, +including numeric nodes rather than quoted numeric strings. This representation +also feeds JSON and automatic shape selection. No public document tree or new +serialization tags. + +Verify JSON field/custom-serialization behavior and meaningful scalar, number, +presence, empty-container, and redaction preservation with focused core tests. +Include large integers and strings resembling numbers or booleans. Tests compare +logical values, not YAML quoting or mapping order. + +## Stage 2: Writer rendering and standard text templates + +Add these public root-package contracts: + +- `Format` with `FormatText`, `FormatYAML`, and `FormatJSON`; its zero value means + automatic selection for direct writer use. +- `Report{Value any; TextTemplate *template.Template}`. +- `ParseTextTemplate(name, source string, funcs template.FuncMap) + (*template.Template, error)`, using standard `text/template`; nil funcs is valid. +- `RenderReport(io.Writer, Report, Format) error`. + +Use one implementation for all formats. Follow the feature roadmap's +[selection table](promptkit-v0.20.0.md#agreed-universal-and-automatic-format-selection): +explicit format first, otherwise a supplied template selects text, otherwise +select by the normalized outer shape. Untemplated strings, numbers, booleans, +and nonempty string lists use plain text; structured values, empty collections, +and null use YAML. Explicit text for that second group uses the same YAML +renderer. For scalar text emit a terminating newline; for string lists emit one +item per line. Execute templated text as supplied without another formatting pass. +Use conventional readable YAML and JSON encoding; whitespace and map order are +not additional contracts. An unknown nonzero writer Format returns an error +rather than selecting a fallback. + +Templates receive the original Go value. Templated text does not marshal JSON +first; explicit YAML/JSON does not execute the template. Template preparation, +execution, unsupported serialization, and writer errors remain observable, with +no renderer fallback on failure. Callers can prepare reusable templates during +assembly and attach preparation errors through existing declaration-error APIs. +Use normal template functions initially; no helper framework or public template +value model. Caller-supplied template objects retain ordinary Go ownership. + +Verify all automatic shapes, explicit precedence, original-value template access, +JSON-ignored fields in templates, unsupported JSON values, template errors, +large-number YAML/JSON fidelity, and short/error writers. Keep expectations +semantic except where the selected text behavior itself matters. + +## Stage 3: Reporter handoff through the existing lifecycle + +Add `(*Reporter).Report(Report) error`. Delegate to Stage 2 through the existing +`RenderOutput` coordination and destination writer. Store the invocation format +selection in reporting state; do not create another reporter or delivery state. +Keep existing raw writes and `RenderOutput` available as deliberate raw paths. + +Preserve quiet-mode rendering through discard, closed-reporter handling, +separate presentation evidence, and existing final outcome precedence. Do not +add a context-cancellation gate to `Report`: handlers decide whether to submit +already-acquired evidence. Do not close or flush caller writers. Avoid recursive +report submission from inside a rendering callback. + +Exercise rendering errors under quiet mode, a successful operation with delivery +failure, a nonzero domain outcome with delivery failure, supported cause identity, +and submission of acquired content after cancellation. Reuse existing reporter +and outcome coverage where unchanged. Document the public handoff and raw-output +boundary in GoDoc. + +## Stage 4: Universal format input, core version, and a core consumer + +Extend neutral core flag metadata and parser selection in +[metadata.go](../../internal/commandmeta/metadata.go), +[parser.go](../../parser.go), and the internal Cobra adapter. Add core-owned +`--format` with `text`, `yaml`, and `json` completion. Omission means automatic; +explicit empty or unknown formats are usage errors before input factories, +acquisition, or handlers. Validate supplied occurrences using normal singleton +conversion behavior; the last valid supplied choice selects the format. Preserve +entered spellings, consumed values, `--`, reporting-mode ordering, and fresh +invocation state. Do not treat the value-taking flag as a boolean when generating +completion or reducing core flag occurrences. + +Use existing core-flag placement and alias mechanisms. Reserve the long name +`format` at installation, with no built-in short spelling. A local binding or +conflicting alias source produces the existing installation collision error; +a deliberate alias to core `--format`, such as `--fmt`, remains supported. +Remove the version command's local format binding and switch its report to +`Report` plus an ordinary version text template. Do not encode help, usage, +completion protocol output, or diagnostic messages as reports. + +Convert one maintained [core consumer](../../examples/core) command to a data +handoff and optional template, with no format switch. Exercise core/application +reports in all three formats, unknown formats before domain work, format aliases, +metadata/help without acquisition, reservation collisions, and repeated +invocations. Update the core CLI and consumer reporting sections with the landed +boundary; later documentation stages complete the integration inventory. + +## Stage 5: Public CLI JSON parsing + +Add `ParseCLIJSON(string) (any, error)` in core. Decode exactly one JSON value +with `UseNumber`, require completion of that value, and recursively convert +numbers under [OD-2](promptkit-v0.20.0.md#od-2-request-controls-and-provider-parameter-grammar). +Integer syntax becomes int64, or uint64 for representable nonnegative overflow; +decimal/exponent syntax becomes float64. Return syntax and numeric range errors; +accept ordinary float approximation. Preserve nested arrays, objects, null, +booleans, and strings. Keep conversion and its required policy/rationale comments +in one private CLI helper. This parser is separate from report normalization. + +Test nested values, signed/unsigned integer boundaries, out-of-range values, +decimal and exponent syntax, floating range failures, trailing JSON, and ordinary +float approximation. Do not add arbitrary-precision types or a public numeric +conversion API. Each integration will enforce its flag's outer shape. + +## Stage 6: Ordered typed occurrences and reusable binding identity + +Extend [binding.go](../../binding.go), [flag_values.go](../../flag_values.go), +and the neutral preparation path to retain ordinal positions from existing +`FlagOccurrences`. Add: + +- `OccurrenceFlag[I,V](FlagMeta, func(string) (V,error), + func(*I, Supplied[V])) Flag[I]`: repeatable, converted once per supplied + occurrence, no fallback occurrences; invokes its setter once per occurrence. +- `RenameFlag[I](Flag[I], name string) Flag[I]`: independent binding identity, + same parser/setter/default/required/completion behavior, replacement long name, + and no inherited short spelling. Normal declaration validation still applies. + +Apply participating occurrence bindings in actual command-line order across +canonical spellings and aliases. Ordinary bindings keep their existing grouped +semantics. During input construction apply ordinary flag values, then ordered +occurrences, then operands, before `CheckInput`. The relative ordering contract +is needed among participating occurrence bindings, not between arbitrary caller +side effects. All conversion failures still occur before input construction. + +Extend private prepared values with typed occurrence closures and ordinals. +`CaptureFlags` retains those records against original binding identities; +`FlagValues.ApplyTo` checks the selected subset and required presence, then +replays only its participating records in order without parsing again. Repeated +applications retain independent core-owned parsed collections. Preserve existing +wiring-versus-usage classification; expose neither raw arguments nor backend +objects. `RenameFlag` must preserve ordered behavior when used on such a binding. + +Verify interleaved distinct flags and aliases, repeated names, explicit empty +values, omitted bindings, subset selection, conversion failure, required checks, +renamed handles, repeated application, and fresh invocations. Do not change the +ordinary `RepeatFlag` replacement semantics to simulate ordering. + +## Stage 7: Migrate existing ckconfig reports to core + +Convert the existing `scopes`, `show`, `sources`, `explain`, `diff`, and concise +`validate` report paths in [ckconfig](../../integrations/ckconfig) to the public +handoff. Remove local format flags, validators, encoding switches, and encoders. +Give integration-owned projections JSON tags for their selected content; thin +path/location/snapshot projections remain appropriate. + +For effective display, capture native `WriteEffective` output, call +`DecodeYAMLReport`, and hand off that logical value without a text template. +For `--scope all`, acquire all requested views and complete required validation +before output; combine their safe values into one map keyed by scope ID, even +with one registered scope. Single-scope output is unwrapped. Retire document +markers and scope-comment framing; do not promise mapping order. An acquisition +failure prevents the combined display. Conversion/rendering failures use the +presentation path, including under quiet mode. + +Keep current content where the target does not change it. Use concise text +templates for scopes/source inventories and existing explanation summaries when +appropriate; default diff remains a structured mapping without a template. +For concise validation, collect reached-scope results before one submission; +stop acquisition on failure/cancellation and preserve its outcome. Stage 20 +extends that same aggregation with structured evidence rather than introducing +another validation delivery path. + +Verify universal formats, safe-value conversion, aggregate shape, selected +single-string output, provider failure before combined display, and separate +presentation failures. Replace obsolete native-byte/document-order assertions +and update current display/validation contracts and the corresponding testing +policy wording as behavior changes. Do not add domain comparison tests. + +## Stage 8: Adopt PromptKit v0.20.0 and native resource inspection + +Update ckprompt's PromptKit requirement and authentic sums to v0.20.0; keep +ConfigKit v1.1.0 and existing Go minima. Review the released notices and update +[module attribution](../../integrations/ckprompt/docs/oss/attribution.md) and +applicable transitive notices. Do not fabricate future CommandKit dependency sums. + +Implement the [resource inspection target](promptkit-v0.20.0.md#resource-inspection). +Remove duplicated prompt/profile report structs and per-field formatters; pass +the native `PromptInspection` and `ProfileInspection` to core, without templates. +Add `BackendRequest{Selection ckconfig.Selection; ID string}` and an independently +optional `Suite.InspectBackend` callback returning +`commandkit.Acquired[*promptkit.BackendInspection]`. Wire `FromEngine` through +native `InspectBackend`, and install `show backend BACKEND_ID` when available. +Stage 12 adds the common namespace field to these requests. + +Use native JSON omission/presence and returned captured messages. Do not complete +profile settings, infer readiness, resolve credentials, or reconstruct provenance +in these commands. Preserve errors, including native backend-not-found identity, +acquisition diagnostics, cancellation, and presentation failures. Adapt only +fixtures and callers affected by the released API; retain legitimate collection +release/version evidence. + +Verify native handoff fidelity across all formats, independent callback absence, +no loading for help/completion, positional IDs, omitted versus explicit resource +fields, native errors, and cancellation. Assert adaptation against returned +native evidence rather than rechecking upstream inheritance or rendering. + +## Stage 9: Consolidate remaining ckprompt reports + +Move requirements show/validate, all catalogs, and smoke reports onto core +rendering. Remove remaining local format bindings, allowlists, encoders, and +format-specific report paths. Preserve selected report content with JSON tags +and text templates where a concise text view already serves operators. Keep +smoke reports as structured values without a dedicated text template. + +Single smoke reports retain native returned evidence, even with an operation +error. `test all` submits one report containing its ordered reached test results; +stop under the existing operation/cancellation lifecycle and retain partial +results. Core does not aggregate tests. Do not drop an acquired report merely +because the context became canceled; do not fabricate a report when native +preparation returned none. Preserve authentication response-limit unknown facts, +preparation-error causes, and operational failures. Findings that are false, +unknown, unsupported, or incomplete do not independently change command status. + +Verify one JSON document for aggregation, partial report plus error, no-report +preparation errors, cancellation after evidence acquisition, quiet rendering, +and delivery failure without losing domain evidence. Use deterministic native +fixtures/test doubles rather than network probes. Update current report guidance +for the converted commands. + +## Stage 10: Reusable execution and resource flag collections + +Implement CLI-specific collections in ckprompt using ordinary public core flags. +Use typed flag-set structs exposing named original `Flag[I]` handles and an +`All() []Flag[I]` convenience method; callers select subsets with ordinary slices. +Constructors take a destination accessor into the application's own input type. +This avoids a new core collection API, string-keyed value lookup, or enum-driven +request builder. + +Select these collection/value boundaries: + +- `ExecutionInput` holds native `*ExecutionTargetOverride` and `*int` + transient retries. `NewExecutionFlags` supplies the eleven execution controls + from OD-2 through named handles. Allocate the native override only when a + relevant value is supplied; retain pointer zero/empty values and upstream + scalar semantics. +- `ResourceInput` holds presence-aware prompt/profile/backend/session IDs. + `NewResourceFlags` exposes those handles independently. +- `PromptInputs` holds native variables and artifact-reference maps. + `NewPromptInputFlags` supplies variable/text/file handles; Stage 11 fills in + ordered text/file construction. No application-internal execution helper is + introduced. + +Use canonical names from the [OD-2 table](promptkit-v0.20.0.md#od-2-request-controls-and-provider-parameter-grammar). +Define each name, usage, and alias relationship once in ckprompt metadata reused +by Stage 13. Preserve existing scalar syntax and integer timeout units. +`--llm-extra-params` is a singleton object parsed by `ParseCLIJSON`; reject a +non-object through the usage path and forward an explicit empty object unchanged. +Leave upstream value validation and whole-map replacement to PromptKit. + +Use execution controls on validation, preview, and smoke. Profile selection is +applicable to all three; prompt selection remains positional for validation and +preview. Backend selection is for native smoke requests; ordinary RunRequest has +no backend-selection field. Session, variables, and prompt inputs apply only to +the request operations that consume them. Requirements show uses only its +profile/session/variable context. Resource inspection gets no execution flags. + +Retain authoritative application builders: seed the native request once, allow +a complete replacement, and never reapply flags afterward. Preserve nil versus +explicit retries and the different native ordinary/smoke defaults. Verify +collection use with an application-owned input, selected subsets, zero/empty +forwarding, JSON object parsing, and builder replacement at the boundary. + +## Stage 11: Ordered literal/file inputs and concrete preview + +Use `OccurrenceFlag` for named text/file assignments. Split at the first `=`, +preserve literal empty text, construct native `Inline` or `File` references, and +assign into the same `PromptInputs.Inputs` map as occurrences are replayed. +The last occurrence per name wins across both forms. Use canonical flags and +aliases exactly as OD-2: `--input` now denotes literal text; file access uses +`--llm-input-file` or its later scoped alias. Do not infer files from text. +No prompt-input flags go onto smoke tests. + +Add `PreparationRequest` carrying selection and native RunRequest, an optional +`Suite.PrepareRequest` callback returning `Acquired[*promptkit.PreparedRun]`, and +`WithRequestPreparation` taking the same loader/builder pattern as +`WithRequestValidation`. Install `show prepared PROMPT_ID` independently of +validation/resource inspection. Forward one final built request to native +`Engine.Prepare` exactly once; do not call ValidateRequest first or retain a +prepared execution handle. Hand off native PreparedRun without a template. +Stage 12 extends the common request envelope with namespace selection. + +Reuse input/state preparation and diagnostics. Explain in command help that +preparation does resource I/O and reports rendered application content without +calling the model. No execution-success or public-disclosure guarantee. + +Verify alternating text/file occurrences, duplicate names, aliases after Stage 13, +empty literals, values containing `=`, fresh invocations, builder replacement, +preview callback independence, request/context forwarding, native result/error +identity, and no model invocation. Derive expected preview evidence from the +native result rather than asserting PromptKit's rendering algorithm. + +## Stage 12: Opt-in namespace composition + +Add `WithNamespaces(suite, promptkit.Namespaces) Suite` and store explicit +application defaults in an optional suite field. Add `Namespaces +*promptkit.Namespaces` to applicable ckprompt request envelopes, including +preparation and smoke. Nil means leave the loader's view untouched. With the +option enabled, start with its declared defaults and replace only supplied CLI +fields, including explicit empty clearing; populate the final native value in +the operation request. Native adapters apply one `Engine.WithNamespaces` call +after loading and before the selected upstream operation. + +Implement only the flags in [OD-3's applicability table](promptkit-v0.20.0.md#od-3-namespace-flags-and-loader-defaults). +Keep catalog filters and global configuration inspection separate. `FromEngine` +callbacks and validation/preparation/smoke adapters consume request namespace +selection consistently; custom callbacks receive the selection without an extra +hidden loader. Builders retain authority over their native requests. Loaders +using the standard option leave view-default selection to the adapter; loaders +without it remain usable as before. + +Explain native requirements profile identity in help, including explicit short +profile selection versus the prompt's stored default reference. Do not rewrite +configured references or try to make discovery profile-independent. + +Verify defaults plus one override preserve unrelated defaults, explicit clearing, +qualified IDs, applicable flag availability, custom loader behavior without the +option, and native view/error forwarding. Test boundary equivalence, not native +namespace membership or requirements-analysis correctness. + +## Stage 13: Generated scoped aliases and complete-family installation + +Add `Declarations(suite) []commandkit.Declaration`, assembling the canonical +family and generated exact-command `FlagAliasFor` rules. Retain `Command(suite)` +for canonical-only installation. Generate aliases from the selected flags and +shared metadata built in Stages 10–12, following OD-2/OD-3; do not keep a separate +command-by-flag matrix. Generate only for installed commands and applicable +bindings. No aliases are application-wide by default. + +Use the existing routing/installation boundary, original binding identities, +and conflict checks. Application-owned commands can install deliberate aliases +through the public core API. Do not add subtree scopes, wrapper commands, or a +new declaration-bundle type. Canonical-only help must not claim convenience +aliases that were never installed. + +Exercise convenient and canonical-only assembly, optional callback subsets, +command aliases with scoped flag aliases, unknown/inapplicable names, native +binding presence, mixed-alias occurrence order, and ordinary installation +conflicts. Metadata/help/completion remain independent of engine acquisition. + +## Stage 14: Metadata and failed-acquisition evidence facets + +Extend [ckconfig contracts](../../integrations/ckconfig/contracts.go) with +`Scope.Features ScopeFeatures`: `PathDiscovery`, `PathShow`, and `Overrides` +booleans. These describe optional modes within existing commands, not new +subcommands. Native adapters advertise the first two; overrides remain explicit +loader opt-in in Stage 16. Retain existing `Operations` and the six-command +family. Capture features with the suite, check requested mode availability +before acquisition, and include supported feature names in scope discovery/help. +A declared mode missing its required acquired facet is an operational provider +wiring error, not an empty successful report. Detailed validation itself remains +available on validation scopes and can report unavailable native findings. + +Add `View.Metadata *configkit.Metadata` and `View.Findings *Findings`, with +`Findings{Records []configkit.Diagnostic; Messages []commandkit.Diagnostic}`. +Nil findings means unavailable; a nonnil empty record set means acquired but +empty. Existing `View.Sources` supplies optional inventory, including after an +error. Keep metadata as a deliberate upstream public value dependency; no +parallel metadata engine or generic diagnostic framework. + +Put native-generated ordinary warning presentations in `Findings.Messages`, +with their known association to the native record set. Keep unrelated application +messages in `Acquired.Diagnostics`. Ordinary handlers queue both groups; +detailed validation reports native records and queues only unrelated messages, +so filtering does not produce duplicate ordinary warnings. Keep the existing +terminal explanation, even when it describes a finding. Do not deduplicate by +message text or discard caller messages with no known relationship. + +Update `FromConfigKit` and `ckprompt.ConfigScope`: successful loads expose native +safe writers, sources, metadata, and findings. A matched `*configkit.LoadError` +exposes its captured Sources/Diagnostics alongside the original error. Use that +error snapshot as the failure evidence rather than appending a duplicate result +inventory; do not expose effective configuration or metadata from a failed load. +Other failures may have no structured evidence. Keep unavailable distinct from +available-empty inventory via the optional source reader. Preserve error chains +and existing diagnostic severity/terminal ownership. Ordinary PromptKit loading +outside ConfigScope continues its normal diagnostic delivery. + +Update acquisition-report helpers to queue native presentations from their new +owner without changing unaffected operations. Test both native adapters, success, +matched/wrapped errors, empty versus unavailable evidence, no effective facet on +failure, independently supplied diagnostics, and metadata/help without loading. + +## Stage 15: Independent comparison selector inputs + +Replace inheritance in [input.go](../../integrations/ckconfig/input.go). +Add `Selector.AgainstName string`; an empty name declares no right-side flag. +For a declared counterpart use Stage 6's `RenameFlag` to retain domain parsing +and setter behavior with a fresh identity and no copied short alias. Capture +left and right values into distinct `FlagValues[I]` stores. Validate name +collisions through normal assembly; do not auto-generate counterpart names. + +Prepare each side with a separate `NewInput`, applying only that side's bindings +and selection. Omitted fields preserve the factory's ordinary defaults and +unsupplied state. Remove `inheritComparisonSelection`; config and overlay +counterparts also start independently. No selector value or repeatable collection +is copied to the opposite side, including when that side is partly supplied. +Required checks apply to the applicable declared subset on its side. Complete +both input checks before one `NewState` and the existing pair provider call. +Command-wide scope/format/detail/assertion controls stay outside side inputs. +Equal selections still acquire both sides and compare. + +Verify OD-9's left-only/right-only/both/neither and partial-side cases, custom +repeated selectors, required inputs, supplied state, fresh invocation storage, +shared state, and checks before acquisition. Keep application factory objects +and caches application-owned; no arbitrary deep copying. Update selector GoDoc +and replace the canonical comparison inheritance description with the selected +model. Explicit-empty custom collections remain application-defined. + +## Stage 16: Opt-in transient override acquisition + +Add `Selection.Overrides []configkit.Override`. Preserve ordered records; nil +means no CLI records. A loader opting in via `scope.Features.Overrides = true` +reads those records during its ordinary load and supplies them to ConfigKit. +Reuse the existing loader signature instead of adding a second loader or trying +to modify an already-loaded result. `FromConfigKit` and `ConfigScope` do not +claim that arbitrary application loaders consume overrides automatically. + +Install repeatable `--set POINTER=JSON` on acquisition commands (`validate`, +`show`, `sources`, `explain`, and `diff`), and `--against-set` on comparisons. +Scope discovery gets no acquisition flags. Parse with a shared ckconfig assignment +helper: split at the first `=`, parse the pointer with native ConfigKit path +syntax, parse one JSON value with `ParseCLIJSON`, and set the safe provenance +label to `--set` or `--against-set`. Syntax/JSON conversion failures are usage +errors. Native restrictions on admissible override paths and combinations remain +load-time ConfigKit errors. Do not prevalidate root/index/schema restrictions, +deduplicate, collapse records, resolve overlaps, or retry a rejected load. + +Only loaders that declared support receive installed override flags for their +scope; reject an unsupported selected mode before acquisition, including mixed +aggregate scope coverage. Supply the same CLI records independently to each +selected ordinary scope that accepts them. Copy CLI-owned record slices and +parsed JSON containers when applied to independently prepared selections; do not +copy arbitrary application runtime objects. For comparison, left and right lists +are independent under OD-9; absence never erases application-owned overrides or +inherits the other side's CLI records. No new clearing flag. + +Document the unsupported `=` in pointer keys and preserve `=` in JSON values. +Verify nested typed values, empty/false/zero/null, duplicate/overlapping records +forwarded in order, safe labels, capability availability, comparison separation, +and propagation of native load errors/provenance. Domain precedence and override +algorithms remain upstream tests. + +## Stage 17: Explanation discovery and metadata + +Extend `config explain` under [OD-4](promptkit-v0.20.0.md#od-4-configuration-path-and-metadata-presentation). +Track supplied `--path` separately from its value; root `--path ''` is an +operation. Bare invocation shows successful command help before input/state +factories or acquisition. Select `--list` or `--path`, with both a usage error. +List-only flags are `--historical`, `--under POINTER`, and +`--explicit=true|false`; reject their use in path mode or without list selection +as an invalid combination rather than silently ignoring them. + +For listing, require declared PathDiscovery and acquired metadata. Enumerate +native HistoricalPaths, use Lookup for current presence and explicitness, and +include historical-only paths only when requested. Obtain History even when +Lookup is absent where detailed explanation requires it. Represent unavailable +current metadata separately from false explicitness. Do not label all +non-explicit values as defaults or enumerate schema fields that never existed. + +Use parsed pointer token boundaries for subtree tests, including root and escaped +keys. A small private pointer-token comparison can consume native paths' String +representations; it must not invent another domain path parser or equate textual +prefixes. Retain native paths and list indexes. Historical-only entries match +neither current explicitness filter. Native path enumeration order is sufficient; +do not add a new ordering guarantee. + +Use a compact discovery report `{scope, paths: [...]}` with per-entry path, +present, and optional metadata containing explicitness when current. Attach a +compact text template; values/history stay out of the list. Extend path-specific +explanation's existing report with native available field metadata, avoiding +repeated evidence. Existing explanation remains usable when PathDiscovery is +absent. Update help, GoDoc, and focused tests for mode/presence/filter behavior, +capabilities, historical-only evidence, and result delivery. + +## Stage 18: Focused effective values and source evidence + +Add `config show --path POINTER` for one scope with PathShow support. Parse the +pointer before loading, call the acquired native `Explain`, and select its safe +effective snapshot. An absent effective path is operational failure; explicitly +present null succeeds. A historical-only explanation does not supply a current +value. Convert the snapshot YAML through core and submit only the selected value, +without snapshot wrappers or a text template. Whole-document aggregate show +continues Stage 7's map; path plus `--scope all` is a usage error. + +Add `config sources --source-id ID` to existing Sources capability. Filter the +acquired inventory rather than invoking another loader. Retain the ordinary +source report envelope and return its selected single entry; unknown IDs are +operational failures. On acquisition error, report available captured source +inventory, filtered when requested, while preserving the acquisition failure. +If a filter also misses during a failed load, preserve the original cause and +include the selection problem in the explanation rather than replacing the load +error. If evidence is unavailable, say so; do not fabricate an empty inventory. +Source IDs are local to this acquisition. Preserve native locations, version +and destination evidence, and redaction in the existing thin source projection. + +Verify mapping/string/false/zero/null focused display across formats, missing +and historical-only paths, optional capability failure, known/unknown source +selection, available-empty versus unavailable failure evidence, native cause +identity, and presentation failure alongside acquisition failure. Do not read +source files again to recover evidence. + +## Stage 19: Detailed differences and assertion outcomes + +Reuse existing Scope.Compare and native Difference records. Keep concise +additions/changes/deletions as default and add `--details`. The detailed report +is `{scope, differences: [...]}`; entries carry native `path`, `before`, `after`, +and `hidden_changed`. Each snapshot has explicit `present`, `redacted`, and a +safe decoded `value` (null when absent, distinguished by present=false). +Decode only present native snapshots; do not interpret marker-looking strings +as redaction. Use one projection path and ordinary JSON tags, no mirrored +upstream graph or custom omission framework. Empty differences is `[]`, not null. +Both modes have no text template, so automatic output is YAML. + +Add opt-in `--check`. Use native record presence, including concealed changes, +to return a domain outcome with status 3 for differences; equality stays status 0. +Usage and operational errors retain 2 and 1 respectively. Without --check, +successful differences remain success. Render the report before returning the +chosen operation outcome. Preserve a nonzero domain result if presentation also +fails, retaining separate presentation evidence under core outcome rules. + +Verify the same provider calls/loads serve concise and detailed views, native +additions/deletions, null versus absence, hidden changes with equal safe values, +empty results, sequence snapshots remaining atomic, all formats, and assertion +outcomes with writer/render failure. Do not compute equality from displayed YAML, +add a comparison callback, reload data, or implement list matching. + +## Stage 20: Detailed validation and reached-scope aggregation + +Complete Stage 7's validation aggregation using Stage 14's evidence. Add +`--details`, repeatable `--severity`, and repeatable `--code` on validation; +filters require detailed mode. Parse severity using native known severities; +codes remain exact native code strings, including future/unmatched strings. +Within one filter match any selected value; across filters match both. Filter +only presentation, never operation outcome. + +Acquire scopes in existing order, stopping at first acquisition failure or +cancellation. Retain completed-scope results and available evidence from the +failing/reached scope. Do not create records claiming unvisited scopes passed. +Submit once after acquisition stops, even if cancellation caused the stop. This +handler must not use an ordinary inspection helper's pre-submission cancellation +guard. Keep native-generated messages in their existing diagnostic lifecycle; +aggregate report timing does not buffer the whole invocation. + +Use one report `{scopes: [...]}` in concise and detailed modes. Each entry names +the scope and its outcome (`valid`, `failed`, or `canceled`); detailed entries +add findings adapted from native records with safe source references, and +distinguish `unavailable`, `empty`, `filtered`, and `present` evidence states. +Use existing thin path/location/source projections, converting native Paths to +operator pointer strings instead of serializing their private storage. Keep +required sources for selected findings, including related locations. Apply the +known-group warning coordination from Stage 14, preserving +unrelated messages and the terminal failure explanation. Concise mode retains +ordinary warnings and a compact text template; detailed mode has the selected +readable text template with scope/outcome followed by findings and locations. +Explicit YAML/JSON renders that same selected report value. + +A failed load establishes no effective configuration. Successfully rendering its +evidence never changes failure to success. Preserve cancellation/load cause and +separate presentation failure. Output errors occur after acquisition has stopped +and cannot undo loads or stop loads already completed. Update the CLI and tests +that formerly stopped on per-scope output failures. + +Verify success, warnings, matched load failure, unavailable/empty evidence, +filters with no matches, source references, known duplicate suppression, +unrelated warnings, aggregate failure/cancellation, one JSON document, quiet +mode, and combined operation/presentation failures. Avoid exact cosmetic +snapshots and upstream validation-rule tests. + +## Stage 21: Simple consumer and core/configuration API exercise + +Update the maintained [simple ckconfig consumer](../../integrations/ckconfig/examples/simple) +to install an explicitly configured FromConfigKit scope with Overrides enabled, +replacing AppCommand convenience wiring there. Append the selected native CLI +records to its ordinary ConfigKit Options.Overrides during loading, leaving +native conflict handling intact. Declare explicit right-side names for any +selected application selectors. Keep ordinary configuration discovery/default +behavior on omitted sides. Demonstrate metadata +listing, focused values, detailed validation, source filtering, detailed diff, +and assertions through the standard family, not custom duplicate handlers. + +Use the existing before/after fixtures and add `fixtures/invalid.yml` with a +valid schema header plus `greeting: [invalid]`, which cannot decode into the +example string field. Use it for acquired-source and diagnostic delivery, not +to independently test upstream type validation. Extend existing consumer tests +for a representative normal task, a failed-load evidence task, and an +independent comparison/override task. Reuse +lower-layer parsing and rendering coverage; do not duplicate the full mode +matrix here. Show a structured application report and text template in the core +consumer without optional integration imports. Ensure metadata-only operations +do not initialize application runtime state. + +## Stage 22: Composed consumer and application-owned flag reuse + +Update the maintained [composed consumer](../../integrations/ckprompt/examples/composed) +to install `ckprompt.Declarations`, explicit empty native namespace defaults +(enabling root defaults plus opt-in selectors), request preparation, extended +ConfigScope facets, and explicit `against-campaign`/`against-limit` comparison +bindings for their existing applicable scopes. Opt the application scope into +overrides and append its CLI records to ordinary ConfigKit overrides; native +duplicate/overlap errors remain native errors. Reuse the public +CLI flag collections on an application-owned command with its own input type, +showing canonical-only behavior there unless it deliberately installs aliases. +Do not introduce application-internal upstream convenience wrappers. + +Keep the PromptKit configuration scope's Overrides feature false in this +consumer. Released PromptKit Config/ConfigurationSources accept sources but do +not expose a ConfigKit Options.Overrides handoff. OD-11 is explicitly a loader +opt-in; it does not require simulating missing native engine support through +source rewriting. All native inspection/evidence features remain enabled. +Application-owned loaders can declare override support when their own acquisition +boundary actually accepts those records. Aggregate --set preflight must account +for this scope difference rather than dropping an unsupported scope silently. + +Keep successful-load caching application-owned and based on each side's complete +selection, overrides, and supplied domain inputs. A source-selection-only cache +must not incorrectly reuse a result for different overrides or comparison sides. +Use a small invocation-local cache-entry list and `reflect.DeepEqual` on owned +selections and relevant supplied domain fields, retaining those inputs with each +entry. Do not invent a universal hash scheme or cache across invocations. +Retain invocation state lifetime and do not cache failed loads as successes. + +Update request fixtures to use released resource/source contracts and explicit +file-input names. Include short inline input, preview, namespaces, and effective +provider parameters. Keep the native default bundle and existing domain commands +unless the selected target changes their usage; do not freeze catalog counts. +Retain the local fake LLM/probe setup and native finding-versus-operation outcome +semantics. No external credentials or model services in default examples/tests. + +Exercise representative config and prompt workflows, aliases and presence, +builder replacement, rendered preview, failure evidence, independent campaign +selections with overrides, ordinary domain dispatch, and help/version without +loading. Expected native evidence should derive from the selected engine/result; +do not reimplement native resolution tests. + +## Stage 23: Canonical contracts and obsolete infrastructure audit + +Review every path in the feature roadmap's +[output inventory](promptkit-v0.20.0.md#output-implementation-inventory). +Remove remaining handler-local format inputs, validators, encoders, legacy +prompt/profile mirrors, inherited comparison helpers, and old document framing. +Do not route raw help, diagnostics, shell protocols, or intentional caller raw +writes through report serialization. Remove direct integration YAML dependencies +only if no legitimate domain/fixture usage remains after `go mod tidy`. + +Complete GoDoc and [CLI reference](../cli.md) updates: universal formats, +representation and text-template behavior, native resources versus prepared +content, flags and scoped aliases, mode/capability availability, metadata and +failure evidence, independent selections/overrides, outcomes, cancellation, and +changed aggregate show/validation delivery. Remove obsolete migration sections +and legacy variants from current guidance as required by the clean-adoption +scope. Historical released notes and tags stay immutable. + +Update the [consumer guide](../consumers/guide.md), current internal inventory, +applicable README/development examples, dependency guidance, and testing policy's +obsolete native-YAML/order requirements. Refer to upstream for domain semantics +rather than copying a parallel specification. Align architecture-policy wording +that describes the former shared comparison selectors with the deliberate new +model; do not add unrelated policy changes or successor ADRs for these +presentation/selector choices. Use maintained examples as complete artifacts. + +Check scope against all roadmap completion criteria and deferred exclusions. +Perform focused documentation/link/fragment, whitespace, notices, and API-boundary +review. No new generic report framework, runtime wrappers, output-contract or +appended-message flags, persistence, live probes, discovery tracing, or secret +bootstrap work enters this sprint. + +## Stage 24: Core release candidate and publication handoff + +Inspect authoritative release state under the [release procedure](../release.md) +before selecting versions. Use the next unused core minor release (expected +v0.4.0 if still unused), a later ckconfig minor release (expected v0.4.0), and +update ckprompt v0.3.0 only if it remains unpublished. If that candidate has been +published, preserve it and select the next unused minor instead. These are +mechanical applications of the existing release policy, not new product decisions. +Record actual versions and source commits here as they become available. + +Prepare the core note, notices, and canonical contracts for the full shared +reporting/input API, with immutable footer links. Explain changed core contracts +concisely; no compatibility adapter or separate migration guide. Use the selected +release toolchain for root standalone tests and the normal candidate preparation. +Commit the reviewed candidate before any publication. + +Core publication is a maintainer handoff requiring separate explicit +authorization. This plan does not authorize push, tags, publication, or hosted +delivery. Without that authorization, finish all available workspace development +and candidate work, report the release dependency pending, and do not claim +final independent integration validation. Do not add polling, CI gates, or an +alternative fake module release to bypass this handoff. After authorized source +publication, proceed to Stage 25. Hosted delivery remains a separate operation. + +## Stage 25: Released core alignment and ckconfig candidate + +Pin the actual released core version supplying Stages 1–6 in both integrations. +Download ckconfig dependencies with GOWORK off and collect authentic sums; tidy +that module with the selected toolchain. Defer ckprompt standalone preparation +until Stage 26 supplies its released ckconfig requirement. Keep ConfigKit v1.1.0 +and PromptKit v0.20.0. +Verify core's module graph still has no optional integration dependency. + +Run ckconfig's standalone suite with released core and its maintained simple +consumer. Prepare and commit the ckconfig minor note, attribution, dependency +metadata, and applicable guidance. The note covers shared reporting, new CLI +modes/override opt-in, independent selections, and assertions directly, with the +module-specific immutable footer. Do not edit older released notes. + +Publication of this candidate is the second separately authorized maintainer +handoff. Until it occurs, ckprompt workspace results remain useful but do not +prove its independent dependency graph. Preserve that distinction in status. +After authorized ckconfig source publication, continue with its real released +version; hosted delivery remains separately tracked under the release procedure. + +## Stage 26: Final ckprompt alignment and end-to-end verification + +Pin released core and ckconfig versions providing the new APIs in ckprompt. +Download and tidy with GOWORK off; retain real sums. Update the unpublished +ckprompt candidate note (or fresh minor selected in Stage 24) with the final +capabilities and pinned dependencies, correct product/version title, and +module-specific immutable licensing footer. Record final module identities here. +No code may depend on the temporary workspace to hide old requirements. + +With Go 1.27.0 selected, run the independent suites from the repository root: + +```sh +GOWORK=off GOTOOLCHAIN=local go test ./... +(cd integrations/ckconfig && GOWORK=off GOTOOLCHAIN=local go test ./...) +(cd integrations/ckprompt && GOWORK=off GOTOOLCHAIN=local go test ./...) +``` + +Then validate the aligned workspace: + +```sh +GOTOOLCHAIN=local go test ./... +GOTOOLCHAIN=local go test ./integrations/ckconfig/... +GOTOOLCHAIN=local go test ./integrations/ckprompt/... +``` + +Confirm tidy produces no remaining module changes after preparation. Format +changed Go files and check public facade/backend import direction, documentation +links/fragments, attribution pins, intended files, and staged/unstaged whitespace. +Use graph tools first for code discovery and ordinary searches for literals, +configuration, and docs. Reuse successful checks for unchanged content; root +`./...` alone is not integration coverage. + +Run maintained consumers outside the workspace for these representative tasks, +using their final installed features and fixtures: + +- Automatic and explicit text/YAML/JSON application/version reports. +- Whole/aggregate/focused config display; metadata listing and root explanation. +- Independent campaign/config comparisons, --details, --check, and both override + sides, including zero/null/list values through standard syntax. +- Invalid-load sources and detailed validation retaining a nonzero operation + outcome, and all-scope validation producing one reached-scope report. +- Native prompt/profile/backend inspection; prepared preview with inline and file + inputs, aliases, namespaces, and provider parameters; requirements validation. +- A deterministic single smoke and `test all` with the configured local client, + retaining native findings and separate operation/presentation semantics. + +From `integrations/ckconfig/examples/simple`, representative final invocations +are: + +```sh +GOWORK=off GOTOOLCHAIN=local go run . config explain --list +GOWORK=off GOTOOLCHAIN=local go run . config show --path /greeting --format json +GOWORK=off GOTOOLCHAIN=local go run . config diff --config fixtures/before.yml --against-config fixtures/after.yml --details +GOWORK=off GOTOOLCHAIN=local go run . config validate --config fixtures/invalid.yml --details --format json +GOWORK=off GOTOOLCHAIN=local go run . config sources --config fixtures/invalid.yml +``` + +The invalid-load invocations intentionally fail while reporting available +evidence. From `integrations/ckprompt/examples/composed`, run: + +```sh +GOWORK=off GOTOOLCHAIN=local go run . config show --scope all --format json +GOWORK=off GOTOOLCHAIN=local go run . config validate --scope all --campaign spring --limit=0 --details +GOWORK=off GOTOOLCHAIN=local go run . config diff --scope app --campaign spring --limit=0 --against-campaign autumn --against-limit=0 --details +GOWORK=off GOTOOLCHAIN=local go run . config diff --scope app --set '/campaigns/spring/model="left"' --against-set '/campaigns/spring/model="right"' --details +GOWORK=off GOTOOLCHAIN=local go run . promptkit show prompt briefing --campaign spring --prompt-namespace field-notes +GOWORK=off GOTOOLCHAIN=local go run . promptkit show profile spring --campaign spring +GOWORK=off GOTOOLCHAIN=local go run . promptkit show backend local --campaign spring +GOWORK=off GOTOOLCHAIN=local go run . promptkit show prepared briefing --campaign spring --input topic=sprint --profile spring --extra-params '{"campaign":"preview"}' +GOWORK=off GOTOOLCHAIN=local go run . promptkit requirements validate briefing --campaign spring --input-file topic=fixtures/topic.txt +GOWORK=off GOTOOLCHAIN=local go run . promptkit test all --campaign spring --prompt briefing --profile spring +``` + +Record actual outcomes and final fixture identities. Use existing consumer tests +to assert native application statuses (including --check status 3); the `go run` +wrapper itself does not preserve a child program's nonzero status code. Existing +focused unit/integration tests own injected cancellation and writer failures; +do not build another exhaustive consumer harness. Default verification stays offline +after dependencies are prepared. + +Audit each completed stage against its behavior and the feature roadmap, remove +leftover migration scaffolding, review the complete diff, and commit the final +candidate. Keep feature/implementation status accurate and preserve deferred +items in future.md when retiring completed records under repository policy. +ckprompt publication and hosted delivery remain separate authorized operations; +preparing this candidate does not perform them. Do not mark the full dependency +alignment complete until both preceding release handoffs and independent suites +have actually succeeded. + +## Open Questions + +None requiring a product or scope decision. API and transition choices are +selected above. Core and ckconfig publication authorization is an explicit +external dependency in Stages 24–25, already required by OD-7 and release policy; +it is not implicit authority granted by an implementation prompt. Exact unused +versions and release commits are established from authoritative state at those +handoffs, without weakening independent-module completion criteria. diff --git a/docs/roadmap/promptkit-v0.20.0.md b/docs/roadmap/promptkit-v0.20.0.md index a9ed368..ed5818f 100644 --- a/docs/roadmap/promptkit-v0.20.0.md +++ b/docs/roadmap/promptkit-v0.20.0.md @@ -1,10 +1,10 @@ # Shared report output, PromptKit v0.20.0 adoption, and ConfigKit operator CLI -Status: agreed implementation roadmap; implementation has not started. The -numbered decisions and final review clarifications are settled. Exact helper -signatures and layouts of integration-owned report projections remain -implementation choices; native resource report fields follow upstream. -Practical beta feedback will guide presentation refinements. +Status: agreed feature roadmap; implementation has not started. The numbered +decisions and final review clarifications are settled. The +[implementation plan](implementation.md) owns staged execution and concrete API +and transition choices; native resource report fields follow upstream. Practical +beta feedback will guide presentation refinements. Reading guide: the core prerequisite sections own shared mechanics; resource inspection and OD-1 through OD-11 own integration behavior. The overview links @@ -17,8 +17,10 @@ The [architecture ownership table](../policy/architecture.md#ownership-boundarie and [Go types and facilities policy](../policy/architecture.md#go-types-and-facilities) now own the agreed principles. Core supplies CLI mechanics and output formatting; applications and integrations choose report content, and upstream libraries own -domain semantics. This roadmap owns the implementation work and its specific -input, serialization, and presentation contracts. +domain semantics. This roadmap owns the desired target and its specific input, +serialization, and presentation contracts. The +[implementation plan](implementation.md) owns the steps from the current +baseline to that target. ## Purpose and ownership @@ -338,8 +340,8 @@ Markdown is not selected for this adoption. New core formats must work with existing commands without handler refactoring or per-command encoder registration. This supersedes both the optional YAML-helper proposal and earlier YAML-only report restrictions. Keep implementation -proportionate; exact public names, signatures, and internal representation remain -design work. +proportionate; the [implementation plan](implementation.md) selects public +handoffs and the representation approach. ### Agreed universal and automatic format selection @@ -572,9 +574,9 @@ prescribe report framing or mapping order. ### Remaining core reporting implementation details -Exact public signatures, reusable template preparation and helper functions, -flag integration/collision handling, and replacement of existing format plumbing -are implementation design tasks. The decisions above do not reopen content +The [implementation plan](implementation.md) selects public signatures, reusable +template preparation, flag integration/collision handling, and replacement of +existing format plumbing. The decisions above do not reopen content selection, JSON conventions for core serialization, original Go values for text templates, no-template text rendering, universal formats, automatic selection, safe YAML input conversion, aggregate configuration presentation, or joint @@ -658,69 +660,13 @@ integration; core does not gain a generic streaming-document framework. Beta feedback should guide exact layouts; avoid tests that freeze incidental spacing or field order. -## Work sequence +## Implementation plan -1. **Finalize the core handoffs.** Use the accepted flags, report - content, aggregate presentation, and automatic format policy as the MVP target. - Specify the report/writer APIs, CLI JSON parsing boundary, ordered typed input - composition, and internal conversion under the agreed representation contract. - Design the acquisition/binding wiring and flag collision handling; use - concrete examples to review report details during implementation rather than - reopening accepted scope. -2. **Implement the core prerequisites.** Deliver the agreed automatic format - policy, universal `--format` selection, format-independent Reporter - operation, writer-based API, and shared representation/encoding machinery. - Deliver YAML encoding, text printing/templates, JSON encoding, CLI JSON parsing, - and ordered typed input support in the core feature release. Exercise the - public API with core reporting and an application-owned command example, and - consolidate suitable existing integration reports onto it. Cover the selected - contracts and update their canonical documentation with the implementation. - Complete this prerequisite before building the downstream additions; use the - aligned workspace until the core release is available under OD-7. -3. **Adopt v0.20.0.** Update `integrations/ckprompt/go.mod` and `go.sum`, then - [module attribution](../../integrations/ckprompt/docs/oss/attribution.md) - against the released notices and source commit. Update the unpublished - candidate note and canonical dependency guidance. Replace the prompt/profile - report adapters with native v0.20.0 report handoffs, including their optional - fields and captured messages. Implement the independent backend-inspection - capability, command, and `FromEngine` wiring under - [resource inspection](#resource-inspection). Keep domain semantics upstream-owned; - no compatibility layer or consumer migration documentation is part of this - work. No core Go-minimum increase follows from this adoption. -4. **Implement request inspection and selection.** Add preview, literal-text - input and renamed file-input flags, applicable override flags, - provider-parameter input, and namespace selectors. Implement - public `ckprompt` execution-flag collections using core bindings and the new - ordered input capability, then reuse them in the standard commands. Generate - scoped convenience aliases and provide a collection for installing the - commands and routing declarations. - Reuse the standard suite's lifecycle and application-owned acquisition and - request-builder boundaries. Render suitable new reports through the shared - core API. -5. **Implement shared configuration inspection.** Add discovery and metadata - within `config explain`, structured diagnostics via `config validate --details`, - detailed diff presentation, and source evidence on failure in `ckconfig`. - Retain the six-command suite and wire native PromptKit facets through - `ConfigScope`. Add focused effective display, source selection, and bounded - metadata/diagnostic filters using those evidence capabilities. Extend typed - comparison selection and add the agreed assertion outcome. Implement explicit - override acquisition and comparison-side wiring under OD-11 as a separate - reviewable unit. Use the shared core API under the initial report - implementation approach. Keep boundary coverage with each change. -6. **Update operator and consumer documentation.** The CLI reference owns - syntax, report schemas, availability, and outcomes; GoDoc owns callback and - value contracts. Keep architectural ownership references aligned, and replace - the testing policy's old native-YAML/document-order guidance when the new report - behavior lands. Extend maintained simple/composed examples to demonstrate - the new CLI tasks using local fixtures, without adding application-internal - execution helpers. Describe the delivered capabilities and selected behavior - directly in module notes. -7. **Align module dependencies and validate.** Prepare the core release needed - by both integrations and the `ckconfig` release needed by `ckprompt`. Align - requirements/checksums and complete the validation below. OD-7 addresses - interim workspace development and dependency order. - Publication and hosted delivery remain separate actions under the - [release procedure](../release.md). +The [staged implementation plan](implementation.md) owns ordered steps, selected +API designs, affected code, focused verification, module release handoffs, and +final independent-module validation. This feature roadmap owns target behavior, +operator intent, and the decisions below. Implementation status is recorded in +the plan; the checklist here defines the target acceptance boundaries. ## Validation and completion checklist @@ -844,22 +790,11 @@ rather than prescribing one test per line or exact cosmetic snapshots. - [ ] Final independent-module and aligned-workspace suites pass with dependency identities recorded. Deferred features remain outside this adoption. -With the documented Go 1.27.0 toolchain selected, run -`GOWORK=off GOTOOLCHAIN=local go test ./...` independently in the root, -`integrations/ckconfig`, and `integrations/ckprompt`. Prepare dependencies before -offline execution as described in the [release procedure](../release.md). -Then validate the aligned workspace from the root with: - -```sh -GOTOOLCHAIN=local go test ./... -GOTOOLCHAIN=local go test ./integrations/ckconfig/... -GOTOOLCHAIN=local go test ./integrations/ckprompt/... -``` - -Use the [development guide](../development.md) for toolchain/workspace setup and -documentation checks. Reuse successful checks for unchanged content; these -adoption checks do not add permanent publication gates. A dependency-only build -is insufficient evidence for the completed CLI and reporting work. +The [implementation plan](implementation.md) owns the concrete verification +sequence and commands. The [development guide](../development.md) and +[release procedure](../release.md) own routine toolchain, workspace, and release +setup. These adoption checks do not add permanent publication gates; a +dependency-only build does not establish the delivered CLI and reporting target. ## Deferred work @@ -884,10 +819,10 @@ performs application startup effects. All numbered decisions are resolved for this adoption and retain their numbers for reference. OD numbers are local to this roadmap, not the retired adoption documents. The core prerequisite sections above own shared reporting and input -mechanics. Exact API signatures, typed binding composition, loader wiring, flag -collision handling, and layouts of integration-owned report projections remain -implementation choices, not unresolved scope. Resource reports use the native -upstream fields selected under [resource inspection](#resource-inspection). +mechanics. Concrete API signatures, typed binding composition, loader wiring, flag +collision handling, and integration-owned projections are selected in the +[implementation plan](implementation.md), not unresolved product scope. Resource +reports use the native upstream fields selected under [resource inspection](#resource-inspection). ### OD-1: Preview command and report presentation