Compare commits
20 Commits
0349682eb9
...
5713ce582e
| Author | SHA1 | Date | |
|---|---|---|---|
| 5713ce582e | |||
| 007d8b830e | |||
| 0b7d6d98a7 | |||
| c297f56b7e | |||
| da799198b2 | |||
| a1be51ea35 | |||
| 81ea76aa51 | |||
| 4e8018405a | |||
| fc803587b8 | |||
| aafee9ea62 | |||
| 8e7af0cebf | |||
| a5d032e2dc | |||
| 819ccb155f | |||
| a1b340be0c | |||
| 8122df641b | |||
| 0c738f4a94 | |||
| 1251143a34 | |||
| a556734cc2 | |||
| fc9f818598 | |||
| 4e861f1f3e |
1
.gitignore
vendored
1
.gitignore
vendored
@@ -10,6 +10,7 @@
|
||||
|
||||
# Local tool state.
|
||||
/.codebase-memory/
|
||||
/.venv/
|
||||
/.idea/
|
||||
/.vscode/
|
||||
*.swp
|
||||
|
||||
77
AGENTS.md
77
AGENTS.md
@@ -7,71 +7,14 @@ deploy the D&D transcript-processing pipeline. It owns cross-repository plans,
|
||||
decisions, status, and workspace tooling. Each application and Ansible project
|
||||
is an independent Git repository.
|
||||
|
||||
## Repository Map
|
||||
## Required Reading
|
||||
|
||||
Repositories inside this directory:
|
||||
|
||||
- `ansible-collection-dnd`: the `rakestraw.dnd` collection that bundles and
|
||||
distributes the pipeline suite.
|
||||
- `ansible-role-dnd-pipeline`: independent source repository for the
|
||||
suite-level role exposed by the collection as `rakestraw.dnd.pipeline`.
|
||||
- `ansible-role-{narratio,notarius,audita,seriatim,scriptorium}`: standalone
|
||||
application roles.
|
||||
- `rakestraw-ansible`: working deployment repository containing the
|
||||
`pipeline_dnd` proof of concept; treat it as read-only reference unless the
|
||||
task explicitly includes it.
|
||||
|
||||
Relevant upstream repositories are siblings of this directory:
|
||||
|
||||
- `../{narratio,notarius,audita,seriatim,scriptorium}`: application source and
|
||||
authoritative application contracts.
|
||||
- `../narratio-prompts`: pipeline prompt-library content.
|
||||
|
||||
Use `workspace.yml` as the complete machine-readable inventory of paths and
|
||||
remotes.
|
||||
|
||||
## Sources of Truth
|
||||
|
||||
- `docs/roadmap/mvp.md`: settled MVP scope, architecture, and open design 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.
|
||||
- Application repositories: CLI, configuration, build, and integration
|
||||
contracts.
|
||||
- Individual Ansible repositories: implementation and repository-local tests.
|
||||
|
||||
Do not duplicate an application contract in workspace documentation when a
|
||||
link and a concise deployment consequence are sufficient.
|
||||
|
||||
## Working Conventions
|
||||
|
||||
- Confirm the target repository before editing; never treat this directory as
|
||||
a monorepo.
|
||||
- Inspect the relevant upstream application before designing or changing its
|
||||
Ansible role.
|
||||
- Keep standalone application roles independently usable. Cross-application
|
||||
policy belongs in `ansible-role-dnd-pipeline` and is exposed to consumers as
|
||||
`rakestraw.dnd.pipeline`.
|
||||
- Use `ansible.builtin` modules directly unless a concrete requirement justifies
|
||||
another dependency.
|
||||
- Prefer codebase-memory graph tools for code discovery. Use text/file search
|
||||
for documentation, configuration, literals, or when the graph is
|
||||
insufficient.
|
||||
- Preserve unrelated and pre-existing working-tree changes in every
|
||||
repository.
|
||||
- Never place credentials or secret values in plans, examples, inventory, or
|
||||
tests.
|
||||
- Validate changes in the repository that owns them and report the commands
|
||||
run.
|
||||
|
||||
## Planning and Progress
|
||||
|
||||
- Update `docs/roadmap/mvp.md` when a design question becomes a settled scope
|
||||
or architecture decision.
|
||||
- Update `docs/status.md` when cross-repository work starts, becomes blocked,
|
||||
or is completed. Completed items must point to concrete evidence.
|
||||
- Create a file in `docs/plans/` only for work spanning multiple meaningful
|
||||
steps or repositories. Remove or archive stale execution detail after the
|
||||
work is complete; durable rationale belongs in `docs/decisions/`.
|
||||
- Use the status values `proposed`, `ready`, `in_progress`, `blocked`, `done`,
|
||||
and `deferred`.
|
||||
- Read [the workspace orientation](docs/orientation.md) before selecting,
|
||||
inspecting, or modifying a repository. It maps the repositories and defines
|
||||
the canonical sources of truth.
|
||||
- Read [the workspace conventions](docs/conventions.md) before reviewing or
|
||||
changing Ansible, preparing a feature roadmap or implementation plan, or
|
||||
making any repository change. It defines the normative house style and
|
||||
working conventions.
|
||||
- Read [the planning policy](docs/planning.md) before preparing a feature
|
||||
roadmap or implementation plan or managing an ongoing work stream.
|
||||
|
||||
22
README.md
22
README.md
@@ -13,11 +13,33 @@ only workspace documentation, planning, and shared development utilities.
|
||||
development.
|
||||
- [`docs/roadmap/mvp.md`](docs/roadmap/mvp.md) records settled MVP decisions
|
||||
and open design work.
|
||||
- [`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/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
|
||||
|
||||
67
docs/conventions.md
Normal file
67
docs/conventions.md
Normal file
@@ -0,0 +1,67 @@
|
||||
# Workspace Conventions
|
||||
|
||||
## Working Conventions
|
||||
|
||||
- Confirm the target repository before editing; never treat this directory as
|
||||
a monorepo.
|
||||
- Inspect the relevant upstream application before designing or changing its
|
||||
Ansible role.
|
||||
- Keep standalone application roles independently usable. Cross-application
|
||||
policy belongs in `ansible-role-dnd-pipeline` and is exposed to consumers as
|
||||
`rakestraw.dnd.pipeline`.
|
||||
- Prefer codebase-memory graph tools for code discovery. Use text/file search
|
||||
for documentation, configuration, literals, or when the graph is
|
||||
insufficient.
|
||||
- Preserve unrelated and pre-existing working-tree changes in every
|
||||
repository.
|
||||
- Never place credentials or secret values in plans, examples, inventory, or
|
||||
tests.
|
||||
- Validate changes in the repository that owns them and report the commands
|
||||
run.
|
||||
- Do not duplicate an application contract in workspace documentation when a
|
||||
link and a concise deployment consequence are sufficient.
|
||||
|
||||
## Ansible House Style (Normative)
|
||||
|
||||
- Always use the smallest clear sequence of declarative tasks that reaches the
|
||||
required end state.
|
||||
- Prefer `ansible.builtin` modules where they directly fit the task.
|
||||
`community.general` is an approved, stable dependency and its modules may be
|
||||
selected freely when appropriate; declare and pin the collection wherever a
|
||||
role or collection depends on it.
|
||||
- Do not strengthen the specification. Implement the requested invariants
|
||||
without inventing additional guarantees for integrity, provenance, drift
|
||||
recovery, corruption detection, rollback, or similar behavior.
|
||||
- Prefer convergence over state inspection. Declare what should be true and
|
||||
let the relevant module reconcile it.
|
||||
- Trust Ansible's abstraction boundary. A module that manages state owns the
|
||||
checks necessary to manage that state. Inspect it beforehand only when the
|
||||
observed state is independently required.
|
||||
- State inspection is justified when its result is necessary to decide whether
|
||||
an imperative operation must run, such as checking whether an arbitrary
|
||||
build command's output exists.
|
||||
- Production role tasks establish required application state; they do not test
|
||||
the role's own implementation. Put implementation verification in
|
||||
repository-local tests unless the specification explicitly requires runtime
|
||||
validation during convergence.
|
||||
- Apply `become: true` to individual tasks that require elevated privileges.
|
||||
Do not require callers to escalate an entire play merely to use a role.
|
||||
- Complexity requires a requirement. Every additional task, conditional,
|
||||
registered variable, or state probe must correspond to behavior the role is
|
||||
required to provide.
|
||||
- Persisted role-private state is a design smell. Fingerprints, checksum
|
||||
databases, stamps, manifests, and similar bookkeeping require specific
|
||||
justification.
|
||||
- **Assume convergence first.** Before adding machinery for an edge case,
|
||||
determine whether rerunning the ordinary desired-state operations already
|
||||
repairs it.
|
||||
- Consider whether a conditional task or a notified handler best expresses the
|
||||
dependency. A `when` condition keeps triggers visible at the action site but
|
||||
grows with their number. Notifications keep the action independent of the
|
||||
number of notifiers, but distribute the control flow and defer execution
|
||||
until the next handler flush. An explicit
|
||||
`ansible.builtin.meta: flush_handlers` affects all pending handlers in the
|
||||
play.
|
||||
- Treat `rakestraw-ansible` as a style reference for direct tasks, shallow
|
||||
control flow, and concise variable use, while retaining current practices
|
||||
such as fully qualified collection names.
|
||||
54
docs/decisions/0001-minimal-module-driven-ansible.md
Normal file
54
docs/decisions/0001-minimal-module-driven-ansible.md
Normal file
@@ -0,0 +1,54 @@
|
||||
# Decision 0001: Minimal, Module-Driven Ansible
|
||||
|
||||
Status: accepted
|
||||
|
||||
Date: 2026-09-07
|
||||
|
||||
## Context
|
||||
|
||||
The first Seriatim implementation surrounded ordinary Ansible operations with
|
||||
preflight inspection, fingerprints, sidecar build state, manual drift logic,
|
||||
and recovery behavior. Much of that machinery duplicated behavior already
|
||||
provided by Ansible modules or addressed threats and failure modes outside the
|
||||
MVP. The result was harder to understand, review, and maintain than the
|
||||
deployment it represented.
|
||||
|
||||
The proof-of-concept roles in `rakestraw-ansible` demonstrate the preferred
|
||||
style: direct module use, shallow task flow, small public interfaces, and
|
||||
loops only for genuinely uniform resources.
|
||||
|
||||
## Decision
|
||||
|
||||
Roles in this workspace will express the required end state with the most
|
||||
direct suitable Ansible module and trust that module's documented idempotence,
|
||||
change detection, check-mode behavior, and error handling.
|
||||
|
||||
Additional inspection or state machinery is justified only when a selected
|
||||
requirement falls outside that module contract. In particular:
|
||||
|
||||
- Do not use `stat`, package queries, content comparisons, or account lookups
|
||||
merely to decide whether to invoke an idempotent module.
|
||||
- Gather state when it is genuinely needed to control application behavior,
|
||||
such as determining whether an imperative build command's output is missing.
|
||||
- Treat a successful module invocation as establishing its documented
|
||||
postcondition. Verify the role's implementation in repository-local tests
|
||||
rather than adding production tasks that immediately re-prove it.
|
||||
- Do not introduce fingerprints, checksums, sidecar state, staged replacement,
|
||||
custom drift recovery, or abstractions without an explicit acceptance
|
||||
criterion and rationale.
|
||||
- Keep role variables to meaningful consumer choices. Do not expose every
|
||||
fixed argument of an upstream build command as a public interface.
|
||||
- Test the intended operating contract and idempotent convergence. Do not
|
||||
build a speculative hardening test matrix into the MVP.
|
||||
|
||||
## Consequences
|
||||
|
||||
Feature roadmaps describe the simplest viable implementation shape, and
|
||||
implementation plans must justify any material complexity beyond it. Reviews
|
||||
should remove logic that merely reimplements a module's contract.
|
||||
|
||||
Potential security hardening and unusual recovery behavior may be recorded for
|
||||
future consideration without becoming part of the initial implementation.
|
||||
This accepts that an MVP role may fail plainly when the managed host contains
|
||||
malicious, corrupted, or unsupported state rather than attempting automatic
|
||||
recovery from every condition.
|
||||
44
docs/orientation.md
Normal file
44
docs/orientation.md
Normal file
@@ -0,0 +1,44 @@
|
||||
# Workspace Orientation
|
||||
|
||||
## Repository Map
|
||||
|
||||
Repositories inside this directory:
|
||||
|
||||
- `ansible-collection-dnd`: the `rakestraw.dnd` collection that bundles and
|
||||
distributes the pipeline suite.
|
||||
- `ansible-role-dnd-pipeline`: independent source repository for the
|
||||
suite-level role exposed by the collection as `rakestraw.dnd.pipeline`.
|
||||
- `ansible-role-{narratio,notarius,audita,seriatim,scriptorium}`: standalone
|
||||
application roles.
|
||||
- `rakestraw-ansible`: working deployment repository containing the
|
||||
`pipeline_dnd` proof of concept; treat it as read-only reference unless the
|
||||
task explicitly includes it.
|
||||
|
||||
Relevant upstream repositories are siblings of this directory:
|
||||
|
||||
- `../{narratio,notarius,audita,seriatim,scriptorium}`: application source and
|
||||
authoritative application contracts.
|
||||
- `../narratio-prompts`: pipeline prompt-library content.
|
||||
|
||||
Use [the workspace inventory](../workspace.yml) as the complete
|
||||
machine-readable inventory of paths and remotes.
|
||||
|
||||
## Sources of Truth
|
||||
|
||||
- [Workspace conventions](conventions.md): normative working and Ansible house
|
||||
style.
|
||||
- [Planning policy](planning.md): normative feature planning and progress
|
||||
workflow.
|
||||
- [MVP roadmap](roadmap/mvp.md): settled MVP scope, architecture, and open
|
||||
design work.
|
||||
- [Feature roadmaps](roadmap/features/): durable scope and target state for
|
||||
selected units of work.
|
||||
- [Workspace status](status.md): current cross-repository progress and next
|
||||
work.
|
||||
- [Decision records](decisions/): durable rationale for significant
|
||||
architectural choices.
|
||||
- [Implementation plan](roadmap/implementation.md): the fixed location for the
|
||||
active staged plan or, when no plan is approved, a pending-plan notice.
|
||||
- Application repositories: CLI, configuration, build, and integration
|
||||
contracts.
|
||||
- Individual Ansible repositories: implementation and repository-local tests.
|
||||
44
docs/planning.md
Normal file
44
docs/planning.md
Normal file
@@ -0,0 +1,44 @@
|
||||
# Planning and Progress
|
||||
|
||||
- Read and follow [the workspace conventions](conventions.md) before preparing
|
||||
or revising any roadmap or implementation plan.
|
||||
- Update [the MVP roadmap](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 a durable document at
|
||||
`docs/roadmap/features/<id>-<slug>.md`. Start from the
|
||||
[feature-roadmap template](roadmap/features/template.md) and add the same
|
||||
identifier to [workspace status](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.
|
||||
- Every feature roadmap must describe its simplest viable implementation shape
|
||||
and identify any deliberate complexity. Keep optional security hardening,
|
||||
unusual corruption recovery, and other speculative resilience outside the
|
||||
MVP unless explicitly selected as requirements.
|
||||
- Start from the [implementation-plan template](roadmap/implementation-template.md)
|
||||
and always write the current plan to
|
||||
[the fixed implementation-plan location](roadmap/implementation.md). Replace
|
||||
that file when planning the next selected feature; Git history preserves
|
||||
prior plans when needed.
|
||||
- When a prior plan has been withdrawn and its replacement has not yet been
|
||||
agreed, replace stale execution instructions with a brief pending-plan
|
||||
notice. Never leave an obsolete plan looking executable.
|
||||
- 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
|
||||
numbering. Each stage must identify its repository, preconditions, required
|
||||
behavior, validation, completion criteria, and expected commit.
|
||||
- Resolve architectural choices during roadmap and plan review. Do not leave
|
||||
unresolved design judgment to the implementation agent.
|
||||
- Update [workspace status](status.md) when cross-repository work starts,
|
||||
becomes blocked, or is completed. Completed items must point to concrete
|
||||
evidence.
|
||||
- Out-of-band implementation should commit each completed stage when that
|
||||
stage leaves its owning repository valid. Review the implementation and its
|
||||
validation evidence before marking the feature complete.
|
||||
- Retain feature roadmaps as durable records. Remove or archive obsolete
|
||||
implementation detail after completion; durable architectural rationale
|
||||
belongs in [decision records](decisions/).
|
||||
- Use the status values `proposed`, `ready`, `in_progress`, `blocked`, `done`,
|
||||
and `deferred`.
|
||||
@@ -1,37 +0,0 @@
|
||||
# Plan: <Title>
|
||||
|
||||
Status: proposed
|
||||
|
||||
## Goal
|
||||
|
||||
State the outcome this plan must achieve.
|
||||
|
||||
## Non-goals
|
||||
|
||||
List adjacent work that is intentionally outside this plan.
|
||||
|
||||
## Owning Repositories
|
||||
|
||||
List every repository this work may change and what each repository owns.
|
||||
|
||||
## Dependencies and Settled Decisions
|
||||
|
||||
Link applicable roadmap sections and decision records. Record prerequisites
|
||||
that constrain implementation.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Define observable conditions for completion.
|
||||
|
||||
## Implementation Sequence
|
||||
|
||||
1. Describe the first independently verifiable step.
|
||||
|
||||
## Validation
|
||||
|
||||
List the commands, tests, or inspections that demonstrate completion.
|
||||
|
||||
## Progress
|
||||
|
||||
Keep only concise current state and blockers here. Git history should preserve
|
||||
obsolete execution detail.
|
||||
219
docs/roadmap/features/0001-seriatim-source-installation.md
Normal file
219
docs/roadmap/features/0001-seriatim-source-installation.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# Feature 0001: Seriatim Source Installation
|
||||
|
||||
Status: done
|
||||
|
||||
## Summary
|
||||
|
||||
Provide a small, independently usable `rakestraw.seriatim` role that installs
|
||||
Seriatim from a pinned Git tag, builds the native executable on the managed
|
||||
host, and converges idempotently. This revised specification replaces the
|
||||
original overengineered implementation target and establishes the preferred
|
||||
module-driven style for subsequent application roles.
|
||||
|
||||
## Problem or Opportunity
|
||||
|
||||
The current role reaches the basic deployment outcome, but it does so with
|
||||
manual source cleanup, compiler parsing, build-input serialization, hashes,
|
||||
checksums, sidecar state, path-shape recovery, and a large defensive test
|
||||
matrix. Those mechanisms are disproportionate to the MVP and obscure the
|
||||
simple job of checking out a repository, building one executable, and
|
||||
installing it with known metadata.
|
||||
|
||||
Seriatim remains the right proving ground because it has no central
|
||||
configuration file. Simplifying it before implementing another role prevents
|
||||
the current design from becoming an accidental suite-wide pattern.
|
||||
|
||||
## Scope
|
||||
|
||||
- Simplify `ansible-role-seriatim` into concise, idiomatic Ansible.
|
||||
- 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 the selected Seriatim version from its official Git repository,
|
||||
defaulting to immutable tag `v1.5.0`, under a root-owned
|
||||
`/usr/local/src/seriatim`.
|
||||
- Build Seriatim using the fixed upstream release build contract and install
|
||||
it at `/usr/local/bin/seriatim`.
|
||||
- Rebuild when the source checkout changes or the binary is absent.
|
||||
- Converge the installed binary to `root:root` ownership and mode `0755`.
|
||||
- Verify the installed version in repository-local integration tests.
|
||||
- Keep the role interface, README, metadata, and focused local tests consistent
|
||||
with the simplified behavior.
|
||||
- Remove obsolete build-state files and implementation machinery from the
|
||||
role repository. Existing build-state data on previously managed hosts does
|
||||
not need to be removed by the role.
|
||||
|
||||
## 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 release artifacts or removal behavior.
|
||||
- Detecting rebuild needs from Go compiler changes, fixed build-command
|
||||
changes, or out-of-band modification of an existing binary.
|
||||
- Build fingerprints, binary checksums, or persistent sidecar build state.
|
||||
- Transactional replacement that preserves a previous executable after a
|
||||
failed local build.
|
||||
- Automatic recovery from deliberately malformed paths, symbolic-link
|
||||
redirection, hostile source trees, or other adversarial host state.
|
||||
- A shared build helper role or abstraction.
|
||||
- Dedicated platform-matrix infrastructure beyond the approved local MVP
|
||||
proxy.
|
||||
|
||||
## Target End State
|
||||
|
||||
On an Ubuntu 26.04 `amd64` or `arm64` host, applying the role with default
|
||||
variables installs Git and Go when requested, checks out Seriatim `v1.5.0`
|
||||
under a root-owned `/usr/local/src/seriatim`, and installs a native executable at
|
||||
`/usr/local/bin/seriatim`. The executable is owned by `root:root`, has mode
|
||||
`0755`, and reports `seriatim version v1.5.0`.
|
||||
|
||||
An immediate second application makes no changes. A changed Git checkout or a
|
||||
missing binary causes one build. The following application is again unchanged.
|
||||
|
||||
The role trusts `apt`, `community.general.snap`, `file`, and `git` to provide
|
||||
their documented idempotence and change detection. It does not inspect state
|
||||
before invoking those modules or maintain a parallel model of the state they
|
||||
already manage.
|
||||
|
||||
## Repository Ownership
|
||||
|
||||
- `ansible-role-seriatim` owns the role implementation, defaults, metadata,
|
||||
README, dependency declaration, and repository-local validation.
|
||||
- `../seriatim` is the read-only authority for the build, version, and CLI
|
||||
contracts.
|
||||
- `rakestraw-ansible` is a read-only style reference.
|
||||
- `ansible-workspace-dnd` owns this roadmap, the active implementation plan,
|
||||
and cross-repository status.
|
||||
- All other 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.
|
||||
- Go is installed from Snap with classic confinement and defaults to channel
|
||||
`1.26/stable`.
|
||||
- `community.general` is an approved dependency and provides Snap management;
|
||||
its version is pinned in the role's collection requirements.
|
||||
- The build runs from the checked-out source using `seriatim_go_binary`
|
||||
(defaulting to `/snap/bin/go`) with `GOWORK=off`, `GOTOOLCHAIN=local`,
|
||||
`CGO_ENABLED=0`, `-trimpath`, package `./cmd/seriatim`, and the upstream
|
||||
linker flag that injects the selected version into
|
||||
`internal/buildinfo.Version`.
|
||||
- The selected version is both the Git revision and the version injected into
|
||||
the executable. Supporting independent source and build identities is not an
|
||||
MVP requirement.
|
||||
- The public interface is limited to meaningful deployment choices:
|
||||
`seriatim_version`, `seriatim_repository_url`, `seriatim_source_dir`,
|
||||
`seriatim_binary_path`, `seriatim_manage_build_dependencies`,
|
||||
`seriatim_go_snap_channel`, and `seriatim_go_binary`.
|
||||
- Build flags, linker symbols, environment values, and package paths are
|
||||
implementation details, not public variables.
|
||||
- Tasks that install dependencies or manage root-owned application state use
|
||||
task-level privilege escalation.
|
||||
- `docs/decisions/0001-minimal-module-driven-ansible.md` governs the role's
|
||||
implementation style.
|
||||
|
||||
## Simplest Viable Implementation
|
||||
|
||||
The intended Seriatim implementation is approximately the following eight
|
||||
ordinary tasks.
|
||||
|
||||
1. Assert the supported distribution, release, and architecture.
|
||||
2. Install Git with `ansible.builtin.apt` when dependency management is
|
||||
enabled.
|
||||
3. Install Go with `community.general.snap` when dependency management is
|
||||
enabled.
|
||||
4. Create the source and binary parent directories with one
|
||||
`ansible.builtin.file` loop.
|
||||
5. Check out the selected source with `ansible.builtin.git` and register its
|
||||
normal changed result.
|
||||
6. Inspect whether the installed binary exists.
|
||||
7. Run the upstream Go build when the Git checkout changed or the binary is
|
||||
absent.
|
||||
8. Converge source ownership and the installed binary's ownership and mode
|
||||
with one `ansible.builtin.file` loop.
|
||||
|
||||
For this fixed set of two rebuild triggers, the build remains an ordinary
|
||||
task with the conditions applied directly to its `when` expression. This keeps
|
||||
the complete decision visible at the action site and avoids deferred execution
|
||||
or a play-wide handler flush. Permission convergence then follows in its
|
||||
natural task order. Do not create an intermediate `seriatim_build_required`
|
||||
fact.
|
||||
|
||||
The implementation may combine or split a task when required for clear and
|
||||
correct Ansible, but it must not add preflight checks around idempotent modules
|
||||
or reintroduce persistent build-state machinery. Prefer a single readable task
|
||||
file unless a split materially improves navigation.
|
||||
|
||||
## Rationale and Alternatives
|
||||
|
||||
This design uses the Git module's changed result as the natural signal that
|
||||
source changed. A binary existence check is the only additional state needed
|
||||
to decide whether the imperative build command must run. That preserves useful
|
||||
convergence without adding unrequested drift detection or maintaining a second
|
||||
database of compiler and build inputs.
|
||||
|
||||
Building directly to the configured binary path is intentionally simpler than
|
||||
staging, checksumming, and recording a transactional installation. A failed
|
||||
build will fail the play visibly; preserving an older executable in every
|
||||
failure mode is not an MVP requirement.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- The role rejects unsupported distributions, Ubuntu releases, and
|
||||
architectures before modifying application state.
|
||||
- Default execution on the local Ubuntu 26.04 host installs or confirms Git
|
||||
and Go and checks out Seriatim tag `v1.5.0`.
|
||||
- The role builds with the documented fixed upstream contract and installs
|
||||
`/usr/local/bin/seriatim` as `root:root` mode `0755`.
|
||||
- The managed source checkout is owned by `root:root`.
|
||||
- `/usr/local/bin/seriatim --version` reports
|
||||
`seriatim version v1.5.0`.
|
||||
- An immediate second role run reports no changes.
|
||||
- A missing binary causes one rebuild followed by an unchanged run.
|
||||
- A changed selected version causes the Git task and build task to change and
|
||||
then converges.
|
||||
- The implementation contains no build-input documents, fingerprints, binary
|
||||
checksums, sidecar build state, manual Git reset or clean commands, or
|
||||
preliminary checks for state already managed by `apt`, Snap, `file`, or
|
||||
`git`.
|
||||
- Public defaults and argument specifications contain only the seven variables
|
||||
named in this roadmap.
|
||||
- A caller may disable dependency management and select an existing Go
|
||||
executable with `seriatim_go_binary`.
|
||||
- Tasks requiring superuser access use task-level privilege escalation.
|
||||
- Syntax checking, ansible-lint, a focused local convergence test, and a clean
|
||||
repeated run pass.
|
||||
- Role documentation describes the actual concise behavior and does not claim
|
||||
transactional build safety or exhaustive corruption recovery.
|
||||
- No repository other than `ansible-role-seriatim` and the workspace control
|
||||
repository is modified.
|
||||
|
||||
## Dependencies and Follow-up Work
|
||||
|
||||
The role requires access to the Seriatim Git repository, Ubuntu Snap
|
||||
infrastructure, and Go module sources from the managed host. After this revised
|
||||
implementation is reviewed, its minimal conventions can inform a fresh Audita
|
||||
roadmap and the remaining application roles.
|
||||
|
||||
The original implementation commits remain in Git history as evidence of the
|
||||
superseded design. The prior completion and remediation documents must not be
|
||||
used as templates for another role.
|
||||
|
||||
## Potential Future Hardening
|
||||
|
||||
- Build in a temporary location and validate before replacing the installed
|
||||
executable.
|
||||
- Verify release signatures or source checksums.
|
||||
- Record compiler and build-input identity for exact rebuild invalidation.
|
||||
- Detect arbitrary binary modification independently of reported version.
|
||||
- Protect or recover from unexpected symbolic links and malformed managed
|
||||
paths.
|
||||
- Add dedicated Ubuntu release and architecture test matrices.
|
||||
|
||||
These are candidates for separately selected features if operational
|
||||
experience or a changed threat model justifies them.
|
||||
@@ -0,0 +1,248 @@
|
||||
# Feature 0002: Audita Source Installation and Configuration
|
||||
|
||||
Status: done
|
||||
|
||||
## Summary
|
||||
|
||||
Provide a small, independently usable `rakestraw.audita` role that installs
|
||||
Audita from a pinned Git tag, builds its executable on the managed host, and
|
||||
manages its versioned YAML configuration. Follow the module-driven Seriatim
|
||||
pattern while adding only the configuration behavior that distinguishes
|
||||
Audita.
|
||||
|
||||
## Problem or Opportunity
|
||||
|
||||
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.
|
||||
|
||||
An earlier implementation direction depended on the superseded Seriatim
|
||||
fingerprint, sidecar-state, staged-build, and corruption-recovery architecture.
|
||||
This roadmap replaces that direction with a concise implementation that trusts
|
||||
Ansible modules, rebuilds only for required conditions, and keeps production
|
||||
role tasks separate from integration verification.
|
||||
|
||||
## Scope
|
||||
|
||||
- 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.
|
||||
|
||||
Implementation and focused integration coverage were completed in
|
||||
`ansible-role-audita` commits `47f1852`, `d37f590`, and `3a8c21f`. The D&D
|
||||
pipeline role can now select concrete `audita_config` values through the
|
||||
standalone role's complete-configuration interface.
|
||||
|
||||
## 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.
|
||||
62
docs/roadmap/features/template.md
Normal file
62
docs/roadmap/features/template.md
Normal file
@@ -0,0 +1,62 @@
|
||||
# Feature <ID>: <Title>
|
||||
|
||||
Status: proposed
|
||||
|
||||
## Summary
|
||||
|
||||
State the selected unit of work and the outcome it enables.
|
||||
|
||||
## Problem or Opportunity
|
||||
|
||||
Describe why this feature is needed and the current limitation it addresses.
|
||||
|
||||
## Scope
|
||||
|
||||
- List behavior and deliverables included in this feature.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- List adjacent behavior intentionally excluded from this feature.
|
||||
|
||||
## Target End State
|
||||
|
||||
Describe the observable repository, deployment, and operator state after the
|
||||
feature is complete. Keep this independent of the implementation sequence.
|
||||
|
||||
## Repository Ownership
|
||||
|
||||
Identify every repository involved and the durable responsibility each one
|
||||
owns. Distinguish repositories that will change from read-only sources of
|
||||
application contracts.
|
||||
|
||||
## Constraints and Settled Decisions
|
||||
|
||||
Link the MVP roadmap and applicable decision records. Record technical or
|
||||
operational constraints that implementations must preserve.
|
||||
|
||||
## Simplest Viable Implementation
|
||||
|
||||
Outline the direct, module-driven task flow at the level needed to constrain
|
||||
the implementation without turning the roadmap into an execution plan. Trust
|
||||
module idempotence and change detection. Identify any non-obvious probe,
|
||||
sidecar state, staging mechanism, command, or abstraction and tie it to a
|
||||
specific acceptance criterion.
|
||||
|
||||
## Rationale and Alternatives
|
||||
|
||||
Explain material tradeoffs and why the selected end state is preferred. Omit
|
||||
this section when the choice is mechanical and needs no durable rationale.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Define observable, testable conditions required for feature completion.
|
||||
|
||||
## Dependencies and Follow-up Work
|
||||
|
||||
List prerequisites and explicitly deferred work without expanding this
|
||||
feature's scope.
|
||||
|
||||
## Potential Future Hardening
|
||||
|
||||
List worthwhile security or resilience improvements that are deliberately not
|
||||
part of the initial implementation. Omit this section when there are none.
|
||||
112
docs/roadmap/implementation-template.md
Normal file
112
docs/roadmap/implementation-template.md
Normal file
@@ -0,0 +1,112 @@
|
||||
# Implementation Plan <ID>: <Title>
|
||||
|
||||
Status: proposed
|
||||
|
||||
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
|
||||
for scope, rationale, target end state, and acceptance criteria.
|
||||
|
||||
## Execution Rules
|
||||
|
||||
- Execute stages in numeric order.
|
||||
- Number stages with consecutive integers beginning with `Stage 1`. Do not use
|
||||
zero-based, decimal, nested, or nonsequential stage identifiers.
|
||||
- Before each stage, confirm its preconditions and the working-tree state of
|
||||
its owning repository.
|
||||
- Preserve unrelated and pre-existing changes.
|
||||
- Do not make unresolved product or architecture decisions during execution;
|
||||
stop and report the decision required.
|
||||
- Start from the feature roadmap's simplest viable implementation. Trust
|
||||
module-provided idempotence, change detection, check-mode behavior, and
|
||||
error handling rather than reproducing them with preliminary probes or
|
||||
supplemental state.
|
||||
- Do not add a task merely for defensive completeness. Every probe, fact,
|
||||
checksum, custom `changed_when`, shell or command invocation, sidecar state
|
||||
file, staging layer, or abstraction must be required by an
|
||||
acceptance criterion and must solve behavior that a direct module does not.
|
||||
- Run every stage's validation before committing it.
|
||||
- Commit each completed stage when it leaves the repository in a valid state,
|
||||
using the commit intent specified by that stage.
|
||||
- Do not begin a dependent stage after an earlier stage fails validation.
|
||||
|
||||
## Starting State and Preconditions
|
||||
|
||||
- List required branches, revisions, tools, dependencies, and prior features.
|
||||
- Identify expected clean or intentionally dirty working trees.
|
||||
|
||||
## Repository Scope
|
||||
|
||||
- List every repository that may change and the changes it owns.
|
||||
- List repositories that may be inspected but must remain unchanged.
|
||||
|
||||
## Stage 1: <Independently Verifiable Outcome>
|
||||
|
||||
### Objective
|
||||
|
||||
State the single outcome delivered by this stage.
|
||||
|
||||
### Preconditions
|
||||
|
||||
- List facts that must be true before editing begins.
|
||||
|
||||
### Owning Repository
|
||||
|
||||
`<repository path>`
|
||||
|
||||
### Required Changes
|
||||
|
||||
1. Describe concrete behavior to implement, including relevant files or
|
||||
components where known.
|
||||
2. State invariants, compatibility requirements, and explicit exclusions.
|
||||
3. Give the expected module-driven task flow. Call out every required use of
|
||||
`command`, `shell`, state inspection, or manual change detection.
|
||||
|
||||
### Validation
|
||||
|
||||
Run:
|
||||
|
||||
```text
|
||||
<exact validation command>
|
||||
```
|
||||
|
||||
Expected result: describe the required observable outcome, not merely a zero
|
||||
exit code.
|
||||
|
||||
### Completion Criteria
|
||||
|
||||
- List the evidence required before this stage is complete.
|
||||
|
||||
### Commit
|
||||
|
||||
Commit intent: `<type and concise purpose>`
|
||||
|
||||
## Stage 2: <Next Independently Verifiable Outcome>
|
||||
|
||||
Repeat the complete stage structure above. Add, remove, or split stages so
|
||||
each is ordered by dependency, reviewable on its own, and small enough to
|
||||
diagnose without repeating unrelated work. Continue with `Stage 3`, `Stage 4`,
|
||||
and subsequent consecutive integers as needed.
|
||||
|
||||
## Final Validation and Handoff
|
||||
|
||||
- Run cross-stage and cross-repository validation required by the feature
|
||||
roadmap.
|
||||
- Confirm every changed repository is clean and identify all resulting commit
|
||||
hashes.
|
||||
- Summarize deviations from this plan, unresolved findings, and deferred work.
|
||||
- Report any implementation complexity added beyond the planned task flow and
|
||||
the acceptance criterion that required it.
|
||||
- Do not mark the feature `done`; implementation results require review first.
|
||||
|
||||
## Progress Notes
|
||||
|
||||
Keep only concise current state, completed stage references, and blockers here.
|
||||
Git history and implementation commits should preserve detailed execution
|
||||
evidence.
|
||||
12
docs/roadmap/implementation.md
Normal file
12
docs/roadmap/implementation.md
Normal file
@@ -0,0 +1,12 @@
|
||||
# Implementation Plan
|
||||
|
||||
Status: pending
|
||||
|
||||
No implementation plan is currently active. Feature 0002 was completed in
|
||||
`ansible-role-audita` through commit `3a8c21f`; its durable scope and rationale
|
||||
remain in
|
||||
[the Feature 0002 roadmap](features/0002-audita-source-installation-and-configuration.md),
|
||||
and its review history remains in [the remediation record](remediation.md).
|
||||
|
||||
Select and approve the next feature roadmap before replacing this notice with
|
||||
a new staged implementation plan.
|
||||
@@ -50,17 +50,23 @@ role will manage the native configuration needed to connect to it.
|
||||
- Released roles build an explicitly selected application release tag.
|
||||
Development may override the selected revision with a branch or commit.
|
||||
- Source checkouts reside at `/usr/local/src/<app>` and are owned by `root`.
|
||||
- Roles build into a staging location, validate the result, and then install
|
||||
the binary at `/usr/local/bin/<app>` with `root:root` ownership and mode
|
||||
`0755`. A failed build must not replace a working installed binary.
|
||||
- Roles build and install the binary at `/usr/local/bin/<app>` with
|
||||
`root:root` ownership and mode `0755`, using the application's native build
|
||||
command and the simplest clear Ansible task flow.
|
||||
- Builds use the application repository's own build contract, including any
|
||||
application-specific version-injection linker flags. The common baseline is
|
||||
`GOWORK=off`, `GOTOOLCHAIN=local`, `CGO_ENABLED=0`, and `-trimpath`.
|
||||
- Build state must account for the checked-out commit, Go toolchain, and build
|
||||
arguments so that roles rebuild when a relevant input changes rather than
|
||||
relying only on the existence of the installed binary.
|
||||
- Each application role exposes variables for its repository, selected
|
||||
version or revision, source directory, binary path, and build settings.
|
||||
- Roles normally rebuild when the Git task reports a changed checkout or the
|
||||
binary is absent. An application-level version or smoke check may add a
|
||||
trigger only when its feature specification explicitly requires that
|
||||
production behavior. Roles do not maintain fingerprints, checksums, or
|
||||
sidecar build-state files for the MVP.
|
||||
- Each application role exposes variables only for meaningful consumer
|
||||
choices, normally including its repository, selected version or revision,
|
||||
source directory, binary path, dependency management, Go Snap channel, and a
|
||||
build-tool path when dependency opt-out permits another provisioning
|
||||
mechanism. Fixed details of the upstream build contract need not become
|
||||
public variables.
|
||||
|
||||
### Go toolchain
|
||||
|
||||
@@ -119,8 +125,11 @@ application-role releases in one source repository.
|
||||
|
||||
### Ansible dependencies and task structure
|
||||
|
||||
- The standalone application roles are self-contained and use
|
||||
`ansible.builtin` modules directly.
|
||||
- The standalone application roles are independently usable and prefer
|
||||
`ansible.builtin` modules where they directly fit the task.
|
||||
- `community.general` is treated as a stable, supported dependency. Roles may
|
||||
freely select its modules when appropriate, provided the collection
|
||||
dependency is declared and pinned for reproducible installation and tests.
|
||||
- The roles do not depend on the private
|
||||
`maximumdirect.core.ansible_role_loader` role used by the proof of concept.
|
||||
- Platform-specific task selection may be added later using ordinary Ansible
|
||||
@@ -128,6 +137,13 @@ application-role releases in one source repository.
|
||||
- Small amounts of repeated prerequisite or installation logic are acceptable
|
||||
during the MVP. A shared helper role or collection plugin should be
|
||||
introduced only if substantial, stable shared behavior emerges.
|
||||
- Ansible modules are trusted to implement their documented state transitions,
|
||||
idempotence, and change detection. Roles do not add preliminary existence
|
||||
checks, manual comparisons, or supplemental state around a module that
|
||||
already owns the desired behavior.
|
||||
- State gathering is appropriate only when it controls behavior outside the
|
||||
responsible module's contract, such as deciding whether an application
|
||||
binary must be rebuilt.
|
||||
|
||||
### Dependency and release reproducibility
|
||||
|
||||
@@ -210,6 +226,12 @@ remain to be designed.
|
||||
- Deploying or managing WhisperX
|
||||
- Versioned Narratio prompt-library releases and pinning
|
||||
- A role-managed scheduler or persistent Narratio service
|
||||
- Cryptographic artifact verification, supply-chain hardening, and protection
|
||||
against adversarial source or dependency infrastructure
|
||||
- Transactional binary replacement and preservation of the prior executable
|
||||
after a local build failure
|
||||
- Compiler-identity fingerprints, binary checksums, sidecar build-state files,
|
||||
and recovery from deliberately malformed or redirected managed paths
|
||||
|
||||
## Design Work Still Open
|
||||
|
||||
|
||||
134
docs/roadmap/remediation.md
Normal file
134
docs/roadmap/remediation.md
Normal file
@@ -0,0 +1,134 @@
|
||||
# Feature 0002 Remediation Review
|
||||
|
||||
Status: resolved
|
||||
|
||||
The Audita production task flow implements the approved architecture and the
|
||||
complete integration suite passes. The following residual issues should be
|
||||
corrected before Feature 0002 is accepted.
|
||||
|
||||
## Finding 1: Correct the Declared Role License
|
||||
|
||||
Severity: medium
|
||||
|
||||
`ansible-role-audita/meta/main.yml` declares `BSD-3-Clause`, but the
|
||||
repository's `LICENSE` file is CC0 1.0 Universal. Published role metadata must
|
||||
identify the license actually granted by the repository.
|
||||
|
||||
### Required Remediation
|
||||
|
||||
- Change `galaxy_info.license` to the Galaxy-compatible SPDX identifier
|
||||
`CC0-1.0`.
|
||||
- Do not replace or otherwise alter the existing license text.
|
||||
|
||||
### Validation
|
||||
|
||||
- `meta/main.yml` and `LICENSE` identify the same license.
|
||||
- Production-profile ansible-lint passes.
|
||||
|
||||
## Finding 2: Describe All Integration-Test Host Effects
|
||||
|
||||
Severity: low
|
||||
|
||||
`ansible-role-audita/README.md` says that the integration suite mutates only
|
||||
the three Audita paths and its private temporary directory. Default
|
||||
convergence also enables dependency management, so on a fresh supported host
|
||||
the suite may install Git through APT, refresh the APT cache, and install the
|
||||
Go Snap. The statement is therefore incomplete.
|
||||
|
||||
### Required Remediation
|
||||
|
||||
- State that the suite may install or converge Git and the Go Snap in addition
|
||||
to managing the listed Audita paths.
|
||||
- Retain the statement that temporary test-specific files are confined to the
|
||||
private temporary directory.
|
||||
|
||||
### Validation
|
||||
|
||||
- The README accurately describes package/Snap effects and managed filesystem
|
||||
paths.
|
||||
- The description agrees with `tests/integration` and the role defaults.
|
||||
|
||||
## Finding 3: Complete Binary-Type Verification
|
||||
|
||||
Severity: low
|
||||
|
||||
`tests/verify.yml` checks binary ownership, mode, and executability, but does
|
||||
not assert that `/usr/local/bin/audita` is a regular file. Stage 1 explicitly
|
||||
requires baseline verification of binary type and metadata. The production
|
||||
`file` task establishes this invariant, but the focused verification does not
|
||||
provide the planned evidence for it.
|
||||
|
||||
### Required Remediation
|
||||
|
||||
- Add an assertion for `audita_binary_metadata.stat.isreg` to the existing
|
||||
binary metadata check.
|
||||
- Do not add another probe or production task.
|
||||
|
||||
### Validation
|
||||
|
||||
- `tests/verify.yml` confirms regular-file type, ownership, mode, and
|
||||
executability from its existing `stat` result.
|
||||
- The integration suite passes.
|
||||
|
||||
## Finding 4: Synchronize Implementation Progress Tracking
|
||||
|
||||
Severity: low
|
||||
|
||||
Both implementation stages are annotated complete in
|
||||
`docs/roadmap/implementation.md`, at role commits `47f1852` and `d37f590`, but
|
||||
the plan remains `ready`, its progress notes still say execution is ready to
|
||||
begin, and `docs/status.md` still describes execution as the current activity.
|
||||
The recorded state should show that implementation is complete and remediation
|
||||
review is in progress.
|
||||
|
||||
The two workspace commits that added stage-completion annotations also diverge
|
||||
from the plan's instruction that the out-of-band executor leave workspace
|
||||
planning files unchanged. No implementation code was placed in the wrong
|
||||
repository, so this requires tracking cleanup rather than code movement.
|
||||
|
||||
### Required Remediation
|
||||
|
||||
- Set the plan to `in_progress` while findings remain open and replace its
|
||||
stale progress note with both completed stage commits and the current
|
||||
remediation state.
|
||||
- Update workspace status so Feature 0002 is `in_progress`, with implementation
|
||||
complete and remediation pending, and make review/remediation the current
|
||||
focus.
|
||||
- Do not mark Feature 0002 `done` until remediation is implemented and
|
||||
reviewed.
|
||||
|
||||
### Validation
|
||||
|
||||
- The plan's status, stage annotations, and progress notes describe one
|
||||
consistent state.
|
||||
- Workspace status agrees with the implementation and remediation records.
|
||||
- `git diff --check` passes in the workspace repository.
|
||||
|
||||
## Review Validation Evidence
|
||||
|
||||
The review ran the complete `ansible-role-audita/tests/integration` suite on
|
||||
Ubuntu 26.04 with Ansible Core 2.21.3 and ansible-lint 26.8.0. It passed syntax
|
||||
checking, production-profile lint, baseline and repeated convergence,
|
||||
missing-binary rebuilding, dependency opt-out with a caller-supplied Go
|
||||
executable, metadata repair without rebuilding, configuration-only
|
||||
convergence, alternate-checkout rebuilding, default restoration, native
|
||||
configuration validation, and all three platform-rejection cases.
|
||||
|
||||
The final state was default commit
|
||||
`a84941d68168a1ed9ea7423b6477ae8218be73f9`, a `root:root` mode `0755` binary,
|
||||
a `root:root` mode `0644` configuration, and native validation output
|
||||
`config is valid`. `bash -n tests/integration` and `git diff --check` also
|
||||
passed. All nested repository working trees remained clean.
|
||||
|
||||
## Resolution
|
||||
|
||||
All four findings were implemented and validated on 2026-09-08. The role now
|
||||
declares `CC0-1.0`, its README identifies dependency-management effects, and
|
||||
its existing binary `stat` result proves regular-file type. Workspace tracking
|
||||
records the completed and accepted feature. Role remediation was committed as
|
||||
`3a8c21f`.
|
||||
|
||||
Validation passed with the complete `tests/integration` suite,
|
||||
production-profile ansible-lint, `bash -n tests/integration`, and
|
||||
`git diff --check` in both changed repositories. The production task flow was
|
||||
not changed.
|
||||
@@ -1,10 +1,10 @@
|
||||
# Workspace Status
|
||||
|
||||
Last updated: 2026-09-07
|
||||
Last updated: 2026-09-08
|
||||
|
||||
Current milestone: MVP design and workspace foundation
|
||||
Current milestone: MVP standalone application roles
|
||||
|
||||
Current focus: Select the next open design topic before role implementation.
|
||||
Current focus: Select and define the next unit of work.
|
||||
|
||||
| ID | Deliverable | Owner | State | Evidence or next step |
|
||||
| --- | --- | --- | --- | --- |
|
||||
@@ -13,10 +13,12 @@ Current focus: Select the next open design topic before role implementation.
|
||||
| M0-03 | Tracked MVP roadmap | workspace | done | `docs/roadmap/mvp.md` established |
|
||||
| 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` |
|
||||
| M1-01 | Remaining MVP design decisions | workspace | ready | Select the next item from the roadmap |
|
||||
| M1-02 | Standalone application roles | role repositories | proposed | Begin after relevant interfaces are settled |
|
||||
| M1-01 | Remaining MVP design decisions | workspace | ready | Select the next design topic or application role |
|
||||
| M1-02 | Standalone application roles | role repositories | in_progress | Select the next standalone application role |
|
||||
| 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 | done | Implementation, integration coverage, and final remediation completed through `fb8dc41` |
|
||||
| F0002 | Install and configure Audita | ansible-role-audita | done | Implementation and remediation completed through `3a8c21f`; full integration suite passed |
|
||||
|
||||
## Updating This File
|
||||
|
||||
|
||||
31
requirements-dev.txt
Normal file
31
requirements-dev.txt
Normal 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
|
||||
Reference in New Issue
Block a user