OTel coordination contract

Copy page

OTEL carries the signal. Tapestry interprets the signal as coordination reinforcement.

OTel is the canonical telemetry transport (OTLP → Grafana Cloud). This page is the attribute contract every Tapestry-emitting event must carry so the observer can read those events as coordination signals — not just hook/tool noise.

Direction

Keep the existing OTLP → Grafana Cloud pipeline.
Preserve current hook / tool / session / snapshot / observer events.
Convert free-text note data into structured attributes where possible.
Add missing attributes only when they can be reliably generated.

Required anchor

Attribute	Purpose
`tapestry.coordination_context_id`	The single anchor that ties every event in one coordination episode together. Required on every Tapestry-emitting event.

Required context

Attribute	When set
`tapestry.project_id`	Always
`tapestry.session_id`	Always
`tapestry.agent_id`	If known
`tapestry.agent_role`	If known
`tapestry.surface_id` or `tapestry.workflow_surface`	If known
`tapestry.surface_type`	If known

Mechanism attributes

Attribute	Carried by
`tapestry.hook_name`	Every hook event
`tapestry.tool_name`	PreToolUse / tool-invocation events
`tapestry.architecture_snapshot_id`	SessionStart snapshot events
`tapestry.diff_report_id`	Snapshot diff events
`tapestry.observer_ran`	Observer events
`tapestry.observer_detected_count`	Observer events
`tapestry.observer_created_count`	Observer events
`tapestry.observer_updated_count`	Observer events
`tapestry.friction_present`	Any event that surfaces friction
`tapestry.friction_type`	When `friction_present=true`
`tapestry.correction_present`	Events involving an operator correction
`tapestry.memory_read_count`	Events that touch loom-memory
`tapestry.memory_write_count`	Events that touch loom-memory
`tapestry.memory_miss`	When a recall returned nothing
`tapestry.upskill_candidate_present`	Events that surfaced a candidate

Explicit states

Coordination-quality signals MUST use one of these four states. Missing instrumentation is blind, not healthy.

State	Meaning
`healthy`	Signal present; coordination working as expected
`degraded`	Signal present; coordination quality dropping
`blind`	Signal not yet instrumented; absence of evidence ≠ evidence of absence
`unknown`	Signal expected but unavailable this event (transient)

Dashboard direction

The Tapestry dashboard reads from OTel-backed telemetry. It is not Grafana. Grafana is the backend observability substrate; the Tapestry dashboard is the coordination-support view layered over that telemetry.

Current state

The transport is wired (integrations/claude-code/tapestry-discipline/scripts/_observability.py) — OTLP/HTTP push to Grafana Cloud via raw urllib, no SDK dependency.

Current attributes per event: hook_name, event, exit_code, elapsed_ms, action, note. The note field carries unstructured strings (out_of_scope, malformed_input, etc.) that this contract is meant to replace with typed attributes.

What this contract does NOT include

Intent. Intent is observer-derived, not telemetry-emitted. Adding intent attributes here would conflate the interpretation layer with the emission layer. The observer reads these typed attributes (plus memory, transcripts, diffs, prior findings) and produces an intent hypothesis as a separate output.

Source of truth

This page is the operator-facing surface of the contract. The internal architecture spec lives at docs/reference/coordination-telemetry-contract.md in the repo root (Tapestry-agent owned). If the two diverge, the repo-root spec is canonical.

Load-bearing files — OTel env vars
The observer — consumes OTel telemetry as one of its sensors
Architecture snapshots — one of several mechanisms; snapshot/diff IDs land in the contract via tapestry.architecture_snapshot_id / tapestry.diff_report_id
Observatory console — the operator-facing view that will read these typed attributes once instrumented