zero-slop 2.5.8 → 2.7.0

package/README.md

@@ -1,193 +1,204 @@
-# Zero Slop: AI Writing Editor and Slop Detector
+# Zero Slop
 
 <p align="center">
   <img alt="MIT" src="https://img.shields.io/badge/license-MIT-202521">
   <img alt="tests" src="https://img.shields.io/badge/tests-passing-227B5B">
   <img alt="dependencies" src="https://img.shields.io/badge/runtime%20dependencies-0-227B5B">
   <img alt="privacy" src="https://img.shields.io/badge/learning-private-227B5B">
-  <img alt="version" src="https://img.shields.io/badge/version-2.5.8-72528F">
+  <img alt="version" src="https://img.shields.io/badge/version-2.7.0-72528F">
 </p>
 
-<p align="center">
-  <strong><a href="https://zero-slop.ai">zero-slop.ai</a></strong> &middot; examples, benchmarks, and blog
-</p>
+Score your writing 0 to 100 for AI slop, then edit it out without changing a single fact.
 
-**Less slop, more pop.**
+![A scored sentence before and after editing](assets/demo.png)
 
-Zero Slop is an Agent Skill, not an AI model. Claude, GPT, or another compatible model
-edits inside your assistant; Zero Slop supplies local checks that protect meaning,
-voice, and format.
+## Problem
 
-The 0-to-100 writing score flags generic AI-style language and lists flagged phrases;
-it does not identify the author. In the test sets, human samples
-scored 9 to 21; unedited AI drafts averaged 77. These are reference points, not
-universal cutoffs.
+AI writing has an accent: "It's not X. It's Y." "Here's the thing nobody tells you."
+"This marks a pivotal moment." Ask an AI to fix it and it sands off the vocabulary and
+cadence that made the writing yours, and rewrites your numbers on the way.
 
-![A scored sentence before and after editing](assets/demo.png)
 
-## Install Zero Slop
+Zero Slop is an Agent Skill and ships no model. Claude, GPT, or another compatible model
+does the editing; Zero Slop supplies the workflow, the meter, and the checks that refuse
+any change to a name, number, quotation or link.
+
+## How to install Zero Slop
 
-Paste this into Claude Code, Codex, Cursor, OpenCode, Warp, Zed, or another
-Agent Skills-compatible assistant:
+Paste this into Claude Code, Codex, Cursor, OpenCode, Warp, or Zed:
 
 ```text
-Install or update Zero Slop from https://github.com/manavmishra/ZeroSlop for
-this agent.
-
-1. Find active installations. Report each path, version, and method. Do not duplicate
-   or remove one without asking.
-2. For updates, keep the existing install method. In Codex, use $skill-installer for
-   `skills/zero-slop`; in Claude Code or Cowork, use the plugin marketplace. Otherwise
-   use `npx skills add manavmishra/ZeroSlop --global` to install or
-   `npx skills update zero-slop --global` to update.
-3. Preserve ZERO_SLOP_HOME (default: ~/.zero-slop) and its private data.
-4. Verify the version. When Python is available, run
-   `python3 scripts/calibrate.py --selftest`.
-5. Report the path, method, version, validation result, and restart requirement.
-
-Do not modify the current project or unrelated configuration. Ask before falling
-back to a project-local installation.
+Install the Zero Slop skill globally from https://github.com/manavmishra/ZeroSlop
 ```
 
-Direct terminal install:
+Or install it with `npx`:
 
-```bash
+```sh
 npx skills add manavmishra/ZeroSlop --global
 ```
 
-Claude Code and Cowork use the plugin marketplace. ChatGPT users can
-download [`dist/zero-slop-single-file.md`](dist/zero-slop-single-file.md); Claude.ai
-users can download the release ZIP.
+ChatGPT users can download [`dist/zero-slop-single-file.md`](dist/zero-slop-single-file.md).
+Claude.ai users can upload [`dist/zero-slop.zip`](dist/zero-slop.zip). `npx skills update zero-slop --global` updates an existing CLI install later.
 
-## How Zero Slop works
+## How to use Zero Slop
 
-![One editing workflow, a private learning loop, and a separate release review](assets/engine.svg)
+```text
+/zero-slop (your writing)
+```
 
-Seven roles form one workflow — jobs, not separate models. Your AI assistant handles
-the editorial passes; local Python tools run repeatable checks.
+You get the edited draft, a before-and-after score, and the flagged phrases quoted with
+what needed work. `/zero-slop inspect (your writing)` reviews without rewriting.
+For a folder, `slopscore.py --batch drafts/ --gate 25` exits non-zero above the threshold
+and drops into CI.
+## The slop that Zero Slop catches
 
-| Role | Who does it | What it does |
-|---|---|---|
-| 1. Scorer | Local tools | Finds exact phrases, mechanical rhythm, dense passages, and distracting formatting; explains the writing score. |
-| 2. Interpreter | Your AI assistant | Reads claims, support, audience, structure, and voice before editing. |
-| 3. Rewriter | Your AI assistant | Removes stock wording and improves order, rhythm, and tone without inventing detail. |
-| 4. Fact gate | Local tools | Rejects versions that add or drop names, numbers, quotations, or links; selects the clearest one left. |
-| 5. Copy desk | Fresh AI pass | Corrects grammar, spelling, usage, and consistency. |
-| 6. Read-aloud editor | Fresh AI pass | Fixes stumbles, repetition, weak transitions, and awkward flow. |
-| 7. Verifier | Local tools and your AI assistant | Compares the final text with the source for facts, meaning, voice, format, and structure. A repair repeats both editorial passes and every check. |
+290 weighted patterns and a 96-term lexicon, including:
 
-### Why separate the work?
+1. **Binary contrasts.** "It's not X. It's Y."
+2. **Throat-clearing openers.** "Here's the thing," "Let me be clear"
+3. **Faux-insight setups.** "What nobody tells you," "The part everyone misses"
+4. **Colon reveals.** "The best part: it learns."
+5. **Dramatic fragments.** "That's it. That's the whole thing."
+6. **Superficial analysis.** "highlighting the team's commitment to innovation"
+7. **Importance puffery.** "marks a pivotal moment," "a testament to"
+8. **Weasel attribution.** "experts agree," "studies show"
+9. **Synonym cycling.** The agent, the assistant, the tool, all one thing.
+10. **Marketing riders.** "robust" and "leverage" score only beside a marketing trigger, so a runbook stays quiet.
 
-Research supports the checks, not the number seven. Studies find
-[predictable wording](https://arxiv.org/abs/2301.11305) and
-[excess vocabulary](https://arxiv.org/abs/2406.07016) in machine text, while detectors
-can [misclassify non-native English](https://arxiv.org/abs/2304.02819). Writing and
-verification stay separate: the rewriter does not certify its own facts, and later
-passes catch surviving errors. Local tools use Python's standard library and never send
-drafts. The
-[research notes](references/evidence.md) cover the rationale and limits.
+A reading pass covers what no pattern reaches, where the defect is the document rather
+than any span: one shape repeated seven times, statistics piled into a paragraph,
+paragraphs that shuffle without loss. [`references/eval.md`](references/eval.md) has all
+76 checks.
 
-## Private learning from writer edits
+Human writing scored 9 to 21 in [`data/corpus/must-not-flag/`](data/corpus/must-not-flag/);
+unedited AI drafts averaged 77 across [`bench/examples.json`](bench/examples.json).
+Neither number claims to identify who wrote the text.
 
-Learning requires the assistant's version and the writer's final version.
-Zero Slop never monitors files, browsers, or publishing systems.
+## How it works
 
-A named profile can exempt existing watchlist words in your sample. It applies only
-when selected by name and does not learn cadence, tone, or a complete writing style.
+![Eight editorial roles, a private learning loop, and a separate release review](assets/engine.svg)
 
-A phrase must be cut from three unrelated pieces before becoming a private rule; a
-single word needs five. New rules must keep known-human samples clean. Repeated fixes
-guide later edits; kept phrases can quiet a rule, and old rules fade. Private state
-under `$ZERO_SLOP_HOME` never retrains the AI model.
+Eight roles form one workflow. Each is a job rather than a service: a single model can handle
+several of them, each as its own pass, so nothing grades its own output.
 
-## What the current release measured
+| Role | Who does it | What happens |
+|---|---|---|
+| 1. Scorer | Local tools | Finds the exact wording, rhythm, readability, and formatting problems that raised the writing score. |
+| 2. Interpreter | Your AI assistant | Reads the claims, purpose, audience, structure, and voice before changing anything. |
+| 3. Rewriter | Your AI assistant | Removes stock language and rebuilds order, rhythm, and tone without inventing detail. |
+| 4. Fact gate | Local tools | Rejects any version that changes names, numbers, quotations, links, code, tables, paths, or structure. |
+| 5. Copy desk | Fresh AI pass | Corrects grammar, spelling, usage, and consistency in the actual deliverable. |
+| 6. Read-aloud editor | Fresh AI pass | Fixes stumbles, repetition, weak transitions, and awkward flow. |
+| 7. Verifier | Local tools and your AI assistant | Compares text with source for facts, meaning, qualifiers, voice, format, structure. |
+| 8. Fresh-eyes finalizer | Fresh AI pass | Reads the verified text as a first-time reader, applying only safe polish. Any final polish restarts the final checks; the same text must return unchanged before release. |
 
-v2.5.8 keeps v2.5.7's context-first review and adds a check for generic lists of
-benefits. On the frozen 38-passage consensus panel, accuracy rose from 71.1% to 84.2%.
-The new check caught five passages the previous version missed. It did not change any
-passage the raters considered clean. Because two LLM editorial raters supplied the
-labels, this is a regression result, not human field accuracy.
+Eight is an engineering choice; research supports the individual checks. Studies find
+[predictable wording](https://arxiv.org/abs/2301.11305) and
+[overused vocabulary](https://arxiv.org/abs/2406.07016) in machine text, and authorship
+detectors can [misclassify non-native English](https://arxiv.org/abs/2304.02819). Local
+tools use only Python's standard library.
 
-### Recent model output: RAID+
+## Private learning from your edits
 
-[RAID+](https://huggingface.co/datasets/markstanl/RAID-Plus) extends the peer-reviewed,
-MIT-licensed RAID benchmark. We scored 8,000 pinned rows; 7,627 abstracts
-remained after excluding failed or empty generations.
+Nothing is learned until you hand over both versions: what the assistant produced and
+what you kept. Zero Slop watches nothing on its own: no file monitoring, no browser
+hooks, no reaching into where you publish.
+
+A phrase must disappear from three unrelated pieces before it becomes a private rule; a
+single word needs five. Each must be new and stay silent on known-human text. Private
+data stays under `$ZERO_SLOP_HOME`.
+
+This is human-in-the-loop online learning. It never retrains Claude, GPT, or another
+model, and involves no neural training or RLHF. A profile can exempt existing watchlist
+words when selected by name; it does not learn cadence, tone, or a complete writing
+style.
 
-| Model | Texts scored | Mean writing score ↓ | At or above 25 |
-|---|---:|---:|---:|
-| DeepSeek V3 | 1,995 | 14.5 | 10.1% |
-| Gemini 3.1 Pro | 1,998 | 17.0 | 18.2% |
-| Gemma 3 27B | 1,634 | 21.6 | 30.4% |
-| Llama 3.3 70B | 2,000 | 25.5 | 41.7% |
-| **Overall** | **7,627** | **19.6** | **24.8%** |
 
-![Current Zero Slop writing scores across four RAID+ model families](assets/bench-raid-plus.png)
+## What's inside
 
-RAID+ records model origin, not editorial quality, so this is a score distribution,
-not an accuracy claim. In a fresh pass over 2,187 Beemo records, raw model responses
-averaged 30.2, expert edits 25.3, and independent human answers 20.0. Expert editing
-lowered the score in 52.2% of pairs; Beemo lacks quality labels.
+[`SKILL.md`](SKILL.md) has the workflow and [`references/eval.md`](references/eval.md) the
+76 checks. [`scripts/slopscore.py`](scripts/slopscore.py) is the meter and fact gate,
+with [`scripts/register.py`](scripts/register.py) running the reading pass.
+[`bench/README.md`](bench/README.md) documents every benchmark with its limits.
 
-### Five workflows, one fixed set of drafts
+## Evidence
 
-The 18 saved rewrites use Zero Slop 2.4.3 and pinned competitor instructions. They were
-not regenerated. Passing requires clean writing and layout without altered facts or
-invented feelings.
+### Against other tools, same model, same drafts
 
-| Method | Mean writing score ↓ | Passed all checks | Important details kept | Average length change |
+We reran Zero Slop, [avoid-ai-writing](https://github.com/conorbronsdon/avoid-ai-writing),
+[no-ai-slop](https://github.com/petergyang/no-ai-slop) and
+[humanizer](https://github.com/blader/humanizer) on the same 18 obvious drafts, each with
+GPT-5.4, high reasoning, batches of three, and its pinned instructions.
+
+| Method | Mean writing score ↓ | Passed all Zero Slop checks | Important details kept | Average length change |
 |---|---:|---:|---:|---:|
 | Original drafts | 76.3 | 0/18 | — | — |
-| Zero Slop | 16.4 | 18/18 | 18/18 | -26.4% |
-| humanizer | 25.3 | 13/18 | 18/18 | -25.7% |
-| stop-slop | 25.7 | 13/18 | 18/18 | -34.4% |
-| no-ai-slop | 29.1 | 12/18 | 18/18 | -28.0% |
-| de-slop | 52.3 | 6/18 | 18/18 | -18.5% |
+| Zero Slop | 12.8 | 18/18 | 18/18 | -8.9% |
+| avoid-ai-writing | 23.3 | 15/18 | 18/18 | -14.6% |
+| no-ai-slop | 28.4 | 12/18 | 17/18 | -13.7% |
+| humanizer | 35.4 | 9/18 | 17/18 | -7.2% |
 
-![The same 18 drafts after each editing workflow; lower scores mean fewer generic AI-style patterns](assets/bench-search-rewrites.png)
+![Fresh same-model editing replay on 18 drafts](assets/bench-search-rewrites.png)
 
-All 18 Zero Slop edits passed, but Zero Slop defines the rules and the rewrites predate
-this release. No available set combines current writing with independent human review,
-so no universal accuracy number exists. See
-[`bench/README.md`](bench/README.md).
+Those checks are Zero Slop's own, so we also ran a method-hidden comparison against the pinned
+incumbent. The GPT-5.4 reviewer favored Zero Slop on 13 drafts and avoid-ai-writing on 3,
+with 2 unresolved; the passes agreed on 16 of 18. Our source check cleared 18/18 of our
+rewrites and 16/18 of the incumbent's. On mean score across this second set we lost,
+17.8 to 17.0.
 
-### The local tools are fast
+![Method-hidden editorial preference on 18 drafts](assets/bench-incumbent-hidden.png)
 
-On one Apple silicon Mac, the local checker processed 1,000 documents in 2.0147 seconds
-(496.4 per second). A 15,201-word document took 0.3222 seconds; the slowest stress case
-took 2.5180 seconds. An alternating six-pair comparison measured 29.4% higher median
-throughput than v2.5.7. The optimization produced the same complete result as v2.5.7
-on all 280 tracked documents. An 8,000-word learning pass took 0.1589 seconds. Time
-spent by the AI assistant is excluded.
+This is a small LLM-reviewed regression study. It measures neither field accuracy nor a
+universal ranking. Drafts, mappings, verdicts, hashes and limits:
+[`bench/incumbent-blind-replay/`](bench/incumbent-blind-replay/). On the 38-item
+editorial panel ([`bench/README.md`](bench/README.md)), v2.6.1 matched the prior 84.2% result. Its four new checks left all 114
+frozen document scores unchanged and 18 human controls clear, while the four target cases
+moved from 9.5 to between 30.7 and 65.1. Median throughput was 0.03% lower across 12
+runs, which is local timing noise and no kind of speed claim.
 
-## What Zero Slop adds
+### Speed
 
-Zero Slop builds on [no-ai-slop](https://github.com/petergyang/no-ai-slop),
-[humanizer](https://github.com/blader/humanizer),
-[de-slop](https://github.com/isatimur/de-slop), and
-[stop-slop](https://github.com/hardikpandya/stop-slop), and draws on
-[unslop-text](https://github.com/JCarterJohnson/vibecoded-design-tells/tree/main/unslop-ai-text)
-research. It adds a local writing score,
-fact protection, separate editorial passes, private learning, and release tests.
+On one Apple silicon Mac: 1,000 documents in 1.9958 seconds (501.1 per second), a
+15,201-word document in 0.3223 seconds, slowest stress case 2.4438 seconds, an 8,000-word
+learning pass 0.1627 seconds. Editing time sits outside these numbers. None is a
+service-level guarantee.
 
-The chart records documented features. It does not decide which tool writes better.
-Details are in [`bench/README.md`](bench/README.md).
+### Current models
 
-![Comparison of features documented in pinned repository versions](assets/competitor-capabilities.png)
+The pinned [RAID+](https://huggingface.co/datasets/markstanl/RAID-Plus) sample yielded
+7,627 usable generations:
 
-## Reproduce the tests and benchmarks
+| Model | Texts scored | Mean writing score ↓ | At or above 25 |
+|---|---:|---:|---:|
+| DeepSeek V3 | 1,995 | 14.5 | 10.1% |
+| Gemini 3.1 Pro | 1,998 | 17.0 | 18.2% |
+| Gemma 3 27B | 1,634 | 21.6 | 30.4% |
+| Llama 3.3 70B | 2,000 | 25.5 | 41.7% |
+
+RAID+ labels capture which model produced a text and say nothing about quality. In
+Beemo, raw responses averaged
+30.2, expert edits 25.3, human answers 20.0. Neither dataset carries quality labels.
+
+
+## Where Zero Slop came from
 
-```bash
+Zero Slop stands on no-ai-slop, humanizer, de-slop, stop-slop, unslop-text and
+avoid-ai-writing, adding a writing score, source protection, separate editorial passes,
+private learning, portfolio analysis and release tests.
+
+![Documented capabilities at pinned repository versions](assets/competitor-capabilities.png)
+
+The chart records which features each project documents, and says nothing about writing
+quality. Reproduce the shipped checks:
+
+```sh
 python3 tests/test_all.py
 python3 scripts/calibrate.py --selftest
-python3 bench/search-corpus/compare.py --check
-python3 bench/raid-plus-corpus/audit.py --check
-python3 bench/beemo-corpus/audit.py --check
-python3 bench/validate_corpus_registry.py
+python3 scripts/register.py --selftest
 python3 bench/make_charts.py --check
 ```
 
-`SKILL.md` defines the skill; `scripts/` contains tools; `bench/` contains tests. See
-the [security policy](SECURITY.md) and [research notes](references/evidence.md).
 
-Released under the [MIT License](LICENSE).
+## License
+
+MIT