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