Files
narratio/docs/roadmap/implementation.md

49 KiB
Raw Blame History

CommandKit adoption implementation plan

Scope and authority

Implement the agreed target in CommandKit adoption, following ADR 0003. 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, CLI contract, ckconfig contracts, and ConfigKit consumer guide as upstream authorities. The ckconfig release's own module metadata and release note 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, Agent Policy, 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

Completed. Session loads receive selected-campaign defaults and record them before handoff, retaining their actual native result and source inventory. Concrete-session checks run in definition validation; typed identity assertions remain explicit. Stable input references are derived without mutating loaded values, and standalone rendering preserves explicit optional-input clearing. Session/default/import/discovery, preparation, initialization, native boundary, and build checks pass with Go 1.27.4. The two catalog dependency tests noted in Stage 2 remain pending Stage 4.

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

Completed. Exposed the retained typed party result and exact explicit-roster selection. Concrete artifacts, dependency closure, family/member provenance, players, and publication rules are derived separately; completed pipeline and campaign values remain unchanged. Removed expansion state from PipelineConfig. The full configuration package and maintained examples pass with Go 1.27.4, including the dependency tests deferred from Stage 2 and independent-roster regressions. Whole-application compilation awaits the family-origin consumers' catalog wiring in Stage 5; no compatibility dispatcher or snapshot was added.

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

Completed. Analysis selection, planning, fingerprinting, reconciliation, previous-session requirements, runtime registration, and artifact inspection use the separate concrete catalog. Run options retain normalized family selection and origins through the stage environment; Scriptorium requests borrow genuine shared settings. An assembled bounded run verifies explicit-roster players, family dependencies, adapter variables, durable identities, and unchanged native configuration. Configuration, stage, and artifact suites, focused runner and bounded-composition checks, and builds pass with Go 1.27.4. CLI tests awaiting the later native command/inspection conversion remain transitional.

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

Completed. Publication selection, lock reporting, and semantic fingerprints consume derived publication actions and concrete artifacts. Preparation and resume use the selected roster's players projection. Safe pipeline materialization preserves credential references, family declarations, and null/empty distinctions without a fabricated native result; comparison uses the actual retained results. Configuration, stage, and artifact suites plus focused prepared-publication, restore, semantic-resume, and bounded-family composition checks pass with Go 1.27.4. Later native CLI conversion tests remain transitional.

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

Completed. Invocation-owned typed selections now acquire pipeline, campaign, party, session, and derived execution context lazily, retaining native results. Exact files and identity assertions are complementary; local errors never trigger remote fallback. Remote session acquisition avoids roster/catalog work, retains storage and cleanup causes, distinguishes committed snapshots, and releases its temporary download through the shared owner. Bootstrap runs once and retains failures. Direct acquisition, identity, discovery, cleanup, pipeline-retention, and prepared-publication round-trip checks and builds pass with Go 1.27.4. Native inspection and command declarations consume this owner in later stages; old CLI invocation tests remain transitional.

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

Completed. Installed native app (default), campaign, session, and party scopes using retained typed results, native diagnostics, and lazy acquisition. Pipeline file-local checks now run within ConfigKit validation. Removed the handwritten config dispatcher, show/validation/source renderers, and synthetic source reconciliation; comparison and domain-catalog conversion retain their scheduled owners. Native scope/path/explanation, filtered validation, aggregate failure, lazy discovery, secret-safe bundle inspection, and bounded execution checks pass. Configuration, stage, and artifact suites and builds pass with Go 1.27.4; remaining command and comparison tests await their scheduled conversion.

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

Completed. Native comparisons expose independent campaign/session/party selectors and load each side separately with normal defaults. App-only native overrides flow directly into ConfigKit; neither comparison sides nor later invocations share overridden results. Removed the custom comparison parser, renderer, same-campaign restrictions, and overlay-pair helper. Tests cover independent root defaults, campaign/session files, explicit and default rosters, one-time bootstrap, detailed differences/status 3, hidden credentials, and unsupported-scope overrides. Configuration, stage, and artifact suites, focused native/composition checks, builds, and diff checks pass with Go 1.27.4.

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

Completed. Native run and artifacts-regenerate declarations use typed selectors and the shared bounded planner/execution operation. Single-stage selection rejects explicit range flags before bootstrap; regeneration fixes forced extract-through-analyze without argv construction. Native reports expose identities, selected/executed/skipped work, artifact targets, and completion after acquisition cleanup. Removed the synthetic regeneration implementation; obsolete routes and duplicate session identity flags are absent from the native tree. Focused native execution, regeneration, selection, inspection, and bounded family composition checks, builds, and diff checks pass with Go 1.27.4. Detailed partial-run accounting remains assigned to Stage 15.

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

Completed. Native session-plan declarations share run selection/checking and one read-only decision builder, including analysis prerequisites/reuse and publication mappings from the same pure publication owner used by execution. Native artifacts-list reports built-in, configured, and extraction sources, producers, dependencies, and selected-party family provenance without requiring a session. Acquisition retains one derived catalog; removed config-artifacts and its custom inspection dependency. Native planning/catalog, existing planning and manifest-cloning, explicit-roster immutability, and bounded composition checks pass. Configuration, stage, and artifact suites, builds, and diff checks pass with Go 1.27.4. Remaining unrelated command conversions stay scheduled below.

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

Completed. Native session validate/status/artifacts declarations share typed selectors and read-only acquisition. Structured reports retain findings, local stage/artifact evidence, audio/previous-input readiness, configuration provenance, remote current state, locks, and exact published-output declarations including carried origins. Partial failures retain reports and original causes; local-only artifact inspection avoids storage and payload reads. Existing entry points consume the same collectors. Native JSON/YAML, readiness/configuration failure, remote partial-failure, carried-output identity, and manifest-immutability checks pass alongside configuration, stage, artifact, focused composition, and build checks with Go 1.27.4. Superseded parser/text assertions await final cleanup.

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.

  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.