diff --git a/docs/roadmap/commandkit-notepad.md b/docs/roadmap/commandkit-notepad.md index bd1abca..4f679ae 100644 --- a/docs/roadmap/commandkit-notepad.md +++ b/docs/roadmap/commandkit-notepad.md @@ -1,9 +1,9 @@ # CommandKit migration notepad -Status: discussion in progress. This is the working record for agreeing on -Scriptorium's CommandKit migration before preparing a feature roadmap. It -captures direction, open decisions, and discussion notes; implementation scope -and sequencing will follow once the relevant decisions are settled. +Status: design direction agreed; ready for feature-roadmap preparation. This +working record captures the decisions for Scriptorium's CommandKit migration. +The remaining integration details below belong in the roadmap alongside +implementation sequencing and validation. ## Product context @@ -34,7 +34,7 @@ Backward compatibility with existing CLI conventions is an explicit non-goal. Legacy command names, flag spellings, parsing rules, report shapes, and exit semantics do not constrain the new interface. Do not add compatibility wrappers, legacy aliases, or duplicate inspection implementations solely to preserve the -old CLI. Upstream convenience aliases can be considered on their own merits. +old CLI. Adopt upstream convenience aliases as described below. Provide migration guidance in release documentation so consumers can update their invocations and output handling. Guidance replaces a compatibility layer; @@ -234,6 +234,34 @@ rendered content. Adopt these native reports without rebuilding Scriptorium's previous summary projections, and explain the changed presentation in migration guidance. Requirements discovery retains its distinct upstream content boundary. +### Application commands and standard request flags + +Decision recorded 2026-11-19: use `run PROMPT_ID` for generation, with the prompt +as a required positional operand and no duplicate prompt-selection flag. Keep +`serve` as the application command for the HTTP service. Both are CommandKit +commands owned by Scriptorium, outside the reserved `config` and `promptkit` +families. The CLI migration does not redesign the HTTP API. + +Reuse ckprompt's applicable resource, input, and execution flag bindings. +Preserve native parsing, explicit-value presence, repeated mapping semantics, +and PromptKit's interpretation of request values. Keep application-specific +configuration/source selection, `--output`, `--report`, server options, and the +whole-operation deadline separate from framework request controls. + +Enable upstream convenience aliases consistently on applicable commands, +including `run`. Prefer their shorter spellings in user-facing documentation, +examples, migration guidance, and subprocess integration examples wherever they +are applicable and unambiguous. For example, prefer `--profile`, `--input-file`, +`--input-text`, and `--var` over their `--llm-*` equivalents. Canonical upstream +spellings remain available with identical semantics; the preference does not +remove or rename them. + +Aliases retain upstream meanings. In particular, `--input` supplies literal +text; file references use `--input-file`. Migration guidance must explain this +change along with endpoint and timeout naming and repeated mapping values. +Use the canonical spelling where a shorter alias would be ambiguous; do not +assign an upstream alias a different application-specific meaning. + ## Upstream baseline The initial review covered CommandKit **v0.7.0**, ckconfig **v0.9.0**, and @@ -257,13 +285,13 @@ The [upstream CLI reference][upstream-cli] owns the detailed conventions. The [subprocess contract](../integrations/subprocess.md) describe the starting point, not requirements to reproduce during migration. -## Open decisions +## Details for the feature roadmap -### 1 Generation integration details +The product and interface direction is settled. The following details need +concrete implementation choices in the roadmap, but do not require another +architectural discussion before drafting it. -The consumer requirements, native result reporting, output destinations, and -verbosity decisions above are settled. The remaining work is to specify their -integration in the feature roadmap. +### Outcomes and process lifecycle Map PromptKit's typed errors and reported outcomes into CommandKit conventions, preserving its distinction between a completed content check reporting @@ -274,35 +302,31 @@ using CommandKit's presentation-failure behavior where applicable. These are adapter mappings, not a new application validation policy. Signal cancellation and the whole-operation deadline remain application -responsibilities. Decide their mapping to the CommandKit invocation context -and PromptKit operation timeout, separately from the standard per-attempt -timeout flag. +responsibilities. Specify their mapping to the CommandKit invocation context +and PromptKit operation timeout, including the application deadline flag and +units, separately from the standard per-attempt timeout flag. -### 2 Application commands and standard request flags +### File delivery -Decide the final generation command operands and application-specific flags -around the reusable ckprompt request flag groups. Use their standard names, -value-presence behavior, and parsing semantics wherever applicable. +Specify ordinary path handling, overwriting, parent-directory behavior, +destination collisions, and delivery ordering for `--output` and `--report`. +Describe partial delivery consistently with native outcome reporting and the +agreed upstream result-availability boundary. -Migration guidance will need to explain changes such as separate literal-text -and file-input flags, endpoint and timeout naming, and repeated mapping values. -In particular, upstream's optional `--input` alias denotes literal text, while -Scriptorium's existing flag denotes a file. Choose any upstream convenience -aliases deliberately and document the new meanings; preserving old meanings -is not a design requirement. +### Adoption and verification -## Continuing the discussion +Confirm the released dependency combination, complete the application-specific +flag and loader mappings, and sequence replacement and removal of CLI code. +Define appropriate verification for the selected behavior and update canonical +documentation, examples, and release migration guidance as implementation lands. -Record discussion notes under the relevant open decision. When a choice is -settled, move its conclusion and rationale into the agreed direction with its -decision date, and remove superseded alternatives. Add new questions when a -concrete product need emerges. +## Preparing the roadmap -Once the command surface, consumer outputs and outcomes, loader and namespace -behavior, and any upstream gaps are settled, fold the decisions into a feature -roadmap. That roadmap will define implementation sequence, removal of replaced -CLI code, appropriate validation, and migration documentation. This notepad does -not prescribe implementation phases or treat the open proposals as commitments. +Fold the agreed decisions and remaining integration details into a feature +roadmap. Preserve the selected upstream conventions and explicit non-goals. +Record any concrete new issue found during preparation without reopening settled +product choices merely to preserve the old CLI. This notepad remains the +discussion record until its decisions have been incorporated into that roadmap. [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 diff --git a/docs/roadmap/narratio-feature-request.md b/docs/roadmap/narratio-feature-request.md index fffd847..3cbd381 100644 --- a/docs/roadmap/narratio-feature-request.md +++ b/docs/roadmap/narratio-feature-request.md @@ -28,7 +28,7 @@ The [upstream CLI contract][requirements-cli] owns syntax and report details. Use the same application configuration and framework source selection as execution, including `--config`, `--overlay`, and applicable application -selectors. The native `--llm-profile`, `--llm-var`, `--llm-session-id`, and +selectors. The preferred native aliases `--profile`, `--var`, `--session-id`, and prompt/profile namespace flags supply the relevant discovery context. Preserve upstream selection semantics, including the prompt's default profile when an explicit profile is omitted. Qualified IDs identify installed resources;