ansible-workspace-dnd/docs/roadmap/implementation.md

Implementation Plan 0002: Install and Configure Audita

Status: ready

Target executor: GPT-5.6-Terra

Feature roadmap: Feature 0002: Audita Source Installation and Configuration

Objective

Implement the small, independently usable rakestraw.audita role defined by Feature 0002. Install Audita from its pinned source release, build its executable on the managed host, and manage its complete versioned configuration mapping using the minimal module-driven Seriatim pattern.

Execution Rules

• Execute Stage 1 and Stage 2 in numeric order.
• Before each stage, confirm its preconditions and the owning repository's working-tree state.
• Modify only ansible-role-audita. Treat this workspace, ../audita, rakestraw-ansible, and every other repository as read-only.
• Preserve unrelated changes. Stop if the role repository is unexpectedly dirty at a stage boundary.
• Follow docs/conventions.md and the Feature 0002 task flow. Trust the idempotence and change detection of APT, Snap, file, git, and copy.
• Put the two rebuild conditions directly on the build task. Do not add an intermediate fact, handler, or handler flush.
• Do not execute Audita from production role tasks. Executable and configuration validation belong only in integration tests.
• Do not add fingerprints, checksums, sidecar state, manual Git cleanup, staged replacement, compiler inspection, configuration preflight, or out-of-band drift detection.
• Use fully qualified collection names and argv for command execution.
• Run each stage's validation before committing. Do not begin Stage 2 if Stage 1 fails.
• Commit each completed stage with its specified plain-English message. Do not push.
• Treat /usr/local/src/audita, /usr/local/bin/audita, and /usr/local/etc/audita/config.yml as disposable role-managed test state.

Starting State and Preconditions

• ansible-role-audita is clean on main at initial commit 793e6d3, tracking origin/main without divergence.
• This plan and the approved Feature 0002 roadmap are committed before out-of-band execution begins.
• The local controller and managed host are Ubuntu 26.04 amd64, with passwordless privilege escalation available.
• Workspace tooling is available in ../.venv/bin from the role repository: Ansible Core 2.21.3 and ansible-lint 26.8.0.
• community.general 13.3.0 and Go Snap channel 1.26/stable are available.
• Upstream tag v0.9.1 resolves to a84941d68168a1ed9ea7423b6477ae8218be73f9 and uses Go 1.24.0.
• The release build uses package gitea.maximumdirect.net/eric/audita/cmd/audita, CGO_ENABLED=0, GOWORK=off, GOTOOLCHAIN=local, -trimpath, and linker flags -s -w -X gitea.maximumdirect.net/eric/audita/internal/buildinfo.Version=<version>.
• Configuration schema version 1 accepts {"version": 1}. The command audita config validate --config <path> emits config is valid for it.
• Buildable commit 46b7356a3b54a2771ce9a617e4fa3e8d13728cac is available for the checkout-change test. Do not use v0.9.0 for that test because it resolves to the same commit as v0.9.1.

Repository Scope

• ansible-role-audita owns all implementation, interface, README, dependency, and repository-local test changes.
• ansible-workspace-dnd owns the roadmap, plan, and aggregate status but remains unchanged during out-of-band implementation.
• ../audita is the authoritative read-only application contract.
• rakestraw-ansible is a read-only style and configuration-policy reference.
• Every other repository in workspace.yml remains unchanged.

Fixed Public Interface

Implement exactly these defaults and matching argument specifications:

Variable	Default
audita_version	v0.9.1
audita_repository_url	https://gitea.maximumdirect.net/eric/audita.git
audita_source_dir	/usr/local/src/audita
audita_binary_path	/usr/local/bin/audita
audita_manage_build_dependencies	true
audita_go_snap_channel	1.26/stable
audita_go_binary	/snap/bin/go
audita_config_path	/usr/local/etc/audita/config.yml
audita_config	{"version": 1}

The build details, ownership, and modes are fixed implementation details. audita_config is the complete document, not an overlay onto hidden defaults.

Stage 1: Implement the Complete Minimal Role

Objective

Create the role contract, concise production task flow, documentation, and baseline test harness that install and configure Audita idempotently.

Preconditions

• The starting revisions and upstream contracts remain unchanged.
• ansible-role-audita has no uncommitted changes.
• The default managed paths contain no data that must be preserved.

Owning Repository

ansible-role-audita

Required Changes

1. Add conventional role structure: defaults, metadata, argument specifications, one task file, collection requirements, and focused local tests. Retain the existing license and declare Ubuntu 26.04 support and Ansible Core 2.18 or newer in Galaxy metadata.
2. Define exactly the nine variables above. Mirror their names and appropriate scalar, boolean, and dictionary types in the argument specification; do not duplicate Audita's configuration schema there.
3. Implement one readable tasks/main.yml with approximately this flow:
   1. assert Ubuntu 26.04 and architecture x86_64 or aarch64;
   2. install Git with ansible.builtin.apt, including cache_valid_time: 3600, when dependency management is enabled;
   3. install the classic Go Snap from audita_go_snap_channel with community.general.snap when dependency management is enabled;
   4. create source, binary, and configuration parent directories as root:root mode 0755 with one ansible.builtin.file loop;
   5. check out audita_version with ansible.builtin.git, force: true, and register its result;
   6. inspect audita_binary_path with ansible.builtin.stat;
   7. build directly to audita_binary_path when the checkout changed or the binary is absent;
   8. converge recursive root:root source ownership and binary root:root mode 0755 with one item-driven ansible.builtin.file loop;
   9. serialize audita_config as YAML at audita_config_path with ansible.builtin.copy, root:root ownership, and mode 0644.
4. Put the rebuild expression directly on the build command. Register only the Git and binary results it needs. Invoke audita_go_binary with argv, the fixed upstream build contract, output path, and source working directory.
5. Use task-level become: true for dependency installation and tasks that manage root-owned state. Do not require play-level privilege escalation.
6. Pin community.general 13.3.0. Do not add handlers or abstractions for the linear task flow.
7. Write a concise README covering the nine-variable interface, supported platform, privilege and fact requirements, dependency opt-out, build and configuration behavior, metadata, rebuild triggers, and test commands.
8. Add a baseline integration driver that installs the pinned collection into a private temporary location, runs syntax checking and production-profile ansible-lint, converges without play-level become, and verifies the selected commit, recursive source ownership, binary metadata and execution, configuration metadata, and exact native validation output config is valid.
9. Require an immediate repeat role application to report changed=0 and failed=0. Keep paths repository-relative and temporary test artifacts out of the repository.

Validation

From ansible-role-audita, run:

tests/integration
git diff --check
git status --short

Expected result: syntax and lint pass; source resolves to a84941d68168a1ed9ea7423b6477ae8218be73f9; the executable runs and is root:root mode 0755; configuration is schema version 1 and root:root mode 0644; native validation reports config is valid; the immediate repeat reports changed=0 and failed=0; only intended Stage 1 changes remain.

Completion Criteria

• Exactly nine defaults and matching argument specifications exist.
• Production flow matches the roadmap without unrequested probes, persisted private state, or production validation commands.
• README, metadata, dependencies, tasks, and baseline tests agree.
• Baseline integration passes and proves default idempotence.
• No repository outside ansible-role-audita changed.

Commit

Commit message: Install and configure Audita

Completion: Complete (ansible-role-audita commit 47f1852).

Stage 2: Add Focused Behavioral Coverage

Objective

Prove the selected rebuild triggers, independent configuration convergence, dependency opt-out, metadata repair, platform guard, and restored default state without expanding production behavior.

Preconditions

• Stage 1 is committed and the role repository is otherwise clean.
• Stage 1 integration passes.
• The default release and alternate buildable commit remain available.

Owning Repository

ansible-role-audita

Required Changes

1. Extend tests/integration using strict shell options, repository-relative paths, a private temporary directory, and cleanup that restores v0.9.1.
2. Retain baseline convergence, verification, and clean repeat, then test:
   • an absent binary causes one rebuild followed by an unchanged run;
   • dependency opt-out with a caller-supplied Go executable causes one build followed by an unchanged run;
   • binary metadata drift is repaired by file without running the build, followed by an unchanged run;
   • changing audita_config updates only configuration state, passes native validation, and reaches an unchanged repeat;
   • selecting 46b7356a3b54a2771ce9a617e4fa3e8d13728cac causes one checkout rebuild followed by an unchanged run;
   • restoring v0.9.1 confirms its commit, causes one rebuild, and reaches a final unchanged repeat;
   • unsupported distribution, Ubuntu release, and architecture facts fail before creating application state at isolated temporary paths.
3. Inspect captured task output only where needed to distinguish a build from metadata or configuration convergence. Fail on hidden task failures or unexpected changes in idempotence runs.
4. Limit test mutation to the three declared managed paths and the driver's private temporary directory.
5. Add no tests for version interrogation, fingerprints, checksums, compiler changes, source dirt, staged failures, malformed host state, production configuration preflight, or other non-goals.
6. Update the README test section to describe the focused suite and its host effects.

Validation

From ansible-role-audita, run:

tests/integration
git diff --check
git status --short

Then confirm the restored installation:

sudo git -C /usr/local/src/audita rev-parse HEAD
sudo stat -c '%U:%G %a' /usr/local/bin/audita
sudo stat -c '%U:%G %a' /usr/local/etc/audita/config.yml
/usr/local/bin/audita config validate --config /usr/local/etc/audita/config.yml

Expected result: the focused suite and negative cases pass; the final repeat reports changed=0 and failed=0; source is restored to a84941d68168a1ed9ea7423b6477ae8218be73f9; metadata is root:root 755 for the binary and root:root 644 for configuration; validation reports config is valid.

Completion Criteria

• Every Feature 0002 acceptance criterion has direct static or test evidence.
• Coverage remains limited to the selected operational contract.
• Configuration-only convergence demonstrably does not rebuild Audita.
• README, interface, tasks, and tests agree.
• Default local state is restored and idempotent.
• No repository outside ansible-role-audita changed.

Commit

Commit message: Add focused Audita integration coverage

Final Validation and Handoff

After Stage 2, run:

tests/integration
git log --oneline -2
git status --short --branch
cd ..
./scripts/status

Report the two commit hashes, final integration and repeat results, restored source commit, file metadata, native configuration-validation result, any deviation or remaining concern, and any complexity beyond this task flow with the acceptance criterion that required it.

Do not edit workspace planning files, mark Feature 0002 done, or push during out-of-band execution. Completion requires subsequent review.

Progress Notes

• Plan approved and ready for out-of-band execution on 2026-09-08.