Plan shared reporting and PromptKit adoption
This commit is contained in:
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user