705 lines
43 KiB
Markdown
705 lines
43 KiB
Markdown
# CommandKit adoption implementation plan
|
||
|
||
## Scope and authority
|
||
|
||
Implement the agreed target in [CommandKit adoption](commandkit.md), following
|
||
[ADR 0003](../adr/0003-assign-configuration-ownership.md). This plan is for a
|
||
Luna coding agent implementing the stages in sequential order during one
|
||
end-to-end sprint. Each stage is one focused implementation prompt.
|
||
|
||
The inspected baseline is commit `bcbfc0f`. Narratio already uses ConfigKit
|
||
v1.2.1 and declares Go 1.27.0. Its handwritten command boundary, post-load
|
||
configuration mutations, replacement inspection snapshots, and successful-only
|
||
run summaries are the migration inputs.
|
||
|
||
Select these released modules directly:
|
||
|
||
| Module | Version | Upstream source commit |
|
||
| --- | --- | --- |
|
||
| `go.maximumdirect.net/commandkit` | v0.7.0 | `b57bfe176cff05a892e6cb07ebb5f350239e55d4` |
|
||
| `go.maximumdirect.net/ckconfig` | v0.9.0 | `9962368f0c1ea1f6ad010638e94621091105d745` |
|
||
| `go.maximumdirect.net/configkit` | v1.2.1, retained | `51ef3144158db1a09fabdbd1c7ae59908c84923b` |
|
||
|
||
Use the pinned [CommandKit consumer guide](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/b57bfe176cff05a892e6cb07ebb5f350239e55d4/docs/consumers/guide.md),
|
||
[CLI contract](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/b57bfe176cff05a892e6cb07ebb5f350239e55d4/docs/cli.md),
|
||
[ckconfig contracts](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/9962368f0c1ea1f6ad010638e94621091105d745/integrations/ckconfig/contracts.go),
|
||
and [ConfigKit consumer guide](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/docs/consumers/README.md)
|
||
as upstream authorities. The ckconfig release's own module metadata and
|
||
[release note](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/9962368f0c1ea1f6ad010638e94621091105d745/integrations/ckconfig/docs/releases/v0.9.0.md)
|
||
confirm the selected pairing; the earlier core guide's integration-version table
|
||
predates that coordinated release. Read the released public declarations when
|
||
details are needed. Sibling checkouts are optional reference material, not
|
||
build or test prerequisites.
|
||
|
||
## Working rules
|
||
|
||
- Start with [Development](../development.md), [Agent Policy](../policy/agents.md),
|
||
and the roadmap. Read applicable architecture, testing, documentation, OSS,
|
||
and release policies through the development guide. Reuse unchanged policies
|
||
already read. Prefer the codebase graph for code discovery; confirm current
|
||
source when indexed locations are stale.
|
||
- Intermediate stages may be incomplete, noncompiling, or have tests awaiting
|
||
later stages. Record that accurately. Do not build compatibility layers,
|
||
parallel dispatchers, replacement configuration views, or temporary no-op
|
||
operations merely to keep intermediate commits green.
|
||
- Commit each completed nonempty unit using a concise plain-English message.
|
||
Add focused tests with their owning behavior. Use real CommandKit and
|
||
ConfigKit; replace only external boundaries, clocks, randomness, and other
|
||
sources of nondeterminism where needed. Keep default tests offline and
|
||
independent of installed downstream applications, credentials, and paid APIs.
|
||
- Preserve consequential stage ordering, invalidation, checkpoint reuse,
|
||
publication, remote locks, restore confinement, workspace modes, and cleanup
|
||
behavior. This CLI cutover does not authorize workspace reorganization,
|
||
downstream adapter upgrades, session migration machinery, or new retention
|
||
rules. Keep the pending Audita and workspace roadmaps separate.
|
||
- Preserve existing operation-specific options unless the roadmap replaces
|
||
them. Adopt upstream flag placement, repetition, help, reporting, and outcome
|
||
behavior; retire tests enforcing superseded parser conventions. Avoid exact
|
||
formatting or error-wording promises unless the contract actually owns them.
|
||
- Use concise, affirmative documentation. Keep current contracts in their
|
||
canonical owners and proposed implementation status here. The migration
|
||
discussion is historical context; the consolidated roadmap owns decisions.
|
||
|
||
## Implementation boundaries
|
||
|
||
Use a small number of concrete data boundaries, adapting the existing owners:
|
||
|
||
- **Loaded configuration:** retain actual typed ConfigKit results for pipeline,
|
||
campaign, session, and party. Complete configuration defaults, normalization,
|
||
and validation inside supported load callbacks. Consume completed values
|
||
without mutation; no defensive-copy framework or new public YAML schema is
|
||
required to express this ownership.
|
||
- **Derived domain context:** hold the selected roster, players projection,
|
||
concrete artifacts, family origins, resolved dependencies, and publication
|
||
actions separately. Existing `config.Config`, `stage.Env`, and
|
||
`artifacts.EffectiveArtifactSet` can carry or reference these products.
|
||
Keep CommandKit types at the application/process boundary.
|
||
- **Invocation selection:** retain explicit presence for identity, file, overlay,
|
||
and secrets selectors. Share acquisition between native inspection and domain
|
||
commands, with invocation-owned state and independent comparison inputs.
|
||
- **Operation results:** domain operations return useful values and errors;
|
||
application handlers present public report DTOs with CommandKit. Use stable
|
||
JSON field tags for YAML/JSON agreement and keep manifests, credentials, and
|
||
internal dependency containers out of public reports.
|
||
|
||
Use native automatic report presentation, including YAML for structured values,
|
||
and `--format text|yaml|json`. Add a text template only when representative
|
||
output demonstrates a substantial readability benefit, using the same report
|
||
data. Report format remains independent of generated artifact formats.
|
||
|
||
These are responsibility boundaries, not a requirement to create four new
|
||
packages or a generic command, configuration, or event framework.
|
||
|
||
## Stage 1: Install the native application boundary
|
||
|
||
**Completed.** Installed the pinned native modules, caller-context/stream entry
|
||
point, native help/version, supplied-value selector declarations, and outcome
|
||
classification with preserved causes. Native boundary tests, release-script
|
||
checks, documentation checks, and repository-wide compilation pass with Go
|
||
1.27.4. Domain command invocation tests await their scheduled native handlers;
|
||
the handwritten dispatcher is no longer an execution path.
|
||
|
||
Read: roadmap command organization and invocation lifecycle; upstream consumer
|
||
guide sections on core commands and invocation reporting; `internal/app/commands.go`,
|
||
`command_dependencies.go`, `version.go`, and `cmd/narratio/main.go`.
|
||
|
||
1. Add the selected CommandKit and ckconfig requirements, retaining ConfigKit
|
||
v1.2.1 and the existing Go minimum. Use released modules, without local
|
||
filesystem replacements or an upstream workspace dependency.
|
||
2. Establish the native application construction and execution entry point in
|
||
`internal/app`. Supply Narratio's existing build version through
|
||
`commandkit.Identity`; use native help and version. Accept a caller context
|
||
and caller-owned streams, and return the native outcome to the process
|
||
boundary. Update the version-checking consumer in release tests/scripts for
|
||
the native version representation when its implementation changes.
|
||
3. Establish typed selection inputs and reusable native flag declarations using
|
||
`Supplied` presence. Domain checks on combinations belong in `CheckInput` or
|
||
the appropriate post-load operation, not token scanning. Other stages add
|
||
the actual command handlers; no second legacy dispatch path is needed.
|
||
4. Establish a small application outcome adapter: public ckconfig classification
|
||
for configuration errors, usage outcomes for identifiable Narratio input
|
||
errors, and operational outcomes otherwise. Preserve wrapped/joined causes
|
||
and operational precedence. Present terminal failures once.
|
||
|
||
Check: native root/group help and version can run with deliberately unusable
|
||
configuration and external dependencies; invalid invocation returns status 2.
|
||
Construction itself performs no credential bootstrap or acquisition.
|
||
|
||
## Stage 2: Retain authoritative pipeline and campaign load results
|
||
|
||
**Completed.** Pipeline and campaign loaders expose their actual typed native
|
||
results, retaining structured load failures and recorded resolution evidence.
|
||
Campaign configuration checks now run in its definition lifecycle; resource
|
||
existence remains a domain concern. Removed duplicated pipeline metadata and
|
||
post-load dependency merging. Native result/import/overlay checks and builds
|
||
pass with Go 1.27.4. Two existing dependency tests await the separate concrete
|
||
catalog in Stage 4; their expectations remain intact.
|
||
|
||
Read: roadmap ownership; `internal/config/pipeline_configkit.go`,
|
||
`document_configkit.go`, `load.go`, `effective_digest.go`, and the upstream
|
||
ConfigKit sections on recorded application resolution and inspection.
|
||
|
||
1. Expose retained pipeline and campaign ConfigKit results through typed loaded
|
||
context/accessors suitable for `ckconfig.FromConfigKit`. Keep load errors and
|
||
native diagnostics available rather than flattening them into text.
|
||
2. Move genuine pipeline defaults and normalization currently performed after
|
||
`configkit.Load` into its definition lifecycle, recording changes with native
|
||
helpers. Audit `finalizeLoadedPipeline` and dependency/default handling;
|
||
concrete family expansion and campaign-dependent work stay outside it.
|
||
3. Put configuration-owned campaign checks in the campaign definition's
|
||
validation callback. Keep input-file existence, remote readiness, and
|
||
artifact execution checks with their domain operations.
|
||
4. Retain source-relative resource semantics using native metadata during
|
||
resolution. Do not add import/source-authoring acceptance rules. Remove
|
||
metadata bookkeeping rendered redundant by the retained results; later stages
|
||
remove the replacement inspection path after its consumers move.
|
||
|
||
Check: loaded values and native show/explain agree for defaults, imports,
|
||
overlays, and explicit values. Loading an app pipeline does not require a party
|
||
or mutate its completed result to make derived artifacts appear.
|
||
|
||
## Stage 3: Complete session defaults within ConfigKit's lifecycle
|
||
|
||
**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
|
||
|
||
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.
|