Record CommandKit migration review findings
This commit is contained in:
176
docs/roadmap/remediation.md
Normal file
176
docs/roadmap/remediation.md
Normal file
@@ -0,0 +1,176 @@
|
||||
# CommandKit migration review
|
||||
|
||||
## Scope
|
||||
|
||||
Reviewed all 21 stages of [implementation.md](implementation.md) against the
|
||||
[approved roadmap](commandkit.md), the implementation from `86692d5` through
|
||||
`0117f3f35d73b3025a0222d25b6924ef455592e1`, current source and documentation,
|
||||
behavioral tests, and focused diagnostic reproductions. Completion annotations
|
||||
were treated as claims to verify rather than proof of completion.
|
||||
|
||||
The native command boundary, actual ConfigKit inspection results, separate domain
|
||||
catalogs, independent selections, reporting, and cancellation architecture are
|
||||
substantially implemented. The following three P2 findings require remediation.
|
||||
This review makes no application changes.
|
||||
|
||||
## 1. P2: Preserve campaign inheritance when materializing session documents
|
||||
|
||||
Stages: 3, 6, and 13; preservation checks in Stage 21.
|
||||
|
||||
Locations: `internal/config/load.go:254–255`,
|
||||
`internal/config/document_render.go:52–62`, and
|
||||
`internal/app/prepared_session_roundtrip_test.go:88`.
|
||||
|
||||
`SessionDocument` now points to the completed session, which already contains
|
||||
campaign defaults. `RenderSessionDocument` writes those inherited stable input
|
||||
paths as explicit session fields. Reloading generated session YAML or the
|
||||
published prepared-session fallback therefore replaces inheritance with fixed
|
||||
paths from the producing campaign. The optional spell-catalog default is also
|
||||
written whenever nonempty.
|
||||
|
||||
Reproduction: load a session whose authored inputs contain only audio; render its
|
||||
prepared session; change the selected campaign's `speakers_file`; reload the
|
||||
prepared bytes with that campaign. The received session still selects the old
|
||||
speaker file. Its native metadata now calls this a session override. The
|
||||
round-trip test was changed to expect `session_config` ownership for the formerly
|
||||
inherited speaker path, so it accepts the regression rather than protecting the
|
||||
prior behavior.
|
||||
|
||||
The [configuration contract](../config.md#pipeline-imports-and-overlays) says
|
||||
omitted session fields remain eligible to inherit the receiving campaign's
|
||||
values. Preserving materialization/authoring semantics was part of the plan.
|
||||
Freezing inherited resource paths is an additional semantic commitment, not a
|
||||
requirement of completing defaults before the ConfigKit handoff. It can select
|
||||
obsolete resources after campaign updates and retain paths unavailable on a
|
||||
receiving host.
|
||||
|
||||
Required remediation:
|
||||
|
||||
- Keep the actual completed ConfigKit result authoritative for inspection and
|
||||
execution. Use native explicitness metadata when serializing session-owned
|
||||
fields so inherited campaign input defaults remain omitted in materialized
|
||||
session YAML. Retain explicit session overrides and explicit optional-input
|
||||
clearing. Preserve import flattening and source-relative resolution.
|
||||
- Apply the distinction to preparation, local/remote initialization, and
|
||||
committed-session fallback through their shared renderer. Do not introduce a
|
||||
replacement configuration result or reparse authoring files for inspection.
|
||||
- Restore coverage that materializes an omitted default, changes the receiving
|
||||
campaign, and observes the new default. Include an explicit override and an
|
||||
explicit empty optional spell catalog to establish the difference. Update the
|
||||
existing round-trip expectation rather than preserving the newly frozen
|
||||
behavior as a contract.
|
||||
|
||||
## 2. P2: Classify identifiable Narratio input errors consistently
|
||||
|
||||
Stages: 1, 7–10, and 12; native outcome verification in Stage 21.
|
||||
|
||||
Locations: `internal/app/configuration_commands.go:75–96`,
|
||||
`internal/app/configuration_acquisition.go:294–297`, and
|
||||
`internal/app/command_outcome.go:30–55`.
|
||||
|
||||
Two integration paths return operational status 1 for identifiable input errors:
|
||||
|
||||
1. Native configuration acquisition/comparison returns
|
||||
`config.SessionIdentityError` for a supplied campaign/session identity that
|
||||
differs from the selected file. The scope wrapper adds explanatory text but
|
||||
passes the same error to ckconfig, whose classifier does not know Narratio's
|
||||
type. For example, `config show --scope campaign --campaign-file FILE
|
||||
--campaign WRONG` returns status 1. Session assertions and comparison-side
|
||||
assertions have the same problem. The application outcome adapter recognizes
|
||||
the type for domain commands, but native config commands do not use it.
|
||||
2. Catalog derivation returns plain errors for invalid configuration relations.
|
||||
A configured artifact with `depends_on: [missing]` reaches domain derivation,
|
||||
then `artifacts list` and `run --stage analyze` return status 1. The error
|
||||
unambiguously identifies invalid supplied configuration, not a service failure.
|
||||
Such relational validation belongs in domain derivation; moving family
|
||||
expansion into native app inspection is not the remedy.
|
||||
|
||||
The roadmap and [CLI outcome contract](../cli.md#cancellation-and-exit-status)
|
||||
reserve status 2 for invalid invocation or identifiable configuration input.
|
||||
Current identity tests check only a nonzero status and explanatory text, leaving
|
||||
this integration mismatch undetected.
|
||||
|
||||
Required remediation:
|
||||
|
||||
- Preserve the agreed status 2 classification for post-resolution identity
|
||||
assertions in native config acquisition and comparison, including the right
|
||||
side. Use genuine native resolution/validation or a supported classification
|
||||
integration point while preserving the underlying typed cause. If the released
|
||||
API lacks the necessary integration point, address that narrow capability
|
||||
upstream rather than forking native commands or matching error strings.
|
||||
- Give Narratio-owned invalid domain-configuration relations typed input
|
||||
classification at their existing boundary. Keep cancellation, storage/access
|
||||
failures, shutdown/persistence errors, and mixed operational causes at status 1.
|
||||
Do not classify every acquisition or catalog error as user input indiscriminately.
|
||||
- Add native invocation regressions asserting exact status classification for
|
||||
campaign/session mismatch, comparison-side mismatch, and an unknown artifact
|
||||
dependency, alongside an operational or joined-cause counterexample.
|
||||
|
||||
## 3. P2: Correct the documented empty spell-catalog behavior
|
||||
|
||||
Stage: 20.
|
||||
|
||||
Location: `docs/config.md:706`, the `inputs.spell_catalog_file` session field row.
|
||||
|
||||
The field table says an empty or omitted value inherits the campaign value.
|
||||
The implemented native-default behavior distinguishes them: omission inherits;
|
||||
an explicit empty string clears the optional input. This behavior is exercised
|
||||
by `TestSessionDefaultsCompleteBeforeNativeHandoff` and is consistent with the
|
||||
agreed explicit-presence rules. The table contradicts both implementation and
|
||||
the reference's general defaults section.
|
||||
|
||||
Required remediation: update the field row and any equivalent current guidance
|
||||
to state the implemented distinction. Retain optional-input clearing behavior;
|
||||
do not change it to satisfy the obsolete wording. This is a documentation-only
|
||||
correction, separate from preserving inherited versus explicit fields during
|
||||
materialization in finding 1.
|
||||
|
||||
## Stage-by-stage coverage
|
||||
|
||||
| Stage | Evidence reviewed and result |
|
||||
| --- | --- |
|
||||
| 1 | Released module selection, native application/process boundary, lazy construction, and outcome adapter; finding 2 covers classification gaps. |
|
||||
| 2 | Retained pipeline/campaign results, lifecycle normalization/validation, native metadata, and absence of replacement inspection results. |
|
||||
| 3 | Campaign defaults, explicit presence, session assertions, and resource bases; findings 1 and 2 cover materialization and native assertion outcomes. |
|
||||
| 4 | Selected-party results/players, pure family expansion, collision/dependency checks, and separate publication rules. |
|
||||
| 5 | Concrete-catalog consumers in planning, analysis, semantic fingerprints, adapter composition, and runtime registration. |
|
||||
| 6 | Preparation, publication, restore round trips, and semantic evidence; finding 1 covers inherited input serialization. |
|
||||
| 7 | Exact-file/local/remote acquisition, source labels, one-time bootstrap, retained errors, and resource cleanup; finding 2 covers typed input classification. |
|
||||
| 8 | Four native scopes, path/history/findings capabilities, aggregate behavior, and lazy acquisition. |
|
||||
| 9 | Independent comparison inputs/defaults, app-only overrides, native difference reports and status 3; finding 2 covers assertion failures. |
|
||||
| 10 | Native bounded run/regeneration wiring, force and artifact selection, and shared execution; finding 2 covers invalid domain configuration. |
|
||||
| 11 | Shared read-only planning, publication actions, and configured artifact catalog reporting. |
|
||||
| 12 | Structured validation/status/artifact inspection, partial findings, local/remote evidence, and read-only behavior. |
|
||||
| 13 | Initialization targets, authoring contexts, generated YAML, explicit lock commands, and conditional lock mutations; finding 1 covers inherited defaults. |
|
||||
| 14 | Restore and cleanup declarations, dry-run behavior, exact action reports, confinement, conflicts, and partial failure handling. |
|
||||
| 15 | Failed-attempt accounting, partial run results, checkpoint evidence, terminal persistence, cause retention, and lock release. |
|
||||
| 16 | Interrupt/termination wiring, context propagation, worker settlement, detached terminal local persistence, and resumability. |
|
||||
| 17 | Narratio-owned reporting seam, native visibility/channels, stage progress, and isolation from downstream debug capture. |
|
||||
| 18 | Audio transfers/cache reuse, speaker/artifact durable completions, checkpoint reuse, and progress-only integration tests. |
|
||||
| 19 | Native completion/static/path hints, lazy discovery tests, and retirement of handwritten routing/parsing/rendering. |
|
||||
| 20 | Canonical references, workflows, migration table, attribution, supported platforms, and preserved release history; findings 1 and 3 cover remaining documentation divergence. |
|
||||
| 21 | Full test/race suites, vet/build, assembled workflows, focused review reproductions, and remaining verification recorded below. |
|
||||
|
||||
No other actionable requirement strengthening was identified. The removed CLI
|
||||
aliases, native flag conventions, inspection-only overrides, domain/native-view
|
||||
separation, and deferred workspace/downstream changes follow the agreed scope.
|
||||
|
||||
## Review validation
|
||||
|
||||
Using official Go 1.27.4 against the reviewed application source:
|
||||
|
||||
- `go test ./...` passed.
|
||||
- `go test -race ./...` passed.
|
||||
- `go vet ./...` and `go build ./...` passed.
|
||||
- Focused Go-overlay diagnostics reproduced both cases in finding 2 and the
|
||||
campaign-default freezing in finding 1. Diagnostic files remained under
|
||||
`/tmp`; application source and tests were unchanged.
|
||||
- `go mod tidy -diff` passed.
|
||||
- The nonpublishing asset builder passed with `v0.0.0-test`, producing Linux
|
||||
amd64/arm64 and macOS arm64 binaries under `/tmp` and verifying the host
|
||||
binary's embedded version. macOS evidence is compilation-only.
|
||||
- Documentation-link checks and `git diff --check` passed with this review
|
||||
document present.
|
||||
|
||||
Only this remediation document changes the repository. No release, tag, push,
|
||||
CI polling, or live downstream service invocation was performed.
|
||||
Reference in New Issue
Block a user