Plan the CommandKit adoption sprint
This commit is contained in:
@@ -3,11 +3,13 @@
|
||||
## Status And Intent
|
||||
|
||||
Initial roadmap, prepared 2026-11-19. The product direction is agreed;
|
||||
implementation has not begun. This document owns the target and implementation
|
||||
sequence, incorporating the decisions in the
|
||||
[migration notepad](commandkit-notepad.md). The notepad remains the discussion
|
||||
implementation has not begun. This document owns the target and product intent,
|
||||
incorporating the decisions in the [migration notepad](commandkit-notepad.md).
|
||||
The notepad remains the discussion
|
||||
record. The [Narratio proposal](narratio-feature-request.md) supplies consumer
|
||||
acceptance scenarios for requirements discovery.
|
||||
acceptance scenarios for requirements discovery. The
|
||||
[implementation plan](implementation.md) owns the ordered stages and concrete
|
||||
adapter choices.
|
||||
|
||||
[ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md) records
|
||||
the native-interface adoption and ownership boundaries, complementing ADRs 0004
|
||||
@@ -53,13 +55,19 @@ and ckprompt v0.10.0, documented at revision
|
||||
reporting, and outcomes.
|
||||
- [CLI reference][upstream-cli]: native command grammar and observable behavior.
|
||||
|
||||
Confirm a released dependency combination during implementation. The reviewed
|
||||
ckprompt release declares PromptKit v0.23.2 and ConfigKit v1.2.1; retain
|
||||
Scriptorium's adopted v0.23.3 fixes and verify the combined module graph.
|
||||
Do not infer compatibility merely from successful dependency resolution.
|
||||
Use supported public APIs and released dependencies under the existing
|
||||
The selected released combination retains Scriptorium's adopted PromptKit
|
||||
v0.23.3 fixes and ConfigKit v1.2.1. The reviewed ckprompt release's PromptKit
|
||||
v0.23.2 minimum does not require a downgrade. Supported public APIs and released
|
||||
dependencies remain subject to the existing
|
||||
[architecture policy](../policy/architecture.md).
|
||||
|
||||
One approved upstream addition is needed: a released selected-format accessor.
|
||||
CommandKit v0.7.0 provides a writer-level renderer but no public access to the
|
||||
invocation's selected format. The accessor enables formatted application-owned
|
||||
output files, including in quiet mode, without duplicating reporting-flag
|
||||
parsing. The implementation plan tracks adoption of its released API; the
|
||||
agreed file-output contract remains the target.
|
||||
|
||||
## Target End State
|
||||
|
||||
### Responsibilities And Scope
|
||||
@@ -160,9 +168,10 @@ inspection must work without constructing a PromptKit engine.
|
||||
`--config` selects Scriptorium application configuration on every applicable
|
||||
command, including framework inspection. That configuration selects framework
|
||||
sources. Adopt native `--overlay` selection and upstream selection presence
|
||||
semantics. Map selections through the application's ConfigKit loader rather
|
||||
than retaining the old flag parser as a compatibility layer. Preserve useful
|
||||
application source and server controls through appropriate selectors.
|
||||
semantics. For ConfigKit v1.2.1 the supplied value selects an overlay by name,
|
||||
not an arbitrary file path. Map selections through the application's ConfigKit
|
||||
loader rather than retaining the old flag parser as a compatibility layer.
|
||||
Preserve useful application source and server controls through appropriate selectors.
|
||||
|
||||
Enable temporary configuration overrides where the loader supports them,
|
||||
passing native override records into loading. The reviewed PromptKit scope
|
||||
@@ -230,28 +239,24 @@ retained generation summary into an appropriate native message category.
|
||||
|
||||
Map typed upstream failures and configuration diagnostics into native outcomes,
|
||||
without parsing error text. Standard statuses remain upstream-owned. Use an
|
||||
application domain outcome for completed validation failure; status `4` is the
|
||||
proposed mapping, avoiding usage status `2` and diff-check status `3`.
|
||||
application domain outcome for completed validation failure, distinct from
|
||||
usage and diff-check outcomes. The implementation plan specifies the mapping.
|
||||
Delivery failures must produce a nonzero outcome and explanation, preserving
|
||||
native presentation-failure behavior where applicable, including an already
|
||||
nonzero domain outcome. Requested file errors must not disappear merely because
|
||||
they occur outside the invocation reporter.
|
||||
|
||||
Use ordinary file operations. During implementation, settle and document
|
||||
overwrite behavior, missing parent directories, destination collisions, and
|
||||
delivery ordering. The recommended starting point is the existing simple file
|
||||
behavior: replace files without creating parents, reject output/report
|
||||
destinations known to name the same file before execution, attempt the main
|
||||
output followed by the report, and attempt the report even if main delivery
|
||||
fails. This adds no rollback, transactional delivery, or stronger filesystem
|
||||
protection. Already delivered output may remain after failure.
|
||||
Use ordinary file operations: replace files without creating parents, reject
|
||||
output/report destinations known to name the same file before execution,
|
||||
attempt the main output followed by the report, and attempt the report even if
|
||||
main delivery fails. This adds no rollback, transactional delivery, or stronger
|
||||
filesystem protection. Already delivered output may remain after failure.
|
||||
|
||||
Wire signal cancellation through the invocation context. Keep the application
|
||||
whole-operation budget separate from the native per-attempt timeout binding.
|
||||
Retaining `--run-timeout` with Go duration values is a suitable application
|
||||
choice; map it to PromptKit's `OperationTimeout` and preserve upstream zero,
|
||||
negative-value, and timeout behavior. Finalize that mapping with command help
|
||||
and outcome tests rather than adding a second timeout policy.
|
||||
Use `--run-timeout` with Go duration values mapped to PromptKit's
|
||||
`OperationTimeout`, preserving upstream zero, negative-value, and timeout
|
||||
behavior without a second timeout policy.
|
||||
|
||||
### Preview And Consumer Inspection
|
||||
|
||||
@@ -274,122 +279,43 @@ readiness; partial discovery can succeed with status zero. Narratio owns its
|
||||
pipeline, binding graph, and policy for incomplete findings. Preserve native
|
||||
metadata without inventing prompt versions, variable defaults, or input schemas.
|
||||
|
||||
## Implementation Sequence
|
||||
## Acceptance And Scope Boundaries
|
||||
|
||||
### 1. Establish Dependencies And Command Composition
|
||||
The target is met when Scriptorium exposes the native command surface and
|
||||
application behavior above, superseded CLI machinery is retired, and maintained
|
||||
documentation and examples describe the shipped interface. In particular:
|
||||
|
||||
- Confirm released module versions and public integration APIs; update modules
|
||||
and applicable [attribution](../oss/attribution.md) when dependencies land.
|
||||
- Build the CommandKit application with identity/version, standard families,
|
||||
application commands, aliases, and completion declarations. Keep help and
|
||||
declaration construction independent of runtime configuration loading.
|
||||
- Inventory existing CLI flags against reusable bindings and application
|
||||
selectors. Resolve spelling collisions in favor of native meanings, using
|
||||
canonical spellings where shorter aliases would be ambiguous.
|
||||
- Specify the concrete outcome and deadline mappings described above. Confirm
|
||||
public namespace binding support for the application command; raise any
|
||||
genuine missing shared adapter capability upstream.
|
||||
- Configuration callbacks, runtime consumers, and native inspection agree on
|
||||
ConfigKit's completed values and evidence. Application-only inspection needs
|
||||
no PromptKit engine, and comparison sides retain independent selections.
|
||||
- Applicable selection and request context remain consistent across execution,
|
||||
preparation, discovery, and inspection of multiple independently maintained
|
||||
collections. Their upstream lifecycle differences remain visible.
|
||||
- Generation defaults to the artifact alone; structured output and separate
|
||||
reports expose the native result. Requested files remain independent of
|
||||
console quiet mode, with useful failure outcomes and nontransactional delivery.
|
||||
- Narratio's linked acceptance scenarios are supported, including useful partial
|
||||
discovery and discovery before generated artifacts exist.
|
||||
- Native help, aliases, completion, and explicit smoke testing are available.
|
||||
Including smoke testing adds no provider access prerequisite to startup or
|
||||
release validation.
|
||||
- Server startup reaches the existing HTTP adapter with its transport,
|
||||
restricted-reading, execution-report, and shared-capacity behavior intact.
|
||||
- Canonical contracts, examples, dependency attribution, and migration guidance
|
||||
reflect the cutover. The CLI migration includes positional prompt selection,
|
||||
command replacements, literal versus file inputs, repeated mappings, overlay
|
||||
selection, native endpoint/timeout controls, content-bearing reports, report
|
||||
availability, quiet behavior, and changed exit statuses.
|
||||
|
||||
### 2. Adapt Loading And Install Native Inspection
|
||||
|
||||
- Adapt `internal/config` loading, explicit overrides, diagnostics, and
|
||||
application selection to ckconfig while preserving the
|
||||
[configuration authority boundary](#configuration-authority-and-native-inspection).
|
||||
Keep application resolution callbacks inside ConfigKit's lifecycle and
|
||||
return its completed result to the native adapter. Inspect the native overlay
|
||||
API mapping and update examples to its selected syntax; do not assume renaming
|
||||
the old flag alone completes adoption.
|
||||
- Install the native application and PromptKit configuration adapters with
|
||||
native comparisons and independent comparison inputs. Avoid accidentally
|
||||
sharing one side's selected values or cached engine with the other.
|
||||
- Compose ckprompt inventories, named inspection, requirements discovery,
|
||||
validation, preparation, and smoke testing through public adapters.
|
||||
- Share request construction where applicable, starting from upstream seed
|
||||
values and preserving explicitly supplied values. Keep application-only
|
||||
inspection and early discovery free of execution-only prerequisites.
|
||||
|
||||
### 3. Cut Over Execution And Server Startup
|
||||
|
||||
- Bind `run PROMPT_ID` through reusable request flags and application selectors;
|
||||
invoke PromptKit using the mapped request and cancellation context.
|
||||
- Implement native result reporting, artifact text output, explicit output and
|
||||
report destinations, and selected delivery/outcome handling.
|
||||
- Register `serve` with CommandKit and route its startup diagnostics through
|
||||
native reporting. Retain HTTP limits, restricted artifact reading, shared
|
||||
engine/backend admission state, DTOs, and optional HTTP execution reporting.
|
||||
- Complete the full command cutover without exposing legacy compatibility
|
||||
aliases or alternate old report formats.
|
||||
|
||||
### 4. Remove Superseded Code And Update Consumer Guidance
|
||||
|
||||
- Remove obsolete CLI parsing, dispatch, custom config/source projections,
|
||||
definition and prepared presentation, and CLI observer-report wiring.
|
||||
Delete packages only after checking remaining consumers; HTTP still uses
|
||||
`internal/report` at the baseline.
|
||||
- Replace tests tied to deliberately removed behavior with protection for the
|
||||
selected adapter contracts. Retain relevant HTTP and dependency-boundary
|
||||
coverage; avoid copying upstream parser or formatter test matrices.
|
||||
- Update canonical CLI, configuration, subprocess, operations, and internal
|
||||
documentation alongside the behavior they own. Update architecture and test
|
||||
ownership descriptions to reflect the new library boundaries. Preserve
|
||||
accepted ADR history under the documentation policy.
|
||||
- Update README workflows and maintained examples, including the existing
|
||||
render script and collection workflows, with preferred native aliases.
|
||||
- Prepare release migration guidance covering positional prompt selection,
|
||||
command replacements, literal versus file inputs, repeated mappings,
|
||||
overlay selection, endpoint/timeout names, output/report formats and
|
||||
availability, quiet behavior, and exit-status changes. Explain native
|
||||
content-bearing reports and changed inspection presentation.
|
||||
The [implementation plan](implementation.md) owns task sequencing, concrete
|
||||
adapter mappings, verification steps, and sprint status. There are no unresolved
|
||||
product decisions; the approved upstream selected-format accessor remains an
|
||||
external release prerequisite.
|
||||
|
||||
The [release policy](../policy/release.md#versioning-and-compatibility) governs
|
||||
the eventual breaking release version. Preparing this roadmap does not select
|
||||
or publish a release.
|
||||
|
||||
## Verification And Completion
|
||||
|
||||
Verify the application integration with real library collaborators and
|
||||
deterministic substitutes at provider boundaries. Prioritize these observable
|
||||
scenarios rather than exhaustive upstream behavior matrices:
|
||||
|
||||
- Positional generation and preferred aliases preserve native input mapping,
|
||||
explicit zero/empty values, and independent namespace selection.
|
||||
- Multiple imported collections work across execution, preview, discovery,
|
||||
and inspection with consistent applicable selections; app-only inspection
|
||||
works without an engine. Comparison sides remain independent.
|
||||
- Application callback changes appear consistently in ConfigKit's completed
|
||||
values and inspection evidence. Runtime conversion preserves those values,
|
||||
and standard inspection exposes the acquired result through native adapters,
|
||||
including native explanation and path behavior. Reuse existing boundary
|
||||
tests where they already provide this coverage.
|
||||
- Default output is the artifact; structured output and separate reports use
|
||||
the native result representation. Format and destination are independent;
|
||||
quiet suppresses console results while requested files are still written.
|
||||
- Completed invalid content, operational failures without results, cancellation,
|
||||
and output/report failures produce the selected statuses and useful native
|
||||
diagnostics. Representative partial delivery does not report success.
|
||||
- Preview and discovery respect their distinct upstream lifecycles. Narratio's
|
||||
linked scenarios exercise complete, incomplete, and failed discovery.
|
||||
- Help, aliases, completion, and smoke-test wiring are reachable through the
|
||||
assembled CLI. Smoke tests use controlled providers in automated checks;
|
||||
live provider tests remain explicitly opt-in.
|
||||
- Server startup still reaches the existing HTTP adapter, whose established
|
||||
transport, reporting, restricted-reading, and shared-capacity behavior retains
|
||||
appropriate coverage.
|
||||
|
||||
Run the repository's [baseline validation](../development.md#baseline-validation)
|
||||
for implementation changes: `go test ./...`, `go test -race ./...`,
|
||||
`go vet ./...`, and `go build ./cmd/scriptorium`, plus formatting, diff,
|
||||
affected example, and documentation-link checks. These checks validate the
|
||||
implementation when it lands; this documentation-only roadmap does not claim
|
||||
the target interface has been built or tested.
|
||||
|
||||
Migration is complete when the native command surface and application behavior
|
||||
above are integrated and verified, superseded CLI machinery has been retired,
|
||||
and maintained documentation and examples describe the shipped interface.
|
||||
Use the roadmap for implementation status until those changes land. No
|
||||
significant product decision remains open; dependency confirmation and the
|
||||
ordinary adapter details identified above are implementation work, not reasons
|
||||
to reopen the agreed cutover.
|
||||
the eventual breaking release version. This migration does not itself select
|
||||
or publish a release, introduce a compatibility layer, or settle the separate
|
||||
pre-v1.0 HTTP design review.
|
||||
|
||||
[upstream-guide]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/consumers/guide.md
|
||||
[upstream-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md
|
||||
|
||||
Reference in New Issue
Block a user