lepisma 0.1.1__tar.gz

lepisma-0.1.1/.claude/skills/prose-rewrite/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: prose-rewrite
+description: Rewrite a Markdown doc so it is easier to read, driven by lepisma warnings. Use when the user asks to clean up, simplify or de-Claude a doc, or when a commit prints lepisma warnings.
+---
+
+# Rewrite a doc with lepisma
+
+1. Run `lepisma check --format json <file>` and note `summary.per_1000_words`.
+2. Rewrite only the flagged prose. Keep the meaning, facts, headings, code and links.
+   - R1 long sentence: split it. One idea per sentence.
+   - R2 noun stack: unpack it with a verb or a preposition
+     ("error handling for config validation", or better, "when validation fails, ...").
+   - R3 habit word: use the suggestion, or delete the word if the sentence still holds.
+   - R4 nominalization: use the hidden verb ("performs validation of X" → "validates X").
+3. Run the check again. Repeat until warnings stop dropping. Zero is not the goal.
+4. Where a warning is wrong, leave the text and add
+   `<!-- lepisma: disable-next Rn -->` above the block. Tell the user why.
+5. Report: density before → after, and any rule that looked noisy. Noisy rules are
+   input for tuning `lepisma.toml`.

lepisma-0.1.1/.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+      - "python"
+    groups:
+      minor-and-patch:
+        update-types:
+          - "minor"
+          - "patch"

lepisma-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,17 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.3.3
+        with:
+          enable-cache: true
+      - run: uv sync
+      - run: uv run poe check

lepisma-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,58 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.3.3
+      - run: uv build
+      - run: uvx twine check dist/*
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/lepisma
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    needs: publish
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/')
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: softprops/action-gh-release@v3
+        with:
+          files: dist/*
+          generate_release_notes: true

lepisma-0.1.1/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.env
+*.so
+.coverage
+htmlcov/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+stats/

lepisma-0.1.1/CLAUDE.md

@@ -0,0 +1,127 @@
+# lepisma
+
+Soft prose warnings for Markdown written by Claude. This is the spaCy prototype. See
+README.md for the design, rules and roadmap. Run `uv run lepisma guide` before
+using the CLI.
+
+## Layout
+
+- `markdown.py` turns Markdown into prose blocks and maps each character back to its
+  line and column. It drops code, tables, front matter and HTML. Inline code becomes
+  the `CODE` placeholder.
+- `rules.py` holds R1 to R4. Each is `(block, doc, cfg) -> Iterator[Finding]`.
+- `engine.py` runs spaCy and the rules. Only it, `server.py` and `measure.py` import
+  spaCy.
+- `client.py` is the commit hook client. **Stdlib only**; it never raises and always
+  exits 0. Keep spaCy and FastAPI out of it, and out of `config.py`, `models.py` and
+  `report.py`, which it imports.
+- `measure.py` computes readability stats for whole docs as Polars tables; it is
+  the library API (`Measurer`). `measure_report.py` builds the scores and
+  `report.md`. Both need the `measure` extra (TextDescriptives, Polars), so keep
+  them off the lint and hook path.
+- `spacy_model.py` finds the spaCy model. An installed `en_core_web_sm` wins (the
+  dev group has it); otherwise it downloads the hash-pinned wheel once into
+  `~/.cache/lepisma/models/`. The model is not a runtime dependency because PyPI
+  rejects URL deps. Bump `VERSION`, `WHEEL_SHA256` and the dev-group URL together
+  with the spaCy minor.
+- `server.py` is the FastAPI server on 127.0.0.1:8737, with an LRU cache and idle exit.
+- `corpus/` is the baseline test set. `tests/test_corpus.py` checks that bad docs score
+  far worse than good ones.
+- `guide.py` and `guide/*.md` are `lepisma guide`, the agent instructions. Pages
+  take `{{section.key}}` placeholders filled from `Config` defaults. Update the
+  pages when a command, rule or config key changes.
+
+## Tuning a rule
+
+Run `uv run lepisma stats corpus/bad corpus/good corpus/toolbox` before and after
+a change to a rule or threshold. A good change keeps bad docs high, and good and
+toolbox docs low. Add a test to
+`tests/test_rules.py` for each false positive you fix.
+
+## Commands
+
+- `uv run poe check` — run lint (incl. ruff `S` security rules), typecheck, vulns, test-lint, clones, then tests
+- `uv run poe fix` — auto-format and fix lint issues
+- `uv run poe test` — run tests only
+- `uv run poe check-all` — run all checks including dead-code and unused-deps
+
+## Releasing
+
+Bump `version` in `pyproject.toml`, commit, then `git tag vX.Y.Z` and
+`git push origin vX.Y.Z`. `.github/workflows/release.yml` builds, runs
+`twine check`, and publishes to PyPI (trusted publishing, environment `pypi`).
+
+## Stack
+
+uv, ruff (lint/format), ty (type check), pytest, poethepoet (task runner)
+
+## Toolbox
+
+The [aesop toolbox](https://mojzis.github.io/aesop/llms.txt) is wired in here. Every
+tool explains itself — run `uv run <tool> guide` before reaching for flags, and
+`uv run <tool> guide tune` before changing a threshold. Call them as `uv run <tool>`;
+ty-find's binary is `tyf`.
+
+### On every commit
+
+**madoqua** is the only commit hook (`hooks/pre-commit`, `core.hooksPath=hooks`). It
+acts on staged `.py`/`.pyi` files only — a commit without one is a silent no-op, not a
+verified hook.
+
+| phase | steps |
+| --- | --- |
+| fix (rewrites and re-stages) | `ruff check --fix`, `ruff format` |
+| check (blocks) | `ruff check`, `ty check`, `biston scan --focus-args`, `zorilla check`, `gerenuk run` |
+
+Whole hook runs in ~0.3 s on this repo (gerenuk ~0.27 s of that; `uv run madoqua stats`
+for current numbers). Don't commit with `--no-verify` or `MADOQUA_SKIP` to get past a
+check that is telling the truth.
+
+Two changes from the hook this replaced:
+
+- `ty check` was repo-wide, it is now **staged-only**. Repo-wide diagnostics no longer
+  block a clean commit, but a file with existing diagnostics blocks the first commit
+  that touches it. `uv run poe typecheck` still checks everything.
+- **bandit is gone.** Security checks are ruff's flake8-bandit `S` rules, so they now run
+  on commit via `ruff check`; `tests/**` ignores S101/S105/S106 in `per-file-ignores`.
+
+### Every now and then
+
+- `uv run pycoati . --format pretty` — scores every test for suspicion and prints a
+  remediation ladder. Run it before a test-cleanup session. Never put it in a hook or
+  CI: it runs the suite three times. It needs pytest-cov or coverage is silently null.
+
+### On demand — instead of grep
+
+- `uv run tyf find <symbol>` / `tyf refs` / `tyf list <file>` / `tyf calls` — type-aware
+  symbol lookup. **Use these instead of grep** for definitions and references; grep
+  cannot tell a definition from a string that happens to match.
+- `uv run gerenuk audit <file>` — lists symbols in a module that nothing references.
+- `uv run gerenuk impacted-tests` — which tests a working-tree diff reaches, and why.
+
+### Fresh clone
+
+```
+uv sync
+uv run madoqua install    # once; core.hooksPath is local config, not tracked
+```
+
+### Refreshing the toolbox
+
+```
+uv lock --refresh --upgrade-package madoqua --upgrade-package gerenuk --upgrade-package biston --upgrade-package zorilla --upgrade-package pycoati --upgrade-package ty-find && uv sync
+```
+
+`--refresh` matters: without it uv may serve a cached index and miss a release
+published minutes ago.
+
+## Notes
+
+- ty is in beta — may produce false positives. Prefer `# ty: ignore[rule]` over blanket suppression.
+- The commit hook auto-fixes and restages files. Only blocks on unfixable issues.
+- gerenuk diffs the **working tree** against `origin/main`, so unstaged edits count, and
+  any commit touching `pyproject.toml` or `uv.lock` runs the full suite. `--base HEAD`
+  scopes it to the commit itself.
+- ty-find's index goes stale after the hook's `ruff format` rewrites a file. The tell is
+  `tyf refs <sym>` listing only the definition, or gerenuk reporting `selected` with an
+  empty list. `uv run tyf daemon restart` fixes it.

lepisma-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mojzis <mojzisek@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lepisma-0.1.1/PKG-INFO

@@ -0,0 +1,308 @@
+Metadata-Version: 2.5
+Name: lepisma
+Version: 0.1.1
+Summary: Soft, fast prose warnings for Claude-written Markdown docs
+Project-URL: Homepage, https://github.com/mojzis/lepisma
+Project-URL: Issues, https://github.com/mojzis/lepisma/issues
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.115
+Requires-Dist: pydantic>=2
+Requires-Dist: spacy<3.9,>=3.8
+Requires-Dist: uvicorn>=0.32
+Provides-Extra: measure
+Requires-Dist: polars>=2.1.0; extra == 'measure'
+Requires-Dist: textdescriptives>=2.8.2; extra == 'measure'
+Description-Content-Type: text/markdown
+
+# lepisma
+
+Fast, soft feedback on Markdown docs that are hard to read. It targets the habits
+of text written by Claude. Warnings go back to Claude so it can rewrite the text.
+**Warnings never block a commit.**
+
+The name: *Lepisma saccharina* is the silverfish, which eats paper and chews
+through books.
+
+Agents: start with the built-in guide. It picks setup or triage from the repo state.
+
+```
+uvx lepisma@latest guide
+```
+
+Sample output:
+
+```
+docs/setup.md:12:1 R1 Sentence has 31 words; consider splitting.
+docs/setup.md:14:22 R2 Stack of 4 nouns ("pipeline configuration validation error"); rephrase with a verb or preposition.
+docs/setup.md:15:9 R3 Habit word "leverage"; try: use.
+docs/setup.md:18:5 R4 "performs validation" hides the verb; try "validate".
+```
+
+## How it works
+
+- **Local spaCy server.** A small FastAPI process keeps `en_core_web_sm` loaded on
+  `127.0.0.1:8737`. The hook starts it on first use and reuses it after that. It
+  exits after 4 hours without requests.
+- **Commit hook client.** It sends only the staged Markdown files to the server and
+  prints the warnings. It uses only the standard library and starts in under 0.1 s.
+- **Fail open.** If the server is down, the hook starts it and skips this commit. If
+  the server takes longer than 300 ms, the hook skips. Either way it prints nothing.
+- **Output for Claude.** One warning per line as `file:line:col rule-id message`, or
+  JSON with `--format json`.
+
+## Install
+
+Add it to the repo's dev dependencies, so the hook finds it in `.venv`:
+
+```
+uv add --dev lepisma
+cp /path/to/lepisma/lepisma.toml .   # optional; every key has a default
+```
+
+### The spaCy model
+
+spaCy models are not on PyPI, so `en_core_web_sm` 3.8.0 is not a dependency. On
+first use, `check`, `stats`, `measure` and the server download the wheel once
+(~13 MB) and check its SHA-256. They unpack it to
+`~/.cache/lepisma/models/`, outside any virtualenv, so every `uvx` run and
+venv shares one copy. This needs no pip. The hook client never downloads; it
+skips commits while the server starts.
+
+Offline, install the model into the environment instead:
+
+```
+uv pip install https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl
+```
+
+Or set `LEPISMA_MODEL_WHEEL` to a local copy (or mirror URL) of that wheel.
+
+### With madoqua (the main path)
+
+Add a check step that wakes on staged Markdown. madoqua appends the matched files:
+
+```toml
+[tool.madoqua]
+extend_check = [
+  { name = "lepisma", cmd = "lepisma hook", on = ["*.md", "*.markdown"], timeout_s = 5 },
+]
+```
+
+**Gap:** madoqua prints a step's output only when the step fails, and
+`lepisma hook` always exits 0. So the warnings stay hidden until madoqua gets
+a warn-only step mode that prints output without blocking
+([madoqua#19](https://github.com/mojzis/madoqua/issues/19)).
+
+### Without madoqua
+
+```
+lepisma install-hook   # adds one warn-only line to the pre-commit hook
+```
+
+`install-hook` follows `core.hooksPath`. It puts its line right after the shebang, so
+it runs even when the rest of the hook ends in `exec`.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `lepisma guide [setup\|triage\|tune]` | Print instructions for an agent. With no topic it picks one from the current directory. |
+| `lepisma check PATH...` | Lint files or folders in-process, no server. `--format json`, `--strict` exits 1 on warnings. |
+| `lepisma stats PATH...` | Warnings per 1,000 words per file and rule, one table per path. |
+| `lepisma measure PATH...` | Readability stats for whole docs. Writes Parquet tables and `report.md` to `--out` (default `stats/`). Needs the `measure` extra. |
+| `lepisma hook [FILE...]` | What the git hook runs. Lints the given files, or asks git for the staged docs. `--wait 10` waits for the server instead of skipping. |
+| `lepisma serve` | Run the server in the foreground. `--idle-timeout 0` keeps it up. |
+| `lepisma stop` | Stop the server, for example after an upgrade. |
+
+The hook replaces a server whose code differs from its own. It compares a hash of the
+package source, so upgrades and local edits take effect. The commit that finds the
+mismatch is skipped.
+
+Environment variables:
+
+- `LEPISMA_VERBOSE=1` prints why the hook skipped.
+- `LEPISMA_DISABLE=1` turns the hook off.
+- `LEPISMA_PORT` and `LEPISMA_TIMEOUT_MS` override the config.
+- `LEPISMA_MODEL_WHEEL` is a path or URL to fetch the spaCy model wheel from.
+
+The server log is in `~/.cache/lepisma/server.log`.
+
+## Rules
+
+| ID | Name | Warns when | Strong when |
+| --- | --- | --- | --- |
+| R1 | `long-sentence` | a sentence has more than 25 words | more than 35 |
+| R2 | `noun-stack` | 4 or more nouns in a row modify each other | 5 or more |
+| R3 | `habit-word` | a word from the habit list appears | more than 2 in one paragraph |
+| R4 | `nominalization` | a weak verb takes an abstract noun ("performs validation of") | the sentence also has 4 or more abstract nouns |
+
+Details:
+
+- **All rules** skip code blocks, inline code, tables, front matter, HTML and link
+  targets. List items that hold only an identifier, like `- max_retries`, are skipped
+  too.
+- **Headings** get R3 only.
+- **R2** ignores runs made only of proper nouns, like "GitHub Actions CI". It also
+  ignores runs with more than one proper noun (`max_proper_nouns`), like "Claude Code
+  conversation logs". Inline code breaks a run, and a hyphenated word like
+  "event-store" counts as one noun. The threshold is 4, not 3: at 3 it flagged plain
+  technical terms like "Unix domain socket" in real docs. At 5 it would miss every true
+  stack the rollout found. The tagger often calls a verb a noun, so R2 drops these from
+  a run before it counts:
+  - a verb that opens a list item, sentence or labelled line: "Test line number
+    accuracy", "Purpose: Validates crossword grid structure";
+  - a plural before another noun, which ends a subject: "a header toggle pins
+    light/dark", "Claude Code loads ancestor files";
+  - a plural verb that the parser made the root of a verbless sentence, like "resets"
+    in "The progress bar resets after a logout".
+
+  The verb test uses the WordNet verb list in spaCy's lemmatizer.
+<!-- lepisma: disable-next R3 -->
+- **R3** matches inflections, so "leveraging" counts as "leverage". The default list:
+  comprehensive, robust, seamless, seamlessly, leverage, utilize, delve, crucial,
+  streamline, ensure, facilitate, "in order to", "it is important to note",
+  successfully, "solid foundation". "successfully" counts only right before a verb:
+  "successfully implemented", not "runs successfully". Words in `ok_at_item_start`
+  (default: ensure) are fine as the first word of a list item or checklist line, as in
+  "- Ensure the build passes". "essential" is off the list. In real docs it mostly
+  meant just that ("essential information").
+- **R4** counts nouns that end in -tion, -sion, -ment, -ance, -ence or -ity. A stoplist
+  removes concrete words like "function", "document" and "instance". A weak verb is
+  flagged only when its noun comes from a verb, as "placement" comes from "place".
+  "fraction" and "flexibility" have no verb, so nothing is hidden. For "be" and "have",
+  the noun must also take "of" and not be counted. So "is the implementation of" is
+  flagged, but "is one placement of" is not. "provide", "give" and "offer" are
+  skipped when they hand something over. That means a recipient ("provides guidance to
+  Claude Code") or a named deliverable ("provide image descriptions").
+
+## Measuring whole docs
+
+`lepisma measure` reports how hard a set of docs is to read, and where the
+hardest parts are. It never edits a doc.
+
+```
+uv add --dev "lepisma[measure]"
+uv run lepisma measure docs/ --out stats/
+```
+
+It writes four files:
+
+- `sentences.parquet`: one row per sentence, with file, line, column, section and
+  source text. It counts words, passives, commas, parentheses, dashes,
+  nominalizations and habit words. It also gives mean dependency distance, main
+  verb position and the longest noun run.
+- `sections.parquet` and `files.parquet`: sentence length as mean, median, p90 and
+  max, and the share of sentences over 25 and 35 words. Readability as Flesch
+  reading ease, Flesch-Kincaid grade, Gunning Fog and LIX. Part-of-speech shares and
+  the noun-to-verb ratio. Nominalizations per 100 words, repeated 5-grams, and habit
+  words per 1,000 words.
+- `report.md`: medians and p90s, the 15 hardest files and sections, the 30 hardest
+  sentences, and which metrics spread enough to make good lint thresholds.
+
+It uses the same parser as the linter, and the R2 to R4 definitions of noun runs,
+nominalizations and habit words. Headings only name sections. List items under 4
+words are skipped. TextDescriptives computes readability, dependency distance,
+part-of-speech shares and repetition.
+
+### As a library
+
+A docs server can load the model once and measure pages on request:
+
+```python
+from lepisma.measure import Measurer
+from lepisma.measure_report import render
+
+measurer = Measurer()  # loads spaCy once; reuse it
+result = measurer.measure({"guide.md": text})  # {path: markdown}
+result.files.row(0, named=True)  # dict of file metrics
+result.sentences.sort("words", descending=True).head(5)
+render(result, min_words=100)  # the report as Markdown
+```
+
+`result.sentences`, `.sections` and `.files` are Polars data frames.
+
+## Configuration
+
+Put one `lepisma.toml` at the repo root. The [sample in this repo](lepisma.toml)
+lists every key with its default.
+
+To turn rules off inside a document:
+
+```markdown
+<!-- lepisma: disable R2 -->        off until enable or end of file
+<!-- lepisma: enable R2 -->
+<!-- lepisma: disable-next R1 R3 --> off for the next block only
+<!-- lepisma: disable -->           all rules
+```
+
+Rules can be named by ID (`R2`) or by name (`noun-stack`).
+
+## Feedback loop with Claude
+
+Add this to the `CLAUDE.md` of a repo that uses the hook:
+
+> When a commit prints `lepisma` warnings, rewrite the flagged prose and commit
+> again. Split long sentences, turn noun stacks and nominalizations into verbs, and
+> replace habit words with plain ones. Use `<!-- lepisma: disable-next Rn -->` only
+> where a warning is wrong, and say why.
+
+For a whole document, run `lepisma check --format json doc.md`, give Claude the
+result, and ask for a rewrite. The `prose-rewrite` skill in `.claude/skills/` does this
+loop. Then check the result with people, not just with the linter.
+
+## Measuring success
+
+- **Density.** Warnings per 1,000 words before and after a rewrite:
+  `lepisma stats before/ after/`.
+- **Human rating.** A quick 1 to 5 readability score on the test set.
+- **Noise.** How often people disable each rule. Remove the noisy ones.
+
+The baseline test set lives in [`corpus/`](corpus/):
+
+- `bad/` and `good/` hold synthetic docs that read badly and well.
+  `tests/test_corpus.py` checks that bad docs score far worse than good ones.
+- `toolbox/` holds the real docs of the aesop tools (gerenuk, madoqua, biston,
+  zorilla, coati, ty-find). They are unlabeled. The test checks that R2 to R4 stay
+  under 1 per 1,000 words there, which catches rules that start flagging normal
+  prose. `scripts/sync-toolbox-corpus.sh` refreshes the copy.
+
+Swap in 10 to 20 real hard-to-read docs from your team for `bad/` before tuning
+further.
+
+Current numbers (warnings per 1,000 words):
+
+| Set | Words | R1 | R2 | R3 | R4 | Total |
+| --- | --- | --- | --- | --- | --- | --- |
+| bad | 2,698 | 7.4 | 3.3 | 41.9 | 8.5 | 61.2 |
+| good | 1,235 | 0 | 0 | 0.8 | 0 | 0.8 |
+| toolbox | 51,529 | 9.0 | 0.1 | 0.0 | 0.2 | 9.3 |
+
+## Roadmap
+
+1. ~~Baseline test set~~ (placeholders; swap in real docs)
+2. ~~Four starter rules~~
+3. ~~Commit hook in warn-only mode~~
+4. Feedback loop: rewrite with Claude, then ask people whether the result reads better.
+5. Expand: try passive voice per paragraph, late main verb, deep nesting, too many
+   parentheses, undefined acronyms, repeated openings, summary filler and Flesch score.
+   Add an optional LLM judge in CI.
+6. Port the useful rules to Rust (harper-core and Weir) if speed or distribution
+   becomes a problem.
+
+## Development
+
+```
+uv sync
+uv run madoqua install
+uv run poe check
+```
+
+### Releasing
+
+Pushing a `vX.Y.Z` tag runs `.github/workflows/release.yml`. It builds, runs
+`twine check`, publishes to PyPI by trusted publishing and creates a GitHub
+release.
+
+1. Bump `version` in `pyproject.toml` and commit.
+2. `git tag vX.Y.Z` (the same version) and `git push origin vX.Y.Z`.