Doc follow-up to #148. The constitution and runtime docs still described the pre-migration observability setup: OTel in release only, and a basic logger in debug.
### V. Observability
-All database operations and HTTP handlers MUST be instrumented
-with OpenTelemetry spans via the `trace_db_call` helper or
-equivalent tracing macros.
-- Release builds export traces to the configured OTLP endpoint.
-- Debug builds use the basic logger.
+… MUST be instrumented with `tracing` spans (tracing-opentelemetry):
+ `otel::trace_db_call` for DAOs, `#[tracing::instrument]` for handlers.
+- Spans in every build; OTLP export gated on OTLP_OTLS_ENDPOINT
+- MUST NOT thread an OpenTelemetry Context: spans parent on the ambient span
+- Every tokio::spawn / cross-thread fan-out MUST carry its parent span
+- RUST_LOG gates span export too, so deployments MUST run at info or debug
+- Logs: env_logger (debug) / OTel log export (release), unchanged
Constitution 1.0.0 → 1.1.0 (MINOR): Principle V is materially expanded with two new MUSTs. No principle is removed. The Layer I and Tech Stack wording now matches.
Also fixed:
CLAUDE.md: the OTLP_OTLS_ENDPOINT line (it said "release builds") and the dependency list.
.env.example: the telemetry header.
README.md: the RUST_LOG default and span gating. OTLP_OTLS_ENDPOINT was never documented there, which Principle IV requires; it is now.
Evidence
Before:constitution.md said "Debug builds use the basic logger" and "Release builds export traces". Both have been false since #148 (otel::init_tracing runs in every build). After: the text matches src/otel.rs and main.rs, and the new MUSTs match the CLAUDE.md "Tracing" conventions and the regression tests (tests/otel_*.rs).
Docs only: no code changes.
Merge Danger
Door: two-way
Blast Radius: docs
It's a governance wording change. The new MUSTs codify rules the code already follows.
## Summary
Doc follow-up to #148. The constitution and runtime docs still described the pre-migration observability setup: OTel in release only, and a basic logger in debug.
```diff
### V. Observability
-All database operations and HTTP handlers MUST be instrumented
-with OpenTelemetry spans via the `trace_db_call` helper or
-equivalent tracing macros.
-- Release builds export traces to the configured OTLP endpoint.
-- Debug builds use the basic logger.
+… MUST be instrumented with `tracing` spans (tracing-opentelemetry):
+ `otel::trace_db_call` for DAOs, `#[tracing::instrument]` for handlers.
+- Spans in every build; OTLP export gated on OTLP_OTLS_ENDPOINT
+- MUST NOT thread an OpenTelemetry Context: spans parent on the ambient span
+- Every tokio::spawn / cross-thread fan-out MUST carry its parent span
+- RUST_LOG gates span export too, so deployments MUST run at info or debug
+- Logs: env_logger (debug) / OTel log export (release), unchanged
```
**Constitution 1.0.0 → 1.1.0 (MINOR):** Principle V is materially expanded with two new MUSTs. No principle is removed. The Layer I and Tech Stack wording now matches.
Also fixed:
- `CLAUDE.md`: the `OTLP_OTLS_ENDPOINT` line (it said "release builds") and the dependency list.
- `.env.example`: the telemetry header.
- `README.md`: the `RUST_LOG` default and span gating. `OTLP_OTLS_ENDPOINT` was never documented there, which Principle IV requires; it is now.
## Evidence
- **Before:** `constitution.md` said "Debug builds use the basic logger" and "Release builds export traces". Both have been false since #148 (`otel::init_tracing` runs in every build).
**After:** the text matches `src/otel.rs` and `main.rs`, and the new MUSTs match the CLAUDE.md "Tracing" conventions and the regression tests (`tests/otel_*.rs`).
- Docs only: no code changes.
## Merge Danger
**Door:** two-way
**Blast Radius:** docs
It's a governance wording change. The new MUSTs codify rules the code already follows.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Principle V now reflects the merged tracing migration (#148):
- tracing + tracing-opentelemetry spans in every build, with OTLP export
gated on OTLP_OTLS_ENDPOINT;
- no manual Context threading;
- every spawn / fan-out carries its parent span;
- RUST_LOG gates span export (run at info/debug).
Layer and Tech Stack wording matches.
Also corrects stale "release builds only" telemetry notes in CLAUDE.md and
.env.example, updates the CLAUDE.md dependency list, and fixes the README's
RUST_LOG default. It also documents OTLP_OTLS_ENDPOINT in the README, as
Principle IV requires.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Summary
Doc follow-up to #148. The constitution and runtime docs still described the pre-migration observability setup: OTel in release only, and a basic logger in debug.
Constitution 1.0.0 → 1.1.0 (MINOR): Principle V is materially expanded with two new MUSTs. No principle is removed. The Layer I and Tech Stack wording now matches.
Also fixed:
CLAUDE.md: theOTLP_OTLS_ENDPOINTline (it said "release builds") and the dependency list..env.example: the telemetry header.README.md: theRUST_LOGdefault and span gating.OTLP_OTLS_ENDPOINTwas never documented there, which Principle IV requires; it is now.Evidence
constitution.mdsaid "Debug builds use the basic logger" and "Release builds export traces". Both have been false since #148 (otel::init_tracingruns in every build).After: the text matches
src/otel.rsandmain.rs, and the new MUSTs match the CLAUDE.md "Tracing" conventions and the regression tests (tests/otel_*.rs).Merge Danger
Door: two-way
Blast Radius: docs
It's a governance wording change. The new MUSTs codify rules the code already follows.
🤖 Generated with Claude Code