Update instructions

Author: kdeldycke

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

@@ -25,7 +25,8 @@ You perform a comprehensive audit of a downstream repository against the upstrea
 Before flagging an issue, verify that the gap isn't **deliberate** or covered by a runtime mechanism. Common false positives:
 
 - **`[tool.repomatic] exclude` is authoritative.** Files listed there (like `workflows/changelog.yaml` or `labels`) are intentionally absent on disk. Do **not** report them as MISSING.
-- **Bundled defaults applied at runtime.** Some config is materialized from the bundled template at runtime when the file is absent: `[tool.ruff]`/`[tool.typos]` defaults from the tool registry are applied without requiring an on-disk copy. **Absence of these files is not a problem** — it is the intended state when the user is happy with the bundled policy. Only flag DRIFT if the user wants to deviate from the bundled policy.
+- **Bundled defaults applied at runtime.** Some config is materialized from the bundled template at runtime when the file is absent, so no on-disk copy is needed. **Absence of these files is not a problem**: it is the intended state when the user is happy with the bundled policy. Only flag DRIFT if the user wants to deviate from it. Exactly five tools carry such a fallback, the ones whose `ToolSpec` sets `default_config` in `repomatic/tool_registry.py`: `actionlint`, `mdformat`, `ruff`, `yamllint` and `zizmor`.
+- **A `[tool.X]` section is never a candidate for deletion.** The inverse of the rule above, and the more expensive mistake. Every other tool has no `default_config`, so its resolution chain has no level 3 to fall back on: `lychee`, `typos`, `mypy`, `pytest`, `coverage`, `bumpversion` and `uv` are *deployed* into `pyproject.toml` by `repomatic init`, and that section is the only config the tool will ever see. Deleting it does not restore inheritance from a bundled default, it drops the tool to level 4 and runs it bare, silently discarding every rule the section held. Read the tool's `default_config` before proposing a section be dropped "to inherit upstream updates". A deployed section that has gone stale is fixed by re-running `repomatic init`, which resyncs the components marked `SyncMode.ONGOING` in `repomatic/registry.py`.
 - **Generator artifacts vs user error.** When local thin-callers diverge from upstream (e.g., extra `workflow_dispatch:`, missing `paths:`), the cause may be the **upstream generator**, not downstream tampering. Inspect `repomatic/github/workflow_sync.py` (`generate_thin_caller`, `_adapt_trigger_paths`, `generate_workflow_header`) before recommending the user re-run `repomatic init` to "fix" something `init` itself produced.
 - **Project-level `claude.md` may live under a sub-directory.** `[tool.repomatic] agents.location` and `skills.location` indicate a project where `.claude/` is not at the root (e.g., dotfiles repos with `dotfiles/.claude/CLAUDE.md`). Search the configured location, not just `./CLAUDE.md`.
 
@@ -41,7 +42,19 @@ When in doubt, search the upstream codebase to confirm whether a behavior is int
 
 ### Fetching reference files
 
-Use `gh api repos/kdeldycke/repomatic/contents/{path} --jq '.content' | base64 -d` to fetch upstream reference files.
+Fetch every reference file at **the version the downstream repo has actually adopted**, never at the tip of `main`. The Context block above prints the `uses:` pins; take the tag from there and pass it as `ref` on every call:
+
+```shell-session
+$ gh api "repos/kdeldycke/repomatic/contents/{path}?ref=vX.Y.Z" --jq '.content' | base64 -d
+```
+
+An unpinned fetch resolves to `main`, which carries unreleased work. Audited against it, every change waiting for the next release reads as downstream drift, and the "fix" that follows can be worse than the phantom problem: a `[tool.X]` section matching its adopted bundled template exactly gets reported as stale, because `main` has since grown entries no release has shipped yet.
+
+Keep the two axes apart in the report, because only one of them is actionable:
+
+- **Drift** is a difference against the adopted tag. Report it.
+- **Available in a newer release** is a difference between the adopted tag and a later published one. That is an upgrade note, never a DRIFT row. Confirm the version actually exists with `gh api repos/kdeldycke/repomatic/releases --jq '.[].tag_name'`.
+- **Only on `main`** is unreleased and belongs in neither list. The changelog's top section is headed with a `.devN` version and a "not released yet" warning; anything described there is not yet available to any downstream repo.
 
 ### 1. Workflow audit (`workflows`)
 

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

@@ -173,7 +173,7 @@ Flag stale or unjustified entries as warnings.
 
 ### Cross-repo reference
 
-When the context shows `DOWNSTREAM`, also compare the dependency list against the canonical `repomatic` `pyproject.toml` (fetch with `gh api repos/kdeldycke/repomatic/contents/pyproject.toml --jq '.content' | base64 -d`) to identify:
+When the context shows `DOWNSTREAM`, also compare the dependency list against the canonical `repomatic` `pyproject.toml`, fetched at the version this repo has adopted rather than at the tip of `main`: take the tag from the `uses:` pins in `.github/workflows/`, then run `gh api "repos/kdeldycke/repomatic/contents/pyproject.toml?ref=vX.Y.Z" --jq '.content' | base64 -d`. An unpinned fetch resolves to `main`, whose floors may have moved for a release the downstream repo cannot use yet, turning unreleased work into a phantom "downstream is behind" finding. Use it to identify:
 
 - Shared dependencies where the downstream floor is lower than upstream (may be missing a needed bump).
 - Shared dev dependencies where upstream has moved to a newer group structure.

changelog.md

@@ -23,6 +23,8 @@
 - New `ToolSpec.rewrite_exit_code` naming the status a formatter returns after rewriting a file. A run exiting with it while leaving every target unchanged is reported as a crash (exit code `70`) instead of passing for a successful reformat: pyproject-fmt uses `1` for both, so its panics reached the autofix job as green runs that formatted nothing.
 - `repomatic run --verify` now surfaces a tool that failed on the throwaway copies, instead of reading the unformatted result as an absence of drift.
 - 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.
+- Fix the `repomatic-audit` and `repomatic-deps` skills auditing a downstream repository against `main` instead of the release it adopted, which reported unreleased work as local drift.
+- The `repomatic-audit` skill now names the five tools a bundled default actually covers at runtime, and warns that deleting any other `[tool.X]` section runs the tool bare instead of restoring one.
 - Every job now caps its runtime with `timeout-minutes`, so a hung job frees its runner in minutes instead of holding it for the platform's 6-hour ceiling. Downstream callers inherit the caps.
 - The bundled `lychee.toml` now excludes `bitdefender.com`, `npmjs.com`, `star-history.com` and `githubstatus.com`, which answer bots with 403, 405 or JavaScript rather than a link.