Skip to content

Commit 331e350

Browse files
committed
docs(health): record day-to-day operating defaults for pyauto-brain health
Capture the conventions converged on during the first end-to-end Health Agent run: md mobile card as the default surface, severity-then-capability reason grouping, unknown-CI tiles kept secondary, an explicit local-checks-blind confidence downgrade when repos live outside PYAUTO_ROOT, fix-citation discipline, staleness handling, and the expected-first-run-gap vs real-problem separation. Presentation/triage only — the verdict is still adopted from Heart verbatim. Co-Authored-By: Claude <noreply@anthropic.com>
1 parent ea4b83e commit 331e350

1 file changed

Lines changed: 35 additions & 0 deletions

File tree

agents/health/AGENTS.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,41 @@ Status: <GREEN | YELLOW | RED> (score <0-100>, snapshot <ts>)
123123
- <red reason, mapped to its capability> (or "None")
124124
```
125125

126+
## Day-to-day defaults (operating agreement)
127+
128+
How `pyauto-brain health` should render and reason on a routine run. These are
129+
presentation/triage conventions layered *on top of* the procedure above — they
130+
never change the verdict, which is always adopted from Heart verbatim.
131+
132+
- **Default surface.** Lead with the `pyauto-heart dashboard --md` mobile card
133+
(verdict · score · warnings · tiles), then the structured report beneath it.
134+
- **Grouping.** Order reasons by severity, then capability: blocking issues
135+
first, then warnings, each mapped to its manifest capability.
136+
- **Unknown-CI tiles.** A repo whose required-workflow conclusion is
137+
unresolved on `main` HEAD is rendered by Heart as `CI in_progress` — an
138+
*unknown*, not an actively-running workflow, and it does **not** enter
139+
`readiness.yellow_reasons`. Keep such tiles visually secondary: note the
140+
"unknown-on-HEAD, gate-irrelevant" nature once and do not let many
141+
near-identical tiles dominate the card.
142+
- **Local-checks-blind.** When `repo_state` reports `present: false` (the
143+
repos are not under `PYAUTO_ROOT`, e.g. a cloud box where they live outside
144+
`~/Code/PyAutoLabs`), the local half of Heart — `repo_state`, `version_skew`,
145+
`worktree_drift`, `script_timing`, `test_run` — observes nothing. Say "local
146+
health unobserved here" and **downgrade confidence**; do not read the
147+
resulting silence (or a vacuously green tile) as *verified clean*. Cite the
148+
one-time fix: set `PYAUTO_ROOT` to the actual checkout root (or auto-detect).
149+
- **`fix` citations.** Cite a `pyauto-heart fix <ci|dirty|drift|timing>` entry
150+
point **only when Heart's verdict names that failure class**. An unknown is
151+
not a failure — never emit a fix for it.
152+
- **Staleness.** If `dashboard.stale == true`, or the snapshot `ts` is older
153+
than the watch interval, downgrade confidence and recommend
154+
`pyauto-heart tick` rather than trusting the stale board.
155+
- **Expected first-run gaps vs. real problems.** Treat "no test-run report",
156+
"install verification not run", and "no release validation for current
157+
source" as standing baseline unknowns (YELLOW), not action items. Only a real
158+
CI failure, dirty tree, worktree drift, or timing regression is a genuine
159+
health signal to act on.
160+
126161
## Gate semantics (what the caller does next)
127162

128163
- **GREEN** — the organism is healthy. PyAutoBuild/Hands may proceed

0 commit comments

Comments
 (0)