diff --git a/docs/roadmap/glossary-stages.md b/docs/roadmap/glossary-stages.md index 324d47b..bbb70b4 100644 --- a/docs/roadmap/glossary-stages.md +++ b/docs/roadmap/glossary-stages.md @@ -5,8 +5,9 @@ **Status:** Accepted feature scope, ownership, and stage-selection semantics for the next Audita major release, including named collections and recursive import placement, optional default sources, collection-scoped entry IDs, extensible -entry content fields, and optional stage IDs. Design decisions are resolved; -implementation remains pending. The +entry content fields, and optional stage IDs. Active glossary vocabulary takes +precedence over overlapping protection. Empty selected collections remain an +open decision; implementation is pending. The [master roadmap](library-adoption.md) owns sequencing and release completion. ## Baseline and Target @@ -29,9 +30,10 @@ Finalize the glossary representation with the agreed [version-3 application schema](configkit.md#application-schema-version--resolved) so operators migrate once. Collection placement and named selection are selected; default import sources, their tier, entry identity, and content fields are also -selected. Runtime ordering and deduplication are selected below, with existing -business logic retained. List clearing and the configuration handoff boundary -are resolved, as are optional stage identity and attribution. +selected. Runtime ordering, deduplication, and active-vocabulary exemptions are +selected below; other validation business logic is retained. List clearing and +the configuration handoff boundary are resolved, as are optional stage identity +and attribution. The treatment of empty selected collections remains open. ## Glossary Configuration Ownership — Resolved @@ -343,7 +345,8 @@ latter to suppress configuration conflicts or rewrite the resolved definitions. Rich prompt data need not lose distinct definitions merely because their text matches in the protection view. Audita owns matching, transcript-specific validation, and the selected stage-specific transformations. Apply the runtime -vocabulary rules below while retaining existing business logic. +vocabulary rules below, including the active-vocabulary exemption, while retaining +other validation business logic. ### Runtime Vocabulary and Ordering — Resolved @@ -362,13 +365,23 @@ matcher rules. Repeated membership must not multiply protection requirements. Retain the association between each spelling and all contributing entries so vocabulary deduplication does not discard identity information. -Preserve the current business logic for overlapping terms, ambiguous aliases, -and identity-dependent validation, including protected-name repetition handling. -This decision changes representation and traversal, not those validation rules. -Carry forward the previously selected stage-selection and active-term exemption -model without introducing a new blanket exemption for spellings shared by distinct -identities. Verify existing behavior when connecting the new runtime views to -consumers; redesigning overlap or ambiguity handling is outside this change. +For a glossary stage, active glossary vocabulary takes precedence over protection +from every selected collection. Remove each active recognized spelling from the +stage's effective protected vocabulary even when a distinct, non-active entry +also contributes that spelling. Apply the existing matching rules to names, +aliases, and supported plurals. The glossary stage must be free to manipulate its +active vocabulary without protected-term rules blocking those changes. + +For example, if the active spell collection and a protected item collection both +contain Shield, that spelling is exempt during the spell pass. Other protected +spellings remain protected; sharing one spelling does not exempt every spelling +of the non-active entry. Configured entries and their associations remain intact. +The exemption is local to that stage, and other validators continue to apply. + +Preserve other existing matching and identity-dependent validation business +logic, including protected-name repetition handling. Integrate the reduced +vocabulary without reintroducing protection for exempt active spellings through +another contributing entry or a downstream protected-term check. ## Root Defaults and Stage Overrides — Resolved @@ -513,9 +526,9 @@ 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 configuration -source files or collection names. For shared spellings associated with different -identities, preserve existing business logic under the runtime vocabulary -decision above. +source files or collection names. Active spellings are exempt even when they +also belong to non-active protected entries, as resolved in the runtime vocabulary +contract above. Explicit protection selections do not override this exemption. Keep the configured protection selection intact and construct the reduced vocabulary separately for that stage. Do not mutate root settings, loaded @@ -849,8 +862,8 @@ selected rules for repeated membership and entry ordering: first occurrence of each `(collection name, id)` wins, while separate records with matching names or content remain distinct. Verify that deduplicated spellings retain all contributing entry associations and do not multiply protection requirements. Preserve existing -overlap, ambiguous-alias, and protected-name repetition behavior when adapting -consumers to these views. +ambiguous-alias and protected-name repetition behavior outside the selected +active-vocabulary exemption when adapting consumers to these views. Exercise the selected request and validation overrides through stage consumers, including independent budgets without changing shared backend admission or the @@ -877,13 +890,38 @@ 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 collections, including legitimate corrections and cleanup; retain regression coverage for existing -overlap and ambiguity behavior. +validation behavior outside the selected active-vocabulary exemption. 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 collections. +Verify a spelling contributed by both an active entry and a distinct non-active +protected entry remains exempt regardless of collection order or explicit +protection selection. Check that protected-term validation does not block changes +to that active spelling, while unrelated spellings of the non-active entry remain +protected. Preserve other validators and later stages' independent protection. 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 + +### Empty Selected Collections + +A nonempty selection such as `glossaries: [party]` can refer to a collection with +no entries. The selected rules reject an empty selection for a glossary-correction +stage, but do not yet settle empty collection definitions or selections whose +combined collections contain no entries. + +**Recommendation:** permit empty collection definitions, but require a glossary +stage's combined selected collections to contain at least one entry. Validate +that requirement through ConfigKit before handoff. This allows reusable assets +and mixtures of empty and populated collections without running a correction +pass that has no vocabulary. + +**Alternative:** allow an empty combined glossary and treat that stage as a no-op. +This supports reusable pipelines when a campaign has no entries for a particular +pass, but can hide an unintentionally empty input and requires explicit reporting +and execution semantics for the skipped stage. This behavior is not selected.