# Stage-Specific Glossary Inputs **Updated:** 2026-11-08 **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 The current [CLI](../cli.md) accepts one glossary input for a processing run. The [pipeline configuration](../config.md) supports repeated glossary stages, but does not select a different glossary input for each occurrence. Allow operators to run ordered glossary stages against different glossary inputs within one processing run. For a D&D transcript, the first glossary stage can use `party.yml` and the second can use `spells.yml`. Each stage uses its selected glossaries and processes the transcript resulting from earlier stages. Operators need not combine those inputs into one glossary or run Audita separately for each pass. 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 glossaries: - party.yml - spells.yml pipeline: stages: - module: glossary glossaries: - party.yml - module: glossary glossaries: - 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` as its correction input, the second uses `spells.yml`, and grammar inherits both glossary inputs. All three stages inherit a protection selection containing both files through the root default described below. Glossary stages then exempt their active vocabulary from protection. Transcript changes carry forward between stages; configuration overrides do not. Each consumer receives the appropriate selection from the stage's effective settings, keeping correction/context inputs and protection inputs distinct. Apply this model to settings governing stage processing. Invocation-wide concerns such as configuration discovery, output destinations, and reporting mode remain global. The selected scope inventory follows below. 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. ## Configuration Scope — Resolved Settings governing an individual stage's requests, acceptance, or model-operation budget support root defaults and stage overrides. Settings governing preprocessing, the invocation's shared resources, or its final outputs remain global. Classify by the setting's meaning and consumer lifecycle, not by where current code stores it. The names below identify current settings; version-3 field representation must preserve these scope decisions. | Setting | Scope and rationale | | --- | --- | | `glossaries` | Stage: ordered glossary files supplying correction and context vocabulary. | | `protected_terms` | Stage: independently selected glossary files supplying protected vocabulary; defaults from root `glossaries` before stage inheritance. | | Applicable confidence threshold | Stage: acceptance of that stage's proposals. | | Proposal and validation profile selection | Stage: models and generation settings appropriate to each role. | | `context.description` | Stage: prompt context shared by proposals and validators. | | `validation.max_prompt_tokens` | Stage: batching budget for that stage's validators. | | `llm.operation_timeout` | Stage: deadline for each logical model operation. | | `llm.repair_attempts` | Stage: structural-repair budget for its requests. | | `llm.transient_retries` | Stage: native transient-retry budget for its requests. | | All `normalization.*` settings | Global: establish transcript segments before stage execution. | | All `chunking.*` settings | Global: establish common section boundaries and identities across stages. | | Transcript input, output destination, and `output.schema` | Global: input and final product of the whole run. | | Reporting, debug capture, and artifact directories | Global: invocation reporting and retained evidence. | | Configuration discovery, imports, and resource-source locations | Global: construct the configuration and catalog shared by stages. | | Backend definitions, credentials, concurrency, and queue capacity | Global native PromptKit resources and shared backend admission. | | Pipeline ordering and application schema version | Global: define the overall processing configuration. | Stages may select different profiles and thereby different configured models or backends. Model parameters remain in native PromptKit profiles rather than a duplicated Audita settings system. Apply stage request budgets through native request controls and operation contexts while retaining the shared engine and backend admission. Do not rebuild or mutate shared backend configuration for each stage. Per-stage validation batching does not change transcript chunking; per-stage rechunking would be a separate feature decision. ### Glossary Selection and Protected Vocabulary — Resolved Use `glossaries` at the root and on stages for an ordered sequence of glossary file paths, including when only one file is selected. Combine the entries from the selected files in declared order for the stage's glossary input. A glossary module stage without an override receives the combined root selection; an explicit stage list selects the files for a focused pass. Paths are direct file selections, with no named catalog or variable-reference language. Use `protected_terms` at both scopes for a separate ordered sequence of glossary file paths, not literal term strings. Its entries supply the protected vocabulary. Each list specifies the complete selection and replaces the inherited list; `protected_terms` is not an additive list of extra glossaries. Do not implicitly union it with correction inputs or with files selected by other stages. Resolve these settings in this order: 1. Load configuration and apply explicit CLI assignments through ConfigKit. 2. If root `protected_terms` is omitted, derive it from a copy of the effective root `glossaries`. Preserve any explicit root protection selection, including `[]`. 3. Independently inherit the effective root `glossaries` and `protected_terms` into each stage wherever that stage omits the corresponding setting. A stage override replaces only its own selected list. 4. For a glossary module stage, construct its effective protected vocabulary by subtracting its active glossary terms from its selected protected terms. Non-glossary stages use their selected protection vocabulary without this subtraction. Protection therefore defaults at the root before stage inheritance. It does not fall back to a focused stage's glossary list. In the example above, no operator protection configuration is needed: | Stage | Glossary input | Protection selection | Effective protected vocabulary | | --- | --- | --- | --- | | Party glossary pass | Party | Party + spells | Spells | | Spell glossary pass | Spells | Party + spells | Party | | Grammar | Party + spells | Party + spells | Party + spells | The table assumes distinct party and spell vocabulary. The subtraction applies after resolving both stage selections, including explicit protection overrides. It operates on recognized terms using the protection matcher's rules, including names, aliases, and supported plural forms, rather than subtracting file paths. Terms shared across files therefore participate in the same operation; shared spellings associated with different identities remain part of the overlap decision below. Keep the configured protection file list intact and construct the reduced vocabulary separately for that stage. Do not mutate root settings, loaded glossary entries, or another stage's protection. A glossary stage selecting all of its protected vocabulary as active input has no glossary-derived protection from those terms; its other validators still assess proposed corrections. A stage can supply a narrower or different `protected_terms` list. Explicit `protected_terms: []` disables glossary-derived protection for that stage without clearing its correction/context inputs or disabling other validators. Explicit `glossaries: []` clears correction/context inputs without changing the protection selection. A glossary-correction stage requires a nonempty effective glossary selection; other stages may operate without glossary context where supported. A glossary selected only by a stage is not automatically added to root protection. Use the active-term exemption for glossary correction and retain the existing module-appropriate allowance for spoken-word cleanup. Carry both selections through execution and validation rather than passing a single combined glossary to every consumer. Combined-entry conflicts and overlapping protected identities remain open below. ### Validation-Profile Fallback — Resolved Combine root and stage selections, including explicit clearing, before deriving the validation-profile fallback. If no validation selection remains, use the stage's effective proposal profile. An explicit root validation profile is inherited unless the stage replaces or clears it. Preserve presence so a value previously derived at the root is not mistaken for an explicit choice. | Root selection | Stage selection | Effective validation profile | | --- | --- | --- | | Proposal A; validation omitted | Proposal B; validation omitted | B | | Proposal A; validation V | Proposal B; validation omitted | V | | Proposal A; validation V | Proposal B; validation null | B | | Proposal A; validation null | Proposal B; validation omitted | B | | Proposal A; validation V or omitted | Validation W | W | | Proposal A; validation omitted | Both omitted | A | Clearing the validation-profile selection does not disable validation. This rule does not invent a proposal selection when none is available; a stage requiring model execution must have a valid effective proposal profile. ### Compound Values and Explicit Clearing — Resolved Resolve eligible settings field by field. A partial settings group overrides only its supplied children; an empty mapping such as `llm: {}` contributes no overrides. For example, a stage setting `llm.repair_attempts: 0` inherits the root proposal profile and operation timeout while explicitly selecting no repairs. Omitted fields inherit root settings, with derived defaults applied at the scope specified for each setting. Root protection defaulting precedes stage inheritance; validation-profile fallback follows the combination of root and stage selections. False, zero, and empty values remain explicit and follow per-field validation: zero repairs is valid, while a zero operation timeout is invalid. | Explicit input | Meaning | | --- | --- | | `context.description: ""` | Clear the inherited description. | | `glossaries: []` | Clear correction/context inputs; a glossary-correction stage then lacks its required input. | | `protected_terms: []` | Disable glossary-derived protection without changing correction/context inputs. | | Empty file-path entry in either list | Error: an empty string is not a valid glossary path. | | `llm.validation_profile: null` | Clear the inherited selection, then use the effective proposal profile. | | `llm.validation_profile: ""` | Error: use null to clear the selection deliberately. | | Empty or null proposal profile | Invalid for a stage requiring model execution. | | `llm: null` | Error: a settings group cannot be cleared as a whole. | Declare genuinely optional selectors nullable and preserve omission versus explicit null through resolution. Null is not a universal reset operation; settings groups are not nullable. The glossary settings are sequences with `[]` as their explicit-clearing form; list-null handling remains open below. Reject a glossary-correction stage's missing or empty effective input before execution. Other stages may operate without glossary context where their operation supports it, independently of their protection selection. Lists replace the entire inherited list where list-valued stage settings apply; `[]` explicitly selects an empty list. Do not append or union implicitly. 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, a CLI assignment replacing root `glossaries` with `[revised-party.yml, spells.yml]` changes grammar's inherited input and, with root `protected_terms` omitted, the derived protection inherited by all three stages. The explicit party and spell correction selections stay unchanged. An explicit root protection list is not changed by a root glossary assignment; an explicit stage protection list or `[]` remains authoritative for that stage. 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 [typed decoding contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/config.md#defaults-and-typed-decoding) already preserves explicit false, zero, empty, and permitted null values, recurses through partial mappings, and replaces ordinary sequences. Represent nullable selectors with nullable typed fields and settings groups with non-nullable structs. Use native decoding and validation rather than a parallel parser or generic deep-merge implementation. Root-to-stage inheritance remains an Audita application rule: ConfigKit does not automatically copy root fields into new sequence elements. Implement that rule in `Definition.Resolve`, using `Resolution.IsExplicit` for presence and `Resolution.EntryInfo` for the fixed pre-resolution metadata. Use `configkit.Default` for omitted stage fields and record root-field dependencies. Do not treat a derived root validation fallback as an explicit selection. Implement root protection defaulting in the same `Definition.Resolve` callback: use `configkit.Default` for root `protected_terms`, copying effective root `glossaries` and recording that path as its dependency. Then default each omitted stage protection list from the effective root protection list, even when that root value was derived. Preserve source context through both steps and avoid shared mutable list storage. Explicit empty lists must suppress defaulting. Leave `protected_terms` absent from the bundled configuration underlay. ConfigKit does not express this live list-to-list dependency as a declarative underlay reference: native `extends` concerns sibling mappings and runs before CLI assignment. Use the public recorded-resolution lifecycle, which sees final CLI assignments, rather than static duplicated lists or custom reference machinery. An explicitly null validation selection needs deliberate application fallback: `configkit.Default` correctly leaves explicit null alone. Apply the chosen fallback and use `Resolution.RecordDerivedDefault` to record the assignment and its effective proposal-profile dependency, retaining the original explicitness and history. Follow the native [recorded-resolution contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/config.md#recorded-application-resolution) for all derived mutations, and use `Definition.Validate` for domain checks on effective settings. Keep stage values independent when copying compound values. No upstream feature request is presently needed for these rules. ### Durable Decision Record 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, 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 [documentation policy](../policy/documentation.md#architecture-decision-records). The roadmap continues to own implementation status until the feature lands. Update the [configuration change guide](../internal/cli-config.md) to require classifying each new setting by consumer lifecycle, specifying its inheritance and presence behavior, and documenting its scope in the configuration reference. New settings should follow the established stage/global distinction; deliberate exceptions need a domain rationale. Link to the durable policy rather than copy the field inventory into multiple developer documents. This documentation work is part of feature acceptance, not an optional follow-up. ## Sequencing and Work Outline Implement after ConfigKit, PromptKit, CommandKit, and ReleaseKit adoption, and before final release validation and preparation. This lets the feature use the 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, glossary/protection selection, compound-value, clearing, CLI precedence, and validation-profile fallback rules. Finalize path resolution and remaining list-input details. 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. Load correction/context and protection selections separately and settle combined-entry and identity conflicts. 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. 4. Verify the selected behavior and update configuration, CLI, input contracts, pipeline documentation, maintained examples, and hard-cutover guidance as the implementation lands. Complete the durable decision record and future-setting classification guidance above. ## Acceptance Direction Use distinct party and spell fixtures with controlled model responses to show that each stage receives its intended correction and protection selections, that overrides do not leak into other stages, and that the second stage sees the first stage's accepted 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 both root glossary inputs. Verify that all three stages inherit root protection derived from those inputs despite the focused correction selections. Cover explicit root and stage protection lists, independent empty-list clearing, a glossary stage with no override using both inputs, and a file selected only on a stage not entering root protection. Verify that modules and validators receive their respective effective selections and recorded source origins. Cover repeated modules and an empty stage list. Exercise the selected request and validation overrides through stage consumers, including independent budgets without changing shared backend admission or the initial transcript sections. Cover all validation-profile fallback cases above and preserve the distinction between explicit and derived values in inspection. Cover partial and empty settings groups, explicit zero and false, nullable 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. 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. Cover root protection defaulting after CLI assignment, explicit root protection surviving glossary overrides, and recorded root-to-stage protection dependencies. Verify module-appropriate protection using terminology from both files, including legitimate corrections and cleanup; test the selected overlap/conflict behavior. For glossary stages, verify that active terms are exempt while remaining selected terms stay protected, including when protection was explicitly configured. Cover names, aliases, supported plurals, and vocabulary shared across files. Verify the all-active case produces an empty effective protected vocabulary without disabling other validators. Confirm that a later non-glossary stage still protects its full selection and that inspection distinguishes configured protection inputs from the glossary stage's effective protected vocabulary. Confirm that the durable policy, configuration contracts, and contributor guidance are in place before declaring this feature complete. ## Open Decisions The recommendations below are proposals, not selected contracts. ### 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. Each inherited glossary or protection path retains its source context, including protection derived from root glossary paths. 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. ### Combined Entries and Protected Identities **Recommendation:** preserve declared file and entry order, coalesce identical entries, and diagnose conflicting definitions rather than silently choosing by file order. Define identity handling for overlapping names, aliases, and plurals across the correction and protection selections, including how the active-term exemption handles a shared spelling associated with different identities. This keeps protection explainable but requires distinguishing true conflicts from harmless repetition or legitimate shared spellings. **Alternative:** use documented ordered precedence for conflicting entries. This supports intentional local overrides and is straightforward to apply, but can hide disagreements and make protection depend on list order. Neither approach should accidentally inherit the existing single-glossary lookup's first-match behavior as a new multi-file contract. ### List Inputs and CLI Representation **Recommendation:** accept explicit null as an empty selection, preserving native ConfigKit slice decoding and presence without an additional rejection rule. Keep `[]` as the primary documented clearing form. This requires documenting a second clearing form and ensuring null suppresses protection defaulting just as `[]` does. Select CLI syntax for supplying each complete root list using native ConfigKit overrides. **Alternative:** reject null for the two glossary-file lists and require `[]` for clearing. This offers one explicit empty-list spelling but adds application validation beyond ConfigKit's nullable slice decoding. CLI spelling remains to be selected; it does not reopen root-versus-stage precedence or imply targeted-stage overrides. ### Stage Identity and Attribution **Recommendation:** support optional operator-chosen stage IDs alongside execution 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 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 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 questions refine the design; they do not reopen whether to deliver the feature.