From 39d91d8581f09a040f93b309cdf8a8c7fb69642b Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 29 Jun 2026 11:21:40 +0000 Subject: [PATCH 1/2] feat: make agents/health the canonical Health Agent home The Health Agent (first PyAutoBrain specialist) was staged in PyAutoHeart's health_agent/ while Brain was out of scope. Relocate its full definition into Brain's own discovery pattern: agents/health/AGENTS.md is now the canonical agent definition (entrypoint health.sh unchanged), surfaced by `pyauto-brain help health`. Preserves verbatim from the staged health_agent.md: adoption of `pyauto-heart readiness --json` as the authoritative verdict (never re-derived), reading Heart's capabilities.yaml as an ABSTRACT provider manifest (read from the PyAutoHeart checkout, never vendored into Brain), the GREEN/YELLOW/RED output schema (Summary / Warnings / Recommendations / Blocking Issues), gate semantics, and the read-and-reason hard boundaries. No checks or gating logic added to Brain. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_015tHLhoSDd7CVvrJ8k7nc7z --- agents/health/AGENTS.md | 138 ++++++++++++++++++++++++++++++++-------- 1 file changed, 113 insertions(+), 25 deletions(-) diff --git a/agents/health/AGENTS.md b/agents/health/AGENTS.md index ff17c00..29fab80 100644 --- a/agents/health/AGENTS.md +++ b/agents/health/AGENTS.md @@ -1,22 +1,39 @@ # 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. +The first 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 @@ -27,17 +44,88 @@ bin/pyauto-brain health status # forward to: pyauto-heart status bin/pyauto-brain health watch 300 # forward to: pyauto-heart watch 300 ``` -## Decision semantics +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) + +- **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. From eb1fc78899cddfbafcd873f56a83572c353b0bc3 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 29 Jun 2026 11:31:42 +0000 Subject: [PATCH 2/2] docs: address Copilot review on health agent definition - Drop the "first" specialist claim (agents/release/ predates and is listed ahead of agents/health/ in the top-level AGENTS.md). - Fix the Run example: `health --json` forwards to `pyauto-heart --json`, an unknown subcommand; use `health readiness --json` (forwarded, no tick). Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_015tHLhoSDd7CVvrJ8k7nc7z --- agents/health/AGENTS.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/agents/health/AGENTS.md b/agents/health/AGENTS.md index 29fab80..ecf1850 100644 --- a/agents/health/AGENTS.md +++ b/agents/health/AGENTS.md @@ -1,8 +1,8 @@ # Health agent -The first 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. +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. ``` Mind (intent) -> Brain (reasoning) -> Heart (gate) -> Hands/Build (execute) @@ -38,10 +38,10 @@ 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