Plan the standalone Audita version 2 upgrade

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.

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)

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
+Status: ready
-before preparing its staged plan.
 
-Feature 0018 is complete and independently reviewed with no remediation
+Target executor: GPT-5.6-Terra
-findings. See [its roadmap](features/0018-scriptorium-v0-15-adoption.md) for
-completion evidence. Git history preserves the completed plan.
 
-Audita standalone adoption is next in the agreed
+Feature roadmap: [0019-audita-v2-adoption.md](features/0019-audita-v2-adoption.md)
-[application upgrade sequence](application-upgrade-sequence.md). Suite and
+
-consumer pins remain unchanged until coordinated integration.
+## 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 <fixture>`, and `audita config print-effective --config <fixture>
+--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.

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 |