docs(telemetry): document the hook/plugin span-production rule and enforce it (Epic #929) #1464

Parent epic: #929
Phase: cross-cutting (do before #1142 starts)
Depends on: nothing
Blocks: #1466

Problem

Mellea has a hard rule about how spans are produced — library code fires a hook,
and a plugin in mellea/telemetry/tracing_plugins.py turns that hook into a
span. Library code never opens spans itself. That rule is nowhere written down,
and nothing enforces it, so it keeps being broken by people acting in good faith.

The history matters, because it explains why "just read the docs" is not
currently an answer:

1. Until refactor(telemetry)!: move backend tracing onto plugin/hook pattern #1181 (2026-06-10, refactor(telemetry)!), calling the span helpers
   directly from library code was the pattern. All five backends contained a
   bare span = start_generate_span(...), with the supporting machinery in
   mellea/telemetry/backend_instrumentation.py.
2. refactor(telemetry)!: move backend tracing onto plugin/hook pattern #1181 moved span production onto hooks and plugins and deleted that module.
   This was the right change.
3. refactor(telemetry)!: move backend tracing onto plugin/hook pattern #1181 rewrote around 97 lines of docs/docs/observability/tracing.md — and
   that page still contains no occurrence of the word "plugin". It documents
   which spans exist and what attributes they carry, never how a span comes to be
   produced.
4. There is no import contract, so reintroducing the pre-refactor(telemetry)!: move backend tracing onto plugin/hook pattern #1181 pattern is
   invisible to CI.
5. The only in-code example of importing telemetry.tracing is
   mellea/stdlib/session.py, which is a deliberate, documented exception
   (OTel Token attach/detach is task-affine). Anyone using it as a template
   copies the exception rather than the pattern.
6. Six weeks after refactor(telemetry)!: move backend tracing onto plugin/hook pattern #1181, docs/dev/adapter_observability.md was written and
   describes the pre-refactor(telemetry)!: move backend tracing onto plugin/hook pattern #1181 approach, naming start_backend_span /
   start_action_span as the model to mirror.
7. feat(backends): LocalFileBinding implements verbs (PEFT/aLoRA path) + from_catalog() (Epic #929 Phase 2) #1141 followed that document, and produced spans inline inside
   mellea/backends/. They are being removed in PR feat(backends): LocalFileBinding implements verbs (PEFT/aLoRA path) + from_catalog() (Epic #929 Phase 2) #1454.

Two live consequences:

• docs/dev/adapter_observability.md still instructs the next implementer to do
  the same thing.

• feat(backends): EmbeddedBinding implements apply_activation (Granite Switch path); remove render_controls + set_request_adapter (Epic #929 Phase 2) #1142's telemetry acceptance criteria mandate the same defect. feat(backends): EmbeddedBinding implements apply_activation (Granite Switch path); remove render_controls + set_request_adapter (Epic #929 Phase 2) #1142 is now
  unblocked, specified spans "under the intrinsic.call parent", and names tests
  (test_prepare_span_binding_type_is_embedded,
  test_activate_span_has_controls_key). Whoever picks it up will reproduce
  feat(backends): LocalFileBinding implements verbs (PEFT/aLoRA path) + from_catalog() (Epic #929 Phase 2) #1454's problem by following the issue as written.

  Partly addressed, 2026-08-11. feat(backends): EmbeddedBinding implements apply_activation (Granite Switch path); remove render_controls + set_request_adapter (Epic #929 Phase 2) #1142 has since been rescoped (apply_activation,
  no lifecycle verbs) and its span criteria now carry an explicit "emitted from a
  tracing plugin, not from library code" qualifier and a blocked on #1464 + #1466
  marker, so the mechanism half of this consequence is defused. The invented
  intrinsic.* span names were also corrected across feat(backends): LocalFileBinding implements verbs (PEFT/aLoRA path) + from_catalog() (Epic #929 Phase 2) #1141, feat(backends): EmbeddedBinding implements apply_activation (Granite Switch path); remove render_controls + set_request_adapter (Epic #929 Phase 2) #1142 and feat(telemetry): add complete adapter-function lifecycle observability #1466 the same
  day. What remains for this issue is the durable half: the page that taught the wrong
  pattern, and CI enforcement so the next occurrence fails a check rather than needing
  a reviewer to spot it.

There is also a structural gap that makes the rule impossible to follow for
adapter functions specifically. ADAPTER_FUNCTION_INVOCATION_COMPLETE and
ADAPTER_FUNCTION_PHASE_COMPLETE are the only HookType family with no
pre/start sibling, so there is no event at which a plugin could open those spans.
Documenting the rule without noting this would set an unmeetable expectation.

Scope

• docs/docs/observability/tracing.md — explain how spans are produced, not just
  which spans exist: hooks fire, plugins emit, and why (telemetry stays optional
  and testable without an exporter).
• Record the session.py exception as an exception, at a place a reader will find
  before copying it.
• docs/dev/adapter_observability.md — correct the direct-start_*_span
  guidance.
• Enforcement in CI, so the next violation fails a check rather than relying on
  review attention. Suggested boundary: nothing under mellea/backends/ imports
  mellea/telemetry/tracing, with mellea/stdlib/session.py as the sole
  allowlisted exception.
• Amend feat(backends): EmbeddedBinding implements apply_activation (Granite Switch path); remove render_controls + set_request_adapter (Epic #929 Phase 2) #1142's telemetry acceptance criteria so they no longer require the
  pre-refactor(telemetry)!: move backend tracing onto plugin/hook pattern #1181 pattern.
• Note the pre/start hook gap for the ADAPTER_FUNCTION_* family where the rule
  is documented, so the exception is visible rather than surprising.

Out of scope

Adding the missing start hooks, and emitting adapter-function spans — both belong
to #1466, which this issue blocks.

Acceptance criteria

• docs/docs/observability/tracing.md states the hook-fires/plugin-emits rule
  and contains at least one worked reference to tracing_plugins.py
• The mellea/stdlib/session.py exception is documented as such
• docs/dev/adapter_observability.md no longer instructs implementers to call
  start_*_span from library code
• A CI check fails on a new telemetry.tracing import under
  mellea/backends/, with session.py allowlisted
• The check is verified to fail by temporarily reintroducing such an import
  (evidence in the PR description; the temporary change is not committed)
• feat(backends): EmbeddedBinding implements apply_activation (Granite Switch path); remove render_controls + set_request_adapter (Epic #929 Phase 2) #1142's telemetry acceptance criteria updated
• npx markdownlint-cli2 passes on every page touched

References

• refactor(telemetry)!: move backend tracing onto plugin/hook pattern #1181 — the refactor that introduced the rule without documenting it
• feat(backends): LocalFileBinding implements verbs (PEFT/aLoRA path) + from_catalog() (Epic #929 Phase 2) #1141 / PR feat(backends): LocalFileBinding implements verbs (PEFT/aLoRA path) + from_catalog() (Epic #929 Phase 2) #1454 — where it went wrong in practice
• refactor(backends): AdapterMixin verb rename/narrow + resolve_model_options + IntrinsicMetricsPlugin (Epic #929 Phase 2) #1140 — the design issue whose span schema named no emitter
• mellea/telemetry/tracing_plugins.py — the four existing span plugins