Plan the CommandKit adoption sprint

This commit is contained in:
2026-11-20 01:07:52 +00:00
parent bcb1a76e34
commit 99b0ebfc03
2 changed files with 618 additions and 137 deletions

View File

@@ -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