# 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.
- Before each stage, read 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.
- 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.

### Required Policy Review

Before beginning this stage, read:

- `AGENTS.md`
- `docs/orientation.md`
- `docs/conventions.md`
- `<docs/ansible.md, docs/testing.md, and/or docs/planning.md as applicable>`

Replace the placeholder with every specialized policy applicable to this
stage. Include `docs/ansible.md` for Ansible design or implementation,
`docs/testing.md` for test work, and `docs/planning.md` for workspace planning
or progress management. Do not list an inapplicable policy merely for
completeness.

### 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.