This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow-steward.git
The following commit(s) were added to refs/heads/main by this push:
new ee29ffc docs(repo-health): sync family README and spec to reflect 5
shipped skills (#585)
ee29ffc is described below
commit ee29ffc8d070e4176df4fc30395a69dc7d664c8c
Author: Justin Mclean <[email protected]>
AuthorDate: Sat Jun 27 20:50:15 2026 +1000
docs(repo-health): sync family README and spec to reflect 5 shipped skills
(#585)
workflow-security-audit and dependency-audit landed on main in PRs #567
and #569 respectively but docs/repo-health/README.md still listed them
as "Candidate skills (not yet built)". Move both into the Current skills
section alongside ci-runner-audit, update their descriptions to match the
shipped skill frontmatter, and note that license-compliance-audit and
flaky-test-triage are still proposed candidates.
Update tools/spec-loop/specs/repo-health-family.md Known Gaps to replace
"Family is one skill deep" with the accurate three-skill count, record
that repo-health-config.md is already on main (via PR #567), and drop the
stale "no adopter-config scaffold yet" note.
Also sync uv.lock to match tools/spec-validator/pyproject.toml (pytest
specifier was >=9.1.0 in the lock but >=8.0 in the pyproject).
Generated-by: Claude (Opus 4.7)
---
docs/repo-health/README.md | 94 +++++++++++++++--------------
tools/spec-loop/specs/repo-health-family.md | 13 ++--
2 files changed, 56 insertions(+), 51 deletions(-)
diff --git a/docs/repo-health/README.md b/docs/repo-health/README.md
index 3c98a82..caed091 100644
--- a/docs/repo-health/README.md
+++ b/docs/repo-health/README.md
@@ -5,12 +5,11 @@
- [Repo-health audits — family overview](#repo-health-audits--family-overview)
- [Current skills](#current-skills)
- [`ci-runner-audit` (experimental)](#ci-runner-audit-experimental)
- - [Candidate skills (not yet built)](#candidate-skills-not-yet-built)
- - [`workflow-security-audit` (proposed)](#workflow-security-audit-proposed)
- - [`dependency-audit` (proposed)](#dependency-audit-proposed)
- - [`license-compliance-audit`
(proposed)](#license-compliance-audit-proposed)
- - [`flaky-test-triage` (proposed)](#flaky-test-triage-proposed)
- - [Adopter contract (planned)](#adopter-contract-planned)
+ - [`workflow-security-audit`
(experimental)](#workflow-security-audit-experimental)
+ - [`dependency-audit` (experimental)](#dependency-audit-experimental)
+ - [`license-compliance-audit`
(experimental)](#license-compliance-audit-experimental)
+ - [`flaky-test-triage` (experimental)](#flaky-test-triage-experimental)
+ - [Adopter contract](#adopter-contract)
- [Cross-references](#cross-references)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -52,46 +51,52 @@ Read-only; no workflow files are modified.
---
-## Candidate skills (not yet built)
+### `workflow-security-audit` (experimental)
-These are enumerated from the triage-mode.md Known Gaps. Each will become
-its own build item once the family shape is confirmed through
-`ci-runner-audit` pilot evaluations.
-
-### `workflow-security-audit` (proposed)
-
-Run [`zizmor`](https://woodruffw.github.io/zizmor/) — the GitHub Actions
+Runs [`zizmor`](https://woodruffw.github.io/zizmor/) — the GitHub Actions
security scanner already wired into the framework's own pre-commit suite —
-across one repo or a named set and surface findings for human review.
+across one repository, an explicit repository set, or a whole GitHub org and
+surfaces findings for human review.
-Proposed finding classes:
+Finding classes surfaced:
-- Injection vulnerabilities (`run:` steps using `${{ github.event.* }}` or
- `${{ github.head_ref }}` in untrusted contexts)
-- Excessive permissions (`permissions: write-all` or unnecessary `write`
- scopes on workflow-level or job-level grants)
-- Unpinned external actions (floating `@main`, `@master`, or tag-only
- references instead of a commit SHA)
-- Self-hosted runner scope leakage (secrets available to PRs from forks)
+- **Injection vulnerabilities** — `run:` steps consuming
+ `${{ github.event.* }}` or `${{ github.head_ref }}` in untrusted contexts.
+- **Excessive permissions** — `permissions: write-all` or unnecessary `write`
+ scopes at the workflow or job level.
+- **Unpinned external actions** — floating `@main`, `@master`, or tag-only
+ references instead of a commit SHA.
+- **Self-hosted runner fork-secret leaks** — secrets reachable from PRs
+ submitted by fork contributors via self-hosted runners.
-Each finding class maps to a concise prose description and a suggested
-remediation (scope reduction, SHA pinning, `${{ env.SAFE_VAR }}` pattern).
+Output is a grouped, prioritised finding report. Read-only; the skill never
+edits workflow files, opens PRs, or posts comments.
**Adopter contract**: reads `<project-config>/repo-health-config.md`
-(planned) for which rule classes to enable and which repos to audit.
+(`workflow_security_audit.enabled_rules`) to select which rule classes to
+enable. All classes are enabled by default.
-### `dependency-audit` (proposed)
+---
-Check direct and transitive dependencies for known vulnerabilities (via
-`pip-audit` / `npm audit` / `trivy` depending on the project's language
-stack) and surface those that have available patches. One finding per
-dependency, formatted for maintainer triage. Does not open update PRs
-autonomously — proposes one per affected dependency.
+### `dependency-audit` (experimental)
-**Adopter contract**: reads `<project-config>/repo-health-config.md` for
-the dependency manager and audit tool to use.
+Detects the project's dependency manager(s), runs the appropriate audit
+tool (`pip-audit`, `npm audit`, `cargo audit`, or `trivy`), and surfaces
+patchable vulnerability findings grouped by severity for maintainer triage.
+
+- Works against one repository (`--repo owner/name`) or a local checkout
+ (`--path /path/to/checkout`).
+- Differentiates CVE-rated vulnerabilities (those with a CVE ID) from
+ advisory-only findings.
+- Proposes one upgrade per affected dependency; never modifies manifests,
+ lock files, or opens update PRs autonomously.
-### `license-compliance-audit` (proposed)
+**Adopter contract**: reads `<project-config>/repo-health-config.md`
+(`dependency_audit.managers`) to select the dependency manager adapter(s).
+
+---
+
+### `license-compliance-audit` (experimental)
Verify that:
@@ -107,16 +112,16 @@ suggested correction) without modifying any file.
**Adopter contract**: reads `<project-config>/repo-health-config.md` for
the required SPDX expression and which source paths to audit.
-### `flaky-test-triage` (proposed)
+### `flaky-test-triage` (experimental)
Parse GitHub Actions run history for a named repo over a configurable window,
-compute per-test failure rates (differentiating consistent failures from
-intermittent ones), and produce a prioritised triage list: tests failing
+compute per-job failure rates (differentiating consistent failures from
+intermittent ones), and produce a prioritised triage list: jobs failing
above a configurable threshold that are likely flaky rather than
deterministically broken.
Signals used: run outcome (`success` / `failure`), re-run count on the same
-SHA, test-name patterns across runs. No test code is modified.
+SHA, job-name patterns across runs. No test code is modified.
**Adopter contract**: reads `<project-config>/repo-health-config.md` for
the audit window, the failure-rate threshold, and which test-name patterns
@@ -124,10 +129,12 @@ to include or exclude.
---
-## Adopter contract (planned)
+## Adopter contract
-A future `projects/_template/repo-health-config.md` will declare per-skill
-switches:
+`projects/_template/repo-health-config.md` provides the per-project
+configuration scaffold for all repo-health skills. Copy it into your
+`<project-config>/` directory and fill in the `TODO` fields for each skill
+you enable:
```yaml
repo_health:
@@ -161,9 +168,6 @@ repo_health:
failure_rate_threshold: 0.1
```
-The config file will land in a separate build item once at least one
-candidate skill reaches the planning stage.
-
---
## Cross-references
diff --git a/tools/spec-loop/specs/repo-health-family.md
b/tools/spec-loop/specs/repo-health-family.md
index 94bb8fb..bc18671 100644
--- a/tools/spec-loop/specs/repo-health-family.md
+++ b/tools/spec-loop/specs/repo-health-family.md
@@ -117,9 +117,10 @@ uv run --project tools/skill-and-tool-validator --group
dev skill-and-tool-valid
and `flaky-test-triage` have all shipped (read-only, `experimental`, each
with an eval suite). No further candidate skills remain designed; the
family is complete pending adopter-pilot evaluation.
-- **No adopter-config scaffold yet.**
`projects/_template/repo-health-config.md`
- is planned alongside the first candidate skill; the keys are sketched in
- `docs/repo-health/README.md § Adopter contract`.
-- **`ci-runner-audit` eval suite exists but no adopter pilot has run.**
- The skill is `experimental`; behaviour may change as cross-org run
- volumes expose edge cases in runner-label classification.
+- **Adopter-config scaffold exists.**
`projects/_template/repo-health-config.md`
+ covers all five skills; adopters copy it into their `<project-config>/`
+ and fill in the relevant keys.
+- **No adopter pilot has run any family skill end-to-end.** All five
+ shipped skills are `experimental`; behaviour may change as cross-org run
+ volumes expose edge cases in classification, runner-label handling, and
+ dependency-manager detection.
