From 331e35083dafee662b844a9a53bca5d0477143f2 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 2 Jul 2026 21:41:34 +0000 Subject: [PATCH 1/4] docs(health): record day-to-day operating defaults for pyauto-brain health MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- agents/health/AGENTS.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/agents/health/AGENTS.md b/agents/health/AGENTS.md index ca3d350..c4c12c5 100644 --- a/agents/health/AGENTS.md +++ b/agents/health/AGENTS.md @@ -123,6 +123,41 @@ Status: (score <0-100>, snapshot ) - (or "None") ``` +## Day-to-day defaults (operating agreement) + +How `pyauto-brain health` should render and reason on a routine run. These are +presentation/triage conventions layered *on top of* the procedure above — they +never change the verdict, which is always adopted from Heart verbatim. + +- **Default surface.** Lead with the `pyauto-heart dashboard --md` mobile card + (verdict · score · warnings · tiles), then the structured report beneath it. +- **Grouping.** Order reasons by severity, then capability: blocking issues + first, then warnings, each mapped to its manifest capability. +- **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 + `readiness.yellow_reasons`. Keep such tiles visually secondary: note the + "unknown-on-HEAD, gate-irrelevant" nature once and do not let many + near-identical tiles dominate the card. +- **Local-checks-blind.** When `repo_state` reports `present: false` (the + repos are not under `PYAUTO_ROOT`, e.g. a cloud box where they live outside + `~/Code/PyAutoLabs`), the local half of Heart — `repo_state`, `version_skew`, + `worktree_drift`, `script_timing`, `test_run` — observes nothing. Say "local + health unobserved here" and **downgrade confidence**; do not read the + resulting silence (or a vacuously green tile) as *verified clean*. Cite the + one-time fix: set `PYAUTO_ROOT` to the actual checkout root (or auto-detect). +- **`fix` citations.** Cite a `pyauto-heart fix ` entry + point **only when Heart's verdict names that failure class**. An unknown is + not a failure — never emit a fix for it. +- **Staleness.** If `dashboard.stale == true`, or the snapshot `ts` is older + than the watch interval, downgrade confidence and recommend + `pyauto-heart tick` rather than trusting the stale board. +- **Expected first-run gaps vs. real problems.** Treat "no test-run report", + "install verification not run", and "no release validation for current + source" as standing baseline unknowns (YELLOW), not action items. Only a real + CI failure, dirty tree, worktree drift, or timing regression is a genuine + health signal to act on. + ## Gate semantics (what the caller does next) - **GREEN** — the organism is healthy. PyAutoBuild/Hands may proceed From 754afc0982574166cb632361cce973f71734cc4c Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 3 Jul 2026 15:59:31 +0000 Subject: [PATCH 2/4] docs(health): reword day-to-day intro for clarity (Copilot review) Front-load the temporal clause so the opening no longer reads as the awkward "reason on a routine run" Copilot flagged. Wording only. Co-Authored-By: Claude --- agents/health/AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/agents/health/AGENTS.md b/agents/health/AGENTS.md index c4c12c5..42de0ad 100644 --- a/agents/health/AGENTS.md +++ b/agents/health/AGENTS.md @@ -125,7 +125,7 @@ Status: (score <0-100>, snapshot ) ## Day-to-day defaults (operating agreement) -How `pyauto-brain health` should render and reason on a routine run. These are +On a routine run, how `pyauto-brain health` should render and reason. These are presentation/triage conventions layered *on top of* the procedure above — they never change the verdict, which is always adopted from Heart verbatim. From 8767ff3bd2b0a42ff3864a78d341789ba5b05a17 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 6 Jul 2026 09:23:02 +0000 Subject: [PATCH 3/4] docs(health): fix JSON-shape ref + fix-notation consistency (Copilot re-review) - `readiness.yellow_reasons` implied a nested JSON shape; readiness returns `yellow_reasons` at the top level. Reworded accordingly. - `pyauto-heart fix ` read as literal syntax and clashed with the Procedure section's explicit forms; now `pyauto-heart fix ` with the topics listed as examples. Co-Authored-By: Claude --- agents/health/AGENTS.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/agents/health/AGENTS.md b/agents/health/AGENTS.md index 42de0ad..4fd7a17 100644 --- a/agents/health/AGENTS.md +++ b/agents/health/AGENTS.md @@ -135,8 +135,8 @@ never change the verdict, which is always adopted from Heart verbatim. first, then warnings, each mapped to its manifest capability. - **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 - `readiness.yellow_reasons`. Keep such tiles visually secondary: note the + *unknown*, not an actively-running workflow, and it does **not** enter the + readiness output's top-level `yellow_reasons`. Keep such tiles visually secondary: note the "unknown-on-HEAD, gate-irrelevant" nature once and do not let many near-identical tiles dominate the card. - **Local-checks-blind.** When `repo_state` reports `present: false` (the @@ -146,9 +146,9 @@ never change the verdict, which is always adopted from Heart verbatim. health unobserved here" and **downgrade confidence**; do not read the resulting silence (or a vacuously green tile) as *verified clean*. Cite the one-time fix: set `PYAUTO_ROOT` to the actual checkout root (or auto-detect). -- **`fix` citations.** Cite a `pyauto-heart fix ` entry - point **only when Heart's verdict names that failure class**. An unknown is - not a failure — never emit a fix for it. +- **`fix` citations.** Cite a `pyauto-heart fix ` entry point (topics: + `ci`, `dirty`, `drift`, `timing`) **only when Heart's verdict names that + failure class**. An unknown is not a failure — never emit a fix for it. - **Staleness.** If `dashboard.stale == true`, or the snapshot `ts` is older than the watch interval, downgrade confidence and recommend `pyauto-heart tick` rather than trusting the stale board. From a54f4e0220396be81831c237f8a2978ed3b6195f Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 6 Jul 2026 09:28:49 +0000 Subject: [PATCH 4/4] docs(health): clarify grouping vs schema order + rewrap (Copilot re-review) - The "Grouping" bullet's "blocking-first" ordering contradicted the Output schema's fixed section order. Clarify it applies to ranking/triage and the dashboard card; the structured report keeps the schema order (Warnings, Recommendations, Blocking Issues). - Rewrap the Unknown-CI-tiles bullet to consistent line lengths. Co-Authored-By: Claude --- agents/health/AGENTS.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/agents/health/AGENTS.md b/agents/health/AGENTS.md index 4fd7a17..afde68c 100644 --- a/agents/health/AGENTS.md +++ b/agents/health/AGENTS.md @@ -131,14 +131,16 @@ never change the verdict, which is always adopted from Heart verbatim. - **Default surface.** Lead with the `pyauto-heart dashboard --md` mobile card (verdict · score · warnings · tiles), then the structured report beneath it. -- **Grouping.** Order reasons by severity, then capability: blocking issues - first, then warnings, each mapped to its manifest capability. +- **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.) - **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 - readiness output's top-level `yellow_reasons`. Keep such tiles visually secondary: note the - "unknown-on-HEAD, gate-irrelevant" nature once and do not let many - near-identical tiles dominate the card. + readiness output's top-level `yellow_reasons`. Keep such tiles visually + secondary: note the "unknown-on-HEAD, gate-irrelevant" nature once and do not + let many near-identical tiles dominate the card. - **Local-checks-blind.** When `repo_state` reports `present: false` (the repos are not under `PYAUTO_ROOT`, e.g. a cloud box where they live outside `~/Code/PyAutoLabs`), the local half of Heart — `repo_state`, `version_skew`,