Let the tool runner resolve a tool's own targets

Four rules the bundled skills spelled out in prose now hold in code: a bare
`repomatic run <tool>` builds the invocation CI performs, a tool with no
matching file is skipped rather than handed the whole tree in write mode,
`--verify` answers what a formatter would rewrite, and `cancel-runs` cannot
kill a release matrix. `tests/test_claude_assets.py` pins the facts the
skills still quote to their source, which is how the `repomatic-audit`
snake_case config keys surfaced.

Author: kdeldycke

.claude/skills/repomatic-audit/SKILL.md

@@ -68,8 +68,8 @@ The header (name, `on:`, `concurrency:`) is synced automatically, but custom job
 
 Header-only sync inherits the canonical `paths:` filter verbatim (after `repomatic/**` substitution). When the project's filesystem layout doesn't match, two outcomes are possible:
 
-- **Inherited entries that don't exist locally** (e.g., `tests/**`, `uv.lock` in a non-Python repo): the trigger never fires for them. Coverage is missing, not noisy. Recommend `[tool.repomatic.workflow.ignore_paths]` to drop them.
-- **Locally relevant paths not in the canonical filter** (e.g., `install.sh`, `dotfiles/**` in a config repo): the trigger silently skips PRs that should run CI. Recommend `[tool.repomatic.workflow.extra_paths]` to append them globally, or `[tool.repomatic.workflow.paths]` keyed by filename for a per-workflow wholesale replacement.
+- **Inherited entries that don't exist locally** (e.g., `tests/**`, `uv.lock` in a non-Python repo): the trigger never fires for them. Coverage is missing, not noisy. Recommend `[tool.repomatic.workflow.ignore-paths]` to drop them.
+- **Locally relevant paths not in the canonical filter** (e.g., `install.sh`, `dotfiles/**` in a config repo): the trigger silently skips PRs that should run CI. Recommend `[tool.repomatic.workflow.extra-paths]` to append them globally, or `[tool.repomatic.workflow.paths]` keyed by filename for a per-workflow wholesale replacement.
 
 The relevant config schema lives in `WorkflowConfig` (`repomatic/config.py`): `source_paths`, `extra_paths`, `ignore_paths`, and `paths` (per-workflow override dict, keyed by workflow filename). Per-workflow override is authoritative — it replaces the entire `paths:` list and ignores the other knobs.
 

.github/workflows/autofix.yaml

@@ -143,12 +143,10 @@ jobs:
         if: fromJSON(needs.metadata.outputs.metadata).python_files
         # Ruff is not wrapping comments: https://github.com/astral-sh/ruff/issues/7414
         # We use autopep8 to only wrap long-line comments.
-        # Explicit list of files is provided, as autopep8 is not able to handle find files in ".github" subdirectory.
-        env:
-          PYTHON_FILES: ${{ fromJSON(needs.metadata.outputs.metadata).python_files }}
-        run: >
-          echo "${PYTHON_FILES}" | xargs uv --no-progress run --frozen -- repomatic
-          run autopep8 --
+        # An explicit file list is required, as autopep8 cannot find files in the
+        # ".github" subdirectory on its own: the tool runner resolves it. See
+        # `ToolSpec.default_paths` in repomatic/tool_registry.py.
+        run: uv --no-progress run --frozen -- repomatic run autopep8
       # XXX Ruff is planning to support linting and formatting in one unified command at one point.
       #     See: https://github.com/astral-sh/ruff/issues/8232
       - name: Run Ruff
@@ -183,17 +181,15 @@ jobs:
         with:
           version: "0.12.2"
       - name: Run pyproject-fmt
-        # pyproject-fmt returns exit code 1 when it reformats the file, but
-        # xargs translates any non-zero child exit to 123. Accept both 0 and
-        # 123 since changes are expected in an autofix workflow.
-        env:
-          PYPROJECT_FILES: ${{ fromJSON(needs.metadata.outputs.metadata).pyproject_files }}
+        # pyproject-fmt returns exit code 1 when it reformats the file, which is
+        # the expected outcome in an autofix workflow. No file list: the tool
+        # runner resolves it, which also drops the xargs that used to translate
+        # that 1 into a 123. See `ToolSpec.default_paths` in
+        # repomatic/tool_registry.py.
         run: |
           rc=0
-          echo "${PYPROJECT_FILES}" \
-            | xargs uv --no-progress run --frozen -- repomatic \
-              run pyproject-fmt -- || rc=$?
-          [ "$rc" -eq 0 ] || [ "$rc" -eq 123 ] || exit "$rc"
+          uv --no-progress run --frozen -- repomatic run pyproject-fmt || rc=$?
+          [ "$rc" -eq 0 ] || [ "$rc" -eq 1 ] || exit "$rc"
       - name: Sync pull request
         env:
           GH_TOKEN: ${{ secrets.REPOMATIC_PAT || github.token }}
@@ -233,11 +229,10 @@ jobs:
           restore-keys: |
             repomatic-${{ runner.os }}-${{ runner.arch }}-shfmt-
       - name: Auto-format Markdown
-        env:
-          MARKDOWN_FILES: ${{ fromJSON(needs.metadata.outputs.metadata).markdown_files }}
-        run: >
-          echo "${MARKDOWN_FILES}" | xargs -n1
-          uv --no-progress run --frozen -- repomatic run mdformat --
+        # No file list: the tool runner resolves mdformat's targets and runs it
+        # once per file, the way `xargs -n1` used to here. See
+        # `ToolSpec.default_paths` in repomatic/tool_registry.py.
+        run: uv --no-progress run --frozen -- repomatic run mdformat
       # Runs inside this job, not its own: it corrects what mdformat just wrote,
       # so a separate job would fight this one across two PRs. See
       # repomatic/awesome_toc.py for rationale.
@@ -273,11 +268,11 @@ jobs:
           restore-keys: |
             repomatic-${{ runner.os }}-${{ runner.arch }}-shfmt-
       - name: Format shell scripts
-        env:
-          SHELL_FILES: ${{ fromJSON(needs.metadata.outputs.metadata).shfmt_files }}
-        run: >
-          echo "${SHELL_FILES}" | xargs uv --no-progress run --frozen -- repomatic
-          run shfmt --
+        # No file list: the tool runner resolves shfmt's targets, and skips the
+        # tool outright when there are none. A pathless shfmt reads stdin, and
+        # an empty `xargs` list used to hand it exactly that. See
+        # `ToolSpec.default_paths` in repomatic/tool_registry.py.
+        run: uv --no-progress run --frozen -- repomatic run shfmt
       - name: Sync pull request
         env:
           GH_TOKEN: ${{ secrets.REPOMATIC_PAT || github.token }}
@@ -307,15 +302,10 @@ jobs:
           restore-keys: |
             repomatic-${{ runner.os }}-${{ runner.arch }}-biome-
       - name: Format JSON
-        # Allow comments and trailing commas for JSONC files.
-        # Biome auto-detects well-known JSONC files (tsconfig.json, etc.).
-        env:
-          JSON_FILES: ${{ fromJSON(needs.metadata.outputs.metadata).json_files }}
-        run: |
-          echo "${JSON_FILES}" | xargs \
-            uv --no-progress run --frozen -- repomatic run biome -- \
-            format --write --no-errors-on-unmatched \
-            --json-parse-allow-comments=true --json-parse-allow-trailing-commas=true
+        # No arguments: the tool runner supplies biome's subcommand, its JSONC
+        # parse flags and the file list. See `ToolSpec.default_args` in
+        # repomatic/tool_registry.py.
+        run: uv --no-progress run --frozen -- repomatic run biome
       - name: Sync pull request
         env:
           GH_TOKEN: ${{ secrets.REPOMATIC_PAT || github.token }}
@@ -735,7 +725,7 @@ jobs:
         # against the empty case: with no doc change, an unconditional reformat would open an
         # update-docs PR carrying only pre-existing formatting drift, a byte-for-byte duplicate of
         # the format-pyproject PR (which owns that drift). Same exit-code handling as that job:
-        # xargs turns pyproject-fmt's reformat exit 1 into 123.
+        # pyproject-fmt exits 1 when it reformats.
         env:
           PYPROJECT_FILES: ${{ fromJSON(needs.metadata.outputs.metadata).pyproject_files }}
         run: |
@@ -744,10 +734,8 @@ jobs:
             exit 0
           fi
           rc=0
-          echo "${PYPROJECT_FILES}" \
-            | xargs uv --no-progress run --frozen -- repomatic \
-              run pyproject-fmt -- || rc=$?
-          [ "$rc" -eq 0 ] || [ "$rc" -eq 123 ] || exit "$rc"
+          uv --no-progress run --frozen -- repomatic run pyproject-fmt || rc=$?
+          [ "$rc" -eq 0 ] || [ "$rc" -eq 1 ] || exit "$rc"
       - name: Sync pull request
         env:
           GH_TOKEN: ${{ secrets.REPOMATIC_PAT || github.token }}

.github/workflows/lint.yaml

@@ -126,11 +126,10 @@ jobs:
         if: fromJSON(needs.metadata.outputs.metadata).is_python_project
         run: uv --no-progress sync --frozen --all-extras --all-groups
       - name: Run Mypy
-        env:
-          PYTHON_FILES: ${{ fromJSON(needs.metadata.outputs.metadata).python_files }}
-        run: >
-          echo "${PYTHON_FILES}" | xargs uv --no-progress run --frozen -- repomatic
-          run mypy --
+        # No file list: the tool runner resolves mypy's targets from the same
+        # inventory this workflow's `python_files` comes from. See
+        # `ToolSpec.default_paths` in repomatic/tool_registry.py.
+        run: uv --no-progress run --frozen -- repomatic run mypy
 
   lint-yaml:
     name: 📄 Lint YAML
@@ -148,7 +147,7 @@ jobs:
         with:
           version: "0.12.2"
       - name: Run yamllint
-        run: uv --no-progress run --frozen -- repomatic run yamllint -- .
+        run: uv --no-progress run --frozen -- repomatic run yamllint
 
   lint-zsh:
     name: 🐚 Lint Zsh
@@ -221,7 +220,7 @@ jobs:
         with:
           version: "0.12.2"
       - name: Run zizmor
-        run: uv --no-progress run --frozen -- repomatic run zizmor -- .
+        run: uv --no-progress run --frozen -- repomatic run zizmor
 
   lint-awesome:
     name: 🌟 Lint awesome

changelog.md

@@ -6,6 +6,11 @@
 > This version is **not released yet** and is under active development.
 
 - `lint-repo` now warns when a Sphinx project's GitHub website field differs from the documentation URL declared in `[project.urls]`.
+- New `repomatic run <tool> --verify` reporting which files a formatter would rewrite, without touching the working tree.
+- `repomatic run` now resolves a tool's targets itself when given no arguments, running the invocation CI performs. A tool with no matching file is skipped instead of invoked pathless.
+- `lint-changelog` now warns about a released section holding no entry.
+- `cancel-runs` now spares a run whose head commit carries `[changelog] Release`, so a sweep of the default branch cannot kill a release matrix.
+- Fix the `[tool.repomatic.workflow]` key names the `repomatic-audit` skill recommends: they are `extra-paths` and `ignore-paths`, not the snake_case attribute names.
 
 ## [`7.11.0` (2026-08-13)](https://github.com/kdeldycke/repomatic/compare/v7.10.0...v7.11.0)
 

docs/tests.md

@@ -108,6 +108,15 @@
    :undoc-members:
 ```
 
+## `tests.test_claude_assets` module
+
+```{eval-rst}
+.. automodule:: tests.test_claude_assets
+   :members:
+   :show-inheritance:
+   :undoc-members:
+```
+
 ## `tests.test_config` module
 
 ```{eval-rst}

repomatic/changelog.py

@@ -981,6 +981,51 @@ def warn_on_long_bullets(changelog: Changelog, threshold: int) -> None:
                 )
 
 
+def warn_on_empty_sections(changelog: Changelog) -> None:
+    """Warn about released sections holding no entry, non-fatally.
+
+    A published heading with nothing under it reads as broken to anyone
+    scanning release notes, and it is not merely cosmetic: the GitHub
+    release body is rebuilt from this section, so an empty one publishes an
+    empty release. `claude.md` § Changelog and docs updates gives the fix,
+    which is to name what actually moved rather than to leave the section
+    blank.
+
+    Only *released* sections are inspected. The unreleased section is
+    legitimately empty for most of a cycle, since the post-release bump
+    creates it with no entries, so flagging it would fire on every push in
+    the hours after a release and train the reader to ignore the check.
+    That is the mirror of {func}`warn_on_long_bullets`, which inspects the
+    unreleased section alone because re-flagging immutable history is the
+    noise there.
+
+    Availability, editorial and yanked admonitions live in their own
+    {class}`VersionElements` fields, so a section carrying nothing but a
+    `[!WARNING]` about missing binaries still counts as empty: an
+    admonition explains a caveat, it does not say what changed.
+
+    :param changelog: The parsed changelog to inspect.
+    """
+    for version, _date in sorted(
+        changelog.extract_all_releases(), key=lambda r: Version(r[0]), reverse=True
+    ):
+        elements = changelog.decompose_version(version)
+        if split_changelog_bullets(elements.changes):
+            continue
+        logging.warning(
+            f"⚠ {version}: released section holds no entry. Add one naming what "
+            f"moved, even on a purely mechanical cycle."
+        )
+        emit_annotation(
+            AnnotationLevel.WARNING,
+            f"Changelog section for {version} is empty. A published release "
+            f"heading with no entries reads as broken, and the GitHub release "
+            f"body is rebuilt from it. Name what moved, per "
+            f"https://github.com/kdeldycke/repomatic/blob/main/claude.md"
+            f"#changelog-and-docs-updates",
+        )
+
+
 @dataclass
 class ReleaseSources:
     """The external lookups a changelog's dates and availability are checked against.
@@ -1364,6 +1409,10 @@ def lint_changelog_dates(
     GitHub releases, or PyPI packages but have no corresponding changelog
     entry. Orphans are logged as warnings and cause a non-zero exit code.
 
+    Two non-fatal content checks run first and never affect the exit code:
+    {func}`warn_on_long_bullets` over the unreleased section, and
+    {func}`warn_on_empty_sections` over the released ones.
+
     When `fix` is enabled, date mismatches are corrected in-place and
     admonitions are added to the changelog:
 
@@ -1417,6 +1466,7 @@ def lint_changelog_dates(
     content = changelog_path.read_text(encoding="UTF-8")
     changelog = Changelog(content)
     warn_on_long_bullets(changelog, bullet_word_threshold)
+    warn_on_empty_sections(changelog)
     releases = changelog.extract_all_releases()
 
     if not releases:

repomatic/cli.py

@@ -236,6 +236,7 @@
 from .tool_runner import (
     resolve_config_source,
     run_tool,
+    verify_via_write_path,
 )
 from .version_sync import strip_dev_suffix
 from .virustotal import (
@@ -2160,6 +2161,16 @@ def lint_repo(
 @argument("tool_name", required=False, default=None)
 @argument("extra_args", nargs=-1, type=UNPROCESSED)
 @option("--list", "list_tools", is_flag=True, help="List all managed tools.")
+@option(
+    "--verify",
+    is_flag=True,
+    default=False,
+    help=(
+        "Report which targets the tool would rewrite, without touching them."
+        " Runs the write path against throwaway copies, so the answer holds"
+        " even for a tool whose own --check mode is unreliable."
+    ),
+)
 @option(
     "--version",
     "tool_version",
@@ -2189,6 +2200,7 @@ def run_cmd(
     tool_name,
     extra_args,
     list_tools,
+    verify,
     tool_version,
     checksum,
     skip_checksum,
@@ -2209,6 +2221,10 @@ def run_cmd(
         repomatic run yamllint -- --strict .
         repomatic run zizmor -- --offline .
 
+    \b
+    Report what a formatter would rewrite, leaving the tree alone:
+        repomatic run mdformat --verify -- changelog.md
+
     \b
     Override the pinned version:
         repomatic run shfmt --version 3.14.0 --skip-checksum -- .
@@ -2230,6 +2246,19 @@ def run_cmd(
             "Missing argument 'TOOL_NAME'. Use --list to see available tools."
         )
 
+    if verify:
+        exit_code, drifted = verify_via_write_path(
+            tool_name,
+            extra_args=extra_args,
+            version=tool_version,
+            checksum=checksum,
+            skip_checksum=skip_checksum,
+            no_cache=no_cache,
+        )
+        for path in drifted:
+            echo(f"Would rewrite: {path}")
+        ctx.exit(exit_code)
+
     exit_code = run_tool(
         tool_name,
         extra_args=extra_args,

repomatic/git_ops.py

@@ -100,6 +100,23 @@
 `bump-version` template title, and the workflow gates to this prefix.
 """
 
+RELEASE_COMMIT_PREFIX = f"{CHANGELOG_COMMIT_PREFIX}Release"
+"""Head-commit-message prefix marking a push that carries the release commit.
+
+The coarser sibling of {data}`RELEASE_COMMIT_PATTERN`: where that one
+validates and extracts a version, this is the prefix test every workflow's
+`cancel-in-progress` gate performs, so a release run is never cancelled by a
+later push entering its concurrency group. A prefix is deliberately weaker
+than the full pattern here, because the question is "does this push carry a
+release" rather than "which version is it", and answering it must not depend
+on the version number parsing.
+
+{func}`repomatic.github.actions.cancel_superseded_runs` applies the same test
+from the API side, which is the half GitHub's own concurrency mechanism
+cannot cover: a manual sweep of a branch's live runs enters no concurrency
+group at all.
+"""
+
 RELEASE_COMMIT_PATTERN = re.compile(
     r"^\[changelog\] Release v(?P<version>[0-9]+\.[0-9]+\.[0-9]+)$"
 )