Merge pull request #248 from UCD-SERG/claude/happy-franklin-6itw7g

Document required relationship arg on dplyr joins

Author: d-morrison

.github/copilot-instructions.md

@@ -556,6 +556,7 @@ expect_false(has_missing_values(complete_data))
 - **Use tidy-selection, not data-masking, in selection contexts**: In `select()`, `rename()`, `summarize(.by = )` / `group_by()`, `across(.cols = )`, `pivot_*(names_from = )`, and join `by =`, select columns named by a variable with `all_of()` / `any_of()` (e.g. `select(any_of(c("a", "b", "new_name" = var)))`), and use bare names or `all_of()` in `.by`. Do **not** reach for the `.data` pronoun (`.data[[var]]`, `.data$x`) there — that pronoun belongs in *data-masking* verbs (`mutate()`, `filter()`, `summarize()` expressions). Using `.data[[var]]` in a selection context is a *soft* deprecation and may not warn at runtime, so it is easy to miss — but it should be rewritten.
 - **Collapse branching that only varies columns**: An `if`/`else` whose only job is to change which columns are selected, renamed, or joined can almost always be replaced by a single `any_of()` / `all_of()` selection or a single tidyselect-keyed join. Prefer one parameterized pipeline over two near-identical stratified/unstratified branches.
 - **Prefer dplyr joins over base `merge()`**: Use `dplyr::left_join()` / `right_join()` with `by = join_by(...)` rather than `merge()` for readability and consistency.
+- **Always set `relationship` on dplyr joins**: Every `dplyr::*_join()` call (`left_join()`, `right_join()`, `inner_join()`, `full_join()`) must specify the `relationship` argument (e.g. `relationship = "many-to-one"`). Declaring the expected cardinality documents the join's intent and makes an unexpected many-to-many match fail loudly instead of silently duplicating rows. Filtering joins (`semi_join()` / `anti_join()`) are out of scope — they cannot duplicate rows. See [PR #240](https://github.com/UCD-SERG/serodynamics/pull/240/changes#diff-58597f8513171a9da41d8e6c89e4230df8879139a10dd2422aa659aa496dd29eR52-R58) for an example.
 
 ### Review focus: convoluted / non-idiomatic code
 

.lintr.R

@@ -49,6 +49,13 @@ snake_case_ACROs1 <- rex::rex(
   end
 )
 
+# Note: dplyr `*_join()` calls must specify the `relationship` argument
+# (e.g. `relationship = "many-to-one"`) so that an unexpected
+# many-to-many match errors out instead of silently duplicating rows.
+# lintr has no built-in linter for "missing argument", so this rule is
+# enforced via code review rather than automatically here; see the
+# contributor guidance in CLAUDE.md and .github/copilot-instructions.md.
+
 linters <- lintr::linters_with_defaults(
   return_linter = NULL,
   trailing_whitespace_linter = NULL,

CLAUDE.md

@@ -42,6 +42,17 @@ form. Treat these as in-scope review findings, not optional nits:
   `right_join()` with `by = join_by(...)` for clarity and consistency
   with the rest of the codebase.
 
+- **dplyr `*_join()` calls must set `relationship`.** Flag any
+  `dplyr::left_join()` / `right_join()` / `inner_join()` / `full_join()`
+  that omits the `relationship` argument. Stating the expected
+  cardinality explicitly (e.g. `relationship = "many-to-one"`) makes the
+  join's intent clear and turns an unexpected many-to-many match into an
+  error instead of a silent row explosion. Filtering joins
+  (`semi_join()` / `anti_join()`) are out of scope here — they return at
+  most one row per left-hand row and so cannot duplicate rows. See
+  [PR #240](https://github.com/UCD-SERG/serodynamics/pull/240/changes#diff-58597f8513171a9da41d8e6c89e4230df8879139a10dd2422aa659aa496dd29eR52-R58)
+  for an example.
+
 - **Near-duplicate stratified / unstratified paths.** Prefer one
   parameterized pipeline over two near-identical branches.
 

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: serodynamics
 Title: What the Package Does (One Line, Title Case)
-Version: 0.0.0.9058
+Version: 0.0.0.9059
 Authors@R: c(
     person("Peter", "Teunis", , "p.teunis@emory.edu", role = c("aut", "cph"),
            comment = "Author of the method and original code."),

NEWS.md

@@ -1,5 +1,10 @@
 # serodynamics (development version)
 
+* Documented in `CLAUDE.md`, `.github/copilot-instructions.md`, and a
+  note in `.lintr.R` that `dplyr::*_join()` calls must specify the
+  `relationship` argument (for example `relationship = "many-to-one"`),
+  so an unexpected many-to-many match errors out instead of silently
+  duplicating rows.
 * The test suite now sets `options(lifecycle_verbosity = "error")` (via
   `tests/testthat/setup.R`), so tidyverse lifecycle deprecations -
   including soft deprecations such as using the `.data` pronoun in a