docs(specs): narrow S03 to logging conventions
Why
S03 currently spans metrics, tracing, logging, health checks, and the internal listener. Logging conventions are needed broadly and immediately: every spec that emits a log record or a wide event blocks on the structured handler, the trace-correlation wrapper, the access-log sampler, and the wide-event typed-emitter discipline. The full S03 has been in review for five passes and stalls on metrics and tracing surface that consumers do not need yet.
This MR narrows S03 to the logging foundation so the universal-consumer sections can land. Metrics, tracing, and the readiness/internal-listener surface move to dedicated follow-up specs, each tracked separately.
What (non-obvious parts)
- Scope cut, not deferred-in-place. The metrics, tracing, health-check, and internal-listener sections are removed, not commented out or marked TBD. Three follow-up specs (#56 (closed), #57, #58) carry the cut surface forward with full author handoff.
- Trace-correlation wrapper stays. The 10-line wrapper that stamps
trace_idandspan_idon log records preserves the wide-event contract whether or not the tracing framework has shipped. It is a no-op without an active span. A new addendum to that subsection records that no span is active in production until #57 ships. - Title changes from "Observability" to "Logging Conventions" (spec index updated alongside).
- AC #6 (closed) (typed-emitter lint rule) tightened to name a specific
mechanism: a custom Go analyzer registered in
.golangci.yml. ## Open Questionssection dropped entirely. OQ5 (the only survivor) was a future-LabKit caveat already captured in the trace-correlation subsection at the line where the wrapper's future replaceability is discussed.
S01 cross-references
S01 references removed S03 sections at several anchor points. The narrowing otherwise leaves S01 alone (full repair belongs with #58), with one exception: the URL anchor at line 297 that lychee would have failed on is repaired in this MR.
Repaired in this MR:
docs/specs/S01-http-server-and-routing.md:297previously linked toS03-observability.md#http-server-middleware. Replaced with prose pointing at the metrics framework follow-up (#56 (closed)). The middleware-chain table semantics are unchanged.
Prose references that lychee does not catch (knowingly stale, follow-up under #58):
- Line 139: "readiness checks ... are registered by S03".
- Line 251:
/-/Infrastructure row lists "S01, S03". - Line 304: "Middleware 8 is defined by S03".
- Line 347: "S03 adds further readiness checks for database, Redis, and object storage".
- Line 389: "S03 enhances this with dependency-aware checks".
- Line 706: "Debug/metrics server on separate port (S03)" deferral row.
- Line 712: "Dependency-aware readiness (S03)" deferral row.
Lines 63 (LogConfig owned by S03) and 714 (Access log volume control) remain accurate and need no edit.
Test plan
- markdownlint clean (0 errors)
- Vale clean (0 errors; 25 pre-existing warnings on surviving prose)
- Placeholder grep returns empty (no
<metrics-follow-up>etc. survived the slot-fill) - Three follow-up issues filed: #56 (closed), #57, #58
- S01 prose-reference audit complete (above)
- lychee passes after the targeted S01:297 anchor repair (
2161fbf)