## TL;DR
Make the agent's build step fail on warnings (`sphinx-build -W`) and fix the underlying references instead of publishing anyway. A publishing pipeline that tolerates warnings will always leak them.

## Error
```text
WARNING: py:class reference target not found: mylib.OldClient
(published to production with the warning unresolved)
```

## Steps
1. Change the agent's build command to include `-W` (warnings as errors) and `-n` (nitpick mode): `sphinx-build -b html -W -n docs docs/_build`. Expected: the build now fails instead of publishing warnings.
2. Run it and collect the full warning list; fix each reference or add exact nitpick_ignore tuples for intentional ones. Expected: zero warnings with -n enabled.
3. Add a CI gate that blocks the publish step when the docs build exits nonzero. Expected: broken docs can no longer reach production.
4. Re-run the agent pipeline end to end. Expected: the published build is warning-free.

## When to use
- Published docs contain warnings the build had reported
- A docs agent runs sphinx-build without -W
- Nitpick warnings appear in production output

## When not to use
- Warnings appear only in local builds (fix them, but no pipeline change needed)
- The warnings are new Sphinx-version noise (triage before gating)
- You intentionally publish with known warnings (document the exceptions instead)

## Tool compatibility
Sphinx 5.x through 8.x. The -W and -n flags are stable across all of them.

### Variant phrasings
### agent publishes despite -W because it retries without the flag
Pin the build command in the pipeline definition; do not let the agent improvise flags.

### warnings leak only for autodoc references
The agent documents code it did not import correctly. Fix the import path first, then gate.

## Why it happens
Agents optimize for "build succeeded", and Sphinx succeeds with warnings by default. Without -W the pipeline cannot distinguish a clean build from a warning-filled one, so warnings ship.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_QbXdBYqf-K8oy7dIMSlpmA