From 098401f674ac921ee0adb6f1ec5e03a3b8807a00 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 9 Nov 2026 12:55:46 +0000 Subject: [PATCH] Resolve optional stage IDs and reporting attribution --- docs/roadmap/configkit.md | 6 +-- docs/roadmap/glossary-stages.md | 79 +++++++++++++++++++++------------ 2 files changed, 54 insertions(+), 31 deletions(-) diff --git a/docs/roadmap/configkit.md b/docs/roadmap/configkit.md index 136ff47..2f50294 100644 --- a/docs/roadmap/configkit.md +++ b/docs/roadmap/configkit.md @@ -141,9 +141,9 @@ file remain terminal. [list-input and handoff contract](glossary-stages.md#list-inputs-and-configuration-handoff--resolved): complete configuration resolution through ConfigKit before handoff; runtime consumers treat null selections as empty without restoring defaults. - Complete its required durable decision record. The glossary roadmap owns - the remaining stage-identity and attribution decision. This application scope - model does not change native source composition or sibling-inheritance semantics. + Apply its [optional stage identity and attribution contract](glossary-stages.md#stage-identity-and-attribution--resolved) + and complete its required durable decision record. 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 3d414f7..324d47b 100644 --- a/docs/roadmap/glossary-stages.md +++ b/docs/roadmap/glossary-stages.md @@ -4,8 +4,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, and extensible -entry content fields. Remaining design decisions and implementation are pending. The +placement, optional default sources, collection-scoped entry IDs, extensible +entry content fields, and optional stage IDs. Design decisions are resolved; +implementation remains pending. The [master roadmap](library-adoption.md) owns sequencing and release completion. ## Baseline and Target @@ -30,7 +31,7 @@ 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; stage identity and attribution remain open. +are resolved, as are optional stage identity and attribution. ## Glossary Configuration Ownership — Resolved @@ -396,6 +397,40 @@ 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. +### Stage Identity and Attribution — Resolved + +Support an optional operator-chosen `id` on each stage for reports and diagnostics: + +```yaml +pipeline: + stages: + - id: party-pass + module: glossary + glossaries: [party] + - id: spell-pass + module: glossary + glossaries: [spells] + - module: grammar +``` + +When supplied, an ID must be a nonempty string unique within the pipeline. +Compare IDs exactly and case-sensitively; no slug syntax or generated identifier +is required. Unnamed stages remain valid. Validate supplied IDs through ConfigKit's +supported lifecycle before handoff so runtime consumers receive resolved IDs +without generating or resolving configuration themselves. + +Retain execution position and module identity alongside the optional ID. Reports +and diagnostics use the supplied ID when present and otherwise identify the stage +by position and module. An operator-chosen ID remains meaningful when stages are +reordered; position continues to describe execution order within a run. Preserve +ordered execution and repeated modules. + +Inspection exposes effective glossary and protection selections and their +ConfigKit source origins for both named and unnamed stages. Stage naming does +not replace configuration provenance. These IDs serve reporting and diagnostics; +they do not introduce targeted-stage CLI overrides or change pipeline composition +semantics. + ## Configuration Scope — Resolved Settings governing an individual stage's requests, acceptance, or model-operation @@ -618,7 +653,7 @@ 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 +The resolved stage-identity contract 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. @@ -717,8 +752,9 @@ into feature implementation. 1. Apply named collection selection, default file/directory underlay imports, recursive placement, and the extensible entry content contract. Apply native - CLI list conventions and settle stage identity and attribution below. Preserve - the selected scope, clearing, CLI precedence, and fallback semantics in version 3. + CLI list conventions and the selected stage identity and attribution rules. + 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 @@ -730,7 +766,8 @@ into feature implementation. 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. + in inspection, diagnostics, and reports using optional IDs alongside position + and module identity. 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 @@ -765,6 +802,13 @@ lists, independent empty-list clearing, a glossary stage with no override using 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. +Verify named, unnamed, and mixed pipelines, rejecting empty or non-string supplied +IDs and duplicate IDs through configuration validation. Cover exact case-sensitive +comparison without imposing slug syntax. Verify IDs remain associated with their +stages after reordering while reported positions reflect the new order. Reports +and diagnostics retain module and position, with optional IDs when supplied; +inspection exposes effective selections and source origins for every stage. +Confirm stage IDs do not change pipeline composition or add CLI targeting. Cover default-source loading with only `glossary.yml`, only `glossary/`, both, and neither present. Verify invocation-directory resolution even with a main file elsewhere or no main file, optional absence, and normal errors for invalid present @@ -843,24 +887,3 @@ 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. - -### 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.