Relocate the Health Agent into PyAutoBrain (canonical home)

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 <topic>`, ...).
+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 <repo>`, `fix dirty <repo>`, `fix drift`,
+   `fix timing <project>`). 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: <GREEN | YELLOW | RED>   (score <0-100>, snapshot <ts>)
+
+### Summary
+<one or two sentences interpreting the verdict>
+
+### Warnings
+- <yellow reason, mapped to its capability>   (or "None")
+
+### Recommendations
+- <actionable next step, citing a `pyauto-heart fix ...` where applicable>   (or "None")
+
+### Blocking Issues
+- <red reason, mapped to its capability>   (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.