eric/ansible-workspace-dnd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Prepare the Audita implementation sprint

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-08 03:34:03 +00:00
parent da799198b2
commit c297f56b7e
4 changed files with 422 additions and 237 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/roadmap/features/0001-seriatim-source-installation.md
View File

@@ -1,6 +1,6 @@
# Feature 0001: Seriatim Source Installation # Feature 0001: Seriatim Source Installation
Status: in_progress Status: done
## Summary ## Summary

266
docs/roadmap/features/0002-audita-source-installation-and-configuration.md
View File

@@ -1,35 +1,247 @@
# Feature 0002: Audita Source Installation and Configuration # Feature 0002: Audita Source Installation and Configuration
Status: proposed Status: ready
## Planning Note ## Summary
Audita remains the likely next application role, but its previously drafted Provide a small, independently usable `rakestraw.audita` role that installs
roadmap and implementation plan were withdrawn before implementation. They Audita from a pinned Git tag, builds its executable on the managed host, and
depended on the original Seriatim fingerprint, sidecar-state, staged-build, manages its versioned YAML configuration. Follow the module-driven Seriatim
and corruption-recovery architecture, which is no longer an approved pattern. pattern while adding only the configuration behavior that distinguishes
Audita.
Do not implement this feature from the withdrawn plan. After the simplified ## Problem or Opportunity
Seriatim role has been implemented and reviewed, discuss Audita again and
write a fresh feature roadmap using the workspace's minimal, module-driven
conventions.
## Preserved Upstream Research The `ansible-role-audita` repository currently contains only its initial
placeholder files. Audita needs a standalone installer before the suite role
can compose the transcript-processing pipeline and supply D&D-specific runtime
policy.
- The latest selected immutable release was `v0.9.1`, resolving to commit An earlier implementation direction depended on the superseded Seriatim
`a84941d68168a1ed9ea7423b6477ae8218be73f9` when inspected. fingerprint, sidecar-state, staged-build, and corruption-recovery architecture.
- The tag declares Go 1.24.0 and builds the package This roadmap replaces that direction with a concise implementation that trusts
`gitea.maximumdirect.net/eric/audita/cmd/audita` with `CGO_ENABLED=0`, Ansible modules, rebuilds only for required conditions, and keeps production
`GOWORK=off`, `GOTOOLCHAIN=local`, `-trimpath`, and the documented release role tasks separate from integration verification.
linker flags.
- The release does not expose a CLI version command suitable for Seriatim's
version-based rebuild check. The simplest appropriate rebuild signal must be
decided during renewed roadmap discussion.
- Audita configuration schema version is `1`. Its native validator accepts
`audita config validate --config <path>` and reports `config is valid` for a
valid file.
- Default configuration discovery prefers
`/usr/local/etc/audita/config.yml` over `/etc/audita/config.yml`.
These facts should be revalidated against the authoritative `../audita` ## Scope
repository before a new roadmap is approved.
- Implement `ansible-role-audita` as a conventional standalone role.
- Support Ubuntu 26.04 on native `amd64` and `arm64` hosts.
- Install Git and the official Go Snap with classic confinement when build
dependency management is enabled.
- Default the Go Snap channel to `1.26/stable`.
- Check out immutable Audita tag `v0.9.1` by default under the root-owned path
`/usr/local/src/audita`.
- Build Audita with its upstream release build contract and install the native
executable at `/usr/local/bin/audita`.
- Rebuild when the Git checkout changes or the binary is absent.
- Converge the installed binary to `root:root` ownership and mode `0755`.
- Manage a versioned Audita YAML configuration at
`/usr/local/etc/audita/config.yml`, owned by `root:root` with mode `0644`.
- Default the managed configuration to the minimal valid mapping
`{"version": 1}`, allowing Audita's own defaults to govern application
behavior.
- Keep role defaults, argument specifications, README, metadata, dependency
declaration, and focused local tests consistent with this contract.
## Non-goals
- D&D-specific model selection, concurrency, thresholds, transcript context,
or other suite policy. The suite-level role will provide those overrides.
- A separate Ansible variable for every field in Audita's configuration
schema.
- API keys, secret values, environment files, or another secret-delivery
mechanism. Configuration may name environment variables but must not contain
their secret values.
- Creation or management of the `narratio` account, operator groups, campaign
data, glossaries, transcript data, or diagnostics directories.
- Installation or configuration of another pipeline application.
- Services, scheduling, removal behavior, or pipeline composition.
- Prebuilt release artifacts or cross-compilation.
- Production execution of Audita to validate the build or configuration.
- Detection of out-of-band binary modification, compiler changes, or fixed
build-command changes.
- Build fingerprints, checksums, sidecar state, staged replacement, manual Git
cleanup, or special recovery for malformed or adversarial host state.
- A shared build helper role or dedicated platform-matrix infrastructure.
## Target End State
On an Ubuntu 26.04 `amd64` or `arm64` host, applying the role with defaults
installs or confirms Git and Go, checks out Audita `v0.9.1` at
`/usr/local/src/audita`, builds `/usr/local/bin/audita`, and writes
`/usr/local/etc/audita/config.yml`. Source and installed files have the stated
root ownership and permissions, and the configuration contains `version: 1`.
An immediate second application reports no changes. A changed Git checkout or
missing binary causes one build; configuration changes converge through the
ordinary file-management module without rebuilding Audita. Repository-local
tests execute the installed CLI to verify the build and validate the managed
configuration.
## Repository Ownership
- `ansible-role-audita` owns the role implementation, public interface,
configuration rendering, metadata, dependency declaration, README, and
repository-local validation.
- `../audita` is the read-only authority for the build, CLI, and configuration
contracts.
- `rakestraw-ansible` is a read-only style and configuration-policy reference.
- `ansible-role-dnd-pipeline` will later own the D&D-specific values supplied
through the standalone role's configuration interface.
- `ansible-workspace-dnd` owns this roadmap, the eventual staged implementation
plan, and aggregate status.
- All other repositories remain unchanged.
## Constraints and Settled Decisions
- The selected release is tag `v0.9.1`, which resolves to commit
`a84941d68168a1ed9ea7423b6477ae8218be73f9`.
- Tags `v0.9.0` and `v0.9.1` resolve to the same commit, so `v0.9.0` cannot
exercise checkout-change rebuilding. Focused integration may temporarily
select buildable commit `46b7356a3b54a2771ce9a617e4fa3e8d13728cac`
before restoring the default tag.
- The tag declares Go 1.24.0. The suite-standard Go Snap channel remains
`1.26/stable`.
- The upstream 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>`.
- Audita exposes no release-version command needed by production convergence.
The role uses only checkout change and binary absence as build triggers.
- Audita configuration schema version `1` is strict. The native command
`audita config validate --config <path>` reports `config is valid` for a
valid file and is used only by tests.
- Audita's default configuration search order prefers
`/usr/local/etc/audita/config.yml` over `/etc/audita/config.yml`; the role
manages the preferred path.
- Configuration is exposed as one mapping rather than many field-specific
variables. This preserves Audita's schema and gives the suite role one clear
override boundary.
- Configuration contains no secrets by default. Consumers use Audita's
`api_key_env` fields and arrange secret environment variables outside this
feature.
- Tasks that install dependencies or manage root-owned application state use
task-level `become: true`.
- `community.general` is an approved dependency and supplies Snap management;
pin version `13.3.0` in the role's collection requirements.
## Fixed Public Interface
| Variable | Default | Purpose |
| --- | --- | --- |
| `audita_version` | `v0.9.1` | Git revision and release value supplied to the build |
| `audita_repository_url` | `https://gitea.maximumdirect.net/eric/audita.git` | Source repository |
| `audita_source_dir` | `/usr/local/src/audita` | Managed source checkout |
| `audita_binary_path` | `/usr/local/bin/audita` | Installed executable |
| `audita_manage_build_dependencies` | `true` | Whether to install Git and Go |
| `audita_go_snap_channel` | `1.26/stable` | Go Snap channel |
| `audita_go_binary` | `/snap/bin/go` | Go executable used for the build |
| `audita_config_path` | `/usr/local/etc/audita/config.yml` | Managed configuration file |
| `audita_config` | `{"version": 1}` | Complete versioned configuration mapping |
The package, build flags, linker symbol, environment values, file ownership,
and file modes are fixed implementation details. The selected version is both
the Git revision and the value supplied to the upstream linker flag.
## Simplest Viable Implementation
The expected implementation is approximately nine ordinary tasks in one
readable task file:
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 the source, binary, and configuration parent directories with one
`ansible.builtin.file` loop.
5. Check out `audita_version` with `ansible.builtin.git`, `force: true`, and
register the module result.
6. Inspect whether `audita_binary_path` exists with `ansible.builtin.stat`.
7. Run the upstream Go build through `audita_go_binary` when the checkout
changed or the binary is absent.
8. Converge recursive source ownership and binary ownership and mode with one
item-driven `ansible.builtin.file` loop.
9. Serialize `audita_config` as YAML and manage `audita_config_path` with
`ansible.builtin.copy`.
Apply task-level privilege escalation only to tasks that require it. Use
`argv` for the build command, and put its two conditions directly on the build
task. Do not add a rebuild fact, handler, handler flush, executable discovery,
compiler interrogation, configuration preflight, or post-operation validation
to production tasks.
## Rationale and Alternatives
Audita's installation mechanics are intentionally the same as Seriatim's:
declarative dependency and checkout management surrounding one imperative
build command. The binary existence probe is justified because Ansible cannot
infer whether that command's output exists; no other build-state model is
needed.
A single configuration mapping is smaller and more durable than duplicating
Audita's evolving schema as dozens of role variables. A minimal default mapping
produces a valid configuration while preserving upstream defaults. The future
suite role can supply its complete D&D-specific mapping without coupling the
standalone role to one deployment.
Managing the preferred `/usr/local/etc` path follows the application's own
discovery order and keeps locally installed software and its configuration
together. `/etc/audita/config.yml` remains an unmanaged application fallback.
## Acceptance Criteria
- Unsupported distributions, Ubuntu releases, and architectures fail before
application state is modified.
- Default execution on the local Ubuntu 26.04 host installs or confirms Git
and Go and checks out Audita tag `v0.9.1` at commit
`a84941d68168a1ed9ea7423b6477ae8218be73f9`.
- The role builds with the fixed upstream contract and installs
`/usr/local/bin/audita` as `root:root` mode `0755`.
- The managed source checkout is recursively owned by `root:root`.
- The default configuration is a valid schema-version `1` document at
`/usr/local/etc/audita/config.yml`, owned by `root:root` with mode `0644`.
- Repository-local tests successfully execute the installed CLI and receive
`config is valid` when validating the managed configuration.
- An immediate second role run reports no changes.
- A missing binary causes one rebuild followed by an unchanged run.
- A changed checkout causes one rebuild followed by an unchanged run.
- A configuration change updates only configuration state and does not rebuild
the binary.
- Dependency opt-out accepts a caller-supplied `audita_go_binary`.
- A play connecting as an ordinary sudo-capable user can apply the role without
play-level privilege escalation.
- Defaults and argument specifications contain exactly the nine variables in
the Fixed Public Interface.
- The implementation contains no production CLI validation, fingerprints,
checksums, sidecar build state, manual Git reset or clean commands, or probes
before state already managed by APT, Snap, `file`, `git`, or `copy`.
- Syntax checking, production-profile ansible-lint, focused local convergence,
configuration validation, and clean repeated runs pass.
- Role documentation describes the actual behavior, dependency opt-out,
complete configuration mapping, privilege use, and local test effects.
- No repository other than `ansible-role-audita` and the workspace control
repository is modified.
## Dependencies and Follow-up Work
The managed host requires access to the Audita Git repository, Ubuntu Snap
infrastructure, and Go module sources. Runtime processing also requires a
glossary, transcript inputs, LLM endpoints, and secret environment variables;
those are consumers' or later suite-level features, not installation
dependencies.
The approved staged plan is maintained at `docs/roadmap/implementation.md`.
The D&D pipeline role can select concrete `audita_config` values after the
standalone interface is implemented and reviewed.
## Potential Future Hardening
- Build into a temporary path before replacing the installed executable.
- Verify source signatures or release checksums.
- Detect compiler, build-command, or out-of-band binary changes.
- Validate configuration during production convergence.
- Manage a dedicated runtime account, secret environment, diagnostics path,
service, or schedule if later operating requirements select them.
- Add dedicated Ubuntu release and architecture test matrices.

380
docs/roadmap/implementation.md
View File

@@ -1,259 +1,239 @@
# Implementation Plan 0001: Simplify Seriatim Source Installation # Implementation Plan 0002: Install and Configure Audita
Status: done Status: ready
Target executor: GPT-5.6-Terra Target executor: GPT-5.6-Terra
Feature roadmap: Feature roadmap:
[Feature 0001: Seriatim Source Installation](features/0001-seriatim-source-installation.md) [Feature 0002: Audita Source Installation and Configuration](features/0002-audita-source-installation-and-configuration.md)
## Objective ## Objective
Replace the current overengineered `ansible-role-seriatim` implementation with Implement the small, independently usable `rakestraw.audita` role defined by
the concise, module-driven role defined by Feature 0001. Preserve the useful Feature 0002. Install Audita from its pinned source release, build its
role metadata and supported installation outcome while removing persistent executable on the managed host, and manage its complete versioned
build state, duplicated module logic, speculative recovery, and obsolete test configuration mapping using the minimal module-driven Seriatim pattern.
coverage.
## Execution Rules ## Execution Rules
- Execute Stage 1 and Stage 2 in numeric order. - Execute Stage 1 and Stage 2 in numeric order.
- Before each stage, confirm its preconditions and the working-tree state of - Before each stage, confirm its preconditions and the owning repository's
the owning repository. working-tree state.
- Modify only `ansible-role-seriatim`. Treat this workspace plan, - Modify only `ansible-role-audita`. Treat this workspace, `../audita`,
`rakestraw-ansible`, and `../seriatim` as read-only during implementation. `rakestraw-ansible`, and every other repository as read-only.
- Preserve unrelated and pre-existing changes. Stop if the role repository is - Preserve unrelated changes. Stop if the role repository is unexpectedly
not clean at a stage boundary unless its changes are the expected output of dirty at a stage boundary.
the immediately preceding stage. - Follow `docs/conventions.md` and the Feature 0002 task flow. Trust the
- Follow `docs/conventions.md` and the Feature 0001 task flow. Trust the idempotence and change detection of APT, Snap, `file`, `git`, and `copy`.
idempotence and change detection of `apt`, Snap, `file`, and `git`. - Put the two rebuild conditions directly on the build task. Do not add an
- Keep the two rebuild triggers directly on the build task. Do not create an intermediate fact, handler, or handler flush.
intermediate rebuild fact, build handlers, or a handler flush. - Do not execute Audita from production role tasks. Executable and
- Do not run the installed executable from production role tasks. Verify its configuration validation belong only in integration tests.
build output in repository-local integration tests. - Do not add fingerprints, checksums, sidecar state, manual Git cleanup,
- Do not reintroduce fingerprints, checksums, sidecar build state, manual Git staged replacement, compiler inspection, configuration preflight, or
cleanup, staged replacement, compiler inspection, or malformed-path out-of-band drift detection.
recovery.
- Use fully qualified collection names and `argv` for command execution. - Use fully qualified collection names and `argv` for command execution.
- Run each stage's validation before committing it. Do not begin Stage 2 if - Run each stage's validation before committing. Do not begin Stage 2 if Stage
Stage 1 fails validation. 1 fails.
- Commit each completed stage with the plain-English message specified below. - Commit each completed stage with its specified plain-English message. Do not
Do not push. push.
- Treat `/usr/local/src/seriatim` and `/usr/local/bin/seriatim` as disposable - Treat `/usr/local/src/audita`, `/usr/local/bin/audita`, and
role-managed state during local integration. Do not remove the obsolete `/usr/local/etc/audita/config.yml` as disposable role-managed test state.
`/usr/local/src/seriatim.ansible-build-state` directory from the host; the
revised role simply stops managing it.
## Starting State and Preconditions ## Starting State and Preconditions
- `ansible-role-seriatim` is clean on `main` at commit `6fb1aa2` and is ten - `ansible-role-audita` is clean on `main` at initial commit `793e6d3`, tracking
commits ahead of its current `origin/main`. `origin/main` without divergence.
- The workspace plan and revised feature roadmap are reviewed and committed - This plan and the approved Feature 0002 roadmap are committed before
before out-of-band execution begins. out-of-band execution begins.
- The local controller and managed host are Ubuntu 26.04 `amd64`, with - The local controller and managed host are Ubuntu 26.04 `amd64`, with
passwordless privilege escalation available for the approved integration passwordless privilege escalation available.
test.
- Workspace tooling is available in `../.venv/bin` from the role repository: - Workspace tooling is available in `../.venv/bin` from the role repository:
Ansible Core 2.21.3 and ansible-lint 26.8.0. Ansible Core 2.21.3 and ansible-lint 26.8.0.
- `community.general` 13.3.0 remains pinned in - `community.general` 13.3.0 and Go Snap channel `1.26/stable` are available.
`collections/requirements.yml`, and the Go Snap channel `1.26/stable` is - Upstream tag `v0.9.1` resolves to
available. `a84941d68168a1ed9ea7423b6477ae8218be73f9` and uses Go 1.24.0.
- Upstream tag `v1.5.0` resolves to commit - The release build uses package
`0fc92f364316c874d366b00cdc884a33e1900b25`. `gitea.maximumdirect.net/eric/audita/cmd/audita`, `CGO_ENABLED=0`,
- The upstream `v1.5.0` contract remains: `GOWORK=off`, `GOTOOLCHAIN=local`, `-trimpath`, and linker flags `-s -w -X
- Go module requirement 1.25; gitea.maximumdirect.net/eric/audita/internal/buildinfo.Version=<version>`.
- build package `./cmd/seriatim`; - Configuration schema version 1 accepts `{"version": 1}`. The command
- `CGO_ENABLED=0`, `GOWORK=off`, `GOTOOLCHAIN=local`, and `-trimpath`; `audita config validate --config <path>` emits `config is valid` for it.
- linker flags `-s -w -X - Buildable commit `46b7356a3b54a2771ce9a617e4fa3e8d13728cac` is available for the
gitea.maximumdirect.net/eric/seriatim/internal/buildinfo.Version=<version>`; checkout-change test. Do not use `v0.9.0` for that test because it resolves
- `seriatim --version` output `seriatim version <version>`. to the same commit as `v0.9.1`.
- Upstream tag `v1.4.0` resolves to
`9202ccddb962ab499f0772d3c01efdf2ff703077` and supports the same build and
version contracts for the selected-version integration case.
## Repository Scope ## Repository Scope
- `ansible-role-seriatim` owns every implementation, interface, README, and - `ansible-role-audita` owns all implementation, interface, README,
repository-local test change in this plan. dependency, and repository-local test changes.
- `ansible-workspace-dnd` owns the roadmap, this plan, and aggregate status but - `ansible-workspace-dnd` owns the roadmap, plan, and aggregate status but
remains unchanged during out-of-band implementation. remains unchanged during out-of-band implementation.
- `../seriatim` is the authoritative read-only application contract. - `../audita` is the authoritative read-only application contract.
- `rakestraw-ansible` is a read-only style reference. - `rakestraw-ansible` is a read-only style and configuration-policy reference.
- Every other repository in `workspace.yml` remains unchanged. - Every other repository in `workspace.yml` remains unchanged.
## Fixed Public Interface ## Fixed Public Interface
Retain exactly these public defaults: Implement exactly these defaults and matching argument specifications:
| Variable | Default | Purpose | | Variable | Default |
| --- | --- | --- | | --- | --- |
| `seriatim_version` | `v1.5.0` | Git revision and version injected into the executable | | `audita_version` | `v0.9.1` |
| `seriatim_repository_url` | `https://gitea.maximumdirect.net/eric/seriatim.git` | Source repository | | `audita_repository_url` | `https://gitea.maximumdirect.net/eric/audita.git` |
| `seriatim_source_dir` | `/usr/local/src/seriatim` | Managed source checkout | | `audita_source_dir` | `/usr/local/src/audita` |
| `seriatim_binary_path` | `/usr/local/bin/seriatim` | Installed executable | | `audita_binary_path` | `/usr/local/bin/audita` |
| `seriatim_manage_build_dependencies` | `true` | Whether to install Git and Go | | `audita_manage_build_dependencies` | `true` |
| `seriatim_go_snap_channel` | `1.26/stable` | Go Snap channel | | `audita_go_snap_channel` | `1.26/stable` |
| `seriatim_go_binary` | `/snap/bin/go` | Go executable used for the build | | `audita_go_binary` | `/snap/bin/go` |
| `audita_config_path` | `/usr/local/etc/audita/config.yml` |
| `audita_config` | `{"version": 1}` |
The package, build flags, linker symbol, and build environment are fixed The build details, ownership, and modes are fixed implementation details.
implementation details. The selected version is both the Git ref and the value `audita_config` is the complete document, not an overlay onto hidden defaults.
injected into the binary.
## Stage 1: Replace the Role with the Minimal Implementation ## Stage 1: Implement the Complete Minimal Role
**Completion:** Complete (`ansible-role-seriatim` commit `325a5c7`).
### Objective ### Objective
Replace the existing role contract, task graph, documentation, and baseline Create the role contract, concise production task flow, documentation, and
test harness with one coherent minimal implementation that installs and baseline test harness that install and configure Audita idempotently.
validates the default Seriatim release idempotently.
### Preconditions ### Preconditions
- The starting-state commits and upstream contracts above are unchanged. - The starting revisions and upstream contracts remain unchanged.
- `ansible-role-seriatim` has no uncommitted changes. - `ansible-role-audita` has no uncommitted changes.
- The default managed paths contain no data that must be preserved. - The default managed paths contain no data that must be preserved.
### Owning Repository ### Owning Repository
`ansible-role-seriatim` `ansible-role-audita`
### Required Changes ### Required Changes
1. Reduce `defaults/main.yml` and `meta/argument_specs.yml` to the seven variables 1. Add conventional role structure: defaults, metadata, argument
in the Fixed Public Interface. Retain useful role and Galaxy metadata in specifications, one task file, collection requirements, and focused local
`meta/main.yml`. tests. Retain the existing license and declare Ubuntu 26.04 support and
2. Replace the imported task structure with one readable `tasks/main.yml` and Ansible Core 2.18 or newer in Galaxy metadata.
remove the obsolete task files. Implement approximately this task flow: 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`; 1. assert Ubuntu 26.04 and architecture `x86_64` or `aarch64`;
2. install Git with `ansible.builtin.apt` when dependency management is 2. install Git with `ansible.builtin.apt`, including
enabled; `cache_valid_time: 3600`, when dependency management is enabled;
3. install the classic Go Snap from `seriatim_go_snap_channel` with 3. install the classic Go Snap from `audita_go_snap_channel` with
`community.general.snap` when dependency management is enabled; `community.general.snap` when dependency management is enabled;
4. create the source and binary parent directories as `root:root` mode 4. create source, binary, and configuration parent directories as
`0755` with one `ansible.builtin.file` loop; `root:root` mode `0755` with one `ansible.builtin.file` loop;
5. check out `seriatim_version` with `ansible.builtin.git`, using 5. check out `audita_version` with `ansible.builtin.git`, `force: true`, and
`seriatim_repository_url`, `seriatim_source_dir`, and `force: true`, and register its result;
register the module result; 6. inspect `audita_binary_path` with `ansible.builtin.stat`;
6. inspect `seriatim_binary_path` with `ansible.builtin.stat`; 7. build directly to `audita_binary_path` when the checkout changed or the
7. build directly to `seriatim_binary_path` when the Git task changed or the
binary is absent; binary is absent;
8. converge recursive `root:root` source ownership and binary 8. converge recursive `root:root` source ownership and binary `root:root`
`root:root` mode `0755` with one item-driven `ansible.builtin.file` loop; mode `0755` with one item-driven `ansible.builtin.file` loop;
3. Put the rebuild expression directly on the build command. Register the 9. serialize `audita_config` as YAML at `audita_config_path` with
Git and binary inspection results needed by its two conditions without `ansible.builtin.copy`, `root:root` ownership, and mode `0644`.
creating an intermediate rebuild fact. 4. Put the rebuild expression directly on the build command. Register only the
4. Invoke `seriatim_go_binary` with `argv`, the fixed package, flags, linker Git and binary results it needs. Invoke `audita_go_binary` with `argv`, the
value, output path, working directory, and environment from the upstream fixed upstream build contract, output path, and source working directory.
contract. Do not turn the remaining fixed values into defaults or facts. 5. Use task-level `become: true` for dependency installation and tasks that
Apply task-level privilege escalation to dependency installation and tasks manage root-owned state. Do not require play-level privilege escalation.
that manage root-owned application state. 6. Pin `community.general` 13.3.0. Do not add handlers or abstractions for the
5. Remove all code for Git executable discovery, Go executable and compiler linear task flow.
validation, manual Git status/reset/clean, resolved-commit facts, temporary 7. Write a concise README covering the nine-variable interface, supported
build directories, build inputs, fingerprints, checksums, sidecar state, platform, privilege and fact requirements, dependency opt-out, build and
special path-object recovery, and transactional installation. configuration behavior, metadata, rebuild triggers, and test commands.
6. Do not add `handlers/main.yml`; the build and permission tasks execute in 8. Add a baseline integration driver that installs the pinned collection into
normal order. a private temporary location, runs syntax checking and production-profile
7. Rewrite the README to document the seven-variable interface, privilege and ansible-lint, converges without play-level `become`, and verifies the
fact requirements, dependency opt-out behavior, authoritative Git checkout, selected commit, recursive source ownership, binary metadata and execution,
direct build contract, two rebuild triggers, installed metadata, and configuration metadata, and exact native validation output
validation commands. Remove every claim or example tied to deleted `config is valid`.
variables, state files, staging, compiler invalidation, or failure 9. Require an immediate repeat role application to report `changed=0` and
preservation. `failed=0`. Keep paths repository-relative and temporary test artifacts out
8. Rewrite `tests/verify.yml` to check only the selected commit, recursive of the repository.
source ownership, binary type and metadata, and exact version output.
9. Replace `tests/integration` with a focused baseline driver that installs the
pinned collection locally, runs syntax checking and ansible-lint, converges
the default role, runs `tests/verify.yml`, and requires `changed=0` and
`failed=0` on an immediate repeat. Keep `tests/converge.yml`,
`tests/inventory`, and the compatible platform-guard playbook concise.
### Validation ### Validation
From `ansible-role-seriatim`, run: From `ansible-role-audita`, run:
```sh ```sh
tests/integration tests/integration
! rg -n \
'seriatim_(source_ref|build_version|build_state_dir|go_build_flags|go_ldflags|go_package)|fingerprint|checksum' \
defaults meta tasks tests README.md
git diff --check git diff --check
git status --short git status --short
``` ```
Expected result: static validation passes; the default source resolves to Expected result: syntax and lint pass; source resolves to
`0fc92f364316c874d366b00cdc884a33e1900b25`; the binary reports `a84941d68168a1ed9ea7423b6477ae8218be73f9`; the executable runs and is
`seriatim version v1.5.0` with `root:root` ownership and mode `0755`; the `root:root` mode `0755`; configuration is schema version 1 and `root:root`
immediate repeat reports `changed=0` and `failed=0`; and only intended Stage 1 mode `0644`; native validation reports `config is valid`; the immediate repeat
changes remain before commit. reports `changed=0` and `failed=0`; only intended Stage 1 changes remain.
### Completion Criteria ### Completion Criteria
- The public interface contains exactly seven defaults and matching argument - Exactly nine defaults and matching argument specifications exist.
specifications. - Production flow matches the roadmap without unrequested probes, persisted
- The role's effective task flow matches the roadmap without intermediate private state, or production validation commands.
rebuild state or handlers. - README, metadata, dependencies, tasks, and baseline tests agree.
- No role code or active documentation references the obsolete sidecar state - Baseline integration passes and proves default idempotence.
or removed variables. - No repository outside `ansible-role-audita` changed.
- The baseline integration driver passes and proves default idempotence.
- No repository outside `ansible-role-seriatim` changed.
### Commit ### Commit
Commit message: `Simplify the Seriatim role` Commit message: `Install and configure Audita`
## Stage 2: Add Focused Behavioral Coverage ## Stage 2: Add Focused Behavioral Coverage
**Completion:** Complete (`ansible-role-seriatim` commit `718030e`).
### Objective ### Objective
Extend the baseline test harness only far enough to prove the revised feature's Prove the selected rebuild triggers, independent configuration convergence,
selected rebuild triggers, metadata convergence, platform guard, and final dependency opt-out, metadata repair, platform guard, and restored default
default state. state without expanding production behavior.
### Preconditions ### Preconditions
- Stage 1 is committed and the role repository is otherwise clean. - Stage 1 is committed and the role repository is otherwise clean.
- The Stage 1 baseline integration test passes. - Stage 1 integration passes.
- Upstream tags `v1.4.0` and `v1.5.0` remain available. - The default release and alternate buildable commit remain available.
### Owning Repository ### Owning Repository
`ansible-role-seriatim` `ansible-role-audita`
### Required Changes ### Required Changes
1. Extend `tests/integration` using strict shell options, repository-relative 1. Extend `tests/integration` using strict shell options, repository-relative
paths, a private temporary directory, and cleanup that restores the default paths, a private temporary directory, and cleanup that restores `v0.9.1`.
`v1.5.0` installation when possible. 2. Retain baseline convergence, verification, and clean repeat, then test:
2. Retain the baseline convergence, verification, and clean-repeat cases, then - an absent binary causes one rebuild followed by an unchanged run;
add focused cases for: - dependency opt-out with a caller-supplied Go executable causes one build
- an absent binary causing one rebuild followed by an unchanged run;
- dependency opt-out with a caller-supplied Go executable causing one build
followed by an unchanged run; followed by an unchanged run;
- binary ownership or mode drift being repaired by the ordinary `file` task - binary metadata drift is repaired by `file` without running the build,
without requiring a rebuild, as shown by the captured Ansible task output; followed by an unchanged run;
- selecting `v1.4.0`, confirming its commit and version output, and reaching - changing `audita_config` updates only configuration state, passes native
an unchanged repeat; validation, and reaches an unchanged repeat;
- restoring `v1.5.0`, confirming its commit and version output, and reaching - selecting `46b7356a3b54a2771ce9a617e4fa3e8d13728cac` causes one checkout
a final unchanged repeat; rebuild followed by an unchanged run;
- unsupported distribution, Ubuntu release, and architecture inputs failing - 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. before creating application state at isolated temporary paths.
3. Keep recap checks simple and fail the driver on hidden task failures or 3. Inspect captured task output only where needed to distinguish a build from
unexpected changes during idempotence runs. metadata or configuration convergence. Fail on hidden task failures or
4. Keep test mutation limited to the two declared managed paths and paths below unexpected changes in idempotence runs.
the driver's private temporary directory. 4. Limit test mutation to the three declared managed paths and the driver's
5. Do not add cases for fingerprints, checksums, compiler changes, source-tree private temporary directory.
dirt, staged failure preservation, custom-parent recovery, symbolic links, 5. Add no tests for version interrogation, fingerprints, checksums, compiler
malformed state, or the obsolete build-state directory. changes, source dirt, staged failures, malformed host state, production
6. Update the README test section to describe the actual focused suite and its configuration preflight, or other non-goals.
managed-host effects without advertising superseded behavior. 6. Update the README test section to describe the focused suite and its host
effects.
### Validation ### Validation
From `ansible-role-seriatim`, run: From `ansible-role-audita`, run:
```sh ```sh
tests/integration tests/integration
@@ -261,32 +241,33 @@ git diff --check
git status --short git status --short
``` ```
Then confirm the restored default installation: Then confirm the restored installation:
```sh ```sh
/usr/local/bin/seriatim --version sudo git -C /usr/local/src/audita rev-parse HEAD
sudo git -C /usr/local/src/seriatim rev-parse HEAD sudo stat -c '%U:%G %a' /usr/local/bin/audita
sudo stat -c '%U:%G %a' /usr/local/bin/seriatim 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 complete focused suite passes; all expected negative Expected result: the focused suite and negative cases pass; the final repeat
platform cases are recognized; the final repeat reports `changed=0` and reports `changed=0` and `failed=0`; source is restored to
`failed=0`; the restored executable reports `seriatim version v1.5.0`; the `a84941d68168a1ed9ea7423b6477ae8218be73f9`; metadata is `root:root 755` for
source is at `0fc92f364316c874d366b00cdc884a33e1900b25`; binary metadata is the binary and `root:root 644` for configuration; validation reports
`root:root 755`; and only intended Stage 2 changes remain before commit. `config is valid`.
### Completion Criteria ### Completion Criteria
- Every Feature 0001 acceptance criterion has direct test or static evidence. - Every Feature 0002 acceptance criterion has direct static or test evidence.
- The suite tests only the revised operational contract and contains no - Coverage remains limited to the selected operational contract.
superseded hardening matrix. - Configuration-only convergence demonstrably does not rebuild Audita.
- The README, defaults, argument specifications, task flow, and tests agree. - README, interface, tasks, and tests agree.
- The default local installation is restored and idempotent. - Default local state is restored and idempotent.
- No repository outside `ansible-role-seriatim` changed. - No repository outside `ansible-role-audita` changed.
### Commit ### Commit
Commit message: `Focus Seriatim integration coverage` Commit message: `Add focused Audita integration coverage`
## Final Validation and Handoff ## Final Validation and Handoff
@@ -300,21 +281,14 @@ cd ..
./scripts/status ./scripts/status
``` ```
The implementation handoff must report: 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.
- the Stage 1 and Stage 2 commit hashes in order; Do not edit workspace planning files, mark Feature 0002 `done`, or push during
- the final integration result and clean-repeat recap; out-of-band execution. Completion requires subsequent review.
- the final source commit, version output, ownership, and mode;
- any deviation from this plan or the feature roadmap;
- any remaining implementation concern or potential future hardening item.
Do not edit workspace roadmap or status files, mark Feature 0001 `done`, or
push during out-of-band execution. Completion requires subsequent review.
## Progress Notes ## Progress Notes
- Stage 1 completed in `ansible-role-seriatim` commit `325a5c7`. - Plan approved and ready for out-of-band execution on 2026-09-08.
- Stage 2 completed in `ansible-role-seriatim` commit `718030e`.
- The final manual-review remediation in `docs/roadmap/remediation.md` was
implemented and validated in `ansible-role-seriatim` commit `fb8dc41` on
2026-09-08. Feature acceptance remains a separate review step.

11
docs/status.md
View File

@@ -4,8 +4,7 @@ Last updated: 2026-09-08
Current milestone: MVP standalone application roles Current milestone: MVP standalone application roles
Current focus: Review the completed Feature 0001 Seriatim simplification and Current focus: Execute the staged Feature 0002 Audita implementation plan.
final remediation.
| ID | Deliverable | Owner | State | Evidence or next step | | ID | Deliverable | Owner | State | Evidence or next step |
| --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- |
@@ -14,12 +13,12 @@ final remediation.
| M0-03 | Tracked MVP roadmap | workspace | done | `docs/roadmap/mvp.md` established | | M0-03 | Tracked MVP roadmap | workspace | done | `docs/roadmap/mvp.md` established |
| M0-04 | Aggregate repository status | workspace | done | `scripts/status` created | | M0-04 | Aggregate repository status | workspace | done | `scripts/status` created |
| M0-05 | Suite-level role repository | ansible-role-dnd-pipeline | done | Repository created and added to `workspace.yml` | | M0-05 | Suite-level role repository | ansible-role-dnd-pipeline | done | Repository created and added to `workspace.yml` |
| M1-01 | Remaining MVP design decisions | workspace | ready | Resume after the revised Seriatim pattern is accepted | | M1-01 | Remaining MVP design decisions | workspace | ready | Continue after the Audita role interface stabilizes |
| M1-02 | Standalone application roles | role repositories | in_progress | Accept the remediated Seriatim pattern before continuing | | M1-02 | Standalone application roles | role repositories | in_progress | Implement Audita from the approved staged plan |
| M1-03 | Suite-level pipeline role | ansible-role-dnd-pipeline | proposed | Begin after standalone role interfaces stabilize | | M1-03 | Suite-level pipeline role | ansible-role-dnd-pipeline | proposed | Begin after standalone role interfaces stabilize |
| M1-04 | Collection assembly | ansible-collection-dnd | proposed | Select and implement the pipeline-role incorporation mechanism | | M1-04 | Collection assembly | ansible-collection-dnd | proposed | Select and implement the pipeline-role incorporation mechanism |
| F0001 | Install Seriatim from pinned source | ansible-role-seriatim | in_progress | Remediation implemented in `fb8dc41` and validated; complete final review | | F0001 | Install Seriatim from pinned source | ansible-role-seriatim | done | Implementation, integration coverage, and final remediation completed through `fb8dc41` |
| F0002 | Install and configure Audita | ansible-role-audita | proposed | Replan after the simplified Seriatim role is reviewed | | F0002 | Install and configure Audita | ansible-role-audita | ready | Execute `docs/roadmap/implementation.md` in two ordered stages |
## Updating This File ## Updating This File