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

Implementation Plan 0001: Simplify Seriatim Source Installation

Status: done

Target executor: GPT-5.6-Terra

Feature roadmap: Feature 0001: Seriatim Source Installation

Objective

Replace the current overengineered ansible-role-seriatim implementation with the concise, module-driven role defined by Feature 0001. Preserve the useful role metadata and supported installation outcome while removing persistent build state, duplicated module logic, speculative recovery, and obsolete test coverage.

Execution Rules

• Execute Stage 1 and Stage 2 in numeric order.
• Before each stage, confirm its preconditions and the working-tree state of the owning repository.
• Modify only ansible-role-seriatim. Treat this workspace plan, rakestraw-ansible, and ../seriatim as read-only during implementation.
• Preserve unrelated and pre-existing changes. Stop if the role repository is not clean at a stage boundary unless its changes are the expected output of the immediately preceding stage.
• Follow docs/conventions.md and the Feature 0001 task flow. Trust the idempotence and change detection of apt, Snap, file, and git.
• Keep the two rebuild triggers directly on the build task. Do not create an intermediate rebuild fact, build handlers, or a handler flush.
• Do not run the installed executable from production role tasks. Verify its build output in repository-local integration tests.
• Do not reintroduce fingerprints, checksums, sidecar build state, manual Git cleanup, staged replacement, compiler inspection, or malformed-path recovery.
• Use fully qualified collection names and argv for command execution.
• Run each stage's validation before committing it. Do not begin Stage 2 if Stage 1 fails validation.
• Commit each completed stage with the plain-English message specified below. Do not push.
• Treat /usr/local/src/seriatim and /usr/local/bin/seriatim as disposable role-managed state during local integration. Do not remove the obsolete /usr/local/src/seriatim.ansible-build-state directory from the host; the revised role simply stops managing it.

Starting State and Preconditions

• ansible-role-seriatim is clean on main at commit 6fb1aa2 and is ten commits ahead of its current origin/main.
• The workspace plan and revised feature roadmap are reviewed and committed before out-of-band execution begins.
• The local controller and managed host are Ubuntu 26.04 amd64, with passwordless privilege escalation available for the approved integration test.
• 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 remains pinned in collections/requirements.yml, and the Go Snap channel 1.26/stable is available.
• Upstream tag v1.5.0 resolves to commit 0fc92f364316c874d366b00cdc884a33e1900b25.
• The upstream v1.5.0 contract remains:
  • Go module requirement 1.25;
  • build package ./cmd/seriatim;
  • CGO_ENABLED=0, GOWORK=off, GOTOOLCHAIN=local, and -trimpath;
  • linker flags -s -w -X gitea.maximumdirect.net/eric/seriatim/internal/buildinfo.Version=<version>;
  • seriatim --version output seriatim version <version>.
• Upstream tag v1.4.0 resolves to 9202ccddb962ab499f0772d3c01efdf2ff703077 and supports the same build and version contracts for the selected-version integration case.

Repository Scope

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

Fixed Public Interface

Retain exactly these public defaults:

Variable	Default	Purpose
seriatim_version	v1.5.0	Git revision and version injected into the executable
seriatim_repository_url	https://gitea.maximumdirect.net/eric/seriatim.git	Source repository
seriatim_source_dir	/usr/local/src/seriatim	Managed source checkout
seriatim_binary_path	/usr/local/bin/seriatim	Installed executable
seriatim_manage_build_dependencies	true	Whether to install Git and Go
seriatim_go_snap_channel	1.26/stable	Go Snap channel
seriatim_go_binary	/snap/bin/go	Go executable used for the build

The package, build flags, linker symbol, and build environment are fixed implementation details. The selected version is both the Git ref and the value injected into the binary.

Stage 1: Replace the Role with the Minimal Implementation

Completion: Complete (ansible-role-seriatim commit 325a5c7).

Objective

Replace the existing role contract, task graph, documentation, and baseline test harness with one coherent minimal implementation that installs and validates the default Seriatim release idempotently.

Preconditions

• The starting-state commits and upstream contracts above are unchanged.
• ansible-role-seriatim has no uncommitted changes.
• The default managed paths contain no data that must be preserved.

Owning Repository

ansible-role-seriatim

Required Changes

1. Reduce defaults/main.yml and meta/argument_specs.yml to the seven variables in the Fixed Public Interface. Retain useful role and Galaxy metadata in meta/main.yml.
2. Replace the imported task structure with one readable tasks/main.yml and remove the obsolete task files. Implement approximately this task flow:
   1. assert Ubuntu 26.04 and architecture x86_64 or aarch64;
   2. install Git with ansible.builtin.apt when dependency management is enabled;
   3. install the classic Go Snap from seriatim_go_snap_channel with community.general.snap when dependency management is enabled;
   4. create the source and binary parent directories as root:root mode 0755 with one ansible.builtin.file loop;
   5. check out seriatim_version with ansible.builtin.git, using seriatim_repository_url, seriatim_source_dir, and force: true, and register the module result;
   6. inspect seriatim_binary_path with ansible.builtin.stat;
   7. build directly to seriatim_binary_path when the Git task 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;
3. Put the rebuild expression directly on the build command. Register the Git and binary inspection results needed by its two conditions without creating an intermediate rebuild fact.
4. Invoke seriatim_go_binary with argv, the fixed package, flags, linker value, output path, working directory, and environment from the upstream contract. Do not turn the remaining fixed values into defaults or facts. Apply task-level privilege escalation to dependency installation and tasks that manage root-owned application state.
5. Remove all code for Git executable discovery, Go executable and compiler validation, manual Git status/reset/clean, resolved-commit facts, temporary build directories, build inputs, fingerprints, checksums, sidecar state, special path-object recovery, and transactional installation.
6. Do not add handlers/main.yml; the build and permission tasks execute in normal order.
7. Rewrite the README to document the seven-variable interface, privilege and fact requirements, dependency opt-out behavior, authoritative Git checkout, direct build contract, two rebuild triggers, installed metadata, and validation commands. Remove every claim or example tied to deleted variables, state files, staging, compiler invalidation, or failure preservation.
8. Rewrite tests/verify.yml to check only the selected commit, recursive 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

From ansible-role-seriatim, run:

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 status --short

Expected result: static validation passes; the default source resolves to 0fc92f364316c874d366b00cdc884a33e1900b25; the binary reports seriatim version v1.5.0 with root:root ownership and mode 0755; the immediate repeat reports changed=0 and failed=0; and only intended Stage 1 changes remain before commit.

Completion Criteria

• The public interface contains exactly seven defaults and matching argument specifications.
• The role's effective task flow matches the roadmap without intermediate rebuild state or handlers.
• No role code or active documentation references the obsolete sidecar state or removed variables.
• The baseline integration driver passes and proves default idempotence.
• No repository outside ansible-role-seriatim changed.

Commit

Commit message: Simplify the Seriatim role

Stage 2: Add Focused Behavioral Coverage

Completion: Complete (ansible-role-seriatim commit 718030e).

Objective

Extend the baseline test harness only far enough to prove the revised feature's selected rebuild triggers, metadata convergence, platform guard, and final default state.

Preconditions

• Stage 1 is committed and the role repository is otherwise clean.
• The Stage 1 baseline integration test passes.
• Upstream tags v1.4.0 and v1.5.0 remain available.

Owning Repository

ansible-role-seriatim

Required Changes

1. Extend tests/integration using strict shell options, repository-relative paths, a private temporary directory, and cleanup that restores the default v1.5.0 installation when possible.
2. Retain the baseline convergence, verification, and clean-repeat cases, then add focused cases for:
   • 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;
   • binary ownership or mode drift being repaired by the ordinary file task without requiring a rebuild, as shown by the captured Ansible task output;
   • selecting v1.4.0, confirming its commit and version output, and reaching an unchanged repeat;
   • restoring v1.5.0, confirming its commit and version output, and reaching a final unchanged repeat;
   • unsupported distribution, Ubuntu release, and architecture inputs failing before creating application state at isolated temporary paths.
3. Keep recap checks simple and fail the driver on hidden task failures or unexpected changes during idempotence runs.
4. Keep test mutation limited to the two declared managed paths and paths below the driver's private temporary directory.
5. Do not add cases for fingerprints, checksums, compiler changes, source-tree dirt, staged failure preservation, custom-parent recovery, symbolic links, malformed state, or the obsolete build-state directory.
6. Update the README test section to describe the actual focused suite and its managed-host effects without advertising superseded behavior.

Validation

From ansible-role-seriatim, run:

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

Then confirm the restored default installation:

/usr/local/bin/seriatim --version
sudo git -C /usr/local/src/seriatim rev-parse HEAD
sudo stat -c '%U:%G %a' /usr/local/bin/seriatim

Expected result: the complete focused suite passes; all expected negative platform cases are recognized; the final repeat reports changed=0 and failed=0; the restored executable reports seriatim version v1.5.0; the source is at 0fc92f364316c874d366b00cdc884a33e1900b25; binary metadata is root:root 755; and only intended Stage 2 changes remain before commit.

Completion Criteria

• Every Feature 0001 acceptance criterion has direct test or static evidence.
• The suite tests only the revised operational contract and contains no superseded hardening matrix.
• The README, defaults, argument specifications, task flow, and tests agree.
• The default local installation is restored and idempotent.
• No repository outside ansible-role-seriatim changed.

Commit

Commit message: Focus Seriatim integration coverage

Final Validation and Handoff

After Stage 2, run:

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

The implementation handoff must report:

• the Stage 1 and Stage 2 commit hashes in order;
• the final integration result and clean-repeat recap;
• 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

• Stage 1 completed in ansible-role-seriatim commit 325a5c7.
• 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.