@jesdi/skills 0.0.14 → 0.0.16

package/README.md

@@ -58,7 +58,7 @@ which ones are part of the standard setup, where they come from, and (under
 upstream with the [skills.sh](https://skills.sh/) CLI:
 
 ```bash
-npx skills add mattpocock/skills          # grill-me, grill-with-docs, grilling, improve-codebase-architecture, to-questionnaire, tdd, code-review, codebase-design, diagnosing-bugs, resolving-merge-conflicts
+npx skills add mattpocock/skills          # grill-me, grill-with-docs, grilling, improve-codebase-architecture, to-questionnaire, tdd, code-review, codebase-design, diagnosing-bugs, resolving-merge-conflicts, handoff, teach, wait-what
 npx skills add JuliusBrussee/caveman      # caveman suite
 npx skills add vercel-labs/skills         # find-skills
 npx skills add vercel-labs/agent-skills   # vercel-react-best-practices

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jesdi/skills",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "description": "jesdi's agent skills (content package consumed by @jesdi/skills-cli)",
   "license": "MIT",
   "repository": {

package/skills/crap-gate/SKILL.md

@@ -2,7 +2,7 @@
 name: crap-gate
 description: >-
   Score every function a branch changed with CRAP (cyclomatic complexity ×
-  untested fraction), fail on existing functions > 15 and new functions > 9,
+  untested fraction), fail on existing functions above 15 and new functions above 9,
   and drive a fixer + independent reviewer loop until the gate passes. Use
   when implementation is done and before pushing, when the user says "run the
   crap gate", "check CRAP", "is this change tested enough", or when a push
@@ -21,16 +21,19 @@ is the human approval gate at push time.
 
 ## Running the engine
 
-The engine ships with this skill and is stdlib-only Python (plus `node` and
-the project's own `typescript` package for TS/TSX targets). Run it from
-anywhere inside the repo — it walks up to `.crap-gate.json`:
+Use the bundled launcher on macOS or Linux (x86_64/ARM64; Windows via WSL).
+It downloads checksum-verified uv 0.12.13 and provisions private Python 3.13.7
+on first use, then reuses them across repositories. No global Python, uv,
+virtualenv activation, or pip installation is needed. The engine uses only
+Python's standard library and supports Python source syntax through 3.13.
+Run from anywhere inside the repo — it walks up to `.crap-gate.json`:
 
 ```bash
-python3 <skill-dir>/crap.py            # human table, exit 1 on violations
-python3 <skill-dir>/crap.py --json     # same data for a subagent prompt
-python3 <skill-dir>/crap.py --no-run   # reuse the last coverage reports
-python3 <skill-dir>/crap.py --all      # whole-repo baseline (exploration only)
-python3 <skill-dir>/crap.py --base main --threshold-new 7   # local what-ifs
+sh "<skill-dir>/run.sh"            # human table, exit 1 on violations
+sh "<skill-dir>/run.sh" --json     # same data for a subagent prompt
+sh "<skill-dir>/run.sh" --no-run   # reuse the last coverage reports
+sh "<skill-dir>/run.sh" --all      # whole-repo baseline (exploration only)
+sh "<skill-dir>/run.sh" --base main --threshold-new 7   # local what-ifs
 ```
 
 `<skill-dir>` is wherever this skill is installed (`.agents/skills/crap-gate`,
@@ -40,13 +43,37 @@ wrap it (`make crap`); prefer the wrapper when one exists.
 When you point a wrapper at an agent symlink, that symlink only exists after
 `skills-cli sync` if the matching agent is declared for the skill in
 `.my-skills.json` — `claude` → `.claude/skills/crap-gate`, `opencode` →
-`.agents/skills/crap-gate`. A wrapper that runs `.agents/skills/crap-gate/crap.py`
+`.agents/skills/crap-gate`. A wrapper that runs `.agents/skills/crap-gate/run.sh`
 therefore needs `"agents": ["opencode"]` (or `["claude", "opencode"]`) on the
 `crap-gate` entry, or a fresh checkout/worktree will lack that path after `sync`.
-The store copy `.my-skills/crap-gate/crap.py` is always materialized regardless
+The store copy `.my-skills/crap-gate/run.sh` is always materialized regardless
 of declared agents, so wrapping against it avoids the agent/path coupling
 entirely.
 
+Existing `make crap` / `make crap-gate` wrappers must replace `python3 .../crap.py`
+with `sh .../run.sh` (quote the path). Prefer the store path, for example:
+
+```makefile
+crap crap-gate:
+	sh "$(CURDIR)/.my-skills/crap-gate/run.sh"
+```
+
+The launcher needs standard shell utilities, `curl`, `tar`, and `sha256sum`
+or `shasum`. Its cache defaults to `${XDG_CACHE_HOME:-$HOME/.cache}/crap-gate`;
+set `CRAP_GATE_CACHE_DIR` to an absolute path to relocate it. To pre-provision,
+run the launcher with `--help` while online. `CRAP_GATE_OFFLINE=1` then requires
+that populated cache and prevents runtime downloads. Runtime setup messages go
+to stderr; `--json` returns a structured error on setup failure, with exit 2.
+Do not bypass the gate or repair global Python when setup fails; resolve the
+reported download/cache problem and rerun the launcher.
+
+TypeScript targets still need `node` and the project's own `typescript` package.
+Coverage commands still need the project's test dependencies; configure them
+with its normal runner (for example, `cd backend && pipenv run pytest ...`).
+The launcher preserves PATH and the caller's environment for these commands;
+its private Python is only for the gate engine. It does not install project
+dependencies or edit project environments.
+
 By default the engine runs each target's coverage command only when that
 target has changed files, so a backend-only change never runs the frontend
 suite. Coverage command output goes to `.crap/<target>.log`.

package/skills/crap-gate/crap.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """crap-gate engine: CRAP score for every function a branch changed.
 
-    python3 crap.py [--config PATH] [--base REF] [--threshold-existing N]
+    sh run.sh [--config PATH] [--base REF] [--threshold-existing N]
                     [--threshold-new N] [--run | --no-run] [--all] [--json]
 
 Exit 0 = no violations, 1 = violations, 2 = configuration/tool error.
@@ -11,12 +11,22 @@ project's own `typescript` package.
 from __future__ import annotations
 
 import argparse
+import json
 import subprocess
 import sys
 import tempfile
 import time
 from pathlib import Path
 
+# Direct invocation remains useful for development, but should fail clearly
+# before importing an analyzer that requires newer AST nodes.
+if sys.version_info < (3, 10):
+    message = "Use the bundled run.sh launcher; direct execution requires Python >= 3.10"
+    print(f"crap: {message}", file=sys.stderr)
+    if "--json" in sys.argv:
+        print(json.dumps({"error": {"kind": "tooling", "message": message}}))
+    sys.exit(2)
+
 import crap_git
 import crap_python
 import crap_typescript
@@ -201,6 +211,8 @@ def main(argv: list[str] | None = None) -> int:
         result = run(cfg, run_mode=args.run_mode, all_functions=args.all)
     except ToolError as exc:
         print(f"crap: {exc}", file=sys.stderr)
+        if args.json:
+            print(json.dumps({"error": {"kind": "tooling", "message": str(exc)}}))
         return 2
     sys.stdout.write(render_json(result) if args.json else render_text(result))
     return 1 if result.summary["fail"] else 0

package/skills/crap-gate/run.sh

@@ -0,0 +1,87 @@
+#!/bin/sh
+# Keep bootstrap dependencies to POSIX tools, curl, tar, and SHA-256.
+set -eu
+
+json=false
+for arg in "$@"; do
+    [ "$arg" != --json ] || json=true
+done
+fail() {
+    printf 'crap: %s\n' "$1" >&2
+    if "$json"; then
+        printf '%s\n' '{"error":{"kind":"tooling","message":"Runtime setup failed; see stderr. Run the launcher again after resolving the setup error."}}'
+    fi
+    exit 2
+}
+
+# Resolve file symlinks as well as symlinked skill directories.
+entry=$0
+while [ -L "$entry" ]; do
+    parent=$(CDPATH= cd -- "$(dirname -- "$entry")" && pwd)
+    entry=$(readlink "$entry")
+    case "$entry" in /*) ;; *) entry=$parent/$entry ;; esac
+done
+skill_dir=$(CDPATH= cd -- "$(dirname -- "$entry")" && pwd)
+cache=${CRAP_GATE_CACHE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/crap-gate}
+case "$cache" in /*) ;; *) fail 'CRAP_GATE_CACHE_DIR must be an absolute path' ;; esac
+uv_version=0.12.13
+python_version=3.13.7
+case "$(uname -s):$(uname -m)" in
+    Darwin:arm64|Darwin:aarch64)
+        target=aarch64-apple-darwin
+        digest=7e6ddb9316acc00f2296c82ff4d99977870ee34b2f0ddcae9444d714db9364ed ;;
+    Darwin:x86_64)
+        target=x86_64-apple-darwin
+        digest=5e287ef61cb6a9b61b3a83fef124fd143e400468a7dac794230147a810e17119 ;;
+    Linux:aarch64|Linux:arm64)
+        target=aarch64-unknown-linux-musl
+        digest=f44bc1037a17889fe562fffd2002d4ed108e499fbe68b4f022af244dc7b8244f ;;
+    Linux:x86_64)
+        target=x86_64-unknown-linux-musl
+        digest=4e2bfd0c9007b1032a50e539e965fd0a6037d87ad93ae1580d220a92d4c94098 ;;
+    *) fail 'Unsupported platform: use macOS or Linux on x86_64 or ARM64 (Windows: WSL)' ;;
+esac
+uv_dir=$cache/uv/$uv_version/$target
+uv=$uv_dir/uv
+if [ ! -x "$uv" ]; then
+    [ "${CRAP_GATE_OFFLINE:-0}" != 1 ] || fail 'uv is not cached; provision this cache online first'
+    mkdir -p "$uv_dir" || fail 'Cannot create runtime cache'
+    stage=$(mktemp -d "$uv_dir/.download.XXXXXX") || fail 'Cannot create download directory'
+    trap 'rm -rf "$stage"' EXIT
+    trap 'exit 2' HUP INT TERM
+    printf 'crap: downloading uv %s\n' "$uv_version" >&2
+    curl --fail --location --silent --show-error --connect-timeout 15 --max-time 300 \
+        "https://github.com/astral-sh/uv/releases/download/$uv_version/uv-$target.tar.gz" \
+        -o "$stage/uv.tar.gz" || fail 'Cannot download uv; check network access and retry'
+    if command -v sha256sum >/dev/null 2>&1; then
+        actual=$(sha256sum "$stage/uv.tar.gz")
+    elif command -v shasum >/dev/null 2>&1; then
+        actual=$(shasum -a 256 "$stage/uv.tar.gz")
+    else
+        fail 'SHA-256 verification requires sha256sum or shasum'
+    fi
+    [ "${actual%% *}" = "$digest" ] || fail 'uv archive checksum mismatch'
+    tar -xzf "$stage/uv.tar.gz" -C "$stage" || fail 'Cannot extract uv'
+    # Atomic publication: concurrent first runs never see a partial executable.
+    mv -f "$stage/uv-$target/uv" "$uv" || fail 'Cannot install cached uv'
+    rm -rf "$stage"
+    trap - EXIT HUP INT TERM
+fi
+
+# Limit uv settings to this subprocess. Do not activate a venv or change PATH:
+# coverage commands must inherit the caller's project environment unchanged.
+managed_uv() (
+    unset UV_NO_MANAGED_PYTHON UV_PYTHON UV_PYTHON_DOWNLOADS UV_PYTHON_BIN_DIR
+    export UV_PYTHON_INSTALL_DIR="$cache/python"
+    export UV_CACHE_DIR="$cache/uv-cache"
+    export UV_MANAGED_PYTHON=true
+    "$uv" --no-config "$@"
+)
+python=$(managed_uv python find --no-project --system --managed-python --no-python-downloads "$python_version" 2>/dev/null) || {
+    [ "${CRAP_GATE_OFFLINE:-0}" != 1 ] || fail 'Python is not cached; provision this cache online first'
+    managed_uv python install --no-bin "$python_version" >&2 || fail 'Cannot provision Python; check network access and retry'
+    python=$(managed_uv python find --no-project --system --managed-python --no-python-downloads "$python_version") || fail 'Cannot locate managed Python'
+}
+# Ignore Python-specific ambient settings for the engine, but preserve them for
+# child coverage processes. -I would also remove the sibling module directory.
+exec "$python" -E -s "$skill_dir/crap.py" "$@"

package/skills/crap-gate/test_launcher.py

@@ -0,0 +1,116 @@
+"""Launcher regressions. Real-runtime cases use a pre-provisioned cache in CI."""
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+
+import pytest
+
+from test_cli import BASE_SRC, repo  # noqa: F401 — shared git repository fixture
+
+LAUNCHER = Path(__file__).with_name("run.sh").resolve()
+
+
+def launch(env, *args, cwd=None, script=LAUNCHER):
+    return subprocess.run(
+        ["/bin/sh", str(script), *args], env=env, cwd=cwd,
+        text=True, capture_output=True, timeout=60,
+    )
+
+
+def test_empty_offline_cache_is_json_tool_error(tmp_path):
+    env = dict(os.environ, CRAP_GATE_CACHE_DIR=str(tmp_path / "cache"), CRAP_GATE_OFFLINE="1")
+    proc = launch(env, "--json")
+    assert proc.returncode == 2
+    assert json.loads(proc.stdout)["error"]["kind"] == "tooling"
+    assert "not cached" in proc.stderr
+    assert not (tmp_path / "cache").exists()
+
+
+def test_bad_download_is_rejected_before_execution(tmp_path):
+    bin_dir = tmp_path / "bin"
+    bin_dir.mkdir()
+    curl = bin_dir / "curl"
+    curl.write_text('#!/bin/sh\nwhile [ "$1" != -o ]; do shift; done\nprintf corrupt > "$2"\n')
+    curl.chmod(0o755)
+    env = dict(os.environ, PATH=f"{bin_dir}:{os.environ['PATH']}",
+               CRAP_GATE_CACHE_DIR=str(tmp_path / "cache"), CRAP_GATE_OFFLINE="0")
+    proc = launch(env, "--json")
+    assert proc.returncode == 2
+    assert "checksum mismatch" in proc.stderr
+    assert json.loads(proc.stdout)["error"]["kind"] == "tooling"
+    assert not list((tmp_path / "cache").rglob("uv.tar.gz"))
+    assert not list((tmp_path / "cache").rglob(".download.*"))
+
+
+@pytest.fixture
+def runtime_env():
+    cache = os.environ.get("CRAP_GATE_TEST_CACHE")
+    if not cache:
+        pytest.skip("Set CRAP_GATE_TEST_CACHE to a cache provisioned by run.sh --help")
+    return dict(os.environ, CRAP_GATE_CACHE_DIR=cache, CRAP_GATE_OFFLINE="1")
+
+
+@pytest.mark.parametrize("python_on_path", ["absent", "incompatible"])
+def test_runtime_ignores_host_python_and_preserves_coverage_environment(
+    repo, tmp_path, runtime_env, python_on_path,
+):
+    bin_dir = tmp_path / "host bin"
+    bin_dir.mkdir()
+    for name in ("uname", "dirname", "git", "sh", "env"):
+        (bin_dir / name).symlink_to(shutil.which(name))
+    if python_on_path == "incompatible":
+        for name in ("python", "python3"):
+            executable = bin_dir / name
+            executable.write_text("#!/bin/sh\necho wrong-python >&2\nexit 99\n")
+            executable.chmod(0o755)
+    runtime_env.update(PATH=str(bin_dir), VIRTUAL_ENV=str(tmp_path / "wrong venv"),
+                       PYTHONHOME="/nonexistent-python", PYTHONPATH="/nonexistent-modules")
+    # Both files must be ignored by runtime discovery.
+    (repo / ".python-version").write_text("3.9.6\n")
+    (repo / "uv.toml").write_text("deliberately invalid configuration\n")
+    (repo / "pkg/m.py").write_text(BASE_SRC + "\ndef added():\n    return 1\n")
+    (repo / ".crap").mkdir()
+    cfg = json.loads((repo / ".crap-gate.json").read_text())
+    cfg["targets"][0]["coverage"]["command"] = (
+        "env > coverage-env.txt; printf '%s' '{\"files\":{}}' > .crap/coverage.json"
+    )
+    (repo / ".crap-gate.json").write_text(json.dumps(cfg))
+    proc = launch(runtime_env, "--json", cwd=repo)
+    assert proc.returncode == 0, proc.stderr
+    assert json.loads(proc.stdout)["functions"][0]["name"] == "added"
+    inherited = dict(line.split("=", 1) for line in (repo / "coverage-env.txt").read_text().splitlines())
+    for name in ("PATH", "VIRTUAL_ENV", "PYTHONHOME", "PYTHONPATH"):
+        assert inherited[name] == runtime_env[name]
+    assert "UV_PYTHON_INSTALL_DIR" not in inherited or inherited["UV_PYTHON_INSTALL_DIR"] == os.environ.get("UV_PYTHON_INSTALL_DIR")
+    assert not (repo / ".venv").exists()
+
+
+def test_symlink_spaces_and_exit_codes(repo, tmp_path, runtime_env):
+    link = tmp_path / "launcher link"
+    link.symlink_to(LAUNCHER)
+    (repo / "pkg/m.py").write_text(BASE_SRC + "\ndef unnew(a, b):\n    return a if b else (b if a else 0)\n")
+    (repo / ".crap").mkdir()
+    (repo / ".crap/coverage.json").write_text('{"files":{}}')
+    proc = launch(runtime_env, "--json", "--no-run", cwd=repo, script=link)
+    assert proc.returncode == 1, proc.stderr
+    assert json.loads(proc.stdout)["summary"]["fail"] == 1
+    proc = launch(runtime_env, "--json", "--base", "missing-ref", cwd=repo, script=link)
+    assert proc.returncode == 2
+    assert json.loads(proc.stdout)["error"]["kind"] == "tooling"
+
+
+def test_offline_cache_missing_python_is_tool_error(tmp_path, runtime_env):
+    original = Path(runtime_env["CRAP_GATE_CACHE_DIR"])
+    cache = tmp_path / "uv only cache"
+    for executable in (original / "uv").rglob("uv"):
+        if executable.is_file():
+            target = cache / executable.relative_to(original)
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.symlink_to(executable)
+    runtime_env["CRAP_GATE_CACHE_DIR"] = str(cache)
+    proc = launch(runtime_env, "--json")
+    assert proc.returncode == 2
+    assert "Python is not cached" in proc.stderr
+    assert json.loads(proc.stdout)["error"]["kind"] == "tooling"

package/skills/deep-quality-review/SKILL.md

@@ -34,23 +34,33 @@ size, orchestration.
 causes it (an invariant enforced by an optional parameter is a structure
 finding). Everything else belongs in a different review.
 
+**Repo conventions come first.** Read the repo's AGENTS.md (and CLAUDE.md,
+CONTRIBUTING.md, or coding-standards file) before the diff. A breach of a
+documented rule is a finding; cite the file and the rule. A documented rule
+overrides a smell: when the repo endorses a pattern the table would flag,
+don't flag it.
+
 ## The smells
 
 Run every meaningful change through this table, top to bottom. Each row is one
 concept; the *Ask* is the question that exposes it, the *Remedy* is what to
-push for.
+push for. Names in parentheses are the matching Fowler smells (*Refactoring*,
+ch. 3), folded into the row that already covers them.
 
 | # | Smell | Ask | Remedy |
 |---|-------|-----|--------|
-| 1 | **Duplicated concept** — one idea expressed twice: near-duplicate helper, parallel model, copy-pasted branch, a flag *and* an optional both meaning "off", the same predicate reimplemented instead of reused | What single concept are these copies of? Where is its canonical home? | Name the concept once; make the variants its data or parameters; delete the copies. Never accept a second copy because the first one exists. |
+| 1 | **Duplicated concept** — one idea expressed twice: near-duplicate helper, parallel model, copy-pasted branch (Duplicated Code), a flag *and* an optional both meaning "off", the same predicate reimplemented instead of reused, the same `switch`/`if`-cascade on the same type in two places (Repeated Switches) | What single concept are these copies of? Where is its canonical home? | Name the concept once; make the variants its data or parameters (one map or one polymorphic dispatch both sites share); delete the copies. Never accept a second copy because the first one exists. |
 | 2 | **Complexity rearranged, not deleted** — the diff moves code around but the reader still holds the same number of branches, modes, and helpers | Which reframing of the model or ownership makes these branches disappear? | Change the model so the special case becomes the default flow. Prefer the version that feels inevitable in hindsight. |
 | 3 | **Special case in a shared flow** — new `if`, one-off boolean, nullable mode, or feature check bolted into an unrelated path | Whose decision is this, and why is it made here? | Move it behind its own abstraction (policy, resolver, dispatcher, module); keep the shared path linear. |
-| 4 | **Wrong layer / boundary leak** — feature logic in a shared module, implementation details through an API, callers re-deriving what the owner already knows | Which module owns this concept? | Move the logic to the owner; callers receive results, not raw inputs to recompute. |
-| 5 | **Indirection without clarity** — thin wrapper, pass-through helper, "generic" mechanism hiding a simple data shape | What does the reader learn from this layer? | Delete it and keep the direct call. Boring and direct beats clever. |
-| 6 | **Weak contract** — `any`, `unknown`, casts, optional params, silent fallbacks that paper over an unclear invariant | What invariant is this hiding? | Make the boundary explicit in the type so the control flow simplifies. |
-| 7 | **File sprawl** — the diff pushes a file past a healthy size boundary (~1k lines) | Should this be decomposed *before* adding to it? | Split by concept first; waive only with a compelling structural reason. |
-| 8 | **Needless sequencing / non-atomic update** — independent work serialized, related updates that can leave state half-applied | Is this actually dependent? Can it be observed half-done? | Parallelize independent work; group related updates. Not micro-optimization — brittleness. |
-| 9 | **Short-horizon change** — "temporary", TODO-later, quick patch, deferred cleanup, a shape chosen because it is the smallest diff | What does this look like when its reason is gone? What does removing it cost? | Do the durable fix now, or structure the stopgap so removal is a pure deletion (one branch, one file), never a refactor of live callers. |
+| 4 | **Wrong layer / boundary leak** — feature logic in a shared module, implementation details through an API, callers re-deriving what the owner already knows, a function that works on another module's data more than its own (Feature Envy), callers walking `a.b().c().d()` to reach what they need (Message Chains) | Which module owns this concept? | Move the logic to the owner; callers receive results, not raw inputs to recompute. Hide a navigation walk behind one method on the first object. |
+| 5 | **Change doesn't follow module lines** — one logical change forces small edits scattered across many files (Shotgun Surgery), or one module is edited for several unrelated reasons (Divergent Change) | If this rule changes again, how many files move? Does this module have one reason to change? | Gather what changes together into one module; split a module that changes for unrelated reasons. |
+| 6 | **Indirection without clarity** — thin wrapper, pass-through helper or class that only delegates (Middle Man), "generic" mechanism hiding a simple data shape, parameters, hooks or abstractions for needs nobody has yet (Speculative Generality) | What does the reader learn from this layer? Who needs this flexibility today? | Delete it and keep the direct call. Boring and direct beats clever. |
+| 7 | **Refused inheritance** — a subclass or implementer that ignores, stubs out, or overrides most of what it inherits (Refused Bequest) | Is this really a kind of its parent? | Drop the inheritance; compose, or implement a narrower interface. |
+| 8 | **Weak contract** — `any`, `unknown`, casts, optional params, silent fallbacks that paper over an unclear invariant; a string or number standing in for a domain concept (Primitive Obsession); the same few fields or params always travelling together (Data Clumps) | What invariant is this hiding? Which type wants to be born? | Make the boundary explicit in the type, a small domain type or one bundled type, so the control flow simplifies. |
+| 9 | **Mysterious name** — a function, variable, or type whose name hides what it does or holds, or says something it no longer does | Could a reader predict the body from the name? | Rename it. If no honest name comes, the concept is murky: fix the design, not the name. |
+| 10 | **File sprawl** — the diff pushes a file past a healthy size boundary (~1k lines) | Should this be decomposed *before* adding to it? | Split by concept first; waive only with a compelling structural reason. |
+| 11 | **Needless sequencing / non-atomic update** — independent work serialized, related updates that can leave state half-applied | Is this actually dependent? Can it be observed half-done? | Parallelize independent work; group related updates. Not micro-optimization — brittleness. |
+| 12 | **Short-horizon change** — "temporary", TODO-later, quick patch, deferred cleanup, a shape chosen because it is the smallest diff | What does this look like when its reason is gone? What does removing it cost? | Do the durable fix now, or structure the stopgap so removal is a pure deletion (one branch, one file), never a refactor of live callers. |
 
 Short-horizon change is the long-term rule and it applies to every other smell: prefer
 consolidating now over a third copy later; prefer the simplification that
@@ -88,9 +98,11 @@ Write the review in this shape:
 
 Working code is not the bar. `REQUEST CHANGES` when any of Duplicated
 concept, Complexity rearranged, Special case in a shared flow, Wrong layer,
-Indirection without clarity, Weak contract, or Short-horizon change is present
-and unjustified, or when a visible code-judo move was skipped. File sprawl and
-Needless sequencing block when the cleaner structure is obvious.
+Change doesn't follow module lines, Indirection without clarity, Refused
+inheritance, Weak contract, or Short-horizon change is present and
+unjustified, when a documented repo rule is broken, or when a visible
+code-judo move was skipped. Mysterious name, File sprawl and Needless
+sequencing block when the cleaner structure is obvious.
 
 ## Author pushback
 
@@ -102,6 +114,9 @@ Needless sequencing block when the cleaner structure is obvious.
 | "The existing code already does it this way" | Existing mess licenses fixing the concept, not adding a copy of it. |
 | "A restructure is out of scope" | If the restructure deletes the complexity this change adds, it is the scope. |
 
+The Fowler smell list is an idea from mattpocock/skills `code-review`; the
+wording here is ours.
+
 ## Review Tone
 
 Be direct, serious, and demanding about quality.

package/skills/review-diff/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: review-diff
+description: >-
+  Review a branch before merge: first a gate (the repo's check command plus
+  crap-gate), then three independent reviewers in parallel — spec (did we build
+  what was asked, no more, no less), correctness via Codex (races, idempotency,
+  money, time, authz, indexes, N+1, migrations, error paths, test quality) and
+  structure (deep-quality-review). `--quick` runs only spec and correctness,
+  shortened, for a live interview. Use when the user says "/review-diff",
+  "review this branch", "review this slice", "review before merge", or before
+  closing out a spec task.
+---
+
+# /review-diff
+
+One gate, then three reviewers that never see each other's output. Each
+answers one question; their reports stay separate, because a strong answer
+on one axis must not hide a failure on another.
+
+| Reviewer | Question | Runs as |
+|---|---|---|
+| Spec | Did we build what the spec asked, no more, no less? | subagent, `spec.md` |
+| Correctness | Can this lose money or corrupt data? | `codex exec`, `correctness.md` |
+| Structure | Is the code getting messier? | subagent, `deep-quality-review` |
+
+`spec.md` and `correctness.md` sit next to this file (`<skill-dir>`).
+
+## Arguments
+
+- A range (`A..B`) or a base ref. Default: the merge-base with the repo's
+  default branch (`origin/main`, else `main`). Review `git diff <base>...HEAD`.
+- A spec path, optional.
+- `--quick`: interview mode. Gate, then spec + correctness only; each report
+  keeps its top 3 findings in under 150 words. Default: all three, full
+  reports.
+
+Before anything else, confirm the range resolves and the diff is non-empty. A
+bad ref fails here, not inside three reviewers.
+
+## Step 0 — gate (sequential, a precondition, not a reviewer)
+
+1. Run the repo's check command: `make check` if the Makefile has it,
+   otherwise the one AGENTS.md / CONTRIBUTING.md / package.json documents. None
+   documented → say so and continue.
+2. Run crap-gate if the repo has `.crap-gate.json`: prefer its wrapper
+   (`make crap-gate` / `make crap`), else `sh <crap-gate-dir>/run.sh`, where
+   the dir is the first of `.my-skills/crap-gate`, `.agents/skills/crap-gate`,
+   `.claude/skills/crap-gate`, `~/.my-skills/crap-gate` that exists. No
+   config → "crap-gate: not configured, skipped". Config but skill missing →
+   "crap-gate: skill not installed, skipped".
+
+Either red → **stop**. Report the failing command and the first failures, and
+no review: reviewing red code wastes the reviewers, and "is there a test for
+this scenario" means nothing while tests fail.
+
+## Steps 1–3 — reviewers, in parallel
+
+Launch all of them in one go; don't let one wait for another. Give each only
+the range, the commit list (`git log --oneline <range>`) and its brief. Never
+paste one reviewer's output into another's prompt.
+
+- **Spec.** Find the spec: the path argument, then a spec under `specs/`
+  matching the branch or feature (skip templates), then issue refs in the
+  commits (`#123`, fetched with `gh issue view`). None → skip: "Spec: no spec
+  found, skipped". Otherwise spawn a subagent: "Read and follow
+  `<skill-dir>/spec.md`. Range: <range>. Commits: <list>. Spec: <path or fetched text>."
+- **Correctness.** If `codex` is on PATH, run it (in the background while
+  the others run):
+
+  ```bash
+  out=$(mktemp) && codex exec -s read-only --ephemeral -o "$out" \
+    "Read and follow <skill-dir>/correctness.md. Range: <range>. Commits: <list>.<quick>" \
+    >/dev/null 2>&1; cat "$out"
+  ```
+
+  No Codex → spawn a subagent with the same instruction and note "Correctness:
+  Codex unavailable, ran on <current model>". The second model is the point;
+  never drop the note.
+- **Structure** (skipped in `--quick`). Spawn a subagent: "Use the
+  `deep-quality-review` skill on range <range>." Skill not installed → skip:
+  "Structure: deep-quality-review not installed, skipped".
+
+In `--quick`, append to each brief: "Quick mode: top 3 findings, under 150
+words." No subagents in this harness → run them one after another, each in a
+fresh context if you can, and say so.
+
+## Output
+
+```
+Gate: `make check` green · crap-gate green
+
+## Spec
+<report, verbatim or lightly cleaned>
+
+## Correctness (Codex)
+<report>
+
+## Structure
+<report>
+
+Spec: 3 findings — worst: <one line>
+Correctness: 1 finding — worst: <one line>
+Structure: REQUEST CHANGES, 2 findings — worst: <one line>
+```
+
+A skipped step keeps its place with its one-line note (in the gate line, or
+as the section body and summary line). `--quick` has no Structure section and
+no Structure summary line. A clean reviewer's summary line is `0 findings`.
+
+Do not merge, dedupe or re-rank findings across reviewers, and do not pick an
+overall winner. A finding two reviewers both raise stays in both reports; that
+is signal.
+
+## Dependencies
+
+Needs the `deep-quality-review` and `crap-gate` skills (install them with the
+skills CLI next to this one) and, for the second model, the `codex` CLI. Any
+of them missing skips that step with a one-line note; it never fails the
+review.
+
+The spec axis is an idea from mattpocock/skills `code-review`; the wording
+here is ours.

package/skills/review-diff/correctness.md

@@ -0,0 +1,29 @@
+# Correctness reviewer
+
+You check one thing: **can this diff lose money, corrupt data, or let the
+wrong person act?** Not style, not structure, not spec coverage. Assume lint,
+types and tests already pass.
+
+Read `git diff <range>` in full, then only the surrounding code a check needs
+(the model behind a query, the existing indexes, the caller of a handler).
+
+| Check | Flag |
+|---|---|
+| Concurrency | Read-then-write without a lock, conditional `UPDATE … WHERE`, or DB constraint: overselling, double-spend, lost updates. Transactions that commit half the work. |
+| Idempotency | Webhooks, payment callbacks, retries and queue consumers that do the work twice when the same message arrives twice. |
+| Money | Floats for amounts (use integer cents or decimal), rounding in more than one place, currency dropped. |
+| Time | Naive datetimes, local time stored, "today" computed without the business timezone. Store UTC. |
+| Authorization | A check done only in the client, or missing on the server: can user A read or change user B's rows by changing an id? |
+| Foreign keys | A new FK column that is filtered or joined on without an index. |
+| N+1 | One query per loop iteration where a join or `IN (…)` would do. |
+| Migrations | Not reversible, or unsafe on a live table (a NOT NULL column without a default, a rewrite under lock). |
+| Failure paths | A payment-provider, checkout or stock-decrement call whose failure (timeout, decline, provider error) is unhandled or silently swallowed. |
+| Test quality | Tautological tests (asserting a mock's return value, or a value the test just set with no code in between) and tests on internals instead of the public seam. Say what they should assert. |
+
+Every finding: `file:line`, the concrete failure scenario (inputs or
+interleaving → wrong result), and the fix. "Consider reviewing" is not a
+finding. Report only what you can point at; mark anything unconfirmed
+"(unverified)".
+
+Output: findings, worst first, then one line naming the checks with nothing
+to report ("Clean: money, time, …"). Under 400 words.

package/skills/review-diff/spec.md

@@ -0,0 +1,24 @@
+# Spec reviewer
+
+You check one thing: **did this diff build what the spec asked, no more, no
+less?** Not style, not structure, not bugs outside the spec.
+
+1. Read the spec in full, then `git diff <range>` in full (not a summary),
+   then the tests the diff adds or touches.
+2. Walk the spec requirement by requirement and report:
+   - **Missing / partial**: asked for, not built or only half built.
+   - **Scope creep**: built, not asked for (endpoints, flags, fields, UI,
+     options). Say what to delete.
+   - **Built wrong**: looks implemented, but behaves differently from the
+     spec line.
+   - **Untested scenario**: each Given/When/Then scenario with no test that
+     exercises it through the public seam (the API, the UI, the use case), not
+     through an internal helper. A test that only passes because a layer
+     above the one the scenario names stops the input (e.g. API validation
+     hiding an untested DB constraint) does not count.
+3. Every finding quotes the spec line it rests on, then `file:line` and the
+   concrete fix. No spec line → not a finding.
+
+Output: findings grouped under those four headings. Leave out empty groups
+and end with one line naming them ("Clean: scope creep, built wrong"). Don't
+list what was fine. Under 400 words.

package/skills-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-07T15:08:46.060Z",
+  "generatedAt": "2026-09-23T16:36:43.907Z",
   "skills": [
     {
       "name": "backlog",
@@ -22,14 +22,14 @@
     },
     {
       "name": "crap-gate",
-      "version": "0.1.2",
-      "hash": "sha256-6f1e0de08917f0b0166959dd25328ed098ce1185cf52996093f2b18b151a9c0a",
-      "description": "Score every function a branch changed with CRAP (cyclomatic complexity × untested fraction), fail on existing functions > 15 and new functions > 9, and drive a fixer + independent reviewer loop until the gate passes. Use when implementation is done and before pushing, when the user says \"run the crap gate\", \"check CRAP\", \"is this change tested enough\", or when a push gate reports CRAP violations."
+      "version": "0.1.3",
+      "hash": "sha256-39041927a985061599a39bb287232b83655ecbac61b7de52486f485991a99d30",
+      "description": "Score every function a branch changed with CRAP (cyclomatic complexity × untested fraction), fail on existing functions above 15 and new functions above 9, and drive a fixer + independent reviewer loop until the gate passes. Use when implementation is done and before pushing, when the user says \"run the crap gate\", \"check CRAP\", \"is this change tested enough\", or when a push gate reports CRAP violations."
     },
     {
       "name": "deep-quality-review",
-      "version": "0.1.1",
-      "hash": "sha256-da5ce29dc5349bcbed74589f3475fa12907ae7eed385e4ecc680bf67edae7e43",
+      "version": "0.1.2",
+      "hash": "sha256-134c1a194e9ec53f244e6500e68cf963b384759d8b5f5c934784665b6ef4b8f6",
       "description": "Extremely strict maintainability review of a branch's changes: duplicated concepts, complexity that got rearranged instead of deleted, spaghetti branching, boundary leaks, weak type contracts, file sprawl, and \"temporary\" fixes that will outlive their reason. Use when the user asks for a \"deep code quality review\", \"thermonuclear review\", \"harsh maintainability review\", \"code judo\", \"is this making the codebase messier\", or before merging a change that touches shared code. Not a correctness, security, or test-coverage review."
     },
     {
@@ -56,6 +56,12 @@
       "hash": "sha256-211e0e116ff6efbc4589ea7264835855b9495ba535f242733af913903fe7707d",
       "description": "Build a throwaway prototype to answer a design question, delivered as one self-contained HTML file. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like."
     },
+    {
+      "name": "review-diff",
+      "version": "0.1.0",
+      "hash": "sha256-f1efdffdad0abf536777a3afcc733b2612ed51abad0b1a04d24f280bf2f223d3",
+      "description": "Review a branch before merge: first a gate (the repo's check command plus crap-gate), then three independent reviewers in parallel — spec (did we build what was asked, no more, no less), correctness via Codex (races, idempotency, money, time, authz, indexes, N+1, migrations, error paths, test quality) and structure (deep-quality-review). `--quick` runs only spec and correctness, shortened, for a live interview. Use when the user says \"/review-diff\", \"review this branch\", \"review this slice\", \"review before merge\", or before closing out a spec task."
+    },
     {
       "name": "to-spec",
       "version": "0.1.0",