slopscore-lint 0.4.2__tar.gz

slopscore_lint-0.4.2/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Sync (dev deps)
+        run: uv sync
+      - name: Lint
+        run: uv run ruff check .
+      - name: Format check
+        run: uv run ruff format --check .
+      - name: Type check
+        run: uv run mypy src
+      - name: Tests
+        run: uv run pytest -q

slopscore_lint-0.4.2/.github/workflows/docs.yml

@@ -0,0 +1,21 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths: ["docs/**", "mkdocs.yml", ".github/workflows/docs.yml"]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force

slopscore_lint-0.4.2/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist + wheel
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    # Trusted publishing (OIDC) — no API tokens. Requires a PyPI trusted publisher configured for
+    # this repo + workflow (Settings → Publishing on the PyPI project page).
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/slopscore-lint
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

slopscore_lint-0.4.2/.gitignore

@@ -0,0 +1,38 @@
+# Local working docs (specs, references) — keep out of the repo
+*.local.md
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.so
+
+# Virtual env (uv.lock IS committed for reproducible dev installs)
+.venv/
+
+# Test / coverage / type-check caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage*
+htmlcov/
+coverage.xml
+
+# Filesystem-sync duplicate artifacts (e.g. "config_file 2.py")
+* [0-9].*
+
+# Editor / OS
+.idea/
+.vscode/
+.DS_Store
+
+# Claude Code runtime artifacts
+.claude/scheduled_tasks.lock
+.slopscore/
+
+# Filesystem-sync duplicate artifacts (e.g. "file 2.py")
+*[0-9].py
+* [0-9].*

slopscore_lint-0.4.2/.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.5.7
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.1
+    hooks:
+      - id: mypy
+        additional_dependencies: [pydantic>=2.7, types-pyyaml]
+        files: ^src/

slopscore_lint-0.4.2/.pre-commit-hooks.yaml

@@ -0,0 +1,10 @@
+- id: slopscore-lint
+  name: slopscore-lint (AI-slop pattern linter)
+  description: Scan prose for AI-slop writing patterns.
+  entry: slopscore-lint scan
+  language: python
+  types: [text]
+  files: '\.(md|markdown|txt|rst)$'
+  args: ["--fail-on", "high"]
+  pass_filenames: true
+  require_serial: false

slopscore_lint-0.4.2/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to slopscore. The PyPI distribution is `slopscore-lint`; the import package
+and the tool are named `slopscore`.
+
+## 0.4.2
+
+- Scrubbed the README, docs, and model card of the writing patterns the tool flags (em dashes and
+  over-polished verbs), so the published prose passes slopscore itself.
+- Config: reject a bare string for `disabled_rules` / `disabled_dimensions` (previously it iterated
+  into per-character entries) with a clear error.
+- CLI: create missing parent directories for `--output` and `baseline -o`; report a friendly error
+  on a malformed `--baseline-file` instead of a traceback; skip non-UTF-8 files in a batch with a
+  warning rather than aborting the run.
+- Added `CHANGELOG.md` and `SECURITY.md`.
+
+## 0.4.1
+
+- Renamed the PyPI distribution and the CLI command to `slopscore-lint` (the name `slopscore` was
+  already taken on PyPI). The import package stays `slopscore`.
+
+## 0.4.0
+
+- Project config via `slopscore.toml` and `[tool.slopscore]` in `pyproject.toml`, with per-rule and
+  per-dimension toggles and severity overrides (`slopscore-lint config`).
+- Inline suppression through `<!-- slopscore-disable ... -->` comments.
+- Findings baseline: `slopscore-lint baseline` plus `scan --baseline-file --fail-on-new` to adopt
+  the linter on an existing repo and gate CI on new findings only.
+- Implemented the `unsupported_claims` dimension (universal and inflated claims).
+- Opt-in rewrite suggestions (`--suggest`) with SARIF `fixes`, advisory and never auto-applied.
+- Authorship-adapter interface (`AuthorshipDetector` protocol) behind the `[detectors]` extra. No
+  detector is bundled; any result is reported separately and never folded into the score.
+- PyPI trusted-publishing workflow and an mkdocs-material docs site.
+
+## 0.3.0
+
+- Transparent learned scorer (`--scorer ml`): a sign-constrained, calibrated logistic regression
+  over the 13 dimensions, serialized as auditable JSON and run with pure numpy. The rule scorer
+  stays the default under a replace-if-wins gate.
+- Evaluation harness/framework (`slopscore-lint eval`): TPR@FPR, PR-AUC, calibration, and
+  per-subgroup false-positive rates. See `MODEL_CARD.md` and `DATA_SOURCES.md`.
+
+## 0.2.1
+
+- console/JSON/Markdown/SARIF/HTML reports, recursive and changed-files (`--diff`) batch scanning
+  with CI exit codes, a GitHub Action, and a pre-commit hook.
+
+## 0.2.0
+
+- Detection expansion grounded in Wikipedia's "Signs of AI writing" guide: significance inflation,
+  superficial analysis, weasel attribution, negative parallelism, copula avoidance, formatting
+  tells, and a negative human-writing signal. Conservative scoring with a corroboration gate and
+  abstention on short or non-English input.
+
+## 0.1.0
+
+- Initial release: ingestion (text, Markdown, JSON, websites), offset-preserving normalization, a
+  feature registry, and the first dimensions with evidence spans.

slopscore_lint-0.4.2/CLAUDE.md

@@ -0,0 +1,156 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+`uv`-managed, src-layout. Common workflows:
+
+```bash
+uv pip install -e . --no-deps    # editable install (see install-stability note below)
+uv run --no-sync slopscore-lint scan FILE   # scan a file/URL/'-' (stdin); --format console|json|markdown
+uv run --no-sync pytest          # tests + coverage (pytest imports from src via pythonpath)
+uv run --no-sync pytest tests/test_scorer.py::test_report_shape   # a single test
+uv run --no-sync ruff check . && uv run --no-sync ruff format --check .   # lint + format
+uv run --no-sync mypy src        # type check (strict)
+```
+
+**Install stability:** `uv sync` installs the project NON-editable and the rebuild can land in a
+broken namespace state (`slopscore.__file__` becomes `None` → `ModuleNotFoundError`). Do an
+editable install once (`uv pip install -e . --no-deps`) and use `uv run --no-sync` so uv does not
+re-sync and clobber it. pytest is insulated regardless via `pythonpath = ["src"]` in pyproject.
+
+Optional features live behind extras: `[web]` (trafilatura), `[nlp]` (spaCy + sentence-transformers),
+`[lang]` (lingua). Default install is lean; `scan <url>` without `[web]` exits 3 with a hint. For
+the spaCy path: `uv pip install spacy && uv run --no-sync python -m spacy download en_core_web_sm`
+(`is_nlp_available()` gates it; syntactic features auto-upgrade when present).
+
+## Architecture (v0.2)
+
+Pipeline in `src/slopscore/`: `ingest/` (text, markdown via marko, json via jsonpath-ng, website)
+→ `normalize/` (ftfy `clean` + offset-preserving `OffsetMapper`, pysbd `segment`, `language`) →
+`features/` → `scoring/` → `report/`. Orchestrated by `core.py:build_document` then
+`scoring/scorer.py:score_document`; public API (`SlopScorer`, `scan_text/_path/_url`) in `__init__.py`.
+
+Reports (v0.2.1): `report/` has console, json, markdown, `sarif.py` (2.1.0, hand-built; severity→
+level), `html.py` (Jinja2 behind the `[report]` extra, highlighted spans), `batch.py` (directory/
+multi-file aggregation), and `locations.py` (char→line/col). `Report.original_text` holds the text
+offsets index into. The `scan` CLI takes multiple targets / a directory, `--recursive`, `--diff
+<ref>`, `--fail-on {none|low|medium|high}` (exit codes 0/1/2/3), and `--format sarif|html`. CI
+distribution: `action.yml` (composite) and `.pre-commit-hooks.yaml`.
+
+Key invariants when extending:
+- **Every feature is a `Feature`** (`features/base.py`): `extract(doc, profile) -> FeatureResult`
+  with a [0,1] score and `Evidence` spans. Importing `slopscore.features` registers them; add a
+  dimension by writing a class + `register()` AND a field in `models.Dimension`/`Dimensions` AND a
+  weight in `scoring/weights.py`. The scorer iterates the registry.
+- **Evidence offsets index the original text, not the cleaned text.** Features run on
+  `doc.cleaned_text` and MUST build spans via `doc.evidence(...)`, which maps offsets back through
+  `OffsetMapper`. The round-trip is enforced across the feature tests — keep it green.
+- **`TextSpan` lives in `spans.py`** (not `document.py`) to avoid a normalize↔document import cycle.
+- **Conservatism is in the scorer, not the features.** `scoring/scorer.py` applies a corroboration
+  gate (`WEAK_DIMENSIONS` damped when they fire alone), `human_writing_signals` enters with a
+  NEGATIVE weight, and `scoring/confidence.py:abstain_reason` caps the label at "mild" on short/
+  non-English input. Don't make individual features "conservative" — let the scorer do it.
+- **Rule data is YAML** under `src/slopscore/data/` (force-included into the wheel). `patterns/` is
+  organized into category subdirs loaded by `_ruleset.load_rules_from_directory`; `lexicons/markers.yaml`
+  carries `era`/`source` tags. The spaCy path lives behind `features/_nlp.py`.
+- Dimensions: lexical_markers, formulaic_structure, significance_inflation, superficial_analysis,
+  weasel_attribution, parallelism, copula_avoidance, genericity, redundancy, cadence_sameness,
+  formatting_tells (weak), prompt_residue, human_writing_signals (negative). unsupported_claims has
+  no feature yet (contributes 0).
+- **Personal baseline:** `scoring/calibrate.py` builds robust per-dimension stats from a corpus;
+  `scan --baseline <name>` attaches z-score deviations. Profiles (`scoring/profiles.py`) are hand-set
+  (see `PROFILE_NOTES.md`); citations + fairness caveats live in `MODEL_CARD.md`.
+
+Scoring engines (v0.3): `scoring/scorer.py` dispatches on `Settings.scorer` (`Scorer.rules` default
+vs `Scorer.ml`). The ML path (`scoring/model.py`) is a pure-numpy logistic model loaded from
+`data/model/slopscore-v0.3.json` over `FEATURE_ORDER`; sign-constrained (slop dims ≥0, human signal
+≤0), Platt-calibrated. The corroboration gate is rules-only; abstention applies to both. Train with
+`scripts/eval/train.py` (sklearn+scipy, OOF metrics); evaluate with `slopscore-lint eval` / the
+`slopscore.eval/` package (metrics, fairness, selective, span_metrics). Promotion is gated by
+`eval/harness.py:should_promote` (TPR@1%FPR + no subgroup-FPR regression) — currently rules wins, so
+ML stays opt-in. Eval data: `eval/datasets/seed.jsonl` (committed) + `scripts/eval/fetch.py` (large
+corpora, not committed); licensing in `DATA_SOURCES.md`. **Never train the shipped model on NC data;
+never import sklearn at scan time** (the ML path is numpy-only).
+
+Linter maturity (v0.4): `config_file.py` loads `slopscore.toml`/`[tool.slopscore]` via `tomllib`
+(precedence CLI > slopscore.toml > pyproject > defaults; `resolve_settings` merges, `Settings`
+carries `disabled_dimensions/rules`, `rule_severity`, `suggest`). The scorer skips disabled
+dimensions and post-filters evidence for disabled rules, severity overrides, and inline suppression
+(`suppress.py`, HTML-comment grammar). `report/baseline.py` fingerprints findings for
+`scan --baseline-file --fail-on-new`. `unsupported_claims` is now a real `_PhrasePack`
+(`data/patterns/claims/`). Opt-in `--suggest` adds `Evidence.suggestion` + SARIF `fixes`
+(`features/suggestions.py`, `data/patterns/suggestions/`) — advisory, excluded from score/`--fail-on`
+(`SUGGEST_*` skipped in `max_severity`). `detectors/` is an interface-only authorship adapter
+(`AuthorshipDetector` protocol + no-op `ReferenceDetector`); its `DetectorResult` populates a
+SEPARATE `Report.authorship` field with a mandatory caveat, never the score. **Wheel packaging:**
+data files ship via hatchling's default package inclusion — do NOT re-add a `force-include` for
+`data/` (it duplicates paths and breaks `uv build`). PyPI publish is OIDC trusted-publishing on tag
+(`.github/workflows/publish.yml`); docs are mkdocs-material (`.github/workflows/docs.yml`).
+
+## Project state
+
+v0.1–v0.4 are implemented and green (ruff/mypy/pytest). The repository also holds two reference
+documents:
+
+- `BACKGROUND_INFORMATION.local.md` — the authoritative spec. Defines the product concept,
+  what to detect, the scoring model, the planned package layout, dependencies, evaluation
+  plan, and a versioned MVP build plan (v0.1 → v1.0). **Read this before writing code or
+  proposing structure** — it is the source of truth for design decisions.
+- `AI_WRITING_SLOP_Guide.local.md` — a ~1,650-line catalog of real AI-slop writing examples
+  and patterns. Use it as a corpus of concrete patterns/phrases to detect and as raw material
+  for test fixtures and the evaluation benchmark.
+
+The `.local.md` suffix marks these as local-only working files. Do not assume they ship with
+the package or are public.
+
+## What this project is (and is not)
+
+`slopscore` is a transparent **AI-slop pattern detector** — not an AI-authorship detector.
+This distinction is load-bearing and shapes every API/report decision:
+
+- It outputs a 0–100 **SlopScore** measuring density of formulaic, generic, low-specificity,
+  over-polished, LLM-associated writing patterns — plus per-dimension scores, a separate
+  confidence score, and **evidence spans** (exact char offsets that triggered each finding).
+- It must **never** claim "this was written by AI." Any authorship signal (v0.4+ detector
+  adapters) is kept in a separate field (`ai_authorship_signal`), never folded into the
+  `slop_score`. The rationale (detector brittleness, false positives on non-native English,
+  paraphrase evasion) is documented in the spec — preserve that separation.
+- Positioning is "Vale/ruff for AI-slop writing patterns," not "another GPTZero clone."
+  Conservative by default: prefer false negatives over false accusations.
+
+## Key design decisions (from the spec)
+
+- **Python first**, not Rust. The hard part is NLP feature extraction, calibration, and
+  evaluation iteration — not raw speed. Rust only later for speed-critical parsing if needed.
+- **Three separate questions, kept distinct:** authorship likelihood (optional, fragile),
+  slop-pattern density (the core score), editorial-quality risk (most useful to writers).
+- **Heavyweight model deps live behind extras** (`[web]`, `[nlp]`, `[detectors]`, `[all]`).
+  The default install and the default score must be **rule-based and transparent** — no
+  black-box detector in the default path.
+- **Genre profiles** (`blog`, `essay`, `academic`, `marketing`, `technical`, `social`)
+  reweight dimensions; default `profile=blog`, `strictness=conservative`. The same feature
+  can be legitimate in one genre and slop in another (e.g. "robust" in a technical paper).
+- **Suppress/heavily qualify scores on short text** (<300 words) and low-confidence inputs
+  (non-English, heavy quotes/code/tables, uncertain web extraction).
+- **Evaluation from day one.** Credibility depends on shipping a benchmark (human-good,
+  raw-LLM, edited-LLM, human-bad) and reporting TPR at fixed low FPR, span-level
+  precision/recall, and per-domain false-positive rates — not just AUROC.
+
+## Roadmap (per spec)
+
+v0.2: genre profile tuning + `calibrate` (personal baseline from your own corpus), HTML report
+with highlighted spans, batch/recursive scanning. v0.3: trained interpretable model (logistic
+regression / LightGBM over the same features). v0.4: optional authorship-signal detector adapters
+(Binoculars, Fast-DetectGPT) in a separate `ai_authorship_signal` field — never folded into
+`slop_score`. v1.0: GitHub Action, SARIF output, evaluation benchmark, model card, docs site.
+See `BACKGROUND_INFORMATION.local.md` for the full plan and the target JSON schema.
+
+## Writing discipline (applies to this repo specifically)
+
+This is a tool that detects AI-slop writing, so its own prose must be exemplary. Scrub all
+READMEs, docs, docstrings, reports, and commit/PR text for the patterns the tool itself flags:
+puffery, AI-vocabulary (delve, crucial, pivotal, robust, seamless, leverage, showcase,
+underscore, tapestry), rule-of-three padding, gratuitous em-dashes, and formulaic scaffolding.
+Prefer specific, concrete, falsifiable wording. Dogfooding: prose here should pass `slopscore`.

slopscore_lint-0.4.2/DATA_SOURCES.md

@@ -0,0 +1,40 @@
+# Evaluation data sources & licensing
+
+slopscore separates **code** (MIT) from **evaluation data** (mixed upstream licenses) from the
+**trained model** (weights licensed to match the most-restrictive *training* source). The shipped
+model is trained only on permissive / CC-BY / CC-BY-SA data, so its weights stay redistributable.
+
+## Committed seed set
+
+`eval/datasets/seed.jsonl` (~54 rows) is a small, hand-authored, original corpus across the four
+buckets the spec calls for, built by `scripts/eval/build_seed.py`. It is deliberately diverse to
+limit leakage between the WP:AISIGNS-derived features and the labels. It is enough to exercise the
+full eval + training pipeline and to back the CI fairness guardrails; it is **not** a substitute
+for the large corpora below in a serious evaluation.
+
+| bucket | label | what |
+|---|---|---|
+| human_good | 0 | specific, plain, factual prose (incl. a simple/plain-English fairness slice) |
+| raw_llm | 1 | LLM-style slop: puffery, trailing "-ing" analyses, parallelism, AI vocab |
+| edited_llm | 1 | slop with concrete details added (harder positives) |
+| human_bad | 1 | vague human marketing/SEO copy (slop patterns, not AI-generated) |
+
+## Large public corpora (fetched, not committed)
+
+Pulled by `scripts/eval/fetch.py` into `~/.cache/slopscore/`; never redistributed.
+
+| source | license | use |
+|---|---|---|
+| RAID (Dugan et al., ACL 2024) | permissive (verify upstream) | train + eval; paraphrase-robustness |
+| MAGE (Li et al.) | CC-BY-4.0 | train + eval |
+| Kobak et al. excess-vocabulary / Wikipedia | CC-BY-SA-3.0 | train + eval; real edited/humanized text |
+| HC3 (Guo et al., 2023) | **CC-BY-NC-4.0** | **eval-only** — never used to train the shipped model |
+
+## Rules we follow
+
+- The shipped `data/model/slopscore-v0.3.json` is trained **only** on train-eligible (non-NC)
+  sources. NC corpora are loaded for measurement only.
+- Splits are domain/era-separated where possible to avoid leakage, since the features themselves
+  derive from WP:AISIGNS (see the plan's leakage-guard notes).
+- Fairness is measured per subgroup (plain/simple English, short text) and reported in
+  `MODEL_CARD.md`; CI fails if subgroup false-positive rates regress.

slopscore_lint-0.4.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Hodge
+
+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.

slopscore_lint-0.4.2/MODEL_CARD.md

@@ -0,0 +1,109 @@
+# slopscore model card (v0.2)
+
+## What it does
+
+slopscore scores text for **AI-slop writing patterns**, formulaic, generic, low-specificity,
+over-polished prose, and returns a 0-100 SlopScore with per-dimension breakdowns and evidence
+spans. It is a transparent rule engine: every point comes from a visible rule with a quotable
+span. It does **not** determine authorship.
+
+## What it is not
+
+It is not an AI-authorship detector and must not be used to accuse a writer. Authorship detectors
+are unreliable and biased; slopscore deliberately reports patterns, not provenance.
+
+## Intended use
+
+Writers, editors, bloggers, maintainers, and content teams self-checking drafts. Not for
+punitive or disciplinary decisions about people.
+
+## How it scores
+
+Rule-based features per dimension → each a [0,1] score → weighted sum → sigmoid → 0-100.
+Conservatism guardrails (v0.2):
+
+- **Corroboration gate.** Weak-alone tells (lexical markers, parallelism, copula avoidance,
+  formatting) are damped when no other dimension co-fires. A single fancy word or em dash cannot
+  by itself reach "severe".
+- **Negative signal.** `human_writing_signals` (plain verbs, superlatives, hedges, concrete
+  numbers) lowers the score for specific, plain prose.
+- **Abstention.** On input under ~100 words, or detected non-English, the label is capped at
+  "mild" and a reason is reported.
+
+## Detection grounding (sources)
+
+Dimensions and the lexicon are drawn from Wikipedia's "Signs of AI writing" (WP:AISIGNS) and the
+research it cites:
+
+- Juzek & Ward, "Why Does ChatGPT 'Delve' So Much?" (arXiv:2412.11385), overused vocabulary.
+- Kobak et al., "Delving into LLM-assisted writing…" (Science Advances 2025), excess vocabulary.
+- Reinhart et al., "Do LLMs write like humans?" (PNAS 2025), present-participle / rhetorical style.
+- Geng & Trotta (arXiv:2404.08627), decline of "is/are" copulas in post-2022 writing.
+- Russell et al. (ACL 2025), humans detect AI near chance; expert LLM-users rely on lexical cues.
+
+Vocabulary drifts by model era (GPT-4 → GPT-4o → GPT-5); the lexicon tags terms with their era.
+
+## Limitations and fairness
+
+- **Non-native English false positives.** Liang et al. (Patterns 2023) found AI detectors flag
+  non-native-English (e.g. TOEFL) essays at up to ~61%. slopscore mitigates with the corroboration
+  gate, the negative human signal, and abstention, but residual risk remains. Do not treat a
+  high score on plain or non-native English as evidence of anything about the author.
+- **Short text.** Under ~300 words confidence is low; under ~100 the score abstains.
+- **Genre.** Marketing and travel writing naturally resemble slop; use `--profile` to reweight.
+- **Adversarial edits.** Light paraphrasing evades pattern matching, as it does all detectors.
+- **Coverage.** Wikipedia/markup-specific and authorship-signal tells are intentionally excluded;
+  slopscore is a general-prose tool.
+
+## v0.3: learned scorer and evaluation
+
+v0.3 adds an evaluation framework (`slopscore-lint eval`) and a transparent learned scorer: a
+**sign-constrained, Platt-calibrated logistic regression** over the 13 interpretable dimensions
+(slop dimensions weight ≥ 0, `human_writing_signals` ≤ 0). It is serialized as auditable JSON
+(`data/model/slopscore-v0.3.json`) and runs with pure numpy at scan time, `--scorer ml`.
+
+**The rule scorer remains the default.** Under the replace-if-wins gate, the learned model must
+both (a) not lose on TPR@1%FPR and (b) not regress any subgroup false-positive rate. On the
+committed seed set it does neither cleanly:
+
+| scorer | TPR@1%FPR | PR-AUC | ECE | simple-English FPR |
+|---|---|---|---|---|
+| rules | 0.80 | 0.96 | 0.14 | 0.00 |
+| ml (out-of-fold) | 0.77 | 0.96 | 0.12 | n/a |
+| ml (in-sample, seed) | 0.80 | 0.98 | 0.06 | **0.62** |
+
+The learned model improves calibration but **over-flags plain/simple English** (a fairness
+regression on exactly the population detectors are known to harm) and does not beat the rules on
+held-out TPR@1%FPR. So `--scorer ml` is available and opt-in; `rules` stays default. This is the
+gate working as intended, not a failure.
+
+Caveats: these numbers are from the small hand-authored seed set (~54 rows; in-sample for ml
+unless noted out-of-fold). They are illustrative, not a serious benchmark, run `slopscore-lint eval`
+on the fetched public corpora (`scripts/eval/fetch.py`, see `DATA_SOURCES.md`) for real figures.
+
+### Real-corpus experiment (MAGE): and why it validates the design
+
+Held-out test split of the committed seed + a fetched MAGE subset (CC-BY; ~1,450 rows total,
+30% test), via `scripts/eval/experiment.py`:
+
+| scorer | TPR@1%FPR | TPR@5%FPR | PR-AUC | ECE |
+|---|---|---|---|---|
+| rules | 0.06 | 0.08 | 0.51 | 0.29 |
+| LR (sign-constrained) | 0.10 | 0.11 | 0.52 | 0.03 |
+| LightGBM (monotone, **experiment only**) | 0.09 | 0.13 | **0.75** | 0.02 |
+
+**MAGE labels by authorship (machine vs human), not by slop.** That the slop scorers sit near
+chance at low FPR on MAGE is the design working, not failing: slopscore detects slop *patterns*,
+not provenance, so it should *not* cleanly separate well-written machine text from human text.
+The learned variants improve calibration sharply (ECE 0.29 → 0.02-0.03), and LightGBM extracts
+more authorship signal from the same 13 features nonlinearly (PR-AUC 0.75). We **do not ship
+LightGBM**: it needs trees at scan time (breaking the pure-numpy path), and optimizing it against
+authorship labels would turn slopscore into an authorship detector, the one thing it refuses to be. The **shipped model stays the seed-trained, slop-labeled LR**, and
+the **rule scorer stays the default**. The shipped model is never trained on MAGE.
+
+## Changes from v0.1
+
+Added significance inflation, superficial "-ing" analyses, vague/over-attribution, negative
+parallelism / rule-of-three, copula avoidance, formatting tells, and a negative human-writing
+signal; expanded the cited lexicon; added the corroboration gate, abstention, and personal-baseline
+calibration. The default install stays lean (regex + scikit-learn); spaCy precision is behind `[nlp]`.