diff --git a/docs/roadmap/commandkit-notepad.md b/docs/roadmap/commandkit-notepad.md index 8ba1ece..5ed23d0 100644 --- a/docs/roadmap/commandkit-notepad.md +++ b/docs/roadmap/commandkit-notepad.md @@ -176,7 +176,9 @@ commands retain their positional session identity and can also select an explicit source using `--session-file`. Identity and file selectors are complementary: the file selects the source and -an accompanying ID asserts the intended identity. Mismatches fail clearly. +an accompanying ID asserts the intended identity. Check that assertion against +the effective configuration after native overrides and resolution; mismatches +fail clearly. For inspection, the file can supply identity when no identity selector is given; session-oriented commands retain their required positional identity. Select the party through its campaign; an independent `--party-file` selector @@ -187,6 +189,85 @@ Comparisons expose `--against-campaign`, `--against-campaign-file`, right-side configuration selectors. Omitted right-side selectors use normal defaults rather than inheriting left-side values. +### Configuration inspection capabilities + +Enable the full applicable native inspection capabilities across the four +configuration scopes: + +- path-selected show using JSON Pointer syntax; +- explanation and path discovery, including available history and provenance; +- detailed validation findings with native severity and code filters; +- detailed comparisons with before/after values and presence information; and +- native `diff --check`, including status `3` when differences exist. + +These operations use the same configuration and evidence as ordinary +inspection. Filtering findings changes presentation, not validation success. +Expose available evidence for derived fields without manufacturing source +history. + +### Native configuration overrides + +Support invocation-local overrides for all four domains, with equivalent +configuration selections available to inspection, planning, and execution. +CommandKit supplies the `POINTER=JSON` flag grammar; ConfigKit applies its native +override mechanism. Do not introduce additional protected-field lists, custom +merge semantics, or a separate override acceptance policy. + +Use these flag spellings: + +| Flag | Target | +| --- | --- | +| `--set POINTER=JSON` | Selected inspection scope; `app` on execution commands | +| `--set-app POINTER=JSON` | App/pipeline configuration explicitly | +| `--set-campaign POINTER=JSON` | Campaign configuration explicitly | +| `--set-session POINTER=JSON` | Session configuration explicitly | +| `--set-party POINTER=JSON` | Party configuration explicitly | + +Explicitly targeted flags also support overriding a configuration on which the +selected inspection view depends, such as inspecting expanded pipeline +artifacts with a party override. Comparisons use native `--against-set` and +the corresponding `--against-set-app`, `--against-set-campaign`, +`--against-set-session`, and `--against-set-party` flags for the right side. +Retain native aggregate-scope behavior rather than inventing scope prefixes +inside JSON Pointers. + +Apply overrides after typed defaults and decoding, before application +resolution and semantic validation. Preserve native explicit empty, false, +zero, and null values, mapping merge and whole-sequence replacement, and +duplicate/overlapping-path rejection. Earlier parsing and decoding failures +remain errors. CommandKit's last-value convention for singleton flags does not +replace ConfigKit's conflict rules for override records. + +Override paths address the configuration accepted by the loader. They do not +provide an independent patch mechanism over the final expanded artifact +catalog. Ordinary Narratio derivation and validation determine the effective +result, regardless of whether values came from files, inheritance, overlays, +or CLI overrides. + +Overrides leave source configuration files unchanged. Normal run metadata and +prepared configuration may record the effective settings through established +secret-safe representations. Reuse decisions continue to depend on semantic +evidence: result-affecting changes can require regeneration, while the presence +of an override alone does not force execution. + +### Identity assertions and credential overrides + +Identity fields are not immutable or excluded from overrides. ConfigKit applies +their overrides normally. Narratio then checks the effective identity against +any explicitly asserted campaign/session identity so an operation targeting one +session cannot silently use another session's workspace, lock, manifest, or +remote destination. This is an ordinary domain consistency check, independent +of how the value was supplied. + +When no identity is asserted, such as inspection of an explicit session file +without `--session`, the effective document can supply its overridden identity. +Session-oriented commands retain their required positional assertion. + +Credential-related fields accept native overrides and use ConfigKit's ordinary +typed-secret handling and normal configuration validation. Safe inspection, +diagnostics, and persistence remain separate output responsibilities; they do +not justify additional restrictions on which fields may be overridden. + ## Reviewed upstream baseline The initial review covered these released modules: @@ -214,19 +295,6 @@ baseline. They remain current-behavior documents until the migration lands. ## Open decisions -### Optional configuration capabilities - -Determine the useful scope of path-selected show, path explanation, detailed -validation findings, comparison details/check mode, and temporary `--set` -overrides. Prefer the native capabilities wherever the provider can faithfully -support them. - -Overrides require a domain decision: which configurations accept them, and do -execution commands accept the same overrides as inspection? The integration's -ability to parse an override does not establish Narratio's intended loading -contract. Avoid an inspection result that purports to describe execution while -silently using different resolution rules. - ### Reports and machine-readable output Design useful report values for planning, status, artifact inventories, @@ -316,6 +384,20 @@ both are supplied, campaign-owned party selection, and independent right-side comparison selectors. Optional configuration capabilities and overrides are the next discussion topic. +### 2026-11-19 — Configuration capabilities and overrides agreed + +Accepted full applicable inspection capabilities and native overrides across +all four configuration domains, with parity across inspection, planning, and +execution. Selected verb-first `--set-app`, `--set-campaign`, `--set-session`, +and `--set-party` spellings and corresponding `--against-set-*` comparison +flags, alongside native `--set` and `--against-set`. + +Clarified that overrides have no Narratio-specific protected fields or custom +merge semantics. Identity assertions are checked against effective values after +native overrides and resolution; they do not make identity fields immutable. +Credential overrides use native typed-secret handling. Safe output and +persistence do not impose additional override restrictions. + ### Continuing the discussion For each topic, record the question, the agreed outcome, its rationale, and any