tune-perl-ci

What this skill does

# Tune Perl CI

## Overview

**Seven transforms applied to Perl CI workflows under `.github/workflows/`:**

1. `fail-fast: false` on every matrix job
2. Extend Linux + macOS matrices through Perl 5.42
3. Bump build + coverage jobs to `perldocker/perl-tester:5.42`
4. Restrict the `push:` trigger to the default branch
5. Add a workflow-level `concurrency:` cancel-in-progress block
6. Install deps with `setup-cpm` + a `cpm install` run step
7. Drop macOS + Windows tests for Perls < 5.24

**Core principle:** modernize the workflow without changing intent. Each transform lands as its own commit so any single change is revertable. Re-running the skill on an already-tuned workflow is a no-op.

## Dispatch this skill to a subagent

When this skill is invoked, dispatch the work to a `general-purpose` subagent via the `Agent` tool. **Do not run the seven transforms inline in the caller's context.**

Why:
- Each transform reads every in-scope workflow, computes a diff, writes the file, runs `yaml.safe_load` + a structural assertion, then stages and commits. Across seven transforms and multiple workflows, that is a lot of `Read`/`Edit`/`Bash` tool traffic — none of it useful to the caller's session.
- The caller only needs the final summary line (`Applied N transforms across M files in K commits`) and the list of commit SHAs. Everything else is intermediate state.

How to dispatch:
- Brief the subagent with this SKILL.md as its working spec — pass the path to the file or invoke the skill from inside the subagent.
- Tell the subagent the working directory and (optionally) a single workflow path if the caller specified one.
- Require the subagent to report back, in under 200 words: the summary line, the per-transform commit SHAs, and any skipped transforms with reason.
- If a transform's verification fails, the subagent must stop and surface the failure rather than continuing or auto-reverting.

If the user explicitly asks to run inline (e.g. "do it here so I can watch"), honour that — the subagent dispatch is the default, not a hard requirement.

## When to Use

- User asks to tune / modernize / harden CI on a Perl repo
- Workflow uses `perldocker/perl-tester`, `shogo82148/actions-setup-perl`, `perl-actions/install-with-cpm`, or `perl-actions/install-with-cpanm`
- A Dist::Zilla starter template has produced a CI workflow that is a few years stale

**Skip when:**
- No `.github/workflows/*.yml` matches the action-signature detection rule below — there's nothing to tune
- The user has deliberately customised concurrency or branch filters — idempotency preserves their choices

## Scope Detection

For each `.github/workflows/*.yml`, the file is **in scope** if it mentions any of:

- `perldocker/perl-tester`
- `shogo82148/actions-setup-perl`
- `perl-actions/install-with-cpm`
- `perl-actions/install-with-cpanm`

Other workflows are skipped silently. If no workflow file matches across the repo, report "no Perl workflows found" and exit cleanly.

If the caller passes a single workflow path as an argument, operate only on that file (still apply the detection rule for safety; bail out with a clear message if it isn't Perl-shaped).

## The Six Transforms

### 1. `fail-fast: false` on every matrix job

**What:** insert `fail-fast: false` under every `strategy:` block whose nested `matrix:` exists. Flip `fail-fast: true` to `false` if already present. No-op if `false` already.

**Why:** when `fail-fast:` is missing it defaults to `true`. One failing Perl/OS cell shouldn't mask the rest of the matrix.

**Before:**

```yaml
test_linux:
  strategy:
    matrix:
      perl-version: ["5.34"]
```

**After:**

```yaml
test_linux:
  strategy:
    fail-fast: false
    matrix:
      perl-version: ["5.34"]
```

### 2. Extend Linux + macOS matrices through Perl 5.42

**What:** in jobs whose `matrix.perl-version` axis exists **and** the job is either

- a Linux container (`container.image` starts with `perldocker/perl-tester`), or
- macOS (`runs-on: macos-*` or matrix `os:` includes a `macos-*` entry),

append any of `"5.36"`, `"5.38"`, `"5.40"`, `"5.42"` not already in the list. Preserve older entries. Match the file's quote style.

**Skip Windows.** Disabling or extending Windows is situational, not a general best practice.

**Hard-coded target:** `5.42`. A future revision can teach the skill to discover the latest stable.

**Before:**

```yaml
perl-version:
  - "5.10"
  - "5.30"
  - "5.34"
```

**After:**

```yaml
perl-version:
  - "5.10"
  - "5.30"
  - "5.34"
  - "5.36"
  - "5.38"
  - "5.40"
  - "5.42"
```

### 3. Bump build + coverage jobs to `perldocker/perl-tester:5.42`

**What:** replace `container.image:` values matching `perldocker/perl-tester:<X.YY>` with `perldocker/perl-tester:5.42`, but **only when the tag is a literal version** — never touch an image whose tag contains `${{` (those use the matrix variable on purpose).

**Why:** the build job produces the release artifact and the coverage job produces the coverage report. Both should run on the latest stable image, not a stale pin.

**Before:**

```yaml
build:
  container:
    image: perldocker/perl-tester:5.34
```

**After:**

```yaml
build:
  container:
    image: perldocker/perl-tester:5.42
```

### 4. Restrict `push:` to the default branch

**What:** in top-level `on.push.branches:`, replace the list with a single-entry list naming the default branch. Leave `pull_request:` and `workflow_dispatch:` alone (even if they have their own `branches:` filter).

**Skip** transform 4 if `on.push:` itself is absent — nothing to restrict. If the key is present but `branches:` is missing, add `branches:` with the resolved default branch.

**Default branch resolution:** Resolve the default branch with `gh repo view --json defaultBranchRef -q .defaultBranchRef.name` (fall back to `main`, then `master`).

**Why:** avoid double CI runs when a push is also part of a PR. Each pushed commit triggers both a push run and a PR run, doubling queue time and burning Actions minutes.

**Before:**

```yaml
on:
  push:
    branches:
      - "*"
  pull_request:
  workflow_dispatch:
```

**After (default branch is `main`):**

```yaml
on:
  push:
    branches:
      - main
  pull_request:
  workflow_dispatch:
```

### 5. Add a workflow-level `concurrency:` block

**What:** insert this block at workflow level, directly after the `on:` block:

```yaml
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
```

**Skip** if any `concurrency:` already exists at workflow level — the user has deliberately customised the concurrency block.

**Why:** new pushes to the same ref cancel the still-running job from the previous push.

### 6. Install deps with `setup-cpm` + a `cpm install` run step

**What:** for every step using either `perl-actions/install-with-cpm@<any-ref>` or `perl-actions/install-with-cpanm@<any-ref>`, replace the single composite step with **two** steps:

1. A setup step that installs the single-file `cpm` tool:

   ```yaml
   - uses: perl-actions/setup-cpm@v1
     with:
       version: compat
   ```

2. An explicit install run step (faithful arg mapping from the old step):

   ```yaml
   - name: <old-step-name>
     run: cpm install -g --cpanfile <cpanfile-value> <args-verbatim>
   ```

Mapping rules:
- Carry the old step's `name:` onto the `cpm install` run step so the CI log keeps its descriptive label. If the old step had no `name:`, omit it.
- The old `cpanfile:` value becomes `--cpanfile <value>`. If no `cpanfile:` key was present, omit `--cpanfile` (cpm reads `./cpanfile` by default).
- The old `args:` value is appended verbatim after `--cpanfile …` (e.g. `--with-recommends --with-suggests --with-test`).
- Keep `-g` (global install) to preserve `install-with-cpm`'s default global-install behavior.
- **Drop the old `sudo:` key.** No sudo is needed: `perldocker/perl-tester` containers run as root, and `shogo82148/actions-setup-perl` provisions a user-local Perl, so the install target is already writable