# Implementation Plan 0002: Install and Configure Audita

Status: ready

Target executor: GPT-5.6-Terra

Feature roadmap:
[Feature 0002: Audita Source Installation and Configuration](features/0002-audita-source-installation-and-configuration.md)

## 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:

```sh
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:

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

Then confirm the restored installation:

```sh
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`

**Completion:** Complete (`ansible-role-audita` commit `d37f590`).

## Final Validation and Handoff

After Stage 2, run:

```sh
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.