From e0153d938b2745e319d0c2783836e0a1f2ca98e9 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 28 Sep 2026 13:33:47 +0000 Subject: [PATCH] Plan the standalone Audita version 2 upgrade --- docs/roadmap/application-upgrade-sequence.md | 2 +- .../features/0019-audita-v2-adoption.md | 182 +++++++++++++ docs/roadmap/implementation.md | 239 +++++++++++++++++- docs/status.md | 4 +- 4 files changed, 416 insertions(+), 11 deletions(-) create mode 100644 docs/roadmap/features/0019-audita-v2-adoption.md diff --git a/docs/roadmap/application-upgrade-sequence.md b/docs/roadmap/application-upgrade-sequence.md index cc88ba3..45b09db 100644 --- a/docs/roadmap/application-upgrade-sequence.md +++ b/docs/roadmap/application-upgrade-sequence.md @@ -36,7 +36,7 @@ link beside each item when its roadmap is created; check it off after independent review and closeout. - [x] [Feature 0018: Scriptorium adoption](features/0018-scriptorium-v0-15-adoption.md) — complete through role `b174c8c`; independent review found no remediation issues. -- [ ] Audita adoption — feature roadmap not yet created. +- [ ] [Feature 0019: Audita adoption](features/0019-audita-v2-adoption.md) — roadmap and staged plan approved; ready for implementation. - [ ] Notarius adoption — feature roadmap not yet created. - [ ] Narratio adoption — feature roadmap not yet created. - [ ] Suite integration — feature roadmap not yet created. diff --git a/docs/roadmap/features/0019-audita-v2-adoption.md b/docs/roadmap/features/0019-audita-v2-adoption.md new file mode 100644 index 0000000..e462dfe --- /dev/null +++ b/docs/roadmap/features/0019-audita-v2-adoption.md @@ -0,0 +1,182 @@ +# Feature 0019: Adopt Audita v2.0.1 in the Standalone Role + +Status: ready + +## Summary + +Replace the standalone Audita role's version-1 configuration interface with +Audita v2.0.1's native interface. Keep provider and D&D policy outside the +generic role. This is the second feature in the agreed +[application upgrade sequence](../application-upgrade-sequence.md). + +## Problem or Opportunity + +The role currently installs Audita v0.9.1 and renders version-1 configuration. +Audita v2 requires version-2 YAML, named backends, and selected PromptKit +profiles. Old per-role endpoint/model/credential/concurrency settings no longer +apply. A version-only update would produce an unusable deployment. + +Unlike the previous minimal configuration, a valid v2 configuration requires +at least one backend and a proposal profile whose file exists. The generic role +must not invent a provider, endpoint, model, or credential to meet that contract. +The caller-input boundary is settled below. + +## Scope + +- Default to Audita v2.0.1 and configuration version 2. +- Replace retired public configuration variables with native v2 settings. +- Preserve still-supported domain controls and inventory composition. +- Document the breaking role-variable migration and caller prerequisites. +- Adapt offline integration tests to real v2 configuration/profile fixtures. + +## Non-goals + +- Updating pipeline, collection, or consumer application/dependency pins. +- Choosing D&D models, endpoints, credentials, concurrency, or retry budgets. +- Compatibility shims, automatic v1 conversion, or a dual-schema template. +- Live inference, operational deployment, report ingestion, service management, + or runtime configuration validation tasks. +- Imports: Audita deliberately disables ConfigKit imports. Do not add an import + variable merely because other applications expose one. +- Automatically provisioning secret values or selecting runtime overlays. + +## Target End State + +### Installation and Schema + +`audita_version` defaults to `v2.0.1`; `audita_config_version` defaults to `2`. +Retain the existing source checkout, conditional Go build, dependency management, +configuration location, and owner/group/mode interfaces. Go 1.26 remains suitable. +The role renders v2 only; selecting an older application does not translate its +configuration. Operators needing v1 retain the previous role revision. + +### Public Configuration Interface + +Use these field-specific variables; optional settings default to null and are +omitted, allowing Audita to own defaults. Serialize native values and preserve +intentional zero, false, empty strings, and empty collections where supported. + +| Role variable | Native field | Ownership | +| --- | --- | --- | +| `audita_profiles_dir` | `profiles_dir` | Optional caller profile location | +| `audita_backends` | `backends` | Caller-supplied native mapping | +| `audita_llm_proposal_profile` | `llm.proposal_profile` | Caller-selected required profile | +| `audita_llm_validation_profile` | `llm.validation_profile` | Optional; omission inherits proposal | +| `audita_llm_transient_retries` | `llm.transient_retries` | Optional native retry budget | +| `audita_llm_repair_attempts` | `llm.repair_attempts` | Optional native repair budget | +| `audita_llm_operation_timeout` | `llm.operation_timeout` | Optional duration string | +| `audita_validation_max_prompt_tokens` | `validation.max_prompt_tokens` | Optional batching control | +| `audita_reporting_enabled` | `reporting.enabled` | Optional report policy | +| `audita_reporting_stdout_dir` | `reporting.stdout_dir` | Optional report destination | +| `audita_diagnostics_debug` | `diagnostics.debug` | Optional debug policy | + +Retain existing variables for modules, output schema, chunking, normalization, +thresholds, context description, and diagnostics work directory. Normalization +gap/duration fields now represent numeric seconds, not duration strings. +Argument specifications must accept the native integer/fractional values without +turning them into quoted strings in YAML. Do not add a duration-conversion layer. + +Remove the old `audita_llm_{proposal,validation}_{base_url,model,api_key_env,timeout,max_retries}`, +`audita_concurrency_{total_llm,proposal_llm,validation_llm}`, and +`audita_diagnostics_retention` interfaces from defaults, templates, argument +specifications, and current examples. Document their replacements rather than +silently interpreting them under different semantics or adding deprecation probes. + +The backend mapping carries endpoint, credential reference, concurrency, and +queue capacity using Audita's schema. Inventory can compose it with ordinary +Jinja expressions. Credential values stay outside the role; every surviving +backend reference must be available when Audita loads configuration, even when +that backend is not selected. Do not introduce separate per-role secret variables. + +Null role variables mean omission, not literal YAML null. In particular, omit +an unset validation profile so Audita can inherit the proposal selection. +Backend mapping values retain native semantics, including a null credential. + +### Profile and Overlay Ownership + +Callers provide `audita_backends` and `audita_llm_proposal_profile`; neither has +a fabricated concrete default. Callers also deploy the selected profile files +before invoking Audita. `audita_profiles_dir` may be supplied or omitted to use +Audita's conventional sibling `profiles/` directory. Keep profile documents and +ConfigKit `overlays/` content caller-owned in this feature. + +The later suite feature will own its D&D profile assets and coordinate their +deployment with Narratio's new external Audita configuration contract. The role +does not start processing or validate file availability during convergence. + +## Repository Ownership + +- `ansible-role-audita`: generic installation/configuration interface, migration + documentation, and local tests. +- Workspace: roadmap, active plan, progress, and review evidence. +- Audita application: read-only tagged schema, migration, and profile contracts. +- Other applications/roles, assets, pipeline, collection, and consumer: unchanged. + +## Constraints and Settled Decisions + +Follow the [Ansible house style](../../ansible.md), +[testing house style](../../testing.md), [MVP roadmap](../mvp.md), and +[upgrade sequence](../application-upgrade-sequence.md). The suite continues to +use its old compatible role/application set until final integration; Narratio v2 +must not be accidentally paired with Audita v2 through a changed suite pin. + +Old timeouts and retries do not map one-to-one to profile per-attempt timeouts, +logical-operation deadlines, transport retries, and structural repair. Expose +native controls without choosing replacement tuning for the D&D suite here. + +## Simplest Viable Implementation + +Update the version/schema defaults and replace the single configuration template's +retired sections with native v2 sections. Align argument specifications and the +README. Keep ordinary file/template/source/build tasks. Use the existing test +harness with caller-owned local backend/profile fixtures; add no state assembly, +profile resolver, migration command, or production probe. + +## Acceptance Criteria + +- The role installs v2.0.1 and renders native v2 configuration from supplied + backend/profile choices and optional settings. +- Native offline validation and effective-settings/profile inspection accept + representative configuration with an externally supplied profile and local + fixture endpoint; no provider request is needed. +- Tests cover supplied mapping composition, omission/inherited validation + selection, representative numeric seconds, and meaningful zero/false values. + Avoid a comprehensive schema matrix or assertions of current upstream defaults. +- Existing useful build and clean-repeat coverage remains. Immediate repeated + role convergence reports no changes; do not test module postconditions. +- Documentation explains required caller inputs and the breaking variable/schema + migration, linking Audita for full field and report semantics. +- No suite, collection, or consumer pins change. Completion records the reviewed + standalone role revision for the final integration feature. + +## Rationale and Alternatives + +Native backend mappings and named profiles preserve Audita's ownership instead +of reproducing per-role endpoint/model settings in Ansible. A dual-schema role +would add maintenance and ambiguity without a selected requirement; retaining +the previous role revision is the simpler boundary for old deployments. + +## Dependencies and Follow-up Work + +The caller-input decision is approved. The staged implementation plan is at +[implementation.md](../implementation.md). After review and closeout, Notarius adoption is +next. D&D backend/profile assets, tuning migration, testing overlays, credential +lists, and coordinated deployment belong to the later integration feature. + +## Settled Caller-Input Decision + +The user approved required `audita_backends` and `audita_llm_proposal_profile` +inputs through the ordinary role argument interface, with caller-owned profile +files. Do not give these variables null or fabricated defaults. A no-input role +invocation is no longer valid; examples and tests supply explicit choices. +Role-managed profile definitions are not part of this feature. + +## Open Questions + +None. + +## Upstream References + +- [v2.0.1 configuration](https://gitea.maximumdirect.net/eric/audita/src/tag/v2.0.1/docs/config.md) +- [v2 migration guide](https://gitea.maximumdirect.net/eric/audita/src/tag/v2.0.1/docs/migrations/v2.md) +- [v2.0.1 release](https://gitea.maximumdirect.net/eric/audita/src/tag/v2.0.1/docs/releases/v2.0.1.md) diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 261786f..5fb673d 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,12 +1,233 @@ -# Implementation Plan +# Implementation Plan 0019: Standalone Audita v2.0.1 Adoption -No implementation plan is currently active. Agree on the next feature roadmap -before preparing its staged plan. +Status: ready -Feature 0018 is complete and independently reviewed with no remediation -findings. See [its roadmap](features/0018-scriptorium-v0-15-adoption.md) for -completion evidence. Git history preserves the completed plan. +Target executor: GPT-5.6-Terra -Audita standalone adoption is next in the agreed -[application upgrade sequence](application-upgrade-sequence.md). Suite and -consumer pins remain unchanged until coordinated integration. +Feature roadmap: [0019-audita-v2-adoption.md](features/0019-audita-v2-adoption.md) + +## Objective and Scope + +Migrate the standalone Audita role to v2.0.1's native configuration interface. +Require caller-provided backend and proposal-profile choices; keep profile files +caller-owned. The roadmap owns intent and target state. This plan owns execution. + +Change only `ansible-role-audita` and workspace planning records. Applications, +other roles, assets, pipeline, collection, and consumer repositories are read-only. +Do not propagate this breaking upgrade into the old suite. In particular, no +suite application defaults, dependency pins, collection subtrees, or deployment +inventory change in this feature. + +## Execution Rules and Starting State + +- Execute stages in numeric order. Immediately before each stage reread its + listed workspace-relative policies, inspect working trees, and preserve + unrelated changes. Commit validated units with the stated plain-English intent. +- The current role selects v0.9.1 and schema 1. Adopt v2.0.1 and schema 2 together + with the template/interface migration; a version-only intermediate commit is + not a usable role. Consult tagged v2.0.1 contracts and migration documentation. +- Existing Go 1.26 and workspace `.venv/bin` Ansible tools suffice. Missing PATH + entries, operational controller access, or real keys are not blockers. +- Use the existing local-development integration workflow, including sudo where + needed. Do not connect to the operational controller/target or call providers. +- Trust native modules and Audita's configuration ownership. No compatibility + shims, duration conversion, runtime validation, backend/profile discovery, + secret provisioning, or additional schema assertion tasks are needed. +- Keep tests focused on role-supplied behavior and clean repeated convergence. + Do not turn current defaults, module postconditions, or a broad negative schema + matrix into acceptance gates. `ansible-doc` rendering is not a gate. +- No push, release tag, collection build, or deployment is required. Later suite + integration selects reviewed role commits. Record evidence in Progress Notes. + +## Stage 1: Migrate the Role and Establish a Valid v2 Baseline + +### Required Policy Review + +Read `AGENTS.md`, `docs/orientation.md`, `docs/conventions.md`, +`docs/ansible.md`, `docs/testing.md`, and the Feature 0019 roadmap. + +### Owning Repository and Preconditions + +`ansible-role-audita`. Inspect existing defaults, argument specifications, +template, tasks, README, and integration fixtures. Read Audita v2.0.1's +`docs/config.md`, `docs/migrations/v2.md`, and maintained profile examples. + +### Required Changes + +1. Change `audita_version` to v2.0.1 and `audita_config_version` to 2. Keep the + existing installation/build and metadata tasks unchanged. The role supports + the v2 configuration contract only; do not add a template switch for v1. +2. Define `audita_backends` as required `dict` and + `audita_llm_proposal_profile` as required `str` in argument specifications. + Do not define either variable in role defaults, including as null or empty. + Document both required inputs prominently. Ordinary argument validation owns + missing-input diagnostics; Audita owns backend/profile semantic validation. +3. Add nullable optional variables listed in the roadmap. Use `path` for + `audita_profiles_dir`, `str` for validation profile and operation timeout, + `int` for transient retries, repair attempts, and validation prompt-token + budget, `bool` for reporting enabled and debug, and `str` for reporting stdout + directory (allowing native conditional empty-value behavior). +4. Remove all retired per-role LLM endpoint/model/key/timeout/retry variables, + old concurrency fields, and diagnostics retention from defaults, argument + specs, template, and active examples. Keep the supported domain controls. + Use `float` argument types for the three numeric-seconds normalization fields, + retaining null defaults; JSON serialization must emit numbers, not strings. +5. Rewrite the one configuration template for native v2 sections. Always render + schema version, supplied backends, and `llm.proposal_profile`. Conditionally + render optional fields with `is not none`, including profiles_dir, validation + profile, retry/repair/deadline, validation batching, reporting, and diagnostics. + Preserve native nested backend mappings, including null credentials. Do not + merge them or add credentials, concurrency, queues, or defaults on their behalf. +6. Adapt the existing integration harness now so this stage leaves a usable, + validated role. Every converge invocation, including syntax-check and recovery + paths, must receive required backend/proposal inputs. Establish baseline + caller variables in the test playbook or a shared fixture argument set. +7. Use a temporary test configuration path and a sibling `profiles/` directory + under the existing `mktemp` fixture root for all convergence cases. The test + caller supplies the fragment assets, not the role. Use a complete local + profile such as `id: fixture-proposal`, `backend: fixture`, + `model: offline-fixture`, and `timeout_seconds: 30`, with backend endpoint + `http://127.0.0.1:11434/v1` and no credential. Leave validation profile unset + so Audita inherits proposal. Keep temporary files writable/removable by the + test user through the existing owner/group variables where needed. +8. Remove the old cleanup call that reapplies the role with no inputs. Do not + overwrite the host's existing application configuration or leave a managed + system config pointing into deleted fixtures. Remove only the script-owned + temporary tree. The script still builds the local managed binary/source, as + before; document that boundary rather than introducing rollback machinery. +9. Replace the old representative v1 case with a small valid v2 case and adjust + `tests/verify-config.yml` paths/expectations accordingly. Retain existing useful + build-executable and missing-binary recovery coverage with the baseline inputs. + Update README current variables and minimal example so neither advertises an + invalid no-input invocation. Detailed migration prose is finalized in Stage 3. + +### Validation and Completion Criteria + +From `ansible-role-audita` run: + +```sh +tests/integration +git diff --check +``` + +The existing script must include syntax/lint, native `audita config validate +--config `, and `audita config print-effective --config +--view profiles`. Both selected roles resolve the fixture profile offline. +Immediate repeated convergence and existing build/recovery behavior pass. +Keep production tasks free of these verification commands. + +### Commit + +`Migrate the standalone Audita role to version 2 configuration`. + +## Stage 2: Complete Focused Configuration Coverage + +### Required Policy Review + +Read `AGENTS.md`, `docs/orientation.md`, `docs/conventions.md`, +`docs/ansible.md`, `docs/testing.md`, and the Feature 0019 roadmap. + +### Owning Repository and Preconditions + +`ansible-role-audita`. Stage 1 is validated and committed. Inspect existing +coverage and add only missing behavioral cases below; do not duplicate it. + +### Required Changes + +1. The baseline verifies the role omits unset optional fields in rendered YAML, + while native profile inspection demonstrates inherited validation selection. + Do not assert Audita's numeric defaults or the entire effective document. +2. Use one representative caller configuration to exercise a backend mapping + composed through Jinja `combine`, an explicitly selected second profile, + fractional numeric seconds, retry/repair zero, reporting/debug false, empty + context, and an empty modules list. Select valid accompanying values, such as + zero queue capacity with positive backend concurrency. These are test inputs, + not new role defaults. The second profile is another small caller-owned file. +3. Inspect resulting role-authored fields and use native settings/profile views + to confirm valid composition and selection. Parse YAML rather than requiring + a byte-for-byte output snapshot. Keep all provider endpoints local fixtures; + neither inspection nor validation should call them. +4. Require an immediate clean repeat for the representative configuration. Do not + add tests of obvious required-variable assertions, native profile-name rules, + report production, or the behavior of Ansible file/template modules. +5. Ensure the script's success and failure cleanup both remove only its own + fixtures; no no-input role reapplication remains. Do not leave retired config + references in active test cases merely to preserve obsolete coverage. + +### Validation and Completion Criteria + +Run `tests/integration` and `git diff --check` from the role. Tests demonstrate +caller choice, omission, falsey values, numeric units, native v2 validity, and +clean repeat without external inference. Reuse fixtures and verification files +rather than introducing a parallel testing framework. + +### Commit + +`Verify Audita version 2 configuration choices`. + +## Stage 3: Document Migration and Record Review Handoff + +### Required Policy Review + +Read `AGENTS.md`, `docs/orientation.md`, `docs/conventions.md`, +`docs/ansible.md`, `docs/testing.md`, `docs/planning.md`, Feature 0019, and +`docs/roadmap/application-upgrade-sequence.md`. + +### Owning Repositories and Preconditions + +`ansible-role-audita` and workspace. Stages 1-2 are committed and validated. + +### Required Changes + +1. Finish the README migration table: old endpoint/key/concurrency settings move + to the backend mapping; models and per-attempt timeouts belong to caller + profile files; operation deadlines, transient retries, and repairs are native + separate controls; normalization uses numeric seconds; retention is removed; + reporting/debug follow Audita v2. Link tagged upstream documentation for full + behavior rather than duplicating the application's reference. +2. Document that valid caller profiles must exist before invoking Audita, not + necessarily before applying the role. No production probe enforces their + presence. Show an inventory/backend/profile-selection example and a minimal + caller-owned profile, clearly identifying it as caller content. No fake + credential or production-model default belongs in role defaults. +3. Explain explicit credential reference names and that all surviving backend + references must resolve when Audita loads configuration. The role neither + provides secret values nor starts a service. Do not add a secrets directory, + environment discovery, ConfigKit imports, or automatic overlay selection. +4. Update validation documentation for the new fixture configuration path and + local binary/source mutation boundary. Do not claim provider connectivity, + runtime report validation, or compatibility with the unchanged D&D suite. +5. Record role commit IDs and validation results in workspace status and this + plan. Mark Feature 0019 in_progress pending independent review. Update the + sequence entry to awaiting review, leaving its completion box unchecked. + No Notarius feature implementation starts in this plan. +6. Confirm pipeline, collection, consumer, and other application pins remain + unchanged by this feature. Preserve unrelated repository changes. + +### Validation and Completion Criteria + +Run `git diff --check` in the role and workspace. Check affected local links +and examples against v2.0.1 documentation. Reuse Stage 2 results for prose-only +edits; no repeated full integration run is needed unless executable inputs change. + +### Commits + +Role, if needed: `Document the Audita version 2 role migration`. +Workspace: `Record the standalone Audita upgrade for review`. + +## Final Validation and Handoff + +Report role/workspace commits, checks performed, deviations, and actual blockers. +Confirm feature-owned working trees are clean. State that suite pins remain +unchanged and that no operational deployment or paid inference was performed. +Independent review and closeout precede the next adoption feature. + +## Progress Notes + +Roadmap, caller-managed profile decision, and implementation plan approved by +the user. Implementation has not started. + +## Open Questions + +None for the approved standalone scope. D&D assets, tuning, credentials, and +coordinated deployment remain final-integration decisions. diff --git a/docs/status.md b/docs/status.md index 3571401..df94940 100644 --- a/docs/status.md +++ b/docs/status.md @@ -4,7 +4,8 @@ Last updated: 2026-09-28 Current milestone: Operational D&D pipeline deployment -Current focus: Prepare the Audita v2.0.1 standalone adoption roadmap next. +Current focus: Feature 0019's implementation plan is approved and ready for the sprint. The Audita +v2.0.1 roadmap and required caller inputs/caller-owned profile files are approved. Feature 0018 is complete after independent review with no findings. Follow the agreed [application upgrade sequence](roadmap/application-upgrade-sequence.md): Scriptorium → Audita → Notarius → Narratio → suite integration. Retain the @@ -40,6 +41,7 @@ is complete. | F0016 | Prepare the D&D deployment playbook for `pipeline-dnd` | rakestraw-ansible and workspace | done | Consumer `716a80e`, `12b2462`, and `7f8353d` passed independent review with no findings; public dependency installation, target-only host listing, syntax and whitespace checks passed. Follow-up `7f4c90a` pins collection `2a53979` for Narratio v2.1.2; collection build and syntax checks passed | | F0017 | Compose the Notarius testing overlay | Narratio role, pipeline role, collection, consumer, and workspace | done | Published through Narratio `330afe7`, Notarius `a82a83d`, pipeline `c56a942`, collection `ce5b838`, and consumer `0ced48c`; independent review found no remediation issues; validation evidence is in the feature roadmap | | F0018 | Adopt Scriptorium v0.15.0 | Scriptorium role and workspace | done | Role commits `61dcafe`, `2fce529`, and `b174c8c` passed independent review with no findings; feature roadmap records validation; suite pins unchanged | +| F0019 | Adopt Audita v2.0.1 | Audita role and workspace | ready | [Approved roadmap](roadmap/features/0019-audita-v2-adoption.md) and [staged plan](roadmap/implementation.md); caller-owned profiles; suite pins unchanged | | A0001 | Audit completed standalone-role test suites | workspace and standalone roles | done | Findings recorded in `docs/roadmap/test-suite-audit-findings.md` | | R0001 | Simplify completed standalone-role test suites | workspace and standalone roles | done | Role commits `e08c63c`, `d2d0b9d`, and `cfecf37` passed implementation and independent review |