# ConfigKit v0.5.0 implementation plan ## Scope and authority Implement [the ConfigKit roadmap](config.md). It owns the target, compatibility choices, and rationale. This plan covers Narratio's upgrade from v0.4.2 to v0.5.0 and integration with native sibling inheritance. Audita adoption and workspace reorganization remain subsequent, separately planned work. ConfigKit owns source assembly and native provenance. Narratio validates the effective domain configuration and exposes the library's metadata to operators. This revision replaces the earlier plan to repair declaration-history counting with removal of that additional acceptance rule. It retains supported callbacks, presence-sensitive defaults, party ordering, and provenance inspection. The reviewed upstream revision is `dc09959cca4e105f49ec316c6d4ba585bd2340bd`, tagged `v0.5.0`. Use the released module, not a local replacement. The pinned [configuration contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/config.md) and [consumer guide](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/consumers/README.md) own upstream semantics. Read their sibling-inheritance and metadata sections when working on the relevant stages; source may also be inspected in the selected Go module cache. The sibling checkout is optional reference material, not a build or test dependency. ## Working instructions The audience is a Luna coding agent. Complete the numbered stages in order. Each stage is a bounded unit with its own verification and completion criteria. Inspect current code before editing; the paths below identify owners rather than requiring changes to every listed file. - Start with `docs/development.md`, `docs/policy/agents.md`, and `config.md` in this directory. Follow the development policy-reading guide. Architecture, testing, documentation, and OSS policies apply to this work; release policy applies if discussing compatibility or eventual release preparation. - Use Go 1.26. Prefer the repository's graph tools for code discovery and inspect focused tests at each package boundary. - Keep ordinary `Load`, typed defaults, explicit imports, one selected overlay, domain validation, and current path-resolution rules. Native inheritance is available wherever ConfigKit and Narratio's schema permit it, with no new collection allowlist, opt-in flag, or Narratio-owned inheritance engine. - Trust ConfigKit's structural acceptance rules. Remove Narratio's one-base-file-per-entry check rather than making it inheritance-aware. Validate resulting domain values; source history is diagnostic evidence, not another acceptance gate. Parent entries that survive composition remain ordinary entries subject to applicable domain rules. - Use native presence and provenance APIs for defaults and operator inspection. Keep supported callbacks and party ordering. Do not impose post-`Load` callback relocation, relaxed empty/null semantics, or retirement of `config sources`. - Keep invocation-owned secrets bootstrap and shared exact-name credential forwarding unchanged. Do not introduce a second base load, file reparse, or historical-secret lookup to reconstruct provenance or validate old input. - Tests use temporary files, controlled synthetic secrets, and real internal collaborators. No downstream executable, sibling checkout, cloud service, or paid provider is needed. Protect integration behavior rather than duplicating ConfigKit's generic algorithm tests or freezing incidental output. - Commit each completed nonempty unit with a short plain-English message after suitable validation. Report blockers and incomplete work accurately. If a review-only task needs no source fix, retain useful behavioral coverage and report that result rather than making a cosmetic rewrite. - Update affected canonical documentation with each implemented behavior change. In particular, Stage 2 updates the removed authoring restrictions and Stage 3 updates changed inspection meanings. Stage 6 consolidates the policy review, inheritance guidance, and example; it is not a reason to leave earlier completed commits describing obsolete behavior. - For documentation updates, state the policy affirmatively using concise, factual language. Avoid negative parallelism. Do not adopt layered loading, new source types, source-relative rebasing, abstract artifacts, automatic YAML conversion, new execution selection rules, new output collision policy, or changes to subprocess credentials and workspace paths in this feature. Existing domain validation and reuse rules still apply; do not add prohibitions, hardening, or guarantees merely because they can be tested. This plan does not authorize a release, push, tag, ADR acceptance, or retirement of pending roadmaps. ## Stage 1: Select the released dependency and update attribution Purpose: establish the actual dependency baseline before integration work. Read `go.mod`, `go.sum`, `docs/oss/attribution.md`, the OSS policy, and the selected release's notes, `COPYRIGHT`, and `LICENSE`. 1. Select `gitea.maximumdirect.net/eric/ConfigKit@v0.5.0` with the normal Go module workflow. Keep Go 1.26 and avoid unrelated dependency upgrades. 2. Update ConfigKit's attribution entry to v0.5.0 and use the full reviewed commit for its Source, COPYRIGHT, and LICENSE links. Preserve upstream copyright wording, SPDX expression, and applicable local license links. Its license and YAML dependency are unchanged; no new license copy is needed. 3. Inspect module changes for unintended churn or a local `replace`. Existing configuration loaders should compile without adopting optional APIs. Verify with `go test ./internal/config ./internal/app ./internal/doccheck` and `go mod tidy -diff`. Confirm `go list -m gitea.maximumdirect.net/eric/ConfigKit` selects v0.5.0 without a replacement. Complete when the released dependency and notices agree and current focused tests pass. The cross-file inheritance defect is addressed in the next stage; this stage does not claim that new inheritance behavior is fully integrated. ## Stage 2: Remove source-authoring acceptance gates Purpose: accept structurally composed configuration from ConfigKit and reject only invalid effective Narratio domain configuration. Read `internal/config/pipeline_configkit.go`, particularly `pipelineMetadataFromConfigKit` and `rejectDuplicateBaseDefinitions`, `pipeline_configkit_test.go`, and `expandFamilyPublishRules` and its tests in `internal/config/artifact_families.go` and `artifact_families_test.go`. 1. Delete `rejectDuplicateBaseDefinitions` and its invocation. Do not replace it with filtering of inheritance events, direct-declaration counting, or another source-history validator. 2. Replace `TestPipelineConfigKitRejectsDuplicateBaseDeclarations` with behavior coverage showing that disjoint contributions to one artifact/family compose successfully when the resulting domain entry is valid. Check selected-overlay replacement/removal without Narratio rejecting superseded declarations. 3. Add cross-file artifact and family inheritance regressions. Supply valid surviving parent and child entries with distinct output destinations, and campaign/party context for family expansion. Verify child identities and effective fields; the inheritance regression must fail on the old check. 4. Remove the `publishDeclared` gate in `expandFamilyPublishRules`, its metadata population, and state retained only for that gate. Validate family publication against the effective `Publish` value, whether authored or supplied by defaults. Preserve the missing-effective-publish check, ordinary enablement behavior, destination validation, and conflicts between effective publish rules. Update the test that currently fabricates an explicit-declaration flag. 5. Retain effective-domain rejection, including invalid artifacts, unresolved dependencies, and destination collisions under current rules. Reuse existing tests where adequate. Retain a representative structural-conflict check at the loader boundary; ConfigKit owns the full conflict/precedence matrix. Verify with `go test ./internal/config`. Assert effective outcomes and safe error categories, not entire diagnostic text or private metadata event order. Do not run a separate base-only load to validate overwritten input. Complete when valid cross-file composition/inheritance succeeds and invalid effective configuration still fails before execution, without authored-source acceptance gates. Keep native metadata available for the next stage. ## Stage 3: Simplify provenance inspection around native APIs Purpose: preserve useful operator inspection without a parallel provenance system or a unique-defining-file contract for composite entries. Read `internal/config/artifact_catalog.go`, `artifact_families.go`, `effective_pipeline.go`, `effective_digest.go`, and the metadata projection in `pipeline_configkit.go`. Inspect `internal/app/config_commands_test.go`, `config_artifacts_test.go`, and ConfigKit's public metadata contracts. 1. Keep `config sources` and provenance-bearing `config artifacts` output. Use public ConfigKit sources, effective origins, history, and explanations for the information they own. Keep presence queries and recorded callbacks where needed; retaining returned metadata is not duplicating its implementation. 2. Review existing helper/state layers for duplicated tracking. Remove redundant cached field-ownership reconstruction where the same result is available directly from retained metadata. Keep a small projection where needed for Narratio's generated family/character/party context and output formatting. Do not add a provenance service, custom ancestry graph, or second source parse. 3. Exercise Stage 2's inherited and multi-file entries through `EffectiveArtifactCatalog` and `EffectivePipelineSources`. Report actual contributors and child overrides. Keep historical definition evidence distinguishable from effective field origins as exposed by ConfigKit. 4. Replace `artifactFamilySource`'s arbitrary first-contributor ownership with native source/origin evidence. Do not infer a unique base defining file or implement a new declaration-accounting algorithm. Composite origins may have several sources; preserve them using existing repeated source records and comma-separated catalog source lists. Adjust the runtime-only representation minimally where a single-source field cannot carry that evidence. 5. Preserve logical artifact IDs, family/character identities, party provenance, inspection command names, and read-only behavior. Retain existing headers where their meanings remain accurate; explain that family source evidence may be composite instead of promising a unique defining file. Do not change native-metadata-based party ordering merely to avoid library APIs. Verify with `go test ./internal/config ./internal/app`. Cover a child family inheriting across files, an entry composed from disjoint files, and an overlay override. Check meaningful source records, logical identities, and absence of secret values rather than full formatted snapshots or upstream event ordering. Complete when native provenance remains useful and truthful, redundant tracking is removed where practical, and no acceptance rule depends on contributor count or an inferred defining file. Application derivation context remains available. ## Stage 4: Verify inherited presence, domain resolution, and path bases Purpose: prevent Narratio's application defaults or normalization from undoing the library's inherited explicit input. Read `pipelineConfigDefaults`, `resolvePipelineConfig`, and `internal/config/load.go`, including `finalizeLoadedPipeline` and `resolveNotariusPaths`. Inspect the current presence/defaulting tests and the relevant domain validators. 1. Add representative inheritance cases for explicit false, zero, empty, and null input versus genuinely absent input. Include a pointer boolean and an entry-level absence-based default where Narratio consumes metadata. For example, inherited `render_debug: false` can exercise artifact presence; inherited empty Scriptorium timeout can exercise an existing invalid value that must not silently become its default. 2. Preserve the existing domain outcome for each chosen field. Valid explicit values retain their value; explicit values already invalid must still fail ordinary validation rather than be refilled. An empty mapping merges under ConfigKit's rules and must not be described as universal container removal. 3. Exercise overlay composition before inheritance: modify a parent's field in the selected overlay and confirm the child's inherited result uses that effective value. A child override still wins over its parent. 4. Verify a known root-relative field, such as enabled Notarius `config_path` or `working_directory`, when inherited from an imported declaration. Resolve it exactly as the existing field contract does. Do not use passive SourceContext to rebase it to the parent's or child's source directory, or newly normalize other path fields merely to make their behavior uniform. 5. Fix any demonstrated Narratio integration defect at its existing defaulting or domain-resolution owner. Use ConfigKit presence and recorded operations; retain supported defaults/resolver/validator callbacks. There is no required move to post-`Load` functions. Do not recreate structural inheritance, inspect old input to add acceptance rules, or relax empty/null semantics to avoid using the library's presence API. Verify with `go test ./internal/config`. Keep coverage representative; generic missing-parent, cycle, resource-context, and expansion-limit matrices belong to ConfigKit. Parents must remain valid Narratio entries, not special templates. Complete when inherited explicit input and absent defaults have distinct, correct domain outcomes and existing path bases are unchanged. ## Stage 5: Verify safe effective projections and inherited credentials Purpose: ensure inheritance changes neither semantic comparison nor the existing secret boundary. Read `internal/config/effective_pipeline.go`, `effective_digest.go`, `effective_projection.go`, `scriptorium_credentials_test.go`, and the effective projection tests in `load_validate_test.go`. For diff composition, read `internal/app/config_diff.go`. Reuse `TestPipelineOverlayDoesNotRequireUnusedBaseCredentials` and `TestCredentialValuesNeverEnterEffectiveProjectionOrDigest` coverage. 1. Load two configurations that produce the same effective domain values: one uses inheritance, the other writes the expanded values explicitly. Include ordinary artifacts and representative resolved family members. Verify equal safe effective mappings and digests and no effective diff. Do not compare private provenance as part of semantic equality. 2. Add a representative typed credential inheritance case using shared fields of valid Narratio sibling mappings and controlled synthetic environment variables. Verify resolved credentials retain their exact configured names; serialization and inspection expose those identities without values. 3. Verify overlay removal/replacement of a credential before inheritance does not resolve the superseded reference. Reuse the existing selected-overlay regression rather than creating a second loader or bootstrap algorithm. 4. Check that changing only synthetic secret values leaves semantic projections and digest unchanged. Fix only demonstrated projection defects; preserve the existing safe typed rendering boundary and semantic reuse evidence. Verify with `go test ./internal/config ./internal/app`. Existing shared adapter credential-forwarding tests remain the owner of subprocess forwarding; do not rewrite adapters or duplicate those tests simply because input can be inherited. Complete when resolved values, not source layout or secret bytes, determine effective comparison, and inherited credentials obey the existing safe boundary. ## Stage 6: Align policy, document inheritance, and maintain an example Purpose: make the adopted behavior understandable and usable without expanding Narratio's configuration surface. Read `docs/config.md`, `docs/internal/configuration.md`, `examples/README.md`, `docs/policy/architecture.md`, the production/testing bundle, and `TestExamplesLoadAndValidate` in `internal/config/load_validate_test.go`. Follow the documentation policy. 1. Revise only the project-specific Configuration section of the architecture policy to record the implemented boundary: ConfigKit owns loading, assembly, inheritance, presence, secrets, and provenance; Narratio owns domain meaning and fail-fast effective validation. Permit native metadata inspection and supported callbacks. Align the ambiguous empty-value statement with existing explicit-presence defaults, not a new blank/null policy. Leave general upstream agent, testing, documentation, and OSS policy wording unchanged. 2. Add native sibling inheritance guidance to the configuration reference. Explain exact sibling lookup, overlay-before-inheritance resolution, explicit presence, ordinary parent validation, distinct child identity, and native contributor inspection. Remove the one-base-file restriction and describe acceptance of ConfigKit-composed entries. Update family-publish guidance for effective configuration rather than explicit authoring. Link to the pinned upstream contract for detailed syntax and structural rules. 3. Explain the reserved `extends` key throughout ConfigKit inputs, including dynamic artifact IDs and prompt-variable mappings. Operators must rename existing ordinary-data keys with that name; there is no opt-in or automatic conversion. Campaign, session, and party inputs also use ConfigKit. 4. Clarify the existing statement that overlays cannot inherit: overlay files cannot inherit or stack, but the selected overlay may supply native sibling directives within its values. Keep imports and overlay selection unchanged. 5. Update configuration internals for inheritance before typed decoding, removal of authoring gates, thin native contributor projection, and the safe effective boundary. Describe implemented mechanisms, linking to the public reference for their operator-facing meaning. Update `docs/cli.md` where source output now reports composite evidence rather than a unique defining file. 6. In `examples/production-testing/overlays/testing.yml`, add `extends: session_recap` to the existing `testing_notes` artifact. Keep its disabled status and distinct output override. It inherits the imported parent's prompt/input and the parent's testing profile after overlay application. The parent remains an ordinary artifact. 7. Update the example guide and extend existing example validation to check those inherited fields. Preserve the bundle's current identities and artifact count; no new example root or template convention is necessary. Verify with `go test ./internal/config -run '^TestExamplesLoadAndValidate$'` and `go test ./internal/doccheck`. Review examples for synthetic-only content and validate local links. Keep unimplemented Audita/workspace behavior in its roadmaps. Do not create a release note under an invented Narratio version; reserved-key compatibility impact remains an explicit release-preparation item. Complete when canonical documentation and a tested copyable example describe the implemented adoption, without promoting new restrictions to policy. ## Stage 7: Verify the assembled inspection workflow and close the feature Purpose: establish that real command composition consumes the integrated configuration correctly and finish the upgrade as a reviewable baseline. Read `internal/app/config_commands_test.go`, `config_artifacts_test.go`, and existing read-only inspection workflow coverage. Reuse the preceding package coverage rather than repeating its entire matrix at the CLI boundary. 1. Add or extend a representative command-level temporary imported bundle with inheritance. Exercise validation, effective show, source reporting, artifact catalog, and diff through existing command entry points. Use a campaign/party fixture for family inspection, and paired overlays with equivalent inherited and explicitly expanded values when testing command-level diff equality. 2. Check semantic output: resolved child values, native contributor/origin sources, logical artifact identities, and no secret values. Keep inspection read-only with respect to session/runtime state, as existing tests establish. Do not invoke downstream applications or introduce new inspection modes. 3. Review the combined diff against `config.md` and this plan. Confirm that ConfigKit v0.5.0 is selected, attribution links use the reviewed revision, authoring-history acceptance checks were removed, native inspection and presence semantics remain, and policy reflects that boundary. Confirm no optional loading feature, Audita/workspace change, or compatibility shim slipped into scope. 4. Run `go test ./...`, `go test -race ./...`, `go vet ./...`, `go build ./...`, `go mod tidy -diff`, and `git diff --check` against the final source. These reuse existing repository checks, not new release gates. The full suite includes example and documentation-link validation; focused checks need not be repeated solely for this stage if unchanged. 5. Commit the completed unit and report the dependency revision, checks, compatibility impact, and any unfinished work. Leave the pending Audita and workspace plans and Proposed ADRs intact. Retire completed planning files only during separately requested cleanup/release preparation, repairing links. Complete when the feature roadmap's completion criteria are evidenced by the released dependency, integrated behavior, maintained documentation/examples, and passing final checks. The next implementation scope is Audita; its concrete plan is prepared separately. Release version selection and publication are outside this implementation pass. ## Open Questions None required for this adoption. Existing decisions select native inheritance, native metadata inspection and callbacks, effective-domain validation instead of authoring-history gates, current path/credential/presence semantics, and ConfigKit before Audita before workspace work. Eventual release preparation must account for the reserved-key compatibility impact and inspection representation changes under the release policy; no version is selected here.