eric/audita
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

Resolve stage CLI precedence within native ConfigKit capabilities

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-08 15:34:20 +00:00
parent 943152d1d5
commit 760a7cecc0
2 changed files with 42 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/roadmap/configkit.md
View File

@@ -123,8 +123,9 @@ file remain terminal.
presence and source provenance, and its module and validators receive consistent
effective settings. Apply its [selected scope and fallback rules](glossary-stages.md#configuration-scope--resolved)
and [compound-value and clearing rules](glossary-stages.md#compound-values-and-explicit-clearing--resolved),
and complete its required durable decision record. The glossary roadmap owns
the remaining precedence, path, and attribution decisions. This
together with its [CLI precedence and native-support boundary](glossary-stages.md#cli-overrides-and-stage-precedence--resolved).
Complete its required durable decision record. The glossary roadmap owns
the remaining path and attribution decisions. This
application scope model does not change native source composition or
sibling-inheritance semantics.

60
docs/roadmap/glossary-stages.md
View File

@@ -152,6 +152,33 @@ Preserve the owning library's semantics for library-owned resources and
identified collections. These scope rules do not introduce a custom merge
language or change ConfigKit source composition.
### CLI Overrides and Stage Precedence — Resolved
Ordinary CLI setting flags override the corresponding root settings through
ConfigKit's native CLI override API. Resolve stage inheritance afterward:
omitted stage fields inherit the effective root values, while explicit stage
values and clearing remain authoritative for that stage. Apply validation-profile
fallback after combining these selections. This preserves deliberate differences
between stages while allowing invocation-specific changes to their defaults.
For the pipeline example above, `--glossary revised-party.yml` changes the
effective glossary for the first glossary stage and the grammar stage to
`revised-party.yml`; the second glossary stage still uses `spells.yml`. A stage
with `glossary: null` remains cleared. Apply this precedence consistently to all
stage-capable settings. Submit only explicitly supplied CLI values to ConfigKit;
preserve false, zero, and empty values under their per-field rules rather than
allowing parser defaults to override configuration.
Keep CLI functionality within ConfigKit's native capabilities. ConfigKit v1.1.0
does not support sequence-index paths in its CLI override API, so targeted-stage
CLI overrides are not part of this plan. Operators supply stage-specific values
in configuration files. Do not implement a parallel override system, custom
merge machinery, or a workaround for addressing stage-list entries. Any future
targeted-stage CLI support should depend on suitable native ConfigKit support.
The open stage-identity decision concerns reporting and diagnostics; stage IDs
do not imply CLI targeting. Audita's domain-specific inheritance and fallback
rules remain within ConfigKit's supported application-resolution lifecycle.
### ConfigKit Support
Use the selected ConfigKit v1.1.0 public lifecycle for this work. Its
@@ -184,7 +211,7 @@ No upstream feature request is presently needed for these rules.
Completion requires recording the scope model in durable documentation before
retiring this roadmap. Put the enduring classification rule and its rationale
in the [architecture policy](../policy/architecture.md); keep the implemented
per-field scope, compound-value, clearing, and fallback contracts in the
per-field scope, compound-value, clearing, precedence, and fallback contracts in the
[configuration reference](../config.md).
These configuration design decisions do not require an ADR. Reserve ADRs for
major architectural decisions under the
@@ -207,8 +234,8 @@ adopted configuration and CLI conventions and avoids adapting it twice. Keep the
requirement visible during library design without expanding those migrations
into feature implementation.
1. Apply the selected scope, compound-value, clearing, and validation-profile
fallback rules. Finalize path resolution and CLI precedence. Incorporate
1. Apply the selected scope, compound-value, clearing, CLI precedence, and
validation-profile fallback rules. Finalize path resolution. Incorporate
these into the version-3 schema rather than retain the old module-name list.
2. Resolve effective stage settings and carry them through stage execution,
proposal generation, and validation. Carry selected glossary inputs through
@@ -245,7 +272,10 @@ selectors, empty-list replacement, and invalid empty strings or group nulls.
Verify that clearing a validation selection follows the effective proposal
profile without disabling validation, and that clearing a required glossary
fails before execution. Check recorded dependencies and retained clear-input
history as well as effective values.
history as well as effective values. Verify that explicit CLI flags change root
defaults and inherited stage values while preserving explicit stage settings
and clearing. Cover profile fallback after CLI assignment, explicit false/zero/
empty CLI values where valid, and the absence of overrides from parser defaults.
Confirm that the durable policy, configuration contracts, and contributor
guidance are in place before declaring this feature complete.
@@ -253,19 +283,6 @@ guidance are in place before declaring this feature complete.
The recommendations below are proposals, not selected contracts.
### CLI Overrides and Stage Precedence
**Recommendation:** an ordinary setting flag changes the root default; explicit
stage settings remain more specific. Add a supported targeted selection for
changing one stage when needed, coordinated with stage identity below. This
preserves the meaning of scope, but a global flag will not force the same value
onto every stage. Preserve explicit false, zero, and empty CLI values.
**Alternative:** apply ordinary CLI setting flags to every stage after resolving
stage settings. This makes a CLI override uniformly authoritative, but can erase
deliberate stage differences, including different glossary files. Choose and
document the rule before wiring flags; do not infer it from parser order.
### Relative Paths and Source Context
**Recommendation:** use ConfigKit's supported source context to resolve a
@@ -296,14 +313,15 @@ input selection alone does not decide this protection policy.
### Stage Identity and Attribution
**Recommendation:** support optional operator-chosen stage IDs alongside execution
position and module identity. Use them for readable reports and targeted overrides
position and module identity. Use them for readable reports and diagnostics
when supplied, and show each stage's effective inputs and source origins. This
helps distinguish repeated modules and survives reordering, but introduces ID
validation and selection rules that must be specified.
validation rules that must be specified. CLI targeting is outside this decision
under the resolved precedence and native-support boundary above.
**Alternative:** identify stages only by position and module. This avoids another
configuration field, but positional references change when stages are reordered
and are less convenient for targeted overrides. In either case, retain ordered
configuration field, but positional references in reports and diagnostics change
when stages are reordered. In either case, retain ordered
execution and repeated modules rather than treating the pipeline as a set.
The capability and its inclusion in the next major release are settled. These