diff --git a/plugins/audits/references/config-schema.md b/plugins/audits/references/config-schema.md index 45e5ec2..438ae75 100644 --- a/plugins/audits/references/config-schema.md +++ b/plugins/audits/references/config-schema.md @@ -108,6 +108,14 @@ Read with whatever is convenient — the `Read` tool, or `jq` for a single value "depsPrCap": 3, // audit-deps: max PRs per run (a batched routine-bump PR counts as one) "depsIssueCap": 5, // audit-deps: max issues per run + // OPTIONAL extra label names applied to every PR (not issue) any audit opens, alongside the + // audit's own category label and labels.automated, wherever those are applied (create, the + // follow-up `gh pr edit`, the REST fallback). Use it for a label that hands the PR to + // downstream automation, e.g. ["foreman:watch"] so a response loop answers its review. + // Each must already exist; the audits check once per run, drop a missing one and report it, + // and never create labels (audits plugin: references/extra-pr-labels.md). Default [] if absent. + "extraPrLabels": [], + // audit-architecture: oversized-file line-count threshold, shared across every language // block (Python, TypeScript, and the language-generic fallback). Raise it on a repo with // many large-but-legitimate files rather than let the category flag dozens of files and diff --git a/plugins/audits/references/extra-pr-labels.md b/plugins/audits/references/extra-pr-labels.md new file mode 100644 index 0000000..cf860ab --- /dev/null +++ b/plugins/audits/references/extra-pr-labels.md @@ -0,0 +1,30 @@ +# `audits.extraPrLabels`: extra labels on audit PRs + +`config.audits.extraPrLabels` (default `[]`) lists labels every audit applies to every **PR** it +opens, alongside its category label and `config.labels.automated`. Issues never get them. The +usual entry is a label that hands the PR to downstream automation, such as `foreman:watch`. + +Every audit that opens PRs follows the same three rules. + +1. **Check they exist, once per run, before the first PR.** When the list is absent or empty, + skip this check and every report line about it. Otherwise run + `gh api "repos//labels" --paginate --jq '.[].name'` and drop any + `extraPrLabels` entry it does not list. Name each dropped label once in the run report. Never + create a label. If the read itself fails (non-zero exit, an error body, or no output at all), + that is not an empty list: fail closed per rule 1 of + [`gh-rest-fallbacks.md`](gh-rest-fallbacks.md). Apply none of the extra labels, open PRs with + the category labels only, and report "extra labels not applied: label check failed", never + that the labels are missing. This matters for three reasons: `gh pr create --label` fails outright on an + unknown name after the branch is already pushed; a single `gh pr edit --add-label …` fails as a + whole, so one missing name would also cost the category and `automated` labels; and the REST + `POST /issues/{n}/labels` call **creates** a missing label as a side effect. +2. **Apply the survivors wherever the category label is applied**: the `gh pr create` call, the + follow-up `gh pr edit`, or the REST labels call in + [`gh-rest-fallbacks.md`](gh-rest-fallbacks.md). When the skill delegates to `create-pr`, tell + it to apply them on its own create call, exactly as it applies the category labels. +3. **Ordering on the REST fallback.** These are routing labels, not review-gating ones: `foreman` + finds watched PRs by listing open PRs that carry the label on every tick, not from the + `opened` webhook, so a label that lands a moment after `opened` is still picked up. Create the + PR non-draft and label it immediately after. If a repo puts a label here that a review bot + reads at open time, it belongs in the draft-then-stop branch of that reference instead, and + this key is the wrong place for it. diff --git a/plugins/audits/skills/audit-architecture/SKILL.md b/plugins/audits/skills/audit-architecture/SKILL.md index fe2449f..5b57d3b 100644 --- a/plugins/audits/skills/audit-architecture/SKILL.md +++ b/plugins/audits/skills/audit-architecture/SKILL.md @@ -18,7 +18,7 @@ Before doing anything else, load the repo config (see [`../../references/config- > This repo has no `.claude/maintainerd.json`. Run `/bootstrap` to generate it, then re-run me. Do not guess values or hardcode another repo's settings. -3. Read the keys this skill uses: `config.repo`, `config.defaultBranch`, `config.language`, `config.paths.source`, `config.paths.tests`, `config.paths.skillsDir`, `config.commands.format`/`lint`/`build`/`test`, `config.guidelines.invariants`, `config.guidelines.coding`, `config.labels.architecture`, `config.labels.automated`, `config.audits.prCap`, `config.audits.issueCap`, `config.audits.oversizedLines`, `config.audits.promoteThreshold`, `config.audits.promoteLookbackDays`. Treat any `null` command as *"this repo has no such step — skip it"*. For any key that is **absent**, fall back to the documented default (caps default to 3 PRs / 5 issues; the oversized-files line-count threshold defaults to 500; pattern-promotion defaults to a threshold of 3 within 90 days) and mention the fallback in your run report. +3. Read the keys this skill uses: `config.repo`, `config.defaultBranch`, `config.language`, `config.paths.source`, `config.paths.tests`, `config.paths.skillsDir`, `config.commands.format`/`lint`/`build`/`test`, `config.guidelines.invariants`, `config.guidelines.coding`, `config.labels.architecture`, `config.labels.automated`, `config.audits.extraPrLabels` (default `[]`), `config.audits.prCap`, `config.audits.issueCap`, `config.audits.oversizedLines`, `config.audits.promoteThreshold`, `config.audits.promoteLookbackDays`. Treat any `null` command as *"this repo has no such step — skip it"*. For any key that is **absent**, fall back to the documented default (caps default to 3 PRs / 5 issues; the oversized-files line-count threshold defaults to 500; pattern-promotion defaults to a threshold of 3 within 90 days) and mention the fallback in your run report. Throughout this skill, `config.` refers to a value from that file. In the detection commands below, `config.paths.source` stands for your configured source root (e.g. `src/pepper/` or `src/`) and `config.paths.tests` your test root — substitute the literal value when you run them. @@ -202,6 +202,7 @@ git push -u origin "$SLUG" gh pr create --repo \ --title ": " \ --label --label \ + --label \ --body "$(cat <<'EOF' ## Summary @@ -229,12 +230,19 @@ EOF Match the conventional prefix to the work (`refactor:`, `chore:`, `fix:`). +Before the first PR of the run, run the extra-label existence check (rule 1 of the reference below). +Repeat `--label` once per `config.audits.extraPrLabels` entry that passed the once-per-run +existence check (omit the line when none did). They go on PRs only, never on the issues in step 6, +and they go on the PR whether you open it here or delegate to `create-pr`. The check, the +delegation and the REST ordering are in +[`../../references/extra-pr-labels.md`](../../references/extra-pr-labels.md). + **When GraphQL is blocked**, `gh pr create` is 403. Push the branch the same way, then open the PR with `POST /repos/{owner}/{repo}/pulls` — **Create a PR** in [`../../references/gh-rest-fallbacks.md`](../../references/gh-rest-fallbacks.md). Labels are a separate `POST /issues/{n}/labels` call there, so `config.labels.architecture` and -`config.labels.automated` land a moment after the `opened` webhook rather than with it. For these -two labels that is fine — they are routing labels, not review-gating ones — so create the PR +`config.labels.automated` (and the checked `config.audits.extraPrLabels` entries) land a moment +after the `opened` webhook rather than with it. For these labels that is fine — they are routing labels, not review-gating ones — so create the PR non-draft and apply them immediately after, and note the ordering in the report. If this repo's labels *do* gate a review bot, take the second branch that reference describes: leave the PR a draft, label it, and stop with the PR URL and the one action a human must take. `gh pr ready` is diff --git a/plugins/audits/skills/audit-deps/SKILL.md b/plugins/audits/skills/audit-deps/SKILL.md index 56ca7b4..3998349 100644 --- a/plugins/audits/skills/audit-deps/SKILL.md +++ b/plugins/audits/skills/audit-deps/SKILL.md @@ -30,6 +30,9 @@ Keys this skill uses: - `config.labels.dependencies` — label applied to every PR/issue this skill opens (default `dependencies`). - `config.labels.automated` — also applied (default `automated`). +- `config.audits.extraPrLabels` — extra labels applied to every PR (not issue) this skill opens, + including through `create-pr` (default `[]`). Run the existence check once, before this run's + first PR, and drop missing ones; never create one. See [`../../references/extra-pr-labels.md`](../../references/extra-pr-labels.md). - `config.audits.depsPrCap` / `config.audits.depsIssueCap` — per-run caps (default **3 / 5**). - `config.guidelines.*` — if the repo documents a **dependency or license policy** (an allowed-license allowlist, a "pin exactly / never auto-bump X" rule, a "stay on major N of Y" constraint), honor @@ -155,7 +158,8 @@ Everything else is its **own** unit of work: For every PR: branch `deps--` off `config.defaultBranch`, **delegate to `create-pr` if installed** (else run `config.commands.*` as pre-flight; no `--no-verify`), label -`config.labels.dependencies` + `config.labels.automated`, never auto-merge. Caps default **3 PRs / +`config.labels.dependencies` + `config.labels.automated` plus every checked `config.audits.extraPrLabels` +entry (pass them to `create-pr` when delegating), never auto-merge. Caps default **3 PRs / 5 issues**; defer overflow to the next run and note it in the report. ### 6. Report diff --git a/plugins/audits/skills/audit-security/SKILL.md b/plugins/audits/skills/audit-security/SKILL.md index 9dbfd94..a6893bc 100644 --- a/plugins/audits/skills/audit-security/SKILL.md +++ b/plugins/audits/skills/audit-security/SKILL.md @@ -36,6 +36,7 @@ Before anything else, load the repo config (see - `config.commands.{format,lint,build,test}` — pre-flight gate before any PR (skip `null` ones). - `config.labels.security` — label applied to every PR/issue this skill opens (default `security`). - `config.labels.automated` — also applied (default `automated`). + - `config.audits.extraPrLabels` — extra labels applied to every PR (not issue) this skill opens, including through `create-pr` (default `[]`). Run the existence check once, before this run's first PR, and drop missing ones; never create one. See [`../../references/extra-pr-labels.md`](../../references/extra-pr-labels.md). - `config.audits.securityPrCap` / `config.audits.securityIssueCap` — per-run caps (default **3 / 5**). - `config.audits.promoteThreshold` / `config.audits.promoteLookbackDays` — pattern-promotion knobs (default **3** within **90** days). See step 6. - `config.guidelines.invariants` / `config.guidelines.coding` — **the repo's own security rules.** @@ -174,7 +175,9 @@ Process findings **highest-severity first**. For each: - Branch `sec--` off `config.defaultBranch`. - **Delegate to `create-pr` if installed**; else run `config.commands.{format,lint,build,test}` (skip `null`) as pre-flight before pushing. No `--no-verify`. Never auto-merge. - - Label `config.labels.security` + `config.labels.automated`. For a dependency bump, the PR body + - Label `config.labels.security` + `config.labels.automated`, plus every + `config.audits.extraPrLabels` entry that passed the existence check (pass them to `create-pr` + when delegating). For a dependency bump, the PR body must name the CVE/GHSA, the version delta, and that tests pass. - **Issue** (counts against `config.audits.securityIssueCap`) otherwise — describe the vuln, its impact, evidence (`file:line`), and a proposed fix; don't write the code. diff --git a/plugins/audits/skills/audit-tests/SKILL.md b/plugins/audits/skills/audit-tests/SKILL.md index 4b530bc..412be4c 100644 --- a/plugins/audits/skills/audit-tests/SKILL.md +++ b/plugins/audits/skills/audit-tests/SKILL.md @@ -32,6 +32,7 @@ Before anything else, load the repo config (see - `config.commands.coverage` — coverage command. **If `null`, skip the coverage-gap category entirely** (don't invent one). - `config.commands.format` / `config.commands.lint` — pre-flight gates (skip any that are `null`). - `config.labels.testQuality` / `config.labels.automated` — labels applied to every PR/issue this skill opens. + - `config.audits.extraPrLabels` — extra labels applied to every PR (not issue) this skill opens, including through `create-pr` (default `[]`). Run the existence check once, before this run's first PR, and drop missing ones; never create one. See [`../../references/extra-pr-labels.md`](../../references/extra-pr-labels.md). - `config.audits.testPrCap` / `config.audits.testIssueCap` — per-run caps (default **2 / 2** if absent; note the fallback in your report). - `config.audits.promoteThreshold` / `config.audits.promoteLookbackDays` — pattern-promotion knobs (default **3** within **90** days if absent). See step 7. - `config.guidelines.testing` — **the repo's own test conventions.** Read this file in full; it holds the repo-specific rules (the DB/fixture pattern, what may and may not be mocked, isolation rules, assertion expectations, redundant framework boilerplate, naming) that this skill checks the suite against. If it's missing or still full of `TODO` markers, say so in your report and proceed with the language-generic checks only. @@ -207,7 +208,8 @@ git push -u origin "$SLUG" gh pr create --repo --base \ --title "test: " \ --body "