Record native pipeline commands and input conventions

This commit is contained in:
2026-11-19 16:19:48 +00:00
parent 93dd406459
commit b038cc1a59

View File

@@ -21,7 +21,8 @@ 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.
Application-specific commands, wiring, and reporting details remain open below.
Item 2 selects the application command structure and input conventions. Loader
wiring and detailed reporting 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
@@ -98,8 +99,8 @@ Two application needs already identified for deliberate treatment are:
### Intended Sequencing
1. Incorporate item 1's selected dependency baseline and standard capabilities,
and resolve native application command design, bringing U10 forward.
1. Incorporate items 1–2's selected dependency baseline, standard capabilities,
and native application command design, bringing U10 forward.
2. Introduce CommandKit composition alongside native source assembly. Connect
shared loaders and standard inspection while retaining application
orchestration responsibilities.
@@ -183,21 +184,149 @@ wiring and presentation details explicitly.
## 2. Native Command Surface And Inputs
**Discussion / decision:** Full native cutover agreed; concrete command and input
choices pending. Preserving the existing CLI is not a selection criterion.
**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.
- How should Notarius workflows be exposed through native standard commands and
application handlers, including upstream naming and flag recommendations?
- Which application input semantics are needed, such as reference selection and
reasoning-effort inheritance or clearing, and how should native typed inputs
express them, including omitted versus explicitly supplied values?
- Which existing commands and custom parsing can disappear once standard
help/version, argument handling, and invalid-invocation behavior are adopted?
### Command Structure
Use the [CLI reference](../cli.md) to identify current workflows and write
migration guidance, not as a compatibility constraint. Coordinate native inputs
with the master roadmap's retry and worker policy decisions; their domain meaning
is separate from how the CLI expresses them.
```text
notarius pipeline list
notarius pipeline show <pipeline-id>
notarius pipeline validate <pipeline-id>
notarius pipeline 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. |
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 clarification:** CommandKit supports both a root `run` command and a
nested `pipeline run` command. Neither is more native. The selected grouping
keeps pipeline discovery, inspection, validation, and execution together; it is
an application usability choice, not an upstream naming requirement. A shorter
root command could be selected on usability grounds without changing the native
architecture. Do not introduce a second route solely for legacy compatibility.
### 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 will settle
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. Detailed report content
and loader wiring remain with items 3–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
@@ -208,8 +337,9 @@ is separate from how the CLI expresses them.
- How should native command selections and overrides reach shared loaders while
retaining the selected ConfigKit source composition and main-source-relative
companion behavior across execution and inspection?
- Where should pipeline-specific validation attach to standard configuration
validation, and what state should be acquired only when a command needs it?
- How should `pipeline show`, `pipeline validate`, and `pipeline run` share
application resolution alongside standard configuration validation, and what
state should be acquired only when a command needs it?
Retain the selected offline preflight boundary: it checks application composition
and known native resources without synthesizing a stage request or requiring