# ConfigKit adoption review remediation ## Review scope Reviewed the twelve completed stages in [implementation.md](implementation.md) against [the approved target](configkit.md), the implementation diff from `65d0e51` through `39a958675d68e940799f4cb8c8e6748830d1483a`, current code, documentation, focused diagnostic reproductions, and repository checks. An integration-focused follow-up reviewed the same implementation at `bccf03a99f45c2b9b342412b85f70e356663df61`, tracing each stage into existing command, preparation, publication, restore, and inspection workflows. Items 5–6 are additional findings from that pass; items 1–4 remain outstanding. The native configuration architecture is substantially implemented. The items below are the remaining required corrections; this review does not implement their fixes. ## 1. P2: Distinguish effective resource origins from superseded history Stage: 9, with documentation coverage in Stage 11. Location: `internal/config/effective_pipeline.go:274–280`, `effectivePipelineOwners`. For a resolution-origin field, the projection adds every main/overlay origin from native history to the same current source-role records. This conflates effective ownership with historical definitions. For example, a root containing `audita: {config_path: original.yml}` and an overlay containing `audita: {config_path: replacement.yml}` produce `audita.config_path` records for the root, overlay, and resolution. The root's superseded value did not supply the effective resource; its record is indistinguishable from an effective contributor. The error is visible to operators using `config sources` to locate the definition that controls an integration path. Required change: use native effective/pre-normalization evidence for effective input attribution. If historical definitions are also displayed, label them separately. Preserve historical contributor information in the artifact catalog where it is explicitly definition evidence. Keep the projection thin; another provenance reconstruction service is unnecessary. Verification: cover a normalized resource with a superseded root/import value, an overlay replacement, and inheritance. The effective overlay and resolution remain visible, while superseded evidence is either absent from current-owner records or explicitly identified as history. Update the command reference for the resulting roles. ## 2. P2: Remove the restore test's incidental startup deadline Stage: 12; the fragile timing assumption predates this migration. Location: `internal/app/restore_execution_test.go:383–387`, `TestExecuteRestoreLockConflictFailsAndWritesNothing`. The test starts a 100 ms context deadline before calling the complete restore command, then requires an error from session-lock acquisition. With the current configuration workflow under the full race suite, the deadline can expire during earlier work. The reproduced failure was: ```text restore: remote check current commit pointer "dnd/campaigns/sample-campaign/sessions/2026-05-03/current/commit-pointer.json": context deadline exceeded, want lock failure ``` An isolated application-suite run passed, while a subsequent full race run failed at this assertion. A green isolated run therefore does not establish Stage 12's repeatable final validation. The test implicitly requires unrelated startup work to finish within 100 ms, which is not an application requirement. This is not evidence that production session locking is incorrect. Required change: make the contention/cancellation test target the intended lock boundary without timing all preceding configuration and remote discovery. Use synchronization at an appropriate existing test boundary, or separate lock-service contention coverage from command-level no-write coverage. A larger arbitrary startup timeout alone leaves the underlying timing dependence. Preserve the assertions that restore cannot write protected files while another invocation owns the session lock. Verification: repeat the focused test and rerun the complete race suite under normal package concurrency. Report actual outcomes rather than treating an isolated pass as full-suite success. ## 3. P3: Finish the planned field-level publish resolution cleanup Stages: 1 and 3; the roadmap's integration scope requires field-level recording for field-only changes. Location: `internal/config/pipeline_configkit.go:202–215,232–235`, `resolvePipelineConfig`. Publish requiredness and derived destinations already use field-level native helpers. The resolver additionally tracks `defaultedOutput`, records the entire `publish.outputs` list for those field edits, and retains a comment claiming that child records cannot cover the changes. ConfigKit v1.2.1 supports exactly this field-level coverage. The ancestor record adds redundant history: querying an untouched output source also returns a whole-list normalization operation with publish-default/destination reasons. Required change: remove the obsolete list-coverage tracking, redundant ancestor records, and inaccurate comment for these field-only edits. Keep field helpers and any whole-list records actually needed for structural membership/order changes. This is completion of the selected simplification, not a new ban on container-level records. Verification: a temporary diagnostic overlay removing only the obsolete workarounds successfully loaded defaulted/derived publish outputs and passed the append/upsert/replace collection tests. Add suitable behavioral coverage for effective values and precise field history, without asserting private helper invocation counts. ## 4. P3: Pin Go attribution links to the selected source commit Stages: 1 and 11. Location: `docs/oss/attribution.md:125–128`. The updated Go entry uses `go1.27.4` in the LICENSE, PATENTS, and Source URLs. The adopted OSS policy requires commit-specific upstream source and notice links. The preceding entry used a source hash; this update replaced it with tag-based references. Required change: use the verified Go 1.27.4 source commit `7b2881024c95a11ddb86663a616340aa3a88b67f` in those three URLs. The hash was resolved through the official Go repository's release tag. Keep the existing license texts, factual notice wording, and Go version identification. Verification: confirm the links identify that source revision and run the documentation checks. This requires no licensing change or new release gate. ## 5. P2: Give session initialization the correct authoring context Stage: 4, interacting with materialization and command validation in Stages 6, 11, and 12. Locations: `internal/app/operator_session_init.go:78–102` and `internal/config/load.go`, `LoadSessionBytesWithOptions`. The existing initializer validates its rendered document through `LoadSessionBytesWithOptions`. That loader now deliberately describes a contextless remote snapshot with imports disabled. A generated local session is an authored file, so this caller no longer uses the same semantics as the ordinary file loader. Two focused reproductions show the mismatch: - A local template with a required `shared.yml` import containing constant metadata fails with `import.disabled`, even when the import exists beside the generated destination and the resulting local session is otherwise valid. - With `--audio-dir ./audio` and an output in another directory, initialization validates the invocation-directory audio path, then writes the original relative text. Loading that generated file selects the output-directory audio path. The persisted resource differs from the validated resource and the documented invocation-relative CLI interpretation. Required change: distinguish authored initialization from contextless snapshot loading. Use ConfigKit's supported source/context facilities for local composition, and make persisted resource references reproduce the validated configuration. Materialize effective values where moving or uploading the document would leave authoring imports unresolved. Preserve the narrow template substitution contract and the existing contextless remote-loading boundary. Verification: initialize a local imported template, load its output through the ordinary loader, and check the imported values. Cover a destination outside the invocation directory and relative CLI audio input. Check that remote generation emits a consumable standalone snapshot and that ordinary placeholder and identity validation still applies. These cases exercise initialization through the real configuration owner without adding remote companion retrieval. ## 6. P2: Reconcile remote session updates with committed-session selection Stage: 7, interacting with the existing initializer and shared command loader from Stages 2 and 4. Locations: `internal/app/config_loader.go:194–223` and `internal/app/operator_session_init.go:113–138`. The new remote loader selects a committed `run:prepare/inputs/session.yml` whenever the current commit declares one. The existing `session init --remote` writer continues to update the session-root `session.yml`. After publication, the writer and reader therefore use different authoritative objects. A prepare → publish → `session init --remote --force --title "After publication"` reproduction succeeds and writes the requested title to the root object. A subsequent ordinary command load still returns the old title from the committed prepared session. The same selection would ignore changed audio or previous-session settings. The documented overwrite workflow silently stops affecting later runs once the session has been published. Required change: reconcile remote input authoring and selection so successful operator updates can be used by subsequent runs. Preserve immutable published snapshots and committed restore authority. Keep an effective remote editing or override workflow; silently ignoring updates or introducing a blanket ban on editing published sessions would leave the integration unresolved. Update the canonical operator guidance for the resulting selection behavior. Verification: publish a prepared session, update it through the supported remote workflow, then load it through the ordinary run/plan configuration path and check the updated values. Include audio or previous-session selection as well as title. Verify that restore still uses its selected immutable commit and that published objects are unchanged by the authoring update. ## Stage-by-stage disposition | Stage | Review result | | --- | --- | | 1: Dependency/toolchain | ConfigKit v1.2.1 and Go 1.27.0/1.27.4 selected; remaining notice pinning in item 4. | | 2: Discovery/bootstrap | Native discovery, exclusive explicit selection, independent bootstrap, and shared diff bootstrap are present. | | 3: Resource bases | Native origin-based resolution and fallbacks are present; field-record cleanup remains in item 3. | | 4: Campaign/session imports | File contexts, contextless remote snapshots, native optional discovery, and detached document values are present; initialization still uses the snapshot path in item 5. | | 5: Party imports | Imported rosters, source-aware ordering, canonical rendering, players, and family resolution are present. | | 6: Prepared inputs/resume | Canonical document materialization and matching resume evidence are present. | | 7: Publish/restore | Prepared documents flow through immutable committed run objects and restore; remote initialization and committed selection conflict in item 6. | | 8: Final-domain snapshots | Defaults-backed native snapshots, safe credential identities, rendering, and digest integration are present. | | 9: Diff/provenance | Native diff and pointer paths are present; effective/history attribution needs item 1. | | 10: Examples | Destination-based definitions, directory imports, list operations, split roster, and secondary imports are demonstrated. | | 11: Documentation/policy | Current references cover the migration; finish attribution, source-role, and initialization/selection corrections above. | | 12: Final verification | Existing integration checks pass; add coverage for items 5–6. Full race validation remains unreliable because of item 2. | The approved discovery, bootstrap, relative-resource, and secondary-import changes are deliberate contract changes. Items 5–6 describe implementation inconsistencies in existing workflows. Item 2 concerns an incidental test-time performance assumption, not a requested startup guarantee. ## Initial review validation Using Go 1.27.4: - `go test ./...` passed. - `go test -race ./...` failed at item 2. The isolated application race suite passed, as did five subsequent repetitions of the focused restore test. - `go vet ./...`, `go build ./...`, and `go mod tidy -diff` passed. - Release-asset cross-builds passed for Linux amd64, Linux arm64, and macOS arm64 with the existing `v0.0.0-test` label and temporary output directory. - Focused diagnostic reproductions confirmed items 1 and 3. Temporary Go overlays kept those diagnostics and proposed-code experiments outside the repository. - Documentation checks and `git diff --check` passed. Review execution made no application changes and invoked no live subprocess services or release publication. ## Integration follow-up validation Using Go 1.27.4 at the follow-up revision: - `go test ./...` passed with local test-server sockets permitted. The sandboxed attempt was blocked by `httptest` socket restrictions. - Focused migration checks across config, stage, and app packages passed both ordinarily and under `-race`. These exercised native discovery/inspection, imported inputs, canonical materialization, published-session round trips, initialization, and command/execution agreement. - Temporary overlay diagnostics reproduced both aspects of item 5 and the publication/update conflict in item 6, ordinarily and under `-race`. - The full race suite was not repeated in this pass; item 2 retains the initial review's observed failure. Application code is unchanged. Only this remediation document changed. Diagnostic files remained outside the repository, and object storage used an in-memory fake.