diff --git a/docs/roadmap/configkit.md b/docs/roadmap/configkit.md index ff47a22..b8c0ca6 100644 --- a/docs/roadmap/configkit.md +++ b/docs/roadmap/configkit.md @@ -1,6 +1,6 @@ # ConfigKit Adoption Outline -**Updated:** 2026-11-08 +**Updated:** 2026-11-09 **Status:** Initial outline. The [master roadmap](library-adoption.md) owns the agreed adoption policy, reviewed versions, shared sequencing, and completion. @@ -135,10 +135,11 @@ file remain terminal. Supply its [optional default glossary sources](glossary-stages.md#default-sources-and-explicit-configuration--resolved) in one underlay, with higher-priority explicit main configuration. Register its [collection-scoped entry IDs](glossary-stages.md#entry-identity--resolved) - through native sequence identity registration. + through native sequence identity registration. Apply its + [extensible entry content contract](glossary-stages.md#entry-content-fields--resolved) + using native typed fields and inline extension data. Complete its required durable decision record. The glossary roadmap owns - the remaining rich-field, runtime-view, - selection-input, and attribution decisions. This + the remaining runtime-view, selection-input, and attribution decisions. This application scope model does not change native source composition or sibling-inheritance semantics. diff --git a/docs/roadmap/glossary-stages.md b/docs/roadmap/glossary-stages.md index a752bcb..5d1b2ee 100644 --- a/docs/roadmap/glossary-stages.md +++ b/docs/roadmap/glossary-stages.md @@ -1,11 +1,11 @@ # Stage-Specific Glossary Inputs -**Updated:** 2026-11-08 +**Updated:** 2026-11-09 **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, and collection-scoped entry IDs. Rich fields, -remaining design decisions, and implementation are pending. The +placement, optional default sources, collection-scoped entry IDs, and extensible +entry content fields. Remaining design decisions and implementation are pending. The [master roadmap](library-adoption.md) owns sequencing and release completion. ## Baseline and Target @@ -27,8 +27,8 @@ 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. Collection placement and named selection are selected; -default import sources, their tier, and entry identity are also selected. Rich -fields, runtime ambiguity, and remaining selection details are open below. +default import sources, their tier, entry identity, and content fields are also +selected. Runtime ambiguity and remaining selection details are open below. ## Glossary Configuration Ownership — Resolved @@ -90,11 +90,14 @@ party: - id: merrin name: Merrin category: character - summary: The party's wizard. + description: The party's wizard. + player: Alex + class: wizard + level: 5 ``` -The `party`/`entries` nesting and explicit `id` are selected. The rich fields in -this illustration remain provisional pending the content-field decision below. +The entry follows the [selected content contract](#entry-content-fields--resolved). +Its additional campaign fields remain available for other consumers. Keep collection identity in document keys. ConfigKit does not infer keys from filenames or subdirectories; all matches of the declaration receive the same @@ -138,6 +141,43 @@ whole matching record. Do not treat an identified list as a mapping that merges individual fields of matching records. The selected ordinary stage-selection lists remain separate from these definition collections. +### Entry Content Fields — Resolved + +Require `id`, `name`, and `category` as nonempty strings. The collection-scoped +identity contract above governs `id`; `name` is the canonical term, and `category` +is free-form text rather than an Audita-defined enumeration. + +Support these optional fields: + +| Field | Contract | +| --- | --- | +| `description` | String providing contextual guidance; omission or an empty string requires no filler text. | +| `aliases` | List of nonempty strings representing alternate names or spellings. | +| `plural` | Nonempty string when supplied, providing an explicit plural form. | + +Allow and preserve additional ordinary entry fields, including nested mappings, +lists, and scalar values. A campaign's party roster can therefore also carry +player names, classes, levels, affiliations, or data for other applications. +Preservation applies to the effective result of native composition; it does not +change whole-record replacement semantics. + +Use typed Go fields for the Audita contract and ConfigKit's native inline +string-keyed map of dynamic values for unmatched fields. Its +[schema binding rules](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/config.md#advanced-type-and-field-rules) +cover decoding and inspection without a custom decoder. Keep additional data in +the resolved Go configuration and native inspection. ConfigKit still owns its +reserved syntax and supported value shapes; extensibility does not mean +accepting arbitrary YAML. Audita validates its known fields without imposing +campaign-specific rules on additional fields. A misspelled optional field may +therefore be retained as additional data; do not add a separate typo-detection +mechanism. + +Build the rich LLM projection deliberately from Audita's known glossary fields, +including `description` when present. Do not automatically forward additional +fields to the LLM. Derive protected vocabulary from names, aliases, and plurals; +unrelated metadata does not contribute vocabulary. These consumer projections +leave the complete resolved entry intact. + ### Default Sources and Explicit Configuration — Resolved Audita supplies one glossary underlay with two optional native imports: @@ -280,7 +320,7 @@ 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. | +| Glossary module LLM | Rich entries projected from known glossary fields, including names, categories, descriptions, aliases, and plurals when present. | | 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. | @@ -292,7 +332,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. Detailed handling -of ambiguous identities and rich-entry payloads remains open below. +of ambiguous identities, repeated membership, and rich-entry ordering remains +open below. ## Root Defaults and Stage Overrides — Resolved @@ -608,9 +649,9 @@ requirement visible during library design without expanding those migrations into feature implementation. 1. Apply named collection selection, default file/directory underlay imports, - and recursive placement. Settle entry schema, CLI selection syntax, and remaining - domain decisions below. Preserve the selected scope, clearing, CLI precedence, - and fallback semantics in version 3. + recursive placement, and the extensible entry content contract. Settle CLI + 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 @@ -677,6 +718,11 @@ Allow the same ID in different collections and the same displayed name on distin records. Verify that changing a term or description while retaining its ID targets the same collection record, and that runtime spelling deduplication does not collapse distinct configuration identities. Cover exact case-sensitive ID matching. +Verify required name/category validation and the optional description, aliases, +and plural contracts, including invalid types and empty values where prohibited. +Cover additional scalar, nested mapping, and list fields surviving native loading +and inspection; extension data must not mask invalid known fields. Verify that +unrelated extra fields affect neither the LLM projection nor protected vocabulary. 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. @@ -721,23 +767,6 @@ guidance are in place before declaring this feature complete. The recommendations below are proposals, not selected contracts. -### Entry Content Fields - -**Recommendation:** retain `name`, `category`, `summary`, `aliases`, and `plural` -as the rich entry fields, with required name/category and optional descriptive -summary, aliases, and explicit plural. This keeps descriptive context available -without requiring filler text for obvious terms. Confirm field validation and -how each consumer uses optional values; the optional-summary contract would be -a deliberate change from the current glossary format. Identity is already -settled independently through `id`. - -**Alternative:** rename the descriptive field to `comment` (or another selected -name) and revise requiredness as part of the major-release schema. This can align -the field with optional operator guidance rather than a formal definition, but -requires agreeing on its meaning and updating all authoring examples. Avoid -parallel interchangeable fields or an unnecessary legacy alias; compatibility -with the old format is not a constraint on the choice. - ### Runtime Vocabulary and Identity Ambiguity **Recommendation:** deduplicate recognized spellings for protection using the