From 86ec48d2e4f129e1bef9943af1b44339050cf50a Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Thu, 19 Nov 2026 18:16:43 +0000 Subject: [PATCH] Record delivery decisions and end-to-end sprint guidance --- docs/roadmap/commandkit-notepad.md | 105 ++++++++++++++++++++++++----- 1 file changed, 88 insertions(+), 17 deletions(-) diff --git a/docs/roadmap/commandkit-notepad.md b/docs/roadmap/commandkit-notepad.md index 3263364..1cdcea8 100644 --- a/docs/roadmap/commandkit-notepad.md +++ b/docs/roadmap/commandkit-notepad.md @@ -1,6 +1,7 @@ # CommandKit migration notepad -Status: working discussion notes. Started 2026-11-19. +Status: discussion decisions recorded; ready for roadmap consolidation. +Started 2026-11-19. Narratio will become a CommandKit-native application. This notepad collects the agreed direction, open questions, and subsequent decisions before they are @@ -381,6 +382,72 @@ Include native completion for command paths, flags, static stage/scope values, and appropriate file/directory selectors. Dynamic campaign and artifact suggestions requiring configuration loading or storage access remain deferred. +### Delivery and migration guidance + +Deliver one complete native CLI cutover through a single end-to-end +implementation sprint. Optimize the work sequence and commits for efficiently +reaching the intended final state. Intermediate commits may leave the overall +application incomplete, incoherent, or noncompiling; they are not independently +shippable units and do not require standalone application validation. Do not +introduce temporary compatibility machinery merely to keep each intermediate +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, inspection, and 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, overrides across supporting +configuration domains, and Narratio-specific commands alongside standard +configuration commands. Address shared-capability gaps upstream where +appropriate rather than silently recreating CommandKit behavior locally. + +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. + +Validate the integration through representative behavioral acceptance cases: + +- Native arguments and selectors reach the intended Narratio operation. +- Inspection, planning, and execution resolve equivalent configuration + selections and overrides. +- Reports remain separate from diagnostics and preserve meaningful partial + results. +- Help and completion avoid configuration and service acquisition. +- Cancellation reaches active work, preserves completed checkpoints, and + permits terminal persistence and lock release. +- Existing consequential pipeline behavior remains protected. + +Use real CommandKit and ConfigKit with controlled external boundaries. Update +or retire tests enforcing superseded CLI conventions while retaining domain +behavior coverage. Final verification uses the repository's established checks +without requiring live services or model calls; do not duplicate upstream +generic parser or configuration tests. Dependency attribution is part of the +adoption work. + +Provide workflow-oriented release migration guidance: an old-to-new command +table plus explanations of removed shortcuts, identity/file selectors, native +flag repetition and placement, configuration scopes and 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; +release notes summarize and link to those contracts rather than duplicate the +command reference. + +Select the Narratio release number under the release policy once the final +compatibility impact is known. No version or publication action is selected by +these planning decisions. Consolidate the agreed target behavior, boundaries, +migration impact, and acceptance criteria into a feature roadmap before preparing +the detailed implementation plan. + ## Reviewed upstream baseline The initial review covered these released modules: @@ -393,8 +460,8 @@ The initial review covered these released modules: Core v0.7.0 and ckconfig v0.9.0 require Go 1.27.0; ckconfig selects ConfigKit v1.2.1. Narratio already declares those Go and ConfigKit versions. CommandKit -identifies itself as alpha. Select exact released versions when preparing the -roadmap and revisit these references if that baseline changes. +identifies itself as alpha. The core and ckconfig versions above are the initial +roadmap baseline; revisit these references if that baseline deliberately changes. Upstream references: @@ -408,20 +475,10 @@ baseline. They remain current-behavior documents until the migration lands. ## Open decisions -### Delivery and migration guidance - -Choose implementation work units that lead to one complete native cutover. -Intermediate development steps need not become a supported dual CLI. - -Once the target command/report surface is settled, identify affected examples, -operator procedures, scripts, and downstream callers. Release guidance should -map old workflows to their native equivalents and explain parsing, output, -diagnostic, and exit-status changes. Select the release version under the -repository's release policy when the compatibility impact is concrete. - -Record appropriate validation for domain behavior and CLI integration in the -eventual plan. Dependency attribution and canonical documentation updates belong -to the adoption work. No release version or publication action is selected here. +No unresolved discussion decisions are currently recorded. Public API fit +checks and detailed implementation sequencing remain preparation work for the +roadmap and subsequent plan. Release version selection remains deferred to +release preparation. ## Discussion and decision record @@ -502,6 +559,20 @@ pipeline cleanup. Accepted static and filesystem completion, with dynamic campaign/artifact suggestions deferred. Delivery and migration guidance remain open. +### 2026-11-19 — Delivery and migration agreed + +Accepted one complete native cutover, the reviewed release baseline, explicit +public API fit checks, domain-behavior preservation, focused integration +verification, and workflow-oriented migration guidance. Release version +selection and publication remain separate from planning. + +The user specified a single end-to-end implementation sprint. Intermediate +commits need not leave the overall application coherent or compilable; their +purpose is to support efficient progress toward the final state. Coherence, +compilation, and full validation are required at completion, without imposing +independently shippable or fully validated intermediate milestones. All +currently discussed decision areas are settled for roadmap consolidation. + ### Continuing the discussion For each topic, record the question, the agreed outcome, its rationale, and any