Plan ConfigKit glossary composition and derived runtime views
This commit is contained in:
@@ -126,10 +126,13 @@ file remain terminal.
|
||||
together with its [CLI precedence and native-support boundary](glossary-stages.md#cli-overrides-and-stage-precedence--resolved).
|
||||
Use its [separate glossary and protection selections](glossary-stages.md#glossary-selection-and-protected-vocabulary--resolved),
|
||||
including root protection defaulting through recorded application resolution.
|
||||
Apply its [post-handoff application-resource path policy](glossary-stages.md#relative-paths-and-source-context--resolved)
|
||||
while leaving upstream configuration resolution to ConfigKit.
|
||||
Adopt its [glossary configuration ownership boundary](glossary-stages.md#glossary-configuration-ownership--resolved):
|
||||
glossary assets use native loading, composition, inheritance, collection
|
||||
identity, and typed decoding before handoff. Audita derives consumer-specific
|
||||
runtime views from that result and removes its separate glossary YAML loader.
|
||||
Complete its required durable decision record. The glossary roadmap owns
|
||||
the remaining list-input, combined-entry, and attribution decisions. This
|
||||
the remaining collection schema, composition scope, identity, runtime-view,
|
||||
selection-input, and attribution decisions. This
|
||||
application scope model does not change native source composition or
|
||||
sibling-inheritance semantics.
|
||||
|
||||
|
||||
@@ -2,73 +2,106 @@
|
||||
|
||||
**Updated:** 2026-11-08
|
||||
|
||||
**Status:** Accepted scope and configuration model for the next Audita major
|
||||
release. Remaining design decisions and implementation are pending. The
|
||||
**Status:** Accepted feature scope, ownership, and stage-selection semantics for
|
||||
the next Audita major release. Collection schema, 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.
|
||||
but does not select different glossary inputs for each occurrence. Glossary
|
||||
files currently have a separate [YAML input contract](../integrations/transcript-glossary-files.md#glossary-yaml-contract).
|
||||
|
||||
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.
|
||||
Make glossaries and glossary collections reusable, composable configuration
|
||||
assets loaded and composed by ConfigKit. Allow ordered stages to select different resolved
|
||||
vocabulary within one processing run: for example, a focused party pass, a
|
||||
focused spell pass, and grammar cleanup using both. Each stage processes the
|
||||
transcript resulting from earlier stages. Operators need not maintain one
|
||||
manually combined 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.
|
||||
The major-release policy permits a hard cutover. The current single-glossary
|
||||
CLI, standalone parser, and file schema do not constrain the target design.
|
||||
Finalize the glossary representation with the agreed
|
||||
[version-3 application schema](configkit.md#application-schema-version--resolved)
|
||||
so operators migrate once. Exact collection, entry, and selection syntax remains
|
||||
open below; the ownership and domain semantics in this roadmap are selected.
|
||||
|
||||
## Glossary Configuration Ownership — Resolved
|
||||
|
||||
Glossaries are configuration. ConfigKit owns their source loading, parsing,
|
||||
composition, inheritance, collection operations, strict typed decoding, and
|
||||
configuration provenance. Audita supplies the Go schema, collection identity
|
||||
registrations where applicable, and domain validation through supported public
|
||||
APIs. Use native imports and layering rather than an Audita YAML loader or
|
||||
private glossary merge engine.
|
||||
|
||||
Before transcript processing, hand off fully resolved, typed Go glossary
|
||||
configuration and stage selections to Audita. Configuration-level domain checks
|
||||
belong in the supported ConfigKit validation lifecycle; structural decoding alone
|
||||
does not establish domain correctness. Audita's processing code must not reopen
|
||||
glossary documents or parse arbitrary YAML after this handoff. Remove the separate
|
||||
glossary decoding/composition path when the new contract lands.
|
||||
|
||||
All configuration-source path and resolution behavior remains upstream-owned,
|
||||
including glossary documents, imports, overlays, and source resource contexts.
|
||||
Retain native source attribution through application resolution. A glossary
|
||||
filename is a configuration source, not an application-data file for a second
|
||||
post-handoff loader. Choose the source arrangement through ConfigKit's public
|
||||
composition APIs; a string in an application field does not automatically cause
|
||||
ConfigKit to load another document. The exact collection layout and load scope
|
||||
must be settled before implementation.
|
||||
|
||||
### Derived Runtime Representations — Resolved
|
||||
|
||||
Keep the resolved configuration intact. Audita derives separate runtime views
|
||||
for its consumers, preserving traceability to configured entries and selections:
|
||||
|
||||
| Consumer | Derived representation |
|
||||
| --- | --- |
|
||||
| Glossary module LLM | Rich entries with terms, categories, descriptive comments/context when present, and other relevant configured fields. |
|
||||
| Protected-term validator | Deduplicated recognized vocabulary prepared for deterministic matching. |
|
||||
| Glossary-stage protection | Selected protected vocabulary minus the active glossary vocabulary. |
|
||||
| Diagnostics and inspection | Resolved definitions and selections with their configuration origins, distinguished from derived runtime views. |
|
||||
|
||||
ConfigKit's identity and composition rules govern which configuration records
|
||||
coexist or replace one another. Runtime vocabulary deduplication governs whether
|
||||
multiple valid records contribute the same recognized spelling. Do not use the
|
||||
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. Detailed handling
|
||||
of ambiguous identities and rich-entry payloads remains open below.
|
||||
|
||||
## Root Defaults and Stage Overrides — Resolved
|
||||
|
||||
Define global stage settings at the configuration root. Represent the pipeline
|
||||
Define global stage defaults 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.
|
||||
optionally overriding stage settings. Resolve every stage independently against
|
||||
the root settings. Omitted stage settings inherit; explicit stage values override.
|
||||
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.
|
||||
root settings or 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.
|
||||
The names `glossaries` and `protected_terms` below identify the agreed correction/
|
||||
context and protection selection roles. Their final representation must select
|
||||
resolved glossary configuration; direct file-path lists are not a settled schema
|
||||
for this redesign. Collection definitions, collection references, and their field
|
||||
names are part of the native configuration-shape decision below. Do not introduce
|
||||
a general variable-substitution language.
|
||||
|
||||
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.
|
||||
For the party/spells use case, the root selects both collections, the first
|
||||
stage selects party vocabulary, the second selects spell vocabulary, and grammar
|
||||
inherits both. All stages inherit the root protection selection by default;
|
||||
glossary stages exempt their active vocabulary as described below. Transcript
|
||||
changes carry forward; configuration overrides do not. Each consumer receives
|
||||
the appropriate view of its stage's effective settings.
|
||||
|
||||
Invocation-wide concerns such as configuration discovery, output destinations,
|
||||
and reporting mode remain global. Preserve stage order, repeated modules, and
|
||||
explicit empty-pipeline behavior. Use native ConfigKit presence and provenance;
|
||||
Audita owns the domain meaning of stage scope.
|
||||
|
||||
## Configuration Scope — Resolved
|
||||
|
||||
@@ -76,13 +109,14 @@ Settings governing an individual stage's requests, acceptance, or model-operatio
|
||||
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.
|
||||
it. The inventory below records the selected scopes; version-3 field
|
||||
representation must preserve these 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. |
|
||||
| `glossaries` selection | Stage: resolved glossary collections supplying correction and context vocabulary. |
|
||||
| `protected_terms` selection | Stage: independently selected glossary collections supplying protected vocabulary; defaults from root `glossaries` before stage inheritance. |
|
||||
| Glossary definitions and collection composition | Global: typed definitions composed through ConfigKit; runtime views are derived per consumer. |
|
||||
| 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. |
|
||||
@@ -108,36 +142,37 @@ 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.
|
||||
Select correction/context vocabulary and protection vocabulary independently
|
||||
at root and stage scopes. A glossary stage without an override uses the entire
|
||||
root glossary selection; an explicit stage selection supports a focused pass.
|
||||
An explicit protection selection is complete, not an additive set of extra
|
||||
vocabulary. Do not implicitly union it with correction inputs or collections
|
||||
selected by other stages.
|
||||
|
||||
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.
|
||||
These domain rules survive the configuration redesign. The native collection
|
||||
shape, entry order, and exact selection representation are open; configuration
|
||||
composition must follow ConfigKit's own contracts rather than a blanket local
|
||||
rule to concatenate independently parsed files.
|
||||
|
||||
Resolve these settings in this order:
|
||||
|
||||
1. Load configuration and apply explicit CLI assignments through ConfigKit.
|
||||
1. Load and compose glossary 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.
|
||||
4. After the configuration handoff, derive runtime views. 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:
|
||||
fall back to a focused stage's glossary list. In the party/spells scenario, no
|
||||
operator protection configuration is needed:
|
||||
|
||||
| Stage | Glossary input | Protection selection | Effective protected vocabulary |
|
||||
| --- | --- | --- | --- |
|
||||
@@ -148,12 +183,12 @@ protection configuration is needed:
|
||||
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.
|
||||
names, aliases, and supported plural forms, rather than subtracting configuration
|
||||
source files or collection names. Terms shared across collections 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
|
||||
Keep the configured protection selection 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
|
||||
@@ -172,7 +207,7 @@ 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.
|
||||
Collection identity, runtime overlap, and payload details remain open below.
|
||||
|
||||
### Validation-Profile Fallback — Resolved
|
||||
|
||||
@@ -212,7 +247,6 @@ zero repairs is valid, while a zero operation timeout is invalid.
|
||||
| `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. |
|
||||
@@ -220,8 +254,9 @@ zero repairs is valid, while a zero operation timeout is invalid.
|
||||
|
||||
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.
|
||||
settings groups are not nullable. Preserve explicit empty selection semantics
|
||||
(`[]` for list selectors) in the final glossary schema; null handling remains open
|
||||
below. This concerns stage selections, not ConfigKit-owned definition collections.
|
||||
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.
|
||||
@@ -241,16 +276,16 @@ values and clearing remain authoritative for that stage. Apply validation-profil
|
||||
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.
|
||||
For the party/spells scenario, a CLI assignment changing the root glossary
|
||||
selection 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.
|
||||
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
|
||||
@@ -262,34 +297,6 @@ 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.
|
||||
|
||||
### Relative Paths and Source Context — Resolved
|
||||
|
||||
ConfigKit owns configuration resolution upstream of its handoff to Audita,
|
||||
including discovery, configuration source paths, imports, overlays, composition,
|
||||
inheritance, and source resource contexts. Use its native behavior and public
|
||||
handoff; do not reinterpret configuration paths, reload source documents, or
|
||||
reconstruct its resolution rules in Audita.
|
||||
|
||||
The following policy applies to glossary and protection files consumed as
|
||||
application data after that handoff:
|
||||
|
||||
- Resolve a relative file path supplied by configuration against the supplying
|
||||
document's source resource context.
|
||||
- Resolve a relative CLI file path against the invocation's working directory,
|
||||
including when no main configuration file was found.
|
||||
- Preserve each input path's source context through root-to-stage inheritance
|
||||
and root protection defaulting. Deriving a protection list does not give its
|
||||
paths a new filesystem base.
|
||||
|
||||
Use ConfigKit's public origin metadata and `Result.SourceContext` to obtain the
|
||||
owning filesystem and base directory, following its
|
||||
[source resource contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/config.md#source-resource-contexts).
|
||||
Retain source attribution through Audita's recorded derivations so each file's
|
||||
original context can be identified. Honor upstream filesystem and context
|
||||
semantics; do not invent a host-file base for a contextless synthetic source.
|
||||
This keeps imported configuration reusable while leaving configuration loading
|
||||
and resolution under ConfigKit's ownership.
|
||||
|
||||
### ConfigKit Support
|
||||
|
||||
Use the selected ConfigKit v1.1.0 public lifecycle for this work. Its
|
||||
@@ -300,6 +307,22 @@ 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.
|
||||
|
||||
Use the native [collection and inheritance contracts](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/config.md#strict-document-composition)
|
||||
for glossary definitions. For identified lists, register identity constraints in
|
||||
Audita's ConfigKit definition so native final validation also covers values from
|
||||
defaults, CLI, and recorded resolution. YAML-only declarations do not provide
|
||||
that final-result guarantee. Decide identity fields and scope below.
|
||||
|
||||
Compose sources in the scope where cross-source identity and inheritance are
|
||||
intended to apply. Loading files separately and concatenating afterward does not
|
||||
provide those upstream guarantees. Strict peers reject duplicate identities,
|
||||
including identical records; higher layers follow native collection operations,
|
||||
and upsert replaces a whole matching record. Empty identified collections follow
|
||||
their native mode (`[]` does not clear an append/upsert collection). These rules
|
||||
are distinct from Audita's whole-list replacement of ordinary stage selections.
|
||||
Do not extend native inheritance beyond its supported sibling scope or treat
|
||||
inherited entries as abstract templates exempt from normal validation.
|
||||
|
||||
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
|
||||
@@ -328,19 +351,25 @@ 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.
|
||||
The selected defaulting rules use existing public APIs. Verify the final glossary
|
||||
composition and selection design against the native API before implementation;
|
||||
do not compensate for a mismatch with a private configuration system.
|
||||
|
||||
### 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.
|
||||
Completion requires durable documentation before retiring this roadmap. Record
|
||||
the glossary-configuration ownership boundary and typed-handoff architecture in
|
||||
an ADR under the [documentation policy](../policy/documentation.md#architecture-decision-records).
|
||||
This is an architectural ownership decision; routine scope and clearing choices
|
||||
do not each require an ADR. The roadmap owns implementation status and sequencing.
|
||||
|
||||
Put enduring scope classification and ownership rules in the
|
||||
[architecture policy](../policy/architecture.md) and the implemented collection,
|
||||
selection, defaulting, and clearing contracts in the
|
||||
[configuration reference](../config.md). Update the glossary input contract and
|
||||
consumer internals as the redesign lands, removing obsolete standalone-parser
|
||||
instructions. Document the distinction between configuration identity and derived
|
||||
runtime vocabulary without copying the native ConfigKit reference into Audita.
|
||||
|
||||
Update the [configuration change guide](../internal/cli-config.md) to require
|
||||
classifying each new setting by consumer lifecycle, specifying its inheritance
|
||||
@@ -358,20 +387,25 @@ 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, application-resource path resolution, and
|
||||
validation-profile fallback rules. Finalize 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.
|
||||
1. Settle the native collection/entry schema, source composition scope, stage
|
||||
selection syntax, and remaining domain decisions below. Preserve the selected
|
||||
scope, clearing, CLI precedence, and fallback semantics in version 3.
|
||||
2. Adopt ConfigKit loading for glossary configuration. Register the selected
|
||||
collection identities, supply domain validation, and deliver final typed
|
||||
definitions and selections before transcript processing. Remove the redundant
|
||||
standalone YAML parser and local composition path.
|
||||
3. Derive rich LLM inputs, deduplicated protection vocabulary, and glossary-stage
|
||||
exemptions from resolved configuration. Route the appropriate views through
|
||||
proposal generation and validators without mutating configuration or other
|
||||
stages. Preserve source attribution for diagnostics and inspection.
|
||||
4. Verify native composition and the domain behavior together. Account for all
|
||||
consumed configuration sources in input handling and output-collision
|
||||
protection. Make repeated stages and their selected collections understandable
|
||||
in inspection, diagnostics, and reports.
|
||||
5. Update configuration, CLI, input contracts, pipeline documentation, maintained
|
||||
examples, and hard-cutover guidance as implementation lands. Complete the ADR,
|
||||
durable policy, and future-setting classification guidance above. No runtime
|
||||
compatibility layer for the old glossary file format is required.
|
||||
|
||||
## Acceptance Direction
|
||||
|
||||
@@ -389,13 +423,21 @@ 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.
|
||||
both inputs, and a collection 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 relative glossary and protection inputs from main and imported
|
||||
configuration sources and from CLI assignments, including no-main-file operation.
|
||||
Verify that inherited and derived protection inputs retain their original source
|
||||
context while Audita leaves ConfigKit's configuration resolution unchanged.
|
||||
Exercise native glossary composition, inheritance, collection identity checks,
|
||||
and supported explicit layering with reusable party/spells fixtures. Cover source
|
||||
origins, strict decoding failures, and domain validation failures before processing.
|
||||
Test configured discovery/no-main-file behavior through the supported load path;
|
||||
do not add a secondary glossary-file resolver. Verify that inheritance and
|
||||
application derivations retain traceability to their configuration inputs.
|
||||
|
||||
Verify that distinct valid definitions can contribute to a deduplicated runtime
|
||||
vocabulary without rewriting rich configured entries. Check that rich LLM input
|
||||
contains the selected descriptive fields, and that deriving or using any runtime
|
||||
view leaves configuration and other consumers' views unchanged. Verify the
|
||||
selected rules for repeated membership, entry ordering, and ambiguous spellings.
|
||||
|
||||
Exercise the selected request and validation overrides through stage consumers,
|
||||
including independent budgets without changing shared backend admission or the
|
||||
@@ -412,11 +454,11 @@ 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
|
||||
Verify module-appropriate protection using terminology from both collections, 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.
|
||||
Cover names, aliases, supported plurals, and vocabulary shared across collections.
|
||||
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
|
||||
@@ -428,21 +470,77 @@ guidance are in place before declaring this feature complete.
|
||||
|
||||
The recommendations below are proposals, not selected contracts.
|
||||
|
||||
### Combined Entries and Protected Identities
|
||||
### Native Collection Shape and Stage Selection
|
||||
|
||||
**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.
|
||||
**Recommendation:** define named glossary collections in a typed mapping and
|
||||
have root/stage selections identify those resolved collections. Use native
|
||||
ConfigKit composition to populate the mapping, with minimal Audita lookup and
|
||||
selection validation after structural resolution. This decouples reusable assets
|
||||
from file layout and keeps focused stages concise. It requires choosing the
|
||||
collection/selection field layout, membership representation, ordering, and
|
||||
behavior when the same entry is selected through several collections. The exact
|
||||
YAML syntax is not yet selected.
|
||||
|
||||
**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.
|
||||
**Alternative:** embed complete glossary entry collections directly in root and
|
||||
stage settings, using native inheritance and source placement for reuse. This
|
||||
avoids collection-reference lookup but makes stage settings larger and reuse
|
||||
subject to native sibling scopes. It can duplicate definitions and complicate
|
||||
independent correction/protection selections. Neither option adds general
|
||||
variable interpolation or a custom merge language.
|
||||
|
||||
### Composition Scope and Reuse
|
||||
|
||||
**Recommendation:** compose glossary definitions within the application's native
|
||||
configuration graph before the final handoff. Treat independent sources as strict
|
||||
peers and reserve intentional replacement for explicit upstream layering. This
|
||||
makes cross-source identity checks, inheritance, and provenance available in the
|
||||
same scope. Verify a practical import/placement layout for standalone reusable
|
||||
assets; neither file-list order nor application selection should secretly create
|
||||
override tiers. Standard inspection integration should follow the resulting
|
||||
ConfigKit configuration rather than a second private catalog.
|
||||
|
||||
**Alternative:** load isolated glossary libraries through separate ConfigKit
|
||||
definitions and assemble a typed application view before processing. This can
|
||||
provide useful library boundaries and independent validation, but inheritance and
|
||||
identity guarantees stop at each load. Cross-library selection validation and
|
||||
inspection integration would need additional application work. Do not claim that
|
||||
concatenating separate results gives native cross-load composition guarantees.
|
||||
|
||||
### Entry Identity and Rich Fields
|
||||
|
||||
**Recommendation:** use explicit stable entry IDs independent of displayed terms,
|
||||
with application-registered identity on identified lists. Choose whether identity
|
||||
is global or scoped by collection and how a shared entry belongs to multiple
|
||||
collections before fixing the schema. Distinct meanings can then share a spelling
|
||||
without being the same record. Retain rich semantic fields for model context;
|
||||
settle their names and required/optional status, including the relationship of
|
||||
current `summary` to optional comment/context data. Explicit IDs add authoring
|
||||
work and require clear identity scope, but survive changes to displayed terms.
|
||||
|
||||
**Alternative:** use a natural key such as term plus category, or a keyed mapping
|
||||
whose keys provide identity. This can reduce record ceremony and fits native
|
||||
ConfigKit mechanisms, but natural keys can conflate meanings and change on rename;
|
||||
mapping keys still need an intentional identity convention. Do not silently
|
||||
infer semantic identity from matching text or inherit first-match lookup behavior.
|
||||
|
||||
### Runtime Vocabulary and Identity Ambiguity
|
||||
|
||||
**Recommendation:** deduplicate recognized spellings for protection using the
|
||||
same matching rules as active-term subtraction, while retaining distinct resolved
|
||||
entry identities and rich data. Repeated membership must not multiply protection.
|
||||
For checks that depend on identity, do not infer equivalence or grant a relaxation
|
||||
solely because entries share an alias; define conservative behavior for ambiguous
|
||||
matches. Specify deterministic rich-input ordering and whether repeated selection
|
||||
of the same resolved entry appears once. This preserves useful context without
|
||||
turning runtime deduplication into configuration conflict resolution, but requires
|
||||
focused decisions and tests around identity-dependent cleanup.
|
||||
|
||||
**Alternative:** reject ambiguous names or aliases at domain validation time.
|
||||
This simplifies deterministic identity checks, but disallows legitimate shared
|
||||
spellings and burdens authors of reusable collections. Native ConfigKit record
|
||||
identity checks remain authoritative in either case; they do not determine which
|
||||
meaning a transcript occurrence has. The active-glossary exemption itself is
|
||||
already selected and is not reopened by this decision.
|
||||
|
||||
### List Inputs and CLI Representation
|
||||
|
||||
@@ -450,10 +548,11 @@ behavior as a new multi-file contract.
|
||||
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.
|
||||
does. After choosing the collection schema, select CLI syntax for whole root
|
||||
selections using native ConfigKit overrides. These are ordinary selection lists,
|
||||
not entry collections governed by native identity/operation policies.
|
||||
|
||||
**Alternative:** reject null for the two glossary-file lists and require `[]` for
|
||||
**Alternative:** reject null for the two selection 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
|
||||
|
||||
@@ -12,8 +12,10 @@ and ReleaseKit so operators and maintainers encounter the same conventions
|
||||
across the application suite. Choose the best target state for Audita; maintaining
|
||||
compatibility with current behavior carries no weight in this major release.
|
||||
|
||||
The release also includes glossary stages that select different glossary inputs.
|
||||
This is required feature scope alongside the library upgrades.
|
||||
The release also includes reusable glossary configuration composed through
|
||||
ConfigKit and stages that select different glossary inputs. This is required
|
||||
feature scope alongside the library upgrades; the glossary roadmap owns the
|
||||
configuration handoff and derived runtime representations.
|
||||
|
||||
This document owns shared adoption principles, sequencing, dependency selection,
|
||||
and cross-library decisions, including the ReleaseKit adoption work below. The
|
||||
@@ -25,7 +27,7 @@ open decisions:
|
||||
| [ConfigKit](configkit.md) | Stable configuration API, loading, discovery, presence, secrets, and provenance |
|
||||
| [PromptKit](promptkit.md) | Native resources and bundled catalog, role integration, execution, and source accounting |
|
||||
| [CommandKit](commandkit.md) | Standard operator interface, configuration commands, full ckprompt inspection, and reporting |
|
||||
| [Stage-Specific Glossary Inputs](glossary-stages.md) | Ordered glossary stages that select different input files |
|
||||
| [Stage-Specific Glossary Inputs](glossary-stages.md) | Reusable glossary configuration, stage selections, and derived runtime vocabulary |
|
||||
|
||||
This master roadmap and the three library outlines replace the removed
|
||||
`import-upgrade.md`. They retain its relevant technical evidence but supersede
|
||||
@@ -158,9 +160,11 @@ for Audita's complete release workflow.
|
||||
scope for the next major release.
|
||||
5. **Add stage-specific glossary inputs.** After all four library adoptions,
|
||||
complete the [glossary-stage roadmap](glossary-stages.md). Use the adopted
|
||||
configuration, resource, and CLI conventions to support ordered stages such
|
||||
as `party.yml` followed by `spells.yml` in one processing run. This sequencing
|
||||
avoids designing the feature around interfaces that the upgrades replace.
|
||||
configuration and CLI conventions to compose reusable glossary assets through
|
||||
ConfigKit, then derive Audita's runtime views for ordered stages such as a
|
||||
party pass followed by a spell pass. Remove the standalone glossary parsing
|
||||
path. This sequencing avoids designing the feature around interfaces that
|
||||
the upgrades replace.
|
||||
6. **Validate and document the assembled application.** Complete the offline
|
||||
behavioral checks from the outlines and the full Audita suite. Update canonical
|
||||
configuration, CLI, operations, integration, and internal documentation with
|
||||
|
||||
Reference in New Issue
Block a user