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

@@ -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.