Simplify the ConfigKit adoption plan
This commit is contained in:
@@ -5,7 +5,9 @@
|
||||
Upgrade Narratio from ConfigKit v0.4.2 to v0.5.0 and integrate its native
|
||||
sibling inheritance with Narratio's configuration validation and inspection.
|
||||
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
|
||||
[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
|
||||
is acceptable.
|
||||
|
||||
### Declaration ownership and provenance
|
||||
### Effective configuration and native provenance
|
||||
|
||||
Distinguish direct base declarations from inherited contributions. A child
|
||||
declared in one file may inherit from a separately declared parent in another
|
||||
file without becoming a duplicate declaration.
|
||||
Remove Narratio's one-base-file-per-artifact/family restriction. If ConfigKit
|
||||
accepts composition of one entry from several files, Narratio accepts that
|
||||
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
|
||||
by multiple base files, including disjoint contributions and declarations
|
||||
later removed by an overlay. Inheritance is not permission to merge multiple
|
||||
direct declarations of the same key.
|
||||
Domain validation concerns the effective configuration, including application
|
||||
resolution and family expansion. Family publication requires an applicable
|
||||
effective publish configuration, not separate evidence that the section was
|
||||
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.
|
||||
Existing source and artifact inspection must describe inherited contributors
|
||||
accurately without presenting them as conflicting declarations. ConfigKit's
|
||||
retained metadata remains the source of that evidence.
|
||||
Retain `config sources` and useful provenance in `config artifacts`. Consume
|
||||
ConfigKit's public source, origin, presence, history, and explanation APIs as
|
||||
intended. A thin formatting/projection layer may add Narratio-specific family,
|
||||
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
|
||||
child family declaration; inherited parent files remain contributor evidence.
|
||||
Keep existing logical artifact IDs and inspection interfaces.
|
||||
An entry can have several contributors. Report the evidence ConfigKit provides
|
||||
without inventing a unique defining-file guarantee or choosing an arbitrary
|
||||
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
|
||||
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
|
||||
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,
|
||||
and source-relative resource rebasing are available upstream but are outside
|
||||
this focused adoption. Narratio continues to own its domain rules; ConfigKit
|
||||
owns structural inheritance, presence, provenance, and secret resolution.
|
||||
this focused adoption. Do not relax empty/null default semantics or change
|
||||
party ordering just to avoid using useful native APIs.
|
||||
|
||||
## Required Changes
|
||||
|
||||
@@ -127,14 +145,17 @@ commit's source and notice links. Existing applicable license texts can remain.
|
||||
|
||||
### Configuration integration
|
||||
|
||||
Adjust the existing duplicate-definition check to identify direct declarations
|
||||
using public ConfigKit history and origin metadata. Preserve genuine duplicate
|
||||
detection while excluding structural transfers from declaration counting.
|
||||
Use the completed load's retained evidence rather than reparsing files or
|
||||
performing a second load that could resolve superseded credential references.
|
||||
Delete the duplicate-definition check and its obsolete declaration-accounting
|
||||
tests. Remove the family-publish explicit-declaration gate and metadata retained
|
||||
only for that gate. Use existing final-value domain checks instead.
|
||||
|
||||
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
|
||||
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
|
||||
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
|
||||
|
||||
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
|
||||
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
|
||||
maintained example when implementation lands. Preserve each field's current
|
||||
path-resolution rule when its value is inherited. Record the reserved-key
|
||||
@@ -164,11 +201,13 @@ conversion is outside this feature.
|
||||
|
||||
### Verification
|
||||
|
||||
Add focused Narratio coverage for the confirmed cross-file artifact inheritance
|
||||
gap and the corresponding artifact-family behavior. Retain coverage for real
|
||||
duplicate declarations, including those hidden by overlay replacement or
|
||||
removal. Verify inherited explicit values against Narratio's defaulting rules,
|
||||
credential safety, contributor reporting, and equivalent effective projections.
|
||||
Add focused Narratio coverage for cross-file artifact/family inheritance and
|
||||
valid disjoint contributions to one entry. Verify that effective invalid
|
||||
configuration still fails before execution and that structural conflicts still
|
||||
surface as ConfigKit errors. Old source-history rejection tests are retired or
|
||||
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
|
||||
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
|
||||
replacement. Cross-file artifact and family inheritance works through the
|
||||
ordinary loader, while genuinely duplicated base declarations remain invalid.
|
||||
Inspection distinguishes declaration ownership from inherited contributors;
|
||||
effective projections and credential handling retain their existing semantics.
|
||||
ordinary loader; valid composition is not rejected by Narratio's declaration
|
||||
history checks. Effective domain errors fail before execution. Native provenance
|
||||
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
|
||||
`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
|
||||
workspace changes as part of this upgrade.
|
||||
|
||||
|
||||
@@ -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
|
||||
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
|
||||
@@ -34,12 +40,17 @@ than requiring changes to every listed file.
|
||||
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.
|
||||
- Distinguish original declarations from inherited contributors. Preserve
|
||||
genuine duplicate-base rejection and truthful provenance. Parent entries
|
||||
remain ordinary entries subject to existing domain rules.
|
||||
- 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 recover declaration information.
|
||||
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
|
||||
@@ -48,6 +59,11 @@ than requiring changes to every listed file.
|
||||
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.
|
||||
|
||||
Do not adopt layered loading, new source types, source-relative rebasing,
|
||||
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;
|
||||
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
|
||||
files while preserving existing duplicate-declaration rejection.
|
||||
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`, and
|
||||
`internal/config/pipeline_configkit_test.go`. Inspect the public ConfigKit
|
||||
`Metadata.History`, `HistoricalPaths`, `Origin`, and `ChangeKind` contracts.
|
||||
`pipelineMetadataFromConfigKit` and `rejectDuplicateBaseDefinitions`,
|
||||
`pipeline_configkit_test.go`, and `expandFamilyPublishRules` and its tests in
|
||||
`internal/config/artifact_families.go` and `artifact_families_test.go`.
|
||||
|
||||
1. Add package-boundary regression fixtures with a valid parent in one imported
|
||||
file and a child using `extends` in another. Cover ordinary artifacts and
|
||||
artifact families. Give parent and child distinct valid output paths or
|
||||
family patterns, and provide canonical-party context for expanded families.
|
||||
Both keys remain ordinary domain entries; child IDs must stay their own.
|
||||
2. Adjust declaration accounting using retained public metadata. In v0.5.0,
|
||||
original base-input events have `LayerBase` and no origin operation;
|
||||
projected transfers carry `ChangeInheritance`. Count original base
|
||||
declarations, not these transfers or subsequent decoding/resolution events.
|
||||
Consumed structural `extends` paths are not artifact declarations.
|
||||
3. Keep the historical-path check, including original declarations erased by
|
||||
a selected overlay. Do not switch to surviving effective keys only or count
|
||||
all displaced origins as fresh declarations. Reuse a small package-local
|
||||
helper only if it makes the next stage clearer.
|
||||
4. Retain `TestPipelineConfigKitRejectsDuplicateBaseDeclarations`, including
|
||||
disjoint fields supplied to the same key, container removal, and removal of
|
||||
Scriptorium by an overlay. An overlay may still modify an existing entry.
|
||||
Add only any missing regression case needed to exercise the new filter.
|
||||
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`. The positive cross-file regression
|
||||
should expose the baseline defect before the fix. Assert loaded values and
|
||||
identities, or the duplicate category and relevant sources, without matching an
|
||||
entire diagnostic or ConfigKit's private event ordering.
|
||||
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 cross-file inheritance loads and expands correctly, and actual
|
||||
duplicates still fail even when the overlay hides them. Do not use the direct
|
||||
declaration filter to remove contributor evidence from inspection.
|
||||
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: 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
|
||||
files, without confusing its defining file with those contributors.
|
||||
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`,
|
||||
`internal/config/artifact_families.go`, `internal/config/effective_pipeline.go`,
|
||||
and metadata-to-ownership projection in `pipeline_configkit.go`. Inspect the
|
||||
focused catalog, family, and effective-source tests.
|
||||
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. Exercise the inherited configurations from Stage 2 through
|
||||
`EffectiveArtifactCatalog` and `EffectivePipelineSources`. Check inherited
|
||||
values against their actual parent contributors and child overrides against
|
||||
the child/overlay contributors. Keep historical definition evidence distinct
|
||||
from effective field ownership.
|
||||
2. Preserve `DefinitionSources` aggregation, including inherited contributors.
|
||||
Do not relabel all inherited values as authored in the child's file.
|
||||
3. Correct `artifactFamilySource` where its first inherited field currently
|
||||
selects the parent's file. For an explicitly declared child family, identify
|
||||
its original declaration using retained metadata: use its base defining file
|
||||
when present, or its overlay defining file for an overlay-only family.
|
||||
Overlay edits to a base family do not relocate its base definition.
|
||||
4. Retain the existing fallback for entries without a direct declaration or
|
||||
programmatically constructed configuration. Do not restrict valid enclosing
|
||||
inheritance merely to force every entry into a single-file ownership model.
|
||||
5. Keep logical `SourceID`, artifact keys, family/character/party provenance,
|
||||
existing source roles, and inspection interfaces. Update projections only
|
||||
where inherited evidence is otherwise lost or incorrectly attributed.
|
||||
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`. Cover an explicitly declared child
|
||||
family inheriting from another file and a selected-overlay contribution. Check
|
||||
meaningful records and source identities, not a complete formatted snapshot.
|
||||
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 contributor reporting remains truthful and generated members
|
||||
identify their child family definition rather than an arbitrary inherited field.
|
||||
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
|
||||
|
||||
@@ -186,7 +212,10 @@ the relevant domain validators.
|
||||
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;
|
||||
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
|
||||
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
|
||||
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
|
||||
Narratio's configuration surface.
|
||||
|
||||
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.
|
||||
|
||||
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,
|
||||
explicit presence, ordinary parent validation, distinct child identity,
|
||||
and cross-file declaration/contributor distinctions. Link to the pinned
|
||||
upstream contract for detailed syntax and structural rules.
|
||||
2. Explain the reserved `extends` key throughout ConfigKit inputs, including
|
||||
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.
|
||||
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
|
||||
directives within its values. Keep imports and overlay selection unchanged.
|
||||
4. Update configuration internals for inheritance before typed decoding,
|
||||
original-declaration counting, contributor projection, and the safe
|
||||
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.
|
||||
5. In `examples/production-testing/overlays/testing.yml`, add
|
||||
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.
|
||||
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
|
||||
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
|
||||
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, expected contributor/defining
|
||||
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 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
|
||||
ConfigKit v0.5.0 is selected, attribution links use the reviewed revision,
|
||||
no optional loading feature was adopted, and no Audita/workspace change or
|
||||
compatibility shim slipped into scope.
|
||||
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.
|
||||
@@ -314,6 +356,8 @@ outside this implementation pass.
|
||||
## Open Questions
|
||||
|
||||
None required for this adoption. Existing decisions select native inheritance,
|
||||
current loading/path/credential semantics, and ConfigKit before Audita before
|
||||
workspace work. Eventual release preparation must account for the reserved-key
|
||||
compatibility impact under the release policy; no version is selected here.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user