Overseer tool: query / review peer exit reflections

[heavygee]

Goal

Make peer exit reflections a first-class Overseer tool surface — so the overseer (and Meta's who-watches-the-watcher loop) can query and summarize the improve-loop corpus without grepping markdown or the raw events dump.

Emit is already SHIPPED (fork soup). This issue is the consumer.

Context

• Canon: docs/plans/2026-08-08-peer-exit-reflection-events.md
• Emit: hapi-emit-exit-reflection → POST /api/system-events (sourceKind=channel, sourceRef=peer-exit-reflection:<sessionId>, provenance=peer-exit-reflection@meta|@peer)
• Dogfood: event #7217 (promote + metaJudgment / retroPath in payload)
• Process: Gate A' MERGED cleanup emits before archive; markdown without emit is incomplete
• Orthogonal to ContributionState 🔧/🧹 babysit chips

Upstream? No. Fork-only. Builds on soup channel ingest + Overseer entity tools. Do not put this in a tiann/hapi PR.

Why a dedicated tool (not only query_events)

query_events?sourceKind=channel already returns the rows, but the overseer brain has to remember the sourceRef prefix, payload shape (metaJudgment, promote, retroPath), and the attention policy. A thin tool:

1. Filters sourceRef^=peer-exit-reflection
2. Projects a lean view (session, PR, promote bar, judgment, path, attention)
3. Optional cluster mode: group by promote theme / High-signal asks (same spirit as query_dispositions groupBy)

That is the improve-loop analogue of query_inbox (urgency) vs neglect — "what should change how we work next?"

Proposed tool (sketch)

Name TBD — e.g. query_exit_reflections (read-only).

Arg	Purpose
limit	Cap (default small, 10–25)
promote	Filter: none / skip / tooling-doc / issue / … or "needs_judgment" (attention=1)
sinceTs / untilTs	Time window
sessionId / relatedSessionId	One peer's retros
groupBy	Optional: promote | theme (best-effort from summary/payload)

Returns: list of projected rows + optional clusters. No write. Disposition of promote asks stays Meta/operator (or later record_disposition on an inbox item if we promote attention rows into inbox — out of scope for v1 tool).

Kill criteria

• Tool that just wraps query_events with no projection → don't ship; document a prompt hint instead
• Inbox spam from skip/none → already enforced at emit (attentionCandidate=0); consumer must not re-surface those as "needs you"
• New table / SCHEMA_VERSION / parallel bus → reject; channel SystemEvent is the store

Stacking concern (explicit)

We already have events + inbox + converse + focus + channel ingest. This issue must not add another substrate.

Do	Don't
One read tool (+ lean projection) on existing events	New SQLite table
Fork PR stacked on current overseer tip / soup layers that already have channel ingest	Upstream PR / new soup layer for storage
Ship when ≥N reflection events exist to dogfood (already #7217+)	Block on expanding emit to all archives

Dependency: emit helper + channel ingest (done). Does not block / depend on: A2A P1 upstream (tiann#1374), notify Settings (tiann#1375), voice #21/#29/#97.

Acceptance

• Overseer tool catalog includes the read tool; converse can call it
• Default query returns only peer-exit-reflection:* rows; skip/none not presented as action-needed
• Projection includes enough to answer "what promote did Meta/peer ask for?" without opening the markdown
• Unit tests on filter + projection; one converse or tool-route test
• Fork-only PR (heavygee/hapi); no docs/operator / plans leak into an upstream-bound branch

Out of scope

• Expanding Meta emit beyond Gate A' (separate process)
• Peer MCP same-turn emit
• Auto-applying promotions / writing docs from reflections
• Treating reflections as A2A work_ads

References

• Plan: docs/plans/2026-08-08-peer-exit-reflection-events.md
• Lifecycle: docs/tooling/feature-work-lifecycle.md § Exit reflection
• Sibling patterns: query_dispositions, query_open_loops