571 lines
32 KiB
Markdown
571 lines
32 KiB
Markdown
# CommandKit Migration Discussion
|
||
|
||
## Purpose And Status
|
||
|
||
Working notepad for the CommandKit decisions that will be incorporated into the
|
||
[master PromptKit-native migration roadmap](promptkit.md). Record the proposal,
|
||
open questions, evidence, and decisions here as we discuss them.
|
||
|
||
**Direction agreed:** Make a full cutover to a CommandKit-native application as
|
||
part of the same migration as modern PromptKit, in separate, reviewable
|
||
implementation steps. Adopt CommandKit's public-facing conventions and
|
||
recommendations to the fullest extent. Bring its design decisions forward and
|
||
complete adoption before the overall cutover.
|
||
|
||
The master roadmap currently places CommandKit in a subsequent Phase 7 and leaves
|
||
its details in U10. That sequencing has not yet been revised. Once the relevant
|
||
details below are settled, fold them into the master roadmap, including its
|
||
dependency baseline, implementation phases, removal inventory, and acceptance
|
||
criteria. No application or dependency changes have been implemented through
|
||
this discussion.
|
||
|
||
Item 1 selects the dependency versions and standard capabilities, including
|
||
PromptKit v0.23.3 in place of the master roadmap's initial v0.23.2 target.
|
||
Item 2 selects the application command structure and input conventions. Item 3
|
||
selects native composition, shared loaders, and application preflight. Detailed
|
||
reporting, debug capture, and verification choices remain open below.
|
||
|
||
The PromptKit architecture and checkpoint decisions remain in force. This
|
||
discussion develops the CommandKit portion of that migration and its interactions
|
||
with U1 (dependencies), U9 (records/reporting), and U10 (CommandKit adoption).
|
||
|
||
## Agreed Proposal
|
||
|
||
### Guiding Rule: Full Native Cutover
|
||
|
||
Backward compatibility with the existing CLI conventions is a non-goal. Use
|
||
CommandKit's native command, input, help/version, reporting, error, and outcome
|
||
conventions as the design baseline. This mirrors the PromptKit-native direction.
|
||
|
||
Existing command names, flags, aliases, parsing behavior, report shapes, and exit
|
||
conventions are migration evidence, not requirements to preserve. Do not add
|
||
legacy aliases, compatibility shims, parallel parsers, or reporting wrappers
|
||
solely to reproduce the old CLI. Any application-specific behavior should serve
|
||
an actual Notarius need and fit the native conventions.
|
||
|
||
Provide migration guidance in release documentation, explaining the new commands
|
||
and conventions and the actions operators or subprocess callers must take.
|
||
Documenting the transition replaces a requirement to keep the old CLI working.
|
||
Update canonical CLI and consumer documentation when the behavior lands.
|
||
|
||
Application responsibilities such as producing artifacts, reporting publication
|
||
outcomes, and managing checkpoint/debug storage remain meaningful. Their existing
|
||
CLI expression is not protected by an implicit compatibility exception. This
|
||
guiding rule does not itself choose stored artifact or checkpoint formats; those
|
||
remain separate application decisions in the master roadmap.
|
||
|
||
### Why Adopt Together
|
||
|
||
- Source assembly and preflight are already changing. CommandKit integrations
|
||
can consume the same application and native engine loaders.
|
||
- ckconfig and ckprompt can replace standard inspection commands directly,
|
||
avoiding an intermediate adaptation of commands that would soon be replaced.
|
||
- Native execution facts and application outcomes can feed the intended reporting
|
||
facilities while duplicate LLM bookkeeping is removed.
|
||
- Configuration and command migration can be documented and verified as one
|
||
coherent transition.
|
||
|
||
The added work is principally CLI composition and contract migration: dispatch,
|
||
flag parsing, configuration selection, reporting, and process-status mapping.
|
||
Choose their native forms deliberately and document the transition, rather than
|
||
spending migration effort recreating existing CLI conventions.
|
||
|
||
### Ownership And Scope
|
||
|
||
| Concern | Selected owner |
|
||
| --- | --- |
|
||
| Command hosting, standard input/help mechanics, common report formatting and visibility | CommandKit. |
|
||
| Standard configuration and PromptKit inspection commands | ckconfig and ckprompt, supplied with application loaders and request builders. |
|
||
| Configuration composition and model execution | ConfigKit and PromptKit, using the native boundaries already selected. |
|
||
| Pipeline execution and listing, pipeline-specific preflight, artifact publication, checkpoints, and domain outcomes | Notarius application handlers and framework. |
|
||
| Receipt content, debug artifact lifecycle, and application outcome meaning | Notarius, expressed through CommandKit's reporting and outcome conventions. |
|
||
|
||
Adopt the standard capability suite selected in item 1, including upstream
|
||
commands and recommendations beyond the existing Notarius surface. Items 2–3
|
||
select application inputs and composition; the remaining discussion determines
|
||
result presentation, debug capture, and verification.
|
||
|
||
Pipeline and domain code should remain independent of CommandKit. Native
|
||
PromptKit observations supply execution facts; Notarius attaches application
|
||
meaning and selects report content. CommandKit supplies presentation mechanics.
|
||
|
||
Two application needs already identified for deliberate treatment are:
|
||
|
||
- The current `run --json` publishes a receipt after output publication. Determine
|
||
the needed result information and express it through an appropriate native
|
||
output facility. The old flag, envelope, formatting, and stream conventions are
|
||
not compatibility requirements; reports must still describe the actual outcome.
|
||
- The current `--debug` requests durable artifacts. Retain the distinction between
|
||
artifact capture and reporting verbosity, while choosing native controls and
|
||
meanings rather than requiring that flag to retain its old behavior.
|
||
|
||
### Intended Sequencing
|
||
|
||
1. Incorporate items 1–2's selected dependency baseline, standard capabilities,
|
||
and native application command design, bringing U10 forward.
|
||
2. Introduce item 3's CommandKit composition alongside native source assembly.
|
||
Connect shared loaders, standard inspection, and the focused application
|
||
preflight package.
|
||
3. Develop native execution and accounting against the intended CLI boundary,
|
||
with pipeline and domain tests independent of CommandKit.
|
||
4. Complete command and reporting migration before final end-to-end verification
|
||
and migration documentation.
|
||
|
||
This is the agreed sequencing direction, not a replacement phase plan. Concrete
|
||
work units and their placement in the master roadmap follow the discussion below.
|
||
|
||
## 1. Adoption Scope And Dependency Baseline
|
||
|
||
**Discussion / decision:** Versions and standard capability scope agreed. Adopt
|
||
the set below, including the move to PromptKit v0.23.3. Items 2–3 select
|
||
application commands and composition; subsequent topics address reporting and
|
||
debug capture. These are selected migration targets; the application dependencies
|
||
have not changed.
|
||
|
||
### Selected Versions
|
||
|
||
| Module | Version | Role |
|
||
| --- | --- | --- |
|
||
| `go.maximumdirect.net/commandkit` | `v0.7.0` | Native command declarations, inputs, help/version, reporting, and completion. |
|
||
| `go.maximumdirect.net/ckconfig` | `v0.9.0` | Standard configuration commands and ConfigKit diagnostic classification. |
|
||
| `go.maximumdirect.net/ckprompt` | `v0.10.0` | Standard PromptKit inspection, validation, preparation, and smoke diagnostics. |
|
||
| `go.maximumdirect.net/configkit` | `v1.2.1` | Shared configuration dependency for the application and integrations. |
|
||
| `go.maximumdirect.net/promptkit` | `v0.23.3` | Native model execution, including corrected timeout/cancellation reporting. |
|
||
|
||
The CommandKit integration releases form a documented compatible set using
|
||
PromptKit v0.23.2. Select v0.23.3 explicitly for its timeout attribution and
|
||
cancellation/error identity fixes. It retains the same dependencies and requires
|
||
no configuration or request API migration from v0.23.2. The Go consumer minimum
|
||
remains 1.27. Verify the assembled dependency set through the migration's normal
|
||
integration checks and update attribution when the dependency changes land.
|
||
|
||
The version review used locally available release tags and tagged dependency
|
||
manifests. Remote release lookup was unavailable, so it did not establish whether
|
||
newer tags existed remotely. These are deliberate selected versions, not a claim
|
||
that every module is the latest published release.
|
||
|
||
Evidence: [integration version guidance](../../../commandkit/docs/consumers/guide.md#module-selection)
|
||
and [PromptKit v0.23.3 release notes](../../../promptkit/docs/releases/v0.23.3.md).
|
||
|
||
### Selected Standard Capabilities
|
||
|
||
| Area | Adopt in the cutover |
|
||
| --- | --- |
|
||
| Core CLI | Native help, `version`, typed flags and operands, supplied-value semantics, standard outcomes, and command declaration/dispatch. |
|
||
| Reporting | Native `--format` with text/YAML/JSON, `--quiet`, `--verbose`, `--debug`, and `--progress`, including upstream visibility and failure behavior. |
|
||
| Configuration | `config scopes`, `validate`, `show`, `sources`, `explain`, and `diff`, for application and PromptKit configuration. |
|
||
| Resource discovery | PromptKit listings for prompts, profiles, backends, namespaces, and collections, with native filters and selectors. |
|
||
| Resource inspection | Native prompt, profile, and backend reports, plus requirements discovery. |
|
||
| Concrete request checks | Requirements validation and prepared-request preview using native inputs, variables, profiles, and execution overrides. |
|
||
| Provider diagnostics | Reachability, authentication, text-inference, structured-output, and aggregate smoke tests. |
|
||
| Convenience features | Bash, Zsh, and Fish completion, useful declaration hints, and upstream PromptKit convenience aliases. |
|
||
|
||
Use the [upstream CLI conventions](../../../commandkit/docs/cli.md) directly.
|
||
Providing the standard capability suite means supplying application loaders and
|
||
callbacks, not recreating those commands locally. Upstream convenience aliases
|
||
are selected native features; this does not reintroduce legacy Notarius aliases.
|
||
|
||
### Wiring Boundaries And Follow-Up
|
||
|
||
- Keep configuration validation, requirements discovery, and concrete request
|
||
validation distinct. Pipeline preflight remains application-owned. Concrete
|
||
preparation may read inputs and schemas and check credentials even though it
|
||
makes no model call.
|
||
- Install smoke commands for explicit invocation. Their availability does not
|
||
introduce provider calls during startup, ordinary validation, or offline tests.
|
||
- Enable application configuration overrides through ConfigKit. The selected
|
||
PromptKit configuration scope does not support arbitrary `--set` overrides;
|
||
use supported request-level controls rather than implementing a local equivalent.
|
||
- Retain application handlers for pipeline execution and discovery, with native
|
||
commands, inputs, and result presentation to be designed in items 2–5.
|
||
|
||
No upstream feature request has been identified as a blocker for this scope.
|
||
Evaluate any later demonstrated gap on its actual application need. On roadmap
|
||
reconciliation, incorporate these versions into U1, replace U10's open standard
|
||
capability selection with this decision, and retain the unresolved application
|
||
wiring and presentation details explicitly.
|
||
|
||
## 2. Native Command Surface And Inputs
|
||
|
||
**Discussion / decision:** Command structure and input conventions agreed. Use a
|
||
small application-owned `pipeline` family alongside the standard `config` and
|
||
`promptkit` families. These are migration targets, not implemented commands.
|
||
|
||
### Command Structure
|
||
|
||
```text
|
||
notarius pipeline list
|
||
notarius pipeline show <pipeline-id>
|
||
notarius pipeline validate <pipeline-id>
|
||
notarius pipeline run <pipeline-id> --input-file <path>
|
||
notarius run <pipeline-id> --input-file <path>
|
||
|
||
notarius config scopes
|
||
notarius config validate|show|sources|explain|diff ...
|
||
|
||
notarius promptkit list ...
|
||
notarius promptkit show ...
|
||
notarius promptkit requirements show|validate ...
|
||
notarius promptkit test <kind>
|
||
|
||
notarius version
|
||
notarius completion bash|zsh|fish
|
||
notarius help [command...]
|
||
```
|
||
|
||
The alternatives separated by `|` above summarize the installed operations;
|
||
they are not literal shell commands.
|
||
|
||
| Application command | Responsibility |
|
||
| --- | --- |
|
||
| `pipeline list` | Discover configured pipelines. |
|
||
| `pipeline show` | Describe the resolved ordered steps, lanes, modules, reference slots, and configured selections. |
|
||
| `pipeline validate` | Perform offline application preflight using the intended selections and overrides. |
|
||
| `pipeline run` | Execute the selected pipeline and publish artifacts. |
|
||
| `run` | Native convenience alias for `pipeline run`. |
|
||
|
||
Move pipeline-specific validation out of `config validate --pipeline ...`.
|
||
Configuration validation, pipeline composition checks, and concrete PromptKit
|
||
request validation remain distinct. Pipeline preflight does not synthesize stage
|
||
requests or require provider credentials. PromptKit's concrete validation may
|
||
read inputs and schemas and check credentials without making a model call.
|
||
|
||
**Naming decision:** Keep `pipeline run` as the canonical command and install
|
||
`run` as a native convenience alias using
|
||
`commandkit.Alias("run", "pipeline run")`. Both routes use the same handler,
|
||
operands, flags, validation, and reporting. CommandKit supplies alias-aware help
|
||
and diagnostics; no forwarding handler or additional parser is needed.
|
||
|
||
The grouped family and root shortcut are application usability choices, not an
|
||
upstream naming requirement. The alias uses the new input conventions and does
|
||
not preserve legacy flags or behavior. Use `notarius run` in quick-start examples
|
||
and document both routes in the command reference when the migration lands.
|
||
See [native alias behavior](../../../commandkit/docs/cli.md#application-owned-aliases).
|
||
|
||
### Input Conventions
|
||
|
||
Use a required pipeline-ID operand and a required `--input-file PATH` for runs.
|
||
Use native typed declarations and supplied-value semantics, including explicit
|
||
empty, false, and zero values. Apply defaults only when the relevant value is
|
||
omitted; application validation still decides whether a supplied value is valid.
|
||
|
||
| Concern | Selected convention |
|
||
| --- | --- |
|
||
| Configuration | Native `--config` and `--overlay`; name the application scope `app`. |
|
||
| Lane selection | Repeatable `--lane ID`; omission selects the normal pipeline lane set. Replace comma-separated `--only`. |
|
||
| Output placement | Application-owned `--output-dir PATH`. |
|
||
| Chunk-plan caching | `--chunk-cache auto\|bypass\|refresh`. |
|
||
| Checkpoint reuse | Keep `--resume` and `--recompute-step ID` with the agreed recovery policy. |
|
||
| Presentation | Native `--format`, `--quiet`, `--verbose`, `--debug`, and `--progress`. |
|
||
| Configuration-valued tuning | Supported application `--set POINTER=JSON` overrides, including worker and semantic-budget settings once their configuration design is settled. |
|
||
|
||
Adopt native parsing rules: flags follow the complete command path and may be
|
||
interspersed with operands; `--` ends option parsing. Singleton flags use the
|
||
last successfully parsed occurrence, with every occurrence checked. Repeatable
|
||
flags preserve occurrence order and treat commas as ordinary value content.
|
||
Use filesystem and choice completion hints where applicable.
|
||
|
||
Keep worker counts and semantic continuation budgets in configuration rather
|
||
than introducing additional dedicated CLI controls now. Their field names,
|
||
defaults, and domain meaning remain master-roadmap decisions. Item 3 selects
|
||
shared loading and override wiring across application and standard commands.
|
||
|
||
### Native LLM Controls
|
||
|
||
Use ckprompt's reusable flag declarations for applicable profile, session, and
|
||
execution controls on `pipeline run`, including model, temperature, timeout,
|
||
reasoning effort, and transient retries. Run-wide overrides reach all LLM-backed
|
||
producers and validators, including continuation calls. Without an override,
|
||
normal binding/pipeline/prompt selection applies.
|
||
|
||
| Reasoning input | Meaning |
|
||
| --- | --- |
|
||
| Omitted | Inherit the selected settings. |
|
||
| `--llm-reasoning-effort high` | Replace the inherited setting. |
|
||
| `--llm-reasoning-effort ""` | Clear the inherited setting. |
|
||
|
||
Remove the separate `--clear-reasoning-effort` control. Native transient retries
|
||
remain distinct from application semantic continuation budgets. Individual
|
||
prompt selection and named prompt input injection belong on standard PromptKit
|
||
commands; pipeline modules construct their own requests and response contracts.
|
||
Use native `--llm-profile` and `--llm-session-id` spellings, without inventing
|
||
another LLM input parser.
|
||
|
||
### Application Reference Inputs
|
||
|
||
Retain repeatable `--reference SELECTOR=PATH` and `--without-reference SELECTOR`.
|
||
Keep useful pipeline-wide, lane, chunk, and stage-specific selectors, such as
|
||
`party=party.txt` and `npc-registry.extract.party=npc-party.txt`. CommandKit owns
|
||
repeatable input parsing and typed conversion; Notarius owns selector expansion,
|
||
specificity, required slots, and external/generated-reference conflict checks.
|
||
These selectors describe pipeline relationships and are not interchangeable
|
||
with PromptKit's individual-request `--llm-input-file` bindings.
|
||
|
||
### Preparing Pipeline Inspection Content
|
||
|
||
**Follow-up clarification:** Leverage ConfigKit for the composed, decoded
|
||
configuration, defaults, imports, overlay, inheritance, overrides, and native
|
||
provenance/redacted inspection. Feed that loaded configuration through the same
|
||
application resolution used by validation and execution to obtain selected
|
||
lanes, registered modules, validator chains, and reference relationships.
|
||
CommandKit renders a small application report of that resolved composition.
|
||
|
||
ConfigKit does not know Notarius's module catalog or pipeline semantics. Reuse
|
||
the existing resolver rather than writing a second resolution path for `show`.
|
||
Generic effective configuration and source explanations remain available through
|
||
`config show` and `config explain`. ConfigKit's safe inspection facilities do not
|
||
automatically redact an arbitrary application report; select appropriate report
|
||
content rather than dumping the raw typed configuration. Item 3 selects loader
|
||
wiring; detailed report content remains with item 4.
|
||
|
||
### Removals And Remaining Work
|
||
|
||
Retire custom dispatch, argument-count handling, assembled help, version-command
|
||
parsing, standard configuration/LLM flag parsing, comma-separated lane parsing,
|
||
and the separate reasoning-clearing machinery. Replace `config effective` with
|
||
native `config show`, `config profile` with `promptkit show profile`, and bespoke
|
||
`--json` switches with `--format json`.
|
||
|
||
Application handlers still validate meaningful input combinations and translate
|
||
typed inputs into pipeline selections. Native `--debug` supplies reporting
|
||
behavior; a distinct artifact-capture control remains to be selected in item 5.
|
||
Items 3–4 own loader behavior, exact report content, and outcome presentation.
|
||
|
||
Evidence: [CommandKit command/input conventions](../../../commandkit/docs/cli.md#registered-command-syntax),
|
||
[reusable PromptKit flags](../../../commandkit/docs/consumers/guide.md#request-builders-and-loading),
|
||
[ConfigKit loading and inspection](../../../ConfigKit/README.md), and the current
|
||
[Notarius configuration boundaries](../internal/configuration.md).
|
||
Use the current [CLI reference](../cli.md) for migration guidance, not as a
|
||
compatibility constraint.
|
||
|
||
## 3. Application Composition, Loaders, And Preflight
|
||
|
||
**Discussion / decision:** Agreed. Fully adopt native ConfigKit, PromptKit, and
|
||
CommandKit workflows through a small composition root, shared loaders, and
|
||
invocation-local state. Follow substantially the same composition/loading pattern
|
||
as Audita while retaining Notarius's pipeline, artifact, validation, recovery,
|
||
and publication responsibilities. Centralize application prompt/profile
|
||
dependency checks in a focused `internal/preflight` package. Implementation is
|
||
pending.
|
||
|
||
### Native Application Composition
|
||
|
||
One application constructor installs the pipeline declarations and native `run`
|
||
alias, a ckconfig suite with `app` and `promptkit` scopes, the selected ckprompt
|
||
capabilities, and native help/version/completion/reporting. Supply ordinary
|
||
callbacks and typed inputs; do not introduce another CLI framework or LLM wrapper.
|
||
|
||
Constructing the application registers declarations without loading configuration,
|
||
building an engine, or initializing run storage. Help, version, and completion
|
||
remain independent of runtime configuration and provider work. Application
|
||
handlers acquire only what their operation requires.
|
||
|
||
### Shared Configuration And Engine Loaders
|
||
|
||
Use two shared loading responsibilities across application and standard commands:
|
||
|
||
1. **Application configuration:** Select explicit `--config`, then the existing
|
||
environment/discovery policy; apply native `--overlay` and supported
|
||
application `--set` overrides. ConfigKit owns composition, imports,
|
||
inheritance, presence, provenance, and inspection. Supply application
|
||
defaults, normalization, and structural validation through its extension
|
||
points. Retain the native ConfigKit result and selected main-source context;
|
||
derive runtime values where needed without copying inspection machinery into
|
||
another result abstraction.
|
||
2. **PromptKit engine:** Build a native `*promptkit.Engine` from that loaded
|
||
application's source context and the agreed native source assembly. Runtime,
|
||
preflight, and inspection use the same builder and definitions.
|
||
|
||
Preserve supplied-value information throughout loading. An explicitly empty
|
||
configuration path receives deliberate validation rather than silently falling
|
||
through to discovery. Across application and PromptKit commands, `--config`
|
||
selects the Notarius application configuration; the PromptKit scope inspects the
|
||
engine assembled for that application selection.
|
||
|
||
Retain the master roadmap's [source assembly](promptkit.md#configuration-sources-and-prompt-assets):
|
||
PromptKit's bundled underlay, embedded Notarius resources, then optional operator
|
||
companions beside the main application source actually selected by ConfigKit.
|
||
Use native imports and filesystem contexts. There is no second source search or
|
||
working-directory fallback; strict composition, missing-companion handling, and
|
||
load-error behavior remain as selected in the master roadmap. Do not reinterpret
|
||
the application document as a standalone PromptKit configuration or add another
|
||
inspection-only assembly path.
|
||
|
||
Application `--set` overrides flow through ConfigKit's load. Native request
|
||
execution overrides remain request controls; they do not mutate captured engine
|
||
configuration. Preserve the selected PromptKit configuration scope's lack of
|
||
arbitrary `--set` support.
|
||
|
||
### Invocation State And Engine Ownership
|
||
|
||
Use CommandKit's supported invocation state to retain configuration and an engine
|
||
when callbacks need them repeatedly. Application handlers use the same loader
|
||
functions with small invocation-owned state. One pipeline execution shares one
|
||
native engine across producers, validators, and continuations, preserving native
|
||
backend admission limits.
|
||
|
||
Do not assume one invocation always means one configuration selection. Native
|
||
`config diff` acquires left and right selections with potentially different
|
||
configuration, overlays, and overrides while sharing invocation state. Load the
|
||
sides independently or distinguish selections in any local reuse. A single
|
||
unqualified cached result would be incorrect. No persistent loader cache or
|
||
cryptographic configuration identity is needed.
|
||
|
||
### Shared Pipeline Resolution And Command Work
|
||
|
||
Reuse the existing application resolver with loaded configuration, selected
|
||
pipeline/lanes/reference changes, applicable overrides, and the module catalog.
|
||
It owns module/options validation, typed artifact compatibility, validator-chain
|
||
selection, ordered dependencies, and reference-binding compatibility.
|
||
|
||
| Command | Required application work |
|
||
| --- | --- |
|
||
| `pipeline list` | Load application configuration and enumerate pipelines. |
|
||
| `pipeline show` | Resolve the selected pipeline and report its composition. |
|
||
| `pipeline validate` | Resolve the pipeline and check its known native resource dependencies offline. |
|
||
| `pipeline run` / `run` | Use the same resolution and preflight checks, then prepare and execute the pipeline. |
|
||
| `config … --scope app` | Supply the native ConfigKit result directly to the integration. |
|
||
| PromptKit inspection commands | Acquire the shared engine assembly and delegate to native inspection. |
|
||
|
||
Run handlers call shared application functions directly; they do not invoke the
|
||
validation command or parse its output. `pipeline show` can describe configured
|
||
prompt/profile selections without constructing an engine just to expand them
|
||
into execution settings or performing every execution-readiness check.
|
||
|
||
### Prompt Dependencies And Offline Preflight
|
||
|
||
Notarius knows which operations need prompts; PromptKit knows whether those
|
||
definitions resolve in the assembled engine. Check every statically known prompt
|
||
dependency of the selected pipeline, including LLM-backed validators and any
|
||
separately selected correction prompts. A deterministic stage may require none,
|
||
an LLM-backed stage may require several, and multiple stages may share one.
|
||
Configuration can select the required set. For data-dependent selections, check
|
||
what is knowable before execution and resolve the final choice at runtime.
|
||
|
||
Share prompt identifiers and selection logic with execution through module or
|
||
operation declarations. Do not maintain a separate hardcoded preflight inventory.
|
||
These small dependency declarations identify required resources; they do not
|
||
restore asset manifests, prompt filesystem registration, message assembly, or
|
||
schema registries. Native sources remain the owners of prompt definitions.
|
||
|
||
Use the same engine and intended namespaces as execution to inspect known prompts
|
||
and applicable profile selections, including a known prompt's default profile
|
||
when effective. Partial profiles alone are not failures. Report missing
|
||
dependencies with pipeline, step/lane, stage or validator, and resource context
|
||
where applicable.
|
||
|
||
Offline preflight does not read the transcript, materialize reference contents,
|
||
synthesize stage requests, require credential values, or contact providers.
|
||
Engine assembly may read configuration and prompt resources. Availability does
|
||
not certify prompt domain correctness or guarantee that future requests pass
|
||
schema, credential, or provider checks. Concrete `Prepare`/`ValidateRequest`
|
||
remains the boundary for completed request validation, and smoke commands remain
|
||
explicit provider operations.
|
||
|
||
### Dedicated Preflight Package
|
||
|
||
Add a small application-level `internal/preflight` package accepting the resolved
|
||
pipeline, relevant module declarations, and the native engine. It checks the
|
||
pipeline's known prompt/profile dependencies and returns contextual findings or
|
||
errors for the command boundary to present.
|
||
|
||
Keep configuration validation in ConfigKit/application definitions, structural
|
||
resolution in the pipeline resolver, and concrete preparation in PromptKit.
|
||
Preflight does not discover configuration, register production modules, construct
|
||
engines, prepare synthetic requests, initialize storage, or own CLI reporting.
|
||
The composition root supplies its collaborators. Module dependency declarations
|
||
remain in existing module contracts; modules do not import the preflight package.
|
||
Exact function signatures and finding representation remain implementation choices.
|
||
|
||
### Request Construction, Storage, And Removals
|
||
|
||
Use native request builders directly for standard PromptKit commands where
|
||
sufficient. Add an application callback only for a demonstrated application need,
|
||
preserving supplied operator values. Pipeline modules construct their own domain
|
||
requests; share concrete request-building functions when useful without
|
||
simulating pipeline execution to populate an inspection command.
|
||
|
||
Output publication, checkpoints, debug capture, and execution records belong to
|
||
the run path. Loaders do not initialize those resources; debug allocation timing
|
||
remains with item 5. Remove command-specific loading paths, copied configuration
|
||
and resource inspection, eager runtime setup, and duplicated preflight
|
||
orchestration. No broader application/package reorganization is required by this
|
||
decision.
|
||
|
||
Evidence: [native suite and loader ownership](../../../commandkit/docs/consumers/guide.md#configkit-scopes),
|
||
[PromptKit integration callbacks](../../../commandkit/docs/consumers/guide.md#request-builders-and-loading),
|
||
[Audita composition](../../../audita/internal/cli/app_wiring.go), and the
|
||
[existing configuration ownership decision](../adr/0020-delegate-configuration-mechanics-to-configkit.md).
|
||
|
||
## 4. Reports, Machine Output, And Outcomes
|
||
|
||
**Discussion / decision:** Pending.
|
||
|
||
- How should native reports and output modes express application results? Where
|
||
does an application data requirement justify raw output rather than a standard
|
||
report, independently of the old CLI's output conventions?
|
||
- How should syntax, configuration, pipeline, and publication outcomes map to
|
||
native outcome/status conventions and user-facing explanations? How should
|
||
presentation failures remain distinguishable from the operation outcome?
|
||
- Which application scope and minimal projections connect native observations
|
||
to progress, terminal summaries, manifests, and receipts without duplicate
|
||
execution accounting?
|
||
|
||
Review the current [run-result contract](../integrations/run-result.md) and
|
||
[CLI failure mapping](../internal/cli.md#failure-mapping-and-terminal-reporting)
|
||
to understand application needs and caller migration impact. Their existing CLI
|
||
shapes and status mappings do not override the native-cutover direction.
|
||
Item 6 of the [PromptKit discussion record](promptkit-architecture-discussion.md#6-inspection-and-execution-bookkeeping)
|
||
provides the bookkeeping boundary; U9 still owns concrete durable record choices.
|
||
|
||
## 5. Debug Capture And Optional Diagnostics
|
||
|
||
**Discussion / decision:** Pending.
|
||
|
||
- How should artifact-capture controls fit alongside native quiet/verbose/debug
|
||
reporting selections without requiring the existing `--debug` behavior?
|
||
- How should requested debug artifact writes, failures, disclosure, and retention
|
||
connect to command completion and native callbacks?
|
||
- For selected preview, request-validation, or smoke capabilities, what native
|
||
request builders and explicit execution choices should the application supply?
|
||
|
||
Keep debug creation and physical storage in Notarius. Ordinary records exclude
|
||
sensitive response/history content, and provider smoke diagnostics remain
|
||
explicitly opt-in. Native inspection alone must not become a model call.
|
||
|
||
## 6. Verification, Migration, And Roadmap Incorporation
|
||
|
||
**Discussion / decision:** Pending.
|
||
|
||
- Which focused command and subprocess tests protect the new native command,
|
||
output, outcome, receipt, and debug behavior? Which tests of superseded CLI
|
||
contracts and parser/formatter implementation can retire?
|
||
- Which representative assembled workflows prove that execution, inspection,
|
||
and preflight use the same intended configuration without duplicating lower-level
|
||
coverage? Keep the default suite offline and independent of real credentials.
|
||
- How should CommandKit steps replace the master roadmap's deferred Phase 7,
|
||
and which migration examples, documentation, and ADRs need coordinated updates?
|
||
- What release-documentation guidance will show operators and subprocess callers
|
||
how to migrate their workflows and integrations to the new conventions?
|
||
|
||
After discussion, reconcile the master roadmap's U1/U9/U10 entries, sequencing,
|
||
removals, and acceptance criteria, including its treatment of existing inspection
|
||
commands and machine-output compatibility. Carry forward the explicit non-goal
|
||
of CLI backward compatibility and release migration guidance. Preserve other
|
||
unresolved choices explicitly. Then mark this document as the discussion record
|
||
and keep implementation status in the master roadmap.
|
||
|
||
## Evidence And Reading
|
||
|
||
These are starting points for discussion, not a completed CommandKit migration
|
||
audit. Sibling links assume the local repositories remain available.
|
||
|
||
- [Notarius CLI implementation overview](../internal/cli.md) and
|
||
[configuration internals](../internal/configuration.md).
|
||
- [CommandKit consumer guide](../../../commandkit/docs/consumers/guide.md), including
|
||
module selection, typed inputs, raw/formatted output, reporting, and loaders.
|
||
- [ckconfig integration](../../../commandkit/integrations/ckconfig/README.md) and
|
||
[ckprompt integration](../../../commandkit/integrations/ckprompt/README.md).
|
||
- [Audita command composition](../../../audita/internal/cli/app_wiring.go), showing
|
||
application handlers and upstream integrations in one CommandKit application.
|