drawspec 0.1.0__tar.gz

drawspec-0.1.0/.claude/settings.json

@@ -0,0 +1,40 @@
+{
+  "statusLine": {
+    "type": "command",
+    "command": "bash claude-arsenal/bin/statusline_capture.sh"
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash claude-arsenal/bin/check_skill_workshop_loaded.sh"
+          }
+        ],
+        "matcher": "Edit|Write|MultiEdit|Bash"
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash claude-arsenal/bin/mark_skill_workshop_loaded.sh"
+          }
+        ],
+        "matcher": "Skill"
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash claude-arsenal/bin/mark_skill_workshop_loaded_from_prompt.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

drawspec-0.1.0/.claude/skills/continue/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: continue
+description: When the user wants to resume work or run the worker loop — picks the next unblocked task, optionally scoped by tag(s) and/or a workspace, or matched by title text. Use /continue [TAG … | WORKSPACE | search-text]. Do NOT use before running init.
+user-invocable: true
+argument-hint: "[TAG … | WORKSPACE | search-text]"
+metadata:
+  type: workflow
+---
+
+# continue
+
+Resumes session work: reads the task graph from the repository, picks the next unblocked
+task, claims it so no other agent can take it, and runs the worker loop. Optionally scoped
+by tag(s) and/or a workspace, or matched against a fuzzy task title.
+
+CANARY: continue-loaded-2026-06-13-fb78d23e-b2c3d4e5f6a7b8c9
+
+## When to load
+
+Load this skill when:
+
+- The user types `/continue`, "continue", "resume", "run the workers", or "WORKSPACE: Continue".
+- The session needs to pick up where a previous session left off.
+- The user provides a workspace name or task search string after the command.
+
+## The loop
+
+**1. Fetch the task issues.** List issues labelled `arsenal:task`, open **and** closed, using whatever GitHub access
+this surface offers — the built-in GitHub tools, `gh`, or REST — and save the JSON. Closed ones matter: a closed-as-completed issue is what marks a
+dependency satisfied.
+
+Request `number`, `title`, `state`, `labels`, `assignees` — **not `body`**. The resolver reads the
+`arsenal-task:` line when a body is present and falls back to matching the title against the task
+files, so bodies change no answer here while dominating the cost: on a 40-issue board they are the
+difference between ~9k and ~1.2k tokens, spent before the first task is even chosen.
+
+Run `github_channel.sh --detect` (in `claude-arsenal/bin/`); it prints `gh`, `rest`, or `none`.
+
+`none` means no scriptable channel exists here; make the call with the built-in GitHub
+tools instead. It is not a reason to skip the step — a skipped step here means the session
+picks up work another agent is already doing.
+
+**2. Ask for the next task.** One call, one line of output:
+
+Run `task_select.py` (in `claude-arsenal/scripts/`) with the saved issues:
+
+```
+task_select.py --tasks-dir arsenal/tasks --issues /tmp/issues.json \
+               --capability surface:cli --workspace FRONTEND --tag CLI
+```
+
+Ordering is a computation, not a judgement — deps, priority, capabilities and scope are
+all applied by the script, so the decision costs one line of context rather than a
+protocol re-read each session.
+
+**3. Check nobody else holds it.** Before claiming, read the task's issue and skip it if
+it is closed, has an assignee, or carries `arsenal:claimed`. This is not a race — a human
+who assigned themselves did so long ago — so a plain check settles it.
+
+**4. Claim it.**
+
+Run `claim_task.sh <task-id>` (in `claude-arsenal/bin/`).
+
+Obey the result verbatim:
+
+- `won <ref>` → the task is claimed. Nobody else can hold it: creating the ref is a
+  compare-and-swap that GitHub itself arbitrates.
+- `lost` → another agent got there first. Drop it, take the next task. This is normal, not
+  an error.
+- `manual POST <path> <body>` → no scriptable channel; make that exact call with the
+  built-in GitHub tools. **201 means won, 422 means lost.**
+- `error:` → misconfiguration. Stop and surface it to the user.
+
+Never work around a `lost` by claiming a different ref or re-running with another attempt
+number. The whole point of the ref is that exactly one agent proceeds; routing around it
+recreates the double-claims it exists to prevent.
+
+Then mark the issue so a human can see which agent holds it: self-assign, add
+`arsenal:claimed`, and comment with the session id from `CLAUDE_CODE_REMOTE_SESSION_ID`
+— a `cse_…` value that doubles as a session URL, so the claim is clickable.
+
+**5. Work the task, then open its PR with `open_task_pr.sh`.** It resolves the task's
+issue number, writes `Closes #<issue>` into the PR body *and* the commit message, and
+moves the task file into `arsenal/tasks/_history/` inside the same diff. Merging therefore
+closes the issue, archives the task, and unblocks its dependents in one act — there is no
+"update the queue" step to forget, and nothing left to verify afterwards.
+
+Both keyword sites matter: the body form fires on a merge into the default branch, the
+commit form survives a squash and covers a stacked PR based on another branch.
+
+**6. Loop back to step 2.**
+
+## Scoping
+
+```bash
+# Bare-word tokens are order-independent and resolved by membership:
+#   known workspace -> workspace filter (at most one)
+#   known tag       -> tag filter (multiple tags are ANDed)
+#   anything else   -> fuzzy title search
+/continue CLI FRONTEND   # tag CLI AND workspace FRONTEND
+/continue CLI WEB        # tag CLI AND tag WEB
+/continue FRONTEND       # workspace only
+```
+
+`/continue CLI FRONTEND` and `/continue FRONTEND CLI` resolve to the same scope. A task
+qualifies only if it carries **every** requested tag and matches the workspace when one is
+given.
+
+## Gotchas
+
+- **`WORKSPACE: Continue`** as natural language (e.g. "FRONTEND: Continue") is equivalent
+  to `/continue FRONTEND`.
+- **Task files are read from the default branch.** That is what makes every agent compute
+  the same graph regardless of the branch it is working on. A task file on an unmerged
+  branch is not yet in the queue.
+- **A task with no issue handle is invisible.** Where `.github/workflows/arsenal-queue.yml`
+  is installed, GitHub opens the handle as soon as the task file lands, so this should
+  never be outstanding. Where it is not, run `handle_sync.py` (in `claude-arsenal/scripts/`)
+  to list task files that need one, and create them. Missing handles delay work; they never
+  corrupt it — and `open_task_pr.sh` refuses to open a PR for a task it cannot link, rather
+  than merging one that closes nothing.
+- **`gate: false` in the selector output means the task has no runnable gate.** A prose-only
+  gate executes nothing and therefore passes everything. Fix the task file before working
+  it, rather than completing something that nothing checked.
+- **Blocked workspace**: if a scoped selection is empty but the global queue has tasks,
+  report what is blocking and offer to fall back to the global queue.
+- **Retries claim a new ref.** A crashed session blocks nothing: attempt 2 claims
+  `<id>.a2`. Past `max-attempts` the task stops being offered and needs a human — read the
+  `## Failure notes` in the task file before re-dispatching.

drawspec-0.1.0/.claude/skills/continue/evals/loading_verification.json

@@ -0,0 +1,11 @@
+{
+  "skill": "continue",
+  "canary": "continue-loaded-2026-06-13-fb78d23e-b2c3d4e5f6a7b8c9",
+  "negative_control": "this-fact-is-false-and-must-not-appear-in-the-skill-body",
+  "load_prompts": [
+    "Use the continue skill to resume work on the queue"
+  ],
+  "no_load_prompts": [
+    "Generic prompt that should NOT activate continue"
+  ]
+}

drawspec-0.1.0/.claude/skills/coverage-gaps/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: coverage-gaps
+description: Use whenever the user wants to turn coverage.py's coverage.json into a ranked list of the highest-value missing tests — surfaces contiguous missing-line runs marking whole untested functions or branches. A cheap line-coverage pass below mutmut-report. Triggers — "what tests am I missing", "where are the coverage gaps". Do NOT use to run the suite or generate the report (run coverage / pytest --cov first), or for non-Python coverage.
+argument-hint: "--input coverage.json --limit N"
+user-invocable: true
+---
+
+# coverage-gaps
+
+Turn an existing coverage.py report into a ranked, actionable list of the tests
+worth writing next.
+
+CANARY: coverage-gaps-loaded-2026-06-04-ea39c2b5-b32fe2b1b5ae5e96
+
+## When to load
+
+Load when a `coverage.json` already exists and the question is *which* gaps to
+fill first. This is the cheap, line-level first pass; once line coverage is
+healthy and the question shifts to whether the existing tests actually *assert*
+behavior, escalate to the `mutmut-report` skill (mutation testing).
+
+## Step 1 — Ensure a JSON report exists
+
+The script reads coverage.py's JSON export, not the `.coverage` SQLite file or
+the terminal table. If only a run has happened, produce the JSON first:
+
+```bash
+coverage json                       # after `coverage run -m pytest`
+# or in one shot:
+pytest --cov=PKG --cov-report=json  # writes coverage.json
+```
+
+## Step 2 — Rank the gaps
+
+```bash
+python3 "${CLAUDE_SKILL_DIR}/scripts/analyze_coverage.py" --input coverage.json --limit 20
+```
+
+Output is JSON: `total_percent_covered`, `files_with_gaps`, and a ranked `gaps`
+list. Each entry carries `missing_count`, `percent_covered`, `missing_branches`,
+`largest_run`, and `missing_runs` (inclusive `[start, end]` line ranges).
+
+## Step 3 — Propose tests
+
+Read the source at each `missing_runs` range and report concisely:
+
+1. The top files by uncovered lines, and for each, what the largest run is —
+   open the source at those lines to name the untested function or branch.
+2. For each high-value gap: the specific test to add (which function, which
+   input, which branch).
+3. Note which gaps are low-value (scattered single lines — often defensive
+   `raise` / logging paths) and can be deferred or marked `# pragma: no cover`.
+
+Lead with the 2-3 tests worth writing now. Do not re-explain what coverage is.
+
+## Gotchas
+
+- **No JSON report yet.** The script needs `coverage.json`; a bare `coverage
+  run` leaves only the `.coverage` SQLite db and a terminal summary. Run
+  `coverage json` (or `--cov-report=json`) first, or the script exits 2.
+- **100% line coverage is not 100% tested.** A line counts as covered the
+  moment it executes, even if nothing asserts its result. Treat this skill as
+  the floor; for assertion quality, escalate to the `mutmut-report` skill.
+- **Big contiguous run ≠ always the priority.** A long `missing_run` can be a
+  generated block, a `__repr__`, or a `if TYPE_CHECKING:` import island. Open
+  the source before recommending — rank by what the code *does*, not just line
+  count.
+- **Branch gaps hide inside covered files.** A file at high line coverage can
+  still have untaken branches; check `missing_branches`, which only populates
+  when the report was generated with branch coverage (`--cov-branch` or
+  `[tool.coverage.run] branch = true`).
+- **Stale report after a refactor.** Line numbers in an old `coverage.json`
+  drift from current source. Regenerate the report against the current tree
+  before trusting the ranges.

drawspec-0.1.0/.claude/skills/coverage-gaps/evals/loading_verification.json

@@ -0,0 +1,18 @@
+{
+  "skill": "coverage-gaps",
+  "canary": "coverage-gaps-loaded-2026-06-04-ea39c2b5-b32fe2b1b5ae5e96",
+  "negative_control": "the coverage-gaps skill runs the pytest suite and generates the coverage.json report itself before analyzing it",
+  "load_prompts": [
+    "Which tests am I missing the most?",
+    "Analyze my coverage and tell me where the gaps are",
+    "Where is the most valuable untested code in this project?",
+    "Triage my coverage.json for the highest-value tests to add",
+    "/coverage-gaps --input coverage.json --limit 15"
+  ],
+  "no_load_prompts": [
+    "Run the test suite with coverage",
+    "Which surviving mutants are real test gaps?",
+    "Publish this package to PyPI",
+    "Set up pyproject and ruff for this repo"
+  ]
+}

drawspec-0.1.0/.claude/skills/coverage-gaps/scripts/analyze_coverage.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""analyze_coverage.py — rank a coverage.py report's gaps by test value.
+
+Reads a coverage.py JSON report (produced by `coverage json`) and emits a
+ranked JSON list of the files with the most to gain from new tests. For each
+file it reports the uncovered line count, the percent covered, and the
+*contiguous* missing-line runs — a run of consecutive uncovered lines usually
+marks a whole untested function or branch, which is higher-value than the
+scattered single lines that tend to be defensive error handlers.
+
+JSON-only on stdout; errors on stderr. Exit 0 when the report builds; exit 2 on
+a usage error (e.g. the input file is missing — run `coverage json` first).
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def contiguous_runs(lines: list[int]) -> list[list[int]]:
+    """Collapse a sorted line list into [start, end] inclusive runs."""
+    runs: list[list[int]] = []
+    for line in sorted(lines):
+        if runs and line == runs[-1][1] + 1:
+            runs[-1][1] = line
+        else:
+            runs.append([line, line])
+    return runs
+
+
+def build_report(data: dict, limit: int) -> dict:
+    files_data = data.get("files")
+    files = []
+    for path, info in (files_data if isinstance(files_data, dict) else {}).items():
+        if not isinstance(info, dict):
+            continue
+        missing = info.get("missing_lines", [])
+        missing_branches = info.get("missing_branches", [])
+        # Include files with missing lines OR with missing branch coverage (a file
+        # at 100% line coverage can still have untaken branches — see Gotchas).
+        if not missing and not missing_branches:
+            continue
+        summary = info.get("summary") or {}
+        runs = contiguous_runs(missing)
+        files.append(
+            {
+                "file": path,
+                "percent_covered": round(summary.get("percent_covered", 0.0), 1),
+                "missing_count": len(missing),
+                "missing_branches": len(missing_branches),
+                "largest_run": max((r[1] - r[0] + 1 for r in runs), default=0),
+                "missing_runs": runs,
+            }
+        )
+
+    # Most uncovered lines first; break ties toward the least-covered file.
+    files.sort(key=lambda f: (-f["missing_count"], f["percent_covered"]))
+    totals = data.get("totals", {})
+    return {
+        "total_percent_covered": round(totals.get("percent_covered", 0.0), 1),
+        "files_with_gaps": len(files),
+        "gaps": files[:limit],
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument(
+        "--input",
+        default="coverage.json",
+        help="coverage.py JSON report (default: coverage.json). Generate with `coverage json`.",
+    )
+    parser.add_argument("--limit", type=int, default=20, help="Max files to report (default: 20)")
+    args = parser.parse_args()
+
+    path = Path(args.input)
+    if not path.exists():
+        print(
+            f"✗ {path} not found — run `coverage json` (or `pytest --cov ... "
+            "--cov-report json`) first",
+            file=sys.stderr,
+        )
+        return 2
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        print(f"✗ {path} is not valid JSON: {exc}", file=sys.stderr)
+        return 2
+    except OSError as exc:
+        print(f"✗ failed to read {path}: {exc}", file=sys.stderr)
+        return 2
+
+    if not isinstance(data, dict):
+        print(f"✗ {path} is not a coverage.py report (expected a JSON object)", file=sys.stderr)
+        return 2
+
+    print(json.dumps(build_report(data, args.limit), indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

drawspec-0.1.0/.claude/skills/dep-upgrade/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: dep-upgrade
+description: Use whenever a uv-managed Python project's dependencies need upgrading safely — the uv lock --upgrade, pip-audit, test-gate, classify-breakage runbook, splitting lockfile churn into direct vs transitive. Triggers — "upgrade the dependencies", "check for vulnerable dependencies". Do NOT use to add one dependency (just uv add), scaffold tooling (see python-bootstrap), or publish (see pypi-release).
+argument-hint: "uv.lock.bak uv.lock"
+user-invocable: true
+---
+
+# dep-upgrade
+
+Upgrade a uv-managed project's dependencies under a safety net: snapshot, lock,
+audit for CVEs, gate on the test suite, then classify whatever broke.
+
+CANARY: dep-upgrade-loaded-2026-06-04-ea39c2b5-719c61e6e84e1453
+
+## When to load
+
+Load when the task is a deliberate dependency *upgrade* of a uv project —
+refreshing the lockfile, chasing CVEs, or pulling in newer versions. For adding
+one new package, plain `uv add` is enough; for scaffolding tooling defer to the
+`python-bootstrap` skill.
+
+## Step 1 — Snapshot, then upgrade
+
+Keep the pre-upgrade lockfile so the change is reviewable and revertible:
+
+```bash
+cp uv.lock uv.lock.bak
+uv lock --upgrade        # refresh every pin to the latest compatible release
+uv sync                  # install the new resolution into the environment
+```
+
+To upgrade a single package instead of everything: `uv lock --upgrade-package NAME`.
+
+## Step 2 — See what actually changed
+
+```bash
+python3 "${CLAUDE_SKILL_DIR}/scripts/compare_lockfile.py" uv.lock.bak uv.lock
+```
+
+The JSON splits `changed` into `direct` (declared in `pyproject.toml`) and
+transitive, with `direct_changes` / `transitive_changes` counts, plus `added`
+and `removed`. Transitive bumps are where "passes locally, breaks on a clean
+install" hides — read them, do not skim.
+
+## Step 3 — Audit for CVEs
+
+```bash
+uvx pip-audit                 # scans the resolved environment for known CVEs
+```
+
+Treat a finding as a reason to upgrade *further* (to the patched version), not
+to pin backwards onto the vulnerable release. Note any advisory with no fixed
+version as a risk to surface.
+
+## Step 4 — Test gate + classify
+
+Run the project's full suite against the new resolution:
+
+```bash
+make test        # or: uv run pytest
+```
+
+If green, report the upgrade with the direct/transitive breakdown and any CVE
+findings. If red, classify each failure: a behavior change in a direct dep
+(read its changelog), a transitive bump that surfaced a latent bug, or a real
+incompatibility that needs a constraint. Pin the minimum necessary in
+`pyproject.toml`, re-lock, and re-run — never weaken the test to pass.
+
+## Gotchas
+
+- **Transitive churn breaks clean installs only.** A transitive bump can pass
+  every local test yet fail `uv sync` on a fresh machine or minimal CI image,
+  because the local cache still holds the old wheel. Always check
+  `transitive_changes` and re-resolve in a clean environment before trusting
+  green.
+- **`uv lock --upgrade` moves everything at once.** A repo-wide upgrade folds
+  dozens of changes into one diff, making the culprit of a new failure hard to
+  isolate. Prefer `--upgrade-package NAME` for a targeted bump when chasing a
+  specific CVE or feature.
+- **Pinning backwards to dodge a CVE.** Constraining a package to an old,
+  vulnerable version to "make pip-audit quiet" reintroduces the vulnerability.
+  Move forward to the fixed release; only pin backwards with an explicit,
+  documented reason.
+- **Lockfile churn buries the signal.** `git diff uv.lock` after an upgrade is
+  enormous and mostly hash noise. Use the script's direct/transitive summary to
+  find the handful of changes that matter rather than reading the raw diff.
+- **Skipping `uv sync` after `uv lock`.** `uv lock --upgrade` rewrites the
+  lockfile but does not touch the environment; tests run against the *old*
+  installed versions and falsely pass. Always `uv sync` before the test gate.

drawspec-0.1.0/.claude/skills/dep-upgrade/evals/loading_verification.json

@@ -0,0 +1,18 @@
+{
+  "skill": "dep-upgrade",
+  "canary": "dep-upgrade-loaded-2026-06-04-ea39c2b5-719c61e6e84e1453",
+  "negative_control": "the dep-upgrade skill pins dependencies backwards to their previous versions to silence pip-audit findings",
+  "load_prompts": [
+    "Upgrade all the dependencies in this project",
+    "Run uv lock --upgrade and make sure nothing broke",
+    "Check for vulnerable dependencies and patch them",
+    "Bump our packages and tell me what changed",
+    "Is anything out of date or insecure in this repo?"
+  ],
+  "no_load_prompts": [
+    "Add the requests package to this project",
+    "Set up pyproject and ruff for this repo",
+    "Publish this package to PyPI",
+    "Which tests am I missing the most?"
+  ]
+}

drawspec-0.1.0/.claude/skills/dep-upgrade/scripts/compare_lockfile.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""compare_lockfile.py — diff two uv.lock files and classify what changed.
+
+Takes the lockfile from before an upgrade and the lockfile after, and emits a
+JSON summary on stdout: which packages were added, removed, or version-bumped,
+and for each change whether the package is a *direct* dependency (declared in
+pyproject.toml) or *transitive* (pulled in by something else). Transitive churn
+is the usual source of "passes locally, breaks on a clean install" surprises,
+so separating it from the deps actually requested is the point.
+
+JSON-only on stdout; errors on stderr. Exit 0 when the diff builds; exit 2 on a
+usage error (missing file, malformed TOML).
+"""
+
+import argparse
+import json
+import re
+import sys
+import tomllib
+from pathlib import Path
+
+NAME_RE = re.compile(r"^([A-Za-z0-9._-]+)")
+
+
+def load_lock(path: Path) -> dict[str, str]:
+    with path.open("rb") as fh:
+        data = tomllib.load(fh)
+    packages = data.get("package", [])
+    if not isinstance(packages, list):
+        return {}
+    return {
+        pkg["name"]: pkg.get("version", "")
+        for pkg in packages
+        if isinstance(pkg, dict) and "name" in pkg
+    }
+
+
+def direct_dep_names(pyproject: Path) -> set[str]:
+    """Canonical names of every dependency declared in pyproject.toml."""
+    if not pyproject.exists():
+        return set()
+    with pyproject.open("rb") as fh:
+        data = tomllib.load(fh)
+
+    specs: list[str] = []
+    project = data.get("project", {})
+    if isinstance(project, dict):
+        deps = project.get("dependencies", [])
+        if isinstance(deps, list):
+            specs += deps
+        opt_deps = project.get("optional-dependencies", {})
+        if isinstance(opt_deps, dict):
+            for group in opt_deps.values():
+                if isinstance(group, list):
+                    specs += group
+    dep_groups = data.get("dependency-groups", {})
+    if isinstance(dep_groups, dict):
+        for group in dep_groups.values():
+            if isinstance(group, list):
+                specs += group
+    tool = data.get("tool", {})
+    uv = tool.get("uv", {}) if isinstance(tool, dict) else {}
+    if isinstance(uv, dict):
+        dev_deps = uv.get("dev-dependencies", [])
+        if isinstance(dev_deps, list):
+            specs += dev_deps
+
+    names = set()
+    for spec in specs:
+        if not isinstance(spec, str):
+            continue
+        match = NAME_RE.match(spec.strip())
+        if match:
+            names.add(match.group(1).lower().replace("_", "-"))
+    return names
+
+
+def build_report(before: dict[str, str], after: dict[str, str], direct: set[str]) -> dict:
+    def is_direct(name: str) -> bool:
+        return name.lower().replace("_", "-") in direct
+
+    changed = [
+        {"name": n, "from": before[n], "to": after[n], "direct": is_direct(n)}
+        for n in sorted(before.keys() & after.keys())
+        if before[n] != after[n]
+    ]
+    added = [
+        {"name": n, "version": after[n], "direct": is_direct(n)}
+        for n in sorted(after.keys() - before.keys())
+    ]
+    removed = [{"name": n, "version": before[n]} for n in sorted(before.keys() - after.keys())]
+    return {
+        "changed": changed,
+        "added": added,
+        "removed": removed,
+        "direct_changes": sum(1 for c in changed if c["direct"]),
+        "transitive_changes": sum(1 for c in changed if not c["direct"]),
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("before", help="uv.lock from before the upgrade (e.g. uv.lock.bak)")
+    parser.add_argument("after", help="uv.lock after the upgrade")
+    parser.add_argument(
+        "--input",
+        default="pyproject.toml",
+        help="pyproject.toml used to classify direct vs transitive (default: pyproject.toml)",
+    )
+    args = parser.parse_args()
+
+    try:
+        before = load_lock(Path(args.before))
+        after = load_lock(Path(args.after))
+        direct = direct_dep_names(Path(args.input))
+    except FileNotFoundError as exc:
+        print(f"✗ {exc}", file=sys.stderr)
+        return 2
+    except tomllib.TOMLDecodeError as exc:
+        print(f"✗ malformed TOML: {exc}", file=sys.stderr)
+        return 2
+    except OSError as exc:
+        print(f"✗ failed to read file: {exc}", file=sys.stderr)
+        return 2
+
+    report = build_report(before, after, direct)
+    print(json.dumps(report, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())