docs: resolve contributing.md docstring/CI-enforcement wording (#104)

contributing.md contradicted conventions.md on whether public-method
docstrings are unconditionally required, and understated what CI
machine-checks vs. overview.md's finer breakdown. Per maintainer
ruling: docstring requirement is unconditional, and both sections now
link to their truth-home files instead of restating them.

Author: lesnik512

docs/dev/contributing.md

@@ -25,13 +25,15 @@ just test           # pytest with coverage
 - `ruff format` enforces formatting; do not hand-format.
 - Type-check with `ty` (Astral). Use `# ty: ignore[<rule>]` for suppressions, not `# type: ignore`.
 - Do NOT use `from __future__ import annotations`. Python 3.11+ is the floor.
-- Module docstrings are required; per-method docstrings only when types alone are insufficient.
+- Module, class, and public-method docstrings are required (PEP 257); see
+  [`architecture/conventions.md`](https://github.com/modern-python/httpware/blob/main/architecture/conventions.md).
 
 ## Architecture invariants
 
-These are project invariants. The CI lint pass (`just lint-ci` — `ruff` + `ty`)
-catches what the linters can see (e.g. `print()` via ruff `T201`); the rest are
-enforced in code review. Do not break them in pull requests:
+These are project invariants — see
+[`architecture/overview.md`](https://github.com/modern-python/httpware/blob/main/architecture/overview.md) for exactly which
+ones CI machine-checks, partially checks, or leaves to review. Do not break
+them in pull requests:
 
 - No `httpx2._*` (private API) usage anywhere in the library.
 - No `from __future__ import annotations`.

planning/audits/2026-07-13-docs-comments-audit.md

@@ -63,12 +63,14 @@ Verified against source: the `try/except Exception: raise DecodeError(...)` live
 `contributing.md`: `"Module docstrings are required; per-method docstrings only when types alone are insufficient."` (conditional)
 `conventions.md`: `"Module / class / public-method docstrings are required ..."` (unconditional)
 *Fix:* pick one policy and make both files say it — recommend keeping `conventions.md`'s unconditional wording since it's the capability truth home, and updating `contributing.md` to match.
+**Resolved** (`2026-07-13.08`) — maintainer ruled unconditional; `contributing.md` now links to `conventions.md` instead of restating.
 
 **I3 — `docs/dev/contributing.md:32-34` understates what CI machine-checks, vs `architecture/overview.md:9`.**
 `contributing.md`: `"The CI lint pass (...) catches what the linters can see (e.g. print() via ruff T201); the rest are enforced in code review."` — reads as "only `print()` is machine-checked."
 `overview.md`: documents two more checks contributing.md omits — `PGH003` (blanket `# type: ignore`) is machine-checked, and `SLF001` partially checks the `httpx2._` ban (attribute access, not import).
 This is a fresh drift, not a re-flag of the 2026-06-13 audit's I1 (that finding was about a since-removed "CI grep gates" phrase, already fixed) — `overview.md`'s finer breakdown was apparently added after `contributing.md`'s wording was last touched.
 *Fix:* replace `contributing.md`'s "the rest are enforced in code review" with the same three-tier breakdown `overview.md` uses (machine-checked / partially-checked / review-only), or have it link to `overview.md` instead of restating.
+**Resolved** (`2026-07-13.08`) — maintainer ruled link-instead-of-restate, per the repo's truth-home principle.
 
 **I4 — `docs/testing.md:110` says `httpx` where it means `httpx2`.**
 `"MockTransport is the public test seam in httpx — supported by the maintainers, stable across versions ... respx patches private internals and has historically broken across httpx major versions."`
@@ -98,14 +100,12 @@ Same argument, ~3 near-identical sentences in each. Bundle this cleanup with the
 - **`2026-07-13.07-docs-comments-audit-fixes`** (lightweight) — fixes C1, C2,
   I1, I4. Verified against source; `just lint-ci`, `mkdocs build --strict`,
   and `just test` (780 passed, 100% coverage) all clean.
+- **`2026-07-13.08-contributing-docstring-ci-wording`** (lightweight) — fixes
+  I2, I3 per maintainer ruling (unconditional docstrings; link instead of
+  restate). Verified: `mkdocs build --strict`, `just lint-ci` clean.
 
 ## Deferred / next steps
 
-- **Needs your call:** I3's fix direction (restate the three-tier breakdown in
-  `contributing.md`, or replace it with a link to `overview.md`) and I2's
-  policy choice (unconditional vs conditional method-docstring requirement) —
-  both are wording contradictions where either side could be "the fix,"
-  not a clear code-vs-doc mismatch. Not yet scheduled.
 - **Compaction:** D1 (`ResponseTooLargeError` triplication) and D2 (bundled
   with I4's `httpx`/`httpx2` fix — the "why not respx" duplication itself
   wasn't touched by `2026-07-13.07`, only the terminology slip within it) are

planning/changes/2026-07-13.08-contributing-docstring-ci-wording.md

@@ -0,0 +1,41 @@
+---
+summary: Fixed 2 verified wording contradictions from the docs-and-comments audit — contributing.md's docstring requirement now matches conventions.md (unconditional), and its CI-enforcement claim links to overview.md instead of restating a stale subset.
+---
+
+# Change: Resolve contributing.md wording contradictions (I2, I3)
+
+**Lane:** lightweight — 1 file, docs-only, no code, no public-API change.
+
+Spec: [`planning/audits/2026-07-13-docs-comments-audit.md`](../../audits/2026-07-13-docs-comments-audit.md)
+(findings I2, I3). Both were policy-wording calls, not code-vs-doc mismatches,
+resolved by the maintainer:
+
+- **I2** — `contributing.md` said per-method docstrings are required "only
+  when types alone are insufficient"; `conventions.md` says public-method
+  docstrings are unconditionally required. Maintainer ruling: unconditional
+  wins — `conventions.md` is the capability truth home.
+- **I3** — `contributing.md` implied only `print()` is CI-machine-checked;
+  `overview.md` documents a finer 3-tier breakdown (machine-checked /
+  partially-checked / review-only). Maintainer ruling: link instead of
+  restate, per the repo's own truth-home principle (the same one D1/D2 in the
+  audit flagged when violated the other way).
+
+## Approach
+
+`docs/dev/contributing.md`'s "Code style" and "Architecture invariants"
+sections now point at `architecture/conventions.md` and
+`architecture/overview.md` respectively instead of carrying their own
+(drifted) copies of the same facts.
+
+## Files
+
+- `docs/dev/contributing.md` — I2 docstring-requirement line now unconditional
+  + links to `conventions.md`; I3 CI-enforcement paragraph now links to
+  `overview.md` instead of restating a stale subset.
+
+## Verification
+
+- [x] `mkdocs build --strict` succeeds (relative links resolve).
+- [x] `just lint-ci` — clean.
+- [x] Final read-through — no residual "only when types alone are
+      insufficient" / "the rest are enforced in code review" wording remains.