ruff-sync 0.1.2.dev1__tar.gz → 0.1.3.dev2__tar.gz

ruff_sync-0.1.3.dev2/.agents/skills/ruff-sync-usage/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: ruff-sync-usage
+description: >-
+  Configure and operate ruff-sync to synchronize Ruff linter settings across Python projects.
+  Use when the user wants to set up ruff-sync, sync Ruff config from an upstream source,
+  check for configuration drift, integrate ruff-sync into CI, troubleshoot sync issues,
+  or keep Ruff rules consistent across multiple repositories.
+---
+
+# ruff-sync Usage
+
+`ruff-sync` pulls a canonical Ruff configuration from an upstream URL and merges it into your local project, preserving comments, whitespace, and per-project overrides.
+
+## Quick Start
+
+```bash
+# 1. Install
+uv tool install ruff-sync
+
+# 2. Sync from an upstream repo (extracts [tool.ruff] / ruff.toml automatically)
+ruff-sync https://github.com/my-org/standards
+
+# 3. Review the changes before committing
+git diff pyproject.toml
+```
+
+## Persist Configuration
+
+Add to `pyproject.toml` so you don't need to pass CLI args every time:
+
+```toml
+[tool.ruff-sync]
+upstream = "https://github.com/my-org/standards"
+exclude = [
+    "target-version",            # each project uses its own Python version
+    "lint.per-file-ignores",     # project-specific suppressions
+    "lint.ignore",
+    "lint.isort.known-first-party",
+]
+```
+
+Then just run `ruff-sync` (no arguments needed).
+
+See [references/configuration.md](references/configuration.md) for all config keys and defaults.
+
+## Common Workflows
+
+### Initial Project Setup
+
+```
+Setup Progress:
+- [ ] 1. Install ruff-sync (uv tool install ruff-sync)
+- [ ] 2. Check for `.pre-commit-config.yaml` — if present, ensure the `ruff` hook is used
+- [ ] 3. Add `[tool.ruff-sync]` to `pyproject.toml` with upstream URL and exclusions
+- [ ] 4. If `.pre-commit-config.yaml` exists, set `pre-commit-version-sync = true` in `[tool.ruff-sync]`
+- [ ] 5. Run `ruff-sync` to pull the upstream config
+- [ ] 6. Review `git diff`
+- [ ] 7. Fix any new lint errors: `uv run ruff check . --fix`
+- [ ] 8. Commit
+```
+
+### Upstream Layers (multi-source)
+
+Stack multiple upstream sources — later entries win on conflict:
+
+```toml
+[tool.ruff-sync]
+upstream = [
+    "https://github.com/my-org/python-standards",   # base company rules
+    "https://github.com/my-org/ml-team-tweaks",     # team-specific overrides
+]
+```
+
+### CI Drift Check
+
+```
+CI Setup Progress:
+- [ ] 1. Add ruff-sync check step to CI workflow (see references/ci-integration.md)
+- [ ] 2. Decide: --semantic for value-only checks, or full string comparison
+- [ ] 3. Set output format: --output-format github for PR annotations
+- [ ] 4. Set exit-code expectations (0 = in sync, 1 = config drift, 2 = pre-commit only)
+- [ ] 5. Verify locally: `ruff-sync check --semantic`
+```
+
+Keep the `ruff-pre-commit` hook version in `.pre-commit-config.yaml` aligned with the project's Ruff version.
+
+**Recommendation:** Always prefer the persistent TOML configuration over the ephemeral `--pre-commit` CLI flag.
+
+```toml
+[tool.ruff-sync]
+pre-commit-version-sync = true
+```
+
+Then run `ruff-sync` — it updates the hook rev automatically. Exit code 2 means only the hook version is out of sync (Ruff config itself is fine).
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | In sync — no action needed |
+| `1` | Ruff config is out of sync with upstream |
+| `2` | Config is in sync, but pre-commit hook version is stale (only when `--pre-commit` is active) |
+
+## URL Formats Supported
+
+All of these work as the `upstream` value:
+
+```bash
+ruff-sync https://github.com/my-org/standards              # repo root
+ruff-sync https://github.com/my-org/standards/tree/main/cfg  # subdirectory
+ruff-sync https://github.com/my-org/standards/blob/main/ruff.toml  # specific file
+ruff-sync https://raw.githubusercontent.com/my-org/standards/main/pyproject.toml
+ruff-sync git@github.com:my-org/standards.git             # SSH (shallow clone)
+```
+
+## CLI Reference (Short)
+
+| Flag | Meaning |
+|------|---------|
+| `--output-format` | `text` (default), `json`, `github` (PR annotations) |
+| `--semantic`      | Ignore whitespace/comments in `check` |
+| `--pre-commit`    | Sync `.pre-commit-config.yaml` hook version |
+| `--save`          | Persist CLI args to `pyproject.toml` |
+
+## Gotchas
+
+- **`exclude` uses dotted paths, not TOML paths.** `lint.per-file-ignores` refers to the `per-file-ignores` key inside `[tool.ruff.lint]`. Do NOT write `tool.ruff.lint.per-file-ignores`.
+- **Use `--init` only for new projects.** `ruff-sync` requires an existing `pyproject.toml` or `ruff.toml`. Pass `--init` to scaffold one if the directory is empty. This will automatically generate a `[tool.ruff-sync]` configuration block for future syncs.
+- **Use `--save` to persist CLI arguments.** If you want to update an existing `pyproject.toml` with a new upstream URL or exclusion, pass `--save` to write the new configuration to the file.
+- **`--semantic` ignores comments and whitespace.** Use it in CI to avoid false positives from cosmetic local edits. Omit it for strict byte-for-byte checks.
+- **SSH URLs trigger a shallow clone.** `git@github.com:...` URLs use `git clone --filter=blob:none --depth=1` — no `git` credential issues as long as SSH auth is configured.
+- **Later upstreams win in `upstream` lists.** In a multi-source list, keys set by entry 2 overwrite keys from entry 1.
+- **Config discovery order matters.** When targeting a directory, `ruff-sync` looks for `ruff.toml` -> `.ruff.toml` -> `pyproject.toml` in that order.
+- **Pre-commit exit code 2 is intentional.** A `2` exit from `ruff-sync check` means the Ruff _config_ is fine, only the pre-commit hook tag is stale. You may want to treat this differently from a full config drift (exit 1) in CI.
+- **Prefer TOML for pre-commit sync.** While `--pre-commit` works on the CLI, setting `pre-commit-version-sync = true` in `pyproject.toml` is the recommended way to ensure hook versioning stays consistent for all contributors.
+
+## References
+
+- **[Configuration reference](references/configuration.md)** — All `[tool.ruff-sync]` keys, types, and defaults
+- **[Troubleshooting](references/troubleshooting.md)** — Common errors and how to resolve them
+- **[CI integration recipes](references/ci-integration.md)** — GitHub Actions, GitLab CI, pre-commit hook

ruff_sync-0.1.3.dev2/.agents/skills/ruff-sync-usage/references/ci-integration.md

@@ -0,0 +1,134 @@
+# CI Integration Recipes
+
+## GitHub Actions
+
+### Basic Drift Check
+
+Add this step to any existing workflow (e.g., `.github/workflows/ci.yaml`):
+
+```yaml
+- name: Check Ruff config is in sync
+  run: ruff-sync check --semantic --output-format github
+```
+
+`--semantic` ignores cosmetic differences (comments, whitespace) — only real value or rule changes cause failure.
+`--output-format github` creates inline PR annotations for errors and warnings.
+
+### Full Workflow Example
+
+Uses [`astral-sh/setup-uv`](https://github.com/astral-sh/setup-uv) — the official action that installs uv, adds it to PATH, and handles caching. No separate `setup-python` step needed.
+
+```yaml
+name: Ruff sync check
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ruff-sync-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.10.x"   # pin to a minor range; Dependabot can keep this current
+
+      - name: Install ruff-sync
+        run: uv tool install ruff-sync
+
+      - name: Check Ruff config is in sync with upstream
+        run: ruff-sync check --semantic --output-format github
+```
+
+### With Pre-commit Sync Check
+
+To also verify the pre-commit hook version, add the `--pre-commit` flag. Any non-zero exit code (1 = config drift, 2 = stale hook rev) will fail the CI step:
+
+```yaml
+- name: Check Ruff config and pre-commit hook
+  run: ruff-sync check --semantic --pre-commit --output-format github
+```
+
+(Note: For better consistency, you can instead set `pre-commit-version-sync = true` in your `pyproject.toml` — then `ruff-sync check --semantic` will automatically include this check.)
+
+---
+
+## GitLab CI
+
+Use the official [`ghcr.io/astral-sh/uv`](https://docs.astral.sh/uv/guides/integration/gitlab/) image — uv is already on the `PATH`, no install step needed.
+
+```yaml
+variables:
+  UV_VERSION: "0.10"
+  PYTHON_VERSION: "3.12"
+  BASE_LAYER: bookworm-slim
+  UV_LINK_MODE: copy   # required: GitLab mounts build dir separately
+
+ruff-sync-check:
+  stage: lint
+  image: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_VERSION-$BASE_LAYER
+  script:
+    - uv tool install ruff-sync
+    - ruff-sync check --semantic
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+    - if: '$CI_COMMIT_BRANCH == "main"'
+```
+
+---
+
+## Pre-commit Hook
+
+Run `ruff-sync check` as a pre-commit hook to catch drift before every commit:
+
+```yaml
+# .pre-commit-config.yaml
+- repo: https://github.com/Kilo59/ruff-sync
+  rev: v0.1.0   # pin to a release tag
+  hooks:
+    - id: ruff-sync-check
+```
+
+The hook runs `ruff-sync check --semantic` automatically. Update `rev` to the latest ruff-sync version.
+
+---
+
+## Makefile
+
+```makefile
+.PHONY: sync-check sync
+
+sync-check:
+	ruff-sync check --semantic
+
+sync:
+	ruff-sync
+	git diff pyproject.toml
+```
+
+---
+
+## Deciding: `--semantic` vs. Full String Check
+
+| Mode | Fails on | Use when |
+|------|---------|---------|
+| `ruff-sync check --semantic` | Value/rule differences only | CI — avoids false positives from local comment edits |
+| `ruff-sync check` | Any string difference (comments, whitespace, values) | Enforcing exact config file consistency |
+
+Recommendation: **use `--semantic` in CI** and save the full-string check for auditing purposes.
+
+---
+
+## Dogfooding (Self-Check)
+
+If `ruff-sync` is configured in the project's own `pyproject.toml` (the standard case), just run:
+
+```bash
+ruff-sync check
+```
+
+No URL argument needed — it reads `upstream` from `[tool.ruff-sync]`.

ruff_sync-0.1.3.dev2/.agents/skills/ruff-sync-usage/references/configuration.md

@@ -0,0 +1,140 @@
+# ruff-sync Configuration Reference
+
+All keys live under `[tool.ruff-sync]` in `pyproject.toml`.
+
+## Keys
+
+### `upstream` *(required unless passed on CLI)*
+
+The URL(s) of your canonical Ruff configuration. Accepts a single string or a list. When a list is given, sources are merged in order — later entries win on conflict.
+
+```toml
+# Single source
+upstream = "https://github.com/my-org/standards"
+
+# Multiple sources (base + team overlay)
+upstream = [
+    "https://github.com/my-org/python-standards",
+    "https://github.com/my-org/ml-team-tweaks",
+]
+```
+
+**Supported URL formats (with automatic browser link resolution):**
+- GitHub/GitLab repo root: `https://github.com/<org>/<repo>`
+- Subdirectory (tree): `https://github.com/<org>/<repo>/tree/main/configs/ruff`
+- Specific file (blob): `https://github.com/<org>/<repo>/blob/main/pyproject.toml`
+- Raw URL: `https://raw.githubusercontent.com/<org>/<repo>/main/pyproject.toml`
+- SSH (triggers shallow clone): `git@github.com:<org>/<repo>.git`
+
+---
+
+### `exclude` *(default: `["lint.per-file-ignores"]`)*
+
+List of config keys to protect from being overwritten by upstream. Use dotted paths to reference nested keys.
+
+```toml
+exclude = [
+    "target-version",                       # keep per-project Python version
+    "lint.per-file-ignores",               # keep per-file suppressions
+    "lint.ignore",                          # keep repo-specific rule suppressions
+    "lint.isort.known-first-party",         # keep first-party package list
+    "lint.flake8-tidy-imports.banned-api",  # keep banned API list
+    "lint.pydocstyle.convention",           # keep docstring style choice
+]
+```
+
+**Key format:**
+- Top-level keys: `"target-version"`, `"line-length"`
+- Nested keys (dotted): `"lint.select"`, `"lint.per-file-ignores"`, `"format.quote-style"`
+- These are ruff config key names, NOT TOML paths — do NOT include `tool.ruff.` prefix.
+
+---
+
+### `branch` *(default: `"main"`)*
+
+The branch, tag, or commit hash to use when fetching from a Git repo URL.
+
+```toml
+branch = "develop"
+```
+
+---
+
+### `path` *(default: `""`)*
+
+Path inside the repository where the config lives, when it's not at the repo root.
+
+```toml
+path = "configs/ruff"
+```
+
+Useful when combined with a repo-root `upstream` URL:
+
+```toml
+upstream = "git@github.com:my-org/standards.git"
+path = "configs/strict"
+```
+
+---
+
+### `to` *(default: `"."`)*
+
+Local target directory or file path to sync into.
+
+```toml
+to = "services/api"   # sync into a subdirectory of the monorepo
+```
+
+---
+
+### `pre-commit-version-sync` *(default: `false`)*
+
+When `true`, `ruff-sync` also updates the `ruff-pre-commit` hook rev in `.pre-commit-config.yaml` to match the Ruff version installed in the project.
+
+> [!TIP]
+> This is the preferred way to enable pre-commit hook synchronization as it persists the setting in your project configuration.
+
+```toml
+pre-commit-version-sync = true
+```
+
+Requires a `- repo: https://github.com/astral-sh/ruff-pre-commit` entry in `.pre-commit-config.yaml`.
+
+---
+
+## Full Example
+
+```toml
+[tool.ruff-sync]
+upstream = [
+    "https://github.com/my-org/python-standards",
+    "https://github.com/my-org/backend-team-rules",
+]
+exclude = [
+    "target-version",
+    "lint.per-file-ignores",
+    "lint.ignore",
+    "lint.isort.known-first-party",
+]
+branch = "main"
+path = "ruff"
+to = "."
+pre-commit-version-sync = true
+```
+
+## CLI Overrides
+
+All config keys have CLI equivalents. CLI values always win over `pyproject.toml`:
+
+```bash
+ruff-sync https://github.com/my-org/standards --exclude lint.ignore --branch develop --output-format github
+```
+
+## Config Discovery for `ruff.toml` Projects
+
+If the local target is a directory, ruff-sync looks for config in this order:
+1. `ruff.toml`
+2. `.ruff.toml`
+3. `pyproject.toml`
+
+If the upstream is a `ruff.toml`, it syncs the root config object (no `[tool.ruff]` section extraction needed).

ruff_sync-0.1.3.dev2/.agents/skills/ruff-sync-usage/references/troubleshooting.md

@@ -0,0 +1,137 @@
+# Troubleshooting ruff-sync
+
+## Config Not Changing After Sync
+
+**Symptom:** `ruff-sync` runs without error, but `git diff` shows no changes.
+
+**Likely causes:**
+1. The key is in `exclude`. Check `[tool.ruff-sync] exclude` in your `pyproject.toml`.
+2. The local value already matches upstream — you're already in sync.
+3. The upstream URL resolved to the wrong file. Verify with `ruff-sync check --semantic` and look at the diff output.
+
+---
+
+## `UpstreamError` / HTTP Failure
+
+**Symptom:**
+```
+UpstreamError: Failed to fetch https://...
+```
+
+**Steps:**
+1. Check the URL works in a browser or with `curl -I <url>`.
+2. For GitHub URLs, make sure you're pointing at a _raw_ or _tree/blob_ URL, not an HTML page.
+3. If using a private repo, the raw URL requires authentication. Use an SSH URL instead:
+   ```bash
+   ruff-sync git@github.com:my-org/private-standards.git
+   ```
+4. Check network/proxy settings if in a corporate environment.
+
+---
+
+## HTTP 404 on GitHub URL
+
+**Symptom:** 404 when fetching a GitHub tree or blob URL.
+
+**Cause:** The branch or path doesn't exist, or the repo is private.
+
+**Fix:**
+```toml
+[tool.ruff-sync]
+upstream = "https://github.com/my-org/standards"
+branch = "main"   # make sure this branch exists
+path = "configs"  # make sure this path exists on that branch
+```
+
+Validate: `curl https://github.com/my-org/standards/tree/main/configs` should return 200.
+
+---
+
+## `FileNotFoundError` — No Local Config
+
+**Symptom:**
+```
+FileNotFoundError: No pyproject.toml or ruff.toml found in .
+```
+
+**Fix:** Use `--init` to scaffold a new config file before syncing:
+```bash
+ruff-sync https://github.com/my-org/standards --init
+```
+
+---
+
+## Pre-commit Version Mismatch (Exit Code 2)
+
+**Symptom:** `ruff-sync check` exits with code 2 and a warning like:
+```
+⚠️  Pre-commit ruff hook version is out of sync: .pre-commit-config.yaml uses v0.9.3, project has ruff==0.10.0
+```
+
+**This is not a config drift.** The Ruff configuration is in sync. Only the pre-commit hook tag is stale.
+
+**Fix:**
+```bash
+ruff-sync          # pulls config AND updates the hook rev (if pre-commit-version-sync = true)
+# or manually: update the 'rev:' line in .pre-commit-config.yaml
+```
+
+To suppress this check entirely, omit `--pre-commit` from `ruff-sync check` or set `pre-commit-version-sync = false`.
+
+---
+
+## Merge Produces Unexpected `tomlkit` Structure
+
+**Symptom:** Synced `pyproject.toml` has repeated sections or oddly formatted keys.
+
+**Cause:** Mixing dotted-key style (`lint.select = [...]`) with explicit table header style (`[tool.ruff.lint]`) in the same file.
+
+**Fix:** Pick one style consistently. `ruff-sync` uses `tomlkit` which preserves formatting, but mixing styles can produce unexpected output.
+
+---
+
+## SSH Clone Fails
+
+**Symptom:** Hangs or fails when using `git@github.com:...` URL.
+
+**Cause:** SSH key not configured or not added to the agent.
+
+**Fix:** Verify SSH auth first:
+```bash
+ssh -T git@github.com
+```
+
+Alternatively, switch to HTTPS:
+```toml
+upstream = "https://github.com/my-org/standards"
+```
+
+---
+
+## `ruff-sync` Not Found After Install
+
+**Symptom:** `ruff-sync: command not found`
+
+**Fix:**
+```bash
+# If installed with uv tool:
+uv tool list   # confirm it appears
+# Ensure uv tools bin dir is on PATH:
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
+
+# If using pipx:
+pipx ensurepath
+```
+
+---
+
+## Getting More Debug Info
+
+```bash
+# Show what config would be merged without applying it
+ruff-sync check https://github.com/my-org/standards
+
+# Show a diff of what changed
+ruff-sync check --semantic   # value-only diff
+ruff-sync check              # full string diff (catches comment/whitespace changes too)
+```

{ruff_sync-0.1.2.dev1 → ruff_sync-0.1.3.dev2}/.github/workflows/ci.yaml

@@ -31,6 +31,26 @@ jobs:
 
       - run: uv run invoke ${{ matrix.task }} --check
 
+  validate-docs-build:
+    name: Validate documentation build
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.10
+
+      - name: Install dependencies
+        run: uv sync --group docs --frozen
+
+      - name: Build documentation
+        run: uv run mkdocs build --strict
+
   tests:
     strategy:
       fail-fast: ${{ github.event.pull_request.draft == true }}
@@ -102,6 +122,13 @@ jobs:
           echo "Testing ruff-sync check against Kilo59/ruff-sync..."
           ruff-sync check https://github.com/Kilo59/ruff-sync
 
+      - name: Dogfood Ruff-Sync Check (GitHub Format)
+        run: |
+          echo "Dogfooding ruff-sync check with GitHub annotations..."
+          # This will produce annotations if the current branch's ruff config
+          # has drifted from the upstream (main branch).
+          ruff-sync check https://github.com/Kilo59/ruff-sync --output-format github
+
       - name: Verify semantic check failure
         run: |
           echo "Verifying that --semantic check fails for kitchen-sink config (expected failure)..."
@@ -131,4 +158,15 @@ jobs:
         run: uv build
 
       - name: Publish package
-        run: uv publish
+        run: |
+          # Capture stderr to a file so we can check for specific error strings
+          uv publish 2> publish_err.log || {
+            exit_code=$?
+            # Check for common "version already exists" markers in the output
+            if grep -qi "already exists" publish_err.log; then
+              echo "::warning title=Ruff Sync Publish::Version already exists on PyPI. Skipping upload."
+            else
+              cat publish_err.log
+              exit $exit_code
+            fi
+          }

{ruff_sync-0.1.2.dev1 → ruff_sync-0.1.3.dev2}/.pre-commit-config.yaml

@@ -16,7 +16,7 @@ repos:
       - id: no-commit-to-branch
         args: [--branch, develop, --branch, main]
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.15.6"
+    rev: "v0.15.8"
     hooks:
       - id: ruff-check
         args: ["--fix"]

{ruff_sync-0.1.2.dev1 → ruff_sync-0.1.3.dev2}/AGENTS.md

@@ -58,6 +58,13 @@ gh label list                           # See available labels
 .agents/               # Agent-specific instructions (Deep Standards)
   TESTING.md           # Mandatory testing patterns and rules
   workflows/           # Step-by-step guides for common tasks
+  skills/
+    ruff-sync-usage/   # Agent Skill for users adopting ruff-sync (keep current!)
+      SKILL.md
+      references/
+        configuration.md
+        troubleshooting.md
+        ci-integration.md
 src/ruff_sync/         # The application source
   __init__.py          # Public API
   cli.py               # CLI, merging logic, HTTP
@@ -151,6 +158,7 @@ uv run coverage run -m pytest -vv
 - Prefer f-strings for logging (we ignore `G004`).
 - Do not create custom exception classes for simple errors (`TRY003` is ignored).
 - **Prefer `NamedTuple` for return types** over plain tuples to improve readability and type safety.
+- **Prefer `typing.Protocol` over `abc.ABC`** for abstract base classes to promote structural subtyping.
 
 ### TOML Handling
 
@@ -158,6 +166,26 @@ uv run coverage run -m pytest -vv
 - Be aware that `tomlkit` returns proxy objects. When you need to convert them to plain Python for comparisons or re-insertion, use `.unwrap()`.
 - Dotted keys (e.g., `lint.select = [...]`) create proxy tables that behave differently from explicit table headers (`[tool.ruff.lint]`). The merge logic in `_recursive_update` handles this.
 
+### Sentinels & Missing Values
+
+- Use the `MissingType.SENTINEL` (aliased as `MISSING`) from `ruff_sync.constants` whenever you need to distinguish between a value that is functionally "absent" and one that was explicitly provided (even if that provided value matches the default, such as `None` or an empty list).
+- **Why?**: This is particularly important for configuration serialization, as it allows `ruff-sync` to distinguish between a setting the user actively chose and one that is simply the default. This keeps the user's `pyproject.toml` clean by ensuring only explicit choices are serialized.
+- **Serialization Rule**: Only serialize fields to `[tool.ruff-sync]` if they are `not MISSING`.
+- Example pattern for resolving configuration (note: use **truthiness**, not `is not None`, so an
+  empty string falls back to config/defaults):
+  ```python
+  def _resolve_branch(args: Any, config: Mapping[str, Any]) -> str | MissingType:
+      # Empty string is treated as falsy → falls back to config or DEFAULT_BRANCH
+      if getattr(args, "branch", None):
+          return cast("str", args.branch)
+      if "branch" in config:
+          return cast("str", config["branch"])
+      return MISSING
+  ```
+  The actual MISSING → default resolution (e.g. `MISSING` → `"main"`) is handled in
+  `resolve_defaults` from `ruff_sync.constants`, which is the single source of truth used
+  by both `cli.main` and `core._merge_multiple_upstreams`.
+
 ### Testing
 
 - New TOML merge edge cases belong in `tests/test_corner_cases.py`.
@@ -176,6 +204,7 @@ Defined in `tasks.py`. **ALWAYS** run these through uv: `uv run invoke <task>`
 | `type-check` | `types`               | Type-check with mypy                   |
 | `deps`       | `sync`                | Sync dependencies with uv              |
 | `new-case`   | `new-lifecycle-tomls` | Scaffold lifecycle TOML fixtures       |
+| `docs`       |                       | Build or serve documentation           |
 
 ## CI
 
@@ -190,3 +219,5 @@ CI is defined in `.github/workflows/ci.yaml`:
 1. **tomlkit proxy objects**: When adding new keys to a proxy table (from dotted keys), the proxy must be converted to a real table first. The `_recursive_update` function handles this. Don't bypass it.
 2. **`cast(Any, ...)` in tests**: Use `cast(Any, tomlkit.parse(...))["tool"]["ruff"]` pattern in tests to avoid mypy complaints about `tomlkit`'s `Item | Container` return types.
 3. **Pre-commit ruff version**: The ruff version in `.pre-commit-config.yaml` must stay in sync with the version in `pyproject.toml`. The test `test_pre_commit_versions_are_in_sync` enforces this.
+4. **Keep the ruff-sync-usage skill current**: After any change to CLI behavior (new flags, changed exit codes, new configuration keys, updated URL handling, etc.), update `.agents/skills/ruff-sync-usage/` accordingly. The `SKILL.md` covers quick start, workflows, exit codes, and gotchas. Detailed references live in `references/configuration.md`, `references/troubleshooting.md`, and `references/ci-integration.md`.
+5. **No `autouse=True` fixtures**: NEVER use `autouse=True` for pytest fixtures. All fixtures must be explicitly requested by the test functions that require them. This ensures dependencies are explicit and avoids hidden side effects.