Add tracing spans, metrics, and alerting to the ODW review pipeline

[coderabbitai]

Summary

The Dakar ODW review pipeline has no tracing spans, structured span
attributes, bounded metrics, or alerting. --telemetry only streams ODW's
own log lines to stderr (see docs/developers-guide.md); there is no
runId/reviewBase/headCommit/stateFile/attempt/latency span
instrumentation, no bounded metrics emission, and no alert path on ODW
invocation failure, result-polling timeout, or record failure.

Rationale

This was raised during review of #1 and confirmed unresolved: a grep across
bin/dakar-review.mjs, workflows/dakar-review.js, and
scripts/review-state.mjs finds no tracing/observability instrumentation.
This is a genuine functional gap in operational visibility, not aspirational
polish, and is out of scope for #1 given its size.

Affected areas

• bin/dakar-review.mjs — prepare/plan/review/verify/synthesize/record
  stages and the ODW result-polling loop
• workflows/dakar-review.js — phase() boundaries
• scripts/review-state.mjs — withStateLock acquisition/release and
  appendReview
• docs/dakar-review-design.md (Section 8) and docs/developers-guide.md —
  documentation of the instrumentation contract

Acceptance criteria

• Structured spans wrap each stage (prepare, plan, review, verify,
  synthesize, record) and the ODW result-polling loop.
• Each span carries runId, reviewBase, headCommit, stateFile,
  attempt, latencyMs, and stage/outcome (ok|error).
• Bounded metrics counters (attempt counts, per-stage latency) are emitted.
• An actionable alert path triggers on ODW invocation failure, result
  polling timeout, or record failure.
• No new runtime dependency beyond Node built-ins unless one is already used
  elsewhere in the repo.
• Existing dryRun and stdout/stderr contracts are preserved.
• Tests added/updated (e.g. tests/cli.test.mjs,
  tests/review-state.robustness.test.mjs, or a new
  tests/observability.test.mjs) asserting span/metric emission for at
  least one success and one failure path per stage.
• docs/dakar-review-design.md Section 8 and docs/developers-guide.md
  updated to describe the instrumentation contract.

AI agent prompt

Add structured tracing spans and alerting to Dakar's ODW review pipeline.

Scope:
- bin/dakar-review.mjs: wrap prepare, plan, review, verify, synthesize, and
  record stages (and the ODW result-polling loop) in structured spans.
- workflows/dakar-review.js: emit span-start/span-end events at each phase()
  boundary already present in the code.
- scripts/review-state.mjs: instrument withStateLock acquisition/release and
  appendReview with span attributes.

Required span fields: runId, reviewBase, headCommit, stateFile, attempt,
latencyMs, and stage/outcome (ok|error).

Add bounded metrics counters (attempt counts, latency histograms per stage)
and an actionable alert path triggered on ODW invocation failure, result
polling timeout, or record failure — reusing the existing stage/error JSON
convention on stderr as the alert payload, or wiring to an external sink if
one is already used elsewhere in the repo.

Constraints: no new runtime dependency beyond Node built-ins unless already
present elsewhere in the repo; keep dryRun and existing stdout/stderr
contracts unchanged; add or update tests (tests/cli.test.mjs,
tests/review-state.robustness.test.mjs, or a new
tests/observability.test.mjs) asserting span/metric emission for at least one
success and one failure path per stage; update docs/dakar-review-design.md
Section 8 and docs/developers-guide.md to describe the new instrumentation
contract.

Backlinks

• PR: Implement Dakar incremental review workflow (1.) #1
• Requested by: @leynos

[coderabbitai]

🔗 Related PRs

leynos/beatcue#7 - Record BeatCue JSON schema decision (1.1.1) [closed]
leynos/beatcue#11 - Record local-only model policy (1.1.3) [closed]
leynos/mdtablefix#303 - Add observability for inline wrapping token classification (#296) [closed]
leynos/odw-lint#1 - Establish odw-lint static analysis design [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!