Plan the CommandKit adoption sprint
This commit is contained in:
@@ -3,8 +3,9 @@
|
|||||||
Status: agreed target; implementation pending.
|
Status: agreed target; implementation pending.
|
||||||
|
|
||||||
This roadmap consolidates the [migration discussion](commandkit-notepad.md).
|
This roadmap consolidates the [migration discussion](commandkit-notepad.md).
|
||||||
It defines the intended end state and required work. Detailed implementation
|
It defines the intended end state and required work. The
|
||||||
sequencing belongs in a subsequent plan.
|
[implementation plan](implementation.md) defines the ordered implementation
|
||||||
|
stages.
|
||||||
|
|
||||||
## Objective And Scope
|
## Objective And Scope
|
||||||
|
|
||||||
@@ -294,7 +295,7 @@ and applicable file/directory selectors.
|
|||||||
|
|
||||||
## Required Work
|
## 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
|
1. **Replace the command boundary.** Add the selected dependencies and native
|
||||||
application/command declarations. Wire typed inputs to domain operations,
|
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
|
final checks from [Development](../development.md#validation): tests, race-enabled
|
||||||
tests, vet, and build, including documentation and maintained-example checks.
|
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
|
## Migration And Deferred Work
|
||||||
|
|
||||||
Release guidance will include an old-to-new command table and explain identity
|
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
|
migration does not promise to discover prompt requirements or prove that every
|
||||||
configured pipeline can complete.
|
configured pipeline can complete.
|
||||||
|
|
||||||
No significant design decisions remain open. Implementation sequencing and
|
No significant design decisions remain open. Release selection remains separate
|
||||||
release selection do not block preparation of the implementation plan.
|
from implementation.
|
||||||
|
|||||||
671
docs/roadmap/implementation.md
Normal file
671
docs/roadmap/implementation.md
Normal file
@@ -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.
|
||||||
Reference in New Issue
Block a user