diff --git a/.gitignore b/.gitignore index 8209fa9..d23c505 100644 --- a/.gitignore +++ b/.gitignore @@ -10,6 +10,7 @@ # Local tool state. /.codebase-memory/ +/.venv/ /.idea/ /.vscode/ *.swp diff --git a/AGENTS.md b/AGENTS.md index 5e206ed..e625c18 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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/-.md` and - `docs/plans/-.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/-.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 diff --git a/README.md b/README.md index 78692f2..e99a506 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/roadmap/features/0001-seriatim-source-installation.md b/docs/roadmap/features/0001-seriatim-source-installation.md new file mode 100644 index 0000000..021366a --- /dev/null +++ b/docs/roadmap/features/0001-seriatim-source-installation.md @@ -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. diff --git a/docs/plans/template.md b/docs/roadmap/implementation-template.md similarity index 98% rename from docs/plans/template.md rename to docs/roadmap/implementation-template.md index 629c690..b26b203 100644 --- a/docs/plans/template.md +++ b/docs/roadmap/implementation-template.md @@ -6,6 +6,8 @@ Target executor: GPT-5.6-Terra Feature roadmap: `docs/roadmap/features/-.md` +Active plan location: `docs/roadmap/implementation.md` + ## Objective Summarize the implementation outcome. The feature roadmap remains authoritative diff --git a/docs/status.md b/docs/status.md index 0b32856..e836d8c 100644 --- a/docs/status.md +++ b/docs/status.md @@ -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 diff --git a/requirements-dev.txt b/requirements-dev.txt new file mode 100644 index 0000000..6babff8 --- /dev/null +++ b/requirements-dev.txt @@ -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