Simplify the ConfigKit adoption plan

This commit is contained in:
2026-10-04 12:42:58 +00:00
parent fe9817f354
commit 2850498043
2 changed files with 204 additions and 119 deletions

View File

@@ -5,7 +5,9 @@
Upgrade Narratio from ConfigKit v0.4.2 to v0.5.0 and integrate its native Upgrade Narratio from ConfigKit v0.4.2 to v0.5.0 and integrate its native
sibling inheritance with Narratio's configuration validation and inspection. sibling inheritance with Narratio's configuration validation and inspection.
Keep the upgrade focused on the existing loading model and the adjustments Keep the upgrade focused on the existing loading model and the adjustments
needed to consume the new release correctly. needed to consume the new release correctly. Rely on ConfigKit's assembly and
metadata features; validate Narratio's effective domain configuration without
adding acceptance rules about how that configuration was authored.
This adoption precedes [Audita adoption](audita.md) and the This adoption precedes [Audita adoption](audita.md) and the
[workspace reorganization](workspace.md). This document defines the target [workspace reorganization](workspace.md). This document defines the target
@@ -81,25 +83,32 @@ presence semantics. Narratio's absence-based defaults must not refill such
values. Normal domain validation still determines whether a resulting value values. Normal domain validation still determines whether a resulting value
is acceptable. is acceptable.
### Declaration ownership and provenance ### Effective configuration and native provenance
Distinguish direct base declarations from inherited contributions. A child Remove Narratio's one-base-file-per-artifact/family restriction. If ConfigKit
declared in one file may inherit from a separately declared parent in another accepts composition of one entry from several files, Narratio accepts that
file without becoming a duplicate declaration. entry when its effective domain values are valid. ConfigKit continues to reject
structural conflicts under its own contract. Narratio does not reconstruct
declaration history to add another conflict rule or reject domain values that
were removed or replaced before the final configuration handoff.
Retain the existing rejection of one artifact or family key directly declared Domain validation concerns the effective configuration, including application
by multiple base files, including disjoint contributions and declarations resolution and family expansion. Family publication requires an applicable
later removed by an overlay. Inheritance is not permission to merge multiple effective publish configuration, not separate evidence that the section was
direct declarations of the same key. explicitly authored rather than defaulted. Existing checks on destinations,
dependencies, identities, and effective publish rules remain.
Keep defining-file ownership distinct from value-contributor provenance. Retain `config sources` and useful provenance in `config artifacts`. Consume
Existing source and artifact inspection must describe inherited contributors ConfigKit's public source, origin, presence, history, and explanation APIs as
accurately without presenting them as conflicting declarations. ConfigKit's intended. A thin formatting/projection layer may add Narratio-specific family,
retained metadata remains the source of that evidence. character, and party context. It must not duplicate upstream source tracking,
inheritance analysis, or derivation bookkeeping.
For generated family members, the family's defining source identifies the An entry can have several contributors. Report the evidence ConfigKit provides
child family declaration; inherited parent files remain contributor evidence. without inventing a unique defining-file guarantee or choosing an arbitrary
Keep existing logical artifact IDs and inspection interfaces. contributor as the owner. Keep logical artifact IDs independent of source files.
Small representation changes needed for truthful composite provenance belong
to this adoption; retiring inspection commands does not.
Effective configuration, diffs, and digests continue to reflect resolved Effective configuration, diffs, and digests continue to reflect resolved
domain values. Equivalent inherited and explicitly authored configurations domain values. Equivalent inherited and explicitly authored configurations
@@ -112,10 +121,19 @@ Retain ordinary ConfigKit loading, centralized typed defaults, imports, selected
overlays, domain resolution, credential bootstrap, and exact-name credential overlays, domain resolution, credential bootstrap, and exact-name credential
forwarding. Preserve current path bases and read-only inspection workflows. forwarding. Preserve current path bases and read-only inspection workflows.
ConfigKit owns parsing, source composition, structural inheritance, presence,
provenance, and secret resolution. Narratio owns its schema, domain defaults,
semantic normalization and validation, campaign/family resolution, and runtime
use. Supported defaults, resolver, and validator callbacks remain appropriate;
there is no requirement to move them after `Load` merely to establish this
ownership boundary. ConfigKit presence APIs remain suitable for absence-based
defaults, and native metadata remains suitable for operator inspection and
existing party ordering.
Layered loading, embedded configuration sources, programmatic mapping sources, Layered loading, embedded configuration sources, programmatic mapping sources,
and source-relative resource rebasing are available upstream but are outside and source-relative resource rebasing are available upstream but are outside
this focused adoption. Narratio continues to own its domain rules; ConfigKit this focused adoption. Do not relax empty/null default semantics or change
owns structural inheritance, presence, provenance, and secret resolution. party ordering just to avoid using useful native APIs.
## Required Changes ## Required Changes
@@ -127,14 +145,17 @@ commit's source and notice links. Existing applicable license texts can remain.
### Configuration integration ### Configuration integration
Adjust the existing duplicate-definition check to identify direct declarations Delete the duplicate-definition check and its obsolete declaration-accounting
using public ConfigKit history and origin metadata. Preserve genuine duplicate tests. Remove the family-publish explicit-declaration gate and metadata retained
detection while excluding structural transfers from declaration counting. only for that gate. Use existing final-value domain checks instead.
Use the completed load's retained evidence rather than reparsing files or
performing a second load that could resolve superseded credential references. Simplify source and artifact-definition projections around ConfigKit's public
metadata. Remove duplicated tracking or inferred ownership where native evidence
already provides the needed information. Retain application context and
formatting that actually serve operators. Use the completed load's evidence
rather than reparsing sources or performing a second base-only load that could
resolve superseded credential references.
Review source ownership and artifact-definition projections against the new
inheritance metadata. Update only where needed to report contributors correctly.
Keep effective rendering and digest construction grounded in the existing safe Keep effective rendering and digest construction grounded in the existing safe
typed projection, with credential identities rather than resolved values. typed projection, with credential identities rather than resolved values.
@@ -142,6 +163,17 @@ Use ConfigKit's native operation directly. No application-owned inheritance
engine, collection registration, alternative keyword, or compatibility loader engine, collection registration, alternative keyword, or compatibility loader
is needed. is needed.
### Policy alignment
Revise the Configuration section of the
[architecture policy](../policy/architecture.md) to record this responsibility
boundary: native loading and metadata belong to ConfigKit; Narratio owns domain
meaning and fail-fast effective validation. Explicitly permit supported
callbacks and native provenance inspection. Remove wording inconsistent with
the established explicit-presence/defaulting semantics rather than introducing
a new empty-value policy. General agent, testing, documentation, and OSS
policies need no broad revisions for this feature.
### Compatibility and operator guidance ### Compatibility and operator guidance
Document that `extends` is now reserved structural input throughout ConfigKit Document that `extends` is now reserved structural input throughout ConfigKit
@@ -156,6 +188,11 @@ pinned upstream contract for detailed inheritance semantics. Clarify that a
selected overlay may contribute sibling inheritance directives; this does not selected overlay may contribute sibling inheritance directives; this does not
add inheritance or stacking between overlay files. add inheritance or stacking between overlay files.
Replace documentation of the one-base-file restriction with ConfigKit's
composition contract and Narratio's effective-value validation boundary.
Describe any inspection representation changes without promising a unique
defining file for a composite entry.
Update the configuration reference, internal configuration guide, and a small Update the configuration reference, internal configuration guide, and a small
maintained example when implementation lands. Preserve each field's current maintained example when implementation lands. Preserve each field's current
path-resolution rule when its value is inherited. Record the reserved-key path-resolution rule when its value is inherited. Record the reserved-key
@@ -164,11 +201,13 @@ conversion is outside this feature.
### Verification ### Verification
Add focused Narratio coverage for the confirmed cross-file artifact inheritance Add focused Narratio coverage for cross-file artifact/family inheritance and
gap and the corresponding artifact-family behavior. Retain coverage for real valid disjoint contributions to one entry. Verify that effective invalid
duplicate declarations, including those hidden by overlay replacement or configuration still fails before execution and that structural conflicts still
removal. Verify inherited explicit values against Narratio's defaulting rules, surface as ConfigKit errors. Old source-history rejection tests are retired or
credential safety, contributor reporting, and equivalent effective projections. rewritten for the new contract, including overlay replacement/removal cases.
Verify inherited explicit values against Narratio's defaulting rules, credential
safety, native contributor reporting, and equivalent effective projections.
Concentrate tests on Narratio's integration behavior. ConfigKit's own tests own Concentrate tests on Narratio's integration behavior. ConfigKit's own tests own
its generic inheritance algorithm and source lifecycle. Narratio's default its generic inheritance algorithm and source lifecycle. Narratio's default
@@ -180,12 +219,14 @@ suite against the selected released module before completing the upgrade.
Narratio selects the released ConfigKit v0.5.0 module without a local checkout Narratio selects the released ConfigKit v0.5.0 module without a local checkout
replacement. Cross-file artifact and family inheritance works through the replacement. Cross-file artifact and family inheritance works through the
ordinary loader, while genuinely duplicated base declarations remain invalid. ordinary loader; valid composition is not rejected by Narratio's declaration
Inspection distinguishes declaration ownership from inherited contributors; history checks. Effective domain errors fail before execution. Native provenance
effective projections and credential handling retain their existing semantics. remains inspectable without unique-file assumptions; effective projections,
explicit-presence defaulting, and credential handling retain their semantics.
Maintained guidance and examples explain native inheritance and the reserved Maintained guidance and examples explain native inheritance and the reserved
`extends` key. Attribution identifies the selected upstream revision. Focused `extends` key, and the architecture policy reflects the ConfigKit/Narratio
boundary. Attribution identifies the selected upstream revision. Focused
regression coverage and the existing suite pass without implementing Audita or regression coverage and the existing suite pass without implementing Audita or
workspace changes as part of this upgrade. workspace changes as part of this upgrade.

View File

@@ -7,6 +7,12 @@ 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 v0.5.0 and integration with native sibling inheritance. Audita adoption and
workspace reorganization remain subsequent, separately planned work. 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 The reviewed upstream revision is
`dc09959cca4e105f49ec316c6d4ba585bd2340bd`, tagged `v0.5.0`. `dc09959cca4e105f49ec316c6d4ba585bd2340bd`, tagged `v0.5.0`.
Use the released module, not a local replacement. The pinned Use the released module, not a local replacement. The pinned
@@ -34,12 +40,17 @@ than requiring changes to every listed file.
domain validation, and current path-resolution rules. Native inheritance is domain validation, and current path-resolution rules. Native inheritance is
available wherever ConfigKit and Narratio's schema permit it, with no new available wherever ConfigKit and Narratio's schema permit it, with no new
collection allowlist, opt-in flag, or Narratio-owned inheritance engine. collection allowlist, opt-in flag, or Narratio-owned inheritance engine.
- Distinguish original declarations from inherited contributors. Preserve - Trust ConfigKit's structural acceptance rules. Remove Narratio's
genuine duplicate-base rejection and truthful provenance. Parent entries one-base-file-per-entry check rather than making it inheritance-aware. Validate
remain ordinary entries subject to existing domain rules. 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 - Keep invocation-owned secrets bootstrap and shared exact-name credential
forwarding unchanged. Do not introduce a second base load, file reparse, or forwarding unchanged. Do not introduce a second base load, file reparse, or
historical-secret lookup to recover declaration information. historical-secret lookup to reconstruct provenance or validate old input.
- Tests use temporary files, controlled synthetic secrets, and real internal - Tests use temporary files, controlled synthetic secrets, and real internal
collaborators. No downstream executable, sibling checkout, cloud service, collaborators. No downstream executable, sibling checkout, cloud service,
or paid provider is needed. Protect integration behavior rather than or paid provider is needed. Protect integration behavior rather than
@@ -48,6 +59,11 @@ than requiring changes to every listed file.
suitable validation. Report blockers and incomplete work accurately. If a suitable validation. Report blockers and incomplete work accurately. If a
review-only task needs no source fix, retain useful behavioral coverage and review-only task needs no source fix, retain useful behavioral coverage and
report that result rather than making a cosmetic rewrite. 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.
Do not adopt layered loading, new source types, source-relative rebasing, Do not adopt layered loading, new source types, source-relative rebasing,
abstract artifacts, automatic YAML conversion, new execution selection rules, abstract artifacts, automatic YAML conversion, new execution selection rules,
@@ -82,79 +98,89 @@ Complete when the released dependency and notices agree and current focused
tests pass. The cross-file inheritance defect is addressed in the next stage; 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. this stage does not claim that new inheritance behavior is fully integrated.
## Stage 2: Correct direct declaration accounting ## Stage 2: Remove source-authoring acceptance gates
Purpose: allow distinct artifact and family keys to inherit across imported Purpose: accept structurally composed configuration from ConfigKit and reject
files while preserving existing duplicate-declaration rejection. only invalid effective Narratio domain configuration.
Read `internal/config/pipeline_configkit.go`, particularly Read `internal/config/pipeline_configkit.go`, particularly
`pipelineMetadataFromConfigKit` and `rejectDuplicateBaseDefinitions`, and `pipelineMetadataFromConfigKit` and `rejectDuplicateBaseDefinitions`,
`internal/config/pipeline_configkit_test.go`. Inspect the public ConfigKit `pipeline_configkit_test.go`, and `expandFamilyPublishRules` and its tests in
`Metadata.History`, `HistoricalPaths`, `Origin`, and `ChangeKind` contracts. `internal/config/artifact_families.go` and `artifact_families_test.go`.
1. Add package-boundary regression fixtures with a valid parent in one imported 1. Delete `rejectDuplicateBaseDefinitions` and its invocation. Do not replace
file and a child using `extends` in another. Cover ordinary artifacts and it with filtering of inheritance events, direct-declaration counting, or
artifact families. Give parent and child distinct valid output paths or another source-history validator.
family patterns, and provide canonical-party context for expanded families. 2. Replace `TestPipelineConfigKitRejectsDuplicateBaseDeclarations` with behavior
Both keys remain ordinary domain entries; child IDs must stay their own. coverage showing that disjoint contributions to one artifact/family compose
2. Adjust declaration accounting using retained public metadata. In v0.5.0, successfully when the resulting domain entry is valid. Check selected-overlay
original base-input events have `LayerBase` and no origin operation; replacement/removal without Narratio rejecting superseded declarations.
projected transfers carry `ChangeInheritance`. Count original base 3. Add cross-file artifact and family inheritance regressions. Supply valid
declarations, not these transfers or subsequent decoding/resolution events. surviving parent and child entries with distinct output destinations, and
Consumed structural `extends` paths are not artifact declarations. campaign/party context for family expansion. Verify child identities and
3. Keep the historical-path check, including original declarations erased by effective fields; the inheritance regression must fail on the old check.
a selected overlay. Do not switch to surviving effective keys only or count 4. Remove the `publishDeclared` gate in `expandFamilyPublishRules`, its metadata
all displaced origins as fresh declarations. Reuse a small package-local population, and state retained only for that gate. Validate family publication
helper only if it makes the next stage clearer. against the effective `Publish` value, whether authored or supplied by defaults.
4. Retain `TestPipelineConfigKitRejectsDuplicateBaseDeclarations`, including Preserve the missing-effective-publish check, ordinary enablement behavior,
disjoint fields supplied to the same key, container removal, and removal of destination validation, and conflicts between effective publish rules.
Scriptorium by an overlay. An overlay may still modify an existing entry. Update the test that currently fabricates an explicit-declaration flag.
Add only any missing regression case needed to exercise the new filter. 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`. The positive cross-file regression Verify with `go test ./internal/config`. Assert effective outcomes and safe
should expose the baseline defect before the fix. Assert loaded values and error categories, not entire diagnostic text or private metadata event order.
identities, or the duplicate category and relevant sources, without matching an Do not run a separate base-only load to validate overwritten input.
entire diagnostic or ConfigKit's private event ordering.
Complete when cross-file inheritance loads and expands correctly, and actual Complete when valid cross-file composition/inheritance succeeds and invalid
duplicates still fail even when the overlay hides them. Do not use the direct effective configuration still fails before execution, without authored-source
declaration filter to remove contributor evidence from inspection. acceptance gates. Keep native metadata available for the next stage.
## Stage 3: Preserve contributor provenance and family ownership ## Stage 3: Simplify provenance inspection around native APIs
Purpose: keep inspection useful when one entry contains values from several Purpose: preserve useful operator inspection without a parallel provenance
files, without confusing its defining file with those contributors. system or a unique-defining-file contract for composite entries.
Read `internal/config/artifact_catalog.go`, Read `internal/config/artifact_catalog.go`, `artifact_families.go`,
`internal/config/artifact_families.go`, `internal/config/effective_pipeline.go`, `effective_pipeline.go`, `effective_digest.go`, and the metadata projection in
and metadata-to-ownership projection in `pipeline_configkit.go`. Inspect the `pipeline_configkit.go`. Inspect `internal/app/config_commands_test.go`,
focused catalog, family, and effective-source tests. `config_artifacts_test.go`, and ConfigKit's public metadata contracts.
1. Exercise the inherited configurations from Stage 2 through 1. Keep `config sources` and provenance-bearing `config artifacts` output.
`EffectiveArtifactCatalog` and `EffectivePipelineSources`. Check inherited Use public ConfigKit sources, effective origins, history, and explanations
values against their actual parent contributors and child overrides against for the information they own. Keep presence queries and recorded callbacks
the child/overlay contributors. Keep historical definition evidence distinct where needed; retaining returned metadata is not duplicating its implementation.
from effective field ownership. 2. Review existing helper/state layers for duplicated tracking. Remove redundant
2. Preserve `DefinitionSources` aggregation, including inherited contributors. cached field-ownership reconstruction where the same result is available
Do not relabel all inherited values as authored in the child's file. directly from retained metadata. Keep a small projection where needed for
3. Correct `artifactFamilySource` where its first inherited field currently Narratio's generated family/character/party context and output formatting.
selects the parent's file. For an explicitly declared child family, identify Do not add a provenance service, custom ancestry graph, or second source parse.
its original declaration using retained metadata: use its base defining file 3. Exercise Stage 2's inherited and multi-file entries through
when present, or its overlay defining file for an overlay-only family. `EffectiveArtifactCatalog` and `EffectivePipelineSources`. Report actual
Overlay edits to a base family do not relocate its base definition. contributors and child overrides. Keep historical definition evidence
4. Retain the existing fallback for entries without a direct declaration or distinguishable from effective field origins as exposed by ConfigKit.
programmatically constructed configuration. Do not restrict valid enclosing 4. Replace `artifactFamilySource`'s arbitrary first-contributor ownership with
inheritance merely to force every entry into a single-file ownership model. native source/origin evidence. Do not infer a unique base defining file or
5. Keep logical `SourceID`, artifact keys, family/character/party provenance, implement a new declaration-accounting algorithm. Composite origins may have
existing source roles, and inspection interfaces. Update projections only several sources; preserve them using existing repeated source records and
where inherited evidence is otherwise lost or incorrectly attributed. 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`. Cover an explicitly declared child Verify with `go test ./internal/config ./internal/app`. Cover a child family
family inheriting from another file and a selected-overlay contribution. Check inheriting across files, an entry composed from disjoint files, and an overlay
meaningful records and source identities, not a complete formatted snapshot. override. Check meaningful source records, logical identities, and absence of
secret values rather than full formatted snapshots or upstream event ordering.
Complete when contributor reporting remains truthful and generated members Complete when native provenance remains useful and truthful, redundant tracking
identify their child family definition rather than an arbitrary inherited field. 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 ## Stage 4: Verify inherited presence, domain resolution, and path bases
@@ -186,7 +212,10 @@ the relevant domain validators.
newly normalize other path fields merely to make their behavior uniform. newly normalize other path fields merely to make their behavior uniform.
5. Fix any demonstrated Narratio integration defect at its existing defaulting 5. Fix any demonstrated Narratio integration defect at its existing defaulting
or domain-resolution owner. Use ConfigKit presence and recorded operations; or domain-resolution owner. Use ConfigKit presence and recorded operations;
do not recreate structural inheritance or weaken ordinary validation. 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 Verify with `go test ./internal/config`. Keep coverage representative; generic
missing-parent, cycle, resource-context, and expansion-limit matrices belong to missing-parent, cycle, resource-context, and expansion-limit matrices belong to
@@ -230,37 +259,48 @@ rewrite adapters or duplicate those tests simply because input can be inherited.
Complete when resolved values, not source layout or secret bytes, determine Complete when resolved values, not source layout or secret bytes, determine
effective comparison, and inherited credentials obey the existing safe boundary. effective comparison, and inherited credentials obey the existing safe boundary.
## Stage 6: Document inheritance and maintain a small example ## Stage 6: Align policy, document inheritance, and maintain an example
Purpose: make the adopted behavior understandable and usable without expanding Purpose: make the adopted behavior understandable and usable without expanding
Narratio's configuration surface. Narratio's configuration surface.
Read `docs/config.md`, `docs/internal/configuration.md`, `examples/README.md`, Read `docs/config.md`, `docs/internal/configuration.md`, `examples/README.md`,
the production/testing bundle, and `TestExamplesLoadAndValidate` in `docs/policy/architecture.md`, the production/testing bundle, and
`TestExamplesLoadAndValidate` in
`internal/config/load_validate_test.go`. Follow the documentation policy. `internal/config/load_validate_test.go`. Follow the documentation policy.
1. Add native sibling inheritance guidance to the configuration reference. 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, Explain exact sibling lookup, overlay-before-inheritance resolution,
explicit presence, ordinary parent validation, distinct child identity, explicit presence, ordinary parent validation, distinct child identity,
and cross-file declaration/contributor distinctions. Link to the pinned and native contributor inspection. Remove the one-base-file restriction and
upstream contract for detailed syntax and structural rules. describe acceptance of ConfigKit-composed entries. Update family-publish
2. Explain the reserved `extends` key throughout ConfigKit inputs, including 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 dynamic artifact IDs and prompt-variable mappings. Operators must rename
existing ordinary-data keys with that name; there is no opt-in or automatic existing ordinary-data keys with that name; there is no opt-in or automatic
conversion. Campaign, session, and party inputs also use ConfigKit. conversion. Campaign, session, and party inputs also use ConfigKit.
3. Clarify the existing statement that overlays cannot inherit: overlay files 4. Clarify the existing statement that overlays cannot inherit: overlay files
cannot inherit or stack, but the selected overlay may supply native sibling cannot inherit or stack, but the selected overlay may supply native sibling
directives within its values. Keep imports and overlay selection unchanged. directives within its values. Keep imports and overlay selection unchanged.
4. Update configuration internals for inheritance before typed decoding, 5. Update configuration internals for inheritance before typed decoding,
original-declaration counting, contributor projection, and the safe removal of authoring gates, thin native contributor projection, and the safe
effective boundary. Describe implemented mechanisms, linking to the public effective boundary. Describe implemented mechanisms, linking to the public
reference for their operator-facing meaning. reference for their operator-facing meaning. Update `docs/cli.md` where source
5. In `examples/production-testing/overlays/testing.yml`, add 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 `extends: session_recap` to the existing `testing_notes` artifact. Keep its
disabled status and distinct output override. It inherits the imported disabled status and distinct output override. It inherits the imported
parent's prompt/input and the parent's testing profile after overlay parent's prompt/input and the parent's testing profile after overlay
application. The parent remains an ordinary artifact. application. The parent remains an ordinary artifact.
6. Update the example guide and extend existing example validation to check 7. Update the example guide and extend existing example validation to check
those inherited fields. Preserve the bundle's current identities and those inherited fields. Preserve the bundle's current identities and
artifact count; no new example root or template convention is necessary. artifact count; no new example root or template convention is necessary.
@@ -287,14 +327,16 @@ package coverage rather than repeating its entire matrix at the CLI boundary.
catalog, and diff through existing command entry points. Use a campaign/party catalog, and diff through existing command entry points. Use a campaign/party
fixture for family inspection, and paired overlays with equivalent inherited fixture for family inspection, and paired overlays with equivalent inherited
and explicitly expanded values when testing command-level diff equality. and explicitly expanded values when testing command-level diff equality.
2. Check semantic output: resolved child values, expected contributor/defining 2. Check semantic output: resolved child values, native contributor/origin
sources, logical artifact identities, and no secret values. Keep inspection sources, logical artifact identities, and no secret values. Keep inspection
read-only with respect to session/runtime state, as existing tests establish. read-only with respect to session/runtime state, as existing tests establish.
Do not invoke downstream applications or add CLI modes or columns. Do not invoke downstream applications or introduce new inspection modes.
3. Review the combined diff against `config.md` and this plan. Confirm that 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, ConfigKit v0.5.0 is selected, attribution links use the reviewed revision,
no optional loading feature was adopted, and no Audita/workspace change or authoring-history acceptance checks were removed, native inspection and
compatibility shim slipped into scope. 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 ./...`, 4. Run `go test ./...`, `go test -race ./...`, `go vet ./...`,
`go build ./...`, `go mod tidy -diff`, and `git diff --check` against the `go build ./...`, `go mod tidy -diff`, and `git diff --check` against the
final source. These reuse existing repository checks, not new release gates. final source. These reuse existing repository checks, not new release gates.
@@ -314,6 +356,8 @@ outside this implementation pass.
## Open Questions ## Open Questions
None required for this adoption. Existing decisions select native inheritance, None required for this adoption. Existing decisions select native inheritance,
current loading/path/credential semantics, and ConfigKit before Audita before native metadata inspection and callbacks, effective-domain validation instead
workspace work. Eventual release preparation must account for the reserved-key of authoring-history gates, current path/credential/presence semantics, and
compatibility impact under the release policy; no version is selected here. 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.