From 7ee362f1c3dbe7a280a4b5441023ef31d6eb6ef2 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 20 Nov 2026 00:16:42 +0000 Subject: [PATCH] Clarify configuration ownership and native inspection boundaries --- docs/roadmap/commandkit-notepad.md | 193 +++++++++++++++++++++-------- 1 file changed, 138 insertions(+), 55 deletions(-) diff --git a/docs/roadmap/commandkit-notepad.md b/docs/roadmap/commandkit-notepad.md index dd6e6a5..0a7529b 100644 --- a/docs/roadmap/commandkit-notepad.md +++ b/docs/roadmap/commandkit-notepad.md @@ -35,10 +35,18 @@ Use the standard inspection capabilities where they apply to Narratio's configuration. Generated help and shell completion belong in the direction for the cutover. -Narratio continues to own pipeline orchestration, configuration-domain -resolution, artifact selection, manifests, resume, publishing, restore, and -cleanup. CommandKit owns CLI mechanics and presentation through its public -APIs. Application-owned declarations and providers connect those boundaries. +ConfigKit owns configuration policy and the lifecycle through the final, +fully resolved configuration handoff. Narratio supplies its configuration +schema, domain defaults, validation, and genuine configuration-resolution +rules through ConfigKit's supported extension points. Those callbacks operate +within ConfigKit's lifecycle and provenance model. + +Narratio owns interpreting the handed-off configuration and using it for +pipeline orchestration, artifact selection, manifests, resume, publishing, +restore, and cleanup. CommandKit owns CLI mechanics and presentation; +`ckconfig` exposes ConfigKit's inspection features through native adapters. +Narratio provides neutral command declarations, selection, and acquisition +wiring rather than an intervening configuration or inspection policy layer. Keep `ckprompt` and direct PromptKit engine ownership outside this migration. Narratio delegates prompt execution to Scriptorium. Prompt-requirements @@ -46,6 +54,29 @@ inspection and early pipeline dependency checks remain separate feature work using an eventual Scriptorium external contract. CommandKit adoption can proceed independently. +### Configuration handoff and domain interpretation + +The completed ConfigKit result is authoritative configuration. Consume it +without post-handoff mutation. Any genuine configuration defaulting, +normalization, or resolution must complete within ConfigKit's supported +lifecycle before handoff, with native evidence. If a required capability is +missing, identify the specific upstream gap instead of implementing a second +configuration system in Narratio. + +Domain interpretation produces separate domain objects. For example, Narratio +can interpret artifact-family declarations and a party roster to produce a +concrete artifact catalog, execution plan, and publication actions. It must +not write those products back into the resolved configuration or present them +as a replacement effective configuration. Domain derivation remains Narratio's +responsibility; it does not need to be moved into configuration callbacks merely +to appear in standard inspection output. + +Standard inspection uses the genuine ConfigKit result through native +`ckconfig` adapters. Do not construct a separate effective inspection document, +combine it with another result's authoring evidence, or add custom path or +provenance reconciliation. Native inspection and override semantics are +upstream contracts that Narratio exposes neutrally. + ### Command organization Use one general execution command, one regeneration convenience, and command @@ -109,34 +140,42 @@ ckconfig operations, with the view defined below. Expose four scopes corresponding to Narratio's configuration domains. Use `app` as the native default scope. -| Scope | Effective configuration | +| Scope | Native ConfigKit configuration result | | --- | --- | -| `app` | Pipeline configuration, including campaign-dependent artifact expansion and generated publish rules | +| `app` | Resolved application/pipeline configuration | | `campaign` | The selected campaign's settings | -| `session` | The selected session's settings, including applicable campaign defaults | -| `party` | The canonical party roster selected by `--party-file` or the campaign default | +| `session` | The selected session's settings, with applicable configuration defaults resolved within ConfigKit's lifecycle | +| `party` | The party configuration selected by `--party-file` or the campaign default | -Use effective values for `show` and `diff`, native provenance for `sources` and -`explain`, and domain validation for `validate`. Inspection reflects imports, -overlays, inheritance, defaults, and applicable Narratio resolution. A separate -raw-versus-resolved mode is not part of the initial design. +Expose standard `show`, `diff`, `sources`, `explain`, and `validate` behavior +through native `ckconfig` adapters for each scope's ConfigKit result. Effective +values, provenance, history, validation findings, and path behavior come from +that result and the upstream integration. Narratio supplies domain validation +through the supported ConfigKit lifecycle, not a separate inspection policy. -`app` show/diff includes the concrete artifacts and publish rules execution -receives. Provenance must distinguish authored and derived values accurately; -a generated artifact must not appear to have been literally declared in a -source file. Use native evidence without inventing source origins. +Remove the earlier requirement that app show/diff include expanded artifacts +and generated publish rules. They display and compare whatever the genuine +ConfigKit result contains. Domain products derived after handoff are not added +to standard inspection, and differences between those products are not added +to native configuration comparisons. A separate raw-versus-resolved mode is +not part of the design. -Keep `config artifacts` as a focused catalog of definitions and dependencies -derived from the same effective pipeline. `session artifacts SESSION` reports -session-specific availability and publication state. Future input discovery can -extend the configuration catalog separately from this migration. +Keep `config artifacts` as a Narratio-owned domain catalog of concrete artifact +definitions and dependencies derived from the handed-off configuration and +selected party. Planning commands describe derived execution and publication +work. These domain views do not redefine ConfigKit's effective configuration. +`session artifacts SESSION` reports session-specific availability and +publication state. Future input discovery can extend the domain catalog +separately from this migration. -Acquire only the context needed for the selected scope. Party-driven pipeline -expansion requires the selected campaign and party; effective session settings -require the session and applicable campaign context. Campaign inspection does -not require a session. Scope discovery and help do not load configuration. -Report missing required context explicitly rather than presenting a partially -resolved view as complete. +Acquire only the context needed for the selected scope's native configuration +load. Applicable campaign defaults for session configuration resolve before +handoff. Standard app inspection does not acquire campaign/party context solely +to expand runtime artifacts. Domain catalog and planning operations acquire +the additional context needed for domain work. Campaign inspection does not +require a session. Scope discovery and help do not load configuration. Report +missing required context explicitly rather than presenting an incomplete load +as a complete configuration result. Retain CommandKit's operation-specific `--scope all` behavior. Do not silently omit a selected scope whose required context is missing. @@ -209,10 +248,11 @@ configuration scopes: - 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. +These capabilities use upstream operations and evidence from the scope's native +result. Filtering findings changes presentation, not validation success. +ConfigKit owns the relationship between effective, historical, explainable, +and overridable paths; Narratio does not add a writable-path registry, +reinterpret explicitness, or manufacture provenance for domain products. ### Native application configuration overrides @@ -248,18 +288,18 @@ authoring and provenance differ from late CLI overrides. This decision removes the need to compose overrides across supporting domains or reconcile generic and explicitly targeted override flags. -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 +ConfigKit applies overrides after typed defaults and decoding, before its +resolution and semantic validation callbacks. 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 application configuration accepted by its 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. +Override paths and acceptance follow ConfigKit's native input semantics for +application configuration. Standard inspection does not promise that every +displayed path accepts an override. Narratio passes explicit assignments to +ConfigKit without translating runtime catalog paths into input paths or +patching domain products after handoff. Overrides leave source configuration files unchanged. Normal run metadata and prepared configuration may record the effective settings through established @@ -369,7 +409,8 @@ Keep startup lightweight and acquire dependencies only when needed: 1. Parse the command and validate syntax and input combinations. 2. Bootstrap credentials when the operation needs configuration. -3. Resolve the required configuration and domain context. +3. Load the required configuration through ConfigKit's completed lifecycle, + then derive the domain context needed by the operation. 4. Acquire execution resources and perform the operation. 5. Finalize domain state, release resources, present the result, and return the outcome. @@ -412,30 +453,41 @@ commit working. Report intermediate status accurately, use focused checks when useful, and require a coherent, compilable, fully validated final application. Useful work boundaries are core invocation/domain commands; configuration -scopes, file selection, inspection, and app overrides; reports, diagnostics, -cancellation, and completion; and integration verification, removal of -superseded CLI machinery, and documentation. These are organizational -boundaries, not mandatory buildable milestones or a supported dual interface. -The subsequent implementation plan determines the most efficient order and -dependencies. +handoff, native scopes and inspection, file selection, and app overrides; +reports, diagnostics, cancellation, and completion; and integration +verification, removal of superseded CLI machinery, and documentation. These +are organizational boundaries, not mandatory buildable milestones or a +supported dual interface. The subsequent implementation plan determines the +most efficient order and dependencies. Use CommandKit v0.7.0 and ckconfig v0.9.0 as the initial roadmap baseline. Review relevant public contract changes before deliberately selecting a later -release. Before finalizing implementation details, verify public API support -for effective views with truthful provenance and Narratio-specific commands -alongside standard configuration commands. Address shared-capability gaps -upstream where appropriate rather than silently recreating CommandKit behavior -locally. +release. Before finalizing implementation details, verify native ConfigKit +loader and `ckconfig` adapter integration and composition of Narratio-specific +commands alongside standard configuration commands. Address required upstream +capability gaps upstream rather than compensating with custom effective views, +provenance reconciliation, or replacement configuration behavior. + +Remove the current post-load configuration mutation and the split between +runtime inspection snapshots and authoring evidence. Separate domain products +from the authoritative configuration handoff while preserving their intended +processing behavior. Do not retain those inspection projections merely to +reproduce existing output. Safe persisted configuration and domain artifacts +remain useful records, but do not replace the result used by native inspection. Retain Narratio's stage sequencing, resume authority, publication semantics, -restore safety, and cleanup rules. Changes required for the agreed overrides, -reporting, and cancellation behavior are in scope. Workspace reorganization, -downstream-tool adoption, and Scriptorium requirements inspection remain -separate work. +restore safety, and cleanup rules. Changes required for the agreed ownership +boundary, inspection, overrides, reporting, and cancellation behavior are in +scope. Workspace reorganization, downstream-tool adoption, and Scriptorium +requirements inspection remain separate work. Validate the integration through representative behavioral acceptance cases: - Native arguments and selectors reach the intended Narratio operation. +- Standard configuration commands expose genuine ConfigKit results through + native adapters, with upstream value, provenance, and path semantics. +- Domain catalog and plan generation consume handed-off configuration without + modifying it or replacing the native inspection result. - App inspection, planning, and execution resolve equivalent application configuration selections and overrides. - Explicit party-file selection consistently feeds roster inspection, derived @@ -460,7 +512,8 @@ adoption work. Provide workflow-oriented release migration guidance: an old-to-new command table plus explanations of removed shortcuts, identity/file selectors including party-file selection, app-only field overrides, native flag repetition and -placement, configuration scopes and comparisons, structured output, diagnostic +placement, native configuration inspection and its distinction from domain +catalogs and plans, configuration comparisons, structured output, diagnostic visibility, exit classifications, and cancellation. Identify affected examples, operator procedures, scripts, and downstream callers. Update canonical documentation and maintained examples as implementation lands; @@ -505,6 +558,10 @@ checks and detailed implementation sequencing remain preparation work for the roadmap and subsequent plan. Release version selection remains deferred to release preparation. +The next discussion is whether and how to crystallize the agreed configuration +ownership boundary in an ADR. The boundary is settled; an ADR has not yet been +prepared. + ## Discussion and decision record ### 2026-11-19 — Initial direction @@ -531,6 +588,10 @@ workflow. Configuration scopes and views are the next discussion topic. ### 2026-11-19 — Configuration scopes and views agreed +The later configuration-ownership revision supersedes the expanded app +inspection view recorded below. The four scopes remain, with standard +inspection exposing their native ConfigKit results. + Accepted `app`, `campaign`, `session`, and `party` scopes, with `app` as default. Show/diff exposes effective values and source/explanation operations use native provenance. Concrete artifacts remain visible in the effective pipeline and the @@ -625,6 +686,28 @@ to meaningfully reduce complexity while retaining native app override behavior and ordinary file-backed configuration composition. This revision supersedes the earlier all-domain override and campaign-only party-selection decisions. +### 2026-11-19 — Configuration ownership and native inspection clarified + +Accepted ConfigKit's completed result as authoritative configuration, with +Narratio's schema, defaults, validation, and genuine resolution rules supplied +through ConfigKit's supported lifecycle. Narratio consumes the handoff without +mutation and produces separate domain catalogs, plans, and execution objects. +CommandKit's `ckconfig` integration neutrally exposes the native ConfigKit +features; Narratio does not reinterpret or improve their inspection semantics. + +Superseded the requirement that app show/diff contain expanded artifacts and +generated publish rules. Standard inspection uses native results and adapters; +domain catalogs and planning commands expose the work derived from those +results. Remove post-load configuration mutation and separate inspection +snapshots rather than reconcile them with retained authoring evidence. Native +path and override semantics remain upstream contracts, not a Narratio design +problem. + +The user identified the configuration/inspection split as a boundary violation. +The agreed correction is to restore ownership, not add machinery to make +different representations appear consistent. A potential ADR recording this +boundary is the next discussion topic. + ### Continuing the discussion For each topic, record the question, the agreed outcome, its rationale, and any