From e26665f4678b6551748a629f09138506d5716936 Mon Sep 17 00:00:00 2001
From: Shumin Liu <shumin.liu@tngtech.com>
Date: Fri, 14 Aug 2026 15:57:26 +1000
Subject: [PATCH 1/8] feat(web): describe each page for search engines
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every page sent a <title> and nothing else, so a search engine built its own
snippet out of the first text it found. On the home page that is the terminal
banner ($ pip install ojhunt), which tells a reader nothing about the project.
A shared link showed no preview either.

base.html.jinja now carries a meta description, a canonical link, and the Open
Graph tags. Each page declares its summary in a meta_description block; the
home and About pages inherit the default, which summarises the project as a
whole. Descriptions stay at 160 characters or shorter, where the snippet is cut.

The easter-egg routes answer 200 on 40+ scanner paths (/admin, /.env,
/wp-login.php). Those pages and the 404 page now send noindex and no canonical
URL, so they stay out of the index.

Page routes render through the new render_page() helper, which supplies the
absolute base URL and the canonical URL from the request — the same
request.base_url pattern robots.txt and sitemap.xml already use.

Resolves #271
---
 src/ojhunt/web/app.py                         |  10 +-
 src/ojhunt/web/pages.py                       |  69 ++++++---
 src/ojhunt/web/templates/404.html.jinja       |   2 +
 src/ojhunt/web/templates/base.html.jinja      |  10 ++
 src/ojhunt/web/templates/crawlers.html.jinja  |   2 +
 .../web/templates/easter_egg.html.jinja       |   2 +
 .../web/templates/easter_egg_rick.html.jinja  |   2 +
 .../web/templates/pdf_legacy.html.jinja       |   2 +
 src/ojhunt/web/templates/pdf_merge.html.jinja |   2 +
 tests/web/pages_test.py                       | 138 ++++++++++++++++++
 10 files changed, 213 insertions(+), 26 deletions(-)

diff --git a/src/ojhunt/web/app.py b/src/ojhunt/web/app.py
index b202404..5150798 100644
--- a/src/ojhunt/web/app.py
+++ b/src/ojhunt/web/app.py
@@ -24,7 +24,7 @@
 from ojhunt.web.api import router as api_router
 from ojhunt.web.crawler_status import start_checker, stop_checker
 from ojhunt.web.http_client import close_http_client, get_http_client, init_http_client
-from ojhunt.web.pages import jinja_env
+from ojhunt.web.pages import render_page
 from ojhunt.web.pages import router as pages_router
 
 load_dotenv()
@@ -145,9 +145,13 @@ async def http_exception_handler(
 ) -> Response:
     if exc.status_code == 404 and not request.url.path.startswith("/api"):
         image_filename = random.choice(["cat.jpg", "man.jpg", "metro.jpg"])
-        template = jinja_env.get_template("404.html.jinja")
         return HTMLResponse(
-            template.render(image_filename=image_filename),
+            render_page(
+                "404.html.jinja",
+                request,
+                canonical=False,
+                image_filename=image_filename,
+            ),
             status_code=404,
         )
     return await _default_http_exception_handler(request, exc)
diff --git a/src/ojhunt/web/pages.py b/src/ojhunt/web/pages.py
index 5ce9dde..6468567 100644
--- a/src/ojhunt/web/pages.py
+++ b/src/ojhunt/web/pages.py
@@ -83,8 +83,24 @@
 jinja_env.globals["static_version"] = STATIC_VERSION
 
 
+def render_page(
+    template_name: str, request: Request, *, canonical: bool = True, **context: object
+) -> str:
+    """Render a page template with the metadata `base.html.jinja` needs.
+
+    Pass `canonical=False` for a page that must stay out of the search index
+    (404, easter eggs) — a noindex page must not claim a canonical URL.
+    """
+    base = str(request.base_url).rstrip("/")
+    return jinja_env.get_template(template_name).render(
+        site_base=base,
+        canonical_url=f"{base}{request.url.path}" if canonical else None,
+        **context,
+    )
+
+
 @router.get("/", response_class=HTMLResponse)
-async def index() -> str:
+async def index(request: Request) -> str:
     crawler_data = {
         name: {
             "title": info.meta.title,
@@ -93,13 +109,11 @@ async def index() -> str:
         }
         for name, info in sorted(crawler_registry.items())
     }
-    template = jinja_env.get_template("index.html.jinja")
-    return template.render(crawlers=crawler_data)
+    return render_page("index.html.jinja", request, crawlers=crawler_data)
 
 
 @router.get("/about", response_class=HTMLResponse)
-async def about() -> str:
-    template = jinja_env.get_template("about.html.jinja")
+async def about(request: Request) -> str:
     build_time_str = None
     if BUILD_TIME:
         try:
@@ -111,7 +125,9 @@ async def about() -> str:
             )
         except ValueError:
             build_time_str = BUILD_TIME
-    return template.render(
+    return render_page(
+        "about.html.jinja",
+        request,
         build_time=build_time_str,
         git_commit_sha=GIT_COMMIT_SHA,
     )
@@ -155,22 +171,24 @@ async def statistics_redirect():
 
 
 @router.get("/pdf/legacy", response_class=HTMLResponse)
-async def pdf_legacy_get() -> str:
-    template = jinja_env.get_template("pdf_legacy.html.jinja")
-    return template.render(
+async def pdf_legacy_get(request: Request) -> str:
+    return render_page(
+        "pdf_legacy.html.jinja",
+        request,
         active_page="legacy",
         legacy_available=Path("legacy.db").exists(),
     )
 
 
 @router.post("/pdf/legacy")
-async def pdf_legacy_post(username: str = Form(...)):
-    template = jinja_env.get_template("pdf_legacy.html.jinja")
+async def pdf_legacy_post(request: Request, username: str = Form(...)):
     try:
         pdf_bytes = export_user_pdf(username.strip())
     except FileNotFoundError:
         return HTMLResponse(
-            template.render(
+            render_page(
+                "pdf_legacy.html.jinja",
+                request,
                 active_page="legacy",
                 legacy_available=False,
                 prefill_username=username,
@@ -178,7 +196,9 @@ async def pdf_legacy_post(username: str = Form(...)):
         )
     except ValueError as e:
         return HTMLResponse(
-            template.render(
+            render_page(
+                "pdf_legacy.html.jinja",
+                request,
                 active_page="legacy",
                 legacy_available=True,
                 error=str(e),
@@ -196,17 +216,16 @@ async def pdf_legacy_post(username: str = Form(...)):
 
 
 @router.get("/pdf/merge", response_class=HTMLResponse)
-async def pdf_merge_get() -> str:
-    template = jinja_env.get_template("pdf_merge.html.jinja")
-    return template.render(active_page="merge")
+async def pdf_merge_get(request: Request) -> str:
+    return render_page("pdf_merge.html.jinja", request, active_page="merge")
 
 
 @router.post("/pdf/merge")
 async def pdf_merge_post(
+    request: Request,
     pdf_a: UploadFile = File(...),
     pdf_b: UploadFile = File(...),
 ):
-    template = jinja_env.get_template("pdf_merge.html.jinja")
     try:
         bytes_a = await pdf_a.read()
         bytes_b = await pdf_b.read()
@@ -223,7 +242,11 @@ async def pdf_merge_post(
         )
         pdf_bytes = generate_pdf(data_a.settings, history, snapshot)
     except ValueError as e:
-        return HTMLResponse(template.render(active_page="merge", error=str(e)))
+        return HTMLResponse(
+            render_page(
+                "pdf_merge.html.jinja", request, active_page="merge", error=str(e)
+            )
+        )
     return Response(
         content=pdf_bytes,
         media_type="application/pdf",
@@ -232,7 +255,7 @@ async def pdf_merge_post(
 
 
 @router.get("/crawlers", response_class=HTMLResponse)
-async def crawlers_page(test_availability: str | None = None) -> str:
+async def crawlers_page(request: Request, test_availability: str | None = None) -> str:
     import json
 
     if test_availability is not None:
@@ -260,16 +283,16 @@ async def crawlers_page(test_availability: str | None = None) -> str:
                 ),
             }
         )
-    template = jinja_env.get_template("crawlers.html.jinja")
-    return template.render(crawlers=crawler_list)
+    return render_page("crawlers.html.jinja", request, crawlers=crawler_list)
 
 
 async def _easter_egg_handler(request: Request) -> HTMLResponse:
     easter_egg_path = random.choice(
         ["easter_egg.html.jinja", "easter_egg_rick.html.jinja"]
     )
-    template = jinja_env.get_template(easter_egg_path)
-    return HTMLResponse(template.render(path=request.url.path))
+    return HTMLResponse(
+        render_page(easter_egg_path, request, canonical=False, path=request.url.path)
+    )
 
 
 for _path in _EASTER_EGG_PATHS:
diff --git a/src/ojhunt/web/templates/404.html.jinja b/src/ojhunt/web/templates/404.html.jinja
index d26e930..c3a5d69 100644
--- a/src/ojhunt/web/templates/404.html.jinja
+++ b/src/ojhunt/web/templates/404.html.jinja
@@ -2,6 +2,8 @@
 
 {% block title %}???????? — OJHunt Lite{% endblock %}
 
+{% block robots %}<meta name="robots" content="noindex">{% endblock %}
+
 {% block extra_head %}
 <style>
     .error-page {
diff --git a/src/ojhunt/web/templates/base.html.jinja b/src/ojhunt/web/templates/base.html.jinja
index 143a63e..1232079 100644
--- a/src/ojhunt/web/templates/base.html.jinja
+++ b/src/ojhunt/web/templates/base.html.jinja
@@ -4,6 +4,16 @@
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>{% block title %}OJHunt Lite{% endblock %}</title>
+    <meta name="description" content="{% block meta_description %}A lightweight async Python tool for Online Judge (OJ) statistics. Track your accepted problems (AC) and submissions across 29+ competitive programming sites.{% endblock %}">
+    {% block robots %}{% endblock %}
+    {% if canonical_url %}<link rel="canonical" href="{{ canonical_url }}">{% endif %}
+    <meta property="og:type" content="website">
+    <meta property="og:site_name" content="OJHunt Lite">
+    <meta property="og:title" content="{{ self.title() }}">
+    <meta property="og:description" content="{{ self.meta_description() }}">
+    {% if canonical_url %}<meta property="og:url" content="{{ canonical_url }}">{% endif %}
+    {% if site_base %}<meta property="og:image" content="{{ site_base }}/assets/logo.png">{% endif %}
+    <meta name="twitter:card" content="summary">
     <link rel="icon" type="image/x-icon" href="/favicon.ico">
     <link rel="describedby" href="/llms.txt" type="text/plain">
     <link rel="preconnect" href="https://fonts.googleapis.com">
diff --git a/src/ojhunt/web/templates/crawlers.html.jinja b/src/ojhunt/web/templates/crawlers.html.jinja
index 4310223..f98edc2 100644
--- a/src/ojhunt/web/templates/crawlers.html.jinja
+++ b/src/ojhunt/web/templates/crawlers.html.jinja
@@ -60,6 +60,8 @@
 
 {% block title %}Supported Crawlers - OJHunt Lite{% endblock %}
 
+{% block meta_description %}All {{ crawlers | length }} online judges that OJHunt Lite supports, with live availability status — Codeforces, AtCoder, LeetCode, HDU, POJ, SPOJ, UVa and more.{% endblock %}
+
 {% block page_id %}page-crawlers{% endblock %}
 
 {% block content %}
diff --git a/src/ojhunt/web/templates/easter_egg.html.jinja b/src/ojhunt/web/templates/easter_egg.html.jinja
index c3bb81c..c919120 100644
--- a/src/ojhunt/web/templates/easter_egg.html.jinja
+++ b/src/ojhunt/web/templates/easter_egg.html.jinja
@@ -2,6 +2,8 @@
 
 {% block title %}你访问的不是 {{ path }} — OJHunt Lite{% endblock %}
 
+{% block robots %}<meta name="robots" content="noindex">{% endblock %}
+
 {% block extra_head %}
 <style>
     .easter-egg-page {
diff --git a/src/ojhunt/web/templates/easter_egg_rick.html.jinja b/src/ojhunt/web/templates/easter_egg_rick.html.jinja
index 863426d..27ec89c 100644
--- a/src/ojhunt/web/templates/easter_egg_rick.html.jinja
+++ b/src/ojhunt/web/templates/easter_egg_rick.html.jinja
@@ -2,6 +2,8 @@
 
 {% block title %}Never Gonna Give You Up — OJHunt Lite{% endblock %}
 
+{% block robots %}<meta name="robots" content="noindex">{% endblock %}
+
 {% block extra_head %}
 <style>
     .easter-egg-page {
diff --git a/src/ojhunt/web/templates/pdf_legacy.html.jinja b/src/ojhunt/web/templates/pdf_legacy.html.jinja
index 5bc5d53..2f8a542 100644
--- a/src/ojhunt/web/templates/pdf_legacy.html.jinja
+++ b/src/ojhunt/web/templates/pdf_legacy.html.jinja
@@ -2,6 +2,8 @@
 
 {% block title %}Legacy Data Export - OJHunt Lite{% endblock %}
 
+{% block meta_description %}Export your solved-problem history from the old acm-statistics site as an OJHunt PDF report, then carry it forward into new queries.{% endblock %}
+
 {% block pdf_heading %}legacy-export{% endblock %}
 {% block pdf_meta %}recover acm-statistics history{% endblock %}
 
diff --git a/src/ojhunt/web/templates/pdf_merge.html.jinja b/src/ojhunt/web/templates/pdf_merge.html.jinja
index dc26666..0ecf489 100644
--- a/src/ojhunt/web/templates/pdf_merge.html.jinja
+++ b/src/ojhunt/web/templates/pdf_merge.html.jinja
@@ -2,6 +2,8 @@
 
 {% block title %}Merge History - OJHunt Lite{% endblock %}
 
+{% block meta_description %}Merge two OJHunt PDF progress reports into one file that keeps the complete solved-problem history from both.{% endblock %}
+
 {% block pdf_heading %}merge-history{% endblock %}
 {% block pdf_meta %}combine history from multiple PDFs{% endblock %}
 
diff --git a/tests/web/pages_test.py b/tests/web/pages_test.py
index aee4575..78b76a6 100644
--- a/tests/web/pages_test.py
+++ b/tests/web/pages_test.py
@@ -4,9 +4,13 @@
 TestClient and mock export_user_pdf where needed.
 """
 
+import re
+
+import pytest
 from fastapi.testclient import TestClient
 
 from ojhunt.web.app import app
+from ojhunt.web.pages import router as pages_router
 from ojhunt.web.pdf import (
     HistoryEntry,
     PdfQueryItem,
@@ -277,3 +281,137 @@ def test_docs_vendored_assets_are_served():
         "/assets/redoc.standalone-2.5.3.js",
     ):
         assert client.get(asset).status_code == 200, asset
+
+
+# ---------------------------------------------------------------------------
+# Search-engine metadata (base.html.jinja + render_page)
+# ---------------------------------------------------------------------------
+
+MAX_DESCRIPTION_LENGTH = 160
+
+STATIC_PAGE_PATHS = sorted(
+    route.path
+    for route in pages_router.routes
+    if "GET" in getattr(route, "methods", set()) and "{" not in route.path
+)
+
+INDEXED_PAGES = ["/", "/about", "/crawlers", "/pdf/legacy", "/pdf/merge"]
+
+
+def _meta_content(html: str, attr: str, name: str) -> str | None:
+    match = re.search(
+        rf'<meta {attr}="{re.escape(name)}" content="([^"]*)"',
+        html,
+    )
+    return match.group(1) if match else None
+
+
+def _description(html: str) -> str | None:
+    return _meta_content(html, "name", "description")
+
+
+def _canonical(html: str) -> str | None:
+    match = re.search(r'<link rel="canonical" href="([^"]*)"', html)
+    return match.group(1) if match else None
+
+
+def _html_response(path: str):
+    response = client.get(path)
+    is_html = response.status_code == 200 and "text/html" in response.headers.get(
+        "content-type", ""
+    )
+    return response if is_html else None
+
+
+def test_no_page_route_takes_path_parameters():
+    templated = [route.path for route in pages_router.routes if "{" in route.path]
+    assert not templated, (
+        f"{templated} take path parameters, and the metadata checks below only "
+        "reach static paths — extend them to cover dynamic pages"
+    )
+
+
+def test_discovery_found_the_known_pages():
+    assert set(INDEXED_PAGES) <= set(STATIC_PAGE_PATHS), (
+        "route discovery missed a page listed in sitemap.xml.jinja"
+    )
+
+
+@pytest.mark.parametrize("path", STATIC_PAGE_PATHS)
+def test_page_has_a_description(path):
+    response = _html_response(path)
+    if response is None:
+        pytest.skip(f"{path} does not answer with HTML")
+    description = _description(response.text)
+    assert description, (
+        f"{path} has no meta description, so a search engine writes its own "
+        "snippet out of whatever text comes first on the page"
+    )
+    assert len(description) <= MAX_DESCRIPTION_LENGTH, (
+        f"{path} description is {len(description)} characters — "
+        f"a search engine truncates it at {MAX_DESCRIPTION_LENGTH}"
+    )
+
+
+def test_home_and_about_share_the_project_summary():
+    home = _description(client.get("/").text)
+    about = _description(client.get("/about").text)
+    assert home == about, "both pages describe the project, not one page of it"
+    assert "Online Judge" in home, "the summary must name what the project queries"
+
+
+def test_other_pages_describe_themselves():
+    generic = _description(client.get("/").text)
+    specific = {
+        path: _description(client.get(path).text)
+        for path in ("/crawlers", "/pdf/legacy", "/pdf/merge")
+    }
+    for path, description in specific.items():
+        assert description != generic, f"{path} reuses the generic description"
+    assert len(set(specific.values())) == len(specific), "descriptions are not unique"
+
+
+@pytest.mark.parametrize("path", STATIC_PAGE_PATHS)
+def test_page_either_claims_a_canonical_url_or_says_noindex(path):
+    response = _html_response(path)
+    if response is None:
+        pytest.skip(f"{path} does not answer with HTML")
+    html = response.text
+    if _meta_content(html, "name", "robots") == "noindex":
+        assert _canonical(html) is None, f"{path} is noindex but claims a canonical URL"
+        return
+    assert _canonical(html) == f"http://testserver{path}", (
+        f"{path} is indexable, so it must be canonical to itself"
+    )
+    assert _meta_content(html, "property", "og:url") == _canonical(html), (
+        f"{path} disagrees with itself: og:url differs from the canonical URL"
+    )
+
+
+def test_home_page_has_open_graph_tags():
+    html = client.get("/").text
+    assert _meta_content(html, "property", "og:type") == "website"
+    assert _meta_content(html, "property", "og:site_name") == "OJHunt Lite"
+    assert _meta_content(html, "property", "og:title") == "OJHunt Lite"
+    assert _meta_content(html, "property", "og:description") == _description(html)
+    assert (
+        _meta_content(html, "property", "og:image")
+        == "http://testserver/assets/logo.png"
+    )
+    assert _meta_content(html, "name", "twitter:card") == "summary"
+
+
+def test_crawlers_page_description_counts_the_registry():
+    from ojhunt.crawlers import crawlers as registry
+
+    description = _description(client.get("/crawlers").text)
+    assert f"All {len(registry)} online judges" in description
+
+
+@pytest.mark.parametrize("path", ["/admin", "/.env", "/no-such-page"])
+def test_junk_page_is_excluded_from_the_index(path):
+    html = client.get(path).text
+    assert _meta_content(html, "name", "robots") == "noindex", (
+        f"{path} answers 200, so without noindex a search engine can index it"
+    )
+    assert _canonical(html) is None, f"{path} must not claim a canonical URL"

From 8f58584154539525f2ed149d0312082cc9314c2e Mon Sep 17 00:00:00 2001
From: Shumin Liu <shumin.liu@tngtech.com>
Date: Fri, 14 Aug 2026 16:38:12 +1000
Subject: [PATCH 2/8] docs: record two environment rules this session exposed

The format hook runs `ruff check --fix` after every Python edit, so an import
added before its first use is deleted before the next edit runs. It happened
twice in one session and surfaced both times as a NameError far from the cause.

The page-metadata work also produced a doc section that restated what the code
already said. Sharpen the routing rule that should have stopped it: prefer a
test that discovers what it checks over a written rule, and keep prose for the
intent a test cannot express.
---
 .claude/skills/ojhunt-update-env/SKILL.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/.claude/skills/ojhunt-update-env/SKILL.md b/.claude/skills/ojhunt-update-env/SKILL.md
index 69d9562..a0d9e27 100644
--- a/.claude/skills/ojhunt-update-env/SKILL.md
+++ b/.claude/skills/ojhunt-update-env/SKILL.md
@@ -55,6 +55,17 @@ The home for development conventions, schemas, templates, and gotchas — the kn
 new, so the agent can find it. **Only document what's non-obvious** — if Claude can derive it by
 reading the files, or it's enforced elsewhere (hook, test, linter), don't write it.
 
+**Docs capture intent, not facts that can be reasoned.** Two questions kill most draft lines:
+
+- Can an agent derive this by opening one file? Delete the line.
+- Does a test, hook, or linter already assert it? Delete the line.
+
+**Before writing a rule, try to make a test assert it instead.** A test fails when somebody
+breaks the rule; a doc line does not. Prefer a test that *discovers* what it checks (walk the
+router, glob the crawler files) over one that hardcodes today's list — a hardcoded list goes
+stale silently, which is the gap the rule was meant to close. Document only what the test
+cannot express: why the rule exists.
+
 **When a well-written doc already covers a topic, reference it — don't replicate.** A skill or
 another doc should point to the authoritative file plus any gotchas it doesn't capture.
 

From ded4c4af214df1911274dc0011ae0408dd919926 Mon Sep 17 00:00:00 2001
From: Shumin Liu <shumin.liu@tngtech.com>
Date: Fri, 14 Aug 2026 17:14:08 +1000
Subject: [PATCH 3/8] chore(env): load code conventions from path-scoped rules

The routing table in docs/development.md told an agent where to look, but
nothing made it look at the moment it mattered. Two conventions were missed in
one session: comments were written above asserts instead of inside them, and a
fact already covered by docs/dev/python.md was duplicated into hooks.md.

Conventions tied to editing a kind of file move to .claude/rules/*.md with
paths: frontmatter, so they enter context when a matching file is opened rather
than waiting to be looked up. Six rules cover Python, tests, e2e, the web layer,
docs and hooks.

Three kinds of knowledge stay in docs/dev/, because no file pattern can trigger
them: a new crawler starts as a file that does not exist yet, ops work touches
no repo file, and questions like "does this warrant an ADR" precede any file.
The routing table now carries only those. The update-env skill records the split
and the compaction caveat.

format-lint-python.sh gains one check: a comment directly above an assert in a
test. It reads the edit payload rather than the file, so the cases already in
the suite do not fire on every unrelated edit.
---
 .claude/hooks/format-lint-python.sh           | 18 ++++
 .claude/rules/docs.md                         | 45 +++++++++
 {docs/dev => .claude/rules}/e2e.md            |  7 +-
 {docs/dev => .claude/rules}/hooks.md          | 12 +++
 {docs/dev => .claude/rules}/python.md         | 15 ++-
 docs/dev/testing.md => .claude/rules/tests.md | 18 +++-
 .claude/rules/web.md                          | 97 +++++++++++++++++++
 .claude/skills/ojhunt-crawlers/SKILL.md       |  2 +-
 .claude/skills/ojhunt-implement/SKILL.md      |  5 +-
 .claude/skills/ojhunt-update-env/SKILL.md     | 49 ++++++----
 CLAUDE.md                                     | 21 ++--
 docs/dev/docs.md                              | 18 ----
 docs/dev/web.md                               | 95 +-----------------
 docs/development.md                           | 16 +--
 14 files changed, 265 insertions(+), 153 deletions(-)
 create mode 100644 .claude/rules/docs.md
 rename {docs/dev => .claude/rules}/e2e.md (95%)
 rename {docs/dev => .claude/rules}/hooks.md (63%)
 rename {docs/dev => .claude/rules}/python.md (87%)
 rename docs/dev/testing.md => .claude/rules/tests.md (76%)
 create mode 100644 .claude/rules/web.md
 delete mode 100644 docs/dev/docs.md

diff --git a/.claude/hooks/format-lint-python.sh b/.claude/hooks/format-lint-python.sh
index ed92dfc..08556cc 100644
--- a/.claude/hooks/format-lint-python.sh
+++ b/.claude/hooks/format-lint-python.sh
@@ -10,4 +10,22 @@ elif command -v ruff &>/dev/null; then
     ruff format "$FILE" 2>/dev/null || true
     ruff check --fix "$FILE" 2>/dev/null || true
 fi
+
+# In tests the explanation belongs in the assert message, not in a comment above it
+# (.claude/rules/python.md). Ruff has no rule for this, and it is a one-line pattern.
+# Only the text this edit introduced is scanned: the suite still carries older comments,
+# and flagging those would fire on every unrelated edit until someone cleaned them up.
+if [[ "$FILE" == *_test.py || "$FILE" == */tests/* ]]; then
+    ADDED=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // ""' 2>/dev/null)
+    HITS=$(printf '%s\n' "$ADDED" | awk '
+        /^[[:space:]]*#/ { comment = 1; text = $0; next }
+        /^[[:space:]]*assert[[:space:](]/ { if (comment) print text }
+        { comment = 0 }
+    ')
+    if [[ -n "$HITS" ]]; then
+        echo "$FILE: this edit puts a comment directly above an assert. Move the explanation into the assert message (see .claude/rules/python.md):" >&2
+        echo "$HITS" >&2
+        exit 2
+    fi
+fi
 exit 0
diff --git a/.claude/rules/docs.md b/.claude/rules/docs.md
new file mode 100644
index 0000000..f58f4f1
--- /dev/null
+++ b/.claude/rules/docs.md
@@ -0,0 +1,45 @@
+---
+paths:
+  - "docs/**/*.md"
+  - "README.md"
+  - ".claude/**/*.md"
+---
+
+# Documentation conventions
+
+For *where* a fact belongs (docs vs rule vs skill vs hook vs ADR), load the
+**ojhunt-update-env** skill. This rule covers how to write once you know the target.
+
+## Write only what cannot be derived
+
+Two questions kill most draft lines:
+
+- Can an agent derive this by opening one file? Delete the line.
+- Does a test, hook, or linter already assert it? Delete the line.
+
+Docs capture intent — why a construct is load-bearing, why the obvious alternative is
+wrong. Before writing a rule, try to make a test assert it instead: a test fails when
+somebody breaks the rule, a doc line does not.
+
+**Prefer deleting to adding.** Appending a clarification is the reflex; usually the file reads
+better with the wrong line gone. A false observation — a flaky test that was really a bad
+connection, a gotcha that was really local misconfiguration — is deleted, not corrected. A
+paragraph saying an earlier paragraph was wrong leaves the reader two claims to adjudicate.
+
+## README.md is a quick start
+
+Keep it short and direct: what the tool is, how to run it, one example per interface.
+Everything else is a link.
+
+When a section grows past a screen, move the detail into `docs/` and leave a pointer.
+Reference material belongs in [`docs/cli.md`](../../docs/cli.md),
+[`docs/web.md`](../../docs/web.md) and [`docs/library.md`](../../docs/library.md) — not in
+the README.
+
+`docs/library.md` is generated by `./doit.sh gen-docs`: write library-facing prose in the
+docstrings it compiles, never in the file itself. A unit test fails while the committed copy
+is stale.
+
+To check whether it is stale, run the task and read `.doit/gen-docs.log`: never suppress the
+generator's stderr, because a crash leaves the file untouched and so looks exactly like
+"already fresh".
diff --git a/docs/dev/e2e.md b/.claude/rules/e2e.md
similarity index 95%
rename from docs/dev/e2e.md
rename to .claude/rules/e2e.md
index 9d977dc..4043f38 100644
--- a/docs/dev/e2e.md
+++ b/.claude/rules/e2e.md
@@ -1,6 +1,11 @@
+---
+paths:
+  - "tests/e2e/**/*.py"
+---
+
 # E2E tests (Playwright)
 
-See [`docs/dev/testing.md`](testing.md) for shared pytest fixture and assertion conventions.
+See [`tests.md`](tests.md) for shared pytest fixture and assertion conventions.
 
 ## Setup
 
diff --git a/docs/dev/hooks.md b/.claude/rules/hooks.md
similarity index 63%
rename from docs/dev/hooks.md
rename to .claude/rules/hooks.md
index 7c1442a..d6ce289 100644
--- a/docs/dev/hooks.md
+++ b/.claude/rules/hooks.md
@@ -1,3 +1,9 @@
+---
+paths:
+  - ".claude/hooks/**"
+  - ".claude/settings.json"
+---
+
 # Project hooks
 
 Hooks enforce constraints mechanically. Check `.claude/settings.json` to see
@@ -8,6 +14,12 @@ what's currently active.
 Scripts live in `.claude/hooks/`, wired in `.claude/settings.json` (checked
 into git — not `settings.local.json`, not `~/.claude/`).
 
+## Write a check only when it is cheap and deterministic
+
+A hook earns its place when the rule is a one-line pattern with an unambiguous fix. If the
+check needs judgement, a rule under `.claude/rules/` states the convention instead — a noisy
+hook trains everyone to ignore it.
+
 ## Regex gotcha for command bans
 
 Do NOT use `(^|[;&|[:space:]])word[[:space:]]` — this matches the word inside
diff --git a/docs/dev/python.md b/.claude/rules/python.md
similarity index 87%
rename from docs/dev/python.md
rename to .claude/rules/python.md
index 9489cc1..e48cbd6 100644
--- a/docs/dev/python.md
+++ b/.claude/rules/python.md
@@ -1,3 +1,9 @@
+---
+paths:
+  - "**/*.py"
+  - "pyproject.toml"
+---
+
 # Python conventions
 
 ## Import order
@@ -30,7 +36,7 @@ Do not use `Dict`, `List`, `Optional` or `Union` from `typing` — ruff rewrites
 (`UP006`, `UP007`, `UP035`, `UP045`), and the `format-lint-python.sh` hook applies that
 rewrite on every edit. Take `Callable` and `Awaitable` from `collections.abc`, not `typing`.
 
-See [ADR 0016](../adr/0016-adopt-ruff-default-rule-set.md) for why this reversed.
+See [ADR 0016](../../docs/adr/0016-adopt-ruff-default-rule-set.md) for why this reversed.
 
 ## Prefer asserts and names over comments
 
@@ -46,6 +52,7 @@ argument, a judge's response — needs a real `raise`, because `python -O` strip
 
 In tests, put the explanation in the assert message, not in a comment above it:
 `assert "items" in listed, "dict's own attributes must survive"`.
+`format-lint-python.sh` flags a comment that sits directly above an `assert`.
 
 Where a comment would explain *what* an expression produces, name the value instead:
 `single_line_description = " ".join(text.split())`.
@@ -67,9 +74,9 @@ resolve. This applies to all packages including FastAPI, uvicorn, etc.
 
 ## Ruff removes imports before their usage
 
-Ruff (pre-commit hook) runs between edits and strips imports that appear unused at
-that moment. If you add an import in one `Edit` call and the code that uses it in a
-second call, ruff will delete the import between the two calls.
+Ruff runs between edits and strips imports that appear unused at that moment. If you add an
+import in one `Edit` call and the code that uses it in a second call, ruff will delete the
+import between the two calls.
 
 **Fix:** always add new imports and the code that uses them in the same `Edit` call.
 
diff --git a/docs/dev/testing.md b/.claude/rules/tests.md
similarity index 76%
rename from docs/dev/testing.md
rename to .claude/rules/tests.md
index 4d7d1b6..73e79f8 100644
--- a/docs/dev/testing.md
+++ b/.claude/rules/tests.md
@@ -1,7 +1,14 @@
+---
+paths:
+  - "**/*_test.py"
+  - "tests/**/*.py"
+---
+
 # Pytest conventions
 
-Crawler-specific test conventions live in [`docs/dev/crawlers.md`](crawlers.md) and the
-**ojhunt-crawlers** skill. Playwright e2e tests live in [`docs/dev/e2e.md`](e2e.md).
+Crawler-specific test conventions live in [`docs/dev/crawlers.md`](../../docs/dev/crawlers.md)
+and the **ojhunt-crawlers** skill. Playwright e2e tests have their own rule in
+[`e2e.md`](e2e.md).
 
 ## Running tests
 
@@ -47,6 +54,13 @@ client = TestClient(app, follow_redirects=False)
 files = {"field": ("name.pdf", bytes_content, "application/pdf")}
 ```
 
+## Prefer discovery over a hardcoded list
+
+A test that enumerates today's routes, crawlers, or files goes stale in silence: the thing it
+was meant to catch is exactly the new entry nobody added to the list. Walk the router or glob
+the directory instead. When a shape genuinely cannot be discovered, assert that no such shape
+exists yet, so the day one appears the suite says so.
+
 ## Markdown doc tests
 
 Python fenced blocks in `README.md` and `docs/` are collected by `pytest-markdown-docs`
diff --git a/.claude/rules/web.md b/.claude/rules/web.md
new file mode 100644
index 0000000..a85cf7f
--- /dev/null
+++ b/.claude/rules/web.md
@@ -0,0 +1,97 @@
+---
+paths:
+  - "src/ojhunt/web/**"
+---
+
+# Web layer conventions
+
+Dev server lifecycle and environment variables are operational, not code conventions —
+they live in [`docs/dev/web.md`](../../docs/dev/web.md). For user-facing usage see
+[`docs/web.md`](../../docs/web.md).
+
+## PDF internals
+
+- `extract_data(pdf_bytes)` returns `PdfEmbeddedData` — has `settings` and `history` only.
+  It does **not** have a `snapshot`; the snapshot is never embedded in the PDF. Build one
+  manually from history if needed.
+- For page routes returning `application/pdf` on success and HTML on error: return explicit
+  `Response(content=..., media_type="application/pdf")` or `HTMLResponse(...)` — do not use
+  `response_class=HTMLResponse` on the decorator.
+- When adding form-based page endpoints accessible to agents, document them in `llms.txt`.
+
+## Minimal JS principle
+
+Keep JavaScript minimal. Business logic belongs in Python; JS handles only browser-specific
+concerns.
+
+- Day boundary / timezone computation → backend (frontend sends IANA timezone string)
+- History merge/dedup → backend
+- Pydantic schemas on all new API endpoints (not loose dicts)
+- Prefer a POST to the server over inline JS computation
+
+JS is appropriate for: reading local files, computing timezone name via
+`Intl.DateTimeFormat().resolvedOptions().timeZone`, triggering downloads, reactive UI state.
+
+## FastAPI trailing slashes + StaticFiles
+
+When `StaticFiles` is mounted at `"/"`, FastAPI's `redirect_slashes` is suppressed.
+`Mount("/")` matches every path first and returns 404 for paths that aren't real files —
+the redirect never fires.
+
+- `fetch()` URLs in `app.js` must exactly match the route path in `api.py` (no trailing
+  slashes unless the route has one)
+- HTML `href` attributes are harmless (browsers follow 307 redirects), but `fetch()` calls
+  can silently fail because StaticFiles returns a non-JSON 404 body that breaks `response.json()`
+
+## Reverse-proxy rate limiting (429)
+
+The app itself never emits HTTP 429 — rate limiting is enforced by the production reverse
+proxy, and its 429 body is **not** JSON. Any client `fetch` that reaches the server can
+therefore receive a 429 with an HTML/plain-text body.
+
+- Client `fetch` handlers must special-case `response.status === 429` **before** calling
+  `response.json()` — otherwise the non-JSON body makes `response.json()` throw and the user
+  sees a confusing parse error instead of a rate-limit message.
+- Established guards live in `app.js`: `executeQuery`, `calculateReport`, `downloadReport`.
+
+## CSS conventions
+
+CSS files live at `src/ojhunt/web/static/assets/`:
+
+| File | What belongs here |
+|------|-------------------|
+| `base.css` | Design-system tokens (`:root`, `[data-accent=...]`), page resets, `.topbar`, `.page`, `.header`, `.footer`, `dialog`/`.dlg-*`, `.card` base layout (including `::before` stripe and `:hover`), `[x-cloak]`, `:focus-visible`, responsive media queries for shared components |
+| `index.css` | Everything used *only* by the home page: `.step`, `.report-slot`, `.grid`, card internals (`.c-hd`, `.c-body-row`, `.c-ft`, `.c-err-msg`, `.solved-link`, `.subs-val`, `.iconbtn`, `.loading-dots`, `.card-empty`), card status variants (`.card.r-ok::before` etc.), `.download-card`/`.summary`/`.dc-*`/`.stat`, `.composer`, `.field`, `.btn` (all variants), `.step-actions` |
+
+**Short templates** (crawlers, about, pdf pages) keep their inline `<style>` blocks — only extract when a template's styles grow long.
+
+**The critical rule:** anything from the original `base.html.jinja` `<style>` block that *any* page besides `index.html` uses must stay in `base.css`. The `about` page uses `.card`, `.card::before`, and `.card:hover` — these are in `base.css`.
+
+**Referencing CSS in templates:**
+
+```html
+<link rel="stylesheet" href="/assets/base.css?v={{ static_version }}">
+```
+
+`static_version` is a Jinja2 global injected via `jinja_env.globals["static_version"] = STATIC_VERSION` in `pages.py` — no need to pass it in individual `.render()` calls.
+
+**Visual regression tests** live in `tests/e2e/test_visual.py` (local-only, skipped in CI). After any CSS change:
+
+```bash
+# Update baselines (dangerouslyDisableSandbox: true)
+./doit.sh update-snapshots
+
+# Verify no unintended visual diff (dangerouslyDisableSandbox: true)
+./doit.sh test-visual
+```
+
+Baselines are stored in `tests/e2e/__snapshots__/`. Commit baseline PNGs alongside the test or CSS change that necessitates them.
+
+## Project history context (for UI copy)
+
+When writing UI copy that refers to "the old site":
+- **Old site** = `github.com/Liu233w/acm-statistics` deployment (also known as *ACM Statistics*,
+  *OJ Analyzer*, *OJHunt*)
+- **Not** npuacm.info (built by Jiduo Zhang; unrelated to this codebase)
+- VPS compromise: October 2025 — data after 2025-10-22 was lost
+- `legacy.db` preserves history up to 2025-10-22; web + CLI export available
diff --git a/.claude/skills/ojhunt-crawlers/SKILL.md b/.claude/skills/ojhunt-crawlers/SKILL.md
index 3b54ed0..7b4ac4c 100644
--- a/.claude/skills/ojhunt-crawlers/SKILL.md
+++ b/.claude/skills/ojhunt-crawlers/SKILL.md
@@ -9,7 +9,7 @@ This skill is the **procedure**. The reference material it points to —
 `__crawler_meta__` fields, login types, code templates, HTML parsing, SSL, license header,
 archived-crawler rules — lives in **`docs/dev/crawlers.md`**. Read that alongside these steps.
 
-For general pytest conventions see **`docs/dev/testing.md`**. For ADR guidance on significant
+For general pytest conventions see **`.claude/rules/tests.md`**. For ADR guidance on significant
 design decisions, invoke the **ojhunt-commit** skill.
 
 ## Implementing a New Crawler
diff --git a/.claude/skills/ojhunt-implement/SKILL.md b/.claude/skills/ojhunt-implement/SKILL.md
index 80e1797..f198d9b 100644
--- a/.claude/skills/ojhunt-implement/SKILL.md
+++ b/.claude/skills/ojhunt-implement/SKILL.md
@@ -7,7 +7,8 @@ description: End-to-end feature workflow — plan (in plan mode) → approval 
 
 This skill is the **procedure** for taking a feature from request to committed code.
 It only orchestrates — the *conventions* for each area (Python style, tests, web
-layer, crawlers, …) live in `docs/dev/*.md`, indexed by the routing table in
+layer, crawlers, …) load from `.claude/rules/*.md` on a file match, or sit in `docs/dev/*.md`
+indexed by the routing table in
 `docs/development.md`. Read the matching doc **before** you write code in that area.
 
 ## User request
@@ -22,7 +23,7 @@ make the change reviewable — don't skip ahead.
 1. **Plan first, and get approval.** If you are not already in plan mode, enter it
    (EnterPlanMode) — planning before editing is what lets the user redirect the
    approach cheaply, before any code is written. Explore the relevant code, read the
-   matching `docs/dev/*.md`, then draft a concrete plan and present it for approval
+   matching rule or `docs/dev/*.md`, then draft a concrete plan and present it for approval
    (ExitPlanMode). **Do not implement until the user approves** — the request above
    is a starting point, not a mandate to build immediately.
 
diff --git a/.claude/skills/ojhunt-update-env/SKILL.md b/.claude/skills/ojhunt-update-env/SKILL.md
index a0d9e27..3f9fa09 100644
--- a/.claude/skills/ojhunt-update-env/SKILL.md
+++ b/.claude/skills/ojhunt-update-env/SKILL.md
@@ -9,13 +9,22 @@ description: Single source of truth for where each piece of knowledge belongs (d
 documentation, point to the authoritative source — don't inline definitions that already exist
 elsewhere. Duplication causes drift.
 
-**Workflow vs. convention — pick the right channel.** A **workflow** (a procedure you run on
-demand: commit, implement a crawler, decide where knowledge goes) is a **skill**. A
-**convention or reference fact** (code style, a schema, a gotcha, a test rule) is a **doc under
-`docs/dev/`** — because skills are lazily triggered and unreliably loaded, whereas `docs/dev/`
-is indexed by `docs/development.md`, which is `@`-imported into `CLAUDE.md` and therefore always
-in context. Don't put a convention in a skill hoping it triggers; add it to `docs/dev/` and its
-routing-table row.
+**Route by what triggers the knowledge, not by what it is about.** A **workflow** (a procedure
+you run on demand: commit, implement a crawler, decide where knowledge goes) is a **skill**. A
+**convention tied to editing a kind of file** is a **rule under `.claude/rules/`** with `paths:`
+frontmatter, so it enters context the moment a matching file is opened. Don't put a convention in
+a skill hoping it triggers.
+
+**`paths:` cannot trigger everything.** Keep a fact in `docs/dev/` plus a routing-table row when:
+
+- The file does not exist yet. A rule fires when Claude *reads* a matching file, so writing a
+  brand-new crawler has nothing to trigger on — this is why `docs/dev/crawlers.md` stays a doc.
+- The knowledge precedes any file: whether to write an ADR, which layer a fact belongs to,
+  which branch to commit on. No glob matches a decision.
+- The activity is not file editing at all: starting the dev server, deploying, ops.
+
+One more limit worth knowing: after `/compact`, path-scoped rules are **not** re-injected. They
+reload the next time a matching file is read. Root `CLAUDE.md` is re-injected.
 
 **Command docs span multiple layers — search before changing.** Shell commands (e.g. how to
 run tests, start the server, add a dependency) can be documented in skills, READMEs, `docs/`,
@@ -39,16 +48,22 @@ Documentation for users running or deploying the project:
   detail in `docs/dev/`, not here.
 - `docs/adr/` — Architectural decisions (see below)
 
-## `docs/dev/` (internal conventions & reference)
-The home for development conventions, schemas, templates, and gotchas — the knowledge you need
-*while working* but that isn't a procedure. One file per domain:
+## `.claude/rules/` (conventions that load on a file match)
+Conventions for editing a kind of file. Each carries `paths:` frontmatter and loads by itself:
+- `python.md` — `**/*.py`, `pyproject.toml`: import order, typing, comments, dependencies
+- `tests.md` — `**/*_test.py`, `tests/**`: pytest conventions, CI scope, page-route tests
+- `e2e.md` — `tests/e2e/**`: Playwright / visual regression conventions
+- `web.md` — `src/ojhunt/web/**`: PDF internals, minimal-JS, CSS, FastAPI gotchas
+- `docs.md` — `docs/**`, `README.md`, `.claude/**`: what to write and what to leave out
+- `hooks.md` — `.claude/hooks/**`, `.claude/settings.json`: hook wiring and the regex gotcha
+
+A rule is not a place to dump reference material: it costs context every time a matching file
+is opened. Keep each one to conventions somebody could get wrong.
+
+## `docs/dev/` (reference no file pattern can trigger)
 - `docs/dev/crawlers.md` — crawler metadata schema, login types, return format, templates,
   HTML parsing, SSL, license header, archived-crawler rules
-- `docs/dev/python.md` — import order, typing, error handling, dependencies (`uv add`)
-- `docs/dev/testing.md` — pytest conventions, CI scope, page-route tests, markdown doc tests
-- `docs/dev/e2e.md` — Playwright e2e / visual regression conventions
-- `docs/dev/web.md` — FastAPI app, PDF internals, dev server, env vars, minimal-JS, CSS
-- `docs/dev/hooks.md` — how project hooks work and the command-ban regex gotcha
+- `docs/dev/web.md` — dev server lifecycle, ports in worktrees, environment variables
 - `docs/dev/deployment.md` — system fonts, `legacy.db`, PDF preview script
 
 **When adding a fact here, add a routing-table row to `docs/development.md`** if the domain is
@@ -94,7 +109,7 @@ directory. Use the `ojhunt-` prefix to group related project skills.
 
 ## Hooks (`.claude/hooks/` + `.claude/settings.json`)
 Hard enforcement rules — things the agent must never do or must always do automatically.
-Update when you need mechanical enforcement, not just reminders. See `docs/dev/hooks.md`.
+Update when you need mechanical enforcement, not just reminders. See `.claude/rules/hooks.md`.
 
 ## Commands (`.claude/commands/`)
 Project-level slash commands that override global ones.
@@ -149,7 +164,7 @@ not here.
 - Development convention, style, schema, or gotcha for a code area → `docs/dev/<area>.md`
   (add a routing-table row in `docs/development.md` if the domain is new)
 - Workflow or process (a procedure run on demand) → `.claude/skills/ojhunt-*/`
-- "Never do X" or "always do Y after Z" → **hook first** (see `docs/dev/hooks.md`); once
+- "Never do X" or "always do Y after Z" → **hook first** (see `.claude/rules/hooks.md`); once
   hook-enforced, do NOT also add a doc/skill entry — the hook is the enforcement, a note just
   creates drift
 - Project-level command override → `.claude/commands/`
diff --git a/CLAUDE.md b/CLAUDE.md
index 5f3664e..9023d80 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -20,8 +20,9 @@ When a `lint`/`test-*`/`full-check` task fails, its full output is already saved
 - **Development conventions & reference** → the index in [docs/development.md](docs/development.md)
 - **Architectural decisions** → [docs/adr/](docs/adr/)
 
-The development index is imported below so its routing table — "working on X → read
-`docs/dev/X.md`" — is always in context. Follow it to the right reference before starting work.
+Code conventions load by themselves: `.claude/rules/*.md` carry `paths:` frontmatter, so the
+Python, test, e2e, web-layer, docs and hook rules enter context when you open a matching file.
+The development index below routes what no file pattern can trigger.
 
 @docs/development.md
 
@@ -35,18 +36,18 @@ tool (don't read skill files as plain text):
 - **ojhunt-commit** — commit, commit conventions, ADRs
 - **ojhunt-update-env** — decide where a new piece of knowledge belongs
 
-**Conventions and reference** (Python style, tests, e2e, web layer, hooks, crawler reference,
-deployment) are *not* skills — they live in `docs/dev/*.md`, indexed by the routing table in
-`docs/development.md` (imported above). Read the matching doc before working in that area
-rather than relying on a skill to trigger.
+**Conventions and reference** are *not* skills. A convention tied to editing a kind of file
+lives in `.claude/rules/*.md` and loads on its own. Crawler reference and ops knowledge stay in
+`docs/dev/*.md`, routed by the table in `docs/development.md` (imported above).
 
 ### Growing project knowledge
 
 If the user mentions a workflow, convention, or recurring pattern that isn't captured yet,
-route it: a **workflow/procedure** → a skill; a **convention or reference fact** →
-`docs/dev/*.md` (and add a row to the routing table in `docs/development.md`); a **hard rule**
-→ a hook. Ask the user before adding, and see the **ojhunt-update-env** skill for the full
-routing map. Don't silently let project knowledge go undocumented.
+route it: a **workflow/procedure** → a skill; a **convention tied to a kind of file** →
+`.claude/rules/*.md` with `paths:` frontmatter; a **fact no file pattern can trigger** →
+`docs/dev/*.md` plus a routing-table row; a **cheap deterministic check** → a hook. Ask the
+user before adding, and see the **ojhunt-update-env** skill for the full routing map. Don't
+silently let project knowledge go undocumented.
 
 ### Self-correcting on repeated failures
 
diff --git a/docs/dev/docs.md b/docs/dev/docs.md
deleted file mode 100644
index 2756504..0000000
--- a/docs/dev/docs.md
+++ /dev/null
@@ -1,18 +0,0 @@
-# Documentation conventions
-
-## README.md is a quick start
-
-Keep it short and direct: what the tool is, how to run it, one example per interface.
-Everything else is a link.
-
-When a section grows past a screen, move the detail into `docs/` and leave a pointer.
-Reference material belongs in [`docs/cli.md`](../cli.md), [`docs/web.md`](../web.md) and
-[`docs/library.md`](../library.md) — not in the README.
-
-`docs/library.md` is generated by `./doit.sh gen-docs`: write library-facing prose in the
-docstrings it compiles, never in the file itself. A unit test fails while the committed copy
-is stale.
-
-To check whether it is stale, run the task and read `.doit/gen-docs.log`: never suppress the
-generator's stderr, because a crash leaves the file untouched and so looks exactly like
-"already fresh".
diff --git a/docs/dev/web.md b/docs/dev/web.md
index 02d0028..6ba0c0e 100644
--- a/docs/dev/web.md
+++ b/docs/dev/web.md
@@ -1,8 +1,8 @@
-# Web layer
+# Web layer operations
 
-Internal reference for the FastAPI app, PDF handling, dev server, and frontend conventions.
-For user-facing usage (production deployment, container, API endpoints) see
-[`docs/web.md`](../web.md).
+Running the dev server and configuring it. Code conventions for the web layer load
+automatically from `.claude/rules/web.md` when you edit `src/ojhunt/web/`. For user-facing
+usage (production deployment, container, API endpoints) see [`docs/web.md`](../web.md).
 
 ## Running the dev server
 
@@ -33,16 +33,6 @@ Use `doit.sh` — it starts the server, waits until it's ready, and manages the
 - e2e tests auto-discover the port (`OJHUNT_DEV_PORT` → `.doit/server.port` → 8080), so
   `./doit.sh test-e2e` / `test-visual` work in any worktree.
 
-## PDF internals
-
-- `extract_data(pdf_bytes)` returns `PdfEmbeddedData` — has `settings` and `history` only.
-  It does **not** have a `snapshot`; the snapshot is never embedded in the PDF. Build one
-  manually from history if needed.
-- For page routes returning `application/pdf` on success and HTML on error: return explicit
-  `Response(content=..., media_type="application/pdf")` or `HTMLResponse(...)` — do not use
-  `response_class=HTMLResponse` on the decorator.
-- When adding form-based page endpoints accessible to agents, document them in `llms.txt`.
-
 ## Environment variables
 
 | Variable | Required | Description |
@@ -54,80 +44,3 @@ Use `doit.sh` — it starts the server, waits until it's ready, and manages the
 
 Credentials go in `.env` (gitignored) — loaded automatically by `load_dotenv()` in
 `src/ojhunt/web/app.py`. No need to `source .env` manually.
-
-## Minimal JS principle
-
-Keep JavaScript minimal. Business logic belongs in Python; JS handles only browser-specific
-concerns.
-
-- Day boundary / timezone computation → backend (frontend sends IANA timezone string)
-- History merge/dedup → backend
-- Pydantic schemas on all new API endpoints (not loose dicts)
-- Prefer a POST to the server over inline JS computation
-
-JS is appropriate for: reading local files, computing timezone name via
-`Intl.DateTimeFormat().resolvedOptions().timeZone`, triggering downloads, reactive UI state.
-
-## FastAPI trailing slashes + StaticFiles
-
-When `StaticFiles` is mounted at `"/"`, FastAPI's `redirect_slashes` is suppressed.
-`Mount("/")` matches every path first and returns 404 for paths that aren't real files —
-the redirect never fires.
-
-- `fetch()` URLs in `app.js` must exactly match the route path in `api.py` (no trailing
-  slashes unless the route has one)
-- HTML `href` attributes are harmless (browsers follow 307 redirects), but `fetch()` calls
-  can silently fail because StaticFiles returns a non-JSON 404 body that breaks `response.json()`
-
-## Reverse-proxy rate limiting (429)
-
-The app itself never emits HTTP 429 — rate limiting is enforced by the production reverse
-proxy, and its 429 body is **not** JSON. Any client `fetch` that reaches the server can
-therefore receive a 429 with an HTML/plain-text body.
-
-- Client `fetch` handlers must special-case `response.status === 429` **before** calling
-  `response.json()` — otherwise the non-JSON body makes `response.json()` throw and the user
-  sees a confusing parse error instead of a rate-limit message.
-- Established guards live in `app.js`: `executeQuery`, `calculateReport`, `downloadReport`.
-
-## CSS conventions
-
-CSS files live at `src/ojhunt/web/static/assets/`:
-
-| File | What belongs here |
-|------|-------------------|
-| `base.css` | Design-system tokens (`:root`, `[data-accent=...]`), page resets, `.topbar`, `.page`, `.header`, `.footer`, `dialog`/`.dlg-*`, `.card` base layout (including `::before` stripe and `:hover`), `[x-cloak]`, `:focus-visible`, responsive media queries for shared components |
-| `index.css` | Everything used *only* by the home page: `.step`, `.report-slot`, `.grid`, card internals (`.c-hd`, `.c-body-row`, `.c-ft`, `.c-err-msg`, `.solved-link`, `.subs-val`, `.iconbtn`, `.loading-dots`, `.card-empty`), card status variants (`.card.r-ok::before` etc.), `.download-card`/`.summary`/`.dc-*`/`.stat`, `.composer`, `.field`, `.btn` (all variants), `.step-actions` |
-
-**Short templates** (crawlers, about, pdf pages) keep their inline `<style>` blocks — only extract when a template's styles grow long.
-
-**The critical rule:** anything from the original `base.html.jinja` `<style>` block that *any* page besides `index.html` uses must stay in `base.css`. The `about` page uses `.card`, `.card::before`, and `.card:hover` — these are in `base.css`.
-
-**Referencing CSS in templates:**
-
-```html
-<link rel="stylesheet" href="/assets/base.css?v={{ static_version }}">
-```
-
-`static_version` is a Jinja2 global injected via `jinja_env.globals["static_version"] = STATIC_VERSION` in `pages.py` — no need to pass it in individual `.render()` calls.
-
-**Visual regression tests** live in `tests/e2e/test_visual.py` (local-only, skipped in CI). After any CSS change:
-
-```bash
-# Update baselines (dangerouslyDisableSandbox: true)
-./doit.sh update-snapshots
-
-# Verify no unintended visual diff (dangerouslyDisableSandbox: true)
-./doit.sh test-visual
-```
-
-Baselines are stored in `tests/e2e/__snapshots__/`. Commit baseline PNGs alongside the test or CSS change that necessitates them.
-
-## Project history context (for UI copy)
-
-When writing UI copy that refers to "the old site":
-- **Old site** = `github.com/Liu233w/acm-statistics` deployment (also known as *ACM Statistics*,
-  *OJ Analyzer*, *OJHunt*)
-- **Not** npuacm.info (built by Jiduo Zhang; unrelated to this codebase)
-- VPS compromise: October 2025 — data after 2025-10-22 was lost
-- `legacy.db` preserves history up to 2025-10-22; web + CLI export available
diff --git a/docs/development.md b/docs/development.md
index 7010118..5423446 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -4,6 +4,10 @@ This is the **index** for internal development knowledge. It is `@`-imported int
 so the routing table below is always in context — use it to find the right reference before
 starting work. Keep this file short; put detail in `docs/dev/*.md`.
 
+Most code conventions are **not** listed here: they live in `.claude/rules/*.md` with `paths:`
+frontmatter and load by themselves when you open a matching file (Python, tests, e2e, the web
+layer, docs, hooks). The table below carries only what no file pattern can trigger.
+
 ## Setup
 
 ```bash
@@ -26,15 +30,13 @@ Read the matching reference **before** implementing or debugging in that area.
 |-------------|------|
 | Crawler reference (metadata schema, login types, return format, templates, HTML parsing, SSL, license, archived rules) | [`docs/dev/crawlers.md`](dev/crawlers.md) |
 | **Implementing / debugging** a crawler (procedure, decision tree, checklist) | **ojhunt-crawlers** skill |
-| Python style, typing, imports, dependencies (`uv add`) | [`docs/dev/python.md`](dev/python.md) |
-| Tests: pytest conventions, CI scope, page-route tests, markdown doc tests | [`docs/dev/testing.md`](dev/testing.md) |
-| Playwright e2e / visual regression tests | [`docs/dev/e2e.md`](dev/e2e.md) |
-| Web layer: FastAPI app, PDF internals, dev server, env vars, CSS, minimal-JS | [`docs/dev/web.md`](dev/web.md) |
-| Writing docs: what belongs in the README vs `docs/` | [`docs/dev/docs.md`](dev/docs.md) |
-| Claude Code hooks (enforcement rules) | [`docs/dev/hooks.md`](dev/hooks.md) |
+| Dev server: start/stop, ports in worktrees, env vars | [`docs/dev/web.md`](dev/web.md) |
 | Deployment / ops: system fonts, `legacy.db`, PDF preview | [`docs/dev/deployment.md`](dev/deployment.md) |
 | Committing, commit conventions, when to write an ADR | **ojhunt-commit** skill |
-| Where a new piece of knowledge belongs (docs vs skill vs hook vs ADR) | **ojhunt-update-env** skill |
+| Where a new piece of knowledge belongs (rule vs docs vs skill vs hook vs ADR) | **ojhunt-update-env** skill |
+
+A crawler is the one code area still routed by this table rather than by a rule: a new crawler
+starts as a file that does not exist yet, so no `paths:` pattern can fire on it.
 
 User-facing usage docs (not development conventions): [`docs/cli.md`](cli.md),
 [`docs/web.md`](web.md), [`docs/library.md`](library.md) — the last one is generated by

From df98ad91f06eaed89ceb92398fcbfe62a378901d Mon Sep 17 00:00:00 2001
From: Shumin Liu <shumin.liu@tngtech.com>
Date: Fri, 14 Aug 2026 17:27:32 +1000
Subject: [PATCH 4/8] refactor(tests): fold comments into their assert messages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A comment above an assert is invisible when that assert fails; a message
prints. .claude/rules/python.md already says so, but 45 sites across 27 files
predate the rule, which makes it read as optional to anyone skimming the suite.

Most were one of two boilerplate lines repeated across the crawler tests. Those
became messages that state the invariant rather than restating the call —
"solved_list must hold one entry per solved problem" instead of "Check that
solved_list has the correct length". The rest carried real reasoning and moved
into the message verbatim.

This clears the way for a lint rule to enforce the convention repo-wide.
---
 tests/cli/output_test.py          |  5 +++--
 tests/crawlers/aizu_test.py       | 10 ++++++----
 tests/crawlers/atcoder_test.py    |  5 +++--
 tests/crawlers/codechef_test.py   | 10 ++++++----
 tests/crawlers/codeforces_test.py |  5 +++--
 tests/crawlers/codewars_test.py   | 15 +++++++++------
 tests/crawlers/csu_test.py        | 10 ++++++----
 tests/crawlers/hdu_test.py        | 10 ++++++----
 tests/crawlers/leetcode_test.py   |  5 +++--
 tests/crawlers/lightoj_test.py    |  5 +++--
 tests/crawlers/loj_test.py        | 10 ++++++----
 tests/crawlers/luogu_test.py      |  3 +--
 tests/crawlers/nbut_test.py       | 10 ++++++----
 tests/crawlers/nit_test.py        | 15 ++++++++-------
 tests/crawlers/nod_test.py        |  5 +++--
 tests/crawlers/nowcoder_test.py   | 10 ++++++----
 tests/crawlers/poj_test.py        | 10 ++++++----
 tests/crawlers/registry_test.py   |  7 ++++---
 tests/crawlers/sdutoj_test.py     | 10 ++++++----
 tests/crawlers/timus_test.py      | 10 ++++++----
 tests/crawlers/uoj_test.py        | 10 ++++++----
 tests/crawlers/uva_test.py        | 10 ++++++----
 tests/crawlers/vnoj_test.py       |  7 ++++---
 tests/e2e/test_pdf_workflow.py    |  3 +--
 tests/web/api_test.py             | 15 ++++++++-------
 tests/web/pages_test.py           |  5 +++--
 tests/web/pdf_test.py             |  5 +++--
 27 files changed, 131 insertions(+), 94 deletions(-)

diff --git a/tests/cli/output_test.py b/tests/cli/output_test.py
index 72ba851..3545f59 100644
--- a/tests/cli/output_test.py
+++ b/tests/cli/output_test.py
@@ -464,8 +464,9 @@ def test_json_show_problems_ignored(self, capsys):
         ]
         print_report(results, show_problems=True, total_duration=1.0, json_output=True)
         data = json.loads(capsys.readouterr().out)
-        # solved_list is always in JSON regardless of show_problems
-        assert data["results"][0]["solved_list"] == ["1A", "2A"]
+        assert data["results"][0]["solved_list"] == ["1A", "2A"], (
+            "solved_list is always in JSON, regardless of show_problems"
+        )
 
 
 class TestPrintReportShowProblems:
diff --git a/tests/crawlers/aizu_test.py b/tests/crawlers/aizu_test.py
index 7afc167..6c29009 100644
--- a/tests/crawlers/aizu_test.py
+++ b/tests/crawlers/aizu_test.py
@@ -44,8 +44,10 @@ async def test_valid_user(session):
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
-    # Check for known solved problem
-    assert "ALDS1_3_C" in result["solved_list"]
+    assert "ALDS1_3_C" in result["solved_list"], (
+        "a known solved problem must appear in solved_list"
+    )
diff --git a/tests/crawlers/atcoder_test.py b/tests/crawlers/atcoder_test.py
index 5b2b1ee..42fc924 100644
--- a/tests/crawlers/atcoder_test.py
+++ b/tests/crawlers/atcoder_test.py
@@ -45,5 +45,6 @@ async def test_valid_user(session):
     assert result["solved"] > 0
     assert result["submissions"] > 0
 
-    # AtCoder only returns AC count, so submissions == solved
-    assert result["submissions"] == result["solved"]
+    assert result["submissions"] == result["solved"], (
+        "AtCoder reports only an AC count, so submissions equals solved"
+    )
diff --git a/tests/crawlers/codechef_test.py b/tests/crawlers/codechef_test.py
index dd6ada2..6f562f8 100644
--- a/tests/crawlers/codechef_test.py
+++ b/tests/crawlers/codechef_test.py
@@ -44,8 +44,10 @@ async def test_valid_user(session):
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
-    # Check for known solved problem
-    assert "KGOOD" in result["solved_list"]
+    assert "KGOOD" in result["solved_list"], (
+        "a known solved problem must appear in solved_list"
+    )
diff --git a/tests/crawlers/codeforces_test.py b/tests/crawlers/codeforces_test.py
index be301a5..89fc30f 100644
--- a/tests/crawlers/codeforces_test.py
+++ b/tests/crawlers/codeforces_test.py
@@ -45,8 +45,9 @@ async def test_valid_user(session):
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
     # Check for known solved problems
     expected_problems = {
diff --git a/tests/crawlers/codewars_test.py b/tests/crawlers/codewars_test.py
index 627fbca..851c4cd 100644
--- a/tests/crawlers/codewars_test.py
+++ b/tests/crawlers/codewars_test.py
@@ -43,11 +43,14 @@ async def test_valid_user(session):
     assert result["solved"] > 0
     assert result["submissions"] > 0
 
-    # Codewars only returns completed kata count, so submissions == solved
-    assert result["submissions"] == result["solved"]
+    assert result["submissions"] == result["solved"], (
+        "Codewars reports only completed kata, so submissions equals solved"
+    )
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
-    # Check for known solved problem
-    assert "equal-sides-of-an-array" in result["solved_list"]
+    assert "equal-sides-of-an-array" in result["solved_list"], (
+        "a known solved problem must appear in solved_list"
+    )
diff --git a/tests/crawlers/csu_test.py b/tests/crawlers/csu_test.py
index d0f1607..debd99c 100644
--- a/tests/crawlers/csu_test.py
+++ b/tests/crawlers/csu_test.py
@@ -44,8 +44,10 @@ async def test_valid_user(session):
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
-    # Check for known solved problem
-    assert "1001" in result["solved_list"]
+    assert "1001" in result["solved_list"], (
+        "a known solved problem must appear in solved_list"
+    )
diff --git a/tests/crawlers/hdu_test.py b/tests/crawlers/hdu_test.py
index 57f6819..8da28b0 100644
--- a/tests/crawlers/hdu_test.py
+++ b/tests/crawlers/hdu_test.py
@@ -43,8 +43,10 @@ async def test_valid_user(session):
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
-    # Check for known solved problem
-    assert "1001" in result["solved_list"]
+    assert "1001" in result["solved_list"], (
+        "a known solved problem must appear in solved_list"
+    )
diff --git a/tests/crawlers/leetcode_test.py b/tests/crawlers/leetcode_test.py
index 100dbef..86fe6f6 100644
--- a/tests/crawlers/leetcode_test.py
+++ b/tests/crawlers/leetcode_test.py
@@ -41,5 +41,6 @@ async def test_valid_user(session):
     assert result["solved"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # LeetCode does not expose the full solved list publicly
-    assert result["solved_list"] is None
+    assert result["solved_list"] is None, (
+        "LeetCode does not expose the full solved list publicly"
+    )
diff --git a/tests/crawlers/lightoj_test.py b/tests/crawlers/lightoj_test.py
index 1270650..72d6028 100644
--- a/tests/crawlers/lightoj_test.py
+++ b/tests/crawlers/lightoj_test.py
@@ -34,5 +34,6 @@ async def test_valid_user(session):
 
     assert result["solved"] > 0
     assert result["submissions"] >= result["solved"]
-    # solved_list is not available without authentication
-    assert result["solved_list"] is None
+    assert result["solved_list"] is None, (
+        "solved_list is unavailable without authentication"
+    )
diff --git a/tests/crawlers/loj_test.py b/tests/crawlers/loj_test.py
index 808c18e..c6e5344 100644
--- a/tests/crawlers/loj_test.py
+++ b/tests/crawlers/loj_test.py
@@ -37,8 +37,10 @@ async def test_valid_user(session):
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
-    # Check for known solved problem
-    assert "103" in result["solved_list"]
+    assert "103" in result["solved_list"], (
+        "a known solved problem must appear in solved_list"
+    )
diff --git a/tests/crawlers/luogu_test.py b/tests/crawlers/luogu_test.py
index fd1cc0d..c10bd5d 100644
--- a/tests/crawlers/luogu_test.py
+++ b/tests/crawlers/luogu_test.py
@@ -47,8 +47,7 @@ async def test_valid_user(session):
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # This user should have more than 100 solved problems
-    assert result["solved"] > 100
+    assert result["solved"] > 100, "the test user has solved more than 100 problems"
 
 
 @pytest.mark.asyncio
diff --git a/tests/crawlers/nbut_test.py b/tests/crawlers/nbut_test.py
index f8ae773..6c30b6b 100644
--- a/tests/crawlers/nbut_test.py
+++ b/tests/crawlers/nbut_test.py
@@ -44,8 +44,10 @@ async def test_valid_user(session):
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
-    # Check for known solved problem
-    assert "1010" in result["solved_list"]
+    assert "1010" in result["solved_list"], (
+        "a known solved problem must appear in solved_list"
+    )
diff --git a/tests/crawlers/nit_test.py b/tests/crawlers/nit_test.py
index 862fbe3..81de4ea 100644
--- a/tests/crawlers/nit_test.py
+++ b/tests/crawlers/nit_test.py
@@ -68,12 +68,13 @@ async def test_valid_user(session):
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # solved_list contains unique problems solved on NIT
-    # Note: solved count from page may differ from unique problems in solved_list
-    assert len(result["solved_list"]) > 0
+    assert len(result["solved_list"]) > 0, (
+        "solved_list holds the unique problems solved on NIT, and its length can "
+        "differ from the count the profile page reports"
+    )
     assert len(result["solved_list"]) <= result["solved"]
 
-    # Check for known solved problems (NIT includes problems from other OJs)
-    assert "nit-100" in result["solved_list"]
-    # NIT problem ID 2097 maps to HDU-2181
-    assert "hdu-2181" in result["solved_list"]
+    assert "nit-100" in result["solved_list"], (
+        "NIT lists problems from other judges alongside its own"
+    )
+    assert "hdu-2181" in result["solved_list"], "NIT problem 2097 maps to hdu-2181"
diff --git a/tests/crawlers/nod_test.py b/tests/crawlers/nod_test.py
index 4eaffa2..4989ab2 100644
--- a/tests/crawlers/nod_test.py
+++ b/tests/crawlers/nod_test.py
@@ -36,5 +36,6 @@ async def test_valid_user(session):
     assert result["solved"] > 0
     assert result["submissions"] >= result["solved"]
     assert isinstance(result["solved_list"], list)
-    # 51Nod may have 1 problem outside standard ProblemTables collections
-    assert len(result["solved_list"]) >= result["solved"] - 1
+    assert len(result["solved_list"]) >= result["solved"] - 1, (
+        "51Nod can hold one problem outside the standard ProblemTables collections"
+    )
diff --git a/tests/crawlers/nowcoder_test.py b/tests/crawlers/nowcoder_test.py
index 672a3a4..4ff5a9b 100644
--- a/tests/crawlers/nowcoder_test.py
+++ b/tests/crawlers/nowcoder_test.py
@@ -53,8 +53,10 @@ async def test_valid_user(session):
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
-    # Check for known solved problem
-    assert "16632" in result["solved_list"]
+    assert "16632" in result["solved_list"], (
+        "a known solved problem must appear in solved_list"
+    )
diff --git a/tests/crawlers/poj_test.py b/tests/crawlers/poj_test.py
index a7bfb45..91cfaeb 100644
--- a/tests/crawlers/poj_test.py
+++ b/tests/crawlers/poj_test.py
@@ -44,8 +44,10 @@ async def test_valid_user(session):
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
-    # Check for known solved problem
-    assert "1001" in result["solved_list"]
+    assert "1001" in result["solved_list"], (
+        "a known solved problem must appear in solved_list"
+    )
diff --git a/tests/crawlers/registry_test.py b/tests/crawlers/registry_test.py
index 3c6a822..a3e38af 100644
--- a/tests/crawlers/registry_test.py
+++ b/tests/crawlers/registry_test.py
@@ -64,6 +64,7 @@ def test_importing_one_crawler_does_not_discover_the_rest():
 def test_accessing_crawlers_discovers_them_all():
     imported = _crawlers_imported_by("from ojhunt.crawlers import crawlers")
 
-    # >=, not ==: _discover() imports every module in the package, and one need
-    # not carry __crawler_meta__ to be imported.
-    assert imported >= len(crawler_registry)
+    assert imported >= len(crawler_registry), (
+        "_discover() imports every module in the package, and a module need not "
+        "carry __crawler_meta__ to be imported — hence >=, not =="
+    )
diff --git a/tests/crawlers/sdutoj_test.py b/tests/crawlers/sdutoj_test.py
index f7d829a..0b6e87d 100644
--- a/tests/crawlers/sdutoj_test.py
+++ b/tests/crawlers/sdutoj_test.py
@@ -43,8 +43,10 @@ async def test_valid_user(session):
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
-    # Check for known solved problem
-    assert "1000" in result["solved_list"]
+    assert "1000" in result["solved_list"], (
+        "a known solved problem must appear in solved_list"
+    )
diff --git a/tests/crawlers/timus_test.py b/tests/crawlers/timus_test.py
index e0ba5c2..d3abdbd 100644
--- a/tests/crawlers/timus_test.py
+++ b/tests/crawlers/timus_test.py
@@ -43,8 +43,10 @@ async def test_valid_user(session):
     assert result["submissions"] > 10  # Specific assertion from test.js
     assert result["submissions"] >= result["solved"]
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
-    # Check for known solved problem
-    assert "1387" in result["solved_list"]
+    assert "1387" in result["solved_list"], (
+        "a known solved problem must appear in solved_list"
+    )
diff --git a/tests/crawlers/uoj_test.py b/tests/crawlers/uoj_test.py
index 9d73864..b42ef13 100644
--- a/tests/crawlers/uoj_test.py
+++ b/tests/crawlers/uoj_test.py
@@ -43,8 +43,10 @@ async def test_valid_user(session):
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
-    # Check for known solved problem
-    assert "30" in result["solved_list"]
+    assert "30" in result["solved_list"], (
+        "a known solved problem must appear in solved_list"
+    )
diff --git a/tests/crawlers/uva_test.py b/tests/crawlers/uva_test.py
index ed0a63a..f6e9be8 100644
--- a/tests/crawlers/uva_test.py
+++ b/tests/crawlers/uva_test.py
@@ -43,8 +43,10 @@ async def test_valid_user(session):
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
-    # Check that solved_list contains valid problem labels
-    assert all(isinstance(p, str) for p in result["solved_list"])
+    assert all(isinstance(p, str) for p in result["solved_list"]), (
+        "every solved_list entry must be a problem label string"
+    )
diff --git a/tests/crawlers/vnoj_test.py b/tests/crawlers/vnoj_test.py
index e911e50..5282719 100644
--- a/tests/crawlers/vnoj_test.py
+++ b/tests/crawlers/vnoj_test.py
@@ -37,8 +37,9 @@ async def test_valid_user(session):
 
     assert isinstance(result["solved"], int)
     assert result["submissions"] == result["solved"], "no total published (ADR 0015)"
-    # VNOJ's API and per-user solved-list page are disabled; only the profile
-    # page count remains, so solved_list is unavailable.
-    assert result["solved_list"] is None
+    assert result["solved_list"] is None, (
+        "VNOJ disabled its API and per-user solved-list page; only the profile "
+        "page count remains"
+    )
 
     assert result["solved"] > 0
diff --git a/tests/e2e/test_pdf_workflow.py b/tests/e2e/test_pdf_workflow.py
index a229e49..42dfc9b 100644
--- a/tests/e2e/test_pdf_workflow.py
+++ b/tests/e2e/test_pdf_workflow.py
@@ -376,9 +376,8 @@ def test_upload_historical_pdf_entries_preserved_in_new_download(
     assert "2020-01-01" in keys, f"Old history entry missing; got keys: {keys}"
     assert "2020-01-02" in keys
     assert "2020-01-03" in keys
-    # And at least one entry from ~2026 (today) was added
     assert any(k.startswith("202") and k > "2020" for k in keys), (
-        f"No recent entry found; keys: {keys}"
+        f"today's run must add an entry of its own; keys: {keys}"
     )
 
 
diff --git a/tests/web/api_test.py b/tests/web/api_test.py
index d6e4d7d..12475cf 100644
--- a/tests/web/api_test.py
+++ b/tests/web/api_test.py
@@ -130,9 +130,10 @@ def test_to_model_unknown_crawler():
     )
     core = dto.to_model()
 
-    # Unknown crawler falls back to NullCrawler; result is still considered
-    # successful so its problems are included in merge (prefixed with crawler name)
-    assert core.success is True
+    assert core.success is True, (
+        "an unknown crawler falls back to NullCrawler but still counts as a success, "
+        "so its problems reach the merge under a crawler-name prefix"
+    )
     assert isinstance(core.crawler, NullCrawler)
     assert core.solved_list == ["1A"]
 
@@ -185,11 +186,11 @@ def test_list_crawlers_defaults_to_waiting():
     data = response.json()["data"]
     assert "codeforces" in data
     cf = data["codeforces"]
-    # Existing metadata fields are preserved alongside the new status fields.
-    assert "title" in cf
+    assert "title" in cf, "existing metadata survives alongside the status fields"
     assert "isAggregator" in cf
-    # Checker hasn't run under TestClient → default status, no error.
-    assert cf["status"] == "waiting"
+    assert cf["status"] == "waiting", (
+        "the checker does not run under TestClient, so status stays at its default"
+    )
     assert cf["statusError"] is None
 
 
diff --git a/tests/web/pages_test.py b/tests/web/pages_test.py
index 78b76a6..72a85f5 100644
--- a/tests/web/pages_test.py
+++ b/tests/web/pages_test.py
@@ -250,8 +250,9 @@ def test_security_headers_present_on_page():
     assert "default-src 'self'" in csp
     assert "frame-ancestors 'none'" in csp
     assert "upgrade-insecure-requests" in csp
-    # ReDoc spawns a blob: web worker; the worker-src directive must allow it.
-    assert "worker-src 'self' blob:" in csp
+    assert "worker-src 'self' blob:" in csp, (
+        "ReDoc spawns a blob: web worker, so worker-src must allow it"
+    )
 
 
 # ---------------------------------------------------------------------------
diff --git a/tests/web/pdf_test.py b/tests/web/pdf_test.py
index 11ffa1a..246d165 100644
--- a/tests/web/pdf_test.py
+++ b/tests/web/pdf_test.py
@@ -306,8 +306,9 @@ def test_api_generate_merges_previous_pdf():
 
     r3 = _extract(pdf2)
     assert r3.status_code == 200
-    # report_date should be the most recent entry (date from r2 since it ran after r1)
-    assert r3.json()["report_date"] is not None
+    assert r3.json()["report_date"] is not None, (
+        "report_date carries the most recent entry, which is r2 — it ran after r1"
+    )
     # Both day keys must appear in embedded history
     extracted = extract_data(pdf2)
     keys = {e.key for e in extracted.history}

From c774d5329270a0f166252a578f437a5790817a22 Mon Sep 17 00:00:00 2001
From: Shumin Liu <shumin.liu@tngtech.com>
Date: Fri, 14 Aug 2026 18:10:19 +1000
Subject: [PATCH 5/8] build(lint): replace the shell check with a tested lint
 rule

The comment-above-assert check was an awk program inside
format-lint-python.sh. Being line-based it could not tell code from a string
literal, so it flagged the example snippets inside the very test file that
documents the rule. It also read the edit payload rather than the file, purely
to route around violations that already existed in the suite.

Rules now live in lint/rules/. ./doit.sh lint runs them over the repo and the
hook runs the same files over the one file that changed, so the two cannot
disagree.

This rule is Python, not ast-grep YAML, because it needs source position. A
trailing comment and an own-line comment are the same shape in the parse tree,
and the YAML version reported one violation three different ways depending on
what came after it: the line below when another assert followed, nothing at all
when a non-assert followed or the body ended, and a false positive when the
trailing comment belonged to an assignment. sgconfig.yml and lint/rule-tests/
stay for rules that are purely structural, where YAML reads better than code.

tests/lint/ pins which line each case is blamed on, including the cases that
must stay silent. rules_are_tested_test.py discovers rules from the directory
and fails when one ships without tests, so this is not a convention to
remember. ./doit.sh lint-rules joins full-check.

The parser-based rule found four trailing comments the line-based one missed;
those are folded into their assert messages.
---
 .claude/hooks/format-lint-python.sh       |  27 ++--
 .claude/rules/hooks.md                    |  13 +-
 .claude/rules/lint-rules.md               |  51 +++++++
 .claude/rules/python.md                   |   5 +-
 .claude/skills/ojhunt-update-env/SKILL.md |   7 +-
 doit.sh                                   |  46 +++++-
 lint/rule-tests/.gitkeep                  |   0
 lint/rules/comment_above_assert.py        | 109 +++++++++++++
 pyproject.toml                            |   2 +
 sgconfig.yml                              |   4 +
 tests/crawlers/atcoder_test.py            |   6 +-
 tests/crawlers/luogu_test.py              |   4 +-
 tests/crawlers/timus_test.py              |   2 +-
 tests/lint/comment_above_assert_test.py   | 177 ++++++++++++++++++++++
 tests/lint/rules_are_tested_test.py       |  41 +++++
 uv.lock                                   |  45 ++++++
 16 files changed, 500 insertions(+), 39 deletions(-)
 create mode 100644 .claude/rules/lint-rules.md
 create mode 100644 lint/rule-tests/.gitkeep
 create mode 100644 lint/rules/comment_above_assert.py
 create mode 100644 sgconfig.yml
 create mode 100644 tests/lint/comment_above_assert_test.py
 create mode 100644 tests/lint/rules_are_tested_test.py

diff --git a/.claude/hooks/format-lint-python.sh b/.claude/hooks/format-lint-python.sh
index 08556cc..9bf3775 100644
--- a/.claude/hooks/format-lint-python.sh
+++ b/.claude/hooks/format-lint-python.sh
@@ -11,21 +11,16 @@ elif command -v ruff &>/dev/null; then
     ruff check --fix "$FILE" 2>/dev/null || true
 fi
 
-# In tests the explanation belongs in the assert message, not in a comment above it
-# (.claude/rules/python.md). Ruff has no rule for this, and it is a one-line pattern.
-# Only the text this edit introduced is scanned: the suite still carries older comments,
-# and flagging those would fire on every unrelated edit until someone cleaned them up.
-if [[ "$FILE" == *_test.py || "$FILE" == */tests/* ]]; then
-    ADDED=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // ""' 2>/dev/null)
-    HITS=$(printf '%s\n' "$ADDED" | awk '
-        /^[[:space:]]*#/ { comment = 1; text = $0; next }
-        /^[[:space:]]*assert[[:space:](]/ { if (comment) print text }
-        { comment = 0 }
-    ')
-    if [[ -n "$HITS" ]]; then
-        echo "$FILE: this edit puts a comment directly above an assert. Move the explanation into the assert message (see .claude/rules/python.md):" >&2
-        echo "$HITS" >&2
-        exit 2
-    fi
+# The project's own rules (lint/rules/), on the one file that just changed. Same
+# rules ./doit.sh lint runs over everything, so the hook cannot drift from CI.
+command -v uv &>/dev/null || exit 0
+FAILURES=""
+for RULE in lint/rules/*.py; do
+    [ -e "$RULE" ] || continue
+    OUTPUT=$(uv run python "$RULE" "$FILE" 2>&1) || FAILURES+="$OUTPUT"$'\n'
+done
+if [[ -n "$FAILURES" ]]; then
+    printf '%s\n' "$FAILURES" >&2
+    exit 2
 fi
 exit 0
diff --git a/.claude/rules/hooks.md b/.claude/rules/hooks.md
index d6ce289..a0f0981 100644
--- a/.claude/rules/hooks.md
+++ b/.claude/rules/hooks.md
@@ -6,19 +6,20 @@ paths:
 
 # Project hooks
 
-Hooks enforce constraints mechanically. Check `.claude/settings.json` to see
-what's currently active.
+Hooks decide *when* a check runs. Check `.claude/settings.json` to see what is currently
+active.
 
 ## Location
 
 Scripts live in `.claude/hooks/`, wired in `.claude/settings.json` (checked
 into git — not `settings.local.json`, not `~/.claude/`).
 
-## Write a check only when it is cheap and deterministic
+## Keep the check out of the hook
 
-A hook earns its place when the rule is a one-line pattern with an unambiguous fix. If the
-check needs judgement, a rule under `.claude/rules/` states the convention instead — a noisy
-hook trains everyone to ignore it.
+`format-lint-python.sh` runs ruff and then every rule in `lint/rules/` over the file that
+changed. What each rule checks is defined there, not here, so the hook and `./doit.sh lint`
+can never disagree. Adding a check to the hook alone gives you a rule that CI does not run and
+nobody can test — write it in `lint/rules/` instead (see `.claude/rules/lint-rules.md`).
 
 ## Regex gotcha for command bans
 
diff --git a/.claude/rules/lint-rules.md b/.claude/rules/lint-rules.md
new file mode 100644
index 0000000..efca82f
--- /dev/null
+++ b/.claude/rules/lint-rules.md
@@ -0,0 +1,51 @@
+---
+paths:
+  - "lint/**"
+  - "tests/lint/**"
+---
+
+# Project lint rules
+
+Rules the project enforces on its own code, beyond what ruff covers. They live in
+`lint/rules/`, run from `./doit.sh lint`, and run again from the edit-time hook on the single
+file that changed — one definition, so the hook cannot drift from CI.
+
+```bash
+./doit.sh lint          # every rule over the whole repo
+./doit.sh lint-rules    # the rules' own tests
+uv run python lint/rules/<rule>.py <file>...   # one rule, one file
+```
+
+## When a convention earns a rule
+
+A rule pays for itself when the convention is objective and somebody will break it without
+noticing. If judging a case needs context the parser does not have, leave the convention in
+`.claude/rules/*.md` as prose — a rule that misfires teaches everyone to ignore it.
+
+Before writing prose, check whether a rule can assert it instead: a rule fails when somebody
+breaks the convention, a paragraph does not.
+
+## Pick the form
+
+| Form | Use when | Tests |
+|------|----------|-------|
+| `lint/rules/<id>.yml` | The match is purely structural — a node shape, nesting, a pattern | `lint/rule-tests/<id>-test.yml` |
+| `lint/rules/<id>.py` | The match needs source position, file paths, or cross-file state | `tests/lint/<id>_test.py` |
+
+Position is the usual reason to reach for Python. A YAML rule sees the parse tree, where a
+trailing comment and an own-line comment are the same shape; only line and column separate
+them. `comment_above_assert.py` exists for exactly that reason — its docstring says so.
+
+A Python rule is a script: `find_violations(source, path)` for tests to call, and a `main()`
+that takes file arguments, prints to stderr and returns 1 on a finding. Copy the shape from
+`lint/rules/comment_above_assert.py`.
+
+For ast-grep's rule syntax, node kinds and relational operators, query the ast-grep
+documentation through Context7 rather than looking for it here.
+
+## Every rule ships with its tests
+
+`tests/lint/rules_are_tested_test.py` fails when a rule has no test file, so this is not a
+convention you can forget. Cover the edge cases, not just the happy path — for anything
+position-sensitive, pin **which line** each case is blamed on, and include the cases that must
+stay silent.
diff --git a/.claude/rules/python.md b/.claude/rules/python.md
index e48cbd6..238eaa3 100644
--- a/.claude/rules/python.md
+++ b/.claude/rules/python.md
@@ -51,8 +51,9 @@ Asserts are for what the code guarantees itself. Data arriving from outside —
 argument, a judge's response — needs a real `raise`, because `python -O` strips asserts.
 
 In tests, put the explanation in the assert message, not in a comment above it:
-`assert "items" in listed, "dict's own attributes must survive"`.
-`format-lint-python.sh` flags a comment that sits directly above an `assert`.
+`assert "items" in listed, "dict's own attributes must survive"`. This is enforced —
+`lint/rules/comment_above_assert.py` flags a comment beside an `assert`, whether it sits
+above the line or trails it.
 
 Where a comment would explain *what* an expression produces, name the value instead:
 `single_line_description = " ".join(text.split())`.
diff --git a/.claude/skills/ojhunt-update-env/SKILL.md b/.claude/skills/ojhunt-update-env/SKILL.md
index 3f9fa09..afd0e48 100644
--- a/.claude/skills/ojhunt-update-env/SKILL.md
+++ b/.claude/skills/ojhunt-update-env/SKILL.md
@@ -56,6 +56,8 @@ Conventions for editing a kind of file. Each carries `paths:` frontmatter and lo
 - `web.md` — `src/ojhunt/web/**`: PDF internals, minimal-JS, CSS, FastAPI gotchas
 - `docs.md` — `docs/**`, `README.md`, `.claude/**`: what to write and what to leave out
 - `hooks.md` — `.claude/hooks/**`, `.claude/settings.json`: hook wiring and the regex gotcha
+- `lint-rules.md` — `lint/**`, `tests/lint/**`: when a convention earns a lint rule, which
+  form it takes (YAML or Python), and the requirement that every rule ships with tests
 
 A rule is not a place to dump reference material: it costs context every time a matching file
 is opened. Keep each one to conventions somebody could get wrong.
@@ -164,8 +166,9 @@ not here.
 - Development convention, style, schema, or gotcha for a code area → `docs/dev/<area>.md`
   (add a routing-table row in `docs/development.md` if the domain is new)
 - Workflow or process (a procedure run on demand) → `.claude/skills/ojhunt-*/`
-- "Never do X" or "always do Y after Z" → **hook first** (see `.claude/rules/hooks.md`); once
-  hook-enforced, do NOT also add a doc/skill entry — the hook is the enforcement, a note just
+- "Never do X" or "always do Y after Z" → a **lint rule** in `lint/rules/` when a parser can
+  judge it (see `.claude/rules/lint-rules.md`), wired by a hook (`.claude/rules/hooks.md`);
+  once enforced, do NOT also add a doc/skill entry — the rule is the enforcement, a note just
   creates drift
 - Project-level command override → `.claude/commands/`
 - Significant architectural decision (multiple approaches considered, choice non-obvious from code) → `docs/adr/`
diff --git a/doit.sh b/doit.sh
index 93b6590..001bfd3 100755
--- a/doit.sh
+++ b/doit.sh
@@ -205,15 +205,45 @@ status() {
 logs() { tail -F "$SERVER_LOG"; }
 
 lint() {
-  run_logged lint _ruff_check_and_format
+  run_logged lint _lint_all
 }
 
-# Both ruff passes always run, so one report lists every problem. Ruff 0.16 also
+# Every pass always runs, so one report lists every problem. Ruff 0.16 also
 # formats python blocks inside markdown, which `ruff check` alone does not see.
-_ruff_check_and_format() {
+# The project's own rules live in lint/rules/ — see .claude/rules/hooks.md.
+_lint_all() {
   local status=0
   uv run ruff check . || status=1
   uv run ruff format --check . || status=1
+  _project_lint_rules || status=1
+  return "$status"
+}
+
+# Python rules take the files to scan; each falls back to its own default scope.
+_project_lint_rules() {  # _project_lint_rules [file...]
+  local status=0 rule
+  for rule in lint/rules/*.py; do
+    [ -e "$rule" ] || continue
+    uv run python "$rule" "$@" || status=1
+  done
+  if compgen -G "lint/rules/*.yml" >/dev/null; then
+    uv run ast-grep scan "$@" || status=1
+  fi
+  return "$status"
+}
+
+# Tests for the rules themselves: pytest for the python ones, `ast-grep test`
+# for the yaml ones. tests/lint/ also fails when a rule has no tests at all.
+lint-rules() {
+  run_logged lint-rules _lint_rules_tests
+}
+
+_lint_rules_tests() {
+  local status=0
+  uv run pytest tests/lint -q || status=1
+  if compgen -G "lint/rules/*.yml" >/dev/null; then
+    uv run ast-grep test || status=1
+  fi
   return "$status"
 }
 
@@ -265,7 +295,7 @@ update-snapshots() {
 }
 
 full-check() {
-  # Full pre-commit gate: lint + every test suite (incl. visual) against a live
+  # Full pre-commit gate: lint + rule tests + every test suite (incl. visual) against a live
   # server. We own the server lifecycle so callers don't have to: start it once,
   # run everything, then stop it — but only if *we* started it, so a dev server
   # you left running with `./doit.sh start` survives.
@@ -278,13 +308,14 @@ full-check() {
   # function returns, where the local no longer exists and `set -u` would abort.
   trap "[[ $started_here == 1 ]] && kill" EXIT
   start
-  # Run all four to completion and collect failures rather than aborting on the
+  # Run every step to completion and collect failures rather than aborting on the
   # first — one run should surface every problem. `set +e` because these commands
   # are expected to fail sometimes and we handle the codes ourselves; each task
   # already tees its full output to .doit/<task>.log via run_logged.
   local -a failed=()
   set +e
   lint        || failed+=("lint")
+  lint-rules  || failed+=("lint-rules")
   test-unit   || failed+=("test-unit")
   test-e2e    || failed+=("test-e2e")
   test-visual || failed+=("test-visual")
@@ -293,7 +324,7 @@ full-check() {
     echo "full-check FAILED: ${failed[*]} — read .doit/<task>.log for details"
     return 1
   fi
-  echo "full-check PASSED (lint, test-unit, test-e2e, test-visual)"
+  echo "full-check PASSED (lint, lint-rules, test-unit, test-e2e, test-visual)"
 }
 
 help() {
@@ -309,7 +340,8 @@ Server:
   reap               kill orphaned servers whose git worktree has been removed
 
 Tests:
-  lint               run ruff linter and formatter check
+  lint               run ruff (linter + formatter check) and the rules in lint/rules/
+  lint-rules         test the lint rules themselves (pytest + ast-grep test)
   test-unit          run unit tests (no network, no playwright) [pytest-args...]
   test-e2e           run e2e tests excluding visual (starts server if needed) [pytest-args...]
   test-visual        run visual regression tests (starts server if needed) [pytest-args...]
diff --git a/lint/rule-tests/.gitkeep b/lint/rule-tests/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/lint/rules/comment_above_assert.py b/lint/rules/comment_above_assert.py
new file mode 100644
index 0000000..91732c3
--- /dev/null
+++ b/lint/rules/comment_above_assert.py
@@ -0,0 +1,109 @@
+"""Lint rule: the explanation next to an assert belongs in its message.
+
+A comment is invisible when the assertion fails; a message prints with the
+failure. See `.claude/rules/python.md`.
+
+This rule is Python rather than YAML because it needs source position. A
+trailing comment and an own-line comment are the same shape in the parse tree —
+both are sibling nodes between two statements — so only line and column tell
+them apart. Getting that wrong reports the violation on the innocent line below
+it, or misses it entirely when no assert follows.
+
+Run over the default scope, or over named files:
+
+    uv run python lint/rules/comment_above_assert.py
+    uv run python lint/rules/comment_above_assert.py tests/web/api_test.py
+"""
+
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from ast_grep_py import SgNode, SgRoot
+
+RULE_ID = "comment-above-assert"
+MESSAGE = "move the explanation into the assert message"
+
+NOTE = """\
+A comment is silent when the assert fails; a message prints.
+
+    # the crawler reports only an AC count
+    assert result["submissions"] == result["solved"]
+
+    assert result["submissions"] == result["solved"], (
+        "the crawler reports only an AC count"
+    )
+"""
+
+# Files the rule applies to, relative to the repository root.
+SCOPE = "tests/**/*.py"
+
+
+@dataclass(frozen=True)
+class Finding:
+    path: Path
+    line: int
+    comment: str
+
+    def __str__(self) -> str:
+        return f"{self.path}:{self.line}: {RULE_ID}: {MESSAGE}\n    {self.comment}"
+
+
+def _trailing_statement(comment: SgNode) -> SgNode | None:
+    """The statement this comment trails, or None when it sits on its own line."""
+    previous = comment.prev()
+    if previous is None:
+        return None
+    if previous.range().end.line != comment.range().start.line:
+        return None
+    return previous
+
+
+def _statement_below(comment: SgNode) -> SgNode | None:
+    """The statement this comment sits above.
+
+    A comment before the *first* statement of a body attaches to the enclosing
+    definition instead of the body, so the next sibling is the block itself.
+    """
+    below = comment.next()
+    if below is not None and below.kind() == "block":
+        children = below.children()
+        return children[0] if children else None
+    return below
+
+
+def find_violations(source: str, path: Path) -> list[Finding]:
+    """Every assert in `source` whose explanation sits in a comment."""
+    findings = []
+    for comment in SgRoot(source, "python").root().find_all(kind="comment"):
+        trailed = _trailing_statement(comment)
+        target = trailed if trailed is not None else _statement_below(comment)
+        if target is None or target.kind() != "assert_statement":
+            continue
+        findings.append(
+            Finding(path, target.range().start.line + 1, comment.text().strip())
+        )
+    return findings
+
+
+def scan(paths: list[Path]) -> list[Finding]:
+    findings = []
+    for path in sorted(paths):
+        findings.extend(find_violations(path.read_text(encoding="utf-8"), path))
+    return findings
+
+
+def main(argv: list[str]) -> int:
+    root = Path(__file__).parents[2]
+    paths = [Path(a) for a in argv] if argv else sorted(root.glob(SCOPE))
+    findings = scan(paths)
+    for finding in findings:
+        print(finding, file=sys.stderr)
+    if findings:
+        print(f"\n{NOTE}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
diff --git a/pyproject.toml b/pyproject.toml
index b081e54..fbb8827 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -77,4 +77,6 @@ dev = [
     "pytest-timeout>=2.4.0",
     "pytest-markdown-docs",
     "ruff>=0.15.1",
+    "ast-grep-cli>=0.45.1",
+    "ast-grep-py>=0.45.1",
 ]
diff --git a/sgconfig.yml b/sgconfig.yml
new file mode 100644
index 0000000..ee98e3c
--- /dev/null
+++ b/sgconfig.yml
@@ -0,0 +1,4 @@
+ruleDirs:
+  - lint/rules
+testConfigs:
+  - testDir: lint/rule-tests
diff --git a/tests/crawlers/atcoder_test.py b/tests/crawlers/atcoder_test.py
index 42fc924..4d731a5 100644
--- a/tests/crawlers/atcoder_test.py
+++ b/tests/crawlers/atcoder_test.py
@@ -38,9 +38,9 @@ async def test_valid_user(session):
 
     assert isinstance(result["solved"], int)
     assert isinstance(result["submissions"], int)
-    assert (
-        result["solved_list"] is None
-    )  # kenkoooo API only provides AC count, not problem list
+    assert result["solved_list"] is None, (
+        "the kenkoooo API provides only an AC count, not a problem list"
+    )
 
     assert result["solved"] > 0
     assert result["submissions"] > 0
diff --git a/tests/crawlers/luogu_test.py b/tests/crawlers/luogu_test.py
index c10bd5d..70ac698 100644
--- a/tests/crawlers/luogu_test.py
+++ b/tests/crawlers/luogu_test.py
@@ -41,7 +41,7 @@ async def test_valid_user(session):
 
     assert isinstance(result["solved"], int)
     assert isinstance(result["submissions"], int)
-    assert result["solved_list"] is None  # Luogu no longer exposes solved list
+    assert result["solved_list"] is None, "Luogu no longer exposes the solved list"
 
     assert result["solved"] > 0
     assert result["submissions"] > 0
@@ -62,7 +62,7 @@ async def test_user_with_many_submissions(session):
 
     assert isinstance(result["solved"], int)
     assert isinstance(result["submissions"], int)
-    assert result["solved_list"] is None  # Luogu no longer exposes solved list
+    assert result["solved_list"] is None, "Luogu no longer exposes the solved list"
 
     assert result["solved"] > 0
     assert result["submissions"] > 1000
diff --git a/tests/crawlers/timus_test.py b/tests/crawlers/timus_test.py
index d3abdbd..20a3807 100644
--- a/tests/crawlers/timus_test.py
+++ b/tests/crawlers/timus_test.py
@@ -40,7 +40,7 @@ async def test_valid_user(session):
     assert isinstance(result["solved_list"], list)
 
     assert result["solved"] > 0
-    assert result["submissions"] > 10  # Specific assertion from test.js
+    assert result["submissions"] > 10, "carried over from the original test.js"
     assert result["submissions"] >= result["solved"]
 
     assert len(result["solved_list"]) == result["solved"], (
diff --git a/tests/lint/comment_above_assert_test.py b/tests/lint/comment_above_assert_test.py
new file mode 100644
index 0000000..a1b468d
--- /dev/null
+++ b/tests/lint/comment_above_assert_test.py
@@ -0,0 +1,177 @@
+"""Tests for the comment-above-assert lint rule (lint/rules/comment_above_assert.py).
+
+The edge cases are the point of this file. A trailing comment and an own-line
+comment are indistinguishable in the parse tree, so every case below pins which
+line the rule blames — the earlier YAML version of this rule reported three
+different outcomes for the same violation depending on what followed it.
+"""
+
+import importlib.util
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).parents[2]
+RULE_PATH = REPO_ROOT / "lint" / "rules" / "comment_above_assert.py"
+
+
+def _rule():
+    """Import the rule, which lives outside the package (mirrors docs_test.py)."""
+    spec = importlib.util.spec_from_file_location("comment_above_assert", RULE_PATH)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+rule = _rule()
+
+
+def _lines(source: str) -> list[int]:
+    return [f.line for f in rule.find_violations(source, Path("probe.py"))]
+
+
+# ---------------------------------------------------------------------------
+# Own-line comment above an assert — the case the rule exists for
+# ---------------------------------------------------------------------------
+
+
+def test_own_line_comment_mid_body():
+    source = """
+def test_x():
+    result = query()
+    # the crawler reports only an AC count
+    assert result["submissions"] == result["solved"]
+"""
+    assert _lines(source) == [5], "the assert below an own-line comment is flagged"
+
+
+def test_own_line_comment_as_first_statement():
+    source = """
+def test_x():
+    # the crawler reports only an AC count
+    assert result["submissions"] == result["solved"]
+"""
+    assert _lines(source) == [4], (
+        "a comment before the first statement attaches to the def, not the body — "
+        "the rule must still reach the assert inside the block"
+    )
+
+
+def test_own_line_comment_inside_a_method():
+    source = """
+class TestThing:
+    def test_x(self):
+        # explanation
+        assert value == 1
+"""
+    assert _lines(source) == [5], "nesting depth must not matter"
+
+
+def test_comment_block_reports_once():
+    source = """
+def test_x():
+    imported = discover()
+    # first line of the explanation
+    # second line of the explanation
+    assert imported >= len(registry)
+"""
+    assert _lines(source) == [6], "a multi-line comment block yields one finding"
+
+
+def test_flagged_even_when_the_assert_has_a_message():
+    source = """
+def test_x():
+    value = compute()
+    # this says something the message does not
+    assert value == 1, "value must be one"
+"""
+    assert _lines(source) == [5], "a message does not excuse a comment beside it"
+
+
+# ---------------------------------------------------------------------------
+# Trailing comments — reported on their own line, never on the one below
+# ---------------------------------------------------------------------------
+
+
+def test_trailing_comment_on_an_assert_is_blamed_on_that_assert():
+    source = """
+def test_x():
+    result = query()
+    assert result["solved"] > 0  # the judge under-reports by one
+    assert result["submissions"] > 0
+"""
+    assert _lines(source) == [4], (
+        "line 4 carries the comment; line 5 is innocent and must not be blamed"
+    )
+
+
+@pytest.mark.parametrize(
+    ("what_follows", "description"),
+    [
+        ("", "nothing — the assert ends the body"),
+        ("    cleanup()\n", "a statement that is not an assert"),
+        ("    assert other > 0\n", "another assert"),
+    ],
+)
+def test_trailing_comment_is_caught_whatever_follows(what_follows, description):
+    source = f"""
+def test_x():
+    result = query()
+    assert result["solved"] > 0  # the judge under-reports by one
+{what_follows}"""
+    assert _lines(source) == [4], f"must be caught when followed by {description}"
+
+
+# ---------------------------------------------------------------------------
+# Cases that must stay silent
+# ---------------------------------------------------------------------------
+
+
+def test_trailing_comment_on_a_non_assert_is_ignored():
+    source = """
+def test_x():
+    reset_env()
+    config = load_config()  # defaults come from .env
+    assert config.debug is False
+"""
+    assert _lines(source) == [], (
+        "the comment explains the assignment it sits on, not the assert below it"
+    )
+
+
+def test_comment_above_a_non_assert_is_ignored():
+    source = """
+def test_x():
+    # build the client once
+    client = TestClient(app)
+    assert client is not None
+"""
+    assert _lines(source) == [], "the comment explains the statement it sits above"
+
+
+def test_assert_with_a_message_and_no_comment_is_ignored():
+    source = """
+def test_x():
+    result = query()
+    assert result["solved"] > 0, "the test user has solved something"
+"""
+    assert _lines(source) == []
+
+
+def test_trailing_comment_at_the_end_of_a_body_is_ignored():
+    source = """
+def test_x():
+    assert value == 1
+    # a note that trails the whole body
+"""
+    assert _lines(source) == [], "no statement follows, so nothing is explained"
+
+
+# ---------------------------------------------------------------------------
+# The rule holds over the repository it guards
+# ---------------------------------------------------------------------------
+
+
+def test_repository_is_clean():
+    findings = rule.scan(sorted(REPO_ROOT.glob(rule.SCOPE)))
+    assert findings == [], "\n".join(str(f) for f in findings)
diff --git a/tests/lint/rules_are_tested_test.py b/tests/lint/rules_are_tested_test.py
new file mode 100644
index 0000000..33492d3
--- /dev/null
+++ b/tests/lint/rules_are_tested_test.py
@@ -0,0 +1,41 @@
+"""Every lint rule must ship with its own tests.
+
+Discovered from the directory rather than listed here: a hardcoded list would go
+stale on exactly the rule nobody remembered to add to it.
+"""
+
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).parents[2]
+RULES_DIR = REPO_ROOT / "lint" / "rules"
+YAML_TESTS_DIR = REPO_ROOT / "lint" / "rule-tests"
+PYTHON_TESTS_DIR = Path(__file__).parent
+
+
+def test_every_python_rule_has_a_pytest_file():
+    missing = [
+        rule.name
+        for rule in sorted(RULES_DIR.glob("*.py"))
+        if not (PYTHON_TESTS_DIR / f"{rule.stem}_test.py").exists()
+    ]
+    assert not missing, (
+        f"{missing} have no tests — add tests/lint/<rule>_test.py covering which "
+        "line each case is blamed on"
+    )
+
+
+def test_every_yaml_rule_has_an_ast_grep_test_file():
+    missing = [
+        rule.name
+        for rule in sorted(RULES_DIR.glob("*.yml"))
+        if not (YAML_TESTS_DIR / f"{rule.stem}-test.yml").exists()
+    ]
+    assert not missing, (
+        f"{missing} have no tests — add lint/rule-tests/<rule>-test.yml with valid "
+        "and invalid cases, then run ./doit.sh lint-rules"
+    )
+
+
+def test_at_least_one_rule_exists():
+    rules = list(RULES_DIR.glob("*.py")) + list(RULES_DIR.glob("*.yml"))
+    assert rules, "lint/rules/ is empty — did a rule get deleted by accident?"
diff --git a/uv.lock b/uv.lock
index 3131277..ed44dc4 100644
--- a/uv.lock
+++ b/uv.lock
@@ -160,6 +160,47 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/38/0e/27be9fdef66e72d64c0cdc3cc2823101b80585f8119b5c112c2e8f5f7dab/anyio-4.12.1-py3-none-any.whl", hash = "sha256:d405828884fc140aa80a3c667b8beed277f1dfedec42ba031bd6ac3db606ab6c", size = 113592, upload-time = "2026-01-06T11:45:19.497Z" },
 ]
 
+[[package]]
+name = "ast-grep-cli"
+version = "0.45.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/bd/31/e202db9b63bb2851f48d29c01aa27b74c5b7b36bc6c158f80f6443a7dbfa/ast_grep_cli-0.45.1.tar.gz", hash = "sha256:3b214f39554cb6fd51d0fd441eab9427c7dd8bfb12dbff5ef7618369c6a22628", size = 279952, upload-time = "2026-08-07T15:25:10.762Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/63/2f/5db21c7c3c61f758f0cde8ebbc60e5876d026857ca5a1ca41acb9607b18b/ast_grep_cli-0.45.1-py3-none-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl", hash = "sha256:3536a040aed9d95b29af27d2eea0c831a48ee151afa8de2c6a842b9fc75e8c87", size = 16028194, upload-time = "2026-08-07T15:24:51.186Z" },
+    { url = "https://files.pythonhosted.org/packages/86/52/4cd380e4fc56f8fc5e9d6526b6c353c7802d96b78624ecb49dca6cfe6a86/ast_grep_cli-0.45.1-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:befa0add772663a012d42e22bb28483ecb8558d66634fa364efe09a1c7187542", size = 8007620, upload-time = "2026-08-07T15:24:54.375Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/f8/2bb3e74a50e75b41a34d8f6f8e6d42867b088147a15fb7e73f5cb94d7f7f/ast_grep_cli-0.45.1-py3-none-manylinux_2_28_aarch64.whl", hash = "sha256:80caab89daefa0ddaf69f59f7838e6ff4480fd35daf6ea273fa3055506e992df", size = 7864976, upload-time = "2026-08-07T15:24:56.366Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/3e/193f347a7add7ba413a0f4169cc8185bd58ba0477e6947a683f4887c4872/ast_grep_cli-0.45.1-py3-none-manylinux_2_28_x86_64.whl", hash = "sha256:497810f387e9ab0624f72dd300557fb25a2a49b0429c71472e5d08180f16bdbc", size = 8166938, upload-time = "2026-08-07T15:24:58.593Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/f1/0d04cd5e0a5bdd1c1f1c8f78ec1efab30ad1d585bda207657d125e0613ef/ast_grep_cli-0.45.1-py3-none-win32.whl", hash = "sha256:bfd8aceeb6d6e8623a18a0804d22f9cdc67ad84d7dd1f03c3e8b6a33990189e3", size = 15198061, upload-time = "2026-08-07T15:25:02.014Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/96/5544e348c00381c7526462332dcb56ed1129de3402b0610a100fc683db84/ast_grep_cli-0.45.1-py3-none-win_amd64.whl", hash = "sha256:b3bbcdeb49db5a7942c4687c117c478be8e5eeb4bcfa79851d4154965f6c7402", size = 16177239, upload-time = "2026-08-07T15:25:05.528Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/52/d2644a91e78e876af197a05ff7bd499d2e0c615935f31756ab432cd157df/ast_grep_cli-0.45.1-py3-none-win_arm64.whl", hash = "sha256:0a945ef6495c2ce2e09001e25b81ad14ccbe7afe446467c4d912ac06271c6c13", size = 15566175, upload-time = "2026-08-07T15:25:08.702Z" },
+]
+
+[[package]]
+name = "ast-grep-py"
+version = "0.45.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/29/81/fa716e61d5be8acc7d1da0125cee2e0726307e4289b6410c6a9581d4f703/ast_grep_py-0.45.1.tar.gz", hash = "sha256:444f09a3928d966ee779b1ab9fbce881d4fa9a276c6e9fac6bb1746d2efc5714", size = 155677, upload-time = "2026-08-07T15:28:58.878Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/28/b7/c4f4bb38175eb78fc9f32ce103e2b42d387b6474d846890e1af01c011756/ast_grep_py-0.45.1-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:012b14be02f2683cc63645670359309ab6feed0e1876cc0901f7f6a72f7a8993", size = 5356973, upload-time = "2026-08-07T15:28:27.761Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/2a/b4d68dd42ed47dc26d6a875e23ff4ebf587bb3418ad282434cc5c8669b70/ast_grep_py-0.45.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:9caa33905cb352a62f5178e41c279f6cbe7fbfd8961ca5d76233d36b58f7e041", size = 5531320, upload-time = "2026-08-07T15:28:29.794Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/2a/a55aff6091b75b9bfc9d2cfad6d5dbc17776f4fc3cc671dc8a85a27cacba/ast_grep_py-0.45.1-cp312-cp312-manylinux_2_28_aarch64.whl", hash = "sha256:dc5a35f1bc86daa3d1c79d322e9ec4d4380b6c72c141ce43879ee21856cea77c", size = 5353991, upload-time = "2026-08-07T15:28:31.664Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/00/2db8135f4826d55f3d8efa544521b73c16c176230b4802dcd0c9935cb572/ast_grep_py-0.45.1-cp312-cp312-manylinux_2_28_x86_64.whl", hash = "sha256:b018c762c1fa913d16e3396f06eb5c5f5f48728bd331cdc591880e62be3eb1ba", size = 5468480, upload-time = "2026-08-07T15:28:33.409Z" },
+    { url = "https://files.pythonhosted.org/packages/71/1e/4ee446c30c130e28589a553f4162f343f9c5256e149b16de4bb52465d3ef/ast_grep_py-0.45.1-cp312-cp312-win32.whl", hash = "sha256:357ff96e75fcc241c6f36a30a7178fbaa4c45e320a8cfa69d2dc87c81d148b06", size = 5076686, upload-time = "2026-08-07T15:28:34.93Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/d9/3f99c33b927192a18faca1ecbc6fd6588c4f6bb18c9c114d2bfb4cbd591d/ast_grep_py-0.45.1-cp312-cp312-win_amd64.whl", hash = "sha256:57fafff917a6f26c60d2e53faee7cbfaba9ccc633fdd69eb31a85abbedebf7cb", size = 5208597, upload-time = "2026-08-07T15:28:36.488Z" },
+    { url = "https://files.pythonhosted.org/packages/a4/1b/d7cfef152cd747306d2760a90b24f4913e07b7c84bd308db3f5268e7cec6/ast_grep_py-0.45.1-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:515e0b1d3f1474b0ee136068f343eb500e38ce055652114059c72a5f362998e2", size = 5360319, upload-time = "2026-08-07T15:28:38.075Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/8a/c9b25e40648d6f21c4717d169d566cc4cb44fc215fa18f702b0885648992/ast_grep_py-0.45.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:35b796de0e8c9bc9454b1ef24f07c86bd182e4f80afc66d0bcd188fd88acd20b", size = 5531479, upload-time = "2026-08-07T15:28:39.869Z" },
+    { url = "https://files.pythonhosted.org/packages/c6/08/bc2179ce647429406a3f48cba7d1b93b8b0dc35ac0209af1820d57f77728/ast_grep_py-0.45.1-cp313-cp313-manylinux_2_28_aarch64.whl", hash = "sha256:955d00b7573738d29aa8f1ec889cec87d5802abc0e3b7fd4b2cfd95c066117cf", size = 5349958, upload-time = "2026-08-07T15:28:41.515Z" },
+    { url = "https://files.pythonhosted.org/packages/53/a1/96857476280ce36f21950856eb57def7b92c95583333106003262f7f93cb/ast_grep_py-0.45.1-cp313-cp313-manylinux_2_28_x86_64.whl", hash = "sha256:841ac568f9f4a94155e43e661367e7c55788c599683bb674ab5fe0b5dfcdb977", size = 5467676, upload-time = "2026-08-07T15:28:43.248Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/ea/c2951e0fd740293c82613f6956d3f9dad81eab1d16cdb3da8543c579f994/ast_grep_py-0.45.1-cp313-cp313-win32.whl", hash = "sha256:4c8581b059026ff4c4249751054a5823175db7f303f9a352f69af017177332b4", size = 5070691, upload-time = "2026-08-07T15:28:45.083Z" },
+    { url = "https://files.pythonhosted.org/packages/35/59/3c9a915405a9aef9bf90b706396bf0393a1e1177ab725b90654b0d6fd921/ast_grep_py-0.45.1-cp313-cp313-win_amd64.whl", hash = "sha256:0bfc05f252e99455296bbad4d87043973052d5c29ff5c08b1f7bbf80e81cad57", size = 5207779, upload-time = "2026-08-07T15:28:46.696Z" },
+    { url = "https://files.pythonhosted.org/packages/e6/19/3157219288b8135cfaeb51cb5a8a3d26cab3adc7484ac13be6aeb0d41915/ast_grep_py-0.45.1-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:48cc4d872ea5f7d60c55e7d19fc795d4e8ede156f675e87245c87efa94889993", size = 5358480, upload-time = "2026-08-07T15:28:48.308Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/c1/af430c2cc01e8f527da258f02e8b06fd7af0d8a9ef8cb181b99bd36049d8/ast_grep_py-0.45.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:0f296c015d618ab41840b4e08db5ba3618ed4e1739f7797002d5b00c64ad2aae", size = 5531104, upload-time = "2026-08-07T15:28:49.933Z" },
+    { url = "https://files.pythonhosted.org/packages/49/bd/4b6ababea21ec5d4a56c86b56959849f8cd5bdfbdc839279521c2be14a5c/ast_grep_py-0.45.1-cp314-cp314-manylinux_2_28_aarch64.whl", hash = "sha256:2534c6d8035fa2397fa7abe1b0b7c9c8ad6a69b57b0316828da2f5f92b41411c", size = 5349994, upload-time = "2026-08-07T15:28:51.601Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/f8/d603657858079fe9c856a23ce543da799c6e265d86e8b7731e6bd8c22531/ast_grep_py-0.45.1-cp314-cp314-manylinux_2_28_x86_64.whl", hash = "sha256:7b1ac42d8872059abe794fd0005a3ba6ebae72c2db72422765a376c56bdaac35", size = 5468660, upload-time = "2026-08-07T15:28:53.773Z" },
+    { url = "https://files.pythonhosted.org/packages/39/fd/26ed2b048fcdd1d81f6da21aa152215e03b390303b0c70c2b96e4108da46/ast_grep_py-0.45.1-cp314-cp314-win32.whl", hash = "sha256:c1c2cf472ef657e6aa3a57f1a7d824d790320a97d0c1245a5b8b060288d1f690", size = 5074686, upload-time = "2026-08-07T15:28:55.405Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/26/b34feb7f35f6d13e5244f67f526b87946e107d9d2ca7b534e927d06bf2b2/ast_grep_py-0.45.1-cp314-cp314-win_amd64.whl", hash = "sha256:00d89d7ae157f18319f897b9779cc449b2e97be4ccb7fc489ed6e41f6436b27f", size = 5207281, upload-time = "2026-08-07T15:28:57.077Z" },
+]
+
 [[package]]
 name = "attrs"
 version = "25.4.0"
@@ -1226,6 +1267,8 @@ dependencies = [
 
 [package.dev-dependencies]
 dev = [
+    { name = "ast-grep-cli" },
+    { name = "ast-grep-py" },
     { name = "hatchling" },
     { name = "pytest" },
     { name = "pytest-asyncio" },
@@ -1251,6 +1294,8 @@ requires-dist = [
 
 [package.metadata.requires-dev]
 dev = [
+    { name = "ast-grep-cli", specifier = ">=0.45.1" },
+    { name = "ast-grep-py", specifier = ">=0.45.1" },
     { name = "hatchling", specifier = ">=1.29.0" },
     { name = "pytest", specifier = ">=9.0.2" },
     { name = "pytest-asyncio", specifier = ">=1.3.0" },

From 3d445da76ee78a6389a8af4dcaf90073bc1c56cb Mon Sep 17 00:00:00 2001
From: Shumin Liu <shumin.liu@tngtech.com>
Date: Fri, 14 Aug 2026 20:39:12 +1000
Subject: [PATCH 6/8] fixup! feat(web): describe each page for search engines

---
 src/ojhunt/web/pages.py | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/src/ojhunt/web/pages.py b/src/ojhunt/web/pages.py
index 6468567..a0e0761 100644
--- a/src/ojhunt/web/pages.py
+++ b/src/ojhunt/web/pages.py
@@ -90,11 +90,14 @@ def render_page(
 
     Pass `canonical=False` for a page that must stay out of the search index
     (404, easter eggs) — a noindex page must not claim a canonical URL.
+
+    The canonical URL comes from the request URL itself, not from `base_url` plus
+    the path: both carry any ASGI `root_path`, so joining them repeats the mount
+    prefix. `site_base` keeps `base_url`, because it is joined with a literal path.
     """
-    base = str(request.base_url).rstrip("/")
     return jinja_env.get_template(template_name).render(
-        site_base=base,
-        canonical_url=f"{base}{request.url.path}" if canonical else None,
+        site_base=str(request.base_url).rstrip("/"),
+        canonical_url=str(request.url.replace(query="")) if canonical else None,
         **context,
     )
 

From 82b22f3108d2ced50b6c20751bada23f04d4323d Mon Sep 17 00:00:00 2001
From: Shumin Liu <shumin.liu@tngtech.com>
Date: Fri, 14 Aug 2026 20:39:12 +1000
Subject: [PATCH 7/8] fixup! chore(env): load code conventions from path-scoped
 rules

---
 docs/adr/0016-adopt-ruff-default-rule-set.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/adr/0016-adopt-ruff-default-rule-set.md b/docs/adr/0016-adopt-ruff-default-rule-set.md
index acdef0c..efb6cbb 100644
--- a/docs/adr/0016-adopt-ruff-default-rule-set.md
+++ b/docs/adr/0016-adopt-ruff-default-rule-set.md
@@ -13,7 +13,7 @@ Two of the newly enabled rule groups collide with the codebase on purpose rather
 accident:
 
 - `UP006`, `UP007`, `UP035` and `UP045` — 341 of the 534 findings — demand PEP 585 and PEP 604
-  syntax (`dict[str, X]`, `X | None`). `docs/dev/python.md` said the opposite: "Use `Dict`,
+  syntax (`dict[str, X]`, `X | None`). The Python convention said the opposite: "Use `Dict`,
   `List`, `Union` from the `typing` module." Both rules cannot hold.
 - `BLE001` flags 23 `except Exception` blocks. Every crawler ends in one by design.
 
@@ -52,7 +52,7 @@ recorded in config, and three at the site:
 | `# noqa: UP031` | `crawlers/eolymp.py` | `.format()` needs every brace in the GraphQL body doubled. |
 | `# noqa: DTZ007` | `web/pdf.py` | The chart axis parses day keys that are already local-day strings. It needs their order, not an instant. |
 
-`docs/dev/python.md` now states the PEP 585/604 rule, and the `query()` templates in
+`.claude/rules/python.md` now states the PEP 585/604 rule, and the `query()` templates in
 `docs/dev/crawlers.md` were updated so a new crawler does not reintroduce the old style.
 
 ## Consequences

From abee746d0c19ae17072651bef45a2ac2acde6457 Mon Sep 17 00:00:00 2001
From: Shumin Liu <shumin.liu@tngtech.com>
Date: Fri, 14 Aug 2026 20:39:12 +1000
Subject: [PATCH 8/8] fixup! build(lint): replace the shell check with a tested
 lint rule

---
 .claude/hooks/format-lint-python.sh     | 18 ++++++++++-
 CLAUDE.md                               |  6 ++--
 doit.sh                                 |  2 +-
 lint/rules/comment_above_assert.py      | 33 ++++++++++++++++----
 tests/lint/comment_above_assert_test.py | 41 +++++++++++++++++++++++++
 5 files changed, 89 insertions(+), 11 deletions(-)

diff --git a/.claude/hooks/format-lint-python.sh b/.claude/hooks/format-lint-python.sh
index 9bf3775..ed392a4 100644
--- a/.claude/hooks/format-lint-python.sh
+++ b/.claude/hooks/format-lint-python.sh
@@ -13,12 +13,28 @@ fi
 
 # The project's own rules (lint/rules/), on the one file that just changed. Same
 # rules ./doit.sh lint runs over everything, so the hook cannot drift from CI.
+# Each rule decides whether the file is in its own scope.
 command -v uv &>/dev/null || exit 0
+
+# An environment that cannot run anything (fresh clone, offline uv cache) would
+# otherwise fail every rule and block every edit on a uv traceback. The exit code
+# cannot tell that apart afterwards: a rule that raises also exits 1. The ruff
+# steps above skip for the same reason.
+uv run python -c "" &>/dev/null || exit 0
+
 FAILURES=""
+collect() {
+    OUTPUT=$("$@" 2>&1) || FAILURES+="$OUTPUT"$'\n'
+    return 0
+}
+
 for RULE in lint/rules/*.py; do
     [ -e "$RULE" ] || continue
-    OUTPUT=$(uv run python "$RULE" "$FILE" 2>&1) || FAILURES+="$OUTPUT"$'\n'
+    collect uv run python "$RULE" "$FILE"
 done
+if compgen -G "lint/rules/*.yml" >/dev/null; then
+    collect uv run ast-grep scan "$FILE"
+fi
 if [[ -n "$FAILURES" ]]; then
     printf '%s\n' "$FAILURES" >&2
     exit 2
diff --git a/CLAUDE.md b/CLAUDE.md
index 9023d80..0b38f53 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,15 +4,15 @@
 
 Run `./doit.sh help` for the full list. Key tasks:
 
-- `./doit.sh lint` — ruff linter
+- `./doit.sh lint` — ruff plus the project's own rules in `lint/rules/`
 - `./doit.sh test-unit` — unit tests (fast, no network, no browser)
 - `./doit.sh test-e2e` — browser e2e tests, excluding visual (starts dev server if needed)
 - `./doit.sh test-crawler <name>` — network tests for one crawler (e.g. `codeforces`)
 - `./doit.sh test-visual` / `update-snapshots` — visual regression tests
-- `./doit.sh full-check` — lint + all tests (unit, e2e, visual); starts & stops the server
+- `./doit.sh full-check` — lint + rule tests + all tests (unit, e2e, visual); starts & stops the server
 - `./doit.sh start` / `kill` / `status` / `logs` — dev server lifecycle
 
-When a `lint`/`test-*`/`full-check` task fails, its full output is already saved to `.doit/<task>.log` — **read that log** (e.g. `grep -nE 'FAILED|error' .doit/test-unit.log`) instead of re-running the task with `| tail`/`| grep`. `full-check` runs each step as its own task, so read the specific step's log (`.doit/test-e2e.log`, `.doit/test-visual.log`, …); its own stdout is only a short `full-check PASSED/FAILED` summary, so don't pipe it through `| tail` either.
+When a `lint*`/`test-*`/`full-check` task fails, its full output is already saved to `.doit/<task>.log` — **read that log** (e.g. `grep -nE 'FAILED|error' .doit/test-unit.log`) instead of re-running the task with `| tail`/`| grep`. `full-check` runs each step as its own task, so read the specific step's log (`.doit/test-e2e.log`, `.doit/test-visual.log`, …); its own stdout is only a short `full-check PASSED/FAILED` summary, so don't pipe it through `| tail` either.
 
 ## Where to find documentation
 
diff --git a/doit.sh b/doit.sh
index 001bfd3..54f9a7a 100755
--- a/doit.sh
+++ b/doit.sh
@@ -347,7 +347,7 @@ Tests:
   test-visual        run visual regression tests (starts server if needed) [pytest-args...]
   test-crawler NAME  run tests for a specific crawler by name [pytest-args...]
   update-snapshots   update visual regression snapshots (starts server if needed)
-  full-check         run lint + all tests (unit, e2e, visual); starts & stops the server
+  full-check         run lint + rule tests + all tests (unit, e2e, visual); starts & stops the server
 
 Docs:
   gen-docs           regenerate docs/library.md from the library docstrings
diff --git a/lint/rules/comment_above_assert.py b/lint/rules/comment_above_assert.py
index 91732c3..931b23f 100644
--- a/lint/rules/comment_above_assert.py
+++ b/lint/rules/comment_above_assert.py
@@ -9,7 +9,9 @@
 them apart. Getting that wrong reports the violation on the innocent line below
 it, or misses it entirely when no assert follows.
 
-Run over the default scope, or over named files:
+Run over the default scope, or over named files. A named file outside the scope
+is skipped, so the edit-time hook can pass whatever file just changed and still
+report exactly what CI reports:
 
     uv run python lint/rules/comment_above_assert.py
     uv run python lint/rules/comment_above_assert.py tests/web/api_test.py
@@ -38,6 +40,10 @@
 # Files the rule applies to, relative to the repository root.
 SCOPE = "tests/**/*.py"
 
+# A tool directive is addressed to another program, so "move it into the assert
+# message" is not advice anybody can take.
+PRAGMAS = ("# type:", "# noqa", "# pragma:", "# fmt:", "# ruff:")
+
 
 @dataclass(frozen=True)
 class Finding:
@@ -76,13 +82,14 @@ def find_violations(source: str, path: Path) -> list[Finding]:
     """Every assert in `source` whose explanation sits in a comment."""
     findings = []
     for comment in SgRoot(source, "python").root().find_all(kind="comment"):
+        text = comment.text().strip()
+        if text.lower().startswith(PRAGMAS):
+            continue
         trailed = _trailing_statement(comment)
         target = trailed if trailed is not None else _statement_below(comment)
         if target is None or target.kind() != "assert_statement":
             continue
-        findings.append(
-            Finding(path, target.range().start.line + 1, comment.text().strip())
-        )
+        findings.append(Finding(path, target.range().start.line + 1, text))
     return findings
 
 
@@ -93,9 +100,23 @@ def scan(paths: list[Path]) -> list[Finding]:
     return findings
 
 
+def scoped_files() -> list[Path]:
+    """Every file in SCOPE. The rule owns its scope, not its callers.
+
+    The hook passes the single file that just changed, whatever it is. Filtering
+    here is what keeps the hook and `./doit.sh lint` from disagreeing about
+    which files the rule covers.
+    """
+    return sorted(Path(__file__).parents[2].glob(SCOPE))
+
+
 def main(argv: list[str]) -> int:
-    root = Path(__file__).parents[2]
-    paths = [Path(a) for a in argv] if argv else sorted(root.glob(SCOPE))
+    scope = scoped_files()
+    if argv:
+        covered = {path.resolve() for path in scope}
+        paths = [path for path in map(Path, argv) if path.resolve() in covered]
+    else:
+        paths = scope
     findings = scan(paths)
     for finding in findings:
         print(finding, file=sys.stderr)
diff --git a/tests/lint/comment_above_assert_test.py b/tests/lint/comment_above_assert_test.py
index a1b468d..42141d7 100644
--- a/tests/lint/comment_above_assert_test.py
+++ b/tests/lint/comment_above_assert_test.py
@@ -158,6 +158,21 @@ def test_x():
     assert _lines(source) == []
 
 
+@pytest.mark.parametrize(
+    "pragma",
+    ["# type: ignore[arg-type]", "# noqa: E501", "# fmt: skip", "# NOQA"],
+)
+def test_tool_pragmas_are_ignored(pragma):
+    source = f"""
+def test_x():
+    result = query()
+    assert isinstance(result, Mapping)  {pragma}
+"""
+    assert _lines(source) == [], (
+        f"{pragma} is addressed to another tool, so it cannot move into the message"
+    )
+
+
 def test_trailing_comment_at_the_end_of_a_body_is_ignored():
     source = """
 def test_x():
@@ -167,6 +182,32 @@ def test_x():
     assert _lines(source) == [], "no statement follows, so nothing is explained"
 
 
+# ---------------------------------------------------------------------------
+# Scope — the hook hands the rule whatever file just changed
+# ---------------------------------------------------------------------------
+
+
+def test_scope_covers_this_test_file():
+    covered = {path.resolve() for path in rule.scoped_files()}
+    assert Path(__file__).resolve() in covered, (
+        "a named file inside SCOPE must reach the scanner"
+    )
+
+
+def test_a_named_file_outside_the_scope_is_skipped(tmp_path):
+    stray = tmp_path / "stray_test.py"
+    stray.write_text(
+        "def test_x():\n    # explanation\n    assert value == 1\n", encoding="utf-8"
+    )
+    assert rule.find_violations(stray.read_text(encoding="utf-8"), stray), (
+        "the probe must violate the rule, or the next assertion proves nothing"
+    )
+    assert rule.main([str(stray)]) == 0, (
+        "only SCOPE decides what the rule covers — otherwise the hook blocks on "
+        "files ./doit.sh lint never looks at"
+    )
+
+
 # ---------------------------------------------------------------------------
 # The rule holds over the repository it guards
 # ---------------------------------------------------------------------------