docs(deps): correct the stale protobuf instruction and drop the orphaned markdown declaration (#15600, #15622)

[mrveiss]

Closes #15600, #15622

Thinking Path

Both issues are the same defect in two places: a dependency record that no
longer describes the tree. #15622 is a doc telling you not to do something the
tree did months ago; #15600 is a manifest line declaring a package nothing
installs. Neither is a code change, both are corrections to the project's
account of its own dependencies, and both were settled by the same instrument —
reading the metadata pip actually resolved into the deployed venvs rather than
reasoning from manifests. One branch, one CI run.

#15600 was not treated as a reflex removal. #15551 established the trap: nltk
looked identically removable — unimported, declared twice — but llama-index
requires it transitively, so deleting the declaration would have left it
installed and unpinned, strictly worse. So markdown had to be disproved, not
assumed:

• The deployed venvs hold 343 distinct distributions — pip's own resolution
  output, not a manifest. markdown is in none of them.
• Every Requires-Dist: markdown* line across those 343 is a different
  distribution (markdown-it-py, markdown2) or an extra nothing selects
  (markdown~=3.4 ; extra == "compare").
• The instrument was validated against the known-correct answer: the same scan
  finds Requires-Dist: nltk>=3.9.3 on llama-index 0.14.24 and
  llama-index-core. It reproduces chore(deps): nltk is declared in two manifests but imported nowhere — remove it rather than carry a permanent allowance #15551's verdict, then returns the opposite
  one for markdown.
• The evidence gap was closed rather than waved at: exactly 9 CI-declared
  packages are absent from deployment (llama-index-readers-file,
  detect-secrets, mouseinfo, opencv-python, playwright, pre-commit,
  pyautogui, pycryptodome, pygetwindow). Their full transitive closure was
  walked from published metadata — 29 nodes, no unreachable metadata, extras
  excluded — and reaches markdown nowhere.

So removal unpins nothing, which is precisely why the nltk outcome does not
apply. The reasoning is recorded at the line the way nltk's is, so the next
reader inherits the verdict instead of re-deriving it.

#15622 was not treated as a digit bump. The doc's instruction was "do not
raise the cap until grpcio/opentelemetry support protobuf 7." Checking whether
the reasoning still holds at the new cap turned up two things:

1. grpcio was never a constraint. Both deployed grpcio versions declare
   zero Requires-Dist: protobuf lines. The original instruction told
   readers to wait on a package that was never gating.
2. The cap is a mirror, not a judgement. opentelemetry-proto declares
   protobuf<8.0,>=5.0 and googleapis-common-protos declares
   protobuf<8.0.0. The cap read <7.0.0 because those packages said <7; it
   reads <8.0.0 because they now say <8.

That is the difference between the right number and the right reason, so the doc
now states the rule — the ceiling copies the lowest upper bound protobuf's
consumers declare, and is raised only when they publish a higher one — and tells
the reader to check their metadata rather than trust the sentence, because that
sentence is what went stale last time. A doc that records the digit fails again
at protobuf 9.

What Changed

• requirements-ci/document.txt — removed markdown==3.10.3; replaced with
  the verdict and the evidence that settled it, mirroring the adjacent nltk note.
• docs/developer/DEPENDENCY_BUMP_AUDIT.md — retitled DISCHARGED and
  marked historical, since re-checking found all three deferred rows have
  landed, not just protobuf (AC2): protobuf → >=7.36.0,<8.0.0, reportlab →
  >=5.0.1, structlog → >=26.1.0. The "Recommended upgrade order" — which
  listed protobuf as blocked — is gone, since it described work already done.
  Added the durable cap rule and the correction of the grpcio claim.
• .github/dependabot.yml — two comments asserted in the present tense that
  the manifest pins protobuf>=7.35.1,<8.0.0; it pins >=7.36.0. Corrected, and
  the dangling note "the stale <7.0 rationale is raised separately for
  confirmation" now records the confirmation instead of pointing at open work.
  Comments only — versions: [">=8.0.0"] was already correct and is untouched.

Verification

• Guard: ansible_requirements_parity_test.py / ansible_pip_parity_baseline.txt —
  unaffected, and checked rather than assumed. The baseline is bidirectional, so
  a removal that changed a divergence would fail as loudly as a new one. markdown
  is declared at no ansible pip site (the only tree-wide markdown: hit is
  docs/_config.yml's Jekyll kramdown setting), so it never diverged, has no
  baseline entry, and none goes stale. The baseline still holds zero entries.
• Guard: declared_distributions.py — the removal drops the declared set by
  exactly one. Re-measured with a standalone replica of the oracle's algorithm
  (same glob patterns, same -r/-c include closure): 39 files, 200
  distributions, against the floor of 180 asserted in
  declared_distributions_test.py:94. No count floor is approached.
• No guard depends on markdown — zero real imports tree-wide (import markdown / from markdown / importorskip); every hit in repo_tests/,
  tools/ and .github/workflows/ is the English word or a --format markdown
  CLI flag.
• Doc retitle is safe — nothing in the repo references
  DEPENDENCY_BUMP_AUDIT by path or heading.
• dependabot.yml still parses — validated as YAML; 23 update blocks, the
  count before the edit.
• Pre-commit hooks ran clean on all three commits; no --no-verify.
• Per the repo rules, nothing was installed and no repo code was executed as an
  application; the venv evidence is read-only metadata, and CI is the authority.

Model Used

Claude Opus 5 (1M context)

---

Two discoveries filed rather than dropped, both deliberately out of scope here:

• chore(deps): structlog floors in the Windows NPU worker and the local-setup guide sit 2-3 majors below the tree's >=26.1.0 #15645 — structlog floors in the Windows NPU worker (>=23.2.0) and the
  local-setup guide (>=24.0.0) sit 2-3 majors below the >=26.1.0 the rest of
  the tree declares. Surfaced by this PR's AC2 check on the structlog row.
  Excluded because raising a floor in a separately deployed component is an
  install-behaviour change, not a documentation correction.
• docs(deps): DOCKER_MIGRATION_NOTES.md is a 2025-08 planning snapshot whose pins and rationales no longer describe the tree #15646 — docs/deployment/DOCKER_MIGRATION_NOTES.md is a 2025-08 planning
  snapshot whose pins are uniformly stale, including protobuf==5.29.5 (causes tensorflow conflicts) — a rationale requirements.txt explicitly records as
  debunked and removed in bug(deps): protobuf version incompatibility with chromadb opentelemetry dependencies #3971. Found by checking whether other docs restated
  the cap. Excluded because correcting one pin among a dozen equally stale ones
  is worse than leaving the file uniformly dated.

[github-actions]

✅ SSOT Configuration Compliance: Passing

🎉 No new hardcoded values of either class — ssot and other both block.

Known backlog in pipeline-scripts/hardcoded_values_baseline.txt is suppressed and tracked in #14371.