Files
narratio/docs/roadmap/implementation.md

857 lines
54 KiB
Markdown
Raw Normal View History

2026-11-20 04:05:11 +00:00
# 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.
2026-11-20 04:05:11 +00:00
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.
2026-11-20 04:05:11 +00:00
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.
2026-11-20 04:05:11 +00:00
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.
2026-11-20 04:05:11 +00:00
Read: `internal/config/party*.go`, `artifact_families.go`, `artifact_catalog.go`,
the family declarations in `config.go`, and the roadmap's ownership boundary.
1. Retain the actual party ConfigKit result and select either an explicit party
file or the campaign-default file. A CLI-relative explicit file uses the
invocation directory; missing or invalid explicit selections fail exactly.
Selection does not rewrite the campaign's configured party field.
Update stable-party references and `validateResolvedPartyInputs` so its
current campaign-only source assertion accepts the agreed explicit selection.
2. Turn family expansion into domain derivation from the completed pipeline and
selected canonical roster. Return concrete definitions, family/member origins,
resolved inputs/dependencies, and expanded publication rules separately.
Keep declarations in the authoritative pipeline configuration.
3. Derive the players projection from the same selected roster. Retain current
family ordering, member-variable semantics, collision and dependency checks,
and family/concrete artifact selection meanings. Validate these products when
deriving the catalog, rather than requiring them for app inspection.
4. Remove family-expansion flags and generated catalogs stored as mutations of
`PipelineConfig`. Reuse existing catalog/model types where appropriate rather
than adding a second family engine or a generic workflow abstraction.
Check: deriving catalogs for two different parties from one loaded pipeline
does not affect either the native result or the other catalog. Explicit roster
selection reaches family members and players; collisions remain errors.
## Stage 5: Wire derived products through planning and execution
**Completed.** Analysis selection, planning, fingerprinting, reconciliation,
previous-session requirements, runtime registration, and artifact inspection use
the separate concrete catalog. Run options retain normalized family selection
and origins through the stage environment; Scriptorium requests borrow genuine
shared settings. An assembled bounded run verifies explicit-roster players,
family dependencies, adapter variables, durable identities, and unchanged native
configuration. Configuration, stage, and artifact suites, focused runner and
bounded-composition checks, and builds pass with Go 1.27.4. CLI tests awaiting
the later native command/inspection conversion remain transitional.
2026-11-20 04:05:11 +00:00
Read: `internal/app/analyze_artifacts.go`, `runner_runtime.go`,
`bounded_prerequisites.go`, `internal/stage/stage.go`, `analyze*.go`,
`trim.go`, and the artifact catalog/resolution owners.
1. Carry the derived catalog and roster products through the invocation context,
`RunOptions`/`stage.Env`, effective artifact registration, and selected-target
resolution. Treat loaded configuration as read-only.
2. Update analysis work planning, dependency/input resolution, previous-session
requirements, and relevant adapter composition to consume concrete domain
definitions rather than expecting expansion inside pipeline configuration.
3. Update all stage consumers, including built-in artifact handling and trim's
Scriptorium use, through their actual dependencies. Preserve full-bundle
extraction and analysis-specific target closure semantics.
4. Keep one shared derivation path for catalog listing, planning, execution, and
session artifact inspection. Remove old paths that expand configuration on
demand or implicitly select a different roster.
Check: a character-family pipeline executes concrete members through the real
planner with fake external adapters; dependencies, family selections, and
selected-party players match the separately derived catalog. Bounded execution
still composes only the collaborators it needs.
## Stage 6: Preserve preparation, publication, and semantic resume evidence
**Completed.** Publication selection, lock reporting, and semantic fingerprints
consume derived publication actions and concrete artifacts. Preparation and
resume use the selected roster's players projection. Safe pipeline materialization
preserves credential references, family declarations, and null/empty distinctions
without a fabricated native result; comparison uses the actual retained results.
Configuration, stage, and artifact suites plus focused prepared-publication,
restore, semantic-resume, and bounded-family composition checks pass with Go
1.27.4. Later native CLI conversion tests remain transitional.
2026-11-20 04:05:11 +00:00
Read: `internal/stage/prepare*.go`, `publish*.go`, `semantic_contracts*.go`,
the prepared-input and remote publication/restore contracts, and
`internal/config/effective_projection.go` and `effective_pipeline.go`.
1. Pass derived publication actions to publish selection and lock validation
rather than inserting them into pipeline configuration. Preserve source IDs,
destinations, selected-artifact filtering, remote lock behavior, and the
immutable commit/current-pointer boundary.
2. Adapt prepared party/players, campaign/session YAML, pipeline snapshots, and
required domain records to the new data flow. A secret-safe serialization
DTO may remain for preparation or persistence where it preserves required
credential references and effective inputs. It must not become a fabricated
native inspection result. Persist additional domain evidence only where an
existing preparation/resume consumer needs it.
3. Update stage/artifact semantic projections to read the same concrete products
used by execution. Preserve result-affecting evidence; overlay labels,
source arrangement, provenance, and a whole-configuration digest remain
informational rather than blanket invalidation keys.
4. Remove `newPipelineInspection`, its `NoSource` freeze, and the separate
authoring-versus-final inspection machinery when their consumers have moved.
Reuse safe digest/materialization code where still needed, separating it from
native show/diff instead of deleting useful persistence indiscriminately.
Check: prepared inputs and publication round-trip through existing restore
fixtures; locked/current outputs keep their behavior. Equivalent authored
configurations reuse valid work, while changed concrete prompts/variables,
dependencies, roster-derived inputs, or publish destinations affect the relevant
semantic checks. Inspection never depends on persisted domain snapshots.
## Stage 7: Share lazy identity and source acquisition
**Completed.** Invocation-owned typed selections now acquire pipeline, campaign,
party, session, and derived execution context lazily, retaining native results.
Exact files and identity assertions are complementary; local errors never trigger
remote fallback. Remote session acquisition avoids roster/catalog work, retains
storage and cleanup causes, distinguishes committed snapshots, and releases its
temporary download through the shared owner. Bootstrap runs once and retains
failures. Direct acquisition, identity, discovery, cleanup, pipeline-retention,
and prepared-publication round-trip checks and builds pass with Go 1.27.4.
Native inspection and command declarations consume this owner in later stages;
old CLI invocation tests remain transitional.
2026-11-20 04:05:11 +00:00
Read: `internal/app/config_loader.go`, `campaign_config_path.go`,
`session_config_path.go`, `remote_session.go`, `command_dependencies.go`,
and the roadmap's selector and session-acquisition sections.
1. Replace positional strings passed among loaders with invocation-owned typed
selections. Distinguish `--campaign` identity from `--campaign-file`, and
inspection `--session` identity from `--session-file`. A supplied identity
and file are complementary: load the exact file and assert the effective ID.
Remove the old campaign-ID/file mutual exclusion. Session domain commands
retain their positional ID; file-only inspection may obtain its ID from data.
2. Acquire supporting configuration only as needed. App needs no campaign/party
expansion; campaign needs no session; an explicit party file needs no session.
Resolve campaign defaults when a session load requires them. Keep the same
selections and acquired results for an operation rather than reloading the
pipeline during session resolution.
3. Share exact-file, local-discovery, and remote-discovery acquisition between
inspection and execution. Only local absence enables remote fallback, with a
known session identity. Prefer remote authored session-root configuration;
use the committed prepared snapshot only on authored-object absence.
Preserve checksum/size and pointer-selected snapshot checks already required.
4. Keep read-only acquisition free of workspace creation, restore, manifest
updates, execution locks, and stage adapters. Remote reads are permitted.
Preserve underlying storage/access/parse errors and source labels for local,
remote-authored, and committed-snapshot inputs. Release temporary resources
on success and failure and retain cleanup errors.
5. Bootstrap secrets once per reached invocation after parsed-input checks and
before typed loading, using the existing explicit/default directory contract.
Invocation caches may share already acquired context, but must not conflate
different files, overlays, campaigns, or comparison sides.
Check: exact-file errors and ID mismatches never fall back; only absence does.
Remote inspection leaves no runtime session state. A selected party file is
used consistently, and app-only acquisition avoids unrelated inputs/services.
## Stage 8: Expose genuine configuration scopes through ckconfig
**Completed.** Installed native app (default), campaign, session, and party
scopes using retained typed results, native diagnostics, and lazy acquisition.
Pipeline file-local checks now run within ConfigKit validation. Removed the
handwritten config dispatcher, show/validation/source renderers, and synthetic
source reconciliation; comparison and domain-catalog conversion retain their
scheduled owners. Native scope/path/explanation, filtered validation, aggregate
failure, lazy discovery, secret-safe bundle inspection, and bounded execution
checks pass. Configuration, stage, and artifact suites and builds pass with Go
1.27.4; remaining command and comparison tests await their scheduled conversion.
2026-11-20 04:05:11 +00:00
Read: upstream `Suite`, `Selector`, `FromConfigKit`, `AdaptDiagnostics`, and the
native configuration CLI contract; Narratio's old `config_commands.go`.
1. Register `app`, `campaign`, `session`, and `party` through
`ckconfig.FromConfigKit`, making `app` the default. Supply actual results and
native load errors from Stages 2–7. Expose all applicable standard operations,
including native path show/discovery, sources, history/explanation, and
detailed validation findings/filters.
2. Bind custom selectors only to scopes needing them. Native `--config` always
selects the pipeline root and `--overlay` its overlay; neither changes
meaning with scope. `--party-file` selects roster input, not an app override.
Use `Suite.CheckInput` for scope request checks and shared lazy state for
reached acquisitions. Keep factories free of side effects.
3. Retain upstream per-operation aggregate-scope behavior. Missing required
context fails visibly rather than dropping a scope. Filtering displayed
findings does not turn invalid configuration into success.
4. Remove Narratio-owned show/source/explanation renderers and synthetic
path/provenance reconciliation after replacement. `config artifacts` moves
to the domain catalog command in Stage 11; the generated config group needs
no custom child-command extension.
Check: native commands inspect each scope with real imported configurations;
show values, path explanations, and diagnostics come from that scope's real
result. Scope discovery and help cause no bootstrap, loading, or storage calls.
## Stage 9: Add independent comparisons and app inspection overrides
**Completed.** Native comparisons expose independent campaign/session/party
selectors and load each side separately with normal defaults. App-only native
overrides flow directly into ConfigKit; neither comparison sides nor later
invocations share overridden results. Removed the custom comparison parser,
renderer, same-campaign restrictions, and overlay-pair helper. Tests cover
independent root defaults, campaign/session files, explicit and default rosters,
one-time bootstrap, detailed differences/status 3, hidden credentials, and
unsupported-scope overrides. Configuration, stage, and artifact suites, focused
native/composition checks, builds, and diff checks pass with Go 1.27.4.
2026-11-20 04:05:11 +00:00
Read: upstream `ComparisonSide`, `Selector.AgainstName`, native override/diff
contracts, and Narratio's old `config_diff.go`.
1. Bind `--against-campaign`, `--against-campaign-file`, `--against-session`,
`--against-session-file`, and `--against-party-file` for their applicable
scopes alongside native `--against-config` and `--against-overlay`.
2. Resolve each side from its own fresh typed input and normal defaults. An
omitted right-side selector does not inherit its left counterpart. Party
defaults follow that side's campaign. Share only invocation-wide services
such as credential bootstrap and correctly keyed acquisitions.
3. Pass native `Selection.Overrides` to the app ConfigKit load and advertise
`Scope.Features.Overrides` only for app. Let ckconfig parse `--set` and
`--against-set`; ConfigKit applies them during the load. Keep native ordering,
merge, path, explicitness, secret, and conflict semantics.
4. Use native comparisons and report shapes, including detailed output and
`diff --check` status 3. Remove overlay-only/same-campaign restrictions and
the final-domain snapshot diff. Other scopes and aggregate inspection reject
overrides according to ckconfig's advertised capabilities.
Check: independent files/campaigns/rosters on each side, right-side defaults,
safe hidden values, and native app override behavior. Execution and planning
declarations expose no field overrides; comparison results do not mutate inputs.
## Stage 10: Replace run and regeneration command wiring
**Completed.** Native run and artifacts-regenerate declarations use typed
selectors and the shared bounded planner/execution operation. Single-stage
selection rejects explicit range flags before bootstrap; regeneration fixes
forced extract-through-analyze without argv construction. Native reports expose
identities, selected/executed/skipped work, artifact targets, and completion
after acquisition cleanup. Removed the synthetic regeneration implementation;
obsolete routes and duplicate session identity flags are absent from the native
tree. Focused native execution, regeneration, selection, inspection, and bounded
family composition checks, builds, and diff checks pass with Go 1.27.4. Detailed
partial-run accounting remains assigned to Stage 15.
2026-11-20 04:05:11 +00:00
Read: `internal/app/run.go`, `bounded_run.go`, `regenerate_artifacts.go`,
`planner.go`, analysis-selection helpers, and the roadmap command tree.
1. Declare `run SESSION` and `artifacts regenerate SESSION` as typed native
commands. Bind common file/identity selectors, overlay/secrets selection,
force, and repeatable analysis artifact values. Remove the compatibility
`--session-id` path. Retain previous-session assertion support where applicable.
2. Extend the shared bounded-plan request with `--stage`: translate it to equal
inclusive endpoints and reject combining it with explicitly supplied
`--from` or `--through`. Preserve full-range defaults, endpoint validation,
and independent force. Check configuration-independent combinations before
bootstrap; check configured targets after catalog derivation.
3. Regeneration calls the same typed execution operation with forced extract
through analyze. Its public options select configuration and analysis targets;
fixed range/force are not independent user options on that command. Never
construct and reparse a synthetic argv string.
4. Return one public run report containing identities, selected stages,
executed/reused outcomes, artifacts, and completion. Stage 15 completes
failure reporting. Use native outcomes and presentation; remove the
`run-stage`, `analyze`, `publish`, and `regenerate-artifacts` command routes.
Check: single-stage, full/ranged execution and force map to the same planner.
Regeneration always includes the complete extraction bundle and never publish;
`--artifacts` narrows analysis targets/prerequisites, not Notarius lanes. Artifact
selection retains its existing analyze/publish consumer and family rules.
## Stage 11: Expose planning and the configured artifact catalog
**Completed.** Native session-plan declarations share run selection/checking and
one read-only decision builder, including analysis prerequisites/reuse and
publication mappings from the same pure publication owner used by execution.
Native artifacts-list reports built-in, configured, and extraction sources,
producers, dependencies, and selected-party family provenance without requiring
a session. Acquisition retains one derived catalog; removed config-artifacts and
its custom inspection dependency. Native planning/catalog, existing planning and
manifest-cloning, explicit-roster immutability, and bounded composition checks
pass. Configuration, stage, and artifact suites, builds, and diff checks pass
with Go 1.27.4. Remaining unrelated command conversions stay scheduled below.
2026-11-20 04:05:11 +00:00
Read: `internal/app/plan.go`, `analyze_artifacts.go`, old config artifact listing,
and the shared domain products from Stages 4–6.
1. Declare `session plan SESSION` with the same stage/range, force, artifact,
and context selection semantics as run. Use the shared pure decision and
analysis work planners; keep planning read-only with cloned manifest state.
2. Include derived publication work as well as stage execution/reuse reasons,
selected analysis targets, prerequisite work, and reuse. Describe decisions
from the planner without predicting unknown output identities or claiming
execution occurred.
3. Declare `artifacts list` as a domain catalog requiring the context needed for
family derivation, but no session solely to list configured definitions.
Include configured/built-in extraction and artifact sources, producers,
dependencies, and family/member identities from existing catalog ownership.
4. Present public plan/catalog DTOs through native reporting. Remove the old
`config artifacts` implementation and its custom inspection dependency.
Check: representative plans and execution make the same reuse/selection
decisions. Listing family members leaves the app result unchanged; neither
operation initializes a runtime workspace or stage adapters.
## Stage 12: Convert read-only session inspection commands
**Completed.** Native session validate/status/artifacts declarations share typed
selectors and read-only acquisition. Structured reports retain findings, local
stage/artifact evidence, audio/previous-input readiness, configuration provenance,
remote current state, locks, and exact published-output declarations including
carried origins. Partial failures retain reports and original causes; local-only
artifact inspection avoids storage and payload reads. Existing entry points
consume the same collectors. Native JSON/YAML, readiness/configuration failure,
remote partial-failure, carried-output identity, and manifest-immutability checks
pass alongside configuration, stage, artifact, focused composition, and build
checks with Go 1.27.4. Superseded parser/text assertions await final cleanup.
2026-11-20 04:05:11 +00:00
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
**Completed.** Native session-init and explicit locks list/add/remove commands
return structured confirmations and lock lists. Initialization shares authoring
and persistence with the existing entry point, retains template/import resource
bases and invocation-relative audio, and keeps generated YAML independent of
report formatting. Target/operand checks precede acquisition; bare locks shows
lazy help. Shared lock mutations retain conditional replacement, original
conflict causes, and idempotent removal, including failure reports. Native local/
remote round-trips, imported-template/context, lock-concurrency, and input-check
fixtures pass alongside configuration, stage, artifact, focused composition,
build, and diff checks with Go 1.27.4.
2026-11-20 04:05:11 +00:00
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
**Completed.** Native restore and session-clean declarations return separate
public action reports after resource release, including conflicts and completed
work on failure. Restore retains pointer authority, transition locking, recovery
markers, confined replacements, and manifest-last installation; its planner no
longer creates directories or changes their modes during dry runs. Cleanup
retains the exact workspace/spool/cache scopes and cache opt-in, checks --all
selection conflicts before bootstrap, and loads only pipeline context for that
mode. Removed top-level cleanup implementation. Focused restore/recovery/cache,
cleanup confinement/partial-failure, native selection, composition, package,
build, and diff checks pass with Go 1.27.4. Legacy workflow/parser assertions
continue their scheduled conversion before final verification.
2026-11-20 04:05:11 +00:00
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
**Completed.** Runner summaries retain the full selected plan, attempted/failed,
completed, reused/self-skipped, and unattempted outcomes, plus durable output and
speaker/artifact checkpoint evidence. One finalizer owns terminal persistence
and summary construction; failed completion/self-skip saves remain failures,
earlier successes survive, and original, persistence, and release causes stay
inspectable. Native reports follow resource release, honor quiet visibility,
and cannot undo completed work when their writer fails. Runner, checkpoint,
retry, composition, native-report, focused race, configuration/stage/artifact,
build, and diff checks pass with Go 1.27.4. Updated an existing publication test
fixture to supply its separately derived publication rules; remaining legacy
CLI conversions stay assigned to final cleanup.
2026-11-20 04:05:11 +00:00
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
**Completed.** Interrupt/termination signals now cancel the native invocation.
Acquisition checks synchronous native loads, planning and scheduling check the
operation context, and running adapters/storage retain it. Transcription settles
workers and preserves returned shutdown/checkpoint causes alongside cancellation.
Terminal local manifest persistence and evidence readback detach cancellation
without detaching active work; acquired locks still release and completed speaker
and artifact checkpoints remain resumable. Restore preserves its incomplete marker
on cancellation, and initialization/cleanup stop before further local actions.
Deterministic process-signal, mid-transcription/analysis, failed-terminal-save,
retry, acquisition, runner/restore, adapter cancellation, focused race, package,
build, and diff checks pass with Go 1.27.4.
2026-11-20 04:05:11 +00:00
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
**Completed.** Replaced the runner's direct stderr logger with a small
Narratio-owned reporting interface adapted to the native invocation reporter.
Stage starts, durable completions, self-skips, and reuse emit Progress; selected
configuration, destinations, and reuse decisions emit Info, with native Warning
and Debug channels. Console delivery failures stay with native finalization and
do not interrupt checkpointing. Native visibility/boolean/repetition, report,
single-failure, downstream-capture isolation, runner/composition, focused race,
configuration/stage/artifact, build, and diff checks pass with Go 1.27.4.
Removed obsolete logger-construction tests in favor of real native invocation
coverage; captured downstream content is never replayed.
2026-11-20 04:05:11 +00:00
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
**Completed.** Audio acquisition reports actual transfer starts, validated spool
completion, and cache reuse. Transcription and analysis report individual durable
checkpoint completions and validated reuse during partial execution, while paths,
source identity, and reuse decisions remain Info. All messages use the existing
invocation-safe seam and finish with the workers; no ledger or durable schema was
added. Native progress-only and combined-context fixtures verify concurrent
speakers, selective retry, artifacts, audio cache reuse, failed downloads, and
checkpoint-save failures without false completions or multiple final reports.
Focused race, native reporting/checkpoint/resume, configuration/stage/audio/
artifact, build, and diff checks pass with Go 1.27.4.
2026-11-20 04:05:11 +00:00
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.