From 0b3734d352f256cf58b38fc278233b7c86df0105 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 8 Nov 2026 14:58:37 +0000 Subject: [PATCH] Plan root defaults and independent stage overrides --- docs/roadmap/configkit.md | 7 ++ docs/roadmap/glossary-stages.md | 147 +++++++++++++++++++++++++++++--- 2 files changed, 140 insertions(+), 14 deletions(-) diff --git a/docs/roadmap/configkit.md b/docs/roadmap/configkit.md index 1aa87ff..a337359 100644 --- a/docs/roadmap/configkit.md +++ b/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 diff --git a/docs/roadmap/glossary-stages.md b/docs/roadmap/glossary-stages.md index 05961cd..9eea68c 100644 --- a/docs/roadmap/glossary-stages.md +++ b/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.