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

docs: define initial Seriatim installation feature

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-07 17:37:03 +00:00
parent 4e861f1f3e
commit fc9f818598
7 changed files with 220 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@@ -10,6 +10,7 @@
# Local tool state.
/.codebase-memory/
/.venv/
/.idea/
/.vscode/
*.swp

12
AGENTS.md
View File

@@ -37,7 +37,8 @@ remotes.
of work.
- `docs/status.md`: current cross-repository progress and next work.
- `docs/decisions/`: durable rationale for significant architectural choices.
- `docs/plans/`: temporary implementation plans for substantial work.
- `docs/roadmap/implementation.md`: the single active staged implementation
plan, replaced for each selected feature after its feature roadmap is agreed.
- Application repositories: CLI, configuration, build, and integration
contracts.
- Individual Ansible repositories: implementation and repository-local tests.
@@ -71,12 +72,15 @@ link and a concise deployment consequence are sufficient.
- Update `docs/roadmap/mvp.md` when a design question becomes a settled scope
or architecture decision.
- Discuss and select the next unit of work before planning implementation.
- Give each selected feature a four-digit identifier and matching documents at
`docs/roadmap/features/<id>-<slug>.md` and
`docs/plans/<id>-<slug>.md`. Add the same identifier to `docs/status.md`.
- Give each selected feature a four-digit identifier and a durable document at
`docs/roadmap/features/<id>-<slug>.md`. Add the same identifier to
`docs/status.md`.
- Write and agree on the feature roadmap before writing its implementation
plan. The roadmap owns scope, target end state, rationale, constraints, and
acceptance criteria.
- Always write the current implementation plan to
`docs/roadmap/implementation.md`. Replace that file when planning the next
selected feature; Git history preserves prior plans when needed.
- Write implementation plans as dependency-ordered stages suitable for
GPT-5.6-Terra to execute sequentially. Number stages with consecutive
integers beginning with `Stage 1`; do not skip numbers or use nested stage

22
README.md
View File

@@ -16,12 +16,30 @@ only workspace documentation, planning, and shared development utilities.
- [`docs/roadmap/features/`](docs/roadmap/features/) contains durable feature
roadmaps for selected units of work.
- [`docs/status.md`](docs/status.md) records current cross-repository progress.
- [`docs/plans/template.md`](docs/plans/template.md) defines the staged format
used for out-of-band implementation.
- [`docs/roadmap/implementation.md`](docs/roadmap/implementation.md), when
present, is the single active out-of-band implementation plan.
- [`docs/roadmap/implementation-template.md`](docs/roadmap/implementation-template.md)
defines its staged format.
Run `./scripts/status` to see the branch and working-tree state of every
repository in the workspace manifest.
## Development Tooling
Create the shared workspace environment on Ubuntu 26.04 with:
```sh
sudo apt-get install python3-venv
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -r requirements-dev.txt
```
Either activate it with `source .venv/bin/activate` or invoke tools directly,
for example `.venv/bin/ansible-playbook` and `.venv/bin/ansible-lint`.
Dependency upgrades are deliberate changes to `requirements-dev.txt`; do not
install workspace development packages into the system Python environment.
## Repository Boundaries
The directories ignored by this repository are intentional nested Git working

155
docs/roadmap/features/0001-seriatim-source-installation.md Normal file
View File

@@ -0,0 +1,155 @@
# Feature 0001: Seriatim Source Installation
Status: proposed
## Summary
Implement the first independently usable application role by teaching
`ansible-role-seriatim` to install Seriatim from a pinned upstream source
release. This feature establishes the source-build and role conventions that
can be reviewed before analogous work begins in the other application roles.
## Problem or Opportunity
The pipeline applications do not yet share a uniform prebuilt release model,
and the new Ansible role repositories contain only initial scaffolding. The MVP
therefore builds applications on the managed host. Seriatim is the smallest
useful proving ground because it has no central application configuration file,
allowing this feature to isolate installation, reproducibility, idempotence,
and validation concerns.
## Scope
- Establish a conventional, independently usable Ansible role structure in
`ansible-role-seriatim`.
- Support Ubuntu 26.04 on native `amd64` and `arm64` hosts.
- Install Git and the official Go Snap using classic confinement when build
dependency management is enabled.
- Default the Go Snap channel to `1.26/stable` and allow consumers to override
the channel or disable build-dependency management.
- Clone the official Seriatim repository into a root-owned managed source
directory, defaulting to `/usr/local/src/seriatim`.
- Default to the immutable `v1.5.0` release tag, verified as the latest current
upstream tag on 2026-09-07, while supporting explicit branch or commit
overrides for development.
- Build a native, statically linked Seriatim binary using the upstream build
contract, including release-version injection.
- Validate a staged binary before installing it as
`/usr/local/bin/seriatim` with `root:root` ownership and mode `0755`.
- Record sufficient build state to rebuild when the resolved source commit,
Go compiler version, or effective build arguments change.
- Validate the installed binary and demonstrate convergence on a repeated role
run.
- Document the role interface, defaults, supported platform, development
overrides, and validation procedure.
## Non-goals
- Application configuration; Seriatim has no central configuration file.
- Creation or management of the `narratio` account or operator membership.
- Installation or configuration of any other pipeline application.
- Pipeline composition, campaign data, prompts, secrets, or scheduling.
- Installation from prebuilt Seriatim release artifacts.
- Removal or purge behavior.
- A shared build helper role or premature abstraction of the first
implementation.
- Full Ubuntu 26.04 platform-matrix or `arm64` integration infrastructure.
## Target End State
On an Ubuntu 26.04 `amd64` or `arm64` host, applying the role with default
variables checks out Seriatim `v1.5.0` under `/usr/local/src/seriatim`, builds
it with the locally installed Go 1.26 toolchain, validates it, and installs a
root-owned executable at `/usr/local/bin/seriatim`. The installed command
reports `v1.5.0` through its global version flag.
A second application of the role makes no changes when the selected source,
compiler, build arguments, and installed binary are unchanged. Changing the
selected revision, compiler patch version, or effective build arguments causes
a rebuild. A failed build or validation does not replace an existing working
binary.
The managed source checkout is authoritative and may be reset to the selected
revision; local modifications beneath it are not preserved. Development users
may select a branch or commit explicitly, but released role and collection
manifests use immutable release tags.
## Repository Ownership
- `ansible-role-seriatim` owns all implementation, defaults, documentation,
and repository-local validation added by this feature.
- `../seriatim` is the read-only authority for the application build, version,
and CLI contracts.
- `ansible-workspace-dnd` owns this roadmap, the active implementation plan,
and cross-repository status only.
- The remaining role, collection, application, content, and proof-of-concept
repositories remain unchanged.
## Constraints and Settled Decisions
- The suite MVP supports Ubuntu 26.04 and native `amd64` and `arm64` builds.
- Local execution on the current Ubuntu 26.04 development host is a sufficient
MVP integration proxy; dedicated platform-matrix infrastructure is deferred.
- Go is installed from Snap with classic confinement. Builds use the local
toolchain with `GOTOOLCHAIN=local` rather than allowing automatic toolchain
downloads.
- The suite standardizes on Go channel `1.26/stable`, even though Seriatim's
current `go.mod` requires Go 1.25.
- Builds use `GOWORK=off`, `CGO_ENABLED=0`, and `-trimpath`.
- Release builds inject the selected release version into
`gitea.maximumdirect.net/eric/seriatim/internal/buildinfo.Version` with
`-ldflags`.
- A change to the installed Go compiler patch version is a build-input change
and triggers a rebuild.
- `/usr/local/src/seriatim` is fully Ansible-managed. The role enforces the
selected Git revision rather than preserving local changes.
- Source and installed binaries are owned by `root` and are not writable by
runtime operators.
## Rationale and Alternatives
Starting with Seriatim exercises the common source installation path without
mixing in application configuration, credentials, shared accounts, or pipeline
composition. This makes the first implementation small enough to review
carefully and allows its conventions to be corrected before being repeated.
Using Go `1.26/stable` across the suite favors one predictable host toolchain
over selecting each application's minimum supported version. Rebuilding after
a compiler patch change preserves an honest relationship between recorded
build inputs and installed output. Keeping the first role self-contained also
avoids committing to a shared abstraction before repeated implementation has
shown which behavior is truly common.
## Acceptance Criteria
- The role rejects unsupported distributions, Ubuntu releases, and
architectures with a clear diagnostic before modifying application state.
- Default role execution on the local Ubuntu 26.04 host installs or confirms
the required Git and Go build dependencies.
- The source checkout resolves to the commit referenced by tag `v1.5.0` and is
root-owned at `/usr/local/src/seriatim` by default.
- The role builds with the documented local-toolchain and version-injection
contract and installs `/usr/local/bin/seriatim` as `root:root` mode `0755`.
- `/usr/local/bin/seriatim --version` reports `v1.5.0`.
- An immediate second role run reports no changes.
- A changed selected revision, Go compiler patch version, or effective build
argument invalidates recorded build state and rebuilds the binary.
- A deliberately failed staged build or version validation leaves a previously
installed working binary intact.
- Development revision overrides converge to the requested branch or commit
and discard unmanaged changes in the source checkout.
- Role defaults, metadata, README documentation, syntax validation, focused
automated checks, and local integration evidence are present in the owning
repository.
- No repository other than `ansible-role-seriatim` and the workspace control
repository is modified.
## Dependencies and Follow-up Work
This feature depends only on access to the Seriatim Git repository, Ubuntu Snap
infrastructure, and Go module sources from the managed host.
After review, the source-build conventions may be adopted by the Audita,
Scriptorium, Notarius, and Narratio roles. Generalization into shared tooling,
prebuilt-binary installation, removal behavior, and dedicated multi-platform
test infrastructure remain deferred until concrete experience justifies them.

2
docs/plans/template.md → docs/roadmap/implementation-template.md
View File

@@ -6,6 +6,8 @@ Target executor: GPT-5.6-Terra
Feature roadmap: `docs/roadmap/features/<id>-<slug>.md`
Active plan location: `docs/roadmap/implementation.md`
## Objective
Summarize the implementation outcome. The feature roadmap remains authoritative

4
docs/status.md
View File

@@ -4,7 +4,8 @@ Last updated: 2026-09-07
Current milestone: MVP design and workspace foundation
Current focus: Select the next open design topic before role implementation.
Current focus: Review Feature 0001 before writing its staged implementation
plan.
| ID | Deliverable | Owner | State | Evidence or next step |
| --- | --- | --- | --- | --- |
@@ -17,6 +18,7 @@ Current focus: Select the next open design topic before role implementation.
| M1-02 | Standalone application roles | role repositories | proposed | Begin after relevant interfaces are settled |
| 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 |
| F0001 | Install Seriatim from pinned source | ansible-role-seriatim | proposed | Review `docs/roadmap/features/0001-seriatim-source-installation.md` |
## Updating This File

31
requirements-dev.txt Normal file
View File

@@ -0,0 +1,31 @@
# Fully resolved workspace development toolchain for Python 3.14 on Ubuntu
# 26.04. Regenerate deliberately when upgrading ansible-core or ansible-lint.
ansible-compat==26.8.0
ansible-core==2.21.3
ansible-lint==26.8.0
attrs==26.1.0
black==26.5.1
bracex==3.0.1
cffi==2.1.1
click==8.5.0
cryptography==50.0.1
distro==1.9.0
filelock==3.32.5
Jinja2==3.1.6
jsonschema==4.26.0
jsonschema-specifications==2025.9.1
MarkupSafe==3.0.3
mypy_extensions==1.1.0
packaging==26.3
pathspec==1.1.1
platformdirs==4.11.7
pycparser==3.0
pytokens==0.4.1
PyYAML==6.0.3
referencing==0.37.0
resolvelib==1.2.1
rpds-py==2026.6.3
ruamel.yaml==0.19.1
subprocess-tee==0.4.2
wcmatch==11.0.1
yamllint==1.38.0