diff --git a/docs/roadmap/commandkit-adoption.md b/docs/roadmap/commandkit-adoption.md new file mode 100644 index 0000000..392f6a0 --- /dev/null +++ b/docs/roadmap/commandkit-adoption.md @@ -0,0 +1,349 @@ +# CommandKit Adoption + +## 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 +record. The [Narratio proposal](narratio-feature-request.md) supplies consumer +acceptance scenarios for requirements discovery. + +Make Scriptorium a CommandKit-native executable interface over PromptKit, +including ckconfig and ckprompt. Most subprocess consumers should be able to +select a stored prompt and consume its resulting artifact directly. Operators +and consumers needing inspection or metadata should use native upstream +interfaces and reports. + +This is a full CLI cutover. Existing command names, flag spellings, parsing, +report shapes, and exit conventions are not compatibility constraints. Release +migration guidance replaces a compatibility layer. Implementation may proceed +in reviewable increments; this does not require shipping both interfaces. + +## Current Baseline And Upstream References + +Reviewed Scriptorium baseline: `5f32a4f2adb2d382a6cfce3a787ada4576be7705`. +The module uses Go 1.27.0, PromptKit v0.23.3, and ConfigKit v1.2.1. CommandKit +is not yet a dependency. + +| Current implementation | Migration work | +| --- | --- | +| `internal/adapter/cli` dispatches and parses commands, resolves configuration, builds engines and requests, writes diagnostics, and returns integer statuses. | Replace dispatch and shared CLI mechanics with CommandKit; retain application loading, request mapping, and effects through its extension points. | +| `run` uses flag-based prompt selection and writes generated content; `--execution-report` writes an observer-derived Scriptorium report. | Adopt positional prompt selection, native request flags, and native result reporting. | +| `render`, `inspect prompt`, and `inspect profile` use custom presentation in `internal/format`. | Replace with native ckprompt operations and remove unused presentation code. | +| `config` and `inspect configuration` separately expose application and framework configuration. | Install one ckconfig family with `app` and `promptkit` scopes, including comparison. | +| `internal/config` owns application schema, discovery, defaults, and conversion through ConfigKit. | Adapt its loader and explicit overrides to standard selections and scope capabilities. | +| `serve` constructs a restricted HTTP artifact reader and one shared PromptKit engine. | Register it as an application command and preserve existing HTTP behavior. | +| `internal/report` also supplies HTTP's optional execution report. | Remove its superseded CLI use; retain functionality still used by HTTP. | + +The [current CLI](../cli.md), [configuration contract](../config.md), +[adapter internals](../internal/adapters.md), and +[subprocess contract](../integrations/subprocess.md) describe the starting +behavior, not a compatibility checklist for this migration. + +The reviewed upstream combination is CommandKit v0.7.0, ckconfig v0.9.0, +and ckprompt v0.10.0, documented at revision +`d330d7637f2e7507eca931a899397222c82bc892`: + +- [Consumer guide][upstream-guide]: composition, loading, reusable bindings, + 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 +[architecture policy](../policy/architecture.md). + +## Target End State + +### Responsibilities And Scope + +CommandKit owns command declarations, dispatch, common parsing, help, reporting, +and outcome mechanics. ckconfig and ckprompt supply their standard families. +ConfigKit owns configuration processing; PromptKit owns definition parsing, +preparation, execution, validation, and domain results. Scriptorium owns +application configuration and source selection, application commands, process +lifecycle, and artifact delivery. + +This preserves Scriptorium's request-independent execution model and support +for valid definitions under [ADR 0004](../adr/0004-definition-boundary.md). +It adds no workflow, conversation, archive, or resume system. HTTP design review +remains separate work before v1.0; migrating its startup command does not +redesign the HTTP API or its execution-report representation. + +Use shared upstream capabilities where available. A concrete missing shared +capability should prompt an upstream discussion before a local substitute. +Application-specific loading and effects remain ordinary application work. + +### Command Surface + +| Surface | Target | +| --- | --- | +| Generation | Application command `run PROMPT_ID`, with a required positional prompt ID and no duplicate prompt flag. | +| HTTP service | Application command `serve`. | +| Configuration | Native `config` family with `app` and `promptkit` scopes: scope discovery, validation, effective values, sources, explanations, and diff. | +| Resource inspection | Native prompt, profile, backend, namespace, and collection inventories and applicable named inspection. | +| Dependency discovery | Native `promptkit requirements show PROMPT_ID`. | +| Concrete validation | Native `promptkit requirements validate` capability. | +| Prepared preview | Native `promptkit show prepared PROMPT_ID`, replacing `render`. | +| Provider diagnostics | Native smoke-test commands, invoked explicitly. | +| Executable support | Native help, version, reporting modes, outcomes, and shell completion. | + +Install application commands outside the reserved standard families. Enable +the native convenience aliases consistently. Prefer shorter spellings such as +`--profile`, `--input-file`, `--input-text`, and `--var` in examples and guidance +where applicable and unambiguous; canonical `--llm-*` spellings remain available. +Aliases retain upstream semantics: `--input` supplies literal text, and file +references use `--input-file`. + +Reuse applicable ckprompt resource, input, and execution bindings for `run`. +Preserve explicit-value presence, including zero and empty values, and native +repeated mapping semantics. Do not carry forward comma splitting or obsolete +aliases merely because the old parser accepted them. Keep application source +selectors, server settings, output destinations, and whole-operation deadlines +distinct from framework request controls. + +Completion initially uses native command, flag, static-value, and path +completion, with suitable application hints. Dynamic installed-resource +completion is not required. Smoke tests are explicit operator operations; +their inclusion does not make provider access a startup or release prerequisite. +Preserve native diagnostic findings, including successful invocations whose +reports describe unsupported or unsuccessful checks. + +### Configuration, Collections, And Request Context + +Expose application configuration through `app` and captured framework +configuration through `promptkit`. Collections are resources within the +framework configuration, not separate configuration scopes. Application-only +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. + +Enable temporary configuration overrides where the loader supports them, +passing native override records into loading. The reviewed PromptKit scope +does not support these overrides; do not emulate them locally. Configuration +comparison must support independent selections for both sides in both scopes, +including corresponding application selectors where needed. + +Keep the established collection-discovery model: ConfigKit imports discover +`collection.yml` and `collection.yaml` entry points; each independently +maintained collection declares its namespace and imports its own definitions +through relative references. Retain the +[discovery example](../../examples/config.discovery.yml) and representative +multi-definition collection documentation. No Git update manager or custom +collection traversal is part of this migration. + +Use native prompt, profile, and backend namespace selectors independently on +applicable commands. Short caller-supplied IDs use their selected namespace; +qualified IDs remain exact. Selection does not rewrite stored references. +Retain upstream inventory filters and defaults, including `--all-namespaces`. +Do not add a configurable default namespace in this migration. + +Share applicable configuration selection, engine loading, and request mapping +across execution, preview, validation, and discovery. Preserve each operation's +upstream lifecycle: discovery can work before artifacts exist; preparation +loads and renders without generation. This is consistency of selection and +mapping, not a promise that separate invocations see an immutable snapshot. + +### Generation, Reports, And Process Outcomes + +Use a CommandKit `Report` whose value is PromptKit's native `RunResult` and whose +text template emits only the resulting artifact content. The template should +emit artifact bytes without presentation decoration. Default/text serves raw +artifact consumers; JSON and YAML expose the full native result. The native +structured serialization, including its representation of artifact bytes, +remains upstream-owned. There is no Scriptorium result envelope. + +| Selection | Behavior | +| --- | --- | +| No destination flag | Main result goes to stdout using the selected format. | +| `--output PATH` | Main result goes to that file, without duplicate stdout output. | +| `--format text` or default | Main result contains only the artifact. | +| `--format json` or `--format yaml` | Main result contains the native result and metadata. | +| `--report PATH` | Additionally write the native result as JSON through CommandKit's renderer, independently of the main format and destination. | + +Filename extensions do not select formats. The separate report includes the +native result's content as well as metadata; it replaces the CLI's old +observer-derived metadata projection. A caller wanting an artifact file plus +metadata can select separate output and report paths. The caller manages paths +and retention; there is no automatic reporting directory or report collection. + +Native result reporting is available when PromptKit returns a result. +Operational errors return nonzero status and native failure diagnostics, without +synthesizing replacement results. Preserve PromptKit's distinction between a +completed content check reporting `ValidationFailed` and an operational failure +to perform the check. Neither extra content judgments nor a structured JSON +invocation-error envelope is part of this migration. + +Adopt CommandKit's quiet and verbosity semantics, including rendering and +presentation failures. Console results use the invocation reporter; diagnostics +use its diagnostic channel. Explicit `--output` and `--report` writes are +application effects rendered through the writer API and still occur in quiet +mode. Quiet does not cancel generation; without requested files it suppresses +ordinary result output while failure explanations remain visible. Move any +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`. +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. + +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. + +### Preview And Consumer Inspection + +Remove `render`, its compatibility aliases, `defaults.render_format`, and +unused prepared-output formatters. Native prepared preview uses its upstream +report, default/text YAML presentation, standard formats, request flags, +diagnostics, and outcomes. It does not call a model. Consumers save preview +output through stdout capture or redirection; generation's `--output` does not +extend the native inspection families. + +Adopt native inspection reports, including captured prompt messages and rendered +prepared content, without recreating old summary projections. Native schemas +and adopted upstream versions govern structured output; this migration adds no +separate schema-version wrapper or compatibility guarantee. + +Implement the [Narratio acceptance scenarios](narratio-feature-request.md#consumer-acceptance-scenarios). +Requirements discovery exposes native classification, completeness, and issue +codes. Complete discovery is distinct from satisfied bindings and execution +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 + +### 1. Establish Dependencies And Command Composition + +- 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. + +### 2. Adapt Loading And Install Native Inspection + +- Adapt `internal/config` loading, explicit overrides, diagnostics, and + application selection to ckconfig. Inspect the native overlay API mapping + and update examples to its selected syntax; do not assume renaming the old + flag alone completes adoption. +- Supply `app` and PromptKit configuration scopes 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 [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. +- 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. + +[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