From 67b6c6bb5c512d314cf269d8909144a6141089a7 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 5 Aug 2026 11:45:39 +0000
Subject: [PATCH] docs(vitals): give the faculty procedure a STALE rung
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Follow-up to #199. The vitals faculty documents Heart's freshness tier
correctly in step 1, but the rest of its procedure predates the tier: step 3
grouped reasons into Blocking and Warnings only, and step 4 read "any
red_reasons -> RED, else any yellow_reasons -> YELLOW, else GREEN" — no stale
rung at all. So the faculty the health conductor consults still described the
pre-fix world, and a reader following steps 3-5 would have filed stale reasons
under Warnings or dropped them.

Step 3 gains an Evidence gaps group (nothing known-bad; the remedy is re-running
the named check, never a code fix — conflating it with Warnings is what trains
ack-fatigue). Step 4 gains the stale rung with the precedence red > yellow >
stale from PyAutoHeart/heart/readiness.py, plus the consumer split that makes
the tier worth having: a release still requires GREEN, while AUTONOMY.md leg 4
treats STALE as passing the dev-ship gate. The output schema gains STALE in the
status line and an Evidence Gaps section, and the section-order note follows.

Docs only — no behaviour change. Suite unchanged at 222 passed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FbLrcRCmUvhRQdtZbDWMDD
---
 agents/faculties/vitals/AGENTS.md | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/agents/faculties/vitals/AGENTS.md b/agents/faculties/vitals/AGENTS.md
index c11487a..af3bb4a 100644
--- a/agents/faculties/vitals/AGENTS.md
+++ b/agents/faculties/vitals/AGENTS.md
@@ -101,14 +101,26 @@ faculty every cycle.)
    - **Warnings** = every entry in `yellow_reasons` (caution / standing debt /
      unknowns). An *unknown* (missing report, library absent from snapshot) is a
      warning, never silently green.
+   - **Evidence gaps** = every entry in `stale_reasons` (the freshness tier).
+     Nothing is known-bad; the evidence is missing or expired, so the remedy is
+     **re-running** the named check, never a code fix. Keep them out of Warnings:
+     conflating the two is what trains ack-fatigue.
    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 any `stale_reasons` -> **STALE**
    - else **GREEN**
 
+   Red dominates yellow, which dominates stale — the structural precedence in
+   `PyAutoHeart/heart/readiness.py`. A release still requires **GREEN** (STALE
+   blocks it exactly as YELLOW does), while the dev-ship gate (`AUTONOMY.md`
+   leg 4) treats STALE as **passing**, because an evidence gap is organism-scope,
+   not branch-scope. A verdict from an older Heart carries no `stale_reasons`
+   key at all and behaves exactly as before.
+
 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`,
@@ -116,12 +128,13 @@ faculty every cycle.)
 
 ## Output schema
 
-Always emit this structure. The headline is the single word GREEN / YELLOW / RED.
+Always emit this structure. The headline is the single word GREEN / STALE /
+YELLOW / RED.
 
 ```
 ## Overall Health
 
-Status: <GREEN | YELLOW | RED>   (score <0-100>, snapshot <ts>)
+Status: <GREEN | STALE | YELLOW | RED>   (score <0-100>, snapshot <ts>)
 
 ### Summary
 <one or two sentences interpreting the verdict>
@@ -129,6 +142,9 @@ Status: <GREEN | YELLOW | RED>   (score <0-100>, snapshot <ts>)
 ### Warnings
 - <yellow reason, mapped to its capability>   (or "None")
 
+### Evidence Gaps
+- <stale reason, mapped to its capability, with the check to re-run>   (or "None")
+
 ### Recommendations
 - <actionable next step, citing a `pyauto-heart fix ...` where applicable>   (or "None")
 
@@ -148,7 +164,7 @@ always adopted from Heart verbatim.
 - **Grouping.** When *ranking* reasons for triage and on the dashboard card,
   order by severity then capability — most-severe first — each mapped to its
   manifest capability. (The structured report keeps its fixed section order from
-  the Output schema above: Warnings, Recommendations, Blocking Issues.)
+  the Output schema above: Warnings, Evidence Gaps, Recommendations, Blocking Issues.)
 - **Unknown-CI tiles.** A repo whose required-workflow conclusion is
   unresolved on `main` HEAD is rendered by Heart as `CI in_progress` — an
   *unknown*, not an actively-running workflow, and it does **not** enter the