Observability Logging

---
name: observability-logging
description: "Records sessions, delegations, reviews, panels and disputes as NDJSON with opencastle log, plus the pre-response quality gate. Use at the end of every session and after every delegation, review, panel or dispute."
---

# Observability Logging

> **⛔ HARD GATE.** Every agent MUST log every session to `events.ndjson` before responding. No exceptions. Session without logs is a failed session.

| File | Event types | Who | When |
|------|------------|-----|------|
| `events.ndjson` | `session`, `delegation`, `review`, `panel`, `dispute` | All agents / Team Lead / Panel runner | After each applicable event |

Full schema: [LOG-SCHEMA.md](./LOG-SCHEMA.md), beside this file; `opencastle log --help` lists the fields too.

Use `opencastle log` CLI. One record per task; never batch-log retrospectively.

**Session** (ALL agents, EVERY session):
```sh
opencastle log --type session --agent Developer --model "$MODEL" \
  --task "Fix login redirect bug" --outcome success --duration_min 15 \
  --files_changed 3 --retries 0
```

**Delegation** (Team Lead, after each delegation — never batched):
```sh
opencastle log --type delegation --session_id feat/prj-57 --agent Developer \
  --model "$MODEL" --tier standard --mechanism sub-agent \
  --tracker_issue PRJ-57 --outcome success --retries 0 --phase 2 \
  --file_partition "src/components/"
```

> `tier` must match the delegated agent's tier in the agent registry. `model` is whatever the assistant actually used — leave it out if it did not report one.

**Review** (Team Lead, after each fast review):
```sh
opencastle log --type review --tracker_issue PRJ-42 --agent Developer \
  --reviewer_model "$MODEL" --verdict pass --attempt 1 \
  --issues_critical 0 --issues_major 0 --issues_minor 2 \
  --confidence high --escalated false --duration_sec 45
```

**Panel** (Panel runner, after each vote):
```sh
opencastle log --type panel --panel_key auth-review --verdict pass \
  --pass_count 3 --block_count 0 --must_fix 0 --should_fix 3 \
  --reviewer_model "$MODEL" --weighted false --attempt 1 \
  --tracker_issue PRJ-42 --artifacts_count 5
```

**Dispute** (Team Lead, after each dispute):
```sh
opencastle log --type dispute --dispute_id DSP-001 --tracker_issue PRJ-42 \
  --priority high --trigger panel-3x-block --implementing_agent Developer \
  --reviewing_agents "Reviewer,Panel (3x)" --total_attempts 6 --status pending
```

Verify any append: `tail -1 .opencastle/logs/events.ndjson`

## Pre-Response Checklist

**⛔ STOP.** Verify before responding — fix any missing log NOW.

- [ ] **Lessons read** — `.opencastle/LESSONS-LEARNED.md` read at session start
- [ ] **Session logged** — `events.ndjson` has a `session` record (ALWAYS)
- [ ] **Delegations logged** — `delegation` record per delegation (Team Lead) (if applicable)
- [ ] **Reviews logged** — `review` record per fast review (if applicable)

## Base Output Contract

Every agent closes its output contract with: observability logged (the `session`
record always, plus `delegation`/`review`/`panel`/`dispute` when they happened),
discovered issues and what was done about them, and lessons applied or added.