ansible-workspace-dnd/docs/conventions.md

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.

Application Configuration Interfaces

• Expose application configuration through documented, field-specific role variables suitable for host_vars, group_vars, play variables, and composing roles.
• Give structurally required fields concrete defaults. Define optional application settings as null unless the role intentionally owns the corresponding policy.
• Treat a null optional variable as "omit this field from the rendered configuration." Do not copy documented upstream defaults into role defaults merely to write them back to the application.
• Let the application supply its built-in defaults for omitted fields. This avoids freezing a duplicate defaults database in Ansible and permits upstream default changes to take effect naturally.
• Use is not none when conditionally rendering optional values. Do not use truthiness, because false, zero, an empty string, or an empty collection may be an intentional value.
• Emit a nested configuration section only when at least one of its descendant variables is non-null.
• Serialize strings and collections with appropriate Ansible or Jinja filters. Do not construct YAML quoting manually.
• Keep argument specifications aligned with the public variables. Optional nullable variables are not required; use a permissive type only when the native application accepts more than one scalar type.
• Prefer one field-specific interface. Do not provide a parallel raw mapping, template override, or merge mechanism unless a concrete requirement defines its precedence and behavior.
• Application roles expose native configuration choices. The suite-level role supplies cross-application and deployment-specific policy through those variables.
• Manage the resulting file with one ordinary ansible.builtin.template task. Do not add configuration assembly facts, preliminary file inspection, or production validation unless independently required.
• Tests should prove the minimal default document, representative rendering across all sections, omission of null fields, preservation of intentional falsey values, native configuration validity, and repeated convergence.

Role defaults define what Ansible intends to manage, not a mirror of every application default. A concrete default means the role deliberately owns that policy; a null default leaves the policy with the application.