Revise the Seriatim plan and workspace conventions

docs/conventions.md

@@ -0,0 +1,49 @@
+# 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.
+- Trust the documented contract of each Ansible module, including its
+  idempotence and change detection.
+- Gather state only when the result controls necessary behavior that the
+  responsible module cannot determine. Fingerprints, checksums, sidecar state,
+  manual drift detection, and speculative recovery paths require an explicit
+  acceptance criterion and rationale. Do not precede a declarative module with
+  a probe or recreate its internal logic unless a concrete requirement cannot
+  be expressed by the module itself.
+- 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.