Plan root defaults and independent stage overrides

docs/roadmap/configkit.md

@@ -117,6 +117,13 @@ file remain terminal.
    its application schema. Native PromptKit resources own those settings and
    their resolution. Coordinate the hard cutover and examples here, using the
    resolved discovery and import policy above.
+7. Account for the [root-default and stage-override model](glossary-stages.md#root-defaults-and-stage-overrides--resolved)
+   in version-3 schema design. Implement it during the glossary feature stage
+   after library adoption. Each stage resolves independently with explicit-value
+   presence and source provenance, and its module and validators receive consistent
+   effective settings. The glossary roadmap owns the remaining scope, precedence,
+   path, and attribution decisions. This application scope model does not change
+   native source composition or sibling-inheritance semantics.
 
 ## Documentation and Acceptance
 

docs/roadmap/glossary-stages.md

@@ -2,8 +2,8 @@
 
 **Updated:** 2026-11-08
 
-**Status:** Accepted scope for the next Audita major release. Initial outline;
-detailed design and implementation remain pending. The
+**Status:** Accepted scope and configuration model for the next Audita major
+release. Remaining design decisions and implementation are pending. The
 [master roadmap](library-adoption.md) owns sequencing and release completion.
 
 ## Baseline and Target
@@ -19,13 +19,50 @@ glossary and processes the transcript resulting from earlier stages. Operators
 need not combine those inputs into one glossary or run Audita separately for
 each pass.
 
-This example describes the intended behavior, not a selected configuration syntax.
 The major-release policy permits a hard cutover; the current single-glossary CLI
 and pipeline representation do not constrain the target design.
 The final representation belongs to the agreed
 [version-3 application schema](configkit.md#application-schema-version--resolved),
 with one hard cutover covering library adoption and this feature.
 
+## Root Defaults and Stage Overrides — Resolved
+
+Define global stage settings at the configuration root. Represent the pipeline
+as an ordered `pipeline.stages` list of objects, each selecting a `module` and
+optionally overriding stage settings. Use typed configuration fields, not a
+separate variable-substitution language. The selected glossary configuration is:
+
+```yaml
+version: 3
+glossary: party.yml
+pipeline:
+  stages:
+    - module: glossary
+    - module: glossary
+      glossary: spells.yml
+    - module: grammar
+```
+
+Resolve every stage independently against the global settings. Omitted stage
+settings inherit their global values; explicit stage values override them.
+Preserve meaningful false, zero, and empty values under each setting's validation
+rules rather than treating them as omission. A stage override does not alter
+the root settings or the defaults seen by later stages.
+
+In this example, the first glossary stage uses `party.yml`, the second uses
+`spells.yml`, and grammar inherits `party.yml` wherever it or its validators
+consume the glossary. Transcript changes carry forward between stages;
+configuration overrides do not. A stage's module and associated validators
+receive its effective stage settings consistently. Whether protected vocabulary
+needs a broader selection remains an open domain decision below.
+
+Apply this model to settings governing stage processing. Invocation-wide
+concerns such as configuration discovery, output destinations, and reporting
+mode remain global. The exact set of stage settings is still to be selected.
+Preserve stage order, repeated modules, and explicit empty-pipeline behavior.
+Use native ConfigKit loading, presence, and provenance facilities; Audita owns
+the meaning of stage scope and passes the effective settings to its consumers.
+
 ## Sequencing and Work Outline
 
 Implement after ConfigKit, PromptKit, CommandKit, and ReleaseKit adoption, and
@@ -34,11 +71,12 @@ 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. Define how a stage selects its glossary, how input paths resolve, and how
-   defaults and CLI selection interact with stage configuration.
-2. Carry the selected glossary through loading, stage execution, proposal
-   generation, and validation. Review glossary consumers outside the glossary
-   module so their input semantics are deliberate.
+1. Finalize the stage-setting inventory, compound-value and clearing rules, path
+   resolution, and CLI precedence under the selected scope model. 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
+   loading and settle the protected-vocabulary behavior for all consumers.
 3. Make repeated stages and their selected inputs understandable in inspection,
    diagnostics, and reports. Account for all consumed glossary files in input
    handling and output-collision protection.
@@ -55,15 +93,96 @@ transcript changes. Verify meaningful errors for invalid selections or inputs,
 and retain the selected domain validation and partial-success behavior. Exact
 test cases follow the design; live provider calls are unnecessary.
 
+Verify root fallback, per-stage override isolation, and explicit-value presence
+for the selected stage settings. Include the grammar stage after the overridden
+glossary stage to establish that it inherits the root glossary. Verify that each
+stage's module and validators receive consistent effective settings, including
+their recorded source origins. Cover repeated modules and an empty stage list.
+
 ## Open Decisions
 
-Detailed choices are deliberately deferred to the feature-design discussion:
+The recommendations below are proposals, not selected contracts.
 
-- Stage representation, glossary references versus inline file paths, and
-  defaults or CLI overrides.
-- Which glossary is used by other modules and validators, including protected
-  term checks and overlapping terms across inputs.
-- Stage identity and input attribution in inspection, errors, and reports.
+### Settings Eligible for Stage Scope
+
+**Recommendation:** include glossary input, applicable confidence thresholds,
+proposal/validation profile selection, and other settings that govern an
+individual stage's work. Inventory current settings by the lifecycle of their
+consumer before finalizing the schema. Keep discovery, transcript destinations,
+reporting, and other invocation-wide settings global. This provides useful
+flexibility without implying that a stage can reconfigure the entire run.
+
+**Alternative:** initially expose only glossary overrides and add other stage
+settings later. This reduces the first implementation's scope, but leaves an
+incomplete application of the selected model and may require further schema
+changes for settings already known to vary by stage.
+
+### Compound Values and Explicit Clearing
+
+**Recommendation:** resolve eligible settings by field, preserving explicit
+presence and following the owning library's semantics for compound values.
+Define omission, null, and empty behavior for each selected field; for glossary
+input, distinguish inheriting a default from an intentional absence if that is
+supported. Reuse native mechanisms rather than introducing a custom generic
+deep-merge engine. This keeps partial stage settings useful and defaults visible.
+
+**Alternative:** replace an entire settings group whenever that group appears
+on a stage. This gives simple replacement semantics, but changing one value may
+require repeating unrelated global settings. The choice must respect upstream
+contracts for any library-owned resource rather than redefine their merging.
+
+### 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
+configuration path relative to the document supplying that value, and resolve
+CLI paths relative to the working directory. A stage inheriting a root glossary
+also inherits that value's source context. This supports reusable imported
+configuration; verify the native facilities before selecting implementation.
+
+**Alternative:** resolve all relative glossary paths from the working directory.
+This has one simple base and suits invocation-local inputs, but makes reusable
+configuration dependent on where Audita is launched. Decide the base explicitly
+for no-main-file operation as well.
+
+### Glossary Selection and Protected Vocabulary
+
+**Recommendation:** start from each stage's effective glossary for its module
+and validators, with no implicit carryover or union of other stage inputs. This
+matches the selected scope model and keeps each stage understandable in isolation.
+Review whether protecting terms corrected by earlier stages requires a separate,
+explicit protected-vocabulary selection; overlapping terms need deliberate rules.
+
+**Alternative:** protect vocabulary from all configured glossary inputs while
+using the effective stage glossary for proposal generation. This could preserve
+party names during later spell or grammar work, but makes stage behavior depend
+on other stages' inputs and requires conflict and overlap semantics. Ordinary
+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
+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.
+
+**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
+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
 questions refine the design; they do not reopen whether to deliver the feature.