# CommandKit adoption implementation plan ## Scope and authority Implement the agreed target in [CommandKit adoption](commandkit.md), following [ADR 0003](../adr/0003-assign-configuration-ownership.md). This plan is for a Luna coding agent implementing the stages in sequential order during one end-to-end sprint. Each stage is one focused implementation prompt. The inspected baseline is commit `bcbfc0f`. Narratio already uses ConfigKit v1.2.1 and declares Go 1.27.0. Its handwritten command boundary, post-load configuration mutations, replacement inspection snapshots, and successful-only run summaries are the migration inputs. Select these released modules directly: | Module | Version | Upstream source commit | | --- | --- | --- | | `go.maximumdirect.net/commandkit` | v0.7.0 | `b57bfe176cff05a892e6cb07ebb5f350239e55d4` | | `go.maximumdirect.net/ckconfig` | v0.9.0 | `9962368f0c1ea1f6ad010638e94621091105d745` | | `go.maximumdirect.net/configkit` | v1.2.1, retained | `51ef3144158db1a09fabdbd1c7ae59908c84923b` | Use the pinned [CommandKit consumer guide](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/b57bfe176cff05a892e6cb07ebb5f350239e55d4/docs/consumers/guide.md), [CLI contract](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/b57bfe176cff05a892e6cb07ebb5f350239e55d4/docs/cli.md), [ckconfig contracts](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/9962368f0c1ea1f6ad010638e94621091105d745/integrations/ckconfig/contracts.go), and [ConfigKit consumer guide](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/docs/consumers/README.md) as upstream authorities. The ckconfig release's own module metadata and [release note](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/9962368f0c1ea1f6ad010638e94621091105d745/integrations/ckconfig/docs/releases/v0.9.0.md) confirm the selected pairing; the earlier core guide's integration-version table predates that coordinated release. Read the released public declarations when details are needed. Sibling checkouts are optional reference material, not build or test prerequisites. ## Working rules - Start with [Development](../development.md), [Agent Policy](../policy/agents.md), and the roadmap. Read applicable architecture, testing, documentation, OSS, and release policies through the development guide. Reuse unchanged policies already read. Prefer the codebase graph for code discovery; confirm current source when indexed locations are stale. - Intermediate stages may be incomplete, noncompiling, or have tests awaiting later stages. Record that accurately. Do not build compatibility layers, parallel dispatchers, replacement configuration views, or temporary no-op operations merely to keep intermediate commits green. - Commit each completed nonempty unit using a concise plain-English message. Add focused tests with their owning behavior. Use real CommandKit and ConfigKit; replace only external boundaries, clocks, randomness, and other sources of nondeterminism where needed. Keep default tests offline and independent of installed downstream applications, credentials, and paid APIs. - Preserve consequential stage ordering, invalidation, checkpoint reuse, publication, remote locks, restore confinement, workspace modes, and cleanup behavior. This CLI cutover does not authorize workspace reorganization, downstream adapter upgrades, session migration machinery, or new retention rules. Keep the pending Audita and workspace roadmaps separate. - Preserve existing operation-specific options unless the roadmap replaces them. Adopt upstream flag placement, repetition, help, reporting, and outcome behavior; retire tests enforcing superseded parser conventions. Avoid exact formatting or error-wording promises unless the contract actually owns them. - Use concise, affirmative documentation. Keep current contracts in their canonical owners and proposed implementation status here. The migration discussion is historical context; the consolidated roadmap owns decisions. ## Implementation boundaries Use a small number of concrete data boundaries, adapting the existing owners: - **Loaded configuration:** retain actual typed ConfigKit results for pipeline, campaign, session, and party. Complete configuration defaults, normalization, and validation inside supported load callbacks. Consume completed values without mutation; no defensive-copy framework or new public YAML schema is required to express this ownership. - **Derived domain context:** hold the selected roster, players projection, concrete artifacts, family origins, resolved dependencies, and publication actions separately. Existing `config.Config`, `stage.Env`, and `artifacts.EffectiveArtifactSet` can carry or reference these products. Keep CommandKit types at the application/process boundary. - **Invocation selection:** retain explicit presence for identity, file, overlay, and secrets selectors. Share acquisition between native inspection and domain commands, with invocation-owned state and independent comparison inputs. - **Operation results:** domain operations return useful values and errors; application handlers present public report DTOs with CommandKit. Use stable JSON field tags for YAML/JSON agreement and keep manifests, credentials, and internal dependency containers out of public reports. Use native automatic report presentation, including YAML for structured values, and `--format text|yaml|json`. Add a text template only when representative output demonstrates a substantial readability benefit, using the same report data. Report format remains independent of generated artifact formats. These are responsibility boundaries, not a requirement to create four new packages or a generic command, configuration, or event framework. ## Stage 1: Install the native application boundary **Completed.** Installed the pinned native modules, caller-context/stream entry point, native help/version, supplied-value selector declarations, and outcome classification with preserved causes. Native boundary tests, release-script checks, documentation checks, and repository-wide compilation pass with Go 1.27.4. Domain command invocation tests await their scheduled native handlers; the handwritten dispatcher is no longer an execution path. Read: roadmap command organization and invocation lifecycle; upstream consumer guide sections on core commands and invocation reporting; `internal/app/commands.go`, `command_dependencies.go`, `version.go`, and `cmd/narratio/main.go`. 1. Add the selected CommandKit and ckconfig requirements, retaining ConfigKit v1.2.1 and the existing Go minimum. Use released modules, without local filesystem replacements or an upstream workspace dependency. 2. Establish the native application construction and execution entry point in `internal/app`. Supply Narratio's existing build version through `commandkit.Identity`; use native help and version. Accept a caller context and caller-owned streams, and return the native outcome to the process boundary. Update the version-checking consumer in release tests/scripts for the native version representation when its implementation changes. 3. Establish typed selection inputs and reusable native flag declarations using `Supplied` presence. Domain checks on combinations belong in `CheckInput` or the appropriate post-load operation, not token scanning. Other stages add the actual command handlers; no second legacy dispatch path is needed. 4. Establish a small application outcome adapter: public ckconfig classification for configuration errors, usage outcomes for identifiable Narratio input errors, and operational outcomes otherwise. Preserve wrapped/joined causes and operational precedence. Present terminal failures once. Check: native root/group help and version can run with deliberately unusable configuration and external dependencies; invalid invocation returns status 2. Construction itself performs no credential bootstrap or acquisition. ## Stage 2: Retain authoritative pipeline and campaign load results **Completed.** Pipeline and campaign loaders expose their actual typed native results, retaining structured load failures and recorded resolution evidence. Campaign configuration checks now run in its definition lifecycle; resource existence remains a domain concern. Removed duplicated pipeline metadata and post-load dependency merging. Native result/import/overlay checks and builds pass with Go 1.27.4. Two existing dependency tests await the separate concrete catalog in Stage 4; their expectations remain intact. Read: roadmap ownership; `internal/config/pipeline_configkit.go`, `document_configkit.go`, `load.go`, `effective_digest.go`, and the upstream ConfigKit sections on recorded application resolution and inspection. 1. Expose retained pipeline and campaign ConfigKit results through typed loaded context/accessors suitable for `ckconfig.FromConfigKit`. Keep load errors and native diagnostics available rather than flattening them into text. 2. Move genuine pipeline defaults and normalization currently performed after `configkit.Load` into its definition lifecycle, recording changes with native helpers. Audit `finalizeLoadedPipeline` and dependency/default handling; concrete family expansion and campaign-dependent work stay outside it. 3. Put configuration-owned campaign checks in the campaign definition's validation callback. Keep input-file existence, remote readiness, and artifact execution checks with their domain operations. 4. Retain source-relative resource semantics using native metadata during resolution. Do not add import/source-authoring acceptance rules. Remove metadata bookkeeping rendered redundant by the retained results; later stages remove the replacement inspection path after its consumers move. Check: loaded values and native show/explain agree for defaults, imports, overlays, and explicit values. Loading an app pipeline does not require a party or mutate its completed result to make derived artifacts appear. ## Stage 3: Complete session defaults within ConfigKit's lifecycle Read: `internal/config/document_configkit.go`, `load.go` and `mergeCampaignSession`, `document_render.go`, campaign/session validation, and ConfigKit's resolution recording and presence contracts. 1. Pass the selected campaign's applicable configuration defaults into the session definition before loading finishes. Resolve effective campaign identity and stable session input defaults there, using presence and domain rules rather than a post-load zero-value merge. Preserve supported explicit empty/null/false/zero semantics and validate effective values normally. 2. Record defaults and normalization with the native helpers and truthful campaign context. Keep the session's actual load as its inspection result; do not simulate a combined source inventory or manufacture a second result. 3. Move concrete-session/template and configuration validation into the appropriate supported callbacks. Retain identity/previous-session assertions as explicit request checks with typed errors where necessary. Assert final identities after resolution; configuration-derived defaults must not conceal a supplied mismatch. 4. Replace `mergeCampaignSession`'s mutations with derivation of stable-input references from the completed configuration and selected sources. Preserve useful standalone campaign/session renderers and their authoring semantics; they are materialization services, not alternative inspection authorities. Check: native session show, planning, execution, and standalone initialization agree on effective defaults and identity. Imports retain correct resource bases; no later operation changes the captured session or campaign result. ## Stage 4: Derive party products and concrete artifact catalogs Read: `internal/config/party*.go`, `artifact_families.go`, `artifact_catalog.go`, the family declarations in `config.go`, and the roadmap's ownership boundary. 1. Retain the actual party ConfigKit result and select either an explicit party file or the campaign-default file. A CLI-relative explicit file uses the invocation directory; missing or invalid explicit selections fail exactly. Selection does not rewrite the campaign's configured party field. Update stable-party references and `validateResolvedPartyInputs` so its current campaign-only source assertion accepts the agreed explicit selection. 2. Turn family expansion into domain derivation from the completed pipeline and selected canonical roster. Return concrete definitions, family/member origins, resolved inputs/dependencies, and expanded publication rules separately. Keep declarations in the authoritative pipeline configuration. 3. Derive the players projection from the same selected roster. Retain current family ordering, member-variable semantics, collision and dependency checks, and family/concrete artifact selection meanings. Validate these products when deriving the catalog, rather than requiring them for app inspection. 4. Remove family-expansion flags and generated catalogs stored as mutations of `PipelineConfig`. Reuse existing catalog/model types where appropriate rather than adding a second family engine or a generic workflow abstraction. Check: deriving catalogs for two different parties from one loaded pipeline does not affect either the native result or the other catalog. Explicit roster selection reaches family members and players; collisions remain errors. ## Stage 5: Wire derived products through planning and execution Read: `internal/app/analyze_artifacts.go`, `runner_runtime.go`, `bounded_prerequisites.go`, `internal/stage/stage.go`, `analyze*.go`, `trim.go`, and the artifact catalog/resolution owners. 1. Carry the derived catalog and roster products through the invocation context, `RunOptions`/`stage.Env`, effective artifact registration, and selected-target resolution. Treat loaded configuration as read-only. 2. Update analysis work planning, dependency/input resolution, previous-session requirements, and relevant adapter composition to consume concrete domain definitions rather than expecting expansion inside pipeline configuration. 3. Update all stage consumers, including built-in artifact handling and trim's Scriptorium use, through their actual dependencies. Preserve full-bundle extraction and analysis-specific target closure semantics. 4. Keep one shared derivation path for catalog listing, planning, execution, and session artifact inspection. Remove old paths that expand configuration on demand or implicitly select a different roster. Check: a character-family pipeline executes concrete members through the real planner with fake external adapters; dependencies, family selections, and selected-party players match the separately derived catalog. Bounded execution still composes only the collaborators it needs. ## Stage 6: Preserve preparation, publication, and semantic resume evidence Read: `internal/stage/prepare*.go`, `publish*.go`, `semantic_contracts*.go`, the prepared-input and remote publication/restore contracts, and `internal/config/effective_projection.go` and `effective_pipeline.go`. 1. Pass derived publication actions to publish selection and lock validation rather than inserting them into pipeline configuration. Preserve source IDs, destinations, selected-artifact filtering, remote lock behavior, and the immutable commit/current-pointer boundary. 2. Adapt prepared party/players, campaign/session YAML, pipeline snapshots, and required domain records to the new data flow. A secret-safe serialization DTO may remain for preparation or persistence where it preserves required credential references and effective inputs. It must not become a fabricated native inspection result. Persist additional domain evidence only where an existing preparation/resume consumer needs it. 3. Update stage/artifact semantic projections to read the same concrete products used by execution. Preserve result-affecting evidence; overlay labels, source arrangement, provenance, and a whole-configuration digest remain informational rather than blanket invalidation keys. 4. Remove `newPipelineInspection`, its `NoSource` freeze, and the separate authoring-versus-final inspection machinery when their consumers have moved. Reuse safe digest/materialization code where still needed, separating it from native show/diff instead of deleting useful persistence indiscriminately. Check: prepared inputs and publication round-trip through existing restore fixtures; locked/current outputs keep their behavior. Equivalent authored configurations reuse valid work, while changed concrete prompts/variables, dependencies, roster-derived inputs, or publish destinations affect the relevant semantic checks. Inspection never depends on persisted domain snapshots. ## Stage 7: Share lazy identity and source acquisition Read: `internal/app/config_loader.go`, `campaign_config_path.go`, `session_config_path.go`, `remote_session.go`, `command_dependencies.go`, and the roadmap's selector and session-acquisition sections. 1. Replace positional strings passed among loaders with invocation-owned typed selections. Distinguish `--campaign` identity from `--campaign-file`, and inspection `--session` identity from `--session-file`. A supplied identity and file are complementary: load the exact file and assert the effective ID. Remove the old campaign-ID/file mutual exclusion. Session domain commands retain their positional ID; file-only inspection may obtain its ID from data. 2. Acquire supporting configuration only as needed. App needs no campaign/party expansion; campaign needs no session; an explicit party file needs no session. Resolve campaign defaults when a session load requires them. Keep the same selections and acquired results for an operation rather than reloading the pipeline during session resolution. 3. Share exact-file, local-discovery, and remote-discovery acquisition between inspection and execution. Only local absence enables remote fallback, with a known session identity. Prefer remote authored session-root configuration; use the committed prepared snapshot only on authored-object absence. Preserve checksum/size and pointer-selected snapshot checks already required. 4. Keep read-only acquisition free of workspace creation, restore, manifest updates, execution locks, and stage adapters. Remote reads are permitted. Preserve underlying storage/access/parse errors and source labels for local, remote-authored, and committed-snapshot inputs. Release temporary resources on success and failure and retain cleanup errors. 5. Bootstrap secrets once per reached invocation after parsed-input checks and before typed loading, using the existing explicit/default directory contract. Invocation caches may share already acquired context, but must not conflate different files, overlays, campaigns, or comparison sides. Check: exact-file errors and ID mismatches never fall back; only absence does. Remote inspection leaves no runtime session state. A selected party file is used consistently, and app-only acquisition avoids unrelated inputs/services. ## Stage 8: Expose genuine configuration scopes through ckconfig Read: upstream `Suite`, `Selector`, `FromConfigKit`, `AdaptDiagnostics`, and the native configuration CLI contract; Narratio's old `config_commands.go`. 1. Register `app`, `campaign`, `session`, and `party` through `ckconfig.FromConfigKit`, making `app` the default. Supply actual results and native load errors from Stages 2–7. Expose all applicable standard operations, including native path show/discovery, sources, history/explanation, and detailed validation findings/filters. 2. Bind custom selectors only to scopes needing them. Native `--config` always selects the pipeline root and `--overlay` its overlay; neither changes meaning with scope. `--party-file` selects roster input, not an app override. Use `Suite.CheckInput` for scope request checks and shared lazy state for reached acquisitions. Keep factories free of side effects. 3. Retain upstream per-operation aggregate-scope behavior. Missing required context fails visibly rather than dropping a scope. Filtering displayed findings does not turn invalid configuration into success. 4. Remove Narratio-owned show/source/explanation renderers and synthetic path/provenance reconciliation after replacement. `config artifacts` moves to the domain catalog command in Stage 11; the generated config group needs no custom child-command extension. Check: native commands inspect each scope with real imported configurations; show values, path explanations, and diagnostics come from that scope's real result. Scope discovery and help cause no bootstrap, loading, or storage calls. ## Stage 9: Add independent comparisons and app inspection overrides Read: upstream `ComparisonSide`, `Selector.AgainstName`, native override/diff contracts, and Narratio's old `config_diff.go`. 1. Bind `--against-campaign`, `--against-campaign-file`, `--against-session`, `--against-session-file`, and `--against-party-file` for their applicable scopes alongside native `--against-config` and `--against-overlay`. 2. Resolve each side from its own fresh typed input and normal defaults. An omitted right-side selector does not inherit its left counterpart. Party defaults follow that side's campaign. Share only invocation-wide services such as credential bootstrap and correctly keyed acquisitions. 3. Pass native `Selection.Overrides` to the app ConfigKit load and advertise `Scope.Features.Overrides` only for app. Let ckconfig parse `--set` and `--against-set`; ConfigKit applies them during the load. Keep native ordering, merge, path, explicitness, secret, and conflict semantics. 4. Use native comparisons and report shapes, including detailed output and `diff --check` status 3. Remove overlay-only/same-campaign restrictions and the final-domain snapshot diff. Other scopes and aggregate inspection reject overrides according to ckconfig's advertised capabilities. Check: independent files/campaigns/rosters on each side, right-side defaults, safe hidden values, and native app override behavior. Execution and planning declarations expose no field overrides; comparison results do not mutate inputs. ## Stage 10: Replace run and regeneration command wiring Read: `internal/app/run.go`, `bounded_run.go`, `regenerate_artifacts.go`, `planner.go`, analysis-selection helpers, and the roadmap command tree. 1. Declare `run SESSION` and `artifacts regenerate SESSION` as typed native commands. Bind common file/identity selectors, overlay/secrets selection, force, and repeatable analysis artifact values. Remove the compatibility `--session-id` path. Retain previous-session assertion support where applicable. 2. Extend the shared bounded-plan request with `--stage`: translate it to equal inclusive endpoints and reject combining it with explicitly supplied `--from` or `--through`. Preserve full-range defaults, endpoint validation, and independent force. Check configuration-independent combinations before bootstrap; check configured targets after catalog derivation. 3. Regeneration calls the same typed execution operation with forced extract through analyze. Its public options select configuration and analysis targets; fixed range/force are not independent user options on that command. Never construct and reparse a synthetic argv string. 4. Return one public run report containing identities, selected stages, executed/reused outcomes, artifacts, and completion. Stage 15 completes failure reporting. Use native outcomes and presentation; remove the `run-stage`, `analyze`, `publish`, and `regenerate-artifacts` command routes. Check: single-stage, full/ranged execution and force map to the same planner. Regeneration always includes the complete extraction bundle and never publish; `--artifacts` narrows analysis targets/prerequisites, not Notarius lanes. Artifact selection retains its existing analyze/publish consumer and family rules. ## Stage 11: Expose planning and the configured artifact catalog Read: `internal/app/plan.go`, `analyze_artifacts.go`, old config artifact listing, and the shared domain products from Stages 4–6. 1. Declare `session plan SESSION` with the same stage/range, force, artifact, and context selection semantics as run. Use the shared pure decision and analysis work planners; keep planning read-only with cloned manifest state. 2. Include derived publication work as well as stage execution/reuse reasons, selected analysis targets, prerequisite work, and reuse. Describe decisions from the planner without predicting unknown output identities or claiming execution occurred. 3. Declare `artifacts list` as a domain catalog requiring the context needed for family derivation, but no session solely to list configured definitions. Include configured/built-in extraction and artifact sources, producers, dependencies, and family/member identities from existing catalog ownership. 4. Present public plan/catalog DTOs through native reporting. Remove the old `config artifacts` implementation and its custom inspection dependency. Check: representative plans and execution make the same reuse/selection decisions. Listing family members leaves the app result unchanged; neither operation initializes a runtime workspace or stage adapters. ## Stage 12: Convert read-only session inspection commands Read: `operator_session_validate.go`, `operator_status.go`, `operator_artifacts_list.go`, `operator_findings.go`, and `operator_inspection.go`. 1. Declare `session validate SESSION`, `session status SESSION`, and `session artifacts SESSION` with shared selectors and their relevant existing options, including optional remote artifact inspection. 2. Separate inspection operations from handwritten parsing/text output. Return structured findings, local stage state, artifact availability, and available remote publication/lock information. Preserve pointer-selected remote state, declared destinations, carried-output identities, and current publish outcomes. 3. Map genuine invalid configuration to the native input classification and operational/readiness failures to operational failure. Preserve useful findings or partial inspection data on failure. Material limitations belong in the report even when informational messages are hidden. 4. Acquire only each operation's required inputs; preserve current payload-free artifact inspection and runtime-state-free preflight behavior. Check: local and remote fixtures yield structured reports with expected domain state in automatic/YAML/JSON modes. Read-only commands leave manifests and work directories unchanged and expose no credential values. ## Stage 13: Convert initialization and remote lock commands Read: `operator_session_init.go`, `operator_locks.go`, their focused tests, and the initialization/lock contracts in the current CLI and operations guides. 1. Declare `session init SESSION`; retain exactly-one output/remote target, date/title, previous-session, mutually exclusive audio choices, force, and applicable configuration/overlay/secrets selectors. Input combinations are checked before loading. It creates new session input rather than acquiring an existing session-file selection. 2. Keep native authoring-context loading, template imports, source-relative resources, invocation-relative audio CLI paths, and standalone generated YAML. Native report `--format` changes only the confirmation, not that YAML file. 3. Declare explicit `session locks list SESSION`, `add SESSION SOURCE`, and `remove SESSION SOURCE`, preserving reason, add-force, conditional generation updates, and idempotent removal. A bare locks group displays help. 4. Return concise initialization/mutation reports and a structured lock list, retaining meaningful state when an operation cannot finish. Replace raw success printing with CommandKit reporting. Check: local and remote initialization round-trips and lock concurrency semantics continue to pass. Missing target/operand combinations fail before bootstrap. File formatting is independent of report formatting. ## Stage 14: Convert restore and local cleanup commands Read: `restore.go`, `restore_plan.go`, `restore_execute.go`, `restore_report.go`, `clean.go`, and their focused safety tests. 1. Declare `session restore SESSION`, retaining dry-run, force, include-audio, and applicable context selectors. Present a public action/conflict/completion report separately from any existing persisted restore execution report. 2. Preserve pointer-bound discovery, confined paths, the shared session lock, incomplete-restore recovery marker, eligible regular-file replacement rules, and manifest-last installation. Reporting does not change restore authority. 3. Move cleanup to `session clean [SESSION | --all]`, retaining dry-run and clear-cache. Check target exclusivity and incompatible session/campaign selections for `--all` before bootstrap. Load only the context required by the chosen cleanup mode. 4. Return structured planned/completed cleanup actions and any failure context. Preserve exact deletion scope, cache opt-in, confinement, and operator choice. Retire the top-level clean route. No new directory layout or retention policy is part of this conversion. Check: dry runs do not mutate; actual restore/cleanup behavior remains protected by existing safety fixtures. Failures after completed actions report those actions accurately instead of losing all result data. ## Stage 15: Preserve partial run results and terminal failures Read: `runner.go`, `runner_stage_execution.go`, `runner_runtime.go`, `runner_finalization.go`, `run_control.go`, and manifest checkpoint contracts. 1. Refactor the runner to return a summary alongside an error after meaningful work. Initialize selected-stage reporting from the bounded plan; distinguish attempted/failed, completed, reused/self-skipped, and not-attempted work. Do not report a failed or unpersisted stage as completed. 2. Account for the current failed attempt before returning from stage execution; today an error returns an empty outcome and the caller loses that attempt. Include useful available artifacts through existing catalog/checkpoint evidence without returning raw manifests as public reports or adding a separate progress ledger. 3. Give terminal failure persistence and summary construction one clear owner across stage execution, composition, and finalization errors. Preserve durable earlier successes and current invalidation rules; join terminal-save and lock release failures with the originating error. Avoid duplicate terminal saves and duplicated failure output. 4. Finalize domain state and release resources before handlers deliver the final report. Present partial results with the failed native outcome; early input failures need no empty result. Report-write errors never undo completed work. Subject all reports to native visibility, including quiet mode. Check: fail a later stage after earlier successes and checkpoints; the returned summary/report and manifest agree and a retry reuses valid work. Inject terminal save and lock-release failures and verify underlying causes remain inspectable. ## Stage 16: Propagate process cancellation and finalize resumable state Read: process entry, runner lifecycle, HTTP/subprocess adapter cancellation, restore finalization, and CommandKit's invocation-context/outcome contracts. 1. Create a signal-aware process context for interrupt and termination and pass it through native execution to configuration acquisition, storage, planning, stages, and existing HTTP/subprocess operations. Check around synchronous native loads where their public API has no context parameter. Keep the application entry injectable for deterministic tests. 2. Check cancellation before scheduling another stage or unit of work and use existing adapter shutdown paths. Wait for started workers to settle before closing reporting handles or returning their final result. 3. Attempt terminal local manifest persistence even when the operation context is canceled; a narrowly scoped `context.WithoutCancel` for that final local save can use the existing store. Keep active I/O and adapters on the canceled operation context. Always release acquired local resources and retain persistence/shutdown errors alongside the original cancellation. 4. Preserve successful speaker/artifact checkpoints, report a meaningful partial result, and return operational status 1. Cancellation never schedules the cleanup stage or deletes resumable work. Abrupt process death has no added finalization guarantee. Check: controlled mid-operation cancellation reaches an adapter, starts no later work, retains successful checkpoints, attempts a terminal save, and releases the lock. A subsequent invocation can resume. Include a failed-save case and representative process signal wiring without timing-based sleeps. ## Stage 17: Centralize native console diagnostics and stage progress Read: CommandKit reporting/visibility contracts, `internal/logging`, `runner_runtime.go`, `runner_stage_execution.go`, and application print/log sites. 1. Route console messages through the invocation's CommandKit reporter. Keep any stage-facing reporting seam small and Narratio-owned; the application adapts it to CommandKit. Avoid a general event bus or backend-specific types in stage/domain contracts. 2. Emit Progress for stage start, completion, self-skip, and reuse. Emit Info for selected configuration, sources/destinations, and decision context; retain warnings/debug with their native severities. Replace the runner's default direct `os.Stderr` logger so it cannot bypass reporting selection. 3. Keep failures in terminal native outcomes and material conditions in report data. Preserve existing captured subprocess/file diagnostics and safe log locations. Do not replay downstream streams automatically or print secrets, transcript bodies, or prompt bodies as incidental messages. 4. Rely on native quiet, verbose, debug, progress, and format behavior, including explicit boolean settings and upstream repetition/placement. Console debug selection does not turn on downstream debug capture or alter retention. Check: ordinary mode, verbose-only, progress-only, their combination, quiet, and debug produce the expected channel categories without changing the report data or execution selection. Check semantic messages/categories, not complete incidental text snapshots. Terminal failures appear once, including in quiet. ## Stage 18: Add useful sub-stage progress Read: existing audio acquisition/materialization, `internal/stage/transcribe.go`, `analyze*.go`, checkpoint reconciliation, and the reporting seam from Stage 17. 1. Emit Progress at actual audio download starts/completions, individual speaker transcription completions, configured artifact completions, and reuse of speaker/artifact work. Connect to the existing operation owners rather than estimating progress from logs or introducing another durable ledger. 2. Keep source identity, selected paths, and decision explanations as Info where they are context rather than work progress. Fine-grained progress requires `--progress` alone; there is no extra verbose-progress mode. 3. Handle concurrent worker submissions through the invocation-safe seam and ensure reporting is finished before invocation finalization. Concurrent completion order need not become a deterministic public ordering contract. Preserve checkpoint validation and actual completion timing semantics. Check: fake downloader/transcriber/artifact adapters demonstrate progress-only download, speaker, artifact, and reuse events. Combining verbose and progress adds contextual diagnostics while stdout remains one final report. No new checkpoint schema, per-invocation history, or progress-output file is needed. ## Stage 19: Finish completion and remove superseded CLI machinery Read: native shell completion contracts, the finished command declarations, and the old session/flag/help/rendering helpers and their callers. 1. Install native completion for `narratio`, with static stage/scope choices and applicable file/directory hints. Supply hints at flag/argument declarations; dynamic campaign/artifact completion remains deferred. 2. Delete unused handwritten dispatch, `flag.FlagSet` command parsing, singleton/repetition enforcement, positional-session reconciliation, manual usage/help, legacy command wrappers, custom inspection/diff renderers, and obsolete output helpers. Keep genuinely reused domain validation and safe persistence helpers. Trace callers before deleting shared code. 3. Remove old command aliases/routes and duplicate session identity flags. Preserve native group help. Update or consolidate tests so real native invocation coverage replaces private-parser or exact-output expectations. 4. Confirm help, version, completion generation/query, and `config scopes` remain lazy even with invalid files, unavailable secrets, and failing external dependency factories. No code path should bootstrap before these operations. Check: every command path in the roadmap is installed and removed paths are absent. Native completion emits static/file hints without acquisition. Search for obsolete routes/parsers and classify any remaining matches as current contracts, deliberate migration guidance, or immutable historical records. ## Stage 20: Update canonical documentation and migration workflows Read: documentation and OSS policies, roadmap migration requirements, current CLI/config/operations/internal owners, maintained examples, and release scripts. 1. Rewrite the CLI reference for the finished tree, selectors, native flag placement/repetition, stage selection, inspection capabilities/overrides, report fields, visibility, completion, and outcome statuses 0/1/2/3. Document structured output from report DTOs without a schema-version system. 2. Update configuration and internal documentation for genuine native results, lifecycle defaults, separate catalog/plan/publication derivation, and semantic resume evidence. Revise obsolete current-policy references such as standalone `publish` to `run --stage publish` without changing publication policy. Leave the accepted ADR decision intact. 3. Update README workflows, operator development/regeneration examples, troubleshooting, relevant integration references, maintained examples, and affected scripts/tests. Highlight `run SESSION --stage analyze --force` for analysis-only rebuilding and `artifacts regenerate SESSION` for forced extraction plus analysis. Explain console versus downstream debug behavior. 4. Add a concise old-to-new command migration table in the CLI reference and link to it from operations. Cover identity/file selectors, party selection, native inspection versus domain views, independent comparison defaults, inspection-only overrides, structured output, and cancellation. Versioned release-note selection remains release preparation, not a sprint blocker. 5. Update dependency attribution for core, ckconfig, and relevant incorporated transitive code using selected-version source commits and existing local license texts where applicable. Audit actual runtime/test imports rather than assuming upstream maintainer tools are distributed. Preserve Narratio's existing grant and policy attribution. Check: documentation links and maintained examples pass; command examples match real declarations. Release version embedding/checks work with native version output. Historical released notes remain unchanged. No release, push, or CI polling is part of this implementation sprint. ## Stage 21: Verify the complete cutover and close implementation Read: roadmap verification/completion, this plan, the canonical updated documentation, and [Development validation](../development.md#validation). 1. Run an assembled offline workflow with real CommandKit/ConfigKit and fake downstream/storage boundaries: imported pipeline and overlay, campaign and party selection, native app/session/party inspection, independent comparison, domain catalog/plan, execution with families, a later failure, resume, and publication/restore where covered by existing fixtures. Preserve existing consequential tests rather than rebuilding upstream parser/configuration test suites inside Narratio. 2. Verify invocation-local overrides, absence of post-handoff mutation, and roster consistency across inspection/domain consumers. Exercise safe diagnostics, serialized configuration, public reports, failure/quiet modes, report-writer errors, and cancellation/finalization. No resolved secret may leak through these paths. 3. Run the established full checks with the selected Go 1.27.4 toolchain: `go test ./...`, `go test -race ./...`, `go vet ./...`, and `go build ./...`. These include documentation and maintained-example checks. Run `go mod tidy -diff` for the changed dependency graph and `git diff --check`; verify the existing supported-target asset builds with the repository's nonpublishing builder. Do not introduce new permanent release gates. 4. Review the final diff against every roadmap target and deferred item. Confirm all commands, four native scopes, supported inspection modes, independent comparisons, reports, progress categories, cancellation, and preserved safety/resume behavior have authoritative test or code evidence. Repair real defects instead of weakening the agreed final state to fit tests. 5. Mark completed stages here with brief results, commit remaining sprint work, and report verification and any genuine limitations. Leave pending roadmaps intact. Tagging/pushing and the final release number require the separate release task. Completion means the entire application compiles, the relevant behavior and repository checks pass, and obsolete CLI/inspection machinery has been retired. An intermediate green subset is not completion of this migration. ## Open Questions None. The agreed roadmap settles the implementation's product decisions. Release-number selection and execution/planning overrides remain deferred as described there and do not block this sprint.