Summary

Add .github/workflows/recipe-health-refresh.yaml, a weekly drift-only bot PR that keeps docs/user/recipe-health.md current, plus the tools/health support needed to surface per-dimension detail in the run's step summary.

Motivation / Context

ADR-009 §5 calls for the public recipe-health matrix to stay current via a weekly, drift-only bot PR — a structural clone of the proven bom-refresh.yaml loop. V1 health changes only on code/registry/chart merges, so a weekly cadence (not daily) is correct, and the job is offset from bom-refresh so the two Monday bot PRs don't contend for runners or /ok re-fire.

Fixes: #1230
Related: #1224 (epic), #1229 (the recipe-health-docs target + committed matrix)

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Refactoring (no functional changes)
• Build/CI/tooling

Component(s) Affected

• CLI (cmd/aicr, pkg/cli)
• API server (cmd/aicrd, pkg/server)
• Recipe engine / data (pkg/recipe)
• Bundlers (pkg/bundler, pkg/component/*)
• Collectors / snapshotter (pkg/collector, pkg/snapshotter)
• Validator (pkg/validator)
• Core libraries (pkg/errors, pkg/k8s)
• Docs/examples (docs/, examples/)
• Other: .github/workflows/, tools/health, Makefile

Implementation Notes

Structurally mirrors bom-refresh.yaml (same pinned action SHAs, global contents: read with the job escalating to contents: write + pull-requests: write, peter-evans/create-pull-request on the built-in GITHUB_TOKEN, branch chore/health-refresh, delete-branch: true, labels documentation / area/docs / area/recipes), with one deliberate divergence: no Helm setup — the health generator is render-free, so the refresh is hermetic and network-free.

Per ADR-009 §5 the step summary is the only home for the structural per-dimension states (resolves / chart_pinned / constraints_wellformed), which the committed matrix omits. To surface them, tools/health gains a -summary-out flag and a renderDetail pass (per-dimension tally + per-recipe table), wired through a new make recipe-health-summary target that the workflow points at $GITHUB_STEP_SUMMARY. The detail is appended (not truncated) per the $GITHUB_STEP_SUMMARY contract, and renders in a fixed dimension order so it stays byte-stable. Matrix rendering is unchanged — verified the matrix functions are untouched and the change to markdown.go is purely additive.

Testing

go test ./tools/health/...                  # ok
golangci-lint v2.12.2 -c .golangci.yaml run ./tools/health/...   # 0 issues
go vet ./tools/health/...                   # clean
yamllint -c .yamllint.yaml .github/workflows/recipe-health-refresh.yaml   # clean
actionlint .github/workflows/recipe-health-refresh.yaml          # clean
make recipe-health-summary                  # renders detail: 32 recipes, all pass

• tools/health coverage 81.1%; new functions 87–100%. No new exported symbols.
• -race was not run locally (no cgo/gcc in this environment) — CI's race job covers it.

Risk Assessment

• Low — Isolated change, well-tested, easy to revert
• Medium — Touches multiple components or has broader impact
• High — Breaking change, affects critical paths, or complex rollout

Rollout notes: New scheduled workflow; first run can be triggered manually via workflow_dispatch. No migration. Fully revertable by deleting the workflow file. Note: the matrix it refreshes is published by #1229 (open) — until that lands, the first run's PR will include the initial matrix body rather than an incremental drift.

Checklist

• Tests pass locally (make test with -race)
• Linter passes (make lint)
• I did not skip/disable tests to make CI green
• I added/updated tests for new functionality
• I updated docs if user-facing behavior changed
• Changes follow existing patterns in the codebase
• Commits are cryptographically signed (git commit -S)