From ac86c77cfe70df8157dbe383906cae8424e10a6c Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 8 Nov 2026 01:42:48 +0000 Subject: [PATCH] Plan stage-specific glossary inputs for the next major release --- docs/roadmap/glossary-stages.md | 66 ++++++++++++++++++++++++++++++++ docs/roadmap/library-adoption.md | 35 +++++++++++------ 2 files changed, 90 insertions(+), 11 deletions(-) create mode 100644 docs/roadmap/glossary-stages.md diff --git a/docs/roadmap/glossary-stages.md b/docs/roadmap/glossary-stages.md new file mode 100644 index 0000000..5d69253 --- /dev/null +++ b/docs/roadmap/glossary-stages.md @@ -0,0 +1,66 @@ +# Stage-Specific Glossary Inputs + +**Updated:** 2026-11-07 + +**Status:** Accepted scope for the next Audita major release. Initial outline; +detailed design and implementation remain 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. + +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 +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. + +## Sequencing and Work Outline + +Implement after ConfigKit, PromptKit, CommandKit, and ReleaseKit adoption, and +before final release validation and preparation. This lets the feature use the +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. +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. + +## Acceptance Direction + +Use distinct party and spell fixtures with controlled model responses to show +that each stage receives the intended glossary, that one stage's input does not +leak into another, and that the second stage sees the first stage's accepted +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. + +## Open Decisions + +Detailed choices are deliberately deferred to the feature-design discussion: + +- 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. + +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. diff --git a/docs/roadmap/library-adoption.md b/docs/roadmap/library-adoption.md index e980aae..c4c251d 100644 --- a/docs/roadmap/library-adoption.md +++ b/docs/roadmap/library-adoption.md @@ -1,9 +1,9 @@ -# Native Library Adoption Roadmap +# Next Major Release Roadmap **Updated:** 2026-11-07 **Status:** Agreed direction with proposed sequencing. Initial outlines only; -no implementation or dependency changes have been made for this adoption. +no implementation or dependency changes have been made for this plan. ## Objective and Document Ownership @@ -12,9 +12,12 @@ 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. + This document owns shared adoption principles, sequencing, dependency selection, and cross-library decisions, including the ReleaseKit adoption work below. The -linked outlines own library-specific outcomes, work, acceptance criteria, and +linked outlines own feature-specific outcomes, work, acceptance criteria, and open decisions: | Outline | Responsibility | @@ -22,10 +25,12 @@ 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 | -These four documents replace the removed `import-upgrade.md`. They retain its -relevant technical evidence but supersede its recommendations to disable the -OpenRouter bundle, defer CommandKit adoption, limit standard inspection, or +This master roadmap and the three library outlines replace the removed +`import-upgrade.md`. They retain its relevant technical evidence but supersede +its recommendations to disable the OpenRouter bundle, defer CommandKit adoption, +limit standard inspection, or preserve Audita's backend ownership restrictions without a domain justification. They do not select unrelated work in [future.md](future.md). @@ -107,6 +112,8 @@ for Audita's complete release workflow. application-only credential rules, finite admission, and preference for standard-library CLI parsing. Update policies with adopted behavior; do not silently treat old integration choices as permanent requirements. + Keep stage-specific glossary inputs in view when choosing configuration and + CLI contracts; detailed feature design and implementation follow adoption. 2. **Prepare toolchain and migration work.** Select Go 1.27 or newer, updating source/build requirements, CI/bootstrap assumptions, release instructions, and toolchain attribution. Upgrade the direct ReleaseKit tool, launcher, and @@ -121,12 +128,17 @@ for Audita's complete release workflow. previously designed operator interface, adapting Audita domain handlers and resolving upstream issues. This is required target scope, not an optional follow-up whose justification is deferred. -5. **Validate and document the assembled application.** Complete the offline +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. +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 implementation; provide maintained examples and hard-cutover guidance. Validate the adopted release workflow without publishing a release. -6. **Prepare the next major release.** Public configuration, inspection, and CLI +7. **Prepare the next major release.** Public configuration, inspection, and CLI changes warrant a major release under [release policy](../policy/release.md). Exact numbering and publication timing remain release-preparation work. Use the adopted ReleaseKit workflow and selected upstream validators; document @@ -179,9 +191,10 @@ provider calls and do not prove migrated Audita behavior or cross-platform execution. Use controlled provider boundaries and proportionate tests under [testing policy](../policy/testing.md); live diagnostics are not release gates. -Completion requires all four adoption targets, resolved decisions, migrated -examples, useful native inspection, the selected domain behavior, a passing -assembled application, and the adopted ReleaseKit workflow. Every retained local +Completion requires all four library adoption targets, stage-specific glossary +inputs, resolved decisions, migrated examples, useful native inspection, the +selected domain behavior, a passing assembled application, and the adopted +ReleaseKit workflow. Every retained local release validator must have a domain-specific justification. Acceptance tests must assert the target contracts; update or remove tests whose sole purpose is preserving superseded behavior. Upstream requests need an explicit disposition