diff --git a/docs/roadmap/commandkit.md b/docs/roadmap/commandkit.md index 2684107..543b0b6 100644 --- a/docs/roadmap/commandkit.md +++ b/docs/roadmap/commandkit.md @@ -3,8 +3,9 @@ Status: agreed target; implementation pending. This roadmap consolidates the [migration discussion](commandkit-notepad.md). -It defines the intended end state and required work. Detailed implementation -sequencing belongs in a subsequent plan. +It defines the intended end state and required work. The +[implementation plan](implementation.md) defines the ordered implementation +stages. ## Objective And Scope @@ -294,7 +295,7 @@ and applicable file/directory selectors. ## Required Work -These work areas describe scope, not mandatory buildable milestones. +The required changes span these areas. 1. **Replace the command boundary.** Add the selected dependencies and native application/command declarations. Wire typed inputs to domain operations, @@ -356,12 +357,6 @@ services, real credentials, and paid model calls. Run the repository's establish final checks from [Development](../development.md#validation): tests, race-enabled tests, vet, and build, including documentation and maintained-example checks. -Carry out implementation as one end-to-end sprint. Intermediate commits may be -incomplete, incoherent, or noncompiling; use focused checks where useful and -report their state accurately. Do not add compatibility scaffolding to make each -commit independently shippable. Completion requires the coherent, compilable, -validated final application and its documentation. - ## Migration And Deferred Work Release guidance will include an old-to-new command table and explain identity @@ -383,5 +378,5 @@ separate work. The catalog exposes Narratio's configured knowledge; this migration does not promise to discover prompt requirements or prove that every configured pipeline can complete. -No significant design decisions remain open. Implementation sequencing and -release selection do not block preparation of the implementation plan. +No significant design decisions remain open. Release selection remains separate +from implementation. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md new file mode 100644 index 0000000..94bedf2 --- /dev/null +++ b/docs/roadmap/implementation.md @@ -0,0 +1,671 @@ +# 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 + +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 + +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.