Add a read-only Analyst for research-health flags

[markfreeman-dot-dev]

v2 migration #100 › M7-lifecycle (epic #15) · Size S · Architecture

Goal

A read-only, LLM-free Analyst periodically flags research-health risks over petri.sqlite: systemic agent blocks, stalled verdict velocity, and staleness on heavily-depended-on cells.

Context

Nothing watches the health of the research process today. After M6-storage's SQL analytics views (blocking patterns, velocity, stalled cells) and M5-otel's spans/usage tables land, the raw signals exist; the Analyst is pure diagnosis over data Petri already has.

Scope

In:

• Three flag rules (systemic agent block, stalled verdict velocity, transitive staleness) with petri.yaml-configurable thresholds and stated defaults.
• ResearchHealthReport model: per-flag records with severity, affected cells and agents, and the query evidence behind each flag.
• analyst_reports migration with append-only writes; schedule registration in the v2 app-bootstrap with a petri.yaml key, off by default.
• GET /api/health serving the latest report; a compact dashboard health panel; an active-flags section in petri check.
• tests/unit/test_analyst.py on fixture views/spans; tests/integration/test_analyst_schedule.py.

Out:

• No remediation or auto-fix (flags are informational).
• No LLM-based diagnosis or alerting integrations (webhooks, email).

Acceptance criteria

• One agent blocking 5 cells yields a systemic-agent flag naming the agent and affected cells; at 4 cells no flag fires (boundary test).
• Stalled-velocity fires when eligible cells have no verdict_issued events in the window and stays silent when recent verdicts exist; transitive-staleness uses edge-intelligence transitive-dependent counts and event-timestamp age, never Cell.created_at.
• Analyst code imports no LLM, provider, or DBOS modules and writes only the analyst_reports table; events, cells, and edges are never written (asserted in tests).
• The analyst_reports migration bumps PRAGMA user_version forward-only; reports append and rows are never updated in place.
• With the schedule key absent no schedule registers; with a test cron exactly one report row appends per firing, and GET /api/health returns it as a schema-valid ResearchHealthReport (TestClient).
• petri check prints active flags and the dashboard health panel shows severity with affected cells and agents on a fixture dish, no LLM required.

Pointers

• petri/query/ (M6 analytics views); petri/analysis/edge_intelligence.py (transitive counts)
• M5-otel spans/usage tables and their migration precedent
• petri/cli/check.py; the dashboard API route module; v2 app-bootstrap (schedule registration)
• Evidence age from event timestamps, never Cell.created_at (empty in v1 metadata, fixed in M3-decomposer)

---

#N in this issue refers to entries in docs/field-reports.md, not issues in this repo.
To claim this issue, leave a comment. Questions welcome — see CONTRIBUTING.md.