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

Plan pipeline operator enrollment

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-18 12:44:26 +00:00
parent eda361fa5d
commit a5bc701f60
4 changed files with 616 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

362
docs/roadmap/implementation.md
View File

@@ -1,8 +1,360 @@
# Implementation Plan
# Implementation Plan 0014: Enroll Existing Pipeline Operators
Status: pending
Status: ready
Feature 0013 is complete. There is no active implementation plan.
Target executor: GPT-5.6-Terra
Select the next unit of work and agree on its numbered feature roadmap before
replacing this notice with a staged implementation plan.
Feature roadmap:
`docs/roadmap/features/0014-existing-pipeline-operator-enrollment.md`
Active plan location: `docs/roadmap/implementation.md`
## Objective
Add one empty-by-default pipeline interface that enrolls explicitly selected
existing human accounts in the suite's runtime group. Implement the behavior
with one account-existence lookup and one additive membership task, adapt the
existing operator integration scenario, and import the reviewed result into
the collection from public Gitea.
The Feature 0014 roadmap remains authoritative for scope, rationale, target
state, and acceptance criteria. This plan does not authorize human-account
creation or removal, exact-list reconciliation, filesystem-policy changes, or
a new release.
## Execution Rules
- Execute stages in numeric order.
- Before each stage, confirm its preconditions and the working-tree state of
its owning repository.
- Before each stage, reread every document listed in that stage's Required
Policy Review. Do not rely on policy recalled from an earlier stage.
- Preserve unrelated and pre-existing changes. Stop and report unexpected
worktree changes or branch divergence rather than overwriting them.
- Do not make unresolved product or architecture decisions during execution;
stop and report the decision required.
- Keep the production behavior to the roadmap's exact direct task flow: one
`ansible.builtin.getent` loop followed by one `ansible.builtin.user` loop.
- Do not add an assertion, registered fact, handler, command, shell operation,
explicit empty-list condition, membership comparison, post-change query,
sidecar state, or account abstraction.
- Trust `getent` to fail for a missing key and `user` to converge additive
membership. Do not reproduce either module's checks.
- Test the public behavior by adapting the existing temporary-operator
scenario. Do not add a missing-user test, inspect `/etc/passwd` or
`/etc/group`, assert task results, or duplicate the detailed test in the
collection.
- Run each stage's validation before committing it. Do not proceed after a
validation failure.
- Commit each completed stage with the stated plain-English intent. Push the
authoritative pipeline commit before importing it into the collection.
- Use only the public Gitea pipeline URL for the subtree update; do not import
from the local sibling repository.
## Starting State and Preconditions
- Features 0009, 0011, 0012, and 0013 are complete.
- This roadmap and implementation plan have been reviewed and committed in the
workspace repository before execution begins.
- The completed Feature 0013 closeout commits `eda361f` in the workspace and
`5e695f3` in the collection are pushed to their respective `origin/main`
branches before implementation begins. Preserve the Git-generated subtree
squash commit that accompanies `5e695f3`.
- `ansible-role-dnd-pipeline` starts clean on `main` at `78afffe`, equal to
`origin/main`.
- `ansible-collection-dnd` starts clean on `main` at `5e695f3`, equal to
`origin/main` after the prerequisite push.
- The workspace `.venv` supplies the tested `ansible-playbook`,
`ansible-galaxy`, and `ansible-lint` commands used by the repository test
drivers.
- The local host remains the approved Ubuntu 26.04 proxy, and passwordless
test-time sudo is available for the existing integration fixtures.
- Git credentials can push the pipeline and collection commits to their public
Gitea origins.
## Repository Scope
- `ansible-role-dnd-pipeline` owns the variable, argument specification,
account lookup, additive enrollment task, README, and detailed integration
behavior.
- `ansible-collection-dnd` receives the reviewed pipeline commit only through
its established squashed subtree and validates the assembled artifact.
- `ansible-workspace-dnd` records implementation progress and the review
handoff after the two implementation repositories are complete.
- All standalone application-role repositories, application source
repositories, asset repositories, and `rakestraw-ansible` are out of scope
and must remain unchanged.
## Stage 1: Implement Existing-Operator Enrollment
### Objective
Give the standalone pipeline role its minimal public interface for enrolling
existing human accounts and prove the behavior through the existing operator
integration scenario.
### Required Policy Review
Before beginning this stage, read:
- `AGENTS.md`
- `docs/orientation.md`
- `docs/conventions.md`
- `docs/ansible.md`
- `docs/testing.md`
- `docs/planning.md`
- `docs/roadmap/features/0014-existing-pipeline-operator-enrollment.md`
### Preconditions
- The workspace planning commit is present.
- `ansible-role-dnd-pipeline` is clean at `78afffe` on `main`, is not behind
or diverged from `origin/main`, and contains no unrelated changes.
- Its Narratio dependency still creates the selected runtime group before the
pipeline role's ordinary tasks execute.
- The existing integration driver still contains the temporary operator and
representative group-access scenario described by the roadmap.
### Owning Repository
`ansible-role-dnd-pipeline`
### Required Changes
1. Add `dnd_pipeline_operator_users: []` beside the existing runtime identity
defaults in `defaults/main.yml`.
2. Add the matching `meta/argument_specs.yml` entry with `type: list`,
`elements: str`, and the same required/default-backed convention used by
the role's other public variables.
3. Add one unprivileged `ansible.builtin.getent` task near the beginning of
`tasks/main.yml`. Loop directly over `dnd_pipeline_operator_users`, use the
`passwd` database and each username as `key`, and rely on the module's
default missing-key failure. Do not register its result or add a separate
assertion.
4. Immediately follow it with one `become: true` `ansible.builtin.user` task
over the same list. Set `name` to the selected account,
`groups` to `dnd_pipeline_runtime_group`, `append: true`, and
`state: present`. Do not set or manage any other account property.
5. Revise the README variable reference and shared-execution section. Replace
the consumer-owned membership example and deferred wording with the new
interface, existing-account prerequisite, additive non-removal behavior,
authorization consequence, and new-login-session caveat.
6. Adapt `tests/integration` rather than adding another scenario. Create its
temporary operator before the initial role application without membership
in the runtime group, pass that username through
`dnd_pipeline_operator_users` for the baseline and repeated applications,
and retain the existing native configuration, secret-boundary, and shared
cache exercises under that identity. Reorder cleanup as necessary so any
final baseline convergence occurs while the selected fixture account still
exists, then remove the fixture account.
7. Retain the existing clean-repeat assertion. Do not add a negative
missing-user case or assertions about module internals, task traces, the
current default value, or raw account database entries.
8. Run the complete existing repository validation, commit the result, push
`main` to the public pipeline origin, and record the full pushed commit for
Stage 2.
### Validation
Run from the workspace root:
```text
(cd ansible-role-dnd-pipeline && tests/integration && git diff --check)
```
Expected result: syntax and production-profile lint pass; the temporary
existing account is enrolled through the public role variable and completes
the existing representative operator-access scenario; native application
checks pass; the immediate identical role application reports `changed=0`
and `failed=0`; and no credential value appears in test output.
### Completion Criteria
- The public interface, argument specification, two direct tasks, and README
implement exactly the roadmap contract.
- The existing operator scenario uses the role interface rather than fixture
group enrollment.
- The full standalone integration suite and `git diff --check` pass.
- The role repository is clean after a plain-English commit.
- The exact commit is present on public `origin/main` and its full hash is
available for the collection import.
### Commit
Commit intent: `Add optional pipeline operator enrollment`
## Stage 2: Import the Reviewed Pipeline Change
### Objective
Expose the reviewed operator interface through `rakestraw.dnd.pipeline` while
preserving the authoritative-standalone-repository and collection-artifact
boundaries.
### Required Policy Review
Before beginning this stage, read:
- `AGENTS.md`
- `docs/orientation.md`
- `docs/conventions.md`
- `docs/ansible.md`
- `docs/testing.md`
- `docs/planning.md`
- `docs/roadmap/features/0014-existing-pipeline-operator-enrollment.md`
- `ansible-collection-dnd/README.md`
### Preconditions
- Stage 1 is complete and its exact commit is publicly reachable from
`https://gitea.maximumdirect.net/eric/ansible-role-dnd-pipeline.git`.
- `ansible-collection-dnd` is clean at `5e695f3` on `main`, is not behind or
diverged from `origin/main`, and contains no unrelated changes.
- The collection's current `roles/pipeline` subtree still corresponds to the
authoritative pipeline history through `78afffe`.
### Owning Repository
`ansible-collection-dnd`
### Required Changes
1. Set a shell variable to the full pushed Stage 1 commit hash and run the
documented remote-only update from the collection repository:
```text
pipeline_revision=<FULL_PUSHED_STAGE_1_COMMIT>
git subtree pull --prefix=roles/pipeline \
https://gitea.maximumdirect.net/eric/ansible-role-dnd-pipeline.git \
"$pipeline_revision" --squash -m "Import pipeline operator enrollment"
```
2. Do not edit role behavior directly beneath `roles/pipeline`. The subtree
import should carry the new default, argument specification, tasks, README,
and standalone tests faithfully.
3. Do not change `galaxy.yml`, dependency manifests, collection-level tests,
or release documentation. No dependency or published version changes in
this feature, and the detailed behavior remains covered by Stage 1.
4. Run the existing collection integration suite against the built and
installed artifact. Commit no additional files after the subtree command
unless validation exposes a genuine collection-boundary issue within this
feature's scope.
5. Push the resulting collection history to `origin/main` and record the
resulting merge commit and Git-generated squashed subtree commit.
### Validation
Run from the workspace root:
```text
(cd ansible-collection-dnd && tests/integration && git diff --check)
```
Expected result: the collection builds; the archive contains the updated
pipeline role while retaining its development-file exclusions; isolated
dependency and artifact installation succeeds; the FQCN resolves; native
representative application checks pass; and the immediate repeat reports
`changed=0` and `failed=0`.
### Completion Criteria
- Git history records a squashed subtree import from the exact public Stage 1
commit with the stated plain-English merge message.
- No pipeline behavior was authored directly in the collection.
- The existing collection suite and `git diff --check` pass without an
unnecessary duplicate operator test.
- The collection is clean and its new history is present on `origin/main`.
### Commit
Commit intent: `Import pipeline operator enrollment`
The subtree command creates the stage's merge commit and its generated squash
commit; do not add an empty or redundant manual commit.
## Stage 3: Record the Implementation Handoff
### Objective
Record the completed implementation evidence without marking Feature 0014
done before independent review.
### Required Policy Review
Before beginning this stage, read:
- `AGENTS.md`
- `docs/orientation.md`
- `docs/conventions.md`
- `docs/planning.md`
- `docs/roadmap/features/0014-existing-pipeline-operator-enrollment.md`
### Preconditions
- Stages 1 and 2 are complete, committed, pushed, and validated.
- Their full commit hashes and validation results are available.
- The workspace repository is clean apart from the expected progress-record
edits for this stage and is not behind or diverged from `origin/main`.
### Owning Repository
`ansible-workspace-dnd`
### Required Changes
1. Change Feature 0014's roadmap status and status-table state to
`in_progress`, indicating implementation is complete but independent review
remains outstanding.
2. Update the workspace current focus and Feature 0014 evidence with the exact
pipeline and collection commit hashes and the validation completed.
3. Replace this plan's Progress Notes with a concise record of the three stage
states and their commits. Do not copy command logs into the repository.
4. Do not mark the feature `done`, remove the active plan, or create
`docs/roadmap/remediation.md`; those are review and closeout decisions.
5. Commit the workspace handoff record with the stated plain-English message.
### Validation
Run from the workspace root:
```text
./scripts/status
git diff --check
```
Expected result: every repository is clean; the pipeline and collection are
not ahead of or behind their origins; only the workspace handoff commit may be
ahead of `origin/main`; and the dashboard points to the exact implementation
evidence while retaining independent review as the next step.
### Completion Criteria
- Workspace status accurately identifies Feature 0014 as implemented and
awaiting review.
- The roadmap remains the durable target-state record and is not polluted with
execution logs.
- The active plan records concise implementation evidence and contains no
false completion claim.
- The workspace repository is clean after the handoff commit.
### Commit
Commit intent: `Record pipeline operator enrollment implementation`
## Final Validation and Handoff
- Confirm Stage 1's complete standalone integration result and Stage 2's
complete collection integration result.
- Run `./scripts/status` and confirm every repository is clean, with no
unexpected branch divergence or untracked artifact.
- Report the full pipeline, collection merge, collection subtree-squash, and
workspace handoff commit hashes.
- Summarize any deviation from this plan, unresolved finding, or added
implementation complexity and identify the acceptance criterion that
required it.
- Do not mark Feature 0014 `done`; implementation results require independent
review first.
## Progress Notes
- Planning complete; implementation has not started.