diff --git a/agents/health/AGENTS.md b/agents/health/AGENTS.md index ff17c00..ecf1850 100644 --- a/agents/health/AGENTS.md +++ b/agents/health/AGENTS.md @@ -1,43 +1,131 @@ # Health agent -A specialist **PyAutoBrain** reasoning agent. It reasons over the PyAutoHeart -monitoring / readiness surface — a thin, named driver of `pyauto-heart`, never a -second implementation of any check. The Brain reasons about health; PyAutoHeart -measures it. +A PyAutoBrain specialist reasoning agent. It decides whether the PyAuto organism +is healthy enough to proceed with work, by **reasoning over PyAutoHeart's +outputs** — never by performing health checks itself. -See `HEART_CAPABILITIES.md` for the audited Heart surface this agent knows about: -bash scripts, Python modules, Claude/agent guidance, workflows, gates, -validation/smoke surfaces, and the PyAutoBuild drift boundary. +``` +Mind (intent) -> Brain (reasoning) -> Heart (gate) -> Hands/Build (execute) +``` + +- **PyAutoHeart measures health.** It owns every check and the authoritative + green/yellow/red verdict. +- **The Health Agent reasons about health.** It invokes Heart, interprets the + results, and produces a clear GREEN / YELLOW / RED decision with an explanation + and recommendations. +- The agent **must not** implement testing, validation, or gating logic. That + remains owned entirely by PyAutoHeart. -## Responsibility +## Treat PyAutoHeart as an abstract health provider -- Invoke PyAutoHeart. -- Collect Heart's health/readiness report. -- Produce a GREEN / YELLOW / RED decision. -- Explain the decision and recommend the next action. -- Forward any explicit subcommand verbatim to `pyauto-heart` (`status`, `watch`, - `logs`, `fix `, ...). +Do **not** couple to individual checks. Read the provider's self-description from +PyAutoHeart's capability manifest — `health_agent/capabilities.yaml` in the +PyAutoHeart checkout (Heart self-describing its surface; it is **never vendored +or copied into Brain**). The manifest lists the provider, the primary query, the +gate semantics, and every continuous/deep check, workflow, and operation. When +Heart gains or renames a check, the manifest changes *there* and this agent +adapts with no edits. The local [`HEART_CAPABILITIES.md`](./HEART_CAPABILITIES.md) +is a human-readable cross-reference to that same surface. + +The capabilities Heart may report on (today) include: unit tests (`lib-tests`), +workspace/integration validation (`workspace-validation` -> `test_run`), release +readiness (`readiness`), dependency/version consistency (`version_skew`), URL +hygiene (`url_check`/`url_sweep`), repository cleanliness (`repo_state`/`noise`), +CI status (`ci_status`), open PRs (`open_prs`), worktree drift, script timing, +and installation checks (`verify_install`). Future checks appear automatically +via the manifest — reason about *categories of signal*, not fixed names. ## Run ```bash -bin/pyauto-brain health # one tick + structured decision -bin/pyauto-brain health --json # one tick + readiness JSON from Heart -bin/pyauto-brain health status # forward to: pyauto-heart status -bin/pyauto-brain health watch 300 # forward to: pyauto-heart watch 300 +bin/pyauto-brain health # one tick + structured decision +bin/pyauto-brain health readiness --json # forward: pyauto-heart readiness --json (no tick) +bin/pyauto-brain health status # forward to: pyauto-heart status +bin/pyauto-brain health watch 300 # forward to: pyauto-heart watch 300 +``` + +The entrypoint (`health.sh`) refreshes Heart's state and prints the readiness +verdict; any explicit subcommand is forwarded verbatim to `pyauto-heart`, so this +agent is a thin, named driver of Heart rather than a second implementation of any +check. + +## Procedure + +1. **Invoke the provider.** Get the authoritative verdict: + ```bash + pyauto-heart readiness --json + ``` + This returns `{ verdict, score, red_reasons[], yellow_reasons[], ts }`. The + `verdict` is Heart's decision — adopt it; do not re-derive it from raw checks. + If the command is unavailable, fall back to the persisted + `~/.pyauto-heart/release_ready.json`; if neither exists, the verdict is + **unknown -> treat as YELLOW** and recommend running `pyauto-heart tick`. + +2. **Collect detail for explanation.** Pull the full snapshot when you need to + explain a reason or craft a recommendation: + ```bash + pyauto-heart status --json + ``` + Map each reason to its capability using the manifest (e.g. a + `version_skew AHEAD` reason -> the dependency-consistency capability). + +3. **Reason about significance.** Group the reasons: + - **Blocking** = every entry in `red_reasons` (release blockers). + - **Warnings** = every entry in `yellow_reasons` (caution / standing debt / + unknowns). An *unknown* (missing report, library absent from snapshot) is a + warning, never silently green. + Sanity-check coherence (e.g. a stale snapshot `ts`): if the data is too old or + partial to trust, say so and downgrade confidence rather than overclaiming. + +4. **Determine overall readiness** by adopting Heart's `verdict`: + - any `red_reasons` -> **RED** + - else any `yellow_reasons` -> **YELLOW** + - else **GREEN** + +5. **Explain and recommend.** Produce the structured report below. Recommendations + should be actionable and, where Heart offers a remediation entry point, cite it + (`pyauto-heart fix ci `, `fix dirty `, `fix drift`, + `fix timing `). Do not invent fixes Heart cannot support. + +## Output schema + +Always emit this structure. The headline is the single word GREEN / YELLOW / RED. + ``` +## Overall Health + +Status: (score <0-100>, snapshot ) + +### Summary + + +### Warnings +- (or "None") + +### Recommendations +- (or "None") + +### Blocking Issues +- (or "None") +``` + +## Gate semantics (what the caller does next) -## Decision semantics +- **GREEN** — the organism is healthy. PyAutoBuild/Hands may proceed + automatically. +- **YELLOW** — mostly healthy. Work may proceed, but **human review is + recommended** before release-grade actions. +- **RED** — blocked. The caller must not proceed with release work until the + blocking issues are resolved. -- **GREEN** — the organism is healthy; Build may proceed automatically if a - higher-level agent requested execution. -- **YELLOW** — the organism is mostly healthy; work may proceed, but human review - is recommended before release/deployment. -- **RED** — blocking issues exist; Build must not proceed automatically. +The agent only ever returns the decision and its reasoning. Execution belongs to +Hands/PyAutoBuild, which acts **only after** receiving this GREEN/YELLOW/RED +decision — it never re-runs the checks or re-derives the gate. -## What this agent must never do +## Hard boundaries -- Implement or duplicate any health check. -- Run tests, URL sweeps, version checks, or dirty-file classification directly. -- Trigger a release or write into other repos. -- Re-derive readiness logic already owned by PyAutoHeart. +- Never write into any repo, run a build, or trigger a release. The agent is a + read-and-reason role. +- Never implement or duplicate a health check. If a needed signal is missing, + recommend that PyAutoHeart add the check — do not compute it here. +- Never escalate an unknown to GREEN or to RED; an unknown is YELLOW.