# ConfigKit Migration Review — Required Remediations

Reviewed 2026-09-07 at `f7a40af`, against the changes after `1558c9c`, the
[feature roadmap](configkit-adoption.md), and the completed
[implementation plan](implementation.md).

The main migration is implemented. The following findings are reproducible gaps
in the intended behavior, not proposals to restore retired compatibility or
filesystem restrictions. P2 denotes a correctness issue to fix before release;
P3 denotes an operator-facing completeness issue also required by the accepted
plan. No application code was changed during this review.

## 1. Derive explicit publish destinations after family expansion

Status: Resolved — P2

Resolution: Missing destinations are now derived through one shared domain helper
both during ConfigKit resolution and again after concrete family expansion. Explicit
destinations remain unchanged, while unknown sources still fail read-only publish
validation. Regression coverage verifies resolved runtime and effective inspection
output for generated members, explicit overrides, and unknown sources.

**Evidence:** `internal/config/pipeline_configkit.go:208` derives missing publish
destinations during the ConfigKit resolver. A concrete family member does not
exist yet, so the resolver ignores the failed derivation. After family expansion,
`internal/config/artifact_families.go:141` calls the now-read-only publish
validator, which rejects the still-empty destination. The previous implementation
could derive it during that later validation.

**Reproduction:** In an otherwise valid pipeline, define a family `meta` over
`party.characters`, with output pattern `artifacts/{character_id}.md`. Select a
valid campaign whose party contains `alice`, and add:

```yaml
publish:
  outputs:
    - source: narratio.artifact.meta_alice
```

`config validate --config <pipeline> --campaign-file <campaign>` fails with
`pipeline.publish.outputs[0].dest is required when destination cannot be derived
from "narratio.artifact.meta_alice"`. Adding `dest: artifacts/alice.md` makes the
same configuration pass. The destination is therefore available and derivable;
the lifecycle omits the required final normalization step.

**Required change:** Complete publish destination resolution after concrete
artifacts exist, before publish validation and final projection/digest generation.
Share the domain derivation logic and keep validation read-only. Preserve
explicit destinations and generated family publish-rule collision checks. Do not
require redundant `dest` fields or revive mutation inside validators.

**Acceptance:** Test an explicit publish source naming a generated member with
omitted destination, an explicit destination override, and a genuinely unknown
source. Validate both effective inspection and resolved runtime configuration.

## 2. Stop re-defaulting an explicitly empty Notarius working directory

Status: Open — P2

**Evidence:** ConfigKit's resolver correctly uses presence-aware defaulting at
`internal/config/pipeline_configkit.go:180`. However,
`internal/config/load.go:454` subsequently replaces any blank working directory
with the config file's directory, irrespective of input presence.
`internal/config/effective_digest.go` also applies a blank-value fallback while
capturing logical paths. These retained legacy fallbacks bypass the new rule that
defaults apply only to absent fields.

**Reproduction:** Set `notarius.enabled: true`, a valid config path, pipeline ID
and output map, and `notarius.working_directory: ""`. With
`config_path: notarius/config.yml`, `config show` succeeds and reports
`working_directory: notarius`; validation never sees the explicit invalid blank.

**Required change:** Let the ConfigKit resolver own the absent-field default.
The subsequent runtime and logical-path conversions must preserve explicit
emptiness so enabled-Notarius validation can reject it. Remove duplicate
value-based defaulting rather than adding another private presence mechanism.

**Acceptance:** Omission still derives the expected directory; explicit empty
and whitespace-only values fail when Notarius is enabled; a configured relative
directory resolves from the pipeline root. Preserve digest relocation invariance.

## 3. Enforce unique base definitions even when a profile removes them

Status: Open — P2

**Evidence:** `rejectDuplicateBaseDefinitions` at
`internal/config/pipeline_configkit.go:354` enumerates only artifact/family keys
remaining in the final typed configuration. It inspects history for those keys
but never examines base declarations removed by an overlay.

**Reproduction:** Import `first.yml` defining
`scriptorium.artifacts.recap.prompt_id` and `second.yml` defining
`scriptorium.artifacts.recap.output_path`. Base validation correctly rejects the
two-file declaration. Add `profiles/clear.yml` containing:

```yaml
scriptorium:
  artifacts: null
```

The same root with `--profile clear` passes. A selected profile can thus hide the
base ownership conflict, contrary to the plan's unique base-definition rule.
This concerns disjoint contributions to one artifact, not ConfigKit's generic
conflicting-leaf checks, which still work.

**Required change:** Discover the complete base declaration set through public
ConfigKit metadata/history, including declarations displaced by an overlay, and
validate ownership independently of final effective-key survival. Keep legitimate
profile overrides and profile-only definitions supported. Do not reparse source
YAML or add a second composer.

**Acceptance:** Cover duplicate ordinary and family definitions hidden by a null
artifact/family container or null Scriptorium section. Base and selected-profile
loads must reject the same base conflict, while a single base declaration with a
valid overlay remains accepted.

## 4. Preserve null versus empty collections in effective YAML

Status: Open — P2

**Evidence:** `internal/config/effective_pipeline.go:154` marshals the typed
projection directly with `yaml.Marshal`. The encoder emits nil slices as `[]`
and nil maps as `{}`, while the JSON projection used by diff and digest preserves
them as `null`. The shared input type does not guarantee shared output semantics.

**Reproduction:** Set `audita.modules: null` in a valid base and
`audita.modules: []` in `profiles/empty.yml`. Both `config show` invocations emit
`modules: []`, but `config diff default empty` reports:

```text
changed audita.modules null []
```

The commands disagree about the effective value. The same renderer also supplies
the resolved pipeline diagnostic written by prepare.

**Required change:** Render YAML from a credential-safe projection that explicitly
preserves nulls and empty collections, consistently with the semantic projection.
Keep exact integers and safe credential reference names. An output-only conversion
is appropriate; do not restore YAML decoding or a configuration parser. This
requires truthful inspection, not a guarantee that inspection output is reloadable.

**Acceptance:** Verify null versus empty maps and slices through the public show
boundary, and agreement with diff/digest distinctions. Retain credential-leakage
and exact-integer regression coverage.

## 5. Complete provenance for generated artifacts and inferred dependencies

Status: Open — P3

Two new reporting paths lose available declaration information:

- **Profile contributions to family members:**
  `internal/config/artifact_catalog.go:52` fills a generated member's definitions
  from the single `member.Source`. That source is chosen by the first matching
  non-default family field in `artifactFamilySource`, not the full set of effective
  contributors. Define family `meta` in the base and override its `prompt_id` in
  `profiles/testing.yml`. `config artifacts --profile testing` reports only the
  base file for `meta_alice`, even though `config sources` correctly attributes
  that member's prompt to the testing overlay.
- **Inferred ordinary dependencies:** With `second.inputs.prior.source` set to
  `narratio.artifact.first` and no explicit dependency list, `config sources`
  reports `scriptorium.artifacts.second.depends_on` as `default / default`.
  `finalizeArtifactDependencies` stores the input-edge origin, but the effective
  ownership projection retains the pre-inference default attribution from
  `internal/config/effective_digest.go:55` and does not consult that origin.

**Impact:** Operators inspecting a testing profile or following a dependency can
be directed to the wrong file or told a user-derived value is a central default.
Runtime ordering and generated artifact values were correct in these reproductions.

**Required change:** Use ConfigKit's contributing locations for family definition
sets, as for ordinary artifacts, and add narrow generated attribution for inferred
dependency lists using their retained edge origins. Preserve family/character/party
identity and deterministic ordering. Avoid introducing a second general provenance
store or choosing a file based on the first alphabetically visited field.

**Acceptance:** A profiled family catalog exposes both relevant files; an inferred
edge points back to its input declaration; mixed explicit/inferred dependencies
retain their relevant contributors. Verify catalog and sources agree after expansion.

## 6. Surface successful secrets bootstrap reports, including skipped empty variables

Status: Open — P3

**Evidence:** `internal/app/secrets_bootstrap.go:36` discards the report whenever
`LoadSecretsDir` returns no error. Reports are only rendered when directory
bootstrap itself fails. This does not implement the roadmap's safe bootstrap
reporting boundary or Stage 6's warning presentation requirement.

**Reproduction:** Place a synthetic key in `secrets/NARRATIO_REVIEW_KEY`, reference
it from `audita.llm_api_key`, and invoke config validation with
`NARRATIO_REVIEW_KEY=` in the environment. ConfigKit correctly skips the file
because the variable already exists, then typed loading fails with `secret.empty`.
Narratio shows only that load failure, omitting the bootstrap report's
`skipped_existing` and `ExistingEmpty` information. A successful load likewise
discards all bootstrap results.

**Required change:** Retain and render or summarize the safe report once per
invocation through a diagnostic output channel, including when a later typed load
fails. Make skipped-existing-empty outcomes explicit. Preserve process environment
precedence and the existing partial report on failure; keep values out of all
diagnostics and keep structured/YAML stdout uncontaminated. Do not add bootstrap
rollback, retries, or repeated directory loading.

**Acceptance:** Command-level tests demonstrate safe success/report output and a
useful skipped-empty diagnostic, without leaking a synthetic secret or polluting
show output. A two-profile diff still bootstraps and reports only once.

## Verification and scope

The following checks passed at the reviewed commit:

- `go test ./...`
- `go test -race ./...`
- `go vet ./...`
- `go build ./...`
- The release asset builder for `v2.0.0`, producing exactly Linux amd64, Linux
  arm64, and macOS arm64 assets; the Linux amd64 binary reported the expected version.

The existing full suites include documentation and maintained-example checks.
The findings above were additionally reproduced through a freshly built CLI with
isolated temporary YAML fixtures and synthetic credentials. No live downstream
tools or cloud services were invoked. Linux arm64 and macOS arm64 were cross-built,
not tested natively. No tag was created or pushed.

The migration removes a net 1,235 production Go lines and 843 test Go lines versus
`1558c9c` (physical diff lines, including comments and whitespace). ConfigKit owns
generic loading/composition; Narratio retains domain resolution, orchestration,
safe inspection, and adapter delivery. These findings require completing that
design, not reversing the simplification.