observability-logging

name	observability-logging
description	Logs sessions, tracks activity, records delegation decisions, and stores review/dispute outcomes as NDJSON audit trails. Use when logging session activity, tracking work, recording decisions, building audit trails, capturing delegation history, or running pre-response verification checklists. Trigger terms: log, track activity, audit trail, session record, delegation log, NDJSON

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

See .opencastle/logs/README.md for full schema.

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

Session (ALL agents, EVERY session):

opencastle log --type session --agent Developer --model claude-opus-4-6 \
  --task "Fix login redirect bug" --outcome success --duration_min 15 \
  --files_changed 3 --retries 0

Delegation (Team Lead, after each delegation — never batched):

opencastle log --type delegation --session_id feat/prj-57 --agent Developer \
  --model claude-sonnet-4-6 --tier quality --mechanism sub-agent \
  --tracker_issue PRJ-57 --outcome success --retries 0 --phase 2 \
  --file_partition "src/components/"

model and tier must reflect the delegated agent's assignment from the agent registry.

Review (Team Lead, after each fast review):

opencastle log --type review --tracker_issue PRJ-42 --agent Developer \
  --reviewer_model gpt-5-mini --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):

opencastle log --type panel --panel_key auth-review --verdict pass \
  --pass_count 3 --block_count 0 --must_fix 0 --should_fix 3 \
  --reviewer_model claude-opus-4-6 --weighted false --attempt 1 \
  --tracker_issue PRJ-42 --artifacts_count 5

Dispute (Team Lead, after each dispute):

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

Inherits: base-output-contract