ansible-workspace-dnd/docs/roadmap/features/0019-audita-v2-adoption.md

# Feature 0019: Adopt Audita v2.0.1 in the Standalone Role

Status: in_progress

## 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 is recorded at
[implementation.md](../implementation.md) and awaits independent review. 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)